/** * Represents observable state for asynchronous values. * * `AsyncResult` records whether asynchronous work has no value yet, * succeeded with an `A`, or failed with an `E`. Every state also carries a * `waiting` flag, so callers can keep showing the current value while newer * work is loading, refreshing, retrying, or recovering. This module includes * constructors, checks, accessors, mapping and matching helpers, ways to combine * several results, and schemas for encoding or decoding results. * * @stability unstable * @since 4.0.0 */ import * as Cause from "../Cause.ts"; import * 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 { Predicate, Refinement } from "../Predicate.ts"; import * as Schema_ from "../Schema.ts"; import type * as Types from "../Types.ts"; /** * Type-level identifier used to recognize `AsyncResult` values. * * @stability unstable * @category type IDs * @since 4.0.0 */ export type TypeId = "~effect/reactivity/AsyncResult"; /** * Runtime identifier attached to `AsyncResult` values and used by `isAsyncResult`. * * @stability unstable * @category type IDs * @since 4.0.0 */ export declare const TypeId: TypeId; /** * Represents the state of an asynchronous value as `Initial`, `Success`, or `Failure`, with a `waiting` flag for in-flight refreshes. * * @stability unstable * @category models * @since 4.0.0 */ export type AsyncResult = Initial | Success | Failure; /** * Returns `true` when a value is an `AsyncResult`. * * @stability unstable * @category guards * @since 4.0.0 */ export declare const isAsyncResult: (u: unknown) => u is AsyncResult; /** * Namespace containing type-level helpers and the shared prototype shape for `AsyncResult` values. * * @stability unstable * @since 4.0.0 */ export declare namespace AsyncResult { /** * Common prototype fields implemented by every `AsyncResult` variant, including pipeability, the type marker, phantom type members, and the `waiting` flag. * * @stability unstable * @category models * @since 4.0.0 */ interface Proto extends Pipeable { readonly [TypeId]: { readonly E: (_: never) => E; readonly A: (_: never) => A; }; readonly waiting: boolean; } /** * Extracts the success value type from an `AsyncResult`. * * @stability unstable * @category utility types * @since 4.0.0 */ type Success = R extends AsyncResult ? A : never; /** * Extracts the failure error type from an `AsyncResult`. * * @stability unstable * @category utility types * @since 4.0.0 */ type Failure = R extends AsyncResult ? E : never; } /** * Rebuilds an `AsyncResult` with new success and failure types while preserving the variant of another result. * * @stability unstable * @category utility types * @since 4.0.0 */ export type With, A, E> = R extends Initial ? Initial : R extends Success ? Success : R extends Failure ? Failure : never; /** * Returns whether an `AsyncResult` is currently waiting for an asynchronous computation or refresh to finish. * * @stability unstable * @category predicates * @since 4.0.0 */ export declare const isWaiting: (result: AsyncResult) => boolean; /** * Initial `AsyncResult` state before a success value or failure cause is available. * * @stability unstable * @category models * @since 4.0.0 */ export interface Initial extends AsyncResult.Proto { readonly _tag: "Initial"; } /** * Converts an `Exit` into a `Success` when it succeeds or a `Failure` carrying the exit cause when it fails. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const fromExit: (exit: Exit.Exit) => Success | Failure; /** * Converts an `Exit` to a result, preserving the latest previous success when the exit is a failure. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const fromExitWithPrevious: (exit: Exit.Exit, previous: Option.Option>) => Success | Failure; /** * Creates a waiting result from an optional previous result, using `Initial(true)` when no previous result exists. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const waitingFrom: (previous: Option.Option>) => AsyncResult; /** * Returns `true` when an `AsyncResult` is in the `Initial` state. * * @stability unstable * @category guards * @since 4.0.0 */ export declare const isInitial: (result: AsyncResult) => result is Initial; /** * Returns `true` when an `AsyncResult` is either `Success` or `Failure`. * * @stability unstable * @category guards * @since 4.0.0 */ export declare const isNotInitial: (result: AsyncResult) => result is Success | Failure; /** * Creates an `Initial` result, optionally marking it as waiting. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const initial: (waiting?: boolean) => Initial; /** * Successful `AsyncResult` containing the current value, its timestamp, and the shared waiting flag. * * @stability unstable * @category models * @since 4.0.0 */ export interface Success extends AsyncResult.Proto { readonly _tag: "Success"; readonly value: A; readonly timestamp: number; } /** * Returns `true` when an `AsyncResult` is a `Success`. * * @stability unstable * @category guards * @since 4.0.0 */ export declare const isSuccess: (result: AsyncResult) => result is Success; /** * Creates a `Success` result with a value and optional `waiting` flag or timestamp override. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const success: (value: A, options?: { readonly waiting?: boolean | undefined; readonly timestamp?: number | undefined; }) => Success; /** * Failed `AsyncResult` containing a failure cause and the latest previous success when one is available. * * @stability unstable * @category models * @since 4.0.0 */ export interface Failure extends AsyncResult.Proto { readonly _tag: "Failure"; readonly cause: Cause.Cause; readonly previousSuccess: Option.Option>; } /** * Returns `true` when an `AsyncResult` is a `Failure`. * * @stability unstable * @category guards * @since 4.0.0 */ export declare const isFailure: (result: AsyncResult) => result is Failure; /** * Returns `true` when an `AsyncResult` is a `Failure` whose cause contains only interruptions. * * @stability unstable * @category guards * @since 4.0.0 */ export declare const isInterrupted: (result: AsyncResult) => result is Failure; /** * Creates a `Failure` result from a `Cause`, optionally preserving a previous success and marking the result as waiting. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const failure: (cause: Cause.Cause, options?: { readonly previousSuccess?: Option.Option> | undefined; readonly waiting?: boolean | undefined; }) => Failure; /** * Creates a `Failure` result from a `Cause`, carrying forward the latest success stored in a previous result. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const failureWithPrevious: (cause: Cause.Cause, options: { readonly previous: Option.Option>; readonly waiting?: boolean | undefined; }) => Failure; /** * Creates a `Failure` result from a typed error, wrapping it in `Cause.fail`. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const fail: (error: E, options?: { readonly previousSuccess?: Option.Option> | undefined; readonly waiting?: boolean | undefined; }) => Failure; /** * Creates a `Failure` result from a typed error while carrying forward the latest success stored in a previous result. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const failWithPrevious: (error: E, options: { readonly previous: Option.Option>; readonly waiting?: boolean | undefined; }) => Failure; /** * Marks an `AsyncResult` as waiting, optionally touching the timestamp when the result is a `Success`. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const waiting: { /** * Marks an `AsyncResult` as waiting, optionally touching the timestamp when the result is a `Success`. * * @stability unstable * @category constructors * @since 4.0.0 */ (options?: { readonly touch?: boolean | undefined; }): >(self: R) => R; /** * Marks an `AsyncResult` as waiting, optionally touching the timestamp when the result is a `Success`. * * @stability unstable * @category constructors * @since 4.0.0 */ >(self: R, options?: { readonly touch?: boolean | undefined; }): R; }; /** * Refreshes the timestamp of a `Success` result while preserving its value and waiting flag; non-success results are returned unchanged. * * @stability unstable * @category combinators * @since 4.0.0 */ export declare const touch: >(result: A) => A; /** * Replaces a `Failure` value's stored previous success with the latest success * found in another result. * * @stability unstable * @category combinators * @since 4.0.0 */ export declare const replacePrevious: { /** * Replaces a `Failure` value's stored previous success with the latest success * found in another result. * * @stability unstable * @category combinators * @since 4.0.0 */ (previous: Option.Option>): >(self: R) => With>; /** * Replaces a `Failure` value's stored previous success with the latest success * found in another result. * * @stability unstable * @category combinators * @since 4.0.0 */ , XE, A>(self: R, previous: Option.Option>): With>; }; /** * Returns the current success value, or the previous success value stored in a failure, as an `Option`. * * @stability unstable * @category accessors * @since 4.0.0 */ export declare const value: (self: AsyncResult) => Option.Option; /** * Returns the available value from `value`, or evaluates the fallback when no current or previous success exists. * * @stability unstable * @category accessors * @since 4.0.0 */ export declare const getOrElse: { /** * Returns the available value from `value`, or evaluates the fallback when no current or previous success exists. * * @stability unstable * @category accessors * @since 4.0.0 */ (orElse: LazyArg): (self: AsyncResult) => A | B; /** * Returns the available value from `value`, or evaluates the fallback when no current or previous success exists. * * @stability unstable * @category accessors * @since 4.0.0 */ (self: AsyncResult, orElse: LazyArg): A | B; }; /** * Returns the available value from `value`, or throws `NoSuchElementError` when no current or previous success exists. * * @stability unstable * @category accessors * @since 4.0.0 */ export declare const getOrThrow: (self: AsyncResult) => A; /** * Returns the failure cause when the result is a `Failure`, otherwise `None`. * * @stability unstable * @category accessors * @since 4.0.0 */ export declare const cause: (self: AsyncResult) => Option.Option>; /** * Returns the first typed error from a failure cause, or `None` for successes, initial results, defects, and interrupt-only causes. * * @stability unstable * @category accessors * @since 4.0.0 */ export declare const error: (self: AsyncResult) => Option.Option; /** * Converts a result to an `Exit`, succeeding with a success value, failing with a failure cause, or failing with `NoSuchElementError` for `Initial`. * * @stability unstable * @category combinators * @since 4.0.0 */ export declare const toExit: (self: AsyncResult) => Exit.Exit; /** * Maps the success value of an `AsyncResult`, also mapping any previous success stored in a failure while leaving initial results unchanged. * * @stability unstable * @category combinators * @since 4.0.0 */ export declare const map: { /** * Maps the success value of an `AsyncResult`, also mapping any previous success stored in a failure while leaving initial results unchanged. * * @stability unstable * @category combinators * @since 4.0.0 */ (f: (a: A) => B): (self: AsyncResult) => AsyncResult; /** * Maps the success value of an `AsyncResult`, also mapping any previous success stored in a failure while leaving initial results unchanged. * * @stability unstable * @category combinators * @since 4.0.0 */ (self: AsyncResult, f: (a: A) => B): AsyncResult; }; /** * Maps the success value of an `AsyncResult` and flattens the result. * * **When to use** * * Use to sequence computations that may return another `AsyncResult` while * preserving initial and failure states. * * **Details** * * Initial results are left unchanged. Failures preserve their cause and remap * the stored previous success when the mapping function returns a success. * * @stability unstable * @category combinators * @since 4.0.0 */ export declare const flatMap: { /** * Maps the success value of an `AsyncResult` and flattens the result. * * **When to use** * * Use to sequence computations that may return another `AsyncResult` while * preserving initial and failure states. * * **Details** * * Initial results are left unchanged. Failures preserve their cause and remap * the stored previous success when the mapping function returns a success. * * @stability unstable * @category combinators * @since 4.0.0 */ (f: (a: A, prev: Success) => AsyncResult): (self: AsyncResult) => AsyncResult; /** * Maps the success value of an `AsyncResult` and flattens the result. * * **When to use** * * Use to sequence computations that may return another `AsyncResult` while * preserving initial and failure states. * * **Details** * * Initial results are left unchanged. Failures preserve their cause and remap * the stored previous success when the mapping function returns a success. * * @stability unstable * @category combinators * @since 4.0.0 */ (self: AsyncResult, f: (a: A, prev: Success) => AsyncResult): AsyncResult; }; /** * Pattern matches an `AsyncResult` by calling the handler for `Initial`, `Failure`, or `Success`. * * @stability unstable * @category combinators * @since 4.0.0 */ export declare const match: { /** * Pattern matches an `AsyncResult` by calling the handler for `Initial`, `Failure`, or `Success`. * * @stability unstable * @category combinators * @since 4.0.0 */ (options: { readonly onInitial: (_: Initial) => X; readonly onFailure: (_: Failure) => Y; readonly onSuccess: (_: Success) => Z; }): (self: AsyncResult) => X | Y | Z; /** * Pattern matches an `AsyncResult` by calling the handler for `Initial`, `Failure`, or `Success`. * * @stability unstable * @category combinators * @since 4.0.0 */ (self: AsyncResult, options: { readonly onInitial: (_: Initial) => X; readonly onFailure: (_: Failure) => Y; readonly onSuccess: (_: Success) => Z; }): X | Y | Z; }; /** * Pattern matches a result, handling successes and initials directly while splitting failures into typed errors or squashed non-error causes passed to `onDefect`. * * @stability unstable * @category combinators * @since 4.0.0 */ export declare const matchWithError: { /** * Pattern matches a result, handling successes and initials directly while splitting failures into typed errors or squashed non-error causes passed to `onDefect`. * * @stability unstable * @category combinators * @since 4.0.0 */ (options: { readonly onInitial: (_: Initial) => W; readonly onError: (error: E, _: Failure) => X; readonly onDefect: (defect: unknown, _: Failure) => Y; readonly onSuccess: (_: Success) => Z; }): (self: AsyncResult) => W | X | Y | Z; /** * Pattern matches a result, handling successes and initials directly while splitting failures into typed errors or squashed non-error causes passed to `onDefect`. * * @stability unstable * @category combinators * @since 4.0.0 */ (self: AsyncResult, options: { readonly onInitial: (_: Initial) => W; readonly onError: (error: E, _: Failure) => X; readonly onDefect: (defect: unknown, _: Failure) => Y; readonly onSuccess: (_: Success) => Z; }): W | X | Y | Z; }; /** * Pattern matches a result by calling `onWaiting` for waiting or initial states, otherwise handling successes and splitting failures into typed errors or squashed non-error causes. * * @stability unstable * @category combinators * @since 4.0.0 */ export declare const matchWithWaiting: { /** * Pattern matches a result by calling `onWaiting` for waiting or initial states, otherwise handling successes and splitting failures into typed errors or squashed non-error causes. * * @stability unstable * @category combinators * @since 4.0.0 */ (options: { readonly onWaiting: (_: AsyncResult) => W; readonly onError: (error: E, _: Failure) => X; readonly onDefect: (defect: unknown, _: Failure) => Y; readonly onSuccess: (_: Success) => Z; }): (self: AsyncResult) => W | X | Y | Z; /** * Pattern matches a result by calling `onWaiting` for waiting or initial states, otherwise handling successes and splitting failures into typed errors or squashed non-error causes. * * @stability unstable * @category combinators * @since 4.0.0 */ (self: AsyncResult, options: { readonly onWaiting: (_: AsyncResult) => W; readonly onError: (error: E, _: Failure) => X; readonly onDefect: (defect: unknown, _: Failure) => Y; readonly onSuccess: (_: Success) => Z; }): W | X | Y | Z; }; /** * Combines an iterable or record of `AsyncResult` and plain values into one `AsyncResult`, returning the first non-success result or a success of the collected values marked waiting when any input success is waiting. * * **Details** * * If the first non-success result is a failure, its previous success is * rebuilt in the combined shape from each input's current or previous value. * It is omitted if any input has no value. * * @stability unstable * @category combinators * @since 4.0.0 */ export declare const all: | Record>(results: Arg) => AsyncResult<[Arg] extends [ReadonlyArray] ? { -readonly [K in keyof Arg]: [Arg[K]] extends [AsyncResult] ? _A : Arg[K]; } : [Arg] extends [Iterable] ? _A extends AsyncResult ? _AA : _A : [Arg] extends [Record] ? { -readonly [K in keyof Arg]: [Arg[K]] extends [AsyncResult] ? _A : Arg[K]; } : never, [Arg] extends [ReadonlyArray] ? AsyncResult.Failure : [Arg] extends [Iterable] ? AsyncResult.Failure<_A> : [Arg] extends [Record] ? AsyncResult.Failure : never>; /** * Creates a typed builder for rendering an `AsyncResult` by handling waiting, initial, success, error, defect, interrupt, and failure cases. * * @stability unstable * @category constructors * @since 4.0.0 */ export declare const builder: >(self: A) => Builder ? _A : never, A extends Failure ? _E : never, A extends Initial ? true : never, A extends Failure ? Defect | Interrupt : never>; /** * Type marker used by `Builder` to track whether defect failures still need to be handled. * * @stability unstable * @category utility types * @since 4.0.0 */ export interface Defect { readonly _: unique symbol; } /** * Type marker used by `Builder` to track whether interrupt failures still need to be handled. * * @stability unstable * @category utility types * @since 4.0.0 */ export interface Interrupt { readonly _: unique symbol; } /** * Fluent renderer for `AsyncResult` values that tracks unhandled cases at the type level and exposes `exhaustive` only after all possible cases are handled. * * @stability unstable * @category models * @since 4.0.0 */ export type Builder = Pipeable & { onWaiting(f: (result: AsyncResult) => B): Builder; orElse(orElse: LazyArg): Out | B; orNull(): Out | null; render(): [A | I] extends [never] ? Out : Out | null; } & ([A | E | I | F] extends [never] ? { exhaustive(): Out; } : unknown) & ([I] extends [never] ? unknown : { onInitial(f: (result: Initial) => B): Builder; onInitialOrWaiting(f: (result: AsyncResult) => B): Builder; }) & ([A] extends [never] ? unknown : { onSuccess(f: (value: A, result: Success) => B): Builder; }) & ([E] extends [never] ? unknown : { onError(f: (error: E, result: Failure) => B): Builder; onErrorIf(refinement: Refinement, f: (error: B, result: Failure) => C): Builder>, I, F>; onErrorIf(predicate: Predicate, f: (error: E, result: Failure) => C): Builder; onErrorTag>, B>(tags: Tags, f: (error: Types.ExtractTag, result: Failure) => B): Builder, I, F>; onErrorTag, B>(tag: Tag, f: (error: Types.ExtractTag, result: Failure) => B): Builder, I, F>; }) & ([E | F] extends [never] ? unknown : { onFailure(f: (cause: Cause.Cause, result: Failure) => B): Builder; }) & (Interrupt extends F ? { onInterrupt(f: (interruptors: ReadonlySet, result: Failure) => B): Builder>; } : unknown) & (Defect extends F ? { onDefect(f: (defect: unknown, result: Failure) => B): Builder>; } : unknown); /** * Schema interface for `AsyncResult` values, retaining the schemas used for success values and failure errors. * * @stability unstable * @category schemas * @since 4.0.0 */ export interface Schema extends Schema_.declareConstructor, AsyncResult, readonly [Success, Schema_.Cause]> { readonly success: Success; readonly error: Error; } /** * Creates a schema for `AsyncResult` values using optional schemas for success values and failure errors. * * @stability unstable * @category schemas * @since 4.0.0 */ export declare const Schema: (options: { readonly success?: A | undefined; readonly error?: E | undefined; }) => Schema; //# sourceMappingURL=AsyncResult.d.ts.map