adaptive-concurrency 0.3.2 → 0.3.3

package/dist/LimitAllotment.d.ts

@@ -1,6 +1,12 @@
 /**
  * Handle returned when a concurrency slot is acquired. The caller must invoke
- * exactly one of the release-and-record methods when the operation completes.
+ * exactly one of the release-and-xxx methods when the operation completes.
+ *
+ * **Important for implementers:** the release methods below must never throw
+ * or produce a rejected promise. If an error occurs internally (e.g. notifying
+ * a strategy), the implementation is responsible for catching and handling it.
+ * Callers may invoke these methods in a fire-and-forget manner (without
+ * awaiting), so any rejection would become an unhandled promise rejection.
  */
 export interface LimitAllotment {
     /**

package/dist/LimitAllotment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LimitAllotment.d.ts","sourceRoot":"","sources":["../src/LimitAllotment.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;OAGG;IACH,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;;;OAIG;IACH,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C"}
+{"version":3,"file":"LimitAllotment.d.ts","sourceRoot":"","sources":["../src/LimitAllotment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;OAGG;IACH,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;;;OAIG;IACH,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C"}

package/dist/Limiter.d.ts

@@ -9,7 +9,7 @@ export type MaybePromise<T> = T | Promise<T>;
 export type AcquireResult = Promise<LimitAllotment | undefined>;
 export interface AcquireOptions<ContextT = void> {
     context?: ContextT;
-    signal?: AbortSignal;
+    signal?: AbortSignal | undefined;
 }
 /**
  * Read-only view of the limiter's current state, provided to strategies so
@@ -40,13 +40,13 @@ export interface AcquireStrategy<ContextT> {
      * Called when the adaptive limit changes. The strategy can react
      * (e.g. adjust available permits by the delta, update partition sub-limits).
      */
-    onLimitChanged?(oldLimit: number, newLimit: number): MaybePromise<void>;
+    onLimitChanged?(oldLimit: number, newLimit: number): void;
 }
 /**
  * Determines what happens when a request is rejected by the
- * {@link AcquireStrategy}. The type parameter `ResultT` flows through to
- * {@link Limiter.acquire}'s return type, enabling the type system to
- * distinguish sync limiters (no promise) from async/blocking ones.
+ * {@link AcquireStrategy} (e.g. queue the caller, reject immediately, or block
+ * until a slot is available). Implementations must return an
+ * {@link AcquireResult}, which is always a `Promise`.
  */
 export interface AllotmentUnavailableStrategy<ContextT> {
     /**
@@ -66,6 +66,11 @@ export interface AllotmentUnavailableStrategy<ContextT> {
      * Blocking strategies use this to wake queued waiters.
      */
     onAllotmentReleased(): MaybePromise<void>;
+    /**
+     * Called when the adaptive limit changes. Blocking strategies can use this to
+     * proactively drain queued waiters when capacity increases.
+     */
+    onLimitChanged?(oldLimit: number, newLimit: number): MaybePromise<void>;
 }
 export interface LimiterOptions<ContextT> {
     limit?: AdaptiveLimit;
@@ -97,8 +102,6 @@ export interface LimiterOptions<ContextT> {
  * Concurrency limiter with pluggable strategies for gating decisions and
  * rejection handling.
  *
- * `acquire()` always returns a `Promise<LimitAllotment | undefined>`.
- *
  * @typeParam ContextT Request context type (e.g. partition key).
  */
 export declare class Limiter<Context = void> {
@@ -122,25 +125,13 @@ export declare class Limiter<Context = void> {
     getLimit(): number;
     getInflight(): number;
 }
-/**
- * Simple semaphore-based acquire strategy. Tracks a permits counter that is
- * decremented when an allotment is taken and incremented on release. When
- * permits reach zero, {@link tryAcquireAllotment} returns false.
- */
-export declare class SemaphoreStrategy {
-    private permits;
-    constructor(initialLimit: number);
-    tryAcquireAllotment(): boolean;
-    onAllotmentReleased(): void;
-    onLimitChanged(oldLimit: number, newLimit: number): void;
-}
 export type RunCallbackArgs<ContextT> = {
     context: ContextT | undefined;
     signal: AbortSignal | undefined;
 };
 export interface LimitedFunction<ContextT> {
-    <T, E extends Error = Error>(fn: (args: RunCallbackArgs<ContextT>) => RunResult<T, E> | Promise<RunResult<T, E>>): Promise<T | typeof QuotaNotAvailable>;
-    <T, E extends Error = Error>(options: AcquireOptions<ContextT>, fn: (args: RunCallbackArgs<ContextT>) => RunResult<T, E> | Promise<RunResult<T, E>>): Promise<T | typeof QuotaNotAvailable>;
+    <T, E extends Error = Error>(fn: (args: RunCallbackArgs<ContextT>) => T | RunResult<T, E> | Promise<T | RunResult<T, E>>): Promise<T | typeof QuotaNotAvailable>;
+    <T, E extends Error = Error>(options: AcquireOptions<ContextT>, fn: (args: RunCallbackArgs<ContextT>) => T | RunResult<T, E> | Promise<T | RunResult<T, E>>): Promise<T | typeof QuotaNotAvailable>;
 }
 /**
  * Creates a helper that runs callbacks under acquired limiter allotments.
@@ -150,6 +141,8 @@ export interface LimitedFunction<ContextT> {
  * - On {@link RunResult} `success` / `ignore`, returns the carried value after
  *   recording success/ignore to the allotment.
  * - On `dropped`, records drop and throws the carried error.
+ * - If callback returns a non-{@link RunResult} value, it is treated as
+ *   implicit success and returned as-is.
  * - On uncaught exceptions from `fn`, records ignore and rethrows, except for
  *   {@link AdaptiveTimeoutError}, which records drop and rethrows.
  * - Callback receives `{ context, signal }` from acquire options.

package/dist/Limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Limiter.d.ts","sourceRoot":"","sources":["../src/Limiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAW,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEnE,OAAO,EAEL,iBAAiB,EACjB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;AAEhE,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,IAAI;IAC7C,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAMD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ;IACvC;;;;OAIG;IACH,mBAAmB,CACjB,OAAO,EAAE,QAAQ,EACjB,KAAK,EAAE,YAAY,GAClB,YAAY,CAAC,OAAO,CAAC,CAAC;IAEzB;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAE3D;;;OAGG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;CACzE;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B,CAAC,QAAQ;IACpD;;;;;;;;;;OAUG;IACH,sBAAsB,CACpB,OAAO,EAAE,QAAQ,EACjB,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,aAAa,EAC3C,MAAM,CAAC,EAAE,WAAW,GACnB,aAAa,CAAC;IAEjB;;;OAGG;IACH,mBAAmB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;CAC3C;AAaD,MAAM,WAAW,cAAc,CAAC,QAAQ;IACtC,KAAK,CAAC,EAAE,aAAa,CAAC;IAEtB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAErB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC;IAEhD;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;IAE5C;;;OAGG;IACH,4BAA4B,CAAC,EAAE,4BAA4B,CAAC,QAAQ,CAAC,CAAC;CACvE;AAED;;;;;;;GAOG;AACH,qBAAa,OAAO,CAAC,OAAO,GAAG,IAAI;IACjC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2B;IAC3D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAEpB;IACd,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8C;IAE7E,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;IAExC,MAAM,CAAC,gBAAgB,IAAI,aAAa;gBAI5B,OAAO,GAAE,cAAc,CAAC,OAAO,CAAM;IA4C3C,OAAO,CACX,OAAO,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,GAChC,aAAa;YA6BF,cAAc;IAW5B,OAAO,CAAC,eAAe;IAsCvB,QAAQ,IAAI,MAAM;IAIlB,WAAW,IAAI,MAAM;CAGtB;AAMD;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAS;gBAEZ,YAAY,EAAE,MAAM;IAIhC,mBAAmB,IAAI,OAAO;IAM9B,mBAAmB,IAAI,IAAI;IAI3B,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;CAGzD;AAED,MAAM,MAAM,eAAe,CAAC,QAAQ,IAAI;IACtC,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;CACjC,CAAC;AACF,MAAM,WAAW,eAAe,CAAC,QAAQ;IACvC,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,GAAG,KAAK,EACzB,EAAE,EAAE,CACF,IAAI,EAAE,eAAe,CAAC,QAAQ,CAAC,KAC5B,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,GAAG,OAAO,iBAAiB,CAAC,CAAC;IAEzC,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,GAAG,KAAK,EACzB,OAAO,EAAE,cAAc,CAAC,QAAQ,CAAC,EACjC,EAAE,EAAE,CACF,IAAI,EAAE,eAAe,CAAC,QAAQ,CAAC,KAC5B,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,GAAG,OAAO,iBAAiB,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EACR,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,eAAe,CAAC,QAAQ,CAAC,CA0DvD"}
+{"version":3,"file":"Limiter.d.ts","sourceRoot":"","sources":["../src/Limiter.ts"],"names":[],"mappings":"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"}

package/dist/Limiter.js

@@ -1,6 +1,7 @@
 import { GradientLimit } from "./limit/GradientLimit.js";
+import { SemaphoreStrategy } from "./limiter/acquire-strategies/SemaphoreStrategy.js";
 import { MetricIds, NoopMetricRegistry } from "./MetricRegistry.js";
-import { isAdaptiveTimeoutError, QuotaNotAvailable, } from "./RunResult.js";
+import { isAdaptiveTimeoutError, isRunResult, QuotaNotAvailable, } from "./RunResult.js";
 // ---------------------------------------------------------------------------
 // Limiter options
 // ---------------------------------------------------------------------------
@@ -14,8 +15,6 @@ let idCounter = 0;
  * Concurrency limiter with pluggable strategies for gating decisions and
  * rejection handling.
  *
- * `acquire()` always returns a `Promise<LimitAllotment | undefined>`.
- *
  * @typeParam ContextT Request context type (e.g. partition key).
  */
 export class Limiter {
@@ -45,7 +44,8 @@ export class Limiter {
         this.limitAlgorithm.subscribe((newLimit) => {
             const oldLimit = this._limit;
             this._limit = newLimit;
-            void Promise.resolve(this.acquireStrategy.onLimitChanged?.(oldLimit, newLimit));
+            this.acquireStrategy.onLimitChanged?.(oldLimit, newLimit);
+            void this.rejectionStrategy?.onLimitChanged?.(oldLimit, newLimit);
         });
         const registry = options.metricRegistry ?? NoopMetricRegistry;
         const limiterName = options.name ?? `unnamed-${++idCounter}`;
@@ -86,6 +86,9 @@ export class Limiter {
         if (!(await this.acquireStrategy.tryAcquireAllotment(ctx, state))) {
             this.rejectedCounter.increment();
             if (this.rejectionStrategy) {
+                if (options?.signal?.aborted) {
+                    return undefined;
+                }
                 return this.rejectionStrategy.onAllotmentUnavailable(ctx, (retryCtx) => this.tryAcquireCore(retryCtx), options?.signal);
             }
             return undefined;
@@ -107,10 +110,12 @@ export class Limiter {
         const currentInflight = ++this._inflight;
         return {
             releaseAndRecordSuccess: async () => {
+                const endTime = this.clock();
+                const rtt = endTime - startTime;
                 this._inflight--;
                 await this.acquireStrategy.onAllotmentReleased(ctx);
                 this.successCounter.increment();
-                this.limitAlgorithm.addSample(startTime, this.clock() - startTime, currentInflight, false);
+                this.limitAlgorithm.addSample(startTime, rtt, currentInflight, false);
                 await this.rejectionStrategy?.onAllotmentReleased();
             },
             releaseAndIgnore: async () => {
@@ -120,10 +125,12 @@ export class Limiter {
                 await this.rejectionStrategy?.onAllotmentReleased();
             },
             releaseAndRecordDropped: async () => {
+                const endTime = this.clock();
+                const rtt = endTime - startTime;
                 this._inflight--;
                 await this.acquireStrategy.onAllotmentReleased(ctx);
                 this.droppedCounter.increment();
-                this.limitAlgorithm.addSample(startTime, this.clock() - startTime, currentInflight, true);
+                this.limitAlgorithm.addSample(startTime, rtt, currentInflight, true);
                 await this.rejectionStrategy?.onAllotmentReleased();
             },
         };
@@ -135,32 +142,6 @@ export class Limiter {
         return this._inflight;
     }
 }
-// ---------------------------------------------------------------------------
-// Built-in acquire strategy: Semaphore
-// ---------------------------------------------------------------------------
-/**
- * Simple semaphore-based acquire strategy. Tracks a permits counter that is
- * decremented when an allotment is taken and incremented on release. When
- * permits reach zero, {@link tryAcquireAllotment} returns false.
- */
-export class SemaphoreStrategy {
-    permits;
-    constructor(initialLimit) {
-        this.permits = initialLimit;
-    }
-    tryAcquireAllotment() {
-        if (this.permits <= 0)
-            return false;
-        this.permits--;
-        return true;
-    }
-    onAllotmentReleased() {
-        this.permits++;
-    }
-    onLimitChanged(oldLimit, newLimit) {
-        this.permits += newLimit - oldLimit;
-    }
-}
 /**
  * Creates a helper that runs callbacks under acquired limiter allotments.
  *
@@ -169,28 +150,26 @@ export class SemaphoreStrategy {
  * - On {@link RunResult} `success` / `ignore`, returns the carried value after
  *   recording success/ignore to the allotment.
  * - On `dropped`, records drop and throws the carried error.
+ * - If callback returns a non-{@link RunResult} value, it is treated as
+ *   implicit success and returned as-is.
  * - On uncaught exceptions from `fn`, records ignore and rethrows, except for
  *   {@link AdaptiveTimeoutError}, which records drop and rethrows.
  * - Callback receives `{ context, signal }` from acquire options.
  */
 export function withLimiter(limiter) {
     async function limited(optionsOrFn, maybeFn) {
-        const hasOptions = maybeFn !== undefined;
-        const options = hasOptions
-            ? optionsOrFn
-            : undefined;
-        const fn = hasOptions
-            ? maybeFn
-            : optionsOrFn;
+        const [options, fn] = typeof optionsOrFn === "function"
+            ? [undefined, optionsOrFn]
+            : [optionsOrFn, maybeFn];
+        if (!fn) {
+            throw new Error("No function provided");
+        }
         const allotment = await limiter.acquire(options);
         if (!allotment) {
             return QuotaNotAvailable;
         }
         const [result] = await Promise.allSettled([
-            fn({
-                context: options?.context,
-                signal: options?.signal,
-            }),
+            fn({ context: options?.context, signal: options?.signal }),
         ]);
         if (result.status === "rejected") {
             if (isAdaptiveTimeoutError(result.reason)) {
@@ -202,16 +181,21 @@ export function withLimiter(limiter) {
             throw result.reason;
         }
         const outcome = result.value;
-        switch (outcome.kind) {
+        if (!isRunResult(outcome)) {
+            await allotment.releaseAndRecordSuccess();
+            return outcome;
+        }
+        const outcomeCast = outcome;
+        switch (outcomeCast.kind) {
             case "success":
                 await allotment.releaseAndRecordSuccess();
-                return outcome.value;
+                return outcomeCast.value;
             case "ignore":
                 await allotment.releaseAndIgnore();
-                return outcome.value;
+                return outcomeCast.value;
             case "dropped":
                 await allotment.releaseAndRecordDropped();
-                throw outcome.error;
+                throw outcomeCast.error;
         }
     }
     return limited;

package/dist/RunResult.d.ts

@@ -14,20 +14,26 @@ export declare class AdaptiveTimeoutError extends Error {
     constructor(message?: string);
 }
 export declare function isAdaptiveTimeoutError(error: unknown): error is AdaptiveTimeoutError;
-export interface RunSuccess<T> {
+declare const isRunResultTag: unique symbol;
+export type RunSuccess<T> = {
     readonly kind: "success";
+    readonly [isRunResultTag]: true;
     readonly value: T;
-}
-export interface RunIgnore<T> {
+};
+export type RunIgnore<T> = {
     readonly kind: "ignore";
+    readonly [isRunResultTag]: true;
     readonly value: T;
-}
-export interface RunDropped<E extends Error = Error> {
+};
+export type RunDropped<E extends Error = Error> = {
     readonly kind: "dropped";
+    readonly [isRunResultTag]: true;
     readonly error: E;
-}
+};
 export type RunResult<T, E extends Error = Error> = RunSuccess<T> | RunIgnore<T> | RunDropped<E>;
+export declare function isRunResult<T extends unknown>(value: T): value is T & RunResult<unknown, Error>;
 export declare function success<T>(value: T): RunSuccess<T>;
 export declare function ignore<T>(value: T): RunIgnore<T>;
 export declare function dropped<E extends Error>(error: E): RunDropped<E>;
+export {};
 //# sourceMappingURL=RunResult.d.ts.map

package/dist/RunResult.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RunResult.d.ts","sourceRoot":"","sources":["../src/RunResult.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,qBAA+B;gBAEhC,OAAO,CAAC,EAAE,MAAM;CAI7B;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,oBAAoB,CAQ/B;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,GAAG,KAAK,IAC5C,UAAU,CAAC,CAAC,CAAC,GACb,SAAS,CAAC,CAAC,CAAC,GACZ,UAAU,CAAC,CAAC,CAAC,CAAC;AAElB,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAEhD;AAED,wBAAgB,OAAO,CAAC,CAAC,SAAS,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAEhE"}
+{"version":3,"file":"RunResult.d.ts","sourceRoot":"","sources":["../src/RunResult.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,qBAA+B;gBAEhC,OAAO,CAAC,EAAE,MAAM;CAI7B;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,oBAAoB,CAQ/B;AAED,QAAA,MAAM,cAAc,eAAwB,CAAC;AAE7C,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,IAAI;IAChD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,GAAG,KAAK,IAC5C,UAAU,CAAC,CAAC,CAAC,GACb,SAAS,CAAC,CAAC,CAAC,GACZ,UAAU,CAAC,CAAC,CAAC,CAAC;AAElB,wBAAgB,WAAW,CAAC,CAAC,SAAS,OAAO,EAC3C,KAAK,EAAE,CAAC,GACP,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAOxC;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAEhD;AAED,wBAAgB,OAAO,CAAC,CAAC,SAAS,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAEhE"}

package/dist/RunResult.js

@@ -24,12 +24,19 @@ export function isAdaptiveTimeoutError(error) {
             "code" in error &&
             error.code === ADAPTIVE_TIMEOUT_ERROR_CODE));
 }
+const isRunResultTag = Symbol("isRunResult");
+export function isRunResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        isRunResultTag in value &&
+        value[isRunResultTag] === true);
+}
 export function success(value) {
-    return { kind: "success", value };
+    return { kind: "success", [isRunResultTag]: true, value };
 }
 export function ignore(value) {
-    return { kind: "ignore", value };
+    return { kind: "ignore", [isRunResultTag]: true, value };
 }
 export function dropped(error) {
-    return { kind: "dropped", error };
+    return { kind: "dropped", [isRunResultTag]: true, error };
 }

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export type { AdaptiveLimit } from "./limit/StreamingLimit.js";
 export type { LimitAllotment } from "./LimitAllotment.js";
-export { Limiter, SemaphoreStrategy, withLimiter, type AcquireOptions, type AcquireResult, type AcquireStrategy, type AllotmentUnavailableStrategy, type LimitedFunction, type LimiterOptions, type LimiterState, type RunCallbackArgs, type MaybePromise, } from "./Limiter.js";
+export { Limiter, withLimiter, type AcquireOptions, type AcquireResult, type AcquireStrategy, type AllotmentUnavailableStrategy, type LimitedFunction, type LimiterOptions, type LimiterState, type MaybePromise, type RunCallbackArgs, } from "./Limiter.js";
 export { ListenerSet } from "./ListenerSet.js";
 export { MetricIds, NoopMetricRegistry, type Counter, type DistributionMetric, type GaugeMetric, type MetricRegistry, } from "./MetricRegistry.js";
-export { AdaptiveTimeoutError, dropped, ignore, isAdaptiveTimeoutError, QuotaNotAvailable, success, type RunDropped, type RunIgnore, type RunResult, type RunSuccess, } from "./RunResult.js";
+export { AdaptiveTimeoutError, dropped, ignore, isAdaptiveTimeoutError, isRunResult, QuotaNotAvailable, success, type RunDropped, type RunIgnore, type RunResult, type RunSuccess, } from "./RunResult.js";
 export { AIMDLimit, type AIMDLimitOptions } from "./limit/AIMDLimit.js";
 export { FixedLimit } from "./limit/FixedLimit.js";
 export { GradientLimit, type Gradient2LimitOptions, } from "./limit/GradientLimit.js";
@@ -20,6 +20,7 @@ export type { SampleWindow } from "./limit/window/SampleWindow.js";
 export { squareRoot, squareRootWithBaseline } from "./utils/index.js";
 export * from "./limiter/factories/index.js";
 export { PartitionedStrategy, type PartitionConfig, } from "./limiter/acquire-strategies/PartitionedStrategy.js";
+export { SemaphoreStrategy } from "./limiter/acquire-strategies/SemaphoreStrategy.js";
 export { DelayedRejectStrategy, type DelayedRejectStrategyOptions, } from "./limiter/allocation-unavailable-strategies/DelayedRejectStrategy.js";
 export { DelayedThenBlockingRejection } from "./limiter/allocation-unavailable-strategies/DelayedThenBlockingRejection.js";
 export { FifoBlockingRejection } from "./limiter/allocation-unavailable-strategies/FifoBlockingRejection.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EACL,OAAO,EACP,iBAAiB,EACjB,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,KAAK,OAAO,EACZ,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,OAAO,EACP,MAAM,EACN,sBAAsB,EACtB,iBAAiB,EACjB,OAAO,EACP,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EACL,aAAa,EACb,KAAK,qBAAqB,GAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,GAC1B,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,YAAY,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAG7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,4BAA4B,EAAE,MAAM,0CAA0C,CAAC;AACxF,YAAY,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAGnE,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAGtE,cAAc,8BAA8B,CAAC;AAC7C,OAAO,EACL,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,qDAAqD,CAAC;AAG7D,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,sEAAsE,CAAC;AAC9E,OAAO,EAAE,4BAA4B,EAAE,MAAM,6EAA6E,CAAC;AAC3H,OAAO,EAAE,qBAAqB,EAAE,MAAM,sEAAsE,CAAC;AAC7G,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,sEAAsE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EACL,OAAO,EACP,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,KAAK,OAAO,EACZ,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,OAAO,EACP,MAAM,EACN,sBAAsB,EACtB,WAAW,EACX,iBAAiB,EACjB,OAAO,EACP,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EACL,aAAa,EACb,KAAK,qBAAqB,GAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,GAC1B,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,YAAY,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAG7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,4BAA4B,EAAE,MAAM,0CAA0C,CAAC;AACxF,YAAY,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAGnE,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAEtE,cAAc,8BAA8B,CAAC;AAG7C,OAAO,EACL,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,qDAAqD,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,mDAAmD,CAAC;AAGtF,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,sEAAsE,CAAC;AAC9E,OAAO,EAAE,4BAA4B,EAAE,MAAM,6EAA6E,CAAC;AAC3H,OAAO,EAAE,qBAAqB,EAAE,MAAM,sEAAsE,CAAC;AAC7G,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,sEAAsE,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
-export { Limiter, SemaphoreStrategy, withLimiter, } from "./Limiter.js";
+export { Limiter, withLimiter, } from "./Limiter.js";
 export { ListenerSet } from "./ListenerSet.js";
 export { MetricIds, NoopMetricRegistry, } from "./MetricRegistry.js";
-export { AdaptiveTimeoutError, dropped, ignore, isAdaptiveTimeoutError, QuotaNotAvailable, success, } from "./RunResult.js";
+export { AdaptiveTimeoutError, dropped, ignore, isAdaptiveTimeoutError, isRunResult, QuotaNotAvailable, success, } from "./RunResult.js";
 // Limit algorithms
 export { AIMDLimit } from "./limit/AIMDLimit.js";
 export { FixedLimit } from "./limit/FixedLimit.js";
@@ -18,9 +18,10 @@ export { makeAverageSampleWindow } from "./limit/window/AverageSampleWindow.js";
 export { createPercentileSampleWindow } from "./limit/window/PercentileSampleWindow.js";
 // Limit functions
 export { squareRoot, squareRootWithBaseline } from "./utils/index.js";
-// Acquire strategies
 export * from "./limiter/factories/index.js";
+// Acquire strategies
 export { PartitionedStrategy, } from "./limiter/acquire-strategies/PartitionedStrategy.js";
+export { SemaphoreStrategy } from "./limiter/acquire-strategies/SemaphoreStrategy.js";
 // Rejection strategies
 export { DelayedRejectStrategy, } from "./limiter/allocation-unavailable-strategies/DelayedRejectStrategy.js";
 export { DelayedThenBlockingRejection } from "./limiter/allocation-unavailable-strategies/DelayedThenBlockingRejection.js";

package/dist/limiter/acquire-strategies/PartitionedStrategy.d.ts

@@ -6,6 +6,25 @@ export type PartitionConfig = {
      * [0.0, 1.0].
      */
     percent: number;
+    /**
+     * Controls whether this partition may exceed its limit-at-global-saturation
+     * while global inflight is still below the global limit.
+     *
+     * - `{ kind: "unbounded" }` (default): current behavior; any partition may
+     *   consume all global slack.
+     * - `{ kind: "capped", maxBurstMultiplier }`: partition may burst, but only
+     *   up to `ceil(limitAtGlobalSaturation * maxBurstMultiplier)`.
+     * - `{ kind: "none" }`: no bursting; partition cannot exceed its
+     *   `limitAtGlobalSaturation`, even when global slack exists.
+     */
+    burstMode?: {
+        kind: "unbounded";
+    } | {
+        kind: "capped";
+        maxBurstMultiplier: number;
+    } | {
+        kind: "none";
+    } | undefined;
 };
 /**
  * ## Partitioned acquire strategy (guaranteed share + bursting)
@@ -16,9 +35,12 @@ export type PartitionConfig = {
  * max(1, ceil(globalLimit * percent))`.
  *
  * Admission policy:
- * - If `globalInflight < globalLimit`, the request is admitted regardless of
- *   its partition's current limitAtGlobalSaturation usage (bursting while slack
- *   exists).
+ * - If `globalInflight < globalLimit`, admission is controlled by partition
+ *   burst policy:
+ *   - `unbounded` (default): always admit while global slack exists.
+ *   - `capped`: admit up to
+ *     `ceil(limitAtGlobalSaturation * maxBurstMultiplier)`.
+ *   - `none`: admit only up to `limitAtGlobalSaturation`.
  *
  * - If `globalInflight >= globalLimit`, admission is checked against the
  *   resolved partition's limitAtGlobalSaturation only (`tryAcquire` on that
@@ -30,8 +52,7 @@ export type PartitionConfig = {
  *
  * Examples (global limit = 10, A=50%, B=50% => limitsAtGlobalSaturation: A=5,
  * B=5):
- * - **Bursting:** A can reach inflight 10 while B is 0 (below-saturation
- *   admissions do not enforce per-partition limits at global saturation).
+ * - **Unbounded bursting:** A can reach inflight 10 while B is 0.
  *
  * - **Limit-at-global-saturation catch-up at saturation:** if A=10 and B=0,
  *   then B requests can still be admitted up to B=5 via `tryAcquire`, so global
@@ -81,6 +102,14 @@ export declare class PartitionedStrategy<ContextT, PartitionName extends string
     getPartition(name: PartitionName): {
         name: PartitionName;
         percent: number;
+        burstMode: {
+            kind: "unbounded";
+        } | {
+            kind: "capped";
+            maxBurstMultiplier: number;
+        } | {
+            kind: "none";
+        };
         limitAtGlobalSaturation: number;
         inFlight: number;
         isLimitAtGlobalSaturationExceeded: boolean;

package/dist/limiter/acquire-strategies/PartitionedStrategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PartitionedStrategy.d.ts","sourceRoot":"","sources":["../../../src/limiter/acquire-strategies/PartitionedStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,yBAAyB,CAAC;AAKjC,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,mBAAmB,CAC9B,QAAQ,EACR,aAAa,SAAS,MAAM,GAAG,MAAM,CACrC,YAAW,eAAe,CAAC,QAAQ,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAG9B;IACF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuB;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAEH;gBAEnB,OAAO,EAAE;QACnB;;;WAGG;QACH,YAAY,EAAE,MAAM,CAAC;QAErB;;;;;WAKG;QACH,iBAAiB,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,aAAa,GAAG,SAAS,CAAC;QACpE,UAAU,EAAE,MAAM,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;QAEnD,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;KAC7C;IAkDD,mBAAmB,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO;IAUpE,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI;IAI5C,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMzD;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,aAAa;;;;;;;IAehC,OAAO,CAAC,gBAAgB;CAUzB"}
+{"version":3,"file":"PartitionedStrategy.d.ts","sourceRoot":"","sources":["../../../src/limiter/acquire-strategies/PartitionedStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAGV,cAAc,EACf,MAAM,yBAAyB,CAAC;AAKjC,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EACN;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,GACrB;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAA;KAAE,GAC9C;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB,SAAS,CAAC;CACf,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,mBAAmB,CAC9B,QAAQ,EACR,aAAa,SAAS,MAAM,GAAG,MAAM,CACrC,YAAW,eAAe,CAAC,QAAQ,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAG9B;IACF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuB;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAEH;gBAEnB,OAAO,EAAE;QACnB;;;WAGG;QACH,YAAY,EAAE,MAAM,CAAC;QAErB;;;;;WAKG;QACH,iBAAiB,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,aAAa,GAAG,SAAS,CAAC;QACpE,UAAU,EAAE,MAAM,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;QAEnD,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;KAC7C;IAmDD,mBAAmB,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO;IASpE,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI;IAI5C,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMzD;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,aAAa;;;;kBAuCpB,WAAW;;kBACX,QAAQ;gCAAsB,MAAM;;kBACpC,MAAM;;;;;;IAzBlB,OAAO,CAAC,gBAAgB;CAUzB"}

package/dist/limiter/acquire-strategies/PartitionedStrategy.js

@@ -9,9 +9,12 @@ const PARTITION_TAG_NAME = "partition";
  * max(1, ceil(globalLimit * percent))`.
  *
  * Admission policy:
- * - If `globalInflight < globalLimit`, the request is admitted regardless of
- *   its partition's current limitAtGlobalSaturation usage (bursting while slack
- *   exists).
+ * - If `globalInflight < globalLimit`, admission is controlled by partition
+ *   burst policy:
+ *   - `unbounded` (default): always admit while global slack exists.
+ *   - `capped`: admit up to
+ *     `ceil(limitAtGlobalSaturation * maxBurstMultiplier)`.
+ *   - `none`: admit only up to `limitAtGlobalSaturation`.
  *
  * - If `globalInflight >= globalLimit`, admission is checked against the
  *   resolved partition's limitAtGlobalSaturation only (`tryAcquire` on that
@@ -23,8 +26,7 @@ const PARTITION_TAG_NAME = "partition";
  *
  * Examples (global limit = 10, A=50%, B=50% => limitsAtGlobalSaturation: A=5,
  * B=5):
- * - **Bursting:** A can reach inflight 10 while B is 0 (below-saturation
- *   admissions do not enforce per-partition limits at global saturation).
+ * - **Unbounded bursting:** A can reach inflight 10 while B is 0.
  *
  * - **Limit-at-global-saturation catch-up at saturation:** if A=10 and B=0,
  *   then B requests can still be admitted up to B=5 via `tryAcquire`, so global
@@ -65,6 +67,7 @@ export class PartitionedStrategy {
             new Partition({
                 name,
                 percent: cfg.percent,
+                burstMode: cfg.burstMode ?? { kind: "unbounded" },
                 initialLimitAtGlobalSaturation: partitionLimitAtGlobalSaturationForGlobal(initialLimit, cfg.percent),
                 registry,
             }),
@@ -72,9 +75,9 @@ export class PartitionedStrategy {
         this.unknownPartition = new Partition({
             name: "unknown",
             percent: 0,
+            burstMode: { kind: "unbounded" },
             // Java never calls updateLimit on unknown; limitAtGlobalSaturation stays
-            // 0 so
-            // tryAcquire always fails at global cap.
+            // 0, so tryAcquire always fails at global saturation.
             initialLimitAtGlobalSaturation: 0,
             registry,
         });
@@ -84,8 +87,7 @@ export class PartitionedStrategy {
         if (state.inflight >= state.limit) {
             return partition.tryAcquire();
         }
-        partition.acquire();
-        return true;
+        return partition.acquireWithinBurst();
     }
     onAllotmentReleased(context) {
         this.resolvePartition(context).release();
@@ -107,6 +109,7 @@ export class PartitionedStrategy {
         return {
             name: partition.name,
             percent: partition.percent,
+            burstMode: partition.burstMode,
             limitAtGlobalSaturation: partition.limitAtGlobalSaturation,
             inFlight: partition.inFlight,
             isLimitAtGlobalSaturationExceeded: partition.isLimitAtGlobalSaturationExceeded,
@@ -129,6 +132,7 @@ function partitionLimitAtGlobalSaturationForGlobal(totalGlobalLimit, percent) {
 class Partition {
     name;
     percent;
+    burstMode;
     inflightDistribution;
     limitAtGlobalSaturationGauge;
     _inflight = 0;
@@ -139,7 +143,12 @@ class Partition {
         }
         this.name = init.name;
         this.percent = init.percent;
+        this.burstMode = init.burstMode;
         this._limitAtGlobalSaturation = init.initialLimitAtGlobalSaturation;
+        if (this.burstMode.kind === "capped" &&
+            this.burstMode.maxBurstMultiplier < 1.0) {
+            throw new Error("maxBurstMultiplier must be >= 1.0");
+        }
         const registry = init.registry;
         this.inflightDistribution = registry.distribution(MetricIds.INFLIGHT_NAME, PARTITION_TAG_NAME, this.name);
         this.limitAtGlobalSaturationGauge = registry.gauge(MetricIds.PARTITION_LIMIT_NAME, () => this._limitAtGlobalSaturation, PARTITION_TAG_NAME, this.name);
@@ -163,6 +172,13 @@ class Partition {
         this._inflight++;
         this.inflightDistribution.addSample(this._inflight);
     }
+    acquireWithinBurst() {
+        if (this._inflight >= this.burstCapBelowGlobalSaturation()) {
+            return false;
+        }
+        this.acquire();
+        return true;
+    }
     tryAcquire() {
         if (this._inflight < this._limitAtGlobalSaturation) {
             this._inflight++;
@@ -177,6 +193,15 @@ class Partition {
     get inFlight() {
         return this._inflight;
     }
+    burstCapBelowGlobalSaturation() {
+        if (this.burstMode.kind === "unbounded") {
+            return Number.POSITIVE_INFINITY;
+        }
+        if (this.burstMode.kind === "none") {
+            return this._limitAtGlobalSaturation;
+        }
+        return Math.max(this._limitAtGlobalSaturation, Math.ceil(this._limitAtGlobalSaturation * this.burstMode.maxBurstMultiplier));
+    }
     toString() {
         return `Partition [pct=${this.percent}, limitAtGlobalSaturation=${this._limitAtGlobalSaturation}, inflight=${this._inflight}]`;
     }

package/dist/limiter/acquire-strategies/SemaphoreStrategy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Simple semaphore-based acquire strategy. Tracks a permits counter that is
+ * decremented when an allotment is taken and incremented on release. When
+ * permits reach zero, `tryAcquireAllotment` returns false.
+ */
+export declare class SemaphoreStrategy {
+    private permits;
+    constructor(initialLimit: number);
+    tryAcquireAllotment(): boolean;
+    onAllotmentReleased(): void;
+    onLimitChanged(oldLimit: number, newLimit: number): void;
+}
+//# sourceMappingURL=SemaphoreStrategy.d.ts.map

package/dist/limiter/acquire-strategies/SemaphoreStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SemaphoreStrategy.d.ts","sourceRoot":"","sources":["../../../src/limiter/acquire-strategies/SemaphoreStrategy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAS;gBAEZ,YAAY,EAAE,MAAM;IAIhC,mBAAmB,IAAI,OAAO;IAM9B,mBAAmB,IAAI,IAAI;IAI3B,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;CAGzD"}

package/dist/limiter/acquire-strategies/SemaphoreStrategy.js

@@ -0,0 +1,23 @@
+/**
+ * Simple semaphore-based acquire strategy. Tracks a permits counter that is
+ * decremented when an allotment is taken and incremented on release. When
+ * permits reach zero, `tryAcquireAllotment` returns false.
+ */
+export class SemaphoreStrategy {
+    permits;
+    constructor(initialLimit) {
+        this.permits = initialLimit;
+    }
+    tryAcquireAllotment() {
+        if (this.permits <= 0)
+            return false;
+        this.permits--;
+        return true;
+    }
+    onAllotmentReleased() {
+        this.permits++;
+    }
+    onLimitChanged(oldLimit, newLimit) {
+        this.permits += newLimit - oldLimit;
+    }
+}