effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Predicate.js

@@ -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
  */
@@ -45,12 +70,11 @@ import { dual } from "./Function.js";
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Returns a new predicate that applies `f` before `self`.
  * - No short-circuit beyond what `self` does.
  *
@@ -78,12 +102,11 @@ export const mapInput = /*#__PURE__*/dual(2, (self, f) => b => self(f(b)));
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Only checks length, not element types.
  * - Returns a refinement on the array type.
  *
@@ -108,12 +131,11 @@ export const isTupleOf = /*#__PURE__*/dual(2, (self, n) => self.length === n);
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Only checks length, not element types.
  * - Returns a refinement on the array type.
  *
@@ -138,12 +160,11 @@ export const isTupleOfAtLeast = /*#__PURE__*/dual(2, (self, n) => self.length >=
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Uses `!!input` under the hood.
  * - Treats `0`, "", `false`, `null`, and `undefined` as false.
  *
@@ -171,11 +192,10 @@ export function isTruthy(input) {
  *
  * **When to use**
  *
- * - You need a runtime guard for `Set` values.
+ * Use when you need a runtime guard for `Set` values.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses `instanceof Set`.
  *
  * **Example** (Guard a Set)
@@ -203,11 +223,10 @@ export function isSet(input) {
  *
  * **When to use**
  *
- * - You need a runtime guard for `Map` values.
+ * Use when you need a runtime guard for `Map` values.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses `instanceof Map`.
  *
  * **Example** (Guard a Map)
@@ -235,12 +254,11 @@ export function isMap(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Uses `typeof input === "string"`.
  *
  * **Example** (Guard string)
@@ -269,11 +287,10 @@ export function isString(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Uses `typeof input === "number"`.
  * - Does not exclude `NaN` or `Infinity`.
  *
@@ -302,11 +319,10 @@ export function isNumber(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Uses `typeof input === "boolean"`.
  *
  * **Example** (Guard boolean)
@@ -334,11 +350,10 @@ export function isBoolean(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Uses `typeof input === "bigint"`.
  *
  * **Example** (Guard bigint)
@@ -365,11 +380,10 @@ export function isBigInt(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Uses `typeof input === "symbol"`.
  *
  * **Example** (Guard symbol)
@@ -396,11 +410,10 @@ export function isSymbol(input) {
  *
  * **When to use**
  *
- * - You need to guard unknown keys before indexing.
+ * Use when you need to guard unknown keys before indexing.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses {@link isString}, {@link isNumber}, and {@link isSymbol}.
  *
  * **Example** (Guard property key)
@@ -430,11 +443,10 @@ export function isPropertyKey(u) {
  *
  * **When to use**
  *
- * - You need to guard an `unknown` value as callable.
+ * Use when you need to guard an `unknown` value as callable.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses `typeof input === "function"`.
  *
  * **Example** (Guard function)
@@ -461,11 +473,10 @@ export function isFunction(input) {
  *
  * **When to use**
  *
- * - You need a guard for optional values.
+ * Use when you need a guard for optional values.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses `input === undefined`.
  *
  * **Example** (Guard undefined)
@@ -491,11 +502,10 @@ export function isUndefined(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Returns a refinement that excludes `undefined`.
  *
  * **Example** (Filter undefined)
@@ -522,11 +532,10 @@ export function isNotUndefined(input) {
  *
  * **When to use**
  *
- * - You need a guard for nullable values.
+ * Use when you need a guard for nullable values.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses `input === null`.
  *
  * **Example** (Guard null)
@@ -552,11 +561,10 @@ export function isNull(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Returns a refinement that excludes `null`.
  *
  * **Example** (Filter null)
@@ -583,11 +591,10 @@ export function isNotNull(input) {
  *
  * **When to use**
  *
- * - You want to guard nullish values explicitly.
+ * Use when you want to guard nullish values explicitly.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses `input === null || input === undefined`.
  *
  * **Example** (Guard nullish)
@@ -615,11 +622,10 @@ export function isNullish(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Uses `input != null`.
  *
  * **Example** (Filter non-nullish)
@@ -643,15 +649,14 @@ export function isNotNullish(input) {
   return input != null;
 }
 /**
- * A guard that always returns `false`.
+ * Type guard that always returns `false`.
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Always returns `false`.
  *
  * **Example** (Never matches)
@@ -670,15 +675,14 @@ export function isNever(_) {
   return false;
 }
 /**
- * A guard that always returns `true`.
+ * Type guard that always returns `true`.
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Always returns `true`.
  *
  * **Example** (Always matches)
@@ -701,11 +705,10 @@ export function isUnknown(_) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Uses `typeof input === "object" && input !== null`.
  * - Includes arrays.
  *
@@ -728,6 +731,10 @@ export function isObjectOrArray(input) {
 /**
  * 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
@@ -755,6 +762,11 @@ export function isObject(input) {
  * 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
@@ -783,11 +795,10 @@ export function isReadonlyObject(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Returns `true` for arrays and functions, `false` for `null`.
  *
  * **Example** (Object keyword)
@@ -812,12 +823,11 @@ export function isObjectKeyword(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Uses the `in` operator and {@link isObjectKeyword}.
  * - Does not check property value types.
  *
@@ -845,12 +855,11 @@ export const hasProperty = /*#__PURE__*/dual(2, (self, property) => isObjectKeyw
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Uses {@link hasProperty} and strict equality on `_tag`.
  *
  * **Example** (Guard tagged)
@@ -873,11 +882,10 @@ export const isTagged = /*#__PURE__*/dual(2, (self, tag) => hasProperty(self, "_
  *
  * **When to use**
  *
- * - You need to guard errors caught from unknown sources.
+ * Use when you need to guard errors caught from unknown sources.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses `instanceof Error`.
  *
  * **Example** (Guard error)
@@ -902,11 +910,10 @@ export function isError(input) {
  *
  * **When to use**
  *
- * - You need to guard binary data at runtime.
+ * Use when you need to guard binary data at runtime.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses `instanceof Uint8Array`.
  *
  * **Example** (Guard Uint8Array)
@@ -932,11 +939,10 @@ export function isUint8Array(input) {
  *
  * **When to use**
  *
- * - You need to guard dates at runtime.
+ * Use when you need to guard dates at runtime.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses `instanceof Date`.
  *
  * **Example** (Guard Date)
@@ -961,11 +967,10 @@ export function isDate(input) {
  *
  * **When to use**
  *
- * - You need a guard before iterating an unknown value.
+ * Use when you need a guard before iterating an unknown value.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Accepts strings as iterable.
  * - Uses {@link hasProperty} for `Symbol.iterator`.
  *
@@ -992,11 +997,10 @@ export function isIterable(input) {
  *
  * **When to use**
  *
- * - You need to detect promise instances across realms.
+ * Use when you need to detect promise instances across realms.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Structural check for `then` and `catch` functions.
  *
  * **Example** (Guard promise)
@@ -1021,11 +1025,10 @@ export function isPromise(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Structural check for a callable `then`.
  *
  * **Example** (Guard promise-like)
@@ -1050,11 +1053,10 @@ export function isPromiseLike(input) {
  *
  * **When to use**
  *
- * - You need a runtime guard for regular expressions.
+ * Use when you need a runtime guard for regular expressions.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Uses `instanceof RegExp`.
  *
  * **Example** (Guard RegExp)
@@ -1079,12 +1081,11 @@ export function isRegExp(input) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - For refinements, the output type is narrowed by both.
  * - Short-circuits on the first `false`.
  *
@@ -1112,12 +1113,11 @@ export const compose = /*#__PURE__*/dual(2, (ab, bc) => a => ab(a) && bc(a));
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Returns a refinement if any element predicate is a refinement.
  * - Stops at the first failing element.
  *
@@ -1151,12 +1151,11 @@ export function Tuple(elements) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Returns a refinement if any field predicate is a refinement.
  * - Checks only the specified keys; extra keys are ignored.
  *
@@ -1194,11 +1193,10 @@ export function Struct(fields) {
  *
  * **When to use**
  *
- * - You want the inverse of an existing predicate.
+ * Use when you want the inverse of an existing predicate.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Returns a new predicate that flips the boolean result.
  *
  * **Example** (Negate)
@@ -1225,12 +1223,11 @@ export function not(self) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Short-circuits on the first `true`.
  * - For refinements, the output type is a union.
  *
@@ -1255,12 +1252,11 @@ export const or = /*#__PURE__*/dual(2, (self, that) => a => self(a) || that(a));
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Short-circuits on the first `false`.
  * - For refinements, the output type is an intersection.
  *
@@ -1293,11 +1289,10 @@ export const and = /*#__PURE__*/dual(2, (self, that) => a => self(a) && that(a))
  *
  * **When to use**
  *
- * - You want an exclusive-or between two conditions.
+ * Use when you want an exclusive-or between two conditions.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Returns `true` when results differ.
  *
  * **Example** (Exclusive or)
@@ -1323,11 +1318,10 @@ export const xor = /*#__PURE__*/dual(2, (self, that) => a => self(a) !== that(a)
  *
  * **When to use**
  *
- * - You want to check equivalence of two predicates.
+ * Use when you want to check equivalence of two predicates.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Returns `true` when both results are equal.
  *
  * **Example** (Equivalence)
@@ -1351,12 +1345,11 @@ export const eqv = /*#__PURE__*/dual(2, (self, that) => a => self(a) === that(a)
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Returns `true` when the antecedent is `false`.
  *
  * **Example** (Implication)
@@ -1382,11 +1375,10 @@ export const implies = /*#__PURE__*/dual(2, (antecedent, consequent) => a => ant
  *
  * **When to use**
  *
- * - You want the logical NOR of two conditions.
+ * Use when you want the logical NOR of two conditions.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Returns the negation of {@link or}.
  *
  * **Example** (NOR)
@@ -1410,11 +1402,10 @@ export const nor = /*#__PURE__*/dual(2, (self, that) => a => !(self(a) || that(a
  *
  * **When to use**
  *
- * - You want the logical NAND of two conditions.
+ * Use when you want the logical NAND of two conditions.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Returns the negation of {@link and}.
  *
  * **Example** (NAND)
@@ -1438,11 +1429,10 @@ export const nand = /*#__PURE__*/dual(2, (self, that) => a => !(self(a) && that(
  *
  * **When to use**
  *
- * - You have a dynamic list of predicates to apply.
+ * Use when you have a dynamic list of predicates to apply.
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Short-circuits on the first `false`.
  * - Iterates the collection each time the predicate is called.
  *
@@ -1476,11 +1466,10 @@ export function every(collection) {
  *
  * **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**
  *
- * - Pure; does not mutate input.
  * - Short-circuits on the first `true`.
  * - Iterates the collection each time the predicate is called.
  *