dynamic-throttled-queue 2.3.0-rc.e78fc2f → 3.0.0-rc.1d87d99

package/dist/pending-work.js

@@ -2,6 +2,8 @@ export function createPendingWork(options, host) {
     const { capacity, compactThreshold } = options;
     const queue = [];
     let head = 0;
+    /** Queued items that were removed but still sit between `head` and the tail; `take` skips them. */
+    const removed = new Set();
     const held = [];
     let frozen = false;
     let active = 0;
@@ -9,7 +11,7 @@ export function createPendingWork(options, host) {
     let deciding = 0;
     const idleWaiters = [];
     function queued() {
-        return queue.length - head;
+        return queue.length - head - removed.size;
     }
     function pending() {
         return queued() + held.length;
@@ -44,6 +46,17 @@ export function createPendingWork(options, host) {
         held.length = 0;
         queue.length = 0;
         head = 0;
+        removed.clear();
+    }
+    function compact() {
+        if (head === queue.length) {
+            queue.length = 0;
+            head = 0;
+        }
+        else if (head > compactThreshold && head > queue.length / 2) {
+            queue.splice(0, head);
+            head = 0;
+        }
     }
     return {
         get queued() {
@@ -61,19 +74,24 @@ export function createPendingWork(options, host) {
             queue.push(item);
         },
         take() {
-            if (head === queue.length)
-                return undefined;
-            const item = queue[head++];
-            active++;
-            if (head === queue.length) {
-                queue.length = 0;
-                head = 0;
-            }
-            else if (head > compactThreshold && head > queue.length / 2) {
-                queue.splice(0, head);
-                head = 0;
+            while (head < queue.length) {
+                const item = queue[head++];
+                if (removed.delete(item))
+                    continue;
+                active++;
+                compact();
+                return item;
             }
-            return item;
+            compact();
+            return undefined;
+        },
+        remove(item) {
+            const index = held.findIndex(retry => retry.item === item);
+            if (index === -1)
+                removed.add(item);
+            else
+                clearTimeout(held.splice(index, 1)[0].timeout);
+            notifyIdle();
         },
         settle(decide, observe) {
             active--;

package/dist/pending-work.js.map

@@ -1 +1 @@
-{"version":3,"file":"pending-work.js","sourceRoot":"","sources":["../src/pending-work.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pending-work.js","sourceRoot":"","sources":["../src/pending-work.ts"],"names":[],"mappings":"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"}

package/dist/retry-policy.d.ts

@@ -0,0 +1,25 @@
+import type { FailureOutcome } from "./adaptive-rate.js";
+export type RetryBackoff = {
+    strategy: "fixed" | "linear" | "exponential";
+    baseDelay: number;
+    maxDelay?: number;
+    jitter?: number;
+    random?: () => number;
+};
+export type RetryClassifier = (outcome: FailureOutcome, attempt: number) => boolean;
+export type RetryPolicyOptions = {
+    retry?: number;
+    retryBackoff?: RetryBackoff;
+    retryClassifier?: RetryClassifier;
+};
+/** How a failed attempt continues: `{}` retries now, `{ delay }` retries after `delay` ms. */
+type RetryDecision = Readonly<{
+    delay?: number;
+}>;
+export type RetryPolicy = {
+    /** Decides whether failed attempt `attempt` (one-based) gets another attempt. `undefined` drops it. */
+    decide: (outcome: FailureOutcome, attempt: number) => RetryDecision | undefined;
+};
+/** Validates the retry options, then decides each failed attempt: drop, retry now, or retry after a delay. */
+export declare function createRetryPolicy({ retry, retryBackoff, retryClassifier }: RetryPolicyOptions): RetryPolicy;
+export {};

package/dist/retry-policy.js

@@ -0,0 +1,73 @@
+const strategies = { fixed: true, linear: true, exponential: true };
+const retryNow = Object.freeze({});
+function validate(retry, retryBackoff) {
+    if (!Number.isInteger(retry) || retry < 0) {
+        throw new Error("retry must be a non-negative integer");
+    }
+    if (retryBackoff === undefined)
+        return;
+    if (!Object.hasOwn(strategies, retryBackoff.strategy)) {
+        throw new Error("retryBackoff.strategy must be fixed, linear, or exponential");
+    }
+    if (!Number.isFinite(retryBackoff.baseDelay) || retryBackoff.baseDelay < 0) {
+        throw new Error("retryBackoff.baseDelay must be a finite non-negative number");
+    }
+    if (retryBackoff.maxDelay !== undefined && (!Number.isFinite(retryBackoff.maxDelay) || retryBackoff.maxDelay < 0)) {
+        throw new Error("retryBackoff.maxDelay must be a finite non-negative number");
+    }
+    if (retryBackoff.jitter !== undefined && (!Number.isFinite(retryBackoff.jitter) || retryBackoff.jitter < 0 || retryBackoff.jitter > 1)) {
+        throw new Error("retryBackoff.jitter must be a finite number from 0 through 1");
+    }
+}
+function readRandom(random) {
+    try {
+        // eslint-disable-next-line sonarjs/pseudo-random -- Default jitter requires a random source.
+        const value = random?.() ?? Math.random();
+        return Number.isFinite(value) && value >= 0 && value <= 1 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function calculateRetryDelay(policy, retryIndex) {
+    let delay;
+    switch (policy.strategy) {
+        case "linear":
+            delay = policy.baseDelay * retryIndex;
+            break;
+        case "exponential":
+            delay = policy.baseDelay * 2 ** (retryIndex - 1);
+            break;
+        default: delay = policy.baseDelay;
+    }
+    const cappedDelay = policy.maxDelay === undefined ? delay : Math.min(delay, policy.maxDelay);
+    if (policy.jitter === undefined)
+        return cappedDelay;
+    const random = readRandom(policy.random);
+    if (random === undefined)
+        return cappedDelay;
+    const jitteredDelay = cappedDelay * (1 + (random * 2 - 1) * policy.jitter);
+    return policy.maxDelay === undefined ? jitteredDelay : Math.min(jitteredDelay, policy.maxDelay);
+}
+/** Validates the retry options, then decides each failed attempt: drop, retry now, or retry after a delay. */
+export function createRetryPolicy({ retry = 0, retryBackoff, retryClassifier }) {
+    validate(retry, retryBackoff);
+    function isRetryable(outcome, attempt) {
+        if (!retryClassifier)
+            return true;
+        try {
+            return retryClassifier(outcome, attempt) === true;
+        }
+        catch {
+            return true;
+        }
+    }
+    return {
+        decide(outcome, attempt) {
+            if (attempt > retry || !isRetryable(outcome, attempt))
+                return undefined;
+            return retryBackoff === undefined ? retryNow : { delay: calculateRetryDelay(retryBackoff, attempt) };
+        },
+    };
+}
+//# sourceMappingURL=retry-policy.js.map

package/dist/retry-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.js","sourceRoot":"","sources":["../src/retry-policy.ts"],"names":[],"mappings":"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"}

package/dist/scheduler.d.ts

@@ -1,3 +1,62 @@
 import type { AdaptiveRateOptions } from "./adaptive-rate.js";
-import type { ThrottleHandle, ThrottleOptions } from "./dynamic-throttled-queue.js";
-export declare function createScheduler(options: ThrottleOptions, adaptiveRateOptions: AdaptiveRateOptions): ThrottleHandle;
+import type { PendingWorkOptions } from "./pending-work.js";
+import type { RetryPolicy } from "./retry-policy.js";
+export type ExecutionContext = Readonly<{
+    signal: AbortSignal;
+    /** One-based attempt number; retries of the same item count up from 1. */
+    attempt: number;
+}>;
+/** Return `false` to signal failure (counts as an error, retries if configured). Any other value is success. */
+export type ThrottleCallback = (context: ExecutionContext) => unknown;
+export type ThrottleFn = (callback: ThrottleCallback) => void;
+/** Submitted work. Every returned value, including `false`, is a result; only a throw or rejection fails. */
+export type TaskCallback<T> = (context: ExecutionContext) => T | Promise<T>;
+/** One accepted logical item across all of its attempts. */
+export type TaskHandle<T> = Readonly<{
+    /** Settles once: the final value, the final failure, or the cancellation reason. */
+    result: Promise<T>;
+    /**
+     * Rejects `result` with `reason` (an `AbortError` by default) unless it already settled. A pending
+     * item is removed; an active one has its signal aborted and is never retried. Repeat calls do nothing.
+     */
+    cancel: (reason?: unknown) => void;
+}>;
+export type QueueLifecycleState = "running" | "paused" | "stopped" | "aborted" | "failed";
+export type QueueState = Readonly<{
+    rate: number;
+    pending: number;
+    active: number;
+    state: QueueLifecycleState;
+    started: number;
+    succeeded: number;
+    failed: number;
+    retried: number;
+    /** Submitted items whose result was rejected by `cancel()`. */
+    canceled: number;
+    rateIncreases: number;
+    rateDecreases: number;
+    /** Milliseconds, rounded up, until a server-directed cooldown ends; `0` when none is active. */
+    cooldownRemaining: number;
+    /** `cooldownFor()` calls that moved the cooldown deadline later. */
+    cooldowns: number;
+    /** Total milliseconds those calls added to the cooldown deadline. */
+    cooldownTotal: number;
+}>;
+export type ThrottleHandle = ThrottleFn & {
+    submit: <T>(callback: TaskCallback<T>) => TaskHandle<T>;
+    pause: () => void;
+    resume: () => void;
+    stop: () => void;
+    abort: () => void;
+    /** Starts nothing new for `delay` ms (capped at `maxCooldown`); never shortens an active cooldown. */
+    cooldownFor: (delay: number) => void;
+    waitForIdle: () => Promise<void>;
+    getState: () => QueueState;
+};
+export type SchedulerOptions = PendingWorkOptions & {
+    /** Most callbacks awaiting asynchronous settlement at once. */
+    concurrency: number;
+    /** Longest cooldown, in ms, that `cooldownFor()` applies; longer requests are clamped to it. */
+    maxCooldown: number;
+};
+export declare function createScheduler(options: SchedulerOptions, adaptiveRateOptions: AdaptiveRateOptions, retryPolicy: RetryPolicy): ThrottleHandle;

package/dist/scheduler.js

@@ -1,6 +1,6 @@
 import { createAdaptiveRate } from "./adaptive-rate.js";
 import { createPendingWork } from "./pending-work.js";
-import { calculateRetryDelay } from "./retry-backoff.js";
+const returnedFalse = Object.freeze({ kind: "returned-false" });
 /** The state each event leads to. An event missing from the current state's row is a no-op. */
 const lifecycleTransitions = {
     running: { pause: "paused", stop: "stopped", abort: "aborted", fail: "failed" },
@@ -9,40 +9,40 @@ const lifecycleTransitions = {
     aborted: {},
     failed: {},
 };
-export function createScheduler(options, adaptiveRateOptions) {
-    const { interval, evenly_spaced = true, retry = 0, retryBackoff, concurrency, maxQueueSize, compact_threshold = 512, retryClassifier, } = options;
-    let last_called = 0;
-    let timeout;
+export function createScheduler(options, adaptiveRateOptions, retryPolicy) {
+    const { concurrency, maxCooldown, ...pendingWorkOptions } = options;
     let lifecycle = { state: "running" };
     let cnt_started = 0;
     let cnt_succeeded = 0;
     let cnt_failed = 0;
     let cnt_retried = 0;
+    let cnt_canceled = 0;
+    let cnt_cooldowns = 0;
+    let cooldownTotal = 0;
+    /** Monotonic (`performance.now()`) time before which nothing starts; `undefined` when no cooldown is active. */
+    let cooldownDeadline;
+    /** Fires at the deadline. Cleared while stopped, which keeps the deadline for the restart. */
+    let cooldownTimer;
     const abortController = new AbortController();
-    const max_concurrency = concurrency ?? Infinity;
-    const work = createPendingWork({ capacity: maxQueueSize ?? Infinity, compactThreshold: compact_threshold }, { retryQueued: start });
+    /** Submitted items whose result has not settled. */
+    const tasks = new Set();
+    const work = createPendingWork(pendingWorkOptions, { retryQueued: start });
     const adaptiveRate = createAdaptiveRate(adaptiveRateOptions, {
         hasPendingWork: () => work.queued > 0,
-        resumeStarts() {
-            last_called = Date.now();
-            clearTimeout(timeout);
-            timeout = setTimeout(dequeue, spacing());
-        },
-        holdStarts(deferBy) {
-            clearTimeout(timeout);
-            timeout = deferBy === undefined ? undefined : setTimeout(dequeue, spacing() + deferBy);
-        },
-        idle() {
-            clearTimeout(timeout);
-            timeout = undefined;
+        startsDue(limit) {
+            const batch = Math.min(limit, work.queued);
+            for (let started = 0; started < batch && work.active < concurrency && cooldownDeadline === undefined; started++) {
+                const item = work.take();
+                if (item === undefined)
+                    break;
+                execute(item);
+            }
+            return work.active < concurrency;
         },
         failed(error) {
             transition("fail", error);
         },
     });
-    function spacing() {
-        return evenly_spaced ? interval / adaptiveRate.rate : interval;
-    }
     /** Moves the lifecycle for `event` and runs the cleanup that entering the new state requires. */
     function transition(event, error) {
         const next = lifecycleTransitions[lifecycle.state][event];
@@ -52,120 +52,205 @@ export function createScheduler(options, adaptiveRateOptions) {
         switch (next) {
             case "running":
                 work.thaw();
-                adaptiveRate.start();
+                if (cooldownDeadline === undefined) {
+                    adaptiveRate.start();
+                    return;
+                }
+                armCooldown(cooldownDeadline);
+                adaptiveRate.suspend();
                 return;
             case "paused":
+                // A cooldown keeps elapsing while paused: its deadline is the server's, not the queue's.
                 work.freeze();
                 adaptiveRate.pause();
                 return;
             case "stopped":
+                clearTimeout(cooldownTimer);
+                cooldownTimer = undefined;
                 work.freeze();
                 adaptiveRate.stop();
                 return;
             case "aborted":
+                clearCooldown();
                 adaptiveRate.stop();
                 work.discard();
                 abortController.abort();
+                rejectTasks(abortController.signal.reason);
                 return;
             case "failed":
+                clearCooldown();
                 adaptiveRate.stop();
                 work.fail(error);
+                rejectTasks(error);
         }
     }
-    function isRetryable(item, outcome) {
-        if (!outcome || item.retries === 0)
-            return false;
-        try {
-            return retryClassifier ? retryClassifier(outcome, retry - item.retries + 1) === true : true;
+    function armCooldown(deadline) {
+        clearTimeout(cooldownTimer);
+        cooldownTimer = setTimeout(expireCooldown, Math.max(0, deadline - performance.now()));
+    }
+    function expireCooldown() {
+        // A timer can fire slightly before the monotonic deadline; wait out the remainder.
+        if (cooldownDeadline !== undefined && performance.now() < cooldownDeadline) {
+            armCooldown(cooldownDeadline);
+            return;
         }
-        catch {
-            return true;
+        cooldownTimer = undefined;
+        cooldownDeadline = undefined;
+        start();
+    }
+    function clearCooldown() {
+        clearTimeout(cooldownTimer);
+        cooldownTimer = undefined;
+        cooldownDeadline = undefined;
+    }
+    /** Rejects every unsettled submitted item with `reason` and aborts its signal. */
+    function rejectTasks(reason) {
+        // Snapshot first: abort listeners run synchronously and may re-enter the queue.
+        const affected = [...tasks];
+        tasks.clear();
+        for (const task of affected) {
+            task.controller.abort(reason);
+            task.reject(reason);
         }
     }
-    function nextAttempt(item, outcome) {
-        if (!isRetryable(item, outcome))
-            return undefined;
-        cnt_retried++;
-        const retryItem = { fn: item.fn, retries: item.retries - 1 };
-        if (retryBackoff === undefined)
-            return { item: retryItem };
-        return { item: retryItem, delay: calculateRetryDelay(retryBackoff, retry - item.retries + 1) };
+    function nextAttempt(item, outcome, value) {
+        const { task } = item;
+        if (outcome) {
+            const decision = retryPolicy.decide(outcome, item.attempt);
+            if (decision && (task === undefined || tasks.has(task))) {
+                cnt_retried++;
+                item.attempt++;
+                if (task)
+                    task.active = false;
+                return { item, ...decision };
+            }
+        }
+        if (task && tasks.delete(task)) {
+            // Submitted items never return-false, so a failure always carries its error.
+            if (outcome)
+                task.reject("error" in outcome ? outcome.error : undefined);
+            else
+                task.resolve(value);
+        }
+        return undefined;
     }
-    function handleSettlement(item, outcome, reportSettlement, resume = false) {
+    function handleSettlement(item, outcome, value, reportSettlement, resume = false) {
         if (lifecycle.state === "aborted" || lifecycle.state === "failed") {
             work.settle();
             return;
         }
+        const observe = () => {
+            reportSettlement(outcome);
+            // An async settlement frees a slot; a start may be due if concurrency held one back.
+            if (resume)
+                start();
+        };
+        if (item.task && !tasks.has(item.task)) {
+            // Canceled: the attempt's outcome neither counts nor retries, but the observation window still closes.
+            outcome = undefined;
+            work.settle(undefined, observe);
+            return;
+        }
         if (outcome)
             cnt_failed++;
         else
             cnt_succeeded++;
-        work.settle(() => nextAttempt(item, outcome), () => {
-            reportSettlement(outcome);
-            if (resume && adaptiveRate.pacing === "open" && work.queued > 0)
-                dequeue();
-        });
+        work.settle(() => nextAttempt(item, outcome, value), observe);
+    }
+    /** Only fire-and-forget callbacks report failure by returning `false`. */
+    function returnedOutcome(item, value) {
+        return value === false && item.task === undefined ? returnedFalse : undefined;
     }
     function execute(item) {
         const reportSettlement = adaptiveRate.started();
         cnt_started++;
+        const { task } = item;
+        if (task)
+            task.active = true;
         let result;
         try {
-            result = item.fn({ signal: abortController.signal });
+            result = item.fn({ signal: task?.controller.signal ?? abortController.signal, attempt: item.attempt });
         }
         catch (error) {
-            handleSettlement(item, { kind: "thrown", error }, reportSettlement);
+            handleSettlement(item, { kind: "thrown", error }, undefined, reportSettlement);
             return;
         }
         if (result instanceof Promise) {
-            void result.then(value => handleSettlement(item, value === false ? { kind: "returned-false" } : undefined, reportSettlement, true), (error) => handleSettlement(item, { kind: "rejected", error }, reportSettlement, true));
+            void result.then((value) => handleSettlement(item, returnedOutcome(item, value), value, reportSettlement, true), (error) => handleSettlement(item, { kind: "rejected", error }, undefined, reportSettlement, true));
             return;
         }
-        handleSettlement(item, result === false ? { kind: "returned-false" } : undefined, reportSettlement);
-    }
-    function dequeue() {
-        const threshold = last_called + spacing();
-        const now = Date.now();
-        if (now < threshold) {
-            clearTimeout(timeout);
-            timeout = setTimeout(dequeue, threshold - now);
-            return;
-        }
-        const batch = Math.min(evenly_spaced ? 1 : adaptiveRate.rate, work.queued);
-        let started = 0;
-        while (started < batch && work.active < max_concurrency) {
-            const item = work.take();
-            if (item === undefined)
-                break;
-            if (started++ === 0)
-                last_called = Date.now();
-            execute(item);
-        }
-        if (work.queued === 0)
-            adaptiveRate.drained();
-        if (adaptiveRate.pacing !== "open" || work.active >= max_concurrency)
-            return;
-        timeout = setTimeout(dequeue, spacing());
+        handleSettlement(item, returnedOutcome(item, result), result, reportSettlement);
     }
     function start() {
-        if (lifecycle.state === "running")
+        if (lifecycle.state === "running" && cooldownDeadline === undefined)
             adaptiveRate.start();
     }
-    function enqueue(callback) {
+    /** Admits `item` or throws: the queue is terminal or every capacity reservation is taken. */
+    function accept(item) {
         if (lifecycle.state === "aborted")
             throw new Error("Cannot enqueue work after the queue has been aborted");
         if (lifecycle.state === "failed")
             throw lifecycle.error;
-        work.accept({ fn: callback, retries: retry });
+        work.accept(item);
+    }
+    /** Schedules newly accepted work. */
+    function schedule() {
         if (lifecycle.state === "stopped")
             transition("restart");
         else
             start();
     }
+    function enqueue(callback) {
+        accept({ fn: callback, attempt: 1 });
+        schedule();
+    }
+    enqueue.submit = (callback) => {
+        const { promise, resolve, reject } = Promise.withResolvers();
+        const task = { controller: new AbortController(), resolve: resolve, reject, active: false };
+        const item = { fn: callback, attempt: 1, task };
+        accept(item);
+        tasks.add(task);
+        schedule();
+        return {
+            result: promise,
+            cancel(reason) {
+                if (!tasks.delete(task))
+                    return;
+                cnt_canceled++;
+                if (!task.active)
+                    work.remove(item);
+                task.controller.abort(reason);
+                task.reject(task.controller.signal.reason);
+            },
+        };
+    };
     enqueue.pause = () => transition("pause");
     enqueue.resume = () => transition("resume");
     enqueue.stop = () => transition("stop");
     enqueue.abort = () => transition("abort");
+    enqueue.cooldownFor = (delay) => {
+        if (!Number.isFinite(delay) || delay < 0)
+            throw new RangeError("cooldownFor delay must be a finite non-negative number");
+        if (lifecycle.state === "aborted" || lifecycle.state === "failed")
+            return;
+        const now = performance.now();
+        const latest = Math.max(now, cooldownDeadline ?? now);
+        const deadline = now + Math.min(delay, maxCooldown);
+        // Hints are absolute ("not before now + delay"), so overlapping ones keep the later deadline, never add up.
+        if (deadline <= latest)
+            return;
+        const beginning = cooldownDeadline === undefined;
+        cnt_cooldowns++;
+        cooldownTotal += deadline - latest;
+        cooldownDeadline = deadline;
+        // Stopped: the restart arms the timer for whatever remains.
+        if (lifecycle.state === "stopped")
+            return;
+        armCooldown(deadline);
+        // Paused: adaptive rate is already stopped; `resume()` suspends it instead of starting it.
+        if (beginning && lifecycle.state === "running")
+            adaptiveRate.suspend();
+    };
     enqueue.waitForIdle = async () => {
         if (lifecycle.state === "failed")
             throw lifecycle.error;
@@ -180,10 +265,13 @@ export function createScheduler(options, adaptiveRateOptions) {
         succeeded: cnt_succeeded,
         failed: cnt_failed,
         retried: cnt_retried,
+        canceled: cnt_canceled,
         rateIncreases: adaptiveRate.rateIncreases,
         rateDecreases: adaptiveRate.rateDecreases,
+        cooldownRemaining: cooldownDeadline === undefined ? 0 : Math.max(0, Math.ceil(cooldownDeadline - performance.now())),
+        cooldowns: cnt_cooldowns,
+        cooldownTotal,
     });
-    Object.defineProperty(enqueue, "pending", { get: () => work.pending });
     return enqueue;
 }
 //# sourceMappingURL=scheduler.js.map