aveazul 1.0.2 → 2.0.0

package/README.md

@@ -16,7 +16,7 @@ Further, if you like Bluebird's API but want to use native Promises, AveAzul giv
 
 ## Requirements
 
-- node.js version >= 12
+- node.js version >= 22.12
 
 ## Installation
 

package/cjs-entry.cjs

@@ -0,0 +1,7 @@
+"use strict";
+
+// ESM-only build; this shim keeps `require("aveazul")` returning the AveAzul class,
+// because require(esm) yields the module namespace rather than the default export.
+const m = require("./dist/index.js");
+
+module.exports = Object.assign(m.default, m);

package/dist/any.d.ts

@@ -0,0 +1,2 @@
+import type { AveAzulClass } from "./aveazul.js";
+export declare function addStaticAny(AveAzul: AveAzulClass, force?: boolean): void;

package/dist/any.js

@@ -0,0 +1,45 @@
+import { toArray, isPromise } from "./util.js";
+import { AggregateError } from "@jchip/error";
+export function addStaticAny(AveAzul, force = false) {
+    if (force || !AveAzul.any) {
+        AveAzul.any = function (args) {
+            let argsArray;
+            try {
+                argsArray = toArray(args);
+            }
+            catch (error) {
+                return AveAzul.reject(error);
+            }
+            if (argsArray.length === 0) {
+                return AveAzul.reject(new RangeError("Input array must contain at least 1 items but contains only 0 items"));
+            }
+            return new AveAzul((resolve, reject) => {
+                const len = argsArray.length;
+                let settled = false;
+                const errors = [];
+                const doFinish = (value) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    resolve(value);
+                };
+                const addError = (err) => {
+                    errors.push(err);
+                    if (!settled && errors.length >= len) {
+                        settled = true;
+                        reject(new AggregateError(errors));
+                    }
+                };
+                for (let i = 0; i < len; i++) {
+                    const arg = argsArray[i];
+                    if (isPromise(arg)) {
+                        arg.then(doFinish, addError);
+                    }
+                    else {
+                        doFinish(arg);
+                    }
+                }
+            });
+        };
+    }
+}

package/dist/aveazul.d.ts

@@ -0,0 +1,344 @@
+import { PromisifyOptions } from "./promisify.js";
+import { PromisifyAllOptions } from "./promisify-all.js";
+import { Disposer } from "./disposer.js";
+import { triggerUncaughtException } from "./util.js";
+import { OperationalError, isOperationalError, isProgrammerError } from "./operational-error.js";
+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;