@xylabs/promise/dist/neutral/index.d.ts

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

import { TypedValue } from '@xylabs/typeof';
export { isPromise } from '@xylabs/typeof';

/**
 * For use with Promise.allSettled to filter only successful results
 * @param val
 * @returns
 */
declare const fulfilled: <T>(val: PromiseSettledResult<T>) => val is PromiseFulfilledResult<T>;

/**
 * For use with Promise.allSettled to reduce to only successful result values
 * @example <caption>Casting the initialValue provided to reduce</caption>
 * const resolved = Promise.resolve('resolved')
 * const rejected = Promise.reject('rejected')
 * const settled = await Promise.allSettled([resolved, rejected])
 * const results = settled.reduce(fulfilledValues, [] as string[])
 * // results === [ 'resolved' ]
 * @example <caption>Providing type parameter to reduce and initialValue type can be inferred</caption>
 * const resolved = Promise.resolve('resolved')
 * const rejected = Promise.reject('rejected')
 * const settled = await Promise.allSettled([resolved, rejected])
 * const results = settled.reduce<string[]>(fulfilledValues, [])
 * // results === [ 'resolved' ]
 * @param previousValue
 * @param currentValue
 * @returns
 */
declare const fulfilledValues: <T>(previousValue: T[], currentValue: PromiseSettledResult<T>) => T[];

type PromiseExSubFunc<T, TResult = T> = (value: T) => TResult;
type PromiseExFunc<T> = (resolve?: PromiseExSubFunc<T, void>, reject?: PromiseExSubFunc<T, void>) => void;
type PromiseExValueFunc<V> = (value?: V) => boolean;
declare class PromiseEx<T, V = void> extends Promise<T> {
    cancelled?: boolean;
    private _value?;
    constructor(func: PromiseExFunc<T>, value?: V);
    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined, onvalue?: (value?: V) => boolean): Promise<TResult1 | TResult2>;
    value(onvalue?: (value?: V) => boolean): this;
}

/**
 * For use with Promise.allSettled to filter only rejected results
 * @param val
 * @returns
 */
declare const rejected: <T>(val: PromiseSettledResult<T>) => val is PromiseRejectedResult;

type Promisable<T, V = never> = PromiseEx<T, V> | Promise<T> | T;
type PromisableArray<T, V = never> = Promisable<T[], V>;
type OptionalPromisable<T, V = never> = Promisable<T | undefined, V>;
type OptionalPromisableArray<T, V = never> = PromisableArray<T | undefined, V>;
type NullablePromisable<T, V = never> = Promisable<T | null, V>;
type NullablePromisableArray<T, V = never> = PromisableArray<T | null, V>;
/** @description Used to document promises that are being used as Mutexes */
type AsyncMutex<T> = Promise<T>;
interface PromiseType {
    then: () => unknown;
}
type AnyNonPromise = Exclude<TypedValue, PromiseType>;

declare function toPromise<T>(value: Promisable<T>): Promise<T>;

export { PromiseEx, fulfilled, fulfilledValues, rejected, toPromise };
export type { AnyNonPromise, AsyncMutex, NullablePromisable, NullablePromisableArray, OptionalPromisable, OptionalPromisableArray, Promisable, PromisableArray, PromiseExFunc, PromiseExSubFunc, PromiseExValueFunc, PromiseType };