effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/ChannelSchema.ts

@@ -53,6 +53,8 @@ import * as Schema from "./Schema.ts"
  * Creates a channel that encodes non-empty chunks of schema values into the
  * schema's encoded representation.
  *
+ * **Details**
+ *
  * Encoding failures are emitted as `SchemaError`, and any encoding services
  * required by the schema become channel requirements.
  *
@@ -79,6 +81,8 @@ export const encode = <S extends Schema.Top>(
  * Creates an `encode` channel variant whose encoded output chunks are typed as
  * `unknown`.
  *
+ * **When to use**
+ *
  * Use this at channel boundaries where the encoded representation is
  * intentionally untyped, while still encoding typed input chunks with the
  * provided schema.
@@ -102,6 +106,8 @@ export const encodeUnknown: <S extends Schema.Top>(
  * Creates a channel that decodes non-empty chunks from the schema's encoded
  * representation into schema values.
  *
+ * **Details**
+ *
  * Decoding failures are emitted as `SchemaError`, and any decoding services
  * required by the schema become channel requirements.
  *
@@ -127,6 +133,8 @@ export const decode = <S extends Schema.Top>(
 /**
  * Creates a `decode` channel variant for schema-decoding channel boundaries.
  *
+ * **Details**
+ *
  * The channel decodes non-empty encoded chunks into schema values, emits
  * `SchemaError` when decoding fails, and requires the schema's decoding
  * services.
@@ -150,6 +158,8 @@ export const decodeUnknown: <S extends Schema.Top>(
  * Wraps a channel so callers work with typed input and output chunks while the
  * wrapped channel uses encoded chunks.
  *
+ * **Details**
+ *
  * Values sent into the resulting channel are encoded with `inputSchema` before
  * reaching the wrapped channel. Values emitted by the wrapped channel are
  * decoded with `outputSchema` before they are emitted downstream. Schema
@@ -163,6 +173,8 @@ export const duplex: {
    * Wraps a channel so callers work with typed input and output chunks while the
    * wrapped channel uses encoded chunks.
    *
+   * **Details**
+   *
    * Values sent into the resulting channel are encoded with `inputSchema` before
    * reaching the wrapped channel. Values emitted by the wrapped channel are
    * decoded with `outputSchema` before they are emitted downstream. Schema
@@ -199,6 +211,8 @@ export const duplex: {
    * Wraps a channel so callers work with typed input and output chunks while the
    * wrapped channel uses encoded chunks.
    *
+   * **Details**
+   *
    * Values sent into the resulting channel are encoded with `inputSchema` before
    * reaching the wrapped channel. Values emitted by the wrapped channel are
    * decoded with `outputSchema` before they are emitted downstream. Schema
@@ -257,6 +271,8 @@ export const duplex: {
    * Wraps a channel so callers work with typed input and output chunks while the
    * wrapped channel uses encoded chunks.
    *
+   * **Details**
+   *
    * Values sent into the resulting channel are encoded with `inputSchema` before
    * reaching the wrapped channel. Values emitted by the wrapped channel are
    * decoded with `outputSchema` before they are emitted downstream. Schema
@@ -269,6 +285,8 @@ export const duplex: {
    * Wraps a channel so callers work with typed input and output chunks while the
    * wrapped channel uses encoded chunks.
    *
+   * **Details**
+   *
    * Values sent into the resulting channel are encoded with `inputSchema` before
    * reaching the wrapped channel. Values emitted by the wrapped channel are
    * decoded with `outputSchema` before they are emitted downstream. Schema
@@ -285,6 +303,8 @@ export const duplex: {
 /**
  * Like `duplex`, but for channels whose encoded side is not statically typed.
  *
+ * **Details**
+ *
  * The resulting channel accepts typed input chunks, encodes them with
  * `inputSchema`, decodes unknown output chunks with `outputSchema`, and
  * surfaces schema failures as `SchemaError`.
@@ -296,6 +316,8 @@ export const duplexUnknown: {
   /**
    * Like `duplex`, but for channels whose encoded side is not statically typed.
    *
+   * **Details**
+   *
    * The resulting channel accepts typed input chunks, encodes them with
    * `inputSchema`, decodes unknown output chunks with `outputSchema`, and
    * surfaces schema failures as `SchemaError`.
@@ -330,6 +352,8 @@ export const duplexUnknown: {
   /**
    * Like `duplex`, but for channels whose encoded side is not statically typed.
    *
+   * **Details**
+   *
    * The resulting channel accepts typed input chunks, encodes them with
    * `inputSchema`, decodes unknown output chunks with `outputSchema`, and
    * surfaces schema failures as `SchemaError`.

package/src/Chunk.ts

@@ -2221,9 +2221,11 @@ export const chunksOf: {
 })
 
 /**
- * Creates a Chunk of unique values that are included in all given Chunks.
+ * Creates a `Chunk` of values that are included in both chunks.
  *
- * The order and references of result values are determined by the Chunk.
+ * **Details**
+ *
+ * The order and references of result values are determined by the first chunk.
  *
  * **Example** (Intersecting chunks)
  *
@@ -2251,9 +2253,11 @@ export const chunksOf: {
  */
 export const intersection: {
   /**
-   * Creates a Chunk of unique values that are included in all given Chunks.
+   * Creates a `Chunk` of values that are included in both chunks.
    *
-   * The order and references of result values are determined by the Chunk.
+   * **Details**
+   *
+   * The order and references of result values are determined by the first chunk.
    *
    * **Example** (Intersecting chunks)
    *
@@ -2281,9 +2285,11 @@ export const intersection: {
    */
   <A>(that: Chunk<A>): <B>(self: Chunk<B>) => Chunk<A & B>
   /**
-   * Creates a Chunk of unique values that are included in all given Chunks.
+   * Creates a `Chunk` of values that are included in both chunks.
+   *
+   * **Details**
    *
-   * The order and references of result values are determined by the Chunk.
+   * The order and references of result values are determined by the first chunk.
    *
    * **Example** (Intersecting chunks)
    *
@@ -2370,7 +2376,9 @@ export const head: <A>(self: Chunk<A>) => Option<A> = get(0)
 /**
  * Returns the first element of this chunk.
  *
- * It will throw an error if the chunk is empty.
+ * **Gotchas**
+ *
+ * Throws an error if the chunk is empty.
  *
  * **Example** (Getting the first element unsafely)
  *
@@ -2435,7 +2443,9 @@ export const last = <A>(self: Chunk<A>): Option<A> => get(self, self.length - 1)
 /**
  * Returns the last element of this chunk.
  *
- * It will throw an error if the chunk is empty.
+ * **Gotchas**
+ *
+ * Throws an error if the chunk is empty.
  *
  * **Example** (Getting the last element unsafely)
  *
@@ -2813,8 +2823,9 @@ export const mapAccum: {
 /**
  * Splits a chunk using a `Filter` into failures and successes.
  *
- * - Returns `[excluded, satisfying]`.
- * - The filter receives `(element, index)`.
+ * **Details**
+ *
+ * Returns `[excluded, satisfying]`. The filter receives `(element, index)`.
  *
  * **Example** (Partitioning with a Result)
  *
@@ -2836,8 +2847,9 @@ export const partition: {
   /**
    * Splits a chunk using a `Filter` into failures and successes.
    *
-   * - Returns `[excluded, satisfying]`.
-   * - The filter receives `(element, index)`.
+   * **Details**
+   *
+   * Returns `[excluded, satisfying]`. The filter receives `(element, index)`.
    *
    * **Example** (Partitioning with a Result)
    *
@@ -2859,8 +2871,9 @@ export const partition: {
   /**
    * Splits a chunk using a `Filter` into failures and successes.
    *
-   * - Returns `[excluded, satisfying]`.
-   * - The filter receives `(element, index)`.
+   * **Details**
+   *
+   * Returns `[excluded, satisfying]`. The filter receives `(element, index)`.
    *
    * **Example** (Partitioning with a Result)
    *
@@ -2894,6 +2907,8 @@ export const partition: {
  * Separates a chunk of `Result` values into a chunk of failures and a chunk of
  * successes.
  *
+ * **Details**
+ *
  * The returned tuple is `[failures, successes]`, preserving the original order
  * within each side.
  *
@@ -3227,6 +3242,8 @@ export const splitAt: {
  * Splits a `NonEmptyChunk` at `n`, returning a non-empty prefix and the
  * remaining suffix.
  *
+ * **Details**
+ *
  * `n` is floored and normalized to at least `1`. If `n` is greater than or
  * equal to the chunk length, the first result is the original chunk and the
  * second result is empty.
@@ -3258,6 +3275,8 @@ export const splitNonEmptyAt: {
    * Splits a `NonEmptyChunk` at `n`, returning a non-empty prefix and the
    * remaining suffix.
    *
+   * **Details**
+   *
    * `n` is floored and normalized to at least `1`. If `n` is greater than or
    * equal to the chunk length, the first result is the original chunk and the
    * second result is empty.
@@ -3289,6 +3308,8 @@ export const splitNonEmptyAt: {
    * Splits a `NonEmptyChunk` at `n`, returning a non-empty prefix and the
    * remaining suffix.
    *
+   * **Details**
+   *
    * `n` is floored and normalized to at least `1`. If `n` is greater than or
    * equal to the chunk length, the first result is the original chunk and the
    * second result is empty.
@@ -3326,6 +3347,8 @@ export const splitNonEmptyAt: {
 /**
  * Splits a chunk into up to `n` chunks, distributing elements in order.
  *
+ * **Details**
+ *
  * The chunk size is derived from the input length and `n`; the final chunk may
  * contain fewer elements than the others.
  *
@@ -3358,6 +3381,8 @@ export const split: {
   /**
    * Splits a chunk into up to `n` chunks, distributing elements in order.
    *
+   * **Details**
+   *
    * The chunk size is derived from the input length and `n`; the final chunk may
    * contain fewer elements than the others.
    *
@@ -3390,6 +3415,8 @@ export const split: {
   /**
    * Splits a chunk into up to `n` chunks, distributing elements in order.
    *
+   * **Details**
+   *
    * The chunk size is derived from the input length and `n`; the final chunk may
    * contain fewer elements than the others.
    *
@@ -3917,9 +3944,11 @@ export const dedupe = <A>(self: Chunk<A>): Chunk<A> => fromArrayUnsafe(RA.dedupe
 export const dedupeAdjacent = <A>(self: Chunk<A>): Chunk<A> => fromArrayUnsafe(RA.dedupeAdjacent(self))
 
 /**
- * Takes a `Chunk` of pairs and return two corresponding `Chunk`s.
+ * Takes a `Chunk` of pairs and returns two corresponding `Chunk`s.
  *
- * Note: The function is reverse of `zip`.
+ * **Details**
+ *
+ * This function is the reverse of `zip`.
  *
  * **Example** (Unzipping pairs)
  *
@@ -4350,9 +4379,11 @@ export const replace: {
 } = dual(3, <A, B>(self: Chunk<A>, i: number, b: B): O.Option<Chunk<B | A>> => modify(self, i, () => b))
 
 /**
- * Return a Chunk of length n with element i initialized with f(i).
+ * Returns a non-empty `Chunk` of length `n` with element `i` initialized by `f(i)`.
+ *
+ * **Details**
  *
- * **Note**. `n` is normalized to an integer >= 1.
+ * `n` is normalized to an integer greater than or equal to `1`.
  *
  * **Example** (Generating chunks from indices)
  *
@@ -4368,9 +4399,11 @@ export const replace: {
  */
 export const makeBy: {
   /**
-   * Return a Chunk of length n with element i initialized with f(i).
+   * Returns a non-empty `Chunk` of length `n` with element `i` initialized by `f(i)`.
+   *
+   * **Details**
    *
-   * **Note**. `n` is normalized to an integer >= 1.
+   * `n` is normalized to an integer greater than or equal to `1`.
    *
    * **Example** (Generating chunks from indices)
    *
@@ -4386,9 +4419,11 @@ export const makeBy: {
    */
   <A>(f: (i: number) => A): (n: number) => NonEmptyChunk<A>
   /**
-   * Return a Chunk of length n with element i initialized with f(i).
+   * Returns a non-empty `Chunk` of length `n` with element `i` initialized by `f(i)`.
    *
-   * **Note**. `n` is normalized to an integer >= 1.
+   * **Details**
+   *
+   * `n` is normalized to an integer greater than or equal to `1`.
    *
    * **Example** (Generating chunks from indices)
    *
@@ -4409,6 +4444,8 @@ export const makeBy: {
  * Creates a non-empty `Chunk` of consecutive integers from `start` through
  * `end`, inclusive.
  *
+ * **Details**
+ *
  * If `start` is greater than `end`, returns a single-element chunk containing
  * `start`.
  *

package/src/Combiner.ts

@@ -63,17 +63,17 @@
 import type * as Order from "./Order.ts"
 
 /**
- * Represents a strategy for combining two values of the same type `A`.
- *
- * A `Combiner` contains a single `combine` method that takes two values and
+ * Represents a strategy for combining two values of the same type `A`. A
+ * `Combiner` contains a single `combine` method that takes two values and
  * returns a merged result. It does not include an identity/empty value; use
  * `Reducer` when you need one.
  *
- * When to use:
- * - You need to describe how two values of the same type merge.
- * - You want to pass a reusable combining strategy to library functions like
- *   `Struct.makeCombiner` or `Option.makeCombinerFailFast`.
- * - You are building a `Reducer` and need to define the combining step first.
+ * **When to use**
+ *
+ * Use `Combiner` when you need to describe how two values of the same type
+ * merge, pass a reusable combining strategy to library functions like
+ * `Struct.makeCombiner` or `Option.makeCombinerFailFast`, or define the
+ * combining step for a `Reducer`.
  *
  * **Example** (number addition combiner)
  *
@@ -87,7 +87,6 @@ import type * as Order from "./Order.ts"
  * ```
  *
  * @see {@link make} – create a `Combiner` from a function
- *
  * @category models
  * @since 4.0.0
  */
@@ -101,9 +100,12 @@ export interface Combiner<A> {
 /**
  * Creates a `Combiner` from a binary function.
  *
- * When to use:
- * - You have a custom combining operation that is not covered by the built-in
- *   constructors (`min`, `max`, `first`, `last`, `constant`).
+ * **When to use**
+ *
+ * Use this when you have a custom combining operation that is not covered by
+ * the built-in constructors (`min`, `max`, `first`, `last`, `constant`).
+ *
+ * **Details**
  *
  * The returned combiner's `combine` method delegates to the provided function.
  * Any purity, associativity, or mutation behavior comes from that function.
@@ -120,7 +122,6 @@ export interface Combiner<A> {
  * ```
  *
  * @see {@link Combiner} – the interface this creates
- *
  * @category constructors
  * @since 4.0.0
  */
@@ -131,15 +132,16 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
 /**
  * Reverses the argument order of a combiner's `combine` method.
  *
- * When to use:
- * - You need the "right" value to act as the accumulator side.
- * - You want to reverse the natural direction of a non-commutative combiner
- *   (e.g. string concatenation).
+ * **When to use**
+ *
+ * Use this when the "right" value should act as the accumulator side, or when
+ * you want to reverse the natural direction of a non-commutative combiner such
+ * as string concatenation.
  *
- * Behavior:
- * - Returns a new `Combiner` where `combine(self, that)` calls the original
- *   combiner as `combine(that, self)`.
- * - Does not mutate the input combiner.
+ * **Details**
+ *
+ * Returns a new `Combiner` where `combine(self, that)` calls the original
+ * combiner as `combine(that, self)`. The input combiner is not mutated.
  *
  * **Example** (reversing string concatenation)
  *
@@ -153,7 +155,6 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
  * ```
  *
  * @see {@link make}
- *
  * @category combinators
  * @since 4.0.0
  */
@@ -165,14 +166,15 @@ export function flip<A>(combiner: Combiner<A>): Combiner<A> {
  * Creates a `Combiner` that returns the smaller of two values according to
  * the provided `Order`.
  *
- * When to use:
- * - You want to accumulate the minimum value across a collection.
- * - You are building a `Reducer` that tracks the running minimum.
+ * **When to use**
+ *
+ * Use this when you want to accumulate the minimum value across a collection or
+ * build a `Reducer` that tracks the running minimum.
+ *
+ * **Details**
  *
- * Behavior:
- * - Compares using the given `Order`. When values are equal, returns `that`
- *   (the second argument).
- * - Pure – does not mutate either argument.
+ * The combiner compares values using the given `Order`. When values are equal,
+ * it returns `that` (the second argument). It does not mutate either argument.
  *
  * **Example** (minimum of two numbers)
  *
@@ -189,7 +191,6 @@ export function flip<A>(combiner: Combiner<A>): Combiner<A> {
  * ```
  *
  * @see {@link max}
- *
  * @category constructors
  * @since 4.0.0
  */
@@ -201,14 +202,15 @@ export function min<A>(order: Order.Order<A>): Combiner<A> {
  * Creates a `Combiner` that returns the larger of two values according to
  * the provided `Order`.
  *
- * When to use:
- * - You want to accumulate the maximum value across a collection.
- * - You are building a `Reducer` that tracks the running maximum.
+ * **When to use**
+ *
+ * Use this when you want to accumulate the maximum value across a collection or
+ * build a `Reducer` that tracks the running maximum.
+ *
+ * **Details**
  *
- * Behavior:
- * - Compares using the given `Order`. When values are equal, returns `that`
- *   (the second argument).
- * - Pure – does not mutate either argument.
+ * The combiner compares values using the given `Order`. When values are equal,
+ * it returns `that` (the second argument). It does not mutate either argument.
  *
  * **Example** (maximum of two numbers)
  *
@@ -225,7 +227,6 @@ export function min<A>(order: Order.Order<A>): Combiner<A> {
  * ```
  *
  * @see {@link min}
- *
  * @category constructors
  * @since 4.0.0
  */
@@ -236,14 +237,15 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
 /**
  * Creates a `Combiner` that always returns the first (left) argument.
  *
- * When to use:
- * - You want "first write wins" semantics when merging values.
- * - You need a combiner but the combining logic should be a no-op that keeps
- *   the existing value.
+ * **When to use**
+ *
+ * Use this when you want "first write wins" semantics while merging values, or
+ * when the combining logic should keep the existing value.
  *
- * Behavior:
- * - `combine(self, that)` returns `self`, ignoring `that`.
- * - Pure – the second argument is discarded, not mutated.
+ * **Details**
+ *
+ * `combine(self, that)` returns `self` and ignores `that`. The second argument
+ * is discarded, not mutated.
  *
  * **Example** (keeping the first value)
  *
@@ -257,7 +259,6 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
  * ```
  *
  * @see {@link last}
- *
  * @category constructors
  * @since 4.0.0
  */
@@ -268,13 +269,15 @@ export function first<A>(): Combiner<A> {
 /**
  * Creates a `Combiner` that always returns the last (right) argument.
  *
- * When to use:
- * - You want "last write wins" semantics when merging values.
- * - You need a combiner that replaces the accumulator with each new value.
+ * **When to use**
  *
- * Behavior:
- * - `combine(self, that)` returns `that`, ignoring `self`.
- * - Pure – the first argument is discarded, not mutated.
+ * Use this when you want "last write wins" semantics while merging values, or
+ * when each new value should replace the accumulator.
+ *
+ * **Details**
+ *
+ * `combine(self, that)` returns `that` and ignores `self`. The first argument
+ * is discarded, not mutated.
  *
  * **Example** (keeping the last value)
  *
@@ -288,7 +291,6 @@ export function first<A>(): Combiner<A> {
  * ```
  *
  * @see {@link first}
- *
  * @category constructors
  * @since 4.0.0
  */
@@ -300,14 +302,16 @@ export function last<A>(): Combiner<A> {
  * Creates a `Combiner` that ignores both arguments and always returns the
  * given constant value.
  *
- * When to use:
- * - You need a combiner that produces a fixed result regardless of input.
- * - You are providing a combiner to a generic API but the combined value is
- *   predetermined.
+ * **When to use**
  *
- * Behavior:
- * - `combine(self, that)` returns the constant `a`, ignoring both arguments.
- * - Pure – no mutation occurs.
+ * Use this when a combiner should produce a fixed result regardless of input,
+ * or when a generic API needs a combiner but the combined value is
+ * predetermined.
+ *
+ * **Details**
+ *
+ * `combine(self, that)` returns the constant `a` and ignores both arguments.
+ * No mutation occurs.
  *
  * **Example** (always returning zero)
  *
@@ -322,7 +326,6 @@ export function last<A>(): Combiner<A> {
  *
  * @see {@link first}
  * @see {@link last}
- *
  * @category constructors
  * @since 4.0.0
  */
@@ -334,16 +337,18 @@ export function constant<A>(a: A): Combiner<A> {
  * Wraps a `Combiner` so that a separator value is inserted between every
  * pair of combined elements.
  *
- * When to use:
- * - You are building delimited strings (CSV, paths, etc.) by repeated
- *   combination.
- * - You need to inject a fixed separator between accumulated values.
+ * **When to use**
  *
- * Behavior:
- * - `intercalate(middle)(combiner).combine(self, that)` is equivalent to
- *   `combiner.combine(self, combiner.combine(middle, that))`.
- * - Curried: first provide the separator, then the base combiner.
- * - Does not mutate the input combiner; returns a new one.
+ * Use this when you are building delimited strings (CSV, paths, etc.) by
+ * repeated combination, or when you need to inject a fixed separator between
+ * accumulated values.
+ *
+ * **Details**
+ *
+ * `intercalate(middle)(combiner).combine(self, that)` is equivalent to
+ * `combiner.combine(self, combiner.combine(middle, that))`. This function is
+ * curried: first provide the separator, then the base combiner. It returns a
+ * new combiner and does not mutate the input combiner.
  *
  * **Example** (joining strings with a separator)
  *
@@ -357,7 +362,6 @@ export function constant<A>(a: A): Combiner<A> {
  * ```
  *
  * @see {@link make}
- *
  * @category combinators
  * @since 4.0.0
  */