/// <reference types="node" />
/**
 * This file contains the Promise algebraic data type. Promise is the javascript
 * built in data structure for asynchronous computation.
 *
 * @module Promise
 * @since 2.0.0
 */
import "./_dnt.polyfills.js";
import type { Kind, Out } from "./kind.js";
import type { Applicable } from "./applicable.js";
import type { Combinable } from "./combinable.js";
import type { Either } from "./either.js";
import type { Initializable } from "./initializable.js";
import type { Mappable } from "./mappable.js";
import type { Flatmappable } from "./flatmappable.js";
import type { Wrappable } from "./wrappable.js";
/**
 * A type for Promise over any, useful as an extension target for
 * functions that take any Promise and do not need to
 * unwrap the type.
 *  @since 2.0.0
 */
export type AnyPromise = Promise<any>;
/**
 * A type level unwrapor, used to pull the inner type from a Promise.
 *
 * @since 2.0.0
 */
export type TypeOf<T> = T extends Promise<infer A> ? A : never;
/**
 * Specifies Promise as a Higher Kinded Type, with
 * covariant parameter A corresponding to the 0th
 * index of any Substitutions.
 *
 * @since 2.0.0
 */
export interface KindPromise extends Kind {
    readonly kind: Promise<Out<this, 0>>;
}
/**
 * A Promise<A> with the inner resolve function
 * hoisted and attached to itself.
 *
 * @since 2.0.0
 */
export type Deferred<A> = Promise<A> & {
    readonly resolve: (a: A | PromiseLike<A>) => void;
};
/**
 * Create a Deferred<A> from a type.
 *
 * @example
 * ```ts
 * import { deferred } from "./promise.ts";
 *
 * const promise = deferred<number>();
 *
 * // Logs 1 after a second
 * promise.then(console.log);
 * setTimeout(() => promise.resolve(1), 1000);
 * ```
 *
 * @since 2.0.0
 */
export declare function deferred<A = never>(): Deferred<A>;
/**
 * Make an existing Promise somewhat abortable. While
 * the returned promise does resolve when the abort signal
 * occurs, the existing promise continues running in the
 * background. For this reason it is important to
 * catch any errors associated with the original promise and
 * to not implement side effects in the aborted promise.
 *
 * @example
 * ```ts
 * import { abortable, wait } from "./promise.ts";
 * import { pipe } from "./fn.ts";
 *
 * const controller = new AbortController();
 * const slow = wait(1000).then(() => 1);
 * const wrapped = pipe(
 *   slow,
 *   abortable(controller.signal, msg => msg),
 * );
 *
 * setTimeout(() => controller.abort("Hi"), 500);
 *
 * // After 500ms result contains the following
 * // { tag: "Left", left: "Hi" }
 * const result = await wrapped;
 * ```
 *
 * @since 2.0.0
 */
export declare function abortable<B>(signal: AbortSignal, onAbort: (reason: unknown) => B): <A>(ua: Promise<A>) => Promise<Either<B, A>>;
/**
 * Create a Promise<void> that resolve after ms milliseconds.
 *
 * @example
 * ```ts
 * import { wait, map } from "./promise.ts";
 * import { pipe } from "./fn.ts";
 *
 * const delayed = pipe(
 *   wait(1000),
 *   map(() => "Hello World"),
 * );
 *
 * // After 1 second
 * const result = await delayed; // "Hello World"
 * ```
 *
 * @since 2.0.0
 */
export declare function wait(ms: number): Promise<void>;
/**
 * Delay the resolution of an existing Promise. This does not
 * affect the original promise directly, it only waits for
 * a ms milliseconds before flatmaping into the original promise.
 *
 * @example
 * ```ts
 * import { wrap, delay } from "./promise.ts";
 * import { pipe } from "./fn.ts";
 *
 * // Waits 250 milliseconds before returning
 * const result = await pipe(
 *   wrap(1),
 *   delay(250),
 * ); // 1
 * ```
 *
 * @since 2.0.0
 */
export declare function delay(ms: number): <A>(ua: Promise<A>) => Promise<A>;
/**
 * An alias for Promise.resolve.
 *
 * @example
 * ```ts
 * import { resolve } from "./promise.ts";
 *
 * const result = await resolve(1); // 1
 * ```
 *
 * @since 2.0.0
 */
export declare function resolve<A>(a: A | PromiseLike<A>): Promise<A>;
/**
 * An alias for Promise.reject.
 *
 * @example
 * ```ts
 * import { reject } from "./promise.ts";
 *
 * const result = await reject(1).catch(x => x); // 1
 * ```
 *
 * @since 2.0.0
 */
export declare function reject(rejection: unknown): Promise<never>;
/**
 * An alias for Promise.then
 *
 * @example
 * ```ts
 * import { wrap, then } from "./promise.ts";
 * import { pipe } from "./fn.ts";
 *
 * const result = await pipe(
 *   wrap(1),
 *   then(n => n + 1),
 * ); // 2
 * ```
 *
 * @since 2.0.0
 */
export declare function then<A, I>(fai: (a: A) => I | Promise<I>): (ua: Promise<A>) => Promise<I>;
/**
 * An alias for Promise.catch
 *
 * @example
 * ```ts
 * import { reject, catchError } from "./promise.ts";
 * import { pipe } from "./fn.ts";
 *
 * const result = await pipe(
 *   reject(1),
 *   catchError(() => "Uhoh"),
 * ); // "UhOh"
 * ```
 *
 * @since 2.0.0
 */
export declare function catchError<A>(fua: (u: unknown) => A): (ta: Promise<A>) => Promise<A>;
/**
 * An alias for Promise.all
 *
 * @example
 * ```ts
 * import { all, wrap } from "./promise.ts";
 *
 * const result = await all(wrap(1), wrap("Hello")); // [1, "Hello"]
 * ```
 *
 * @since 2.0.0
 */
export declare function all<T extends AnyPromise[]>(...ua: T): Promise<{
    [K in keyof T]: Awaited<T[K]>;
}>;
/**
 * An alias for Promise.race. Note that Promise.race leaks
 * async operations in most runtimes. This means that the
 * slower promise does not stop when the faster promise
 * resolves/rejects. In effect Promise.race does not
 * handle cancellation.
 *
 * @example
 * ```ts
 * import { wait, map, race, wrap } from "./promise.ts";
 * import { pipe } from "./fn.ts";
 *
 * const one = pipe(wait(200), map(() => "one"));
 * const two = pipe(wait(300), map(() => "two"));
 *
 * // After 200 milliseconds resolves from one
 * const result = await race(one, two); // "one"
 * ```
 *
 * @since 2.0.0
 */
export declare function race<T extends AnyPromise[]>(...ua: T): Promise<Awaited<T[keyof T]>>;
/**
 * Create a Promise from a value A or another PromiseLike. This
 * is essentially an alias of Promise.resolve.
 *
 * @example
 * ```ts
 * import { wrap } from "./promise.ts";
 *
 * const result = await wrap(1); // 1
 * ```
 *
 * @since 2.0.0
 */
export declare function wrap<A>(a: A | PromiseLike<A>): Promise<A>;
/**
 * Create a new Promise<I> from a Promise<(a: A) => I> and
 * a Promise<A>. Although Promises encapsulate
 * asynchrony, there is no way defer a Promise once created,
 * thus this ap function always evaluates both input Promises
 * in parallel.
 *
 * @example
 * ```ts
 * import { wrap, apply } from "./promise.ts";
 * import { pipe } from "./fn.ts";
 *
 * type Person = { name: string, age: number };
 *
 * const person = (name: string) => (age: number): Person => ({ name, age });
 *
 * const result = pipe(
 *   wrap(person),
 *   apply(wrap("Brandon")),
 *   apply(wrap(37)),
 * ); // Promise<Person>
 * ```
 *
 * @since 2.0.0
 */
export declare function apply<A>(ua: Promise<A>): <I>(ufai: Promise<(a: A) => I>) => Promise<I>;
/**
 * Create a new Promise by mapping over the result of an existing Promise.
 * This is effectively Promise.then, but narrowed to non-promise returning
 * functions. If the mapping function returns a Promise then the type
 * for this function will be incorrect, as there is no way to create a
 * Promise<Promise<I>>.
 *
 * @example
 * ```ts
 * import { wrap, map } from "./promise.ts";
 * import { pipe } from "./fn.ts";
 *
 * const result = await pipe(
 *   wrap(1),
 *   map(n => n + 1),
 * ); // 2
 * ```
 *
 * @since 2.0.0
 */
export declare function map<A, I>(fai: (a: A) => I): (ua: Promise<A>) => Promise<I>;
/**
 * Create a new Promise by flatmaping over the result of an existing Promise.
 * This is effectively Promise.then.
 *
 * @example
 * ```ts
 * import { wrap, flatmap } from "./promise.ts";
 * import { pipe } from "./fn.ts";
 *
 * const result = await pipe(
 *   wrap(1),
 *   flatmap(n => wrap(n + 1)),
 * ); // 2
 * ```
 *
 * @since 2.0.0
 */
export declare function flatmap<A, I>(faui: (a: A) => Promise<I>): (ua: Promise<A>) => Promise<I>;
/**
 * @since 2.0.0
 */
export declare function fail<A = never>(b: unknown): Promise<A>;
/**
 * Wrap a function that potentially throws in a try/catch block,
 * handling any thrown errors and returning the result inside
 * of a Promise.
 *
 * @example
 * ```ts
 * import { tryCatch, reject, wrap } from "./promise.ts";
 * import { pipe, todo } from "./fn.ts";
 * // Note that todo will always throw synchronously.
 *
 * const add = (n: number) => n + 1;
 * const throwSync = (_: number): number => todo();
 * const throwAsync = (_: number): Promise<number> => reject("Ha!");
 *
 * const catchAdd = tryCatch(add, () => -1);
 * const catchSync = tryCatch(throwSync, () => -1);
 * const catchAsync = tryCatch(throwAsync, () => -1);
 *
 * const resultAdd = await catchAdd(1); // 2
 * const resultSync = await catchSync(1); // -1
 * const resultAsync = await catchAsync(1); // -1
 * ```
 * @since 2.0.0
 */
export declare function tryCatch<D extends unknown[], A>(handle: (...args: D) => A | PromiseLike<A>, onThrow: (error: unknown, args: D) => A): (...args: D) => Promise<A>;
/**
 * @since 2.0.0
 */
export declare function getCombinablePromise<A>({ combine }: Combinable<A>): Combinable<Promise<A>>;
/**
 * @since 2.0.0
 */
export declare function getInitializablePromise<A>(I: Initializable<A>): Initializable<Promise<A>>;
/**
 * The canonical implementation of Applicable for Promise. It contains
 * the methods wrap, apply, and map.
 *
 * @since 2.0.0
 */
export declare const ApplicablePromise: Applicable<KindPromise>;
/**
 * The canonical implementation of Mappable for Promise. It contains
 * the method map.
 *
 * @since 2.0.0
 */
export declare const MappablePromise: Mappable<KindPromise>;
/**
 * The canonical implementation of Flatmappable for Promise. It contains
 * the methods wrap, apply, map, and flatmap.
 *
 * @since 2.0.0
 */
export declare const FlatmappablePromise: Flatmappable<KindPromise>;
/**
 * @since 2.0.0
 */
export declare const WrappablePromise: Wrappable<KindPromise>;
/**
 * @since 2.0.0
 */
export declare const tap: <A>(fn: (value: A) => void) => <B = never, C = never, D = unknown, E = unknown>(ua: Promise<A>) => Promise<A>;
/**
 * @since 2.0.0
 */
export declare const bind: <N extends string, A, I, J = never, K = never, L = unknown, M = unknown>(name: Exclude<N, keyof A>, faui: (a: A) => Promise<I>) => <B = never, C = never, D extends L = L>(ua: Promise<A>) => Promise<{ readonly [K_1 in N | keyof A]: K_1 extends keyof A ? A[K_1] : I; }>;
/**
 * @since 2.0.0
 */
export declare const bindTo: <N extends string>(name: N) => <A, B = never, C = never, D = unknown, E = unknown>(ua: Promise<A>) => Promise<{ readonly [K in N]: A; }>;