@chainlink/external-adapter-framework 2.11.0 → 2.11.1

package/generator-adapter/node_modules/p-queue/dist/index.js

@@ -1,16 +1,19 @@
 import { EventEmitter } from 'eventemitter3';
-import pTimeout, { TimeoutError } from 'p-timeout';
+import pTimeout from 'p-timeout';
 import PriorityQueue from './priority-queue.js';
 /**
 Promise queue with concurrency control.
 */
 export default class PQueue extends EventEmitter {
-    #carryoverConcurrencyCount;
+    #carryoverIntervalCount;
     #isIntervalIgnored;
     #intervalCount = 0;
     #intervalCap;
+    #rateLimitedInInterval = false;
+    #rateLimitFlushScheduled = false;
     #interval;
     #intervalEnd = 0;
+    #lastExecutionTime = 0;
     #intervalId;
     #timeoutId;
     #queue;
@@ -19,19 +22,31 @@ export default class PQueue extends EventEmitter {
     // The `!` is needed because of https://github.com/microsoft/TypeScript/issues/32194
     #concurrency;
     #isPaused;
-    #throwOnTimeout;
+    // Use to assign a unique identifier to a promise function, if not explicitly specified
+    #idAssigner = 1n;
+    // Track currently running tasks for debugging
+    #runningTasks = new Map();
     /**
-    Per-operation timeout in milliseconds. Operations fulfill once `timeout` elapses if they haven't already.
+    Get or set the default timeout for all tasks. Can be changed at runtime.
 
-    Applies to each future operation.
+    Operations will throw a `TimeoutError` if they don't complete within the specified time.
+
+    The timeout begins when the operation is dequeued and starts execution, not while it's waiting in the queue.
+
+    @example
+    ```
+    const queue = new PQueue({timeout: 5000});
+
+    // Change timeout for all future tasks
+    queue.timeout = 10000;
+    ```
     */
     timeout;
-    // TODO: The `throwOnTimeout` option should affect the return types of `add()` and `addAll()`
     constructor(options) {
         super();
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
         options = {
-            carryoverConcurrencyCount: false,
+            carryoverIntervalCount: false,
             intervalCap: Number.POSITIVE_INFINITY,
             interval: 0,
             concurrency: Number.POSITIVE_INFINITY,
@@ -45,16 +60,21 @@ export default class PQueue extends EventEmitter {
         if (options.interval === undefined || !(Number.isFinite(options.interval) && options.interval >= 0)) {
             throw new TypeError(`Expected \`interval\` to be a finite number >= 0, got \`${options.interval?.toString() ?? ''}\` (${typeof options.interval})`);
         }
-        this.#carryoverConcurrencyCount = options.carryoverConcurrencyCount;
+        // TODO: Remove this fallback in the next major version
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        this.#carryoverIntervalCount = options.carryoverIntervalCount ?? options.carryoverConcurrencyCount ?? false;
         this.#isIntervalIgnored = options.intervalCap === Number.POSITIVE_INFINITY || options.interval === 0;
         this.#intervalCap = options.intervalCap;
         this.#interval = options.interval;
         this.#queue = new options.queueClass();
         this.#queueClass = options.queueClass;
         this.concurrency = options.concurrency;
+        if (options.timeout !== undefined && !(Number.isFinite(options.timeout) && options.timeout > 0)) {
+            throw new TypeError(`Expected \`timeout\` to be a positive finite number, got \`${options.timeout}\` (${typeof options.timeout})`);
+        }
         this.timeout = options.timeout;
-        this.#throwOnTimeout = options.throwOnTimeout === true;
         this.#isPaused = options.autoStart === false;
+        this.#setupRateLimitTracking();
     }
     get #doesIntervalAllowAnother() {
         return this.#isIntervalIgnored || this.#intervalCount < this.#intervalCap;
@@ -64,11 +84,14 @@ export default class PQueue extends EventEmitter {
     }
     #next() {
         this.#pending--;
+        if (this.#pending === 0) {
+            this.emit('pendingZero');
+        }
         this.#tryToStartAnother();
         this.emit('next');
     }
     #onResumeInterval() {
-        this.#onInterval();
+        this.#onInterval(); // Already schedules update
         this.#initializeIntervalIfNeeded();
         this.#timeoutId = undefined;
     }
@@ -77,52 +100,81 @@ export default class PQueue extends EventEmitter {
         if (this.#intervalId === undefined) {
             const delay = this.#intervalEnd - now;
             if (delay < 0) {
-                // Act as the interval was done
-                // We don't need to resume it here because it will be resumed on line 160
-                this.#intervalCount = (this.#carryoverConcurrencyCount) ? this.#pending : 0;
+                // If the interval has expired while idle, check if we should enforce the interval
+                // from the last task execution. This ensures proper spacing between tasks even
+                // when the queue becomes empty and then new tasks are added.
+                if (this.#lastExecutionTime > 0) {
+                    const timeSinceLastExecution = now - this.#lastExecutionTime;
+                    if (timeSinceLastExecution < this.#interval) {
+                        // Not enough time has passed since the last task execution
+                        this.#createIntervalTimeout(this.#interval - timeSinceLastExecution);
+                        return true;
+                    }
+                }
+                // Enough time has passed or no previous execution, allow execution
+                this.#intervalCount = (this.#carryoverIntervalCount) ? this.#pending : 0;
             }
             else {
                 // Act as the interval is pending
-                if (this.#timeoutId === undefined) {
-                    this.#timeoutId = setTimeout(() => {
-                        this.#onResumeInterval();
-                    }, delay);
-                }
+                this.#createIntervalTimeout(delay);
                 return true;
             }
         }
         return false;
     }
+    #createIntervalTimeout(delay) {
+        if (this.#timeoutId !== undefined) {
+            return;
+        }
+        this.#timeoutId = setTimeout(() => {
+            this.#onResumeInterval();
+        }, delay);
+    }
+    #clearIntervalTimer() {
+        if (this.#intervalId) {
+            clearInterval(this.#intervalId);
+            this.#intervalId = undefined;
+        }
+    }
+    #clearTimeoutTimer() {
+        if (this.#timeoutId) {
+            clearTimeout(this.#timeoutId);
+            this.#timeoutId = undefined;
+        }
+    }
     #tryToStartAnother() {
         if (this.#queue.size === 0) {
             // We can clear the interval ("pause")
             // Because we can redo it later ("resume")
-            if (this.#intervalId) {
-                clearInterval(this.#intervalId);
-            }
-            this.#intervalId = undefined;
+            this.#clearIntervalTimer();
             this.emit('empty');
             if (this.#pending === 0) {
+                // Clear timeout as well when completely idle
+                this.#clearTimeoutTimer();
                 this.emit('idle');
             }
             return false;
         }
+        let taskStarted = false;
         if (!this.#isPaused) {
             const canInitializeInterval = !this.#isIntervalPaused;
             if (this.#doesIntervalAllowAnother && this.#doesConcurrentAllowAnother) {
                 const job = this.#queue.dequeue();
-                if (!job) {
-                    return false;
+                // Increment interval count immediately to prevent race conditions
+                if (!this.#isIntervalIgnored) {
+                    this.#intervalCount++;
+                    this.#scheduleRateLimitUpdate();
                 }
                 this.emit('active');
+                this.#lastExecutionTime = Date.now();
                 job();
                 if (canInitializeInterval) {
                     this.#initializeIntervalIfNeeded();
                 }
-                return true;
+                taskStarted = true;
             }
         }
-        return false;
+        return taskStarted;
     }
     #initializeIntervalIfNeeded() {
         if (this.#isIntervalIgnored || this.#intervalId !== undefined) {
@@ -135,11 +187,11 @@ export default class PQueue extends EventEmitter {
     }
     #onInterval() {
         if (this.#intervalCount === 0 && this.#pending === 0 && this.#intervalId) {
-            clearInterval(this.#intervalId);
-            this.#intervalId = undefined;
+            this.#clearIntervalTimer();
         }
-        this.#intervalCount = this.#carryoverConcurrencyCount ? this.#pending : 0;
+        this.#intervalCount = this.#carryoverIntervalCount ? this.#pending : 0;
         this.#processQueue();
+        this.#scheduleRateLimitUpdate();
     }
     /**
     Executes all queued functions until it reaches the limit.
@@ -158,46 +210,118 @@ export default class PQueue extends EventEmitter {
         this.#concurrency = newConcurrency;
         this.#processQueue();
     }
-    async #throwOnAbort(signal) {
-        return new Promise((_resolve, reject) => {
-            signal.addEventListener('abort', () => {
-                reject(signal.reason);
-            }, { once: true });
-        });
+    /**
+    Updates the priority of a promise function by its id, affecting its execution order. Requires a defined concurrency limit to take effect.
+
+    For example, this can be used to prioritize a promise function to run earlier.
+
+    ```js
+    import PQueue from 'p-queue';
+
+    const queue = new PQueue({concurrency: 1});
+
+    queue.add(async () => '🦄', {priority: 1});
+    queue.add(async () => '🦀', {priority: 0, id: '🦀'});
+    queue.add(async () => '🦄', {priority: 1});
+    queue.add(async () => '🦄', {priority: 1});
+
+    queue.setPriority('🦀', 2);
+    ```
+
+    In this case, the promise function with `id: '🦀'` runs second.
+
+    You can also deprioritize a promise function to delay its execution:
+
+    ```js
+    import PQueue from 'p-queue';
+
+    const queue = new PQueue({concurrency: 1});
+
+    queue.add(async () => '🦄', {priority: 1});
+    queue.add(async () => '🦀', {priority: 1, id: '🦀'});
+    queue.add(async () => '🦄');
+    queue.add(async () => '🦄', {priority: 0});
+
+    queue.setPriority('🦀', -1);
+    ```
+    Here, the promise function with `id: '🦀'` executes last.
+    */
+    setPriority(id, priority) {
+        if (typeof priority !== 'number' || !Number.isFinite(priority)) {
+            throw new TypeError(`Expected \`priority\` to be a finite number, got \`${priority}\` (${typeof priority})`);
+        }
+        this.#queue.setPriority(id, priority);
     }
     async add(function_, options = {}) {
+        // In case `id` is not defined.
+        options.id ??= (this.#idAssigner++).toString();
         options = {
             timeout: this.timeout,
-            throwOnTimeout: this.#throwOnTimeout,
             ...options,
         };
         return new Promise((resolve, reject) => {
+            // Create a unique symbol for tracking this task
+            const taskSymbol = Symbol(`task-${options.id}`);
             this.#queue.enqueue(async () => {
                 this.#pending++;
-                this.#intervalCount++;
+                // Track this running task
+                this.#runningTasks.set(taskSymbol, {
+                    id: options.id,
+                    priority: options.priority ?? 0, // Match priority-queue default
+                    startTime: Date.now(),
+                    timeout: options.timeout,
+                });
+                let eventListener;
                 try {
-                    options.signal?.throwIfAborted();
+                    // Check abort signal - if aborted, need to decrement the counter
+                    // that was incremented in tryToStartAnother
+                    try {
+                        options.signal?.throwIfAborted();
+                    }
+                    catch (error) {
+                        // Decrement the counter that was already incremented
+                        if (!this.#isIntervalIgnored) {
+                            this.#intervalCount--;
+                        }
+                        // Clean up tracking before throwing
+                        this.#runningTasks.delete(taskSymbol);
+                        throw error;
+                    }
                     let operation = function_({ signal: options.signal });
                     if (options.timeout) {
-                        operation = pTimeout(Promise.resolve(operation), { milliseconds: options.timeout });
+                        operation = pTimeout(Promise.resolve(operation), {
+                            milliseconds: options.timeout,
+                            message: `Task timed out after ${options.timeout}ms (queue has ${this.#pending} running, ${this.#queue.size} waiting)`,
+                        });
                     }
                     if (options.signal) {
-                        operation = Promise.race([operation, this.#throwOnAbort(options.signal)]);
+                        const { signal } = options;
+                        operation = Promise.race([operation, new Promise((_resolve, reject) => {
+                                eventListener = () => {
+                                    reject(signal.reason);
+                                };
+                                signal.addEventListener('abort', eventListener, { once: true });
+                            })]);
                     }
                     const result = await operation;
                     resolve(result);
                     this.emit('completed', result);
                 }
                 catch (error) {
-                    if (error instanceof TimeoutError && !options.throwOnTimeout) {
-                        resolve();
-                        return;
-                    }
                     reject(error);
                     this.emit('error', error);
                 }
                 finally {
-                    this.#next();
+                    // Clean up abort event listener
+                    if (eventListener) {
+                        options.signal?.removeEventListener('abort', eventListener);
+                    }
+                    // Remove from running tasks
+                    this.#runningTasks.delete(taskSymbol);
+                    // Use queueMicrotask to prevent deep recursion while maintaining timing
+                    queueMicrotask(() => {
+                        this.#next();
+                    });
                 }
             }, options);
             this.emit('add');
@@ -229,6 +353,10 @@ export default class PQueue extends EventEmitter {
     */
     clear() {
         this.#queue = new this.#queueClass();
+        // Note: We don't clear #runningTasks as those tasks are still running
+        // They will be removed when they complete in the finally block
+        // Force synchronous update since clear() should have immediate effect
+        this.#updateRateLimitState();
     }
     /**
     Can be called multiple times. Useful if you for example add additional items at a later time.
@@ -268,6 +396,74 @@ export default class PQueue extends EventEmitter {
         }
         await this.#onEvent('idle');
     }
+    /**
+    The difference with `.onIdle` is that `.onPendingZero` only waits for currently running tasks to finish, ignoring queued tasks.
+
+    @returns A promise that settles when all currently running tasks have completed; `queue.pending === 0`.
+    */
+    async onPendingZero() {
+        if (this.#pending === 0) {
+            return;
+        }
+        await this.#onEvent('pendingZero');
+    }
+    /**
+    @returns A promise that settles when the queue becomes rate-limited due to intervalCap.
+    */
+    async onRateLimit() {
+        if (this.isRateLimited) {
+            return;
+        }
+        await this.#onEvent('rateLimit');
+    }
+    /**
+    @returns A promise that settles when the queue is no longer rate-limited.
+    */
+    async onRateLimitCleared() {
+        if (!this.isRateLimited) {
+            return;
+        }
+        await this.#onEvent('rateLimitCleared');
+    }
+    /**
+    @returns A promise that rejects when any task in the queue errors.
+
+    Use with `Promise.race([queue.onError(), queue.onIdle()])` to fail fast on the first error while still resolving normally when the queue goes idle.
+
+    Important: The promise returned by `add()` still rejects. You must handle each `add()` promise (for example, `.catch(() => {})`) to avoid unhandled rejections.
+
+    @example
+    ```
+    import PQueue from 'p-queue';
+
+    const queue = new PQueue({concurrency: 2});
+
+    queue.add(() => fetchData(1)).catch(() => {});
+    queue.add(() => fetchData(2)).catch(() => {});
+    queue.add(() => fetchData(3)).catch(() => {});
+
+    // Stop processing on first error
+    try {
+        await Promise.race([
+            queue.onError(),
+            queue.onIdle()
+        ]);
+    } catch (error) {
+        queue.pause(); // Stop processing remaining tasks
+        console.error('Queue failed:', error);
+    }
+    ```
+    */
+    // eslint-disable-next-line @typescript-eslint/promise-function-async
+    async onError() {
+        return new Promise((_resolve, reject) => {
+            const handleError = (error) => {
+                this.off('error', handleError);
+                reject(error);
+            };
+            this.on('error', handleError);
+        });
+    }
     async #onEvent(event, filter) {
         return new Promise(resolve => {
             const listener = () => {
@@ -307,4 +503,129 @@ export default class PQueue extends EventEmitter {
     get isPaused() {
         return this.#isPaused;
     }
+    #setupRateLimitTracking() {
+        // Only schedule updates when rate limiting is enabled
+        if (this.#isIntervalIgnored) {
+            return;
+        }
+        // Wire up to lifecycle events that affect rate limit state
+        // Only 'add' and 'next' can actually change rate limit state
+        this.on('add', () => {
+            if (this.#queue.size > 0) {
+                this.#scheduleRateLimitUpdate();
+            }
+        });
+        this.on('next', () => {
+            this.#scheduleRateLimitUpdate();
+        });
+    }
+    #scheduleRateLimitUpdate() {
+        // Skip if rate limiting is not enabled or already scheduled
+        if (this.#isIntervalIgnored || this.#rateLimitFlushScheduled) {
+            return;
+        }
+        this.#rateLimitFlushScheduled = true;
+        queueMicrotask(() => {
+            this.#rateLimitFlushScheduled = false;
+            this.#updateRateLimitState();
+        });
+    }
+    #updateRateLimitState() {
+        const previous = this.#rateLimitedInInterval;
+        const shouldBeRateLimited = !this.#isIntervalIgnored
+            && this.#intervalCount >= this.#intervalCap
+            && this.#queue.size > 0;
+        if (shouldBeRateLimited !== previous) {
+            this.#rateLimitedInInterval = shouldBeRateLimited;
+            this.emit(shouldBeRateLimited ? 'rateLimit' : 'rateLimitCleared');
+        }
+    }
+    /**
+    Whether the queue is currently rate-limited due to intervalCap.
+    */
+    get isRateLimited() {
+        return this.#rateLimitedInInterval;
+    }
+    /**
+    Whether the queue is saturated. Returns `true` when:
+    - All concurrency slots are occupied and tasks are waiting, OR
+    - The queue is rate-limited and tasks are waiting
+
+    Useful for detecting backpressure and potential hanging tasks.
+
+    ```js
+    import PQueue from 'p-queue';
+
+    const queue = new PQueue({concurrency: 2});
+
+    // Backpressure handling
+    if (queue.isSaturated) {
+        console.log('Queue is saturated, waiting for capacity...');
+        await queue.onSizeLessThan(queue.concurrency);
+    }
+
+    // Monitoring for stuck tasks
+    setInterval(() => {
+        if (queue.isSaturated) {
+            console.warn(`Queue saturated: ${queue.pending} running, ${queue.size} waiting`);
+        }
+    }, 60000);
+    ```
+    */
+    get isSaturated() {
+        return (this.#pending === this.#concurrency && this.#queue.size > 0)
+            || (this.isRateLimited && this.#queue.size > 0);
+    }
+    /**
+    The tasks currently being executed. Each task includes its `id`, `priority`, `startTime`, and `timeout` (if set).
+
+    Returns an array of task info objects.
+
+    ```js
+    import PQueue from 'p-queue';
+
+    const queue = new PQueue({concurrency: 2});
+
+    // Add tasks with IDs for better debugging
+    queue.add(() => fetchUser(123), {id: 'user-123'});
+    queue.add(() => fetchPosts(456), {id: 'posts-456', priority: 1});
+
+    // Check what's running
+    console.log(queue.runningTasks);
+    // => [{
+    //   id: 'user-123',
+    //   priority: 0,
+    //   startTime: 1759253001716,
+    //   timeout: undefined
+    // }, {
+    //   id: 'posts-456',
+    //   priority: 1,
+    //   startTime: 1759253001916,
+    //   timeout: undefined
+    // }]
+    ```
+    */
+    get runningTasks() {
+        // Return fresh array with fresh objects to prevent mutations
+        return [...this.#runningTasks.values()].map(task => ({ ...task }));
+    }
 }
+/**
+Error thrown when a task times out.
+
+@example
+```
+import PQueue, {TimeoutError} from 'p-queue';
+
+const queue = new PQueue({timeout: 1000});
+
+try {
+    await queue.add(() => someTask());
+} catch (error) {
+    if (error instanceof TimeoutError) {
+        console.log('Task timed out');
+    }
+}
+```
+*/
+export { TimeoutError } from 'p-timeout';

package/generator-adapter/node_modules/p-queue/dist/options copy.d.ts

@@ -0,0 +1,121 @@
+import { type Queue, type RunFunction } from './queue.js';
+type TimeoutOptions = {
+    /**
+    Per-operation timeout in milliseconds. Operations will throw a `TimeoutError` if they don't complete within the specified time.
+
+    The timeout begins when the operation is dequeued and starts execution, not while it's waiting in the queue.
+
+    @default undefined
+
+    Can be overridden per task using the `timeout` option in `.add()`:
+
+    @example
+    ```
+    const queue = new PQueue({timeout: 5000});
+
+    // This task uses the global 5s timeout
+    await queue.add(() => fetchData());
+
+    // This task has a 10s timeout
+    await queue.add(() => slowTask(), {timeout: 10000});
+    ```
+    */
+    timeout?: number;
+};
+export type Options<QueueType extends Queue<RunFunction, QueueOptions>, QueueOptions extends QueueAddOptions> = {
+    /**
+    Concurrency limit.
+
+    Minimum: `1`.
+
+    @default Infinity
+    */
+    readonly concurrency?: number;
+    /**
+    Whether queue tasks within concurrency limit, are auto-executed as soon as they're added.
+
+    @default true
+    */
+    readonly autoStart?: boolean;
+    /**
+    Class with a `enqueue` and `dequeue` method, and a `size` getter. See the [Custom QueueClass](https://github.com/sindresorhus/p-queue#custom-queueclass) section.
+    */
+    readonly queueClass?: new () => QueueType;
+    /**
+    The max number of runs in the given interval of time.
+
+    Minimum: `1`.
+
+    @default Infinity
+    */
+    readonly intervalCap?: number;
+    /**
+    The length of time in milliseconds before the interval count resets. Must be finite.
+
+    Minimum: `0`.
+
+    @default 0
+    */
+    readonly interval?: number;
+    /**
+    Whether the task must finish in the given interval or will be carried over into the next interval count.
+
+    @default false
+    */
+    readonly carryoverIntervalCount?: boolean;
+    /**
+    @deprecated Renamed to `carryoverIntervalCount`.
+    */
+    readonly carryoverConcurrencyCount?: boolean;
+} & TimeoutOptions;
+export type QueueAddOptions = {
+    /**
+    Priority of operation. Operations with greater priority will be scheduled first.
+
+    @default 0
+    */
+    readonly priority?: number;
+    /**
+    Unique identifier for the promise function, used to update its priority before execution. If not specified, it is auto-assigned an incrementing BigInt starting from `1n`.
+    */
+    id?: string;
+} & TaskOptions & TimeoutOptions;
+export type TaskOptions = {
+    /**
+    [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for cancellation of the operation. When aborted, it will be removed from the queue and the `queue.add()` call will reject with an `AbortError`. If the operation is already running, the signal will need to be handled by the operation itself.
+
+    @example
+    ```
+    import PQueue, {AbortError} from 'p-queue';
+    import got, {CancelError} from 'got';
+
+    const queue = new PQueue();
+
+    const controller = new AbortController();
+
+    try {
+        await queue.add(({signal}) => {
+            const request = got('https://sindresorhus.com');
+
+            signal.addEventListener('abort', () => {
+                request.cancel();
+            });
+
+            try {
+                return await request;
+            } catch (error) {
+                if (!(error instanceof CancelError)) {
+                    throw error;
+                }
+            }
+        }, {signal: controller.signal});
+    } catch (error) {
+        if (!(error instanceof AbortError)) {
+            throw error;
+        }
+    }
+    ```
+    */
+    readonly signal?: AbortSignal;
+};
+export {};

package/generator-adapter/node_modules/p-queue/dist/options copy.js

@@ -0,0 +1 @@
+export {};