effect 4.0.0-beta.71 → 4.0.0-beta.73

package/dist/Effect.js

@@ -19,7 +19,7 @@ import { internalCall } from "./Utils.js";
  */
 export const TypeId = core.EffectTypeId;
 /**
- * Tests if a value is an `Effect`.
+ * Checks whether a value is an `Effect`.
  *
  * **Example** (Checking whether a value is an Effect)
  *
@@ -440,11 +440,9 @@ export const promise = internal.promise;
  *
  * **When to use**
  *
- * Use when in situations where you need to perform asynchronous operations that might
- * fail, such as fetching data from an API, you can use the `tryPromise`
- * constructor. This constructor is designed to handle operations that could
- * throw exceptions by capturing those exceptions and transforming them into
- * manageable errors.
+ * Use when you need to perform asynchronous operations that might fail, such
+ * as fetching data from an API, and want thrown exceptions or rejected promises
+ * captured as Effect errors.
  *
  * **Details**
  *
@@ -564,7 +562,7 @@ export const succeedNone = internal.succeedNone;
  */
 export const succeedSome = internal.succeedSome;
 /**
- * Delays the creation of an `Effect` until it is actually needed.
+ * Creates an `Effect` lazily, delaying construction until it is needed.
  *
  * **When to use**
  *
@@ -764,8 +762,8 @@ export const callback = internal.callback;
  */
 export const never = internal.never;
 /**
- * An `Effect` containing an empty record `{}`, used as the starting point for
- * do notation chains.
+ * Effect that succeeds with an empty record `{}`, used as the starting point
+ * for do notation chains.
  *
  * **Example** (Starting do notation)
  *
@@ -936,10 +934,13 @@ export const fail = internal.fail;
 /**
  * Creates an `Effect` that represents a recoverable error using a lazy evaluation.
  *
+ * **When to use**
+ *
+ * Use to defer computing a recoverable error value until the effect is run.
+ *
  * **Details**
  *
- * This function is useful when you need to create an error effect but want to
- * defer the computation of the error value until the effect is actually run.
+ * The error-producing function is evaluated each time the effect is executed.
  *
  * **Example** (Lazily creating failures)
  *
@@ -986,10 +987,13 @@ export const failCause = internal.failCause;
 /**
  * Creates an `Effect` that represents a failure with a `Cause` computed lazily.
  *
+ * **When to use**
+ *
+ * Use to defer computing a full `Cause` until the effect is run.
+ *
  * **Details**
  *
- * This function is useful when you need to create a failure effect with a
- * complex cause but want to defer the computation until the effect is run.
+ * The cause-producing function is evaluated each time the effect is executed.
  *
  * **Example** (Lazily creating a Cause)
  *
@@ -1480,7 +1484,7 @@ export const andThen = internal.andThen;
  */
 export const tap = internal.tap;
 /**
- * Encapsulates both success and failure of an `Effect` into a `Result` type.
+ * Converts both success and failure of an `Effect` into a `Result` type.
  *
  * **When to use**
  *
@@ -1535,7 +1539,7 @@ export const tap = internal.tap;
  */
 export const result = internal.result;
 /**
- * Convert success to `Option.some` and failure to `Option.none`.
+ * Converts success to `Option.some` and failure to `Option.none`.
  *
  * **When to use**
  *
@@ -1715,9 +1719,7 @@ export const map = internal.map;
  */
 export const as = internal.as;
 /**
- * This function maps the success value of an `Effect` value to a `Some` value
- * in an `Option` value. If the original `Effect` value fails, the returned
- * `Effect` value will also fail.
+ * Maps the success value of an `Effect` to `Some`, preserving failures.
  *
  * **Example** (Wrapping success in Option.some)
  *
@@ -1735,10 +1737,7 @@ export const as = internal.as;
  */
 export const asSome = internal.asSome;
 /**
- * This function maps the success value of an `Effect` value to `void`. If the
- * original `Effect` value succeeds, the returned `Effect` value will also
- * succeed. If the original `Effect` value fails, the returned `Effect` value
- * will fail with the same error.
+ * Maps the success value of an `Effect` to `void`, preserving failures.
  *
  * **Example** (Discarding success values)
  *
@@ -1756,15 +1755,16 @@ export const asSome = internal.asSome;
  */
 export const asVoid = internal.asVoid;
 /**
- * The `flip` function swaps the success and error channels of an effect,
- * so that the success becomes the error, and the error becomes the success.
+ * Swaps an effect's success and failure channels.
+ *
+ * **When to use**
+ *
+ * Use to handle the failure value as a success, or to move the success value
+ * into the failure channel.
  *
  * **Details**
  *
- * This function is useful when you need to reverse the flow of an effect,
- * treating the previously successful values as errors and vice versa. This can
- * be helpful in scenarios where you want to handle a success as a failure or
- * treat an error as a valid result.
+ * For an `Effect<A, E, R>`, the returned effect has type `Effect<E, A, R>`.
  *
  * **Example** (Swapping success and failure channels)
  *
@@ -1868,9 +1868,8 @@ export const zip = internal.zip;
  *
  * **When to use**
  *
- * Use when the `zipWith` function is similar to {@link zip}, but instead of returning a
- * tuple of results, it applies a provided function to the results of the two
- * effects, combining them into a single value.
+ * Use when you need to run two effects sequentially and combine their results
+ * with a function instead of keeping the results as a tuple.
  *
  * **Details**
  *
@@ -1985,12 +1984,9 @@ export const catchTag = internal.catchTag;
  *
  * **When to use**
  *
- * Use when `catchTags` is a convenient way to handle multiple error types at
- * once. Instead of using {@link catchTag} multiple times, you can pass an
- * object where each key is an error type's `_tag`, and the value is the handler
- * for that specific error. This allows you to catch and recover from multiple
- * error types in a single call. You can also provide a fallback handler for
- * unhandled errors.
+ * Use when one recovery step should handle several tagged error types by
+ * matching their readonly `_tag` fields. Pass a handler table whose keys are
+ * tags, plus an optional fallback for unmatched errors.
  *
  * The error type must have a readonly `_tag` field to use `catchTag`. This
  * field is used to identify and match errors.
@@ -2144,10 +2140,8 @@ export const unwrapReason = internal.unwrapReason;
  *
  * **When to use**
  *
- * Use when the `catchCause` function allows you to handle all errors, including
- * unrecoverable defects, by providing a recovery effect. The recovery logic is
- * based on the `Cause` of the error, which provides detailed information about
- * the failure.
+ * Use when recovery needs the full `Cause`, including recoverable failures,
+ * defects, and interruptions, instead of only the typed error value.
  *
  * **Details**
  *
@@ -2226,7 +2220,7 @@ export const catchDefect = internal.catchDefect;
  *
  * **When to use**
  *
- * Use when `catchIf` lets you recover from errors that match a condition. Use a
+ * Use when you need to recover from errors that match a condition. Use a
  * `Refinement` for type narrowing or a `Predicate` for simple boolean
  * matching. Non-matching errors re-fail with the original cause. Defects and
  * interrupts are not caught.
@@ -2385,8 +2379,7 @@ export const catchCauseIf = internal.catchCauseIf;
  */
 export const catchCauseFilter = internal.catchCauseFilter;
 /**
- * The `mapError` function is used to transform or modify the error
- * produced by an effect, without affecting its success value.
+ * Transforms the failure value of an effect without changing its success value.
  *
  * **When to use**
  *
@@ -2394,10 +2387,8 @@ export const catchCauseFilter = internal.catchCauseFilter;
  *
  * **Details**
  *
- * This function is helpful when you want to enhance the error with additional
- * information, change the error type, or apply custom error handling while
- * keeping the original behavior of the effect's success values intact. It only
- * operates on the error channel and leaves the success channel unchanged.
+ * Only the failure channel is transformed. The success channel and requirements
+ * are preserved.
  *
  * **Example** (Transforming the error channel)
  *
@@ -2604,7 +2595,7 @@ export const tapErrorTag = internal.tapErrorTag;
  */
 export const tapCause = internal.tapCause;
 /**
- * Conditionally executes a side effect based on the cause of a failed effect.
+ * Executes a side effect conditionally when a failed effect's cause matches a predicate.
  *
  * **Details**
  *
@@ -2636,7 +2627,7 @@ export const tapCause = internal.tapCause;
  */
 export const tapCauseIf = internal.tapCauseIf;
 /**
- * Conditionally executes a side effect based on the cause of a failed effect.
+ * Executes a side effect conditionally when a failed effect's cause passes a filter.
  *
  * **When to use**
  *
@@ -2887,9 +2878,8 @@ export const sandbox = internal.sandbox;
  *
  * **When to use**
  *
- * Use when `ignore` allows you to run an effect without caring about its result, whether
- * it succeeds or fails. This is useful when you only care about the side
- * effects of the effect and do not need to handle or process its outcome.
+ * Use when an effect should run for its side effects while both success and
+ * failure values are discarded.
  *
  * Use the `log` option to emit the full {@link Cause} when the effect fails,
  * and `message` to prepend a custom log message.
@@ -2947,7 +2937,7 @@ export const ignore = internal.ignore;
  */
 export const ignoreCause = internal.ignoreCause;
 /**
- * Apply an `ExecutionPlan` to an effect, retrying with step-provided resources
+ * Applies an `ExecutionPlan` to an effect, retrying with step-provided resources
  * until it succeeds or the plan is exhausted.
  *
  * **Details**
@@ -3205,8 +3195,8 @@ export const timeoutOption = internal.timeoutOption;
  *
  * **Details**
  *
- * This function is useful when you want to set a maximum duration for an operation
- * and provide an alternative action if the timeout is exceeded.
+ * The fallback effect is created lazily by `orElse` and may introduce its own
+ * success, failure, and requirement types.
  *
  * **Gotchas**
  *
@@ -3295,7 +3285,7 @@ export const delay = internal.delay;
  */
 export const sleep = internal.sleep;
 /**
- * Measures the runtime of an effect and returns the duration with its result.
+ * Returns the runtime duration of an effect together with its result.
  *
  * **Details**
  *
@@ -3493,7 +3483,7 @@ export const filter = internal.filter;
  */
 export const filterMap = internal.filterMap;
 /**
- * Effectfully filters and maps elements of an iterable with a `FilterEffect`.
+ * Filters and maps elements of an iterable effectfully with a `FilterEffect`.
  *
  * **When to use**
  *
@@ -3626,7 +3616,7 @@ export const filterMapOrFail = internal.filterMapOrFail;
 // Conditional Operators
 // -----------------------------------------------------------------------------
 /**
- * Conditionally runs an effect based on the result of an effectful boolean
+ * Runs an effect conditionally based on the result of an effectful boolean
  * condition.
  *
  * **When to use**
@@ -3823,7 +3813,7 @@ export const matchCause = internal.matchCause;
  */
 export const matchCauseEager = internal.matchCauseEager;
 /**
- * Eagerly handles success or failure with effectful handlers when the effect is already resolved.
+ * Handles success or failure eagerly with effectful handlers when the effect is already resolved.
  *
  * **When to use**
  *
@@ -4232,6 +4222,11 @@ export const service = internal.service;
 /**
  * Optionally accesses a service from the environment.
  *
+ * **When to use**
+ *
+ * Use to read an optional dependency from the current context without making
+ * that dependency part of the effect's required environment.
+ *
  * **Details**
  *
  * This function attempts to access a service from the environment. If the
@@ -4344,8 +4339,7 @@ export const updateContext = internal.updateContext;
  */
 export const updateService = internal.updateService;
 /**
- * The `provideService` function is used to provide an actual
- * implementation for a service in the context of an effect.
+ * Provides one concrete service implementation to an effect.
  *
  * **When to use**
  *
@@ -4353,11 +4347,8 @@ export const updateService = internal.updateService;
  *
  * **Details**
  *
- * This function allows you to associate a service with its implementation so
- * that it can be used in your program. You define the service (e.g., a random
- * number generator), and then you use `provideService` to link that
- * service to its implementation. Once the implementation is provided, the
- * effect can be run successfully without further requirements.
+ * The service requirement identified by the `Context.Key` is removed from the
+ * effect requirements after the implementation is provided.
  *
  * **Example** (Providing a service value)
  *
@@ -4524,9 +4515,16 @@ export const withConcurrency = internal.withConcurrency;
  */
 export const scope = internal.scope;
 /**
- * Scopes all resources used in this workflow to the lifetime of the workflow,
- * ensuring that their finalizers are run as soon as this workflow completes
- * execution, whether by success, failure, or interruption.
+ * Runs an effect with a scope that closes when the effect completes.
+ *
+ * **When to use**
+ *
+ * Use to acquire scoped resources for the duration of a single workflow.
+ *
+ * **Details**
+ *
+ * Finalizers for resources acquired inside the workflow run as soon as the
+ * workflow completes, whether by success, failure, or interruption.
  *
  * **Example** (Running a scoped acquisition)
  *
@@ -4659,8 +4657,7 @@ export const scopedWith = internal.scopedWith;
  */
 export const acquireRelease = internal.acquireRelease;
 /**
- * This function constructs a scoped resource from an Effect that acquires a
- * disposable value.
+ * Acquires a scoped resource that implements JavaScript disposal protocols.
  *
  * **When to use**
  *
@@ -4706,10 +4703,7 @@ export const acquireRelease = internal.acquireRelease;
  */
 export const acquireDisposable = internal.acquireDisposable;
 /**
- * This function is used to ensure that an `Effect` value that represents the
- * acquisition of a resource (for example, opening a file, launching a thread,
- * etc.) will not be interrupted, and that the resource will always be released
- * when the `Effect` value completes execution.
+ * Runs resource acquisition, usage, and release as one bracketed effect.
  *
  * **When to use**
  *
@@ -4787,9 +4781,7 @@ export const acquireDisposable = internal.acquireDisposable;
  */
 export const acquireUseRelease = internal.acquireUseRelease;
 /**
- * This function adds a finalizer to the scope of the calling `Effect` value.
- * The finalizer is guaranteed to be run when the scope is closed, and it may
- * depend on the `Exit` value that the scope is closed with.
+ * Adds a finalizer to the current scope.
  *
  * **When to use**
  *
@@ -4797,9 +4789,8 @@ export const acquireUseRelease = internal.acquireUseRelease;
  *
  * **Details**
  *
- * Finalizers are useful for cleanup operations that must run regardless of
- * whether the effect succeeds or fails. They're commonly used for resource
- * cleanup, logging, or other side effects that should always occur.
+ * The finalizer runs when the surrounding scope is closed and receives the
+ * `Exit` value used to close the scope.
  *
  * **Example** (Registering scope finalizers)
  *
@@ -4973,8 +4964,8 @@ export const onErrorFilter = internal.onErrorFilter;
  */
 export const onExitPrimitive = internal.onExitPrimitive;
 /**
- * Ensures that a cleanup functions runs, whether this effect succeeds, fails,
- * or is interrupted.
+ * Ensures that a cleanup function runs whether this effect succeeds, fails, or
+ * is interrupted.
  *
  * **Example** (Observing every exit)
  *
@@ -5180,18 +5171,14 @@ export const cached = internal.cached;
  */
 export const cachedWithTTL = internal.cachedWithTTL;
 /**
- * Caches an effect's result for a specified duration and allows manual
+ * Creates a cached effect result for a specified duration and allows manual
  * invalidation before expiration.
  *
  * **When to use**
  *
- * Use when you use this function when you have an effect whose result needs to be cached for
- * a certain period, but you also want the option to refresh the cache manually
- * before the expiration time.
- *
- * This is useful when you need to ensure that the cached data remains valid for
- * a certain period but still want to invalidate it if the underlying data
- * changes or if you want to force a recomputation.
+ * Use when an effect result should be cached for a bounded time and callers
+ * also need a manual invalidation effect to force recomputation before
+ * expiration.
  *
  * **Details**
  *
@@ -5376,9 +5363,8 @@ export const uninterruptible = internal.uninterruptible;
  */
 export const uninterruptibleMask = internal.uninterruptibleMask;
 /**
- * This function behaves like {@link interruptible}, but it also provides a
- * `restore` function. This function can be used to restore the interruptibility
- * of any specific region of code.
+ * Runs an effect in an interruptible region while providing `restore` for
+ * locally restoring the previous interruptibility.
  *
  * **Example** (Controlling interruptibility locally)
  *
@@ -5967,7 +5953,7 @@ export const spanAnnotations = internal.spanAnnotations;
  */
 export const spanLinks = internal.spanLinks;
 /**
- * For all spans in this effect, add a link with the provided span.
+ * Adds a link with the provided span to all spans in this effect.
  *
  * **Details**
  *
@@ -6103,7 +6089,7 @@ export const makeSpanScoped = internal.makeSpanScoped;
  */
 export const useSpan = internal.useSpan;
 /**
- * Wraps the effect with a new span for tracing.
+ * Wraps the effect with a child span for tracing.
  *
  * **Example** (Wrapping an effect in a child span)
  *
@@ -6125,7 +6111,7 @@ export const useSpan = internal.useSpan;
  */
 export const withSpan = internal.withSpan;
 /**
- * Wraps the effect with a new span for tracing.
+ * Wraps the effect with a scoped child span for tracing.
  *
  * **Details**
  *
@@ -6213,7 +6199,7 @@ export const withParentSpan = internal.withParentSpan;
  */
 export const request = internalRequest.request;
 /**
- * Low-level entry point that registers a request with a resolver and delivers the exit value via `onExit`.
+ * Registers a request with a resolver and delivers the exit value via `onExit`.
  *
  * **When to use**
  *
@@ -6404,7 +6390,7 @@ export const forkDetach = internal.forkDetach;
  */
 export const awaitAllChildren = internal.awaitAllChildren;
 /**
- * Access the fiber currently executing the effect.
+ * Accesses the fiber currently executing the effect.
  *
  * **Example** (Accessing the current fiber)
  *
@@ -6422,7 +6408,7 @@ export const awaitAllChildren = internal.awaitAllChildren;
  */
 export const fiber = internal.fiber;
 /**
- * Access the current fiber id executing the effect.
+ * Accesses the current fiber id executing the effect.
  *
  * **Example** (Accessing the current fiber id)
  *
@@ -6445,17 +6431,14 @@ export const fiber = internal.fiber;
  */
 export const fiberId = internal.fiberId;
 /**
- * The foundational function for running effects, returning a "fiber" that can
+ * Runs an effect in the background, returning a fiber that can
  * be observed or interrupted.
  *
  * **When to use**
  *
- * Use when `runFork` is used to run an effect in the background by creating a
- * fiber. It is the base function for all other run functions. It starts a fiber
- * that can be observed or interrupted.
- *
- * Unless you specifically need a `Promise` or synchronous operation,
- * `runFork` is a good default choice.
+ * Use when an effect should start in the background and return a fiber that can
+ * be observed or interrupted. Prefer this when you do not need a `Promise` or
+ * synchronous result.
  *
  * **Example** (Running an effect in the background)
  *
@@ -6754,7 +6737,8 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
  *
  * **When to use**
  *
- * Use when you use `runSync` only for effects that can complete synchronously.
+ * Use when you need to execute an effect that is guaranteed to complete
+ * synchronously.
  *
  * **Details**
  *
@@ -6841,7 +6825,7 @@ export const runSync = internal.runSync;
  */
 export const runSyncWith = internal.runSyncWith;
 /**
- * Runs an effect synchronously and returns the result as an `Exit` type, which
+ * Runs an effect synchronously and captures the outcome safely as an `Exit` type, which
  * represents the outcome (success or failure) of the effect.
  *
  * **When to use**
@@ -6915,7 +6899,7 @@ export const runSyncWith = internal.runSyncWith;
  */
 export const runSyncExit = internal.runSyncExit;
 /**
- * Runs an effect synchronously with provided services, returning an Exit result.
+ * Runs an effect synchronously with provided services, returning an Exit result safely.
  *
  * **Example** (Running synchronously with services as Exit)
  *
@@ -7697,12 +7681,12 @@ export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
 // Transactions
 // -----------------------------------------------------------------------------
 /**
- * Service that holds the current transaction state, it includes
+ * Service that holds the current transaction state.
  *
  * **Details**
  *
- * - a journal that stores any non committed change to TxRef values
- * - a retry flag to know if the transaction should be retried
+ * It includes a journal that stores non-committed changes to `TxRef` values and
+ * a retry flag that records whether the transaction should be retried.
  *
  * **Example** (Building transactions)
  *
@@ -7843,7 +7827,7 @@ function clearTransaction(state) {
   state.journal.clear();
 }
 /**
- * Signals that the current transaction needs to be retried.
+ * Retries the current transaction by signaling that it must be retried.
  *
  * **Details**
  *
@@ -8039,14 +8023,12 @@ export const satisfiesErrorType = () => effect => effect;
  */
 export const satisfiesServicesType = () => effect => effect;
 /**
- * An optimized version of `map` that checks if an effect is already resolved
- * and applies the mapping function eagerly when possible.
+ * Applies `map` eagerly when an effect is already resolved.
  *
  * **When to use**
  *
- * Use when `mapEager` provides better performance for effects that are already resolved
- * by applying the transformation immediately instead of deferring it through
- * the effect pipeline.
+ * Use when an already-resolved effect should apply a success transformation
+ * immediately while pending effects still use regular mapping.
  *
  * **Details**
  *
@@ -8075,14 +8057,13 @@ export const satisfiesServicesType = () => effect => effect;
  */
 export const mapEager = internal.mapEager;
 /**
- * An optimized version of `mapError` that checks if an effect is already resolved
- * and applies the error mapping function eagerly when possible.
+ * Applies `mapError` eagerly when an effect is already resolved.
  *
  * **When to use**
  *
- * Use when `mapErrorEager` provides better performance for effects that are already resolved
- * by applying the error transformation immediately instead of deferring it through
- * the effect pipeline.
+ * Use when an already-resolved failed effect should apply an error
+ * transformation immediately while pending effects still use regular error
+ * mapping.
  *
  * **Details**
  *
@@ -8114,14 +8095,12 @@ export const mapEager = internal.mapEager;
  */
 export const mapErrorEager = internal.mapErrorEager;
 /**
- * An optimized version of `mapBoth` that checks if an effect is already resolved
- * and applies the appropriate mapping function eagerly when possible.
+ * Applies `mapBoth` eagerly when an effect is already resolved.
  *
  * **When to use**
  *
- * Use when `mapBothEager` provides better performance for effects that are already resolved
- * by applying the transformation immediately instead of deferring it through
- * the effect pipeline.
+ * Use when an already-resolved effect should transform either success or
+ * failure immediately while pending effects still use regular channel mapping.
  *
  * **Details**
  *
@@ -8155,14 +8134,12 @@ export const mapErrorEager = internal.mapErrorEager;
  */
 export const mapBothEager = internal.mapBothEager;
 /**
- * An optimized version of `flatMap` that checks if an effect is already resolved
- * and applies the flatMap function eagerly when possible.
+ * Applies `flatMap` eagerly when an effect is already resolved.
  *
  * **When to use**
  *
- * Use when `flatMapEager` provides better performance for effects that are already resolved
- * by applying the transformation immediately instead of deferring it through
- * the effect pipeline.
+ * Use when an already-resolved successful effect should bind immediately to the
+ * next effect while pending effects still use regular flat mapping.
  *
  * **Details**
  *
@@ -8194,14 +8171,12 @@ export const mapBothEager = internal.mapBothEager;
  */
 export const flatMapEager = internal.flatMapEager;
 /**
- * An optimized version of `catch` that checks if an effect is already resolved
- * and applies the catch function eagerly when possible.
+ * Applies `catch` eagerly when an effect is already resolved.
  *
  * **When to use**
  *
- * Use when `catchEager` provides better performance for effects that are already resolved
- * by applying the error recovery immediately instead of deferring it through
- * the effect pipeline.
+ * Use when an already-resolved failed effect should recover immediately while
+ * pending effects still use regular error recovery.
  *
  * **Details**
  *