effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/Array.ts

@@ -462,7 +462,7 @@ export const ensure = <A>(self: ReadonlyArray<A> | A): Array<A> => Array.isArray
  * console.log(result) // [["a", 1], ["b", 2], ["c", 3]]
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export const fromRecord: <K extends string, A>(self: Readonly<Record<K, A>>) => Array<[K, A]> = Record.toEntries
@@ -481,7 +481,7 @@ export const fromRecord: <K extends string, A>(self: Readonly<Record<K, A>>) =>
  *
  * @see {@link getSomes} — extract `Some` values from an array of Options
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export const fromOption: <A>(self: Option.Option<A>) => Array<A> = Option.toArray
@@ -1394,7 +1394,7 @@ export const isArray: {
  * @see {@link isArrayNonEmpty} — opposite check
  *
  * @category guards
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isArrayEmpty = <A>(self: Array<A>): self is [] => self.length === 0
 
@@ -1414,7 +1414,7 @@ export const isArrayEmpty = <A>(self: Array<A>): self is [] => self.length === 0
  * @see {@link isReadonlyArrayNonEmpty} — opposite check
  *
  * @category guards
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isReadonlyArrayEmpty: <A>(self: ReadonlyArray<A>) => self is readonly [] = isArrayEmpty as any
 
@@ -1435,7 +1435,7 @@ export const isReadonlyArrayEmpty: <A>(self: ReadonlyArray<A>) => self is readon
  * @see {@link isArrayEmpty} — opposite check
  *
  * @category guards
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isArrayNonEmpty: <A>(self: Array<A>) => self is NonEmptyArray<A> = internalArray.isArrayNonEmpty
 
@@ -1456,7 +1456,7 @@ export const isArrayNonEmpty: <A>(self: Array<A>) => self is NonEmptyArray<A> =
  * @see {@link isReadonlyArrayEmpty} — opposite check
  *
  * @category guards
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const isReadonlyArrayNonEmpty: <A>(self: ReadonlyArray<A>) => self is NonEmptyReadonlyArray<A> =
   internalArray.isArrayNonEmpty
@@ -1578,8 +1578,8 @@ export const get: {
  *
  * @see {@link get} — safe version returning `Option`
  *
- * @since 2.0.0
  * @category unsafe
+ * @since 4.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 4.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 4.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(
@@ -4135,7 +4169,7 @@ export const intersperse: {
  * @see {@link modifyLastNonEmpty} — modify the last element
  *
  * @category elements
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const modifyHeadNonEmpty: {
   /**
@@ -4154,7 +4188,7 @@ export const modifyHeadNonEmpty: {
    * @see {@link modifyLastNonEmpty} — modify the last element
    *
    * @category elements
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B): (self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
   /**
@@ -4173,7 +4207,7 @@ export const modifyHeadNonEmpty: {
    * @see {@link modifyLastNonEmpty} — modify the last element
    *
    * @category elements
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A) => B): NonEmptyArray<A | B>
 } = dual(
@@ -4199,7 +4233,7 @@ export const modifyHeadNonEmpty: {
  * @see {@link setLastNonEmpty} — replace the last element
  *
  * @category elements
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const setHeadNonEmpty: {
   /**
@@ -4217,7 +4251,7 @@ export const setHeadNonEmpty: {
    * @see {@link setLastNonEmpty} — replace the last element
    *
    * @category elements
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <B>(b: B): <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
   /**
@@ -4235,7 +4269,7 @@ export const setHeadNonEmpty: {
    * @see {@link setLastNonEmpty} — replace the last element
    *
    * @category elements
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(self: NonEmptyReadonlyArray<A>, b: B): NonEmptyArray<A | B>
 } = dual(
@@ -4259,7 +4293,7 @@ export const setHeadNonEmpty: {
  * @see {@link modifyHeadNonEmpty} — modify the first element
  *
  * @category elements
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const modifyLastNonEmpty: {
   /**
@@ -4278,7 +4312,7 @@ export const modifyLastNonEmpty: {
    * @see {@link modifyHeadNonEmpty} — modify the first element
    *
    * @category elements
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B): (self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
   /**
@@ -4297,7 +4331,7 @@ export const modifyLastNonEmpty: {
    * @see {@link modifyHeadNonEmpty} — modify the first element
    *
    * @category elements
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A) => B): NonEmptyArray<A | B>
 } = dual(
@@ -4321,7 +4355,7 @@ export const modifyLastNonEmpty: {
  * @see {@link setHeadNonEmpty} — replace the first element
  *
  * @category elements
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const setLastNonEmpty: {
   /**
@@ -4339,7 +4373,7 @@ export const setLastNonEmpty: {
    * @see {@link setHeadNonEmpty} — replace the first element
    *
    * @category elements
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <B>(b: B): <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
   /**
@@ -4357,7 +4391,7 @@ export const setLastNonEmpty: {
    * @see {@link setHeadNonEmpty} — replace the first element
    *
    * @category elements
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(self: NonEmptyReadonlyArray<A>, b: B): NonEmptyArray<A | B>
 } = 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)
    *
@@ -4775,7 +4813,7 @@ export const splitAt: {
  * @see {@link splitAt} — for possibly-empty arrays
  *
  * @category splitting
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const splitAtNonEmpty: {
   /**
@@ -4794,7 +4832,7 @@ export const splitAtNonEmpty: {
    * @see {@link splitAt} — for possibly-empty arrays
    *
    * @category splitting
-   * @since 2.0.0
+   * @since 4.0.0
    */
   (n: number): <A>(self: NonEmptyReadonlyArray<A>) => [beforeIndex: NonEmptyArray<A>, fromIndex: Array<A>]
   /**
@@ -4813,7 +4851,7 @@ export const splitAtNonEmpty: {
    * @see {@link splitAt} — for possibly-empty arrays
    *
    * @category splitting
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A>(self: NonEmptyReadonlyArray<A>, n: number): [beforeIndex: NonEmptyArray<A>, fromIndex: Array<A>]
 } = dual(2, <A>(self: NonEmptyReadonlyArray<A>, n: number): [NonEmptyArray<A>, Array<A>] => {
@@ -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) => {
@@ -5984,14 +6022,14 @@ export const of = <A>(a: A): NonEmptyArray<A> => [a]
  * Utility types for working with `ReadonlyArray` at the type level. Use these
  * to infer element types, preserve non-emptiness, and flatten nested arrays.
  *
- * @category types
  * @since 2.0.0
  */
 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 +6047,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 +6065,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 +6092,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 +6119,8 @@ export declare namespace ReadonlyArray {
   /**
    * Flattens a nested array type.
    *
-   * @example
+   * **Example** (Flattening nested array types)
+   *
    * ```ts
    * import type { Array } from "effect"
    *
@@ -6327,7 +6369,7 @@ export const getSomes: <T extends Iterable<Option.Option<X>>, X = any>(
  * @see {@link separate} — split into failures and successes
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const getFailures = <T extends Iterable<Result.Result<any, any>>>(
   self: T
@@ -6359,7 +6401,7 @@ export const getFailures = <T extends Iterable<Result.Result<any, any>>>(
  * @see {@link separate} — split into failures and successes
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const getSuccesses = <T extends Iterable<Result.Result<any, any>>>(
   self: T
@@ -6392,7 +6434,7 @@ export const getSuccesses = <T extends Iterable<Result.Result<any, any>>>(
  * @see {@link filter} — keep original elements matching a predicate
  *
  * @category filtering
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const filterMap: {
   /**
@@ -6413,7 +6455,7 @@ export const filterMap: {
    * @see {@link filter} — keep original elements matching a predicate
    *
    * @category filtering
-   * @since 4.0.0
+   * @since 2.0.0
    */
   <A, B, X>(f: (input: NoInfer<A>, i: number) => Result.Result<B, X>): (self: Iterable<A>) => Array<B>
   /**
@@ -6434,7 +6476,7 @@ export const filterMap: {
    * @see {@link filter} — keep original elements matching a predicate
    *
    * @category filtering
-   * @since 4.0.0
+   * @since 2.0.0
    */
   <A, B, X>(self: Iterable<A>, f: (input: A, i: number) => Result.Result<B, X>): Array<B>
 } = dual(2, <A, B, X>(self: Iterable<A>, f: (input: A, i: number) => Result.Result<B, X>): Array<B> => {
@@ -6581,7 +6623,7 @@ export const filter: {
  * ```
  *
  * @see {@link filter} — keep only matching elements
- * @see {@link partitionMap} — partition using a Result-returning function
+ * @see {@link separate} — split an iterable of `Result` values
  *
  * @category filtering
  * @since 2.0.0
@@ -6605,7 +6647,7 @@ export const partition: {
    * ```
    *
    * @see {@link filter} — keep only matching elements
-   * @see {@link partitionMap} — partition using a Result-returning function
+   * @see {@link separate} — split an iterable of `Result` values
    *
    * @category filtering
    * @since 2.0.0
@@ -6629,7 +6671,7 @@ export const partition: {
    * ```
    *
    * @see {@link filter} — keep only matching elements
-   * @see {@link partitionMap} — partition using a Result-returning function
+   * @see {@link separate} — split an iterable of `Result` values
    *
    * @category filtering
    * @since 2.0.0
@@ -6657,9 +6699,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)
  *
@@ -6908,8 +6951,8 @@ export const liftOption = <A extends Array<unknown>, B>(
  * @see {@link liftNullishOr} — lift a nullable-returning function
  * @see {@link fromOption} — convert from Option
  *
- * @category conversions
- * @since 2.0.0
+ * @category converting
+ * @since 4.0.0
  */
 export const fromNullishOr = <A>(a: A): Array<NonNullable<A>> => a == null ? empty() : [a as NonNullable<A>]
 
@@ -6934,7 +6977,7 @@ export const fromNullishOr = <A>(a: A): Array<NonNullable<A>> => a == null ? emp
  * @see {@link liftOption} — lift an Option-returning function
  *
  * @category lifting
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const liftNullishOr = <A extends Array<unknown>, B>(
   f: (...a: A) => B
@@ -6955,7 +6998,7 @@ export const liftNullishOr = <A extends Array<unknown>, B>(
  * ```
  *
  * @category sequencing
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const flatMapNullishOr: {
   /**
@@ -6972,7 +7015,7 @@ export const flatMapNullishOr: {
    * ```
    *
    * @category sequencing
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B): (self: ReadonlyArray<A>) => Array<NonNullable<B>>
   /**
@@ -6989,7 +7032,7 @@ export const flatMapNullishOr: {
    * ```
    *
    * @category sequencing
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(self: ReadonlyArray<A>, f: (a: A) => B): Array<NonNullable<B>>
 } = dual(
@@ -7020,7 +7063,7 @@ export const flatMapNullishOr: {
  * @see {@link liftPredicate} — lift a boolean predicate
  *
  * @category lifting
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const liftResult = <A extends Array<unknown>, E, B>(
   f: (...a: A) => Result.Result<B, E>
@@ -7426,7 +7469,7 @@ export const unfold = <B, A>(b: B, f: (b: B) => Option.Option<readonly [A, B]>):
  * @see {@link makeEquivalence} — create an equivalence for arrays
  *
  * @category instances
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const makeOrder: <A>(O: Order.Order<A>) => Order.Order<ReadonlyArray<A>> = Order.Array
 
@@ -7447,7 +7490,7 @@ export const makeOrder: <A>(O: Order.Order<A>) => Order.Order<ReadonlyArray<A>>
  * @see {@link makeOrder} — create an ordering for arrays
  *
  * @category instances
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const makeEquivalence: <A>(
   isEquivalent: Equivalence.Equivalence<A>
@@ -7729,8 +7772,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 +7789,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 +7806,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 +7832,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 +7856,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 +7880,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 +7922,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 +7944,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 +7966,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 +7993,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 +8014,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 +8035,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 +8300,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 +8312,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>> {