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

package/dist/References.js

@@ -4,51 +4,115 @@ import { MaxOpsBeforeYield, PreventSchedulerYield } from "./Scheduler.js";
 import { CurrentTraceLevel, DisablePropagation, MinimumTraceLevel, Tracer } from "./Tracer.js";
 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
  */
 Tracer };
 /**
- * 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
@@ -86,9 +150,14 @@ Tracer };
  */
 export const CurrentConcurrency = 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
@@ -142,9 +211,14 @@ export const CurrentConcurrency = references.CurrentConcurrency;
  */
 export const CurrentLogAnnotations = 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.
@@ -189,9 +263,14 @@ export const CurrentLogAnnotations = references.CurrentLogAnnotations;
  */
 export const CurrentLogLevel = 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
@@ -250,23 +329,34 @@ export const CurrentLogLevel = references.CurrentLogLevel;
  */
 export const CurrentLogSpans = 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 = 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
@@ -315,9 +405,13 @@ export const CurrentStackFrame = references.CurrentStackFrame;
  */
 export const MinimumLogLevel = 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
@@ -361,9 +455,13 @@ export const MinimumLogLevel = references.MinimumLogLevel;
  */
 export const TracerEnabled = 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
@@ -413,9 +511,13 @@ export const TracerEnabled = references.TracerEnabled;
  */
 export const TracerSpanAnnotations = 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
@@ -475,10 +577,14 @@ export const TracerSpanAnnotations = references.TracerSpanAnnotations;
  */
 export const TracerSpanLinks = 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
@@ -518,19 +624,42 @@ 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.
+ * 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
  */
 export const UnhandledLogLevel = references.UnhandledLogLevel;
 /**
- * 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.
  *
@@ -539,12 +668,17 @@ export const UnhandledLogLevel = references.UnhandledLogLevel;
  */
 export const CurrentLoggers = 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
@@ -552,9 +686,14 @@ export const CurrentLoggers = internalEffect.CurrentLoggers;
 export const LogToStderr = internalEffect.LogToStderr;
 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/dist/References.js.map

@@ -1 +1 @@
-{"version":3,"file":"References.js","names":["internalEffect","references","MaxOpsBeforeYield","PreventSchedulerYield","CurrentTraceLevel","DisablePropagation","MinimumTraceLevel","Tracer","CurrentConcurrency","CurrentLogAnnotations","CurrentLogLevel","CurrentLogSpans","CurrentStackFrame","MinimumLogLevel","TracerEnabled","TracerSpanAnnotations","TracerSpanLinks","TracerTimingEnabled","UnhandledLogLevel","CurrentLoggers","LogToStderr","Scheduler"],"sources":["../src/References.ts"],"sourcesContent":[null],"mappings":"AAaA,OAAO,KAAKA,cAAc,MAAM,sBAAsB;AACtD,OAAO,KAAKC,UAAU,MAAM,0BAA0B;AAItD,SAASC,iBAAiB,EAAEC,qBAAqB,QAAQ,gBAAgB;AACzE,SAASC,iBAAiB,EAAEC,kBAAkB,EAAEC,iBAAiB,EAAiBC,MAAM,QAAQ,aAAa;AAE7G;AACE;;;;;;AAMAH,iBAAiB;AACjB;;;;;;AAMAC,kBAAkB;AAClB;;;;;;AAMAH,iBAAiB;AACjB;;;;;;AAMAI,iBAAiB;AACjB;;;;;;AAMAH,qBAAqB;AACrB;;;;;;AAMAI,MAAM;AAGR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,OAAO,MAAMC,kBAAkB,GAA4CP,UAAU,CAACO,kBAAkB;AAExG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,OAAO,MAAMC,qBAAqB,GAChCR,UAAU,CAACQ,qBAAqB;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,OAAO,MAAMC,eAAe,GAAgCT,UAAU,CAACS,eAAe;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,OAAO,MAAMC,eAAe,GAC1BV,UAAU,CAACU,eAAe;AAE5B;;;;;;;;;;;;;AAaA,OAAO,MAAMC,iBAAiB,GAA8CX,UAAU,CAACW,iBAAiB;AAExG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,OAAO,MAAMC,eAAe,GAAgCZ,UAAU,CAACY,eAAe;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,OAAO,MAAMC,aAAa,GAA+Bb,UAAU,CAACa,aAAa;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,OAAO,MAAMC,qBAAqB,GAChCd,UAAU,CAACc,qBAAqB;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,OAAO,MAAMC,eAAe,GAA+Cf,UAAU,CAACe,eAAe;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,OAAO,MAAMC,mBAAmB,GAA+BhB,UAAU,CAACgB,mBAAmB;AAE7F;;;;;;;AAOA,OAAO,MAAMC,iBAAiB,GAA4CjB,UAAU,CAACiB,iBAAiB;AAmBtG;;;;;;;;;;;;AAYA,OAAO,MAAMC,cAAc,GAAyDnB,cAAc,CAACmB,cAAc;AAEjH;;;;;;;;;;;AAWA,OAAO,MAAMC,WAAW,GAA+BpB,cAAc,CAACoB,WAAW;AAEjF;AACE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCAC,SAAS,QACJ,gBAAgB","ignoreList":[]}
+{"version":3,"file":"References.js","names":["internalEffect","references","MaxOpsBeforeYield","PreventSchedulerYield","CurrentTraceLevel","DisablePropagation","MinimumTraceLevel","Tracer","CurrentConcurrency","CurrentLogAnnotations","CurrentLogLevel","CurrentLogSpans","CurrentStackFrame","MinimumLogLevel","TracerEnabled","TracerSpanAnnotations","TracerSpanLinks","TracerTimingEnabled","UnhandledLogLevel","CurrentLoggers","LogToStderr","Scheduler"],"sources":["../src/References.ts"],"sourcesContent":[null],"mappings":"AA+DA,OAAO,KAAKA,cAAc,MAAM,sBAAsB;AACtD,OAAO,KAAKC,UAAU,MAAM,0BAA0B;AAItD,SAASC,iBAAiB,EAAEC,qBAAqB,QAAQ,gBAAgB;AACzE,SAASC,iBAAiB,EAAEC,kBAAkB,EAAEC,iBAAiB,EAAiBC,MAAM,QAAQ,aAAa;AAE7G;AACE;;;;;;;;;;;;;AAaAH,iBAAiB;AACjB;;;;;;;;;;;;;;;;;;AAkBAC,kBAAkB;AAClB;;;;;;;;;;;;;;;;;AAiBAH,iBAAiB;AACjB;;;;;;;;;;;;;AAaAI,iBAAiB;AACjB;;;;;;;;;;;;;;;;;;;;;;;AAuBAH,qBAAqB;AACrB;;;;;;;;;;;AAWAI,MAAM;AAGR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,OAAO,MAAMC,kBAAkB,GAA4CP,UAAU,CAACO,kBAAkB;AAExG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,OAAO,MAAMC,qBAAqB,GAChCR,UAAU,CAACQ,qBAAqB;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,OAAO,MAAMC,eAAe,GAAgCT,UAAU,CAACS,eAAe;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,OAAO,MAAMC,eAAe,GAC1BV,UAAU,CAACU,eAAe;AAE5B;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAMC,iBAAiB,GAA8CX,UAAU,CAACW,iBAAiB;AAExG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,OAAO,MAAMC,eAAe,GAAgCZ,UAAU,CAACY,eAAe;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,OAAO,MAAMC,aAAa,GAA+Bb,UAAU,CAACa,aAAa;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,OAAO,MAAMC,qBAAqB,GAChCd,UAAU,CAACc,qBAAqB;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,OAAO,MAAMC,eAAe,GAA+Cf,UAAU,CAACe,eAAe;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,OAAO,MAAMC,mBAAmB,GAA+BhB,UAAU,CAACgB,mBAAmB;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,MAAMC,iBAAiB,GAA4CjB,UAAU,CAACiB,iBAAiB;AA0BtG;;;;;;;;;;;;;;;;;;AAkBA,OAAO,MAAMC,cAAc,GAAyDnB,cAAc,CAACmB,cAAc;AAEjH;;;;;;;;;;;;;;;;AAgBA,OAAO,MAAMC,WAAW,GAA+BpB,cAAc,CAACoB,WAAW;AAEjF;AACE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCAC,SAAS,QACJ,gBAAgB","ignoreList":[]}

package/dist/RegExp.d.ts

@@ -1,5 +1,10 @@
 /**
- * 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)
  *
@@ -19,7 +24,11 @@
  */
 export declare const RegExp: RegExpConstructor;
 /**
- * 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)
  *
@@ -38,6 +47,10 @@ export declare const isRegExp: (input: unknown) => input is RegExp;
 /**
  * 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

package/dist/RegExp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RegExp.d.ts","sourceRoot":"","sources":["../src/RegExp.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,MAAM,mBAAoB,CAAA;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,MAA2B,CAAA;AAE/E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,GAAI,QAAQ,MAAM,KAAG,MAAwD,CAAA"}
+{"version":3,"file":"RegExp.d.ts","sourceRoot":"","sources":["../src/RegExp.ts"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,MAAM,mBAAoB,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,MAA2B,CAAA;AAE/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,MAAM,GAAI,QAAQ,MAAM,KAAG,MAAwD,CAAA"}

package/dist/RegExp.js

@@ -1,11 +1,49 @@
 /**
- * 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.js";
 /**
- * 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)
  *
@@ -25,7 +63,11 @@ import * as predicate from "./Predicate.js";
  */
 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)
  *
@@ -44,6 +86,10 @@ export const isRegExp = 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

package/dist/RegExp.js.map

@@ -1 +1 @@
-{"version":3,"file":"RegExp.js","names":["predicate","RegExp","globalThis","isRegExp","escape","string","replace"],"sources":["../src/RegExp.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;AAKA,OAAO,KAAKA,SAAS,MAAM,gBAAgB;AAE3C;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,MAAMC,MAAM,GAAGC,UAAU,CAACD,MAAM;AAEvC;;;;;;;;;;;;;;;;AAgBA,OAAO,MAAME,QAAQ,GAAwCH,SAAS,CAACG,QAAQ;AAE/E;;;;;;;;;;;;;;;AAeA,OAAO,MAAMC,MAAM,GAAIC,MAAc,IAAaA,MAAM,CAACC,OAAO,CAAC,sBAAsB,EAAE,MAAM,CAAC","ignoreList":[]}
+{"version":3,"file":"RegExp.js","names":["predicate","RegExp","globalThis","isRegExp","escape","string","replace"],"sources":["../src/RegExp.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,OAAO,KAAKA,SAAS,MAAM,gBAAgB;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,MAAMC,MAAM,GAAGC,UAAU,CAACD,MAAM;AAEvC;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAME,QAAQ,GAAwCH,SAAS,CAACG,QAAQ;AAE/E;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,MAAMC,MAAM,GAAIC,MAAc,IAAaA,MAAM,CAACC,OAAO,CAAC,sBAAsB,EAAE,MAAM,CAAC","ignoreList":[]}