adaptive-concurrency 0.1.0

package/dist/Limit.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Contract for an algorithm that calculates a concurrency limit based on
+ * rtt measurements.
+ */
+export interface Limit {
+    /**
+     * @returns Current estimated limit
+     */
+    getLimit(): number;
+    /**
+     * Register a callback to receive notification whenever the limit is updated
+     * to a new value.
+     *
+     * Returns a function to unsubscribe. Optional AbortSignal support is
+     * provided for ergonomic cancellation.
+     */
+    notifyOnChange(consumer: (newLimit: number) => void, options?: {
+        signal?: AbortSignal;
+    }): () => void;
+    /**
+     * Adjust the estimated limit using a completed request sample.
+     * @param startTime Start time in fractional milliseconds (from performance.now())
+     * @param rtt Round trip time in fractional milliseconds
+     * @param inflight Number of inflight requests at the time the request started
+     * @param didDrop Whether the request was dropped (timeout or rejection)
+     */
+    adjustForSample(startTime: number, rtt: number, inflight: number, didDrop: boolean): void;
+}
+//# sourceMappingURL=Limit.d.ts.map

package/dist/Limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Limit.d.ts","sourceRoot":"","sources":["../src/Limit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB;;OAEG;IACH,QAAQ,IAAI,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,cAAc,CACZ,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,EACpC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,MAAM,IAAI,CAAC;IAEd;;;;;;OAMG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3F"}

package/dist/Limit.js

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

package/dist/LimitAllotment.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Handle returned when a concurrency slot is acquired. The caller must invoke
+ * exactly one of the report methods when the operation completes.
+ */
+export interface LimitAllotment {
+    /**
+     * The operation succeeded and internally measured latency should be used as
+     * an RTT sample.
+     */
+    reportSuccess(): void;
+    /**
+     * The operation failed before any meaningful RTT measurement could be made
+     * and should be ignored so it does not introduce an artificially low RTT.
+     */
+    reportIgnore(): void;
+    /**
+     * The request failed and was dropped due to being rejected by an external
+     * limit or hitting a timeout. Loss based StreamingLimit implementations will
+     * likely do an aggressive reduction in limit when this happens.
+     */
+    reportDropped(): void;
+}
+//# sourceMappingURL=LimitAllotment.d.ts.map

package/dist/LimitAllotment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LimitAllotment.d.ts","sourceRoot":"","sources":["../src/LimitAllotment.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;OAGG;IACH,YAAY,IAAI,IAAI,CAAC;IAErB;;;;OAIG;IACH,aAAa,IAAI,IAAI,CAAC;CACvB"}

package/dist/LimitAllotment.js

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

package/dist/Limiter.d.ts

@@ -0,0 +1,175 @@
+import type { AdaptiveLimit } from "./limit/StreamingLimit.js";
+import type { LimitAllotment } from "./LimitAllotment.js";
+import type { MetricRegistry } from "./MetricRegistry.js";
+import { QuotaNotAvailable, type RunResult } from "./RunResult.js";
+export type SyncAcquireResult = LimitAllotment | undefined;
+export type AsyncAcquireResult = Promise<LimitAllotment | undefined>;
+/**
+ * Union of all possible acquire return types. Useful for code that must handle
+ * both sync and async limiters generically.
+ */
+export type AcquireResult = SyncAcquireResult | AsyncAcquireResult;
+export interface AcquireOptions<ContextT = void> {
+    context?: ContextT;
+    signal?: AbortSignal;
+}
+/**
+ * Read-only view of the limiter's current state, provided to strategies so
+ * they can make gating decisions without coupling to the Limiter class.
+ */
+export interface LimiterState {
+    readonly limit: number;
+    readonly inflight: number;
+}
+/**
+ * Decides whether a non-bypassed caller may take a concurrency allotment and
+ * updates strategy bookkeeping when they may (e.g. permits counter or
+ * per-partition tracking).
+ */
+export interface AcquireStrategy<ContextT> {
+    /**
+     * Tries to acquire an allotment for this request under the strategy's rules.
+     * When `true`, the strategy has reserved capacity for one inflight unit; when
+     * `false`, an allotment was not available.
+     */
+    tryAcquireAllotment(context: ContextT, state: LimiterState): boolean;
+    /**
+     * Called when an acquired allotment completes (success, ignore, or drop).
+     * Perform any cleanup (e.g. increment permits, release a partition slot).
+     */
+    onAllotmentReleased(context: ContextT): void;
+    /**
+     * 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): 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.
+ */
+export interface AllotmentUnavailableStrategy<ContextT, ResultT extends SyncAcquireResult | AsyncAcquireResult> {
+    /**
+     * Called when the acquire strategy cannot allocate an allotment for a
+     * request.
+     *
+     * @param context The request context.
+     * @param retry Callback to re-attempt acquisition. The rejection strategy can
+     *   call this after a waiter is woken to try again. The retry runs
+     *   {@link AcquireStrategy.tryAcquireAllotment} and, if successful, returns a
+     *   ready-to-use allotment with all required wrapping.
+     * @param signal Optional abort signal from the caller.
+     */
+    onAllotmentUnavailable(context: ContextT, retry: (context: ContextT) => SyncAcquireResult, signal?: AbortSignal): ResultT;
+    /**
+     * Called whenever any allotment is released (success, ignore, or drop).
+     * Blocking strategies use this to wake queued waiters.
+     */
+    onAllotmentReleased(): void;
+}
+export interface LimiterOptions<ContextT, RejResultT extends SyncAcquireResult | AsyncAcquireResult = SyncAcquireResult> {
+    limit?: AdaptiveLimit;
+    /**
+     * 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.
+     */
+    bypassResolver?: (context: ContextT) => boolean;
+    /**
+     * Strategy that decides whether a request gets a concurrency slot.
+     * Default: SemaphoreStrategy.
+     */
+    acquireStrategy?: AcquireStrategy<ContextT>;
+    /**
+     * Strategy that decides what happens when the acquire strategy rejects a
+     * request. When omitted, rejected requests immediately receive `undefined`.
+     */
+    allotmentUnavailableStrategy?: AllotmentUnavailableStrategy<ContextT, RejResultT>;
+}
+/**
+ * Concurrency limiter with pluggable strategies for gating decisions and
+ * rejection handling.
+ *
+ * When no rejection strategy is provided, `acquire()` returns synchronously
+ * (`LimitAllotment | undefined`). When a blocking rejection strategy is
+ * configured, `acquire()` may also return a `Promise`.
+ *
+ * @typeParam ContextT Request context type (e.g. partition key).
+ * @typeParam RejResultT The result type produced by the rejection strategy.
+ */
+export declare class Limiter<Context = void, AcquireResult extends SyncAcquireResult | AsyncAcquireResult = SyncAcquireResult> {
+    private _inflight;
+    private _limit;
+    private readonly clock;
+    private readonly limitAlgorithm;
+    private readonly acquireStrategy;
+    private readonly rejectionStrategy;
+    private readonly bypassResolver;
+    private readonly successCounter;
+    private readonly droppedCounter;
+    private readonly ignoredCounter;
+    private readonly rejectedCounter;
+    private readonly bypassCounter;
+    static makeDefaultLimit(): AdaptiveLimit;
+    constructor(options?: LimiterOptions<Context, AcquireResult>);
+    acquire(options?: AcquireOptions<Context>): SyncAcquireResult | AcquireResult;
+    private tryAcquireCore;
+    private createAllotment;
+    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;
+}
+/**
+ * Run a callback when an acquire result is ready. If the result is a Promise,
+ * waits asynchronously; otherwise invokes the callback synchronously.
+ */
+export declare function whenAcquireSettled(result: AcquireResult, callback: (allotment: LimitAllotment | undefined) => void): 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>;
+}
+/**
+ * Creates a helper that runs callbacks under acquired limiter allotments.
+ *
+ * - If {@link Limiter.acquire} yields no allotment, returns
+ *   {@link QuotaNotAvailable} without invoking `fn`.
+ * - On {@link RunResult} `success` / `ignore`, returns the carried value after
+ *   reporting to the allotment.
+ * - On `dropped`, reports drop and throws the carried error.
+ * - On uncaught exceptions from `fn`, reports ignore and rethrows, except for
+ *   {@link AdaptiveTimeoutError}, which reports drop and rethrows.
+ * - Callback receives `{ context, signal }` from acquire options.
+ */
+export declare function withLimiter<ContextT, RejResultT extends SyncAcquireResult | AsyncAcquireResult>(limiter: Limiter<ContextT, RejResultT>): LimitedFunction<ContextT>;
+/**
+ * Synchronous try-acquire interface. A `Limiter<Ctx>` (with default sync
+ * rejection) is structurally compatible with this interface.
+ */
+export interface SyncLimiter<ContextT = void> {
+    acquire(options?: AcquireOptions<ContextT>): LimitAllotment | undefined;
+}
+//# sourceMappingURL=Limiter.d.ts.map

package/dist/Limiter.d.ts.map

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

package/dist/Limiter.js

@@ -0,0 +1,240 @@
+import { GradientLimit } from "./limit/GradientLimit.js";
+import { MetricIds, NoopMetricRegistry } from "./MetricRegistry.js";
+import { isAdaptiveTimeoutError, QuotaNotAvailable, } from "./RunResult.js";
+// ---------------------------------------------------------------------------
+// Limiter options
+// ---------------------------------------------------------------------------
+const NOOP_ALLOTMENT = {
+    reportSuccess() { },
+    reportIgnore() { },
+    reportDropped() { },
+};
+let idCounter = 0;
+/**
+ * Concurrency limiter with pluggable strategies for gating decisions and
+ * rejection handling.
+ *
+ * When no rejection strategy is provided, `acquire()` returns synchronously
+ * (`LimitAllotment | undefined`). When a blocking rejection strategy is
+ * configured, `acquire()` may also return a `Promise`.
+ *
+ * @typeParam ContextT Request context type (e.g. partition key).
+ * @typeParam RejResultT The result type produced by the rejection strategy.
+ */
+export class Limiter {
+    _inflight = 0;
+    _limit;
+    clock;
+    limitAlgorithm;
+    acquireStrategy;
+    rejectionStrategy;
+    bypassResolver;
+    successCounter;
+    droppedCounter;
+    ignoredCounter;
+    rejectedCounter;
+    bypassCounter;
+    static makeDefaultLimit() {
+        return new GradientLimit();
+    }
+    constructor(options = {}) {
+        this.clock = options.clock ?? (() => performance.now());
+        this.limitAlgorithm = options.limit ?? Limiter.makeDefaultLimit();
+        this._limit = this.limitAlgorithm.currentLimit;
+        this.bypassResolver = options.bypassResolver;
+        this.acquireStrategy =
+            options.acquireStrategy ?? new SemaphoreStrategy(this._limit);
+        this.rejectionStrategy = options.allotmentUnavailableStrategy;
+        this.limitAlgorithm.subscribe((newLimit) => {
+            const oldLimit = this._limit;
+            this._limit = newLimit;
+            this.acquireStrategy.onLimitChanged?.(oldLimit, newLimit);
+        });
+        const registry = options.metricRegistry ?? NoopMetricRegistry;
+        const limiterName = options.name ?? `unnamed-${++idCounter}`;
+        registry.gauge(MetricIds.LIMIT_NAME, () => this._limit);
+        this.successCounter = registry.counter(MetricIds.CALL_NAME, {
+            id: limiterName,
+            status: "success",
+        });
+        this.droppedCounter = registry.counter(MetricIds.CALL_NAME, {
+            id: limiterName,
+            status: "dropped",
+        });
+        this.ignoredCounter = registry.counter(MetricIds.CALL_NAME, {
+            id: limiterName,
+            status: "ignored",
+        });
+        this.rejectedCounter = registry.counter(MetricIds.CALL_NAME, {
+            id: limiterName,
+            status: "rejected",
+        });
+        this.bypassCounter = registry.counter(MetricIds.CALL_NAME, {
+            id: limiterName,
+            status: "bypassed",
+        });
+    }
+    acquire(options) {
+        if (options?.signal?.aborted)
+            return undefined;
+        const ctx = (options?.context ?? undefined);
+        if (this.bypassResolver?.(ctx)) {
+            this.bypassCounter.increment();
+            return NOOP_ALLOTMENT;
+        }
+        const state = {
+            limit: this._limit,
+            inflight: this._inflight,
+        };
+        if (!this.acquireStrategy.tryAcquireAllotment(ctx, state)) {
+            this.rejectedCounter.increment();
+            if (this.rejectionStrategy) {
+                return this.rejectionStrategy.onAllotmentUnavailable(ctx, (retryCtx) => this.tryAcquireCore(retryCtx), options?.signal);
+            }
+            return undefined;
+        }
+        return this.createAllotment(ctx);
+    }
+    tryAcquireCore(ctx) {
+        const state = {
+            limit: this._limit,
+            inflight: this._inflight,
+        };
+        if (!this.acquireStrategy.tryAcquireAllotment(ctx, state)) {
+            return undefined;
+        }
+        return this.createAllotment(ctx);
+    }
+    createAllotment(ctx) {
+        const startTime = this.clock();
+        const currentInflight = ++this._inflight;
+        return {
+            reportSuccess: () => {
+                this._inflight--;
+                this.acquireStrategy.onAllotmentReleased(ctx);
+                this.successCounter.increment();
+                this.limitAlgorithm.addSample(startTime, this.clock() - startTime, currentInflight, false);
+                this.rejectionStrategy?.onAllotmentReleased();
+            },
+            reportIgnore: () => {
+                this._inflight--;
+                this.acquireStrategy.onAllotmentReleased(ctx);
+                this.ignoredCounter.increment();
+                this.rejectionStrategy?.onAllotmentReleased();
+            },
+            reportDropped: () => {
+                this._inflight--;
+                this.acquireStrategy.onAllotmentReleased(ctx);
+                this.droppedCounter.increment();
+                this.limitAlgorithm.addSample(startTime, this.clock() - startTime, currentInflight, true);
+                this.rejectionStrategy?.onAllotmentReleased();
+            },
+        };
+    }
+    getLimit() {
+        return this._limit;
+    }
+    getInflight() {
+        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;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helper: whenAcquireSettled
+// ---------------------------------------------------------------------------
+/**
+ * Run a callback when an acquire result is ready. If the result is a Promise,
+ * waits asynchronously; otherwise invokes the callback synchronously.
+ */
+export function whenAcquireSettled(result, callback) {
+    if (result !== null &&
+        typeof result === "object" &&
+        "then" in result &&
+        typeof result.then ===
+            "function") {
+        void result.then(callback);
+    }
+    else {
+        callback(result);
+    }
+}
+/**
+ * Creates a helper that runs callbacks under acquired limiter allotments.
+ *
+ * - If {@link Limiter.acquire} yields no allotment, returns
+ *   {@link QuotaNotAvailable} without invoking `fn`.
+ * - On {@link RunResult} `success` / `ignore`, returns the carried value after
+ *   reporting to the allotment.
+ * - On `dropped`, reports drop and throws the carried error.
+ * - On uncaught exceptions from `fn`, reports ignore and rethrows, except for
+ *   {@link AdaptiveTimeoutError}, which reports 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 allotment = await Promise.resolve(limiter.acquire(options));
+        if (!allotment) {
+            return QuotaNotAvailable;
+        }
+        const [result] = await Promise.allSettled([
+            fn({
+                context: options?.context,
+                signal: options?.signal,
+            }),
+        ]);
+        if (result.status === "rejected") {
+            if (isAdaptiveTimeoutError(result.reason)) {
+                allotment.reportDropped();
+            }
+            else {
+                allotment.reportIgnore();
+            }
+            throw result.reason;
+        }
+        const outcome = result.value;
+        switch (outcome.kind) {
+            case "success":
+                allotment.reportSuccess();
+                return outcome.value;
+            case "ignore":
+                allotment.reportIgnore();
+                return outcome.value;
+            case "dropped":
+                allotment.reportDropped();
+                throw outcome.error;
+        }
+    }
+    return limited;
+}

package/dist/Listener.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Callback interface for the result of a request. The caller must invoke
+ * exactly one of these methods when the operation completes.
+ */
+export interface Listener {
+    /**
+     * Notification that the operation succeeded and internally measured latency
+     * should be used as an RTT sample.
+     */
+    onSuccess(): void;
+    /**
+     * The operation failed before any meaningful RTT measurement could be made
+     * and should be ignored to not introduce an artificially low RTT.
+     */
+    onIgnore(): void;
+    /**
+     * The request failed and was dropped due to being rejected by an external
+     * limit or hitting a timeout. Loss based StreamingLimit implementations will
+     * likely do an aggressive reduction in limit when this happens.
+     */
+    onDropped(): void;
+}
+//# sourceMappingURL=Listener.d.ts.map

package/dist/Listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Listener.d.ts","sourceRoot":"","sources":["../src/Listener.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,SAAS,IAAI,IAAI,CAAC;IAElB;;;OAGG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;;OAIG;IACH,SAAS,IAAI,IAAI,CAAC;CACnB"}

package/dist/Listener.js

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

package/dist/ListenerSet.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Fan-out for numeric change notifications with the same subscribe contract as
+ * {@link StreamingLimit.subscribe}.
+ */
+export declare class ListenerSet<T extends (this: void, ...args: any[]) => any> {
+    private readonly listeners;
+    subscribe(consumer: T, options?: {
+        signal?: AbortSignal;
+    }): () => void;
+    notify(...args: Parameters<T>): void;
+}
+//# sourceMappingURL=ListenerSet.d.ts.map

package/dist/ListenerSet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ListenerSet.d.ts","sourceRoot":"","sources":["../src/ListenerSet.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAE1C,SAAS,CACP,QAAQ,EAAE,CAAC,EACX,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrC,MAAM,IAAI;IA6Bb,MAAM,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;CAKrC"}

package/dist/ListenerSet.js

@@ -0,0 +1,35 @@
+/**
+ * Fan-out for numeric change notifications with the same subscribe contract as
+ * {@link StreamingLimit.subscribe}.
+ */
+export class ListenerSet {
+    listeners = [];
+    subscribe(consumer, options = {}) {
+        if (options.signal?.aborted) {
+            return () => { };
+        }
+        this.listeners.push(consumer);
+        let unsubscribed = false;
+        const onAbort = () => {
+            unsubscribe();
+        };
+        const unsubscribe = () => {
+            if (unsubscribed) {
+                return;
+            }
+            unsubscribed = true;
+            const idx = this.listeners.indexOf(consumer);
+            if (idx !== -1) {
+                this.listeners.splice(idx, 1);
+            }
+            options.signal?.removeEventListener("abort", onAbort);
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        return unsubscribe;
+    }
+    notify(...args) {
+        for (const listener of this.listeners) {
+            listener(...args);
+        }
+    }
+}

package/dist/MetricIds.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Common metric ids used by the limiters and limit algorithms.
+ */
+export declare const MetricIds: {
+    readonly LIMIT_NAME: "limit";
+    readonly CALL_NAME: "call";
+    readonly INFLIGHT_NAME: "inflight";
+    readonly PARTITION_LIMIT_NAME: "limit.partition";
+    readonly MIN_RTT_NAME: "min_rtt";
+    readonly WINDOW_MIN_RTT_NAME: "min_window_rtt";
+    readonly WINDOW_QUEUE_SIZE_NAME: "queue_size";
+};
+//# sourceMappingURL=MetricIds.d.ts.map

package/dist/MetricIds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetricIds.d.ts","sourceRoot":"","sources":["../src/MetricIds.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;CAQZ,CAAC"}

package/dist/MetricIds.js

@@ -0,0 +1,12 @@
+/**
+ * Common metric ids used by the limiters and limit algorithms.
+ */
+export const MetricIds = {
+    LIMIT_NAME: "limit",
+    CALL_NAME: "call",
+    INFLIGHT_NAME: "inflight",
+    PARTITION_LIMIT_NAME: "limit.partition",
+    MIN_RTT_NAME: "min_rtt",
+    WINDOW_MIN_RTT_NAME: "min_window_rtt",
+    WINDOW_QUEUE_SIZE_NAME: "queue_size",
+};

package/dist/MetricRegistry.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Common metric ids used by the limiters and limit algorithms.
+ */
+export declare const MetricIds: {
+    readonly LIMIT_NAME: "limit";
+    readonly CALL_NAME: "call";
+    readonly INFLIGHT_NAME: "inflight";
+    readonly PARTITION_LIMIT_NAME: "limit.partition";
+    readonly MIN_RTT_NAME: "min_rtt";
+    readonly WINDOW_MIN_RTT_NAME: "min_window_rtt";
+    readonly WINDOW_QUEUE_SIZE_NAME: "queue_size";
+};
+/**
+ * Listener to receive samples for a distribution.
+ */
+export interface DistributionMetric {
+    addSample(value: number): void;
+}
+/**
+ * A counter that can be incremented when an event occurs. Counters normally
+ * translate into an actions-per-second metric.
+ */
+export interface Counter {
+    increment(): void;
+}
+/** Opaque handle for a registered gauge (supplier is polled by the registry on flush). */
+export interface GaugeMetric {
+}
+/**
+ * Simple abstraction for tracking metrics in the limiters.
+ */
+export interface MetricRegistry {
+    /**
+     * Register a sample distribution. Samples are added to the distribution via
+     * the returned {@link DistributionMetric}. Will reuse an existing
+     * {@link DistributionMetric} if the distribution already exists.
+     *
+     * @param id Metric identifier
+     * @param tagNameValuePairs Pairs of tag name and tag value
+     * @returns SampleListener for the caller to add samples
+     */
+    distribution(id: string, ...tagNameValuePairs: string[]): DistributionMetric;
+    /**
+     * Register a gauge using the provided supplier. The supplier will be polled
+     * whenever the gauge value is flushed by the registry.
+     *
+     * @param id Metric identifier
+     * @param supplier Function that returns the current gauge value
+     * @param tagNameValuePairs Pairs of tag name and tag value
+     * @returns Registration handle for the gauge
+     */
+    gauge(id: string, supplier: () => number, ...tagNameValuePairs: string[]): GaugeMetric;
+    /**
+     * Create a counter that will be incremented when an event occurs.
+     *
+     * @param id Metric identifier
+     * @param attributes Counter attributes/tags
+     */
+    counter(id: string, attributes: Record<string, string>): Counter;
+}
+/**
+ * No-op MetricRegistry that discards all metrics. Used as the default when
+ * no registry is configured.
+ */
+export declare const NoopMetricRegistry: MetricRegistry;
+//# sourceMappingURL=MetricRegistry.d.ts.map