effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/Take.ts

@@ -1,4 +1,22 @@
 /**
+ * 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.
+ *
+ * `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`.
+ *
+ * **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.
+ *
  * @since 2.0.0
  */
 import type { NonEmptyReadonlyArray } from "./Array.ts"
@@ -8,14 +26,20 @@ import * as Exit from "./Exit.ts"
 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.
+ *
+ * @category models
  * @since 2.0.0
- * @category Models
  */
 export type Take<A, E = never, Done = void> = NonEmptyReadonlyArray<A> | Exit.Exit<Done, E>
 
 /**
+ * Converts a `Take` into a `Pull`, succeeding with value batches, failing with
+ * failure exits, and translating successful exits into pull completion.
+ *
+ * @category converting
  * @since 4.0.0
- * @category Conversions
  */
 export const toPull = <A, E, Done>(take: Take<A, E, Done>): Pull.Pull<NonEmptyReadonlyArray<A>, E, Done> =>
   Exit.isExit(take)

package/src/Terminal.ts

@@ -1,4 +1,20 @@
 /**
+ * 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.
+ *
  * @since 4.0.0
  */
 import type * as Cause from "./Cause.ts"
@@ -17,8 +33,8 @@ const TypeId = "~effect/platform/Terminal"
  * A `Terminal` represents a command-line interface which can read input from a
  * user and display messages to a user.
  *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface Terminal {
   readonly [TypeId]: typeof TypeId
@@ -27,6 +43,11 @@ export interface Terminal {
    * The number of columns available on the platform's terminal interface.
    */
   readonly columns: Effect.Effect<number>
+  /**
+   * The number of rows available on the platform's terminal interface.
+   */
+
+  readonly rows: Effect.Effect<number>
   /**
    * Reads input events from the default standard input.
    */
@@ -42,8 +63,11 @@ export interface Terminal {
 }
 
 /**
+ * Keyboard key metadata for terminal input, including the key name and
+ * modifier state.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface Key {
   /**
@@ -65,8 +89,11 @@ export interface Key {
 }
 
 /**
+ * A terminal input event containing an optional raw character and the parsed
+ * key that was pressed.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface UserInput {
   /**
@@ -85,35 +112,41 @@ 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`).
  *
- * @since 4.0.0
  * @category QuitError
+ * @since 4.0.0
  */
 export class QuitError extends Schema.ErrorClass<QuitError>("QuitError")({
   _tag: Schema.tag("QuitError")
 }) {
   /**
+   * Marks this value as a terminal quit error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [QuitErrorTypeId] = QuitErrorTypeId
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` if the provided value is a `Terminal.QuitError`.
+ *
  * @category QuitError
+ * @since 4.0.0
  */
 export const isQuitError = (u: unknown): u is QuitError => Predicate.hasProperty(u, QuitErrorTypeId)
 
 /**
+ * Context service tag for accessing a `Terminal` implementation.
+ *
+ * @category services
  * @since 4.0.0
- * @category Services
  */
 export const Terminal: Context.Service<Terminal, Terminal> = Context.Service("effect/platform/Terminal")
 
 /**
  * Creates a Terminal implementation
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const make = (
   impl: Omit<Terminal, typeof TypeId>

package/src/Tracer.ts

@@ -1,4 +1,42 @@
 /**
+ * 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}
+ *
+ * **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
+ *
  * @since 2.0.0
  */
 import * as Context from "./Context.ts"
@@ -10,8 +48,14 @@ import type { LogLevel } from "./LogLevel.ts"
 import * as Option from "./Option.ts"
 
 /**
- * @since 2.0.0
+ * A tracing backend used by Effect to create spans.
+ *
+ * Custom tracers implement `span` to allocate a span from the supplied name,
+ * parent, annotations, links, start time, kind, root flag, and sampling
+ * decision.
+ *
  * @category models
+ * @since 2.0.0
  */
 export interface Tracer {
   span(this: Tracer, options: {
@@ -32,35 +76,49 @@ export interface Tracer {
 const evaluate = "~effect/Effect/evaluate" satisfies core.evaluate
 
 /**
- * @since 4.0.0
+ * A low-level Effect primitive that can be evaluated by a tracer-specific
+ * context for the current fiber.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface EffectPrimitive<X> {
   [evaluate](this: EffectPrimitive<X>, fiber: Fiber<any, any>): X
 }
 
 /**
- * @since 2.0.0
- * @category models
- * @example
+ * Lifecycle state of a span.
+ *
+ * `Started` records the start time, while `Ended` records the start time, end
+ * time, and exit value with which the span completed.
+ *
+ * **Example** (Creating span statuses)
+ *
  * ```ts
- * import type { Tracer } from "effect"
  * import { Exit } from "effect"
+ * import type { Tracer } from "effect"
+ *
+ * const startTime = 1_000_000_000n
+ * const endTime = 1_500_000_000n
  *
- * // Started span status
  * const startedStatus: Tracer.SpanStatus = {
  *   _tag: "Started",
- *   startTime: BigInt(Date.now() * 1000000)
+ *   startTime
  * }
  *
- * // Ended span status
  * const endedStatus: Tracer.SpanStatus = {
  *   _tag: "Ended",
- *   startTime: BigInt(Date.now() * 1000000),
- *   endTime: BigInt(Date.now() * 1000000 + 1000000),
+ *   startTime,
+ *   endTime,
  *   exit: Exit.succeed("result")
  * }
+ *
+ * console.log(startedStatus._tag) // "Started"
+ * console.log(endedStatus.endTime - endedStatus.startTime) // 500000000n
  * ```
+ *
+ * @category models
+ * @since 2.0.0
  */
 export type SpanStatus = {
   _tag: "Started"
@@ -73,9 +131,11 @@ export type SpanStatus = {
 }
 
 /**
- * @since 2.0.0
- * @category models
- * @example
+ * A span value that can participate in tracing, either an Effect-managed
+ * `Span` or an `ExternalSpan` propagated from another tracing system.
+ *
+ * **Example** (Accepting any span)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -91,26 +151,35 @@ export type SpanStatus = {
  *   traceId: "trace-456"
  * })
  * ```
+ *
+ * @category models
+ * @since 2.0.0
  */
 export type AnySpan = Span | ExternalSpan
 
 /**
- * @since 2.0.0
- * @category tags
- * @example
+ * The string key used to identify the `ParentSpan` context service.
+ *
+ * **Example** (Reading the parent span key)
+ *
  * ```ts
  * import { Tracer } from "effect"
  *
  * // The key used to identify parent spans in the context
  * console.log(Tracer.ParentSpanKey) // "effect/Tracer/ParentSpan"
  * ```
+ *
+ * @category tags
+ * @since 4.0.0
  */
 export const ParentSpanKey = "effect/Tracer/ParentSpan"
 
 /**
- * @since 2.0.0
- * @category tags
- * @example
+ * Context service containing the `Span` or `ExternalSpan` to use as the parent
+ * of newly-created child spans.
+ *
+ * **Example** (Accessing the parent span)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -120,16 +189,22 @@ export const ParentSpanKey = "effect/Tracer/ParentSpan"
  *   console.log(`Parent span: ${parentSpan.spanId}`)
  * })
  * ```
+ *
+ * @category tags
+ * @since 2.0.0
  */
 export class ParentSpan extends Context.Service<ParentSpan, AnySpan>()(ParentSpanKey) {}
 
 /**
- * @since 2.0.0
- * @category models
- * @example
+ * Represents a span created outside Effect's tracer, carrying trace and span
+ * identifiers, sampling state, and annotations so it can be used as a parent or
+ * link in Effect tracing.
+ *
+ * **Example** (Creating an external span value)
+ *
  * ```ts
- * import type { Tracer } from "effect"
  * import { Context } from "effect"
+ * import type { Tracer } from "effect"
  *
  * // Create an external span from another tracing system
  * const externalSpan: Tracer.ExternalSpan = {
@@ -142,6 +217,9 @@ export class ParentSpan extends Context.Service<ParentSpan, AnySpan>()(ParentSpa
  *
  * console.log(`External span: ${externalSpan.spanId}`)
  * ```
+ *
+ * @category models
+ * @since 2.0.0
  */
 export interface ExternalSpan {
   readonly _tag: "ExternalSpan"
@@ -152,12 +230,15 @@ export interface ExternalSpan {
 }
 
 /**
- * @since 3.1.0
- * @category models
- * @example
+ * Options accepted by span-creating APIs, combining span metadata such as
+ * attributes, links, parent/root selection, kind, sampling, and trace level
+ * with stack trace capture settings.
+ *
+ * **Example** (Configuring span options)
+ *
  * ```ts
- * import type { Tracer } from "effect"
  * import { Effect } from "effect"
+ * import type { Tracer } from "effect"
  *
  * // Create an effect with span options
  * const options: Tracer.SpanOptions = {
@@ -171,12 +252,19 @@ export interface ExternalSpan {
  *   Effect.withSpan("my-operation", options)
  * )
  * ```
+ *
+ * @category models
+ * @since 3.1.0
  */
 export interface SpanOptions extends SpanOptionsNoTrace, TraceOptions {}
 
 /**
- * @since 3.1.0
+ * Span creation options that do not control stack trace capture, including
+ * attributes, links, parent or root selection, annotations, span kind,
+ * sampling, and the trace level used for filtering.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface SpanOptionsNoTrace {
   readonly attributes?: Record<string, unknown> | undefined
@@ -190,20 +278,26 @@ export interface SpanOptionsNoTrace {
 }
 
 /**
- * @since 3.1.0
+ * Options that control stack trace capture for tracing wrappers.
+ *
+ * `captureStackTrace` can disable capture or provide a lazy stack string.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface TraceOptions {
   readonly captureStackTrace?: boolean | LazyArg<string | undefined> | undefined
 }
 
 /**
- * @since 3.1.0
- * @category models
- * @example
+ * OpenTelemetry-style role describing the kind of operation represented by a
+ * span: internal work, server handling, client calls, producing, or consuming.
+ *
+ * **Example** (Configuring span kinds)
+ *
  * ```ts
- * import type { Tracer } from "effect"
  * import { Effect } from "effect"
+ * import type { Tracer } from "effect"
  *
  * // Different span kinds for different operations
  * const serverSpan = Effect.withSpan("handle-request", {
@@ -218,24 +312,70 @@ export interface TraceOptions {
  *   kind: "internal" as Tracer.SpanKind
  * })
  * ```
+ *
+ * @category models
+ * @since 3.1.0
  */
 export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer"
 
 /**
- * @since 2.0.0
- * @category models
- * @example
+ * A span created by an Effect tracer.
+ *
+ * It carries trace identity, parent, annotations, attributes, links, sampling
+ * and kind information, lifecycle status, and methods to end the span or add
+ * attributes, events, and links.
+ *
+ * **Example** (Working with spans)
+ *
  * ```ts
- * import { Effect } from "effect"
+ * import { Context, Exit, Option } from "effect"
+ * import type { Tracer } from "effect"
  *
- * // Working with spans using withSpan
- * const program = Effect.succeed("Hello World").pipe(
- *   Effect.withSpan("my-operation")
- * )
+ * const attributes = new Map<string, unknown>()
+ * const links: Array<Tracer.SpanLink> = []
+ * let status: Tracer.SpanStatus = {
+ *   _tag: "Started",
+ *   startTime: 1_000_000_000n
+ * }
+ *
+ * const span: Tracer.Span = {
+ *   _tag: "Span",
+ *   name: "load-user",
+ *   spanId: "span-1",
+ *   traceId: "trace-1",
+ *   parent: Option.none(),
+ *   annotations: Context.empty(),
+ *   get status() {
+ *     return status
+ *   },
+ *   attributes,
+ *   links,
+ *   sampled: true,
+ *   kind: "internal",
+ *   end(endTime, exit) {
+ *     status = { _tag: "Ended", startTime: status.startTime, endTime, exit }
+ *   },
+ *   attribute(key, value) {
+ *     attributes.set(key, value)
+ *   },
+ *   event(name, startTime, eventAttributes = {}) {
+ *     console.log(`${name} at ${startTime} with ${Object.keys(eventAttributes).length} attributes`)
+ *   },
+ *   addLinks(newLinks) {
+ *     links.push(...newLinks)
+ *   }
+ * }
+ *
+ * span.attribute("user.id", "123")
+ * span.end(1_500_000_000n, Exit.succeed("user"))
  *
- * // The span interface defines the properties available
- * // when working with tracing in your effects
+ * console.log(span.name) // "load-user"
+ * console.log(span.attributes.get("user.id")) // "123"
+ * console.log(span.status._tag) // "Ended"
  * ```
+ *
+ * @category models
+ * @since 2.0.0
  */
 export interface Span {
   readonly _tag: "Span"
@@ -256,9 +396,11 @@ export interface Span {
 }
 
 /**
- * @since 2.0.0
- * @category models
- * @example
+ * A relationship from one span to another span, with attributes describing the
+ * relationship.
+ *
+ * **Example** (Linking spans)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -277,6 +419,9 @@ export interface Span {
  *   Effect.withSpan("linked-operation", { links: [link] })
  * )
  * ```
+ *
+ * @category models
+ * @since 2.0.0
  */
 export interface SpanLink {
   readonly span: AnySpan
@@ -284,15 +429,20 @@ export interface SpanLink {
 }
 
 /**
- * @since 2.0.0
+ * Creates a `Tracer` value from a tracer implementation object.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export const make = (options: Tracer): Tracer => options
 
 /**
- * @since 2.0.0
- * @category constructors
- * @example
+ * Creates an `ExternalSpan` from trace and span identifiers, defaulting
+ * `sampled` to `true` and annotations to an empty context when they are not
+ * provided.
+ *
+ * **Example** (Creating an external span)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -308,6 +458,9 @@ export const make = (options: Tracer): Tracer => options
  *   Effect.withSpan("child-operation", { parent: span })
  * )
  * ```
+ *
+ * @category constructors
+ * @since 2.0.0
  */
 export const externalSpan = (
   options: {
@@ -325,9 +478,14 @@ export const externalSpan = (
 })
 
 /**
- * @since 3.12.0
- * @category references
- * @example
+ * 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.
+ *
+ * **Example** (Disabling span propagation)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -338,6 +496,9 @@ export const externalSpan = (
  *   Effect.provideService(Tracer.DisablePropagation, true)
  * )
  * ```
+ *
+ * @category references
+ * @since 3.12.0
  */
 export const DisablePropagation = Context.Reference<boolean>(
   "effect/Tracer/DisablePropagation",
@@ -368,15 +529,20 @@ export const MinimumTraceLevel = Context.Reference<
 >("effect/Tracer/MinimumTraceLevel", { defaultValue: () => "All" })
 
 /**
- * @since 4.0.0
+ * The string key used to identify the active `Tracer` context reference.
+ *
  * @category references
+ * @since 4.0.0
  */
 export const TracerKey = "effect/Tracer"
 
 /**
- * @since 4.0.0
- * @category references
- * @example
+ * Context reference for the active tracer service.
+ *
+ * By default it uses the native tracer, which creates `NativeSpan` instances.
+ *
+ * **Example** (Accessing the current tracer)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -392,6 +558,9 @@ export const TracerKey = "effect/Tracer"
  *   console.log("Current tracer obtained")
  * })
  * ```
+ *
+ * @category references
+ * @since 2.0.0
  */
 export const Tracer: Context.Reference<Tracer> = Context.Reference<Tracer>(TracerKey, {
   defaultValue: () =>
@@ -401,8 +570,13 @@ export const Tracer: Context.Reference<Tracer> = Context.Reference<Tracer>(Trace
 })
 
 /**
- * @since 4.0.0
+ * Default in-memory `Span` implementation used by the native tracer.
+ *
+ * It generates span and trace identifiers, stores attributes, events, and
+ * links, and records `Started` or `Ended` status.
+ *
  * @category native tracer
+ * @since 4.0.0
  */
 export class NativeSpan implements Span {
   readonly _tag = "Span"