already/dist/index.d.ts

Promise extensions; map, filter, etc

declare const _default: {
    defer: typeof defer;
    deferSet: typeof deferSet;
    delay: typeof delay;
    delayChain: typeof delayChain;
    each: typeof each;
    filter: typeof filter;
    flatMap: typeof flatMap;
    funnel: typeof funnel;
    inspect: typeof inspect;
    map: typeof map;
    once: typeof once;
    props: typeof props;
    reduce: typeof reduce;
    rethrow: typeof rethrow;
    retry: typeof retry;
    some: typeof some;
    specific: typeof specific;
    tap: typeof tap;
    wrapFunction: typeof wrapFunction;
};
export default _default;
/**
 * IfPromise< P, T[, U] > returns T if P is a promise, otherwise returns U (or
 * fallbacks to <never> ).
 */
export type IfPromise<P, T, U = never> = P extends Promise<infer _X> ? T : U;
/**
 * IfNotPromise< P, T[, U] > returns U (fallbacks to <never>) if P is a
 * promise, otherwise returns T.
 */
export type IfNotPromise<P, T, U = never> = P extends Promise<infer _X> ? U : T;
/**
 * Returns the Promise wrapped value of P, unless it's already a promise, where
 * the promise itself is returned instead.
 *
 * For P being Promise<E>, it returns P
 * For non-promise P, it returns Promise<P>
 */
export type PromiseOf<P> = P extends Promise<infer _U> ? P : Promise<P>;
/**
 * Returns the element type of a promise, or the type itself if it isn't
 * wrapped in a promise.
 *
 * For P being Promise<E>, it returns E
 * For non-promise P, it returns P
 */
export type PromiseElement<P> = P extends Promise<infer U> ? U : P;
/**
 * Given type P, returns the same type P if it is a Promise, otherwise never.
 */
export type EnsurePromise<P> = P extends Promise<infer _U> ? P : never;
/**
 * Given type T, returns the same type T if it is *not* a Promise, otherwise
 * never.
 */
export type EnsureNotPromise<T> = T extends Promise<infer _U> ? never : T;
export type Callback<R, A extends any[]> = (...args: A) => Promise<R>;
/**
 * Create a maximum concurrency for fn (can be curried)
 *
 * Either specify fn and invoke the returned function, or skip fn and the
 * returned function will take an arbitrary function to limit concurrency for.
 *
 * @param size Concurrency limit
 * @param fn The function to limit the concurrency for
 * @returns Concurrency-limited version of fn
 */
export declare function concurrent<R, A extends any[]>(size: number, fn: Callback<R, A>): (...a: A) => Promise<R>;
export declare function concurrent(size: number): <R, A extends any[]>(fn: Callback<R, A>, ...a: A) => Promise<R>;
export declare function delay(milliseconds: number): Promise<void>;
export declare function delay<T>(milliseconds: number, t: T): Promise<T>;
export declare function delayChain(milliseconds: number): <T>(t: T) => Promise<T>;
export declare function tap<U, Fn extends (t: U) => (void | PromiseLike<void>)>(fn: Fn): (u: U) => Promise<U>;
export declare function props(obj: any): Promise<any>;
export interface ConcurrencyOptions {
    concurrency: number;
}
export interface ChunkOptions {
    chunk: number | 'idle';
}
export type FilterMapOptions = Partial<ConcurrencyOptions | ChunkOptions>;
export type MapArray<T> = Array<T | PromiseLike<T>> | ConcatArray<T | PromiseLike<T>>;
export type MapFn<T, U> = (t: T, index: number, arr: MapArray<T>) => U | Promise<U>;
export type FlatMapFn<T, U> = (t: T, index: number, arr: MapArray<T>) => U | ConcatArray<U | Promise<U>> | Array<U | Promise<U>> | Promise<U | ConcatArray<U | Promise<U>> | Array<U | Promise<U>>>;
export type FilterFn<T> = MapFn<T, boolean>;
export declare function filter<T>(filterFn: FilterFn<T>): (t: ConcatArray<T | PromiseLike<T>>) => Promise<Array<T>>;
export declare function filter<T>(opts: FilterMapOptions, filterFn: FilterFn<T>): (t: ConcatArray<T | PromiseLike<T>>) => Promise<Array<T>>;
export declare function filter<T>(arr: ConcatArray<T | PromiseLike<T>>, filterFn: FilterFn<T>): Promise<Array<T>>;
export declare function filter<T>(arr: ConcatArray<T | PromiseLike<T>>, opts: FilterMapOptions, filterFn: FilterFn<T>): Promise<Array<T>>;
export declare function map<T, U>(mapFn: MapFn<T, U>): (t: ConcatArray<T | PromiseLike<T>>) => Promise<Array<U>>;
export declare function map<T, U>(opts: FilterMapOptions, mapFn: MapFn<T, U>): (t: ConcatArray<T | PromiseLike<T>>) => Promise<Array<U>>;
export declare function map<T, U>(arr: ConcatArray<T | PromiseLike<T>>, mapFn: MapFn<T, U>): Promise<Array<U>>;
export declare function map<T, U>(arr: ConcatArray<T | PromiseLike<T>>, opts: FilterMapOptions, mapFn: MapFn<T, U>): Promise<Array<U>>;
export declare function flatMap<T, U>(mapFn: FlatMapFn<T, U>): (t: ConcatArray<T | PromiseLike<T>>) => Promise<Array<U>>;
export declare function flatMap<T, U>(opts: FilterMapOptions, mapFn: FlatMapFn<T, U>): (t: ConcatArray<T | PromiseLike<T>>) => Promise<Array<U>>;
export declare function flatMap<T, U>(arr: ConcatArray<T | PromiseLike<T>>, mapFn: FlatMapFn<T, U>): Promise<Array<U>>;
export declare function flatMap<T, U>(arr: ConcatArray<T | PromiseLike<T>>, opts: FilterMapOptions, mapFn: FlatMapFn<T, U>): Promise<Array<U>>;
export type SyncReduceInput<T> = Iterable<T | PromiseLike<T>>;
export type ReduceInput<T> = SyncReduceInput<T> | PromiseLike<SyncReduceInput<T>>;
export type ReduceFunction<T, R> = (accumulator: R, current: T, index: number, length: number) => R | PromiseLike<R>;
export declare function reduce<T, R>(input: ReduceInput<T>, reducer: ReduceFunction<T, R>): Promise<R | undefined>;
export declare function reduce<T, R>(input: ReduceInput<T>, reducer: ReduceFunction<T, R>, initialValue: R | PromiseLike<R>): Promise<R>;
export declare function reduce<T, R>(reducer: ReduceFunction<T, R>): <U extends SyncReduceInput<T>>(input: U) => Promise<R | undefined>;
export declare function reduce<T, R>(reducer: ReduceFunction<T, R>, initialValue: R | PromiseLike<R>): <U extends SyncReduceInput<T>>(input: U) => Promise<R>;
export type EachFn<T> = (t: T, index: number, length: number) => void | Promise<void>;
export declare function each<T>(eachFn: EachFn<T>): (t: ConcatArray<T | PromiseLike<T>>) => Promise<Array<T>>;
export declare function each<T>(opts: FilterMapOptions, eachFn: EachFn<T>): (t: ConcatArray<T | PromiseLike<T>>) => Promise<Array<T>>;
export declare function each<T>(arr: ConcatArray<T | PromiseLike<T>>, eachFn: EachFn<T>): Promise<Array<T>>;
export declare function each<T>(arr: ConcatArray<T | PromiseLike<T>>, opts: FilterMapOptions, eachFn: EachFn<T>): Promise<Array<T>>;
export type SomeReturn<R> = Promise<R | false>;
export type SomeSyncReturn<R> = SomeReturn<R> | R | false;
export type SomePredicate<T, R> = (t: T) => SomeSyncReturn<R>;
export type SomeArray<T> = ConcatArray<T | PromiseLike<T>> | PromiseLike<ConcatArray<T | PromiseLike<T>>>;
export declare function some<T, R>(list: SomeArray<T>, fn: SomePredicate<T, R>): SomeReturn<R>;
export declare function some<T, R>(fn: SomePredicate<T, R>): (list: SomeArray<T>) => SomeReturn<R>;
export type OnceRunnee<T, R> = T extends void ? (() => R) : ((t: T) => R);
export interface OnceRunner {
    <T, R>(fn: OnceRunnee<T, R>, t: T): R;
    <R>(fn: OnceRunnee<void, R>): R;
}
export declare function once(): OnceRunner;
export declare function once<R>(fn: OnceRunnee<void, R>): OnceRunnee<void, R>;
export declare function once<T, R>(fn: OnceRunnee<T, R>): OnceRunnee<T, R>;
export declare function retry<R>(times: number, fn: () => R, retryable?: (err: unknown) => boolean): R;
export interface Deferred<T> {
    resolve: (t: T | PromiseLike<T>) => void;
    reject: <E extends Error>(err: E) => void;
    promise: Promise<T>;
}
export interface EmptyDeferred {
    resolve: ((t: void | PromiseLike<void>) => void) & (() => void);
    reject: <E extends Error>(err: E) => void;
    promise: Promise<void>;
}
/**
 * Creates a defer object used to pass around a promise and its resolver
 */
export declare function defer<T>(): Deferred<T>;
export declare function defer(v: void): EmptyDeferred;
export interface ResolvedReflection<T> {
    error?: undefined;
    value: T;
    isResolved: true;
    isRejected: false;
}
export interface RejectedReflection {
    error: Error;
    value?: undefined;
    isResolved: false;
    isRejected: true;
}
export type Reflection<T> = ResolvedReflection<T> | RejectedReflection;
export declare function reflect<T>(promise: Promise<T>): Promise<Reflection<T>>;
export interface InspectablePromise<T> {
    promise: Promise<T>;
    isResolved: boolean;
    isRejected: boolean;
    isPending: boolean;
}
export declare function inspect<T>(promise: Promise<T>): InspectablePromise<T>;
export type DeferredInspectable<T> = InspectablePromise<T> & Deferred<T>;
export type EmptyDeferredInspectable = InspectablePromise<void> & EmptyDeferred;
/**
 * Creates a defer object used to pass around a promise and its resolver
 */
export declare function deferInspectable<T>(): DeferredInspectable<T>;
export declare function deferInspectable(v: void): EmptyDeferredInspectable;
export type ErrorFilterFunction = (err: Error) => boolean;
export interface ErrorFilterObject {
    [key: string]: any;
}
export type CatchFilter = ErrorConstructor | ErrorFilterFunction | ErrorFilterObject;
export declare function specific<T, U extends Promise<T>>(filters: CatchFilter | ConcatArray<CatchFilter> | null, handler: (err: Error) => U): (err: Error) => (U);
export declare function specific<T>(filters: CatchFilter | ConcatArray<CatchFilter> | null, handler: (err: Error) => T): (err: Error) => (T | Promise<T>);
export declare function rethrow<T extends Error = any>(fn: (err?: T) => (void | PromiseLike<void>)): (err: T) => Promise<never>;
export interface NotTimedOutValue<T> {
    timedout: false;
    reflection: Reflection<T>;
    promise: Promise<T>;
}
export interface TimedOutValue<T> {
    timedout: true;
    reflection: undefined;
    promise: Promise<T>;
}
/**
 * A TimeoutValue contains:
 *   * A boolean whether the promise timed out
 *   * The synchronous value or error of a resolved or rejected promise (if
 *     not timed out)
 *   * The promise itself to further await if timed out.
 */
export type TimeoutValue<T> = NotTimedOutValue<T> | TimedOutValue<T>;
/**
 * Timeout a promise with a certain number of milliseconds.
 *
 * Returns a promise (that will never be rejected) being resolved within _at
 * least_ the timeout duration. The returned value contains the promise
 * value or error, unless timeout was reached.
 *
 * @param promise The promise to await for at most <timeout> ms
 * @param timeout Milliseconds to wait at most before timing out
 * @returns A promise to a {@link TimeoutValue} object
 */
export declare function timeout<T>(promise: Promise<T>, timeout: number): Promise<TimeoutValue<T>>;
export declare function wrapFunction<R extends void>(wrap: () => () => R): (<U extends void, V extends Promise<U> | U>(cb: () => V) => V) & (<U extends any, V extends Promise<U> | U>(cb: () => V) => V);
export declare function wrapFunction<T extends {}, R extends void>(wrap: (t: T) => () => R): (<U extends void, V extends Promise<U> | U>(t: T, cb: () => V) => V) & (<U extends any, V extends Promise<U> | U>(t: T, cb: () => V) => V);
export declare function wrapFunction<R extends void>(wrap: () => Promise<() => R>): (<U extends void, V extends Promise<U> | U>(cb: () => V) => Promise<U>) & (<U extends any, V extends Promise<U> | U>(cb: () => V) => Promise<U>);
export declare function wrapFunction<T, R extends void>(wrap: (t: T) => Promise<() => R>): (<U extends void, V extends Promise<U> | U>(t: T, cb: () => V) => Promise<U>) & (<U extends any, V extends Promise<U> | U>(t: T, cb: () => V) => Promise<U>);
export declare function wrapFunction<R extends Promise<void>>(wrap: () => (() => R) | Promise<() => R>): <U, V extends Promise<U> | U>(cb: () => V) => Promise<U>;
export declare function wrapFunction<T, R extends Promise<void>>(wrap: (t: T) => (() => R) | Promise<() => R>): <U, V extends Promise<U> | U>(t: T, cb: () => V) => Promise<U>;
export type FunnelShouldRetry = () => boolean;
export type FunnelRetry<T> = () => Promise<T>;
export type FunnelShortcut = () => void;
export type FunnelFunction<T> = (shouldRetry: FunnelShouldRetry, retry: FunnelRetry<T>, shortcut: FunnelShortcut) => Promise<T>;
export type Funnel<T> = (funnelFunction: FunnelFunction<T>) => Promise<T>;
export interface FunnelOptions {
    onEmpty: () => void;
    concurrency: number;
}
export declare function funnel<T>(opts?: Partial<FunnelOptions>): Funnel<T>;
export declare class OrderedAsynchrony {
    private deferrals;
    wait(waitForIndex: number | ConcatArray<number>, resolveIndex?: number | ConcatArray<number> | undefined | null, rejectIndex?: number | ConcatArray<number> | undefined | null): Promise<void> & this;
    resolve(index: number | ConcatArray<number>): Promise<void> & this;
    reject(index: number | ConcatArray<number>, error?: Error): Promise<void> & this;
    private ensureDeferral;
    private decorate;
}
export declare function deferSet(): OrderedAsynchrony;