adaptive-concurrency 0.1.0

package/dist/limiter/BlockingLimiter.js

@@ -0,0 +1,111 @@
+/**
+ * Limiter that blocks the caller when the limit has been reached. The caller
+ * is blocked (via a promise) until the limiter has been released, or a timeout
+ * is reached. This limiter is commonly used in batch clients that use the
+ * limiter as a back-pressure mechanism.
+ *
+ * Because JavaScript is single-threaded, "blocking" here means awaiting a
+ * promise that resolves when a token becomes available.
+ */
+export class BlockingLimiter {
+    static MAX_TIMEOUT = 60 * 60 * 1000; // 1 hour in ms
+    static wrap(delegate, timeout) {
+        const t = timeout ?? BlockingLimiter.MAX_TIMEOUT;
+        if (t > BlockingLimiter.MAX_TIMEOUT) {
+            throw new Error(`Timeout cannot be greater than ${BlockingLimiter.MAX_TIMEOUT} ms`);
+        }
+        return new BlockingLimiter(delegate, t);
+    }
+    delegate;
+    timeout;
+    /** Queue of waiters blocked until a token is released */
+    waiters = [];
+    constructor(delegate, timeout) {
+        this.delegate = delegate;
+        this.timeout = timeout;
+    }
+    /** Returns the timeout used when blocking to acquire a permit, in ms. */
+    getTimeout() {
+        return this.timeout;
+    }
+    async acquire(context, options = {}) {
+        const requestContext = context;
+        if (options.signal?.aborted) {
+            return undefined;
+        }
+        const deadline = performance.now() + this.timeout;
+        while (true) {
+            const remaining = deadline - performance.now();
+            if (remaining <= 0) {
+                return undefined;
+            }
+            // Try to acquire a token and return immediately if successful
+            const allotment = this.delegate.acquire(requestContext);
+            if (allotment) {
+                return this.wrapAllotment(allotment);
+            }
+            // We have reached the limit so block until a token is released
+            const acquired = await this.waitForRelease(remaining, options.signal);
+            if (!acquired) {
+                return undefined;
+            }
+        }
+    }
+    waitForRelease(timeoutMs, signal) {
+        if (signal?.aborted) {
+            return Promise.resolve(false);
+        }
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (acquired) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                resolve(acquired);
+            };
+            const waiter = {
+                wake: () => settle(true),
+            };
+            this.waiters.push(waiter);
+            const timer = setTimeout(() => settle(false), timeoutMs);
+            const onAbort = () => settle(false);
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                const idx = this.waiters.indexOf(waiter);
+                if (idx !== -1) {
+                    this.waiters.splice(idx, 1);
+                }
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    wrapAllotment(delegate) {
+        return {
+            reportSuccess: () => {
+                delegate.reportSuccess();
+                this.unblock();
+            },
+            reportIgnore: () => {
+                delegate.reportIgnore();
+                this.unblock();
+            },
+            reportDropped: () => {
+                delegate.reportDropped();
+                this.unblock();
+            },
+        };
+    }
+    unblock() {
+        // Wake all waiters so they can retry acquiring
+        const waiters = this.waiters.splice(0);
+        for (const waiter of waiters) {
+            waiter.wake();
+        }
+    }
+    toString() {
+        return `BlockingLimiter [${this.delegate}]`;
+    }
+}

package/dist/limiter/DelayedRejectStrategy.d.ts

@@ -0,0 +1,32 @@
+import type { LimitAllotment } from "../LimitAllotment.js";
+import type { AllotmentUnavailableStrategy, AsyncAcquireResult, SyncAcquireResult } from "../Limiter.js";
+export interface DelayedRejectStrategyOptions<ContextT> {
+    /**
+     * Milliseconds to wait before resolving with no allotment. Return 0 to reject
+     * immediately. With `PartitionedStrategy`, usually mirror `partitionResolver`
+     * here and look up delay from your own per-partition config.
+     */
+    delayMsForContext: (context: ContextT) => number;
+    /**
+     * Maximum number of acquire attempts that may be waiting on a delay at once.
+     * When exceeded, new rejections skip the delay (immediate `undefined`).
+     */
+    maxConcurrentDelays?: number;
+}
+/**
+ * When the acquire strategy rejects, waits up to `delayMsForContext(context)`,
+ * then still returns no allotment. This adds a form of backpressure. Does not
+ * call `retry` — unlike {@link FifoBlockingRejection}, this is "delay then
+ * reject," not "wait for capacity." Compose with `PartitionedStrategy` via
+ * `Limiter.rejectionStrategy`; partition delays are not fields on `PartitionConfig`.
+ */
+export declare class DelayedRejectStrategy<ContextT> implements AllotmentUnavailableStrategy<ContextT, AsyncAcquireResult> {
+    private readonly delayMsForContext;
+    private readonly maxConcurrentDelays;
+    private concurrentDelays;
+    constructor(options: DelayedRejectStrategyOptions<ContextT>);
+    onAllotmentUnavailable(context: ContextT, _retry: (context: ContextT) => SyncAcquireResult, signal?: AbortSignal): Promise<LimitAllotment | undefined>;
+    onAllotmentReleased(): void;
+    private run;
+}
+//# sourceMappingURL=DelayedRejectStrategy.d.ts.map

package/dist/limiter/DelayedRejectStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DelayedRejectStrategy.d.ts","sourceRoot":"","sources":["../../src/limiter/DelayedRejectStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EACV,4BAA4B,EAC5B,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,4BAA4B,CAAC,QAAQ;IACpD;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,CAAC;IAEjD;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,qBAAa,qBAAqB,CAChC,QAAQ,CACR,YAAW,4BAA4B,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACrE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAgC;IAClE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,OAAO,EAAE,4BAA4B,CAAC,QAAQ,CAAC;IAS3D,sBAAsB,CACpB,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,iBAAiB,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAItC,mBAAmB,IAAI,IAAI;YAIb,GAAG;CA0BlB"}

package/dist/limiter/DelayedRejectStrategy.js

@@ -0,0 +1,60 @@
+/**
+ * When the acquire strategy rejects, waits up to `delayMsForContext(context)`,
+ * then still returns no allotment. This adds a form of backpressure. Does not
+ * call `retry` — unlike {@link FifoBlockingRejection}, this is "delay then
+ * reject," not "wait for capacity." Compose with `PartitionedStrategy` via
+ * `Limiter.rejectionStrategy`; partition delays are not fields on `PartitionConfig`.
+ */
+export class DelayedRejectStrategy {
+    delayMsForContext;
+    maxConcurrentDelays;
+    concurrentDelays = 0;
+    constructor(options) {
+        this.delayMsForContext = options.delayMsForContext;
+        const max = options.maxConcurrentDelays ?? 100;
+        if (max < 1 || !Number.isFinite(max)) {
+            throw new Error("maxConcurrentDelays must be a finite number >= 1");
+        }
+        this.maxConcurrentDelays = max;
+    }
+    onAllotmentUnavailable(context, _retry, signal) {
+        return this.run(context, signal);
+    }
+    onAllotmentReleased() {
+        // No waiters (unlike FIFO/LIFO blocking).
+    }
+    async run(context, signal) {
+        if (signal?.aborted) {
+            return undefined;
+        }
+        const ms = this.delayMsForContext(context);
+        if (ms <= 0) {
+            return undefined;
+        }
+        if (this.concurrentDelays >= this.maxConcurrentDelays) {
+            return undefined;
+        }
+        this.concurrentDelays++;
+        try {
+            await sleep(ms, signal);
+        }
+        finally {
+            this.concurrentDelays--;
+        }
+        return undefined;
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const t = setTimeout(resolve, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            resolve();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/limiter/DelayedThenBlockingRejection.d.ts

@@ -0,0 +1,19 @@
+import type { LimitAllotment } from "../LimitAllotment.js";
+import type { AllotmentUnavailableStrategy, AsyncAcquireResult, SyncAcquireResult } from "../Limiter.js";
+import type { DelayedRejectStrategy } from "./DelayedRejectStrategy.js";
+/**
+ * Composes "delay then reject" backoff with blocking behavior. On rejection:
+ * first applies delayed-reject semantics, then delegates to a blocking strategy
+ * (FIFO/LIFO) to await capacity.
+ */
+export declare class DelayedThenBlockingRejection<ContextT> implements AllotmentUnavailableStrategy<ContextT, AsyncAcquireResult> {
+    private readonly delayStrategy;
+    private readonly blockingStrategy;
+    constructor(options: {
+        delayStrategy: DelayedRejectStrategy<ContextT>;
+        blockingStrategy: AllotmentUnavailableStrategy<ContextT, AsyncAcquireResult>;
+    });
+    onAllotmentUnavailable(context: ContextT, retry: (context: ContextT) => SyncAcquireResult, signal?: AbortSignal): Promise<LimitAllotment | undefined>;
+    onAllotmentReleased(): void;
+}
+//# sourceMappingURL=DelayedThenBlockingRejection.d.ts.map

package/dist/limiter/DelayedThenBlockingRejection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DelayedThenBlockingRejection.d.ts","sourceRoot":"","sources":["../../src/limiter/DelayedThenBlockingRejection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EACV,4BAA4B,EAC5B,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExE;;;;GAIG;AACH,qBAAa,4BAA4B,CACvC,QAAQ,CACR,YAAW,4BAA4B,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACrE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAChE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAG/B;gBAEU,OAAO,EAAE;QACnB,aAAa,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAC;QAC/C,gBAAgB,EAAE,4BAA4B,CAC5C,QAAQ,EACR,kBAAkB,CACnB,CAAC;KACH;IAKK,sBAAsB,CAC1B,OAAO,EAAE,QAAQ,EACjB,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,iBAAiB,EAC/C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAYtC,mBAAmB,IAAI,IAAI;CAI5B"}

package/dist/limiter/DelayedThenBlockingRejection.js

@@ -0,0 +1,26 @@
+/**
+ * Composes "delay then reject" backoff with blocking behavior. On rejection:
+ * first applies delayed-reject semantics, then delegates to a blocking strategy
+ * (FIFO/LIFO) to await capacity.
+ */
+export class DelayedThenBlockingRejection {
+    delayStrategy;
+    blockingStrategy;
+    constructor(options) {
+        this.delayStrategy = options.delayStrategy;
+        this.blockingStrategy = options.blockingStrategy;
+    }
+    async onAllotmentUnavailable(context, retry, signal) {
+        await this.delayStrategy.onAllotmentUnavailable(context, retry, signal);
+        if (signal?.aborted) {
+            return undefined;
+        }
+        const allotment = retry(context);
+        return (allotment ??
+            this.blockingStrategy.onAllotmentUnavailable(context, retry, signal));
+    }
+    onAllotmentReleased() {
+        this.delayStrategy.onAllotmentReleased();
+        this.blockingStrategy.onAllotmentReleased();
+    }
+}

package/dist/limiter/FifoBlockingRejection.d.ts

@@ -0,0 +1,26 @@
+import type { LimitAllotment } from "../LimitAllotment.js";
+import type { AllotmentUnavailableStrategy, AsyncAcquireResult, SyncAcquireResult } from "../Limiter.js";
+/**
+ * Rejection strategy that blocks the caller in a FIFO queue when the limit
+ * has been reached, waiting for a slot to open up. This strategy favors
+ * fairness: callers are served in the order they arrived.
+ *
+ * Because JavaScript is single-threaded, "blocking" means awaiting a promise
+ * that resolves when a token becomes available.
+ */
+export declare class FifoBlockingRejection<ContextT> implements AllotmentUnavailableStrategy<ContextT, AsyncAcquireResult> {
+    private readonly timeout;
+    private readonly waiters;
+    constructor(options?: {
+        /**
+         * Maximum time in milliseconds to wait for a slot to become available.
+         * Default: 3_600_000 (1 hour).
+         */
+        timeout?: number | undefined;
+    });
+    onAllotmentUnavailable(_context: ContextT, retry: (context: ContextT) => SyncAcquireResult, signal?: AbortSignal): Promise<LimitAllotment | undefined>;
+    onAllotmentReleased(): void;
+    private acquireAsync;
+    private waitForRelease;
+}
+//# sourceMappingURL=FifoBlockingRejection.d.ts.map

package/dist/limiter/FifoBlockingRejection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FifoBlockingRejection.d.ts","sourceRoot":"","sources":["../../src/limiter/FifoBlockingRejection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EACV,4BAA4B,EAC5B,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAMvB;;;;;;;GAOG;AACH,qBAAa,qBAAqB,CAChC,QAAQ,CACR,YAAW,4BAA4B,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACrE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAG3C,OAAO,GAAE;QACP;;;WAGG;QACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACzB;IASR,sBAAsB,CACpB,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,iBAAiB,EAC/C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAItC,mBAAmB,IAAI,IAAI;YAOb,YAAY;IA6B1B,OAAO,CAAC,cAAc;CAoCvB"}

package/dist/limiter/FifoBlockingRejection.js

@@ -0,0 +1,77 @@
+const MAX_TIMEOUT = 60 * 60 * 1000; // 1 hour
+/**
+ * Rejection strategy that blocks the caller in a FIFO queue when the limit
+ * has been reached, waiting for a slot to open up. This strategy favors
+ * fairness: callers are served in the order they arrived.
+ *
+ * Because JavaScript is single-threaded, "blocking" means awaiting a promise
+ * that resolves when a token becomes available.
+ */
+export class FifoBlockingRejection {
+    timeout;
+    waiters = [];
+    constructor(options = {}) {
+        const t = options.timeout ?? MAX_TIMEOUT;
+        if (t > MAX_TIMEOUT) {
+            throw new Error(`Timeout cannot be greater than ${MAX_TIMEOUT} ms`);
+        }
+        this.timeout = t;
+    }
+    onAllotmentUnavailable(_context, retry, signal) {
+        return this.acquireAsync(_context, retry, signal);
+    }
+    onAllotmentReleased() {
+        const waiters = this.waiters.splice(0);
+        for (const waiter of waiters) {
+            waiter();
+        }
+    }
+    async acquireAsync(context, retry, signal) {
+        const deadline = performance.now() + this.timeout;
+        while (true) {
+            const remaining = deadline - performance.now();
+            if (remaining <= 0) {
+                return undefined;
+            }
+            if (signal?.aborted) {
+                return undefined;
+            }
+            const allotment = retry(context);
+            if (allotment) {
+                return allotment;
+            }
+            const acquired = await this.waitForRelease(remaining, signal);
+            if (!acquired) {
+                return undefined;
+            }
+        }
+    }
+    waitForRelease(timeoutMs, signal) {
+        if (signal?.aborted) {
+            return Promise.resolve(false);
+        }
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (acquired) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve(acquired);
+            };
+            const waiter = () => settle(true);
+            this.waiters.push(waiter);
+            const timer = setTimeout(() => settle(false), timeoutMs);
+            const onAbort = () => settle(false);
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                const idx = this.waiters.indexOf(waiter);
+                if (idx !== -1) {
+                    this.waiters.splice(idx, 1);
+                }
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+}

package/dist/limiter/LifoBlockingLimiter.d.ts

@@ -0,0 +1,53 @@
+import type { Limiter } from "../Limiter.js";
+import type { LimitAllotment } from "../LimitAllotment.js";
+import type { AcquireOptions, AsyncLimiter } from "./BlockingLimiter.js";
+/**
+ * Limiter decorator that blocks the caller when the limit has been reached.
+ * This strategy ensures the resource is properly protected but favors
+ * availability over latency by not fast failing requests when the limit has
+ * been reached. To help keep success latencies low and minimize timeouts any
+ * blocked requests are processed in last in/first out order.
+ *
+ * Use this limiter only when the calling model allows the limiter to be
+ * blocked (i.e. the caller can await).
+ */
+export interface LifoBlockingLimiterOptions<ContextT> {
+    /**
+     * Maximum number of blocked callers in the backlog. Default: 100
+     */
+    backlogSize?: number;
+    /**
+     * Maximum timeout for callers blocked on the limiter, in milliseconds.
+     * Can be a fixed number or a function that derives the timeout from the
+     * request context (e.g. from a deadline). Default: 1000
+     */
+    backlogTimeout?: number | ((context: ContextT) => number);
+}
+export declare class LifoBlockingLimiter<ContextT> implements AsyncLimiter<ContextT> {
+    private readonly delegate;
+    private readonly backlogSize;
+    private readonly getBacklogTimeout;
+    /**
+     * Fixed backlog timeout in milliseconds, or undefined if the timeout is
+     * derived from the request context.
+     */
+    readonly fixedBacklogTimeoutMillis: number | undefined;
+    /**
+     * LIFO backlog of waiters. The front of the array is the most recently
+     * added (highest priority).
+     */
+    private readonly backlog;
+    constructor(delegate: Limiter<ContextT>, options?: LifoBlockingLimiterOptions<ContextT>);
+    /**
+     * Acquire a token, waiting in a LIFO queue if the limit has been reached.
+     * Returns a promise that resolves to a LimitAllotment if acquired, or undefined
+     * if the backlog is full, timeout elapses, or the operation is aborted.
+     */
+    acquire(this: LifoBlockingLimiter<void>): Promise<LimitAllotment | undefined>;
+    acquire(context: ContextT, options?: AcquireOptions): Promise<LimitAllotment | undefined>;
+    private waitForBacklog;
+    private wrapAllotment;
+    private unblock;
+    toString(): string;
+}
+//# sourceMappingURL=LifoBlockingLimiter.d.ts.map

package/dist/limiter/LifoBlockingLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LifoBlockingLimiter.d.ts","sourceRoot":"","sources":["../../src/limiter/LifoBlockingLimiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzE;;;;;;;;;GASG;AACH,MAAM,WAAW,0BAA0B,CAAC,QAAQ;IAClD;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,CAAC,CAAC;CAC3D;AAOD,qBAAa,mBAAmB,CAAC,QAAQ,CAAE,YAAW,YAAY,CAAC,QAAQ,CAAC;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAgC;IAElE;;;OAGG;IACH,QAAQ,CAAC,yBAAyB,EAAE,MAAM,GAAG,SAAS,CAAC;IAEvD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;gBAGrD,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC3B,OAAO,GAAE,0BAA0B,CAAC,QAAQ,CAAM;IAepD;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAC7E,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAwBzF,OAAO,CAAC,cAAc;IAsCtB,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,OAAO;IAcf,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/limiter/LifoBlockingLimiter.js

@@ -0,0 +1,108 @@
+export class LifoBlockingLimiter {
+    delegate;
+    backlogSize;
+    getBacklogTimeout;
+    /**
+     * Fixed backlog timeout in milliseconds, or undefined if the timeout is
+     * derived from the request context.
+     */
+    fixedBacklogTimeoutMillis;
+    /**
+     * LIFO backlog of waiters. The front of the array is the most recently
+     * added (highest priority).
+     */
+    backlog = [];
+    constructor(delegate, options = {}) {
+        this.delegate = delegate;
+        this.backlogSize = options.backlogSize ?? 100;
+        const timeout = options.backlogTimeout ?? 1_000;
+        if (typeof timeout === "number") {
+            this.getBacklogTimeout = () => timeout;
+            this.fixedBacklogTimeoutMillis = timeout;
+        }
+        else {
+            this.getBacklogTimeout = timeout;
+            this.fixedBacklogTimeoutMillis = undefined;
+        }
+    }
+    async acquire(context, options = {}) {
+        const requestContext = context;
+        if (options.signal?.aborted) {
+            return undefined;
+        }
+        // Try to acquire a token and return immediately if successful
+        const allotment = this.delegate.acquire(requestContext);
+        if (allotment) {
+            return this.wrapAllotment(allotment);
+        }
+        // Restrict backlog size so the queue doesn't grow unbounded during an outage
+        if (this.backlog.length >= this.backlogSize) {
+            return undefined;
+        }
+        // Create a waiter and block until an allotment is released by another
+        // operation. Waiters will be unblocked in LIFO order.
+        const result = await this.waitForBacklog(requestContext, options.signal);
+        return result ? this.wrapAllotment(result) : undefined;
+    }
+    waitForBacklog(context, signal) {
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (allotment) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                resolve(allotment);
+            };
+            const waiter = {
+                context,
+                resolve: (allotment) => settle(allotment),
+            };
+            this.backlog.unshift(waiter);
+            const timer = setTimeout(() => settle(undefined), this.getBacklogTimeout(context));
+            const onAbort = () => settle(undefined);
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                const idx = this.backlog.indexOf(waiter);
+                if (idx !== -1) {
+                    this.backlog.splice(idx, 1);
+                }
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    wrapAllotment(delegate) {
+        return {
+            reportSuccess: () => {
+                delegate.reportSuccess();
+                this.unblock();
+            },
+            reportIgnore: () => {
+                delegate.reportIgnore();
+                this.unblock();
+            },
+            reportDropped: () => {
+                delegate.reportDropped();
+                this.unblock();
+            },
+        };
+    }
+    unblock() {
+        if (this.backlog.length === 0)
+            return;
+        // Peek at the front (most recently added) waiter
+        const waiter = this.backlog[0];
+        const allotment = this.delegate.acquire(waiter.context);
+        if (allotment) {
+            this.backlog.shift();
+            waiter.resolve(allotment);
+        }
+        // Still can't acquire the limit. unblock will be called again next time
+        // the limit is released.
+    }
+    toString() {
+        return `LifoBlockingLimiter [${this.delegate}]`;
+    }
+}

package/dist/limiter/LifoBlockingRejection.d.ts

@@ -0,0 +1,31 @@
+import type { LimitAllotment } from "../LimitAllotment.js";
+import type { AllotmentUnavailableStrategy, AsyncAcquireResult, SyncAcquireResult } from "../Limiter.js";
+export interface LifoBlockingRejectionOptions<ContextT> {
+    /**
+     * Maximum number of blocked callers in the backlog. Default: 100
+     */
+    backlogSize?: number | undefined;
+    /**
+     * Maximum timeout for callers blocked on the limiter, in milliseconds.
+     * Can be a fixed number or a function that derives the timeout from the
+     * request context (e.g. from a deadline). Default: 1000
+     */
+    backlogTimeout?: number | ((context: ContextT) => number) | undefined;
+}
+/**
+ * Rejection strategy that blocks the caller in a LIFO queue when the limit
+ * has been reached. This strategy favors availability over latency by
+ * processing the most recently blocked request first, keeping success
+ * latencies low and minimizing timeouts.
+ */
+export declare class LifoBlockingRejection<ContextT> implements AllotmentUnavailableStrategy<ContextT, AsyncAcquireResult> {
+    private readonly backlogSize;
+    private readonly getBacklogTimeout;
+    private readonly backlog;
+    private retry;
+    constructor(options?: LifoBlockingRejectionOptions<ContextT>);
+    onAllotmentUnavailable(context: ContextT, retry: (context: ContextT) => SyncAcquireResult, signal?: AbortSignal): Promise<LimitAllotment | undefined>;
+    onAllotmentReleased(): void;
+    private waitForBacklog;
+}
+//# sourceMappingURL=LifoBlockingRejection.d.ts.map

package/dist/limiter/LifoBlockingRejection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LifoBlockingRejection.d.ts","sourceRoot":"","sources":["../../src/limiter/LifoBlockingRejection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EACV,4BAA4B,EAC5B,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAOvB,MAAM,WAAW,4BAA4B,CAAC,QAAQ;IACpD;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEjC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;CACvE;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB,CAChC,QAAQ,CACR,YAAW,4BAA4B,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACrE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAgC;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IAEvD,OAAO,CAAC,KAAK,CAAyD;gBAE1D,OAAO,GAAE,4BAA4B,CAAC,QAAQ,CAAM;IAQhE,sBAAsB,CACpB,OAAO,EAAE,QAAQ,EACjB,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,iBAAiB,EAC/C,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAUtC,mBAAmB,IAAI,IAAI;IAW3B,OAAO,CAAC,cAAc;CAsCvB"}

package/dist/limiter/LifoBlockingRejection.js

@@ -0,0 +1,63 @@
+/**
+ * Rejection strategy that blocks the caller in a LIFO queue when the limit
+ * has been reached. This strategy favors availability over latency by
+ * processing the most recently blocked request first, keeping success
+ * latencies low and minimizing timeouts.
+ */
+export class LifoBlockingRejection {
+    backlogSize;
+    getBacklogTimeout;
+    backlog = [];
+    retry;
+    constructor(options = {}) {
+        this.backlogSize = options.backlogSize ?? 100;
+        const timeout = options.backlogTimeout ?? 1_000;
+        this.getBacklogTimeout =
+            typeof timeout === "number" ? () => timeout : timeout;
+    }
+    onAllotmentUnavailable(context, retry, signal) {
+        this.retry = retry;
+        if (this.backlog.length >= this.backlogSize) {
+            return Promise.resolve(undefined);
+        }
+        return this.waitForBacklog(context, signal);
+    }
+    onAllotmentReleased() {
+        if (this.backlog.length === 0 || !this.retry)
+            return;
+        const waiter = this.backlog[0];
+        const allotment = this.retry(waiter.context);
+        if (allotment) {
+            this.backlog.shift();
+            waiter.resolve(allotment);
+        }
+    }
+    waitForBacklog(context, signal) {
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (allotment) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve(allotment);
+            };
+            const waiter = {
+                context,
+                resolve: (allotment) => settle(allotment),
+            };
+            this.backlog.unshift(waiter);
+            const timer = setTimeout(() => settle(undefined), this.getBacklogTimeout(context));
+            const onAbort = () => settle(undefined);
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                const idx = this.backlog.indexOf(waiter);
+                if (idx !== -1) {
+                    this.backlog.splice(idx, 1);
+                }
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+}