effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/Array.d.ts

@@ -1377,8 +1377,8 @@ export declare const get: {
  *
  * @see {@link get} — safe version returning `Option`
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export declare const getUnsafe: {
     /**
@@ -1398,8 +1398,8 @@ export declare const getUnsafe: {
      *
      * @see {@link get} — safe version returning `Option`
      *
-     * @since 2.0.0
      * @category unsafe
+     * @since 2.0.0
      */
     (index: number): <A>(self: ReadonlyArray<A>) => A;
     /**
@@ -1419,8 +1419,8 @@ export declare const getUnsafe: {
      *
      * @see {@link get} — safe version returning `Option`
      *
-     * @since 2.0.0
      * @category unsafe
+     * @since 2.0.0
      */
     <A>(self: ReadonlyArray<A>, index: number): A;
 };
@@ -2532,8 +2532,12 @@ export declare const findFirst: {
     <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option.Option<A>;
 };
 /**
- * Returns a tuple `[element, index]` of the first element matching a
- * predicate, wrapped in an `Option`.
+ * Returns the first selected value together with its index, wrapped in an
+ * `Option`.
+ *
+ * Accepts a predicate, a refinement, or a function returning `Option`. For an
+ * `Option`-returning function, returns `[mappedValue, index]` for the first
+ * `Some`, or `Option.none()` if no element is selected.
  *
  * **Example** (Finding element with its index)
  *
@@ -2551,8 +2555,12 @@ export declare const findFirst: {
  */
 export declare const findFirstWithIndex: {
     /**
-     * Returns a tuple `[element, index]` of the first element matching a
-     * predicate, wrapped in an `Option`.
+     * Returns the first selected value together with its index, wrapped in an
+     * `Option`.
+     *
+     * Accepts a predicate, a refinement, or a function returning `Option`. For an
+     * `Option`-returning function, returns `[mappedValue, index]` for the first
+     * `Some`, or `Option.none()` if no element is selected.
      *
      * **Example** (Finding element with its index)
      *
@@ -2570,8 +2578,12 @@ export declare const findFirstWithIndex: {
      */
     <A, B>(f: (a: NoInfer<A>, i: number) => Option.Option<B>): (self: Iterable<A>) => Option.Option<[B, number]>;
     /**
-     * Returns a tuple `[element, index]` of the first element matching a
-     * predicate, wrapped in an `Option`.
+     * Returns the first selected value together with its index, wrapped in an
+     * `Option`.
+     *
+     * Accepts a predicate, a refinement, or a function returning `Option`. For an
+     * `Option`-returning function, returns `[mappedValue, index]` for the first
+     * `Some`, or `Option.none()` if no element is selected.
      *
      * **Example** (Finding element with its index)
      *
@@ -2589,8 +2601,12 @@ export declare const findFirstWithIndex: {
      */
     <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option.Option<[B, number]>;
     /**
-     * Returns a tuple `[element, index]` of the first element matching a
-     * predicate, wrapped in an `Option`.
+     * Returns the first selected value together with its index, wrapped in an
+     * `Option`.
+     *
+     * Accepts a predicate, a refinement, or a function returning `Option`. For an
+     * `Option`-returning function, returns `[mappedValue, index]` for the first
+     * `Some`, or `Option.none()` if no element is selected.
      *
      * **Example** (Finding element with its index)
      *
@@ -2608,8 +2624,12 @@ export declare const findFirstWithIndex: {
      */
     <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option.Option<[A, number]>;
     /**
-     * Returns a tuple `[element, index]` of the first element matching a
-     * predicate, wrapped in an `Option`.
+     * Returns the first selected value together with its index, wrapped in an
+     * `Option`.
+     *
+     * Accepts a predicate, a refinement, or a function returning `Option`. For an
+     * `Option`-returning function, returns `[mappedValue, index]` for the first
+     * `Some`, or `Option.none()` if no element is selected.
      *
      * **Example** (Finding element with its index)
      *
@@ -2627,8 +2647,12 @@ export declare const findFirstWithIndex: {
      */
     <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option.Option<B>): Option.Option<[B, number]>;
     /**
-     * Returns a tuple `[element, index]` of the first element matching a
-     * predicate, wrapped in an `Option`.
+     * Returns the first selected value together with its index, wrapped in an
+     * `Option`.
+     *
+     * Accepts a predicate, a refinement, or a function returning `Option`. For an
+     * `Option`-returning function, returns `[mappedValue, index]` for the first
+     * `Some`, or `Option.none()` if no element is selected.
      *
      * **Example** (Finding element with its index)
      *
@@ -2646,8 +2670,12 @@ export declare const findFirstWithIndex: {
      */
     <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option.Option<[B, number]>;
     /**
-     * Returns a tuple `[element, index]` of the first element matching a
-     * predicate, wrapped in an `Option`.
+     * Returns the first selected value together with its index, wrapped in an
+     * `Option`.
+     *
+     * Accepts a predicate, a refinement, or a function returning `Option`. For an
+     * `Option`-returning function, returns `[mappedValue, index]` for the first
+     * `Some`, or `Option.none()` if no element is selected.
      *
      * **Example** (Finding element with its index)
      *
@@ -2888,9 +2916,10 @@ export declare const insertAt: {
     <A, B>(self: Iterable<A>, i: number, b: B): Option.Option<NonEmptyArray<A | B>>;
 };
 /**
- * Replaces the element at the specified index with a new value, returning a new
- * array, wrapped in an `Option`.
+ * Replaces the element at the specified index with a new value, returning the
+ * updated array in `Option.some`.
  *
+ * - Returns `Option.none()` when the index is out of bounds.
  * - Does not mutate the input.
  *
  * **Example** (Replacing an element)
@@ -2909,9 +2938,10 @@ export declare const insertAt: {
  */
 export declare const replace: {
     /**
-     * Replaces the element at the specified index with a new value, returning a new
-     * array, wrapped in an `Option`.
+     * Replaces the element at the specified index with a new value, returning the
+     * updated array in `Option.some`.
      *
+     * - Returns `Option.none()` when the index is out of bounds.
      * - Does not mutate the input.
      *
      * **Example** (Replacing an element)
@@ -2930,9 +2960,10 @@ export declare const replace: {
      */
     <B>(i: number, b: B): <A, S extends Iterable<A> = Iterable<A>>(self: S) => Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>;
     /**
-     * Replaces the element at the specified index with a new value, returning a new
-     * array, wrapped in an `Option`.
+     * Replaces the element at the specified index with a new value, returning the
+     * updated array in `Option.some`.
      *
+     * - Returns `Option.none()` when the index is out of bounds.
      * - Does not mutate the input.
      *
      * **Example** (Replacing an element)
@@ -2952,9 +2983,10 @@ export declare const replace: {
     <A, B, S extends Iterable<A> = Iterable<A>>(self: S, i: number, b: B): Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>;
 };
 /**
- * Applies a function to the element at the specified index, returning a new
- * array, wrapped in an `Option`.
+ * Applies a function to the element at the specified index, returning the
+ * updated array in `Option.some`.
  *
+ * - Returns `Option.none()` when the index is out of bounds.
  * - Does not mutate the input.
  *
  * **Example** (Modifying an element)
@@ -2975,9 +3007,10 @@ export declare const replace: {
  */
 export declare const modify: {
     /**
-     * Applies a function to the element at the specified index, returning a new
-     * array, wrapped in an `Option`.
+     * Applies a function to the element at the specified index, returning the
+     * updated array in `Option.some`.
      *
+     * - Returns `Option.none()` when the index is out of bounds.
      * - Does not mutate the input.
      *
      * **Example** (Modifying an element)
@@ -2998,9 +3031,10 @@ export declare const modify: {
      */
     <A, B, S extends Iterable<A> = Iterable<A>>(i: number, f: (a: ReadonlyArray.Infer<S>) => B): (self: S) => Option.Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>;
     /**
-     * Applies a function to the element at the specified index, returning a new
-     * array, wrapped in an `Option`.
+     * Applies a function to the element at the specified index, returning the
+     * updated array in `Option.some`.
      *
+     * - Returns `Option.none()` when the index is out of bounds.
      * - Does not mutate the input.
      *
      * **Example** (Modifying an element)
@@ -3218,8 +3252,8 @@ export declare const sort: {
  * @see {@link sort} — sort by a direct `Order`
  * @see {@link sortBy} — sort by multiple orders
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const sortWith: {
     /**
@@ -3241,8 +3275,8 @@ export declare const sortWith: {
      * @see {@link sort} — sort by a direct `Order`
      * @see {@link sortBy} — sort by multiple orders
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <S extends Iterable<any>, B>(f: (a: ReadonlyArray.Infer<S>) => B, order: Order.Order<B>): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>;
     /**
@@ -3264,8 +3298,8 @@ export declare const sortWith: {
      * @see {@link sort} — sort by a direct `Order`
      * @see {@link sortBy} — sort by multiple orders
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A) => B, O: Order.Order<B>): NonEmptyArray<A>;
     /**
@@ -3287,8 +3321,8 @@ export declare const sortWith: {
      * @see {@link sort} — sort by a direct `Order`
      * @see {@link sortBy} — sort by multiple orders
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B>(self: Iterable<A>, f: (a: A) => B, order: Order.Order<B>): Array<A>;
 };
@@ -3850,11 +3884,12 @@ export declare const setLastNonEmpty: {
     <A, B>(self: NonEmptyReadonlyArray<A>, b: B): NonEmptyArray<A | B>;
 };
 /**
- * Rotates an array by `n` steps. Positive `n` rotates left (front elements
- * move to the back).
+ * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+ * rotates left.
  *
+ * - `n` is rounded to the nearest integer before rotating.
  * - Preserves `NonEmptyArray` in the return type.
- * - Returns a copy for empty arrays or `n === 0`.
+ * - Returns a copy for empty arrays or when the normalized rotation is `0`.
  *
  * **Example** (Rotating elements)
  *
@@ -3869,11 +3904,12 @@ export declare const setLastNonEmpty: {
  */
 export declare const rotate: {
     /**
-     * Rotates an array by `n` steps. Positive `n` rotates left (front elements
-     * move to the back).
+     * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+     * rotates left.
      *
+     * - `n` is rounded to the nearest integer before rotating.
      * - Preserves `NonEmptyArray` in the return type.
-     * - Returns a copy for empty arrays or `n === 0`.
+     * - Returns a copy for empty arrays or when the normalized rotation is `0`.
      *
      * **Example** (Rotating elements)
      *
@@ -3888,11 +3924,12 @@ export declare const rotate: {
      */
     (n: number): <S extends Iterable<any>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>;
     /**
-     * Rotates an array by `n` steps. Positive `n` rotates left (front elements
-     * move to the back).
+     * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+     * rotates left.
      *
+     * - `n` is rounded to the nearest integer before rotating.
      * - Preserves `NonEmptyArray` in the return type.
-     * - Returns a copy for empty arrays or `n === 0`.
+     * - Returns a copy for empty arrays or when the normalized rotation is `0`.
      *
      * **Example** (Rotating elements)
      *
@@ -3907,11 +3944,12 @@ export declare const rotate: {
      */
     <A>(self: NonEmptyReadonlyArray<A>, n: number): NonEmptyArray<A>;
     /**
-     * Rotates an array by `n` steps. Positive `n` rotates left (front elements
-     * move to the back).
+     * Rotates an array by `n` steps. Positive `n` rotates right; negative `n`
+     * rotates left.
      *
+     * - `n` is rounded to the nearest integer before rotating.
      * - Preserves `NonEmptyArray` in the return type.
-     * - Returns a copy for empty arrays or `n === 0`.
+     * - Returns a copy for empty arrays or when the normalized rotation is `0`.
      *
      * **Example** (Rotating elements)
      *
@@ -4253,8 +4291,8 @@ export declare const splitAtNonEmpty: {
  *
  * @see {@link chunksOf} — split into fixed-size chunks
  *
- * @since 2.0.0
  * @category splitting
+ * @since 2.0.0
  */
 export declare const split: {
     /**
@@ -4273,8 +4311,8 @@ export declare const split: {
      *
      * @see {@link chunksOf} — split into fixed-size chunks
      *
-     * @since 2.0.0
      * @category splitting
+     * @since 2.0.0
      */
     (n: number): <A>(self: Iterable<A>) => Array<Array<A>>;
     /**
@@ -4293,8 +4331,8 @@ export declare const split: {
      *
      * @see {@link chunksOf} — split into fixed-size chunks
      *
-     * @since 2.0.0
      * @category splitting
+     * @since 2.0.0
      */
     <A>(self: Iterable<A>, n: number): Array<Array<A>>;
 };
@@ -5250,7 +5288,8 @@ export declare namespace ReadonlyArray {
     /**
      * Infers the element type of an iterable.
      *
-     * @example
+     * **Example** (Inferring an element type)
+     *
      * ```ts
      * import type { Array } from "effect"
      *
@@ -5265,7 +5304,8 @@ export declare namespace ReadonlyArray {
     /**
      * Constructs an array type preserving non-emptiness.
      *
-     * @example
+     * **Example** (Preserving non-emptiness)
+     *
      * ```ts
      * import type { Array } from "effect"
      *
@@ -5280,7 +5320,8 @@ export declare namespace ReadonlyArray {
     /**
      * Creates a non-empty array if either input is non-empty.
      *
-     * @example
+     * **Example** (Preserving non-emptiness from either input)
+     *
      * ```ts
      * import type { Array } from "effect"
      *
@@ -5299,7 +5340,8 @@ export declare namespace ReadonlyArray {
     /**
      * Creates a non-empty array only if both inputs are non-empty.
      *
-     * @example
+     * **Example** (Preserving non-emptiness from both inputs)
+     *
      * ```ts
      * import type { Array } from "effect"
      *
@@ -5318,7 +5360,8 @@ export declare namespace ReadonlyArray {
     /**
      * Flattens a nested array type.
      *
-     * @example
+     * **Example** (Flattening nested array types)
+     *
      * ```ts
      * import type { Array } from "effect"
      *
@@ -5792,9 +5835,10 @@ export declare const partition: {
     <A, Pass, Fail>(self: Iterable<A>, f: (input: A, i: number) => Result.Result<Pass, Fail>): [excluded: Array<Fail>, satisfying: Array<Pass>];
 };
 /**
- * Separates an iterable of `Result`s into two arrays: failures and successes.
+ * Separates an iterable of `Result`s into failure values and success values.
  *
- * - Equivalent to `partitionMap(identity)`.
+ * - Returns `[failures, successes]`.
+ * - Equivalent to `partition(identity)`.
  *
  * **Example** (Separating Results)
  *
@@ -6757,8 +6801,8 @@ export declare const dedupeAdjacent: <A>(self: Iterable<A>) => Array<A>;
  *
  * @see {@link intersperse} — insert separator elements without joining
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export declare const join: {
     /**
@@ -6774,8 +6818,8 @@ export declare const join: {
      *
      * @see {@link intersperse} — insert separator elements without joining
      *
-     * @since 2.0.0
      * @category folding
+     * @since 2.0.0
      */
     (sep: string): (self: Iterable<string>) => string;
     /**
@@ -6791,8 +6835,8 @@ export declare const join: {
      *
      * @see {@link intersperse} — insert separator elements without joining
      *
-     * @since 2.0.0
      * @category folding
+     * @since 2.0.0
      */
     (self: Iterable<string>, sep: string): string;
 };
@@ -6816,8 +6860,8 @@ export declare const join: {
  * @see {@link scan} — when you only need the accumulated results (not the final state)
  * @see {@link reduce} — when you only need the final accumulated value
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export declare const mapAccum: {
     /**
@@ -6840,8 +6884,8 @@ export declare const mapAccum: {
      * @see {@link scan} — when you only need the accumulated results (not the final state)
      * @see {@link reduce} — when you only need the final accumulated value
      *
-     * @since 2.0.0
      * @category folding
+     * @since 2.0.0
      */
     <S, A, B, I extends Iterable<A> = Iterable<A>>(s: S, f: (s: S, a: ReadonlyArray.Infer<I>, i: number) => readonly [S, B]): (self: I) => [state: S, mappedArray: ReadonlyArray.With<I, B>];
     /**
@@ -6864,8 +6908,8 @@ export declare const mapAccum: {
      * @see {@link scan} — when you only need the accumulated results (not the final state)
      * @see {@link reduce} — when you only need the final accumulated value
      *
-     * @since 2.0.0
      * @category folding
+     * @since 2.0.0
      */
     <S, A, B, I extends Iterable<A> = Iterable<A>>(self: I, s: S, f: (s: S, a: ReadonlyArray.Infer<I>, i: number) => readonly [S, B]): [state: S, mappedArray: ReadonlyArray.With<I, B>];
 };
@@ -6887,8 +6931,8 @@ export declare const mapAccum: {
  *
  * @see {@link cartesian} — returns tuples instead of applying a combiner
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const cartesianWith: {
     /**
@@ -6909,8 +6953,8 @@ export declare const cartesianWith: {
      *
      * @see {@link cartesian} — returns tuples instead of applying a combiner
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B, C>(that: ReadonlyArray<B>, f: (a: A, b: B) => C): (self: ReadonlyArray<A>) => Array<C>;
     /**
@@ -6931,8 +6975,8 @@ export declare const cartesianWith: {
      *
      * @see {@link cartesian} — returns tuples instead of applying a combiner
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B, C>(self: ReadonlyArray<A>, that: ReadonlyArray<B>, f: (a: A, b: B) => C): Array<C>;
 };
@@ -6953,8 +6997,8 @@ export declare const cartesianWith: {
  *
  * @see {@link cartesianWith} — apply a combiner to each pair
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const cartesian: {
     /**
@@ -6974,8 +7018,8 @@ export declare const cartesian: {
      *
      * @see {@link cartesianWith} — apply a combiner to each pair
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <B>(that: ReadonlyArray<B>): <A>(self: ReadonlyArray<A>) => Array<[A, B]>;
     /**
@@ -6995,8 +7039,8 @@ export declare const cartesian: {
      *
      * @see {@link cartesianWith} — apply a combiner to each pair
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B>(self: ReadonlyArray<A>, that: ReadonlyArray<B>): Array<[A, B]>;
 };
@@ -7243,6 +7287,7 @@ let_ as let };
  *
  * @see {@link makeReducerConcat} — mutable `Array` variant
  *
+ * @category folding
  * @since 4.0.0
  */
 export declare function getReadonlyReducerConcat<A>(): Reducer.Reducer<ReadonlyArray<A>>;
@@ -7251,6 +7296,7 @@ export declare function getReadonlyReducerConcat<A>(): Reducer.Reducer<ReadonlyA
  *
  * @see {@link getReadonlyReducerConcat} — readonly variant
  *
+ * @category folding
  * @since 4.0.0
  */
 export declare function makeReducerConcat<A>(): Reducer.Reducer<Array<A>>;