effect 4.0.0-beta.83 → 4.0.0-beta.84

package/dist/Array.d.ts

@@ -16,7 +16,7 @@ import type { NoInfer, TupleOf } from "./Types.ts";
  * Use to access native JavaScript array constructor methods such as `isArray`
  * or `from` from the Effect module namespace.
  *
- * **Example** (Using the Array constructor)
+ * **Example** (Accessing the Array constructor)
  *
  * ```ts
  * import { Array } from "effect"
@@ -418,7 +418,7 @@ export declare const ensure: <A>(self: ReadonlyArray<A> | A) => Array<A>;
  * Key order follows `Object.entries` semantics. Empty records produce an empty
  * array.
  *
- * **Example** (Record to entries)
+ * **Example** (Converting a record to entries)
  *
  * ```ts
  * import { Array } from "effect"
@@ -441,7 +441,7 @@ export declare const fromRecord: <K extends string, A>(self: Readonly<Record<K,
  *
  * Use to convert a single `Option` into an array for downstream array operations.
  *
- * **Example** (Option to array)
+ * **Example** (Converting an Option to an array)
  *
  * ```ts
  * import { Array, Option } from "effect"
@@ -572,7 +572,7 @@ export declare const match: {
  *
  * `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
  *
- * **Example** (Head and tail destructuring)
+ * **Example** (Destructuring head and tail)
  *
  * ```ts
  * import { Array } from "effect"
@@ -605,7 +605,7 @@ export declare const matchLeft: {
      *
      * `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
      *
-     * **Example** (Head and tail destructuring)
+     * **Example** (Destructuring head and tail)
      *
      * ```ts
      * import { Array } from "effect"
@@ -641,7 +641,7 @@ export declare const matchLeft: {
      *
      * `onNonEmpty` receives `(head, tail)` where `tail` is the rest of the array.
      *
-     * **Example** (Head and tail destructuring)
+     * **Example** (Destructuring head and tail)
      *
      * ```ts
      * import { Array } from "effect"
@@ -678,7 +678,7 @@ export declare const matchLeft: {
  *
  * `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
  *
- * **Example** (Init and last destructuring)
+ * **Example** (Destructuring init and last)
  *
  * ```ts
  * import { Array } from "effect"
@@ -711,7 +711,7 @@ export declare const matchRight: {
      *
      * `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
      *
-     * **Example** (Init and last destructuring)
+     * **Example** (Destructuring init and last)
      *
      * ```ts
      * import { Array } from "effect"
@@ -747,7 +747,7 @@ export declare const matchRight: {
      *
      * `onNonEmpty` receives `(init, last)` where `init` is everything but the last element.
      *
-     * **Example** (Init and last destructuring)
+     * **Example** (Destructuring init and last)
      *
      * ```ts
      * import { Array } from "effect"
@@ -1295,7 +1295,7 @@ export declare const scan: {
  * The output length is `input.length + 1` because it ends with the initial
  * value. The result is always a `NonEmptyArray`.
  *
- * **Example** (Reverse running totals)
+ * **Example** (Scanning running totals in reverse)
  *
  * ```ts
  * import { Array } from "effect"
@@ -1324,7 +1324,7 @@ export declare const scanRight: {
      * The output length is `input.length + 1` because it ends with the initial
      * value. The result is always a `NonEmptyArray`.
      *
-     * **Example** (Reverse running totals)
+     * **Example** (Scanning running totals in reverse)
      *
      * ```ts
      * import { Array } from "effect"
@@ -1353,7 +1353,7 @@ export declare const scanRight: {
      * The output length is `input.length + 1` because it ends with the initial
      * value. The result is always a `NonEmptyArray`.
      *
-     * **Example** (Reverse running totals)
+     * **Example** (Scanning running totals in reverse)
      *
      * ```ts
      * import { Array } from "effect"
@@ -1575,7 +1575,7 @@ export declare const length: <A>(self: ReadonlyArray<A>) => number;
  *
  * The index is floored to an integer. This never throws.
  *
- * **Example** (Safe index access)
+ * **Example** (Accessing indexes safely)
  *
  * ```ts
  * import { Array } from "effect"
@@ -1605,7 +1605,7 @@ export declare const get: {
      *
      * The index is floored to an integer. This never throws.
      *
-     * **Example** (Safe index access)
+     * **Example** (Accessing indexes safely)
      *
      * ```ts
      * import { Array } from "effect"
@@ -1635,7 +1635,7 @@ export declare const get: {
      *
      * The index is floored to an integer. This never throws.
      *
-     * **Example** (Safe index access)
+     * **Example** (Accessing indexes safely)
      *
      * ```ts
      * import { Array } from "effect"
@@ -1666,7 +1666,7 @@ export declare const get: {
  * Throws an `Error` with the message `"Index out of bounds: <i>"`. Prefer
  * `get` for safe access.
  *
- * **Example** (Unsafe index access)
+ * **Example** (Accessing indexes unsafely)
  *
  * ```ts
  * import { Array } from "effect"
@@ -1694,7 +1694,7 @@ export declare const getUnsafe: {
      * Throws an `Error` with the message `"Index out of bounds: <i>"`. Prefer
      * `get` for safe access.
      *
-     * **Example** (Unsafe index access)
+     * **Example** (Accessing indexes unsafely)
      *
      * ```ts
      * import { Array } from "effect"
@@ -1722,7 +1722,7 @@ export declare const getUnsafe: {
      * Throws an `Error` with the message `"Index out of bounds: <i>"`. Prefer
      * `get` for safe access.
      *
-     * **Example** (Unsafe index access)
+     * **Example** (Accessing indexes unsafely)
      *
      * ```ts
      * import { Array } from "effect"
@@ -4183,7 +4183,7 @@ export declare const sortWith: {
  * This is data-last only and returns a function. The return type preserves
  * `NonEmptyArray`.
  *
- * **Example** (Multi-key sorting)
+ * **Example** (Sorting by multiple keys)
  *
  * ```ts
  * import { Array, Order, pipe } from "effect"
@@ -4998,7 +4998,7 @@ export declare const rotate: {
  * Use when checking membership with caller-provided equality instead of
  * `Equal.equivalence()`.
  *
- * **Example** (Custom equality check)
+ * **Example** (Checking with custom equality)
  *
  * ```ts
  * import { Array, pipe } from "effect"
@@ -5825,7 +5825,7 @@ export declare const chunksOf: {
  * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
  * Each window is a tuple of exactly `n` elements.
  *
- * **Example** (Sliding windows)
+ * **Example** (Creating sliding windows)
  *
  * ```ts
  * import { Array } from "effect"
@@ -5852,7 +5852,7 @@ export declare const window: {
      * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
      * Each window is a tuple of exactly `n` elements.
      *
-     * **Example** (Sliding windows)
+     * **Example** (Creating sliding windows)
      *
      * ```ts
      * import { Array } from "effect"
@@ -5879,7 +5879,7 @@ export declare const window: {
      * Returns an empty array if `n <= 0` or the array has fewer than `n` elements.
      * Each window is a tuple of exactly `n` elements.
      *
-     * **Example** (Sliding windows)
+     * **Example** (Creating sliding windows)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6128,7 +6128,7 @@ export declare const groupBy: {
  * Use when you need the union of two arrays but duplicate detection must use a
  * custom equivalence instead of the default `Equal.equivalence()`.
  *
- * **Example** (Union with custom equality)
+ * **Example** (Computing unions with custom equality)
  *
  * ```ts
  * import { Array } from "effect"
@@ -6153,7 +6153,7 @@ export declare const unionWith: {
      * Use when you need the union of two arrays but duplicate detection must use a
      * custom equivalence instead of the default `Equal.equivalence()`.
      *
-     * **Example** (Union with custom equality)
+     * **Example** (Computing unions with custom equality)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6178,7 +6178,7 @@ export declare const unionWith: {
      * Use when you need the union of two arrays but duplicate detection must use a
      * custom equivalence instead of the default `Equal.equivalence()`.
      *
-     * **Example** (Union with custom equality)
+     * **Example** (Computing unions with custom equality)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6203,7 +6203,7 @@ export declare const unionWith: {
      * Use when you need the union of two arrays but duplicate detection must use a
      * custom equivalence instead of the default `Equal.equivalence()`.
      *
-     * **Example** (Union with custom equality)
+     * **Example** (Computing unions with custom equality)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6228,7 +6228,7 @@ export declare const unionWith: {
      * Use when you need the union of two arrays but duplicate detection must use a
      * custom equivalence instead of the default `Equal.equivalence()`.
      *
-     * **Example** (Union with custom equality)
+     * **Example** (Computing unions with custom equality)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6249,7 +6249,7 @@ export declare const unionWith: {
  * Computes the union of two arrays, removing duplicates using
  * `Equal.equivalence()`.
  *
- * **Example** (Array union)
+ * **Example** (Computing array unions)
  *
  * ```ts
  * import { Array } from "effect"
@@ -6269,7 +6269,7 @@ export declare const union: {
      * Computes the union of two arrays, removing duplicates using
      * `Equal.equivalence()`.
      *
-     * **Example** (Array union)
+     * **Example** (Computing array unions)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6289,7 +6289,7 @@ export declare const union: {
      * Computes the union of two arrays, removing duplicates using
      * `Equal.equivalence()`.
      *
-     * **Example** (Array union)
+     * **Example** (Computing array unions)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6309,7 +6309,7 @@ export declare const union: {
      * Computes the union of two arrays, removing duplicates using
      * `Equal.equivalence()`.
      *
-     * **Example** (Array union)
+     * **Example** (Computing array unions)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6329,7 +6329,7 @@ export declare const union: {
      * Computes the union of two arrays, removing duplicates using
      * `Equal.equivalence()`.
      *
-     * **Example** (Array union)
+     * **Example** (Computing array unions)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6355,7 +6355,7 @@ export declare const union: {
  * Use when you need to keep only values present in both arrays and equality
  * must be defined by a custom comparator, such as matching objects by id.
  *
- * **Example** (Intersection with custom equality)
+ * **Example** (Computing intersections with custom equality)
  *
  * ```ts
  * import { Array } from "effect"
@@ -6386,7 +6386,7 @@ export declare const intersectionWith: <A>(isEquivalent: (self: A, that: A) => b
  * Use when Effect equality is the right membership test and you want to keep
  * values present in both inputs while preserving the first input's order.
  *
- * **Example** (Array intersection)
+ * **Example** (Computing array intersections)
  *
  * ```ts
  * import { Array } from "effect"
@@ -6411,7 +6411,7 @@ export declare const intersection: {
      * Use when Effect equality is the right membership test and you want to keep
      * values present in both inputs while preserving the first input's order.
      *
-     * **Example** (Array intersection)
+     * **Example** (Computing array intersections)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6436,7 +6436,7 @@ export declare const intersection: {
      * Use when Effect equality is the right membership test and you want to keep
      * values present in both inputs while preserving the first input's order.
      *
-     * **Example** (Array intersection)
+     * **Example** (Computing array intersections)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6462,7 +6462,7 @@ export declare const intersection: {
  * Use when you need to keep only values from the first array and equality must
  * be defined by a custom comparator, such as matching objects by id.
  *
- * **Example** (Difference with custom equality)
+ * **Example** (Computing differences with custom equality)
  *
  * ```ts
  * import { Array } from "effect"
@@ -6491,7 +6491,7 @@ export declare const differenceWith: <A>(isEquivalent: (self: A, that: A) => boo
  * Use when you need to keep values from the first array that are absent from
  * the second and the default `Equal.equivalence()` comparison is appropriate.
  *
- * **Example** (Array difference)
+ * **Example** (Computing array differences)
  *
  * ```ts
  * import { Array } from "effect"
@@ -6516,7 +6516,7 @@ export declare const difference: {
      * Use when you need to keep values from the first array that are absent from
      * the second and the default `Equal.equivalence()` comparison is appropriate.
      *
-     * **Example** (Array difference)
+     * **Example** (Computing array differences)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6541,7 +6541,7 @@ export declare const difference: {
      * Use when you need to keep values from the first array that are absent from
      * the second and the default `Equal.equivalence()` comparison is appropriate.
      *
-     * **Example** (Array difference)
+     * **Example** (Computing array differences)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6788,7 +6788,7 @@ export declare const map: {
  * The function receives `(element, index)`. This returns `NonEmptyArray` when
  * both the input and mapped arrays are non-empty.
  *
- * **Example** (FlatMapping an array)
+ * **Example** (Flat mapping an array)
  *
  * ```ts
  * import { Array } from "effect"
@@ -6816,7 +6816,7 @@ export declare const flatMap: {
      * The function receives `(element, index)`. This returns `NonEmptyArray` when
      * both the input and mapped arrays are non-empty.
      *
-     * **Example** (FlatMapping an array)
+     * **Example** (Flat mapping an array)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6844,7 +6844,7 @@ export declare const flatMap: {
      * The function receives `(element, index)`. This returns `NonEmptyArray` when
      * both the input and mapped arrays are non-empty.
      *
-     * **Example** (FlatMapping an array)
+     * **Example** (Flat mapping an array)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6872,7 +6872,7 @@ export declare const flatMap: {
      * The function receives `(element, index)`. This returns `NonEmptyArray` when
      * both the input and mapped arrays are non-empty.
      *
-     * **Example** (FlatMapping an array)
+     * **Example** (Flat mapping an array)
      *
      * ```ts
      * import { Array } from "effect"
@@ -6995,7 +6995,7 @@ export declare const getSuccesses: <T extends Iterable<Result.Result<any, any>>>
  *
  * The filter receives `(element, index)`. Failures are discarded.
  *
- * **Example** (Filter and transform)
+ * **Example** (Filtering and transforming)
  *
  * ```ts
  * import { Array, Result } from "effect"
@@ -7023,7 +7023,7 @@ export declare const filterMap: {
      *
      * The filter receives `(element, index)`. Failures are discarded.
      *
-     * **Example** (Filter and transform)
+     * **Example** (Filtering and transforming)
      *
      * ```ts
      * import { Array, Result } from "effect"
@@ -7051,7 +7051,7 @@ export declare const filterMap: {
      *
      * The filter receives `(element, index)`. Failures are discarded.
      *
-     * **Example** (Filter and transform)
+     * **Example** (Filtering and transforming)
      *
      * ```ts
      * import { Array, Result } from "effect"
@@ -7428,7 +7428,7 @@ export declare const reduce: {
  *
  * The function receives `(accumulator, element, index)`.
  *
- * **Example** (Right-to-left fold)
+ * **Example** (Folding from right to left)
  *
  * ```ts
  * import { Array } from "effect"
@@ -7454,7 +7454,7 @@ export declare const reduceRight: {
      *
      * The function receives `(accumulator, element, index)`.
      *
-     * **Example** (Right-to-left fold)
+     * **Example** (Folding from right to left)
      *
      * ```ts
      * import { Array } from "effect"
@@ -7480,7 +7480,7 @@ export declare const reduceRight: {
      *
      * The function receives `(accumulator, element, index)`.
      *
-     * **Example** (Right-to-left fold)
+     * **Example** (Folding from right to left)
      *
      * ```ts
      * import { Array } from "effect"
@@ -7500,7 +7500,7 @@ export declare const reduceRight: {
  * Lifts a predicate into an array: returns `[value]` if the predicate holds,
  * `[]` otherwise.
  *
- * **Example** (Conditional wrapping)
+ * **Example** (Wrapping values conditionally)
  *
  * ```ts
  * import { Array } from "effect"
@@ -7522,7 +7522,7 @@ export declare const liftPredicate: {
      * Lifts a predicate into an array: returns `[value]` if the predicate holds,
      * `[]` otherwise.
      *
-     * **Example** (Conditional wrapping)
+     * **Example** (Wrapping values conditionally)
      *
      * ```ts
      * import { Array } from "effect"
@@ -7577,7 +7577,7 @@ export declare const liftOption: <A extends Array<unknown>, B>(f: (...a: A) => O
  *
  * Use to treat a nullable single value as zero or one array element.
  *
- * **Example** (Nullable to array)
+ * **Example** (Converting nullable values to an array)
  *
  * ```ts
  * import { Array } from "effect"
@@ -7627,7 +7627,7 @@ export declare const liftNullishOr: <A extends Array<unknown>, B>(f: (...a: A) =
  * Use when you need to map and filter in one step, where the mapper can return
  * `null` or `undefined` to skip elements.
  *
- * **Example** (FlatMapping with nullable)
+ * **Example** (Flat mapping with nullable values)
  *
  * ```ts
  * import { Array } from "effect"
@@ -7652,7 +7652,7 @@ export declare const flatMapNullishOr: {
      * Use when you need to map and filter in one step, where the mapper can return
      * `null` or `undefined` to skip elements.
      *
-     * **Example** (FlatMapping with nullable)
+     * **Example** (Flat mapping with nullable values)
      *
      * ```ts
      * import { Array } from "effect"
@@ -7677,7 +7677,7 @@ export declare const flatMapNullishOr: {
      * Use when you need to map and filter in one step, where the mapper can return
      * `null` or `undefined` to skip elements.
      *
-     * **Example** (FlatMapping with nullable)
+     * **Example** (Flat mapping with nullable values)
      *
      * ```ts
      * import { Array } from "effect"
@@ -7920,7 +7920,7 @@ export declare const some: {
  *
  * For index `i`, the function receives `self.slice(i)`.
  *
- * **Example** (Suffix lengths)
+ * **Example** (Computing suffix lengths)
  *
  * ```ts
  * import { Array } from "effect"
@@ -7947,7 +7947,7 @@ export declare const extend: {
      *
      * For index `i`, the function receives `self.slice(i)`.
      *
-     * **Example** (Suffix lengths)
+     * **Example** (Computing suffix lengths)
      *
      * ```ts
      * import { Array } from "effect"
@@ -7974,7 +7974,7 @@ export declare const extend: {
      *
      * For index `i`, the function receives `self.slice(i)`.
      *
-     * **Example** (Suffix lengths)
+     * **Example** (Computing suffix lengths)
      *
      * ```ts
      * import { Array } from "effect"
@@ -8711,7 +8711,7 @@ export declare const cartesianWith: {
  * Produces every `[a, b]` combination of an element from `self` with an element
  * from `that`, so the result length is `self.length * that.length`.
  *
- * **Example** (All pairs of two arrays)
+ * **Example** (Generating all pairs from two arrays)
  *
  * ```ts
  * import { Array } from "effect"
@@ -8738,7 +8738,7 @@ export declare const cartesian: {
      * Produces every `[a, b]` combination of an element from `self` with an element
      * from `that`, so the result length is `self.length * that.length`.
      *
-     * **Example** (All pairs of two arrays)
+     * **Example** (Generating all pairs from two arrays)
      *
      * ```ts
      * import { Array } from "effect"
@@ -8765,7 +8765,7 @@ export declare const cartesian: {
      * Produces every `[a, b]` combination of an element from `self` with an element
      * from `that`, so the result length is `self.length * that.length`.
      *
-     * **Example** (All pairs of two arrays)
+     * **Example** (Generating all pairs from two arrays)
      *
      * ```ts
      * import { Array } from "effect"
@@ -8795,7 +8795,7 @@ export declare const cartesian: {
  * like nested loops. Use `filter` and `map` in the pipeline to add conditions
  * and transformations.
  *
- * **Example** (Array comprehension with do notation)
+ * **Example** (Building array comprehensions with do notation)
  *
  * ```ts
  * import { Array, pipe } from "effect"