@commandkit/ratelimit 0.0.0-dev.20260317060555

package/dist/storage/memory.d.ts

@@ -0,0 +1,146 @@
+/**
+ * In-memory storage.
+ *
+ * Used for tests and local development; implements TTL and sorted-set helpers.
+ * Not suitable for multi-process deployments.
+ */
+import type { FixedWindowConsumeResult, RateLimitStorage, SlidingWindowConsumeResult } from '../types';
+/**
+ * In-memory storage used for tests and local usage.
+ *
+ * @implements RateLimitStorage
+ */
+export declare class MemoryRateLimitStorage implements RateLimitStorage {
+    private readonly kv;
+    private readonly zsets;
+    private now;
+    private isExpired;
+    /**
+     * Clear expired entries so reads reflect current state.
+     *
+     * @param key - Storage key to clean.
+     */
+    private cleanupKey;
+    /**
+     * Read a value from the in-memory key/value store.
+     *
+     * @param key - Storage key to read.
+     * @returns Stored value or null when absent/expired.
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Store a value in memory with optional TTL.
+     *
+     * @param key - Storage key to write.
+     * @param value - Value to store.
+     * @param ttlMs - Optional TTL in milliseconds.
+     * @returns Resolves when the value is stored.
+     */
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
+    /**
+     * Delete a key from the in-memory store.
+     *
+     * @param key - Storage key to delete.
+     * @returns Resolves when the key is removed.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Increment a fixed-window counter with TTL handling.
+     *
+     * @param key - Storage key to increment.
+     * @param ttlMs - TTL window in milliseconds.
+     * @returns Updated counter value and remaining TTL.
+     */
+    incr(key: string, ttlMs: number): Promise<FixedWindowConsumeResult>;
+    /**
+     * Read the TTL for a key when present.
+     *
+     * @param key - Storage key to inspect.
+     * @returns Remaining TTL in ms or null when no TTL is set.
+     */
+    ttl(key: string): Promise<number | null>;
+    /**
+     * Update the TTL for an existing key.
+     *
+     * @param key - Storage key to update.
+     * @param ttlMs - TTL in milliseconds.
+     * @returns Resolves after the TTL is updated.
+     */
+    expire(key: string, ttlMs: number): Promise<void>;
+    /**
+     * Add a member to a sorted set with the given score.
+     *
+     * @param key - Sorted-set key.
+     * @param score - Score to associate with the member.
+     * @param member - Member identifier.
+     * @returns Resolves when the member is added.
+     */
+    zAdd(key: string, score: number, member: string): Promise<void>;
+    /**
+     * Remove sorted-set members with scores in the given range.
+     *
+     * @param key - Sorted-set key.
+     * @param min - Minimum score (inclusive).
+     * @param max - Maximum score (inclusive).
+     * @returns Resolves when the range is removed.
+     */
+    zRemRangeByScore(key: string, min: number, max: number): Promise<void>;
+    /**
+     * Count members in a sorted set.
+     *
+     * @param key - Sorted-set key.
+     * @returns Number of members in the set.
+     */
+    zCard(key: string): Promise<number>;
+    /**
+     * Read sorted-set members in a score range.
+     *
+     * @param key - Sorted-set key.
+     * @param min - Minimum score (inclusive).
+     * @param max - Maximum score (inclusive).
+     * @returns Ordered members in the score range.
+     */
+    zRangeByScore(key: string, min: number, max: number): Promise<string[]>;
+    /**
+     * Atomically consume a fixed-window counter for the key.
+     *
+     * @param key - Storage key to consume.
+     * @param limit - Request limit for the window.
+     * @param windowMs - Window size in milliseconds.
+     * @param nowMs - Current timestamp in milliseconds.
+     * @returns Fixed-window consume result.
+     */
+    consumeFixedWindow(key: string, _limit: number, windowMs: number, _nowMs: number): Promise<FixedWindowConsumeResult>;
+    /**
+     * Atomically consume a sliding-window log for the key.
+     *
+     * @param key - Storage key to consume.
+     * @param limit - Request limit for the window.
+     * @param windowMs - Window size in milliseconds.
+     * @param nowMs - Current timestamp in milliseconds.
+     * @param member - Member identifier for this request.
+     * @returns Sliding-window consume result.
+     */
+    consumeSlidingWindowLog(key: string, limit: number, windowMs: number, nowMs: number, member: string): Promise<SlidingWindowConsumeResult>;
+    /**
+     * Delete keys with the given prefix.
+     *
+     * @param prefix - Prefix to match.
+     * @returns Resolves after matching keys are deleted.
+     */
+    deleteByPrefix(prefix: string): Promise<void>;
+    /**
+     * Delete keys matching a glob pattern.
+     *
+     * @param pattern - Glob pattern to match.
+     * @returns Resolves after matching keys are deleted.
+     */
+    deleteByPattern(pattern: string): Promise<void>;
+    /**
+     * List keys that match a prefix.
+     *
+     * @param prefix - Prefix to match.
+     * @returns Matching keys.
+     */
+    keysByPrefix(prefix: string): Promise<string[]>;
+}

package/dist/storage/memory.js

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * In-memory storage.
+ *
+ * Used for tests and local development; implements TTL and sorted-set helpers.
+ * Not suitable for multi-process deployments.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryRateLimitStorage = void 0;
+/**
+ * In-memory storage used for tests and local usage.
+ *
+ * @implements RateLimitStorage
+ */
+class MemoryRateLimitStorage {
+    constructor() {
+        this.kv = new Map();
+        this.zsets = new Map();
+    }
+    now() {
+        return Date.now();
+    }
+    isExpired(expiresAt) {
+        return expiresAt != null && expiresAt <= this.now();
+    }
+    /**
+     * Clear expired entries so reads reflect current state.
+     *
+     * @param key - Storage key to clean.
+     */
+    cleanupKey(key) {
+        const kvEntry = this.kv.get(key);
+        if (kvEntry && this.isExpired(kvEntry.expiresAt)) {
+            this.kv.delete(key);
+        }
+        const zEntry = this.zsets.get(key);
+        if (zEntry && this.isExpired(zEntry.expiresAt)) {
+            this.zsets.delete(key);
+        }
+    }
+    /**
+     * Read a value from the in-memory key/value store.
+     *
+     * @param key - Storage key to read.
+     * @returns Stored value or null when absent/expired.
+     */
+    async get(key) {
+        this.cleanupKey(key);
+        const entry = this.kv.get(key);
+        if (!entry)
+            return null;
+        return entry.value;
+    }
+    /**
+     * Store a value in memory with optional TTL.
+     *
+     * @param key - Storage key to write.
+     * @param value - Value to store.
+     * @param ttlMs - Optional TTL in milliseconds.
+     * @returns Resolves when the value is stored.
+     */
+    async set(key, value, ttlMs) {
+        const expiresAt = typeof ttlMs === 'number' ? this.now() + ttlMs : null;
+        this.kv.set(key, { value, expiresAt });
+    }
+    /**
+     * Delete a key from the in-memory store.
+     *
+     * @param key - Storage key to delete.
+     * @returns Resolves when the key is removed.
+     */
+    async delete(key) {
+        this.kv.delete(key);
+        this.zsets.delete(key);
+    }
+    /**
+     * Increment a fixed-window counter with TTL handling.
+     *
+     * @param key - Storage key to increment.
+     * @param ttlMs - TTL window in milliseconds.
+     * @returns Updated counter value and remaining TTL.
+     */
+    async incr(key, ttlMs) {
+        this.cleanupKey(key);
+        const entry = this.kv.get(key);
+        if (!entry || typeof entry.value !== 'number') {
+            const expiresAt = this.now() + ttlMs;
+            this.kv.set(key, { value: 1, expiresAt });
+            return { count: 1, ttlMs };
+        }
+        const count = entry.value + 1;
+        entry.value = count;
+        if (!entry.expiresAt) {
+            entry.expiresAt = this.now() + ttlMs;
+        }
+        const remainingTtl = Math.max(0, (entry.expiresAt ?? this.now()) - this.now());
+        return { count, ttlMs: remainingTtl };
+    }
+    /**
+     * Read the TTL for a key when present.
+     *
+     * @param key - Storage key to inspect.
+     * @returns Remaining TTL in ms or null when no TTL is set.
+     */
+    async ttl(key) {
+        this.cleanupKey(key);
+        const entry = this.kv.get(key) ?? this.zsets.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiresAt == null)
+            return null;
+        return Math.max(0, entry.expiresAt - this.now());
+    }
+    /**
+     * Update the TTL for an existing key.
+     *
+     * @param key - Storage key to update.
+     * @param ttlMs - TTL in milliseconds.
+     * @returns Resolves after the TTL is updated.
+     */
+    async expire(key, ttlMs) {
+        const expiresAt = this.now() + ttlMs;
+        const kvEntry = this.kv.get(key);
+        if (kvEntry)
+            kvEntry.expiresAt = expiresAt;
+        const zEntry = this.zsets.get(key);
+        if (zEntry)
+            zEntry.expiresAt = expiresAt;
+    }
+    /**
+     * Add a member to a sorted set with the given score.
+     *
+     * @param key - Sorted-set key.
+     * @param score - Score to associate with the member.
+     * @param member - Member identifier.
+     * @returns Resolves when the member is added.
+     */
+    async zAdd(key, score, member) {
+        this.cleanupKey(key);
+        const entry = this.zsets.get(key) ?? { items: [], expiresAt: null };
+        const existingIndex = entry.items.findIndex((item) => item.member === member);
+        if (existingIndex >= 0) {
+            entry.items[existingIndex] = { score, member };
+        }
+        else {
+            entry.items.push({ score, member });
+        }
+        entry.items.sort((a, b) => a.score - b.score);
+        this.zsets.set(key, entry);
+    }
+    /**
+     * Remove sorted-set members with scores in the given range.
+     *
+     * @param key - Sorted-set key.
+     * @param min - Minimum score (inclusive).
+     * @param max - Maximum score (inclusive).
+     * @returns Resolves when the range is removed.
+     */
+    async zRemRangeByScore(key, min, max) {
+        this.cleanupKey(key);
+        const entry = this.zsets.get(key);
+        if (!entry)
+            return;
+        entry.items = entry.items.filter((item) => item.score < min || item.score > max);
+    }
+    /**
+     * Count members in a sorted set.
+     *
+     * @param key - Sorted-set key.
+     * @returns Number of members in the set.
+     */
+    async zCard(key) {
+        this.cleanupKey(key);
+        const entry = this.zsets.get(key);
+        return entry ? entry.items.length : 0;
+    }
+    /**
+     * Read sorted-set members in a score range.
+     *
+     * @param key - Sorted-set key.
+     * @param min - Minimum score (inclusive).
+     * @param max - Maximum score (inclusive).
+     * @returns Ordered members in the score range.
+     */
+    async zRangeByScore(key, min, max) {
+        this.cleanupKey(key);
+        const entry = this.zsets.get(key);
+        if (!entry)
+            return [];
+        return entry.items
+            .filter((item) => item.score >= min && item.score <= max)
+            .map((item) => item.member);
+    }
+    /**
+     * Atomically consume a fixed-window counter for the key.
+     *
+     * @param key - Storage key to consume.
+     * @param limit - Request limit for the window.
+     * @param windowMs - Window size in milliseconds.
+     * @param nowMs - Current timestamp in milliseconds.
+     * @returns Fixed-window consume result.
+     */
+    async consumeFixedWindow(key, _limit, windowMs, _nowMs) {
+        return this.incr(key, windowMs);
+    }
+    /**
+     * Atomically consume a sliding-window log for the key.
+     *
+     * @param key - Storage key to consume.
+     * @param limit - Request limit for the window.
+     * @param windowMs - Window size in milliseconds.
+     * @param nowMs - Current timestamp in milliseconds.
+     * @param member - Member identifier for this request.
+     * @returns Sliding-window consume result.
+     */
+    async consumeSlidingWindowLog(key, limit, windowMs, nowMs, member) {
+        await this.zRemRangeByScore(key, 0, nowMs - windowMs);
+        const count = await this.zCard(key);
+        if (count >= limit) {
+            const oldest = await this.zRangeByScore(key, Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY);
+            const oldestMember = oldest[0];
+            const oldestTs = parseMemberTimestamp(oldestMember, nowMs);
+            return { allowed: false, count, resetAt: oldestTs + windowMs };
+        }
+        await this.zAdd(key, nowMs, member);
+        await this.expire(key, windowMs);
+        const newCount = count + 1;
+        const oldest = await this.zRangeByScore(key, Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY);
+        const oldestMember = oldest[0];
+        const oldestTs = parseMemberTimestamp(oldestMember, nowMs);
+        return { allowed: true, count: newCount, resetAt: oldestTs + windowMs };
+    }
+    /**
+     * Delete keys with the given prefix.
+     *
+     * @param prefix - Prefix to match.
+     * @returns Resolves after matching keys are deleted.
+     */
+    async deleteByPrefix(prefix) {
+        for (const key of Array.from(this.kv.keys())) {
+            if (key.startsWith(prefix))
+                this.kv.delete(key);
+        }
+        for (const key of Array.from(this.zsets.keys())) {
+            if (key.startsWith(prefix))
+                this.zsets.delete(key);
+        }
+    }
+    /**
+     * Delete keys matching a glob pattern.
+     *
+     * @param pattern - Glob pattern to match.
+     * @returns Resolves after matching keys are deleted.
+     */
+    async deleteByPattern(pattern) {
+        const regex = globToRegex(pattern);
+        for (const key of Array.from(this.kv.keys())) {
+            if (regex.test(key))
+                this.kv.delete(key);
+        }
+        for (const key of Array.from(this.zsets.keys())) {
+            if (regex.test(key))
+                this.zsets.delete(key);
+        }
+    }
+    /**
+     * List keys that match a prefix.
+     *
+     * @param prefix - Prefix to match.
+     * @returns Matching keys.
+     */
+    async keysByPrefix(prefix) {
+        const keys = new Set();
+        const kvKeys = Array.from(this.kv.keys());
+        for (const key of kvKeys) {
+            this.cleanupKey(key);
+            if (this.kv.has(key) && key.startsWith(prefix)) {
+                keys.add(key);
+            }
+        }
+        const zsetKeys = Array.from(this.zsets.keys());
+        for (const key of zsetKeys) {
+            this.cleanupKey(key);
+            if (this.zsets.has(key) && key.startsWith(prefix)) {
+                keys.add(key);
+            }
+        }
+        return Array.from(keys);
+    }
+}
+exports.MemoryRateLimitStorage = MemoryRateLimitStorage;
+function globToRegex(glob) {
+    const escaped = glob.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    const regex = `^${escaped.replace(/\*/g, '.*')}$`;
+    return new RegExp(regex);
+}
+function parseMemberTimestamp(member, fallback) {
+    if (!member)
+        return fallback;
+    const prefix = member.split('-')[0];
+    const parsed = Number(prefix);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWVtb3J5LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3N0b3JhZ2UvbWVtb3J5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7QUFBQTs7Ozs7R0FLRzs7O0FBdUJIOzs7O0dBSUc7QUFDSCxNQUFhLHNCQUFzQjtJQUFuQztRQUNtQixPQUFFLEdBQUcsSUFBSSxHQUFHLEVBQW1CLENBQUM7UUFDaEMsVUFBSyxHQUFHLElBQUksR0FBRyxFQUFxQixDQUFDO0lBeVR4RCxDQUFDO0lBdlRTLEdBQUc7UUFDVCxPQUFPLElBQUksQ0FBQyxHQUFHLEVBQUUsQ0FBQztJQUNwQixDQUFDO0lBRU8sU0FBUyxDQUFDLFNBQXdCO1FBQ3hDLE9BQU8sU0FBUyxJQUFJLElBQUksSUFBSSxTQUFTLElBQUksSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDO0lBQ3RELENBQUM7SUFFRDs7OztPQUlHO0lBQ0ssVUFBVSxDQUFDLEdBQVc7UUFDNUIsTUFBTSxPQUFPLEdBQUcsSUFBSSxDQUFDLEVBQUUsQ0FBQyxHQUFHLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDakMsSUFBSSxPQUFPLElBQUksSUFBSSxDQUFDLFNBQVMsQ0FBQyxPQUFPLENBQUMsU0FBUyxDQUFDLEVBQUUsQ0FBQztZQUNqRCxJQUFJLENBQUMsRUFBRSxDQUFDLE1BQU0sQ0FBQyxHQUFHLENBQUMsQ0FBQztRQUN0QixDQUFDO1FBRUQsTUFBTSxNQUFNLEdBQUcsSUFBSSxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDbkMsSUFBSSxNQUFNLElBQUksSUFBSSxDQUFDLFNBQVMsQ0FBQyxNQUFNLENBQUMsU0FBUyxDQUFDLEVBQUUsQ0FBQztZQUMvQyxJQUFJLENBQUMsS0FBSyxDQUFDLE1BQU0sQ0FBQyxHQUFHLENBQUMsQ0FBQztRQUN6QixDQUFDO0lBQ0gsQ0FBQztJQUVEOzs7OztPQUtHO0lBQ0gsS0FBSyxDQUFDLEdBQUcsQ0FBYyxHQUFXO1FBQ2hDLElB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QyxHQUFHLENBQUMsQ0FBQztZQUNyQixJQUFJLElBQUksQ0FBQyxFQUFFLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxJQUFJLEdBQUcsQ0FBQyxVQUFVLENBQUMsTUFBTSxDQUFDLEVBQUUsQ0FBQztnQkFDL0MsSUFBSSxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsQ0FBQztZQUNoQixDQUFDO1FBQ0gsQ0FBQztRQUNELE1BQU0sUUFBUSxHQUFHLEtBQUssQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLEVBQUUsQ0FBQyxDQUFDO1FBQy9DLEtBQUssTUFBTSxHQUFHLElBQUksUUFBUSxFQUFFLENBQUM7WUFDM0IsSUFBSSxDQUFDLFVBQVUsQ0FBQyxHQUFHLENBQUMsQ0FBQztZQUNyQixJQUFJLElBQUksQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxJQUFJLEdBQUcsQ0FBQyxVQUFVLENBQUMsTUFBTSxDQUFDLEVBQUUsQ0FBQztnQkFDbEQsSUFBSSxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsQ0FBQztZQUNoQixDQUFDO1FBQ0gsQ0FBQztRQUNELE9BQU8sS0FBSyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUMxQixDQUFDO0NBQ0Y7QUEzVEQsd0RBMlRDO0FBRUQsU0FBUyxXQUFXLENBQUMsSUFBWTtJQUMvQixNQUFNLE9BQU8sR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDLG9CQUFvQixFQUFFLE1BQU0sQ0FBQyxDQUFDO0lBQzNELE1BQU0sS0FBSyxHQUFHLElBQUksT0FBTyxDQUFDLE9BQU8sQ0FBQyxLQUFLLEVBQUUsSUFBSSxDQUFDLEdBQUcsQ0FBQztJQUNsRCxPQUFPLElBQUksTUFBTSxDQUFDLEtBQUssQ0FBQyxDQUFDO0FBQzNCLENBQUM7QUFFRCxTQUFTLG9CQUFvQixDQUMzQixNQUEwQixFQUMxQixRQUFnQjtJQUVoQixJQUFJLENBQUMsTUFBTTtRQUFFLE9BQU8sUUFBUSxDQUFDO0lBQzdCLE1BQU0sTUFBTSxHQUFHLE1BQU0sQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDcEMsTUFBTSxNQUFNLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQyxDQUFDO0lBQzlCLE9BQU8sTUFBTSxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQyxRQUFRLENBQUM7QUFDckQsQ0FBQyJ9

package/dist/storage/redis.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Redis storage.
+ *
+ * Uses Lua scripts for atomic fixed/sliding window operations.
+ */
+import Redis, { type RedisOptions } from 'ioredis';
+import type { FixedWindowConsumeResult, RateLimitStorage, SlidingWindowConsumeResult } from '../types';
+/**
+ * Redis-backed storage with Lua scripts for atomic window operations.
+ *
+ * @implements RateLimitStorage
+ */
+export declare class RedisRateLimitStorage implements RateLimitStorage {
+    readonly redis: Redis;
+    constructor(redis?: Redis | RedisOptions);
+    /**
+     * Read a value from Redis and JSON-decode it.
+     *
+     * @param key - Storage key to read.
+     * @returns Parsed value or null when absent.
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Store a value in Redis with optional TTL.
+     *
+     * @param key - Storage key to write.
+     * @param value - Value to serialize and store.
+     * @param ttlMs - Optional TTL in milliseconds.
+     * @returns Resolves when the value is stored.
+     */
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
+    /**
+     * Delete a key from Redis.
+     *
+     * @param key - Storage key to delete.
+     * @returns Resolves when the key is removed.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Read the TTL for a key when present.
+     *
+     * @param key - Storage key to inspect.
+     * @returns Remaining TTL in ms or null when no TTL is set.
+     */
+    ttl(key: string): Promise<number | null>;
+    /**
+     * Update the TTL for an existing key.
+     *
+     * @param key - Storage key to update.
+     * @param ttlMs - TTL in milliseconds.
+     * @returns Resolves after the TTL is updated.
+     */
+    expire(key: string, ttlMs: number): Promise<void>;
+    /**
+     * Add a member to a sorted set with the given score.
+     *
+     * @param key - Sorted-set key.
+     * @param score - Score to associate with the member.
+     * @param member - Member identifier.
+     * @returns Resolves when the member is added.
+     */
+    zAdd(key: string, score: number, member: string): Promise<void>;
+    /**
+     * Remove sorted-set members with scores in the given range.
+     *
+     * @param key - Sorted-set key.
+     * @param min - Minimum score (inclusive).
+     * @param max - Maximum score (inclusive).
+     * @returns Resolves when the range is removed.
+     */
+    zRemRangeByScore(key: string, min: number, max: number): Promise<void>;
+    /**
+     * Count members in a sorted set.
+     *
+     * @param key - Sorted-set key.
+     * @returns Number of members in the set.
+     */
+    zCard(key: string): Promise<number>;
+    /**
+     * Read sorted-set members in a score range.
+     *
+     * @param key - Sorted-set key.
+     * @param min - Minimum score (inclusive).
+     * @param max - Maximum score (inclusive).
+     * @returns Ordered members in the score range.
+     */
+    zRangeByScore(key: string, min: number, max: number): Promise<string[]>;
+    /**
+     * Atomically consume a fixed-window counter via Lua.
+     *
+     * @param key - Storage key to consume.
+     * @param _limit - Limit (unused by the script).
+     * @param windowMs - Window size in milliseconds.
+     * @param _nowMs - Current time (unused by the script).
+     * @returns Fixed-window consume result.
+     */
+    consumeFixedWindow(key: string, _limit: number, windowMs: number, _nowMs: number): Promise<FixedWindowConsumeResult>;
+    /**
+     * Atomically consume a sliding-window log via Lua.
+     *
+     * @param key - Storage key to consume.
+     * @param limit - Request limit for the window.
+     * @param windowMs - Window size in milliseconds.
+     * @param nowMs - Current timestamp in milliseconds.
+     * @param member - Member identifier for this request.
+     * @returns Sliding-window consume result.
+     */
+    consumeSlidingWindowLog(key: string, limit: number, windowMs: number, nowMs: number, member: string): Promise<SlidingWindowConsumeResult>;
+    /**
+     * Delete keys with the given prefix.
+     *
+     * @param prefix - Prefix to match.
+     * @returns Resolves after matching keys are deleted.
+     */
+    deleteByPrefix(prefix: string): Promise<void>;
+    /**
+     * Delete keys matching a glob pattern using SCAN to avoid blocking Redis.
+     *
+     * @param pattern - Glob pattern to match keys against.
+     * @returns Resolves after matching keys are deleted.
+     */
+    deleteByPattern(pattern: string): Promise<void>;
+    /**
+     * List keys that match a prefix using SCAN.
+     *
+     * @param prefix - Prefix to match.
+     * @returns Matching keys.
+     */
+    keysByPrefix(prefix: string): Promise<string[]>;
+}