effect 4.0.4 → 4.0.6

package/dist/Array.d.ts

@@ -475,8 +475,10 @@ export declare const fromOption: <A>(self: Option.Option<A>) => Array<A>;
  *
  * **Details**
  *
- * `onNonEmpty` receives a `NonEmptyReadonlyArray`. Supports both data-first and
- * data-last usage.
+ * `onNonEmpty` receives a `NonEmptyArray` for mutable arrays and a
+ * `NonEmptyReadonlyArray` otherwise. Data-last calls default to the readonly
+ * callback, so the returned function still accepts `ReadonlyArray`. Supports
+ * both data-first and data-last usage.
  *
  * **Example** (Branching on emptiness)
  *
@@ -509,8 +511,10 @@ export declare const match: {
      *
      * **Details**
      *
-     * `onNonEmpty` receives a `NonEmptyReadonlyArray`. Supports both data-first and
-     * data-last usage.
+     * `onNonEmpty` receives a `NonEmptyArray` for mutable arrays and a
+     * `NonEmptyReadonlyArray` otherwise. Data-last calls default to the readonly
+     * callback, so the returned function still accepts `ReadonlyArray`. Supports
+     * both data-first and data-last usage.
      *
      * **Example** (Branching on emptiness)
      *
@@ -546,8 +550,88 @@ export declare const match: {
      *
      * **Details**
      *
-     * `onNonEmpty` receives a `NonEmptyReadonlyArray`. Supports both data-first and
-     * data-last usage.
+     * `onNonEmpty` receives a `NonEmptyArray` for mutable arrays and a
+     * `NonEmptyReadonlyArray` otherwise. Data-last calls default to the readonly
+     * callback, so the returned function still accepts `ReadonlyArray`. Supports
+     * both data-first and data-last usage.
+     *
+     * **Example** (Branching on emptiness)
+     *
+     * ```ts import.meta.vitest
+     * import { Array } from "effect"
+     *
+     * const describe = Array.match({
+     *   onEmpty: () => "empty",
+     *   onNonEmpty: ([head, ...tail]) => `head: ${head}, tail: ${tail.length}`
+     * })
+     *
+     * describe([]) // => "empty"
+     * describe([1, 2, 3]) // => "head: 1, tail: 2"
+     * ```
+     *
+     * @see {@link matchLeft} — destructures into head + tail
+     * @see {@link matchRight} — destructures into init + last
+     *
+     * @stability stable
+     * @category pattern matching
+     * @since 2.0.0
+     */
+    <B, A, C = B>(options: {
+        readonly onEmpty: LazyArg<B>;
+        readonly onNonEmpty: (self: NonEmptyArray<A>) => C;
+    }): (self: Array<A>) => B | C;
+    /**
+     * Pattern-matches on an array, handling empty and non-empty cases separately.
+     *
+     * **When to use**
+     *
+     * Use when you need to branch on whether an array is empty.
+     *
+     * **Details**
+     *
+     * `onNonEmpty` receives a `NonEmptyArray` for mutable arrays and a
+     * `NonEmptyReadonlyArray` otherwise. Data-last calls default to the readonly
+     * callback, so the returned function still accepts `ReadonlyArray`. Supports
+     * both data-first and data-last usage.
+     *
+     * **Example** (Branching on emptiness)
+     *
+     * ```ts import.meta.vitest
+     * import { Array } from "effect"
+     *
+     * const describe = Array.match({
+     *   onEmpty: () => "empty",
+     *   onNonEmpty: ([head, ...tail]) => `head: ${head}, tail: ${tail.length}`
+     * })
+     *
+     * describe([]) // => "empty"
+     * describe([1, 2, 3]) // => "head: 1, tail: 2"
+     * ```
+     *
+     * @see {@link matchLeft} — destructures into head + tail
+     * @see {@link matchRight} — destructures into init + last
+     *
+     * @stability stable
+     * @category pattern matching
+     * @since 2.0.0
+     */
+    <A, B, C = B>(self: Array<A>, options: {
+        readonly onEmpty: LazyArg<B>;
+        readonly onNonEmpty: (self: NonEmptyArray<A>) => C;
+    }): B | C;
+    /**
+     * Pattern-matches on an array, handling empty and non-empty cases separately.
+     *
+     * **When to use**
+     *
+     * Use when you need to branch on whether an array is empty.
+     *
+     * **Details**
+     *
+     * `onNonEmpty` receives a `NonEmptyArray` for mutable arrays and a
+     * `NonEmptyReadonlyArray` otherwise. Data-last calls default to the readonly
+     * callback, so the returned function still accepts `ReadonlyArray`. Supports
+     * both data-first and data-last usage.
      *
      * **Example** (Branching on emptiness)
      *
@@ -5168,7 +5252,7 @@ export declare const rotate: {
  * **When to use**
  *
  * Use when checking membership with caller-provided equality instead of
- * `Equal.equivalence()`.
+ * `Equal.asEquivalence()`.
  *
  * **Example** (Checking with custom equality)
  *
@@ -5180,7 +5264,7 @@ export declare const rotate: {
  * pipe([1, 2, 3, 4], containsNumber(3)) // => true
  * ```
  *
- * @see {@link contains} for the `Equal.equivalence()` variant
+ * @see {@link contains} for the `Equal.asEquivalence()` variant
  *
  * @stability stable
  * @category predicates
@@ -5191,7 +5275,7 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
     (self: Iterable<A>, a: A): boolean;
 };
 /**
- * Checks whether an array contains a value, using `Equal.equivalence()` for
+ * Checks whether an array contains a value, using `Equal.asEquivalence()` for
  * comparison.
  *
  * **When to use**
@@ -5215,7 +5299,7 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  */
 export declare const contains: {
     /**
-     * Checks whether an array contains a value, using `Equal.equivalence()` for
+     * Checks whether an array contains a value, using `Equal.asEquivalence()` for
      * comparison.
      *
      * **When to use**
@@ -5239,7 +5323,7 @@ export declare const contains: {
      */
     <A>(a: A): (self: Iterable<A>) => boolean;
     /**
-     * Checks whether an array contains a value, using `Equal.equivalence()` for
+     * Checks whether an array contains a value, using `Equal.asEquivalence()` for
      * comparison.
      *
      * **When to use**
@@ -6144,7 +6228,7 @@ export declare const window: {
  * ) // => [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
  * ```
  *
- * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+ * @see {@link group} for grouping adjacent elements with `Equal.asEquivalence()`
  * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
  *
  * @stability stable
@@ -6176,7 +6260,7 @@ export declare const groupWith: {
      * ) // => [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
      * ```
      *
-     * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+     * @see {@link group} for grouping adjacent elements with `Equal.asEquivalence()`
      * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
      *
      * @stability stable
@@ -6208,7 +6292,7 @@ export declare const groupWith: {
      * ) // => [["a", "a"], ["b", "b", "b"], ["c"], ["a"]]
      * ```
      *
-     * @see {@link group} for grouping adjacent elements with `Equal.equivalence()`
+     * @see {@link group} for grouping adjacent elements with `Equal.asEquivalence()`
      * @see {@link groupBy} for grouping all elements into a record by key, regardless of adjacency
      *
      * @stability stable
@@ -6218,7 +6302,7 @@ export declare const groupWith: {
     <A>(self: NonEmptyReadonlyArray<A>, isEquivalent: (self: A, that: A) => boolean): NonEmptyArray<NonEmptyArray<A>>;
 };
 /**
- * Groups consecutive equal elements using `Equal.equivalence()`.
+ * Groups consecutive equal elements using `Equal.asEquivalence()`.
  *
  * **When to use**
  *
@@ -6373,13 +6457,22 @@ export declare const groupBy: {
     <A, K extends string | symbol>(self: Iterable<A>, f: (a: A) => K): Record.ReadonlyRecord.GroupByResult<K, NonEmptyArray<A>>;
 };
 /**
- * Computes the union of two arrays using a custom equivalence, removing
- * duplicates.
+ * Computes the union of two iterables using a custom equivalence.
  *
  * **When to use**
  *
  * Use when you need the union of two arrays but duplicate detection must use a
- * custom equivalence instead of the default `Equal.equivalence()`.
+ * custom equivalence instead of the default `Equal.asEquivalence()`.
+ *
+ * **Details**
+ *
+ * Keeps the elements of `self`, then appends elements of `that` that have no
+ * equivalent in `self`. Calls `isEquivalent` with an element from `self` first
+ * and an element from `that` second.
+ *
+ * **Gotchas**
+ *
+ * Each input must already be deduplicated.
  *
  * **Example** (Computing unions with custom equality)
  *
@@ -6389,7 +6482,7 @@ export declare const groupBy: {
  * Array.unionWith([1, 2], [2, 3], (a, b) => a === b) // => [1, 2, 3]
  * ```
  *
- * @see {@link union} for the `Equal.equivalence()` variant
+ * @see {@link union} for the `Equal.asEquivalence()` variant
  * @see {@link intersectionWith} for keeping elements present in both arrays
  * @see {@link differenceWith} for keeping elements present only in the first array
  *
@@ -6399,13 +6492,22 @@ export declare const groupBy: {
  */
 export declare const unionWith: {
     /**
-     * Computes the union of two arrays using a custom equivalence, removing
-     * duplicates.
+     * Computes the union of two iterables using a custom equivalence.
      *
      * **When to use**
      *
      * Use when you need the union of two arrays but duplicate detection must use a
-     * custom equivalence instead of the default `Equal.equivalence()`.
+     * custom equivalence instead of the default `Equal.asEquivalence()`.
+     *
+     * **Details**
+     *
+     * Keeps the elements of `self`, then appends elements of `that` that have no
+     * equivalent in `self`. Calls `isEquivalent` with an element from `self` first
+     * and an element from `that` second.
+     *
+     * **Gotchas**
+     *
+     * Each input must already be deduplicated.
      *
      * **Example** (Computing unions with custom equality)
      *
@@ -6415,7 +6517,7 @@ export declare const unionWith: {
      * Array.unionWith([1, 2], [2, 3], (a, b) => a === b) // => [1, 2, 3]
      * ```
      *
-     * @see {@link union} for the `Equal.equivalence()` variant
+     * @see {@link union} for the `Equal.asEquivalence()` variant
      * @see {@link intersectionWith} for keeping elements present in both arrays
      * @see {@link differenceWith} for keeping elements present only in the first array
      *
@@ -6425,13 +6527,22 @@ export declare const unionWith: {
      */
     <S extends Iterable<any>, T extends Iterable<any>>(that: T, isEquivalent: (self: ReadonlyArray.Infer<S>, that: ReadonlyArray.Infer<T>) => boolean): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>;
     /**
-     * Computes the union of two arrays using a custom equivalence, removing
-     * duplicates.
+     * Computes the union of two iterables using a custom equivalence.
      *
      * **When to use**
      *
      * Use when you need the union of two arrays but duplicate detection must use a
-     * custom equivalence instead of the default `Equal.equivalence()`.
+     * custom equivalence instead of the default `Equal.asEquivalence()`.
+     *
+     * **Details**
+     *
+     * Keeps the elements of `self`, then appends elements of `that` that have no
+     * equivalent in `self`. Calls `isEquivalent` with an element from `self` first
+     * and an element from `that` second.
+     *
+     * **Gotchas**
+     *
+     * Each input must already be deduplicated.
      *
      * **Example** (Computing unions with custom equality)
      *
@@ -6441,7 +6552,7 @@ export declare const unionWith: {
      * Array.unionWith([1, 2], [2, 3], (a, b) => a === b) // => [1, 2, 3]
      * ```
      *
-     * @see {@link union} for the `Equal.equivalence()` variant
+     * @see {@link union} for the `Equal.asEquivalence()` variant
      * @see {@link intersectionWith} for keeping elements present in both arrays
      * @see {@link differenceWith} for keeping elements present only in the first array
      *
@@ -6451,13 +6562,22 @@ export declare const unionWith: {
      */
     <A, B>(self: NonEmptyReadonlyArray<A>, that: Iterable<B>, isEquivalent: (self: A, that: B) => boolean): NonEmptyArray<A | B>;
     /**
-     * Computes the union of two arrays using a custom equivalence, removing
-     * duplicates.
+     * Computes the union of two iterables using a custom equivalence.
      *
      * **When to use**
      *
      * Use when you need the union of two arrays but duplicate detection must use a
-     * custom equivalence instead of the default `Equal.equivalence()`.
+     * custom equivalence instead of the default `Equal.asEquivalence()`.
+     *
+     * **Details**
+     *
+     * Keeps the elements of `self`, then appends elements of `that` that have no
+     * equivalent in `self`. Calls `isEquivalent` with an element from `self` first
+     * and an element from `that` second.
+     *
+     * **Gotchas**
+     *
+     * Each input must already be deduplicated.
      *
      * **Example** (Computing unions with custom equality)
      *
@@ -6467,7 +6587,7 @@ export declare const unionWith: {
      * Array.unionWith([1, 2], [2, 3], (a, b) => a === b) // => [1, 2, 3]
      * ```
      *
-     * @see {@link union} for the `Equal.equivalence()` variant
+     * @see {@link union} for the `Equal.asEquivalence()` variant
      * @see {@link intersectionWith} for keeping elements present in both arrays
      * @see {@link differenceWith} for keeping elements present only in the first array
      *
@@ -6477,13 +6597,22 @@ export declare const unionWith: {
      */
     <A, B>(self: Iterable<A>, that: NonEmptyReadonlyArray<B>, isEquivalent: (self: A, that: B) => boolean): NonEmptyArray<A | B>;
     /**
-     * Computes the union of two arrays using a custom equivalence, removing
-     * duplicates.
+     * Computes the union of two iterables using a custom equivalence.
      *
      * **When to use**
      *
      * Use when you need the union of two arrays but duplicate detection must use a
-     * custom equivalence instead of the default `Equal.equivalence()`.
+     * custom equivalence instead of the default `Equal.asEquivalence()`.
+     *
+     * **Details**
+     *
+     * Keeps the elements of `self`, then appends elements of `that` that have no
+     * equivalent in `self`. Calls `isEquivalent` with an element from `self` first
+     * and an element from `that` second.
+     *
+     * **Gotchas**
+     *
+     * Each input must already be deduplicated.
      *
      * **Example** (Computing unions with custom equality)
      *
@@ -6493,7 +6622,7 @@ export declare const unionWith: {
      * Array.unionWith([1, 2], [2, 3], (a, b) => a === b) // => [1, 2, 3]
      * ```
      *
-     * @see {@link union} for the `Equal.equivalence()` variant
+     * @see {@link union} for the `Equal.asEquivalence()` variant
      * @see {@link intersectionWith} for keeping elements present in both arrays
      * @see {@link differenceWith} for keeping elements present only in the first array
      *
@@ -6504,8 +6633,12 @@ export declare const unionWith: {
     <A, B>(self: Iterable<A>, that: Iterable<B>, isEquivalent: (self: A, that: B) => boolean): Array<A | B>;
 };
 /**
- * Computes the union of two arrays, removing duplicates using
- * `Equal.equivalence()`.
+ * Computes the union of two iterables using `Equal.asEquivalence()`.
+ *
+ * **Gotchas**
+ *
+ * Each input must already be deduplicated. Use {@link dedupe} to remove
+ * duplicates from an input first.
  *
  * **Example** (Computing array unions)
  *
@@ -6525,8 +6658,12 @@ export declare const unionWith: {
  */
 export declare const union: {
     /**
-     * Computes the union of two arrays, removing duplicates using
-     * `Equal.equivalence()`.
+     * Computes the union of two iterables using `Equal.asEquivalence()`.
+     *
+     * **Gotchas**
+     *
+     * Each input must already be deduplicated. Use {@link dedupe} to remove
+     * duplicates from an input first.
      *
      * **Example** (Computing array unions)
      *
@@ -6546,8 +6683,12 @@ export declare const union: {
      */
     <T extends Iterable<any>>(that: T): <S extends Iterable<any>>(self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>;
     /**
-     * Computes the union of two arrays, removing duplicates using
-     * `Equal.equivalence()`.
+     * Computes the union of two iterables using `Equal.asEquivalence()`.
+     *
+     * **Gotchas**
+     *
+     * Each input must already be deduplicated. Use {@link dedupe} to remove
+     * duplicates from an input first.
      *
      * **Example** (Computing array unions)
      *
@@ -6567,8 +6708,12 @@ export declare const union: {
      */
     <A, B>(self: NonEmptyReadonlyArray<A>, that: ReadonlyArray<B>): NonEmptyArray<A | B>;
     /**
-     * Computes the union of two arrays, removing duplicates using
-     * `Equal.equivalence()`.
+     * Computes the union of two iterables using `Equal.asEquivalence()`.
+     *
+     * **Gotchas**
+     *
+     * Each input must already be deduplicated. Use {@link dedupe} to remove
+     * duplicates from an input first.
      *
      * **Example** (Computing array unions)
      *
@@ -6588,8 +6733,12 @@ export declare const union: {
      */
     <A, B>(self: ReadonlyArray<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<A | B>;
     /**
-     * Computes the union of two arrays, removing duplicates using
-     * `Equal.equivalence()`.
+     * Computes the union of two iterables using `Equal.asEquivalence()`.
+     *
+     * **Gotchas**
+     *
+     * Each input must already be deduplicated. Use {@link dedupe} to remove
+     * duplicates from an input first.
      *
      * **Example** (Computing array unions)
      *
@@ -6630,7 +6779,7 @@ export declare const union: {
  * Array.intersectionWith(isEquivalent)(array2)(array1) // => [{ id: 1 }, { id: 3 }]
  * ```
  *
- * @see {@link intersection} for the `Equal.equivalence()` variant
+ * @see {@link intersection} for the `Equal.asEquivalence()` variant
  * @see {@link unionWith} for keeping values from either array with custom equality
  * @see {@link differenceWith} for keeping values only from the first array with custom equality
  *
@@ -6643,7 +6792,7 @@ export declare const intersectionWith: <A>(isEquivalent: (self: A, that: A) => b
     (self: Iterable<A>, that: Iterable<A>): Array<A>;
 };
 /**
- * Computes the intersection of two arrays using `Equal.equivalence()`. Order is
+ * Computes the intersection of two arrays using `Equal.asEquivalence()`. Order is
  * determined by the first array.
  *
  * **When to use**
@@ -6669,7 +6818,7 @@ export declare const intersectionWith: <A>(isEquivalent: (self: A, that: A) => b
  */
 export declare const intersection: {
     /**
-     * Computes the intersection of two arrays using `Equal.equivalence()`. Order is
+     * Computes the intersection of two arrays using `Equal.asEquivalence()`. Order is
      * determined by the first array.
      *
      * **When to use**
@@ -6695,7 +6844,7 @@ export declare const intersection: {
      */
     <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Array<A & B>;
     /**
-     * Computes the intersection of two arrays using `Equal.equivalence()`. Order is
+     * Computes the intersection of two arrays using `Equal.asEquivalence()`. Order is
      * determined by the first array.
      *
      * **When to use**
@@ -6738,7 +6887,7 @@ export declare const intersection: {
  * Array.differenceWith<number>((a, b) => a === b)([1, 2, 3], [2, 3, 4]) // => [1]
  * ```
  *
- * @see {@link difference} for the `Equal.equivalence()` variant
+ * @see {@link difference} for the `Equal.asEquivalence()` variant
  * @see {@link unionWith} for keeping values from either array with custom equality
  * @see {@link intersectionWith} for keeping values present in both arrays with custom equality
  *
@@ -6752,12 +6901,12 @@ export declare const differenceWith: <A>(isEquivalent: (self: A, that: A) => boo
 };
 /**
  * Computes elements in the first array that are not in the second, using
- * `Equal.equivalence()`.
+ * `Equal.asEquivalence()`.
  *
  * **When to use**
  *
  * 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.
+ * the second and the default `Equal.asEquivalence()` comparison is appropriate.
  *
  * **Example** (Computing array differences)
  *
@@ -6778,12 +6927,12 @@ export declare const differenceWith: <A>(isEquivalent: (self: A, that: A) => boo
 export declare const difference: {
     /**
      * Computes elements in the first array that are not in the second, using
-     * `Equal.equivalence()`.
+     * `Equal.asEquivalence()`.
      *
      * **When to use**
      *
      * 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.
+     * the second and the default `Equal.asEquivalence()` comparison is appropriate.
      *
      * **Example** (Computing array differences)
      *
@@ -6804,12 +6953,12 @@ export declare const difference: {
     <A>(that: Iterable<A>): (self: Iterable<A>) => Array<A>;
     /**
      * Computes elements in the first array that are not in the second, using
-     * `Equal.equivalence()`.
+     * `Equal.asEquivalence()`.
      *
      * **When to use**
      *
      * 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.
+     * the second and the default `Equal.asEquivalence()` comparison is appropriate.
      *
      * **Example** (Computing array differences)
      *
@@ -8667,7 +8816,7 @@ export declare const dedupeWith: {
     <A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Array<A>;
 };
 /**
- * Removes duplicates using `Equal.equivalence()`, preserving the order of the
+ * Removes duplicates using `Equal.asEquivalence()`, preserving the order of the
  * first occurrence.
  *
  * **When to use**
@@ -8780,7 +8929,7 @@ export declare const dedupeAdjacentWith: {
     <A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Array<A>;
 };
 /**
- * Removes consecutive duplicate elements using `Equal.equivalence()`.
+ * Removes consecutive duplicate elements using `Equal.asEquivalence()`.
  *
  * **When to use**
  *