Effect
Describes workflows that run only when executed by the Effect runtime.
An Effect<A, E, R> can succeed with an A, fail with an E, and require services R. Creating an effect does not perform the work; it builds a value that can be composed, provided with services, retried, interrupted, run concurrently, or inspected by the runtime. This module is the main API for creating effects, combining them, handling failures, managing resources, and running effect programs.
Accessors
Signature
declare const clockWith: <A, E, R>(f: (clock: Clock) => Effect<A, E, R>) => Effect<A, E, R>;Returns the complete context.
When to use
Use to read the complete Context available to the current effect.
Details
This function allows you to access all services that are currently available in the effect's environment. This can be useful for debugging, introspection, or when you need to pass the entire context to another function.
See
contextWithfor deriving an effect from the complete contextservicefor reading one service from the context
Signature
declare const context: <R = never>() => Effect<Context.Context<R>, never, R>;contextWith
Transforms the current context using the provided function.
When to use
Use to derive an effect from the complete Context.
Details
This function allows you to access the complete context and perform computations based on all available services. This is useful when you need to conditionally execute logic based on what services are available.
See
Signature
declare const contextWith: <R, A, E, R2>(
f: (context: Context.Context<R>) => Effect<A, E, R2>,
) => Effect<A, E, R | R2>;Accesses the fiber currently executing the effect.
Signature
declare const fiber: Effect<Fiber<unknown, unknown>>;Accesses the current fiber id executing the effect.
Signature
declare const fiberId: Effect<number>;Accesses a service from the context.
Signature
declare const service: <I, S>(service: Context.Key<I, S>) => Effect<S, never, I>;serviceOption
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 service is available, it returns Some(service). If the service is not available, it returns None. Unlike service, this function does not require the service to be present in the environment.
Signature
declare const serviceOption: <I, S>(key: Context.Key<I, S>) => Effect<Option<S>>;Caching
Returns an effect that lazily computes a result and caches it for subsequent evaluations.
When to use
Use when you need an expensive or time-consuming operation to be evaluated once and reused by later callers.
Details
This function wraps an effect and ensures that its result is computed only once. Once the result is computed, it is cached, meaning that subsequent evaluations of the same effect will return the cached result without re-executing the logic.
See
cachedWithTTLfor a similar function that includes a time-to-live duration for the cached value.cachedInvalidateWithTTLfor a similar function that includes an additional effect for manually invalidating the cached value.
Signature
declare const cached: <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>;cachedInvalidateWithTTL
Creates a cached effect result for a specified duration and allows manual invalidation before expiration.
When to use
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
This function behaves similarly to cachedWithTTL by caching the result of an effect for a specified period of time. However, it introduces an additional feature: it provides an effect that allows you to manually invalidate the cached result before it naturally expires.
This gives you more control over the cache, allowing you to refresh the result when needed, even if the original cache has not yet expired.
Once the cache is invalidated, the next time the effect is evaluated, the result will be recomputed, and the cache will be refreshed.
See
cachedfor a similar function that caches the result indefinitely.cachedWithTTLfor a similar function that caches the result for a specified duration but does not include an effect for manual invalidation.
Signature
declare const cachedInvalidateWithTTL: {
(
timeToLive: Input,
): <A, E, R>(self: Effect<A, E, R>) => Effect<[Effect<A, E, R>, Effect<void, never, never>]>;
<A, E, R>(
self: Effect<A, E, R>,
timeToLive: Input,
): Effect<[Effect<A, E, R>, Effect<void, never, never>]>;
};cachedWithTTL
Returns an effect that caches its result for a specified Duration, known as "timeToLive" (TTL).
When to use
Use when you need a costly effect result to be reused for a bounded duration before being recomputed.
Details
This function is used to cache the result of an effect for a specified amount of time. This means that the first time the effect is evaluated, its result is computed and stored.
If the effect is evaluated again within the specified timeToLive, the cached result will be used, avoiding recomputation.
After the specified duration has passed, the cache expires, and the effect will be recomputed upon the next evaluation.
See
cachedfor a similar function that caches the result indefinitely.cachedInvalidateWithTTLfor a similar function that includes an additional effect for manually invalidating the cached value.
Signature
declare const cachedWithTTL: {
(timeToLive: Input): <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>;
<A, E, R>(self: Effect<A, E, R>, timeToLive: Input): Effect<Effect<A, E, R>>;
};Combining
Combines an iterable or record of effects into one effect whose success shape follows the input.
When to use
Use to run a known collection of effects and collect results in the same tuple, iterable, or record shape.
Details
Tuple and iterable inputs collect results in order. Record inputs collect results under the same keys. By default, the combined effect fails on the first failure; with concurrent execution, effects that have already started may be interrupted, while effects not yet started are skipped.
Options:
Use concurrency to control sequential or concurrent execution. Use mode: "result" to run every effect and collect each success or failure as a Result in the same output shape. Use discard: true to ignore successful values and return void.
See
forEachfor iterating over elements and applying an effect.
Signature
declare const all: <
Arg extends Iterable<Effect<any, any, any>> | Record<string, Effect<any, any, any>>,
O extends {
readonly concurrency?: Concurrency;
readonly discard?: boolean;
readonly mode?: "default" | "result";
},
>(
arg: Arg,
options?: O,
) => All.Return<Arg, O>;Constructors
Creates an Effect from a callback-based asynchronous API.
When to use
Use when you need to integrate APIs that complete through callbacks instead of returning a Promise.
Details
The registration function receives a resume callback and, when requested, an AbortSignal. Call resume at most once with the effect that should complete the fiber; later calls are ignored. Return an optional cleanup effect from the registration function to run if the fiber is interrupted.
Signature
declare const callback: <A, E = never, R = never>(
register: (
this: Scheduler,
resume: (effect: Effect<A, E, R>) => void,
signal: AbortSignal,
) => void | Effect<void, never, R>,
) => Effect<A, E, R>;Creates an effect that terminates a fiber with a specified error.
When to use
Use when you need an Effect to report an unrecoverable defect instead of a typed error.
Details
The die function is used to signal a defect, which represents a critical and unexpected error in the code. When invoked, it produces an effect that does not handle the error and instead terminates the fiber.
The error channel of the resulting effect is of type never, indicating that it cannot recover from this failure.
Signature
declare const die: (defect: unknown) => Effect<never>;Effect that succeeds with an empty record {}, used as the starting point for do notation chains.
Signature
declare const Do: Effect<{}>;Creates an Effect that represents a recoverable error.
When to use
Use to explicitly signal a recoverable error in an Effect.
Details
The error keeps propagating unless it is handled. You can handle tagged errors with functions like catchTag or catchTags.
See
succeedto create an effect that represents a successful value.
Signature
declare const fail: <E>(error: E) => Effect<never, E>;Creates an Effect that represents a failure with a specific Cause.
When to use
Use when you already have a full Cause and need to preserve defects, interruptions, annotations, or combined failures in the effect's failure channel.
Details
This function allows you to create effects that fail with complex error structures, including multiple errors, defects, interruptions, and more.
Signature
declare const failCause: <E>(cause: Cause.Cause<E>) => Effect<never, E>;failCauseSync
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
The cause-producing function is evaluated each time the effect is executed.
Signature
declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Effect<never, E>;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
The error-producing function is evaluated each time the effect is executed.
Signature
declare const failSync: <E>(evaluate: LazyArg<E>) => Effect<never, E>;Creates a reusable traced function from an Effect body.
When to use
Use when you are defining a reusable Effect function whose implementation would otherwise be a normal function returning gen, and you want tracing spans or stack-frame capture.
Details
Compared to a plain function that returns gen, Effect.fn reuses the generator body instead of allocating a fresh generator closure around the arguments on every call. Call Effect.fn(body, ...) for a generic stack-frame boundary without creating a span. Call Effect.fn("operationName", options?)(body, ...) when that boundary should have a readable operation name and the returned Effect should create a tracing span when run. SpanOptionsNoTrace configures span metadata such as attributes, links, parent or root selection, kind, sampling, and log level. Additional arguments after the generator body act like pipe transforms: each transform receives the previous result and the original function arguments. When those transforms return an Effect, the returned effect includes stack-frame metadata and, for the named form, a tracing span. Generator bodies may declare a this parameter; pass { self } before the body to bind this when the function is created.
Signature
declare const fn: Traced & (name: string, options?: SpanOptionsNoTrace) => TracedfnUntraced
Creates an Effect-returning function without tracing.
When to use
Use when you are defining a reusable Effect function whose implementation would otherwise be a normal function returning gen, especially when tracing spans or stack-frame capture are not needed.
Details
Compared to a plain function that returns gen, Effect.fnUntraced reuses the generator body instead of allocating a fresh generator closure around the arguments on every call. It does not record an Effect stack-frame boundary and does not create tracing spans. Use fn when you need those stack frames or spans. Additional arguments after the generator body act like pipe transforms: each transform receives the previous result and the original function arguments. Annotate the generator return type with Effect.fn.Return<A, E, R> when the produced Effect type needs to be stated explicitly.
Signature
declare const fnUntraced: fn.Untraced;fnUntracedEager
Creates untraced function effects with eager evaluation optimization.
Details
Executes generator functions eagerly when all yielded effects are synchronous, stopping at the first async effect and deferring to normal execution.
Signature
declare const fnUntracedEager: fn.Untraced;Provides a way to write effectful code using generator functions, simplifying control flow and error handling.
When to use
Use when you want to write effectful code that looks and behaves like synchronous code, while still handling asynchronous tasks, errors, and complex control flow such as loops and conditions.
Generator functions work similarly to async/await but keep errors, requirements, and interruption in the Effect type. You can yield* values from effects and return the final result at the end.
Signature
declare const gen: {
<Eff extends Effect<any, any, any>, AEff>(
f: () => Generator<Eff, AEff, never>,
): Effect<
AEff,
[Eff] extends [never] ? never : [Eff] extends [Effect<_A, E, _R>] ? E : never,
[Eff] extends [never] ? never : [Eff] extends [Effect<_A, _E, R>] ? R : never
>;
<Self, Eff extends Effect<any, any, any>, AEff>(
options: {
readonly self: Self;
},
f: (this: Self) => Generator<Eff, AEff, never>,
): Effect<
AEff,
[Eff] extends [never] ? never : [Eff] extends [Effect<_A, E, _R>] ? E : never,
[Eff] extends [never] ? never : [Eff] extends [Effect<_A, _E, R>] ? R : never
>;
};Returns an effect that will never produce anything. The moral equivalent of while(true) {}, only without the wasted CPU cycles.
Signature
declare const never: Effect<never>;Creates an Effect that represents an asynchronous computation guaranteed to succeed.
When to use
Use to convert a Promise into an Effect when the async operation is guaranteed to succeed and will not reject.
Details
An optional AbortSignal can be provided to allow for interruption of the wrapped Promise API.
Gotchas
The Promise must not reject. If it rejects, the rejection is treated as a defect, not as a typed failure. Use tryPromise when rejection is expected.
Interruption aborts the provided AbortSignal, but the underlying asynchronous operation only stops if it observes that signal.
See
tryPromisefor a version that can handle failures.
Signature
declare const promise: <A>(evaluate: (signal: AbortSignal) => PromiseLike<A>) => Effect<A>;Creates an Effect that always succeeds with a given value.
When to use
Use when an effect should complete successfully with a specific value without any errors or external dependencies.
See
failto create an effect that represents a failure.
Signature
declare const succeed: <A>(value: A) => Effect<A>;succeedNone
Returns an effect which succeeds with None.
Signature
declare const succeedNone: Effect<Option<never>>;succeedSome
Returns an effect which succeeds with the value wrapped in a Some.
Signature
declare const succeedSome: <A>(value: A) => Effect<Option<A>>;Creates an Effect lazily, delaying construction until it is needed.
When to use
Use when you need to defer the evaluation of an effect until it is required.
Details
suspend takes a thunk that represents an effect and delays creating it until the suspended effect is evaluated. This is useful for optimizing expensive computations, managing circular dependencies such as recursive functions, and helping TypeScript unify return types when branches construct different effects. Any side effects or scoped captures inside the thunk are re-executed on each invocation.
Signature
declare const suspend: <A, E, R>(effect: LazyArg<Effect<A, E, R>>) => Effect<A, E, R>;Creates an Effect that represents a synchronous side-effectful computation.
When to use
Use when you need to wrap a synchronous side-effectful operation that is not expected to throw.
Details
The provided function is evaluated lazily when the effect runs.
Gotchas
The function must not throw. If it throws, the thrown value is treated as a defect, not as a typed failure. Use try when throwing is expected.
See
tryfor a version that can handle failures.
Signature
declare const sync: <A>(thunk: LazyArg<A>) => Effect<A>;tryPromise
Creates an Effect from an asynchronous computation that may throw or reject, mapping failures into the error channel.
When to use
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
The promise thunk is evaluated when the effect runs. If it returns a promise that resolves, the resolved value becomes the success value. If the thunk throws before returning a promise, or if the returned promise rejects, the thrown or rejected value is mapped into the error channel.
Passing the thunk directly maps failures to Cause.UnknownError. Passing { try, catch } uses catch to map failures to an error of type E.
The thunk receives an AbortSignal that is aborted if the effect is interrupted. The underlying asynchronous operation only stops if it observes that signal.
Gotchas
If catch throws while mapping the error, that thrown value is treated as a defect. Return the error value you want in the error channel instead of throwing it.
See
promiseif the effectful computation is asynchronous and does not throw errors.
Signature
declare const tryPromise: <A, E = Cause.UnknownError>(options: {
readonly catch: (error: unknown) => E;
readonly try: (signal: AbortSignal) => PromiseLike<A>;
} | (signal: AbortSignal) => PromiseLike<A>) => Effect<A, E>Provides access to the current fiber within an effect computation.
Signature
declare const withFiber: <A, E = never, R = never>(
evaluate: (fiber: Fiber<unknown, unknown>) => Effect<A, E, R>,
) => Effect<A, E, R>;Yields control back to the Effect runtime, allowing other fibers to execute.
Signature
declare const yieldNow: Effect<void>;yieldNowWith
Yields control back to the Effect runtime with a specified priority, allowing other fibers to execute.
Signature
declare const yieldNowWith: (priority?: number) => Effect<void>;Converting
Converts an error-first callback API into a function that returns an Effect.
Details
The original function is called with the supplied arguments plus a final callback. A non-null callback error fails the returned effect, while a successful callback value becomes the effect success. Use onError to map callback errors and onSyncError to turn synchronous throws into typed failures; otherwise synchronous throws become defects.
Signature
declare const effectify: {
<F extends (...args: Array<any>) => any>(fn: F): Effectify<F, EffectifyError<F>>;
<F extends (...args: Array<any>) => any, E>(
fn: F,
onError: (error: EffectifyError<F>, args: Parameters<F>) => E,
): Effectify<F, E>;
<F extends (...args: Array<any>) => any, E, E2>(
fn: F,
onError: (error: EffectifyError<F>, args: Parameters<F>) => E,
onSyncError: (error: unknown, args: Parameters<F>) => E2,
): Effectify<F, E | E2>;
};fromNullishOr
Converts a nullable value to an Effect, failing with a NoSuchElementError when the value is null or undefined.
Signature
declare const fromNullishOr: <A>(value: A) => Effect<NonNullable<A>, Cause.NoSuchElementError>;fromOption
Converts an Option into an Effect.
When to use
Use when absence should become a typed NoSuchElementError in the effect error channel.
Details
Option.some becomes a successful effect with the contained value, while Option.none becomes a failed effect. By default the failure is a NoSuchElementError, but you can provide an onNone callback to customize the error value.
Signature
declare const fromOption: <
Arg extends Option<unknown> | LazyArg<unknown>,
E = Cause.NoSuchElementError,
>(
arg: Arg,
...rest: [Arg] extends [Option<unknown>] ? [onNone?: LazyArg<E>] : []
) => [Arg] extends [Option<infer A>]
? Effect<A, E>
: [Arg] extends [LazyArg<infer E>]
? <A>(option: Option<A>) => Effect<A, E>
: never;fromResult
Converts a Result to an Effect.
Signature
declare const fromResult: <A, E>(result: Result.Result<A, E>) => Effect<A, E>;transposeOption
Converts an Option of an Effect into an Effect of an Option.
When to use
Use when an effect should run only when an optional value is present, while preserving absence as a successful None.
Details
- None becomes an effect that succeeds with None - Some(effect) runs the inner effect and wraps its success value in Some - Inner failures are preserved in the resulting effect
Signature
declare const transposeOption: <A = never, E = never, R = never>(
self: Option<Effect<A, E, R>>,
) => Effect<Option<A>, E, R>;Delays & Timeouts
Returns an effect that is delayed from this effect by the specified Duration.
Signature
declare const delay: {
(duration: Input): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R>(self: Effect<A, E, R>, duration: Input): Effect<A, E, R>;
};Returns an effect that suspends the current fiber for the specified duration without blocking a JavaScript thread.
Signature
declare const sleep: (duration: Duration.Input) => Effect<void>;Returns the runtime duration of an effect together with its result.
Details
The original success, failure, or interruption is preserved; only the success value is paired with the duration.
Signature
declare const timed: <A, E, R>(
self: Effect<A, E, R>,
) => Effect<[duration: Duration.Duration, result: A], E, R>;Adds a time limit to an effect, triggering a timeout if the effect exceeds the duration.
When to use
Use when you need a timeout of an Effect to be represented as a typed failure.
Details
The timeout function allows you to specify a time limit for an effect's execution. If the effect does not complete within the given time, a TimeoutError is raised. This can be useful for controlling how long your program waits for a task to finish, ensuring that it doesn't hang indefinitely if the task takes too long.
Gotchas
If the timeout wins, the source effect is interrupted.
See
timeoutOptionfor returningOption.noneon timeout.timeoutOrElsefor a version that allows specifying both success and timeout handlers.
Signature
declare const timeout: {
(duration: Input): <A, E, R>(self: Effect<A, E, R>) => Effect<A, TimeoutError | E, R>;
<A, E, R>(self: Effect<A, E, R>, duration: Input): Effect<A, TimeoutError | E, R>;
};timeoutOption
Runs an effect with a time limit and represents only the timeout case as Option.none.
When to use
Use when a timeout of an Effect should be handled as Option.none.
Details
If the source effect succeeds before the timeout, the returned effect succeeds with Option.some(value). If the timeout wins, the source effect is interrupted and the returned effect succeeds with Option.none. If the source effect fails before the timeout, that failure is preserved.
See
timeoutfor a version that raises aTimeoutError.timeoutOrElsefor a version that allows specifying both success and timeout handlers.
Signature
declare const timeoutOption: {
(duration: Input): <A, E, R>(self: Effect<A, E, R>) => Effect<Option<A>, E, R>;
<A, E, R>(self: Effect<A, E, R>, duration: Input): Effect<Option<A>, E, R>;
};timeoutOrElse
Applies a timeout to an effect, with a fallback effect executed if the timeout is reached.
When to use
Use when a timeout of an Effect should switch to a fallback effect.
Details
The fallback effect is created lazily by orElse and may introduce its own success, failure, and requirement types.
Gotchas
If the timeout wins, the source effect is interrupted before the fallback is run.
See
timeoutfor failing with aTimeoutError.timeoutOptionfor returningOption.noneon timeout.
Signature
declare const timeoutOrElse: {
<A2, E2, R2>(options: {
readonly duration: Duration.Input;
readonly orElse: LazyArg<Effect<A2, E2, R2>>;
}): <A, E, R>(self: Effect<A, E, R>) => Effect<A2 | A, E2 | E, R2 | R>;
<A, E, R, A2, E2, R2>(
self: Effect<A, E, R>,
options: {
readonly duration: Duration.Input;
readonly orElse: LazyArg<Effect<A2, E2, R2>>;
},
): Effect<A | A2, E | E2, R | R2>;
};Error Handling
catchCause
Handles both recoverable and unrecoverable errors by providing a recovery effect.
When to use
Use when you need to recover from an Effect by inspecting the full Cause, including recoverable failures, defects, and interruptions, instead of only the typed error value.
Details
When to Recover from Defects:
Defects are unexpected errors that typically shouldn't be recovered from, as they often indicate serious issues. However, in some cases, such as dynamically loaded plugins, controlled recovery might be needed.
Signature
declare const catchCause: {
<E, A2, E2, R2>(
f: (cause: Cause<E>) => Effect<A2, E2, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<A2 | A, E2, R2 | R>;
<A, E, R, A2, E2, R2>(
self: Effect<A, E, R>,
f: (cause: Cause<E>) => Effect<A2, E2, R2>,
): Effect<A | A2, E2, R | R2>;
};catchCauseFilter
Recovers from specific failures based on a Filter.
When to use
Use when you need to recover an Effect only from causes selected by a Filter, while giving the recovery both the selected value and the original Cause.
Details
The filter is applied to the full Cause. When it succeeds, the handler receives the selected value and the original cause. When it fails, the effect re-fails with the residual cause returned by the filter.
See
catchCauseIffor predicate-based cause selectioncatchFilterfor filtering typed error values instead of full causescatchCausefor recovering from every cause without filtering
Signature
declare const catchCauseFilter: {
<E, B, E2, R2, EB, X extends Cause<any>>(
filter: Filter<Cause<E>, EB, X>,
f: (failure: EB, cause: Cause<E>) => Effect<B, E2, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<B | A, E2 | Error<X>, R2 | R>;
<A, E, R, B, E2, R2, EB, X extends Cause<any>>(
self: Effect<A, E, R>,
filter: Filter<Cause<E>, EB, X>,
f: (failure: EB, cause: Cause<E>) => Effect<B, E2, R2>,
): Effect<A | B, E2 | Error<X>, R | R2>;
};catchCauseIf
Recovers from specific failures based on a predicate.
When to use
Use to recover an Effect from full causes selected by a predicate.
Details
This function allows you to conditionally catch and recover from failures that match a specific predicate. This is useful when you want to handle only certain types of errors while letting others propagate.
See
catchCausefor recovering from every causecatchCauseFilterfor selecting full causes with aFiltercatchIffor predicate-based recovery from typed errors
Signature
declare const catchCauseIf: {
<E, B, E2, R2>(
predicate: Predicate<Cause<E>>,
f: (cause: Cause<E>) => Effect<B, E2, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<B | A, E | E2, R2 | R>;
<A, E, R, B, E2, R2>(
self: Effect<A, E, R>,
predicate: Predicate<Cause<E>>,
f: (cause: Cause<E>) => Effect<B, E2, R2>,
): Effect<A | B, E | E2, R | R2>;
};catchDefect
Recovers from defects using a provided recovery function.
When to use
Use when you need to report or translate defects at integration boundaries.
Details
catchDefect handles unexpected defects, such as thrown exceptions or values passed to die, without catching typed failures or interruptions.
When to Recover from Defects:
Defects are unexpected errors that typically should not be recovered from, as they often indicate serious issues. In some cases, such as dynamically loaded plugins, controlled recovery may be needed.
Signature
declare const catchDefect: {
<A2, E2, R2>(
f: (defect: unknown) => Effect<A2, E2, R2>,
): <A, E, R>(self: Effect<A, E, R>) => Effect<A2 | A, E2 | E, R2 | R>;
<A, E, R, A2, E2, R2>(
self: Effect<A, E, R>,
f: (defect: unknown) => Effect<A2, E2, R2>,
): Effect<A | A2, E | E2, R | R2>;
};catchEager
Applies catch eagerly when an effect is already resolved.
When to use
Use when an already-resolved failed effect should recover immediately while pending effects still use regular error recovery.
Details
Success effects pass through unchanged because there is no error to catch. Failure effects apply the catch function immediately, and pending effects fall back to regular catch behavior.
Signature
declare const catchEager: {
<E, B, E2, R2>(
f: (e: NoInfer<E>) => Effect<B, E2, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<B | A, E2, R2 | R>;
<A, E, R, B, E2, R2>(
self: Effect<A, E, R>,
f: (e: NoInfer<E>) => Effect<B, E2, R2>,
): Effect<A | B, E2, R | R2>;
};catchFilter
Recovers from specific errors using a Filter.
When to use
Use to recover from typed Effect errors with a reusable Filter when matching can also narrow or transform the error before choosing the recovery effect.
Details
The filter runs on typed failures extracted from the Cause. Successful filter results are passed to f; failed filter results are passed to orElse when provided. Without orElse, the original failure cause is preserved.
See
catchIffor predicate-based recovery from typed errorscatchTagfor recovering from a single tagged errorcatchTagsfor recovering from several tagged errorscatchCauseFilterfor filtering full causes instead of typed errors
Signature
declare const catchFilter: {
<E, EB, A2, E2, R2, X, A3 = unassigned, E3 = never, R3 = never>(
filter: Filter<NoInfer<E>, EB, X>,
f: (e: EB) => Effect<A2, E2, R2>,
orElse?: (e: X) => Effect<A3, E3, R3>,
): <A, R>(
self: Effect<A, E, R>,
) => Effect<
A2 | A | Exclude<A3, unassigned>,
E2 | E3 | A3 extends unassigned ? X : never,
R2 | R3 | R
>;
<A, E, R, EB, A2, E2, R2, X, A3 = unassigned, E3 = never, R3 = never>(
self: Effect<A, E, R>,
filter: Filter<NoInfer<E>, EB, X>,
f: (e: EB) => Effect<A2, E2, R2>,
orElse?: (e: X) => Effect<A3, E3, R3>,
): Effect<
A | A2 | Exclude<A3, unassigned>,
E2 | E3 | A3 extends unassigned ? X : never,
R | R2 | R3
>;
};Recovers from specific errors using a Predicate or Refinement.
When to use
Use when you need to recover from errors that match a condition.
Details
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.
Signature
declare const catchIf: {
<E, EB, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
refinement: Refinement<NoInfer<E>, EB>,
f: (e: EB) => Effect<A2, E2, R2>,
orElse?: (e: Exclude<E, EB>) => Effect<A3, E3, R3>,
): <A, R>(
self: Effect<A, E, R>,
) => Effect<
A2 | A | Exclude<A3, unassigned>,
E2 | E3 | A3 extends unassigned ? Exclude<E, EB> : never,
R2 | R3 | R
>;
<E, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
predicate: Predicate<NoInfer<E>>,
f: (e: NoInfer<E>) => Effect<A2, E2, R2>,
orElse?: (e: NoInfer<E>) => Effect<A3, E3, R3>,
): <A, R>(
self: Effect<A, E, R>,
) => Effect<
A2 | A | Exclude<A3, unassigned>,
E2 | E3 | A3 extends unassigned ? E : never,
R2 | R3 | R
>;
<A, E, R, EB, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
self: Effect<A, E, R>,
refinement: Refinement<E, EB>,
f: (e: EB) => Effect<A2, E2, R2>,
orElse?: (e: Exclude<E, EB>) => Effect<A3, E3, R3>,
): Effect<
A | A2 | Exclude<A3, unassigned>,
E2 | E3 | A3 extends unassigned ? Exclude<E, EB> : never,
R | R2 | R3
>;
<A, E, R, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
self: Effect<A, E, R>,
predicate: Predicate<E>,
f: (e: E) => Effect<A2, E2, R2>,
orElse?: (e: E) => Effect<A3, E3, R3>,
): Effect<
A | A2 | Exclude<A3, unassigned>,
E2 | E3 | A3 extends unassigned ? E : never,
R | R2 | R3
>;
};catchNoSuchElement
Catches NoSuchElementError failures and converts them to Option.none.
When to use
Use when you expect missing-value failures and want them to become an optional success while all other failures keep failing.
Details
Success values become Option.some, NoSuchElementError becomes Option.none, and all other errors are preserved.
See
fromOptionfor convertingOption.noneintoNoSuchElementErrorfromNullishOrfor converting nullish values intoNoSuchElementErroroptionfor converting any failure intoOption.none
Signature
declare const catchNoSuchElement: <A, E, R>(
self: Effect<A, E, R>,
) => Effect<Option<A>, Exclude<E, Cause.NoSuchElementError>, R>;catchReason
Catches a specific reason within a tagged error.
When to use
Use to handle one nested reason inside an Effect's tagged error while preserving the parent error shape for unmatched reasons.
Details
Use this to handle nested error causes without removing the parent error from the error channel. The handler receives the unwrapped reason.
See
catchReasonsfor handling several nested reason tags
Signature
declare const catchReason: {
<K extends string, E, RK extends string, A2, E2, R2, A3 = unassigned, E3 = never, R3 = never>(
errorTag: K,
reasonTag: RK,
f: (
reason: ExtractReason<ExtractTag<NoInfer<E>, K>, RK>,
error: NarrowReason<ExtractTag<NoInfer<E>, K>, RK>,
) => Effect<A2, E2, R2>,
orElse?: (
reasons: ExcludeReason<ExtractTag<NoInfer<E>, K>, RK>,
error: OmitReason<ExtractTag<NoInfer<E>, K>, RK>,
) => Effect<A3, E3, R3>,
): <A, R>(
self: Effect<A, E, R>,
) => Effect<
A2 | A | Exclude<A3, unassigned>,
E2 | E3 | ExcludeTag<E, K> | A3 extends unassigned ? ExtractTag<E, K> : never,
R2 | R3 | R
>;
<
A,
E,
R,
K extends string,
RK extends string,
A2,
E2,
R2,
A3 = unassigned,
E3 = never,
R3 = never,
>(
self: Effect<A, E, R>,
errorTag: K,
reasonTag: RK,
f: (
reason: ExtractReason<ExtractTag<E, K>, RK>,
error: NarrowReason<ExtractTag<E, K>, RK>,
) => Effect<A2, E2, R2>,
orElse?: (
reasons: ExcludeReason<ExtractTag<E, K>, RK>,
error: OmitReason<ExtractTag<E, K>, RK>,
) => Effect<A3, E3, R3>,
): Effect<
A | A2 | Exclude<A3, unassigned>,
E2 | E3 | ExcludeTag<E, K> | A3 extends unassigned ? ExtractTag<E, K> : never,
R | R2 | R3
>;
};catchReasons
Catches multiple reasons within a tagged error using an object of handlers.
Signature
declare const catchReasons: {
<
K extends string,
E,
Cases extends {
[RK in string]: (
reason: ExtractReason<ExtractTag<NoInfer<E>, K>, RK>,
error: NarrowReason<ExtractTag<NoInfer<E>, K>, RK>,
) => Effect<any, any, any>;
},
A2 = unassigned,
E2 = never,
R2 = never,
>(
errorTag: K,
cases: Cases,
orElse?: (
reason: ExcludeReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>,
error: OmitReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>,
) => Effect<A2, E2, R2>,
): <A, R>(
self: Effect<A, E, R>,
) => Effect<
| A
| Exclude<A2, unassigned>
| {
[RK in string | number | symbol]: Cases[RK] extends (
...args: Array<any>
) => Effect<A, any, any>
? A
: never;
}[keyof Cases],
E2 | ExcludeTag<E, K> | A2 extends unassigned
? ExtractTag<E, K>
:
| never
| {
[RK in string | number | symbol]: Cases[RK] extends (
...args: Array<any>
) => Effect<any, E, any>
? E
: never;
}[keyof Cases],
| R2
| R
| {
[RK in string | number | symbol]: Cases[RK] extends (
...args: Array<any>
) => Effect<any, any, R>
? R
: never;
}[keyof Cases]
>;
<
A,
E,
R,
K extends string,
Cases extends {
[RK in string]: (
reason: ExtractReason<ExtractTag<E, K>, RK>,
error: NarrowReason<ExtractTag<E, K>, RK>,
) => Effect<any, any, any>;
},
A2 = unassigned,
E2 = never,
R2 = never,
>(
self: Effect<A, E, R>,
errorTag: K,
cases: Cases,
orElse?: (
reason: ExcludeReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>,
error: OmitReason<ExtractTag<NoInfer<E>, K>, Extract<keyof Cases, string>>,
) => Effect<A2, E2, R2>,
): Effect<
| A
| Exclude<A2, unassigned>
| {
[RK in string | number | symbol]: Cases[RK] extends (
...args: Array<any>
) => Effect<A, any, any>
? A
: never;
}[keyof Cases],
E2 | ExcludeTag<E, K> | A2 extends unassigned
? ExtractTag<E, K>
:
| never
| {
[RK in string | number | symbol]: Cases[RK] extends (
...args: Array<any>
) => Effect<any, E, any>
? E
: never;
}[keyof Cases],
| R
| R2
| {
[RK in string | number | symbol]: Cases[RK] extends (
...args: Array<any>
) => Effect<any, any, R>
? R
: never;
}[keyof Cases]
>;
};Catches and handles specific errors by their _tag field, which is used as a discriminator.
When to use
Use when you need to recover from one specific tagged error in an effect error channel.
Details
The error type must have a readonly _tag field. catchTag matches that field and only handles errors with the requested tag.
See
Signature
declare const catchTag: {
<
K extends string | readonly [Tags<E>, Tags<E>],
E,
A1,
E1,
R1,
A2 = unassigned,
E2 = never,
R2 = never,
>(
k: K,
f: (
e: ExtractTag<NoInfer<E>, K extends readonly [string, string] ? K[number] : K>,
) => Effect<A1, E1, R1>,
orElse?: (
e: ExcludeTag<E, K extends readonly [string, string] ? K[number] : K>,
) => Effect<A2, E2, R2>,
): <A, R>(
self: Effect<A, E, R>,
) => Effect<
A1 | A | Exclude<A2, unassigned>,
E1 | E2 | A2 extends unassigned
? ExcludeTag<E, K extends readonly [string, string] ? K[number] : K>
: never,
R1 | R2 | R
>;
<
A,
E,
R,
K extends string | readonly [Tags<E>, Tags<E>],
R1,
E1,
A1,
A2 = unassigned,
E2 = never,
R2 = never,
>(
self: Effect<A, E, R>,
k: K,
f: (
e: ExtractTag<E, K extends readonly [string, string] ? K[number] : K>,
) => Effect<A1, E1, R1>,
orElse?: (
e: ExcludeTag<E, K extends readonly [string, string] ? K[number] : K>,
) => Effect<A2, E2, R2>,
): Effect<
A | A1 | Exclude<A2, unassigned>,
E1 | E2 | A2 extends unassigned
? ExcludeTag<E, K extends readonly [string, string] ? K[number] : K>
: never,
R | R1 | R2
>;
};Handles multiple errors in a single block of code using their _tag field.
When to use
Use when one recovery step should handle several tagged error types by matching their readonly _tag fields.
Details
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 catchTags. This field is used to identify and match errors.
Signature
declare const catchTags: {
<
E,
Cases extends
| {
[K in string]: (
error: Extract<
E,
{
_tag: K;
}
>,
) => Effect<any, any, any>;
}
| ({
[K in string]: (
error: Extract<
E,
{
_tag: K;
}
>,
) => Effect<any, any, any>;
} & { [K in number | symbol]: never }),
A2 = unassigned,
E2 = never,
R2 = never,
>(
cases: Cases,
orElse?: (
e: Exclude<
E,
{
_tag: keyof Cases;
}
>,
) => Effect<A2, E2, R2>,
): <A, R>(
self: Effect<A, E, R>,
) => Effect<
| A
| Exclude<A2, unassigned>
| {
[K in string | number | symbol]: Cases[K] extends (
...args: Array<any>
) => Effect<A, any, any>
? A
: never;
}[keyof Cases],
E2 | A2 extends unassigned
? Exclude<
E,
{
_tag: keyof Cases;
}
>
:
| never
| {
[K in string | number | symbol]: Cases[K] extends (
...args: Array<any>
) => Effect<any, E, any>
? E
: never;
}[keyof Cases],
| R2
| R
| {
[K in string | number | symbol]: Cases[K] extends (
...args: Array<any>
) => Effect<any, any, R>
? R
: never;
}[keyof Cases]
>;
<
R,
E,
A,
Cases extends
| {
[K in string]: (
error: Extract<
E,
{
_tag: K;
}
>,
) => Effect<any, any, any>;
}
| ({
[K in string]: (
error: Extract<
E,
{
_tag: K;
}
>,
) => Effect<any, any, any>;
} & { [K in number | symbol]: never }),
A2 = unassigned,
E2 = never,
R2 = never,
>(
self: Effect<A, E, R>,
cases: Cases,
orElse?: (
e: Exclude<
E,
{
_tag: keyof Cases;
}
>,
) => Effect<A2, E2, R2>,
): Effect<
| A
| Exclude<A2, unassigned>
| {
[K in string | number | symbol]: Cases[K] extends (
...args: Array<any>
) => Effect<A, any, any>
? A
: never;
}[keyof Cases],
E2 | A2 extends unassigned
? Exclude<
E,
{
_tag: keyof Cases;
}
>
:
| never
| {
[K in string | number | symbol]: Cases[K] extends (
...args: Array<any>
) => Effect<any, E, any>
? E
: never;
}[keyof Cases],
| R
| R2
| {
[K in string | number | symbol]: Cases[K] extends (
...args: Array<any>
) => Effect<any, any, R>
? R
: never;
}[keyof Cases]
>;
};Transforms an effect to encapsulate both failure and success using the Exit data type.
When to use
Use when you need to inspect the full outcome, including typed failures, defects, and interruptions.
Details
exit wraps an effect's success or failure inside an Exit type, allowing you to handle both cases explicitly.
The resulting effect cannot fail because the failure is encapsulated within the Exit.Failure type. The error type is set to never, indicating that the effect is structured to never fail directly.
See
Signature
declare const exit: <A, E, R>(self: Effect<A, E, R>) => Effect<Exit.Exit<A, E>, never, R>;firstSuccessOf
Runs a sequence of effects and returns the result of the first successful one.
When to use
Use when you have prioritized fallback Effects, such as attempting multiple APIs, reading configuration from several sources, or trying alternative resource locations in order.
Details
This function executes the provided effects in sequence, stopping at the first success. If an effect succeeds, its result is returned immediately and no further effects in the sequence are executed.
If all effects fail, the returned effect fails with the error from the last effect. If the collection is empty, the returned effect defects with an Error whose message is "Received an empty collection of effects".
Signature
declare const firstSuccessOf: <Eff extends Effect<any, any, any>>(
effects: Iterable<Eff>,
) => Effect<Success<Eff>, Error<Eff>, Services<Eff>>;Discards both the success and failure values of an effect.
When to use
Use when an effect should run for its side effects while both success and failure values are discarded.
Details
Use the log option to emit the full Cause when the effect fails, and message to prepend a custom log message.
Signature
declare const ignore: <
Arg extends
| Effect<any, any, any>
| {
readonly log?: boolean | Severity;
readonly message?: string;
}
| undefined = {
readonly log?: boolean | Severity;
readonly message?: string;
},
>(
effectOrOptions?: Arg,
options?: {
readonly log?: boolean | Severity;
readonly message?: string;
},
) => [Arg] extends [Effect<infer _A, infer _E, infer _R>]
? Effect<void, never, _R>
: <A, E, R>(self: Effect<A, E, R>) => Effect<void, never, R>;ignoreCause
Ignores the effect's failure cause, including defects and interruptions.
When to use
Use when a best-effort effect should never fail, even from defects or interruption, and optional cause logging is enough.
Details
Use the log option to emit the full Cause when the effect fails, and message to prepend a custom log message.
Signature
declare const ignoreCause: <
Arg extends
| Effect<any, any, any>
| {
readonly log?: boolean | Severity;
readonly message?: string;
}
| undefined = {
readonly log?: boolean | Severity;
readonly message?: string;
},
>(
effectOrOptions?: Arg,
options?: {
readonly log?: boolean | Severity;
readonly message?: string;
},
) => [Arg] extends [Effect<infer _A, infer _E, infer _R>]
? Effect<void, never, _R>
: <A, E, R>(self: Effect<A, E, R>) => Effect<void, never, R>;Transforms the failure value of an effect without changing its success value.
When to use
Use to translate an Effect's typed failures while leaving successful values unchanged.
Details
Only the failure channel is transformed. The success channel and requirements are preserved.
See
Signature
declare const mapError: {
<E, E2>(f: (e: E) => E2): <A, R>(self: Effect<A, E, R>) => Effect<A, E2, R>;
<A, E, R, E2>(self: Effect<A, E, R>, f: (e: E) => E2): Effect<A, E2, R>;
};mapErrorEager
Applies mapError eagerly when an effect is already resolved.
When to use
Use when an already-resolved failed effect should apply an error transformation immediately while pending effects still use regular error mapping.
Details
Success effects pass through unchanged because there is no error to transform. Failure effects apply the mapping function immediately, and pending effects fall back to regular mapError behavior.
Signature
declare const mapErrorEager: {
<E, E2>(f: (e: E) => E2): <A, R>(self: Effect<A, E, R>) => Effect<A, E2, R>;
<A, E, R, E2>(self: Effect<A, E, R>, f: (e: E) => E2): Effect<A, E2, R>;
};Converts success to Option.some and failure to Option.none.
When to use
Use when you only care whether an effect succeeds and want recoverable failures represented as Option.none.
Details
Success values become Option.some, recoverable failures become Option.none, and defects still fail the effect.
Gotchas
option only captures typed, recoverable failures as Option.none. Defects and interruptions are not captured inside the Option and still fail the effect.
option also discards typed failure values. Use result if the failure value matters.
See
Signature
declare const option: <A, E, R>(self: Effect<A, E, R>) => Effect<Option<A>, never, R>;Converts typed failures from the error channel into defects, removing the error type from the returned effect.
When to use
Use when you need to turn an Effect typed failure that represents an unrecoverable bug or invalid state into a defect.
Signature
declare const orDie: <A, E, R>(self: Effect<A, E, R>) => Effect<A, never, R>;orElseSucceed
Recovers from a typed failure by producing a fallback success value.
Details
If the source effect succeeds, its value is preserved. If it fails in the error channel, orElseSucceed evaluates the fallback and succeeds with that value, removing the typed error from the returned effect.
Defects and interruptions are not recovered by this operator.
Signature
declare const orElseSucceed: {
<A2>(evaluate: LazyArg<A2>): <A, E, R>(self: Effect<A, E, R>) => Effect<A2 | A, never, R>;
<A, E, R, A2>(self: Effect<A, E, R>, evaluate: LazyArg<A2>): Effect<A | A2, never, R>;
};Converts both success and failure of an Effect into a Result type.
When to use
Use when you want an Effect's typed failures to be handled as Result data while preserving the original error value.
Details
This function converts an effect that may fail into an effect that always succeeds, wrapping the outcome in a Result type. The result will be Result.Failure if the effect fails, containing the recoverable error, or Result.Success if it succeeds, containing the result.
Using this function, you can handle recoverable errors explicitly without causing the effect to fail. This is particularly useful in scenarios where you want to chain effects and manage both success and failure in the same logical flow.
The resulting effect cannot fail directly because all recoverable failures are represented inside the Result type.
Gotchas
result only captures typed, recoverable failures. Defects and interruptions are not captured inside the Result and still fail the effect.
See
Signature
declare const result: <A, E, R>(self: Effect<A, E, R>) => Effect<Result.Result<A, E>, never, R>;Retries typed failures from an effect according to a retry policy.
When to use
Use when you need to rerun an effect after transient typed failures, such as network issues or temporary resource unavailability.
Details
The policy can be a Schedule, a schedule builder, or a Retry.Options object using schedule, times, while, or until. If a retry eventually succeeds, the returned effect succeeds with that value. If the policy stops while the effect is still failing, the last failure is propagated.
Gotchas
The source effect is always evaluated once before any retry policy is applied. For example, Schedule.recurs(3) allows up to three retries after the initial attempt.
Defects and interruptions are not retried.
See
retryOrElsefor a version that allows you to run a fallback.repeatif your retry condition is based on successful outcomes rather than errors.
Signature
declare const retry: {
<E, O extends Options<E>>(
options: O,
): <A, R>(
self: Effect<A, E, R>,
) => Effect<
A,
O extends {
schedule: Schedule<infer _O, infer _I, infer _E1, infer _R>;
}
? E
: O extends {
times: number;
}
? E
: O extends {
until: Predicate.Refinement<E, infer E2>;
}
? E2
: O extends {
while: Predicate.Refinement<E, infer E2>;
}
? Exclude<E, E2>
: E | O extends {
schedule: Schedule<infer _O, infer _I, infer E, infer _R>;
}
? E
: never | O extends {
while: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
}
? E
: never | O extends {
until: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
}
? E
: never,
R | O extends {
schedule: Schedule<infer _O, infer _I, infer _E1, infer R>;
}
? R
: never | O extends {
while: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
}
? R
: never | O extends {
until: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
}
? R
: never
>;
<B, E, Error, Env>(
policy: Schedule<B, NoInfer<E>, Error, Env>,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E | Error, Env | R>;
<B, E, Error, Env>(
builder: (
$: <O, SE, R>(_: Schedule<O, NoInfer<E>, SE, R>) => Schedule<O, E, SE, R>,
) => Schedule<B, NoInfer<E>, Error, Env>,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E | Error, Env | R>;
<A, E, R, O extends Options<E>>(
self: Effect<A, E, R>,
options: O,
): Effect<
A,
O extends {
schedule: Schedule<infer _O, infer _I, infer _E1, infer _R>;
}
? E
: O extends {
times: number;
}
? E
: O extends {
until: Predicate.Refinement<E, infer E2>;
}
? E2
: O extends {
while: Predicate.Refinement<E, infer E2>;
}
? Exclude<E, E2>
: E | O extends {
schedule: Schedule<infer _O, infer _I, infer E, infer _R>;
}
? E
: never | O extends {
while: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
}
? E
: never | O extends {
until: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
}
? E
: never,
R | O extends {
schedule: Schedule<infer _O, infer _I, infer _E1, infer R>;
}
? R
: never | O extends {
while: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
}
? R
: never | O extends {
until: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
}
? R
: never
>;
<A, E, R, B, Error, Env>(
self: Effect<A, E, R>,
policy: Schedule<B, NoInfer<E>, Error, Env>,
): Effect<A, E | Error, R | Env>;
<A, E, R, B, Error, Env>(
self: Effect<A, E, R>,
builder: (
$: <O, SE, R>(_: Schedule<O, NoInfer<E>, SE, R>) => Schedule<O, E, SE, R>,
) => Schedule<B, NoInfer<E>, Error, Env>,
): Effect<A, E | Error, R | Env>;
};retryOrElse
Retries a failing effect and runs a fallback effect if retries are exhausted.
When to use
Use when you want to handle failures gracefully by specifying an alternative action after repeated failures.
Details
The Effect.retryOrElse function attempts to retry a failing effect multiple times according to a defined Schedule policy.
If the retries are exhausted and the effect still fails, it runs a fallback effect instead.
See
retryfor a version that does not run a fallback effect.
Signature
declare const retryOrElse: {
<A1, E, E1, R1, A2, E2, R2>(
policy: Schedule<A1, NoInfer<E>, E1, R1>,
orElse: (e: NoInfer<E>, out: A1) => Effect<A2, E2, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<A2 | A, E1 | E2, R1 | R2 | R>;
<A, E, R, A1, E1, R1, A2, E2, R2>(
self: Effect<A, E, R>,
policy: Schedule<A1, NoInfer<E>, E1, R1>,
orElse: (e: NoInfer<E>, out: A1) => Effect<A2, E2, R2>,
): Effect<A | A2, E1 | E2, R | R1 | R2>;
};Exposes an effect's full failure cause in the error channel as Cause<E>.
Details
Use sandbox when downstream error handling needs to distinguish typed failures, defects, and interruptions. Use unsandbox to restore the original typed error channel after cause-level handling.
Signature
declare const sandbox: <A, E, R>(self: Effect<A, E, R>) => Effect<A, Cause.Cause<E>, R>;TagsWithReason type
Type helper that keeps only error tags whose tagged error contains a tagged reason field.
When to use
Use to constrain custom helpers or overloads to parent error tags whose error contains a tagged reason.
Details
The mapped type keeps each parent error tag whose extracted tagged error has at least one reason tag, and removes tags that do not carry tagged reasons.
See
unwrapReasonfor promoting nested reason errors into the error channelcatchReasonfor handling one nested reason tagcatchReasonsfor handling several nested reason tags
Signature
type TagsWithReason<E> = {
[T in Tags<E>]: ReasonTags<ExtractTag<E, T>> extends never ? never : T;
}[Tags<E>];unwrapReason
Promotes nested reason errors into the Effect error channel, replacing the parent error.
Signature
declare const unwrapReason: {
<K extends string, E>(
errorTag: K,
): <A, R>(self: Effect<A, E, R>) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>;
<A, E, R, K extends string>(
self: Effect<A, E, R>,
errorTag: K,
): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>;
};withErrorReporting
Runs an effect and reports any errors to the configured ErrorReporters.
Details
If the defectsOnly option is set to true, only defects (unrecoverable errors) will be reported, while regular failures will be ignored.
Signature
declare const withErrorReporting: <
Arg extends
| Effect<any, any, any>
| {
readonly defectsOnly?: boolean;
}
| undefined = {
readonly defectsOnly?: boolean;
},
>(
effectOrOptions: Arg,
options?: {
readonly defectsOnly?: boolean;
},
) => [Arg] extends [Effect<infer _A, infer _E, infer _R>]
? Arg
: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;withExecutionPlan
Applies an ExecutionPlan to an effect, retrying with step-provided resources until it succeeds or the plan is exhausted.
Details
Each attempt updates ExecutionPlan.CurrentMetadata (attempt and step index), and retry timing is derived per step (the first attempt uses the remaining attempts schedule; later retries apply the step schedule at least once).
Attempts can be observed from outside the effect by passing options.onEvent, which receives an ExecutionPlan.Event before each attempt and after it settles. The handler is awaited inline before and after every attempt, so events are strictly ordered; keep it cheap. It cannot fail, which keeps observation from changing the plan's outcome, and its requirements are added to the resulting effect. Terminal events run like finalizers, so they are emitted even when the attempt is interrupted.
Signature
declare const withExecutionPlan: {
<Input, Provides, PlanE, PlanR, RX = never>(
plan: ExecutionPlan<{
error: PlanE;
input: Input;
provides: Provides;
requirements: PlanR;
}>,
options?: {
readonly onEvent?: (event: ExecutionPlan.Event<Input | PlanE>) => Effect<void, never, RX>;
},
): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, PlanE | E, PlanR | RX | Exclude<R, Provides>>;
<A, E, R, Provides, Input, PlanE, PlanR, RX = never>(
effect: Effect<A, E, R>,
plan: ExecutionPlan<{
error: PlanE;
input: Input;
provides: Provides;
requirements: PlanR;
}>,
options?: {
readonly onEvent?: (event: ExecutionPlan.Event<E | PlanE>) => Effect<void, never, RX>;
},
): Effect<A, E | PlanE, PlanR | RX | Exclude<R, Provides>>;
};Filtering
Filters elements of an iterable using a predicate, refinement, or effectful predicate.
Signature
declare const filter: {
<A, B>(refinement: Refinement<NoInfer<A>, B>): (elements: Iterable<A>) => Effect<Array<B>>;
<A>(predicate: Predicate<NoInfer<A>>): (elements: Iterable<A>) => Effect<Array<A>>;
<A, E, R>(
predicate: (a: NoInfer<A>, i: number) => Effect<boolean, E, R>,
options?: {
readonly concurrency?: Concurrency;
},
): (iterable: Iterable<A>) => Effect<Array<A>, E, R>;
<A, B>(elements: Iterable<A>, refinement: Refinement<A, B>): Effect<Array<B>>;
<A>(elements: Iterable<A>, predicate: Predicate<A>): Effect<Array<A>>;
<A, E, R>(
iterable: Iterable<A>,
predicate: (a: NoInfer<A>, i: number) => Effect<boolean, E, R>,
options?: {
readonly concurrency?: Concurrency;
},
): Effect<Array<A>, E, R>;
};Filters and maps elements of an iterable with a Filter.
When to use
Use when you need to filter an iterable with a Filter inside an Effect, collecting each filter success value.
Details
Result.succeed values are collected in the returned array, and Result.fail values are skipped.
See
filterfor keeping original elements with a boolean predicate, refinement, or effectful predicatefilterMapEffectfor using an effectfulFilter
Signature
declare const filterMap: {
<A, B, X>(filter: Filter<NoInfer<A>, B, X>): (elements: Iterable<A>) => Effect<Array<B>>;
<A, B, X>(elements: Iterable<A>, filter: Filter<NoInfer<A>, B, X>): Effect<Array<B>>;
};filterMapEffect
Filters and maps elements of an iterable effectfully with a FilterEffect.
When to use
Use when you need to filter each iterable element effectfully and transform accepted elements into successful output values.
Details
Result.succeed values are collected in the returned array, and Result.fail values are skipped.
Gotchas
With concurrent execution, successful values are collected in completion order, not input order.
See
Signature
declare const filterMapEffect: {
<A, B, X, E, R>(
filter: FilterEffect<NoInfer<A>, B, X, E, R>,
options?: {
readonly concurrency?: Concurrency;
},
): (elements: Iterable<A>) => Effect<Array<B>, E, R>;
<A, B, X, E, R>(
elements: Iterable<A>,
filter: FilterEffect<NoInfer<A>, B, X, E, R>,
options?: {
readonly concurrency?: Concurrency;
},
): Effect<Array<B>, E, R>;
};filterMapOrElse
Filters an effect with a Filter, providing an alternative effect on failure.
When to use
Use when a successful effect value should be accepted and transformed by a Filter, while rejected values should continue with an alternative effect built from the filter failure.
Details
Result.succeed becomes the returned success value, and Result.fail is passed to orElse.
See
filterOrElsefor using a predicate and fallback effectfilterMapOrFailfor failing the effect when the filter fails
Signature
declare const filterMapOrElse: {
<A, B, X, C, E2, R2>(
filter: Filter<NoInfer<A>, B, X>,
orElse: (x: X) => Effect<C, E2, R2>,
): <E, R>(self: Effect<A, E, R>) => Effect<B | C, E2 | E, R2 | R>;
<A, E, R, B, X, C, E2, R2>(
self: Effect<A, E, R>,
filter: Filter<NoInfer<A>, B, X>,
orElse: (x: X) => Effect<C, E2, R2>,
): Effect<B | C, E | E2, R | R2>;
};filterMapOrFail
Filters and maps an effect with a Filter, failing when the filter fails.
When to use
Use when validating and transforming one effect success with a synchronous Filter, while rejected values should fail the effect.
Details
Result.succeed becomes the returned success value. Result.fail is mapped with orFailWith when provided, or fails with NoSuchElementError.
See
filterMapOrElsefor continuing with a fallback effect when the filter failsfilterOrFailfor validating with a predicate instead of aFilterfilterMapfor filtering and mapping iterable elements
Signature
declare const filterMapOrFail: {
<A, B, X, E2>(
filter: Filter<NoInfer<A>, B, X>,
orFailWith: (x: X) => E2,
): <E, R>(self: Effect<A, E, R>) => Effect<B, E2 | E, R>;
<A, B, X>(
filter: Filter<NoInfer<A>, B, X>,
): <E, R>(self: Effect<A, E, R>) => Effect<B, NoSuchElementError | E, R>;
<A, E, R, B, X, E2>(
self: Effect<A, E, R>,
filter: Filter<A, B, X>,
orFailWith: (x: X) => E2,
): Effect<B, E | E2, R>;
<A, E, R, B, X>(
self: Effect<A, E, R>,
filter: Filter<A, B, X>,
): Effect<B, NoSuchElementError | E, R>;
};filterOrElse
Filters an effect, providing an alternative effect if the predicate fails.
When to use
Use when a successful value that fails a predicate should continue with an effectful fallback instead of failing the effect.
Details
This function applies a predicate to the result of an effect. If the predicate evaluates to false, it executes the orElse effect instead. The orElse effect can produce an alternative value or perform additional computations.
Signature
declare const filterOrElse: {
<A, C, E2, R2, B>(
refinement: Refinement<NoInfer<A>, B>,
orElse: (a: EqualsWith<A, B, NoInfer<A>, Exclude<NoInfer<A>, B>>) => Effect<C, E2, R2>,
): <E, R>(self: Effect<A, E, R>) => Effect<C | B, E2 | E, R2 | R>;
<A, C, E2, R2>(
predicate: Predicate<NoInfer<A>>,
orElse: (a: NoInfer<A>) => Effect<C, E2, R2>,
): <E, R>(self: Effect<A, E, R>) => Effect<A | C, E2 | E, R2 | R>;
<A, E, R, C, E2, R2, B>(
self: Effect<A, E, R>,
refinement: Refinement<A, B>,
orElse: (a: EqualsWith<A, B, A, Exclude<A, B>>) => Effect<C, E2, R2>,
): Effect<C | B, E | E2, R | R2>;
<A, E, R, C, E2, R2>(
self: Effect<A, E, R>,
predicate: Predicate<NoInfer<A>>,
orElse: (a: NoInfer<A>) => Effect<C, E2, R2>,
): Effect<A | C, E | E2, R | R2>;
};filterOrFail
Filters an effect, failing with a custom error if the predicate fails.
Details
This function applies a predicate to the result of an effect. If the predicate evaluates to false, the effect fails with either a custom error (if orFailWith is provided) or a NoSuchElementError.
Signature
declare const filterOrFail: {
<A, E2, B>(
refinement: Refinement<NoInfer<A>, B>,
orFailWith: (a: NoInfer<A>) => E2,
): <E, R>(self: Effect<A, E, R>) => Effect<B, E2 | E, R>;
<A, E2>(
predicate: Predicate<NoInfer<A>>,
orFailWith: (a: NoInfer<A>) => E2,
): <E, R>(self: Effect<A, E, R>) => Effect<A, E2 | E, R>;
<A, B>(
refinement: Refinement<NoInfer<A>, B>,
): <E, R>(self: Effect<A, E, R>) => Effect<B, NoSuchElementError | E, R>;
<A>(
predicate: Predicate<NoInfer<A>>,
): <E, R>(self: Effect<A, E, R>) => Effect<A, NoSuchElementError | E, R>;
<A, E, R, E2, B>(
self: Effect<A, E, R>,
refinement: Refinement<NoInfer<A>, B>,
orFailWith: (a: NoInfer<A>) => E2,
): Effect<B, E | E2, R>;
<A, E, R, E2>(
self: Effect<A, E, R>,
predicate: Predicate<NoInfer<A>>,
orFailWith: (a: NoInfer<A>) => E2,
): Effect<A, E | E2, R>;
<A, E, R, B>(
self: Effect<A, E, R>,
refinement: Refinement<NoInfer<A>, B>,
): Effect<B, NoSuchElementError | E, R>;
<A, E, R>(
self: Effect<A, E, R>,
predicate: Predicate<NoInfer<A>>,
): Effect<A, NoSuchElementError | E, R>;
};Applies an effectful function to each element and partitions failures and successes.
Details
The returned tuple is [excluded, satisfying], where excluded contains all failures and satisfying contains all successes.
This function runs every effect and never fails. Use concurrency to control parallelism.
Signature
declare const partition: {
<A, B, E, R>(
f: (a: A, i: number) => Effect<B, E, R>,
options?: {
readonly concurrency?: Concurrency;
},
): (elements: Iterable<A>) => Effect<[excluded: Array<E>, satisfying: Array<B>], never, R>;
<A, B, E, R>(
elements: Iterable<A>,
f: (a: A, i: number) => Effect<B, E, R>,
options?: {
readonly concurrency?: Concurrency;
},
): Effect<[excluded: Array<E>, satisfying: Array<B>], never, R>;
};Runs an effect conditionally based on the result of an effectful boolean condition.
When to use
Use when you need an effectful check to decide whether another effect should run while representing the skipped case explicitly.
Details
The condition effect is evaluated first. If it succeeds with true, the source effect is run and its success value is wrapped in Option.some. If it succeeds with false, the source effect is skipped and the result is Option.none. If the condition effect fails, that failure is preserved.
Signature
declare const when: {
<E2 = never, R2 = never>(
condition: Effect<boolean, E2, R2>,
): <A, E, R>(self: Effect<A, E, R>) => Effect<Option<A>, E2 | E, R2 | R>;
<A, E, R, E2 = never, R2 = never>(
self: Effect<A, E, R>,
condition: Effect<boolean, E2, R2>,
): Effect<Option<A>, E | E2, R | R2>;
};Folding
Reduces elements from left to right with an effectful accumulator function.
When to use
Use when each accumulation step is effectful and must run sequentially in iteration order.
Details
The accumulator function receives the current accumulator, the current element, and its zero-based index. The zero function is evaluated each time the effect runs. An empty iterable succeeds with its result. If a step fails, remaining elements are not processed.
Signature
declare const reduce: {
<Z, A, E, R>(
zero: LazyArg<Z>,
f: (z: Z, a: A, i: number) => Effect<Z, E, R>,
): (elements: Iterable<A>) => Effect<Z, E, R>;
<A, Z, E, R>(
elements: Iterable<A>,
zero: LazyArg<Z>,
f: (z: Z, a: A, i: number) => Effect<Z, E, R>,
): Effect<Z, E, R>;
};Forking
Returns an effect that forks this effect into its own separate fiber, returning the fiber immediately, without waiting for it to begin executing the effect.
Details
You can use the forkChild method whenever you want to execute an effect in a new fiber, concurrently and without "blocking" the fiber executing other effects. Using fibers can be tricky, so instead of using this method directly, consider other higher-level methods, such as raceWith, zipPar, and so forth.
The fiber returned by this method has methods to interrupt the fiber and to wait for it to finish executing the effect. See Fiber for more information.
Whenever you use this method to launch a new fiber, the new fiber is attached to the parent fiber's scope. This means when the parent fiber terminates, the child fiber will be terminated as well, ensuring that no fibers leak. This behavior is called "auto supervision", and if this behavior is not desired, you may use the forkDetach or forkIn methods.
Signature
declare const forkChild: <
Arg extends
| Effect<any, any, any>
| {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
}
| undefined = {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
},
>(
effectOrOptions?: Arg,
options?: {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
},
) => [Arg] extends [Effect<infer _A, infer _E, infer _R>]
? Effect<Fiber<_A, _E>, never, _R>
: <A, E, R>(self: Effect<A, E, R>) => Effect<Fiber<A, E>, never, R>;forkDetach
Forks the effect into a new fiber attached to the global scope. Because the new fiber is attached to the global scope, when the fiber executing the returned effect terminates, the forked fiber will continue running.
Signature
declare const forkDetach: <
Arg extends
| Effect<any, any, any>
| {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
}
| undefined = {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
},
>(
effectOrOptions?: Arg,
options?: {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
},
) => [Arg] extends [Effect<infer _A, infer _E, infer _R>]
? Effect<Fiber<_A, _E>, never, _R>
: <A, E, R>(self: Effect<A, E, R>) => Effect<Fiber<A, E>, never, R>;Forks the effect in the specified scope. The fiber will be interrupted when the scope is closed.
Signature
declare const forkIn: {
(
scope: Scope,
options?: {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
},
): <A, E, R>(self: Effect<A, E, R>) => Effect<Fiber<A, E>, never, R>;
<A, E, R>(
self: Effect<A, E, R>,
scope: Scope,
options?: {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
},
): Effect<Fiber<A, E>, never, R>;
};forkScoped
Forks the fiber in a Scope, interrupting it when the scope is closed.
Signature
declare const forkScoped: <
Arg extends
| Effect<any, any, any>
| {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
}
| undefined = {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
},
>(
effectOrOptions?: Arg,
options?: {
readonly startImmediately?: boolean;
readonly uninterruptible?: boolean | "inherit";
},
) => [Arg] extends [Effect<infer _A, infer _E, infer _R>]
? Effect<Fiber<_A, _E>, never, _R | Scope>
: <A, E, R>(self: Effect<A, E, R>) => Effect<Fiber<A, E>, never, R | Scope>;Guards
Interruption
abortSignal
Creates an AbortSignal that is managed by the provided scope.
When to use
Use to obtain a scope-managed AbortSignal for APIs that accept cancellation through a signal.
Details
Each acquisition creates a fresh AbortController. Closing the owning scope runs a finalizer that aborts the controller and the effect succeeds with the controller's signal.
Gotchas
The signal is aborted when its owning scope closes, so avoid keeping it for work that outlives that scope.
See
scopedfor binding resource lifetime to a scope
Signature
declare const abortSignal: Effect<AbortSignal, never, Scope>;Returns an effect that is immediately interrupted.
Signature
declare const interrupt: Effect<never>;interruptible
Returns a new effect that allows the effect to be interruptible.
Signature
declare const interruptible: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;interruptibleMask
Runs an effect in an interruptible region while providing restore for locally restoring the previous interruptibility.
Signature
declare const interruptibleMask: <A, E, R>(
f: (restore: <AX, EX, RX>(effect: Effect<AX, EX, RX>) => Effect<AX, EX, RX>) => Effect<A, E, R>,
) => Effect<A, E, R>;onInterrupt
Runs the specified finalizer effect if this effect is interrupted.
Signature
declare const onInterrupt: {
<XE, XR>(
finalizer: (interruptors: ReadonlySet<number>) => Effect<void, XE, XR>,
): <A, E, R>(self: Effect<A, E, R>) => Effect<A, XE | E, XR | R>;
<A, E, R, XE, XR>(
self: Effect<A, E, R>,
finalizer: (interruptors: ReadonlySet<number>) => Effect<void, XE, XR>,
): Effect<A, E | XE, R | XR>;
};uninterruptible
Returns a new effect that disables interruption for the given effect.
Signature
declare const uninterruptible: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;uninterruptibleMask
Disables interruption and provides a restore function to restore the interruptible state within the effect.
Signature
declare const uninterruptibleMask: <A, E, R>(
f: (restore: <AX, EX, RX>(effect: Effect<AX, EX, RX>) => Effect<AX, EX, RX>) => Effect<A, E, R>,
) => Effect<A, E, R>;Logging
annotateLogs
Adds an annotation to each log line in this effect.
Signature
declare const annotateLogs: {
(key: string, value: unknown): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
(values: Record<string, unknown>): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
} & {
<A, E, R>(effect: Effect<A, E, R>, key: string, value: unknown): Effect<A, E, R>;
<A, E, R>(effect: Effect<A, E, R>, values: Record<string, unknown>): Effect<A, E, R>;
};annotateLogsScoped
Adds log annotations to the current scope.
When to use
Use to attach log annotations that last until the current scope closes.
Details
This differs from annotateLogs, which only annotates a specific effect. annotateLogsScoped updates annotations for the entire current Scope and restores the previous annotations when the scope closes.
See
annotateLogsfor annotating one effect
Signature
declare const annotateLogsScoped: {
(key: string, value: unknown): Effect<void, never, Scope>;
(values: Record<string, unknown>): Effect<void, never, Scope>;
};Logs one or more messages using the default log level.
Signature
declare const log: (...message: ReadonlyArray<any>) => Effect<void>;Logs one or more messages at the DEBUG level.
Signature
declare const logDebug: (...message: ReadonlyArray<any>) => Effect<void>;Logs one or more messages at the ERROR level.
Signature
declare const logError: (...message: ReadonlyArray<any>) => Effect<void>;Logs one or more messages at the FATAL level.
Signature
declare const logFatal: (...message: ReadonlyArray<any>) => Effect<void>;Logs one or more messages at the INFO level.
Signature
declare const logInfo: (...message: ReadonlyArray<any>) => Effect<void>;Logs one or more messages at the TRACE level.
Signature
declare const logTrace: (...message: ReadonlyArray<any>) => Effect<void>;logWarning
Logs one or more messages at the WARNING level.
Signature
declare const logWarning: (...message: ReadonlyArray<any>) => Effect<void>;logWithLevel
Creates a logger function that logs at the specified level.
Details
If no level is provided, the logger uses the fiber's current log level and extracts any Cause values from the message list.
Signature
declare const logWithLevel: (level?: Severity) => (...message: ReadonlyArray<any>) => Effect<void>;withLogger
Adds a logger to the set of loggers which will output logs for this effect.
Signature
declare const withLogger: <Output>(logger: Logger<unknown, Output>) => <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R> & <A, E, R, Output>(effect: Effect<A, E, R>, logger: Logger<unknown, Output>) => Effect<A, E, R>withLogSpan
Adds a span to each log line in this effect.
Signature
declare const withLogSpan: (label: string) => <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R> & <A, E, R>(effect: Effect<A, E, R>, label: string) => Effect<A, E, R>Mapping
Replaces the value inside an effect with a constant value.
When to use
Use to replace a successful value with a constant while preserving failures and requirements.
Details
as allows you to ignore the original value inside an effect and replace it with a new constant value.
See
Signature
declare const as: {
<B>(value: B): <A, E, R>(self: Effect<A, E, R>) => Effect<B, E, R>;
<A, E, R, B>(self: Effect<A, E, R>, value: B): Effect<B, E, R>;
};Maps the success value of an Effect to Some, preserving failures.
Signature
declare const asSome: <A, E, R>(self: Effect<A, E, R>) => Effect<Option<A>, E, R>;Maps the success value of an Effect to void, preserving failures.
Signature
declare const asVoid: <A, E, R>(self: Effect<A, E, R>) => Effect<void, E, R>;Gives a name to the success value of an Effect, creating a single-key record used in do notation pipelines.
When to use
Use to start a do-notation pipeline from an existing Effect when its success value should become the first named field in the accumulated record.
See
Signature
declare const bindTo: {
<N extends string>(
name: N,
): <A, E, R>(self: Effect<A, E, R>) => Effect<{ [K in string]: A }, E, R>;
<A, E, R, N extends string>(self: Effect<A, E, R>, name: N): Effect<{ [K in string]: A }, E, R>;
};Swaps an effect's success and failure channels.
When to use
Use to swap an Effect's success and failure channels.
Details
For an Effect<A, E, R>, the returned effect has type Effect<E, A, R>.
Signature
declare const flip: <A, E, R>(self: Effect<A, E, R>) => Effect<E, A, R>;Transforms the value inside an effect by applying a function to it.
When to use
Use to transform an effect's success value with a function that returns a plain value, producing a new effect without changing the original effect's typed error or context requirements.
Details
map takes a function and applies it to the value contained within an effect, creating a new effect with the transformed value.
It's important to note that effects are immutable, meaning that the original effect is not modified. Instead, a new effect is returned with the updated value.
See
Signature
declare const map: {
<A, B>(f: (a: A) => B): <E, R>(self: Effect<A, E, R>) => Effect<B, E, R>;
<A, E, R, B>(self: Effect<A, E, R>, f: (a: A) => B): Effect<B, E, R>;
};Applies transformations to both the success and error channels of an effect.
When to use
Use to transform both success and failure channels of an Effect without changing whether it succeeds or fails.
Details
This function takes two map functions as arguments: one for the error channel and one for the success channel. You can use it when you want to modify both the error and the success values without altering the overall success or failure status of the effect.
See
Signature
declare const mapBoth: {
<E, E2, A, A2>(options: {
readonly onFailure: (e: E) => E2;
readonly onSuccess: (a: A) => A2;
}): <R>(self: Effect<A, E, R>) => Effect<A2, E2, R>;
<A, E, R, E2, A2>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (e: E) => E2;
readonly onSuccess: (a: A) => A2;
},
): Effect<A2, E2, R>;
};mapBothEager
Applies mapBoth eagerly when an effect is already resolved.
When to use
Use when an already-resolved effect should transform either success or failure immediately while pending effects still use regular channel mapping.
Details
Success effects apply onSuccess immediately, and failure effects apply onFailure immediately. Pending effects fall back to regular mapBoth behavior.
Signature
declare const mapBothEager: {
<E, E2, A, A2>(options: {
readonly onFailure: (e: E) => E2;
readonly onSuccess: (a: A) => A2;
}): <R>(self: Effect<A, E, R>) => Effect<A2, E2, R>;
<A, E, R, E2, A2>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (e: E) => E2;
readonly onSuccess: (a: A) => A2;
},
): Effect<A2, E2, R>;
};Applies map eagerly when an effect is already resolved.
When to use
Use when an already-resolved effect should apply a success transformation immediately while pending effects still use regular mapping.
Details
Success effects apply the mapping function immediately. Failure effects pass through unchanged, and pending effects fall back to regular map behavior.
Signature
declare const mapEager: {
<A, B>(f: (a: A) => B): <E, R>(self: Effect<A, E, R>) => Effect<B, E, R>;
<A, E, R, B>(self: Effect<A, E, R>, f: (a: A) => B): Effect<B, E, R>;
};Metrics
Updates the Metric every time the Effect is executed.
Details
Also accepts an optional function which can be used to map the Exit value of the Effect into a valid Input for the Metric.
Signature
declare const track: {
<Input, State, E, A>(
metric: Metric<Input, State>,
f: (exit: Exit<A, E>) => Input,
): <E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<State, E, A>(
metric: Metric<Exit<NoInfer<A>, NoInfer<E>>, State>,
): <R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Input, State>(
self: Effect<A, E, R>,
metric: Metric<Input, State>,
f: (exit: Exit<A, E>) => Input,
): Effect<A, E, R>;
<A, E, R, State>(
self: Effect<A, E, R>,
metric: Metric<Exit<NoInfer<A>, NoInfer<E>>, State>,
): Effect<A, E, R>;
};trackDefects
Updates the provided Metric every time the wrapped Effect fails with an unexpected error (i.e. a defect).
Details
Also accepts an optional function which can be used to map the defect value of the Effect into a valid Input for the Metric.
Signature
declare const trackDefects: {
<Input, State>(
metric: Metric<Input, State>,
f: (defect: unknown) => Input,
): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<State, E>(metric: Metric<unknown, State>): <A, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Input, State>(
self: Effect<A, E, R>,
metric: Metric<Input, State>,
f: (defect: unknown) => Input,
): Effect<A, E, R>;
<A, E, R, State>(self: Effect<A, E, R>, metric: Metric<unknown, State>): Effect<A, E, R>;
};trackDuration
Updates the provided Metric with the Duration of time (in nanoseconds) that the wrapped Effect took to complete.
Details
Also accepts an optional function which can be used to map the Duration that the wrapped Effect took to complete into a valid Input for the Metric.
Signature
declare const trackDuration: {
<Input, State>(
metric: Metric<Input, State>,
f: (duration: Duration) => Input,
): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<State, E>(metric: Metric<Duration, State>): <A, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Input, State>(
self: Effect<A, E, R>,
metric: Metric<Input, State>,
f: (duration: Duration) => Input,
): Effect<A, E, R>;
<A, E, R, State>(self: Effect<A, E, R>, metric: Metric<Duration, State>): Effect<A, E, R>;
};trackErrors
Updates the provided Metric every time the wrapped Effect fails with an expected error.
Details
Also accepts an optional function which can be used to map the error value of the Effect into a valid Input for the Metric.
Signature
declare const trackErrors: {
<Input, State, E>(
metric: Metric<Input, State>,
f: (error: E) => Input,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<State, E>(metric: Metric<NoInfer<E>, State>): <A, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Input, State>(
self: Effect<A, E, R>,
metric: Metric<Input, State>,
f: (error: E) => Input,
): Effect<A, E, R>;
<A, E, R, State>(self: Effect<A, E, R>, metric: Metric<NoInfer<E>, State>): Effect<A, E, R>;
};trackSuccesses
Updates the provided Metric every time the wrapped Effect succeeds with a value.
Details
Also accepts an optional function which can be used to map the success value of the Effect into a valid Input for the Metric.
Signature
declare const trackSuccesses: {
<Input, State, A>(
metric: Metric<Input, State>,
f: (value: A) => Input,
): <E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<State, A>(metric: Metric<NoInfer<A>, State>): <E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Input, State>(
self: Effect<A, E, R>,
metric: Metric<Input, State>,
f: (value: A) => Input,
): Effect<A, E, R>;
<A, E, R, State>(self: Effect<A, E, R>, metric: Metric<NoInfer<A>, State>): Effect<A, E, R>;
};Models
The Effect interface defines a value that lazily describes a workflow or job. The workflow requires some context R, and may fail with an error of type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world, including synchronous, asynchronous, concurrent, and parallel interaction. They use a fiber-based concurrency model, with built-in support for scheduling, fine-grained interruption, structured concurrency, and high scalability.
To run an Effect value, you need a Runtime, which is a type that is capable of executing Effect values.
Signature
interface Effect<out A, out E = never, out R = never> extends Pipeable, Inspectable {
[ignoreSymbol]?: {};
[typeSymbol]?: unknown;
[unifySymbol]?: EffectUnify<Effect<A, E, R>>;
readonly "~effect/Effect": Variance<A, E, R>;
[iterator](): EffectIterator<Effect<A, E, R>>;
}EffectIterator interface
Iterator interface for Effect generators, enabling Effect values to work with generator functions.
When to use
Use when defining or typing [Symbol.iterator]() for values typed as Effects so yield* can pass their success type back into Effect.gen.
See
genfor writing generator-basedEffectprograms that consume this iterator protocol
Signature
interface EffectIterator<T extends Effect<any, any, any>> {
next(...args: readonly Array<any>): IteratorResult<T, Success<T>>;
}EffectUnify interface
Type-level unification support for Effect values.
Signature
interface EffectUnify<
A extends {
[typeSymbol]?: any;
},
> {
Effect?: () => A[typeof typeSymbol] extends Effect<A0, E0, R0> | _ ? Effect<A0, E0, R0> : never;
}Variance interface for Effect, encoding the type parameters' variance.
Signature
interface Variance<A, E, R> {
_A: Covariant<A>;
_E: Covariant<E>;
_R: Covariant<R>;
}Other
Namespace containing type utilities for the Effect.all function, which handles collecting multiple effects into various output structures.
Signature
declare const catch: {
<E, A2, E2, R2>(f: (e: E) => Effect<A2, E2, R2>): <A, R>(self: Effect<A, E, R>) => Effect<A2 | A, E2, R2 | R>;
<A, E, R, A2, E2, R2>(self: Effect<A, E, R>, f: (e: E) => Effect<A2, E2, R2>): Effect<A | A2, E2, R | R2>;
}Type helpers for converting callback-based functions into Effect functions.
Type helpers for functions built with Effect.fn and Effect.fnUntraced.
Details
Use these to describe generator-based signatures and traced or untraced variants.
Type helpers for Effect.gen generator return signatures.
Signature
declare const let: {
<N extends string, A extends Record<string, any>, B>(
name: N,
f: (a: NoInfer<A>) => B,
): <E, R>(self: Effect<A, E, R>) => Effect<Simplify<Omit<A, N> & Record<N, B>>, E, R>;
<A extends Record<string, any>, E, R, B, N extends string>(
self: Effect<A, E, R>,
name: N,
f: (a: NoInfer<A>) => B,
): Effect<Simplify<Omit<A, N> & Record<N, B>>, E, R>;
};Type helpers for repeating effects.
Type helpers for retrying effects.
Signature
declare const try: <A, E = Cause.UnknownError>(options: {
readonly catch: (error: unknown) => E;
readonly try: LazyArg<A>;
} | LazyArg<A>) => Effect<A, E>Signature
declare const undefined: Effect<undefined>;Signature
declare const void: Effect<void>Pattern Matching
Handles both success and failure cases of an effect without performing side effects.
When to use
Use when you need to fold an Effect into a value by handling success and failure differently without triggering side effects.
Details
match lets you define custom handlers for both success and failure scenarios. You provide separate functions to handle each case, allowing you to process the result if the effect succeeds, or handle the error if the effect fails.
See
matchEffectif you need to perform side effects in the handlers.
Signature
declare const match: {
<E, A2, A, A3>(options: {
readonly onFailure: (error: E) => A2;
readonly onSuccess: (value: A) => A3;
}): <R>(self: Effect<A, E, R>) => Effect<A2 | A3, never, R>;
<A, E, R, A2, A3>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (error: E) => A2;
readonly onSuccess: (value: A) => A3;
},
): Effect<A2 | A3, never, R>;
};matchCause
Handles failures by matching the cause of failure.
When to use
Use when you need to fold an Effect while the failure handler inspects the full Cause.
Details
The matchCause function allows you to handle failures with access to the full cause of the failure within a fiber.
See
matchCauseEffectif you need to perform side effects in the handlers.matchif you don't need to handle the cause of the failure.
Signature
declare const matchCause: {
<E, A2, A, A3>(options: {
readonly onFailure: (cause: Cause.Cause<E>) => A2;
readonly onSuccess: (a: A) => A3;
}): <R>(self: Effect<A, E, R>) => Effect<A2 | A3, never, R>;
<A, E, R, A2, A3>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (cause: Cause.Cause<E>) => A2;
readonly onSuccess: (a: A) => A3;
},
): Effect<A2 | A3, never, R>;
};matchCauseEager
Handles failures by matching the cause of failure with eager evaluation.
When to use
Use when you expect an Effect to already be resolved and want to match the Cause without regular effect pipeline overhead.
Details
matchCauseEager works like matchCause but provides better performance for resolved effects by immediately applying the matching function instead of deferring it through the effect pipeline.
Signature
declare const matchCauseEager: {
<E, A2, A, A3>(options: {
readonly onFailure: (cause: Cause.Cause<E>) => A2;
readonly onSuccess: (value: A) => A3;
}): <R>(self: Effect<A, E, R>) => Effect<A2 | A3, never, R>;
<A, E, R, A2, A3>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (cause: Cause.Cause<E>) => A2;
readonly onSuccess: (value: A) => A3;
},
): Effect<A2 | A3, never, R>;
};matchCauseEffect
Handles failures with access to the cause and allows performing side effects.
When to use
Use when you need to fold an Effect with effectful success handlers and Cause-aware failure handlers.
Details
The matchCauseEffect function works similarly to matchCause, but it also allows you to perform additional side effects based on the failure cause. This function provides access to the complete cause of the failure, making it possible to differentiate between various failure types, and allows you to respond accordingly while performing side effects (like logging or other operations).
See
matchCauseif you don't need side effects and only want to handle the result or failure.matchEffectif you don't need to handle the cause of the failure.
Signature
declare const matchCauseEffect: {
<E, A2, E2, R2, A, A3, E3, R3>(options: {
readonly onFailure: (cause: Cause.Cause<E>) => Effect<A2, E2, R2>;
readonly onSuccess: (a: A) => Effect<A3, E3, R3>;
}): <R>(self: Effect<A, E, R>) => Effect<A2 | A3, E2 | E3, R2 | R3 | R>;
<A, E, R, A2, E2, R2, A3, E3, R3>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (cause: Cause.Cause<E>) => Effect<A2, E2, R2>;
readonly onSuccess: (a: A) => Effect<A3, E3, R3>;
},
): Effect<A2 | A3, E2 | E3, R | R2 | R3>;
};matchCauseEffectEager
Handles success or failure eagerly with effectful handlers when the effect is already resolved.
When to use
Use when you need effectful success and cause-aware failure handlers for Effect inputs that may already be resolved.
Details
If the effect is an Exit, the matching handler runs immediately; otherwise it behaves like matchCauseEffect.
See
matchCauseEffectfor the non-eager effectful variantmatchCauseEagerfor eager cause matching with pure handlersmatchEffectfor effectful matching on typed failures instead of full causes
Signature
declare const matchCauseEffectEager: {
<E, A2, E2, R2, A, A3, E3, R3>(options: {
readonly onFailure: (cause: Cause.Cause<E>) => Effect<A2, E2, R2>;
readonly onSuccess: (a: A) => Effect<A3, E3, R3>;
}): <R>(self: Effect<A, E, R>) => Effect<A2 | A3, E2 | E3, R2 | R3 | R>;
<A, E, R, A2, E2, R2, A3, E3, R3>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (cause: Cause.Cause<E>) => Effect<A2, E2, R2>;
readonly onSuccess: (a: A) => Effect<A3, E3, R3>;
},
): Effect<A2 | A3, E2 | E3, R | R2 | R3>;
};matchEager
Handles both success and failure cases of an effect without performing side effects, with eager evaluation for resolved effects.
When to use
Use when you need to handle both success and failure cases of an already-resolved Effect with optimized handling.
Details
matchEager works like match but provides better performance for resolved effects (Success or Failure). When the effect is already resolved, it applies the handlers immediately without fiber scheduling. For unresolved effects, it falls back to the regular match behavior.
See
matchfor the non-eager version.matchEffectif you need to perform side effects in the handlers.
Signature
declare const matchEager: {
<E, A2, A, A3>(options: {
readonly onFailure: (error: E) => A2;
readonly onSuccess: (value: A) => A3;
}): <R>(self: Effect<A, E, R>) => Effect<A2 | A3, never, R>;
<A, E, R, A2, A3>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (error: E) => A2;
readonly onSuccess: (value: A) => A3;
},
): Effect<A2 | A3, never, R>;
};matchEffect
Handles both success and failure by running effectful handlers.
When to use
Use when you need to handle an Effect's failure or success with handlers that return effects.
Details
Use matchEffect when either branch needs to return an Effect, such as performing logging, recovery, notification, or other effectful work. The returned effect succeeds or fails according to the handler that is run.
See
matchif you don't need side effects and only want to handle the result or failure.
Signature
declare const matchEffect: {
<E, A2, E2, R2, A, A3, E3, R3>(options: {
readonly onFailure: (e: E) => Effect<A2, E2, R2>;
readonly onSuccess: (a: A) => Effect<A3, E3, R3>;
}): <R>(self: Effect<A, E, R>) => Effect<A2 | A3, E2 | E3, R2 | R3 | R>;
<A, E, R, A2, E2, R2, A3, E3, R3>(
self: Effect<A, E, R>,
options: {
readonly onFailure: (e: E) => Effect<A2, E2, R2>;
readonly onSuccess: (a: A) => Effect<A3, E3, R3>;
},
): Effect<A2 | A3, E2 | E3, R | R2 | R3>;
};Predicates
Determines whether an effect fails.
Details
Defects are not converted; if the effect dies, the resulting effect dies too.
Signature
declare const isFailure: <A, E, R>(self: Effect<A, E, R>) => Effect<boolean, never, R>;Returns whether an effect completes successfully.
Details
Returns false for failures in the error channel, but defects still fail the effect.
Signature
declare const isSuccess: <A, E, R>(self: Effect<A, E, R>) => Effect<boolean, never, R>;Providing Services
Provides dependencies to an effect using layers or a context. Use options.local to build the layer every time; by default, layers are shared between provide calls.
Signature
declare const provide: {
<Layers extends [Any, ...Array<Any>]>(
layers: Layers,
options?: {
readonly local?: boolean;
},
): <A, E, R>(
self: Effect<A, E, R>,
) => Effect<
A,
E | Error<Layers[number]>,
Services<Layers[number]> | Exclude<R, Success<Layers[number]>>
>;
<ROut, E2, RIn>(
layer: Layer<ROut, E2, RIn>,
options?: {
readonly local?: boolean;
},
): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E2 | E, RIn | Exclude<R, ROut>>;
<R2>(context: Context<R2>): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, R2>>;
<A, E, R, Layers extends [Any, ...Array<Any>]>(
self: Effect<A, E, R>,
layers: Layers,
options?: {
readonly local?: boolean;
},
): Effect<
A,
E | Error<Layers[number]>,
Services<Layers[number]> | Exclude<R, Success<Layers[number]>>
>;
<A, E, R, ROut, E2, RIn>(
self: Effect<A, E, R>,
layer: Layer<ROut, E2, RIn>,
options?: {
readonly local?: boolean;
},
): Effect<A, E | E2, RIn | Exclude<R, ROut>>;
<A, E, R, R2>(self: Effect<A, E, R>, context: Context<R2>): Effect<A, E, Exclude<R, R2>>;
};provideContext
Provides a context to an effect, fulfilling its service requirements.
Details
This function provides multiple services at once by supplying a context that contains all the required services. It removes the provided services from the effect's requirements, making them available to the effect.
Signature
declare const provideContext: {
<XR>(context: Context<XR>): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, XR>>;
<A, E, R, XR>(self: Effect<A, E, R>, context: Context<XR>): Effect<A, E, Exclude<R, XR>>;
};provideService
Provides one concrete service implementation to an effect.
When to use
Use to satisfy one service requirement with an already-built implementation.
Details
The service requirement identified by the Context.Key is removed from the effect requirements after the implementation is provided.
See
providefor providing multiple layers to an effect.provideServiceEffectfor acquiring the service implementation effectfully.provideContextfor providing a complete context.
Signature
declare const provideService: {
<I, S>(
service: Key<I, S>,
): {
(implementation: S): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, I>>;
<A, E, R>(self: Effect<A, E, R>, implementation: S): Effect<A, E, Exclude<R, I>>;
};
<I, S>(
service: Key<I, S>,
implementation: S,
): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, I>>;
<A, E, R, I, S>(
self: Effect<A, E, R>,
service: Key<I, S>,
implementation: S,
): Effect<A, E, Exclude<R, I>>;
};provideServiceEffect
Provides one service to an effect using an effectful acquisition.
When to use
Use when the service implementation must be created by an effect and its acquisition failure should remain in the returned effect.
Details
provideServiceEffect runs the acquisition effect to produce the service implementation, removes that service from the wrapped effect's requirements, and leaves any other requirements to be provided later. Acquisition failures are included in the returned effect's error channel.
Signature
declare const provideServiceEffect: {
<I, S, E2, R2>(
service: Key<I, S>,
acquire: Effect<NoInfer<S>, E2, R2>,
): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E2 | E, R2 | Exclude<R, I>>;
<A, E, R, I, S, E2, R2>(
self: Effect<A, E, R>,
service: Key<I, S>,
acquire: Effect<NoInfer<S>, E2, R2>,
): Effect<A, E | E2, R2 | Exclude<R, I>>;
};setContext
Runs an effect with the provided context as its complete environment.
When to use
Use when you already have a Context containing every service required by the effect and want the wrapped effect to run with exactly that context.
Gotchas
setContext replaces the current context for the wrapped effect. Services from an outer context are not inherited unless they are also present in the context passed to setContext.
See
provideContextfor partially satisfying an effect's context requirements.updateContextfor deriving the required context from the current one.
Signature
declare const setContext: {
<R>(context: Context<R>): <A, E>(self: Effect<A, E, R>) => Effect<A, E>;
<A, E, R>(self: Effect<A, E, R>, context: Context<R>): Effect<A, E>;
};updateContext
Provides part of the required context while leaving the rest unchanged.
Details
This function allows you to transform the context required by an effect, providing part of the context and leaving the rest to be fulfilled later.
Signature
declare const updateContext: {
<R2, R>(
f: (context: Context<R2>) => Context<NoInfer<R>>,
): <A, E>(self: Effect<A, E, R>) => Effect<A, E, R2>;
<A, E, R, R2>(
self: Effect<A, E, R>,
f: (context: Context<R2>) => Context<NoInfer<R>>,
): Effect<A, E, R2>;
};updateService
Runs an effect with a service implementation transformed by the provided function.
Details
The service must be available in the effect's context; updateService replaces it for the wrapped effect with the value returned by the updater.
Signature
declare const updateService: {
<I, A>(
service: Key<I, A>,
f: (value: A) => NoInfer<A>,
): <XA, E, R>(self: Effect<XA, E, R>) => Effect<XA, E, I | R>;
<XA, E, R, I, A>(
self: Effect<XA, E, R>,
service: Key<I, A>,
f: (value: A) => NoInfer<A>,
): Effect<XA, E, R | I>;
};updateServiceScoped
Updates a service for the lifetime of the current scope and restores its previous value when the scope closes.
When to use
Use when you need a setup effect to change a service for subsequent effects in the same scope.
Details
The updater receives the currently visible service value. A Context.Service remains in the requirements, while a Context.Reference uses its default when no override is present and adds no service requirement. The returned effect always requires Scope. The optional reset function receives the original, updated, and current values when the scope closes, allowing changes to be merged during restoration. It defaults to returning the original value.
See
updateServicefor updating a service only within a wrapped effect
Signature
declare const updateServiceScoped: <I, A>(
service: Context.Key<I, A>,
f: (value: A) => NoInfer<A>,
options?: {
readonly reset?: (original: A, updated: A, current: A) => A;
},
) => Effect<void, never, I | Scope>;Racing
Races two effects and returns the first successful result.
Details
If one effect succeeds, the other is interrupted and onWinner can observe the winning fiber. If both fail, the race fails.
Signature
declare const race: {
<A2, E2, R2>(
that: Effect<A2, E2, R2>,
options?: {
readonly onWinner?: (options: {
readonly fiber: Fiber<any, any>;
readonly index: number;
readonly parentFiber: Fiber<any, any>;
}) => void;
},
): <A, E, R>(self: Effect<A, E, R>) => Effect<A2 | A, E2 | E, R2 | R>;
<A, E, R, A2, E2, R2>(
self: Effect<A, E, R>,
that: Effect<A2, E2, R2>,
options?: {
readonly onWinner?: (options: {
readonly fiber: Fiber<any, any>;
readonly index: number;
readonly parentFiber: Fiber<any, any>;
}) => void;
},
): Effect<A | A2, E | E2, R | R2>;
};Runs multiple effects concurrently and returns the first successful result.
When to use
Use when early failures should be ignored until a success occurs or all effects fail.
Details
Early failures do not finish the race; raceAll keeps waiting until one effect succeeds or every effect has failed. When one effect succeeds, the remaining effects are interrupted. If every effect fails, the returned effect fails with a cause containing the collected failure reasons.
See
racefor a version that handles only two effects.
Signature
declare const raceAll: <Eff extends Effect<any, any, any>>(
all: Iterable<Eff>,
options?: {
readonly onWinner?: (options: {
readonly fiber: Fiber<any, any>;
readonly index: number;
readonly parentFiber: Fiber<any, any>;
}) => void;
},
) => Effect<Success<Eff>, Error<Eff>, Services<Eff>>;raceAllFirst
Runs multiple effects concurrently and completes with the first effect to finish, whether it succeeds or fails.
Details
After the first effect completes, all remaining effects are interrupted. Use raceAll when early failures should be ignored until a success occurs or all effects fail.
Signature
declare const raceAllFirst: <Eff extends Effect<any, any, any>>(
all: Iterable<Eff>,
options?: {
readonly onWinner?: (options: {
readonly fiber: Fiber<any, any>;
readonly index: number;
readonly parentFiber: Fiber<any, any>;
}) => void;
},
) => Effect<Success<Eff>, Error<Eff>, Services<Eff>>;Races two effects and returns the result of the first one to complete, whether it succeeds or fails.
When to use
Use when any completion, including failure, should decide the race and interrupt the losing effect.
Details
The losing effect is interrupted, and onWinner can observe the winning fiber.
Signature
declare const raceFirst: {
<A2, E2, R2>(
that: Effect<A2, E2, R2>,
options?: {
readonly onWinner?: (options: {
readonly fiber: Fiber<any, any>;
readonly index: number;
readonly parentFiber: Fiber<any, any>;
}) => void;
},
): <A, E, R>(self: Effect<A, E, R>) => Effect<A2 | A, E2 | E, R2 | R>;
<A, E, R, A2, E2, R2>(
self: Effect<A, E, R>,
that: Effect<A2, E2, R2>,
options?: {
readonly onWinner?: (options: {
readonly fiber: Fiber<any, any>;
readonly index: number;
readonly parentFiber: Fiber<any, any>;
}) => void;
},
): Effect<A | A2, E | E2, R | R2>;
};Repetition
eventually
Retries an effect until it succeeds, discarding failures.
Details
Yields between attempts so other fibers can run.
Signature
declare const eventually: <A, E, R>(self: Effect<A, E, R>) => Effect<A, never, R>;Repeats this effect forever (until the first error).
Signature
declare const forever: <
Arg extends
| Effect<any, any, any>
| {
readonly disableYield?: boolean;
}
| undefined = {
readonly disableYield?: boolean;
},
>(
effectOrOptions?: Arg,
options?: {
readonly disableYield?: boolean;
},
) => [Arg] extends [Effect<infer _A, infer _E, infer _R>]
? Effect<never, _E, _R>
: <A, E, R>(self: Effect<A, E, R>) => Effect<never, E, R>;Repeats an effect based on a specified schedule or until the first failure.
When to use
Use to rerun an effect after successful executions.
Details
This function executes an effect repeatedly according to the given schedule. Each repetition occurs after the initial execution of the effect, meaning that the schedule determines the number of additional repetitions. For example, using Schedule.once will result in the effect being executed twice (once initially and once as part of the repetition).
If the effect succeeds, it is repeated according to the schedule. If it fails, the repetition stops immediately, and the failure is returned.
The schedule can also specify delays between repetitions, making it useful for tasks like retrying operations with backoff, periodic execution, or performing a series of dependent actions.
You can combine schedules for more advanced repetition logic, such as adding delays, limiting recursions, or dynamically adjusting based on the outcome of each execution.
Gotchas
The source effect is always evaluated once before the schedule is stepped. The schedule controls additional repetitions, not the initial execution.
See
retryfor failure-based repetitionrepeatOrElsefor fallback handling when repetition fails
Signature
declare const repeat: {
<O extends Options<A>, A>(
options: O,
): <E, R>(
self: Effect<A, E, R>,
) => Effect<
O extends {
until: Predicate.Refinement<A, infer B>;
}
? B
: O extends {
while: Predicate.Refinement<A, infer B>;
}
? Exclude<A, B>
: A,
E | O extends {
schedule: Schedule<infer _Out, infer _I, infer E, infer _R>;
}
? E
: never | O extends {
while: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
}
? E
: never | O extends {
until: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
}
? E
: never,
R | O extends {
schedule: Schedule<infer _O, infer _I, infer _E, infer R>;
}
? R
: never | O extends {
while: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
}
? R
: never | O extends {
until: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
}
? R
: never
>;
<Output, Input, Error, Env>(
schedule: Schedule<Output, NoInfer<Input>, Error, Env>,
): <E, R>(self: Effect<Input, E, R>) => Effect<Output, Error | E, Env | R>;
<Output, Input, Error, Env>(
builder: (
$: <O, E, R>(_: Schedule<O, NoInfer<Input>, E, R>) => Schedule<O, Input, E, R>,
) => Schedule<Output, NoInfer<Input>, Error, Env>,
): <E, R>(self: Effect<Input, E, R>) => Effect<Output, Error | E, Env | R>;
<A, E, R, O extends Options<A>>(
self: Effect<A, E, R>,
options: O,
): Effect<
O extends {
until: Predicate.Refinement<A, infer B>;
}
? B
: O extends {
while: Predicate.Refinement<A, infer B>;
}
? Exclude<A, B>
: A,
E | O extends {
schedule: Schedule<infer _Out, infer _I, infer E, infer _R>;
}
? E
: never | O extends {
while: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
}
? E
: never | O extends {
until: (...args: Array<any>) => Effect<infer _A, infer E, infer _R>;
}
? E
: never,
R | O extends {
schedule: Schedule<infer _O, infer _I, infer _E, infer R>;
}
? R
: never | O extends {
while: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
}
? R
: never | O extends {
until: (...args: Array<any>) => Effect<infer _A, infer _E, infer R>;
}
? R
: never
>;
<Input, E, R, Output, Error, Env>(
self: Effect<Input, E, R>,
schedule: Schedule<Output, NoInfer<Input>, Error, Env>,
): Effect<Output, E | Error, R | Env>;
<Input, E, R, Output, Error, Env>(
self: Effect<Input, E, R>,
builder: (
$: <O, E, R>(_: Schedule<O, NoInfer<Input>, E, R>) => Schedule<O, Input, E, R>,
) => Schedule<Output, NoInfer<Input>, Error, Env>,
): Effect<Output, E | Error, R | Env>;
};repeatOrElse
Repeats an effect according to a schedule and runs a fallback effect if repetition fails before the schedule completes.
When to use
Use when successful repetitions should follow a schedule, but failures from the repeated effect or schedule need an effectful fallback.
Details
If the repeated effect or schedule step fails, orElse receives the failure and the latest schedule metadata when at least one schedule step has run; otherwise it receives None. If the schedule completes normally, the returned effect succeeds with the schedule's output.
Signature
declare const repeatOrElse: {
<R2, A, B, E, E2, E3, R3>(
schedule: Schedule<B, A, E2, R2>,
orElse: (error: E | E2, option: Option<B>) => Effect<B, E3, R3>,
): <R>(self: Effect<A, E, R>) => Effect<B, E3, R2 | R3 | R>;
<A, E, R, R2, B, E2, E3, R3>(
self: Effect<A, E, R>,
schedule: Schedule<B, A, E2, R2>,
orElse: (error: E | E2, option: Option<B>) => Effect<B, E3, R3>,
): Effect<B, E3, R | R2 | R3>;
};Returns an array of n identical effects.
When to use
Use when you need an array of identical effect values without running them yet.
Details
This only creates the array of effects. It does not run or collect them.
See
allfor running the returned effects and collecting resultsreplicateEffectfor repeating an effect and collecting results in one step with concurrency and discard options
Signature
declare const replicate: {
(n: number): <A, E, R>(self: Effect<A, E, R>) => Array<Effect<A, E, R>>;
<A, E, R>(self: Effect<A, E, R>, n: number): Array<Effect<A, E, R>>;
};replicateEffect
Performs this effect n times and collects results with Effect.all semantics.
When to use
Use when you want to run the repeated effects immediately, with optional concurrency control or result discarding.
Details
Use concurrency to control parallelism and discard: true to ignore results.
Signature
declare const replicateEffect: {
(
n: number,
options?: {
readonly concurrency?: Concurrency;
readonly discard?: false;
},
): <A, E, R>(self: Effect<A, E, R>) => Effect<Array<A>, E, R>;
(
n: number,
options: {
readonly concurrency?: Concurrency;
readonly discard: true;
},
): <A, E, R>(self: Effect<A, E, R>) => Effect<void, E, R>;
<A, E, R>(
self: Effect<A, E, R>,
n: number,
options?: {
readonly concurrency?: Concurrency;
readonly discard?: false;
},
): Effect<Array<A>, E, R>;
<A, E, R>(
self: Effect<A, E, R>,
n: number,
options: {
readonly concurrency?: Concurrency;
readonly discard: true;
},
): Effect<void, E, R>;
};Runs an effect repeatedly according to a schedule and returns the schedule's final output.
When to use
Use to rerun a successful effect according to a Schedule when the schedule does not need a custom initial input.
Details
The schedule is first stepped with undefined. After each successful execution, the effect's success value is fed to the schedule to decide whether to run again. The returned effect fails if the effect or schedule fails, and otherwise succeeds with the schedule output when the schedule completes.
See
scheduleFromfor a variant that allows the schedule's decision to depend on the result of this effect.
Signature
declare const schedule: {
<Output, Error, Env>(
schedule: Schedule<Output, unknown, Error, Env>,
): <A, E, R>(self: Effect<A, E, R>) => Effect<Output, Error | E, Env | R>;
<A, E, R, Output, Error, Env>(
self: Effect<A, E, R>,
schedule: Schedule<Output, unknown, Error, Env>,
): Effect<Output, E | Error, R | Env>;
};scheduleFrom
Runs an effect repeatedly according to a schedule that is initialized with a specific schedule input.
Details
initial is passed to the schedule before the first execution, not to the effect itself. After each successful execution, the effect's success value is fed back into the schedule to decide whether to continue. The returned effect succeeds with the schedule output when the schedule completes and fails if the effect or schedule fails.
Signature
declare const scheduleFrom: {
<Input, Output, Error, Env>(
initial: Input,
schedule: Schedule<Output, Input, Error, Env>,
): <E, R>(self: Effect<Input, E, R>) => Effect<Output, Error | E, Env | R>;
<Input, E, R, Output, Error, Env>(
self: Effect<Input, E, R>,
initial: Input,
schedule: Schedule<Output, Input, Error, Env>,
): Effect<Output, E | Error, R | Env>;
};Executes a body effect repeatedly while a condition holds true.
Signature
declare const whileLoop: <A, E, R>(options: {
readonly body: LazyArg<Effect<A, E, R>>;
readonly step: (a: A) => void;
readonly while: LazyArg<boolean>;
}) => Effect<void, E, R>;Resource Management
acquireDisposable
Acquires a scoped resource that implements JavaScript disposal protocols.
When to use
Use when you work with JavaScript Disposable or AsyncDisposable resources that should be closed with the surrounding scope.
Details
The resource is automatically disposed when the surrounding Scope is closed, using Symbol.dispose for synchronous disposables or Symbol.asyncDispose for asynchronous disposables.
This is similar to acquireRelease, but uses the standard JavaScript disposal protocol instead of requiring an explicit release function. It works with JavaScript Disposable and AsyncDisposable resources.
See
acquireReleasefor resources that need an explicit finalizer
Signature
declare const acquireDisposable: <A extends AsyncDisposable | Disposable, E, R>(
acquire: Effect<A, E, R>,
) => Effect<A, E, R | Scope>;acquireRelease
Constructs a scoped resource from an acquisition effect and a release finalizer.
When to use
Use to acquire a scoped resource with an explicit release finalizer.
Details
If acquisition succeeds, the release finalizer is added to the current scope and is guaranteed to run when that scope closes. The finalizer receives the Exit value used to close the scope.
By default, acquisition is protected by an uninterruptible region. Pass { interruptible: true } to allow the acquisition effect to be interrupted.
See
acquireDisposablefor resources that implement JavaScript disposal protocolsacquireUseReleasefor bracketing acquire, use, and release in one effect
Signature
declare const acquireRelease: <A, E, R, R2>(
acquire: Effect<A, E, R>,
release: (a: A, exit: Exit.Exit<unknown, unknown>) => Effect<unknown, never, R2>,
options?: {
readonly interruptible?: boolean;
},
) => Effect<A, E, R | R2 | Scope>;acquireUseRelease
Runs resource acquisition, usage, and release as one bracketed effect.
When to use
Use to bracket acquire, use, and release logic in one effect.
Details
acquireUseRelease does the following:
1. Ensures that the Effect value that acquires the resource will not be interrupted. Note that acquisition may still fail due to internal reasons (such as an uncaught exception). 2. Ensures that the release Effect value will not be interrupted, and will be executed as long as the acquisition Effect value successfully acquires the resource.
During the time period between the acquisition and release of the resource, the use Effect value will be executed.
If the release Effect value fails, then the entire Effect value will fail, even if the use Effect value succeeds. If this fail-fast behavior is not desired, errors produced by the release Effect value can be caught and ignored.
See
acquireReleasefor scoped resources whose use happens later
Signature
declare const acquireUseRelease: <Resource, E, R, A, E2, R2, E3, R3>(
acquire: Effect<Resource, E, R>,
use: (a: Resource) => Effect<A, E2, R2>,
release: (a: Resource, exit: Exit.Exit<A, E2>) => Effect<void, E3, R3>,
) => Effect<A, E | E2 | E3, R | R2 | R3>;addFinalizer
Adds a finalizer to the current scope.
When to use
Use to register low-level cleanup in the current scope.
Details
The finalizer runs when the surrounding scope is closed and receives the Exit value used to close the scope.
See
acquireReleasefor resource acquisition with a release finalizerensuringfor attaching a finalizer to one effect
Signature
declare const addFinalizer: <R>(
finalizer: (exit: Exit.Exit<unknown, unknown>) => Effect<void, never, R>,
) => Effect<void, never, R | Scope>;Returns an effect that, if this effect _starts_ execution, then the specified finalizer is guaranteed to be executed, whether this effect succeeds, fails, or is interrupted.
Details
For use cases that need access to the effect's result, see onExit.
Finalizers offer very powerful guarantees, but they are low-level, and should generally not be used for releasing resources. For higher-level logic built on ensuring, see the acquireRelease family of methods.
Signature
declare const ensuring: {
<X, R1>(
finalizer: Effect<X, never, R1>,
): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R1 | R>;
<A, E, R, X, R1>(self: Effect<A, E, R>, finalizer: Effect<X, never, R1>): Effect<A, E, R | R1>;
};Runs the specified effect if this effect fails, providing the error to the effect if it exists. The provided effect will not be interrupted.
Signature
declare const onError: {
<E, X, R2>(
cleanup: (cause: Cause<E>) => Effect<X, never, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E, R2 | R>;
<A, E, R, X, R2>(
self: Effect<A, E, R>,
cleanup: (cause: Cause<E>) => Effect<X, never, R2>,
): Effect<A, E, R | R2>;
};onErrorFilter
Runs the finalizer only when this effect fails and the cause matches the provided Filter.
When to use
Use when cleanup or diagnostics should run only for failures whose full Cause is accepted or transformed by a Filter, and the finalizer needs the filter's pass value plus the original cause.
See
onErrorfor cleanup on every failureonErrorIffor selecting failures with a boolean predicateonExitFilterfor selecting from every exit instead of only failures
Signature
declare const onErrorFilter: {
<A, E, EB, X, XE, XR>(
filter: Filter<Cause<E>, EB, X>,
f: (failure: EB, cause: Cause<E>) => Effect<void, XE, XR>,
): <R>(self: Effect<A, E, R>) => Effect<A, E | XE, XR | R>;
<A, E, R, EB, X, XE, XR>(
self: Effect<A, E, R>,
filter: Filter<Cause<E>, EB, X>,
f: (failure: EB, cause: Cause<E>) => Effect<void, XE, XR>,
): Effect<A, E | XE, R | XR>;
};Runs the finalizer only when this effect fails and the Cause matches the provided predicate.
Signature
declare const onErrorIf: {
<E, XE, XR>(
predicate: Predicate<Cause<E>>,
f: (cause: Cause<E>) => Effect<void, XE, XR>,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E | XE, XR | R>;
<A, E, R, XE, XR>(
self: Effect<A, E, R>,
predicate: Predicate<Cause<E>>,
f: (cause: Cause<E>) => Effect<void, XE, XR>,
): Effect<A, E | XE, R | XR>;
};Ensures that a cleanup function runs whether this effect succeeds, fails, or is interrupted.
Signature
declare const onExit: {
<A, E, XE = never, XR = never>(
f: (exit: Exit<A, E>) => Effect<void, XE, XR>,
): <R>(self: Effect<A, E, R>) => Effect<A, E | XE, XR | R>;
<A, E, R, XE = never, XR = never>(
self: Effect<A, E, R>,
f: (exit: Exit<A, E>) => Effect<void, XE, XR>,
): Effect<A, E | XE, R | XR>;
};onExitFilter
Runs the cleanup effect only when the Exit matches the provided Filter.
When to use
Use when cleanup should run only for Exit values selected by a Filter, and the cleanup needs the extracted pass value together with the original Exit.
Details
Result.fail skips cleanup, and Result.succeed runs cleanup with the selected value and the original Exit.
See
onExitfor cleanup on every exitonExitIffor selecting exits with a boolean predicateonErrorFilterfor selecting only failure causes
Signature
declare const onExitFilter: {
<A, E, XE, XR, B, X>(
filter: Filter<Exit<NoInfer<A>, NoInfer<E>>, B, X>,
f: (b: B, exit: Exit<NoInfer<A>, NoInfer<E>>) => Effect<void, XE, XR>,
): <R>(self: Effect<A, E, R>) => Effect<A, E | XE, XR | R>;
<A, E, R, XE, XR, B, X>(
self: Effect<A, E, R>,
filter: Filter<Exit<NoInfer<A>, NoInfer<E>>, B, X>,
f: (b: B, exit: Exit<NoInfer<A>, NoInfer<E>>) => Effect<void, XE, XR>,
): Effect<A, E | XE, R | XR>;
};Runs the cleanup effect only when the Exit satisfies the provided predicate.
Signature
declare const onExitIf: {
<A, E, XE, XR>(
predicate: Predicate<Exit<NoInfer<A>, NoInfer<E>>>,
f: (exit: Exit<NoInfer<A>, NoInfer<E>>) => Effect<void, XE, XR>,
): <R>(self: Effect<A, E, R>) => Effect<A, E | XE, XR | R>;
<A, E, R, XE, XR>(
self: Effect<A, E, R>,
predicate: Predicate<Exit<NoInfer<A>, NoInfer<E>>>,
f: (exit: Exit<NoInfer<A>, NoInfer<E>>) => Effect<void, XE, XR>,
): Effect<A, E | XE, R | XR>;
};onExitPrimitive
Runs an optional finalizer with the effect's Exit value when the effect completes.
When to use
Use when you are building a low-level Effect operator that must inspect the source effect's Exit, may skip finalization by returning undefined, or must choose whether finalization is forced into an uninterruptible region.
Details
This low-level operator preserves the source effect's result unless the finalizer fails. Prefer onExit for normal cleanup logic.
See
onExitfor ordinary exit-aware cleanup whose finalizer always returns an effect
Signature
declare const onExitPrimitive: <A, E, R, XE = never, XR = never>(
self: Effect<A, E, R>,
f: (exit: Exit.Exit<A, E>) => Effect<void, XE, XR> | undefined,
interruptible?: boolean,
) => Effect<A, E | XE, R | XR>;Returns the current scope for resource management.
Signature
declare const scope: Effect<Scope, never, Scope>;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.
Signature
declare const scoped: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, Scope>>;scopedWith
Creates a scoped effect by providing access to the scope.
When to use
Use when resource acquisition needs direct access to the scope being created, for example to register finalizers manually.
Signature
declare const scopedWith: <A, E, R>(f: (scope: Scope) => Effect<A, E, R>) => Effect<A, E, R>;Running
Executes a request using the provided resolver.
When to use
Use when you need resolver-driven batching for a typed Request.
See
requestUnsafefor the low-level entry point when you already have aContextand need to enqueue outside anEffect
Signature
declare const request: {
<A extends Any, EX = never, RX = never>(
resolver: RequestResolver<A> | Effect<RequestResolver<A>, EX, RX>,
): (self: A) => Effect<Success<A>, EX | Error<A>, RX | Services<A>>;
<A extends Any, EX = never, RX = never>(
self: A,
resolver: RequestResolver<A> | Effect<RequestResolver<A>, EX, RX>,
): Effect<Success<A>, EX | Error<A>, RX | Services<A>>;
};runCallback
Runs an effect asynchronously, registering onExit as a fiber observer and returning an interruptor.
Details
The interruptor calls fiber.interruptUnsafe with the optional interruptor id.
Signature
declare const runCallback: <A, E>(
effect: Effect<A, E, never>,
options?: RunOptions & {
readonly onExit: (exit: Exit.Exit<A, E>) => void;
},
) => (interruptor?: number) => void;runCallbackWith
Forks an effect with the provided services, registers onExit as a fiber observer, and returns an interruptor.
When to use
Use when embedding an effect into callback-style code with explicit services and a synchronous interruptor.
Details
The returned interruptor calls fiber.interruptUnsafe, optionally with an interruptor id.
Signature
declare const runCallbackWith: <R>(context: Context.Context<R>) => <A, E>(
effect: Effect<A, E, R>,
options?: RunOptions & {
readonly onExit: (exit: Exit.Exit<A, E>) => void;
},
) => (interruptor?: number) => void;Runs an effect in the background, returning a fiber that can be observed or interrupted.
When to use
Use when you need to start an effect in the background and receive a fiber.
Signature
declare const runFork: <A, E>(effect: Effect<A, E, never>, options?: RunOptions) => Fiber<A, E>;runForkWith
Runs an effect in the background with the provided services.
When to use
Use when an effect still requires services, you already have a Context, and you want a background fiber.
Signature
declare const runForkWith: <R>(
context: Context.Context<R>,
) => <A, E>(effect: Effect<A, E, R>, options?: RunOptions) => Fiber<A, E>;RunOptions interface
Configuration options for running Effect programs, providing control over interruption and scheduling behavior.
When to use
Use to pass cancellation, scheduler, interruptibility, and fiber-start hooks when running an Effect at a program boundary.
Details
signal interrupts the fiber, scheduler provides the scheduler service, uninterruptible starts the fiber uninterruptibly, and onFiberStart receives the created fiber.
See
runForkfor starting a fiber with these optionsrunCallbackfor callback-based running with these optionsrunPromisefor promise-based running with these optionsrunPromiseExitfor promise-based running that returns anExit
Signature
interface RunOptions {
readonly onFiberStart?: (fiber: Fiber<unknown, unknown>) => void;
readonly scheduler?: Scheduler;
readonly signal?: AbortSignal;
readonly uninterruptible?: boolean;
}runPromise
Executes an effect and returns the result as a Promise.
When to use
Use when you need to execute an effect and work with the result using Promise syntax, typically for compatibility with other promise-based code.
If the effect succeeds, the promise will resolve with the result. If the effect fails, the promise will reject with an error.
See
runPromiseExitfor a version that returns anExittype instead of rejecting.
Signature
declare const runPromise: <A, E>(effect: Effect<A, E>, options?: RunOptions) => Promise<A>;runPromiseExit
Runs an effect and returns a Promise that resolves to an Exit, which represents the outcome (success or failure) of the effect.
When to use
Use when you need to determine if an effect succeeded or failed, including any defects, and you want to work with a Promise.
Details
The Exit type represents the result of the effect. Successful effects are wrapped in Success, and failed effects are wrapped in Failure with a Cause.
See
runPromisefor a version that rejects on failure.
Signature
declare const runPromiseExit: <A, E>(
effect: Effect<A, E>,
options?: RunOptions,
) => Promise<Exit.Exit<A, E>>;runPromiseExitWith
Runs an effect and returns a Promise of Exit with provided services.
When to use
Use when you already have a Context and need Promise interop that preserves success and failure as an Exit.
Signature
declare const runPromiseExitWith: <R>(
context: Context.Context<R>,
) => <A, E>(effect: Effect<A, E, R>, options?: RunOptions) => Promise<Exit.Exit<A, E>>;runPromiseWith
Executes an effect as a Promise with the provided services.
When to use
Use when you already have a Context and need Promise interop that rejects on effect failure.
Signature
declare const runPromiseWith: <R>(
context: Context.Context<R>,
) => <A, E>(effect: Effect<A, E, R>, options?: RunOptions) => Promise<A>;Executes an effect synchronously and returns its success value.
When to use
Use when you need to execute an effect that is guaranteed to complete synchronously.
Details
If the effect fails, dies, is interrupted, or performs asynchronous work, runSync throws a FiberFailure instead of returning a value. Use runSyncExit when you want the failure captured as an Exit.
See
runSyncExitfor a version that returns anExittype instead of throwing an error.
Signature
declare const runSync: <A, E>(effect: Effect<A, E>) => A;runSyncExit
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
Use to find out whether an effect succeeded or failed, including any defects, without dealing with asynchronous operations.
Details
The Exit type represents the result of the effect. Successful effects are wrapped in Success, and failed effects are wrapped in Failure with a Cause.
If the effect contains asynchronous operations, runSyncExit will return an Failure with a Die cause, indicating that the effect cannot be resolved synchronously.
See
runSyncfor a version that throws on failure.
Signature
declare const runSyncExit: <A, E>(effect: Effect<A, E>) => Exit.Exit<A, E>;runSyncExitWith
Runs an effect synchronously with provided services, returning an Exit result safely.
When to use
Use when you already have a Context and need a synchronous Exit instead of throwing on failure.
Signature
declare const runSyncExitWith: <R>(
context: Context.Context<R>,
) => <A, E>(effect: Effect<A, E, R>) => Exit.Exit<A, E>;runSyncWith
Executes an effect synchronously with provided services.
When to use
Use when you already have a Context, the effect is known to complete synchronously, and failures should throw.
Signature
declare const runSyncWith: <R>(context: Context.Context<R>) => <A, E>(effect: Effect<A, E, R>) => A;Searching
Returns the first element that satisfies an effectful predicate.
Details
The predicate receives the element and its index. Evaluation short-circuits as soon as an element matches.
Signature
declare const findFirst: {
<A, E, R>(
predicate: (a: NoInfer<A>, i: number) => Effect<boolean, E, R>,
): (elements: Iterable<A>) => Effect<Option<A>, E, R>;
<A, E, R>(
elements: Iterable<A>,
predicate: (a: NoInfer<A>, i: number) => Effect<boolean, E, R>,
): Effect<Option<A>, E, R>;
};findFirstFilter
Returns the first value that passes an effectful FilterEffect.
When to use
Use when you need to find the first element that satisfies an effectful filter returning a Result, which also transforms the matching element.
Details
The filter receives the element and index. Evaluation short-circuits on the first Result.succeed and returns the transformed value in Option.some.
See
findFirstfor the simpler effectful predicate-based variant
Signature
declare const findFirstFilter: {
<A, B, X, E, R>(
filter: (input: NoInfer<A>, i: number) => Effect<Result<B, X>, E, R>,
): (elements: Iterable<A>) => Effect<Option<B>, E, R>;
<A, B, X, E, R>(
elements: Iterable<A>,
filter: (input: NoInfer<A>, i: number) => Effect<Result<B, X>, E, R>,
): Effect<Option<B>, E, R>;
};Sequencing
Runs this effect and then runs another effect, optionally using the first effect's success value to choose the next effect.
When to use
Use when you need one effect to run after another and the second effect may depend on the first effect's success value.
Details
When the second argument is an Effect, the first success value is discarded and the returned effect produces the second effect's value. When the second argument is a function, it receives the first success value and must return the next Effect.
Failures or requirements from either effect are preserved in the returned effect.
Signature
declare const andThen: {
<A, B, E2, R2>(
f: (a: A) => Effect<B, E2, R2>,
): <E, R>(self: Effect<A, E, R>) => Effect<B, E2 | E, R2 | R>;
<B, E2, R2>(f: Effect<B, E2, R2>): <A, E, R>(self: Effect<A, E, R>) => Effect<B, E2 | E, R2 | R>;
<A, E, R, B, E2, R2>(
self: Effect<A, E, R>,
f: (a: A) => Effect<B, E2, R2>,
): Effect<B, E | E2, R | R2>;
<A, E, R, B, E2, R2>(self: Effect<A, E, R>, f: Effect<B, E2, R2>): Effect<B, E | E2, R | R2>;
};awaitAllChildren
Waits for all child fibers forked by this effect to complete before this effect completes.
When to use
Use to let an effect start child work concurrently while still delaying its own completion until that child work is done.
Gotchas
Child fibers that already exist before the wrapped effect starts are not awaited.
See
forkChildfor forking child fibers that are awaited by this operatorforkDetachfor forking fibers outside the child scopeforkInfor forking into an explicit scopeforkScopedfor forking fibers tied to the current scope
Signature
declare const awaitAllChildren: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;Adds an Effect value to the do notation record under a given name.
When to use
Use to sequence an effectful step in a do-notation pipeline when that step depends on fields already accumulated in the record and its success value should be stored under a name.
Details
The function receives the current record, runs the returned effect after the input effect succeeds, and inserts its success value under name. The resulting effect combines the error and service requirements of both steps.
Gotchas
Binding a name that already exists replaces that field in the resulting record.
See
Signature
declare const bind: {
<N extends string, A extends Record<string, any>, B, E2, R2>(
name: N,
f: (a: NoInfer<A>) => Effect<B, E2, R2>,
): <E, R>(self: Effect<A, E, R>) => Effect<Simplify<Omit<A, N> & Record<N, B>>, E2 | E, R2 | R>;
<A extends Record<string, any>, E, R, B, E2, R2, N extends string>(
self: Effect<A, E, R>,
name: N,
f: (a: NoInfer<A>) => Effect<B, E2, R2>,
): Effect<Simplify<Omit<A, N> & Record<N, B>>, E | E2, R | R2>;
};Chains effects to produce new Effect instances, useful for combining operations that depend on previous results.
When to use
Use when you need to chain multiple effects, ensuring that each step produces a new Effect while flattening any nested effects that may occur.
Details
flatMap lets you sequence effects so that the result of one effect can be used in the next step. It is similar to flatMap used with arrays but works specifically with Effect instances, allowing you to avoid deeply nested effect structures.
Since effects are immutable, flatMap always returns a new effect instead of changing the original one.
See
tapfor a version that ignores the result of the effect.
Signature
declare const flatMap: {
<A, B, E1, R1>(
f: (a: A) => Effect<B, E1, R1>,
): <E, R>(self: Effect<A, E, R>) => Effect<B, E1 | E, R1 | R>;
<A, E, R, B, E1, R1>(
self: Effect<A, E, R>,
f: (a: A) => Effect<B, E1, R1>,
): Effect<B, E | E1, R | R1>;
};flatMapEager
Applies flatMap eagerly when an effect is already resolved.
When to use
Use when an already-resolved successful effect should bind immediately to the next effect while pending effects still use regular flat mapping.
Details
Success effects apply the flatMap function immediately. Failure effects pass through unchanged, and pending effects fall back to regular flatMap behavior.
Signature
declare const flatMapEager: {
<A, B, E2, R2>(
f: (a: A) => Effect<B, E2, R2>,
): <E, R>(self: Effect<A, E, R>) => Effect<B, E2 | E, R2 | R>;
<A, E, R, B, E2, R2>(
self: Effect<A, E, R>,
f: (a: A) => Effect<B, E2, R2>,
): Effect<B, E | E2, R | R2>;
};Flattens an Effect that produces another Effect into a single effect.
Signature
declare const flatten: <A, E, R, E2, R2>(
self: Effect<Effect<A, E, R>, E2, R2>,
) => Effect<A, E | E2, R | R2>;Executes an effectful operation for each element in an Iterable.
When to use
Use to traverse an iterable with an effectful function while preserving element order in the collected results.
Details
The forEach function applies a provided operation to each element in the iterable, producing a new effect that returns an array of results.
If any effect fails, the iteration stops immediately (short-circuiting), and the error is propagated.
Concurrency:
The concurrency option controls how many operations are performed concurrently. By default, the operations are performed sequentially.
Discarding Results:
If the discard option is set to true, the intermediate results are not collected, and the final result of the operation is void.
See
allfor combining multiple effects into one.
Signature
declare const forEach: {
<B, E, R, S extends Iterable<any, any, any>, Discard extends boolean = false>(
f: (a: Infer<S>, i: number) => Effect<B, E, R>,
options?: {
readonly concurrency?: Concurrency;
readonly discard?: Discard;
},
): (self: S) => Effect<Discard extends false ? With<S, B> : void, E, R>;
<B, E, R, S extends Iterable<any, any, any>, Discard extends boolean = false>(
self: S,
f: (a: Infer<S>, i: number) => Effect<B, E, R>,
options?: {
readonly concurrency?: Concurrency;
readonly discard?: Discard;
},
): Effect<Discard extends false ? With<S, B> : void, E, R>;
};Runs a side effect with the result of an effect without changing the original value.
When to use
Use when you need to run an effectful observation, such as logging or tracking, while passing the original success value to the next step.
Details
tap works similarly to flatMap, but it ignores the result of the function passed to it. The value from the previous effect remains available for the next part of the chain. Note that if the side effect fails, the entire chain will fail too.
Signature
declare const tap: {
<A, B, E2, R2>(
f: (a: NoInfer<A>) => Effect<B, E2, R2>,
): <E, R>(self: Effect<A, E, R>) => Effect<A, E2 | E, R2 | R>;
<B, E2, R2>(f: Effect<B, E2, R2>): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E2 | E, R2 | R>;
<A, E, R, B, E2, R2>(
self: Effect<A, E, R>,
f: (a: NoInfer<A>) => Effect<B, E2, R2>,
): Effect<A, E | E2, R | R2>;
<A, E, R, B, E2, R2>(self: Effect<A, E, R>, f: Effect<B, E2, R2>): Effect<A, E | E2, R | R2>;
};Runs an effectful operation with the full Cause when the source effect fails.
When to use
Use when failure observation needs typed failures, defects, and interruptions rather than only the typed error value.
Details
Use this to log or inspect typed failures, defects, and interruptions. When the operation succeeds, the original cause is preserved. If the operation fails, its error is also represented in the returned effect.
Signature
declare const tapCause: {
<E, X, E2, R2>(
f: (cause: Cause<NoInfer<E>>) => Effect<X, E2, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E | E2, R2 | R>;
<A, E, R, X, E2, R2>(
self: Effect<A, E, R>,
f: (cause: Cause<E>) => Effect<X, E2, R2>,
): Effect<A, E | E2, R | R2>;
};tapCauseFilter
Executes a side effect conditionally when a failed effect's cause passes a filter.
When to use
Use when you need to observe only failure causes selected by a Filter, while giving the side effect both the selected value and the original Cause.
Details
A successful filter result runs the side effect with the selected value and original cause. A failed filter result skips the side effect and preserves the original cause.
See
tapCauseIffor selecting causes with a boolean predicatetapCausefor observing every failure causecatchCauseFilterfor recovering from selected causes instead of only observing them
Signature
declare const tapCauseFilter: {
<E, B, E2, R2, EB, X extends Cause<any>>(
filter: Filter<Cause<E>, EB, X>,
f: (a: EB, cause: Cause<E>) => Effect<B, E2, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E | E2, R2 | R>;
<A, E, R, B, E2, R2, EB, X extends Cause<any>>(
self: Effect<A, E, R>,
filter: Filter<Cause<E>, EB, X>,
f: (a: EB, cause: Cause<E>) => Effect<B, E2, R2>,
): Effect<A, E | E2, R | R2>;
};tapCauseIf
Executes a side effect conditionally when a failed effect's cause matches a predicate.
Details
This function allows you to tap into the cause of an effect's failure only when the cause matches a specific predicate. This is useful for conditional logging, monitoring, or other side effects based on the type of failure.
Signature
declare const tapCauseIf: {
<E, B, E2, R2>(
predicate: Predicate<Cause<E>>,
f: (cause: Cause<E>) => Effect<B, E2, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E | E2, R2 | R>;
<A, E, R, B, E2, R2>(
self: Effect<A, E, R>,
predicate: Predicate<Cause<E>>,
f: (cause: Cause<E>) => Effect<B, E2, R2>,
): Effect<A, E | E2, R | R2>;
};Runs an effectful operation when the source effect dies with a defect.
Details
Use this for diagnostics such as logging unexpected thrown exceptions or values passed to die. Recoverable failures are not handled. When the operation succeeds, the original defect is preserved; if the operation fails, its error is also represented in the returned effect.
Signature
declare const tapDefect: {
<E, B, E2, R2>(
f: (defect: unknown) => Effect<B, E2, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E | E2, R2 | R>;
<A, E, R, B, E2, R2>(
self: Effect<A, E, R>,
f: (defect: unknown) => Effect<B, E2, R2>,
): Effect<A, E | E2, R | R2>;
};Runs an effectful operation when the source effect fails, while preserving the original failure when the operation succeeds.
Details
Use this for logging, metrics, or other failure-side observations. If the operation passed to tapError fails, that error is also represented in the returned effect's error channel.
Signature
declare const tapError: {
<E, X, E2, R2>(
f: (e: NoInfer<E>) => Effect<X, E2, R2>,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E | E2, R2 | R>;
<A, E, R, X, E2, R2>(
self: Effect<A, E, R>,
f: (e: E) => Effect<X, E2, R2>,
): Effect<A, E | E2, R | R2>;
};tapErrorTag
Runs an effectful handler when a failure's _tag matches.
Details
Use this with tagged-union errors to perform side effects for one tag or a list of tags. When the handler succeeds, the original failure is preserved; if the handler fails, its error is also included in the returned effect.
Signature
declare const tapErrorTag: {
<K extends string | readonly [Tags<E>, Tags<E>], E, A1, E1, R1>(
k: K,
f: (
e: ExtractTag<NoInfer<E>, K extends readonly [string, string] ? K[number] : K>,
) => Effect<A1, E1, R1>,
): <A, R>(self: Effect<A, E, R>) => Effect<A, E | E1, R1 | R>;
<A, E, R, K extends string | readonly [Tags<E>, Tags<E>], R1, E1, A1>(
self: Effect<A, E, R>,
k: K,
f: (
e: ExtractTag<E, K extends readonly [string, string] ? K[number] : K>,
) => Effect<A1, E1, R1>,
): Effect<A, E | E1, R | R1>;
};Services
Transaction
Service that holds the current transaction state.
Details
It includes a journal that stores non-committed changes to TxRef values and a retry flag that records whether the transaction should be retried.
Signature
declare class Transaction extends Shape<
"effect/Effect/Transaction",
{
readonly journal: Map<
TxRef<any>,
{
value: any;
readonly version: number;
}
>;
retry: boolean;
},
this
> {
constructor(_: never);
}Tracing
annotateCurrentSpan
Adds an annotation to the current span if available.
Signature
declare const annotateCurrentSpan: {
(key: string, value: unknown): Effect<void>;
(values: Record<string, unknown>): Effect<void>;
};annotateSpans
Adds an annotation to each span in this effect.
Signature
declare const annotateSpans: {
(key: string, value: unknown): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
(values: Record<string, unknown>): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R>(effect: Effect<A, E, R>, key: string, value: unknown): Effect<A, E, R>;
<A, E, R>(effect: Effect<A, E, R>, values: Record<string, unknown>): Effect<A, E, R>;
};currentParentSpan
Returns the current parent span from the effect context.
Details
The effect succeeds with either a local span or external span when one is present, and fails with NoSuchElementError when no parent span is available.
Signature
declare const currentParentSpan: Effect<AnySpan, Cause.NoSuchElementError>;currentSpan
Returns the currently active local tracing span.
Details
The effect fails with NoSuchElementError when there is no active local Span.
Signature
declare const currentSpan: Effect<Span, Cause.NoSuchElementError>;Adds a link with the provided span to all spans in this effect.
Details
This is useful for connecting spans that are related but not in a direct parent-child relationship. For example, you might want to link spans from parallel operations or connect spans across different traces.
Signature
declare const linkSpans: {
(span: AnySpan | readonly Array<AnySpan>, attributes?: Record<string, unknown>): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R>(self: Effect<A, E, R>, span: AnySpan | readonly Array<AnySpan>, attributes?: Record<string, unknown>): Effect<A, E, R>;
}Creates a new tracing span and returns it without managing its lifetime.
Details
The span is not added to the current span stack and is not ended automatically. Use withSpan, useSpan, or makeSpanScoped when the span should be installed as context or closed automatically.
Signature
declare const makeSpan: (name: string, options?: SpanOptionsNoTrace) => Effect<Span>;makeSpanScoped
Create a new span for tracing, and automatically close it when the Scope finalizes.
Details
The span is not added to the current span stack, so no child spans will be created for it.
Signature
declare const makeSpanScoped: (
name: string,
options?: SpanOptionsNoTrace,
) => Effect<Span, never, Scope>;spanAnnotations
Returns the tracing span annotations currently carried in the effect context.
Details
These annotations are applied to spans created inside the context, such as spans created by withSpan, useSpan, or makeSpan.
Signature
declare const spanAnnotations: Effect<Readonly<Record<string, unknown>>>;Returns the tracing span links currently carried in the effect context.
Details
These links are attached to spans created inside the context. Span links connect related spans without making one span the parent of another.
Signature
declare const spanLinks: Effect<ReadonlyArray<SpanLink>>;Returns the current tracer from the context.
Signature
declare const tracer: Effect<Tracer>;Create a new span for tracing, and automatically close it when the effect completes.
Details
The span is not added to the current span stack, so no child spans will be created for it.
Signature
declare const useSpan: {
<A, E, R>(name: string, evaluate: (span: Span) => Effect<A, E, R>): Effect<A, E, R>;
<A, E, R>(
name: string,
options: SpanOptionsNoTrace,
evaluate: (span: Span) => Effect<A, E, R>,
): Effect<A, E, R>;
};withParentSpan
Adds the provided span to the current span stack.
Signature
declare const withParentSpan: {
(
value: AnySpan,
options?: TraceOptions,
): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, ParentSpan>>;
<A, E, R>(
self: Effect<A, E, R>,
value: AnySpan,
options?: TraceOptions,
): Effect<A, E, Exclude<R, ParentSpan>>;
};Wraps the effect with a child span for tracing.
Signature
declare const withSpan: {
<Args extends readonly Array<any>>(name: string, options?: SpanOptionsNoTrace | (...args: NoInfer<Args>) => SpanOptionsNoTrace, traceOptions?: TraceOptions): <A, E, R>(self: Effect<A, E, R>, ...args: Args) => Effect<A, E, Exclude<R, ParentSpan>>;
<A, E, R>(self: Effect<A, E, R>, name: string, options?: SpanOptions): Effect<A, E, Exclude<R, ParentSpan>>;
}withSpanScoped
Wraps the effect with a scoped child span for tracing.
Details
The span is ended when the Scope is finalized.
Signature
declare const withSpanScoped: {
(
name: string,
options?: SpanOptions,
): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Scope | Exclude<R, ParentSpan>>;
<A, E, R>(
self: Effect<A, E, R>,
name: string,
options?: SpanOptions,
): Effect<A, E, Scope | Exclude<R, ParentSpan>>;
};withTracer
Provides a tracer to an effect.
Signature
declare const withTracer: {
(value: Tracer): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R>(effect: Effect<A, E, R>, value: Tracer): Effect<A, E, R>;
};withTracerEnabled
Enables or disables tracing for spans created by the given effect.
Details
When enabled is false, spans created inside the effect are not registered with the current tracer and do not propagate as normal trace parents.
Signature
declare const withTracerEnabled: {
(enabled: boolean): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R>(effect: Effect<A, E, R>, enabled: boolean): Effect<A, E, R>;
};withTracerTiming
Enables or disables tracer timing for the given Effect.
Signature
declare const withTracerTiming: {
(enabled: boolean): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R>(effect: Effect<A, E, R>, enabled: boolean): Effect<A, E, R>;
};Transactions
Defines a transaction boundary. Transactions are "all or nothing" with respect to changes made to transactional values (i.e. TxRef) that occur within the transaction body.
Details
If called inside an active transaction, tx composes with the current transaction and reuses its journal and retry state instead of creating a nested boundary.
Effect transactions are optimistic with retry. A transaction is retried when its body explicitly calls Effect.txRetry and any accessed transactional value changes, or when any accessed transactional value changes because a different transaction commits before the current one.
The outermost tx call creates the transaction boundary and commits or rolls back the full composed transaction.
Signature
declare function tx<A, E, R>(effect: Effect<A, E, R>): Effect<A, E, Exclude<R, Transaction>>;Retries the current transaction by signaling that it must be retried.
Details
NOTE: the transaction retries on any change to transactional values (i.e. TxRef) accessed in its body.
Signature
declare const txRetry: Effect<never, never, Transaction>;Type IDs
Unsafe
requestUnsafe
Registers a request with a resolver and delivers the exit value via onExit.
When to use
Use when you already have a Context and need to enqueue a request outside an Effect while receiving completion through onExit.
Details
It returns a canceler that removes the pending request entry.
See
requestfor theEffect-returning API used for normal request execution
Signature
declare const requestUnsafe: <A extends Request.Any>(
self: A,
options: {
readonly context: Context.Context<never>;
readonly onExit: (exit: Exit.Exit<Request.Success<A>, Request.Error<A>>) => void;
readonly resolver: RequestResolver<A>;
},
) => () => void;Utility Types
EffectTypeLambda interface
Type lambda used to represent Effect in higher-kinded APIs.
Signature
interface EffectTypeLambda extends TypeLambda {
readonly type: Effect<unknown, unknown, unknown>;
}Extracts the error type from an Effect.
When to use
Use to derive the error type from an existing Effect type when declaring helper types, wrappers, or APIs that preserve the effect's failure channel.
Details
Non-Effect inputs resolve to never.
See
Signature
type Error<T> = T extends Effect<infer _A, infer _E, infer _R> ? _E : never;satisfiesErrorType
Ensures that an effect's error type extends a given type E.
Details
This helper is checked at compile time and does not change the effect's runtime behavior.
Signature
declare function satisfiesErrorType<E>(): <A, E2, R>(effect: Effect<A, E2, R>) => Effect<A, E2, R>;satisfiesServicesType
Ensures that an effect's requirements type extends a given type R.
Details
This helper is checked at compile time and does not change the effect's runtime behavior.
Signature
declare function satisfiesServicesType<R>(): <A, E, R2>(
effect: Effect<A, E, R2>,
) => Effect<A, E, R2>;satisfiesSuccessType
Ensures that an effect's success type extends a given type A.
Details
This helper is checked at compile time and does not change the effect's runtime behavior.
Signature
declare function satisfiesSuccessType<A>(): <A2, E, R>(
effect: Effect<A2, E, R>,
) => Effect<A2, E, R>;Extracts the required services type from an Effect.
When to use
Use to derive the context requirements of a generic or inferred Effect without restating its R type parameter.
See
Signature
type Services<T> = T extends Effect<infer _A, infer _E, infer _R> ? _R : never;Extracts the success type from an Effect.
When to use
Use to derive the value produced by an existing effect when declaring reusable type aliases, service interfaces, or function signatures.
See
Signature
type Success<T> = T extends Effect<infer _A, infer _E, infer _R> ? _A : never;Validation
Applies an effectful function to each element and accumulates all failures.
Details
This function always evaluates every element. If at least one effect fails, all failures are returned as a non-empty array and successes are discarded. If all effects succeed, it returns all collected successes.
Use discard: true to ignore successful values while still validating all elements.
Signature
declare const validate: {
<A, B, E, R>(
f: (a: A, i: number) => Effect<B, E, R>,
options?: {
readonly concurrency?: Concurrency;
readonly discard?: false;
},
): (elements: Iterable<A>) => Effect<Array<B>, [E, ...Array<E>], R>;
<A, B, E, R>(
f: (a: A, i: number) => Effect<B, E, R>,
options: {
readonly concurrency?: Concurrency;
readonly discard: true;
},
): (elements: Iterable<A>) => Effect<void, [E, ...Array<E>], R>;
<A, B, E, R>(
elements: Iterable<A>,
f: (a: A, i: number) => Effect<B, E, R>,
options?: {
readonly concurrency?: Concurrency;
readonly discard?: false;
},
): Effect<Array<B>, [E, ...Array<E>], R>;
<A, B, E, R>(
elements: Iterable<A>,
f: (a: A, i: number) => Effect<B, E, R>,
options: {
readonly concurrency?: Concurrency;
readonly discard: true;
},
): Effect<void, [E, ...Array<E>], R>;
};Zipping
Combines two effects into a single effect, producing a tuple with the results of both effects.
When to use
Use to combine exactly two effects into a tuple.
Details
The zip function executes the first effect (left) and then the second effect (right). Once both effects succeed, their results are combined into a tuple.
Concurrency:
By default, zip processes the effects sequentially. To execute the effects concurrently, use the { concurrent: true } option.
See
Signature
declare const zip: {
<A2, E2, R2>(
that: Effect<A2, E2, R2>,
options?: {
readonly concurrent?: boolean;
},
): <A, E, R>(self: Effect<A, E, R>) => Effect<[A, A2], E2 | E, R2 | R>;
<A, E, R, A2, E2, R2>(
self: Effect<A, E, R>,
that: Effect<A2, E2, R2>,
options?: {
readonly concurrent?: boolean;
},
): Effect<[A, A2], E | E2, R | R2>;
};Combines two effects sequentially and applies a function to their results to produce a single value.
When to use
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
Concurrency:
By default, the effects are run sequentially. To execute them concurrently, use the { concurrent: true } option.
Signature
declare const zipWith: {
<A2, E2, R2, A, B>(
that: Effect<A2, E2, R2>,
f: (a: A, b: A2) => B,
options?: {
readonly concurrent?: boolean;
},
): <E, R>(self: Effect<A, E, R>) => Effect<B, E2 | E, R2 | R>;
<A, E, R, A2, E2, R2, B>(
self: Effect<A, E, R>,
that: Effect<A2, E2, R2>,
f: (a: A, b: A2) => B,
options?: {
readonly concurrent?: boolean;
},
): Effect<B, E | E2, R | R2>;
};
Retrieves the
Clockservice from the context and provides it to the specified effectful function.