@adaptive-concurrency-toolkit/core 1.0.0

package/dist/limit/gradient2-limit.js

@@ -0,0 +1,139 @@
+import { Ema } from "../util/ema.js";
+import { clamp } from "../util/math.js";
+import { ChangeListeners } from "../util/listeners.js";
+const DEFAULT_QUEUE_SIZE = (limit) => 4 * Math.sqrt(limit);
+/**
+ * Gradient2 — adaptive limit based on the ratio of long-window RTT baseline to
+ * the current short-window RTT.
+ *
+ * Per window:
+ *
+ *   shortRtt  = window min RTT
+ *   longRtt   = EMA over windows of shortRtt
+ *   gradient  = clamp(tolerance · longRtt / shortRtt, minGradient, 1)
+ *   queue     = queueSize(limit)
+ *   newLimit  = limit · gradient + queue
+ *   if newLimit < limit:  newLimit ← smoothing · newLimit + (1−smoothing) · limit
+ *
+ * The `gradient ≤ 1` constraint means we only grow via the queue-size hedge —
+ * `limit · gradient` alone can never increase the limit. This matches the
+ * intuition that a fast response window is permission to add a probe, not to
+ * scale up multiplicatively.
+ */
+export class Gradient2Limit {
+    _limit;
+    minLimit;
+    maxLimit;
+    windowNanos;
+    minWindowSamples;
+    tolerance;
+    smoothing;
+    minGradient;
+    backoffRatio;
+    queueSizeFn;
+    longRtt;
+    listeners = new ChangeListeners();
+    windowStartNanos = -1;
+    windowMinRttNanos = Number.POSITIVE_INFINITY;
+    windowMaxInflight = 0;
+    windowSamples = 0;
+    windowDropped = false;
+    constructor(opts = {}) {
+        const initial = opts.initialLimit ?? 20;
+        const min = opts.minLimit ?? 1;
+        const max = opts.maxLimit ?? 1000;
+        if (!(min >= 1))
+            throw new RangeError(`minLimit must be >= 1`);
+        if (!(max >= min))
+            throw new RangeError(`maxLimit must be >= minLimit`);
+        if (!(initial >= min && initial <= max)) {
+            throw new RangeError(`initialLimit must be in [${min}, ${max}]`);
+        }
+        this._limit = initial;
+        this.minLimit = min;
+        this.maxLimit = max;
+        this.windowNanos = opts.windowNanos ?? 1_000_000_000;
+        this.minWindowSamples = opts.minWindowSamples ?? 10;
+        this.tolerance = opts.tolerance ?? 1.5;
+        this.smoothing = opts.smoothing ?? 0.2;
+        this.minGradient = opts.minGradient ?? 0.5;
+        this.backoffRatio = opts.backoffRatio ?? 0.9;
+        this.queueSizeFn = opts.queueSize ?? DEFAULT_QUEUE_SIZE;
+        this.longRtt = Ema.withWindow(opts.longWindowCount ?? 100);
+        if (!(this.tolerance > 0))
+            throw new RangeError(`tolerance must be > 0`);
+        if (!(this.smoothing > 0 && this.smoothing <= 1)) {
+            throw new RangeError(`smoothing must be in (0, 1]`);
+        }
+        if (!(this.minGradient > 0 && this.minGradient <= 1)) {
+            throw new RangeError(`minGradient must be in (0, 1]`);
+        }
+        if (!(this.backoffRatio > 0 && this.backoffRatio < 1)) {
+            throw new RangeError(`backoffRatio must be in (0, 1)`);
+        }
+    }
+    get limit() {
+        return this._limit;
+    }
+    /** Long-window RTT baseline (ns). 0 until the first window commits. */
+    get longRttNanos() {
+        return this.longRtt.value;
+    }
+    onSample(startNanos, rttNanos, inflight, didDrop) {
+        if (this.windowStartNanos < 0)
+            this.windowStartNanos = startNanos;
+        if (rttNanos < this.windowMinRttNanos)
+            this.windowMinRttNanos = rttNanos;
+        if (inflight > this.windowMaxInflight)
+            this.windowMaxInflight = inflight;
+        if (didDrop)
+            this.windowDropped = true;
+        this.windowSamples++;
+        const elapsed = startNanos - this.windowStartNanos;
+        if (elapsed >= this.windowNanos && this.windowSamples >= this.minWindowSamples) {
+            this.commitWindow();
+        }
+    }
+    onChange(listener) {
+        return this.listeners.add(listener);
+    }
+    commitWindow() {
+        const current = this._limit;
+        const shortRtt = this.windowMinRttNanos;
+        const maxInflight = this.windowMaxInflight;
+        const dropped = this.windowDropped;
+        this.windowStartNanos = -1;
+        this.windowMinRttNanos = Number.POSITIVE_INFINITY;
+        this.windowMaxInflight = 0;
+        this.windowSamples = 0;
+        this.windowDropped = false;
+        let next;
+        if (dropped) {
+            next = Math.max(this.minLimit, Math.floor(current * this.backoffRatio));
+        }
+        else {
+            // Skip the very first window — the long-RTT EMA seeds from it, so the
+            // gradient would be 1.0 trivially with no real signal yet.
+            const wasInitialized = this.longRtt.initialized;
+            const longRtt = this.longRtt.update(shortRtt);
+            if (!wasInitialized)
+                return;
+            const gradient = clamp((this.tolerance * longRtt) / shortRtt, this.minGradient, 1);
+            const queue = this.queueSizeFn(current);
+            let candidate = current * gradient + queue;
+            // Only grow when we are actually using the limit; otherwise hold.
+            if (candidate > current && maxInflight * 2 < current)
+                return;
+            if (candidate < current) {
+                candidate = this.smoothing * candidate + (1 - this.smoothing) * current;
+            }
+            next = candidate;
+        }
+        next = Math.round(clamp(next, this.minLimit, this.maxLimit));
+        if (next !== current) {
+            this._limit = next;
+            this.listeners.emit(next);
+        }
+    }
+}
+//# sourceMappingURL=gradient2-limit.js.map

package/dist/limit/gradient2-limit.js.map

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

package/dist/limit/index.d.ts

@@ -0,0 +1,5 @@
+export type { Limit } from './limit.ts';
+export { FixedLimit, type FixedLimitOptions } from './fixed-limit.ts';
+export { AimdLimit, type AimdLimitOptions } from './aimd-limit.ts';
+export { VegasLimit, type VegasLimitOptions } from './vegas-limit.ts';
+export { Gradient2Limit, type Gradient2LimitOptions } from './gradient2-limit.ts';

package/dist/limit/index.js

@@ -0,0 +1,5 @@
+export { FixedLimit } from "./fixed-limit.js";
+export { AimdLimit } from "./aimd-limit.js";
+export { VegasLimit } from "./vegas-limit.js";
+export { Gradient2Limit } from "./gradient2-limit.js";
+//# sourceMappingURL=index.js.map

package/dist/limit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/limit/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAA0B,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,SAAS,EAAyB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,UAAU,EAA0B,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,cAAc,EAA8B,MAAM,sBAAsB,CAAC"}

package/dist/limit/limit.d.ts

@@ -0,0 +1,30 @@
+import type { LimitChangeListener, Nanos, Unsubscribe } from '../types.ts';
+/**
+ * Concurrency limit algorithm. Implementations consume completion samples and
+ * expose the current inferred ceiling on in-flight work.
+ *
+ * The {@link onSample} signature is intentionally positional so the call site
+ * never allocates a sample object on the hot path.
+ */
+export interface Limit {
+    /** Current inferred concurrency ceiling. Always >= 1. */
+    readonly limit: number;
+    /**
+     * Report a completed operation.
+     *
+     * @param startTimeNanos Monotonic timestamp when the permit was issued.
+     *   Algorithms may use it for windowing.
+     * @param rttNanos       Observed round-trip time (now − startTimeNanos).
+     * @param inflight       In-flight count when the permit was issued
+     *   (or peak in-flight observed during the sample's lifetime — see limiter).
+     * @param didDrop        True if the caller reported the request as dropped
+     *   (timeout, 5xx, overload). Algorithms typically treat this as the
+     *   strongest decrease signal.
+     */
+    onSample(startTimeNanos: Nanos, rttNanos: Nanos, inflight: number, didDrop: boolean): void;
+    /**
+     * Subscribe to limit changes. Returns an unsubscribe function. The callback
+     * is invoked synchronously from `onSample` when the limit changes.
+     */
+    onChange(listener: LimitChangeListener): Unsubscribe;
+}

package/dist/limit/limit.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=limit.js.map

package/dist/limit/limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limit.js","sourceRoot":"","sources":["../../src/limit/limit.ts"],"names":[],"mappings":""}

package/dist/limit/vegas-limit.d.ts

@@ -0,0 +1,80 @@
+import type { LimitChangeListener, Nanos, Unsubscribe } from '../types.ts';
+import type { Limit } from './limit.ts';
+export interface VegasLimitOptions {
+    readonly initialLimit?: number;
+    readonly minLimit?: number;
+    readonly maxLimit?: number;
+    /**
+     * Window duration in nanoseconds. Samples within a window are aggregated and
+     * the limit is updated at most once per window. Defaults to 1 s.
+     */
+    readonly windowNanos?: number;
+    /** Minimum samples required to update at the end of a window. Defaults to 10. */
+    readonly minWindowSamples?: number;
+    /**
+     * Lower queue-size target as a function of limit. Default: `3·log10(limit)`.
+     * Below this, the limit is increased.
+     */
+    readonly alpha?: (limit: number) => number;
+    /**
+     * Upper queue-size target as a function of limit. Default: `6·log10(limit)`.
+     * Above this, the limit is decreased.
+     */
+    readonly beta?: (limit: number) => number;
+    /** Increase step. Default: `log10(limit)`. */
+    readonly increase?: (limit: number) => number;
+    /** Decrease step. Default: `log10(limit)`. */
+    readonly decrease?: (limit: number) => number;
+    /** Multiplicative back-off on a drop sample. Default 0.9. */
+    readonly backoffRatio?: number;
+    /**
+     * After this many windows without observing a new minimum RTT, the noload
+     * estimate is reset to the current window's min RTT — re-probing the floor.
+     * Default 10.
+     */
+    readonly probeIntervalWindows?: number;
+}
+/**
+ * TCP-Vegas inspired adaptive limit.
+ *
+ * Per window (≈ 1 s by default) compute:
+ *
+ *   queue = limit · (1 − rttNoLoad / rttWindowMin)
+ *
+ * and adjust:
+ *
+ *   queue ≤ α(limit) → grow  (limit + log10 limit)
+ *   queue ≥ β(limit) → shrink
+ *   else            → hold
+ *
+ * `rttNoLoad` is the rolling minimum RTT, periodically re-probed so the floor
+ * adapts to legitimate baseline shifts.
+ */
+export declare class VegasLimit implements Limit {
+    private _limit;
+    readonly minLimit: number;
+    readonly maxLimit: number;
+    readonly windowNanos: number;
+    readonly minWindowSamples: number;
+    readonly backoffRatio: number;
+    readonly probeIntervalWindows: number;
+    private readonly alphaFn;
+    private readonly betaFn;
+    private readonly increaseFn;
+    private readonly decreaseFn;
+    private readonly listeners;
+    private rttNoLoadNanos;
+    private windowStartNanos;
+    private windowMinRttNanos;
+    private windowMaxInflight;
+    private windowSamples;
+    private windowDropped;
+    private windowsSinceNewMin;
+    constructor(opts?: VegasLimitOptions);
+    get limit(): number;
+    /** Current rtt-no-load estimate (ns). `+Infinity` until the first sample. */
+    get rttNoLoad(): number;
+    onSample(startNanos: Nanos, rttNanos: Nanos, inflight: number, didDrop: boolean): void;
+    onChange(listener: LimitChangeListener): Unsubscribe;
+    private commitWindow;
+}

package/dist/limit/vegas-limit.js

@@ -0,0 +1,137 @@
+import { clamp } from "../util/math.js";
+import { ChangeListeners } from "../util/listeners.js";
+const DEFAULT_ALPHA = (limit) => 3 * Math.log10(limit);
+const DEFAULT_BETA = (limit) => 6 * Math.log10(limit);
+const DEFAULT_STEP = (limit) => Math.log10(limit);
+/**
+ * TCP-Vegas inspired adaptive limit.
+ *
+ * Per window (≈ 1 s by default) compute:
+ *
+ *   queue = limit · (1 − rttNoLoad / rttWindowMin)
+ *
+ * and adjust:
+ *
+ *   queue ≤ α(limit) → grow  (limit + log10 limit)
+ *   queue ≥ β(limit) → shrink
+ *   else            → hold
+ *
+ * `rttNoLoad` is the rolling minimum RTT, periodically re-probed so the floor
+ * adapts to legitimate baseline shifts.
+ */
+export class VegasLimit {
+    _limit;
+    minLimit;
+    maxLimit;
+    windowNanos;
+    minWindowSamples;
+    backoffRatio;
+    probeIntervalWindows;
+    alphaFn;
+    betaFn;
+    increaseFn;
+    decreaseFn;
+    listeners = new ChangeListeners();
+    rttNoLoadNanos = Number.POSITIVE_INFINITY;
+    windowStartNanos = -1;
+    windowMinRttNanos = Number.POSITIVE_INFINITY;
+    windowMaxInflight = 0;
+    windowSamples = 0;
+    windowDropped = false;
+    windowsSinceNewMin = 0;
+    constructor(opts = {}) {
+        const initial = opts.initialLimit ?? 20;
+        const min = opts.minLimit ?? 1;
+        const max = opts.maxLimit ?? 1000;
+        if (!(min >= 1))
+            throw new RangeError(`minLimit must be >= 1`);
+        if (!(max >= min))
+            throw new RangeError(`maxLimit must be >= minLimit`);
+        if (!(initial >= min && initial <= max)) {
+            throw new RangeError(`initialLimit must be in [${min}, ${max}]`);
+        }
+        this._limit = initial;
+        this.minLimit = min;
+        this.maxLimit = max;
+        this.windowNanos = opts.windowNanos ?? 1_000_000_000;
+        this.minWindowSamples = opts.minWindowSamples ?? 10;
+        this.backoffRatio = opts.backoffRatio ?? 0.9;
+        this.probeIntervalWindows = opts.probeIntervalWindows ?? 10;
+        this.alphaFn = opts.alpha ?? DEFAULT_ALPHA;
+        this.betaFn = opts.beta ?? DEFAULT_BETA;
+        this.increaseFn = opts.increase ?? DEFAULT_STEP;
+        this.decreaseFn = opts.decrease ?? DEFAULT_STEP;
+    }
+    get limit() {
+        return this._limit;
+    }
+    /** Current rtt-no-load estimate (ns). `+Infinity` until the first sample. */
+    get rttNoLoad() {
+        return this.rttNoLoadNanos;
+    }
+    onSample(startNanos, rttNanos, inflight, didDrop) {
+        if (this.windowStartNanos < 0)
+            this.windowStartNanos = startNanos;
+        if (rttNanos < this.windowMinRttNanos)
+            this.windowMinRttNanos = rttNanos;
+        if (inflight > this.windowMaxInflight)
+            this.windowMaxInflight = inflight;
+        if (didDrop)
+            this.windowDropped = true;
+        this.windowSamples++;
+        const elapsed = startNanos - this.windowStartNanos;
+        if (elapsed >= this.windowNanos && this.windowSamples >= this.minWindowSamples) {
+            this.commitWindow();
+        }
+    }
+    onChange(listener) {
+        return this.listeners.add(listener);
+    }
+    commitWindow() {
+        const current = this._limit;
+        const minRtt = this.windowMinRttNanos;
+        const maxInflight = this.windowMaxInflight;
+        const dropped = this.windowDropped;
+        // Reset window state up-front so we always start a clean window even if
+        // we early-return below.
+        this.windowStartNanos = -1;
+        this.windowMinRttNanos = Number.POSITIVE_INFINITY;
+        this.windowMaxInflight = 0;
+        this.windowSamples = 0;
+        this.windowDropped = false;
+        let next = current;
+        if (dropped) {
+            next = Math.max(this.minLimit, Math.floor(current * this.backoffRatio));
+        }
+        else {
+            // Track rtt-noload as a rolling minimum, re-probed periodically.
+            if (minRtt < this.rttNoLoadNanos) {
+                this.rttNoLoadNanos = minRtt;
+                this.windowsSinceNewMin = 0;
+            }
+            else if (++this.windowsSinceNewMin >= this.probeIntervalWindows) {
+                // Re-baseline so a transient one-off low sample doesn't pin us forever.
+                this.rttNoLoadNanos = minRtt;
+                this.windowsSinceNewMin = 0;
+            }
+            // Don't grow if we aren't using the limit we have.
+            if (maxInflight * 2 < current)
+                return;
+            const queue = current * (1 - this.rttNoLoadNanos / minRtt);
+            const alpha = this.alphaFn(current);
+            const beta = this.betaFn(current);
+            if (queue <= alpha) {
+                next = current + this.increaseFn(current);
+            }
+            else if (queue >= beta) {
+                next = current - this.decreaseFn(current);
+            }
+        }
+        next = Math.round(clamp(next, this.minLimit, this.maxLimit));
+        if (next !== current) {
+            this._limit = next;
+            this.listeners.emit(next);
+        }
+    }
+}
+//# sourceMappingURL=vegas-limit.js.map

package/dist/limit/vegas-limit.js.map

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

package/dist/limiter/index.d.ts

@@ -0,0 +1,2 @@
+export type { Limiter } from './limiter.ts';
+export { SimpleLimiter, type SimpleLimiterOptions } from './simple-limiter.ts';

package/dist/limiter/index.js

@@ -0,0 +1,2 @@
+export { SimpleLimiter } from "./simple-limiter.js";
+//# sourceMappingURL=index.js.map

package/dist/limiter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/limiter/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC"}

package/dist/limiter/limiter.d.ts

@@ -0,0 +1,18 @@
+import type { Listener } from '../types.ts';
+/**
+ * Gate work against an adaptive concurrency ceiling. Acquire a permit before
+ * starting work; call exactly one of `onSuccess` / `onDropped` / `onIgnore` on
+ * the returned {@link Listener} when work completes.
+ */
+export interface Limiter {
+    /**
+     * Attempt to acquire a permit. Returns `undefined` if the current in-flight
+     * count is at or above the algorithm's limit, in which case the caller is
+     * expected to shed load (e.g. respond 429, route to a fallback, queue).
+     */
+    acquire(): Listener | undefined;
+    /** Current in-flight count. */
+    readonly inflight: number;
+    /** Current algorithm limit. */
+    readonly limit: number;
+}

package/dist/limiter/limiter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=limiter.js.map

package/dist/limiter/limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter.js","sourceRoot":"","sources":["../../src/limiter/limiter.ts"],"names":[],"mappings":""}

package/dist/limiter/simple-limiter.d.ts

@@ -0,0 +1,28 @@
+import { type Clock } from '../clock.ts';
+import type { Limit } from '../limit/limit.ts';
+import type { Listener, Nanos } from '../types.ts';
+import type { Limiter } from './limiter.ts';
+export interface SimpleLimiterOptions {
+    /** Time source. Defaults to {@link defaultClock} (monotonic, nanosecond). */
+    readonly clock?: Clock;
+}
+/**
+ * Minimal {@link Limiter}: tracks an in-flight counter and gates new permits
+ * against the underlying {@link Limit}'s ceiling. No queueing — over-limit
+ * calls return `undefined` immediately so the caller can shed load.
+ *
+ * Sample reporting on the hot path is allocation-free aside from the listener
+ * itself: each listener carries its own start state and calls a positional
+ * method on the limiter to release.
+ */
+export declare class SimpleLimiter implements Limiter {
+    readonly algorithm: Limit;
+    readonly clock: Clock;
+    private _inflight;
+    constructor(algorithm: Limit, opts?: SimpleLimiterOptions);
+    get inflight(): number;
+    get limit(): number;
+    acquire(): Listener | undefined;
+    /** @internal */
+    _release(startNanos: Nanos, startInflight: number, didDrop: boolean, ignore: boolean): void;
+}

package/dist/limiter/simple-limiter.js

@@ -0,0 +1,70 @@
+import { defaultClock } from "../clock.js";
+/**
+ * Minimal {@link Limiter}: tracks an in-flight counter and gates new permits
+ * against the underlying {@link Limit}'s ceiling. No queueing — over-limit
+ * calls return `undefined` immediately so the caller can shed load.
+ *
+ * Sample reporting on the hot path is allocation-free aside from the listener
+ * itself: each listener carries its own start state and calls a positional
+ * method on the limiter to release.
+ */
+export class SimpleLimiter {
+    algorithm;
+    clock;
+    _inflight = 0;
+    constructor(algorithm, opts = {}) {
+        this.algorithm = algorithm;
+        this.clock = opts.clock ?? defaultClock;
+    }
+    get inflight() {
+        return this._inflight;
+    }
+    get limit() {
+        return this.algorithm.limit;
+    }
+    acquire() {
+        const next = this._inflight + 1;
+        if (next > this.algorithm.limit)
+            return undefined;
+        this._inflight = next;
+        return new SimpleListener(this, this.clock.nowNanos(), next);
+    }
+    /** @internal */
+    _release(startNanos, startInflight, didDrop, ignore) {
+        this._inflight--;
+        if (ignore)
+            return;
+        const rtt = this.clock.nowNanos() - startNanos;
+        this.algorithm.onSample(startNanos, rtt, startInflight, didDrop);
+    }
+}
+class SimpleListener {
+    limiter;
+    startNanos;
+    startInflight;
+    done = false;
+    constructor(limiter, startNanos, startInflight) {
+        this.limiter = limiter;
+        this.startNanos = startNanos;
+        this.startInflight = startInflight;
+    }
+    onSuccess() {
+        if (this.done)
+            return;
+        this.done = true;
+        this.limiter._release(this.startNanos, this.startInflight, false, false);
+    }
+    onDropped() {
+        if (this.done)
+            return;
+        this.done = true;
+        this.limiter._release(this.startNanos, this.startInflight, true, false);
+    }
+    onIgnore() {
+        if (this.done)
+            return;
+        this.done = true;
+        this.limiter._release(this.startNanos, this.startInflight, false, true);
+    }
+}
+//# sourceMappingURL=simple-limiter.js.map

package/dist/limiter/simple-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-limiter.js","sourceRoot":"","sources":["../../src/limiter/simple-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AAUvD;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IACf,SAAS,CAAQ;IACjB,KAAK,CAAQ;IACd,SAAS,GAAG,CAAC,CAAC;IAEtB,YAAY,SAAgB,EAAE,OAA6B,EAAE;QAC3D,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,YAAY,CAAC;IAC1C,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;IAC9B,CAAC;IAED,OAAO;QACL,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QAChC,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAClD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,OAAO,IAAI,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,IAAI,CAAC,CAAC;IAC/D,CAAC;IAED,gBAAgB;IAChB,QAAQ,CAAC,UAAiB,EAAE,aAAqB,EAAE,OAAgB,EAAE,MAAe;QAClF,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,MAAM;YAAE,OAAO;QACnB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,UAAU,CAAC;QAC/C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IACnE,CAAC;CACF;AAED,MAAM,cAAc;IACD,OAAO,CAAgB;IACvB,UAAU,CAAQ;IAClB,aAAa,CAAS;IAC/B,IAAI,GAAG,KAAK,CAAC;IAErB,YAAY,OAAsB,EAAE,UAAiB,EAAE,aAAqB;QAC1E,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;IAED,SAAS;QACP,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAC3E,CAAC;IAED,SAAS;QACP,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1E,CAAC;IAED,QAAQ;QACN,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1E,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Time durations are represented as `number` nanoseconds carried in IEEE-754
+ * doubles. This keeps arithmetic on the hot path zero-allocation while still
+ * giving sub-microsecond precision for any realistic process uptime.
+ */
+export type Nanos = number;
+/**
+ * Returned by {@link Limiter.acquire} when a permit was successfully reserved.
+ * Exactly one of `onSuccess` / `onDropped` / `onIgnore` must be called for each
+ * permit; subsequent calls on the same listener are no-ops.
+ *
+ * Semantics:
+ *  - `onSuccess` — work completed within expected bounds. RTT is informative.
+ *  - `onDropped` — work failed in a way that indicates the upstream is
+ *                  overloaded (timeout, 5xx, queue-full). Strongest decrease
+ *                  signal for adaptive algorithms.
+ *  - `onIgnore`  — work completed but the sample should not influence the
+ *                  limit (e.g. client cancellation, 4xx validation error,
+ *                  cache hit). The permit is released; RTT is discarded.
+ */
+export interface Listener {
+    onSuccess(): void;
+    onDropped(): void;
+    onIgnore(): void;
+}
+export type LimitChangeListener = (newLimit: number) => void;
+export type Unsubscribe = () => void;

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/util/ema.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Exponential moving average with lazy initialization. The first value seeds
+ * the average so the EMA does not bias toward zero during warm-up.
+ *
+ * Update formula (after init):
+ *   v ← α·x + (1 − α)·v
+ *
+ * Hot path is one multiply + one fused-multiply-add equivalent; no allocations.
+ */
+export declare class Ema {
+    readonly alpha: number;
+    private _value;
+    private _initialized;
+    /**
+     * @param alpha smoothing factor in (0, 1]. Higher α reacts faster, lower α
+     * smooths more. Equivalent time constant ≈ 1/α samples.
+     */
+    constructor(alpha: number);
+    /**
+     * Construct an EMA whose smoothing factor approximates `n` samples of memory.
+     */
+    static withWindow(n: number): Ema;
+    update(x: number): number;
+    get value(): number;
+    get initialized(): boolean;
+    reset(): void;
+}