/**
* 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