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

package/src/Boolean.ts

@@ -1,57 +1,10 @@
 /**
- * Operations for working with TypeScript `boolean` values in expression-oriented
- * code. Use this module to narrow unknown input, branch without inline
- * conditionals, combine boolean flags with named logical operators, and reduce
- * boolean collections.
- *
- * **Mental model**
- *
- * Boolean values are plain JavaScript booleans. The module adds a small
- * vocabulary around them: {@link match} for choosing between two lazy branches,
- * logical combinators such as {@link and}, {@link or}, {@link xor}, and
- * {@link implies}, and collection helpers such as {@link every} and
- * {@link some}. The exported {@link Order} sorts `false` before `true`, and
- * {@link Equivalence} compares booleans with strict equality.
- *
- * **Common tasks**
- *
- * - Coerce or narrow input: {@link Boolean}, {@link isBoolean}
- * - Branch on a boolean: {@link match}
- * - Invert and combine flags: {@link not}, {@link and}, {@link or},
- *   {@link nand}, {@link nor}, {@link xor}, {@link eqv}, {@link implies}
- * - Check boolean collections: {@link every}, {@link some}
- * - Pass boolean instances to generic APIs: {@link Order}, {@link Equivalence},
- *   {@link ReducerAnd}, {@link ReducerOr}
+ * Works with TypeScript `boolean` values.
  *
- * **Gotchas**
- *
- * - {@link Boolean} is the native JavaScript constructor. It follows truthiness
- *   rules, so values such as `"false"` and `[]` coerce to `true`.
- * - {@link every} returns `true` for an empty iterable, matching logical AND.
- *   {@link some} returns `false` for an empty iterable, matching logical OR.
- * - {@link ReducerAnd} and {@link ReducerOr} are for APIs that consume a
- *   `Reducer`; use {@link every} or {@link some} when you want direct iterable
- *   checks.
- *
- * **Quickstart**
- *
- * **Example** (Combining validation flags)
- *
- * ```ts
- * import { Boolean } from "effect"
- *
- * const hasName = true
- * const hasEmail = false
- *
- * const isComplete = Boolean.and(hasName, hasEmail)
- * console.log(isComplete) // false
- *
- * const message = Boolean.match(isComplete, {
- *   onFalse: () => "missing fields",
- *   onTrue: () => "ready"
- * })
- * console.log(message) // "missing fields"
- * ```
+ * This module exposes the native `Boolean` constructor together with helpers
+ * for checking values, choosing between lazy branches, combining booleans with
+ * logical operations, checking collections with `every` or `some`, ordering
+ * booleans, and reducing boolean values.
  *
  * @since 2.0.0
  */

package/src/Brand.ts

@@ -5,50 +5,6 @@
  * information lives in the type system unless you choose a validating
  * constructor.
  *
- * **Mental model**
- *
- * - {@link Branded} is an existing value type plus a phantom {@link Brand}
- *   marker
- * - {@link nominal} creates constructors for purely nominal brands and
- *   performs no runtime validation
- * - {@link make} and {@link check} create constructors that validate input
- *   before returning the branded value
- * - A {@link Constructor} can throw, return `Option`, return `Result`, or act
- *   as a type guard through its `is` method
- * - {@link all} combines multiple brand constructors with the same base type so
- *   a value can carry several brands
- *
- * **Common tasks**
- *
- * - Distinguish identifiers with the same primitive representation, such as
- *   `UserId` and `OrderId`
- * - Constrain primitive values after validation, such as positive numbers,
- *   non-empty strings, or normalized tokens
- * - Keep public APIs precise without wrapping values in runtime classes
- *
- * **Quickstart**
- *
- * **Example** (Validated identifier)
- *
- * ```ts
- * import { Brand } from "effect"
- *
- * type UserId = Brand.Branded<number, "UserId">
- *
- * const UserId = Brand.make<UserId>(
- *   (n) => Number.isInteger(n) && n > 0 || "Expected a positive integer"
- * )
- *
- * const id = UserId(1)
- * ```
- *
- * **Gotchas**
- *
- * - Brands do not change the runtime value; `id` above is still a number at
- *   runtime
- * - {@link nominal} accepts every value of the base type, so use
- *   {@link make} or {@link check} at trust boundaries that need validation
- *
  * @since 2.0.0
  */
 import * as Arr from "./Array.ts"

package/src/Cache.ts

@@ -1,49 +1,10 @@
 /**
- * The `Cache` module provides an effectful, mutable key-value cache for values
- * computed by lookup effects. A `Cache<Key, A, E, R>` stores lookup exits for
- * keys, shares concurrent misses for the same key, and manages entry lifetime
- * with capacity limits and optional time-to-live policies.
- *
- * **Mental model**
- *
- * - {@link make} and {@link makeWith} create a cache from a lookup function and
- *   a maximum capacity
- * - {@link get} returns a cached value when present, or runs the lookup for a
- *   missing or expired key
- * - Concurrent misses for the same key share one pending lookup and all await
- *   the same result
- * - Successes and failures are both cached as `Exit` values until their entry
- *   expires or is replaced
- * - Entries can live forever, use a fixed TTL, or use a dynamic TTL based on
- *   the lookup `Exit`
- * - Capacity uses access order: reads move entries to the back and overflow
- *   removes the oldest entries
- *
- * **Common tasks**
- *
- * - Create a cache: {@link make}, {@link makeWith}
- * - Read values: {@link get}, {@link getOption}, {@link getSuccess}
- * - Seed or overwrite values: {@link set}
- * - Refresh values: {@link refresh}
- * - Remove entries: {@link invalidate}, {@link invalidateWhen}, {@link invalidateAll}
- * - Inspect contents: {@link has}, {@link size}, {@link keys}, {@link values}, {@link entries}
+ * Caches values loaded by an Effect lookup function.
  *
- * **Gotchas**
- *
- * - {@link getOption} does not run the lookup, but it awaits pending entries
- *   and fails when the existing entry is a failure
- * - {@link getSuccess} returns `Option.none` for missing, expired, pending, or
- *   failed entries
- * - {@link size} may include expired entries until they are observed and removed
- * - {@link values} and {@link entries} include only successfully resolved,
- *   non-expired entries
- * - Use `Data` or another `Equal`-compatible key type when keys should compare
- *   structurally
- *
- * **See also**
- *
- * - {@link Duration} for configuring fixed or dynamic time-to-live values
- * - {@link Effect} for the lookup effects used to compute cached values
+ * A cache stores successful and failed lookup results, shares an in-progress
+ * lookup when multiple callers request the same missing key, and limits entries
+ * by capacity and optional time-to-live rules. This module includes helpers for
+ * reading, setting, refreshing, invalidating, and inspecting cache contents.
  *
  * @since 4.0.0
  */

package/src/Cause.ts

@@ -1,77 +1,11 @@
 /**
- * Structured representation of how an Effect can fail.
- *
- * A `Cause<E>` holds a flat array of `Reason` values, where each reason is one of:
- *
- * - **Fail** — a typed, expected error `E` (created by `Effect.fail`)
- * - **Die** — an untyped defect (`unknown`) from `Effect.die` or uncaught throws
- * - **Interrupt** — a fiber interruption, optionally carrying the interrupting fiber's ID
- *
- * ## Mental model
- *
- * - A `Cause` is always flat: concurrent and sequential failures are stored together
- *   in `cause.reasons` (a `ReadonlyArray<Reason<E>>`).
- * - Each `Reason` carries an `annotations` map with tracing metadata (stack frames, spans).
- * - An empty `reasons` array means the computation succeeded or the cause was empty
- *   ({@link empty}).
- * - `Cause` implements `Equal`, so two causes with identical reasons compare as equal.
- *
- * ## Common tasks
- *
- * | Intent | API |
- * |--------|-----|
- * | Create a cause | {@link fail}, {@link die}, {@link interrupt}, {@link fromReasons} |
- * | Test for reason types | {@link hasFails}, {@link hasDies}, {@link hasInterrupts} |
- * | Extract the first error/defect | {@link findError}, {@link findDefect}, {@link findFail}, {@link findDie} |
- * | Iterate over reasons manually | `cause.reasons.filter(Cause.isFailReason)` |
- * | Combine two causes | {@link combine} |
- * | Transform errors | {@link map} |
- * | Collapse to a single thrown value | {@link squash} |
- * | Render for logging | {@link pretty}, {@link prettyErrors} |
- * | Attach/read tracing metadata | {@link annotate}, {@link annotations}, {@link reasonAnnotations} |
- *
- * ## Gotchas
- *
- * - `findError`/`findDefect` return `Result.fail` (not `Option.none`) when no match is
- *   found. Use {@link findErrorOption} if you need an `Option`.
- * - `squash` picks the first `Fail` error, then the first `Die` defect, then falls back
- *   to a generic "interrupted" / "empty" error. It is lossy — use `prettyErrors` or
- *   iterate `reasons` directly when you need all failures.
- * - The module also exports several built-in error classes (`NoSuchElementError`,
- *   `TimeoutError`, `IllegalArgumentError`, `ExceededCapacityError`, `UnknownError`)
- *   and the `Done` completion signal. These all implement `YieldableError` and can be
- *   yielded directly inside `Effect.gen`.
- *
- * **Example** (inspecting a concurrent failure)
+ * Records the full reason an `Effect` failed.
  *
- * ```ts
- * import { Cause, Effect } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const cause = yield* Effect.sandbox(
- *     Effect.all([
- *       Effect.fail("err1"),
- *       Effect.die("defect"),
- *       Effect.fail("err2")
- *     ], { concurrency: "unbounded" })
- *   ).pipe(Effect.flip)
- *
- *   const errors = cause.reasons
- *     .filter(Cause.isFailReason)
- *     .map((r) => r.error)
- *     .sort()
- *
- *   const defects = cause.reasons
- *     .filter(Cause.isDieReason)
- *     .map((r) => String(r.defect))
- *     .sort()
- *
- *   console.log(errors.join(",")) // "err1,err2"
- *   console.log(defects.join(",")) // "defect"
- * })
- *
- * Effect.runPromise(program)
- * ```
+ * A `Cause<E>` can contain typed failures, unexpected defects, interruptions,
+ * and annotations. Keeping those details together lets code inspect or format
+ * failures without first collapsing them to a single error value. This module
+ * includes the `Cause` and `Reason` data types, helpers for building and
+ * checking causes, and small error types used by several Effect APIs.
  *
  * @since 2.0.0
  */

package/src/Channel.ts

@@ -1,72 +1,11 @@
 /**
- * The `Channel` module provides the low-level stream processing primitive used
- * to build Effect streams, sinks, and stream operators.
- *
- * A `Channel<OutElem, OutErr, OutDone, InElem, InErr, InDone, Env>` describes a
- * scoped process that can read elements from an upstream input, emit elements
- * downstream, fail with a typed error, or complete with a typed done value.
- * Most application code works with higher-level stream APIs; channels are for
- * implementing reusable streaming primitives, adapting pull-based sources, and
- * controlling how input, output, errors, final values, and resources compose.
- *
- * **Mental model**
- *
- * - `OutElem`, `OutErr`, and `OutDone` describe the values, failures, and final
- *   value produced by the channel.
- * - `InElem`, `InErr`, and `InDone` describe the upstream protocol consumed by
- *   the channel when it is piped after another channel.
- * - `Env` is the Effect environment required while the channel is interpreted.
- * - Constructors such as {@link fromArray}, {@link fromIterable},
- *   {@link fromEffect}, {@link succeed}, and {@link fail} create sources.
- * - Combinators such as {@link map}, {@link mapEffect}, {@link flatMap}, and
- *   {@link pipeTo} transform, sequence, and connect channels.
- * - Execution functions such as {@link runCollect} and {@link runDrain}
- *   interpret channels that no longer require upstream input.
- *
- * **Common tasks**
- *
- * - Build finite sources from values, arrays, iterables, queues, pub/sub
- *   subscriptions, effects, or pulls.
- * - Transform output elements with pure or effectful functions.
- * - Connect channels with {@link pipeTo} when one channel's output protocol
- *   should become another channel's input protocol.
- * - Sequence dependent channels with {@link flatMap}, or concatenate channels
- *   with {@link concat}.
- * - Manage channel-scoped resources with {@link acquireRelease} and
- *   {@link ensuring}.
- * - Bridge to lower-level pull loops with {@link toPull} and {@link fromPull}.
- *
- * **Example** (Collecting transformed output)
+ * Provides low-level building blocks for streaming data through Effect.
  *
- * ```ts
- * import { Channel, Effect } from "effect"
- *
- * const program = Channel.fromArray([1, 2, 3]).pipe(
- *   Channel.map((n) => n * 2),
- *   Channel.runCollect
- * )
- *
- * Effect.runPromise(program).then(console.log)
- * ```
- *
- * **Gotchas**
- *
- * - A channel's done value is distinct from its emitted elements; use
- *   done-focused APIs when the final value matters.
- * - `pipeTo` connects the output side of the left channel to the input side of
- *   the right channel, so type errors usually mean those protocols do not line
- *   up.
- * - Resource finalizers run when the channel scope closes, not when a channel
- *   value is merely constructed.
- * - Prefer stream and sink APIs unless you are implementing lower-level
- *   streaming behavior.
- *
- * **See also**
- *
- * - {@link Channel} for the type parameters and variance of channel values.
- * - {@link pipeTo} for wiring one channel into another.
- * - {@link runCollect}, {@link runDrain}, and {@link runDone} for common
- *   execution modes.
+ * A `Channel` can read input elements, write output elements, fail with a typed
+ * error, and finish with a typed result while managing resources safely.
+ * Streams and sinks are built on channels, so most application code uses those
+ * higher-level modules instead. This module is useful when implementing stream
+ * operators or specialized streaming workflows.
  *
  * @since 2.0.0
  */

package/src/ChannelSchema.ts

@@ -1,45 +1,9 @@
 /**
- * The `ChannelSchema` module provides helpers for applying `Schema` encoding
- * and decoding at `Channel` boundaries. It is useful when a channel should
- * expose typed values to application code while communicating with an upstream
- * or downstream component through an encoded representation such as JSON-ready
- * data, wire protocol values, or any other schema-defined format.
- *
- * **Mental model**
- *
- * - A channel schema adapter is a streaming boundary: chunks flow through a
- *   `Channel`, and each non-empty chunk is validated and transformed with a
- *   `Schema`
- * - `encode` turns typed schema values into their encoded representation before
- *   they leave a typed part of a pipeline
- * - `decode` turns encoded input into typed schema values before application
- *   code consumes them
- * - `duplex` wraps a bidirectional channel so callers work with typed input and
- *   output while the wrapped channel continues to operate on encoded chunks
- * - Schema failures are surfaced through the channel error type as
- *   `SchemaError`, and schema services are reflected in the channel
- *   requirements
- *
- * **Common tasks**
- *
- * - Encode typed channel input before sending it to an encoded transport:
- *   {@link encode}
- * - Decode encoded channel output before handling it as domain data:
- *   {@link decode}
- * - Use unknown encoded boundaries when static encoded types are intentionally
- *   erased: {@link encodeUnknown} and {@link decodeUnknown}
- * - Wrap a bidirectional encoded channel with typed input and output schemas:
- *   {@link duplex} or {@link duplexUnknown}
- *
- * **Gotchas**
- *
- * - These helpers operate on `NonEmptyReadonlyArray` chunks, so schemas are
- *   applied to non-empty batches rather than individual scalar values
- * - Encoding and decoding can require services from the schema; those
- *   requirements become part of the resulting channel type
- * - `duplex` encodes values flowing into the wrapped channel and decodes values
- *   emitted by it, so choose `inputSchema` and `outputSchema` from the
- *   perspective of the typed caller
+ * Schema adapters for `Channel` boundaries. The helpers encode typed channel
+ * chunks before they cross an encoded boundary, decode encoded chunks before
+ * application code receives them, and wrap bidirectional channels so callers
+ * work with schema-typed input and output while the inner channel uses encoded
+ * values.
  *
  * @since 4.0.0
  */

package/src/Chunk.ts

@@ -1,72 +1,11 @@
 /**
- * The `Chunk` module provides an immutable, high-performance sequence data structure
- * optimized for functional programming patterns. A `Chunk` is a persistent data structure
- * that supports efficient append, prepend, and concatenation operations.
+ * Stores many values in an immutable ordered collection.
  *
- * ## What is a Chunk?
- *
- * A `Chunk<A>` is an immutable sequence of elements of type `A` that provides:
- * - **O(1) append and prepend operations**
- * - **Efficient concatenation** through tree-like structure
- * - **Memory efficiency** with structural sharing
- * - **Rich API** with functional programming operations
- * - **Type safety** with full TypeScript integration
- *
- * ## Key Features
- *
- * - **Immutable**: All operations return new chunks without modifying the original
- * - **Efficient**: Optimized data structure with logarithmic complexity for most operations
- * - **Functional**: Rich set of transformation and combination operators
- * - **Lazy evaluation**: Many operations are deferred until needed
- * - **Interoperable**: Easy conversion to/from arrays and other collections
- *
- * ## Performance Characteristics
- *
- * - **Append/Prepend**: O(1) amortized
- * - **Random Access**: O(log n)
- * - **Concatenation**: O(log min(m, n))
- * - **Iteration**: O(n)
- * - **Memory**: Structural sharing minimizes allocation
- *
- * **Example** (Creating and combining chunks)
- *
- * ```ts
- * import { Chunk } from "effect"
- *
- * // Creating chunks
- * const chunk1 = Chunk.fromIterable([1, 2, 3])
- * const chunk2 = Chunk.fromIterable([4, 5, 6])
- * const empty = Chunk.empty<number>()
- *
- * // Combining chunks
- * const combined = Chunk.appendAll(chunk1, chunk2)
- * console.log(Chunk.toReadonlyArray(combined)) // [1, 2, 3, 4, 5, 6]
- * ```
- *
- * **Example** (Transforming chunks)
- *
- * ```ts
- * import { Chunk } from "effect"
- *
- * // Functional transformations
- * const numbers = Chunk.range(1, 5) // [1, 2, 3, 4, 5]
- * const doubled = Chunk.map(numbers, (n) => n * 2) // [2, 4, 6, 8, 10]
- * const evens = Chunk.filter(doubled, (n) => n % 4 === 0) // [4, 8]
- * const sum = Chunk.reduce(evens, 0, (acc, n) => acc + n) // 12
- * ```
- *
- * **Example** (Processing chunks with Effect)
- *
- * ```ts
- * import { Chunk, Effect } from "effect"
- *
- * // Working with Effects
- * const processChunk = Effect.fnUntraced(function*(chunk: Chunk.Chunk<number>) {
- *   const mapped = Chunk.map(chunk, (n) => n * 2)
- *   const filtered = Chunk.filter(mapped, (n) => n > 5)
- *   return Chunk.toReadonlyArray(filtered)
- * })
- * ```
+ * A `Chunk<A>` is useful when you need to build or transform collections
+ * without changing the original collection. It is designed for efficient
+ * append, prepend, and concatenation. This module includes helpers for
+ * creating, reading, slicing, mapping, filtering, sorting, zipping, combining,
+ * and converting chunks to and from arrays and iterables.
  *
  * @since 2.0.0
  */

package/src/Clock.ts

@@ -1,60 +1,8 @@
 /**
- * The `Clock` module provides functionality for time-based operations in Effect applications.
- * It offers precise time measurements, scheduling capabilities, and controlled time management
- * for testing scenarios.
- *
- * The Clock service is a core component of the Effect runtime, providing:
- * - Current time access in milliseconds and nanoseconds
- * - Sleep operations for delaying execution
- * - Time-based scheduling primitives
- * - Testable time control through `TestClock`
- *
- * ## Key Features
- *
- * - **Precise timing**: Access to both millisecond and nanosecond precision
- * - **Sleep operations**: Non-blocking sleep with proper interruption handling
- * - **Service integration**: Seamless integration with Effect's dependency injection
- * - **Testable**: Mock time control for deterministic testing
- * - **Resource-safe**: Automatic cleanup of time-based resources
- *
- * **Example** (Measuring elapsed time)
- *
- * ```ts
- * import { Clock, Effect } from "effect"
- *
- * // Get current time in milliseconds
- * const getCurrentTime = Clock.currentTimeMillis
- *
- * // Sleep for 1 second
- * const sleep1Second = Effect.sleep("1 seconds")
- *
- * // Measure execution time
- * const measureTime = Effect.gen(function*() {
- *   const start = yield* Clock.currentTimeMillis
- *   yield* Effect.sleep("100 millis")
- *   const end = yield* Clock.currentTimeMillis
- *   return end - start
- * })
- * ```
- *
- * **Example** (Using the Clock service)
- *
- * ```ts
- * import { Clock, Effect } from "effect"
- *
- * // Using Clock service directly
- * const program = Effect.gen(function*() {
- *   const clock = yield* Clock.Clock
- *   const currentTime = yield* clock.currentTimeMillis
- *   console.log(`Current time: ${currentTime}`)
- *
- *   // Sleep for 500ms
- *   yield* Effect.sleep("500 millis")
- *
- *   const afterSleep = yield* clock.currentTimeMillis
- *   console.log(`After sleep: ${afterSleep}`)
- * })
- * ```
+ * Service and helpers for reading time and sleeping inside Effect programs.
+ * The active `Clock` provides current time in milliseconds or nanoseconds and a
+ * `sleep` operation for delaying work. Because time is accessed through a
+ * service, tests can replace the clock with a controlled implementation.
  *
  * @since 2.0.0
  */

package/src/Combiner.ts

@@ -1,62 +1,11 @@
 /**
- * A module for combining two values of the same type into one.
+ * Defines reusable rules for merging two values of the same type.
  *
- * A `Combiner<A>` wraps a single binary function `(self: A, that: A) => A`.
- * It describes *how* two values merge but carries no initial/empty value
- * (for that, see `Reducer` which extends `Combiner` with an
- * `initialValue`).
- *
- * ## Mental model
- *
- * - **Combiner** – an object with a `combine(self, that)` method that returns
- *   a value of the same type.
- * - **Argument order** – `self` is the "left" / accumulator side, `that` is
- *   the "right" / incoming side.
- * - **No identity element** – unlike a monoid, a `Combiner` does not require
- *   a neutral element. Use `Reducer` when you need one.
- * - **Purity** – all combiners produced by this module are pure; they never
- *   mutate their arguments.
- * - **Composability** – combiners can be lifted into `Option`, `Struct`,
- *   `Tuple`, and other container types via helpers in those modules.
- *
- * ## Common tasks
- *
- * - Create a combiner from any binary function → {@link make}
- * - Swap argument order → {@link flip}
- * - Pick the smaller / larger of two values → {@link min} / {@link max}
- * - Always keep the first or last value → {@link first} / {@link last}
- * - Ignore both values and return a fixed result → {@link constant}
- * - Insert a separator between combined values → {@link intercalate}
- *
- * ## Gotchas
- *
- * - `min` and `max` require an `Order<A>`, not a raw comparator. Import from
- *   e.g. `Number.Order` or `String.Order`.
- * - `intercalate` is curried: call it with the separator first, then pass the
- *   base combiner.
- * - A `Reducer` (which adds `initialValue`) is also a valid `Combiner` — you
- *   can pass a `Reducer` anywhere a `Combiner` is expected.
- *
- * ## Quickstart
- *
- * **Example** (combining strings with a separator)
- *
- * ```ts
- * import { Combiner, String } from "effect"
- *
- * const csv = Combiner.intercalate(",")(String.ReducerConcat)
- *
- * console.log(csv.combine("a", "b"))
- * // Output: "a,b"
- *
- * console.log(csv.combine(csv.combine("a", "b"), "c"))
- * // Output: "a,b,c"
- * ```
- *
- * ## See also
- *
- * - {@link make} – the primary constructor
- * - {@link Combiner} – the core interface
+ * A `Combiner<A>` contains one operation, `combine(self, that)`, which returns
+ * the merged value. It does not define an initial value for reducing a
+ * collection; use a `Reducer` when you need that. This module includes the
+ * `Combiner` interface, a constructor for custom combining logic, and common
+ * combiners for choosing or ordering values.
  *
  * @since 4.0.0
  */