aveazul/dist-esm/aveazul.d.ts

Bluebird drop-in replacement built on native Promise

import { PromisifyOptions } from "./promisify.ts";
import { PromisifyAllOptions } from "./promisify-all.ts";
import { Disposer } from "./disposer.ts";
import { triggerUncaughtException } from "./util.ts";
import { OperationalError, isOperationalError, isProgrammerError } from "./operational-error.ts";
export interface MapOptions {
    concurrency?: number;
}
export interface AsCallbackOptions {
    spread?: boolean;
}
export interface FromCallbackOptions {
    multiArgs?: boolean;
}
export interface Deferred<T> {
    promise: AveAzul<T>;
    resolve: (value: T | PromiseLike<T>) => void;
    reject: (reason?: unknown) => void;
}
export interface AveAzulClass {
    new <T>(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: unknown) => void) => void): AveAzul<T>;
    resolve<T>(value: T | PromiseLike<T>): AveAzul<T>;
    resolve(): AveAzul<void>;
    reject<T = never>(reason?: unknown): AveAzul<T>;
    all<T>(values: Iterable<T | PromiseLike<T>>): AveAzul<Awaited<T>[]>;
    delay<T>(ms: number, value?: T): AveAzul<T>;
    map<T, U>(value: Iterable<T | PromiseLike<T>>, fn: (item: T, index: number, length: number) => U | PromiseLike<U>, options?: MapOptions): AveAzul<U[]>;
    mapSeries<T, U>(value: Iterable<T | PromiseLike<T>>, fn: (item: T, index: number, length: number) => U | PromiseLike<U>): AveAzul<U[]>;
    try<T>(fn: () => T | PromiseLike<T>): AveAzul<T>;
    props<T extends object>(obj: T): AveAzul<{
        [K in keyof T]: Awaited<T[K]>;
    }>;
    defer<T>(): Deferred<T>;
    each<T>(items: Iterable<T | PromiseLike<T>>, fn: (item: T, index: number, length: number) => unknown): AveAzul<T[]>;
    reduce<T, U>(array: Iterable<T | PromiseLike<T>>, fn: (value: U, item: T, index: number, length: number) => U | PromiseLike<U>, initialValue?: U): AveAzul<U>;
    promisify<T = unknown>(fn: (...args: any[]) => void, options?: PromisifyOptions): (...args: any[]) => AveAzul<T>;
    promisifyAll<T extends object>(target: T, options?: PromisifyAllOptions): T;
    method<T, Args extends any[]>(fn: (...args: Args) => T | PromiseLike<T>): (...args: Args) => AveAzul<T>;
    using<R>(...args: any[]): AveAzul<R>;
    join(...args: any[]): AveAzul<any>;
    fromCallback<T>(fn: (callback: (err: Error | null, result?: T) => void) => void, options?: FromCallbackOptions): AveAzul<T>;
    fromNode<T>(fn: (callback: (err: Error | null, result?: T) => void) => void, options?: FromCallbackOptions): AveAzul<T>;
    some<T>(promises: Iterable<T | PromiseLike<T>>, count: number): AveAzul<T[]>;
    any<T>(args: Iterable<T | PromiseLike<T>>): AveAzul<T>;
    ___throwUncaughtError(error: unknown): void;
    OperationalError: typeof OperationalError;
    __notImplementedInstance?: string[];
    __notImplementedStatic?: string[];
}
export type AveAzulInstance<T> = AveAzul<T>;
/**
 * @fileoverview
 * AveAzul ("Blue Bird" in Spanish) - Extended Promise class that provides Bluebird like utility methods
 * This implementation is inspired by and provides similar APIs to the Bluebird Promise library,
 * but built on top of native Promises. The name is a Spanish play on words referencing Bluebird.
 * @extends Promise
 */
declare class AveAzul<T> extends Promise<T> {
    constructor(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: unknown) => void) => void);
    /**
     * Note: Per ECMAScript specification, when extending Promise, both .then() and static methods
     * (resolve, reject, all, etc) must return instances of the derived class (AveAzul), so there's
     * no need to explicitly wrap returns in new AveAzul(). This behavior is standard across all
     * spec-compliant JS engines (V8, SpiderMonkey, JavaScriptCore, etc).
     */
    /**
     * Bluebird-style tap() method that lets you perform side effects in a chain
     * Similar to Bluebird's Promise.prototype.tap()
     * @param fn - Function to execute with the resolved value
     * @returns Promise that resolves with the original value
     */
    tap(fn: (value: T) => unknown): AveAzul<T>;
    /**
     * Bluebird-style filter() method for array operations
     * Similar to Bluebird's Promise.prototype.filter()
     * @param fn - Filter function to apply to each element
     * @returns Promise that resolves with the filtered array
     */
    filter(fn: (item: any, index: number, length: number) => any): AveAzul<any[]>;
    /**
     * Bluebird-style map() method for array operations
     * Similar to Bluebird's Promise.prototype.map()
     * @param fn - Map function to apply to each element
     * @returns Promise that resolves with the mapped array
     */
    map<U>(fn: (item: any, index: number, length: number) => U | PromiseLike<U>, options?: MapOptions): AveAzul<U[]>;
    /**
     * Bluebird-style mapSeries() method for array operations
     * Similar to Bluebird's Promise.prototype.mapSeries()
     * @param fn - Map function to apply to each element
     * @returns Promise that resolves with the mapped array
     */
    mapSeries<U>(fn: (item: any, index: number, length: number) => U | PromiseLike<U>): AveAzul<U[]>;
    /**
     * Bluebird-style return() method to inject a value into the chain
     * Similar to Bluebird's Promise.prototype.return()
     * @param value - Value to return
     * @returns Promise that resolves with the new value
     */
    return<U>(value: U): AveAzul<U>;
    /**
     * Bluebird-style any() method for waiting for any promises to resolve
     * @returns Promise that resolves with the first resolved promise
     */
    any(): AveAzul<any>;
    /**
     * Bluebird-style each() method for array iteration
     * Similar to Bluebird's Promise.prototype.each()
     * @param fn - Function to execute for each element
     * @returns Promise that resolves when iteration is complete
     */
    each(fn: (item: any, index: number, length: number) => unknown): AveAzul<any[]>;
    /**
     * Bluebird-style delay() method
     * @param ms - Milliseconds to delay
     * @returns Promise that resolves after the delay
     */
    delay(ms: number): AveAzul<void>;
    /**
     * Bluebird-style timeout() method
     * @param ms - Milliseconds before timeout
     * @param message - Optional error message
     * @returns Promise that rejects if timeout occurs
     */
    timeout(ms: number, message?: string): AveAzul<T>;
    /**
     * Bluebird-style props() for object properties
     * @returns Promise that resolves with an object of resolved values
     */
    props(): AveAzul<any>;
    /**
     * Bluebird-style tapCatch() for side effects on rejection
     * @param fn - Function to execute on rejection
     * @returns Promise that maintains the rejection
     */
    tapCatch(fn: (err: Error) => unknown): AveAzul<T>;
    /**
     * Bluebird-style reduce() method for array reduction
     * Similar to Bluebird's Promise.prototype.reduce()
     * @param fn - Reducer function to apply to each element
     * @param initialValue - Optional initial value
     * @returns Promise that resolves with the final reduced value
     */
    reduce<U>(fn: (value: U, item: any, index: number, length: number) => U | PromiseLike<U>, initialValue?: U): AveAzul<U>;
    /**
     * Bluebird-style throw() that returns a rejected promise with the given reason
     * @param reason - Value to reject the promise with
     * @returns Promise that rejects with the given reason
     */
    throw(reason: unknown): AveAzul<never>;
    /**
     * Bluebird-style catchThrow() that catches an error and throws a new one
     * @param reason - Value to reject the promise with
     * @returns Promise that rejects with the new reason
     */
    catchThrow(reason: unknown): AveAzul<T>;
    /**
     * Bluebird-style catchReturn() that catches an error and returns a value instead
     * @param value - Value to return
     * @returns Promise that resolves with the given value
     */
    catchReturn<U>(value: U): AveAzul<T | U>;
    /**
     * Bluebird-style get() for retrieving a property value
     * @param key - Key to retrieve
     * @returns Promise that resolves with the property value
     */
    get<K extends keyof T>(key: K): AveAzul<T[K]>;
    /**
     * Bluebird-style disposer() for resource cleanup
     * @param fn - Cleanup function
     * @returns Disposer object
     */
    disposer(fn: (resource: T) => void | Promise<void>): Disposer<T>;
    /**
     * Bluebird-style spread() method for handling array arguments
     * Similar to Bluebird's Promise.prototype.spread()
     * @param fn - Function to apply to the array arguments
     * @returns Promise that resolves with the function's return value
     */
    spread<U>(fn: (...args: any[]) => U | PromiseLike<U>): AveAzul<U>;
    some(count: number): AveAzul<any[]>;
    /**
     * Bluebird-style all() method for array operations
     * Similar to Promise.all() but operates on the resolved value of this promise
     * @returns Promise that resolves when all items in the array resolve
     */
    all(): AveAzul<any[]>;
    /**
     * Bluebird-style asCallback() method
     * Attaches a callback to the promise and returns the promise.
     * The callback is invoked when the promise is resolved or rejected.
     *
     * @param cb - Node.js-style callback function (err, value)
     * @param options - Additional options
     * @returns The same promise instance
     */
    asCallback(cb: ((err: Error | null, value?: T) => void) | undefined | null, options?: AsCallbackOptions): AveAzul<T>;
    nodeify(cb: ((err: Error | null, value?: T) => void) | undefined | null, options?: AsCallbackOptions): AveAzul<T>;
    /**
     * Bluebird-style call() method for calling a method on the resolved value
     * @param methodName - Name of the method to call
     * @param args - Arguments to pass to the method
     * @returns Promise that resolves with the method's return value
     */
    call(methodName: string, ...args: any[]): AveAzul<any>;
    /**
     * Catches only operational errors and passes them to the handler.
     * Programmer errors (non-operational) are rethrown.
     * @param handler - Function to handle operational errors
     * @returns Promise with the error handled or rethrown
     */
    error(handler: (err: Error) => unknown): AveAzul<T>;
    /**
     * Static helper methods
     */
    /**
     * Bluebird-style delay() that resolves after specified milliseconds
     * @param ms - Milliseconds to delay
     * @param value - Optional value to resolve with
     * @returns Promise that resolves after the delay
     */
    static delay<U>(ms: number, value?: U): AveAzul<U>;
    /**
     * Bluebird-style map() for array operations
     * @param value - Array to map over
     * @param fn - Map function to apply to each element
     * @returns Promise that resolves with the mapped array
     */
    static map<T, U>(value: Iterable<T | PromiseLike<T>>, fn: (item: T, index: number, length: number) => U | PromiseLike<U>, options?: MapOptions): AveAzul<U[]>;
    /**
     * Bluebird-style mapSeries() for array operations
     * @param value - Array to map over
     * @param fn - Map function to apply to each element
     * @returns Promise that resolves with the mapped array
     */
    static mapSeries<T, U>(value: Iterable<T | PromiseLike<T>>, fn: (item: T, index: number, length: number) => U | PromiseLike<U>): AveAzul<U[]>;
    /**
     * Bluebird-style try() for wrapping sync/async functions
     * @param fn - Function to execute
     * @returns Promise that resolves with the function's return value
     */
    static try<T>(fn: () => T | PromiseLike<T>): AveAzul<T>;
    /**
     * Bluebird-style props() for object properties
     * @param obj - Object with promise values
     * @returns Promise that resolves with an object of resolved values
     */
    static props<T extends object>(obj: T): AveAzul<{
        [K in keyof T]: Awaited<T[K]>;
    }>;
    /**
     * Bluebird-style defer() for creating a deferred promise
     * @returns Deferred object with promise, resolve, and reject methods
     */
    static defer<T>(): Deferred<T>;
    /**
     * Bluebird-style each() for array iteration
     * @param items - Array to iterate over
     * @param fn - Iterator function to call for each item
     * @returns Promise that resolves when iteration is complete
     */
    static each<T>(items: Iterable<T | PromiseLike<T>>, fn: (item: T, index: number, length: number) => unknown): AveAzul<T[]>;
    /**
     * Bluebird-style reduce() for array reduction
     * @param array - Array to reduce
     * @param fn - Reducer function (value, item, index, length)
     * @param initialValue - Optional initial value
     * @returns Promise that resolves with the final reduced value
     */
    static reduce<T, U>(array: Iterable<T | PromiseLike<T>>, fn: (value: U, item: T, index: number, length: number) => U | PromiseLike<U>, initialValue?: U): AveAzul<U>;
    /**
     * Bluebird-style promisify() for converting callback-based functions to promises
     * @param fn - Function to promisify
     * @param options - Options object
     * @returns Promisified function
     */
    static promisify<T = unknown>(fn: (...args: any[]) => void, options?: PromisifyOptions): (...args: any[]) => AveAzul<T>;
    /**
     * Bluebird-style promisifyAll() for converting callback-based functions to promises
     * @param target - Object to promisify
     * @param options - Options object
     * @returns Object with promisified methods
     */
    static promisifyAll<T extends object>(target: T, options?: PromisifyAllOptions): T;
    /**
     * Bluebird-style method() for creating a method that returns a promise
     * @param fn - Function to create a method for
     * @returns Method function that returns a promise
     */
    static method<T, Args extends any[]>(fn: (...args: Args) => T | PromiseLike<T>): (...args: Args) => AveAzul<T>;
    /**
     * Bluebird-style using() for resource management. There is only a static version of this method.
     * After the handler finish and returns, regardless of whether it resolves or rejects, the resources will be disposed.
     *
     * @param resources - Resource disposers, either an array of disposers or a variadic argument list
     * @param args - Handler function that will receive the resources as arguments
     * @returns Promise that resolves with handler result
     */
    static using<R>(resources: any, ...args: any[]): AveAzul<R>;
    /**
     * Bluebird-style join() for joining promises
     *
     * @param args - Promises to join
     * @returns Promise that resolves with the handler's return value
     */
    static join(...args: any[]): AveAzul<any>;
    /**
     * Bluebird-style fromCallback() for converting callback-based functions to promises
     * @param fn - Function to convert
     * @param options - Options object
     * @returns Promise that resolves with the function's return value
     */
    static fromCallback<T>(fn: (callback: (err: Error | null, ...args: T[]) => void) => void, options?: FromCallbackOptions): AveAzul<T>;
    static fromNode: typeof AveAzul.fromCallback;
    /**
     * When fatal error and AveAzul needs to crash the process,
     * this method is used to throw the error.
     *
     * @param error - The error to throw.
     */
    static ___throwUncaughtError: typeof triggerUncaughtException;
    /**
     * Bluebird-style some() for waiting for some promises to resolve
     * @param promises - Array or iterable of promises
     * @param count - Number of promises that need to resolve
     * @returns Promise that resolves when count promises have resolved
     */
    static some<T>(promises: Iterable<T | PromiseLike<T>>, count: number): AveAzul<T[]>;
    /**
     * Bluebird-style any() for waiting for any promise to resolve
     * @param args - Array or iterable of promises
     * @returns Promise that resolves with the first resolved value
     */
    static any<T>(args: Iterable<T | PromiseLike<T>>): AveAzul<T>;
    static OperationalError: typeof OperationalError;
    static isOperationalError: typeof isOperationalError;
    static isProgrammerError: typeof isProgrammerError;
    static Disposer: typeof Disposer;
    static __notImplementedInstance?: string[];
    static __notImplementedStatic?: string[];
}
export { AveAzul };
export default AveAzul;