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

package/src/Take.ts

@@ -1,21 +1,32 @@
 /**
- * The `Take` module provides the representation used by stream-like producers
- * to describe a single pull result. A `Take<A, E, Done>` is either a
- * non-empty batch of emitted values, a failed `Exit`, or a successful `Exit`
- * carrying the stream's completion value.
+ * The `Take` module provides the stored representation of one pull result from
+ * a stream-like producer. A `Take<A, E, Done>` is either a non-empty batch of
+ * emitted values, a failed `Exit`, or a successful `Exit` carrying the
+ * completion value.
  *
- * `Take` is useful at boundaries where pull results need to be stored,
- * transferred, or interpreted later while preserving the distinction between
- * emitted elements, failures, and normal completion. Use {@link toPull} to turn
- * a `Take` back into a `Pull`: value batches become successful pulls, failure
- * exits are propagated, and successful exits signal completion with `Done`.
+ * **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**
  *
- * - A value batch is always represented by a `NonEmptyReadonlyArray`; empty
- *   batches are not valid `Take` values.
- * - Successful `Exit` values do not emit elements. They represent pull
- *   completion and carry the `Done` value.
+ * - 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
  */
@@ -29,6 +40,13 @@ import type * as Pull from "./Pull.ts"
  * Represents one pull result: either a non-empty batch of values, a failure
  * `Exit`, or a successful `Exit` that signals completion with a `Done` value.
  *
+ * **When to use**
+ *
+ * Use to store, transfer, or interpret pull results later while preserving
+ * emitted values, failures, and normal completion.
+ *
+ * @see {@link toPull} for interpreting a `Take` as a `Pull` step
+ *
  * @category models
  * @since 2.0.0
  */
@@ -38,6 +56,11 @@ export type Take<A, E = never, Done = void> = NonEmptyReadonlyArray<A> | Exit.Ex
  * Converts a `Take` into a `Pull`, succeeding with value batches, failing with
  * failure exits, and translating successful exits into pull completion.
  *
+ * **When to use**
+ *
+ * Use to interpret a stored or transferred `Take` as a `Pull` step while
+ * preserving emitted batches, ordinary failures, and completion values.
+ *
  * @category converting
  * @since 4.0.0
  */

package/src/Terminal.ts

@@ -1,19 +1,32 @@
 /**
- * The `Terminal` module defines the service interface used by platform
- * integrations to model command-line input and output. It gives programs a
- * uniform way to query terminal dimensions, read lines, stream low-level key
- * events, and write text without depending directly on Node, the browser, or a
- * test-specific console implementation.
- *
- * Use this module when building interactive command-line tools, prompts, or
- * platform abstractions that need terminal capabilities as an Effect service.
- * Implementations are supplied through context, so application code can depend
- * on `Terminal` while tests and runtimes provide the concrete behavior.
- *
- * `readLine` can fail with {@link QuitError} when the user requests to quit,
- * commonly via `Ctrl+C`. For lower-level interaction, `readInput` returns a
- * scoped stream of {@link UserInput} values containing parsed key metadata and
- * any raw character input.
+ * 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.
  *
  * @since 4.0.0
  */
@@ -92,6 +105,13 @@ export interface Key {
  * A terminal input event containing an optional raw character and the parsed
  * key that was pressed.
  *
+ * **When to use**
+ *
+ * Use when consuming low-level terminal input events from `Terminal.readInput`
+ * and you need both raw character input and parsed key metadata.
+ *
+ * @see {@link Key} for the parsed key metadata stored on each input event
+ *
  * @category models
  * @since 4.0.0
  */
@@ -109,9 +129,16 @@ export interface UserInput {
 const QuitErrorTypeId = "effect/platform/Terminal/QuitError"
 
 /**
- * A `QuitError` represents an error that occurs when a user attempts to
+ * Represents an error that occurs when a user attempts to
  * quit out of a `Terminal` prompt for input (usually by entering `ctrl`+`c`).
  *
+ * **When to use**
+ *
+ * Use when implementing terminal input or prompts that need to signal
+ * user-requested cancellation through the typed error channel.
+ *
+ * @see {@link isQuitError} for checking unknown errors when handling terminal cancellation
+ *
  * @category QuitError
  * @since 4.0.0
  */
@@ -129,21 +156,50 @@ export class QuitError extends Schema.ErrorClass<QuitError>("QuitError")({
 /**
  * Returns `true` if the provided value is a `Terminal.QuitError`.
  *
- * @category QuitError
+ * **When to use**
+ *
+ * Use to narrow unknown failures to `QuitError` when handling terminal input
+ * cancellation.
+ *
+ * **Details**
+ *
+ * Returns `true` when the value carries the `QuitError` runtime marker and
+ * narrows it to `QuitError`.
+ *
+ * @see {@link QuitError} for the error value produced when terminal input is quit
+ *
+ * @category guards
  * @since 4.0.0
  */
 export const isQuitError = (u: unknown): u is QuitError => Predicate.hasProperty(u, QuitErrorTypeId)
 
 /**
- * Context service tag for accessing a `Terminal` implementation.
+ * Service tag for command-line input and output services.
  *
- * @category services
+ * **When to use**
+ *
+ * Use to access or provide platform terminal capabilities such as reading
+ * input, writing output, and inspecting terminal dimensions.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export const Terminal: Context.Service<Terminal, Terminal> = Context.Service("effect/platform/Terminal")
 
 /**
- * Creates a Terminal implementation
+ * Creates a `Terminal` service implementation.
+ *
+ * **When to use**
+ *
+ * Use to construct a custom `Terminal` service implementation from concrete
+ * terminal capabilities when writing a platform adapter, test implementation,
+ * or custom runtime service.
+ *
+ * **Details**
+ *
+ * The implementation object supplies `columns`, `rows`, `readInput`,
+ * `readLine`, and `display`; `make` attaches the `Terminal` service marker so
+ * the result can be provided through the `Terminal` context service.
  *
  * @category constructors
  * @since 4.0.0

package/src/Tracer.ts

@@ -155,7 +155,12 @@ export type SpanStatus = {
 export type AnySpan = Span | ExternalSpan
 
 /**
- * The string key used to identify the `ParentSpan` context service.
+ * Defines the string key for the parent-span context service.
+ *
+ * **When to use**
+ *
+ * Use when integrating lower-level tracing code that needs the raw context key
+ * for parent span lookup.
  *
  * **Example** (Reading the parent span key)
  *
@@ -425,6 +430,19 @@ export interface SpanLink {
 /**
  * Creates a `Tracer` value from a tracer implementation object.
  *
+ * **When to use**
+ *
+ * Use to create a custom tracing backend value that Effect can use when
+ * creating spans.
+ *
+ * **Details**
+ *
+ * `make` returns the supplied implementation object unchanged. The object must
+ * satisfy the `Tracer` contract, including a `span` method that returns a
+ * `Span`.
+ *
+ * @see {@link Span} for the span values returned by tracer implementations
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -472,9 +490,17 @@ export const externalSpan = (
 })
 
 /**
- * Reference used to disable trace propagation. When set on the fiber or span
- * annotations, new spans are created as non-propagating no-op spans and
- * disabled spans are skipped when deriving a parent span.
+ * Context reference for disabling trace propagation.
+ *
+ * **When to use**
+ *
+ * Use to prevent spans in a scope from propagating tracing context.
+ *
+ * **Details**
+ *
+ * When enabled on fiber or span annotations, new spans are created as
+ * non-propagating no-op spans and disabled spans are skipped when deriving a
+ * parent span.
  *
  * **Example** (Disabling span propagation)
  *
@@ -498,7 +524,19 @@ export const DisablePropagation = Context.Reference<boolean>(
 )
 
 /**
- * Reference for controlling the current trace level for dynamic filtering.
+ * Context reference for controlling the current trace level for dynamic filtering.
+ *
+ * **When to use**
+ *
+ * Use to set the default trace level for spans in a scope when span options do
+ * not provide `level`.
+ *
+ * **Details**
+ *
+ * The default value is `"Info"`. Span creation uses `options.level ??
+ * CurrentTraceLevel` before applying `MinimumTraceLevel`.
+ *
+ * @see {@link MinimumTraceLevel} for the threshold that decides whether spans at that level are sampled
  *
  * @category references
  * @since 4.0.0
@@ -509,10 +547,26 @@ export const CurrentTraceLevel: Context.Reference<LogLevel> = Context.Reference<
 )
 
 /**
- * Reference for setting the minimum trace level threshold. Spans and their
+ * Context reference for setting the minimum trace level threshold. Spans and their
  * descendants below this level will have their sampling decision forced to
  * false, preventing them from being exported.
  *
+ * **When to use**
+ *
+ * Use to set the trace-level threshold that controls whether spans are sampled
+ * by default.
+ *
+ * **Details**
+ *
+ * The default value is `"All"`. Span creation compares the span level from
+ * `options.level ?? CurrentTraceLevel` against this threshold.
+ *
+ * **Gotchas**
+ *
+ * Explicit `options.sampled` bypasses threshold computation.
+ *
+ * @see {@link CurrentTraceLevel} for the default span level used when options do not specify one
+ *
  * @category references
  * @since 4.0.0
  */
@@ -521,7 +575,12 @@ export const MinimumTraceLevel = Context.Reference<
 >("effect/Tracer/MinimumTraceLevel", { defaultValue: () => "All" })
 
 /**
- * The string key used to identify the active `Tracer` context reference.
+ * Defines the string key for the active tracer context reference.
+ *
+ * **When to use**
+ *
+ * Use when integrating lower-level tracing code that needs the raw context key
+ * for active tracer lookup.
  *
  * @category references
  * @since 4.0.0
@@ -565,6 +624,14 @@ export const Tracer: Context.Reference<Tracer> = Context.Reference<Tracer>(Trace
  * generates span and trace identifiers, stores attributes, events, and links,
  * and records `Started` or `Ended` status.
  *
+ * **Details**
+ *
+ * The constructor initializes the span with `Started` status, inherits the
+ * parent trace id or generates a new one, and always generates a new span id.
+ * Attributes, events, links, and status are then mutated through `Span` methods.
+ *
+ * @see {@link Span} for the interface implemented by native spans
+ *
  * @category native tracer
  * @since 4.0.0
  */

package/src/Trie.ts

@@ -1,17 +1,54 @@
 /**
- * A `Trie` is used for locating specific `string` keys from within a set.
+ * Immutable string-keyed maps optimized for prefix lookup.
  *
- * It works similar to `HashMap`, but with keys required to be `string`.
- * This constraint unlocks some performance optimizations and new methods to get string prefixes (e.g. `keysWithPrefix`, `longestPrefixOf`).
+ * 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?".
  *
- * Prefix search is also the main feature that makes a `Trie` more suited than `HashMap` for certain usecases.
+ * **Mental model**
  *
- * A `Trie` is often used to store a dictionary (list of words) that can be searched
- * in a manner that allows for efficient generation of completion lists
- * (e.g. predict the rest of a word a user is typing).
+ * - 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.
  *
- * A `Trie` has O(n) lookup time where `n` is the size of the key,
- * or even less than `n` on search misses.
+ * **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"]])
+ * ```
  *
  * @since 2.0.0
  */
@@ -153,7 +190,7 @@ export const make: <Entries extends Array<readonly [string, any]>>(
 ) => Trie<Entries[number] extends readonly [any, infer V] ? V : never> = TR.make
 
 /**
- * Insert a new entry in the `Trie`.
+ * Inserts a new entry in the `Trie`.
  *
  * **Example** (Inserting entries)
  *
@@ -182,7 +219,7 @@ export const make: <Entries extends Array<readonly [string, any]>>(
  */
 export const insert: {
   /**
-   * Insert a new entry in the `Trie`.
+   * Inserts a new entry in the `Trie`.
    *
    * **Example** (Inserting entries)
    *
@@ -211,7 +248,7 @@ export const insert: {
    */
   <V>(key: string, value: V): (self: Trie<V>) => Trie<V>
   /**
-   * Insert a new entry in the `Trie`.
+   * Inserts a new entry in the `Trie`.
    *
    * **Example** (Inserting entries)
    *
@@ -780,7 +817,7 @@ export const longestPrefixOf: {
 export const size: <V>(self: Trie<V>) => number = TR.size
 
 /**
- * Safely lookup the value for the specified key in the `Trie`.
+ * Looks up the value for the specified key in the `Trie` safely.
  *
  * **Example** (Looking up values safely)
  *
@@ -810,7 +847,7 @@ export const size: <V>(self: Trie<V>) => number = TR.size
  */
 export const get: {
   /**
-   * Safely lookup the value for the specified key in the `Trie`.
+   * Looks up the value for the specified key in the `Trie` safely.
    *
    * **Example** (Looking up values safely)
    *
@@ -840,7 +877,7 @@ export const get: {
    */
   (key: string): <V>(self: Trie<V>) => Option<V>
   /**
-   * Safely lookup the value for the specified key in the `Trie`.
+   * Looks up the value for the specified key in the `Trie` safely.
    *
    * **Example** (Looking up values safely)
    *
@@ -872,7 +909,7 @@ export const get: {
 } = TR.get
 
 /**
- * Check if the given key exists in the `Trie`.
+ * Checks whether the given key exists in the `Trie`.
  *
  * **Example** (Checking key membership)
  *
@@ -902,7 +939,7 @@ export const get: {
  */
 export const has: {
   /**
-   * Check if the given key exists in the `Trie`.
+   * Checks whether the given key exists in the `Trie`.
    *
    * **Example** (Checking key membership)
    *
@@ -932,7 +969,7 @@ export const has: {
    */
   (key: string): <V>(self: Trie<V>) => boolean
   /**
-   * Check if the given key exists in the `Trie`.
+   * Checks whether the given key exists in the `Trie`.
    *
    * **Example** (Checking key membership)
    *
@@ -985,7 +1022,7 @@ export const has: {
 export const isEmpty: <V>(self: Trie<V>) => boolean = TR.isEmpty
 
 /**
- * Unsafely looks up the value for the specified key in the `Trie`.
+ * Looks up the value for the specified key in the `Trie` unsafely.
  *
  * **Gotchas**
  *
@@ -1011,7 +1048,7 @@ export const isEmpty: <V>(self: Trie<V>) => boolean = TR.isEmpty
  */
 export const getUnsafe: {
   /**
-   * Unsafely looks up the value for the specified key in the `Trie`.
+   * Looks up the value for the specified key in the `Trie` unsafely.
    *
    * **Gotchas**
    *
@@ -1037,7 +1074,7 @@ export const getUnsafe: {
    */
   (key: string): <V>(self: Trie<V>) => V
   /**
-   * Unsafely looks up the value for the specified key in the `Trie`.
+   * Looks up the value for the specified key in the `Trie` unsafely.
    *
    * **Gotchas**
    *
@@ -1065,7 +1102,7 @@ export const getUnsafe: {
 } = TR.getUnsafe
 
 /**
- * Remove the entry for the specified key in the `Trie`.
+ * Removes the entry for the specified key in the `Trie`.
  *
  * **Example** (Removing entries)
  *
@@ -1093,7 +1130,7 @@ export const getUnsafe: {
  */
 export const remove: {
   /**
-   * Remove the entry for the specified key in the `Trie`.
+   * Removes the entry for the specified key in the `Trie`.
    *
    * **Example** (Removing entries)
    *
@@ -1121,7 +1158,7 @@ export const remove: {
    */
   (key: string): <V>(self: Trie<V>) => Trie<V>
   /**
-   * Remove the entry for the specified key in the `Trie`.
+   * Removes the entry for the specified key in the `Trie`.
    *
    * **Example** (Removing entries)
    *
@@ -1151,7 +1188,7 @@ export const remove: {
 } = TR.remove
 
 /**
- * Reduce a state over the entries of the `Trie`.
+ * Reduces a state over the entries of the `Trie`.
  *
  * **Example** (Reducing entries)
  *
@@ -1190,7 +1227,7 @@ export const remove: {
  */
 export const reduce: {
   /**
-   * Reduce a state over the entries of the `Trie`.
+   * Reduces a state over the entries of the `Trie`.
    *
    * **Example** (Reducing entries)
    *
@@ -1229,7 +1266,7 @@ export const reduce: {
    */
   <Z, V>(zero: Z, f: (accumulator: Z, value: V, key: string) => Z): (self: Trie<V>) => Z
   /**
-   * Reduce a state over the entries of the `Trie`.
+   * Reduces a state over the entries of the `Trie`.
    *
    * **Example** (Reducing entries)
    *
@@ -1980,7 +2017,7 @@ export const removeMany: {
 } = TR.removeMany
 
 /**
- * Insert multiple entries in the `Trie` at once.
+ * Inserts multiple entries in the `Trie` at once.
  *
  * **Example** (Inserting multiple entries)
  *
@@ -2012,7 +2049,7 @@ export const removeMany: {
  */
 export const insertMany: {
   /**
-   * Insert multiple entries in the `Trie` at once.
+   * Inserts multiple entries in the `Trie` at once.
    *
    * **Example** (Inserting multiple entries)
    *
@@ -2044,7 +2081,7 @@ export const insertMany: {
    */
   <V>(iter: Iterable<[string, V]>): (self: Trie<V>) => Trie<V>
   /**
-   * Insert multiple entries in the `Trie` at once.
+   * Inserts multiple entries in the `Trie` at once.
    *
    * **Example** (Inserting multiple entries)
    *