async-flex-loop 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,282 @@
+/**
+ * Result of a task - similar to Promise.allSettled()
+ */
+type TaskResult<T, I = unknown> = {
+    status: "fulfilled";
+    value: T;
+    index: number;
+} | {
+    status: "rejected";
+    reason: Error;
+    item: I;
+    index: number;
+};
+/**
+ * Item in the internal queue with metadata
+ */
+interface QueueItem<T> {
+    item: T;
+    index: number;
+    retryCount: number;
+    addedAt: number;
+}
+interface QueueStats {
+    totalProcessed: number;
+    totalSuccess: number;
+    totalFailed: number;
+    avgProcessingTime: number;
+    successRate: number;
+}
+/**
+ * Options for AsyncFlexLoop (does not include initialItems and onItem - those are passed via constructor)
+ */
+interface AsyncFlexLoopOptions<InputType, ResponseType> {
+    /**
+     * Number of tasks that run concurrently
+     * @default Infinity
+     */
+    concurrency?: number;
+    /**
+     * Automatically start processing after construction
+     * @default true
+     */
+    autoStart?: boolean;
+    /**
+     * Number of retries when a task fails
+     * @default 0
+     */
+    retry?: number;
+    /**
+     * Delay between retries (ms)
+     * @default 0
+     */
+    retryDelay?: number;
+    /**
+     * Exponential backoff multiplier for retry
+     * @default 1 (no backoff)
+     */
+    retryBackoff?: number;
+    /**
+     * Delay after each task completes (ms)
+     * @default 0
+     */
+    delayAfterTask?: number;
+    /**
+     * Timeout for each task (ms)
+     * @default undefined (no timeout)
+     */
+    timeout?: number;
+    /**
+     * Yield to the event loop (setTimeout(0)) to reduce blocking
+     * @default true
+     */
+    yieldLoop?: boolean;
+    /**
+     * Throw error and stop the queue when an error occurs
+     * @default true
+     */
+    throwOnError?: boolean;
+    /**
+     * Callback when an error occurs
+     * @param this - AsyncFlexLoop instance for accessing queue methods
+     */
+    onError?: (this: any, error: Error, item: InputType, index: number) => void | Promise<void>;
+    /**
+     * Callback when a task completes
+     * @param this - AsyncFlexLoop instance for accessing queue methods
+     */
+    onTaskComplete?: (this: any, result: ResponseType | undefined, item: InputType, index: number) => Promise<void>;
+    /**
+     * Callback for progress updates
+     * @param this - AsyncFlexLoop instance for accessing queue methods
+     */
+    onProgress?: (this: any) => Promise<void>;
+    /**
+     * Callback when the queue becomes idle (all items processed)
+     * @param this - AsyncFlexLoop instance for accessing queue methods
+     */
+    onIdle?: (this: any) => void | Promise<void>;
+}
+
+declare enum QueueState {
+    Idle = "idle",
+    Pending = "pending",
+    Processing = "processing",
+    Paused = "paused"
+}
+
+/**
+ * AsyncFlexLoop - Flexible async array processing with dynamic concurrency
+ *
+ * @example
+ * ```typescript
+ * const queue = new AsyncFlexLoop(
+ *   [1, 2, 3],
+ *   async (item) => item * 2,
+ *   { concurrency: 2 }
+ * );
+ *
+ * await queue.onIdle();
+ * const results = await queue.getResults();
+ * ```
+ */
+declare class AsyncFlexLoop<InputType, ResponseType> {
+    private state;
+    private queue;
+    private activeCount;
+    private nextIndex;
+    private readonly results;
+    private idleResolvers;
+    private idleRejectors;
+    private readonly stats;
+    private readonly onItemHandler;
+    private readonly options;
+    /**
+     * Constructor with required parameters
+     */
+    constructor(initialItems: InputType[], onItem: (item: InputType, index: number) => Promise<ResponseType>, options?: AsyncFlexLoopOptions<InputType, ResponseType>);
+    /**
+     * Add items to the queue
+     * @returns Array of assigned indices
+     */
+    push(...items: InputType[]): number[];
+    /**
+     * Start processing the queue
+     */
+    start(): void;
+    /**
+     * Pause processing (currently running tasks will finish)
+     */
+    pause(): void;
+    /**
+     * Resume processing after a pause
+     */
+    resume(): void;
+    /**
+     * Clear all remaining items in the queue
+     */
+    clear(): void;
+    /**
+     * Wait until the queue is empty and all tasks have completed
+     */
+    onIdle(): Promise<void>;
+    getNextItem(): InputType | undefined;
+    /**
+     * Get results (waits for queue to finish)
+     * @returns Array with undefined for failed tasks
+     */
+    getResults(): Promise<(ResponseType | undefined)[]>;
+    /**
+     * Get raw results with full information (waits for queue to finish)
+     */
+    getRawResults(): Promise<TaskResult<ResponseType, InputType>[]>;
+    /**
+     * Get only successful results (waits for queue to finish)
+     */
+    getCompletedResultsAsync(): Promise<ResponseType[]>;
+    /**
+     * Get current successful results (does not wait)
+     */
+    getCompletedResults(): ResponseType[];
+    /**
+     * Number of items remaining in the queue
+     */
+    getPendingCount(): number;
+    /**
+     * Number of items that have been processed
+     */
+    getProcessedCount(): number;
+    /**
+     * Check whether the queue is currently processing
+     */
+    isRunning(): boolean;
+    /**
+     * Get the current state
+     */
+    getState(): QueueState;
+    /**
+     * Get statistics
+     */
+    getStats(): QueueStats;
+    /**
+     * Process the next items if there are available slots
+     */
+    private processNext;
+    /**
+     * Process a single item
+     */
+    private processItem;
+    /**
+     * Execute the task with optional timeout
+     */
+    private executeTask;
+    /**
+     * Handle successful task execution
+     */
+    private handleSuccess;
+    /**
+     * Handle task execution error
+     */
+    private handleError;
+    /**
+     * Finalize task processing
+     */
+    private finalizeTask;
+    /**
+     * Schedule a retry for a failed task
+     */
+    private scheduleRetry;
+    /**
+     * Record successful result
+     */
+    private recordSuccess;
+    /**
+     * Record failed result
+     */
+    private recordFailure;
+    /**
+     * Update statistics
+     */
+    private updateStats;
+    /**
+     * Handle fatal error (throwOnError=true)
+     */
+    private handleFatalError;
+    /**
+     * Check if queue is idle
+     */
+    private checkIdle;
+    /**
+     * Resolve all idle waiters
+     */
+    private resolveIdleWaiters;
+    /**
+     * Build results array maintaining order
+     */
+    private buildResultsArray;
+}
+
+declare class TimeoutError extends Error {
+    readonly item: unknown;
+    readonly index: number;
+    readonly timeoutMs: number;
+    constructor(item: unknown, index: number, timeoutMs: number);
+}
+declare class MaxRetryError extends Error {
+    readonly item: unknown;
+    readonly index: number;
+    readonly retryCount: number;
+    readonly originalError: Error;
+    constructor(item: unknown, index: number, retryCount: number, originalError: Error);
+}
+declare class QueueAbortError extends Error {
+    constructor(message?: string);
+}
+
+declare const delay: (ms: number) => Promise<void>;
+declare const yieldToEventLoop: () => Promise<void>;
+declare const calculateRetryDelay: (baseDelay: number, backoff: number, attemptNumber: number) => number;
+
+declare const withTimeout: <T>(promise: Promise<T>, ms: number, item: unknown, index: number) => Promise<T>;
+
+export { AsyncFlexLoop, type AsyncFlexLoopOptions, MaxRetryError, QueueAbortError, type QueueItem, QueueState, type QueueStats, type TaskResult, TimeoutError, calculateRetryDelay, delay, withTimeout, yieldToEventLoop };

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Result of a task - similar to Promise.allSettled()
+ */
+type TaskResult<T, I = unknown> = {
+    status: "fulfilled";
+    value: T;
+    index: number;
+} | {
+    status: "rejected";
+    reason: Error;
+    item: I;
+    index: number;
+};
+/**
+ * Item in the internal queue with metadata
+ */
+interface QueueItem<T> {
+    item: T;
+    index: number;
+    retryCount: number;
+    addedAt: number;
+}
+interface QueueStats {
+    totalProcessed: number;
+    totalSuccess: number;
+    totalFailed: number;
+    avgProcessingTime: number;
+    successRate: number;
+}
+/**
+ * Options for AsyncFlexLoop (does not include initialItems and onItem - those are passed via constructor)
+ */
+interface AsyncFlexLoopOptions<InputType, ResponseType> {
+    /**
+     * Number of tasks that run concurrently
+     * @default Infinity
+     */
+    concurrency?: number;
+    /**
+     * Automatically start processing after construction
+     * @default true
+     */
+    autoStart?: boolean;
+    /**
+     * Number of retries when a task fails
+     * @default 0
+     */
+    retry?: number;
+    /**
+     * Delay between retries (ms)
+     * @default 0
+     */
+    retryDelay?: number;
+    /**
+     * Exponential backoff multiplier for retry
+     * @default 1 (no backoff)
+     */
+    retryBackoff?: number;
+    /**
+     * Delay after each task completes (ms)
+     * @default 0
+     */
+    delayAfterTask?: number;
+    /**
+     * Timeout for each task (ms)
+     * @default undefined (no timeout)
+     */
+    timeout?: number;
+    /**
+     * Yield to the event loop (setTimeout(0)) to reduce blocking
+     * @default true
+     */
+    yieldLoop?: boolean;
+    /**
+     * Throw error and stop the queue when an error occurs
+     * @default true
+     */
+    throwOnError?: boolean;
+    /**
+     * Callback when an error occurs
+     * @param this - AsyncFlexLoop instance for accessing queue methods
+     */
+    onError?: (this: any, error: Error, item: InputType, index: number) => void | Promise<void>;
+    /**
+     * Callback when a task completes
+     * @param this - AsyncFlexLoop instance for accessing queue methods
+     */
+    onTaskComplete?: (this: any, result: ResponseType | undefined, item: InputType, index: number) => Promise<void>;
+    /**
+     * Callback for progress updates
+     * @param this - AsyncFlexLoop instance for accessing queue methods
+     */
+    onProgress?: (this: any) => Promise<void>;
+    /**
+     * Callback when the queue becomes idle (all items processed)
+     * @param this - AsyncFlexLoop instance for accessing queue methods
+     */
+    onIdle?: (this: any) => void | Promise<void>;
+}
+
+declare enum QueueState {
+    Idle = "idle",
+    Pending = "pending",
+    Processing = "processing",
+    Paused = "paused"
+}
+
+/**
+ * AsyncFlexLoop - Flexible async array processing with dynamic concurrency
+ *
+ * @example
+ * ```typescript
+ * const queue = new AsyncFlexLoop(
+ *   [1, 2, 3],
+ *   async (item) => item * 2,
+ *   { concurrency: 2 }
+ * );
+ *
+ * await queue.onIdle();
+ * const results = await queue.getResults();
+ * ```
+ */
+declare class AsyncFlexLoop<InputType, ResponseType> {
+    private state;
+    private queue;
+    private activeCount;
+    private nextIndex;
+    private readonly results;
+    private idleResolvers;
+    private idleRejectors;
+    private readonly stats;
+    private readonly onItemHandler;
+    private readonly options;
+    /**
+     * Constructor with required parameters
+     */
+    constructor(initialItems: InputType[], onItem: (item: InputType, index: number) => Promise<ResponseType>, options?: AsyncFlexLoopOptions<InputType, ResponseType>);
+    /**
+     * Add items to the queue
+     * @returns Array of assigned indices
+     */
+    push(...items: InputType[]): number[];
+    /**
+     * Start processing the queue
+     */
+    start(): void;
+    /**
+     * Pause processing (currently running tasks will finish)
+     */
+    pause(): void;
+    /**
+     * Resume processing after a pause
+     */
+    resume(): void;
+    /**
+     * Clear all remaining items in the queue
+     */
+    clear(): void;
+    /**
+     * Wait until the queue is empty and all tasks have completed
+     */
+    onIdle(): Promise<void>;
+    getNextItem(): InputType | undefined;
+    /**
+     * Get results (waits for queue to finish)
+     * @returns Array with undefined for failed tasks
+     */
+    getResults(): Promise<(ResponseType | undefined)[]>;
+    /**
+     * Get raw results with full information (waits for queue to finish)
+     */
+    getRawResults(): Promise<TaskResult<ResponseType, InputType>[]>;
+    /**
+     * Get only successful results (waits for queue to finish)
+     */
+    getCompletedResultsAsync(): Promise<ResponseType[]>;
+    /**
+     * Get current successful results (does not wait)
+     */
+    getCompletedResults(): ResponseType[];
+    /**
+     * Number of items remaining in the queue
+     */
+    getPendingCount(): number;
+    /**
+     * Number of items that have been processed
+     */
+    getProcessedCount(): number;
+    /**
+     * Check whether the queue is currently processing
+     */
+    isRunning(): boolean;
+    /**
+     * Get the current state
+     */
+    getState(): QueueState;
+    /**
+     * Get statistics
+     */
+    getStats(): QueueStats;
+    /**
+     * Process the next items if there are available slots
+     */
+    private processNext;
+    /**
+     * Process a single item
+     */
+    private processItem;
+    /**
+     * Execute the task with optional timeout
+     */
+    private executeTask;
+    /**
+     * Handle successful task execution
+     */
+    private handleSuccess;
+    /**
+     * Handle task execution error
+     */
+    private handleError;
+    /**
+     * Finalize task processing
+     */
+    private finalizeTask;
+    /**
+     * Schedule a retry for a failed task
+     */
+    private scheduleRetry;
+    /**
+     * Record successful result
+     */
+    private recordSuccess;
+    /**
+     * Record failed result
+     */
+    private recordFailure;
+    /**
+     * Update statistics
+     */
+    private updateStats;
+    /**
+     * Handle fatal error (throwOnError=true)
+     */
+    private handleFatalError;
+    /**
+     * Check if queue is idle
+     */
+    private checkIdle;
+    /**
+     * Resolve all idle waiters
+     */
+    private resolveIdleWaiters;
+    /**
+     * Build results array maintaining order
+     */
+    private buildResultsArray;
+}
+
+declare class TimeoutError extends Error {
+    readonly item: unknown;
+    readonly index: number;
+    readonly timeoutMs: number;
+    constructor(item: unknown, index: number, timeoutMs: number);
+}
+declare class MaxRetryError extends Error {
+    readonly item: unknown;
+    readonly index: number;
+    readonly retryCount: number;
+    readonly originalError: Error;
+    constructor(item: unknown, index: number, retryCount: number, originalError: Error);
+}
+declare class QueueAbortError extends Error {
+    constructor(message?: string);
+}
+
+declare const delay: (ms: number) => Promise<void>;
+declare const yieldToEventLoop: () => Promise<void>;
+declare const calculateRetryDelay: (baseDelay: number, backoff: number, attemptNumber: number) => number;
+
+declare const withTimeout: <T>(promise: Promise<T>, ms: number, item: unknown, index: number) => Promise<T>;
+
+export { AsyncFlexLoop, type AsyncFlexLoopOptions, MaxRetryError, QueueAbortError, type QueueItem, QueueState, type QueueStats, type TaskResult, TimeoutError, calculateRetryDelay, delay, withTimeout, yieldToEventLoop };