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

package/src/Array.ts

@@ -1578,8 +1578,8 @@ export const get: {
  *
  * @see {@link get} — safe version returning `Option`
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 2.0.0
  */
 export const getUnsafe: {
   /**
@@ -1599,8 +1599,8 @@ export 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
   /**
@@ -1620,8 +1620,8 @@ export 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
 } = dual(2, <A>(self: ReadonlyArray<A>, index: number): A => {
@@ -2869,8 +2869,12 @@ export const findFirst: {
 } = moduleIterable.findFirst
 
 /**
- * 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,8 +2892,12 @@ export const findFirst: {
  */
 export 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)
    *
@@ -2907,8 +2915,12 @@ export 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)
    *
@@ -2926,8 +2938,12 @@ export 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)
    *
@@ -2945,8 +2961,12 @@ export 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)
    *
@@ -2964,8 +2984,12 @@ export 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)
    *
@@ -2983,8 +3007,12 @@ export 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)
    *
@@ -3279,9 +3307,10 @@ export const insertAt: {
 })
 
 /**
- * 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)
@@ -3300,9 +3329,10 @@ export const insertAt: {
  */
 export 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)
@@ -3323,9 +3353,10 @@ export const replace: {
     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)
@@ -3349,9 +3380,10 @@ export const replace: {
 )
 
 /**
- * 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)
@@ -3372,9 +3404,10 @@ export const replace: {
  */
 export 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)
@@ -3395,9 +3428,10 @@ export 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)
@@ -3642,8 +3676,8 @@ export 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 const sortWith: {
   /**
@@ -3665,8 +3699,8 @@ export 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>>
   /**
@@ -3688,8 +3722,8 @@ export 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>
   /**
@@ -3711,8 +3745,8 @@ export 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>
 } = dual(
@@ -4366,11 +4400,12 @@ export const setLastNonEmpty: {
 )
 
 /**
- * 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)
  *
@@ -4385,11 +4420,12 @@ export const setLastNonEmpty: {
  */
 export 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)
    *
@@ -4404,11 +4440,12 @@ export 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)
    *
@@ -4423,11 +4460,12 @@ export 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)
    *
@@ -4839,8 +4877,8 @@ export const splitAtNonEmpty: {
  *
  * @see {@link chunksOf} — split into fixed-size chunks
  *
- * @since 2.0.0
  * @category splitting
+ * @since 2.0.0
  */
 export const split: {
   /**
@@ -4859,8 +4897,8 @@ export 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>>
   /**
@@ -4879,8 +4917,8 @@ export 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>>
 } = dual(2, <A>(self: Iterable<A>, n: number) => {
@@ -5991,7 +6029,8 @@ export declare namespace ReadonlyArray {
   /**
    * Infers the element type of an iterable.
    *
-   * @example
+   * **Example** (Inferring an element type)
+   *
    * ```ts
    * import type { Array } from "effect"
    *
@@ -6009,7 +6048,8 @@ export declare namespace ReadonlyArray {
   /**
    * Constructs an array type preserving non-emptiness.
    *
-   * @example
+   * **Example** (Preserving non-emptiness)
+   *
    * ```ts
    * import type { Array } from "effect"
    *
@@ -6026,7 +6066,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"
    *
@@ -6052,7 +6093,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"
    *
@@ -6078,7 +6120,8 @@ export declare namespace ReadonlyArray {
   /**
    * Flattens a nested array type.
    *
-   * @example
+   * **Example** (Flattening nested array types)
+   *
    * ```ts
    * import type { Array } from "effect"
    *
@@ -6657,9 +6700,10 @@ export const partition: {
 )
 
 /**
- * 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)
  *
@@ -7729,8 +7773,8 @@ export const dedupeAdjacent: <A>(self: Iterable<A>) => Array<A> = dedupeAdjacent
  *
  * @see {@link intersperse} — insert separator elements without joining
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export const join: {
   /**
@@ -7746,8 +7790,8 @@ export 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
   /**
@@ -7763,8 +7807,8 @@ export 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
 } = dual(2, (self: Iterable<string>, sep: string): string => fromIterable(self).join(sep))
@@ -7789,8 +7833,8 @@ export 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 const mapAccum: {
   /**
@@ -7813,8 +7857,8 @@ export 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>]
   /**
@@ -7837,8 +7881,8 @@ export 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,
@@ -7879,8 +7923,8 @@ export const mapAccum: {
  *
  * @see {@link cartesian} — returns tuples instead of applying a combiner
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const cartesianWith: {
   /**
@@ -7901,8 +7945,8 @@ export 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>
   /**
@@ -7923,8 +7967,8 @@ export 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>
 } = dual(
@@ -7950,8 +7994,8 @@ export const cartesianWith: {
  *
  * @see {@link cartesianWith} — apply a combiner to each pair
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const cartesian: {
   /**
@@ -7971,8 +8015,8 @@ export 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]>
   /**
@@ -7992,8 +8036,8 @@ export 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]>
 } = dual(
@@ -8257,6 +8301,7 @@ const reducer = Reducer.make((a, b) => a.concat(b), [] as any)
  *
  * @see {@link makeReducerConcat} — mutable `Array` variant
  *
+ * @category folding
  * @since 4.0.0
  */
 export function getReadonlyReducerConcat<A>(): Reducer.Reducer<ReadonlyArray<A>> {
@@ -8268,6 +8313,7 @@ export function getReadonlyReducerConcat<A>(): Reducer.Reducer<ReadonlyArray<A>>
  *
  * @see {@link getReadonlyReducerConcat} — readonly variant
  *
+ * @category folding
  * @since 4.0.0
  */
 export function makeReducerConcat<A>(): Reducer.Reducer<Array<A>> {