@commandkit/ratelimit 0.0.0-dev.20260317060555

package/dist/errors.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Rate limit error type.
+ *
+ * Lets callers distinguish rate-limit failures from other errors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitError = void 0;
+/**
+ * Error thrown by the directive wrapper when a function is rate-limited.
+ *
+ * @extends Error
+ */
+class RateLimitError extends Error {
+    /**
+     * Create a rate-limit error with the stored result payload.
+     *
+     * @param result - Aggregated rate-limit result.
+     * @param message - Optional error message override.
+     */
+    constructor(result, message) {
+        super(message ?? 'Rate limit exceeded');
+        this.name = 'RateLimitError';
+        this.result = result;
+    }
+}
+exports.RateLimitError = RateLimitError;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2Vycm9ycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7R0FJRzs7O0FBSUg7Ozs7R0FJRztBQUNILE1BQWEsY0FBZSxTQUFRLEtBQUs7SUFHdkM7Ozs7O09BS0c7SUFDSCxZQUFtQixNQUEyQixFQUFFLE9BQWdCO1FBQzlELEtBQUssQ0FBQyxPQUFPLElBQUkscUJBQXFCLENBQUMsQ0FBQztRQUN4QyxJQUFJLENBQUMsSUFBSSxHQUFHLGdCQUFnQixDQUFDO1FBQzdCLElBQUksQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFDO0lBQ3ZCLENBQUM7Q0FDRjtBQWRELHdDQWNDIn0=

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import './augmentation';
+import type { CommandKitPlugin } from 'commandkit';
+/**
+ * Create compiler + runtime plugins for rate limiting.
+ *
+ * Runtime options are provided via configureRatelimit().
+ *
+ * @param options - Optional compiler plugin configuration.
+ * @returns Ordered array of compiler and runtime plugins.
+ */
+export declare function ratelimit(options?: Partial<{
+    compiler: import('commandkit').CommonDirectiveTransformerOptions;
+}>): CommandKitPlugin[];
+export * from './types';
+export * from './constants';
+export * from './runtime';
+export * from './configure';
+export * from './errors';
+export * from './api';
+export * from './plugin';
+export * from './directive/use-ratelimit';
+export * from './directive/use-ratelimit-directive';
+export * from './engine/RateLimitEngine';
+export * from './engine/algorithms/fixed-window';
+export * from './engine/algorithms/sliding-window';
+export * from './engine/algorithms/token-bucket';
+export * from './engine/algorithms/leaky-bucket';
+export * from './engine/violations';
+export * from './storage/memory';
+export * from './storage/redis';
+export * from './storage/fallback';

package/dist/index.js

@@ -0,0 +1,53 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ratelimit = ratelimit;
+require("./augmentation");
+const plugin_1 = require("./plugin");
+const use_ratelimit_directive_1 = require("./directive/use-ratelimit-directive");
+const configure_1 = require("./configure");
+/**
+ * Create compiler + runtime plugins for rate limiting.
+ *
+ * Runtime options are provided via configureRatelimit().
+ *
+ * @param options - Optional compiler plugin configuration.
+ * @returns Ordered array of compiler and runtime plugins.
+ */
+function ratelimit(options) {
+    const compiler = new use_ratelimit_directive_1.UseRateLimitDirectivePlugin(options?.compiler);
+    const runtime = new plugin_1.RateLimitPlugin((0, configure_1.getRateLimitConfig)());
+    return [compiler, runtime];
+}
+__exportStar(require("./types"), exports);
+__exportStar(require("./constants"), exports);
+__exportStar(require("./runtime"), exports);
+__exportStar(require("./configure"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./api"), exports);
+__exportStar(require("./plugin"), exports);
+__exportStar(require("./directive/use-ratelimit"), exports);
+__exportStar(require("./directive/use-ratelimit-directive"), exports);
+__exportStar(require("./engine/RateLimitEngine"), exports);
+__exportStar(require("./engine/algorithms/fixed-window"), exports);
+__exportStar(require("./engine/algorithms/sliding-window"), exports);
+__exportStar(require("./engine/algorithms/token-bucket"), exports);
+__exportStar(require("./engine/algorithms/leaky-bucket"), exports);
+__exportStar(require("./engine/violations"), exports);
+__exportStar(require("./storage/memory"), exports);
+__exportStar(require("./storage/redis"), exports);
+__exportStar(require("./storage/fallback"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQWNBLDhCQVFDO0FBdEJELDBCQUF3QjtBQUN4QixxQ0FBMkM7QUFDM0MsaUZBQWtGO0FBRWxGLDJDQUFpRDtBQUVqRDs7Ozs7OztHQU9HO0FBQ0gsU0FBZ0IsU0FBUyxDQUN2QixPQUVFO0lBRUYsTUFBTSxRQUFRLEdBQUcsSUFBSSxxREFBMkIsQ0FBQyxPQUFPLEVBQUUsUUFBUSxDQUFDLENBQUM7SUFDcEUsTUFBTSxPQUFPLEdBQUcsSUFBSSx3QkFBZSxDQUFDLElBQUEsOEJBQWtCLEdBQUUsQ0FBQyxDQUFDO0lBQzFELE9BQU8sQ0FBQyxRQUFRLEVBQUUsT0FBTyxDQUFDLENBQUM7QUFDN0IsQ0FBQztBQUVELDBDQUF3QjtBQUN4Qiw4Q0FBNEI7QUFDNUIsNENBQTBCO0FBQzFCLDhDQUE0QjtBQUM1QiwyQ0FBeUI7QUFDekIsd0NBQXNCO0FBQ3RCLDJDQUF5QjtBQUN6Qiw0REFBMEM7QUFDMUMsc0VBQW9EO0FBQ3BELDJEQUF5QztBQUN6QyxtRUFBaUQ7QUFDakQscUVBQW1EO0FBQ25ELG1FQUFpRDtBQUNqRCxtRUFBaUQ7QUFDakQsc0RBQW9DO0FBQ3BDLG1EQUFpQztBQUNqQyxrREFBZ0M7QUFDaEMscURBQW1DIn0=

package/dist/plugin.d.ts

@@ -0,0 +1,140 @@
+import { RuntimePlugin } from 'commandkit';
+import type { CommandKitEnvironment, CommandKitPluginRuntime, CommandKitHMREvent, PreparedAppCommandExecution } from 'commandkit';
+import { Message } from 'discord.js';
+import type { Interaction } from 'discord.js';
+import type { RateLimitPluginOptions } from './types';
+/**
+ * Runtime plugin that enforces rate limits for CommandKit commands so handlers stay lean.
+ *
+ * @extends RuntimePlugin<RateLimitPluginOptions>
+ */
+export declare class RateLimitPlugin extends RuntimePlugin<RateLimitPluginOptions> {
+    readonly name = "RateLimitPlugin";
+    private readonly engines;
+    private readonly memoryStorage;
+    private readonly queues;
+    private hasLoggedMissingStorage;
+    constructor(options: RateLimitPluginOptions);
+    /**
+     * Initialize runtime storage and defaults for this plugin instance.
+     *
+     * @param ctx - CommandKit runtime for the active application.
+     * @returns Resolves when runtime storage has been initialized.
+     * @throws Error when the plugin has not been configured.
+     */
+    activate(ctx: CommandKitPluginRuntime): Promise<void>;
+    /**
+     * Dispose queues and clear shared runtime state.
+     *
+     * @returns Resolves after queues are aborted and runtime state is cleared.
+     */
+    deactivate(): Promise<void>;
+    /**
+     * Evaluate rate limits and optionally queue execution to avoid dropping commands.
+     *
+     * @param ctx - CommandKit runtime for the active application.
+     * @param env - Command execution environment.
+     * @param source - Interaction or message triggering the command.
+     * @param prepared - Prepared command execution data.
+     * @param execute - Callback that executes the command handler.
+     * @returns True when execution is deferred or handled, otherwise false to continue.
+     */
+    executeCommand(ctx: CommandKitPluginRuntime, env: CommandKitEnvironment, source: Interaction | Message, prepared: PreparedAppCommandExecution, execute: () => Promise<any>): Promise<boolean>;
+    /**
+     * Clear matching keys when a command is hot-reloaded to avoid stale state.
+     *
+     * @param ctx - CommandKit runtime for the active application.
+     * @param event - HMR event describing the changed file.
+     * @returns Resolves after matching keys are cleared and the event is handled.
+     */
+    performHMR(ctx: CommandKitPluginRuntime, event: CommandKitHMREvent): Promise<void>;
+    /**
+     * Resolve a cached engine instance for a storage backend.
+     *
+     * @param storage - Storage backend to associate with the engine.
+     * @returns Cached engine instance for the storage.
+     */
+    private getEngine;
+    /**
+     * Normalize a storage config into a storage driver instance.
+     *
+     * @param config - Storage config or driver.
+     * @returns Storage driver instance or null when not configured.
+     */
+    private resolveStorage;
+    /**
+     * Resolve the default storage, falling back to memory when enabled.
+     *
+     * @returns Resolved storage instance or null when disabled.
+     */
+    private resolveDefaultStorage;
+    /**
+     * Log a one-time error when storage is missing.
+     *
+     * @returns Nothing; logs at most once per process.
+     */
+    private logMissingStorage;
+    /**
+     * Emit a ratelimited event through CommandKit's event bus.
+     *
+     * @param ctx - CommandKit runtime for the active application.
+     * @param payload - Rate-limit event payload to emit.
+     * @returns Nothing; emits the event when available.
+     */
+    private emitRateLimited;
+    /**
+     * Determine whether a source should bypass rate limits.
+     *
+     * @param source - Interaction or message to evaluate.
+     * @returns True when the source should bypass rate limiting.
+     */
+    private shouldBypass;
+    /**
+     * Check for temporary exemptions in storage for the source.
+     *
+     * @param source - Interaction or message to evaluate.
+     * @returns True when a temporary exemption is found.
+     */
+    private hasTemporaryBypass;
+    /**
+     * Send the default rate-limited response when no custom handler is set.
+     *
+     * @param env - Command execution environment.
+     * @param source - Interaction or message that was limited.
+     * @param info - Aggregated rate-limit info for the response.
+     * @returns Resolves after the response is sent.
+     */
+    private respondRateLimited;
+    /**
+     * Enqueue a command execution for later retry under queue rules.
+     *
+     * @param params - Queue execution parameters.
+     * @returns True when the execution was queued.
+     */
+    private enqueueExecution;
+    /**
+     * Get or create an async queue for the given key.
+     *
+     * @param key - Queue identifier.
+     * @param options - Normalized queue settings.
+     * @returns Async queue instance.
+     */
+    private getQueue;
+    /**
+     * Consume limits for queued execution to decide whether to run now.
+     *
+     * @param engine - Rate limit engine.
+     * @param limiter - Resolved limiter configuration.
+     * @param resolvedKeys - Scope keys to consume.
+     * @returns Aggregated rate-limit info for the queue check.
+     */
+    private consumeForQueue;
+    /**
+     * Defer interaction replies when queueing and the source is repliable.
+     *
+     * @param source - Interaction or message that may be deferred.
+     * @param queue - Normalized queue settings.
+     * @returns Resolves after attempting to defer the interaction.
+     */
+    private deferInteractionIfNeeded;
+}