@adaptive-concurrency/redis 0.1.0 → 0.1.1

package/dist/RedisTokenBucket.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Minimal Redis client surface used for token-bucket operations.
+ *
+ * Implementations only need to expose `SCRIPT LOAD` + `EVALSHA`, which the
+ * standard `redis` (node-redis) client already provides via `scriptLoad` and
+ * `evalSha` with the same signatures used here. This minimal interface lets
+ * this package work with any Redis client without a hard dependency on a
+ * specific one.
+ */
+export type RedisTokenBucketClient = {
+    scriptLoad(script: string): Promise<string>;
+    evalSha(sha: string, options: {
+        keys: string[];
+        arguments: string[];
+    }): Promise<unknown>;
+};
+export type RedisTokenBucketConfig = {
+    /** Redis key prefix, e.g., "emr-ratelimit:axiscare-api". */
+    keyPrefix: string;
+    /** Max tokens in the bucket. */
+    maxTokens: number;
+    /** Refill interval in ms (time to refill an empty bucket back to maxTokens). */
+    refillIntervalMs: number;
+    /**
+     * Optional callback invoked when a Redis call fails. The bucket degrades
+     * gracefully on Redis failures (allowing the request through), so this is
+     * how callers can plug in their own logger/metrics for visibility.
+     *
+     * `tryAcquire` and `refund` do not await the callback before returning,
+     * so a slow async logger can't add latency to the request path.
+     * Synchronous throws and rejected promises returned from the callback
+     * are both swallowed — the callback is observability-only and must not
+     * be able to break the bucket's "always degrades gracefully" contract.
+     */
+    onError?: (info: {
+        keyPrefix: string;
+        key: string;
+        error: unknown;
+    }) => void;
+    /**
+     * Source of the current time, in epoch milliseconds, passed to the acquire
+     * script as `nowMs`. Defaults to `Date.now`.
+     *
+     * This MUST be a wall-clock source (not a monotonic one like
+     * `performance.now`): the bucket is shared across processes, so every
+     * participant has to agree on what "now" means for the refill math to line
+     * up. The seam exists primarily so tests can drive refill/wait-time logic
+     * deterministically.
+     */
+    clock?: () => number;
+};
+export type AcquireResult = {
+    acquired: true;
+} | {
+    acquired: false;
+    waitMs: number;
+};
+export declare class RedisTokenBucket {
+    #private;
+    constructor(redisClient: RedisTokenBucketClient, config: RedisTokenBucketConfig);
+    /**
+     * Attempt to acquire a token for the given key.
+     * If Redis is unavailable, degrades gracefully by allowing the request.
+     */
+    tryAcquire(key: string): Promise<AcquireResult>;
+    /**
+     * Refund a previously-acquired token back to the bucket. Use this when a
+     * downstream gate rejects a request after `tryAcquire` already consumed a
+     * token, so the configured rate is preserved.
+     *
+     * If Redis is unavailable, degrades gracefully: the refund is silently
+     * dropped (the token will refill naturally over `refillIntervalMs`).
+     */
+    refund(key: string): Promise<void>;
+}
+//# sourceMappingURL=RedisTokenBucket.d.ts.map

package/dist/RedisTokenBucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisTokenBucket.d.ts","sourceRoot":"","sources":["../src/RedisTokenBucket.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO,CACL,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,GAC/C,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB,CAAC;AAqHF,MAAM,MAAM,sBAAsB,GAAG;IACnC,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IAC7E;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAClB;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,qBAAa,gBAAgB;;gBAOzB,WAAW,EAAE,sBAAsB,EACnC,MAAM,EAAE,sBAAsB;IAsBhC;;;OAGG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAyBrD;;;;;;;OAOG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAqCzC"}

package/dist/RedisTokenBucket.js

@@ -0,0 +1,249 @@
+/**
+ * Lua script for atomic token bucket acquire.
+ *
+ * Loaded once per process via SCRIPT LOAD; executions use EVALSHA so the
+ * script source is not sent on every tryAcquire (see RedisTokenBucket).
+ *
+ * KEYS[1] = bucket key (e.g., "myratelimit:tenant-1234")
+ * ARGV[1] = maxTokens
+ * ARGV[2] = refillIntervalMs
+ * ARGV[3] = current time in ms
+ *
+ * Note: We expire the key after refillIntervalMs. Because refillIntervalMs is
+ * the time it takes to refill an empty bucket to maxTokens, so we KNOW that a
+ * bucket that's been untouched for refillIntervalMs is full. Therefore, it's
+ * safe to expire the key because it'll get recreated with a full bucket.
+ *
+ * Allowing the caller to provide an expiry time less than refillIntervalMs
+ * would risk the following scenario: a key untouched for expiry time ms has
+ * _fewer_ than a full bucket worth of tokens, then expires, then gets recreated
+ * with a full bucket, allowing the caller to exceed the intended rate limit.
+ *
+ * The code could compute a _dynamic_ expiry time based on the number of tokens
+ * in the bucket (i.e., at current token count, how long until the bucket is
+ * full?). This isn't worth the complexity though, nor is it an unambiguous win:
+ * it reclaims Redis memory faster, but slows down some acquires as the bucket
+ * key needs to be recreated.
+ *
+ * Returns:
+ *   - [1, 0] if token acquired successfully
+ *   - [0, waitTimeMs] if no tokens available, caller should wait waitTimeMs
+ */
+const TOKEN_BUCKET_LUA = `
+local key = KEYS[1]
+local maxTokens = tonumber(ARGV[1])
+local refillIntervalMs = tonumber(ARGV[2])
+local nowMs = tonumber(ARGV[3])
+
+local bucket = redis.call('HMGET', key, 'tokens', 'lastRefillMs')
+local tokens = tonumber(bucket[1])
+local lastRefillMs = tonumber(bucket[2])
+
+-- Initialize bucket if it doesn't exist
+if tokens == nil or lastRefillMs == nil then
+  tokens = maxTokens - 1
+  redis.call('HMSET', key, 'tokens', tokens, 'lastRefillMs', nowMs)
+  redis.call('PEXPIRE', key, refillIntervalMs)
+  return {1, 0}
+end
+
+-- Calculate refill: proportional tokens based on elapsed time
+local elapsedMs = nowMs - lastRefillMs
+local tokensToAdd = math.floor(elapsedMs * maxTokens / refillIntervalMs)
+
+if tokensToAdd > 0 then
+  tokens = math.min(maxTokens, tokens + tokensToAdd)
+  lastRefillMs = lastRefillMs + math.floor(tokensToAdd * refillIntervalMs / maxTokens)
+end
+
+-- Try to consume a token
+if tokens >= 1 then
+  tokens = tokens - 1
+  redis.call('HMSET', key, 'tokens', tokens, 'lastRefillMs', lastRefillMs)
+  redis.call('PEXPIRE', key, refillIntervalMs)
+  return {1, 0}
+end
+
+-- No tokens: compute wait time until next token refills
+local msPerToken = refillIntervalMs / maxTokens
+local waitMs = math.ceil(msPerToken - (nowMs - lastRefillMs))
+if waitMs < 0 then waitMs = 0 end
+
+redis.call('PEXPIRE', key, refillIntervalMs)
+return {0, waitMs}
+`;
+/**
+ * Lua script that refunds a previously-acquired token to the bucket. Used
+ * when a downstream gate rejects a request whose token has already been
+ * consumed (see RedisTokenBucketStrategy's bucket-first fallback path), so
+ * that the token isn't lost and the configured rate is preserved.
+ *
+ * Refund increments the token count by 1, capped at maxTokens. If the bucket
+ * key doesn't exist, the script is a no-op: an absent key implicitly
+ * represents a full bucket on next access (see TOKEN_BUCKET_LUA), so there's
+ * nothing to put back. We refresh the PEXPIRE on a successful refund so the
+ * key continues to live at least one full refill interval — same invariant
+ * the acquire script relies on.
+ *
+ * KEYS[1] = bucket key
+ * ARGV[1] = maxTokens
+ * ARGV[2] = refillIntervalMs
+ *
+ * Returns:
+ *   - 1 if a token was refunded
+ *   - 0 if the bucket was already at maxTokens or didn't exist
+ */
+const TOKEN_BUCKET_REFUND_LUA = `
+local key = KEYS[1]
+local maxTokens = tonumber(ARGV[1])
+local refillIntervalMs = tonumber(ARGV[2])
+
+local tokens = tonumber(redis.call('HGET', key, 'tokens'))
+if tokens == nil then
+  return 0
+end
+
+if tokens < maxTokens then
+  redis.call('HINCRBY', key, 'tokens', 1)
+  redis.call('PEXPIRE', key, refillIntervalMs)
+  return 1
+end
+
+return 0
+`;
+export class RedisTokenBucket {
+    #config;
+    #clock;
+    #acquireTokenScript;
+    #refundTokenScript;
+    constructor(redisClient, config) {
+        if (!Number.isSafeInteger(config.maxTokens) || config.maxTokens <= 0) {
+            throw new RangeError("maxTokens must be a positive safe integer");
+        }
+        if (!Number.isSafeInteger(config.refillIntervalMs) ||
+            config.refillIntervalMs <= 0) {
+            throw new RangeError("refillIntervalMs must be a positive safe integer");
+        }
+        this.#config = config;
+        this.#clock = config.clock ?? Date.now;
+        this.#acquireTokenScript = new RedisScript(redisClient, TOKEN_BUCKET_LUA);
+        this.#refundTokenScript = new RedisScript(redisClient, TOKEN_BUCKET_REFUND_LUA);
+    }
+    /**
+     * Attempt to acquire a token for the given key.
+     * If Redis is unavailable, degrades gracefully by allowing the request.
+     */
+    async tryAcquire(key) {
+        const redisKey = `${this.#config.keyPrefix}:${key}`;
+        try {
+            const result = await this.#acquireTokenScript.evaluate({
+                keys: [redisKey],
+                arguments: [
+                    String(this.#config.maxTokens),
+                    String(this.#config.refillIntervalMs),
+                    String(this.#clock()),
+                ],
+            });
+            if (result[0] === 1) {
+                return { acquired: true };
+            }
+            return { acquired: false, waitMs: result[1] ?? 0 };
+        }
+        catch (error) {
+            this.#fireOnError(key, error);
+            // Degrade gracefully: allow the request through.
+            return { acquired: true };
+        }
+    }
+    /**
+     * Refund a previously-acquired token back to the bucket. Use this when a
+     * downstream gate rejects a request after `tryAcquire` already consumed a
+     * token, so the configured rate is preserved.
+     *
+     * If Redis is unavailable, degrades gracefully: the refund is silently
+     * dropped (the token will refill naturally over `refillIntervalMs`).
+     */
+    async refund(key) {
+        const redisKey = `${this.#config.keyPrefix}:${key}`;
+        try {
+            await this.#refundTokenScript.evaluate({
+                keys: [redisKey],
+                arguments: [
+                    String(this.#config.maxTokens),
+                    String(this.#config.refillIntervalMs),
+                ],
+            });
+        }
+        catch (error) {
+            this.#fireOnError(key, error);
+        }
+    }
+    /**
+     * Invoke the user-supplied `onError` callback fire-and-forget style:
+     *
+     * - We do **not** await it, so a slow async logger can't extend the
+     *   latency of the request path. Synchronous side effects of the
+     *   callback (the typical `errors.push(...)` shape) still happen before
+     *   this method returns, since the call itself is synchronous.
+     * - If the callback throws synchronously OR returns a rejected promise,
+     *   the resulting rejection is swallowed inside `fireAndForget` so it
+     *   can't surface as an unhandled rejection.
+     *
+     * Both guarantees are contractually important: the bucket promises to
+     * degrade gracefully on Redis errors, and a misbehaving observer must
+     * not be able to break that promise.
+     */
+    #fireOnError(key, error) {
+        const onError = this.#config.onError;
+        if (!onError)
+            return;
+        const keyPrefix = this.#config.keyPrefix;
+        void fireAndForget(() => onError({ keyPrefix, key, error }));
+    }
+}
+class RedisScript {
+    #shaPromise; // undefined until first evaluate
+    #redisClient;
+    #lua;
+    constructor(redisClient, lua) {
+        this.#redisClient = redisClient;
+        this.#lua = lua;
+    }
+    async #ensureLoadedAndGetSha() {
+        if (this.#shaPromise === undefined) {
+            this.#shaPromise = this.#redisClient
+                .scriptLoad(this.#lua)
+                .catch((error) => {
+                this.#shaPromise = undefined;
+                throw error;
+            });
+        }
+        return await this.#shaPromise;
+    }
+    async evaluate(options) {
+        const sha = await this.#ensureLoadedAndGetSha();
+        try {
+            return (await this.#redisClient.evalSha(sha, options));
+        }
+        catch (error) {
+            // Reload the script if deleted or removed from redis cache.
+            if (isNoScriptError(error)) {
+                this.#shaPromise = undefined;
+                const newSha = await this.#ensureLoadedAndGetSha();
+                return (await this.#redisClient.evalSha(newSha, options));
+            }
+            throw error;
+        }
+    }
+}
+function isNoScriptError(error) {
+    return error instanceof Error && error.message.startsWith("NOSCRIPT");
+}
+async function fireAndForget(fn) {
+    try {
+        await fn();
+    }
+    catch {
+        // Ignore errors deliberately.
+    }
+}

package/dist/RedisTokenBucketStrategy.d.ts

@@ -0,0 +1,100 @@
+import { AllotmentReservation, type AcquireStrategy, type LimiterState } from "adaptive-concurrency";
+import type { RedisTokenBucket } from "./RedisTokenBucket.js";
+/**
+ * Higher-level acquire strategy that layers a distributed Redis token-bucket
+ * limit on top of any inner {@link AcquireStrategy} (e.g. `SemaphoreStrategy`,
+ * `PartitionedStrategy`). A request is admitted only when **both**:
+ *
+ * 1. The inner strategy reserves an allotment (its own local rules), and
+ * 2. The Redis token bucket grants a token (a fleet-wide rate limit of tokens
+ *    per `refillIntervalMs` shared across processes).
+ *
+ * **Ordering.** The inner runs first. Reservation is contractually
+ * side-effect free beyond admission bookkeeping, so a bucket denial cancels
+ * the inner reservation cleanly with no observable trace (no metric pollution,
+ * no waiter notifications). Reservation is also typically synchronous and
+ * cheap, so cheap-rejecting locally before paying the Redis round trip is a
+ * win on the rejection path.
+ *
+ * **Caveats.** Between the inner reserve and the bucket reply the inner
+ * strategy is briefly "more full" than it really is. Concurrent acquires can
+ * be falsely rejected by the inner during that ~RTT window — most visible at
+ * small inner limits. This is inherent to the inner-first ordering.
+ *
+ * **Failure handling.**
+ *
+ * - If Redis is unavailable, the underlying {@link RedisTokenBucket} degrades
+ *   gracefully (treats `tryAcquire` as granted, silently drops `refund`), so
+ *   this strategy effectively falls back to inner-only behavior.
+ *
+ * - **Inner `cancel()` throws** (after the bucket has denied, or the outer
+ *   reservation is later cancelled): the error is swallowed and surfaced via
+ *   `onReservationError({ phase: "cancel", ... })`. The strategy still
+ *   returns `undefined` (or completes the cancel) — matching `Limiter`'s
+ *   defensive release-error handling so a flaky inner can't turn a bucket
+ *   denial into a thrown `acquire()`. The inner's reservation is leaked
+ *   (decremented permits/inflight that never get restored).
+ *
+ * - **Inner `commit()` throws** (during the outer reservation's `commit()`):
+ *   the bucket token is refunded (always safe — bucket is rate-based), the
+ *   error is surfaced via `onReservationError({ phase: "commit", ... })`,
+ *   and the error is **re-thrown**. Unlike a cancel-throw, we hadn't yet
+ *   decided to reject, so quietly swallowing would hide a genuine
+ *   inner-strategy fault; propagation makes it visible to the caller. The
+ *   inner's reservation is in an indeterminate state and may be leaked.
+ *
+ * Limit change and release events are forwarded to the inner strategy.
+ */
+/**
+ * Information passed to {@link RedisTokenBucketStrategyOptions.onReservationError}
+ * when the inner's reservation transition fails.
+ */
+export type ReservationErrorInfo<ContextT> = {
+    context: ContextT;
+    /**
+     * Which transition threw:
+     * - `"cancel"`: the inner's `reservation.cancel()` threw while undoing the
+     *   speculative reservation (because the bucket denied, or because the
+     *   outer reservation was cancelled). The strategy continues; the inner's
+     *   reservation is leaked.
+     * - `"commit"`: the inner's `reservation.commit()` threw while finalizing
+     *   the outer reservation. The bucket token has been refunded; the error
+     *   is re-thrown to the caller after this hook returns.
+     */
+    phase: "cancel" | "commit";
+    error: unknown;
+};
+export declare class RedisTokenBucketStrategy<ContextT> {
+    #private;
+    constructor(options: {
+        /** Token bucket used as the second gate. */
+        bucket: RedisTokenBucket;
+        /**
+         * Inner acquire strategy. Consulted *before* the bucket: its reservation
+         * is committed when the bucket grants and cancelled when the bucket
+         * denies. Must be a two-phase {@link AcquireStrategy}.
+         */
+        inner: AcquireStrategy<ContextT>;
+        /**
+         * Derives the bucket sub-key from the request context. Use this to maintain
+         * separate buckets per tenant, route, etc. When omitted, all acquires share
+         * a single `"default"` bucket.
+         */
+        keyResolver?: (context: ContextT) => string;
+        /**
+         * Invoked when the inner's `reservation.cancel()` or `reservation.commit()`
+         * throws. Lets callers wire up logging/metrics. Behavior per phase:
+         *
+         * - `"cancel"`: error is swallowed; the strategy continues with its
+         *   rejection (the bucket already denied, or the outer cancelled). The
+         *   inner's reservation is leaked.
+         * - `"commit"`: bucket token is refunded, then the error is re-thrown so
+         *   the caller can see the strategy fault.
+         */
+        onReservationError?: (info: ReservationErrorInfo<ContextT>) => void;
+    });
+    tryReserveAllotment(context: ContextT, state: LimiterState): Promise<AllotmentReservation | undefined>;
+    onAllotmentReleased(context: ContextT): ReturnType<AcquireStrategy<ContextT>["onAllotmentReleased"]>;
+    onLimitChanged(oldLimit: number, newLimit: number): void;
+}
+//# sourceMappingURL=RedisTokenBucketStrategy.d.ts.map

package/dist/RedisTokenBucketStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisTokenBucketStrategy.d.ts","sourceRoot":"","sources":["../src/RedisTokenBucketStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,QAAQ,IAAI;IAC3C,OAAO,EAAE,QAAQ,CAAC;IAClB;;;;;;;;;OASG;IACH,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,qBAAa,wBAAwB,CAAC,QAAQ;;gBAShC,OAAO,EAAE;QACnB,4CAA4C;QAC5C,MAAM,EAAE,gBAAgB,CAAC;QACzB;;;;WAIG;QACH,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;QACjC;;;;WAIG;QACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,CAAC;QAC5C;;;;;;;;;WASG;QACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;KACrE;IAOK,mBAAmB,CACvB,OAAO,EAAE,QAAQ,EACjB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC;IAsD5C,mBAAmB,CACjB,OAAO,EAAE,QAAQ,GAChB,UAAU,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,qBAAqB,CAAC,CAAC;IAI/D,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;CAqCzD"}

package/dist/RedisTokenBucketStrategy.js

@@ -0,0 +1,104 @@
+import { AllotmentReservation, } from "adaptive-concurrency";
+export class RedisTokenBucketStrategy {
+    #bucket;
+    #keyResolver;
+    #onReservationError;
+    #inner;
+    constructor(options) {
+        this.#bucket = options.bucket;
+        this.#inner = options.inner;
+        this.#keyResolver = options.keyResolver ?? defaultKeyResolver;
+        this.#onReservationError = options.onReservationError;
+    }
+    async tryReserveAllotment(context, state) {
+        const key = this.#keyResolver(context);
+        const reservation = await this.#inner.tryReserveAllotment(context, state);
+        if (!reservation) {
+            return undefined;
+        }
+        const result = await this.#bucket.tryAcquire(key);
+        if (!result.acquired) {
+            try {
+                await reservation.cancel();
+            }
+            catch (error) {
+                await this.#fireReservationError({ context, phase: "cancel", error });
+            }
+            return undefined;
+        }
+        // Both gates granted. Return a reservation that, on commit, commits the
+        // inner; on cancel, cancels the inner AND refunds the bucket token. The
+        // bucket-refund branch matters for nested composition (some outer
+        // strategy that wraps this one and may call cancel after both gates have
+        // already speculatively granted).
+        return new AllotmentReservation(async () => {
+            try {
+                await reservation.commit();
+            }
+            catch (error) {
+                // Inner is in an indeterminate state per the AllotmentReservation
+                // contract. The bucket token is purely ours to manage and refund is
+                // always safe (rate-based, not absolute), so refund it. We propagate
+                // the error rather than swallowing it because (unlike a cancel-throw
+                // on bucket-denied) the strategy genuinely failed to finalize and
+                // that's worth surfacing.
+                //
+                // Both side effects below are best-effort and isolated so a throw
+                // from either can't shadow `error` — the inner-commit failure is what
+                // the caller asked us to surface and we must guarantee it propagates.
+                await this.#refundQuietly(key);
+                await this.#fireReservationError({ context, phase: "commit", error });
+                throw error;
+            }
+        }, async () => {
+            try {
+                await reservation.cancel();
+            }
+            catch (error) {
+                await this.#fireReservationError({ context, phase: "cancel", error });
+            }
+            await this.#refundQuietly(key);
+        });
+    }
+    onAllotmentReleased(context) {
+        return this.#inner.onAllotmentReleased(context);
+    }
+    onLimitChanged(oldLimit, newLimit) {
+        this.#inner.onLimitChanged?.(oldLimit, newLimit);
+    }
+    /**
+     * Fire {@link #onReservationError} without ever throwing. The hook is
+     * observability-only; a throw from a misbehaving observer would otherwise
+     * shadow the genuinely interesting error (a bucket-denial cancel-throw,
+     * or an inner-commit failure that the commit-throw branch is contractually
+     * required to re-throw).
+     */
+    async #fireReservationError(info) {
+        try {
+            // wait in case the callback is async
+            await this.#onReservationError?.(info);
+        }
+        catch {
+            // Swallowed deliberately.
+        }
+    }
+    /**
+     * Refund the bucket token without ever throwing. {@link RedisTokenBucket}
+     * already degrades gracefully on Redis errors, but we still isolate the
+     * call here so neither a future change in the bucket's contract nor an
+     * unexpected synchronous throw can leak out of the cancel/commit-failure
+     * paths and shadow more important errors.
+     */
+    async #refundQuietly(key) {
+        try {
+            await this.#bucket.refund(key);
+        }
+        catch {
+            // The un-refunded token will be restored by the next natural
+            // refill, so the long-run rate is preserved.
+        }
+    }
+}
+function defaultKeyResolver() {
+    return "default";
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { RedisTokenBucket, type AcquireResult, type RedisTokenBucketClient, type RedisTokenBucketConfig, } from "./RedisTokenBucket.js";
+export { RedisTokenBucketStrategy, type ReservationErrorInfo, } from "./RedisTokenBucketStrategy.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,wBAAwB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,+BAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { RedisTokenBucket, } from "./RedisTokenBucket.js";
+export { RedisTokenBucketStrategy, } from "./RedisTokenBucketStrategy.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adaptive-concurrency/redis",
   "description": "Redis-backed strategies for adaptive-concurrency (e.g. distributed token-bucket rate limiting).",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "exports": {
     ".": {
@@ -12,16 +12,17 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsc",
-    "test": "node --import tsx --test \"src/**/*.test.ts\""
-  },
   "peerDependencies": {
-    "adaptive-concurrency": "workspace:*"
+    "adaptive-concurrency": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "ioredis-mock": "^8.13.1",
     "tsx": "^4.19.0",
     "typescript": "^6.0.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx --test \"src/**/*.test.ts\""
   }
-}
+}