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

package/src/References.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
  */
@@ -21,42 +71,101 @@ import { CurrentTraceLevel, DisablePropagation, MinimumTraceLevel, type SpanLink
 
 export {
   /**
-   * Reference for the current trace level used for dynamic trace filtering.
+   * Context 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
    */
   CurrentTraceLevel,
   /**
-   * Reference used to disable trace propagation in the current context.
+   * Context reference for disabling 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
    */
   DisablePropagation,
   /**
-   * Reference controlling the maximum operation budget before a fiber yields to the scheduler.
+   * Context reference for 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
    */
   MaxOpsBeforeYield,
   /**
-   * Reference setting the minimum trace level threshold for span sampling.
+   * Context reference for 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
    */
   MinimumTraceLevel,
   /**
-   * Reference controlling whether the runtime bypasses scheduler yield checks.
+   * Context reference for 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
    */
   PreventSchedulerYield,
   /**
-   * Reference for the active tracer service used to create spans.
+   * Context 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
@@ -65,9 +174,14 @@ export {
 }
 
 /**
- * Reference for controlling the current concurrency limit. Can be set to "unbounded"
+ * Context 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
@@ -106,9 +220,14 @@ export {
 export const CurrentConcurrency: Context.Reference<number | "unbounded"> = references.CurrentConcurrency
 
 /**
- * Reference for managing log annotations that are automatically added to all log entries.
+ * Context 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
@@ -164,9 +283,14 @@ export const CurrentLogAnnotations: Context.Reference<ReadonlyRecord<string, unk
   references.CurrentLogAnnotations
 
 /**
- * Reference for the current log severity used by `Effect.log` when no explicit
+ * Context 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.
@@ -212,9 +336,14 @@ export const CurrentLogAnnotations: Context.Reference<ReadonlyRecord<string, unk
 export const CurrentLogLevel: Context.Reference<Severity> = references.CurrentLogLevel
 
 /**
- * Reference for managing log spans that track the duration and hierarchy of operations.
+ * Context 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
@@ -275,24 +404,35 @@ export const CurrentLogSpans: Context.Reference<ReadonlyArray<[label: string, ti
   references.CurrentLogSpans
 
 /**
- * Reference containing the current captured stack-frame chain for the running
+ * Context reference for 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
  */
 export const CurrentStackFrame: Context.Reference<StackFrame | undefined> = references.CurrentStackFrame
 
 /**
- * Reference for setting the minimum log level threshold. Log entries below this
+ * Context 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
@@ -342,9 +482,13 @@ export const CurrentStackFrame: Context.Reference<StackFrame | undefined> = refe
 export const MinimumLogLevel: Context.Reference<LogLevel> = references.MinimumLogLevel
 
 /**
- * Reference for controlling whether tracing is enabled globally. When set to false,
+ * Context 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
@@ -389,9 +533,13 @@ export const MinimumLogLevel: Context.Reference<LogLevel> = references.MinimumLo
 export const TracerEnabled: Context.Reference<boolean> = references.TracerEnabled
 
 /**
- * Reference for managing span annotations that are automatically added to all new spans.
+ * Context 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
@@ -443,9 +591,13 @@ export const TracerSpanAnnotations: Context.Reference<ReadonlyRecord<string, unk
   references.TracerSpanAnnotations
 
 /**
- * Reference for managing span links that are automatically added to all new spans.
+ * Context 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
@@ -506,10 +658,14 @@ export const TracerSpanAnnotations: Context.Reference<ReadonlyRecord<string, unk
 export const TracerSpanLinks: Context.Reference<ReadonlyArray<SpanLink>> = references.TracerSpanLinks
 
 /**
- * Reference for controlling whether trace timing is enabled globally. When set
+ * Context reference for controlling whether trace timing is enabled globally. When set
  * 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
@@ -550,8 +706,25 @@ export const TracerSpanLinks: Context.Reference<ReadonlyArray<SpanLink>> = refer
 export const TracerTimingEnabled: Context.Reference<boolean> = 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.
+ * Context 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
@@ -561,11 +734,18 @@ export const UnhandledLogLevel: Context.Reference<Severity | undefined> = refere
 /**
  * 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
  */
@@ -576,11 +756,17 @@ export interface StackFrame {
 }
 
 /**
- * Reference containing the set of loggers currently used by Effect logging
+ * Context reference for 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.
  *
@@ -590,12 +776,17 @@ export interface StackFrame {
 export const CurrentLoggers: Context.Reference<ReadonlySet<Logger<unknown, any>>> = internalEffect.CurrentLoggers
 
 /**
- * Reference controlling whether the default console logger writes to stderr.
+ * Context reference for 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
@@ -604,9 +795,14 @@ export const LogToStderr: Context.Reference<boolean> = internalEffect.LogToStder
 
 export {
   /**
-   * Reference for the current scheduler implementation used by the Effect runtime.
+   * Context 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/src/RegExp.ts

@@ -1,12 +1,50 @@
 /**
- * This module provides utility functions for working with RegExp in TypeScript.
+ * Tools for working with JavaScript regular expressions from the Effect module
+ * namespace. The module exposes the native `RegExp` constructor, a guard for
+ * narrowing unknown values, and escaping for literal text that will be embedded
+ * in a pattern.
+ *
+ * Reach for `RegExp` when you need to build a regular expression from user or
+ * data-driven text, check whether an unknown value is already a `RegExp`, or
+ * access the native constructor without leaving the Effect namespace.
+ *
+ * **Common tasks**
+ *
+ * - Construct expressions with the native constructor: {@link RegExp}
+ * - Narrow unknown input to `RegExp`: {@link isRegExp}
+ * - Escape literal text before interpolating it into a pattern: {@link escape}
+ *
+ * **Gotchas**
+ *
+ * - {@link escape} only escapes regular expression metacharacters in a string.
+ *   It does not add anchors, flags, grouping, or validation for a full pattern.
+ *
+ * **Quickstart**
+ *
+ * **Example** (Matching literal text)
+ *
+ * ```ts
+ * import { RegExp } from "effect"
+ *
+ * const literal = "a+b.txt"
+ * const expression = new RegExp.RegExp(`^${RegExp.escape(literal)}$`)
+ *
+ * console.log(expression.test("a+b.txt")) // true
+ * console.log(expression.test("aaab.txt")) // false
+ * console.log(RegExp.isRegExp(expression)) // true
+ * ```
  *
  * @since 2.0.0
  */
 import * as predicate from "./Predicate.ts"
 
 /**
- * Re-exports the JavaScript `RegExp` constructor from `globalThis`.
+ * Exposes the JavaScript regular expression constructor from `globalThis`.
+ *
+ * **When to use**
+ *
+ * Use to construct JavaScript regular expressions through the Effect module
+ * namespace.
  *
  * **Example** (Creating a regular expression)
  *
@@ -27,7 +65,11 @@ import * as predicate from "./Predicate.ts"
 export const RegExp = globalThis.RegExp
 
 /**
- * Tests if a value is a `RegExp`.
+ * Checks whether a value is a `RegExp`.
+ *
+ * **When to use**
+ *
+ * Use to validate unknown input before treating it as a regular expression.
  *
  * **Example** (Checking for regular expressions)
  *
@@ -47,6 +89,10 @@ export const isRegExp: (input: unknown) => input is RegExp = predicate.isRegExp
 /**
  * Escapes special characters in a regular expression pattern.
  *
+ * **When to use**
+ *
+ * Use to turn literal text into a safe regular expression pattern fragment.
+ *
  * **Example** (Escaping a pattern string)
  *
  * ```ts