effect 4.0.0-beta.74 → 4.0.0-beta.75

package/dist/Predicate.js

@@ -70,13 +70,13 @@ import { dual } from "./Function.js";
  *
  * **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)
  *
@@ -102,13 +102,13 @@ export const mapInput = /*#__PURE__*/dual(2, (self, f) => b => self(f(b)));
  *
  * **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)
  *
@@ -131,13 +131,13 @@ export const isTupleOf = /*#__PURE__*/dual(2, (self, n) => self.length === n);
  *
  * **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)
  *
@@ -160,13 +160,13 @@ export const isTupleOfAtLeast = /*#__PURE__*/dual(2, (self, n) => self.length >=
  *
  * **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)
  *
@@ -192,11 +192,11 @@ export function isTruthy(input) {
  *
  * **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)
  *
@@ -223,11 +223,11 @@ export function isSet(input) {
  *
  * **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)
  *
@@ -254,12 +254,12 @@ export function isMap(input) {
  *
  * **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)
  *
@@ -287,12 +287,12 @@ export function isString(input) {
  *
  * **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)
  *
@@ -319,11 +319,12 @@ export function isNumber(input) {
  *
  * **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)
  *
@@ -350,11 +351,12 @@ export function isBoolean(input) {
  *
  * **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)
  *
@@ -380,11 +382,12 @@ export function isBigInt(input) {
  *
  * **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)
  *
@@ -410,11 +413,12 @@ export function isSymbol(input) {
  *
  * **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)
  *
@@ -443,11 +447,12 @@ export function isPropertyKey(u) {
  *
  * **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)
  *
@@ -473,11 +478,12 @@ export function isFunction(input) {
  *
  * **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)
  *
@@ -502,11 +508,12 @@ export function isUndefined(input) {
  *
  * **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)
  *
@@ -532,11 +539,11 @@ export function isNotUndefined(input) {
  *
  * **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)
  *
@@ -561,11 +568,12 @@ export function isNull(input) {
  *
  * **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)
  *
@@ -591,11 +599,11 @@ export function isNotNull(input) {
  *
  * **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)
  *
@@ -622,11 +630,12 @@ export function isNullish(input) {
  *
  * **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)
  *
@@ -653,11 +662,7 @@ export function isNotNullish(input) {
  *
  * **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)
  *
@@ -679,11 +684,7 @@ export function isNever(_) {
  *
  * **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)
  *
@@ -705,12 +706,12 @@ export function isUnknown(_) {
  *
  * **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)
  *
@@ -733,7 +734,8 @@ export function isObjectOrArray(input) {
  *
  * **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**
  *
@@ -765,7 +767,7 @@ export function isObject(input) {
  * **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**
  *
@@ -795,11 +797,12 @@ export function isReadonlyObject(input) {
  *
  * **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)
  *
@@ -823,13 +826,13 @@ export function isObjectKeyword(input) {
  *
  * **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)
  *
@@ -855,12 +858,12 @@ export const hasProperty = /*#__PURE__*/dual(2, (self, property) => isObjectKeyw
  *
  * **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)
  *
@@ -882,11 +885,11 @@ export const isTagged = /*#__PURE__*/dual(2, (self, tag) => hasProperty(self, "_
  *
  * **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)
  *
@@ -910,11 +913,11 @@ export function isError(input) {
  *
  * **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)
  *
@@ -939,11 +942,11 @@ export function isUint8Array(input) {
  *
  * **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)
  *
@@ -967,12 +970,11 @@ export function isDate(input) {
  *
  * **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)
  *
@@ -997,11 +999,11 @@ export function isIterable(input) {
  *
  * **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)
  *
@@ -1025,11 +1027,12 @@ export function isPromise(input) {
  *
  * **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)
  *
@@ -1053,11 +1056,11 @@ export function isPromiseLike(input) {
  *
  * **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)
  *
@@ -1081,13 +1084,13 @@ export function isRegExp(input) {
  *
  * **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)
  *
@@ -1113,13 +1116,13 @@ export const compose = /*#__PURE__*/dual(2, (ab, bc) => a => ab(a) && bc(a));
  *
  * **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)
  *
@@ -1151,13 +1154,13 @@ export function Tuple(elements) {
  *
  * **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)
  *
@@ -1197,7 +1200,7 @@ export function Struct(fields) {
  *
  * **Details**
  *
- * - Returns a new predicate that flips the boolean result.
+ * Returns a new predicate that flips the boolean result.
  *
  * **Example** (Negate)
  *
@@ -1223,13 +1226,13 @@ export function not(self) {
  *
  * **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)
  *
@@ -1252,13 +1255,14 @@ export const or = /*#__PURE__*/dual(2, (self, that) => a => self(a) || that(a));
  *
  * **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)
  *
@@ -1289,11 +1293,11 @@ export const and = /*#__PURE__*/dual(2, (self, that) => a => self(a) && that(a))
  *
  * **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)
  *
@@ -1318,11 +1322,11 @@ export const xor = /*#__PURE__*/dual(2, (self, that) => a => self(a) !== that(a)
  *
  * **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)
  *
@@ -1345,12 +1349,13 @@ export const eqv = /*#__PURE__*/dual(2, (self, that) => a => self(a) === that(a)
  *
  * **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)
  *
@@ -1375,11 +1380,11 @@ export const implies = /*#__PURE__*/dual(2, (antecedent, consequent) => a => ant
  *
  * **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)
  *
@@ -1402,11 +1407,11 @@ export const nor = /*#__PURE__*/dual(2, (self, that) => a => !(self(a) || that(a
  *
  * **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)
  *
@@ -1433,8 +1438,8 @@ export const nand = /*#__PURE__*/dual(2, (self, that) => a => !(self(a) && that(
  *
  * **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)
  *
@@ -1470,8 +1475,8 @@ export function every(collection) {
  *
  * **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)
  *