effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/String.ts

@@ -1,68 +1,10 @@
 /**
- * Operations for working with TypeScript `string` values. Use this module to
- * normalize text, inspect and extract characters, search with `Option` results,
- * split or iterate lines, convert identifier casing, and pass string instances
- * to generic APIs.
- *
- * **Mental model**
- *
- * Strings are plain JavaScript strings. Many operations mirror native string
- * methods while giving them Effect-style names and data-last forms for `pipe`.
- * Operations that may miss, such as {@link at}, {@link charCodeAt},
- * {@link codePointAt}, {@link indexOf}, {@link lastIndexOf}, {@link match}, and
- * {@link search}, return `Option` instead of sentinel values such as `-1`,
- * `undefined`, or `null`.
- *
- * **Common tasks**
- *
- * - Coerce or narrow input: {@link String}, {@link isString}
- * - Build and compare strings: {@link empty}, {@link concat}, {@link Order},
- *   {@link Equivalence}, {@link ReducerConcat}
- * - Change text shape: {@link trim}, {@link trimStart}, {@link trimEnd},
- *   {@link toUpperCase}, {@link toLowerCase}, {@link capitalize},
- *   {@link uncapitalize}
- * - Slice, split, and inspect: {@link slice}, {@link substring},
- *   {@link takeLeft}, {@link takeRight}, {@link split}, {@link length}
- * - Search and match: {@link includes}, {@link startsWith}, {@link endsWith},
- *   {@link indexOf}, {@link lastIndexOf}, {@link match}, {@link matchAll},
- *   {@link search}
- * - Normalize identifiers and text blocks: {@link camelCase},
- *   {@link pascalCase}, {@link snakeCase}, {@link kebabCase},
- *   {@link constantCase}, {@link linesIterator}, {@link linesWithSeparators},
- *   {@link stripMargin}
+ * Works with TypeScript `string` values.
  *
- * **Gotchas**
- *
- * - {@link length} reports JavaScript string length in UTF-16 code units, not
- *   user-perceived characters.
- * - {@link String} is the native JavaScript constructor. `String.String(value)`
- *   returns native string coercion results.
- * - {@link split} always returns a non-empty array; splitting `""` with `""`
- *   returns `[""]`.
- * - {@link replace} and {@link replaceAll} follow native JavaScript behavior.
- *   In particular, `replace` only replaces all matches when given a global
- *   regular expression.
- * - Fixed converters such as {@link snakeToCamel} expect their named input
- *   shape. For mixed free-form input, prefer {@link camelCase},
- *   {@link pascalCase}, {@link snakeCase}, {@link kebabCase}, or
- *   {@link noCase}.
- *
- * **Quickstart**
- *
- * **Example** (Normalizing and searching text)
- *
- * ```ts
- * import { String } from "effect"
- *
- * const slug = String.kebabCase("User profile ID")
- * console.log(slug) // "user-profile-id"
- *
- * const parts = String.split(slug, "-")
- * console.log(parts) // ["user", "profile", "id"]
- *
- * const firstDash = String.indexOf("-")(slug)
- * console.log(firstDash) // Option.some(4)
- * ```
+ * This module exposes common string operations in a pipe-friendly style. The
+ * helpers cover checks, comparison, concatenation, trimming, casing, slicing,
+ * padding, replacement, normalization, safe character access, search helpers
+ * that return `Option`, and joining strings through a reducer.
  *
  * @since 2.0.0
  */

package/src/Struct.ts

@@ -1,75 +1,12 @@
 /**
- * Utilities for creating, transforming, and comparing plain TypeScript objects
- * (structs). Every function produces a new object — inputs are never mutated.
- *
- * ## Mental model
- *
- * - **Struct**: A plain JS object with a fixed set of known keys (e.g.,
- *   `{ name: string; age: number }`). Not a generic key-value record.
- * - **Dual API**: Most functions accept arguments in both data-first
- *   (`Struct.pick(obj, keys)`) and data-last (`pipe(obj, Struct.pick(keys))`)
- *   style.
- * - **Immutability**: All operations return a new object; the original is
- *   never modified.
- * - **Lambda**: A type-level function interface (`~lambda.in` / `~lambda.out`)
- *   used by {@link map}, {@link mapPick}, and {@link mapOmit} so the compiler
- *   can track how value types change.
- * - **Evolver pattern**: {@link evolve}, {@link evolveKeys}, and
- *   {@link evolveEntries} let you selectively transform values, keys, or both
- *   while leaving untouched properties unchanged.
- *
- * ## Common tasks
- *
- * - Access a property in a pipeline → {@link get}
- * - List string keys with proper types → {@link keys}
- * - Subset / remove properties → {@link pick}, {@link omit}
- * - Merge two structs (second wins) → {@link assign}
- * - Rename keys → {@link renameKeys}
- * - Transform selected values → {@link evolve}
- * - Transform selected keys → {@link evolveKeys}
- * - Transform both keys and values → {@link evolveEntries}
- * - Map all values with a typed lambda → {@link map}, {@link mapPick},
- *   {@link mapOmit}
- * - Compare structs → {@link makeEquivalence}, {@link makeOrder}
- * - Combine / reduce structs → {@link makeCombiner}, {@link makeReducer}
- * - Flatten intersection types → {@link Simplify}
- * - Strip `readonly` modifiers → {@link Mutable}
- *
- * ## Gotchas
- *
- * - {@link keys} only returns `string` keys; symbol keys are excluded.
- * - {@link pick} and {@link omit} iterate with `for...in`, which includes
- *   inherited enumerable properties but excludes non-enumerable ones.
- * - {@link assign} spreads with `...`; property order follows standard
- *   JS spread rules.
- * - {@link map}, {@link mapPick}, {@link mapOmit} require a {@link Lambda}
- *   value created with {@link lambda}; a plain function won't type-check.
- *
- * ## Quickstart
- *
- * **Example** (Picking, renaming, and evolving struct properties)
+ * Works with plain TypeScript objects, also called structs.
  *
- * ```ts
- * import { pipe, Struct } from "effect"
- *
- * const user = { firstName: "Alice", lastName: "Smith", age: 30, admin: false }
- *
- * const result = pipe(
- *   user,
- *   Struct.pick(["firstName", "age"]),
- *   Struct.evolve({ age: (n) => n + 1 }),
- *   Struct.renameKeys({ firstName: "name" })
- * )
- *
- * console.log(result) // { name: "Alice", age: 31 }
- * ```
- *
- * ## See also
- *
- * - {@link Equivalence} – building equivalence relations for structs
- * - `Order` – ordering structs by their fields
- * - {@link Combiner} – combining two values of the same type
- * - {@link Reducer} – combining with an initial value
+ * The runtime helpers in this module create new objects instead of mutating
+ * their inputs. They cover common object workflows such as reading properties,
+ * listing typed keys, picking or omitting fields, assigning and renaming keys,
+ * transforming values, deriving comparison helpers, and creating records from a
+ * list of keys. The module also includes type-level helpers for simplifying and
+ * merging object shapes.
  *
  * @since 2.0.0
  */
@@ -1522,7 +1459,8 @@ function buildStruct<
   f: f
 ): any {
   const out: Record<PropertyKey, unknown> = {}
-  for (const k in source) {
+  for (const k of Reflect.ownKeys(source) as Array<keyof S>) {
+    if (!Object.prototype.propertyIsEnumerable.call(source, k)) continue
     const res = f(k, source[k])
     if (res) {
       const [nk, nv] = res

package/src/SubscriptionRef.ts

@@ -1,58 +1,11 @@
 /**
- * The `SubscriptionRef` module combines a fiber-safe mutable reference with a
- * replaying stream of state changes. A `SubscriptionRef<A>` stores the latest
- * value, serializes updates, and publishes each committed value so subscribers
- * can observe state as it evolves.
- *
- * **Mental model**
- *
- * - {@link make} creates the reference and immediately publishes the initial
- *   value.
- * - {@link get} reads the latest value without subscribing.
- * - {@link set}, {@link update}, and {@link modify} change the value under the
- *   reference semaphore and publish the new value.
- * - {@link changes} returns a stream that first emits the current value and
- *   then emits future published values.
- * - The `Some` variants leave the value unchanged and publish nothing when
- *   their `Option` result is empty.
- *
- * **Common tasks**
- *
- * - Create shared state with {@link make}.
- * - Read once with {@link get} or observe over time with {@link changes}.
- * - Replace state with {@link set}, {@link setAndGet}, or {@link getAndSet}.
- * - Transform state with {@link update}, {@link updateAndGet},
- *   {@link getAndUpdate}, or their effectful variants.
- * - Compute a separate result while updating with {@link modify} or
- *   {@link modifyEffect}.
- *
- * **Example** (Reading the current value through changes)
+ * Stores mutable state and publishes changes as a stream.
  *
- * ```ts
- * import { Effect, Stream, SubscriptionRef } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const ref = yield* SubscriptionRef.make(0)
- *
- *   yield* SubscriptionRef.update(ref, (n) => n + 1)
- *
- *   const latest = yield* SubscriptionRef.changes(ref).pipe(
- *     Stream.take(1),
- *     Stream.runCollect
- *   )
- *
- *   return latest
- * })
- * ```
- *
- * **Gotchas**
- *
- * - Every successful set or non-empty update is published, even when the new
- *   value is equal to the old one.
- * - New subscribers receive the current value from the replay buffer before
- *   future updates.
- * - Unsafe helpers bypass the semaphore and should only be used when the caller
- *   already controls access.
+ * A `SubscriptionRef<A>` stores the latest value, publishes the initial value,
+ * and publishes every committed update so subscribers can observe state over
+ * time. Updates are serialized so only one change is applied at a time. This
+ * module includes constructors, current-value reads, the `changes` stream,
+ * writes, updates, partial updates, and effectful update helpers.
  *
  * @since 2.0.0
  */

package/src/Symbol.ts

@@ -4,23 +4,6 @@
  * and must be narrowed before it can be used as a symbol key, identifier, or
  * discriminant.
  *
- * **Mental model**
- *
- * - {@link isSymbol} checks `typeof value === "symbol"`
- * - Symbols created with `globalThis.Symbol()` or `globalThis.Symbol.for(...)`
- *   satisfy the predicate
- * - Boxed symbols such as `Object(globalThis.Symbol())` are objects, so they do
- *   not satisfy the predicate
- *
- * **Example** (Narrowing unknown input)
- *
- * ```ts
- * import { Symbol } from "effect"
- *
- * const describe = (value: unknown) =>
- *   Symbol.isSymbol(value) ? value.description : "not a symbol"
- * ```
- *
  * @since 2.0.0
  */
 

package/src/SynchronizedRef.ts

@@ -1,25 +1,12 @@
 /**
- * The `SynchronizedRef` module provides mutable references whose updates are
- * serialized, including updates that run effects before deciding the next
- * value. A `SynchronizedRef<A>` behaves like a `Ref<A>` for reading and basic
- * updates, but uses an internal semaphore so concurrent modifications observe a
- * consistent current value and apply one at a time.
- *
- * **When to use**
- *
- * Use to coordinate shared state that may be updated by many fibers
- * - Running effectful state transitions that must not overlap
- * - Computing both a return value and a new stored value atomically
- * - Applying partial updates with `Option`, where `None` leaves the value
- *   unchanged
- *
- * **Gotchas**
- *
- * - Effectful update functions run while the semaphore is held, so long-running
- *   effects delay other updates to the same ref
- * - Failed effectful updates do not replace the stored value
- * - `getUnsafe` and `makeUnsafe` bypass the `Effect` API and should be reserved
- *   for low-level or carefully controlled code
+ * Stores mutable state whose updates run one at a time.
+ *
+ * A `SynchronizedRef<A>` behaves like a `Ref<A>` for reading and simple state
+ * storage, but update and modify operations are serialized so each change sees
+ * a consistent current value. This is especially useful when the next value is
+ * computed by an effect, because the effectful transition is still protected
+ * from concurrent updates. This module includes constructors, reads, writes,
+ * updates, partial updates, and effectful update helpers.
  *
  * @since 2.0.0
  */

package/src/Take.ts

@@ -4,30 +4,6 @@
  * emitted values, a failed `Exit`, or a successful `Exit` carrying the
  * completion value.
  *
- * **Mental model**
- *
- * - A value batch represents elements that were pulled successfully
- * - A failed `Exit` represents an ordinary pull failure
- * - A successful `Exit` represents normal completion and carries `Done`
- * - {@link toPull} interprets the stored result as a `Pull.Pull` step
- *
- * **Common tasks**
- *
- * - Store or transfer one pull result as {@link Take}
- * - Turn a stored result back into a pull step with {@link toPull}
- *
- * **Gotchas**
- *
- * - Value batches are `NonEmptyReadonlyArray` values; empty arrays are not
- *   valid `Take` values
- * - Successful `Exit` values do not emit elements; they signal completion
- * - `Take` is a representation, not a queue or stream by itself
- *
- * **See also**
- *
- * - {@link Pull.Pull} for the pull-step effect interpreted by {@link toPull}
- * - {@link Exit.Exit} for the success and failure outcomes stored by `Take`
- *
  * @since 2.0.0
  */
 import type { NonEmptyReadonlyArray } from "./Array.ts"

package/src/Terminal.ts

@@ -1,32 +1,11 @@
 /**
- * The `Terminal` module defines Effect's service for interactive terminal
- * capabilities. Programs can query dimensions, read a line of input, subscribe
- * to low-level key events, and display text without depending directly on Node,
- * the browser, or a test-specific console implementation.
- *
- * **Mental model**
- *
- * `Terminal` sits above raw standard I/O. `Stdio` exposes process streams,
- * while `Terminal` exposes already interpreted terminal operations as an Effect
- * service. Application code depends on the {@link Terminal} service; platform
- * runtimes and tests provide the concrete implementation, often by constructing
- * one with {@link make}.
- *
- * **Common tasks**
- *
- * - Read prompt answers with `readLine` and handle user cancellation through
- *   {@link QuitError}.
- * - Build interactive prompts from `readInput` by consuming {@link UserInput}
- *   values with parsed key metadata and optional raw character input.
- * - Write terminal output through `display` while keeping platform failures in
- *   the Effect error channel.
- *
- * **Gotchas**
- *
- * - `readLine` can fail with {@link QuitError} when the user requests to quit,
- *   commonly via `Ctrl+C`.
- * - `readInput` requires a `Scope` because the returned dequeue represents a
- *   live input subscription.
+ * Service definition for interactive terminal capabilities. Programs can query
+ * terminal dimensions, read a line of input, receive low-level key events, and
+ * display text without depending directly on a specific platform implementation.
+ *
+ * This module defines the `Terminal` service, input event shapes, key metadata,
+ * the `QuitError` used when a user cancels input, a guard for that error, and a
+ * constructor for custom terminal service implementations.
  *
  * @since 4.0.0
  */

package/src/Tracer.ts

@@ -1,41 +1,11 @@
 /**
- * The `Tracer` module defines the low-level tracing model used by Effect to
- * describe and propagate spans. A span records the lifetime of an operation,
- * including its name, parent, attributes, links, annotations, sampling decision,
- * kind, and completion status.
- *
- * **Mental model**
- *
- * - `Tracer` is the backend interface responsible for creating spans
- * - `Span` values represent Effect-managed operations with mutable lifecycle
- *   hooks for ending spans and adding attributes, events, or links
- * - `ExternalSpan` represents trace context imported from another tracing
- *   system so Effect spans can be parented by or linked to external work
- * - `ParentSpan`, `Tracer`, and related context references control propagation,
- *   sampling, and trace-level filtering through the Effect context
- *
- * **Common tasks**
- *
- * - Implement a custom tracing backend with {@link make}
- * - Provide or inspect parent span context with {@link ParentSpan}
- * - Convert external trace identifiers into Effect span values with
- *   {@link externalSpan}
- * - Configure span metadata with {@link SpanOptions}, {@link SpanKind}, and
- *   {@link SpanLink}
- * - Disable propagation or adjust trace filtering with
- *   {@link DisablePropagation}, {@link CurrentTraceLevel}, and
- *   {@link MinimumTraceLevel}
+ * Defines the low-level tracing model used by Effect.
  *
- * **Gotchas**
- *
- * - This module exposes the tracing data model and backend hooks; most
- *   application code should create spans through higher-level Effect APIs such
- *   as `Effect.withSpan`
- * - `ExternalSpan` only carries identity and metadata from another system; it
- *   does not have lifecycle methods like `Span`
- * - Propagation and sampling are context-dependent, so parent selection can be
- *   affected by disabled propagation, root span options, and trace-level
- *   thresholds
+ * A span records the lifetime of an operation, including its name, parent,
+ * attributes, links, annotations, sampling decision, kind, and completion
+ * status. The module also defines the tracer service, parent-span context,
+ * external span support, trace propagation settings, and the default in-memory
+ * span implementation.
  *
  * @since 2.0.0
  */

package/src/Trie.ts

@@ -1,54 +1,11 @@
 /**
- * Immutable string-keyed maps optimized for prefix lookup.
+ * Stores string-keyed values in an immutable prefix tree.
  *
- * A `Trie<Value>` stores values under `string` keys, similar to a `HashMap`
- * whose key type is fixed to `string`. That restriction lets the data
- * structure organize keys by their shared prefixes, which is useful for
- * autocomplete, route tables, dictionaries, command lookup, and any workflow
- * that needs to ask "which entries start with this string?".
- *
- * **Mental model**
- *
- * - Exact-key lookup uses {@link get}, {@link has}, or {@link getUnsafe}.
- * - Prefix lookup uses {@link keysWithPrefix}, {@link valuesWithPrefix},
- *   {@link entriesWithPrefix}, {@link toEntriesWithPrefix}, or
- *   {@link longestPrefixOf}.
- * - Iteration yields entries in key order, not insertion order.
- * - Lookup work is proportional to the key or prefix length rather than the
- *   total number of entries.
- *
- * **Common tasks**
- *
- * - Create tries with {@link empty}, {@link make}, or {@link fromIterable}.
- * - Read all keys, values, or entries with {@link keys}, {@link values},
- *   {@link entries}, and {@link toEntries}.
- * - Transform values with {@link map}, {@link filter}, {@link filterMap},
- *   {@link compact}, {@link forEach}, and {@link reduce}.
- *
- * **Gotchas**
- *
- * - Keys must be strings. Use `HashMap` when keys need structural equality or
- *   are not naturally represented as strings.
- * - {@link get} returns an `Option`; {@link getUnsafe} throws when the key is
- *   absent.
- * - Sorted iteration is convenient for presentation, but it also means
- *   insertion order is not preserved.
- *
- * **Example** (Finding entries by prefix)
- *
- * ```ts
- * import { Trie } from "effect"
- * import * as assert from "node:assert"
- *
- * const commands = Trie.make(
- *   ["commit", "Record changes"],
- *   ["checkout", "Switch branches"],
- *   ["clone", "Copy a repository"]
- * )
- *
- * const matches = Trie.toEntriesWithPrefix(commands, "ch")
- * assert.deepStrictEqual(matches, [["checkout", "Switch branches"]])
- * ```
+ * A `Trie<Value>` is similar to a map whose keys are strings, but it is built
+ * for looking up keys by prefix. It is useful for autocomplete, route tables,
+ * dictionaries, and command lookup. Updates return new tries, and the module
+ * includes exact lookup, prefix lookup, longest-prefix lookup, iteration,
+ * mapping, filtering, reducing, and traversal helpers.
  *
  * @since 2.0.0
  */

package/src/Tuple.ts

@@ -1,70 +1,12 @@
 /**
- * Utilities for creating, accessing, transforming, and comparing fixed-length
- * arrays (tuples). Every function produces a new tuple — inputs are never
- * mutated.
- *
- * ## Mental model
- *
- * - **Tuple**: A fixed-length readonly array where each position can have a
- *   different type (e.g., `readonly [string, number, boolean]`).
- * - **Index-based access**: Elements are accessed by numeric index, and the
- *   type system tracks the type at each position.
- * - **Dual API**: Most functions accept arguments in both data-first
- *   (`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 `Struct`) used by
- *   {@link map}, {@link mapPick}, and {@link mapOmit} so the compiler can
- *   track how element types change.
- *
- * ## Common tasks
- *
- * - Create a tuple → {@link make}
- * - Access an element by index → {@link get}
- * - Select / remove elements by index → {@link pick}, {@link omit}
- * - Append elements → {@link appendElement}, {@link appendElements}
- * - Transform selected elements → {@link evolve}
- * - Swap element positions → {@link renameIndices}
- * - Map all elements with a typed lambda → {@link map}, {@link mapPick},
- *   {@link mapOmit}
- * - Compare tuples → {@link makeEquivalence}, {@link makeOrder}
- * - Combine / reduce tuples → {@link makeCombiner}, {@link makeReducer}
- * - Check tuple length at runtime → `isTupleOf`, `isTupleOfAtLeast`
- *
- * ## Gotchas
- *
- * - {@link pick} and {@link omit} use numeric indices, not string keys.
- * - {@link renameIndices} takes an array of stringified source indices
- *   (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.
- * - `isTupleOf` and `isTupleOfAtLeast` only check length, not
- *   element types.
- *
- * ## Quickstart
- *
- * **Example** (Creating and transforming a tuple)
- *
- * ```ts
- * import { pipe, Tuple } from "effect"
- *
- * const point = Tuple.make(10, 20, "red")
- *
- * const result = pipe(
- *   point,
- *   Tuple.evolve([
- *     (x) => x * 2,
- *     (y) => y * 2
- *   ])
- * )
- *
- * console.log(result) // [20, 40, "red"]
- * ```
- *
- * ## See also
- *
- * - `Struct` – similar utilities for objects with named keys
- * - {@link Array} – operations on variable-length arrays
+ * Works with fixed-length arrays, also called tuples.
+ *
+ * The runtime helpers in this module create new tuples instead of mutating
+ * their inputs, and the types preserve element positions where possible. The
+ * helpers cover tuple construction, indexed access, selecting or removing
+ * positions, appending values, transforming elements, renaming indices, mapping
+ * typed positions, and deriving comparison or combination helpers for tuple
+ * shapes.
  *
  * @since 2.0.0
  */

package/src/TxChunk.ts

@@ -1,44 +1,12 @@
 /**
- * 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
+ * Stores a `Chunk` inside transactional state.
+ *
+ * A `TxChunk<A>` keeps its current `Chunk<A>` in a `TxRef`, so reads and
+ * updates can be committed atomically with other transactional operations. This
+ * module offers a transactional version of common chunk workflows, including
+ * creating collections, reading or replacing the current chunk, adding or
+ * removing values, checking size, slicing, mapping, filtering, and combining
+ * chunks.
  *
  * @since 4.0.0
  */

package/src/TxDeferred.ts

@@ -7,24 +7,6 @@
  * 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
  */