@systemfsoftware/effect-atom 0.5.3

package/dist/Result-CAjFdzam.d.ts

@@ -0,0 +1,490 @@
+import * as Cause from "effect/Cause";
+import * as Exit from "effect/Exit";
+import { LazyArg } from "effect/Function";
+import * as Option from "effect/Option";
+import * as Schema_ from "effect/Schema";
+import { Pipeable } from "effect/Pipeable";
+import { Predicate, Refinement } from "effect/Predicate";
+import * as Types from "effect/Types";
+//#region src/internal/result-values.d.ts
+/**
+ * Type-level identifier used to recognize `Result` values.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+type TypeId = '~effect-atom/atom/Result';
+/**
+ * Runtime identifier attached to `Result` values and used by `isResult`.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+declare const TypeId: TypeId;
+/**
+ * Namespace containing the shared prototype shape and type-level helpers for
+ * `Result` values. The interface members are declared ahead of their use in
+ * the variant interfaces below.
+ *
+ * @since 4.0.0
+ */
+declare namespace Result {
+  /**
+   * Common prototype fields implemented by every `Result` variant, including
+   * pipeability, the type marker, phantom type members, and the `waiting` flag.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  interface Proto<A, E> extends Pipeable {
+    readonly [TypeId]: {
+      readonly E: (_: never) => E;
+      readonly A: (_: never) => A;
+    };
+    readonly waiting: boolean;
+  }
+  /**
+   * Extracts the success value type from an `Result`.
+   *
+   * @category utility types
+   * @since 4.0.0
+   */
+  type Success<R> = R extends Result<infer A, infer _> ? A : never;
+  /**
+   * Extracts the failure error type from an `Result`.
+   *
+   * @category utility types
+   * @since 4.0.0
+   */
+  type Failure<R> = R extends Result<infer _, infer E> ? E : never;
+}
+/**
+ * Represents the state of an asynchronous value as `Initial`, `Success`, or
+ * `Failure`, with a `waiting` flag for in-flight refreshes.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+type Result<A, E = never> = Initial<A, E> | Success<A, E> | Failure<A, E>;
+/**
+ * Initial `Result` state before a success value or failure cause is available.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+interface Initial<A, E = never> extends Result.Proto<A, E> {
+  readonly _tag: 'Initial';
+}
+/**
+ * Successful `Result` containing the current value, its timestamp, and the
+ * shared waiting flag.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+interface Success<A, E = never> extends Result.Proto<A, E> {
+  readonly _tag: 'Success';
+  readonly value: A;
+  readonly timestamp: number;
+}
+/**
+ * Failed `Result` containing a failure cause and the latest previous success
+ * when one is available.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+interface Failure<A, E = never> extends Result.Proto<A, E> {
+  readonly _tag: 'Failure';
+  readonly cause: Cause.Cause<E>;
+  readonly previousSuccess: Option.Option<Success<A, E>>;
+}
+/**
+ * Returns `true` when a value is an `Result`.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+declare const isResult: (u: unknown) => u is Result<unknown, unknown>;
+/**
+ * Creates an `Initial` result, optionally marking it as waiting.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const initial: <A = never, E = never>(waiting?: boolean) => Initial<A, E>;
+/**
+ * Creates a `Success` result with a value and optional `waiting` flag or
+ * timestamp override.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const success: <A, E = never>(value: A, options?: {
+  readonly waiting?: boolean | undefined;
+  readonly timestamp?: number | undefined;
+}) => Success<A, E>;
+/**
+ * Creates a `Failure` result from a `Cause`, optionally preserving a previous
+ * success and marking the result as waiting.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const failure: <A, E = never>(cause: Cause.Cause<E>, options?: {
+  readonly previousSuccess?: Option.Option<Success<A, E>> | undefined;
+  readonly waiting?: boolean | undefined;
+}) => Failure<A, E>;
+//#endregion
+//#region src/internal/result-schema.d.ts
+/**
+ * Schema interface for `Result` values, retaining the schemas used for success values and failure errors.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+interface Schema<Success extends Schema_.Constraint, Error extends Schema_.Constraint> extends Schema_.declareConstructor<Result<Success['Type'], Error['Type']>, Result<Success['Encoded'], Error['Encoded']>, readonly [Success, Schema_.Cause<Error, Schema_.Defect>]> {
+  readonly success: Success;
+  readonly error: Error;
+}
+/**
+ * Creates a schema for `Result` values using optional schemas for success values and failure errors.
+ *
+ * @category schemas
+ * @since 4.0.0
+ */
+declare const Schema: <A extends Schema_.Constraint = Schema_.Never, E extends Schema_.Constraint = Schema_.Never>(options: {
+  readonly success?: A | undefined;
+  readonly error?: E | undefined;
+}) => Schema<A, E>;
+declare namespace Result_d_exports {
+  export { Builder, Defect, Failure, Initial, Interrupt, Result, Schema, Success, TypeId, With, all, builder, cause, error, fail, failWithPrevious, failure, failureWithPrevious, flatMap, fromExit, fromExitWithPrevious, getOrElse, getOrThrow, initial, isResult as isAsyncResult, isFailure, isInitial, isInterrupted, isNotInitial, isResult, isSuccess, isWaiting, map, match, matchWithError, matchWithWaiting, replacePrevious, success, toExit, touch, value, waiting, waitingFrom };
+}
+/**
+ * Rebuilds an `Result` with new success and failure types while preserving the variant of another result.
+ *
+ * @category utility types
+ * @since 4.0.0
+ */
+type With<R extends Result<any, any>, A, E> = R extends Initial<infer _A, infer _E> ? Initial<A, E> : R extends Success<infer _A, infer _E> ? Success<A, E> : R extends Failure<infer _A, infer _E> ? Failure<A, E> : never;
+/**
+ * Returns whether an `Result` is currently waiting for an asynchronous computation or refresh to finish.
+ *
+ * @category predicates
+ * @since 4.0.0
+ */
+declare const isWaiting: <A, E>(result: Result<A, E>) => boolean;
+/**
+ * Converts an `Exit` into a `Success` when it succeeds or a `Failure` carrying the exit cause when it fails.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const fromExit: <A, E>(exit: Exit.Exit<A, E>) => Success<A, E> | Failure<A, E>;
+/**
+ * Converts an `Exit` to a result, preserving the latest previous success when the exit is a failure.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const fromExitWithPrevious: <A, E>(exit: Exit.Exit<A, E>, previous: Option.Option<Result<A, E>>) => Success<A, E> | Failure<A, E>;
+/**
+ * Creates a waiting result from an optional previous result, using `Initial(true)` when no previous result exists.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const waitingFrom: <A, E>(previous: Option.Option<Result<A, E>>) => Result<A, E>;
+/**
+ * Returns `true` when an `Result` is in the `Initial` state.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+declare const isInitial: <A, E>(result: Result<A, E>) => result is Initial<A, E>;
+/**
+ * Returns `true` when an `Result` is either `Success` or `Failure`.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+declare const isNotInitial: <A, E>(result: Result<A, E>) => result is Success<A, E> | Failure<A, E>;
+/**
+ * Returns `true` when an `Result` is a `Success`.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+declare const isSuccess: <A, E>(result: Result<A, E>) => result is Success<A, E>;
+/**
+ * Returns `true` when an `Result` is a `Failure`.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+declare const isFailure: <A, E>(result: Result<A, E>) => result is Failure<A, E>;
+/**
+ * Returns `true` when an `Result` is a `Failure` whose cause contains only interruptions.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+declare const isInterrupted: <A, E>(result: Result<A, E>) => result is Failure<A, E>;
+/**
+ * Creates a `Failure` result from a `Cause`, carrying forward the latest success stored in a previous result.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const failureWithPrevious: <A, E>(cause: Cause.Cause<E>, options: {
+  readonly previous: Option.Option<Result<A, E>>;
+  readonly waiting?: boolean | undefined;
+}) => Failure<A, E>;
+/**
+ * Creates a `Failure` result from a typed error, wrapping it in `Cause.fail`.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const fail: <E, A = never>(error: E, options?: {
+  readonly previousSuccess?: Option.Option<Success<A, E>> | undefined;
+  readonly waiting?: boolean | undefined;
+}) => Failure<A, E>;
+/**
+ * Creates a `Failure` result from a typed error while carrying forward the latest success stored in a previous result.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const failWithPrevious: <A, E>(error: E, options: {
+  readonly previous: Option.Option<Result<A, E>>;
+  readonly waiting?: boolean | undefined;
+}) => Failure<A, E>;
+/**
+ * Marks an `Result` as waiting, optionally touching the timestamp when the result is a `Success`.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+declare const waiting: <R extends Result<any, any>>(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.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+declare const touch: <A extends Result<any, any>>(result: A) => A;
+/**
+ * Replaces a `Failure` value's stored previous success with the latest success
+ * found in another result.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+declare const replacePrevious: <R extends Result<any, any>, XE, A>(self: R, previous: Option.Option<Result<A, XE>>) => With<R, A, Result.Failure<R>>;
+/**
+ * Returns the current success value, or the previous success value stored in a failure, as an `Option`.
+ *
+ * @category accessors
+ * @since 4.0.0
+ */
+declare const value: <A, E>(self: Result<A, E>) => Option.Option<A>;
+/**
+ * Returns the available value from `value`, or evaluates the fallback when no current or previous success exists.
+ *
+ * @category accessors
+ * @since 4.0.0
+ */
+declare const getOrElse: {
+  <B>(orElse: LazyArg<B>): <A, E>(self: Result<A, E>) => A | B;
+  <A, E, B>(self: Result<A, E>, orElse: LazyArg<B>): A | B;
+};
+/**
+ * Returns the available value from `value`, or throws `NoSuchElementError` when no current or previous success exists.
+ *
+ * @category accessors
+ * @since 4.0.0
+ */
+declare const getOrThrow: <A, E>(self: Result<A, E>) => A;
+/**
+ * Returns the failure cause when the result is a `Failure`, otherwise `None`.
+ *
+ * @category accessors
+ * @since 4.0.0
+ */
+declare const cause: <A, E>(self: Result<A, E>) => Option.Option<Cause.Cause<E>>;
+/**
+ * Returns the first typed error from a failure cause, or `None` for successes, initial results, defects, and interrupt-only causes.
+ *
+ * @category accessors
+ * @since 4.0.0
+ */
+declare const error: <A, E>(self: Result<A, E>) => Option.Option<E>;
+/**
+ * Converts a result to an `Exit`, succeeding with a success value, failing with a failure cause, or failing with `NoSuchElementError` for `Initial`.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+declare const toExit: {
+  <A, E>(self: Success<A, E> | Failure<A, E>): Exit.Exit<A, E>;
+  <A, E>(self: Result<A, E>): Exit.Exit<A, E | Cause.NoSuchElementError>;
+};
+/**
+ * Maps the success value of an `Result`, also mapping any previous success stored in a failure while leaving initial results unchanged.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+declare const map: {
+  <A, B>(f: (a: A) => B): <E>(self: Result<A, E>) => Result<B, E>;
+  <E, A, B>(self: Result<A, E>, f: (a: A) => B): Result<B, E>;
+};
+/**
+ * Maps the success value of an `Result` and flattens the result.
+ *
+ * **When to use**
+ *
+ * Use to sequence computations that may return another `Result` 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.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+declare const flatMap: {
+  <A, E, B, E2>(f: (a: A, prev: Success<A, E>) => Result<B, E2>): (self: Result<A, E>) => Result<B, E | E2>;
+  <E, A, B, E2>(self: Result<A, E>, f: (a: A, prev: Success<A, E>) => Result<B, E2>): Result<B, E | E2>;
+};
+/**
+ * Pattern matches an `Result` by calling the handler for `Initial`, `Failure`, or `Success`.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+declare const match: {
+  <A, E, X, Y, Z>(options: {
+    readonly onInitial: (_: Initial<A, E>) => X;
+    readonly onFailure: (_: Failure<A, E>) => Y;
+    readonly onSuccess: (_: Success<A, E>) => Z;
+  }): (self: Result<A, E>) => X | Y | Z;
+  <A, E, X, Y, Z>(self: Result<A, E>, options: {
+    readonly onInitial: (_: Initial<A, E>) => X;
+    readonly onFailure: (_: Failure<A, E>) => Y;
+    readonly onSuccess: (_: Success<A, E>) => 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`.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+declare const matchWithError: {
+  <A, E, W, X, Y, Z>(options: {
+    readonly onInitial: (_: Initial<A, E>) => W;
+    readonly onError: (error: E, _: Failure<A, E>) => X;
+    readonly onDefect: (defect: unknown, _: Failure<A, E>) => Y;
+    readonly onSuccess: (_: Success<A, E>) => Z;
+  }): (self: Result<A, E>) => W | X | Y | Z;
+  <A, E, W, X, Y, Z>(self: Result<A, E>, options: {
+    readonly onInitial: (_: Initial<A, E>) => W;
+    readonly onError: (error: E, _: Failure<A, E>) => X;
+    readonly onDefect: (defect: unknown, _: Failure<A, E>) => Y;
+    readonly onSuccess: (_: Success<A, E>) => 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.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+declare const matchWithWaiting: {
+  <A, E, W, X, Y, Z>(options: {
+    readonly onWaiting: (_: Result<A, E>) => W;
+    readonly onError: (error: E, _: Failure<A, E>) => X;
+    readonly onDefect: (defect: unknown, _: Failure<A, E>) => Y;
+    readonly onSuccess: (_: Success<A, E>) => Z;
+  }): (self: Result<A, E>) => W | X | Y | Z;
+  <A, E, W, X, Y, Z>(self: Result<A, E>, options: {
+    readonly onWaiting: (_: Result<A, E>) => W;
+    readonly onError: (error: E, _: Failure<A, E>) => X;
+    readonly onDefect: (defect: unknown, _: Failure<A, E>) => Y;
+    readonly onSuccess: (_: Success<A, E>) => Z;
+  }): W | X | Y | Z;
+};
+/**
+ * Combines an iterable or record of `Result` and plain values into one `Result`, returning the first non-success result or a success of the collected values marked waiting when any input success is waiting.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+type AllSuccess<Arg> = [Arg] extends [readonly any[]] ? { -readonly [K in keyof Arg]: [Arg[K]] extends [Result<infer _A, infer _E>] ? _A : Arg[K]; } : [Arg] extends [Iterable<infer _A>] ? _A extends Result<infer _AA, infer _E> ? _AA : _A : [Arg] extends [Record<string, any>] ? { -readonly [K in keyof Arg]: [Arg[K]] extends [Result<infer _A, infer _E>] ? _A : Arg[K]; } : never;
+type AllError<Arg> = [Arg] extends [readonly any[]] ? Result.Failure<Arg[number]> : [Arg] extends [Iterable<infer _A>] ? Result.Failure<_A> : [Arg] extends [Record<string, any>] ? Result.Failure<Arg[keyof Arg]> : never;
+declare const all: <const Arg extends Iterable<any> | Record<string, any>>(results: Arg) => Result<AllSuccess<Arg>, AllError<Arg>>;
+/**
+ * Creates a typed builder for rendering an `Result` by handling waiting, initial, success, error, defect, interrupt, and failure cases.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+type BuilderFor<A extends Result<any, any>> = Builder<never, A extends Success<infer _A, infer _E> ? _A : never, A extends Failure<infer _A, infer _E> ? _E : never, A extends Initial<infer _A, infer _E> ? true : never, A extends Failure<infer _A, infer _E> ? Defect | Interrupt : never>;
+declare const builder: <A extends Result<any, any>>(self: A) => BuilderFor<A>;
+/**
+ * Type marker used by `Builder` to track whether defect failures still need to be handled.
+ *
+ * @category utility types
+ * @since 4.0.0
+ */
+interface Defect {
+  readonly _: unique symbol;
+}
+/**
+ * Type marker used by `Builder` to track whether interrupt failures still need to be handled.
+ *
+ * @category utility types
+ * @since 4.0.0
+ */
+interface Interrupt {
+  readonly _: unique symbol;
+}
+/**
+ * Fluent renderer for `Result` values that tracks unhandled cases at the type level and exposes `exhaustive` only after all possible cases are handled.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+type Builder<Out, A, E, I, F> = Pipeable & {
+  onWaiting<B>(f: (result: Result<A, E>) => B): Builder<Out | B, A, E, I, F>;
+  orElse<B>(orElse: LazyArg<B>): 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<B>(f: (result: Initial<A, E>) => B): Builder<Out | B, A, E, never, F>;
+  onInitialOrWaiting<B>(f: (result: Result<A, E>) => B): Builder<Out | B, A, E, never, F>;
+}) & ([A] extends [never] ? unknown : {
+  onSuccess<B>(f: (value: A, result: Success<A, E>) => B): Builder<Out | B, never, E, I, F>;
+}) & ([E] extends [never] ? unknown : {
+  onError<B>(f: (error: E, result: Failure<A, E>) => B): Builder<Out | B, A, never, I, F>;
+  onErrorIf<B extends E, C>(refinement: Refinement<E, B>, f: (error: B, result: Failure<A, E>) => C): Builder<Out | C, A, Types.EqualsWith<E, B, E, Exclude<E, B>>, I, F>;
+  onErrorIf<C>(predicate: Predicate<E>, f: (error: E, result: Failure<A, E>) => C): Builder<Out | C, A, E, I, F>;
+  onErrorTag<const Tags extends readonly Types.Tags<E>[], B>(tags: Tags, f: (error: Types.ExtractTag<E, Tags[number]>, result: Failure<A, E>) => B): Builder<Out | B, A, Types.ExcludeTag<E, Tags[number]>, I, F>;
+  onErrorTag<const Tag extends Types.Tags<E>, B>(tag: Tag, f: (error: Types.ExtractTag<E, Tag>, result: Failure<A, E>) => B): Builder<Out | B, A, Types.ExcludeTag<E, Tag>, I, F>;
+}) & ([E | F] extends [never] ? unknown : {
+  onFailure<B>(f: (cause: Cause.Cause<E>, result: Failure<A, E>) => B): Builder<Out | B, A, never, I, never>;
+}) & (Interrupt extends F ? {
+  onInterrupt<B>(f: (interruptors: ReadonlySet<number>, result: Failure<A, E>) => B): Builder<Out | B, A, E, I, Exclude<F, Interrupt>>;
+} : unknown) & (Defect extends F ? {
+  onDefect<B>(f: (defect: unknown, result: Failure<A, E>) => B): Builder<Out | B, A, E, I, Exclude<F, Defect>>;
+} : unknown);
+//#endregion
+export { touch as A, failure as B, isWaiting as C, matchWithWaiting as D, matchWithError as E, Failure as F, isResult as H, Initial as I, Result as L, waiting as M, waitingFrom as N, replacePrevious as O, Schema as P, Success as R, isSuccess as S, match as T, success as U, initial as V, getOrThrow as _, With as a, isInterrupted as b, cause as c, failWithPrevious as d, failureWithPrevious as f, getOrElse as g, fromExitWithPrevious as h, Result_d_exports as i, value as j, toExit as k, error as l, fromExit as m, Defect as n, all as o, flatMap as p, Interrupt as r, builder as s, Builder as t, fail as u, isFailure as v, map as w, isNotInitial as x, isInitial as y, TypeId as z };