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

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
  */
@@ -112,6 +132,13 @@ const QuitErrorTypeId = "effect/platform/Terminal/QuitError"
  * A `QuitError` 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,7 +156,19 @@ 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)
@@ -143,7 +182,19 @@ export const isQuitError = (u: unknown): u is QuitError => Predicate.hasProperty
 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

@@ -425,6 +425,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
  */
@@ -500,6 +513,18 @@ export const DisablePropagation = Context.Reference<boolean>(
 /**
  * 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
  */
@@ -513,6 +538,22 @@ export const CurrentTraceLevel: Context.Reference<LogLevel> = Context.Reference<
  * 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
  */
@@ -565,6 +606,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,56 @@
 /**
- * A `Trie` is used for locating specific `string` keys from within a set.
+ * Immutable string-keyed maps optimized for prefix lookup.
+ *
+ * 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}.
+ * - Updates such as {@link insert}, {@link remove}, {@link insertMany}, and
+ *   {@link removeMany} return new tries; existing tries are not mutated.
+ * - 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}.
  *
- * 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`).
+ * **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.
  *
- * Prefix search is also the main feature that makes a `Trie` more suited than `HashMap` for certain usecases.
+ * **Example** (Finding entries by prefix)
+ *
+ * ```ts
+ * import { Trie } from "effect"
+ * import * as assert from "node:assert"
  *
- * 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).
+ * const commands = Trie.make(
+ *   ["commit", "Record changes"],
+ *   ["checkout", "Switch branches"],
+ *   ["clone", "Copy a repository"]
+ * )
  *
- * A `Trie` has O(n) lookup time where `n` is the size of the key,
- * or even less than `n` on search misses.
+ * const matches = Trie.toEntriesWithPrefix(commands, "ch")
+ * assert.deepStrictEqual(matches, [["checkout", "Switch branches"]])
+ * ```
  *
  * @since 2.0.0
  */