@commandkit/ratelimit 0.0.0-dev.20260317060555

package/dist/directive/use-ratelimit.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Runtime wrapper for the "use ratelimit" directive.
+ *
+ * Uses the runtime default limiter for arbitrary async functions.
+ * Throws RateLimitError when the call is limited.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.$ckitirl = void 0;
+const node_crypto_1 = require("node:crypto");
+const RateLimitEngine_1 = require("../engine/RateLimitEngine");
+const errors_1 = require("../errors");
+const config_1 = require("../utils/config");
+const runtime_1 = require("../runtime");
+const constants_1 = require("../constants");
+const RATELIMIT_FN_SYMBOL = Symbol('commandkit.ratelimit.directive');
+let cachedEngine = null;
+let cachedStorage = null;
+/**
+ * Resolve the cached engine instance for a storage backend.
+ *
+ * @param storage - Storage backend to associate with the engine.
+ * @returns Cached engine instance for the storage.
+ */
+function getEngine(storage) {
+    /**
+     * Cache per storage instance so violation tracking stays consistent.
+     */
+    if (!cachedEngine || cachedStorage !== storage) {
+        cachedEngine = new RateLimitEngine_1.RateLimitEngine(storage);
+        cachedStorage = storage;
+    }
+    return cachedEngine;
+}
+/**
+ * Apply an optional prefix to a storage key.
+ *
+ * @param prefix - Optional prefix to prepend.
+ * @param key - Base key to prefix.
+ * @returns Prefixed key.
+ */
+function withPrefix(prefix, key) {
+    if (!prefix)
+        return key;
+    return `${prefix}${key}`;
+}
+/**
+ * Append a window suffix to a key when a window id is present.
+ *
+ * @param key - Base storage key.
+ * @param windowId - Optional window identifier.
+ * @returns Key with window suffix when provided.
+ */
+function withWindowSuffix(key, windowId) {
+    if (!windowId)
+        return key;
+    return `${key}:w:${windowId}`;
+}
+/**
+ * Merge a runtime default limiter with an override when provided.
+ *
+ * @param runtimeDefault - Runtime default limiter configuration.
+ * @param limiter - Optional override limiter.
+ * @returns Resolved limiter configuration.
+ */
+function resolveLimiter(runtimeDefault, limiter) {
+    if (!limiter)
+        return runtimeDefault;
+    return (0, config_1.mergeLimiterConfigs)(runtimeDefault, limiter);
+}
+/**
+ * Wrap an async function with the runtime default limiter.
+ *
+ * Throws RateLimitError when the call exceeds limits.
+ *
+ * @template R - Argument tuple type for the wrapped async function.
+ * @template F - Async function type being wrapped.
+ * @param fn - Async function to wrap with rate limiting.
+ * @returns Wrapped async function that enforces the default limiter.
+ * @throws RateLimitError when the call exceeds limits.
+ */
+function useRateLimit(fn) {
+    if (Object.prototype.hasOwnProperty.call(fn, RATELIMIT_FN_SYMBOL)) {
+        return fn;
+    }
+    const fnId = (0, node_crypto_1.randomUUID)();
+    const wrapped = (async (...args) => {
+        const runtime = (0, runtime_1.getRateLimitRuntime)();
+        if (!runtime) {
+            throw new Error('RateLimit runtime is not initialized. Register the RateLimitPlugin first.');
+        }
+        const limiterConfig = resolveLimiter((0, config_1.mergeLimiterConfigs)(config_1.DEFAULT_LIMITER, runtime.defaultLimiter));
+        const key = `${constants_1.DEFAULT_KEY_PREFIX}fn:${fnId}`;
+        const finalKey = withPrefix(runtime.keyPrefix, key);
+        const engine = getEngine(runtime.storage);
+        const resolvedConfigs = (0, config_1.resolveLimiterConfigs)(limiterConfig, 'custom');
+        const results = [];
+        for (const resolved of resolvedConfigs) {
+            const resolvedKey = withWindowSuffix(finalKey, resolved.windowId);
+            const { result } = await engine.consume(resolvedKey, resolved);
+            results.push(result);
+        }
+        const aggregate = aggregateResults(results);
+        if (aggregate.limited) {
+            throw new errors_1.RateLimitError(aggregate);
+        }
+        return fn(...args);
+    });
+    Object.defineProperty(wrapped, RATELIMIT_FN_SYMBOL, {
+        value: true,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+    return wrapped;
+}
+/**
+ * Aggregate multiple rate-limit results into a single summary object.
+ *
+ * @param results - Individual limiter/window results.
+ * @returns Aggregated rate-limit store value.
+ */
+function aggregateResults(results) {
+    if (!results.length) {
+        return {
+            limited: false,
+            remaining: 0,
+            resetAt: 0,
+            retryAfter: 0,
+            results: [],
+        };
+    }
+    const limitedResults = results.filter((r) => r.limited);
+    const limited = limitedResults.length > 0;
+    const remaining = Math.min(...results.map((r) => r.remaining));
+    const resetAt = Math.max(...results.map((r) => r.resetAt));
+    const retryAfter = limited
+        ? Math.max(...limitedResults.map((r) => r.retryAfter))
+        : 0;
+    return {
+        limited,
+        remaining,
+        resetAt,
+        retryAfter,
+        results,
+    };
+}
+/**
+ * Wrapper symbol injected by the compiler plugin.
+ *
+ * @param fn - Generic function to wrap with runtime rate limiting.
+ * @returns Wrapped function that enforces the runtime default limiter.
+ */
+const $ckitirl = (fn) => {
+    return useRateLimit(fn);
+};
+exports.$ckitirl = $ckitirl;
+if (!('$ckitirl' in globalThis)) {
+    /**
+     * Expose the wrapper globally so directive transforms can call it.
+     */
+    Object.defineProperty(globalThis, '$ckitirl', {
+        value: exports.$ckitirl,
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXNlLXJhdGVsaW1pdC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kaXJlY3RpdmUvdXNlLXJhdGVsaW1pdC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7O0dBS0c7OztBQUVILDZDQUF5QztBQUV6QywrREFBNEQ7QUFDNUQsc0NBQTJDO0FBTzNDLDRDQUl5QjtBQUN6Qix3Q0FBaUQ7QUFDakQsNENBQWtEO0FBRWxELE1BQU0sbUJBQW1CLEdBQUcsTUFBTSxDQUFDLGdDQUFnQyxDQUFDLENBQUM7QUFFckUsSUFBSSxZQUFZLEdBQTJCLElBQUksQ0FBQztBQUNoRCxJQUFJLGFBQWEsR0FBNEIsSUFBSSxDQUFDO0FBRWxEOzs7OztHQUtHO0FBQ0gsU0FBUyxTQUFTLENBQUMsT0FBeUI7SUFDMUM7O09BRUc7SUFDSCxJQUFJLENBQUMsWUFBWSxJQUFJLGFBQWEsS0FBSyxPQUFPLEVBQUUsQ0FBQztRQUMvQyxZQUFZLEdBQUcsSUFBSSxpQ0FBZSxDQUFDLE9BQU8sQ0FBQyxDQUFDO1FBQzVDLGFBQWEsR0FBRyxPQUFPLENBQUM7SUFDMUIsQ0FBQztJQUNELE9BQU8sWUFBWSxDQUFDO0FBQ3RCLENBQUM7QUFFRDs7Ozs7O0dBTUc7QUFDSCxTQUFTLFVBQVUsQ0FBQyxNQUEwQixFQUFFLEdBQVc7SUFDekQsSUFBSSxDQUFDLE1BQU07UUFBRSxPQUFPLEdBQUcsQ0FBQztJQUN4QixPQUFPLEdBQUcsTUFBTSxHQUFHLEdBQUcsRUFBRSxDQUFDO0FBQzNCLENBQUM7QUFFRDs7Ozs7O0dBTUc7QUFDSCxTQUFTLGdCQUFnQixDQUFDLEdBQVcsRUFBRSxRQUFpQjtJQUN0RCxJQUFJLENBQUMsUUFBUTtRQUFFLE9BQU8sR0FBRyxDQUFDO0lBQzFCLE9BQU8sR0FBRyxHQUFHLE1BQU0sUUFBUSxFQUFFLENBQUM7QUFDaEMsQ0FBQztBQUVEOzs7Ozs7R0FNRztBQUNILFNBQVMsY0FBYyxDQUNyQixjQUFzQyxFQUN0QyxPQUFnQztJ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

package/dist/engine/RateLimitEngine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Engine coordinator.
+ *
+ * Selects algorithms and applies violation escalation before returning results.
+ */
+import type { RateLimitResult, RateLimitStorage, ResolvedLimiterConfig } from '../types';
+/**
+ * Consume output including optional violation count for callers.
+ */
+export interface RateLimitConsumeOutput {
+    result: RateLimitResult;
+    violationCount?: number;
+}
+/**
+ * Coordinates algorithm selection and violation escalation per storage.
+ */
+export declare class RateLimitEngine {
+    private readonly storage;
+    private readonly violations;
+    /**
+     * Create a rate limit engine bound to a storage backend.
+     *
+     * @param storage - Storage backend for rate-limit state.
+     */
+    constructor(storage: RateLimitStorage);
+    /**
+     * Create an algorithm instance for a resolved config.
+     *
+     * @param config - Resolved limiter configuration.
+     * @returns Algorithm instance for the resolved config.
+     */
+    private createAlgorithm;
+    /**
+     * Consume a single key and apply escalation rules when enabled.
+     *
+     * @param key - Storage key for the limiter.
+     * @param config - Resolved limiter configuration.
+     * @returns Result plus optional violation count.
+     */
+    consume(key: string, config: ResolvedLimiterConfig): Promise<RateLimitConsumeOutput>;
+    /**
+     * Reset a key and its associated violation state.
+     *
+     * @param key - Storage key to reset.
+     * @returns Resolves after the key and violations are cleared.
+     */
+    reset(key: string): Promise<void>;
+}

package/dist/engine/RateLimitEngine.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Engine coordinator.
+ *
+ * Selects algorithms and applies violation escalation before returning results.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitEngine = void 0;
+const fixed_window_1 = require("./algorithms/fixed-window");
+const sliding_window_1 = require("./algorithms/sliding-window");
+const token_bucket_1 = require("./algorithms/token-bucket");
+const leaky_bucket_1 = require("./algorithms/leaky-bucket");
+const violations_1 = require("./violations");
+/**
+ * Coordinates algorithm selection and violation escalation per storage.
+ */
+class RateLimitEngine {
+    /**
+     * Create a rate limit engine bound to a storage backend.
+     *
+     * @param storage - Storage backend for rate-limit state.
+     */
+    constructor(storage) {
+        this.storage = storage;
+        this.violations = new violations_1.ViolationTracker(storage);
+    }
+    /**
+     * Create an algorithm instance for a resolved config.
+     *
+     * @param config - Resolved limiter configuration.
+     * @returns Algorithm instance for the resolved config.
+     */
+    createAlgorithm(config) {
+        switch (config.algorithm) {
+            case 'fixed-window':
+                return new fixed_window_1.FixedWindowAlgorithm(this.storage, {
+                    maxRequests: config.maxRequests,
+                    intervalMs: config.intervalMs,
+                    scope: config.scope,
+                });
+            case 'sliding-window':
+                return new sliding_window_1.SlidingWindowLogAlgorithm(this.storage, {
+                    maxRequests: config.maxRequests,
+                    intervalMs: config.intervalMs,
+                    scope: config.scope,
+                });
+            case 'token-bucket':
+                return new token_bucket_1.TokenBucketAlgorithm(this.storage, {
+                    capacity: config.burst,
+                    refillRate: config.refillRate,
+                    scope: config.scope,
+                });
+            case 'leaky-bucket':
+                return new leaky_bucket_1.LeakyBucketAlgorithm(this.storage, {
+                    capacity: config.burst,
+                    leakRate: config.leakRate,
+                    scope: config.scope,
+                });
+            default:
+                /**
+                 * Fall back to fixed-window so unknown algorithms still enforce a limit.
+                 */
+                return new fixed_window_1.FixedWindowAlgorithm(this.storage, {
+                    maxRequests: config.maxRequests,
+                    intervalMs: config.intervalMs,
+                    scope: config.scope,
+                });
+        }
+    }
+    /**
+     * Consume a single key and apply escalation rules when enabled.
+     *
+     * @param key - Storage key for the limiter.
+     * @param config - Resolved limiter configuration.
+     * @returns Result plus optional violation count.
+     */
+    async consume(key, config) {
+        const now = Date.now();
+        const shouldEscalate = config.violations != null && config.violations.escalate !== false;
+        if (shouldEscalate) {
+            const active = await this.violations.checkCooldown(key);
+            if (active) {
+                /**
+                 * When an escalation cooldown is active, skip the algorithm to enforce the cooldown.
+                 */
+                const limit = config.algorithm === 'token-bucket' ||
+                    config.algorithm === 'leaky-bucket'
+                    ? config.burst
+                    : config.maxRequests;
+                const result = {
+                    key,
+                    scope: config.scope,
+                    algorithm: config.algorithm,
+                    limited: true,
+                    remaining: 0,
+                    resetAt: active.cooldownUntil,
+                    retryAfter: Math.max(0, active.cooldownUntil - now),
+                    limit,
+                    windowId: config.windowId,
+                };
+                return {
+                    result,
+                    violationCount: active.count,
+                };
+            }
+        }
+        const algorithm = this.createAlgorithm(config);
+        const result = await algorithm.consume(key);
+        if (config.windowId) {
+            result.windowId = config.windowId;
+        }
+        if (result.limited && shouldEscalate) {
+            const state = await this.violations.recordViolation(key, result.retryAfter, config.violations);
+            /**
+             * If escalation extends the cooldown, update the result so retry info stays accurate.
+             */
+            if (state.cooldownUntil > result.resetAt) {
+                result.resetAt = state.cooldownUntil;
+                result.retryAfter = Math.max(0, state.cooldownUntil - now);
+            }
+            return { result, violationCount: state.count };
+        }
+        return { result };
+    }
+    /**
+     * Reset a key and its associated violation state.
+     *
+     * @param key - Storage key to reset.
+     * @returns Resolves after the key and violations are cleared.
+     */
+    async reset(key) {
+        await this.storage.delete(key);
+        await this.violations.reset(key);
+    }
+}
+exports.RateLimitEngine = RateLimitEngine;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUmF0ZUxpbWl0RW5naW5lLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2VuZ2luZS9SYXRlTGltaXRFbmdpbmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7O0dBSUc7OztBQVNILDREQUFpRTtBQUNqRSxnRUFBd0U7QUFDeEUsNERBQWlFO0FBQ2pFLDREQUFpRTtBQUNqRSw2Q0FBZ0Q7QUFVaEQ7O0dBRUc7QUFDSCxNQUFhLGVBQWU7SUFHMUI7Ozs7T0FJRztJQUNILFlBQW9DLE9BQXlCO1FBQXpCLFlBQU8sR0FBUCxPQUFPLENBQWtCO1FBQzNELElBQUksQ0FBQyxVQUFVLEdBQUcsSUFBSSw2QkFBZ0IsQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUNsRCxDQUFDO0lBRUQ7Ozs7O09BS0c7SUFDSyxlQUFlLENBQUMsTUFBNkI7UUFDbkQsUUFBUSxNQUFNLENBQUMsU0FBUyxFQUFFLENBQUM7WUFDekIsS0FBSyxjQUFjO2dCQUNqQixPQUFPLElBQUksbUNBQW9CLENBQUMsSUFBSSxDQUFDLE9BQU8sRUFBRTtvQkFDNUMsV0FBVyxFQUFFLE1BQU0sQ0FBQyxXQUFXO29CQUMvQixVQUFVLEVBQUUsTUFBTSxDQUFDLFVBQVU7b0JBQzdCLEtBQUssRUFBRSxNQUFNLENBQUMsS0FBSztpQkFDcEIsQ0FBQyxDQUFDO1lBQ0wsS0FBSyxnQkFBZ0I7Z0JBQ25CLE9BQU8sSUFBSSwwQ0FBeUIsQ0FBQyxJQUFJLENBQUMsT0FBTyxFQUFFO29CQUNqRCxXQUFXLEVBQUUsTUFBTSxDQUFDLFdBQVc7b0JBQy9CLFVBQVUsRUFBRSxNQUFNLENBQUMsVUFBVTtvQkFDN0IsS0FBSyxFQUFFLE1BQU0sQ0FBQyxLQUFLO2lCQUNwQixDQUFDLENBQUM7WUFDTCxLQUFLLGNBQWM7Z0JBQ2pCLE9BQU8sSUFBSSxtQ0FBb0IsQ0FBQyxJQUFJLENBQUMsT0FBTyxFQUFFO29CQUM1QyxRQUFRLEVBQUUsTUFBTSxDQUFDLEtBQUs7b0JBQ3RCLFVBQVUs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

package/dist/engine/algorithms/fixed-window.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Fixed window rate limiting.
+ *
+ * Simple counters per window are fast and predictable, at the cost of allowing
+ * bursts within the window boundary. Prefer atomic storage for correctness.
+ */
+import type { RateLimitAlgorithm, RateLimitAlgorithmType, RateLimitResult, RateLimitStorage } from '../../types';
+interface FixedWindowConfig {
+    maxRequests: number;
+    intervalMs: number;
+    scope: RateLimitResult['scope'];
+}
+/**
+ * Basic fixed-window counter for low-cost rate limits.
+ *
+ * @implements RateLimitAlgorithm
+ */
+export declare class FixedWindowAlgorithm implements RateLimitAlgorithm {
+    private readonly storage;
+    private readonly config;
+    readonly type: RateLimitAlgorithmType;
+    /**
+     * Create a fixed-window algorithm bound to a storage backend.
+     *
+     * @param storage - Storage backend for rate-limit state.
+     * @param config - Fixed-window configuration.
+     */
+    constructor(storage: RateLimitStorage, config: FixedWindowConfig);
+    /**
+     * Record one attempt and return the current window status for this key.
+     *
+     * @param key - Storage key for the limiter.
+     * @returns Rate limit result for the current window.
+     */
+    consume(key: string): Promise<RateLimitResult>;
+    /**
+     * Reset the stored key state for this limiter.
+     *
+     * @param key - Storage key to reset.
+     * @returns Resolves after the key is deleted.
+     */
+    reset(key: string): Promise<void>;
+}
+export {};

package/dist/engine/algorithms/fixed-window.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Fixed window rate limiting.
+ *
+ * Simple counters per window are fast and predictable, at the cost of allowing
+ * bursts within the window boundary. Prefer atomic storage for correctness.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FixedWindowAlgorithm = void 0;
+const locking_1 = require("../../utils/locking");
+/**
+ * Basic fixed-window counter for low-cost rate limits.
+ *
+ * @implements RateLimitAlgorithm
+ */
+class FixedWindowAlgorithm {
+    /**
+     * Create a fixed-window algorithm bound to a storage backend.
+     *
+     * @param storage - Storage backend for rate-limit state.
+     * @param config - Fixed-window configuration.
+     */
+    constructor(storage, config) {
+        this.storage = storage;
+        this.config = config;
+        this.type = 'fixed-window';
+    }
+    /**
+     * Record one attempt and return the current window status for this key.
+     *
+     * @param key - Storage key for the limiter.
+     * @returns Rate limit result for the current window.
+     */
+    async consume(key) {
+        const limit = this.config.maxRequests;
+        const interval = this.config.intervalMs;
+        if (this.storage.consumeFixedWindow) {
+            const now = Date.now();
+            const { count, ttlMs } = await this.storage.consumeFixedWindow(key, limit, interval, now);
+            const resetAt = now + ttlMs;
+            const limited = count > limit;
+            return {
+                key,
+                scope: this.config.scope,
+                algorithm: this.type,
+                limited,
+                remaining: Math.max(0, limit - count),
+                resetAt,
+                retryAfter: limited ? Math.max(0, resetAt - now) : 0,
+                limit,
+            };
+        }
+        if (this.storage.incr) {
+            const now = Date.now();
+            const { count, ttlMs } = await this.storage.incr(key, interval);
+            const resetAt = now + ttlMs;
+            const limited = count > limit;
+            return {
+                key,
+                scope: this.config.scope,
+                algorithm: this.type,
+                limited,
+                remaining: Math.max(0, limit - count),
+                resetAt,
+                retryAfter: limited ? Math.max(0, resetAt - now) : 0,
+                limit,
+            };
+        }
+        /**
+         * Fallback is serialized per process to avoid same-instance races.
+         * Multi-process strictness still requires atomic storage operations.
+         */
+        return (0, locking_1.withStorageKeyLock)(this.storage, key, async () => {
+            const maxRetries = 5;
+            for (let attempt = 0; attempt < maxRetries; attempt++) {
+                const attemptNow = Date.now();
+                const existingRaw = await this.storage.get(key);
+                const existing = isFixedWindowState(existingRaw) ? existingRaw : null;
+                if (!existing || existing.resetAt <= attemptNow) {
+                    const resetAt = attemptNow + interval;
+                    const state = { count: 1, resetAt, version: 1 };
+                    const currentRaw = await this.storage.get(key);
+                    const current = isFixedWindowState(currentRaw) ? currentRaw : null;
+                    if (current && current.resetAt > attemptNow) {
+                        continue;
+                    }
+                    await this.storage.set(key, state, interval);
+                    const verifyRaw = await this.storage.get(key);
+                    const verify = isFixedWindowState(verifyRaw) ? verifyRaw : null;
+                    if ((verify?.version ?? 0) !== 1) {
+                        continue;
+                    }
+                    return {
+                        key,
+                        scope: this.config.scope,
+                        algorithm: this.type,
+                        limited: false,
+                        remaining: Math.max(0, limit - 1),
+                        resetAt,
+                        retryAfter: 0,
+                        limit,
+                    };
+                }
+                if (existing.count >= limit) {
+                    return {
+                        key,
+                        scope: this.config.scope,
+                        algorithm: this.type,
+                        limited: true,
+                        remaining: 0,
+                        resetAt: existing.resetAt,
+                        retryAfter: Math.max(0, existing.resetAt - attemptNow),
+                        limit,
+                    };
+                }
+                let nextState = {
+                    count: existing.count + 1,
+                    resetAt: existing.resetAt,
+                    version: (existing.version ?? 0) + 1,
+                };
+                const currentRaw = await this.storage.get(key);
+                const current = isFixedWindowState(currentRaw) ? currentRaw : null;
+                if (!current ||
+                    current.resetAt !== existing.resetAt ||
+                    current.count !== existing.count ||
+                    (current.version ?? 0) !== (existing.version ?? 0)) {
+                    continue;
+                }
+                let ttlMs = existing.resetAt - attemptNow;
+                if (ttlMs <= 0) {
+                    nextState = {
+                        count: 1,
+                        resetAt: attemptNow + interval,
+                        version: 1,
+                    };
+                    ttlMs = interval;
+                }
+                await this.storage.set(key, nextState, ttlMs);
+                const verifyRaw = await this.storage.get(key);
+                const verify = isFixedWindowState(verifyRaw) ? verifyRaw : null;
+                if ((verify?.version ?? 0) !== (nextState.version ?? 0)) {
+                    continue;
+                }
+                return {
+                    key,
+                    scope: this.config.scope,
+                    algorithm: this.type,
+                    limited: false,
+                    remaining: Math.max(0, limit - nextState.count),
+                    resetAt: nextState.resetAt,
+                    retryAfter: 0,
+                    limit,
+                };
+            }
+            const now = Date.now();
+            const resetAt = now + interval;
+            return {
+                key,
+                scope: this.config.scope,
+                algorithm: this.type,
+                limited: true,
+                remaining: 0,
+                resetAt,
+                retryAfter: Math.max(0, resetAt - now),
+                limit,
+            };
+        });
+    }
+    /**
+     * Reset the stored key state for this limiter.
+     *
+     * @param key - Storage key to reset.
+     * @returns Resolves after the key is deleted.
+     */
+    async reset(key) {
+        await this.storage.delete(key);
+    }
+}
+exports.FixedWindowAlgorithm = FixedWindowAlgorithm;
+/**
+ * Type guard for fixed-window state entries loaded from storage.
+ *
+ * @param value - Stored value to validate.
+ * @returns True when the value matches the FixedWindowState shape.
+ */
+function isFixedWindowState(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const state = value;
+    const hasValidVersion = state.version === undefined ||
+        (typeof state.version === 'number' && Number.isFinite(state.version));
+    return (typeof state.count === 'number' &&
+        Number.isFinite(state.count) &&
+        typeof state.resetAt === 'number' &&
+        Number.isFinite(state.resetAt) &&
+        hasValidVersion);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZml4ZWQtd2luZG93LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2VuZ2luZS9hbGdvcml0aG1zL2ZpeGVkLXdpbmRvdy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7O0dBS0c7OztBQVFILGlEQUF5RDtBQWN6RDs7OztHQUlHO0FBQ0gsTUFBYSxvQkFBb0I7SUFHL0I7Ozs7O09BS0c7SUFDSCxZQUNtQixPQUF5QixFQUN6QixNQUF5QjtRQUR6QixZQUFPLEdBQVAsT0FBTyxDQUFrQjtRQUN6QixXQUFNLEdBQU4sTUFBTSxDQUFtQjtRQVY1QixTQUFJLEdBQTJCLGNBQWMsQ0FBQztJQVczRCxDQUFDO0lBRUo7Ozs7O09BS0c7SUFDSSxLQUFLLENBQUMsT0FBTyxDQUFDLEdBQVc7UUFDOUIsTUFBTSxLQUFLLEdBQUcsSUFBSSxDQUFDLE1BQU0sQ0FBQyxXQUFXLENBQUM7UUFDdEMsTUFBTSxRQUFRLEdBQUcsSUFBSSxDQUFDLE1BQU0sQ0FBQyxVQUFVLENBQUM7UUFFeEMsSUFBSSxJQUFJLENBQUMsT0FBTyxDQUFDLGtCQUFrQixFQUFFLENBQUM7WUFDcEMsTUFBTSxHQUFHLEdBQUcsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDO1lBQ3ZCLE1BQU0sRUFBRSxLQUFLLEVBQUUsS0FBSyxFQUFFLEdBQUcsTUFBTSxJQUFJLENBQUMsT0FBTyxDQUFDLGtCQUFrQixDQUM1RCxHQUFHLEVBQ0gsS0FBSyxFQUNMLFFBQVEsRUFDUixHQUFHLENBQ0osQ0FBQztZQUNGLE1BQU0sT0FBTyxHQUFHLEdBQUcsR0FBRyxLQUFLLENBQUM7WUFDNUIsTUFBTSxPQUFPLEdBQUcsS0FBSyxHQUFHLEtBQUssQ0FBQztZQUM5QixPQUFPO2dCQUNMLEdBQUc7Z0JBQ0gsS0FBSyxFQUFFLElBQUksQ0FBQyxNQUFNLENBQUMsS0FBSztnQkFDeEIsU0FBUyxFQUFFLElBQUksQ0FBQyxJQUFJO2dCQUNwQixPQUFPO2dCQUNQLFNBQVMsRUFB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

package/dist/engine/algorithms/leaky-bucket.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Leaky bucket rate limiting.
+ *
+ * Drains at a steady rate to smooth spikes in traffic.
+ * The stored level keeps limits consistent across commands.
+ */
+import type { RateLimitAlgorithm, RateLimitAlgorithmType, RateLimitResult, RateLimitStorage } from '../../types';
+interface LeakyBucketConfig {
+    /** Maximum fill level before limiting. */
+    capacity: number;
+    /** Tokens drained per second during leak. */
+    leakRate: number;
+    /** Scope reported in rate-limit results. */
+    scope: RateLimitResult['scope'];
+}
+/**
+ * Leaky bucket algorithm for smoothing output to a steady rate.
+ *
+ * @implements RateLimitAlgorithm
+ */
+export declare class LeakyBucketAlgorithm implements RateLimitAlgorithm {
+    private readonly storage;
+    private readonly config;
+    readonly type: RateLimitAlgorithmType;
+    /**
+     * Create a leaky-bucket algorithm bound to a storage backend.
+     *
+     * @param storage - Storage backend for rate-limit state.
+     * @param config - Leaky-bucket configuration.
+     */
+    constructor(storage: RateLimitStorage, config: LeakyBucketConfig);
+    /**
+     * Record one attempt and return the current bucket status for this key.
+     *
+     * @param key - Storage key for the limiter.
+     * @returns Rate limit result for the current bucket.
+     * @throws Error when leakRate is non-positive.
+     */
+    consume(key: string): Promise<RateLimitResult>;
+    /**
+     * Reset the stored key state for this limiter.
+     *
+     * @param key - Storage key to reset.
+     * @returns Resolves after the key is deleted.
+     */
+    reset(key: string): Promise<void>;
+}
+export {};