resultar 0.6.1 → 0.8.0

package/dist/index-ph1sfvDU.d.cts

@@ -0,0 +1,393 @@
+declare class ResultAsync<T, E> implements PromiseLike<Result<T, E>> {
+    static fromSafePromise<T, E = never>(promise: PromiseLike<T>): ResultAsync<T, E>;
+    static fromPromise<T, E>(promise: PromiseLike<T>, errorFn: (e: unknown) => E): ResultAsync<T, E>;
+    static combine<T extends readonly [ResultAsync<unknown, unknown>, ...Array<ResultAsync<unknown, unknown>>]>(asyncResultList: T): CombineResultAsyncs<T>;
+    static combine<T extends ReadonlyArray<ResultAsync<unknown, unknown>>>(asyncResultList: T): CombineResultAsyncs<T>;
+    static combineWithAllErrors<T extends readonly [ResultAsync<unknown, unknown>, ...Array<ResultAsync<unknown, unknown>>]>(asyncResultList: T): CombineResultsWithAllErrorsArrayAsync<T>;
+    static combineWithAllErrors<T extends ReadonlyArray<ResultAsync<unknown, unknown>>>(asyncResultList: T): CombineResultsWithAllErrorsArrayAsync<T>;
+    private readonly innerPromise;
+    constructor(res: Promise<Result<T, E>>);
+    then<A, B>(// eslint-disable-line unicorn/no-thenable
+    successCallback?: (res: Result<T, E>) => A | PromiseLike<A>, failureCallback?: (reason: unknown) => B | PromiseLike<B>): PromiseLike<A | B>;
+    mapErr<U>(f: (t: E) => U | Promise<U>): ResultAsync<T, U>;
+    map<X>(f: (t: T) => X | Promise<X>): ResultAsync<X, E>;
+    andThen<R extends Result<unknown, unknown>>(f: (t: T) => R): ResultAsync<InferOkTypes<R>, InferErrTypes<R> | E>;
+    andThen<R extends ResultAsync<unknown, unknown>>(f: (t: T) => R): ResultAsync<InferAsyncOkTypes<R>, InferAsyncErrTypes<R> | E>;
+    andThen<U, F>(f: (t: T) => Result<U, F> | ResultAsync<U, F>): ResultAsync<U, E | F>;
+    match<X>(ok: (t: T) => X, _err: (e: E) => X): Promise<X>;
+    tap(f: (t: T) => void | Promise<void>): ResultAsync<T, E>;
+    /**
+     * Emulates Rust's `?` operator in `safeTry`'s body. See also `safeTry`.
+     */
+    safeUnwrap(): AsyncGenerator<Result<never, E>, T>;
+}
+declare function fromSafePromise<T, E = never>(promise: PromiseLike<T>): ResultAsync<T, E>;
+declare function fromPromise<T, E>(promise: PromiseLike<T>, errorFn: (e: unknown) => E): ResultAsync<T, E>;
+declare function okAsync<T, E = never>(value: T): ResultAsync<T, E>;
+declare function errAsync<T = never, E = unknown>(error: E): ResultAsync<T, E>;
+declare function fromThrowableAsync<A extends readonly any[], T, E>(fn: (...args: A) => Promise<T>, errorFn?: (err: unknown) => E): (...args: A) => ResultAsync<T, E>;
+declare function safeTryAsync<T, E>(body: () => AsyncGenerator<Result<never, E>, Result<T, E>>): ResultAsync<T, E>;
+type CombineResultAsyncs<T extends ReadonlyArray<ResultAsync<unknown, unknown>>> = IsLiteralArray<T> extends 1 ? TraverseAsync<UnwrapAsync<T>> : ResultAsync<ExtractOkAsyncTypes<T>, ExtractErrAsyncTypes<T>[number]>;
+type CombineResultsWithAllErrorsArrayAsync<T extends ReadonlyArray<ResultAsync<unknown, unknown>>> = IsLiteralArray<T> extends 1 ? TraverseWithAllErrorsAsync<UnwrapAsync<T>> : ResultAsync<ExtractOkAsyncTypes<T>, Array<ExtractErrAsyncTypes<T>[number]>>;
+type UnwrapAsync<T> = IsLiteralArray<T> extends 1 ? Writable<T> extends [infer H, ...infer Rest] ? H extends PromiseLike<infer HI> ? HI extends Result<unknown, unknown> ? [Dedup<HI>, ...UnwrapAsync<Rest>] : never : never : [] : T extends Array<infer A> ? A extends PromiseLike<infer HI> ? HI extends Result<infer L, infer R> ? Array<Result<L, R>> : never : never : never;
+type TraverseAsync<T, Depth extends number = 5> = IsLiteralArray<T> extends 1 ? Combine<T, Depth> extends [infer Oks, infer Errs] ? ResultAsync<EmptyArrayToNever<Oks>, MembersToUnion<Errs>> : never : T extends Array<infer I> ? Combine<MemberListOf<I>, Depth> extends [infer Oks, infer Errs] ? Oks extends unknown[] ? Errs extends unknown[] ? ResultAsync<EmptyArrayToNever<Array<Oks[number]>>, MembersToUnion<Array<Errs[number]>>> : ResultAsync<EmptyArrayToNever<Array<Oks[number]>>, Errs> : Errs extends unknown[] ? ResultAsync<Oks, MembersToUnion<Array<Errs[number]>>> : ResultAsync<Oks, Errs> : never : never;
+type TraverseWithAllErrorsAsync<T, Depth extends number = 5> = IsLiteralArray<T> extends 1 ? Combine<T, Depth> extends [infer Oks, infer Errs] ? ResultAsync<EmptyArrayToNever<Oks>, EmptyArrayToNever<Errs>> : never : Writable<T> extends Array<infer I> ? Combine<MemberListOf<I>, Depth> extends [infer Oks, infer Errs] ? Oks extends unknown[] ? Errs extends unknown[] ? ResultAsync<EmptyArrayToNever<Array<Oks[number]>>, EmptyArrayToNever<Array<Errs[number]>>> : ResultAsync<EmptyArrayToNever<Array<Oks[number]>>, Errs> : Errs extends unknown[] ? ResultAsync<Oks, EmptyArrayToNever<Array<Errs[number]>>> : ResultAsync<Oks, Errs> : never : never;
+type Writable<T> = T extends readonly unknown[] ? [...T] : T;
+
+type Dedup<T> = T extends Result<infer RL, infer RR> ? Result<RL, RR> : T;
+type MemberListOf<T> = ((T extends unknown ? (t: T) => T : never) extends infer U ? (U extends unknown ? (u: U) => unknown : never) extends (v: infer V) => unknown ? V : never : never) extends (_: unknown) => infer W ? [...MemberListOf<Exclude<T, W>>, W] : [];
+type ExtractOkTypes<T extends ReadonlyArray<Result<unknown, unknown>>> = {
+    [idx in keyof T]: T[idx] extends Result<infer U, unknown> ? U : never;
+};
+type ExtractOkAsyncTypes<T extends ReadonlyArray<ResultAsync<unknown, unknown>>> = {
+    [idx in keyof T]: T[idx] extends ResultAsync<infer U, unknown> ? U : never;
+};
+type ExtractErrTypes<T extends ReadonlyArray<Result<unknown, unknown>>> = {
+    [idx in keyof T]: T[idx] extends Result<unknown, infer E> ? E : never;
+};
+type ExtractErrAsyncTypes<T extends ReadonlyArray<ResultAsync<unknown, unknown>>> = {
+    [idx in keyof T]: T[idx] extends ResultAsync<unknown, infer E> ? E : never;
+};
+type InferOkTypes<R> = R extends Result<infer T, unknown> ? T : never;
+type InferErrTypes<R> = R extends Result<unknown, infer E> ? E : never;
+type InferAsyncOkTypes<R> = R extends ResultAsync<infer T, unknown> ? T : never;
+type InferAsyncErrTypes<R> = R extends ResultAsync<unknown, infer E> ? E : never;
+type IsLiteralArray<T> = T extends {
+    length: infer L;
+} ? L extends number ? number extends L ? 0 : 1 : 0 : 0;
+type EmptyArrayToNever<T, NeverArrayToNever extends number = 0> = T extends [] ? never : NeverArrayToNever extends 1 ? T extends [never, ...infer Rest] ? [EmptyArrayToNever<Rest>] extends [never] ? never : T : T : T;
+type Prev = [
+    never,
+    0,
+    1,
+    2,
+    3,
+    4,
+    5,
+    6,
+    7,
+    8,
+    9,
+    10,
+    11,
+    12,
+    13,
+    14,
+    15,
+    16,
+    17,
+    18,
+    19,
+    20,
+    21,
+    22,
+    23,
+    24,
+    25,
+    26,
+    27,
+    28,
+    29,
+    30,
+    31,
+    32,
+    33,
+    34,
+    35,
+    36,
+    37,
+    38,
+    39,
+    40,
+    41,
+    42,
+    43,
+    44,
+    45,
+    46,
+    47,
+    48,
+    49,
+    ...Array<0>
+];
+type Transpose<A, Transposed extends unknown[][] = [], Depth extends number = 10> = A extends [infer T, ...infer Rest] ? T extends [infer L, infer R] ? Transposed extends [infer PL, infer PR] ? PL extends unknown[] ? PR extends unknown[] ? Transpose<Rest, [[...PL, L], [...PR, R]], Prev[Depth]> : never : never : Transpose<Rest, [[L], [R]], Prev[Depth]> : Transposed : Transposed;
+type CollectResults<T, Collected extends unknown[] = [], Depth extends number = 50> = [
+    Depth
+] extends [never] ? [] : T extends [infer H, ...infer Rest] ? H extends Result<infer L, infer R> ? CollectResults<Rest, [
+    ...Collected,
+    [L, R]
+], Prev[Depth]> : never : Collected;
+type UnknownMembersToNever<T> = T extends [infer H, ...infer R] ? [[unknown] extends [H] ? never : H, ...UnknownMembersToNever<R>] : T;
+type MembersToUnion<T> = T extends unknown[] ? T[number] : never;
+type Combine<T, Depth extends number = 5> = Transpose<CollectResults<T>, [], Depth> extends [
+    infer L,
+    infer R
+] ? [UnknownMembersToNever<L>, UnknownMembersToNever<R>] : Transpose<CollectResults<T>, [], Depth> extends [] ? [[], []] : never;
+type Traverse<T, Depth extends number = 5> = Combine<T, Depth> extends [infer Oks, infer Errs] ? Result<EmptyArrayToNever<Oks, 1>, MembersToUnion<Errs>> : never;
+type TraverseWithAllErrors<T, Depth extends number = 5> = Combine<T, Depth> extends [
+    infer Oks,
+    infer Errs
+] ? Result<EmptyArrayToNever<Oks>, EmptyArrayToNever<Errs>> : never;
+type CombineResults<T extends ReadonlyArray<Result<unknown, unknown>>> = IsLiteralArray<T> extends 1 ? Traverse<T> : Result<ExtractOkTypes<T>, ExtractErrTypes<T>[number]>;
+type CombineResultsWithAllErrorsArray<T extends ReadonlyArray<Result<unknown, unknown>>> = IsLiteralArray<T> extends 1 ? TraverseWithAllErrors<T> : Result<ExtractOkTypes<T>, Array<ExtractErrTypes<T>[number]>>;
+declare const combineResultAsyncList: <T, E>(asyncResultList: ReadonlyArray<ResultAsync<T, E>>) => ResultAsync<readonly T[], E>;
+/**
+ * Short circuits on the FIRST Err value that we find
+ */
+declare const combineResultList: <T, E>(resultList: ReadonlyArray<Result<T, E>>) => Result<readonly T[], E>;
+declare const combineResultAsyncListWithAllErrors: <T, E>(asyncResultList: ReadonlyArray<ResultAsync<T, E>>) => ResultAsync<readonly T[], E[]>;
+/**
+ * Give a list of all the errors we find
+ */
+declare const combineResultListWithAllErrors: <T, E>(resultList: ReadonlyArray<Result<T, E>>) => Result<readonly T[], E[]>;
+
+/**
+ * A Result interface that is used to define the methods that are available on a
+ * `Result` object.
+ *
+ * The immutability of the `Result` object is maintained by the interface.
+ */
+interface Resultable<T, E> {
+    get value(): T;
+    get error(): E;
+    /**
+     * Used to check if a `Result` is an `OK`
+     *
+     * @returns `true` if the result is an `OK` variant of Result
+     */
+    isOk(): boolean;
+    /**
+     * Used to check if a `Result` is an `Err`
+     *
+     * @returns `true` if the result is an `Err` variant of Result
+     */
+    isErr(): boolean;
+    /**
+     * Unwrap the `Ok` value, or return the default if there is an `Err`
+     *
+     * @param v the default value to return if there is an `Err`
+     */
+    unwrapOr<A>(defaultValue: A): T | A;
+    /**
+     * **This method is unsafe, and should only be used in a test environments**
+     *
+     * Takes a `Result<T, E>` and returns a `T` when the result is an `Ok`, otherwise it throws a custom object.
+     *
+     * @param config
+     */
+    _unsafeUnwrap(config?: ErrorConfig): T;
+    /**
+     * **This method is unsafe, and should only be used in a test environments**
+     *
+     * takes a `Result<T, E>` and returns a `E` when the result is an `Err`,
+     * otherwise it throws a custom object.
+     *
+     * @param config
+     */
+    _unsafeUnwrapErr(config?: ErrorConfig): E;
+}
+declare class Result<T, E> implements Resultable<T, E> {
+    private readonly state;
+    /**
+     * Wraps a function with a try catch, creating a new function with the same
+     * arguments but returning `Ok` if successful, `Err` if the function throws
+     *
+     * @param fn function to wrap with ok on success or err on failure
+     * @param errorFn when an error is thrown, this will wrap the error result if provided
+     */
+    static fromThrowable<Fn extends (...args: readonly any[]) => unknown, E>(fn: Fn, errorFn?: (e: any) => E): (...args: Parameters<Fn>) => Result<ReturnType<Fn>, E>;
+    static ok<T, E = never>(value: T): Result<T, E>;
+    static err<T = never, E = unknown>(error: E): Result<T, E>;
+    static combine<T extends readonly [Result<unknown, unknown>, ...Array<Result<unknown, unknown>>]>(resultList: T): CombineResults<T>;
+    static combine<T extends ReadonlyArray<Result<unknown, unknown>>>(resultList: T): CombineResults<T>;
+    static combineWithAllErrors<T extends readonly [Result<unknown, unknown>, ...Array<Result<unknown, unknown>>]>(resultList: T): CombineResultsWithAllErrorsArray<T>;
+    static combineWithAllErrors<T extends ReadonlyArray<Result<unknown, unknown>>>(resultList: T): CombineResultsWithAllErrorsArray<T>;
+    readonly value: T;
+    readonly error: E;
+    private constructor();
+    /**
+     * Used to check if a `Result` is an `OK`
+     *
+     * @returns `true` if the result is an `OK` variant of Result
+     */
+    isOk(): boolean;
+    /**
+     * Used to check if a `Result` is an `Err`
+     *
+     * @returns `true` if the result is an `Err` variant of Result
+     */
+    isErr(): boolean;
+    /**
+     * Maps a `Result<T, E>` to `Result<U, E>`
+     * by applying a function to a contained `Ok` value, leaving an `Err` value
+     * untouched.
+     *
+     * @param f The function to apply an `OK` value
+     * @returns the result of applying `f` or an `Err` untouched
+     */
+    map<X, Y>(f: (t: T) => X): Result<X, E | Y>;
+    /**
+     * Maps a `Result<T, E>` to `Result<T, F>` by applying a function to a
+     * contained `Err` value, leaving an `Ok` value untouched.
+     *
+     * This function can be used to pass through a successful result while
+     * handling an error.
+     *
+     * @param f a function to apply to the error `Err` value
+     */
+    mapErr<X>(fn: (t: E) => X): Result<T, X>;
+    /**
+     * Similar to `map` Except you must return a new `Result`.
+     *
+     * This is useful for when you need to do a subsequent computation using the
+     * inner `T` value, but that computation might fail.
+     * Additionally, `andThen` is really useful as a tool to flatten a
+     * `Result<Result<A, E2>, E1>` into a `Result<A, E2>` (see example below).
+     *
+     * @param f The function to apply to the current value
+     */
+    andThen<X, Y>(f: (t: T) => Result<X, Y>): Result<X, E | Y>;
+    /**
+     * Takes an `Err` value and maps it to a `Result<T, SomeNewType>`.
+     *
+     * This is useful for error recovery.
+     *
+     *
+     * @param f  A function to apply to an `Err` value, leaving `Ok` values
+     * untouched.
+     */
+    orElse<Y>(f: (t: E) => Result<T, Y>): Result<T, Y>;
+    /**
+     * Similar to `map` Except you must return a new `Result`.
+     *
+     * This is useful for when you need to do a subsequent async computation using
+     * the inner `T` value, but that computation might fail. Must return a ResultAsync
+     *
+     * @param f The function that returns a `ResultAsync` to apply to the current
+     * value
+     */
+    asyncAndThen<X, Y>(f: (t: T) => ResultAsync<X, Y>): ResultAsync<X, E | Y>;
+    /**
+     * Maps a `Result<T, E>` to `ResultAsync<U, E>`
+     * by applying an async function to a contained `Ok` value, leaving an `Err`
+     * value untouched.
+     *
+     * @param f An async function to apply an `OK` value
+     */
+    asyncMap<X>(f: (t: T) => Promise<X>): ResultAsync<X, E>;
+    /**
+     * Unwrap the `Ok` value, or return the default if there is an `Err`
+     *
+     * @param v the default value to return if there is an `Err`
+     */
+    unwrapOr<A>(defaultValue: A): T | A;
+    /**
+     *
+     * Given 2 functions (one for the `Ok` variant and one for the `Err` variant)
+     * execute the function that matches the `Result` variant.
+     *
+     * Match callbacks do not necessitate to return a `Result`, however you can
+     * return a `Result` if you want to.
+     *
+     * `match` is like chaining `map` and `mapErr`, with the distinction that
+     * with `match` both functions must have the same return type.
+     *
+     * @param ok
+     * @param err
+     */
+    match<X>(fnOk: (t: T) => X, fnErr: (e: E) => X): X;
+    /**
+     * Performs a side effect for the `Ok` variant of `Result`.
+     *
+     * @param f The function to apply an `OK` value
+     * @returns the result of applying `f` or an `Err` untouched
+     */
+    tap(f: (t: T) => void): Result<T, E>;
+    /**
+     * This method is used to clean up and release any resources that the `Result`
+     * @param f The function that will be called to clean up the resources
+     */
+    finally<X = T, Y = E>(f: (value: X, error: Y) => void): DisposableResult<X, Y>;
+    /**
+     * **This method is unsafe, and should only be used in a test environments**
+     *
+     * Takes a `Result<T, E>` and returns a `T` when the result is an `Ok`, otherwise it throws a custom object.
+     *
+     * @param config
+     */
+    _unsafeUnwrap(config?: ErrorConfig): T;
+    /**
+     * **This method is unsafe, and should only be used in a test environments**
+     *
+     * takes a `Result<T, E>` and returns a `E` when the result is an `Err`,
+     * otherwise it throws a custom object.
+     *
+     * @param config
+     */
+    _unsafeUnwrapErr(config?: ErrorConfig): E;
+    safeUnwrap(): Generator<Result<never, E>, T>;
+}
+/**
+ * A `Disposable` is an object that has a `dispose` method that can be used to
+ * clean up resources.
+ */
+declare class DisposableResult<T, E> implements Resultable<T, E>, Disposable {
+    readonly result: Resultable<T, E>;
+    private readonly finalizer;
+    constructor(result: Resultable<T, E>, finalizer: (value: T, error: E) => void);
+    get value(): T;
+    get error(): E;
+    _unsafeUnwrap(config?: ErrorConfig | undefined): T;
+    _unsafeUnwrapErr(config?: ErrorConfig | undefined): E;
+    isOk(): boolean;
+    isErr(): boolean;
+    unwrapOr<A>(defaultValue: A): T | A;
+    [Symbol.dispose](): void;
+}
+declare const ok: <T, E = never>(value: T) => Result<T, E>;
+declare const err: <T = never, E = unknown>(error: E) => Result<T, E>;
+declare const fromThrowable: <Fn extends (...args: readonly any[]) => unknown, E>(fn: Fn, errorFn?: ((e: any) => E) | undefined) => (...args: Parameters<Fn>) => Result<ReturnType<Fn>, E>;
+/**
+ * Evaluates the given generator to a Result returned or an Err yielded from it,
+ * whichever comes first.
+ *
+ * This function, in combination with `Result.safeUnwrap()`, is intended to emulate
+ * Rust's ? operator.
+ * See `/tests/safeTry.test.ts` for examples.
+ *
+ * @param body - What is evaluated. In body, `yield* result.safeUnwrap()` works as
+ * Rust's `result?` expression.
+ * @returns The first occurence of either an yielded Err or a returned Result.
+ */
+declare function safeTry<T, E>(body: () => Generator<Result<never, E>, Result<T, E>>): Result<T, E>;
+/**
+ * Evaluates the given generator to a Result returned or an Err yielded from it,
+ * whichever comes first.
+ *
+ * This function, in combination with `Result.safeUnwrap()`, is intended to emulate
+ * Rust's ? operator.
+ * See `/tests/safeTry.test.ts` for examples.
+ *
+ * @param body - What is evaluated. In body, `yield* result.safeUnwrap()` and
+ * `yield* resultAsync.safeUnwrap()` work as Rust's `result?` expression.
+ * @returns The first occurence of either an yielded Err or a returned Result.
+ */
+declare function safeTry<T, E>(body: () => AsyncGenerator<Result<never, E>, Result<T, E>>): Promise<Result<T, E>>;
+
+interface ErrorConfig {
+    withStackTrace: boolean;
+}
+interface ResultarError<T, E> {
+    data: {
+        type: string;
+        value: T | undefined;
+    } | {
+        type: string;
+        value: E | undefined;
+    };
+    message: string;
+    stack: string | undefined;
+}
+declare const createResultarError: <T, E>(message: string, result: Result<T, E>, config?: ErrorConfig) => ResultarError<T, E>;
+
+export { err as A, fromThrowable as B, type CombineResultAsyncs as C, type Dedup as D, type ExtractOkTypes as E, safeTry as F, type ErrorConfig as G, createResultarError as H, type InferOkTypes as I, type MemberListOf as M, ResultAsync as R, type Transpose as T, fromPromise as a, fromThrowableAsync as b, type CombineResultsWithAllErrorsArrayAsync as c, type ExtractOkAsyncTypes as d, errAsync as e, fromSafePromise as f, type ExtractErrTypes as g, type ExtractErrAsyncTypes as h, type InferErrTypes as i, type InferAsyncOkTypes as j, type InferAsyncErrTypes as k, type IsLiteralArray as l, type EmptyArrayToNever as m, type MembersToUnion as n, okAsync as o, type Combine as p, type CombineResults as q, type CombineResultsWithAllErrorsArray as r, safeTryAsync as s, combineResultAsyncList as t, combineResultList as u, combineResultAsyncListWithAllErrors as v, combineResultListWithAllErrors as w, Result as x, DisposableResult as y, ok as z };