effect 4.0.0-beta.82 → 4.0.0-beta.84

package/src/Array.ts

@@ -34,7 +34,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"
@@ -458,7 +458,7 @@ export const ensure = <A>(self: ReadonlyArray<A> | A): Array<A> => Array.isArray
  * 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"
@@ -482,7 +482,7 @@ export const fromRecord: <K extends string, A>(self: Readonly<Record<K, A>>) =>
  *
  * 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"
@@ -626,7 +626,7 @@ export 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"
@@ -659,7 +659,7 @@ export 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"
@@ -697,7 +697,7 @@ export 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"
@@ -744,7 +744,7 @@ export 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"
@@ -777,7 +777,7 @@ export 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"
@@ -815,7 +815,7 @@ export 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"
@@ -1395,7 +1395,7 @@ export 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"
@@ -1424,7 +1424,7 @@ export 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"
@@ -1453,7 +1453,7 @@ export 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"
@@ -1698,7 +1698,7 @@ const clamp = <A>(i: number, as: ReadonlyArray<A>): number => Math.floor(Math.mi
  *
  * The index is floored to an integer. This never throws.
  *
- * **Example** (Safe index access)
+ * **Example** (Accessing indexes safely)
  *
  * ```ts
  * import { Array } from "effect"
@@ -1728,7 +1728,7 @@ export 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"
@@ -1758,7 +1758,7 @@ export 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"
@@ -1793,7 +1793,7 @@ export 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"
@@ -1821,7 +1821,7 @@ export 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"
@@ -1849,7 +1849,7 @@ export 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"
@@ -4538,7 +4538,7 @@ export 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"
@@ -5457,7 +5457,7 @@ export 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"
@@ -6367,7 +6367,7 @@ export 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"
@@ -6394,7 +6394,7 @@ export 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"
@@ -6421,7 +6421,7 @@ export 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"
@@ -6719,7 +6719,7 @@ export 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"
@@ -6744,7 +6744,7 @@ export 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"
@@ -6772,7 +6772,7 @@ export 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"
@@ -6801,7 +6801,7 @@ export 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"
@@ -6830,7 +6830,7 @@ export 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"
@@ -6867,7 +6867,7 @@ export 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"
@@ -6887,7 +6887,7 @@ export 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"
@@ -6909,7 +6909,7 @@ export 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"
@@ -6929,7 +6929,7 @@ export 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"
@@ -6949,7 +6949,7 @@ export 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"
@@ -6971,7 +6971,7 @@ export 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"
@@ -6998,7 +6998,7 @@ export 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"
@@ -7039,7 +7039,7 @@ export const intersectionWith = <A>(isEquivalent: (self: A, that: A) => boolean)
  * 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"
@@ -7064,7 +7064,7 @@ export 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"
@@ -7089,7 +7089,7 @@ export 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"
@@ -7116,7 +7116,7 @@ export 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"
@@ -7155,7 +7155,7 @@ export const differenceWith = <A>(isEquivalent: (self: A, that: A) => boolean):
  * 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"
@@ -7180,7 +7180,7 @@ export 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"
@@ -7205,7 +7205,7 @@ export 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"
@@ -7478,7 +7478,7 @@ export 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"
@@ -7506,7 +7506,7 @@ export 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"
@@ -7534,7 +7534,7 @@ export 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"
@@ -7565,7 +7565,7 @@ export 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"
@@ -7742,7 +7742,7 @@ export 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"
@@ -7770,7 +7770,7 @@ export const filterMap: {
    *
    * The filter receives `(element, index)`. Failures are discarded.
    *
-   * **Example** (Filter and transform)
+   * **Example** (Filtering and transforming)
    *
    * ```ts
    * import { Array, Result } from "effect"
@@ -7798,7 +7798,7 @@ export const filterMap: {
    *
    * The filter receives `(element, index)`. Failures are discarded.
    *
-   * **Example** (Filter and transform)
+   * **Example** (Filtering and transforming)
    *
    * ```ts
    * import { Array, Result } from "effect"
@@ -8227,7 +8227,7 @@ export const reduce: {
  *
  * The function receives `(accumulator, element, index)`.
  *
- * **Example** (Right-to-left fold)
+ * **Example** (Folding from right to left)
  *
  * ```ts
  * import { Array } from "effect"
@@ -8253,7 +8253,7 @@ export const reduceRight: {
    *
    * The function receives `(accumulator, element, index)`.
    *
-   * **Example** (Right-to-left fold)
+   * **Example** (Folding from right to left)
    *
    * ```ts
    * import { Array } from "effect"
@@ -8279,7 +8279,7 @@ export const reduceRight: {
    *
    * The function receives `(accumulator, element, index)`.
    *
-   * **Example** (Right-to-left fold)
+   * **Example** (Folding from right to left)
    *
    * ```ts
    * import { Array } from "effect"
@@ -8304,7 +8304,7 @@ export 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"
@@ -8326,7 +8326,7 @@ export const liftPredicate: { // Note: I intentionally avoid using the NoInfer p
    * 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"
@@ -8386,7 +8386,7 @@ export const liftOption = <A extends Array<unknown>, B>(
  *
  * 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"
@@ -8441,7 +8441,7 @@ export const liftNullishOr = <A extends Array<unknown>, B>(
  * 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"
@@ -8466,7 +8466,7 @@ export 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"
@@ -8491,7 +8491,7 @@ export 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"
@@ -8755,7 +8755,7 @@ export const some: {
  *
  * For index `i`, the function receives `self.slice(i)`.
  *
- * **Example** (Suffix lengths)
+ * **Example** (Computing suffix lengths)
  *
  * ```ts
  * import { Array } from "effect"
@@ -8782,7 +8782,7 @@ export const extend: {
    *
    * For index `i`, the function receives `self.slice(i)`.
    *
-   * **Example** (Suffix lengths)
+   * **Example** (Computing suffix lengths)
    *
    * ```ts
    * import { Array } from "effect"
@@ -8809,7 +8809,7 @@ export const extend: {
    *
    * For index `i`, the function receives `self.slice(i)`.
    *
-   * **Example** (Suffix lengths)
+   * **Example** (Computing suffix lengths)
    *
    * ```ts
    * import { Array } from "effect"
@@ -9634,7 +9634,7 @@ export 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"
@@ -9661,7 +9661,7 @@ export 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"
@@ -9688,7 +9688,7 @@ export 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"
@@ -9726,7 +9726,7 @@ export 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"

package/src/Cache.ts

@@ -145,7 +145,7 @@ export interface Entry<A, E> {
  * The timeToLive function receives both the exit result and the key, allowing
  * for flexible TTL policies based on success/failure state and key characteristics.
  *
- * **Example** (Using dynamic time to live)
+ * **Example** (Configuring dynamic time to live)
  *
  * ```ts
  * import { Cache, Effect, Exit } from "effect"