effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/TxHashMap.ts

@@ -1,28 +1,11 @@
 /**
- * The `TxHashMap` module provides a transactional hash map for storing and
- * updating key-value pairs inside Effect transactions. It is useful when
- * multiple fibers need to coordinate shared map state and each read-modify-write
- * sequence must be committed atomically.
+ * Transactional hash maps for storing and updating key-value pairs inside
+ * Effect transactions.
  *
- * A `TxHashMap<K, V>` has the familiar shape of a `HashMap<K, V>`, but every
- * operation returns an `Effect` and participates in transaction semantics
- * through `TxRef`. Use it for concurrent registries, caches, counters, indexes,
- * and other mutable maps whose updates should compose safely with other
- * transactional references.
- *
- * **Common tasks**
- *
- * - Create maps with {@link empty}, {@link fromIterable}, or {@link make}
- * - Read entries with {@link get}, {@link has}, {@link keys}, {@link values}, and {@link entries}
- * - Update entries with {@link set}, {@link modify}, {@link modifyAt}, and {@link remove}
- * - Inspect aggregate state with {@link size}, {@link isEmpty}, and {@link reduce}
- *
- * **Gotchas**
- *
- * - Operations are effectful; run them in `Effect.gen` and wrap multi-step
- *   transactions with `Effect.tx` when the whole sequence must commit together.
- * - Reads that may be absent return `Option`, so handle both `Some` and `None`
- *   instead of assuming a key exists.
+ * A `TxHashMap` stores an immutable `HashMap` in a `TxRef`, so map reads and
+ * writes can commit atomically with other transactional operations. Use it for
+ * shared registries, counters, indexes, and other maps that need safe
+ * read-modify-write sequences alongside related transactional state.
  *
  * @since 2.0.0
  */

package/src/TxHashSet.ts

@@ -1,23 +1,14 @@
 /**
- * The `TxHashSet` module provides a transactional hash set for storing unique
- * values inside Effect transactions. A `TxHashSet<A>` wraps a `HashSet<A>` in a
- * transactional reference, so reads and writes can be composed with other
- * transactional operations and committed atomically.
- *
- * **Common tasks**
- *
- * - Create transactional sets with {@link empty}, {@link make}, or {@link fromIterable}
- * - Mutate an existing set with {@link add}, {@link remove}, and {@link clear}
- * - Query membership and size with {@link has}, {@link size}, and {@link isEmpty}
- * - Derive new sets with {@link map}, {@link filter}, {@link union}, {@link intersection}, and {@link difference}
- * - Fold or collect values with {@link reduce} and {@link toHashSet}
- *
- * **Gotchas**
- *
- * - Mutation operations update the same transactional set; transform operations
- *   return a new `TxHashSet`
- * - Operations are `Effect` values and must be yielded, piped, or run to take effect
- * - Use `Effect.tx` when several operations must observe and commit one atomic transaction
+ * Transactional hash sets for storing unique values inside Effect
+ * transactions.
+ *
+ * A `TxHashSet` keeps an immutable `HashSet` inside a `TxRef`, so membership
+ * checks and updates can commit atomically with other transactional operations.
+ * Use it when several pieces of shared transactional state must change
+ * together, such as adding a value only after checking related state. The
+ * module includes the usual set operations, including adding, removing,
+ * membership checks, set algebra, mapping, filtering, reducing, and conversion
+ * back to `HashSet`.
  *
  * @since 2.0.0
  */

package/src/TxPriorityQueue.ts

@@ -1,33 +1,13 @@
 /**
- * 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.
+ * Transactional priority queues whose state is stored in a `TxRef`. 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.
+ *
+ * Use `TxPriorityQueue` when multiple fibers coordinate through a shared queue
+ * and queue operations need to compose with other transactional state changes.
+ * The retrying `peek` and `take` operations wait transactionally when the queue
+ * is empty, so they can be combined with other transactional reads and writes in
+ * one atomic workflow.
  *
  * @since 4.0.0
  */

package/src/TxPubSub.ts

@@ -1,49 +1,11 @@
 /**
- * The `TxPubSub` module provides a transactional publish/subscribe hub for
- * broadcasting values to scoped subscribers. Each subscriber owns a `TxQueue`,
- * so every value is offered independently to the queues registered at the time
- * of publication.
+ * Broadcasts values to subscribers inside Effect transactions.
  *
- * **Mental model**
- *
- * A `TxPubSub` is a registry of subscriber queues plus a shutdown flag.
- * Publishing reads the current subscribers and offers the value to each queue
- * in one transactional operation. Subscribers only receive values published
- * after they subscribe, and `subscribe` removes the queue when its scope
- * closes.
- *
- * **Common tasks**
- *
- * - Use `bounded` when slow subscribers should apply backpressure to
- *   publishers.
- * - Use `dropping` when new messages may be skipped for full subscribers.
- * - Use `sliding` when full subscribers should keep the newest messages.
- * - Use `unbounded` when subscriber queues should grow without backpressure.
- *
- * **Example** (Broadcasting to a subscriber)
- *
- * ```ts
- * import { Effect, TxPubSub, TxQueue } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const hub = yield* TxPubSub.unbounded<string>()
- *
- *   return yield* Effect.scoped(
- *     Effect.gen(function*() {
- *       const subscriber = yield* TxPubSub.subscribe(hub)
- *       yield* TxPubSub.publish(hub, "updated")
- *       return yield* TxQueue.take(subscriber)
- *     })
- *   )
- * })
- * ```
- *
- * **Gotchas**
- *
- * - `size` reports the maximum pending messages in any subscriber queue, not
- *   the total number of queued copies.
- * - `shutdown` stops future publishes and shuts down subscriber queues that are
- *   registered at shutdown time.
+ * A `TxPubSub<A>` is a transactional publish/subscribe hub. Each subscriber
+ * owns a `TxQueue`, and each published value is offered to the subscriber
+ * queues that are registered at the time of publication. This module includes
+ * bounded, dropping, sliding, and unbounded hubs, publishing helpers, scoped
+ * subscriptions, shutdown operations, and a guard.
  *
  * @since 4.0.0
  */

package/src/TxQueue.ts

@@ -1,52 +1,12 @@
 /**
- * The `TxQueue` module provides queues whose state changes participate in
- * Effect transactions. A `TxQueue<A, E>` stores values of type `A`, exposes
- * write-only {@link TxEnqueue} and read-only {@link TxDequeue} handles, and can
- * complete or fail with causes observed by consumers.
- *
- * **Mental model**
- *
- * - Queue contents and lifecycle state are transactional, so a transaction can
- *   offer, take, inspect, and update other transactional values atomically
- * - {@link take}, {@link takeAll}, {@link takeN}, {@link takeBetween}, and
- *   {@link peek} retry while the queue has no required value available
- * - {@link bounded} queues retry producers when full; {@link dropping}
- *   rejects new values; {@link sliding} removes old values; {@link unbounded}
- *   always accepts while open
- * - {@link interrupt}, {@link fail}, {@link failCause}, {@link end}, and
- *   {@link shutdown} move the queue toward completion and affect later offers
- *   and takes
- *
- * **Common tasks**
- *
- * - Create queues: {@link bounded}, {@link dropping}, {@link sliding},
- *   {@link unbounded}
- * - Produce values: {@link offer}, {@link offerAll}
- * - Consume values: {@link take}, {@link poll}, {@link peek}, {@link takeN},
- *   {@link takeBetween}, {@link takeAll}
- * - Inspect state: {@link size}, {@link isEmpty}, {@link isFull},
- *   {@link isOpen}, {@link isClosing}, {@link isDone}
- * - Finish queues: {@link end}, {@link fail}, {@link failCause},
- *   {@link interrupt}, {@link shutdown}, {@link awaitCompletion}
- *
- * **Gotchas**
- *
- * - {@link take} and {@link peek} are blocking in transactional terms: they
- *   use `Effect.txRetry` until an item is offered or the queue reaches a
- *   terminal state. Use {@link poll} when absence should be immediate.
- * - {@link offer} returns `false` for closing or done queues, and for full
- *   {@link dropping} queues
- * - Closing queues keep serving buffered values; done queues fail blocking
- *   consumers with the stored cause, while {@link poll} returns `Option.none`
- * - `TxQueue` is for coordinating transactional state. Use `Queue` for general
- *   fiber communication outside an atomic transaction.
- *
- * **See also**
- *
- * - {@link TxEnqueue} for write-only queue handles
- * - {@link TxDequeue} for read-only queue handles
- * - {@link TxChunk} and {@link TxRef} for the transactional storage used by
- *   this module
+ * Transactional queues whose state changes participate in Effect transactions.
+ *
+ * A `TxQueue<A, E>` stores values of type `A`, exposes write-only `TxEnqueue`
+ * and read-only `TxDequeue` handles, and can complete, fail, or shut down with
+ * causes observed by consumers. Queue operations can retry transactionally when
+ * they cannot proceed, such as taking from an empty open queue or offering to a
+ * full bounded queue. This makes the queue useful for coordinating producers
+ * and consumers alongside other transactional state changes.
  *
  * @since 4.0.0
  */

package/src/TxReentrantLock.ts

@@ -1,44 +1,12 @@
 /**
- * The `TxReentrantLock` module provides a transactional read/write lock whose
- * ownership is tracked per fiber. Multiple fibers may hold read locks at the
- * same time, while a write lock gives one fiber exclusive access.
- *
- * **Mental model**
- *
- * The lock stores reader counts and an optional writer count in transactional
- * state. A fiber can reacquire locks it already owns, so nested read or write
- * sections are safe as long as each acquisition is matched by a release. A
- * write acquisition waits when another fiber owns a read or write lock, and a
- * read acquisition waits when another fiber owns the write lock.
- *
- * **Common tasks**
- *
- * - Use `withReadLock` to run an effect that may share access with other
- *   readers.
- * - Use `withWriteLock` or `withLock` to run an effect with exclusive access.
- * - Use `readLock` or `writeLock` when lock ownership should be tied to an
- *   existing scope.
- *
- * **Example** (Protecting a read/write workflow)
- *
- * ```ts
- * import { Effect, Ref, TxReentrantLock } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const lock = yield* TxReentrantLock.make()
- *   const state = yield* Ref.make(0)
- *
- *   yield* TxReentrantLock.withWriteLock(lock, Ref.update(state, (n) => n + 1))
- *   return yield* TxReentrantLock.withReadLock(lock, Ref.get(state))
- * })
- * ```
- *
- * **Gotchas**
- *
- * - Manual acquisitions are counted; release the same number of times or use
- *   the scoped and `with*` helpers.
- * - Releasing a lock from a fiber that does not own it leaves the lock
- *   unchanged and returns `0`.
+ * Coordinates shared access inside transactions with read and write locks.
+ *
+ * A `TxReentrantLock` lets many fibers hold read locks at the same time, or one
+ * fiber hold a write lock for exclusive access. Lock ownership is tracked by
+ * fiber, so a fiber that already holds the lock can acquire it again and later
+ * release each acquisition. Attempts that cannot proceed retry transactionally
+ * until the lock becomes available. This module includes manual, scoped, and
+ * wrapper-style operations for read and write locking.
  *
  * @since 4.0.0
  */

package/src/TxRef.ts

@@ -1,63 +1,13 @@
 /**
- * The `TxRef` module provides transactional references for coordinating mutable
- * state with Effect transactions. A `TxRef<A>` stores a current value, but
- * reads and writes inside `Effect.tx` are recorded in a transaction journal and
- * committed together only when the outermost transaction succeeds.
- *
- * **Mental model**
- *
- * - {@link make} creates a reference whose value can participate in
- *   optimistic transactions.
- * - {@link get}, {@link set}, {@link update}, and {@link modify} read and
- *   write the transaction journal when a transaction is active.
- * - At commit time, the transaction checks whether any accessed reference was
- *   changed by another transaction. If so, it retries with a fresh journal.
- * - `Effect.txRetry` suspends the transaction until one of the `TxRef` values
- *   read by the transaction changes.
- *
- * **Common tasks**
- *
- * - Create transactional state with {@link make}.
- * - Read the current value with {@link get}.
- * - Replace or transform the value with {@link set} and {@link update}.
- * - Return a derived result while writing a new value with {@link modify}.
- * - Wrap related reads and writes in one `Effect.tx` boundary so they commit or
- *   roll back as a unit.
- *
- * **Example** (Committing multiple updates atomically)
- *
- * ```ts
- * import { Effect, TxRef } from "effect"
- *
- * const transfer = Effect.gen(function*() {
- *   const checking = yield* TxRef.make(100)
- *   const savings = yield* TxRef.make(0)
- *
- *   yield* Effect.tx(Effect.gen(function*() {
- *     const balance = yield* TxRef.get(checking)
- *     if (balance < 30) {
- *       return yield* Effect.fail("insufficient funds")
- *     }
- *     yield* TxRef.set(checking, balance - 30)
- *     yield* TxRef.update(savings, (amount) => amount + 30)
- *   }))
- *
- *   return {
- *     checking: yield* TxRef.get(checking),
- *     savings: yield* TxRef.get(savings)
- *   }
- * })
- * ```
- *
- * **Gotchas**
- *
- * - Group related operations in the same `Effect.tx` call; separate
- *   transactions can observe and commit intermediate states.
- * - A transaction body can run more than once after a conflict or
- *   `Effect.txRetry`, so keep externally visible effects outside the
- *   transaction body or make them idempotent.
- * - If a transaction fails, its journal is discarded and other fibers continue
- *   to see the last committed values.
+ * Transactional references for coordinating mutable state with Effect
+ * transactions. A `TxRef` stores a current value, but reads and writes inside
+ * `Effect.tx` are recorded in a transaction journal and committed together only
+ * when the outermost transaction succeeds.
+ *
+ * This is the basic building block behind the other transactional collections
+ * in Effect. The module provides effectful and unsafe constructors plus the
+ * core operations for reading, setting, updating, and modifying a transactional
+ * value while returning a separate result.
  *
  * @since 4.0.0
  */

package/src/TxSemaphore.ts

@@ -1,39 +1,11 @@
 /**
- * Coordinate access to limited resources with a semaphore whose permit count
- * participates in Effect transactions. A `TxSemaphore` keeps a fixed capacity
- * and records permit changes in transactional state, so acquiring or releasing
- * permits can commit atomically with related `TxRef` updates.
- *
- * **Mental model**
- *
- * - {@link make} creates a semaphore with a fixed number of permits.
- * - {@link acquire} and {@link acquireN} wait by retrying the transaction when
- *   there are not enough permits available.
- * - {@link tryAcquire} and {@link tryAcquireN} update the permit count only
- *   when enough permits are already available.
- * - {@link release} and {@link releaseN} return permits, and the total cannot
- *   exceed the original capacity.
- * - {@link withPermit} and {@link withPermits} bracket a supplied effect,
- *   while {@link withPermitScoped} holds one permit until the current scope
- *   closes.
- *
- * **Common tasks**
- *
- * - Reserve capacity before committing related transactional state changes.
- * - Protect a pool, queue, or rate-limited section with permit accounting that
- *   composes with `TxRef`.
- * - Inspect the current number of permits with {@link available} and the fixed
- *   total with {@link capacity}.
+ * Coordinates access to limited resources inside transactions.
  *
- * **Gotchas**
- *
- * - Permit operations enter `Effect.tx`; group related transactional
- *   work inside the same boundary when it must commit together.
- * - Requesting more permits than the semaphore capacity with
- *   {@link acquireN} can wait forever because the capacity never grows.
- * - Creating a semaphore with negative permits, acquiring a non-positive number
- *   of permits, or releasing a non-positive number of permits defects.
- * - Extra releases are capped at the fixed capacity.
+ * A `TxSemaphore` has a fixed capacity and stores its available permit count in
+ * a `TxRef`. Acquiring or releasing permits can therefore commit atomically
+ * with other transactional state changes. This module includes operations for
+ * creating semaphores, checking capacity and availability, acquiring or
+ * releasing permits, and running effects while permits are held.
  *
  * @since 4.0.0
  */

package/src/TxSubscriptionRef.ts

@@ -1,39 +1,11 @@
 /**
- * The `TxSubscriptionRef` module provides a transactional reference that can
- * also be observed as a stream of committed values. It combines the read and
- * update behavior of a `TxRef.TxRef` with a subscription channel, so each
- * subscriber first receives the current value and then receives every value
- * published by later updates.
- *
- * **Mental model**
- *
- * - The current value is stored transactionally and can be read with
- *   {@link get}
- * - Mutations such as {@link set}, {@link update}, and {@link modify} commit a
- *   new value and publish that value to active subscribers
- * - {@link changes} creates a scoped transactional queue for one subscriber
- * - {@link changesStream} exposes the same change feed as a `Stream.Stream`
- * - Subscriptions are per subscriber; each subscriber gets its own queue of
- *   committed values
- *
- * **Common tasks**
- *
- * - Create observable transactional state with {@link make}
- * - Read or replace the current value with {@link get} and {@link set}
- * - Derive new values atomically with {@link update} or {@link modify}
- * - Consume changes from transactional code with {@link changes}
- * - Consume changes from stream pipelines with {@link changesStream}
- *
- * **Gotchas**
- *
- * - A subscription starts with the value current at subscription time, not just
- *   future updates
- * - The queue returned by {@link changes} is scoped; leaving the scope removes
- *   the subscriber
- * - Updates are published even when the new value is equal to the previous
- *   value
- * - Subscriber queues are unbounded, so long-lived slow subscribers can retain
- *   pending values until they catch up or their scope closes
+ * Stores transactional state and publishes committed changes.
+ *
+ * A `TxSubscriptionRef<A>` combines a `TxRef<A>` for the current value with a
+ * transactional pub/sub channel for updates. Subscribers first receive the
+ * current value and then every later value that is published by committed
+ * updates. This module includes constructors, reads, writes, update and modify
+ * helpers, transactional-queue subscriptions, stream subscriptions, and a guard.
  *
  * @since 4.0.0
  */

package/src/Types.ts

@@ -1,52 +1,10 @@
 /**
- * Type-level utility types for TypeScript.
- *
- * This module provides generic type aliases used throughout the Effect
- * ecosystem. Everything here is compile-time only — there are no runtime
- * values. Use these types to manipulate object shapes, tagged unions, tuples,
- * and variance markers at the type level.
- *
- * ## Mental model
- *
- * - **Tagged union**: a union of objects each having a discriminating
- *   `_tag: string` field. {@link Tags}, {@link ExtractTag}, and
- *   {@link ExcludeTag} operate on these.
- * - **Reason**: a nested error pattern where an error has a `reason` field
- *   containing a tagged union of sub-errors. {@link ReasonOf},
- *   {@link ReasonTags}, {@link ExtractReason}, and {@link ExcludeReason} work
- *   with this pattern.
- * - **Variance markers**: {@link Covariant}, {@link Contravariant}, and
- *   {@link Invariant} are function-type aliases encoding variance for phantom
- *   type parameters.
- * - **Simplify**: {@link Simplify} flattens intersection types (`A & B`) into
- *   a single object type for cleaner IDE tooltips.
- * - **Concurrency**: {@link Concurrency} is a union type
- *   (`number | "unbounded" | "inherit"`) used across Effect APIs that accept
- *   concurrency options.
- * - **Marker types**: {@link unassigned} and {@link unhandled} are branded
- *   interfaces used internally to represent missing or unhandled type
- *   parameters.
- *
- * ## Common tasks
- *
- * - Flatten an intersection for readability → {@link Simplify}
- * - Check type equality at compile time → {@link Equals} / {@link EqualsWith}
- * - Merge two object types → {@link MergeLeft} / {@link MergeRight}
- * - Work with tagged unions → {@link Tags} / {@link ExtractTag} / {@link ExcludeTag}
- * - Work with nested reason errors → {@link ReasonOf} / {@link ExtractReason}
- * - Create fixed-length tuples → {@link TupleOf} / {@link TupleOfAtLeast}
- * - Strip `readonly` modifiers → {@link Mutable} / {@link DeepMutable}
- * - Encode variance in phantom types → {@link Covariant} / {@link Contravariant} / {@link Invariant}
- * - Check if a type is a union → {@link IsUnion}
- *
- * ## Gotchas
- *
- * - {@link TupleOf} with a non-literal `number` (e.g. `TupleOf<number, string>`)
- *   degrades to `Array<string>`.
- * - {@link NoInfer} uses the `[A][A extends any ? 0 : never]` trick, not the
- *   built-in `NoInfer` from TypeScript 5.4+.
- * - {@link DeepMutable} recurses into `Map`, `Set`, arrays, and objects but
- *   stops at primitives and functions.
+ * Provides compile-time utility types for TypeScript.
+ *
+ * Everything in this module is type-level only; it does not define runtime
+ * values. The types are used throughout Effect to work with tuple lengths,
+ * object shapes, tagged unions, reason-tagged errors, mutability, exactness,
+ * required keys, concurrency settings, and variance markers.
  *
  * @since 4.0.0
  */

package/src/UndefinedOr.ts

@@ -1,59 +1,12 @@
 /**
- * The `UndefinedOr` module works with plain TypeScript values of type
- * `A | undefined` where `undefined` is the only absence marker. It is a small
- * alternative to wrapping values in `Option` when your domain already uses
- * `undefined` to mean "no value".
- *
- * **Mental model**
- *
- * - A defined value is the present branch.
- * - `undefined` is reserved for absence; the payload type `A` should not itself
- *   include `undefined`.
- * - Helpers such as {@link map} and {@link match} keep values unwrapped and use
- *   `undefined` directly instead of allocating tagged values.
- * - The fail-fast combiner and reducer helpers propagate `undefined` when a
- *   required value is missing.
- *
- * **Common tasks**
- *
- * - Transform a present value: {@link map}
- * - Branch on present versus absent: {@link match}
- * - Unwrap at a boundary: {@link getOrThrow}, {@link getOrThrowWith}
- * - Adapt throwing code to an optional result: {@link liftThrowable}
- * - Lift combination and reduction logic: {@link makeReducer},
- *   {@link makeCombinerFailFast}, {@link makeReducerFailFast}
- *
- * **Gotchas**
- *
- * - `A | undefined` cannot distinguish "missing" from "present and
- *   undefined". Use `Option` when that distinction matters.
- * - {@link liftThrowable} discards the thrown value and also returns
- *   `undefined` when the wrapped function throws.
- *
- * **Example** (Parsing optional input)
- *
- * ```ts
- * import { UndefinedOr } from "effect"
- *
- * const parseInteger = UndefinedOr.liftThrowable((input: string) => {
- *   const value = Number.parseInt(input, 10)
- *   if (Number.isNaN(value)) {
- *     throw new Error("not an integer")
- *   }
- *   return value
- * })
- *
- * console.log(UndefinedOr.map(parseInteger("42"), (n) => n + 1))
- * // 43
- *
- * console.log(
- *   UndefinedOr.match(parseInteger("abc"), {
- *     onUndefined: () => "missing",
- *     onDefined: (n) => `parsed ${n}`
- *   })
- * )
- * // "missing"
- * ```
+ * Works with values that may be `undefined`.
+ *
+ * Use this module for plain TypeScript values of type `A | undefined` when
+ * `undefined` is the only absence marker. It is a small alternative to wrapping
+ * values in `Option` when your data already uses `undefined` to mean "no
+ * value". The module includes helpers for mapping defined values, matching both
+ * cases, throwing when a value is missing, adapting throwing functions, and
+ * building reducers or combiners.
  *
  * @since 4.0.0
  */

package/src/Unify.ts

@@ -1,33 +1,12 @@
 /**
- * The `Unify` module defines the type-level protocol Effect uses to collapse
- * unions of protocol-enabled values into their public data types. It is mostly
- * for maintainers of Effect data types and advanced library authors; ordinary
- * application code usually benefits from unification through APIs such as
- * `Effect`, `Option`, `Result`, `Stream`, `Layer`, and `Match`.
- *
- * **Mental model**
- *
- * A type opts in by carrying phantom entries keyed by {@link typeSymbol} and
- * {@link unifySymbol}. {@link Unify} reads those entries, ignores any protocol
- * members listed through {@link ignoreSymbol}, and widens matching union
- * members to the public type each entry returns. The runtime helper
- * {@link unify} is an identity function; it changes only the static type that
- * TypeScript sees.
- *
- * **Common tasks**
- *
- * - Add unification support to a new Effect data type so mixed unions infer as
- *   the public container type instead of an implementation shape.
- * - Normalize the return type of branching APIs, matchers, or builders that can
- *   produce several protocol-enabled values.
- * - Apply unification to a value or curried function result with {@link unify}
- *   while preserving the original runtime behavior.
- *
- * **Gotchas**
- *
- * - Unification is a compile-time protocol, not a runtime conversion hook.
- * - Protocol entries should be specific to the data type they widen; overly
- *   broad entries can make inferred unions less precise.
+ * Defines Effect's type-level unification protocol.
+ *
+ * Unification collapses unions of protocol-enabled values into their public data
+ * types. It is mostly for maintainers of Effect data types and advanced library
+ * authors; application code usually benefits from it through APIs such as
+ * `Effect`, `Option`, `Result`, `Stream`, `Layer`, and `Match`. This module
+ * exports the protocol symbols, the `Unify` type that performs normalization,
+ * and `unify`, an identity function that changes only the inferred type.
  *
  * @since 2.0.0
  */