/** * One-time coordination cells for Effect programs. A `Deferred` starts * empty, can be completed exactly once with a success, failure, defect, or * interruption, and lets any number of fibers wait for that result. Awaiting a * `Deferred` suspends the fiber instead of blocking an operating-system thread, * and every waiter observes the same completion. * * @stability stable * @since 2.0.0 */ import type * as Cause from "./Cause.ts"; import type { Effect } from "./Effect.ts"; import type * as Exit from "./Exit.ts"; import { type LazyArg } from "./Function.ts"; import * as Option from "./Option.ts"; import type { Pipeable } from "./Pipeable.ts"; import type * as Types from "./Types.ts"; declare const TypeId = "~effect/Deferred"; /** * A `Deferred` represents an asynchronous variable that can be set exactly * once, with the ability for an arbitrary number of fibers to suspend (by * calling `Deferred.await`) and automatically resume when the variable is set. * * **When to use** * * Use to coordinate multiple fibers around a value or failure that will be * supplied exactly once. * * **Example** (Creating a Deferred for inter-fiber communication) * * ```ts import.meta.vitest * import { Deferred, Effect, Fiber } from "effect" * * const program = Effect.gen(function*() { * const deferred: Deferred.Deferred = yield* Deferred.make() * const producer = yield* Effect.forkChild( * Effect.gen(function*() { * yield* Deferred.succeed(deferred, "Hello, World!") * }) * ) * * const consumer = yield* Effect.forkChild(Deferred.await(deferred)) * yield* Fiber.join(producer) * return yield* Fiber.join(consumer) * }) * * await Effect.runPromise(program) // => "Hello, World!" * ``` * * @stability stable * @category models * @since 2.0.0 */ export interface Deferred extends Deferred.Variance, Pipeable { effect?: Effect; resumes?: Array<(effect: Effect) => void> | undefined; } /** * Checks whether a value is a `Deferred`. * * **When to use** * * Use to validate unknown values at runtime boundaries before treating them as * `Deferred` values. * * @stability stable * @category guards * @since 4.0.0 */ export declare const isDeferred: (u: unknown) => u is Deferred; /** * Companion namespace containing type-level metadata for `Deferred`. * * **When to use** * * Use to reference type-level metadata associated with `Deferred`. * * @stability stable * @since 2.0.0 */ export declare namespace Deferred { /** * Type-level variance marker for the value and error channels of `Deferred`. * * **When to use** * * Use to carry the value and error type parameters for `Deferred` in Effect's * type machinery. * * **Details** * * This interface is part of the public type structure and is not intended to * be constructed directly. * * @category models * @since 2.0.0 */ interface Variance { readonly [TypeId]: { readonly _A: Types.Invariant; readonly _E: Types.Invariant; }; } } /** * Creates an empty `Deferred` synchronously outside the `Effect` runtime. * * **When to use** * * Use to allocate a `Deferred` synchronously when direct allocation outside * `Effect` is required. * * **Example** (Creating a Deferred unsafely) * * ```ts import.meta.vitest * import { Deferred } from "effect" * * const deferred = Deferred.makeUnsafe() * Deferred.isDoneUnsafe(deferred) // => false * ``` * * @stability stable * @category unsafe * @since 4.0.0 */ export declare const makeUnsafe: () => Deferred; /** * Creates a new `Deferred`. * * **When to use** * * Use to allocate an empty `Deferred` inside an `Effect` workflow. * * **Example** (Creating a Deferred) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.succeed(deferred, 42) * return yield* Deferred.await(deferred) * }) * * await Effect.runPromise(program) // => 42 * ``` * * @stability stable * @category constructors * @since 2.0.0 */ export declare const make: () => Effect>; declare const _await: (self: Deferred) => Effect; export { /** * Retrieves the value of the `Deferred`, suspending the fiber running the * workflow until the result is available. * * **When to use** * * Use to wait for a `Deferred` to be completed and resume with its success, * failure, defect, or interruption. * * **Details** * * Awaiters observe the completion effect stored in the `Deferred`. * * **Example** (Awaiting a Deferred value) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.succeed(deferred, 42) * * return yield* Deferred.await(deferred) * }) * * await Effect.runPromise(program) // => 42 * ``` * * @see {@link complete} for completing from an effect and memoizing its result * @see {@link completeWith} for completing with an effect directly * * @stability stable * @category getters * @since 2.0.0 */ _await as await }; /** * Runs the supplied `Effect` and attempts to complete the `Deferred` with its * memoized result. * * **When to use** * * Use when completing a `Deferred` should run an effect once and share its * result with all awaiters. * * **Details** * * The returned effect succeeds with `true` when this call completed the * `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred from an effect) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const completed = yield* Deferred.complete(deferred, Effect.succeed(42)) * const value = yield* Deferred.await(deferred) * return [completed, value] * }) * * await Effect.runPromise(program) // => [true, 42] * ``` * * @see {@link completeWith} for storing an effect directly without memoizing its result * * @stability stable * @category completion * @since 2.0.0 */ export declare const complete: { /** * Runs the supplied `Effect` and attempts to complete the `Deferred` with its * memoized result. * * **When to use** * * Use when completing a `Deferred` should run an effect once and share its * result with all awaiters. * * **Details** * * The returned effect succeeds with `true` when this call completed the * `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred from an effect) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const completed = yield* Deferred.complete(deferred, Effect.succeed(42)) * const value = yield* Deferred.await(deferred) * return [completed, value] * }) * * await Effect.runPromise(program) // => [true, 42] * ``` * * @see {@link completeWith} for storing an effect directly without memoizing its result * * @stability stable * @category completion * @since 2.0.0 */ (effect: Effect): (self: Deferred) => Effect; /** * Runs the supplied `Effect` and attempts to complete the `Deferred` with its * memoized result. * * **When to use** * * Use when completing a `Deferred` should run an effect once and share its * result with all awaiters. * * **Details** * * The returned effect succeeds with `true` when this call completed the * `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred from an effect) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const completed = yield* Deferred.complete(deferred, Effect.succeed(42)) * const value = yield* Deferred.await(deferred) * return [completed, value] * }) * * await Effect.runPromise(program) // => [true, 42] * ``` * * @see {@link completeWith} for storing an effect directly without memoizing its result * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, effect: Effect): Effect; }; /** * Attempts to complete the `Deferred` with the specified effect directly. * * **When to use** * * Use to store an already environment-free effect as the completion without * running it during completion. * * **Details** * * The returned effect succeeds with `true` when this call completed the * `Deferred`, or `false` if it was already completed. * * **Gotchas** * * The supplied effect is not memoized by `completeWith`; each awaiter may run * the stored effect independently. * * **Example** (Completing a Deferred with an effect) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const completed = yield* Deferred.completeWith(deferred, Effect.succeed(42)) * const value = yield* Deferred.await(deferred) * return [completed, value] * }) * * await Effect.runPromise(program) // => [true, 42] * ``` * * @see {@link complete} for running an effect once and sharing its result * @see {@link done} for completing from an already computed `Exit` * * @stability stable * @category completion * @since 2.0.0 */ export declare const completeWith: { /** * Attempts to complete the `Deferred` with the specified effect directly. * * **When to use** * * Use to store an already environment-free effect as the completion without * running it during completion. * * **Details** * * The returned effect succeeds with `true` when this call completed the * `Deferred`, or `false` if it was already completed. * * **Gotchas** * * The supplied effect is not memoized by `completeWith`; each awaiter may run * the stored effect independently. * * **Example** (Completing a Deferred with an effect) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const completed = yield* Deferred.completeWith(deferred, Effect.succeed(42)) * const value = yield* Deferred.await(deferred) * return [completed, value] * }) * * await Effect.runPromise(program) // => [true, 42] * ``` * * @see {@link complete} for running an effect once and sharing its result * @see {@link done} for completing from an already computed `Exit` * * @stability stable * @category completion * @since 2.0.0 */ (effect: Effect): (self: Deferred) => Effect; /** * Attempts to complete the `Deferred` with the specified effect directly. * * **When to use** * * Use to store an already environment-free effect as the completion without * running it during completion. * * **Details** * * The returned effect succeeds with `true` when this call completed the * `Deferred`, or `false` if it was already completed. * * **Gotchas** * * The supplied effect is not memoized by `completeWith`; each awaiter may run * the stored effect independently. * * **Example** (Completing a Deferred with an effect) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const completed = yield* Deferred.completeWith(deferred, Effect.succeed(42)) * const value = yield* Deferred.await(deferred) * return [completed, value] * }) * * await Effect.runPromise(program) // => [true, 42] * ``` * * @see {@link complete} for running an effect once and sharing its result * @see {@link done} for completing from an already computed `Exit` * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, effect: Effect): Effect; }; /** * Completes the `Deferred` with the specified `Exit` value, which will be * propagated to all fibers waiting on the value of the `Deferred`. * * **When to use** * * Use to complete a `Deferred` from an already computed `Exit`. * * **Details** * * The returned effect succeeds with `true` when this call completed the * `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred with an Exit) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.done(deferred, Exit.succeed(42)) * return yield* Effect.exit(Deferred.await(deferred)) * }) * * await Effect.runPromise(program) // => Exit.succeed(42) * ``` * * @see {@link complete} for completing from an effect and memoizing its result * @see {@link completeWith} for storing an effect directly * @see {@link succeed} for completing with a success value * @see {@link failCause} for completing with a failure cause * * @stability stable * @category completion * @since 2.0.0 */ export declare const done: { /** * Completes the `Deferred` with the specified `Exit` value, which will be * propagated to all fibers waiting on the value of the `Deferred`. * * **When to use** * * Use to complete a `Deferred` from an already computed `Exit`. * * **Details** * * The returned effect succeeds with `true` when this call completed the * `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred with an Exit) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.done(deferred, Exit.succeed(42)) * return yield* Effect.exit(Deferred.await(deferred)) * }) * * await Effect.runPromise(program) // => Exit.succeed(42) * ``` * * @see {@link complete} for completing from an effect and memoizing its result * @see {@link completeWith} for storing an effect directly * @see {@link succeed} for completing with a success value * @see {@link failCause} for completing with a failure cause * * @stability stable * @category completion * @since 2.0.0 */ (exit: Exit.Exit): (self: Deferred) => Effect; /** * Completes the `Deferred` with the specified `Exit` value, which will be * propagated to all fibers waiting on the value of the `Deferred`. * * **When to use** * * Use to complete a `Deferred` from an already computed `Exit`. * * **Details** * * The returned effect succeeds with `true` when this call completed the * `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred with an Exit) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.done(deferred, Exit.succeed(42)) * return yield* Effect.exit(Deferred.await(deferred)) * }) * * await Effect.runPromise(program) // => Exit.succeed(42) * ``` * * @see {@link complete} for completing from an effect and memoizing its result * @see {@link completeWith} for storing an effect directly * @see {@link succeed} for completing with a success value * @see {@link failCause} for completing with a failure cause * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, exit: Exit.Exit): Effect; }; /** * Attempts to complete the `Deferred` with the specified error. * * **When to use** * * Use to complete a `Deferred` with a typed failure value. * * **Details** * * Fibers waiting on the `Deferred` fail with that error only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with an error) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.fail(deferred, "Operation failed") * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.fail("Operation failed")] * ``` * * @stability stable * @category completion * @since 2.0.0 */ export declare const fail: { /** * Attempts to complete the `Deferred` with the specified error. * * **When to use** * * Use to complete a `Deferred` with a typed failure value. * * **Details** * * Fibers waiting on the `Deferred` fail with that error only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with an error) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.fail(deferred, "Operation failed") * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.fail("Operation failed")] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (error: E): (self: Deferred) => Effect; /** * Attempts to complete the `Deferred` with the specified error. * * **When to use** * * Use to complete a `Deferred` with a typed failure value. * * **Details** * * Fibers waiting on the `Deferred` fail with that error only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with an error) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.fail(deferred, "Operation failed") * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.fail("Operation failed")] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, error: E): Effect; }; /** * Computes an error when the returned effect is run, then attempts to complete * the `Deferred` with that error. * * **When to use** * * Use to lazily compute a typed failure value when the `Deferred` completion * effect runs. * * **Details** * * Fibers waiting on the `Deferred` fail with the computed error only if this * call completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with a lazy error) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.failSync(deferred, () => "Lazy error") * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.fail("Lazy error")] * ``` * * @stability stable * @category completion * @since 2.0.0 */ export declare const failSync: { /** * Computes an error when the returned effect is run, then attempts to complete * the `Deferred` with that error. * * **When to use** * * Use to lazily compute a typed failure value when the `Deferred` completion * effect runs. * * **Details** * * Fibers waiting on the `Deferred` fail with the computed error only if this * call completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with a lazy error) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.failSync(deferred, () => "Lazy error") * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.fail("Lazy error")] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (evaluate: LazyArg): (self: Deferred) => Effect; /** * Computes an error when the returned effect is run, then attempts to complete * the `Deferred` with that error. * * **When to use** * * Use to lazily compute a typed failure value when the `Deferred` completion * effect runs. * * **Details** * * Fibers waiting on the `Deferred` fail with the computed error only if this * call completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with a lazy error) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.failSync(deferred, () => "Lazy error") * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.fail("Lazy error")] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, evaluate: LazyArg): Effect; }; /** * Attempts to complete the `Deferred` with the specified `Cause`. * * **When to use** * * Use to complete a `Deferred` with a full failure cause. * * **Details** * * Fibers waiting on the `Deferred` observe that cause only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with a Cause) * * ```ts import.meta.vitest * import { Cause, Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.failCause(deferred, Cause.fail("Operation failed")) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Operation failed"))] * ``` * * @stability stable * @category completion * @since 2.0.0 */ export declare const failCause: { /** * Attempts to complete the `Deferred` with the specified `Cause`. * * **When to use** * * Use to complete a `Deferred` with a full failure cause. * * **Details** * * Fibers waiting on the `Deferred` observe that cause only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with a Cause) * * ```ts import.meta.vitest * import { Cause, Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.failCause(deferred, Cause.fail("Operation failed")) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Operation failed"))] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (cause: Cause.Cause): (self: Deferred) => Effect; /** * Attempts to complete the `Deferred` with the specified `Cause`. * * **When to use** * * Use to complete a `Deferred` with a full failure cause. * * **Details** * * Fibers waiting on the `Deferred` observe that cause only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with a Cause) * * ```ts import.meta.vitest * import { Cause, Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.failCause(deferred, Cause.fail("Operation failed")) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Operation failed"))] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, cause: Cause.Cause): Effect; }; /** * Computes a `Cause` when the returned effect is run, then attempts to * complete the `Deferred` with that cause. * * **When to use** * * Use to lazily compute a full failure cause when the `Deferred` completion * effect runs. * * **Details** * * Fibers waiting on the `Deferred` observe the computed cause only if this * call completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with a lazy Cause) * * ```ts import.meta.vitest * import { Cause, Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.failCauseSync(deferred, () => Cause.fail("Lazy error")) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Lazy error"))] * ``` * * @stability stable * @category completion * @since 2.0.0 */ export declare const failCauseSync: { /** * Computes a `Cause` when the returned effect is run, then attempts to * complete the `Deferred` with that cause. * * **When to use** * * Use to lazily compute a full failure cause when the `Deferred` completion * effect runs. * * **Details** * * Fibers waiting on the `Deferred` observe the computed cause only if this * call completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with a lazy Cause) * * ```ts import.meta.vitest * import { Cause, Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.failCauseSync(deferred, () => Cause.fail("Lazy error")) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Lazy error"))] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (evaluate: LazyArg>): (self: Deferred) => Effect; /** * Computes a `Cause` when the returned effect is run, then attempts to * complete the `Deferred` with that cause. * * **When to use** * * Use to lazily compute a full failure cause when the `Deferred` completion * effect runs. * * **Details** * * Fibers waiting on the `Deferred` observe the computed cause only if this * call completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Failing a Deferred with a lazy Cause) * * ```ts import.meta.vitest * import { Cause, Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.failCauseSync(deferred, () => Cause.fail("Lazy error")) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.failCause(Cause.fail("Lazy error"))] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, evaluate: LazyArg>): Effect; }; /** * Attempts to complete the `Deferred` with a defect. * * **When to use** * * Use to complete a `Deferred` with an unexpected defect. * * **Details** * * Fibers waiting on the `Deferred` die with that defect only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Killing a Deferred with a defect) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const defect = new Error("Something went wrong") * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.die(deferred, defect) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.die(defect)] * ``` * * @stability stable * @category completion * @since 2.0.0 */ export declare const die: { /** * Attempts to complete the `Deferred` with a defect. * * **When to use** * * Use to complete a `Deferred` with an unexpected defect. * * **Details** * * Fibers waiting on the `Deferred` die with that defect only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Killing a Deferred with a defect) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const defect = new Error("Something went wrong") * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.die(deferred, defect) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.die(defect)] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (defect: unknown): (self: Deferred) => Effect; /** * Attempts to complete the `Deferred` with a defect. * * **When to use** * * Use to complete a `Deferred` with an unexpected defect. * * **Details** * * Fibers waiting on the `Deferred` die with that defect only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Killing a Deferred with a defect) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const defect = new Error("Something went wrong") * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.die(deferred, defect) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.die(defect)] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, defect: unknown): Effect; }; /** * Computes a defect when the returned effect is run, then attempts to complete * the `Deferred` with that defect. * * **When to use** * * Use to lazily compute an unexpected defect when the completion effect runs. * * **Details** * * Fibers waiting on the `Deferred` die with the computed defect only if this * call completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Killing a Deferred with a lazy defect) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const defect = new Error("Lazy error") * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.dieSync(deferred, () => defect) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.die(defect)] * ``` * * @stability stable * @category completion * @since 2.0.0 */ export declare const dieSync: { /** * Computes a defect when the returned effect is run, then attempts to complete * the `Deferred` with that defect. * * **When to use** * * Use to lazily compute an unexpected defect when the completion effect runs. * * **Details** * * Fibers waiting on the `Deferred` die with the computed defect only if this * call completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Killing a Deferred with a lazy defect) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const defect = new Error("Lazy error") * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.dieSync(deferred, () => defect) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.die(defect)] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (evaluate: LazyArg): (self: Deferred) => Effect; /** * Computes a defect when the returned effect is run, then attempts to complete * the `Deferred` with that defect. * * **When to use** * * Use to lazily compute an unexpected defect when the completion effect runs. * * **Details** * * Fibers waiting on the `Deferred` die with the computed defect only if this * call completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Killing a Deferred with a lazy defect) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const defect = new Error("Lazy error") * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.dieSync(deferred, () => defect) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.die(defect)] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, evaluate: LazyArg): Effect; }; /** * Attempts to complete the `Deferred` with interruption by the current fiber. * * **When to use** * * Use to complete a `Deferred` as interrupted by the current fiber. * * **Details** * * Fibers waiting on the `Deferred` are interrupted with the current fiber id * only if this call completes it. The returned effect succeeds with `true` * when this call completed the `Deferred`, or `false` if it was already * completed. * * **Example** (Interrupting a Deferred) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.interrupt(deferred) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] as const * }) * * const [success, exit] = await Effect.runPromise(program) * success // => true * Exit.hasInterrupts(exit) // => true * ``` * * @stability stable * @category completion * @since 2.0.0 */ export declare const interrupt: (self: Deferred) => Effect; /** * Attempts to complete the `Deferred` with interruption by the specified * `FiberId`. * * **When to use** * * Use to complete a `Deferred` as interrupted by a specific fiber id. * * **Details** * * Fibers waiting on the `Deferred` are interrupted with that fiber id only if * this call completes it. The returned effect succeeds with `true` when this * call completed the `Deferred`, or `false` if it was already completed. * * **Example** (Interrupting a Deferred with a fiber id) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.interruptWith(deferred, 42) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.interrupt(42)] * ``` * * @stability stable * @category completion * @since 2.0.0 */ export declare const interruptWith: { /** * Attempts to complete the `Deferred` with interruption by the specified * `FiberId`. * * **When to use** * * Use to complete a `Deferred` as interrupted by a specific fiber id. * * **Details** * * Fibers waiting on the `Deferred` are interrupted with that fiber id only if * this call completes it. The returned effect succeeds with `true` when this * call completed the `Deferred`, or `false` if it was already completed. * * **Example** (Interrupting a Deferred with a fiber id) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.interruptWith(deferred, 42) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.interrupt(42)] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (fiberId: number): (self: Deferred) => Effect; /** * Attempts to complete the `Deferred` with interruption by the specified * `FiberId`. * * **When to use** * * Use to complete a `Deferred` as interrupted by a specific fiber id. * * **Details** * * Fibers waiting on the `Deferred` are interrupted with that fiber id only if * this call completes it. The returned effect succeeds with `true` when this * call completed the `Deferred`, or `false` if it was already completed. * * **Example** (Interrupting a Deferred with a fiber id) * * ```ts import.meta.vitest * import { Deferred, Effect, Exit } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const success = yield* Deferred.interruptWith(deferred, 42) * const exit = yield* Effect.exit(Deferred.await(deferred)) * return [success, exit] * }) * * await Effect.runPromise(program) // => [true, Exit.interrupt(42)] * ``` * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, fiberId: number): Effect; }; /** * Returns `true` if this `Deferred` has already been completed with a value or * an error, `false` otherwise. * * **When to use** * * Use to check completion status inside an `Effect` workflow. * * **Example** (Checking Deferred completion) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const beforeCompletion = yield* Deferred.isDone(deferred) * yield* Deferred.succeed(deferred, 42) * const afterCompletion = yield* Deferred.isDone(deferred) * return [beforeCompletion, afterCompletion] * }) * * await Effect.runPromise(program) // => [false, true] * ``` * * @stability stable * @category predicates * @since 2.0.0 */ export declare const isDone: (self: Deferred) => Effect; /** * Returns whether this `Deferred` has already been completed synchronously. * * **When to use** * * Use to check `Deferred` completion synchronously in code that cannot return * an `Effect`, such as low-level integration code. * * @see {@link isDone} for checking completion inside `Effect` * @see {@link poll} for reading the completed effect when available * * @stability stable * @category predicates * @since 4.0.0 */ export declare const isDoneUnsafe: (self: Deferred) => boolean; /** * Returns the current completion effect as an `Option`. This returns * `Option.some(effect)` when the `Deferred` is completed, `Option.none()` * otherwise. * * **When to use** * * Use to inspect whether a `Deferred` is already completed and retrieve its * stored completion effect when available. * * **Example** (Polling Deferred completion) * * ```ts import.meta.vitest * import { Deferred, Effect, Option } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const beforeCompletion = yield* Deferred.poll(deferred) * yield* Deferred.succeed(deferred, 42) * const afterCompletion = yield* Deferred.poll(deferred) * const afterValue = yield* Effect.transposeOption(afterCompletion) * return [beforeCompletion, afterValue] * }) * * await Effect.runPromise(program) // => [Option.none(), Option.some(42)] * ``` * * @stability stable * @category getters * @since 2.0.0 */ export declare function poll(self: Deferred): Effect>>; /** * Attempts to complete the `Deferred` with the specified value. * * **When to use** * * Use to complete a `Deferred` with a successful value. * * **Details** * * Fibers waiting on the `Deferred` receive the value only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred with a value) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.succeed(deferred, 42) * * return yield* Deferred.await(deferred) * }) * * await Effect.runPromise(program) // => 42 * ``` * * @stability stable * @category completion * @since 2.0.0 */ export declare const succeed: { /** * Attempts to complete the `Deferred` with the specified value. * * **When to use** * * Use to complete a `Deferred` with a successful value. * * **Details** * * Fibers waiting on the `Deferred` receive the value only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred with a value) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.succeed(deferred, 42) * * return yield* Deferred.await(deferred) * }) * * await Effect.runPromise(program) // => 42 * ``` * * @stability stable * @category completion * @since 2.0.0 */ (value: A): (self: Deferred) => Effect; /** * Attempts to complete the `Deferred` with the specified value. * * **When to use** * * Use to complete a `Deferred` with a successful value. * * **Details** * * Fibers waiting on the `Deferred` receive the value only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred with a value) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.succeed(deferred, 42) * * return yield* Deferred.await(deferred) * }) * * await Effect.runPromise(program) // => 42 * ``` * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, value: A): Effect; }; /** * Computes a value when the returned effect is run, then attempts to complete * the `Deferred` with that value. * * **When to use** * * Use to lazily compute a successful value when the `Deferred` completion * effect runs. * * **Details** * * Fibers waiting on the `Deferred` receive the computed value only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred with a lazy value) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.sync(deferred, () => 42) * return yield* Deferred.await(deferred) * }) * * await Effect.runPromise(program) // => 42 * ``` * * @stability stable * @category completion * @since 2.0.0 */ export declare const sync: { /** * Computes a value when the returned effect is run, then attempts to complete * the `Deferred` with that value. * * **When to use** * * Use to lazily compute a successful value when the `Deferred` completion * effect runs. * * **Details** * * Fibers waiting on the `Deferred` receive the computed value only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred with a lazy value) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.sync(deferred, () => 42) * return yield* Deferred.await(deferred) * }) * * await Effect.runPromise(program) // => 42 * ``` * * @stability stable * @category completion * @since 2.0.0 */ (evaluate: LazyArg): (self: Deferred) => Effect; /** * Computes a value when the returned effect is run, then attempts to complete * the `Deferred` with that value. * * **When to use** * * Use to lazily compute a successful value when the `Deferred` completion * effect runs. * * **Details** * * Fibers waiting on the `Deferred` receive the computed value only if this call * completes it. The returned effect succeeds with `true` when this call * completed the `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred with a lazy value) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * yield* Deferred.sync(deferred, () => 42) * return yield* Deferred.await(deferred) * }) * * await Effect.runPromise(program) // => 42 * ``` * * @stability stable * @category completion * @since 2.0.0 */ (self: Deferred, evaluate: LazyArg): Effect; }; /** * Attempts to complete the `Deferred` synchronously with the specified * completion effect. * * **When to use** * * Use to complete a `Deferred` synchronously in low-level code that already has * the completion effect. * * **Details** * * This mutates the `Deferred` directly and should be reserved for low-level * code; prefer the effectful completion APIs when possible. Returns `true` if * this call completed the `Deferred`, or `false` if it was already completed. * * **Example** (Completing a Deferred unsafely) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const deferred = Deferred.makeUnsafe() * Deferred.doneUnsafe(deferred, Effect.succeed(42)) // => true * ``` * * @stability stable * @category unsafe * @since 4.0.0 */ export declare const doneUnsafe: (self: Deferred, effect: Effect) => boolean; /** * Runs an `Effect` and attempts to complete a `Deferred` with the effect's * result. * * **When to use** * * Use to pipe an effect result into a `Deferred` while preserving success, * failure, defects, and interruption. * * **Details** * * If the effect succeeds, fails, dies, or is interrupted, that result is used * as the attempted completion. The returned effect cannot fail; it succeeds * with `true` if it completed the `Deferred`, or `false` if the `Deferred` was * already completed. * * **Example** (Completing a Deferred from an effect result) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const successEffect = Effect.succeed(42) * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const isCompleted = yield* Deferred.into(successEffect, deferred) * const value = yield* Deferred.await(deferred) * return [isCompleted, value] * }) * * await Effect.runPromise(program) // => [true, 42] * ``` * * @stability stable * @category completion * @since 4.0.0 */ export declare const into: { /** * Runs an `Effect` and attempts to complete a `Deferred` with the effect's * result. * * **When to use** * * Use to pipe an effect result into a `Deferred` while preserving success, * failure, defects, and interruption. * * **Details** * * If the effect succeeds, fails, dies, or is interrupted, that result is used * as the attempted completion. The returned effect cannot fail; it succeeds * with `true` if it completed the `Deferred`, or `false` if the `Deferred` was * already completed. * * **Example** (Completing a Deferred from an effect result) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const successEffect = Effect.succeed(42) * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const isCompleted = yield* Deferred.into(successEffect, deferred) * const value = yield* Deferred.await(deferred) * return [isCompleted, value] * }) * * await Effect.runPromise(program) // => [true, 42] * ``` * * @stability stable * @category completion * @since 4.0.0 */ (deferred: Deferred): (self: Effect) => Effect; /** * Runs an `Effect` and attempts to complete a `Deferred` with the effect's * result. * * **When to use** * * Use to pipe an effect result into a `Deferred` while preserving success, * failure, defects, and interruption. * * **Details** * * If the effect succeeds, fails, dies, or is interrupted, that result is used * as the attempted completion. The returned effect cannot fail; it succeeds * with `true` if it completed the `Deferred`, or `false` if the `Deferred` was * already completed. * * **Example** (Completing a Deferred from an effect result) * * ```ts import.meta.vitest * import { Deferred, Effect } from "effect" * * const successEffect = Effect.succeed(42) * * const program = Effect.gen(function*() { * const deferred = yield* Deferred.make() * const isCompleted = yield* Deferred.into(successEffect, deferred) * const value = yield* Deferred.await(deferred) * return [isCompleted, value] * }) * * await Effect.runPromise(program) // => [true, 42] * ``` * * @stability stable * @category completion * @since 4.0.0 */ (self: Effect, deferred: Deferred): Effect; }; //# sourceMappingURL=Deferred.d.ts.map