effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Predicate.ts

@@ -1,41 +1,66 @@
 /**
- * Predicate and Refinement helpers for runtime checks, filtering, and type narrowing.
- * This module provides small, pure functions you can combine to decide whether a
- * value matches a condition and, when using refinements, narrow TypeScript types.
- *
- * Mental model:
- * - A `Predicate<A>` is just `(a: A) => boolean`.
- * - A `Refinement<A, B>` is a predicate that narrows `A` to `B` when true.
- * - Guards like `isString` are predicates/refinements for common runtime types.
- * - Combinators like `and`/`or` build new predicates from existing ones.
- * - `Tuple` and `Struct` lift element/property predicates to compound values.
- *
- * Common tasks:
- * - Reuse an existing predicate on a different input shape -> {@link mapInput}
- * - Combine checks -> {@link and}, {@link or}, {@link not}, {@link xor}
- * - Build tuple/object checks -> {@link Tuple}, {@link Struct}
- * - Narrow `unknown` to a concrete type -> {@link Refinement}, {@link compose}
- * - Check runtime types -> {@link isString}, {@link isNumber}, {@link isObject}
- *
- * Gotchas:
- * - `isTruthy` uses JavaScript truthiness; `0`, "", and `false` are false.
- * - `isObject` excludes arrays; use {@link isObjectOrArray} for both.
- * - `isIterable` treats strings as iterable.
- * - `isPromise`/`isPromiseLike` are structural checks (then/catch), not `instanceof`.
- * - `isTupleOf` and `isTupleOfAtLeast` only check length, not element types.
+ * Predicates are small boolean functions for checking values at runtime.
+ * Refinements are predicates that also narrow TypeScript types after a
+ * successful check. This module provides primitive guards for common JavaScript
+ * values and combinators for building larger checks from smaller ones.
+ *
+ * **Mental model**
+ *
+ * - A `Predicate<A>` is `(a: A) => boolean`
+ * - A `Refinement<A, B>` is `(a: A) => a is B`; when it returns `true`,
+ *   TypeScript can treat the value as `B`
+ * - Guards such as {@link isString}, {@link isNumber}, and {@link isObject}
+ *   refine `unknown` values into useful runtime types
+ * - Combinators such as {@link and}, {@link or}, {@link not}, and {@link xor}
+ *   build new predicates while preserving refinement information where possible
+ * - {@link Tuple} and {@link Struct} lift element and property predicates to
+ *   tuple-like arrays and object shapes
+ *
+ * **Common tasks**
+ *
+ * - Check primitive runtime types: {@link isString}, {@link isNumber},
+ *   {@link isBoolean}, {@link isBigInt}, {@link isSymbol}
+ * - Check object-like values: {@link isObject}, {@link isObjectOrArray},
+ *   {@link hasProperty}, {@link isTagged}
+ * - Combine predicates: {@link and}, {@link or}, {@link not}, {@link xor}
+ * - Reuse a predicate on derived input: {@link mapInput}
+ * - Compose refinements that narrow in stages: {@link compose}
+ * - Validate tuple or object shapes: {@link Tuple}, {@link Struct}
+ *
+ * **Gotchas**
+ *
+ * - Predicates only return `true` or `false`; they do not explain why a value
+ *   failed a check
+ * - {@link isTruthy} uses JavaScript truthiness, so `0`, `""`, and `false`
+ *   are rejected
+ * - {@link isObject} excludes arrays; use {@link isObjectOrArray} when arrays
+ *   should also pass
+ * - {@link isIterable} accepts strings because strings are iterable in
+ *   JavaScript
+ * - {@link isPromise} and {@link isPromiseLike} are structural checks, not
+ *   `instanceof` checks
+ * - {@link isTupleOf} and {@link isTupleOfAtLeast} check length only, not
+ *   element types
+ *
+ * **Quickstart**
  *
  * **Example** (Filter by a predicate)
  *
  * ```ts
  * import { Predicate } from "effect"
  *
- * const isPositive = (n: number) => n > 0
- * const data = [2, -1, 3]
+ * const values: Array<unknown> = ["one", 2, "three", null]
+ * const strings = values.filter(Predicate.isString)
  *
- * console.log(data.filter(isPositive))
+ * console.log(strings)
+ * // Output: ["one", "three"]
  * ```
  *
- * See also: {@link Predicate}, {@link Refinement}, {@link and}, {@link or}, {@link mapInput}
+ * **See also**
+ *
+ * - {@link Predicate} for plain boolean checks
+ * - {@link Refinement} for checks that narrow types
+ * - {@link Struct} and {@link Tuple} for checking compound values
  *
  * @since 2.0.0
  */
@@ -48,7 +73,7 @@ import type { TupleOf, TupleOfAtLeast } from "./Types.ts"
  *
  * **When to use**
  *
- * - You want a reusable boolean check for `A`.
+ * Use when you want a reusable boolean check for `A`.
  * - You plan to combine checks with {@link and}/{@link or}.
  * - You want a simple filter predicate for arrays or iterables.
  *
@@ -83,7 +108,7 @@ export interface Predicate<in A> {
  *
  * **When to use**
  *
- * - You are defining APIs that abstract over predicates with HKTs.
+ * Use when you are defining APIs that abstract over predicates with HKTs.
  * - You need a `TypeLambda` instance for predicate-based type classes.
  *
  * **Details**
@@ -113,7 +138,7 @@ export interface PredicateTypeLambda extends TypeLambda {
  *
  * **When to use**
  *
- * - You want a runtime check that refines `A` to `B` for TypeScript.
+ * Use when you want a runtime check that refines `A` to `B` for TypeScript.
  * - You want to compose multiple type guards with {@link compose}.
  * - You need to guard `unknown` values safely.
  *
@@ -151,7 +176,7 @@ export interface Refinement<in A, out B extends A> {
  *
  * **When to use**
  *
- * - You need to extract input types from predicate signatures.
+ * Use when you need to extract input types from predicate signatures.
  * - You want to write generic helpers over predicate types.
  *
  * **Details**
@@ -178,7 +203,7 @@ export declare namespace Predicate {
    *
    * **When to use**
    *
-   * - You want to infer the input type from a predicate type.
+   * Use when you want to infer the input type from a predicate type.
    * - You are defining generic utilities over predicates.
    *
    * **Details**
@@ -207,7 +232,7 @@ export declare namespace Predicate {
    *
    * **When to use**
    *
-   * - You need a constraint for "any predicate" in generic code.
+   * Use when you need a constraint for "any predicate" in generic code.
    *
    * **Details**
    *
@@ -233,7 +258,7 @@ export declare namespace Predicate {
  *
  * **When to use**
  *
- * - You need to extract input/output types from refinement signatures.
+ * Use when you need to extract input/output types from refinement signatures.
  * - You want to write generic helpers over refinements.
  *
  * **Details**
@@ -261,7 +286,7 @@ export declare namespace Refinement {
    *
    * **When to use**
    *
-   * - You want to infer the input type from a refinement type.
+   * Use when you want to infer the input type from a refinement type.
    *
    * **Details**
    *
@@ -290,7 +315,7 @@ export declare namespace Refinement {
    *
    * **When to use**
    *
-   * - You want to infer the narrowed type from a refinement type.
+   * Use when you want to infer the narrowed type from a refinement type.
    *
    * **Details**
    *
@@ -317,7 +342,7 @@ export declare namespace Refinement {
    *
    * **When to use**
    *
-   * - You need a constraint for "any refinement" in generic code.
+   * Use when you need a constraint for "any refinement" in generic code.
    *
    * **Details**
    *
@@ -344,7 +369,7 @@ export declare namespace Refinement {
  *
  * **When to use**
  *
- * - You have a predicate on `A` and want one on `B` via `B -> A`.
+ * Use when you have a predicate on `A` and want one on `B` via `B -> A`.
  * - You want to check derived values (lengths, projections, etc.).
  *
  * **Details**
@@ -377,7 +402,7 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * - You have a predicate on `A` and want one on `B` via `B -> A`.
+   * Use when you have a predicate on `A` and want one on `B` via `B -> A`.
    * - You want to check derived values (lengths, projections, etc.).
    *
    * **Details**
@@ -410,7 +435,7 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * - You have a predicate on `A` and want one on `B` via `B -> A`.
+   * Use when you have a predicate on `A` and want one on `B` via `B -> A`.
    * - You want to check derived values (lengths, projections, etc.).
    *
    * **Details**
@@ -445,7 +470,7 @@ export const mapInput: {
  *
  * **When to use**
  *
- * - You need a runtime check for tuple length.
+ * Use when you need a runtime check for tuple length.
  * - You want to narrow `ReadonlyArray<T>` to `TupleOf<N, T>`.
  *
  * **Details**
@@ -475,7 +500,7 @@ export const isTupleOf: {
    *
    * **When to use**
    *
-   * - You need a runtime check for tuple length.
+   * Use when you need a runtime check for tuple length.
    * - You want to narrow `ReadonlyArray<T>` to `TupleOf<N, T>`.
    *
    * **Details**
@@ -505,7 +530,7 @@ export const isTupleOf: {
    *
    * **When to use**
    *
-   * - You need a runtime check for tuple length.
+   * Use when you need a runtime check for tuple length.
    * - You want to narrow `ReadonlyArray<T>` to `TupleOf<N, T>`.
    *
    * **Details**
@@ -537,7 +562,7 @@ export const isTupleOf: {
  *
  * **When to use**
  *
- * - You need a runtime check for tuple-like minimum length.
+ * Use when you need a runtime check for tuple-like minimum length.
  * - You want to narrow `ReadonlyArray<T>` to `TupleOfAtLeast<N, T>`.
  *
  * **Details**
@@ -567,7 +592,7 @@ export const isTupleOfAtLeast: {
    *
    * **When to use**
    *
-   * - You need a runtime check for tuple-like minimum length.
+   * Use when you need a runtime check for tuple-like minimum length.
    * - You want to narrow `ReadonlyArray<T>` to `TupleOfAtLeast<N, T>`.
    *
    * **Details**
@@ -597,7 +622,7 @@ export const isTupleOfAtLeast: {
    *
    * **When to use**
    *
-   * - You need a runtime check for tuple-like minimum length.
+   * Use when you need a runtime check for tuple-like minimum length.
    * - You want to narrow `ReadonlyArray<T>` to `TupleOfAtLeast<N, T>`.
    *
    * **Details**
@@ -629,7 +654,7 @@ export const isTupleOfAtLeast: {
  *
  * **When to use**
  *
- * - You want a predicate that mirrors JavaScript truthiness.
+ * Use when you want a predicate that mirrors JavaScript truthiness.
  * - You need to filter out falsy values like `0`, "", and `false`.
  *
  * **Details**
@@ -663,7 +688,7 @@ export function isTruthy(input: unknown): boolean {
  *
  * **When to use**
  *
- * - You need a runtime guard for `Set` values.
+ * Use when you need a runtime guard for `Set` values.
  *
  * **Details**
  *
@@ -696,7 +721,7 @@ export function isSet(input: unknown): input is Set<unknown> {
  *
  * **When to use**
  *
- * - You need a runtime guard for `Map` values.
+ * Use when you need a runtime guard for `Map` values.
  *
  * **Details**
  *
@@ -729,7 +754,7 @@ export function isMap(input: unknown): input is Map<unknown, unknown> {
  *
  * **When to use**
  *
- * - You need to guard an `unknown` value as a string.
+ * Use when you need to guard an `unknown` value as a string.
  * - You want to narrow in `if` statements.
  *
  * **Details**
@@ -764,7 +789,7 @@ export function isString(input: unknown): input is string {
  *
  * **When to use**
  *
- * - You need to guard an `unknown` value as a number.
+ * Use when you need to guard an `unknown` value as a number.
  *
  * **Details**
  *
@@ -798,7 +823,7 @@ export function isNumber(input: unknown): input is number {
  *
  * **When to use**
  *
- * - You need to guard an `unknown` value as a boolean.
+ * Use when you need to guard an `unknown` value as a boolean.
  *
  * **Details**
  *
@@ -831,7 +856,7 @@ export function isBoolean(input: unknown): input is boolean {
  *
  * **When to use**
  *
- * - You need to guard an `unknown` value as a bigint.
+ * Use when you need to guard an `unknown` value as a bigint.
  *
  * **Details**
  *
@@ -863,7 +888,7 @@ export function isBigInt(input: unknown): input is bigint {
  *
  * **When to use**
  *
- * - You need to guard an `unknown` value as a symbol.
+ * Use when you need to guard an `unknown` value as a symbol.
  *
  * **Details**
  *
@@ -895,7 +920,7 @@ export function isSymbol(input: unknown): input is symbol {
  *
  * **When to use**
  *
- * - You need to guard unknown keys before indexing.
+ * Use when you need to guard unknown keys before indexing.
  *
  * **Details**
  *
@@ -930,7 +955,7 @@ export function isPropertyKey(u: unknown): u is PropertyKey {
  *
  * **When to use**
  *
- * - You need to guard an `unknown` value as callable.
+ * Use when you need to guard an `unknown` value as callable.
  *
  * **Details**
  *
@@ -962,7 +987,7 @@ export function isFunction(input: unknown): input is Function {
  *
  * **When to use**
  *
- * - You need a guard for optional values.
+ * Use when you need a guard for optional values.
  *
  * **Details**
  *
@@ -993,7 +1018,7 @@ export function isUndefined(input: unknown): input is undefined {
  *
  * **When to use**
  *
- * - You want to filter out `undefined` while preserving other falsy values.
+ * Use when you want to filter out `undefined` while preserving other falsy values.
  *
  * **Details**
  *
@@ -1025,7 +1050,7 @@ export function isNotUndefined<A>(input: A): input is Exclude<A, undefined> {
  *
  * **When to use**
  *
- * - You need a guard for nullable values.
+ * Use when you need a guard for nullable values.
  *
  * **Details**
  *
@@ -1056,7 +1081,7 @@ export function isNull(input: unknown): input is null {
  *
  * **When to use**
  *
- * - You want to filter out `null` while preserving other falsy values.
+ * Use when you want to filter out `null` while preserving other falsy values.
  *
  * **Details**
  *
@@ -1088,7 +1113,7 @@ export function isNotNull<A>(input: A): input is Exclude<A, null> {
  *
  * **When to use**
  *
- * - You want to guard nullish values explicitly.
+ * Use when you want to guard nullish values explicitly.
  *
  * **Details**
  *
@@ -1121,7 +1146,7 @@ export function isNullish<A>(input: A): input is A & (null | undefined) {
  *
  * **When to use**
  *
- * - You want to filter out nullish values but keep other falsy ones.
+ * Use when you want to filter out nullish values but keep other falsy ones.
  *
  * **Details**
  *
@@ -1154,7 +1179,7 @@ export function isNotNullish<A>(input: A): input is NonNullable<A> {
  *
  * **When to use**
  *
- * - You need a predicate that never accepts, e.g. in default branches.
+ * Use when you need a predicate that never accepts, e.g. in default branches.
  *
  * **Details**
  *
@@ -1182,7 +1207,7 @@ export function isNever(_: unknown): _ is never {
  *
  * **When to use**
  *
- * - You need a predicate that always accepts, e.g. as a placeholder.
+ * Use when you need a predicate that always accepts, e.g. as a placeholder.
  *
  * **Details**
  *
@@ -1210,7 +1235,7 @@ export function isUnknown(_: unknown): _ is unknown {
  *
  * **When to use**
  *
- * - You want to accept plain objects and arrays, but not `null`.
+ * Use when you want to accept plain objects and arrays, but not `null`.
  *
  * **Details**
  *
@@ -1238,6 +1263,10 @@ export function isObjectOrArray(input: unknown): input is { [x: PropertyKey]: un
 /**
  * Checks whether a value is a non-null object value that is not an array.
  *
+ * **When to use**
+ *
+ * Use to narrow unknown input to a non-null, non-array object.
+ *
  * **Details**
  *
  * This is a structural runtime check using `typeof input === "object"`, so it
@@ -1266,6 +1295,11 @@ export function isObject(input: unknown): input is { [x: PropertyKey]: unknown }
  * Checks whether a value is a non-null, non-array object and narrows it to a
  * readonly indexable object type.
  *
+ * **When to use**
+ *
+ * Use to narrow unknown input to a readonly view of a non-null, non-array
+ * object.
+ *
  * **Details**
  *
  * Readonly-ness is a TypeScript type-level view; it is not observable at
@@ -1295,7 +1329,7 @@ export function isReadonlyObject(input: unknown): input is { readonly [x: Proper
  *
  * **When to use**
  *
- * - You want to accept arrays and functions as well as objects.
+ * Use when you want to accept arrays and functions as well as objects.
  *
  * **Details**
  *
@@ -1325,7 +1359,7 @@ export function isObjectKeyword(input: unknown): input is object {
  *
  * **When to use**
  *
- * - You need to guard property access on `unknown` values.
+ * Use when you need to guard property access on `unknown` values.
  * - You want a simple structural guard for objects.
  *
  * **Details**
@@ -1358,7 +1392,7 @@ export const hasProperty: {
    *
    * **When to use**
    *
-   * - You need to guard property access on `unknown` values.
+   * Use when you need to guard property access on `unknown` values.
    * - You want a simple structural guard for objects.
    *
    * **Details**
@@ -1391,7 +1425,7 @@ export const hasProperty: {
    *
    * **When to use**
    *
-   * - You need to guard property access on `unknown` values.
+   * Use when you need to guard property access on `unknown` values.
    * - You want a simple structural guard for objects.
    *
    * **Details**
@@ -1430,7 +1464,7 @@ export const hasProperty: {
  *
  * **When to use**
  *
- * - You model tagged unions with a `_tag` field.
+ * Use when you model tagged unions with a `_tag` field.
  * - You want a quick, structural guard for tagged values.
  *
  * **Details**
@@ -1458,7 +1492,7 @@ export const isTagged: {
    *
    * **When to use**
    *
-   * - You model tagged unions with a `_tag` field.
+   * Use when you model tagged unions with a `_tag` field.
    * - You want a quick, structural guard for tagged values.
    *
    * **Details**
@@ -1486,7 +1520,7 @@ export const isTagged: {
    *
    * **When to use**
    *
-   * - You model tagged unions with a `_tag` field.
+   * Use when you model tagged unions with a `_tag` field.
    * - You want a quick, structural guard for tagged values.
    *
    * **Details**
@@ -1519,7 +1553,7 @@ export const isTagged: {
  *
  * **When to use**
  *
- * - You need to guard errors caught from unknown sources.
+ * Use when you need to guard errors caught from unknown sources.
  *
  * **Details**
  *
@@ -1549,7 +1583,7 @@ export function isError(input: unknown): input is Error {
  *
  * **When to use**
  *
- * - You need to guard binary data at runtime.
+ * Use when you need to guard binary data at runtime.
  *
  * **Details**
  *
@@ -1580,7 +1614,7 @@ export function isUint8Array(input: unknown): input is Uint8Array {
  *
  * **When to use**
  *
- * - You need to guard dates at runtime.
+ * Use when you need to guard dates at runtime.
  *
  * **Details**
  *
@@ -1610,7 +1644,7 @@ export function isDate(input: unknown): input is Date {
  *
  * **When to use**
  *
- * - You need a guard before iterating an unknown value.
+ * Use when you need a guard before iterating an unknown value.
  *
  * **Details**
  *
@@ -1642,7 +1676,7 @@ export function isIterable(input: unknown): input is Iterable<unknown> {
  *
  * **When to use**
  *
- * - You need to detect promise instances across realms.
+ * Use when you need to detect promise instances across realms.
  *
  * **Details**
  *
@@ -1672,7 +1706,7 @@ export function isPromise(input: unknown): input is Promise<unknown> {
  *
  * **When to use**
  *
- * - You only need `then` to interop with promise-like values.
+ * Use when you only need `then` to interop with promise-like values.
  *
  * **Details**
  *
@@ -1702,7 +1736,7 @@ export function isPromiseLike(input: unknown): input is PromiseLike<unknown> {
  *
  * **When to use**
  *
- * - You need a runtime guard for regular expressions.
+ * Use when you need a runtime guard for regular expressions.
  *
  * **Details**
  *
@@ -1732,7 +1766,7 @@ export function isRegExp(input: unknown): input is RegExp {
  *
  * **When to use**
  *
- * - You want to chain two refinements for progressive narrowing.
+ * Use when you want to chain two refinements for progressive narrowing.
  * - You want a predicate that applies two checks in sequence.
  *
  * **Details**
@@ -1765,7 +1799,7 @@ export const compose: {
    *
    * **When to use**
    *
-   * - You want to chain two refinements for progressive narrowing.
+   * Use when you want to chain two refinements for progressive narrowing.
    * - You want a predicate that applies two checks in sequence.
    *
    * **Details**
@@ -1798,7 +1832,7 @@ export const compose: {
    *
    * **When to use**
    *
-   * - You want to chain two refinements for progressive narrowing.
+   * Use when you want to chain two refinements for progressive narrowing.
    * - You want a predicate that applies two checks in sequence.
    *
    * **Details**
@@ -1831,7 +1865,7 @@ export const compose: {
    *
    * **When to use**
    *
-   * - You want to chain two refinements for progressive narrowing.
+   * Use when you want to chain two refinements for progressive narrowing.
    * - You want a predicate that applies two checks in sequence.
    *
    * **Details**
@@ -1864,7 +1898,7 @@ export const compose: {
    *
    * **When to use**
    *
-   * - You want to chain two refinements for progressive narrowing.
+   * Use when you want to chain two refinements for progressive narrowing.
    * - You want a predicate that applies two checks in sequence.
    *
    * **Details**
@@ -1903,7 +1937,7 @@ export const compose: {
  *
  * **When to use**
  *
- * - You want to validate tuple positions independently.
+ * Use when you want to validate tuple positions independently.
  * - You want to lift element predicates into a tuple predicate.
  *
  * **Details**
@@ -1950,7 +1984,7 @@ export function Tuple<const T extends ReadonlyArray<Predicate.Any>>(
  *
  * **When to use**
  *
- * - You want to validate a record shape at runtime.
+ * Use when you want to validate a record shape at runtime.
  * - You want to lift property predicates into an object predicate.
  *
  * **Details**
@@ -2001,7 +2035,7 @@ export function Struct<R extends Record<string, Predicate.Any>>(
  *
  * **When to use**
  *
- * - You want the inverse of an existing predicate.
+ * Use when you want the inverse of an existing predicate.
  *
  * **Details**
  *
@@ -2033,7 +2067,7 @@ export function not<A>(self: Predicate<A>): Predicate<A> {
  *
  * **When to use**
  *
- * - You want to accept values that satisfy at least one condition.
+ * Use when you want to accept values that satisfy at least one condition.
  * - You want to combine refinements with union narrowing.
  *
  * **Details**
@@ -2063,7 +2097,7 @@ export const or: {
    *
    * **When to use**
    *
-   * - You want to accept values that satisfy at least one condition.
+   * Use when you want to accept values that satisfy at least one condition.
    * - You want to combine refinements with union narrowing.
    *
    * **Details**
@@ -2093,7 +2127,7 @@ export const or: {
    *
    * **When to use**
    *
-   * - You want to accept values that satisfy at least one condition.
+   * Use when you want to accept values that satisfy at least one condition.
    * - You want to combine refinements with union narrowing.
    *
    * **Details**
@@ -2123,7 +2157,7 @@ export const or: {
    *
    * **When to use**
    *
-   * - You want to accept values that satisfy at least one condition.
+   * Use when you want to accept values that satisfy at least one condition.
    * - You want to combine refinements with union narrowing.
    *
    * **Details**
@@ -2153,7 +2187,7 @@ export const or: {
    *
    * **When to use**
    *
-   * - You want to accept values that satisfy at least one condition.
+   * Use when you want to accept values that satisfy at least one condition.
    * - You want to combine refinements with union narrowing.
    *
    * **Details**
@@ -2185,7 +2219,7 @@ export const or: {
  *
  * **When to use**
  *
- * - You want to accept values that satisfy multiple conditions.
+ * Use when you want to accept values that satisfy multiple conditions.
  * - You want to combine refinements with intersection narrowing.
  *
  * **Details**
@@ -2223,7 +2257,7 @@ export const and: {
    *
    * **When to use**
    *
-   * - You want to accept values that satisfy multiple conditions.
+   * Use when you want to accept values that satisfy multiple conditions.
    * - You want to combine refinements with intersection narrowing.
    *
    * **Details**
@@ -2261,7 +2295,7 @@ export const and: {
    *
    * **When to use**
    *
-   * - You want to accept values that satisfy multiple conditions.
+   * Use when you want to accept values that satisfy multiple conditions.
    * - You want to combine refinements with intersection narrowing.
    *
    * **Details**
@@ -2299,7 +2333,7 @@ export const and: {
    *
    * **When to use**
    *
-   * - You want to accept values that satisfy multiple conditions.
+   * Use when you want to accept values that satisfy multiple conditions.
    * - You want to combine refinements with intersection narrowing.
    *
    * **Details**
@@ -2337,7 +2371,7 @@ export const and: {
    *
    * **When to use**
    *
-   * - You want to accept values that satisfy multiple conditions.
+   * Use when you want to accept values that satisfy multiple conditions.
    * - You want to combine refinements with intersection narrowing.
    *
    * **Details**
@@ -2377,7 +2411,7 @@ export const and: {
  *
  * **When to use**
  *
- * - You want an exclusive-or between two conditions.
+ * Use when you want an exclusive-or between two conditions.
  *
  * **Details**
  *
@@ -2407,7 +2441,7 @@ export const xor: {
    *
    * **When to use**
    *
-   * - You want an exclusive-or between two conditions.
+   * Use when you want an exclusive-or between two conditions.
    *
    * **Details**
    *
@@ -2437,7 +2471,7 @@ export const xor: {
    *
    * **When to use**
    *
-   * - You want an exclusive-or between two conditions.
+   * Use when you want an exclusive-or between two conditions.
    *
    * **Details**
    *
@@ -2469,7 +2503,7 @@ export const xor: {
  *
  * **When to use**
  *
- * - You want to check equivalence of two predicates.
+ * Use when you want to check equivalence of two predicates.
  *
  * **Details**
  *
@@ -2497,7 +2531,7 @@ export const eqv: {
    *
    * **When to use**
    *
-   * - You want to check equivalence of two predicates.
+   * Use when you want to check equivalence of two predicates.
    *
    * **Details**
    *
@@ -2525,7 +2559,7 @@ export const eqv: {
    *
    * **When to use**
    *
-   * - You want to check equivalence of two predicates.
+   * Use when you want to check equivalence of two predicates.
    *
    * **Details**
    *
@@ -2555,7 +2589,7 @@ export const eqv: {
  *
  * **When to use**
  *
- * - You want a rule that only applies when a precondition holds.
+ * Use when you want a rule that only applies when a precondition holds.
  * - You model constraints like "if A then B".
  *
  * **Details**
@@ -2586,7 +2620,7 @@ export const implies: {
    *
    * **When to use**
    *
-   * - You want a rule that only applies when a precondition holds.
+   * Use when you want a rule that only applies when a precondition holds.
    * - You model constraints like "if A then B".
    *
    * **Details**
@@ -2617,7 +2651,7 @@ export const implies: {
    *
    * **When to use**
    *
-   * - You want a rule that only applies when a precondition holds.
+   * Use when you want a rule that only applies when a precondition holds.
    * - You model constraints like "if A then B".
    *
    * **Details**
@@ -2653,7 +2687,7 @@ export const implies: {
  *
  * **When to use**
  *
- * - You want the logical NOR of two conditions.
+ * Use when you want the logical NOR of two conditions.
  *
  * **Details**
  *
@@ -2681,7 +2715,7 @@ export const nor: {
    *
    * **When to use**
    *
-   * - You want the logical NOR of two conditions.
+   * Use when you want the logical NOR of two conditions.
    *
    * **Details**
    *
@@ -2709,7 +2743,7 @@ export const nor: {
    *
    * **When to use**
    *
-   * - You want the logical NOR of two conditions.
+   * Use when you want the logical NOR of two conditions.
    *
    * **Details**
    *
@@ -2742,7 +2776,7 @@ export const nor: {
  *
  * **When to use**
  *
- * - You want the logical NAND of two conditions.
+ * Use when you want the logical NAND of two conditions.
  *
  * **Details**
  *
@@ -2770,7 +2804,7 @@ export const nand: {
    *
    * **When to use**
    *
-   * - You want the logical NAND of two conditions.
+   * Use when you want the logical NAND of two conditions.
    *
    * **Details**
    *
@@ -2798,7 +2832,7 @@ export const nand: {
    *
    * **When to use**
    *
-   * - You want the logical NAND of two conditions.
+   * Use when you want the logical NAND of two conditions.
    *
    * **Details**
    *
@@ -2831,7 +2865,7 @@ export const nand: {
  *
  * **When to use**
  *
- * - You have a dynamic list of predicates to apply.
+ * Use when you have a dynamic list of predicates to apply.
  *
  * **Details**
  *
@@ -2870,7 +2904,7 @@ export function every<A>(collection: Iterable<Predicate<A>>): Predicate<A> {
  *
  * **When to use**
  *
- * - You have a dynamic list of predicates and only need one to pass.
+ * Use when you have a dynamic list of predicates and only need one to pass.
  *
  * **Details**
  *