@commandkit/ratelimit 0.0.0-dev.20260317060555

package/dist/engine/algorithms/leaky-bucket.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Leaky bucket rate limiting.
+ *
+ * Drains at a steady rate to smooth spikes in traffic.
+ * The stored level keeps limits consistent across commands.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LeakyBucketAlgorithm = void 0;
+/**
+ * Leaky bucket algorithm for smoothing output to a steady rate.
+ *
+ * @implements RateLimitAlgorithm
+ */
+class LeakyBucketAlgorithm {
+    /**
+     * 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, config) {
+        this.storage = storage;
+        this.config = config;
+        this.type = 'leaky-bucket';
+    }
+    /**
+     * 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.
+     */
+    async consume(key) {
+        const now = Date.now();
+        const { capacity, leakRate } = this.config;
+        if (leakRate <= 0) {
+            throw new Error('leakRate must be greater than 0');
+        }
+        const stored = await this.storage.get(key);
+        const state = isLeakyBucketState(stored)
+            ? stored
+            : { level: 0, lastLeak: now };
+        const elapsedSeconds = Math.max(0, (now - state.lastLeak) / 1000);
+        const leaked = Math.max(0, state.level - elapsedSeconds * leakRate);
+        const nextState = {
+            level: leaked,
+            lastLeak: now,
+        };
+        if (leaked + 1 > capacity) {
+            const overflow = leaked + 1 - capacity;
+            const retryAfter = Math.ceil((overflow / leakRate) * 1000);
+            const resetAt = now + retryAfter;
+            await this.storage.set(key, nextState, estimateLeakyTtl(capacity, leakRate));
+            return {
+                key,
+                scope: this.config.scope,
+                algorithm: this.type,
+                limited: true,
+                remaining: 0,
+                resetAt,
+                retryAfter,
+                limit: capacity,
+            };
+        }
+        nextState.level = leaked + 1;
+        await this.storage.set(key, nextState, estimateLeakyTtl(capacity, leakRate));
+        const remaining = Math.floor(Math.max(0, capacity - nextState.level));
+        const resetAt = now + Math.ceil((nextState.level / leakRate) * 1000);
+        return {
+            key,
+            scope: this.config.scope,
+            algorithm: this.type,
+            limited: false,
+            remaining,
+            resetAt,
+            retryAfter: 0,
+            limit: capacity,
+        };
+    }
+    /**
+     * 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.LeakyBucketAlgorithm = LeakyBucketAlgorithm;
+/**
+ * Type guard for leaky-bucket state entries loaded from storage.
+ *
+ * @param value - Stored value to validate.
+ * @returns True when the value matches the LeakyBucketState shape.
+ */
+function isLeakyBucketState(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const state = value;
+    return (typeof state.level === 'number' &&
+        Number.isFinite(state.level) &&
+        typeof state.lastLeak === 'number' &&
+        Number.isFinite(state.lastLeak));
+}
+/**
+ * Estimate a TTL window large enough to cover full bucket drainage.
+ *
+ * @param capacity - Bucket capacity.
+ * @param leakRate - Tokens drained per second.
+ * @returns TTL in milliseconds.
+ */
+function estimateLeakyTtl(capacity, leakRate) {
+    if (leakRate <= 0)
+        return 60000;
+    return Math.ceil((capacity / leakRate) * 1000 * 2);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibGVha3ktYnVja2V0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2VuZ2luZS9hbGdvcml0aG1zL2xlYWt5LWJ1Y2tldC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7O0dBS0c7OztBQXVCSDs7OztHQUlHO0FBQ0gsTUFBYSxvQkFBb0I7SUFHL0I7Ozs7O09BS0c7SUFDSCxZQUNtQixPQUF5QixFQUN6QixNQUF5QjtRQUR6QixZQUFPLEdBQVAsT0FBTyxDQUFrQjtRQUN6QixXQUFNLEdBQU4sTUFBTSxDQUFtQjtRQVY1QixTQUFJLEdBQTJCLGNBQWMsQ0FBQztJQVczRCxDQUFDO0lBRUo7Ozs7OztPQU1HO0lBQ0ksS0FBSyxDQUFDLE9BQU8sQ0FBQyxHQUFXO1FBQzlCLE1BQU0sR0FBRyxHQUFHLElBQUksQ0FBQyxHQUFHLEVBQUUsQ0FBQztRQUN2QixNQUFNLEVBQUUsUUFBUSxFQUFFLFFBQVEsRUFBRSxHQUFHLElBQUksQ0FBQyxNQUFNLENBQUM7UUFFM0MsSUFBSSxRQUFRLElBQUksQ0FBQyxFQUFFLENBQUM7WUFDbEIsTUFBTSxJQUFJLEtBQUssQ0FBQyxpQ0FBaUMsQ0FBQyxDQUFDO1FBQ3JELENBQUM7UUFFRCxNQUFNLE1BQU0sR0FBRyxNQUFNLElBQUksQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFtQixHQUFHLENBQUMsQ0FBQztRQUM3RCxNQUFNLEtBQUssR0FBRyxrQkFBa0IsQ0FBQyxNQUFNLENBQUM7WUFDdEMsQ0FBQyxDQUFDLE1BQU07WUFDUixDQUFDLENBQUUsRUFBRSxLQUFLLEVBQUUsQ0FBQyxFQUFFLFFBQVEsRUFBRSxHQUFHLEVBQThCLENBQUM7UUFFN0QsTUFBTSxjQUFjLEdBQUcsSUFBSSxDQUFDLEdBQUcsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxHQUFHLEdBQUcsS0FBSyxDQUFDLFFBQVEsQ0FBQyxHQUFHLElBQUksQ0FBQyxDQUFDO1FBQ2xFLE1BQU0sTUFBTSxHQUFHLElBQUksQ0FB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

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

@@ -0,0 +1,45 @@
+/**
+ * Sliding window log rate limiting.
+ *
+ * Tracks individual request timestamps for smoother limits and accurate retry
+ * timing. Requires sorted-set support or an atomic storage helper.
+ */
+import type { RateLimitAlgorithm, RateLimitAlgorithmType, RateLimitResult, RateLimitStorage } from '../../types';
+interface SlidingWindowConfig {
+    maxRequests: number;
+    intervalMs: number;
+    scope: RateLimitResult['scope'];
+}
+/**
+ * Sliding-window log algorithm for smoother limits.
+ *
+ * @implements RateLimitAlgorithm
+ */
+export declare class SlidingWindowLogAlgorithm implements RateLimitAlgorithm {
+    private readonly storage;
+    private readonly config;
+    readonly type: RateLimitAlgorithmType;
+    /**
+     * Create a sliding-window algorithm bound to a storage backend.
+     *
+     * @param storage - Storage backend for rate-limit state.
+     * @param config - Sliding-window configuration.
+     */
+    constructor(storage: RateLimitStorage, config: SlidingWindowConfig);
+    /**
+     * 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.
+     * @throws Error when the storage backend lacks sorted-set support.
+     */
+    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/sliding-window.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Sliding window log rate limiting.
+ *
+ * Tracks individual request timestamps for smoother limits and accurate retry
+ * timing. Requires sorted-set support or an atomic storage helper.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SlidingWindowLogAlgorithm = void 0;
+const locking_1 = require("../../utils/locking");
+/**
+ * Sliding-window log algorithm for smoother limits.
+ *
+ * @implements RateLimitAlgorithm
+ */
+class SlidingWindowLogAlgorithm {
+    /**
+     * Create a sliding-window algorithm bound to a storage backend.
+     *
+     * @param storage - Storage backend for rate-limit state.
+     * @param config - Sliding-window configuration.
+     */
+    constructor(storage, config) {
+        this.storage = storage;
+        this.config = config;
+        this.type = 'sliding-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.
+     * @throws Error when the storage backend lacks sorted-set support.
+     */
+    async consume(key) {
+        const limit = this.config.maxRequests;
+        const windowMs = this.config.intervalMs;
+        if (this.storage.consumeSlidingWindowLog) {
+            const now = Date.now();
+            /**
+             * Include the timestamp so reset time can be derived without extra reads.
+             */
+            const member = `${now}-${Math.random().toString(36).slice(2, 8)}`;
+            const res = await this.storage.consumeSlidingWindowLog(key, limit, windowMs, now, member);
+            const limited = !res.allowed;
+            return {
+                key,
+                scope: this.config.scope,
+                algorithm: this.type,
+                limited,
+                remaining: Math.max(0, limit - res.count),
+                resetAt: res.resetAt,
+                retryAfter: limited ? Math.max(0, res.resetAt - now) : 0,
+                limit,
+            };
+        }
+        if (!this.storage.zRemRangeByScore ||
+            !this.storage.zCard ||
+            !this.storage.zAdd) {
+            throw new Error('Sliding window requires sorted set support in storage');
+        }
+        return (0, locking_1.withStorageKeyLock)(this.storage, key, async () => {
+            const now = Date.now();
+            /**
+             * Include the timestamp so reset time can be derived without extra reads.
+             */
+            const member = `${now}-${Math.random().toString(36).slice(2, 8)}`;
+            /**
+             * Fallback is serialized per process; multi-process strictness needs atomic storage.
+             */
+            await this.storage.zRemRangeByScore(key, 0, now - windowMs);
+            const count = await this.storage.zCard(key);
+            if (count >= limit) {
+                const oldestMembers = this.storage.zRangeByScore
+                    ? await this.storage.zRangeByScore(key, Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY)
+                    : [];
+                const oldestMember = oldestMembers[0];
+                const oldestTs = oldestMember
+                    ? Number(oldestMember.split('-')[0])
+                    : now;
+                const resetAt = oldestTs + windowMs;
+                return {
+                    key,
+                    scope: this.config.scope,
+                    algorithm: this.type,
+                    limited: true,
+                    remaining: 0,
+                    resetAt,
+                    retryAfter: Math.max(0, resetAt - now),
+                    limit,
+                };
+            }
+            await this.storage.zAdd(key, now, member);
+            if (this.storage.expire) {
+                await this.storage.expire(key, windowMs);
+            }
+            const newCount = count + 1;
+            const oldestMembers = this.storage.zRangeByScore
+                ? await this.storage.zRangeByScore(key, Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY)
+                : [];
+            const oldestMember = oldestMembers[0];
+            const oldestTs = oldestMember ? Number(oldestMember.split('-')[0]) : now;
+            const resetAt = oldestTs + windowMs;
+            return {
+                key,
+                scope: this.config.scope,
+                algorithm: this.type,
+                limited: false,
+                remaining: Math.max(0, limit - newCount),
+                resetAt,
+                retryAfter: 0,
+                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.SlidingWindowLogAlgorithm = SlidingWindowLogAlgorithm;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2xpZGluZy13aW5kb3cuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvZW5naW5lL2FsZ29yaXRobXMvc2xpZGluZy13aW5kb3cudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7OztHQUtHOzs7QUFRSCxpREFBeUQ7QUFRekQ7Ozs7R0FJRztBQUNILE1BQWEseUJBQXlCO0lBR3BDOzs7OztPQUtHO0lBQ0gsWUFDbUIsT0FBeUIsRUFDekIsTUFBMkI7UUFEM0IsWUFBTyxHQUFQLE9BQU8sQ0FBa0I7UUFDekIsV0FBTSxHQUFOLE1BQU0sQ0FBcUI7UUFWOUIsU0FBSSxHQUEyQixnQkFBZ0IsQ0FBQztJQVc3RCxDQUFDO0lBRUo7Ozs7OztPQU1HO0lBQ0ksS0FBSyxDQUFDLE9BQU8sQ0FBQyxHQUFXO1FBQzlCLE1BQU0sS0FBSyxHQUFHLElBQUksQ0FBQyxNQUFNLENBQUMsV0FBVyxDQUFDO1FBQ3RDLE1BQU0sUUFBUSxHQUFHLElBQUksQ0FBQyxNQUFNLENBQUMsVUFBVSxDQUFDO1FBRXhDLElBQUksSUFBSSxDQUFDLE9BQU8sQ0FBQyx1QkFBdUIsRUFBRSxDQUFDO1lBQ3pDLE1BQU0sR0FBRyxHQUFHLElBQUksQ0FBQyxHQUFHLEVBQUUsQ0FBQztZQUN2Qjs7ZUFFRztZQUNILE1BQU0sTUFBTSxHQUFHLEdBQUcsR0FBRyxJQUFJLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQyxRQUFRLENBQUMsRUFBRSxDQUFDLENBQUMsS0FBSyxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsRUFBRSxDQUFDO1lBQ2xFLE1BQU0sR0FBRyxHQUFHLE1BQU0sSUFBSSxDQUFDLE9BQU8sQ0FBQyx1QkFBdUIsQ0FDcEQsR0FBRyxFQUNILEtBQUssRUFDTCxRQUFRLEVBQ1IsR0FBRyxFQUNILE1BQU0sQ0FDUCxDQUFDO1lBQ0YsTUFBTSxPQUFPLEdBQUcsQ0FBQyxHQUFHLENBQUMsT0FBTyxDQUFDO1lBQzdCLE9BQU87Z0JBQ0wsR0FBRztn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

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

@@ -0,0 +1,47 @@
+/**
+ * Token bucket rate limiting.
+ *
+ * Allows short bursts while refilling steadily up to a cap.
+ * Bucket state is stored so limits stay consistent across commands.
+ */
+import type { RateLimitAlgorithm, RateLimitAlgorithmType, RateLimitResult, RateLimitStorage } from '../../types';
+export interface TokenBucketConfig {
+    /** Maximum tokens available when the bucket is full. */
+    capacity: number;
+    /** Tokens added per second during refill. */
+    refillRate: number;
+    /** Scope reported in rate-limit results. */
+    scope: RateLimitResult['scope'];
+}
+/**
+ * Token bucket algorithm for bursty traffic with steady refill.
+ *
+ * @implements RateLimitAlgorithm
+ */
+export declare class TokenBucketAlgorithm implements RateLimitAlgorithm {
+    private readonly storage;
+    private readonly config;
+    readonly type: RateLimitAlgorithmType;
+    /**
+     * Create a token-bucket algorithm bound to a storage backend.
+     *
+     * @param storage - Storage backend for rate-limit state.
+     * @param config - Token-bucket configuration.
+     */
+    constructor(storage: RateLimitStorage, config: TokenBucketConfig);
+    /**
+     * 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 refillRate 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>;
+}

package/dist/engine/algorithms/token-bucket.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Token bucket rate limiting.
+ *
+ * Allows short bursts while refilling steadily up to a cap.
+ * Bucket state is stored so limits stay consistent across commands.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenBucketAlgorithm = void 0;
+/**
+ * Token bucket algorithm for bursty traffic with steady refill.
+ *
+ * @implements RateLimitAlgorithm
+ */
+class TokenBucketAlgorithm {
+    /**
+     * Create a token-bucket algorithm bound to a storage backend.
+     *
+     * @param storage - Storage backend for rate-limit state.
+     * @param config - Token-bucket configuration.
+     */
+    constructor(storage, config) {
+        this.storage = storage;
+        this.config = config;
+        this.type = 'token-bucket';
+    }
+    /**
+     * 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 refillRate is non-positive.
+     */
+    async consume(key) {
+        const now = Date.now();
+        const { capacity, refillRate } = this.config;
+        if (refillRate <= 0) {
+            throw new Error('refillRate must be greater than 0');
+        }
+        const stored = await this.storage.get(key);
+        const state = isTokenBucketState(stored)
+            ? stored
+            : { tokens: capacity, lastRefill: now };
+        const elapsedSeconds = Math.max(0, (now - state.lastRefill) / 1000);
+        const refilled = Math.min(capacity, state.tokens + elapsedSeconds * refillRate);
+        const nextState = {
+            tokens: refilled,
+            lastRefill: now,
+        };
+        if (refilled < 1) {
+            const retryAfter = Math.ceil(((1 - refilled) / refillRate) * 1000);
+            const resetAt = now + retryAfter;
+            await this.storage.set(key, nextState, estimateBucketTtl(capacity, refillRate));
+            return {
+                key,
+                scope: this.config.scope,
+                algorithm: this.type,
+                limited: true,
+                remaining: 0,
+                resetAt,
+                retryAfter,
+                limit: capacity,
+            };
+        }
+        nextState.tokens = refilled - 1;
+        await this.storage.set(key, nextState, estimateBucketTtl(capacity, refillRate));
+        const remaining = Math.floor(nextState.tokens);
+        const resetAt = now + Math.ceil(((capacity - nextState.tokens) / refillRate) * 1000);
+        return {
+            key,
+            scope: this.config.scope,
+            algorithm: this.type,
+            limited: false,
+            remaining,
+            resetAt,
+            retryAfter: 0,
+            limit: capacity,
+        };
+    }
+    /**
+     * 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.TokenBucketAlgorithm = TokenBucketAlgorithm;
+/**
+ * Type guard for token-bucket state entries loaded from storage.
+ *
+ * @param value - Stored value to validate.
+ * @returns True when the value matches the TokenBucketState shape.
+ */
+function isTokenBucketState(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const state = value;
+    return (typeof state.tokens === 'number' &&
+        Number.isFinite(state.tokens) &&
+        typeof state.lastRefill === 'number' &&
+        Number.isFinite(state.lastRefill));
+}
+/**
+ * Estimate a TTL window large enough to cover full bucket refills.
+ *
+ * @param capacity - Bucket capacity.
+ * @param refillRate - Tokens refilled per second.
+ * @returns TTL in milliseconds.
+ */
+function estimateBucketTtl(capacity, refillRate) {
+    if (refillRate <= 0)
+        return 60000;
+    return Math.ceil((capacity / refillRate) * 1000 * 2);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidG9rZW4tYnVja2V0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2VuZ2luZS9hbGdvcml0aG1zL3Rva2VuLWJ1Y2tldC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7O0dBS0c7OztBQXVCSDs7OztHQUlHO0FBQ0gsTUFBYSxvQkFBb0I7SUFHL0I7Ozs7O09BS0c7SUFDSCxZQUNtQixPQUF5QixFQUN6QixNQUF5QjtRQUR6QixZQUFPLEdBQVAsT0FBTyxDQUFrQjtRQUN6QixXQUFNLEdBQU4sTUFBTSxDQUFtQjtRQVY1QixTQUFJLEdBQTJCLGNBQWMsQ0FBQztJQVczRCxDQUFDO0lBRUo7Ozs7OztPQU1HO0lBQ0ksS0FBSyxDQUFDLE9BQU8sQ0FBQyxHQUFXO1FBQzlCLE1BQU0sR0FBRyxHQUFHLElBQUksQ0FBQyxHQUFHLEVBQUUsQ0FBQztRQUN2QixNQUFNLEVBQUUsUUFBUSxFQUFFLFVBQVUsRUFBRSxHQUFHLElBQUksQ0FBQyxNQUFNLENBQUM7UUFFN0MsSUFBSSxVQUFVLElBQUksQ0FBQyxFQUFFLENBQUM7WUFDcEIsTUFBTSxJQUFJLEtBQUssQ0FBQyxtQ0FBbUMsQ0FBQyxDQUFDO1FBQ3ZELENBQUM7UUFFRCxNQUFNLE1BQU0sR0FBRyxNQUFNLElBQUksQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFtQixHQUFHLENBQUMsQ0FBQztRQUM3RCxNQUFNLEtBQUssR0FBRyxrQkFBa0IsQ0FBQyxNQUFNLENBQUM7WUFDdEMsQ0FBQyxDQUFDLE1BQU07WUFDUixDQUFDLENBQUUsRUFBRSxNQUFNLEVBQUUsUUFBUSxFQUFFLFVBQVUsRUFBRSxHQUFHLEVBQThCLENBQUM7UUFFdkUsTUFBTSxjQUFjLEdBQUcsSUFBSSxDQUFDLEdBQUcsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxHQUFHLEdBQUcsS0FBSyxDQUFDLFVBQVUsQ0FBQyxHQUFHLElBQUksQ0FBQyxDQUFDO1FBQ3BFLE1BQU0sUUFBUSxHQUFHLElBQUksQ0FB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

package/dist/engine/violations.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Violation tracking.
+ *
+ * Persists repeat violations so cooldowns can escalate predictably.
+ */
+import type { RateLimitStorage, ViolationOptions } from '../types';
+interface ViolationState {
+    count: number;
+    cooldownUntil: number;
+    lastViolationAt: number;
+}
+/**
+ * Tracks repeated violations and computes escalating cooldowns.
+ */
+export declare class ViolationTracker {
+    private readonly storage;
+    /**
+     * Create a violation tracker bound to a storage backend.
+     *
+     * @param storage - Storage backend for violation state.
+     */
+    constructor(storage: RateLimitStorage);
+    private key;
+    /**
+     * Read stored violation state for a key, if present.
+     *
+     * @param key - Storage key for the limiter.
+     * @returns Stored violation state or null when none is present.
+     */
+    getState(key: string): Promise<ViolationState | null>;
+    /**
+     * Check if a cooldown is currently active for this key.
+     *
+     * @param key - Storage key for the limiter.
+     * @returns Violation state when cooldown is active, otherwise null.
+     */
+    checkCooldown(key: string): Promise<ViolationState | null>;
+    /**
+     * Record a violation and return the updated state for callers.
+     *
+     * @param key - Storage key for the limiter.
+     * @param baseRetryAfterMs - Base retry delay in milliseconds.
+     * @param options - Optional escalation settings.
+     * @returns Updated violation state.
+     */
+    recordViolation(key: string, baseRetryAfterMs: number, options?: ViolationOptions): Promise<ViolationState>;
+    /**
+     * Clear stored violation state for a key.
+     *
+     * @param key - Storage key to reset.
+     * @returns Resolves after the violation entry is deleted.
+     */
+    reset(key: string): Promise<void>;
+}
+export {};

package/dist/engine/violations.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Violation tracking.
+ *
+ * Persists repeat violations so cooldowns can escalate predictably.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViolationTracker = void 0;
+const time_1 = require("../utils/time");
+const DEFAULT_MAX_VIOLATIONS = 5;
+const DEFAULT_ESCALATION_MULTIPLIER = 2;
+const DEFAULT_RESET_AFTER_MS = 60 * 60 * 1000;
+/**
+ * Tracks repeated violations and computes escalating cooldowns.
+ */
+class ViolationTracker {
+    /**
+     * Create a violation tracker bound to a storage backend.
+     *
+     * @param storage - Storage backend for violation state.
+     */
+    constructor(storage) {
+        this.storage = storage;
+    }
+    key(key) {
+        return `violation:${key}`;
+    }
+    /**
+     * Read stored violation state for a key, if present.
+     *
+     * @param key - Storage key for the limiter.
+     * @returns Stored violation state or null when none is present.
+     */
+    async getState(key) {
+        const stored = await this.storage.get(this.key(key));
+        return isViolationState(stored) ? stored : null;
+    }
+    /**
+     * Check if a cooldown is currently active for this key.
+     *
+     * @param key - Storage key for the limiter.
+     * @returns Violation state when cooldown is active, otherwise null.
+     */
+    async checkCooldown(key) {
+        const state = await this.getState(key);
+        if (!state)
+            return null;
+        if (state.cooldownUntil > Date.now())
+            return state;
+        return null;
+    }
+    /**
+     * Record a violation and return the updated state for callers.
+     *
+     * @param key - Storage key for the limiter.
+     * @param baseRetryAfterMs - Base retry delay in milliseconds.
+     * @param options - Optional escalation settings.
+     * @returns Updated violation state.
+     */
+    async recordViolation(key, baseRetryAfterMs, options) {
+        const now = Date.now();
+        const prev = await this.getState(key);
+        const maxViolations = options?.maxViolations ?? DEFAULT_MAX_VIOLATIONS;
+        const multiplier = options?.escalationMultiplier ?? DEFAULT_ESCALATION_MULTIPLIER;
+        const resetAfter = (0, time_1.resolveDuration)(options?.resetAfter, DEFAULT_RESET_AFTER_MS);
+        const count = Math.min((prev?.count ?? 0) + 1, maxViolations);
+        const base = Math.max(0, baseRetryAfterMs);
+        const cooldownMs = base * Math.pow(multiplier, Math.max(0, count - 1));
+        const cooldownUntil = now + cooldownMs;
+        const state = {
+            count,
+            cooldownUntil,
+            lastViolationAt: now,
+        };
+        await this.storage.set(this.key(key), state, resetAfter);
+        return state;
+    }
+    /**
+     * Clear stored violation state for a key.
+     *
+     * @param key - Storage key to reset.
+     * @returns Resolves after the violation entry is deleted.
+     */
+    async reset(key) {
+        await this.storage.delete(this.key(key));
+    }
+}
+exports.ViolationTracker = ViolationTracker;
+/**
+ * Type guard for violation state entries loaded from storage.
+ *
+ * @param value - Stored value to validate.
+ * @returns True when the value matches the ViolationState shape.
+ */
+function isViolationState(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const state = value;
+    return (typeof state.count === 'number' &&
+        Number.isFinite(state.count) &&
+        typeof state.cooldownUntil === 'number' &&
+        Number.isFinite(state.cooldownUntil) &&
+        typeof state.lastViolationAt === 'number' &&
+        Number.isFinite(state.lastViolationAt));
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmlvbGF0aW9ucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9lbmdpbmUvdmlvbGF0aW9ucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7R0FJRzs7O0FBR0gsd0NBQWdEO0FBUWhELE1BQU0sc0JBQXNCLEdBQUcsQ0FBQyxDQUFDO0FBQ2pDLE1BQU0sNkJBQTZCLEdBQUcsQ0FBQyxDQUFDO0FBQ3hDLE1BQU0sc0JBQXNCLEdBQUcsRUFBRSxHQUFHLEVBQUUsR0FBRyxJQUFJLENBQUM7QUFFOUM7O0dBRUc7QUFDSCxNQUFhLGdCQUFnQjtJQUMzQjs7OztPQUlHO0lBQ0gsWUFBb0MsT0FBeUI7UUFBekIsWUFBTyxHQUFQLE9BQU8sQ0FBa0I7SUFBRyxDQUFDO0lBRXpELEdBQUcsQ0FBQyxHQUFXO1FBQ3JCLE9BQU8sYUFBYSxHQUFHLEVBQUUsQ0FBQztJQUM1QixDQUFDO0lBRUQ7Ozs7O09BS0c7SUFDSCxLQUFLLENBQUMsUUFBUSxDQUFDLEdBQVc7UUFDeEIsTUFBTSxNQUFNLEdBQUcsTUFBTSxJQUFJLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBaUIsSUFBSSxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDO1FBQ3JFLE9BQU8sZ0JBQWdCLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDO0lBQ2xELENBQUM7SUFFRDs7Ozs7T0FLRztJQUNILEtBQUssQ0FBQyxhQUFhLENBQUMsR0FBVztRQUM3QixNQUFNLEtBQUssR0FBRyxNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDdkMsSUFBSSxDQUFDLEtBQUs7WUFBRSxPQUFPLElBQUksQ0FBQztRQUN4QixJQUFJLEtBQUssQ0FBQyxhQUFhLEdBQUcsSUFBSSxDQUFDLEdBQUcsRUFBRTtZQUFFLE9BQU8sS0FBSyxDQUFDO1FBQ25ELE9BQU8sSUFBSSxDQUFDO0lBQ2QsQ0FBQztJQUVEOzs7Ozs7O09BT0c7SUFDSCxLQUFLLENBQUMsZUFBZSxDQUNuQixHQUFXLEVBQ1gsZ0JBQXdCLEVBQ3hCLE9BQTBCO1FBRTFCLE1BQU0sR0FBRyxHQUFHLElBQUksQ0FBQyxHQUFHLEVBQUUsQ0FBQztRQUN2QixNQUFNLElBQUksR0FBRyxNQUFNLElBQUksQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDdEMsTUFBTSxhQUFhLEdBQUcsT0FBTyxFQUFFLGFBQWEsSUFBSSxzQkFBc0IsQ0FBQztRQUN2RSxNQUFNLFVBQVUsR0FDZCxPQUFPLEVBQUUsb0JBQW9CLElBQUksNkJBQTZCLENBQUM7UUFDakUsTUFBTSxVQUFVLEdBQUcsSUFBQSxzQkFBZSxFQUNoQyxPQUFPLEVBQUUsVUFBVSxFQUNuQixzQkFBc0IsQ0FDdkIsQ0FBQztRQUVGLE1BQU0sS0FBSyxHQUFHLElBQUksQ0FBQyxHQUFHLENBQUMsQ0FBQyxJQUFJLEVBQUUsS0FBSyxJQUFJLENBQUMsQ0FBQyxHQUFHLENBQUMsRUFBRSxhQUFhLENBQUMsQ0FBQztRQUM5RCxNQUFNLElBQUksR0FBRyxJQUFJLENBQUMsR0FBRyxDQUFDLENBQUMsRUFBRSxnQkFBZ0IsQ0FBQyxDQUFDO1FBQzNDLE1BQU0sVUFBVSxHQUFHLElBQUksR0FBRyxJQUFJLENBQUMsR0FBRyxDQUFDLFVBQVUsRUFBRSxJQUFJLENBQUMsR0FBRyxDQUFDLENBQUMsRUFBRSxLQUFLLEdBQUcsQ0FBQyxDQUFDLENBQUMsQ0FBQztRQUN2RSxNQUFNLGFBQWEsR0FBRyxHQUFHLEdBQUcsVUFBVSxDQUFDO1FBRXZDLE1BQU0sS0FBSyxHQUFtQjtZQUM1QixLQUFLO1lBQ0wsYUFBYTtZQUNiLGVBQWUsRUFBRSxHQUFHO1NBQ3JCLENBQUM7UUFFRixNQUFNLElBQUksQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLElBQUksQ0FBQyxHQUFHLENBQUMsR0FBRyxDQUFDLEVBQUUsS0FBSyxFQUFFLFVBQVUsQ0FBQyxDQUFDO1FBQ3pELE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUVEOzs7OztPQUtHO0lBQ0gsS0FBSyxDQUFDLEtBQUssQ0FBQyxHQUFXO1FBQ3JCLE1BQU0sSUFBSSxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDO0lBQzNDLENBQUM7Q0FDRjtBQW5GRCw0Q0FtRkM7QUFFRDs7Ozs7R0FLRztBQUNILFNBQVMsZ0JBQWdCLENBQUMsS0FBYztJQUN0QyxJQUFJLENBQUMsS0FBSyxJQUFJLE9BQU8sS0FBSyxLQUFLLFFBQVE7UUFBRSxPQUFPLEtBQUssQ0FBQztJQUN0RCxNQUFNLEtBQUssR0FBRyxLQUF1QixDQUFDO0lBQ3RDLE9BQU8sQ0FDTCxPQUFPLEtBQUssQ0FBQyxLQUFLLEtBQUssUUFBUTtRQUMvQixNQUFNLENBQUMsUUFBUSxDQUFDLEtBQUssQ0FBQyxLQUFLLENBQUM7UUFDNUIsT0FBTyxLQUFLLENBQUMsYUFBYSxLQUFLLFFBQVE7UUFDdkMsTUFBTSxDQUFDLFFBQVEsQ0FBQyxLQUFLLENBQUMsYUFBYSxDQUFDO1FBQ3BDLE9BQU8sS0FBSyxDQUFDLGVBQWUsS0FBSyxRQUFRO1FBQ3pDLE1BQU0sQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLGVBQWUsQ0FBQyxDQUN2QyxDQUFDO0FBQ0osQ0FBQyJ9

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Rate limit error type.
+ *
+ * Lets callers distinguish rate-limit failures from other errors.
+ */
+import type { RateLimitStoreValue } from './types';
+/**
+ * Error thrown by the directive wrapper when a function is rate-limited.
+ *
+ * @extends Error
+ */
+export declare class RateLimitError extends Error {
+    readonly result: RateLimitStoreValue;
+    /**
+     * Create a rate-limit error with the stored result payload.
+     *
+     * @param result - Aggregated rate-limit result.
+     * @param message - Optional error message override.
+     */
+    constructor(result: RateLimitStoreValue, message?: string);
+}