@commandkit/ratelimit 0.0.0-dev.20260317060555

package/dist/utils/config.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Limiter config resolution.
+ *
+ * Applies defaults and merges overrides into concrete limiter settings
+ * used by the engine and plugin.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LIMITER = void 0;
+exports.mergeLimiterConfigs = mergeLimiterConfigs;
+exports.resolveLimiterConfig = resolveLimiterConfig;
+exports.resolveLimiterConfigs = resolveLimiterConfigs;
+const time_1 = require("./time");
+const DEFAULT_MAX_REQUESTS = 10;
+const DEFAULT_INTERVAL_MS = 60000;
+const DEFAULT_ALGORITHM = 'fixed-window';
+const DEFAULT_SCOPE = 'user';
+/**
+ * Default limiter used when no explicit configuration is provided.
+ */
+exports.DEFAULT_LIMITER = {
+    maxRequests: DEFAULT_MAX_REQUESTS,
+    interval: DEFAULT_INTERVAL_MS,
+    algorithm: DEFAULT_ALGORITHM,
+    scope: DEFAULT_SCOPE,
+};
+/**
+ * Merge limiter configs; later values override earlier ones for layering.
+ *
+ * @param configs - Limiter configs ordered from lowest to highest priority.
+ * @returns Merged limiter config with later overrides applied.
+ */
+function mergeLimiterConfigs(...configs) {
+    return configs.reduce((acc, cfg) => ({ ...acc, ...(cfg ?? {}) }), {});
+}
+/**
+ * Resolve a limiter config for a single scope with defaults applied.
+ *
+ * @param config - Base limiter configuration.
+ * @param scope - Scope to resolve for the limiter.
+ * @returns Resolved limiter config with defaults and derived values.
+ */
+function resolveLimiterConfig(config, scope) {
+    const maxRequests = typeof config.maxRequests === 'number' && config.maxRequests > 0
+        ? config.maxRequests
+        : DEFAULT_MAX_REQUESTS;
+    const intervalMs = (0, time_1.clampAtLeast)((0, time_1.resolveDuration)(config.interval, DEFAULT_INTERVAL_MS), 1);
+    const algorithm = config.algorithm ?? DEFAULT_ALGORITHM;
+    const intervalSeconds = intervalMs / 1000;
+    const burst = typeof config.burst === 'number' && config.burst > 0
+        ? config.burst
+        : maxRequests;
+    const refillRate = typeof config.refillRate === 'number' && config.refillRate > 0
+        ? config.refillRate
+        : maxRequests / intervalSeconds;
+    const leakRate = typeof config.leakRate === 'number' && config.leakRate > 0
+        ? config.leakRate
+        : maxRequests / intervalSeconds;
+    return {
+        maxRequests,
+        intervalMs,
+        algorithm,
+        scope,
+        burst,
+        refillRate,
+        leakRate,
+        violations: config.violations,
+    };
+}
+/**
+ * Resolve a stable window id when one is missing.
+ *
+ * @param window - Window config entry.
+ * @param index - Index of the window in the config list.
+ * @returns Window id string.
+ */
+function resolveWindowId(window, index) {
+    if (window.id && window.id.trim())
+        return window.id;
+    /**
+     * Stable fallback IDs keep window identity deterministic for resets.
+     */
+    return `w${index + 1}`;
+}
+/**
+ * Resolve limiter configs for a scope across all configured windows.
+ *
+ * @param config - Base limiter configuration that may include windows.
+ * @param scope - Scope to resolve for the limiter.
+ * @returns Resolved limiter configs for each window (or a single config).
+ */
+function resolveLimiterConfigs(config, scope) {
+    const windows = config.windows;
+    if (!windows || windows.length === 0) {
+        return [resolveLimiterConfig(config, scope)];
+    }
+    const { windows: _windows, ...base } = config;
+    return windows.map((window, index) => {
+        const windowId = resolveWindowId(window, index);
+        const merged = { ...base, ...window };
+        const resolved = resolveLimiterConfig(merged, scope);
+        return windowId ? { ...resolved, windowId } : resolved;
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uZmlnLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3V0aWxzL2NvbmZpZy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7O0dBS0c7OztBQWdDSCxrREFPQztBQVNELG9EQXlDQztBQXdCRCxzREFpQkM7QUF6SEQsaUNBQXVEO0FBRXZELE1BQU0sb0JBQW9CLEdBQUcsRUFBRSxDQUFDO0FBQ2hDLE1BQU0sbUJBQW1CLEdBQUcsS0FBTSxDQUFDO0FBQ25DLE1BQU0saUJBQWlCLEdBQTJCLGNBQWMsQ0FBQztBQUNqRSxNQUFNLGFBQWEsR0FBbUIsTUFBTSxDQUFDO0FBRTdDOztHQUVHO0FBQ1UsUUFBQSxlQUFlLEdBQTJCO0lBQ3JELFdBQVcsRUFBRSxvQkFBb0I7SUFDakMsUUFBUSxFQUFFLG1CQUFtQjtJQUM3QixTQUFTLEVBQUUsaUJBQWlCO0lBQzVCLEtBQUssRUFBRSxhQUFhO0NBQ3JCLENBQUM7QUFFRjs7Ozs7R0FLRztBQUNILFNBQWdCLG1CQUFtQixDQUNqQyxHQUFHLE9BQWtEO0lBRXJELE9BQU8sT0FBTyxDQUFDLE1BQU0sQ0FDbkIsQ0FBQyxHQUFHLEVBQUUsR0FBRyxFQUFFLEVBQUUsQ0FBQyxDQUFDLEVBQUUsR0FBRyxHQUFHLEVBQUUsR0FBRyxDQUFDLEdBQUcsSUFBSSxFQUFFLENBQUMsRUFBRSxDQUFDLEVBQzFDLEVBQUUsQ0FDSCxDQUFDO0FBQ0osQ0FBQztBQUVEOzs7Ozs7R0FNRztBQUNILFNBQWdCLG9CQUFvQixDQUNsQyxNQUE4QixFQUM5QixLQUFxQjtJQUVyQixNQUFNLFdBQVcsR0FDZixPQUFPLE1BQU0sQ0FBQyxXQUFXLEtBQUssUUFBUSxJQUFJLE1BQU0sQ0FBQyxXQUFXLEdBQUcsQ0FBQztRQUM5RCxDQUFDLENBQUMsTUFBTSxDQUFDLFdBQVc7UUFDcEIsQ0FBQyxDQUFDLG9CQUFvQixDQUFDO0lBRTNCLE1BQU0sVUFBVSxHQUFHLElBQUEsbUJBQVksRUFDN0IsSUFBQSxzQkFB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

package/dist/utils/keys.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Key construction helpers.
+ *
+ * Builds consistent storage keys for scopes and exemptions across
+ * message and interaction sources so limits remain comparable.
+ */
+import { Message } from 'discord.js';
+import type { Interaction } from 'discord.js';
+import type { Context } from 'commandkit';
+import type { LoadedCommand } from 'commandkit';
+import type { RateLimitExemptionScope, RateLimitKeyResolver, RateLimitScope } from '../types';
+/**
+ * Inputs for resolving a scope-based key from a command/source.
+ */
+export interface ResolveScopeKeyParams {
+    ctx: Context;
+    source: Interaction | Message;
+    command: LoadedCommand;
+    scope: RateLimitScope;
+    keyPrefix?: string;
+    keyResolver?: RateLimitKeyResolver;
+}
+/**
+ * Resolved key paired with its scope for aggregation.
+ */
+export interface ResolvedScopeKey {
+    scope: RateLimitScope;
+    key: string;
+}
+/**
+ * Extract role IDs from a message/interaction for role-based limits.
+ *
+ * @param source - Interaction or message to read role data from.
+ * @returns Array of role IDs for the source, or an empty array.
+ */
+export declare function getRoleIds(source: Interaction | Message): string[];
+/**
+ * Build a storage key for a temporary exemption entry.
+ *
+ * @param scope - Exemption scope to encode.
+ * @param id - Scope identifier (user, guild, role, etc.).
+ * @param keyPrefix - Optional prefix to prepend to the key.
+ * @returns Fully-qualified exemption storage key.
+ */
+export declare function buildExemptionKey(scope: RateLimitExemptionScope, id: string, keyPrefix?: string): string;
+/**
+ * Build a prefix for scanning exemption keys in storage.
+ *
+ * @param keyPrefix - Optional prefix to prepend to the key.
+ * @param scope - Optional exemption scope to narrow the prefix.
+ * @returns Prefix suitable for storage scans.
+ */
+export declare function buildExemptionPrefix(keyPrefix?: string, scope?: RateLimitExemptionScope): string;
+/**
+ * Parse an exemption key into scope and ID for listing.
+ *
+ * @param key - Exemption key to parse.
+ * @param keyPrefix - Optional prefix to strip before parsing.
+ * @returns Parsed scope/id pair or null when the key is invalid.
+ */
+export declare function parseExemptionKey(key: string, keyPrefix?: string): {
+    scope: RateLimitExemptionScope;
+    id: string;
+} | null;
+/**
+ * Resolve all exemption keys that could apply to a source.
+ *
+ * @param source - Interaction or message to resolve keys for.
+ * @param keyPrefix - Optional prefix to prepend to keys.
+ * @returns Exemption keys that should be checked for the source.
+ */
+export declare function resolveExemptionKeys(source: Interaction | Message, keyPrefix?: string): string[];
+/**
+ * Resolve the storage key for a single scope.
+ *
+ * @param params - Inputs required to resolve the scope key.
+ * @returns Resolved scope key or null when required identifiers are missing.
+ */
+export declare function resolveScopeKey({ ctx, source, command, scope, keyPrefix, keyResolver, }: ResolveScopeKeyParams): ResolvedScopeKey | null;
+/**
+ * Resolve keys for multiple scopes, dropping unresolvable ones.
+ *
+ * @param params - Inputs required to resolve all scope keys.
+ * @returns Array of resolved scope keys.
+ */
+export declare function resolveScopeKeys(params: Omit<ResolveScopeKeyParams, 'scope'> & {
+    scopes: RateLimitScope[];
+}): ResolvedScopeKey[];
+/**
+ * Build a prefix for resets by scope/identifier.
+ *
+ * @param scope - Scope to build the prefix for.
+ * @param keyPrefix - Optional prefix to prepend to the key.
+ * @param identifiers - Identifiers required for the scope.
+ * @returns Prefix string or null when identifiers are missing.
+ */
+export declare function buildScopePrefix(scope: RateLimitScope, keyPrefix: string | undefined, identifiers: {
+    userId?: string;
+    guildId?: string;
+    channelId?: string;
+    commandName?: string;
+}): string | null;

package/dist/utils/keys.js

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * Key construction helpers.
+ *
+ * Builds consistent storage keys for scopes and exemptions across
+ * message and interaction sources so limits remain comparable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRoleIds = getRoleIds;
+exports.buildExemptionKey = buildExemptionKey;
+exports.buildExemptionPrefix = buildExemptionPrefix;
+exports.parseExemptionKey = parseExemptionKey;
+exports.resolveExemptionKeys = resolveExemptionKeys;
+exports.resolveScopeKey = resolveScopeKey;
+exports.resolveScopeKeys = resolveScopeKeys;
+exports.buildScopePrefix = buildScopePrefix;
+const discord_js_1 = require("discord.js");
+const types_1 = require("../types");
+const constants_1 = require("../constants");
+/**
+ * Apply an optional prefix to a storage key.
+ *
+ * @param prefix - Optional prefix to prepend.
+ * @param key - Base key to prefix.
+ * @returns Prefixed key.
+ */
+function applyPrefix(prefix, key) {
+    if (!prefix)
+        return key;
+    return `${prefix}${key}`;
+}
+/**
+ * Resolve a user id from a message or interaction.
+ *
+ * @param source - Interaction or message source.
+ * @returns User id or null when unavailable.
+ */
+function getUserId(source) {
+    if (source instanceof discord_js_1.Message)
+        return source.author.id;
+    return source.user?.id ?? null;
+}
+/**
+ * Resolve a guild id from a message or interaction.
+ *
+ * @param source - Interaction or message source.
+ * @returns Guild id or null when unavailable.
+ */
+function getGuildId(source) {
+    if (source instanceof discord_js_1.Message)
+        return source.guildId ?? null;
+    return source.guildId ?? null;
+}
+/**
+ * Resolve a channel id from a message or interaction.
+ *
+ * @param source - Interaction or message source.
+ * @returns Channel id or null when unavailable.
+ */
+function getChannelId(source) {
+    if (source instanceof discord_js_1.Message)
+        return source.channelId ?? null;
+    return source.channelId ?? null;
+}
+/**
+ * Resolve a parent category id from a channel object.
+ *
+ * @param channel - Channel object to inspect.
+ * @returns Parent id or null when unavailable.
+ */
+function getParentId(channel) {
+    if (!channel || typeof channel !== 'object')
+        return null;
+    if (!('parentId' in channel))
+        return null;
+    const parentId = channel.parentId;
+    return parentId ?? null;
+}
+/**
+ * Resolve a category id from a message or interaction.
+ *
+ * @param source - Interaction or message source.
+ * @returns Category id or null when unavailable.
+ */
+function getCategoryId(source) {
+    if (source instanceof discord_js_1.Message) {
+        return getParentId(source.channel);
+    }
+    return getParentId(source.channel);
+}
+/**
+ * Extract role IDs from a message/interaction for role-based limits.
+ *
+ * @param source - Interaction or message to read role data from.
+ * @returns Array of role IDs for the source, or an empty array.
+ */
+function getRoleIds(source) {
+    const roles = source.member?.roles;
+    if (!roles)
+        return [];
+    if (Array.isArray(roles))
+        return roles;
+    if ('cache' in roles) {
+        return roles.cache.map((role) => role.id);
+    }
+    return [];
+}
+/**
+ * Build a storage key for a temporary exemption entry.
+ *
+ * @param scope - Exemption scope to encode.
+ * @param id - Scope identifier (user, guild, role, etc.).
+ * @param keyPrefix - Optional prefix to prepend to the key.
+ * @returns Fully-qualified exemption storage key.
+ */
+function buildExemptionKey(scope, id, keyPrefix) {
+    const prefix = keyPrefix ?? '';
+    return applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}exempt:${scope}:${id}`);
+}
+/**
+ * Build a prefix for scanning exemption keys in storage.
+ *
+ * @param keyPrefix - Optional prefix to prepend to the key.
+ * @param scope - Optional exemption scope to narrow the prefix.
+ * @returns Prefix suitable for storage scans.
+ */
+function buildExemptionPrefix(keyPrefix, scope) {
+    const prefix = keyPrefix ?? '';
+    const base = `${constants_1.DEFAULT_KEY_PREFIX}exempt:`;
+    if (!scope)
+        return applyPrefix(prefix, base);
+    return applyPrefix(prefix, `${base}${scope}:`);
+}
+/**
+ * Parse an exemption key into scope and ID for listing.
+ *
+ * @param key - Exemption key to parse.
+ * @param keyPrefix - Optional prefix to strip before parsing.
+ * @returns Parsed scope/id pair or null when the key is invalid.
+ */
+function parseExemptionKey(key, keyPrefix) {
+    const prefix = keyPrefix ?? '';
+    const base = `${prefix}${constants_1.DEFAULT_KEY_PREFIX}exempt:`;
+    if (!key.startsWith(base))
+        return null;
+    const rest = key.slice(base.length);
+    const [scope, ...idParts] = rest.split(':');
+    if (!scope || idParts.length === 0)
+        return null;
+    if (!types_1.RATE_LIMIT_EXEMPTION_SCOPES.includes(scope)) {
+        return null;
+    }
+    return { scope: scope, id: idParts.join(':') };
+}
+/**
+ * Resolve all exemption keys that could apply to a source.
+ *
+ * @param source - Interaction or message to resolve keys for.
+ * @param keyPrefix - Optional prefix to prepend to keys.
+ * @returns Exemption keys that should be checked for the source.
+ */
+function resolveExemptionKeys(source, keyPrefix) {
+    const keys = [];
+    const userId = getUserId(source);
+    if (userId) {
+        keys.push(buildExemptionKey('user', userId, keyPrefix));
+    }
+    const guildId = getGuildId(source);
+    if (guildId) {
+        keys.push(buildExemptionKey('guild', guildId, keyPrefix));
+    }
+    const channelId = getChannelId(source);
+    if (channelId) {
+        keys.push(buildExemptionKey('channel', channelId, keyPrefix));
+    }
+    const categoryId = getCategoryId(source);
+    if (categoryId) {
+        keys.push(buildExemptionKey('category', categoryId, keyPrefix));
+    }
+    const roleIds = getRoleIds(source);
+    for (const roleId of roleIds) {
+        keys.push(buildExemptionKey('role', roleId, keyPrefix));
+    }
+    return keys;
+}
+/**
+ * Resolve the storage key for a single scope.
+ *
+ * @param params - Inputs required to resolve the scope key.
+ * @returns Resolved scope key or null when required identifiers are missing.
+ */
+function resolveScopeKey({ ctx, source, command, scope, keyPrefix, keyResolver, }) {
+    const prefix = keyPrefix ?? '';
+    const commandName = ctx.commandName || command.command.name;
+    switch (scope) {
+        case 'user': {
+            const userId = getUserId(source);
+            if (!userId)
+                return null;
+            return {
+                scope,
+                key: applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}user:${userId}:${commandName}`),
+            };
+        }
+        case 'guild': {
+            const guildId = getGuildId(source);
+            if (!guildId)
+                return null;
+            return {
+                scope,
+                key: applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}guild:${guildId}:${commandName}`),
+            };
+        }
+        case 'channel': {
+            const channelId = getChannelId(source);
+            if (!channelId)
+                return null;
+            return {
+                scope,
+                key: applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}channel:${channelId}:${commandName}`),
+            };
+        }
+        case 'global': {
+            return {
+                scope,
+                key: applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}global:${commandName}`),
+            };
+        }
+        case 'user-guild': {
+            const userId = getUserId(source);
+            const guildId = getGuildId(source);
+            if (!userId || !guildId)
+                return null;
+            return {
+                scope,
+                key: applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}user:${userId}:guild:${guildId}:${commandName}`),
+            };
+        }
+        case 'custom': {
+            if (!keyResolver)
+                return null;
+            const customKey = keyResolver(ctx, command, source);
+            if (!customKey)
+                return null;
+            return {
+                scope,
+                key: applyPrefix(prefix, customKey),
+            };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Resolve keys for multiple scopes, dropping unresolvable ones.
+ *
+ * @param params - Inputs required to resolve all scope keys.
+ * @returns Array of resolved scope keys.
+ */
+function resolveScopeKeys(params) {
+    const results = [];
+    for (const scope of params.scopes) {
+        const resolved = resolveScopeKey({ ...params, scope });
+        if (resolved)
+            results.push(resolved);
+    }
+    return results;
+}
+/**
+ * Build a prefix for resets by scope/identifier.
+ *
+ * @param scope - Scope to build the prefix for.
+ * @param keyPrefix - Optional prefix to prepend to the key.
+ * @param identifiers - Identifiers required for the scope.
+ * @returns Prefix string or null when identifiers are missing.
+ */
+function buildScopePrefix(scope, keyPrefix, identifiers) {
+    const prefix = keyPrefix ?? '';
+    switch (scope) {
+        case 'user':
+            return identifiers.userId
+                ? applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}user:${identifiers.userId}:`)
+                : null;
+        case 'guild':
+            return identifiers.guildId
+                ? applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}guild:${identifiers.guildId}:`)
+                : null;
+        case 'channel':
+            return identifiers.channelId
+                ? applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}channel:${identifiers.channelId}:`)
+                : null;
+        case 'global':
+            return applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}global:`);
+        case 'user-guild':
+            return identifiers.userId && identifiers.guildId
+                ? applyPrefix(prefix, `${constants_1.DEFAULT_KEY_PREFIX}user:${identifiers.userId}:guild:${identifiers.guildId}:`)
+                : null;
+        case 'custom':
+            return null;
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoia2V5cy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy91dGlscy9rZXlzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7QUFBQTs7Ozs7R0FLRzs7QUErR0gsZ0NBUUM7QUFVRCw4Q0FPQztBQVNELG9EQVFDO0FBU0QsOENBY0M7QUFTRCxvREFnQ0M7QUFRRCwwQ0EyRUM7QUFRRCw0Q0FXQztBQVVELDRDQStDQztBQXRYRCwyQ0FBcUM7QUFTckMsb0NBQXVEO0FBQ3ZELDRDQUFrRDtBQXNCbEQ7Ozs7OztHQU1HO0FBQ0gsU0FBUyxXQUFXLENBQUMsTUFBMEIsRUFBRSxHQUFXO0lBQzFELElBQUksQ0FBQyxNQUFNO1FBQUUsT0FBTyxHQUFHLENBQUM7SUFDeEIsT0FBTyxHQUFHLE1BQU0sR0FBRyxHQUFHLEVBQUUsQ0FBQztBQUMzQixDQUFDO0FBRUQ7Ozs7O0dBS0c7QUFDSCxTQUFTLFNBQVMsQ0FBQyxNQUE2QjtJQUM5QyxJQUFJLE1BQU0sWUFBWSxvQkFBTztRQUFFLE9BQU8sTUFBTSxDQUFDLE1BQU0sQ0FBQyxFQUFFLENBQUM7SUFDdkQsT0FBTyxNQUFNLENBQUMsSUFBSSxFQUFFLEVBQUUsSUFBSSxJQUFJLENBQUM7QUFDakMsQ0FBQztBQUVEOzs7OztHQUtHO0FBQ0gsU0FBUyxVQUFVLENBQUMsTUFBNkI7SUFDL0MsSUFBSSxNQUFNLFlBQVksb0JBQU87UUFBRSxPQUFPLE1BQU0sQ0FBQyxPQUFPLElBQUksSUFBSSxDQUFDO0lBQzdELE9BQU8sTUFBTSxDQUFDLE9BQU8sSUFBSSxJQUFJLENBQUM7QUFDaEMsQ0FBQztBQUVEOzs7OztHQUtHO0FBQ0gsU0FBUyxZQUFZLENBQUMsTUFBNkI7SUFDakQsSUFBSSxNQUFNLFlBQVksb0JBQU87UUFBRSxPQUFPLE1BQU0sQ0FBQyxTQUFTLElBQUksSUFBSSxDQUFDO0lBQy9ELE9BQU8sTUFBTSxDQUFDLFNBQVMsSUFBSSxJQUFJLENBQUM7QUFDbEMsQ0FBQztBQUVEOzs7OztHQUtH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

package/dist/utils/locking.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Storage-scoped locking helpers.
+ *
+ * Serializes fallback storage operations per key to reduce same-process races.
+ */
+import type { RateLimitStorage } from '../types';
+type LockedFn<T> = () => Promise<T>;
+/**
+ * Serialize work for a storage key to avoid same-process conflicts.
+ *
+ * @param storage - Storage instance that owns the key.
+ * @param key - Storage key to lock on.
+ * @param fn - Async function to run under the lock.
+ * @returns Result of the locked function.
+ */
+export declare function withStorageKeyLock<T>(storage: RateLimitStorage, key: string, fn: LockedFn<T>): Promise<T>;
+export {};

package/dist/utils/locking.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Storage-scoped locking helpers.
+ *
+ * Serializes fallback storage operations per key to reduce same-process races.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withStorageKeyLock = withStorageKeyLock;
+/**
+ * Queue-based mutex keyed by string identifiers.
+ */
+class KeyedMutex {
+    constructor() {
+        this.queues = new Map();
+    }
+    /**
+     * Run a function exclusively for the given key.
+     *
+     * @param key - Key to serialize on.
+     * @param fn - Async function to run under the lock.
+     * @returns Result of the locked function.
+     */
+    async run(key, fn) {
+        const previous = this.queues.get(key) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        const tail = previous.then(() => current);
+        this.queues.set(key, tail);
+        await previous;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+            if (this.queues.get(key) === tail) {
+                this.queues.delete(key);
+            }
+        }
+    }
+}
+const mutexByStorage = new WeakMap();
+/**
+ * Serialize work for a storage key to avoid same-process conflicts.
+ *
+ * @param storage - Storage instance that owns the key.
+ * @param key - Storage key to lock on.
+ * @param fn - Async function to run under the lock.
+ * @returns Result of the locked function.
+ */
+async function withStorageKeyLock(storage, key, fn) {
+    let mutex = mutexByStorage.get(storage);
+    if (!mutex) {
+        mutex = new KeyedMutex();
+        mutexByStorage.set(storage, mutex);
+    }
+    return mutex.run(key, fn);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibG9ja2luZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy91dGlscy9sb2NraW5nLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7QUFBQTs7OztHQUlHOztBQWtESCxnREFXQztBQXZERDs7R0FFRztBQUNILE1BQU0sVUFBVTtJQUFoQjtRQUNtQixXQUFNLEdBQUcsSUFBSSxHQUFHLEVBQXlCLENBQUM7SUE0QjdELENBQUM7SUExQkM7Ozs7OztPQU1HO0lBQ0ksS0FBSyxDQUFDLEdBQUcsQ0FBSSxHQUFXLEVBQUUsRUFBZTtRQUM5QyxNQUFNLFFBQVEsR0FBRyxJQUFJLENBQUMsTUFBTSxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsSUFBSSxPQUFPLENBQUMsT0FBTyxFQUFFLENBQUM7UUFDM0QsSUFBSSxPQUFtQixDQUFDO1FBQ3hCLE1BQU0sT0FBTyxHQUFHLElBQUksT0FBTyxDQUFPLENBQUMsT0FBTyxFQUFFLEVBQUU7WUFDNUMsT0FBTyxHQUFHLE9BQU8sQ0FBQztRQUNwQixDQUFDLENBQUMsQ0FBQztRQUNILE1BQU0sSUFBSSxHQUFHLFFBQVEsQ0FBQyxJQUFJLENBQUMsR0FBRyxFQUFFLENBQUMsT0FBTyxDQUFDLENBQUM7UUFDMUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxHQUFHLENBQUMsR0FBRyxFQUFFLElBQUksQ0FBQyxDQUFDO1FBRTNCLE1BQU0sUUFBUSxDQUFDO1FBQ2YsSUFBSSxDQUFDO1lBQ0gsT0FBTyxNQUFNLEVBQUUsRUFBRSxDQUFDO1FBQ3BCLENBQUM7Z0JBQVMsQ0FBQztZQUNULE9BQVEsRUFBRSxDQUFDO1lBQ1gsSUFBSSxJQUFJLENBQUMsTUFBTSxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsS0FBSyxJQUFJLEVBQUUsQ0FBQztnQkFDbEMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxNQUFNLENBQUMsR0FBRyxDQUFDLENBQUM7WUFDMUIsQ0FBQztRQUNILENBQUM7SUFDSCxDQUFDO0NBQ0Y7QUFFRCxNQUFNLGNBQWMsR0FBRyxJQUFJLE9BQU8sRUFBZ0MsQ0FBQztBQUVuRTs7Ozs7OztHQU9HO0FBQ0ksS0FBSyxVQUFVLGtCQUFrQixDQUN0QyxPQUF5QixFQUN6QixHQUFXLEVBQ1gsRUFBZTtJQUVmLElBQUksS0FBSyxHQUFHLGNBQWMsQ0FBQyxHQUFHLENBQUMsT0FBTyxDQUFDLENBQUM7SUFDeEMsSUFBSSxDQUFDLEtBQUssRUFBRSxDQUFDO1FBQ1gsS0FBSyxHQUFHLElBQUksVUFBVSxFQUFFLENBQUM7UUFDekIsY0FBYyxDQUFDLEdBQUcsQ0FBQyxPQUFPLEVBQUUsS0FBSyxDQUFDLENBQUM7SUFDckMsQ0FBQztJQUNELE9BQU8sS0FBSyxDQUFDLEdBQUcsQ0FBQyxHQUFHLEVBQUUsRUFBRSxDQUFDLENBQUM7QUFDNUIsQ0FBQyJ9

package/dist/utils/time.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Time helpers for rate limits.
+ *
+ * Converts user-friendly durations into milliseconds and clamps values
+ * so storage and algorithms always receive safe inputs.
+ */
+import type { DurationLike } from '../types';
+/**
+ * Resolve a duration input into milliseconds with a fallback.
+ *
+ * @param value - Duration input as ms or string.
+ * @param fallback - Fallback value used when parsing fails.
+ * @returns Parsed duration in milliseconds.
+ */
+export declare function resolveDuration(value: DurationLike | undefined, fallback: number): number;
+/**
+ * Clamp a number to a minimum value to avoid zero/negative windows.
+ *
+ * @param value - Value to clamp.
+ * @param min - Minimum allowed value.
+ * @returns The clamped value.
+ */
+export declare function clampAtLeast(value: number, min: number): number;