effect 4.0.0-beta.70 → 4.0.0-beta.71

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,7 +111,7 @@ 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**
  *
@@ -139,7 +138,7 @@ 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**
    *
@@ -166,7 +165,7 @@ 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**
    *
@@ -211,7 +210,7 @@ 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**
  *
@@ -238,7 +237,7 @@ 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**
    *
@@ -265,7 +264,7 @@ 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**
    *
@@ -304,7 +303,7 @@ 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**
  *
@@ -330,7 +329,7 @@ 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**
    *
@@ -356,7 +355,7 @@ 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**
    *
@@ -391,6 +390,10 @@ 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
@@ -413,6 +416,10 @@ 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
@@ -435,6 +442,10 @@ 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
@@ -459,6 +470,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 +496,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 +522,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,7 +564,7 @@ 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**
  *
@@ -576,7 +599,7 @@ 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**
    *
@@ -611,7 +634,7 @@ 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**
    *
@@ -651,6 +674,10 @@ export const evolve: {
  * 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.
@@ -681,6 +708,10 @@ export const renameIndices: {
    * 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.
@@ -711,6 +742,10 @@ export const renameIndices: {
    * 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.
@@ -751,7 +786,7 @@ 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**
  *
@@ -790,7 +825,7 @@ 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**
    *
@@ -831,7 +866,7 @@ 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**
    *
@@ -878,7 +913,7 @@ 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**
@@ -915,7 +950,7 @@ 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**
@@ -954,7 +989,7 @@ 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**
@@ -1003,7 +1038,7 @@ 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**
@@ -1040,7 +1075,7 @@ 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**
@@ -1079,7 +1114,7 @@ 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**
@@ -1129,7 +1164,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 +1197,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**
  *
@@ -1192,7 +1227,7 @@ export {
    *
    * **When to use**
    *
-   * Use this to guard against unexpected array lengths at runtime.
+   * Use to guard against unexpected array lengths at runtime.
    *
    * **Details**
    *
@@ -1215,7 +1250,7 @@ export {
    * }
    * ```
    *
-   * @see {@link isTupleOfAtLeast} – check for a minimum length
+   * @see `isTupleOfAtLeast` – check for a minimum length
    * @category guards
    * @since 3.3.0
    */
@@ -1226,7 +1261,7 @@ export {
    *
    * **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 +1285,7 @@ export {
    * }
    * ```
    *
-   * @see {@link isTupleOf} – check for an exact length
+   * @see `isTupleOf` – check for an exact length
    * @category guards
    * @since 3.3.0
    */
@@ -1264,7 +1299,7 @@ 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**
@@ -1309,7 +1344,7 @@ export function makeCombiner<A extends ReadonlyArray<unknown>>(
  *
  * **When to use**
  *
- * Use this to fold a collection of tuples into a single summary tuple.
+ * Use to fold a collection of tuples into a single summary tuple.
  *
  * **Details**
  *

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
  */

package/src/TxDeferred.ts

@@ -1,6 +1,29 @@
 /**
- * A transactional deferred value — a write-once cell that can be read within transactions.
- * Readers retry until a value is set; once set, the value is immutable.
+ * Transactional deferred values for coordinating Effect transactions.
+ *
+ * A `TxDeferred<A, E>` is a write-once cell whose completion is a
+ * `Result<A, E>` stored in transactional state. Readers can wait for the value
+ * from inside a transaction: while the cell is empty the transaction retries,
+ * and when another transaction completes the deferred the waiting transaction
+ * can resume with either the success value or the typed failure.
+ *
+ * **Mental model**
+ *
+ * `TxDeferred` is the transaction-aware counterpart to a regular deferred
+ * value. Completion is single-assignment, reads participate in transaction
+ * retry semantics, and all observers see the same committed result once the
+ * deferred has been completed.
+ *
+ * **Common tasks**
+ *
+ * Create an empty deferred with {@link make}, wait for completion with
+ * `await`, inspect the current state with {@link poll}, and complete it with
+ * {@link done}, {@link succeed}, or {@link fail}.
+ *
+ * **Gotchas**
+ *
+ * Only the first completion wins. Later completion attempts return `false`
+ * instead of replacing the stored result.
  *
  * @since 4.0.0
  */
@@ -25,6 +48,11 @@ const TypeId = "~effect/transactions/TxDeferred"
  * Readers block (retry the transaction) until a value is committed, and writers
  * succeed only on the first call; subsequent writes return `false`.
  *
+ * **When to use**
+ *
+ * Use to coordinate transaction-local readers and one-time completion with a
+ * success or failure result.
+ *
  * **Example** (Completing a transactional deferred)
  *
  * ```ts
@@ -79,6 +107,10 @@ const makeTxDeferred = <A, E>(ref: TxRef.TxRef<Option<Result<A, E>>>): TxDeferre
 /**
  * Creates a new empty `TxDeferred`.
  *
+ * **When to use**
+ *
+ * Use to create a transactional deferred that can be completed exactly once.
+ *
  * **Example** (Creating a transactional deferred)
  *
  * ```ts
@@ -133,6 +165,13 @@ export {
    * Reads the deferred value. Retries the transaction if the deferred has not
    * been completed yet.
    *
+   * **When to use**
+   *
+   * Use to read the success value of a `TxDeferred` while retrying until the
+   * deferred is completed.
+   *
+   * @see {@link poll} for inspecting the current completion state without retrying the transaction
+   *
    * @category getters
    * @since 4.0.0
    */
@@ -143,6 +182,10 @@ export {
  * Reads the current state of the deferred without retrying. Returns `None` if
  * not yet completed.
  *
+ * **When to use**
+ *
+ * Use to inspect a `TxDeferred` without retrying when it is not completed yet.
+ *
  * **Example** (Polling a deferred)
  *
  * ```ts
@@ -168,6 +211,10 @@ export const poll = <A, E>(self: TxDeferred<A, E>): Effect.Effect<Option<Result<
  * Completes the deferred with a `Result`. Returns `true` if this was the first
  * completion, `false` if already completed.
  *
+ * **When to use**
+ *
+ * Use to complete a `TxDeferred` with an already computed `Result`.
+ *
  * **Example** (Completing with a result)
  *
  * ```ts
@@ -190,6 +237,10 @@ export const done: {
    * Completes the deferred with a `Result`. Returns `true` if this was the first
    * completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with an already computed `Result`.
+   *
    * **Example** (Completing with a result)
    *
    * ```ts
@@ -212,6 +263,10 @@ export const done: {
    * Completes the deferred with a `Result`. Returns `true` if this was the first
    * completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with an already computed `Result`.
+   *
    * **Example** (Completing with a result)
    *
    * ```ts
@@ -245,6 +300,10 @@ export const done: {
  * Completes the deferred with a success value. Returns `true` if this was the
  * first completion, `false` if already completed.
  *
+ * **When to use**
+ *
+ * Use to complete a `TxDeferred` with a successful value.
+ *
  * **Example** (Completing with a success value)
  *
  * ```ts
@@ -267,6 +326,10 @@ export const succeed: {
    * Completes the deferred with a success value. Returns `true` if this was the
    * first completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with a successful value.
+   *
    * **Example** (Completing with a success value)
    *
    * ```ts
@@ -289,6 +352,10 @@ export const succeed: {
    * Completes the deferred with a success value. Returns `true` if this was the
    * first completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with a successful value.
+   *
    * **Example** (Completing with a success value)
    *
    * ```ts
@@ -316,6 +383,10 @@ export const succeed: {
  * Completes the deferred with a failure. Returns `true` if this was the first
  * completion, `false` if already completed.
  *
+ * **When to use**
+ *
+ * Use to complete a `TxDeferred` with a typed failure value.
+ *
  * **Example** (Completing with a failure)
  *
  * ```ts
@@ -338,6 +409,10 @@ export const fail: {
    * Completes the deferred with a failure. Returns `true` if this was the first
    * completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with a typed failure value.
+   *
    * **Example** (Completing with a failure)
    *
    * ```ts
@@ -360,6 +435,10 @@ export const fail: {
    * Completes the deferred with a failure. Returns `true` if this was the first
    * completion, `false` if already completed.
    *
+   * **When to use**
+   *
+   * Use to complete a `TxDeferred` with a typed failure value.
+   *
    * **Example** (Completing with a failure)
    *
    * ```ts
@@ -386,6 +465,10 @@ export const fail: {
 /**
  * Determines if the provided value is a `TxDeferred`.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a transactional deferred.
+ *
  * **Example** (Checking transactional deferreds)
  *
  * ```ts

package/src/TxPriorityQueue.ts

@@ -1,6 +1,33 @@
 /**
- * A transactional priority queue. Elements are dequeued in order determined by the
- * provided `Order` instance. All operations participate in the STM transaction system.
+ * The `TxPriorityQueue` module provides a mutable priority queue whose state is
+ * stored in a transactional reference. Elements are kept in the order defined by
+ * the `Order` supplied at construction time, and dequeue operations return the
+ * first element according to that ordering.
+ *
+ * A `TxPriorityQueue<A>` is useful when multiple fibers coordinate through a
+ * shared queue and the queue operation needs to compose with other
+ * transactional state changes. Every operation returns an `Effect`; group
+ * several queue operations with `Effect.tx` when the whole sequence must commit
+ * or retry as one transaction.
+ *
+ * **Common tasks**
+ *
+ * - Create queues with {@link empty}, {@link fromIterable}, or {@link make}
+ * - Insert values with {@link offer} and {@link offerAll}
+ * - Read priority order with {@link peek}, {@link peekOption}, and
+ *   {@link toArray}
+ * - Remove values with {@link take}, {@link takeOption}, {@link takeAll}, and
+ *   {@link takeUpTo}
+ * - Keep or remove subsets with {@link retainIf} and {@link removeIf}
+ *
+ * **Gotchas**
+ *
+ * - `take` and `peek` retry when the queue is empty; use `takeOption` or
+ *   `peekOption` when empty queues should be represented as `Option.none`.
+ * - `Order.Number` is ascending, so lower numbers are dequeued first. Provide a
+ *   reversed order when larger values should have higher priority.
+ * - The queue preserves all values with equal priority; equal values are not
+ *   merged or deduplicated.
  *
  * @since 4.0.0
  */