adaptive-concurrency 0.1.0

package/dist/limit/window/PercentileSampleWindow.js

@@ -0,0 +1,81 @@
+/**
+ * SampleWindow that uses a configurable percentile of observed RTTs as the
+ * tracked RTT and the minimum RTT as the candidate RTT. Samples beyond the
+ * window size are discarded.
+ */
+class ImmutablePercentileSampleWindow {
+    minRtt;
+    _maxInflight;
+    hasSeenDrop;
+    observedRtts;
+    _sampleCount;
+    percentile;
+    windowSize;
+    constructor(opts) {
+        const { minRtt, maxInflight, dropped, observedRtts, sampleCount, percentile, windowSize } = opts;
+        this.minRtt = minRtt ?? Infinity;
+        this._maxInflight = maxInflight ?? 0;
+        this.hasSeenDrop = dropped ?? false;
+        this.observedRtts = observedRtts ?? new Array(windowSize).fill(0);
+        this._sampleCount = sampleCount ?? 0;
+        this.percentile = percentile;
+        this.windowSize = windowSize;
+    }
+    addSample(rtt, inflight, didDrop) {
+        if (this._sampleCount >= this.windowSize) {
+            return this;
+        }
+        // Share the backing array between windows (safe because we only ever
+        // write to indices that haven't been written to yet in a given window
+        // lifecycle, and the array is never modified after the window is closed).
+        this.observedRtts[this._sampleCount] = rtt;
+        return new ImmutablePercentileSampleWindow({
+            minRtt: Math.min(this.minRtt, rtt),
+            maxInflight: Math.max(inflight, this._maxInflight),
+            dropped: this.hasSeenDrop || didDrop,
+            observedRtts: this.observedRtts,
+            sampleCount: this._sampleCount + 1,
+            percentile: this.percentile,
+            windowSize: this.windowSize,
+        });
+    }
+    get candidateRttMs() {
+        return this.minRtt;
+    }
+    get trackedRttMs() {
+        if (this._sampleCount === 0) {
+            return 0;
+        }
+        const sorted = this.observedRtts.slice(0, this._sampleCount).sort((a, b) => a - b);
+        const rttIndex = Math.round(this._sampleCount * this.percentile);
+        const zeroBasedIndex = rttIndex - 1;
+        return sorted[zeroBasedIndex];
+    }
+    get maxInFlight() {
+        return this._maxInflight;
+    }
+    get sampleCount() {
+        return this._sampleCount;
+    }
+    get dropped() {
+        return this.hasSeenDrop;
+    }
+    toString() {
+        return (`ImmutablePercentileSampleWindow [` +
+            `minRtt=${this.minRtt.toFixed(3)}` +
+            `, p${this.percentile} rtt=${this.trackedRttMs.toFixed(3)}` +
+            `, maxInFlight=${this._maxInflight}` +
+            `, sampleCount=${this._sampleCount}` +
+            `, didDrop=${this.hasSeenDrop}]`);
+    }
+}
+/**
+ * @param percentile Percentile to track, in the range (0, 1)
+ * @param windowSize Maximum number of samples per window
+ */
+export function createPercentileSampleWindow(percentile, windowSize) {
+    if (percentile <= 0 || percentile >= 1) {
+        throw new Error("Percentile should belong to (0, 1.0)");
+    }
+    return new ImmutablePercentileSampleWindow({ percentile, windowSize });
+}

package/dist/limit/window/SampleWindow.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Immutable sample window used to track request samples over a time window.
+ * Each call to addSample returns a new instance with the updated state.
+ *
+ * @see WindowedLimit
+ */
+export interface SampleWindow {
+    addSample(rtt: number, inflight: number, dropped: boolean): SampleWindow;
+    /**
+     * RTT used as a candidate for the minimum (e.g. the minimum observed RTT).
+     */
+    readonly candidateRttMs: number;
+    /**
+     * RTT used for limit decisions (e.g. average or percentile).
+     */
+    readonly trackedRttMs: number;
+    /**
+     * Maximum number of inflight requests seen in this window.
+     */
+    readonly maxInFlight: number;
+    /**
+     * Number of samples collected in this window.
+     */
+    readonly sampleCount: number;
+    /**
+     * Whether any sample in this window was a drop.
+     */
+    readonly dropped: boolean;
+}
+//# sourceMappingURL=SampleWindow.d.ts.map

package/dist/limit/window/SampleWindow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SampleWindow.d.ts","sourceRoot":"","sources":["../../../src/limit/window/SampleWindow.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,YAAY,CAAC;IAEzE;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B"}

package/dist/limit/window/SampleWindow.js

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

package/dist/limiter/AbstractLimiter.d.ts

@@ -0,0 +1,48 @@
+import type { Limiter } from "../Limiter.js";
+import type { LimitAllotment } from "../LimitAllotment.js";
+import type { MetricRegistry } from "../MetricRegistry.js";
+import type { StreamingLimit } from "../limit/StreamingLimit.js";
+export interface AbstractLimiterOptions<ContextT> {
+    limit?: StreamingLimit;
+    /**
+     * Clock function returning the current time in fractional milliseconds
+     * (like performance.now()). Default: performance.now
+     */
+    clock?: () => number;
+    name?: string;
+    metricRegistry?: MetricRegistry;
+    /**
+     * Predicate that, when returning true for a context, causes the request to
+     * bypass the limiter entirely. The request won't affect inflight count or
+     * the limit algorithm.
+     *
+     * Predicates should not rely strictly on the state of the limiter (such as
+     * inflight count) when evaluating whether to bypass. There is no guarantee
+     * that the state will be synchronized or consistent with respect to the
+     * bypass predicate.
+     */
+    bypassResolver?: (context: ContextT) => boolean;
+}
+export declare abstract class AbstractLimiter<ContextT> implements Limiter<ContextT> {
+    private inflight;
+    private readonly clock;
+    private readonly limitAlgorithm;
+    private readonly successCounter;
+    private readonly droppedCounter;
+    private readonly ignoredCounter;
+    private readonly rejectedCounter;
+    private readonly bypassCounter;
+    private readonly bypassResolver;
+    private _limit;
+    protected constructor(options?: AbstractLimiterOptions<ContextT>);
+    abstract acquire(this: Limiter<void>): LimitAllotment | undefined;
+    abstract acquire(context: ContextT): LimitAllotment | undefined;
+    protected shouldBypass(context: ContextT): boolean;
+    protected createRejectedAllotment(): undefined;
+    protected createBypassAllotment(): LimitAllotment;
+    protected createAllotment(): LimitAllotment;
+    getLimit(): number;
+    getInflight(): number;
+    protected onNewLimit(newLimit: number): void;
+}
+//# sourceMappingURL=AbstractLimiter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractLimiter.d.ts","sourceRoot":"","sources":["../../src/limiter/AbstractLimiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAW,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAcjE,MAAM,WAAW,sBAAsB,CAAC,QAAQ;IAC9C,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAErB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC;CACjD;AAED,8BAAsB,eAAe,CAAC,QAAQ,CAAE,YAAW,OAAO,CAAC,QAAQ,CAAC;IAC1E,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+C;IAE9E,OAAO,CAAC,MAAM,CAAS;IAEvB,SAAS,aAAa,OAAO,GAAE,sBAAsB,CAAC,QAAQ,CAAM;IAkBpE,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,cAAc,GAAG,SAAS;IACjE,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,GAAG,cAAc,GAAG,SAAS;IAE/D,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO;IAIlD,SAAS,CAAC,uBAAuB,IAAI,SAAS;IAK9C,SAAS,CAAC,qBAAqB,IAAI,cAAc;IAKjD,SAAS,CAAC,eAAe,IAAI,cAAc;IAgC3C,QAAQ,IAAI,MAAM;IAIlB,WAAW,IAAI,MAAM;IAIrB,SAAS,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CAG7C"}

package/dist/limiter/AbstractLimiter.js

@@ -0,0 +1,78 @@
+import { MetricIds } from "../MetricIds.js";
+import { NoopMetricRegistry } from "../MetricRegistry.js";
+import { VegasLimit } from "../limit/VegasLimit.js";
+const ID_TAG = "id";
+const STATUS_TAG = "status";
+const NOOP_ALLOTMENT = {
+    reportSuccess() { },
+    reportIgnore() { },
+    reportDropped() { },
+};
+let idCounter = 0;
+export class AbstractLimiter {
+    inflight = 0;
+    clock;
+    limitAlgorithm;
+    successCounter;
+    droppedCounter;
+    ignoredCounter;
+    rejectedCounter;
+    bypassCounter;
+    bypassResolver;
+    _limit;
+    constructor(options = {}) {
+        this.clock = options.clock ?? (() => performance.now());
+        this.limitAlgorithm = options.limit ?? new VegasLimit();
+        this._limit = this.limitAlgorithm.currentLimit;
+        this.limitAlgorithm.subscribe((newLimit) => this.onNewLimit(newLimit));
+        this.bypassResolver = options.bypassResolver;
+        const registry = options.metricRegistry ?? NoopMetricRegistry;
+        const name = options.name ?? `unnamed-${++idCounter}`;
+        registry.gauge(MetricIds.LIMIT_NAME, () => this.getLimit());
+        this.successCounter = registry.counter(MetricIds.CALL_NAME, { [ID_TAG]: name, [STATUS_TAG]: "success" });
+        this.droppedCounter = registry.counter(MetricIds.CALL_NAME, { [ID_TAG]: name, [STATUS_TAG]: "dropped" });
+        this.ignoredCounter = registry.counter(MetricIds.CALL_NAME, { [ID_TAG]: name, [STATUS_TAG]: "ignored" });
+        this.rejectedCounter = registry.counter(MetricIds.CALL_NAME, { [ID_TAG]: name, [STATUS_TAG]: "rejected" });
+        this.bypassCounter = registry.counter(MetricIds.CALL_NAME, { [ID_TAG]: name, [STATUS_TAG]: "bypassed" });
+    }
+    shouldBypass(context) {
+        return this.bypassResolver?.(context) ?? false;
+    }
+    createRejectedAllotment() {
+        this.rejectedCounter.increment();
+        return undefined;
+    }
+    createBypassAllotment() {
+        this.bypassCounter.increment();
+        return NOOP_ALLOTMENT;
+    }
+    createAllotment() {
+        const startTime = this.clock();
+        const currentInflight = ++this.inflight;
+        return {
+            reportSuccess: () => {
+                this.inflight--;
+                this.successCounter.increment();
+                this.limitAlgorithm.accumulateSample(startTime, this.clock() - startTime, currentInflight, false);
+            },
+            reportIgnore: () => {
+                this.inflight--;
+                this.ignoredCounter.increment();
+            },
+            reportDropped: () => {
+                this.inflight--;
+                this.droppedCounter.increment();
+                this.limitAlgorithm.accumulateSample(startTime, this.clock() - startTime, currentInflight, true);
+            },
+        };
+    }
+    getLimit() {
+        return this._limit;
+    }
+    getInflight() {
+        return this.inflight;
+    }
+    onNewLimit(newLimit) {
+        this._limit = newLimit;
+    }
+}

package/dist/limiter/AbstractPartitionedLimiter.d.ts

@@ -0,0 +1,66 @@
+import type { Limiter } from "../Limiter.js";
+import type { LimitAllotment } from "../LimitAllotment.js";
+import type { AbstractLimiterOptions } from "./AbstractLimiter.js";
+import { AbstractLimiter } from "./AbstractLimiter.js";
+export interface PartitionConfig {
+    /** Percentage of the total limit guaranteed to this partition. Must be in [0.0, 1.0]. */
+    percent: number;
+    /**
+     * Delay in milliseconds introduced as a sleep to slow down the caller when
+     * this partition is rejected. Not recommended when using an event loop.
+     */
+    rejectDelay?: number;
+}
+export interface AbstractPartitionedLimiterOptions<ContextT> extends AbstractLimiterOptions<ContextT> {
+    /**
+     * Function(s) to resolve a context to a partition name. Multiple resolvers
+     * are processed in order; the first non-null/non-undefined value is used.
+     * If all resolvers return null/undefined, the "unknown" partition is used.
+     */
+    partitionResolver?: ((context: ContextT) => string | undefined) | Array<(context: ContextT) => string | undefined>;
+    /**
+     * Partitions keyed by name.
+     */
+    partitions?: Record<string, PartitionConfig>;
+    /**
+     * Maximum number of in-flight requests that can be delayed when rejecting
+     * excessive traffic for a partition. Default: 100
+     */
+    maxDelayedRequests?: number;
+}
+export interface PartitionState {
+    name: string;
+    percent: number;
+    limit: number;
+    inflight: number;
+    backoffMillis: number;
+    limitExceeded: boolean;
+}
+/**
+ * Build a limiter from partitioned options. If partitions and resolvers are
+ * both provided, creates a partitioned limiter; otherwise falls back to a
+ * SimpleLimiter.
+ */
+export declare function buildPartitionedLimiter<ContextT>(options: AbstractPartitionedLimiterOptions<ContextT>): Limiter<ContextT>;
+/**
+ * Limiter that supports partitioning requests into groups, each with a
+ * guaranteed percentage of the total concurrency limit. Partitions are not
+ * hard limits: when the system is below the global limit, any partition can
+ * burst beyond its guaranteed share. Only when the global limit is reached
+ * are per-partition limits enforced.
+ */
+export declare class PartitionedLimiter<ContextT> extends AbstractLimiter<ContextT> {
+    private readonly partitions;
+    private readonly unknownPartition;
+    private readonly partitionResolvers;
+    private readonly maxDelayedRequests;
+    private delayedRequests;
+    constructor(options: AbstractPartitionedLimiterOptions<ContextT>);
+    private resolvePartition;
+    acquire(this: PartitionedLimiter<void>): LimitAllotment | undefined;
+    acquire(context: ContextT): LimitAllotment | undefined;
+    protected onNewLimit(newLimit: number): void;
+    /** Returns partition state for observability and tests. */
+    getPartition(name: string): PartitionState | undefined;
+}
+//# sourceMappingURL=AbstractPartitionedLimiter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractPartitionedLimiter.d.ts","sourceRoot":"","sources":["../../src/limiter/AbstractPartitionedLimiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAgGvD,MAAM,WAAW,eAAe;IAC9B,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iCAAiC,CAAC,QAAQ,CAAE,SAAQ,sBAAsB,CAAC,QAAQ,CAAC;IACnG;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;IAEnH;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAE7C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAC9C,OAAO,EAAE,iCAAiC,CAAC,QAAQ,CAAC,GACnD,OAAO,CAAC,QAAQ,CAAC,CAQnB;AAED;;;;;;GAMG;AACH,qBAAa,kBAAkB,CAAC,QAAQ,CAAE,SAAQ,eAAe,CAAC,QAAQ,CAAC;IACzE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAY;IAC7C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAmD;IACtF,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,eAAe,CAAK;gBAEhB,OAAO,EAAE,iCAAiC,CAAC,QAAQ,CAAC;IAuChE,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC,GAAG,cAAc,GAAG,SAAS;IACnE,OAAO,CAAC,OAAO,EAAE,QAAQ,GAAG,cAAc,GAAG,SAAS;cAmDnC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOrD,2DAA2D;IAC3D,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;CAcvD"}

package/dist/limiter/AbstractPartitionedLimiter.js

@@ -0,0 +1,209 @@
+import { MetricIds } from "../MetricIds.js";
+import { NoopMetricRegistry } from "../MetricRegistry.js";
+import { AbstractLimiter } from "./AbstractLimiter.js";
+import { SimpleLimiter } from "./SimpleLimiter.js";
+const PARTITION_TAG_NAME = "partition";
+class Partition {
+    name;
+    busy = 0;
+    _percent = 0;
+    _limit = 0;
+    _backoffMillis = 0;
+    inflightDistribution;
+    constructor(name) {
+        this.name = name;
+    }
+    get percent() {
+        return this._percent;
+    }
+    setPercent(percent) {
+        this._percent = percent;
+        return this;
+    }
+    setBackoffMillis(backoffMillis) {
+        this._backoffMillis = backoffMillis;
+        return this;
+    }
+    get backoffMillis() {
+        return this._backoffMillis;
+    }
+    /**
+     * Calculate this partition's limit while rounding up and ensuring the value
+     * is at least 1. With this technique the sum of partition limits may end up
+     * being higher than the concurrency limit.
+     */
+    updateLimit(totalLimit) {
+        this._limit = Math.max(1, Math.ceil(totalLimit * this._percent));
+    }
+    get limit() {
+        return this._limit;
+    }
+    isLimitExceeded() {
+        return this.busy >= this._limit;
+    }
+    acquire() {
+        this.busy++;
+        this.inflightDistribution.addSample(this.busy);
+    }
+    /**
+     * Try to acquire a slot, returning false if the partition limit is exceeded.
+     */
+    tryAcquire() {
+        if (this.busy < this._limit) {
+            this.busy++;
+            this.inflightDistribution.addSample(this.busy);
+            return true;
+        }
+        return false;
+    }
+    release() {
+        this.busy--;
+    }
+    getInflight() {
+        return this.busy;
+    }
+    createMetrics(registry) {
+        this.inflightDistribution = registry.distribution(MetricIds.INFLIGHT_NAME, PARTITION_TAG_NAME, this.name);
+        registry.gauge(MetricIds.PARTITION_LIMIT_NAME, () => this._limit, PARTITION_TAG_NAME, this.name);
+    }
+    toString() {
+        return `Partition [pct=${this._percent}, limit=${this._limit}, busy=${this.busy}]`;
+    }
+}
+/**
+ * Build a limiter from partitioned options. If partitions and resolvers are
+ * both provided, creates a partitioned limiter; otherwise falls back to a
+ * SimpleLimiter.
+ */
+export function buildPartitionedLimiter(options) {
+    const hasPartitions = options.partitions && Object.keys(options.partitions).length > 0;
+    const hasResolvers = options.partitionResolver !== undefined;
+    if (hasPartitions && hasResolvers) {
+        return new PartitionedLimiter(options);
+    }
+    return new SimpleLimiter(options);
+}
+/**
+ * Limiter that supports partitioning requests into groups, each with a
+ * guaranteed percentage of the total concurrency limit. Partitions are not
+ * hard limits: when the system is below the global limit, any partition can
+ * burst beyond its guaranteed share. Only when the global limit is reached
+ * are per-partition limits enforced.
+ */
+export class PartitionedLimiter extends AbstractLimiter {
+    partitions;
+    unknownPartition;
+    partitionResolvers;
+    maxDelayedRequests;
+    delayedRequests = 0;
+    constructor(options) {
+        super(options);
+        const partitionEntries = Object.entries(options.partitions ?? {});
+        if (partitionEntries.length === 0) {
+            throw new Error("No partitions specified");
+        }
+        const totalPercent = partitionEntries.reduce((sum, [, cfg]) => sum + cfg.percent, 0);
+        if (totalPercent > 1.0) {
+            throw new Error("Sum of partition percentages must be <= 1.0");
+        }
+        const registry = options.metricRegistry ?? NoopMetricRegistry;
+        this.partitions = new Map();
+        for (const [name, cfg] of partitionEntries) {
+            if (cfg.percent < 0 || cfg.percent > 1) {
+                throw new Error("Partition percentage must be in the range [0.0, 1.0]");
+            }
+            const partition = new Partition(name);
+            partition.setPercent(cfg.percent);
+            if (cfg.rejectDelay !== undefined) {
+                partition.setBackoffMillis(cfg.rejectDelay);
+            }
+            partition.createMetrics(registry);
+            this.partitions.set(name, partition);
+        }
+        this.unknownPartition = new Partition("unknown");
+        this.unknownPartition.createMetrics(registry);
+        const resolver = options.partitionResolver;
+        this.partitionResolvers = Array.isArray(resolver) ? resolver : resolver ? [resolver] : [];
+        this.maxDelayedRequests = options.maxDelayedRequests ?? 100;
+        this.onNewLimit(this.getLimit());
+    }
+    resolvePartition(context) {
+        for (const resolver of this.partitionResolvers) {
+            const name = resolver(context);
+            if (name != null) {
+                const partition = this.partitions.get(name);
+                if (partition) {
+                    return partition;
+                }
+            }
+        }
+        return this.unknownPartition;
+    }
+    acquire(context) {
+        const requestContext = context;
+        if (this.shouldBypass(requestContext)) {
+            return this.createBypassAllotment();
+        }
+        const partition = this.resolvePartition(requestContext);
+        // The partition limit is not a hard limit. It is only applied if the
+        // global limit is exceeded. This allows for excess capacity in each
+        // partition to allow for bursting over the limit, but only if there is
+        // spare global capacity.
+        let overLimit;
+        if (this.getInflight() >= this.getLimit()) {
+            // Over global limit, so respect partition limit
+            overLimit = !partition.tryAcquire();
+        }
+        else {
+            // Below global limit, so no need to respect partition limit
+            partition.acquire();
+            overLimit = false;
+        }
+        if (overLimit) {
+            if (partition.backoffMillis > 0 && this.delayedRequests < this.maxDelayedRequests) {
+                // In the Java version this sleeps the thread. In JS we don't block,
+                // but we track the delayed count for consistency. A future async
+                // variant could use setTimeout-based delay.
+                this.delayedRequests++;
+                this.delayedRequests--;
+            }
+            return this.createRejectedAllotment();
+        }
+        const inner = this.createAllotment();
+        return {
+            reportSuccess: () => {
+                inner.reportSuccess();
+                partition.release();
+            },
+            reportIgnore: () => {
+                inner.reportIgnore();
+                partition.release();
+            },
+            reportDropped: () => {
+                inner.reportDropped();
+                partition.release();
+            },
+        };
+    }
+    onNewLimit(newLimit) {
+        super.onNewLimit(newLimit);
+        for (const [, partition] of this.partitions) {
+            partition.updateLimit(newLimit);
+        }
+    }
+    /** Returns partition state for observability and tests. */
+    getPartition(name) {
+        const partition = this.partitions.get(name);
+        if (!partition) {
+            return undefined;
+        }
+        return {
+            name: partition.name,
+            percent: partition.percent,
+            limit: partition.limit,
+            inflight: partition.getInflight(),
+            backoffMillis: partition.backoffMillis,
+            limitExceeded: partition.isLimitExceeded(),
+        };
+    }
+}

package/dist/limiter/BlockingLimiter.d.ts

@@ -0,0 +1,55 @@
+import type { Limiter } from "../Limiter.js";
+import type { LimitAllotment } from "../LimitAllotment.js";
+/**
+ * A limiter whose acquire method returns a promise, for use with blocking
+ * limiter wrappers that may need to wait for a token to become available.
+ */
+export interface AcquireOptions {
+    signal?: AbortSignal;
+}
+export interface AsyncLimiter<ContextT = void> {
+    acquire(this: AsyncLimiter<void>): Promise<LimitAllotment | undefined>;
+    acquire(context: ContextT, options?: AcquireOptions): Promise<LimitAllotment | undefined>;
+}
+/**
+ * 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 declare class BlockingLimiter<ContextT> implements AsyncLimiter<ContextT> {
+    static readonly MAX_TIMEOUT: number;
+    /**
+     * Wrap a limiter such that acquire will block up to MAX_TIMEOUT if the
+     * limit was reached instead of returning undefined immediately.
+     */
+    static wrap<ContextT>(delegate: Limiter<ContextT>): BlockingLimiter<ContextT>;
+    /**
+     * Wrap a limiter such that acquire will block up to the provided timeout
+     * (in ms) if the limit was reached instead of returning undefined
+     * immediately.
+     */
+    static wrap<ContextT>(delegate: Limiter<ContextT>, timeout: number): BlockingLimiter<ContextT>;
+    private readonly delegate;
+    private readonly timeout;
+    /** Queue of waiters blocked until a token is released */
+    private readonly waiters;
+    private constructor();
+    /** Returns the timeout used when blocking to acquire a permit, in ms. */
+    getTimeout(): number;
+    /**
+     * Acquire a token, waiting up to the configured timeout if the limit has
+     * been reached. Returns a promise that resolves to a LimitAllotment if acquired,
+     * or undefined if the timeout elapsed or the operation was aborted.
+     */
+    acquire(this: BlockingLimiter<void>): Promise<LimitAllotment | undefined>;
+    acquire(context: ContextT, options?: AcquireOptions): Promise<LimitAllotment | undefined>;
+    private waitForRelease;
+    private wrapAllotment;
+    private unblock;
+    toString(): string;
+}
+//# sourceMappingURL=BlockingLimiter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BlockingLimiter.d.ts","sourceRoot":"","sources":["../../src/limiter/BlockingLimiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAMD,MAAM,WAAW,YAAY,CAAC,QAAQ,GAAG,IAAI;IAC3C,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACvE,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;CAC3F;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe,CAAC,QAAQ,CAAE,YAAW,YAAY,CAAC,QAAQ,CAAC;IACtE,MAAM,CAAC,QAAQ,CAAC,WAAW,SAAkB;IAE7C;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,eAAe,CAAC,QAAQ,CAAC;IAE7E;;;;OAIG;IACH,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC;IAa9F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAE7C,OAAO;IAKP,yEAAyE;IACzE,UAAU,IAAI,MAAM;IAIpB;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IACzE,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IA8BzF,OAAO,CAAC,cAAc;IAsCtB,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,OAAO;IAQf,QAAQ,IAAI,MAAM;CAGnB"}