effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Tuple.ts

@@ -13,7 +13,7 @@
  *   (`Tuple.get(t, 0)`) and data-last (`pipe(t, Tuple.get(0))`) style.
  * - **Immutability**: All operations return a new tuple; the original is
  *   never modified.
- * - **Lambda**: A type-level function interface (from {@link Struct}) used by
+ * - **Lambda**: A type-level function interface (from `Struct`) used by
  *   {@link map}, {@link mapPick}, and {@link mapOmit} so the compiler can
  *   track how element types change.
  *
@@ -29,8 +29,7 @@
  *   {@link mapOmit}
  * - Compare tuples → {@link makeEquivalence}, {@link makeOrder}
  * - Combine / reduce tuples → {@link makeCombiner}, {@link makeReducer}
- * - Check tuple length at runtime → {@link isTupleOf},
- *   {@link isTupleOfAtLeast}
+ * - Check tuple length at runtime → `isTupleOf`, `isTupleOfAtLeast`
  *
  * ## Gotchas
  *
@@ -39,7 +38,7 @@
  *   (e.g., `["2", "1", "0"]`), not arbitrary names.
  * - {@link map}, {@link mapPick}, {@link mapOmit} require a Lambda value
  *   created with `Struct.lambda`; a plain function won't type-check.
- * - {@link isTupleOf} and {@link isTupleOfAtLeast} only check length, not
+ * - `isTupleOf` and `isTupleOfAtLeast` only check length, not
  *   element types.
  *
  * ## Quickstart
@@ -64,7 +63,7 @@
  *
  * ## See also
  *
- * - {@link Struct} – similar utilities for objects with named keys
+ * - `Struct` – similar utilities for objects with named keys
  * - {@link Array} – operations on variable-length arrays
  *
  * @since 2.0.0
@@ -81,7 +80,7 @@ import type { Apply, Lambda } from "./Struct.ts"
  *
  * **When to use**
  *
- * Use this instead of `[a, b, c] as const` when you want a properly typed tuple
+ * Use when you use this instead of `[a, b, c] as const` when you want a properly typed tuple
  * without a manual cast.
  *
  * **Details**
@@ -112,12 +111,11 @@ type Indices<T extends ReadonlyArray<unknown>> = Exclude<Partial<T>["length"], T
  *
  * **When to use**
  *
- * Use this in a pipeline when you need to extract a single element.
+ * Use when you use this in a pipeline when you need to extract a single element.
  *
  * **Details**
  *
- * The index is constrained to valid tuple positions at the type level, and the
- * input tuple is not mutated.
+ * The index is constrained to valid tuple positions at the type level.
  *
  * **Example** (Extracting an element by index)
  *
@@ -139,12 +137,11 @@ export const get: {
    *
    * **When to use**
    *
-   * Use this in a pipeline when you need to extract a single element.
+   * Use when you use this in a pipeline when you need to extract a single element.
    *
    * **Details**
    *
-   * The index is constrained to valid tuple positions at the type level, and the
-   * input tuple is not mutated.
+   * The index is constrained to valid tuple positions at the type level.
    *
    * **Example** (Extracting an element by index)
    *
@@ -166,12 +163,11 @@ export const get: {
    *
    * **When to use**
    *
-   * Use this in a pipeline when you need to extract a single element.
+   * Use when you use this in a pipeline when you need to extract a single element.
    *
    * **Details**
    *
-   * The index is constrained to valid tuple positions at the type level, and the
-   * input tuple is not mutated.
+   * The index is constrained to valid tuple positions at the type level.
    *
    * **Example** (Extracting an element by index)
    *
@@ -211,12 +207,11 @@ type PickTuple<T extends ReadonlyArray<unknown>, K> = _BuildTuple<T, K>
  *
  * **When to use**
  *
- * Use this to select a subset of elements from a tuple by position.
+ * Use to select a subset of elements from a tuple by position.
  *
  * **Details**
  *
- * The result order matches the order of the provided indices. The input tuple is
- * not mutated; a fresh tuple is returned.
+ * The result order matches the order of the provided indices.
  *
  * **Example** (Selecting elements by index)
  *
@@ -238,12 +233,11 @@ export const pick: {
    *
    * **When to use**
    *
-   * Use this to select a subset of elements from a tuple by position.
+   * Use to select a subset of elements from a tuple by position.
    *
    * **Details**
    *
-   * The result order matches the order of the provided indices. The input tuple is
-   * not mutated; a fresh tuple is returned.
+   * The result order matches the order of the provided indices.
    *
    * **Example** (Selecting elements by index)
    *
@@ -265,12 +259,11 @@ export const pick: {
    *
    * **When to use**
    *
-   * Use this to select a subset of elements from a tuple by position.
+   * Use to select a subset of elements from a tuple by position.
    *
    * **Details**
    *
-   * The result order matches the order of the provided indices. The input tuple is
-   * not mutated; a fresh tuple is returned.
+   * The result order matches the order of the provided indices.
    *
    * **Example** (Selecting elements by index)
    *
@@ -304,12 +297,11 @@ type OmitTuple<T extends ReadonlyArray<unknown>, K> = _BuildTuple<T, Exclude<Ind
  *
  * **When to use**
  *
- * Use this to drop elements from a tuple by position.
+ * Use to drop elements from a tuple by position.
  *
  * **Details**
  *
- * Elements not at the specified indices are kept in their original order. The
- * input tuple is not mutated; a fresh tuple is returned.
+ * Elements not at the specified indices are kept in their original order.
  *
  * **Example** (Removing elements by index)
  *
@@ -330,12 +322,11 @@ export const omit: {
    *
    * **When to use**
    *
-   * Use this to drop elements from a tuple by position.
+   * Use to drop elements from a tuple by position.
    *
    * **Details**
    *
-   * Elements not at the specified indices are kept in their original order. The
-   * input tuple is not mutated; a fresh tuple is returned.
+   * Elements not at the specified indices are kept in their original order.
    *
    * **Example** (Removing elements by index)
    *
@@ -356,12 +347,11 @@ export const omit: {
    *
    * **When to use**
    *
-   * Use this to drop elements from a tuple by position.
+   * Use to drop elements from a tuple by position.
    *
    * **Details**
    *
-   * Elements not at the specified indices are kept in their original order. The
-   * input tuple is not mutated; a fresh tuple is returned.
+   * Elements not at the specified indices are kept in their original order.
    *
    * **Example** (Removing elements by index)
    *
@@ -391,10 +381,13 @@ export const omit: {
 /**
  * Appends a single element to the end of a tuple.
  *
+ * **When to use**
+ *
+ * Use to add one element to the end of a tuple while preserving tuple types.
+ *
  * **Details**
  *
- * The result type is `[...T, E]`, preserving all existing element types. The
- * input tuple is not mutated; a fresh tuple is returned.
+ * The result type is `[...T, E]`, preserving all existing element types.
  *
  * **Example** (Appending an element)
  *
@@ -413,10 +406,13 @@ export const appendElement: {
   /**
    * Appends a single element to the end of a tuple.
    *
+   * **When to use**
+   *
+   * Use to add one element to the end of a tuple while preserving tuple types.
+   *
    * **Details**
    *
-   * The result type is `[...T, E]`, preserving all existing element types. The
-   * input tuple is not mutated; a fresh tuple is returned.
+   * The result type is `[...T, E]`, preserving all existing element types.
    *
    * **Example** (Appending an element)
    *
@@ -435,10 +431,13 @@ export const appendElement: {
   /**
    * Appends a single element to the end of a tuple.
    *
+   * **When to use**
+   *
+   * Use to add one element to the end of a tuple while preserving tuple types.
+   *
    * **Details**
    *
-   * The result type is `[...T, E]`, preserving all existing element types. The
-   * input tuple is not mutated; a fresh tuple is returned.
+   * The result type is `[...T, E]`, preserving all existing element types.
    *
    * **Example** (Appending an element)
    *
@@ -459,6 +458,10 @@ export const appendElement: {
 /**
  * Concatenates two tuples into a single tuple.
  *
+ * **When to use**
+ *
+ * Use to append all elements from one tuple to another tuple.
+ *
  * **Details**
  *
  * The result type is `[...T1, ...T2]`, preserving all element types from both
@@ -481,6 +484,10 @@ export const appendElements: {
   /**
    * Concatenates two tuples into a single tuple.
    *
+   * **When to use**
+   *
+   * Use to append all elements from one tuple to another tuple.
+   *
    * **Details**
    *
    * The result type is `[...T1, ...T2]`, preserving all element types from both
@@ -503,6 +510,10 @@ export const appendElements: {
   /**
    * Concatenates two tuples into a single tuple.
    *
+   * **When to use**
+   *
+   * Use to append all elements from one tuple to another tuple.
+   *
    * **Details**
    *
    * The result type is `[...T1, ...T2]`, preserving all element types from both
@@ -541,12 +552,12 @@ type Evolved<T, E> = { [I in keyof T]: I extends keyof E ? (E[I] extends (...a:
  *
  * **When to use**
  *
- * Use this when you want to update the first N elements while keeping the rest.
+ * Use when you want to update the first N elements while keeping the rest.
  *
  * **Details**
  *
  * Each transform function receives the current value and can return a different
- * type. The input tuple is not mutated; a fresh tuple is returned.
+ * type.
  *
  * **Example** (Transforming selected elements)
  *
@@ -576,12 +587,12 @@ export const evolve: {
    *
    * **When to use**
    *
-   * Use this when you want to update the first N elements while keeping the rest.
+   * Use when you want to update the first N elements while keeping the rest.
    *
    * **Details**
    *
    * Each transform function receives the current value and can return a different
-   * type. The input tuple is not mutated; a fresh tuple is returned.
+   * type.
    *
    * **Example** (Transforming selected elements)
    *
@@ -611,12 +622,12 @@ export const evolve: {
    *
    * **When to use**
    *
-   * Use this when you want to update the first N elements while keeping the rest.
+   * Use when you want to update the first N elements while keeping the rest.
    *
    * **Details**
    *
    * Each transform function receives the current value and can return a different
-   * type. The input tuple is not mutated; a fresh tuple is returned.
+   * type.
    *
    * **Example** (Transforming selected elements)
    *
@@ -647,13 +658,17 @@ export const evolve: {
 )
 
 /**
- * Rearranges elements of a tuple by providing an array of stringified source
+ * Renames tuple indices by providing an array of stringified source
  * indices. Each position in the array specifies which index to read from
  * (e.g., `["2", "1", "0"]` reverses a 3-element tuple).
  *
+ * **When to use**
+ *
+ * Use to reorder tuple elements while preserving index-specific types.
+ *
  * **Details**
  *
- * The input tuple is not mutated; a fresh tuple is returned.
+ * The mapping returns a tuple in the requested index order.
  *
  * **Gotchas**
  *
@@ -677,13 +692,17 @@ export const evolve: {
  */
 export const renameIndices: {
   /**
-   * Rearranges elements of a tuple by providing an array of stringified source
+   * Renames tuple indices by providing an array of stringified source
    * indices. Each position in the array specifies which index to read from
    * (e.g., `["2", "1", "0"]` reverses a 3-element tuple).
    *
+   * **When to use**
+   *
+   * Use to reorder tuple elements while preserving index-specific types.
+   *
    * **Details**
    *
-   * The input tuple is not mutated; a fresh tuple is returned.
+   * The mapping returns a tuple in the requested index order.
    *
    * **Gotchas**
    *
@@ -707,13 +726,17 @@ export const renameIndices: {
    */
   <const T extends ReadonlyArray<unknown>, const M extends { readonly [I in keyof T]?: `${keyof T & string}` }>(mapping: M): (self: T) => { [I in keyof T]: I extends keyof M ? M[I] extends keyof T ? T[M[I]] : T[I] : T[I] }
   /**
-   * Rearranges elements of a tuple by providing an array of stringified source
+   * Renames tuple indices by providing an array of stringified source
    * indices. Each position in the array specifies which index to read from
    * (e.g., `["2", "1", "0"]` reverses a 3-element tuple).
    *
+   * **When to use**
+   *
+   * Use to reorder tuple elements while preserving index-specific types.
+   *
    * **Details**
    *
-   * The input tuple is not mutated; a fresh tuple is returned.
+   * The mapping returns a tuple in the requested index order.
    *
    * **Gotchas**
    *
@@ -751,12 +774,11 @@ export const renameIndices: {
  *
  * **When to use**
  *
- * Use this when you want to apply the same transformation to every element.
+ * Use when you want to apply the same transformation to every element.
  *
  * **Details**
  *
- * The lambda lets the compiler track the output type for each element. The
- * input tuple is not mutated; a fresh tuple is returned.
+ * The lambda lets the compiler track the output type for each element.
  *
  * **Gotchas**
  *
@@ -790,12 +812,11 @@ export const map: {
    *
    * **When to use**
    *
-   * Use this when you want to apply the same transformation to every element.
+   * Use when you want to apply the same transformation to every element.
    *
    * **Details**
    *
-   * The lambda lets the compiler track the output type for each element. The
-   * input tuple is not mutated; a fresh tuple is returned.
+   * The lambda lets the compiler track the output type for each element.
    *
    * **Gotchas**
    *
@@ -831,12 +852,11 @@ export const map: {
    *
    * **When to use**
    *
-   * Use this when you want to apply the same transformation to every element.
+   * Use when you want to apply the same transformation to every element.
    *
    * **Details**
    *
-   * The lambda lets the compiler track the output type for each element. The
-   * input tuple is not mutated; a fresh tuple is returned.
+   * The lambda lets the compiler track the output type for each element.
    *
    * **Gotchas**
    *
@@ -878,13 +898,9 @@ export const map: {
  *
  * **When to use**
  *
- * Use this when you want to apply the same transformation to a subset of
+ * Use when you want to apply the same transformation to a subset of
  * positions.
  *
- * **Details**
- *
- * The input tuple is not mutated; a fresh tuple is returned.
- *
  * **Example** (Wrapping only selected elements in arrays)
  *
  * ```ts
@@ -915,13 +931,9 @@ export const mapPick: {
    *
    * **When to use**
    *
-   * Use this when you want to apply the same transformation to a subset of
+   * Use when you want to apply the same transformation to a subset of
    * positions.
    *
-   * **Details**
-   *
-   * The input tuple is not mutated; a fresh tuple is returned.
-   *
    * **Example** (Wrapping only selected elements in arrays)
    *
    * ```ts
@@ -954,13 +966,9 @@ export const mapPick: {
    *
    * **When to use**
    *
-   * Use this when you want to apply the same transformation to a subset of
+   * Use when you want to apply the same transformation to a subset of
    * positions.
    *
-   * **Details**
-   *
-   * The input tuple is not mutated; a fresh tuple is returned.
-   *
    * **Example** (Wrapping only selected elements in arrays)
    *
    * ```ts
@@ -1003,13 +1011,9 @@ export const mapPick: {
  *
  * **When to use**
  *
- * Use this when most elements should be transformed but a few should be
+ * Use when most elements should be transformed but a few should be
  * preserved.
  *
- * **Details**
- *
- * The input tuple is not mutated; a fresh tuple is returned.
- *
  * **Example** (Wrapping all elements except one in arrays)
  *
  * ```ts
@@ -1040,13 +1044,9 @@ export const mapOmit: {
    *
    * **When to use**
    *
-   * Use this when most elements should be transformed but a few should be
+   * Use when most elements should be transformed but a few should be
    * preserved.
    *
-   * **Details**
-   *
-   * The input tuple is not mutated; a fresh tuple is returned.
-   *
    * **Example** (Wrapping all elements except one in arrays)
    *
    * ```ts
@@ -1079,13 +1079,9 @@ export const mapOmit: {
    *
    * **When to use**
    *
-   * Use this when most elements should be transformed but a few should be
+   * Use when most elements should be transformed but a few should be
    * preserved.
    *
-   * **Details**
-   *
-   * The input tuple is not mutated; a fresh tuple is returned.
-   *
    * **Example** (Wrapping all elements except one in arrays)
    *
    * ```ts
@@ -1129,7 +1125,7 @@ export const mapOmit: {
  *
  * **When to use**
  *
- * Use this when you need to compare tuples element-by-element.
+ * Use when you need to compare tuples element-by-element.
  *
  * **Details**
  *
@@ -1162,7 +1158,7 @@ export const makeEquivalence = Equivalence.Tuple
  *
  * **When to use**
  *
- * Use this to sort or compare tuples lexicographically by element position.
+ * Use to sort or compare tuples lexicographically by element position.
  *
  * **Details**
  *
@@ -1187,12 +1183,12 @@ export const makeOrder = order.Tuple
 
 export {
   /**
-   * Checks if an array has exactly `N` elements, narrowing the type to a
+   * Checks whether an array has exactly `N` elements, narrowing the type to a
    * fixed-length tuple.
    *
    * **When to use**
    *
-   * Use this to guard against unexpected array lengths at runtime.
+   * Use to guard against unexpected array lengths at runtime.
    *
    * **Details**
    *
@@ -1215,18 +1211,18 @@ export {
    * }
    * ```
    *
-   * @see {@link isTupleOfAtLeast} – check for a minimum length
+   * @see `isTupleOfAtLeast` – check for a minimum length
    * @category guards
    * @since 3.3.0
    */
   isTupleOf,
   /**
-   * Checks if an array has at least `N` elements, narrowing the type to a
+   * Checks whether an array has at least `N` elements, narrowing the type to a
    * tuple with a minimum length.
    *
    * **When to use**
    *
-   * Use this to guard that an array has at least the expected number of
+   * Use to guard that an array has at least the expected number of
    * elements.
    *
    * **Details**
@@ -1250,7 +1246,7 @@ export {
    * }
    * ```
    *
-   * @see {@link isTupleOf} – check for an exact length
+   * @see `isTupleOf` – check for an exact length
    * @category guards
    * @since 3.3.0
    */
@@ -1264,13 +1260,9 @@ export {
  *
  * **When to use**
  *
- * Use this when you need to merge two tuples of the same shape, such as summing
+ * Use when you need to merge two tuples of the same shape, such as summing
  * counters or concatenating strings.
  *
- * **Details**
- *
- * The inputs are not mutated; a fresh tuple is returned.
- *
  * **Example** (Combining tuple elements)
  *
  * ```ts
@@ -1309,11 +1301,7 @@ export function makeCombiner<A extends ReadonlyArray<unknown>>(
  *
  * **When to use**
  *
- * Use this to fold a collection of tuples into a single summary tuple.
- *
- * **Details**
- *
- * The inputs are not mutated; a fresh tuple is returned.
+ * Use to fold a collection of tuples into a single summary tuple.
  *
  * **Example** (Reducing a collection of tuples)
  *

package/src/TxChunk.ts

@@ -1,11 +1,44 @@
 /**
- * TxChunk is a transactional chunk data structure that provides Software Transactional Memory (STM)
- * semantics for chunk operations. It uses a `TxRef<Chunk<A>>` internally to ensure all operations
- * are performed atomically within transactions.
- *
- * Accessed values are tracked by the transaction in order to detect conflicts and to track changes.
- * A transaction will retry whenever a conflict is detected or whenever the transaction explicitly
- * calls `Effect.txRetry` and any of the accessed TxChunk values change.
+ * The `TxChunk` module provides a transactional collection backed by an
+ * immutable {@link Chunk}. A `TxChunk<A>` stores the current chunk in a
+ * {@link TxRef}, so reads and updates are tracked by Effect transactions and
+ * committed atomically.
+ *
+ * **Mental model**
+ *
+ * - A `TxChunk` is mutable at the reference level, but every stored value is a
+ *   persistent `Chunk`
+ * - Single operations such as {@link append}, {@link drop}, or {@link get} run
+ *   as transactions on their own
+ * - Wrap several operations in `Effect.tx` when they must observe one
+ *   consistent snapshot and commit or retry together
+ * - If a transaction reads a `TxChunk` and another transaction changes it
+ *   before commit, the transaction retries instead of publishing a stale write
+ *
+ * **Common tasks**
+ *
+ * - Create collections: {@link empty}, {@link make}, {@link fromIterable}
+ * - Replace or transform contents: {@link set}, {@link update}, {@link modify}
+ * - Add values: {@link append}, {@link prepend}, {@link appendAll},
+ *   {@link prependAll}
+ * - Keep or remove ranges: {@link take}, {@link drop}, {@link slice},
+ *   {@link filter}
+ * - Inspect contents: {@link get}, {@link size}, {@link isEmpty},
+ *   {@link isNonEmpty}
+ *
+ * **Gotchas**
+ *
+ * - `get` returns the current immutable `Chunk`, not a live mutable view
+ * - Operations such as {@link append}, {@link drop}, and {@link filter} update
+ *   the stored chunk; they do not return a new `TxChunk`
+ * - Use `TxQueue` instead when producers should wait, drop, or slide based on
+ *   queue capacity
+ *
+ * **See also**
+ *
+ * - {@link TxRef} for the lower-level transactional reference used internally
+ * - {@link Chunk} for immutable chunk operations
+ * - `TxQueue` for transactional producer/consumer queues
  *
  * @since 4.0.0
  */
@@ -751,7 +784,7 @@ export const size = <A>(self: TxChunk<A>): Effect.Effect<number> =>
   modify(self, (current) => [Chunk.size(current), current])
 
 /**
- * Checks if the `TxChunk` is empty.
+ * Checks whether the `TxChunk` is empty.
  *
  * **Example** (Checking for an empty chunk)
  *
@@ -778,7 +811,7 @@ export const isEmpty = <A>(self: TxChunk<A>): Effect.Effect<boolean> =>
   modify(self, (current) => [Chunk.isEmpty(current), current])
 
 /**
- * Checks if the `TxChunk` is non-empty.
+ * Checks whether the `TxChunk` is non-empty.
  *
  * **Example** (Checking for a non-empty chunk)
  *