effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/Predicate.ts

@@ -73,14 +73,14 @@ import type { TupleOf, TupleOfAtLeast } from "./Types.ts"
  *
  * **When to use**
  *
- * 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.
+ * Use when you want a reusable boolean check for `A`, especially when you plan
+ * to combine checks with {@link and}/{@link or} or pass a predicate to arrays
+ * and iterables.
  *
  * **Details**
  *
- * - Returns `true` or `false`; never throws by itself.
- * - Does not narrow types unless you use {@link Refinement}.
+ * A predicate returns `true` or `false` and never throws by itself. It does not
+ * narrow types unless you use `Refinement`.
  *
  * **Example** (Define a predicate)
  *
@@ -107,13 +107,13 @@ export interface Predicate<in A> {
  *
  * **When to use**
  *
- * Use when you are defining APIs that abstract over predicates with HKTs.
- * - You need a `TypeLambda` instance for predicate-based type classes.
+ * Use when you are defining APIs that abstract over predicates with HKTs and
+ * need a `TypeLambda` instance for predicate-based type classes.
  *
  * **Details**
  *
- * - Type-only; no runtime value is created.
- * - Does not affect emitted JavaScript.
+ * This is type-only, creates no runtime value, and does not affect emitted
+ * JavaScript.
  *
  * **Example** (Type-level usage)
  *
@@ -137,14 +137,14 @@ export interface PredicateTypeLambda extends TypeLambda {
  *
  * **When to use**
  *
- * 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.
+ * Use when you want a runtime check that refines `A` to `B` for TypeScript,
+ * especially when composing type guards with {@link compose} or safely
+ * checking `unknown` values.
  *
  * **Details**
  *
- * - Returns a type predicate (`a is B`).
- * - Use with `if`/`filter` to narrow types.
+ * A refinement returns a type predicate (`a is B`). Use it with `if` or
+ * `filter` to narrow types.
  *
  * **Example** (Narrow unknown)
  *
@@ -174,13 +174,13 @@ export interface Refinement<in A, out B extends A> {
  *
  * **When to use**
  *
- * Use when you need to extract input types from predicate signatures.
- * - You want to write generic helpers over predicate types.
+ * Use when you need to extract input types from predicate signatures while
+ * writing generic helpers over predicate types.
  *
  * **Details**
  *
- * - Type-only; no runtime value is created.
- * - The namespace is erased at runtime.
+ * These utilities are type-only, create no runtime values, and the namespace is
+ * erased at runtime.
  *
  * **Example** (Extract predicate input)
  *
@@ -201,13 +201,13 @@ export declare namespace Predicate {
    *
    * **When to use**
    *
-   * Use when you want to infer the input type from a predicate type.
-   * - You are defining generic utilities over predicates.
+   * Use when you want to infer the input type from a predicate type while
+   * defining generic utilities over predicates.
    *
    * **Details**
    *
-   * - Type-only; no runtime value is created.
-   * - Resolves to `never` if the type does not match `Predicate`.
+   * This is type-only and creates no runtime value. It resolves to `never` if
+   * the type does not match `Predicate`.
    *
    * **Example** (Infer input)
    *
@@ -220,7 +220,7 @@ export declare namespace Predicate {
    *
    * @see {@link Predicate.Any}
    * @see {@link Refinement.In}
-   * @category type-level
+   * @category utility types
    * @since 3.6.0
    */
   export type In<T extends Any> = [T] extends [Predicate<infer _A>] ? _A : never
@@ -234,7 +234,7 @@ export declare namespace Predicate {
    *
    * **Details**
    *
-   * - Type-only; no runtime value is created.
+   * This is type-only and creates no runtime value.
    *
    * **Example** (Generic constraint)
    *
@@ -245,7 +245,7 @@ export declare namespace Predicate {
    * ```
    *
    * @see {@link Predicate.In}
-   * @category type-level
+   * @category utility types
    * @since 3.6.0
    */
   export type Any = Predicate<any>
@@ -256,13 +256,13 @@ export declare namespace Predicate {
  *
  * **When to use**
  *
- * Use when you need to extract input/output types from refinement signatures.
- * - You want to write generic helpers over refinements.
+ * Use when you need to extract input and output types from refinement
+ * signatures while writing generic helpers over refinements.
  *
  * **Details**
  *
- * - Type-only; no runtime value is created.
- * - The namespace is erased at runtime.
+ * These utilities are type-only, create no runtime values, and the namespace is
+ * erased at runtime.
  *
  * **Example** (Extract refinement types)
  *
@@ -288,8 +288,8 @@ export declare namespace Refinement {
    *
    * **Details**
    *
-   * - Type-only; no runtime value is created.
-   * - Resolves to `never` if the type does not match `Refinement`.
+   * This is type-only and creates no runtime value. It resolves to `never` if
+   * the type does not match `Refinement`.
    *
    * **Example** (Infer input)
    *
@@ -302,7 +302,7 @@ export declare namespace Refinement {
    *
    * @see {@link Refinement.Out}
    * @see {@link Predicate.In}
-   * @category type-level
+   * @category utility types
    * @since 3.6.0
    */
 
@@ -317,8 +317,8 @@ export declare namespace Refinement {
    *
    * **Details**
    *
-   * - Type-only; no runtime value is created.
-   * - Resolves to `never` if the type does not match `Refinement`.
+   * This is type-only and creates no runtime value. It resolves to `never` if
+   * the type does not match `Refinement`.
    *
    * **Example** (Infer output)
    *
@@ -330,7 +330,7 @@ export declare namespace Refinement {
    * ```
    *
    * @see {@link Refinement.In}
-   * @category type-level
+   * @category utility types
    * @since 3.6.0
    */
   export type Out<T extends Any> = [T] extends [Refinement<infer _, infer _B>] ? _B : never
@@ -344,7 +344,7 @@ export declare namespace Refinement {
    *
    * **Details**
    *
-   * - Type-only; no runtime value is created.
+   * This is type-only and creates no runtime value.
    *
    * **Example** (Generic constraint)
    *
@@ -356,7 +356,7 @@ export declare namespace Refinement {
    *
    * @see {@link Refinement.In}
    * @see {@link Refinement.Out}
-   * @category type-level
+   * @category utility types
    * @since 3.6.0
    */
   export type Any = Refinement<any, any>
@@ -367,13 +367,13 @@ export declare namespace Refinement {
  *
  * **When to use**
  *
- * 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.).
+ * Use when you have a predicate on `A` and want to check `B` values by mapping
+ * each `B` to an `A`, such as checking lengths or projections.
  *
  * **Details**
  *
- * - Returns a new predicate that applies `f` before `self`.
- * - No short-circuit beyond what `self` does.
+ * Returns a new predicate that applies `f` before `self`. There is no
+ * additional short-circuiting beyond what `self` does.
  *
  * **Example** (Check string length)
  *
@@ -399,13 +399,13 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * 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.).
+   * Use when you have a predicate on `A` and want to check `B` values by mapping
+   * each `B` to an `A`, such as checking lengths or projections.
    *
    * **Details**
    *
-   * - Returns a new predicate that applies `f` before `self`.
-   * - No short-circuit beyond what `self` does.
+   * Returns a new predicate that applies `f` before `self`. There is no
+   * additional short-circuiting beyond what `self` does.
    *
    * **Example** (Check string length)
    *
@@ -431,13 +431,13 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * 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.).
+   * Use when you have a predicate on `A` and want to check `B` values by mapping
+   * each `B` to an `A`, such as checking lengths or projections.
    *
    * **Details**
    *
-   * - Returns a new predicate that applies `f` before `self`.
-   * - No short-circuit beyond what `self` does.
+   * Returns a new predicate that applies `f` before `self`. There is no
+   * additional short-circuiting beyond what `self` does.
    *
    * **Example** (Check string length)
    *
@@ -465,13 +465,13 @@ export const mapInput: {
  *
  * **When to use**
  *
- * Use when you need a runtime check for tuple length.
- * - You want to narrow `ReadonlyArray<T>` to `TupleOf<N, T>`.
+ * Use when you need a `Predicate` guard for exact tuple length that narrows
+ * `ReadonlyArray<T>` to `TupleOf<N, T>`.
  *
  * **Details**
  *
- * - Only checks length, not element types.
- * - Returns a refinement on the array type.
+ * This only checks length, not element types, and returns a refinement on the
+ * array type.
  *
  * **Example** (Exact length)
  *
@@ -494,13 +494,13 @@ export const isTupleOf: {
    *
    * **When to use**
    *
-   * Use when you need a runtime check for tuple length.
-   * - You want to narrow `ReadonlyArray<T>` to `TupleOf<N, T>`.
+   * Use when you need a `Predicate` guard for exact tuple length that narrows
+   * `ReadonlyArray<T>` to `TupleOf<N, T>`.
    *
    * **Details**
    *
-   * - Only checks length, not element types.
-   * - Returns a refinement on the array type.
+   * This only checks length, not element types, and returns a refinement on the
+   * array type.
    *
    * **Example** (Exact length)
    *
@@ -523,13 +523,13 @@ export const isTupleOf: {
    *
    * **When to use**
    *
-   * Use when you need a runtime check for tuple length.
-   * - You want to narrow `ReadonlyArray<T>` to `TupleOf<N, T>`.
+   * Use when you need a `Predicate` guard for exact tuple length that narrows
+   * `ReadonlyArray<T>` to `TupleOf<N, T>`.
    *
    * **Details**
    *
-   * - Only checks length, not element types.
-   * - Returns a refinement on the array type.
+   * This only checks length, not element types, and returns a refinement on the
+   * array type.
    *
    * **Example** (Exact length)
    *
@@ -554,13 +554,13 @@ export const isTupleOf: {
  *
  * **When to use**
  *
- * Use when you need a runtime check for tuple-like minimum length.
- * - You want to narrow `ReadonlyArray<T>` to `TupleOfAtLeast<N, T>`.
+ * Use when you need a `Predicate` guard for tuple-like minimum length that
+ * narrows `ReadonlyArray<T>` to `TupleOfAtLeast<N, T>`.
  *
  * **Details**
  *
- * - Only checks length, not element types.
- * - Returns a refinement on the array type.
+ * This only checks length, not element types, and returns a refinement on the
+ * array type.
  *
  * **Example** (Minimum length)
  *
@@ -583,13 +583,13 @@ export const isTupleOfAtLeast: {
    *
    * **When to use**
    *
-   * Use when you need a runtime check for tuple-like minimum length.
-   * - You want to narrow `ReadonlyArray<T>` to `TupleOfAtLeast<N, T>`.
+   * Use when you need a `Predicate` guard for tuple-like minimum length that
+   * narrows `ReadonlyArray<T>` to `TupleOfAtLeast<N, T>`.
    *
    * **Details**
    *
-   * - Only checks length, not element types.
-   * - Returns a refinement on the array type.
+   * This only checks length, not element types, and returns a refinement on the
+   * array type.
    *
    * **Example** (Minimum length)
    *
@@ -612,13 +612,13 @@ export const isTupleOfAtLeast: {
    *
    * **When to use**
    *
-   * Use when you need a runtime check for tuple-like minimum length.
-   * - You want to narrow `ReadonlyArray<T>` to `TupleOfAtLeast<N, T>`.
+   * Use when you need a `Predicate` guard for tuple-like minimum length that
+   * narrows `ReadonlyArray<T>` to `TupleOfAtLeast<N, T>`.
    *
    * **Details**
    *
-   * - Only checks length, not element types.
-   * - Returns a refinement on the array type.
+   * This only checks length, not element types, and returns a refinement on the
+   * array type.
    *
    * **Example** (Minimum length)
    *
@@ -643,13 +643,13 @@ export const isTupleOfAtLeast: {
  *
  * **When to use**
  *
- * Use when you want a predicate that mirrors JavaScript truthiness.
- * - You need to filter out falsy values like `0`, "", and `false`.
+ * Use when you want a predicate that mirrors JavaScript truthiness and filters
+ * out falsy values like `0`, `""`, and `false`.
  *
  * **Details**
  *
- * - Uses `!!input` under the hood.
- * - Treats `0`, "", `false`, `null`, and `undefined` as false.
+ * This uses `!!input` and treats `0`, `""`, `false`, `null`, and `undefined`
+ * as false.
  *
  * **Example** (Filter truthy)
  *
@@ -676,11 +676,11 @@ export function isTruthy(input: unknown): boolean {
  *
  * **When to use**
  *
- * Use when you need a runtime guard for `Set` values.
+ * Use when you need a `Predicate` runtime guard for `Set` values.
  *
  * **Details**
  *
- * - Uses `instanceof Set`.
+ * Uses `instanceof Set`.
  *
  * **Example** (Guard a Set)
  *
@@ -708,11 +708,11 @@ export function isSet(input: unknown): input is Set<unknown> {
  *
  * **When to use**
  *
- * Use when you need a runtime guard for `Map` values.
+ * Use when you need a `Predicate` runtime guard for `Map` values.
  *
  * **Details**
  *
- * - Uses `instanceof Map`.
+ * Uses `instanceof Map`.
  *
  * **Example** (Guard a Map)
  *
@@ -740,12 +740,12 @@ export function isMap(input: unknown): input is Map<unknown, unknown> {
  *
  * **When to use**
  *
- * Use when you need to guard an `unknown` value as a string.
- * - You want to narrow in `if` statements.
+ * Use when you need a `Predicate` guard to narrow an `unknown` value to a
+ * string.
  *
  * **Details**
  *
- * - Uses `typeof input === "string"`.
+ * Uses `typeof input === "string"`.
  *
  * **Example** (Guard string)
  *
@@ -774,12 +774,12 @@ export function isString(input: unknown): input is string {
  *
  * **When to use**
  *
- * Use when you need to guard an `unknown` value as a number.
+ * Use when you need a `Predicate` guard to narrow an `unknown` value to a
+ * number.
  *
  * **Details**
  *
- * - Uses `typeof input === "number"`.
- * - Does not exclude `NaN` or `Infinity`.
+ * Uses `typeof input === "number"` and does not exclude `NaN` or `Infinity`.
  *
  * **Example** (Guard number)
  *
@@ -807,11 +807,12 @@ export function isNumber(input: unknown): input is number {
  *
  * **When to use**
  *
- * Use when you need to guard an `unknown` value as a boolean.
+ * Use when you need a `Predicate` guard to narrow an `unknown` value to a
+ * boolean.
  *
  * **Details**
  *
- * - Uses `typeof input === "boolean"`.
+ * Uses `typeof input === "boolean"`.
  *
  * **Example** (Guard boolean)
  *
@@ -839,11 +840,12 @@ export function isBoolean(input: unknown): input is boolean {
  *
  * **When to use**
  *
- * Use when you need to guard an `unknown` value as a bigint.
+ * Use when you need a `Predicate` guard to narrow an `unknown` value to a
+ * bigint.
  *
  * **Details**
  *
- * - Uses `typeof input === "bigint"`.
+ * Uses `typeof input === "bigint"`.
  *
  * **Example** (Guard bigint)
  *
@@ -870,11 +872,12 @@ export function isBigInt(input: unknown): input is bigint {
  *
  * **When to use**
  *
- * Use when you need to guard an `unknown` value as a symbol.
+ * Use when you need a `Predicate` guard to narrow an `unknown` value to a
+ * symbol.
  *
  * **Details**
  *
- * - Uses `typeof input === "symbol"`.
+ * Uses `typeof input === "symbol"`.
  *
  * **Example** (Guard symbol)
  *
@@ -901,11 +904,12 @@ export function isSymbol(input: unknown): input is symbol {
  *
  * **When to use**
  *
- * Use when you need to guard unknown keys before indexing.
+ * Use when you need a `Predicate` guard for unknown property keys before
+ * indexing.
  *
  * **Details**
  *
- * - Uses {@link isString}, {@link isNumber}, and {@link isSymbol}.
+ * Uses `isString`, `isNumber`, and `isSymbol`.
  *
  * **Example** (Guard property key)
  *
@@ -935,11 +939,12 @@ export function isPropertyKey(u: unknown): u is PropertyKey {
  *
  * **When to use**
  *
- * Use when you need to guard an `unknown` value as callable.
+ * Use when you need a `Predicate` guard to narrow an `unknown` value to a
+ * callable function.
  *
  * **Details**
  *
- * - Uses `typeof input === "function"`.
+ * Uses `typeof input === "function"`.
  *
  * **Example** (Guard function)
  *
@@ -966,11 +971,12 @@ export function isFunction(input: unknown): input is Function {
  *
  * **When to use**
  *
- * Use when you need a guard for optional values.
+ * Use when you need a `Predicate` guard for values that are exactly
+ * `undefined`.
  *
  * **Details**
  *
- * - Uses `input === undefined`.
+ * Uses `input === undefined`.
  *
  * **Example** (Guard undefined)
  *
@@ -996,11 +1002,12 @@ export function isUndefined(input: unknown): input is undefined {
  *
  * **When to use**
  *
- * Use when you want to filter out `undefined` while preserving other falsy values.
+ * Use when you need a `Predicate` refinement that filters out `undefined`
+ * while preserving other falsy values.
  *
  * **Details**
  *
- * - Returns a refinement that excludes `undefined`.
+ * Returns a refinement that excludes `undefined`.
  *
  * **Example** (Filter undefined)
  *
@@ -1027,11 +1034,11 @@ export function isNotUndefined<A>(input: A): input is Exclude<A, undefined> {
  *
  * **When to use**
  *
- * Use when you need a guard for nullable values.
+ * Use when you need a `Predicate` guard for nullable values.
  *
  * **Details**
  *
- * - Uses `input === null`.
+ * Uses `input === null`.
  *
  * **Example** (Guard null)
  *
@@ -1057,11 +1064,12 @@ export function isNull(input: unknown): input is null {
  *
  * **When to use**
  *
- * Use when you want to filter out `null` while preserving other falsy values.
+ * Use when you need a `Predicate` refinement that filters out `null` while
+ * preserving other falsy values.
  *
  * **Details**
  *
- * - Returns a refinement that excludes `null`.
+ * Returns a refinement that excludes `null`.
  *
  * **Example** (Filter null)
  *
@@ -1088,11 +1096,11 @@ export function isNotNull<A>(input: A): input is Exclude<A, null> {
  *
  * **When to use**
  *
- * Use when you want to guard nullish values explicitly.
+ * Use when you need a `Predicate` guard for nullish values.
  *
  * **Details**
  *
- * - Uses `input === null || input === undefined`.
+ * Uses `input === null || input === undefined`.
  *
  * **Example** (Guard nullish)
  *
@@ -1120,11 +1128,12 @@ export function isNullish<A>(input: A): input is A & (null | undefined) {
  *
  * **When to use**
  *
- * Use when you want to filter out nullish values but keep other falsy ones.
+ * Use when you need a `Predicate` refinement that filters out nullish values
+ * but keeps other falsy ones.
  *
  * **Details**
  *
- * - Uses `input != null`.
+ * Uses `input != null`.
  *
  * **Example** (Filter non-nullish)
  *
@@ -1152,11 +1161,7 @@ export function isNotNullish<A>(input: A): input is NonNullable<A> {
  *
  * **When to use**
  *
- * Use when you need a predicate that never accepts, e.g. in default branches.
- *
- * **Details**
- *
- * - Always returns `false`.
+ * Use when you need a `Predicate` that never accepts, e.g. in default branches.
  *
  * **Example** (Never matches)
  *
@@ -1179,11 +1184,7 @@ export function isNever(_: unknown): _ is never {
  *
  * **When to use**
  *
- * Use when you need a predicate that always accepts, e.g. as a placeholder.
- *
- * **Details**
- *
- * - Always returns `true`.
+ * Use when you need a `Predicate` that always accepts, e.g. as a placeholder.
  *
  * **Example** (Always matches)
  *
@@ -1206,12 +1207,12 @@ export function isUnknown(_: unknown): _ is unknown {
  *
  * **When to use**
  *
- * Use when you want to accept plain objects and arrays, but not `null`.
+ * Use when you need a `Predicate` guard that accepts plain objects and arrays,
+ * but not `null`.
  *
  * **Details**
  *
- * - Uses `typeof input === "object" && input !== null`.
- * - Includes arrays.
+ * Uses `typeof input === "object" && input !== null` and includes arrays.
  *
  * **Example** (Object or array)
  *
@@ -1235,7 +1236,8 @@ export function isObjectOrArray(input: unknown): input is { [x: PropertyKey]: un
  *
  * **When to use**
  *
- * Use to narrow unknown input to a non-null, non-array object.
+ * Use to narrow unknown input to a non-null, non-array object with a
+ * `Predicate` guard.
  *
  * **Details**
  *
@@ -1268,7 +1270,7 @@ export function isObject(input: unknown): input is { [x: PropertyKey]: unknown }
  * **When to use**
  *
  * Use to narrow unknown input to a readonly view of a non-null, non-array
- * object.
+ * object with a `Predicate` guard.
  *
  * **Details**
  *
@@ -1299,11 +1301,12 @@ export function isReadonlyObject(input: unknown): input is { readonly [x: Proper
  *
  * **When to use**
  *
- * Use when you want to accept arrays and functions as well as objects.
+ * Use when you need a `Predicate` guard that accepts arrays and functions as
+ * well as objects.
  *
  * **Details**
  *
- * - Returns `true` for arrays and functions, `false` for `null`.
+ * Returns `true` for arrays and functions, and `false` for `null`.
  *
  * **Example** (Object keyword)
  *
@@ -1328,13 +1331,13 @@ export function isObjectKeyword(input: unknown): input is object {
  *
  * **When to use**
  *
- * Use when you need to guard property access on `unknown` values.
- * - You want a simple structural guard for objects.
+ * Use when you need a `Predicate` guard for property access on `unknown`
+ * values with a simple structural object check.
  *
  * **Details**
  *
- * - Uses the `in` operator and {@link isObjectKeyword}.
- * - Does not check property value types.
+ * Uses the `in` operator and `isObjectKeyword`. This does not check property
+ * value types.
  *
  * **Example** (Guard property)
  *
@@ -1360,13 +1363,13 @@ export const hasProperty: {
    *
    * **When to use**
    *
-   * Use when you need to guard property access on `unknown` values.
-   * - You want a simple structural guard for objects.
+   * Use when you need a `Predicate` guard for property access on `unknown`
+   * values with a simple structural object check.
    *
    * **Details**
    *
-   * - Uses the `in` operator and {@link isObjectKeyword}.
-   * - Does not check property value types.
+   * Uses the `in` operator and `isObjectKeyword`. This does not check property
+   * value types.
    *
    * **Example** (Guard property)
    *
@@ -1392,13 +1395,13 @@ export const hasProperty: {
    *
    * **When to use**
    *
-   * Use when you need to guard property access on `unknown` values.
-   * - You want a simple structural guard for objects.
+   * Use when you need a `Predicate` guard for property access on `unknown`
+   * values with a simple structural object check.
    *
    * **Details**
    *
-   * - Uses the `in` operator and {@link isObjectKeyword}.
-   * - Does not check property value types.
+   * Uses the `in` operator and `isObjectKeyword`. This does not check property
+   * value types.
    *
    * **Example** (Guard property)
    *
@@ -1430,12 +1433,12 @@ export const hasProperty: {
  *
  * **When to use**
  *
- * Use when you model tagged unions with a `_tag` field.
- * - You want a quick, structural guard for tagged values.
+ * Use when you model tagged unions with a `_tag` field and want a quick
+ * `Predicate` guard for tagged values.
  *
  * **Details**
  *
- * - Uses {@link hasProperty} and strict equality on `_tag`.
+ * Uses `hasProperty` and strict equality on `_tag`.
  *
  * **Example** (Guard tagged)
  *
@@ -1457,12 +1460,12 @@ export const isTagged: {
    *
    * **When to use**
    *
-   * Use when you model tagged unions with a `_tag` field.
-   * - You want a quick, structural guard for tagged values.
+   * Use when you model tagged unions with a `_tag` field and want a quick
+   * `Predicate` guard for tagged values.
    *
    * **Details**
    *
-   * - Uses {@link hasProperty} and strict equality on `_tag`.
+   * Uses `hasProperty` and strict equality on `_tag`.
    *
    * **Example** (Guard tagged)
    *
@@ -1484,12 +1487,12 @@ export const isTagged: {
    *
    * **When to use**
    *
-   * Use when you model tagged unions with a `_tag` field.
-   * - You want a quick, structural guard for tagged values.
+   * Use when you model tagged unions with a `_tag` field and want a quick
+   * `Predicate` guard for tagged values.
    *
    * **Details**
    *
-   * - Uses {@link hasProperty} and strict equality on `_tag`.
+   * Uses `hasProperty` and strict equality on `_tag`.
    *
    * **Example** (Guard tagged)
    *
@@ -1516,11 +1519,11 @@ export const isTagged: {
  *
  * **When to use**
  *
- * Use when you need to guard errors caught from unknown sources.
+ * Use when you need a `Predicate` guard for errors caught from unknown sources.
  *
  * **Details**
  *
- * - Uses `instanceof Error`.
+ * Uses `instanceof Error`.
  *
  * **Example** (Guard error)
  *
@@ -1545,11 +1548,11 @@ export function isError(input: unknown): input is Error {
  *
  * **When to use**
  *
- * Use when you need to guard binary data at runtime.
+ * Use when you need a `Predicate` runtime guard for binary data.
  *
  * **Details**
  *
- * - Uses `instanceof Uint8Array`.
+ * Uses `instanceof Uint8Array`.
  *
  * **Example** (Guard Uint8Array)
  *
@@ -1575,11 +1578,11 @@ export function isUint8Array(input: unknown): input is Uint8Array {
  *
  * **When to use**
  *
- * Use when you need to guard dates at runtime.
+ * Use when you need a `Predicate` runtime guard for dates.
  *
  * **Details**
  *
- * - Uses `instanceof Date`.
+ * Uses `instanceof Date`.
  *
  * **Example** (Guard Date)
  *
@@ -1604,12 +1607,11 @@ export function isDate(input: unknown): input is Date {
  *
  * **When to use**
  *
- * Use when you need a guard before iterating an unknown value.
+ * Use when you need a `Predicate` guard before iterating an unknown value.
  *
  * **Details**
  *
- * - Accepts strings as iterable.
- * - Uses {@link hasProperty} for `Symbol.iterator`.
+ * Accepts strings as iterable and uses `hasProperty` for `Symbol.iterator`.
  *
  * **Example** (Guard iterable)
  *
@@ -1635,11 +1637,11 @@ export function isIterable(input: unknown): input is Iterable<unknown> {
  *
  * **When to use**
  *
- * Use when you need to detect promise instances across realms.
+ * Use when you need a `Predicate` guard for promise instances across realms.
  *
  * **Details**
  *
- * - Structural check for `then` and `catch` functions.
+ * Performs a structural check for `then` and `catch` functions.
  *
  * **Example** (Guard promise)
  *
@@ -1664,11 +1666,12 @@ export function isPromise(input: unknown): input is Promise<unknown> {
  *
  * **When to use**
  *
- * Use when you only need `then` to interop with promise-like values.
+ * Use when you need a `Predicate` guard for promise-like values with a
+ * callable `then` method.
  *
  * **Details**
  *
- * - Structural check for a callable `then`.
+ * Performs a structural check for a callable `then`.
  *
  * **Example** (Guard promise-like)
  *
@@ -1693,11 +1696,11 @@ export function isPromiseLike(input: unknown): input is PromiseLike<unknown> {
  *
  * **When to use**
  *
- * Use when you need a runtime guard for regular expressions.
+ * Use when you need a `Predicate` runtime guard for regular expressions.
  *
  * **Details**
  *
- * - Uses `instanceof RegExp`.
+ * Uses `instanceof RegExp`.
  *
  * **Example** (Guard RegExp)
  *
@@ -1722,13 +1725,13 @@ export function isRegExp(input: unknown): input is RegExp {
  *
  * **When to use**
  *
- * Use when you want to chain two refinements for progressive narrowing.
- * - You want a predicate that applies two checks in sequence.
+ * Use when you want to compose two `Predicate` checks in sequence, especially
+ * when chaining refinements for progressive narrowing.
  *
  * **Details**
  *
- * - For refinements, the output type is narrowed by both.
- * - Short-circuits on the first `false`.
+ * For refinements, the output type is narrowed by both checks. Evaluation
+ * short-circuits on the first `false`.
  *
  * **Example** (Compose refinements)
  *
@@ -1754,13 +1757,13 @@ export const compose: {
    *
    * **When to use**
    *
-   * Use when you want to chain two refinements for progressive narrowing.
-   * - You want a predicate that applies two checks in sequence.
+   * Use when you want to compose two `Predicate` checks in sequence, especially
+   * when chaining refinements for progressive narrowing.
    *
    * **Details**
    *
-   * - For refinements, the output type is narrowed by both.
-   * - Short-circuits on the first `false`.
+   * For refinements, the output type is narrowed by both checks. Evaluation
+   * short-circuits on the first `false`.
    *
    * **Example** (Compose refinements)
    *
@@ -1786,13 +1789,13 @@ export const compose: {
    *
    * **When to use**
    *
-   * Use when you want to chain two refinements for progressive narrowing.
-   * - You want a predicate that applies two checks in sequence.
+   * Use when you want to compose two `Predicate` checks in sequence, especially
+   * when chaining refinements for progressive narrowing.
    *
    * **Details**
    *
-   * - For refinements, the output type is narrowed by both.
-   * - Short-circuits on the first `false`.
+   * For refinements, the output type is narrowed by both checks. Evaluation
+   * short-circuits on the first `false`.
    *
    * **Example** (Compose refinements)
    *
@@ -1818,13 +1821,13 @@ export const compose: {
    *
    * **When to use**
    *
-   * Use when you want to chain two refinements for progressive narrowing.
-   * - You want a predicate that applies two checks in sequence.
+   * Use when you want to compose two `Predicate` checks in sequence, especially
+   * when chaining refinements for progressive narrowing.
    *
    * **Details**
    *
-   * - For refinements, the output type is narrowed by both.
-   * - Short-circuits on the first `false`.
+   * For refinements, the output type is narrowed by both checks. Evaluation
+   * short-circuits on the first `false`.
    *
    * **Example** (Compose refinements)
    *
@@ -1850,13 +1853,13 @@ export const compose: {
    *
    * **When to use**
    *
-   * Use when you want to chain two refinements for progressive narrowing.
-   * - You want a predicate that applies two checks in sequence.
+   * Use when you want to compose two `Predicate` checks in sequence, especially
+   * when chaining refinements for progressive narrowing.
    *
    * **Details**
    *
-   * - For refinements, the output type is narrowed by both.
-   * - Short-circuits on the first `false`.
+   * For refinements, the output type is narrowed by both checks. Evaluation
+   * short-circuits on the first `false`.
    *
    * **Example** (Compose refinements)
    *
@@ -1888,13 +1891,13 @@ export const compose: {
  *
  * **When to use**
  *
- * Use when you want to validate tuple positions independently.
- * - You want to lift element predicates into a tuple predicate.
+ * Use when you want to validate tuple positions independently by lifting
+ * element predicates into a tuple predicate.
  *
  * **Details**
  *
- * - Returns a refinement if any element predicate is a refinement.
- * - Stops at the first failing element.
+ * Returns a refinement if any element predicate is a refinement. Evaluation
+ * stops at the first failing element.
  *
  * **Example** (Tuple predicate)
  *
@@ -1934,13 +1937,13 @@ export function Tuple<const T extends ReadonlyArray<Predicate.Any>>(
  *
  * **When to use**
  *
- * Use when you want to validate a record shape at runtime.
- * - You want to lift property predicates into an object predicate.
+ * Use when you want to validate a record shape at runtime by lifting property
+ * predicates into an object predicate.
  *
  * **Details**
  *
- * - Returns a refinement if any field predicate is a refinement.
- * - Checks only the specified keys; extra keys are ignored.
+ * Returns a refinement if any field predicate is a refinement. Only the
+ * specified keys are checked, and extra keys are ignored.
  *
  * **Example** (Struct predicate)
  *
@@ -1988,7 +1991,7 @@ export function Struct<R extends Record<string, Predicate.Any>>(
  *
  * **Details**
  *
- * - Returns a new predicate that flips the boolean result.
+ * Returns a new predicate that flips the boolean result.
  *
  * **Example** (Negate)
  *
@@ -2015,13 +2018,13 @@ export function not<A>(self: Predicate<A>): Predicate<A> {
  *
  * **When to use**
  *
- * Use when you want to accept values that satisfy at least one condition.
- * - You want to combine refinements with union narrowing.
+ * Use when you want to combine `Predicate`s with OR, accepting values that
+ * satisfy at least one condition, including refinements that narrow to a union.
  *
  * **Details**
  *
- * - Short-circuits on the first `true`.
- * - For refinements, the output type is a union.
+ * Evaluation short-circuits on the first `true`. For refinements, the output
+ * type is a union.
  *
  * **Example** (Either condition)
  *
@@ -2044,13 +2047,13 @@ export const or: {
    *
    * **When to use**
    *
-   * Use when you want to accept values that satisfy at least one condition.
-   * - You want to combine refinements with union narrowing.
+   * Use when you want to combine `Predicate`s with OR, accepting values that
+   * satisfy at least one condition, including refinements that narrow to a union.
    *
    * **Details**
    *
-   * - Short-circuits on the first `true`.
-   * - For refinements, the output type is a union.
+   * Evaluation short-circuits on the first `true`. For refinements, the output
+   * type is a union.
    *
    * **Example** (Either condition)
    *
@@ -2073,13 +2076,13 @@ export const or: {
    *
    * **When to use**
    *
-   * Use when you want to accept values that satisfy at least one condition.
-   * - You want to combine refinements with union narrowing.
+   * Use when you want to combine `Predicate`s with OR, accepting values that
+   * satisfy at least one condition, including refinements that narrow to a union.
    *
    * **Details**
    *
-   * - Short-circuits on the first `true`.
-   * - For refinements, the output type is a union.
+   * Evaluation short-circuits on the first `true`. For refinements, the output
+   * type is a union.
    *
    * **Example** (Either condition)
    *
@@ -2102,13 +2105,13 @@ export const or: {
    *
    * **When to use**
    *
-   * Use when you want to accept values that satisfy at least one condition.
-   * - You want to combine refinements with union narrowing.
+   * Use when you want to combine `Predicate`s with OR, accepting values that
+   * satisfy at least one condition, including refinements that narrow to a union.
    *
    * **Details**
    *
-   * - Short-circuits on the first `true`.
-   * - For refinements, the output type is a union.
+   * Evaluation short-circuits on the first `true`. For refinements, the output
+   * type is a union.
    *
    * **Example** (Either condition)
    *
@@ -2131,13 +2134,13 @@ export const or: {
    *
    * **When to use**
    *
-   * Use when you want to accept values that satisfy at least one condition.
-   * - You want to combine refinements with union narrowing.
+   * Use when you want to combine `Predicate`s with OR, accepting values that
+   * satisfy at least one condition, including refinements that narrow to a union.
    *
    * **Details**
    *
-   * - Short-circuits on the first `true`.
-   * - For refinements, the output type is a union.
+   * Evaluation short-circuits on the first `true`. For refinements, the output
+   * type is a union.
    *
    * **Example** (Either condition)
    *
@@ -2162,13 +2165,14 @@ export const or: {
  *
  * **When to use**
  *
- * Use when you want to accept values that satisfy multiple conditions.
- * - You want to combine refinements with intersection narrowing.
+ * Use when you want to combine `Predicate`s with AND, accepting values that
+ * satisfy multiple conditions, including refinements that narrow to an
+ * intersection.
  *
  * **Details**
  *
- * - Short-circuits on the first `false`.
- * - For refinements, the output type is an intersection.
+ * Evaluation short-circuits on the first `false`. For refinements, the output
+ * type is an intersection.
  *
  * **Example** (Both conditions)
  *
@@ -2199,13 +2203,14 @@ export const and: {
    *
    * **When to use**
    *
-   * Use when you want to accept values that satisfy multiple conditions.
-   * - You want to combine refinements with intersection narrowing.
+   * Use when you want to combine `Predicate`s with AND, accepting values that
+   * satisfy multiple conditions, including refinements that narrow to an
+   * intersection.
    *
    * **Details**
    *
-   * - Short-circuits on the first `false`.
-   * - For refinements, the output type is an intersection.
+   * Evaluation short-circuits on the first `false`. For refinements, the output
+   * type is an intersection.
    *
    * **Example** (Both conditions)
    *
@@ -2236,13 +2241,14 @@ export const and: {
    *
    * **When to use**
    *
-   * Use when you want to accept values that satisfy multiple conditions.
-   * - You want to combine refinements with intersection narrowing.
+   * Use when you want to combine `Predicate`s with AND, accepting values that
+   * satisfy multiple conditions, including refinements that narrow to an
+   * intersection.
    *
    * **Details**
    *
-   * - Short-circuits on the first `false`.
-   * - For refinements, the output type is an intersection.
+   * Evaluation short-circuits on the first `false`. For refinements, the output
+   * type is an intersection.
    *
    * **Example** (Both conditions)
    *
@@ -2273,13 +2279,14 @@ export const and: {
    *
    * **When to use**
    *
-   * Use when you want to accept values that satisfy multiple conditions.
-   * - You want to combine refinements with intersection narrowing.
+   * Use when you want to combine `Predicate`s with AND, accepting values that
+   * satisfy multiple conditions, including refinements that narrow to an
+   * intersection.
    *
    * **Details**
    *
-   * - Short-circuits on the first `false`.
-   * - For refinements, the output type is an intersection.
+   * Evaluation short-circuits on the first `false`. For refinements, the output
+   * type is an intersection.
    *
    * **Example** (Both conditions)
    *
@@ -2310,13 +2317,14 @@ export const and: {
    *
    * **When to use**
    *
-   * Use when you want to accept values that satisfy multiple conditions.
-   * - You want to combine refinements with intersection narrowing.
+   * Use when you want to combine `Predicate`s with AND, accepting values that
+   * satisfy multiple conditions, including refinements that narrow to an
+   * intersection.
    *
    * **Details**
    *
-   * - Short-circuits on the first `false`.
-   * - For refinements, the output type is an intersection.
+   * Evaluation short-circuits on the first `false`. For refinements, the output
+   * type is an intersection.
    *
    * **Example** (Both conditions)
    *
@@ -2349,11 +2357,11 @@ export const and: {
  *
  * **When to use**
  *
- * Use when you want an exclusive-or between two conditions.
+ * Use when you want to combine two `Predicate`s with exclusive-or semantics.
  *
  * **Details**
  *
- * - Returns `true` when results differ.
+ * Returns `true` when results differ.
  *
  * **Example** (Exclusive or)
  *
@@ -2378,11 +2386,11 @@ export const xor: {
    *
    * **When to use**
    *
-   * Use when you want an exclusive-or between two conditions.
+   * Use when you want to combine two `Predicate`s with exclusive-or semantics.
    *
    * **Details**
    *
-   * - Returns `true` when results differ.
+   * Returns `true` when results differ.
    *
    * **Example** (Exclusive or)
    *
@@ -2407,11 +2415,11 @@ export const xor: {
    *
    * **When to use**
    *
-   * Use when you want an exclusive-or between two conditions.
+   * Use when you want to combine two `Predicate`s with exclusive-or semantics.
    *
    * **Details**
    *
-   * - Returns `true` when results differ.
+   * Returns `true` when results differ.
    *
    * **Example** (Exclusive or)
    *
@@ -2438,11 +2446,11 @@ export const xor: {
  *
  * **When to use**
  *
- * Use when you want to check equivalence of two predicates.
+ * Use when you want to check equivalence of two `Predicate`s.
  *
  * **Details**
  *
- * - Returns `true` when both results are equal.
+ * Returns `true` when both results are equal.
  *
  * **Example** (Equivalence)
  *
@@ -2465,11 +2473,11 @@ export const eqv: {
    *
    * **When to use**
    *
-   * Use when you want to check equivalence of two predicates.
+   * Use when you want to check equivalence of two `Predicate`s.
    *
    * **Details**
    *
-   * - Returns `true` when both results are equal.
+   * Returns `true` when both results are equal.
    *
    * **Example** (Equivalence)
    *
@@ -2492,11 +2500,11 @@ export const eqv: {
    *
    * **When to use**
    *
-   * Use when you want to check equivalence of two predicates.
+   * Use when you want to check equivalence of two `Predicate`s.
    *
    * **Details**
    *
-   * - Returns `true` when both results are equal.
+   * Returns `true` when both results are equal.
    *
    * **Example** (Equivalence)
    *
@@ -2521,12 +2529,13 @@ export const eqv: {
  *
  * **When to use**
  *
- * Use when you want a rule that only applies when a precondition holds.
- * - You model constraints like "if A then B".
+ * Use when you need to encode logical implication between `Predicate` rules,
+ * where one rule only applies when a precondition holds.
  *
  * **Details**
  *
- * - Returns `true` when the antecedent is `false`.
+ * Models constraints like "if A then B" and returns `true` when the antecedent
+ * is `false`.
  *
  * **Example** (Implication)
  *
@@ -2551,12 +2560,13 @@ export const implies: {
    *
    * **When to use**
    *
-   * Use when you want a rule that only applies when a precondition holds.
-   * - You model constraints like "if A then B".
+   * Use when you need to encode logical implication between `Predicate` rules,
+   * where one rule only applies when a precondition holds.
    *
    * **Details**
    *
-   * - Returns `true` when the antecedent is `false`.
+   * Models constraints like "if A then B" and returns `true` when the antecedent
+   * is `false`.
    *
    * **Example** (Implication)
    *
@@ -2581,12 +2591,13 @@ export const implies: {
    *
    * **When to use**
    *
-   * Use when you want a rule that only applies when a precondition holds.
-   * - You model constraints like "if A then B".
+   * Use when you need to encode logical implication between `Predicate` rules,
+   * where one rule only applies when a precondition holds.
    *
    * **Details**
    *
-   * - Returns `true` when the antecedent is `false`.
+   * Models constraints like "if A then B" and returns `true` when the antecedent
+   * is `false`.
    *
    * **Example** (Implication)
    *
@@ -2616,11 +2627,11 @@ export const implies: {
  *
  * **When to use**
  *
- * Use when you want the logical NOR of two conditions.
+ * Use when you want to combine two `Predicate`s with logical NOR semantics.
  *
  * **Details**
  *
- * - Returns the negation of {@link or}.
+ * Returns the negation of `or`.
  *
  * **Example** (NOR)
  *
@@ -2643,11 +2654,11 @@ export const nor: {
    *
    * **When to use**
    *
-   * Use when you want the logical NOR of two conditions.
+   * Use when you want to combine two `Predicate`s with logical NOR semantics.
    *
    * **Details**
    *
-   * - Returns the negation of {@link or}.
+   * Returns the negation of `or`.
    *
    * **Example** (NOR)
    *
@@ -2670,11 +2681,11 @@ export const nor: {
    *
    * **When to use**
    *
-   * Use when you want the logical NOR of two conditions.
+   * Use when you want to combine two `Predicate`s with logical NOR semantics.
    *
    * **Details**
    *
-   * - Returns the negation of {@link or}.
+   * Returns the negation of `or`.
    *
    * **Example** (NOR)
    *
@@ -2702,11 +2713,11 @@ export const nor: {
  *
  * **When to use**
  *
- * Use when you want the logical NAND of two conditions.
+ * Use when you want to combine two `Predicate`s with logical NAND semantics.
  *
  * **Details**
  *
- * - Returns the negation of {@link and}.
+ * Returns the negation of `and`.
  *
  * **Example** (NAND)
  *
@@ -2729,11 +2740,11 @@ export const nand: {
    *
    * **When to use**
    *
-   * Use when you want the logical NAND of two conditions.
+   * Use when you want to combine two `Predicate`s with logical NAND semantics.
    *
    * **Details**
    *
-   * - Returns the negation of {@link and}.
+   * Returns the negation of `and`.
    *
    * **Example** (NAND)
    *
@@ -2756,11 +2767,11 @@ export const nand: {
    *
    * **When to use**
    *
-   * Use when you want the logical NAND of two conditions.
+   * Use when you want to combine two `Predicate`s with logical NAND semantics.
    *
    * **Details**
    *
-   * - Returns the negation of {@link and}.
+   * Returns the negation of `and`.
    *
    * **Example** (NAND)
    *
@@ -2792,8 +2803,8 @@ export const nand: {
  *
  * **Details**
  *
- * - Short-circuits on the first `false`.
- * - Iterates the collection each time the predicate is called.
+ * Evaluation short-circuits on the first `false`. The collection is iterated
+ * each time the predicate is called.
  *
  * **Example** (All checks)
  *
@@ -2830,8 +2841,8 @@ export function every<A>(collection: Iterable<Predicate<A>>): Predicate<A> {
  *
  * **Details**
  *
- * - Short-circuits on the first `true`.
- * - Iterates the collection each time the predicate is called.
+ * Evaluation short-circuits on the first `true`. The collection is iterated
+ * each time the predicate is called.
  *
  * **Example** (Any check)
  *