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

package/dist/References.d.ts

@@ -1,12 +1,62 @@
 /**
- * This module provides a collection of reference implementations for commonly used
- * Effect runtime configuration values. These references allow you to access and
- * modify runtime behavior such as concurrency limits, scheduling policies,
- * tracing configuration, and logging settings.
+ * The `References` module exposes the built-in `Context.Reference` keys that
+ * the Effect runtime consults for execution settings and diagnostic metadata.
+ * These references cover concurrency, scheduling, logging, tracing, and
+ * low-level diagnostic state.
+ *
+ * A `Context.Reference<A>` is a service key with a default value. Reading one
+ * of these references returns the value from the current fiber context, and
+ * providing a new value changes behavior for the provided effect and the fibers
+ * it starts.
+ *
+ * **Mental model**
+ *
+ * - Each exported value is a context key with a runtime default, so it can be
+ *   read even when application code has not provided an override.
+ * - Runtime services such as logging, tracing, scheduling, and concurrency
+ *   controls read these keys from the current context.
+ * - `Effect.provideService` overrides a reference for a specific effect scope;
+ *   it does not mutate a process-wide global.
+ * - Child fibers inherit the context active at the point they are started.
+ *
+ * **Common tasks**
+ *
+ * - Limit default concurrency with {@link CurrentConcurrency}.
+ * - Control log severity and filtering with {@link CurrentLogLevel},
+ *   {@link MinimumLogLevel}, and {@link UnhandledLogLevel}.
+ * - Attach log metadata with {@link CurrentLogAnnotations} and
+ *   {@link CurrentLogSpans}, or replace the active loggers with
+ *   {@link CurrentLoggers}.
+ * - Configure tracing with {@link Tracer}, {@link TracerEnabled},
+ *   {@link TracerTimingEnabled}, {@link TracerSpanAnnotations}, and
+ *   {@link TracerSpanLinks}.
+ * - Tune scheduler behavior with {@link Scheduler}, {@link MaxOpsBeforeYield},
+ *   and {@link PreventSchedulerYield}.
+ *
+ * **Example** (Providing a runtime reference)
  *
- * References are special service instances that can be dynamically updated
- * during runtime, making them ideal for configuration that may need to change
- * based on application state or external conditions.
+ * ```ts
+ * import { Effect, References } from "effect"
+ *
+ * const readConcurrency = Effect.gen(function*() {
+ *   return yield* References.CurrentConcurrency
+ * })
+ *
+ * const limited = Effect.provideService(
+ *   readConcurrency,
+ *   References.CurrentConcurrency,
+ *   4
+ * )
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - Prefer higher-level logging, tracing, and concurrency APIs when they fit;
+ *   this module is for direct access to the runtime knobs they use.
+ * - `CurrentLogLevel` chooses the severity assigned to ordinary log entries,
+ *   while `MinimumLogLevel` decides which entries are filtered out.
+ * - References are context values, so scoped overrides end when the provided
+ *   effect completes.
  *
  * @since 4.0.0
  */
@@ -20,6 +70,13 @@ export {
 /**
  * Reference for the current trace level used for dynamic trace filtering.
  *
+ * **When to use**
+ *
+ * Use to set the default trace level for spans created in a scope when span
+ * options do not provide `level`.
+ *
+ * @see {@link MinimumTraceLevel} for configuring the threshold that decides whether spans at a given level are sampled or exported
+ *
  * @category references
  * @since 4.0.0
  */
@@ -27,6 +84,18 @@ CurrentTraceLevel,
 /**
  * Reference used to disable trace propagation in the current context.
  *
+ * **When to use**
+ *
+ * Use to mark tracing work as non-propagating while still allowing local span
+ * tracking.
+ *
+ * **Details**
+ *
+ * Annotated spans become non-propagating no-op spans, and parent selection
+ * skips spans marked with disabled propagation.
+ *
+ * @see {@link TracerEnabled} for disabling span registration instead of only propagation
+ *
  * @category references
  * @since 4.0.0
  */
@@ -34,6 +103,17 @@ DisablePropagation,
 /**
  * Reference controlling the maximum operation budget before a fiber yields to the scheduler.
  *
+ * **When to use**
+ *
+ * Use to tune scheduler fairness for CPU-bound fibers by changing the
+ * operation budget that triggers a scheduler yield.
+ *
+ * **Details**
+ *
+ * The default value is `2048` operations.
+ *
+ * @see {@link PreventSchedulerYield} for bypassing scheduler yield checks instead of changing the operation budget
+ *
  * @category references
  * @since 4.0.0
  */
@@ -41,6 +121,13 @@ MaxOpsBeforeYield,
 /**
  * Reference setting the minimum trace level threshold for span sampling.
  *
+ * **When to use**
+ *
+ * Use to set the trace-level threshold that decides whether newly created
+ * spans are sampled and exported.
+ *
+ * @see {@link CurrentTraceLevel} for setting the level assigned to spans before this threshold is applied
+ *
  * @category references
  * @since 4.0.0
  */
@@ -48,6 +135,23 @@ MinimumTraceLevel,
 /**
  * Reference controlling whether the runtime bypasses scheduler yield checks.
  *
+ * **When to use**
+ *
+ * Use to bypass automatic scheduler yield checks in a controlled runtime scope
+ * where throughput is preferred over scheduler fairness.
+ *
+ * **Details**
+ *
+ * When set to `true`, the fiber run loop skips `Scheduler.shouldYield`. The
+ * default value is `false`.
+ *
+ * **Gotchas**
+ *
+ * Disabling automatic yield checks can let long-running fibers monopolize the
+ * JavaScript thread.
+ *
+ * @see {@link MaxOpsBeforeYield} for tuning the operation budget while keeping scheduler yield checks enabled
+ *
  * @category references
  * @since 4.0.0
  */
@@ -55,6 +159,11 @@ PreventSchedulerYield,
 /**
  * Reference for the active tracer service used to create spans.
  *
+ * **When to use**
+ *
+ * Use to access or override the active tracer service through the references
+ * module when working directly with Effect runtime references.
+ *
  * @category references
  * @since 4.0.0
  */
@@ -63,6 +172,11 @@ Tracer };
  * Reference for controlling the current concurrency limit. Can be set to "unbounded"
  * for unlimited concurrency or a specific number to limit concurrent operations.
  *
+ * **When to use**
+ *
+ * Use to configure the default concurrency limit for operations that read
+ * concurrency from the current context.
+ *
  * **Example** (Setting current concurrency)
  *
  * ```ts
@@ -103,6 +217,11 @@ export declare const CurrentConcurrency: Context.Reference<number | "unbounded">
  * Reference for managing log annotations that are automatically added to all log entries.
  * These annotations provide contextual metadata that appears in every log message.
  *
+ * **When to use**
+ *
+ * Use to attach shared contextual metadata to every log entry emitted in the
+ * current context.
+ *
  * **Example** (Managing log annotations)
  *
  * ```ts
@@ -159,6 +278,11 @@ export declare const CurrentLogAnnotations: Context.Reference<ReadonlyRecord<str
  * Reference for the current log severity used by `Effect.log` when no explicit
  * level is provided.
  *
+ * **When to use**
+ *
+ * Use to set the default severity for `Effect.log` entries that do not provide
+ * an explicit level.
+ *
  * **Details**
  *
  * Use `MinimumLogLevel` to control which log entries are filtered out.
@@ -206,6 +330,11 @@ export declare const CurrentLogLevel: Context.Reference<Severity>;
  * Reference for managing log spans that track the duration and hierarchy of operations.
  * Each span represents a labeled time period for performance analysis and debugging.
  *
+ * **When to use**
+ *
+ * Use to carry the active log span stack that should be included with log
+ * entries in the current context.
+ *
  * **Example** (Tracking log spans)
  *
  * ```ts
@@ -267,12 +396,19 @@ export declare const CurrentLogSpans: Context.Reference<ReadonlyArray<[label: st
  * Reference containing the current captured stack-frame chain for the running
  * fiber.
  *
+ * **When to use**
+ *
+ * Use when writing low-level tracing or diagnostic integrations that need direct
+ * access to the stack-frame chain carried by the current fiber.
+ *
  * **Details**
  *
  * Effect and Layer tracing use this reference to attach stack-frame information
  * to failures and interruption causes. It is normally managed by tracing APIs
  * rather than provided directly by application code.
  *
+ * @see {@link StackFrame} for the frame node stored in this reference
+ *
  * @category references
  * @since 4.0.0
  */
@@ -281,6 +417,10 @@ export declare const CurrentStackFrame: Context.Reference<StackFrame | undefined
  * Reference for setting the minimum log level threshold. Log entries below this
  * level will be filtered out completely.
  *
+ * **When to use**
+ *
+ * Use to filter out log entries below a severity threshold.
+ *
  * **Example** (Setting the minimum log level)
  *
  * ```ts
@@ -332,6 +472,10 @@ export declare const MinimumLogLevel: Context.Reference<LogLevel>;
  * Reference for controlling whether tracing is enabled globally. When set to false,
  * spans will not be registered with the tracer and tracing overhead is minimized.
  *
+ * **When to use**
+ *
+ * Use to disable or re-enable span registration in the current context.
+ *
  * **Example** (Toggling tracing)
  *
  * ```ts
@@ -378,6 +522,10 @@ export declare const TracerEnabled: Context.Reference<boolean>;
  * Reference for managing span annotations that are automatically added to all new spans.
  * These annotations provide context and metadata that applies across multiple spans.
  *
+ * **When to use**
+ *
+ * Use to attach shared metadata to every span created in the current context.
+ *
  * **Example** (Managing span annotations)
  *
  * ```ts
@@ -430,6 +578,10 @@ export declare const TracerSpanAnnotations: Context.Reference<ReadonlyRecord<str
  * Reference for managing span links that are automatically added to all new spans.
  * Span links connect related spans that are not in a parent-child relationship.
  *
+ * **When to use**
+ *
+ * Use to attach shared links to every span created in the current context.
+ *
  * **Example** (Managing span links)
  *
  * ```ts
@@ -493,6 +645,10 @@ export declare const TracerSpanLinks: Context.Reference<ReadonlyArray<SpanLink>>
  * to false, spans will not contain timing information (trace time will always
  * be set to zero).
  *
+ * **When to use**
+ *
+ * Use to disable or re-enable timing capture for spans in the current context.
+ *
  * **Example** (Toggling trace timing)
  *
  * ```ts
@@ -532,8 +688,25 @@ export declare const TracerSpanLinks: Context.Reference<ReadonlyArray<SpanLink>>
  */
 export declare const TracerTimingEnabled: Context.Reference<boolean>;
 /**
- * The log level for unhandled errors. This reference allows you to set the log
- * level for unhandled errors that occur during Effect execution.
+ * Reference for the log severity used when a pool finalizer reports an
+ * unhandled error.
+ *
+ * **When to use**
+ *
+ * Use to choose whether and at which severity pool finalizer failures are
+ * reported.
+ *
+ * **Details**
+ *
+ * The default level is `"Error"`.
+ *
+ * **Gotchas**
+ *
+ * Providing `undefined` suppresses this report; it does not fall back to
+ * `CurrentLogLevel`.
+ *
+ * @see {@link CurrentLogLevel} for the default severity used by ordinary `Effect.log` calls
+ * @see {@link MinimumLogLevel} for filtering emitted log entries by threshold
  *
  * @category references
  * @since 4.0.0
@@ -542,11 +715,18 @@ export declare const UnhandledLogLevel: Context.Reference<Severity | undefined>;
 /**
  * A captured stack-frame node used to describe the traced execution path.
  *
+ * **When to use**
+ *
+ * Use when reading or supplying the stack-frame chain that Effect tracing uses
+ * to attach diagnostic call-site information to failures and interruptions.
+ *
  * **Details**
  *
  * Each frame has a span or operation `name`, a lazy `stack` supplier, and an
  * optional `parent` frame that links it to the previous captured frame.
  *
+ * @see {@link CurrentStackFrame} for the fiber reference carrying the active stack-frame chain
+ *
  * @category references
  * @since 4.0.0
  */
@@ -559,8 +739,14 @@ export interface StackFrame {
  * Reference containing the set of loggers currently used by Effect logging
  * operations.
  *
+ * **When to use**
+ *
+ * Use to inspect or provide the complete set of loggers used by Effect logging
+ * in the current context.
+ *
  * **Details**
  *
+ * The default set contains the built-in default logger and tracer logger.
  * Providing this reference changes which `Logger` instances receive log entries
  * in the current context.
  *
@@ -569,12 +755,17 @@ export interface StackFrame {
  */
 export declare const CurrentLoggers: Context.Reference<ReadonlySet<Logger<unknown, any>>>;
 /**
- * Reference controlling whether the default console logger writes to stderr.
+ * Reference controlling whether built-in console loggers write to stderr.
+ *
+ * **When to use**
+ *
+ * Use to keep stdout reserved for protocol messages or data output while still
+ * allowing Effect runtime logs to be emitted.
  *
  * **Details**
  *
- * When set to `true`, the pretty console logger uses `console.error`; otherwise
- * it uses `console.log`.
+ * The default value is `false`. When set to `true`, the built-in default logger
+ * and TTY pretty console logger call `console.error` instead of `console.log`.
  *
  * @category references
  * @since 4.0.0
@@ -585,6 +776,11 @@ export {
  * Reference for the current scheduler implementation used by the Effect runtime.
  * Controls how Effects are scheduled and executed.
  *
+ * **When to use**
+ *
+ * Use to provide the scheduler implementation that fibers use in the current
+ * context.
+ *
  * **Example** (Providing a custom scheduler)
  *
  * ```ts

package/dist/References.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"References.d.ts","sourceRoot":"","sources":["../src/References.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"References.d.ts","sourceRoot":"","sources":["../src/References.ts"],"names":[],"mappings":"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"}

package/dist/References.js

@@ -6,6 +6,13 @@ export {
 /**
  * Reference for the current trace level used for dynamic trace filtering.
  *
+ * **When to use**
+ *
+ * Use to set the default trace level for spans created in a scope when span
+ * options do not provide `level`.
+ *
+ * @see {@link MinimumTraceLevel} for configuring the threshold that decides whether spans at a given level are sampled or exported
+ *
  * @category references
  * @since 4.0.0
  */
@@ -13,6 +20,18 @@ CurrentTraceLevel,
 /**
  * Reference used to disable trace propagation in the current context.
  *
+ * **When to use**
+ *
+ * Use to mark tracing work as non-propagating while still allowing local span
+ * tracking.
+ *
+ * **Details**
+ *
+ * Annotated spans become non-propagating no-op spans, and parent selection
+ * skips spans marked with disabled propagation.
+ *
+ * @see {@link TracerEnabled} for disabling span registration instead of only propagation
+ *
  * @category references
  * @since 4.0.0
  */
@@ -20,6 +39,17 @@ DisablePropagation,
 /**
  * Reference controlling the maximum operation budget before a fiber yields to the scheduler.
  *
+ * **When to use**
+ *
+ * Use to tune scheduler fairness for CPU-bound fibers by changing the
+ * operation budget that triggers a scheduler yield.
+ *
+ * **Details**
+ *
+ * The default value is `2048` operations.
+ *
+ * @see {@link PreventSchedulerYield} for bypassing scheduler yield checks instead of changing the operation budget
+ *
  * @category references
  * @since 4.0.0
  */
@@ -27,6 +57,13 @@ MaxOpsBeforeYield,
 /**
  * Reference setting the minimum trace level threshold for span sampling.
  *
+ * **When to use**
+ *
+ * Use to set the trace-level threshold that decides whether newly created
+ * spans are sampled and exported.
+ *
+ * @see {@link CurrentTraceLevel} for setting the level assigned to spans before this threshold is applied
+ *
  * @category references
  * @since 4.0.0
  */
@@ -34,6 +71,23 @@ MinimumTraceLevel,
 /**
  * Reference controlling whether the runtime bypasses scheduler yield checks.
  *
+ * **When to use**
+ *
+ * Use to bypass automatic scheduler yield checks in a controlled runtime scope
+ * where throughput is preferred over scheduler fairness.
+ *
+ * **Details**
+ *
+ * When set to `true`, the fiber run loop skips `Scheduler.shouldYield`. The
+ * default value is `false`.
+ *
+ * **Gotchas**
+ *
+ * Disabling automatic yield checks can let long-running fibers monopolize the
+ * JavaScript thread.
+ *
+ * @see {@link MaxOpsBeforeYield} for tuning the operation budget while keeping scheduler yield checks enabled
+ *
  * @category references
  * @since 4.0.0
  */
@@ -41,6 +95,11 @@ PreventSchedulerYield,
 /**
  * Reference for the active tracer service used to create spans.
  *
+ * **When to use**
+ *
+ * Use to access or override the active tracer service through the references
+ * module when working directly with Effect runtime references.
+ *
  * @category references
  * @since 4.0.0
  */
@@ -49,6 +108,11 @@ Tracer };
  * Reference for controlling the current concurrency limit. Can be set to "unbounded"
  * for unlimited concurrency or a specific number to limit concurrent operations.
  *
+ * **When to use**
+ *
+ * Use to configure the default concurrency limit for operations that read
+ * concurrency from the current context.
+ *
  * **Example** (Setting current concurrency)
  *
  * ```ts
@@ -89,6 +153,11 @@ export const CurrentConcurrency = references.CurrentConcurrency;
  * Reference for managing log annotations that are automatically added to all log entries.
  * These annotations provide contextual metadata that appears in every log message.
  *
+ * **When to use**
+ *
+ * Use to attach shared contextual metadata to every log entry emitted in the
+ * current context.
+ *
  * **Example** (Managing log annotations)
  *
  * ```ts
@@ -145,6 +214,11 @@ export const CurrentLogAnnotations = references.CurrentLogAnnotations;
  * Reference for the current log severity used by `Effect.log` when no explicit
  * level is provided.
  *
+ * **When to use**
+ *
+ * Use to set the default severity for `Effect.log` entries that do not provide
+ * an explicit level.
+ *
  * **Details**
  *
  * Use `MinimumLogLevel` to control which log entries are filtered out.
@@ -192,6 +266,11 @@ export const CurrentLogLevel = references.CurrentLogLevel;
  * Reference for managing log spans that track the duration and hierarchy of operations.
  * Each span represents a labeled time period for performance analysis and debugging.
  *
+ * **When to use**
+ *
+ * Use to carry the active log span stack that should be included with log
+ * entries in the current context.
+ *
  * **Example** (Tracking log spans)
  *
  * ```ts
@@ -253,12 +332,19 @@ export const CurrentLogSpans = references.CurrentLogSpans;
  * Reference containing the current captured stack-frame chain for the running
  * fiber.
  *
+ * **When to use**
+ *
+ * Use when writing low-level tracing or diagnostic integrations that need direct
+ * access to the stack-frame chain carried by the current fiber.
+ *
  * **Details**
  *
  * Effect and Layer tracing use this reference to attach stack-frame information
  * to failures and interruption causes. It is normally managed by tracing APIs
  * rather than provided directly by application code.
  *
+ * @see {@link StackFrame} for the frame node stored in this reference
+ *
  * @category references
  * @since 4.0.0
  */
@@ -267,6 +353,10 @@ export const CurrentStackFrame = references.CurrentStackFrame;
  * Reference for setting the minimum log level threshold. Log entries below this
  * level will be filtered out completely.
  *
+ * **When to use**
+ *
+ * Use to filter out log entries below a severity threshold.
+ *
  * **Example** (Setting the minimum log level)
  *
  * ```ts
@@ -318,6 +408,10 @@ export const MinimumLogLevel = references.MinimumLogLevel;
  * Reference for controlling whether tracing is enabled globally. When set to false,
  * spans will not be registered with the tracer and tracing overhead is minimized.
  *
+ * **When to use**
+ *
+ * Use to disable or re-enable span registration in the current context.
+ *
  * **Example** (Toggling tracing)
  *
  * ```ts
@@ -364,6 +458,10 @@ export const TracerEnabled = references.TracerEnabled;
  * Reference for managing span annotations that are automatically added to all new spans.
  * These annotations provide context and metadata that applies across multiple spans.
  *
+ * **When to use**
+ *
+ * Use to attach shared metadata to every span created in the current context.
+ *
  * **Example** (Managing span annotations)
  *
  * ```ts
@@ -416,6 +514,10 @@ export const TracerSpanAnnotations = references.TracerSpanAnnotations;
  * Reference for managing span links that are automatically added to all new spans.
  * Span links connect related spans that are not in a parent-child relationship.
  *
+ * **When to use**
+ *
+ * Use to attach shared links to every span created in the current context.
+ *
  * **Example** (Managing span links)
  *
  * ```ts
@@ -479,6 +581,10 @@ export const TracerSpanLinks = references.TracerSpanLinks;
  * to false, spans will not contain timing information (trace time will always
  * be set to zero).
  *
+ * **When to use**
+ *
+ * Use to disable or re-enable timing capture for spans in the current context.
+ *
  * **Example** (Toggling trace timing)
  *
  * ```ts
@@ -518,8 +624,25 @@ export const TracerSpanLinks = references.TracerSpanLinks;
  */
 export const TracerTimingEnabled = references.TracerTimingEnabled;
 /**
- * The log level for unhandled errors. This reference allows you to set the log
- * level for unhandled errors that occur during Effect execution.
+ * Reference for the log severity used when a pool finalizer reports an
+ * unhandled error.
+ *
+ * **When to use**
+ *
+ * Use to choose whether and at which severity pool finalizer failures are
+ * reported.
+ *
+ * **Details**
+ *
+ * The default level is `"Error"`.
+ *
+ * **Gotchas**
+ *
+ * Providing `undefined` suppresses this report; it does not fall back to
+ * `CurrentLogLevel`.
+ *
+ * @see {@link CurrentLogLevel} for the default severity used by ordinary `Effect.log` calls
+ * @see {@link MinimumLogLevel} for filtering emitted log entries by threshold
  *
  * @category references
  * @since 4.0.0
@@ -529,8 +652,14 @@ export const UnhandledLogLevel = references.UnhandledLogLevel;
  * Reference containing the set of loggers currently used by Effect logging
  * operations.
  *
+ * **When to use**
+ *
+ * Use to inspect or provide the complete set of loggers used by Effect logging
+ * in the current context.
+ *
  * **Details**
  *
+ * The default set contains the built-in default logger and tracer logger.
  * Providing this reference changes which `Logger` instances receive log entries
  * in the current context.
  *
@@ -539,12 +668,17 @@ export const UnhandledLogLevel = references.UnhandledLogLevel;
  */
 export const CurrentLoggers = internalEffect.CurrentLoggers;
 /**
- * Reference controlling whether the default console logger writes to stderr.
+ * Reference controlling whether built-in console loggers write to stderr.
+ *
+ * **When to use**
+ *
+ * Use to keep stdout reserved for protocol messages or data output while still
+ * allowing Effect runtime logs to be emitted.
  *
  * **Details**
  *
- * When set to `true`, the pretty console logger uses `console.error`; otherwise
- * it uses `console.log`.
+ * The default value is `false`. When set to `true`, the built-in default logger
+ * and TTY pretty console logger call `console.error` instead of `console.log`.
  *
  * @category references
  * @since 4.0.0
@@ -555,6 +689,11 @@ export {
  * Reference for the current scheduler implementation used by the Effect runtime.
  * Controls how Effects are scheduled and executed.
  *
+ * **When to use**
+ *
+ * Use to provide the scheduler implementation that fibers use in the current
+ * context.
+ *
  * **Example** (Providing a custom scheduler)
  *
  * ```ts