for-promise/dist/index.d.mts

A lightweight utility to run async loops with full control using Promises — like for, forEach, and while, but smarter.

/**
 * @typedef {Object} forPromiseIteration
 * @property {Record<string, any>|any[]|number} data - The main data source. Can be an array-like object, number (as count), or object for keys.
 * @property {string} [type] - Optional type of iteration. Currently supports "while" for while-like looping.
 * @property {*} [while] - While validator
 * @property {Function} [checker] - Used only with type: "while" to determine loop continuation.
 */
/**
 * Extra control object.
 *
 * @typedef {Object} forPromiseExtra
 * @property {boolean} complete - Whether the extra item has completed processing.
 * @property {boolean} forceBreak - Whether the extra item has triggered a forced break.
 * @property {number} count - Number of processed items.
 * @property {number|null} total - Total expected items, or null if not set.
 * @property {Array<any>} items - List of items processed.
 * @property {string} [type] - Optional type of processing (e.g., 'while').
 * @property {boolean} [error] - Is error.
 */
/**
 * @typedef {{
 *  error: boolean;
 *  forceBreak: boolean;
 *  type?: string;
 *  extra?: Array<forPromiseExtra>;
 *  count: number;
 *  total: number|null;
 *  items: Array<any>
 * }} ForPromiseStatus
 */
/**
 * Runs an asynchronous iterative operation with advanced control over flow, breaks, and nested (extra) iterations.
 * The function accepts a data object and a callback, and returns a Promise that resolves with iteration results.
 *
 * @param {forPromiseIteration} obj - The data object used to control the iteration process. It must follow a specific structure.
 * @param {Function} callback - A function that will be called on each iteration step.
 *
 * @returns {Promise<ForPromiseStatus>}
 */
export default function forPromise(obj: forPromiseIteration, callback: Function): Promise<ForPromiseStatus>;
export type forPromiseIteration = {
    /**
     * - The main data source. Can be an array-like object, number (as count), or object for keys.
     */
    data: Record<string, any> | any[] | number;
    /**
     * - Optional type of iteration. Currently supports "while" for while-like looping.
     */
    type?: string | undefined;
    /**
     * - While validator
     */
    while?: any;
    /**
     * - Used only with type: "while" to determine loop continuation.
     */
    checker?: Function | undefined;
};
/**
 * Extra control object.
 */
export type forPromiseExtra = {
    /**
     * - Whether the extra item has completed processing.
     */
    complete: boolean;
    /**
     * - Whether the extra item has triggered a forced break.
     */
    forceBreak: boolean;
    /**
     * - Number of processed items.
     */
    count: number;
    /**
     * - Total expected items, or null if not set.
     */
    total: number | null;
    /**
     * - List of items processed.
     */
    items: Array<any>;
    /**
     * - Optional type of processing (e.g., 'while').
     */
    type?: string | undefined;
    /**
     * - Is error.
     */
    error?: boolean | undefined;
};
export type ForPromiseStatus = {
    error: boolean;
    forceBreak: boolean;
    type?: string;
    extra?: Array<forPromiseExtra>;
    count: number;
    total: number | null;
    items: Array<any>;
};