docs(ratelimit): refine jsdoc coverage

Author: CallRay

packages/ratelimit/spec/algorithms.test.ts

@@ -1,6 +1,8 @@
-// Algorithm integration tests.
-//
-// Fake timers keep limiter math deterministic and avoid flakiness.
+/**
+ * Algorithm integration tests.
+ *
+ * Fake timers keep limiter math deterministic and avoid flakiness.
+ */
 
 import { afterEach, describe, expect, test, vi } from 'vitest';
 import { MemoryRateLimitStorage } from '../src/storage/memory';
@@ -13,6 +15,11 @@ import type { RateLimitStorage } from '../src/types';
 const scope = 'user' as const;
 const delay = (ms = 0) => new Promise<void>((resolve) => setTimeout(resolve, ms));
 
+/**
+ * Test storage that delays sorted-set calls to simulate contention.
+ *
+ * @implements RateLimitStorage
+ */
 class DelayedSlidingWindowStorage implements RateLimitStorage {
   private readonly kv = new Map<string, unknown>();
   private readonly zset = new MemoryRateLimitStorage();
@@ -60,6 +67,11 @@ class DelayedSlidingWindowStorage implements RateLimitStorage {
   }
 }
 
+/**
+ * Test storage that delays key/value calls for fixed-window tests.
+ *
+ * @implements RateLimitStorage
+ */
 class DelayedFixedWindowStorage implements RateLimitStorage {
   private readonly kv = new Map<string, unknown>();
 

packages/ratelimit/spec/api.test.ts

@@ -1,6 +1,8 @@
-// API helper tests.
-//
-// Uses in-memory storage to keep exemption/reset tests isolated.
+/**
+ * API helper tests.
+ *
+ * Uses in-memory storage to keep exemption/reset tests isolated.
+ */
 
 import { afterEach, describe, expect, test } from 'vitest';
 import { MemoryRateLimitStorage } from '../src/storage/memory';

packages/ratelimit/spec/engine.test.ts

@@ -1,6 +1,8 @@
-// Engine escalation tests.
-//
-// Fake timers keep violation cooldowns deterministic.
+/**
+ * Engine escalation tests.
+ *
+ * Fake timers keep violation cooldowns deterministic.
+ */
 
 import { afterEach, describe, expect, test, vi } from 'vitest';
 import { RateLimitEngine } from '../src/engine/RateLimitEngine';

packages/ratelimit/spec/helpers.ts

@@ -1,7 +1,9 @@
-// Test helpers for ratelimit specs.
-//
-// Provides lightweight stubs for Discord and CommandKit so tests stay focused
-// on rate limit behavior without a live client.
+/**
+ * Test helpers for ratelimit specs.
+ *
+ * Provides lightweight stubs for Discord and CommandKit so tests stay focused
+ * on rate limit behavior without a live client.
+ */
 
 import { Collection, Message } from 'discord.js';
 import { vi } from 'vitest';
@@ -19,7 +21,11 @@ export interface InteractionStubOptions {
 
 /**
  * Build an Interaction-like stub with only the fields the plugin reads.
+ *
  * Keeps tests fast without a live Discord client.
+ *
+ * @param options - Overrides for interaction fields used in tests.
+ * @returns Interaction stub matching the minimal plugin contract.
  */
 export function createInteractionStub(options: InteractionStubOptions = {}) {
   const interaction = {
@@ -61,6 +67,9 @@ export interface MessageStubOptions {
 
 /**
  * Build a Message-like stub with minimal fields used by rate limit logic.
+ *
+ * @param options - Overrides for message fields used in tests.
+ * @returns Message stub matching the minimal plugin contract.
  */
 export function createMessageStub(options: MessageStubOptions = {}) {
   const message = Object.create(Message.prototype) as Message & {
@@ -87,6 +96,9 @@ export function createMessageStub(options: MessageStubOptions = {}) {
 
 /**
  * Create a minimal CommandKit env with a store for plugin results.
+ *
+ * @param commandName - Command name to seed into the context.
+ * @returns Minimal CommandKit environment for plugin tests.
  */
 export function createEnv(commandName = 'ping') {
   return {
@@ -97,6 +109,9 @@ export function createEnv(commandName = 'ping') {
 
 /**
  * Create a runtime context with stubbed analytics and capture hooks.
+ *
+ * @param overrides - Optional overrides for command arrays.
+ * @returns Runtime context and stubbed helpers.
  */
 export function createRuntimeContext(
   overrides: {
@@ -129,6 +144,9 @@ export function createRuntimeContext(
 
 /**
  * Build a prepared command shape for plugin tests.
+ *
+ * @param options - Command metadata overrides.
+ * @returns Prepared command payload for plugin tests.
  */
 export function createPreparedCommand(options: {
   name?: string;

packages/ratelimit/spec/plugin.test.ts

@@ -1,6 +1,8 @@
-// Plugin integration tests.
-//
-// Uses stubs to keep plugin tests fast and offline.
+/**
+ * Plugin integration tests.
+ *
+ * Uses stubs to keep plugin tests fast and offline.
+ */
 
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 import { MessageFlags } from 'discord.js';

packages/ratelimit/spec/setup.ts

@@ -1,6 +1,8 @@
-// Vitest setup for ratelimit specs.
-//
-// Restores the Console constructor so logging helpers behave consistently.
+/**
+ * Vitest setup for ratelimit specs.
+ *
+ * Restores the Console constructor so logging helpers behave consistently.
+ */
 
 import { Console } from 'node:console';
 

packages/ratelimit/src/api.ts

@@ -1,6 +1,8 @@
-// Public rate limit helpers.
-//
-// Used by handlers and admin tools to inspect, reset, and manage exemptions.
+/**
+ * Public rate limit helpers.
+ *
+ * Used by handlers and admin tools to inspect, reset, and manage exemptions.
+ */
 
 import type { CommandKitEnvironment, Context } from 'commandkit';
 import { RATELIMIT_STORE_KEY } from './constants';
@@ -51,6 +53,9 @@ export interface ResetAllRateLimitsParams {
 
 /**
  * Read aggregated rate limit info stored on a CommandKit env or context.
+ *
+ * @param envOrCtx - CommandKit environment or context holding the rate-limit store.
+ * @returns Aggregated rate-limit info or null when no store is present.
  */
 export function getRateLimitInfo(
   envOrCtx: CommandKitEnvironment | Context | null | undefined,
@@ -61,10 +66,22 @@ export function getRateLimitInfo(
   return (store.get(RATELIMIT_STORE_KEY) as RateLimitStoreValue) ?? null;
 }
 
+/**
+ * Resolve the active storage or throw when none is configured.
+ *
+ * @returns Configured rate-limit storage.
+ * @throws Error when storage is not configured.
+ */
 function getRequiredStorage(): RateLimitStorage {
   return getRuntimeStorage().storage;
 }
 
+/**
+ * Resolve runtime context plus the effective storage to use.
+ *
+ * @returns Runtime context (if any) and the resolved storage.
+ * @throws Error when storage is not configured.
+ */
 function getRuntimeStorage(): {
   runtime: ReturnType<typeof getRateLimitRuntime>;
   storage: RateLimitStorage;
@@ -77,12 +94,22 @@ function getRuntimeStorage(): {
   return { runtime, storage };
 }
 
+/**
+ * Normalize a prefix to include the window suffix marker.
+ *
+ * @param prefix - Base key prefix.
+ * @returns Prefix guaranteed to end with `w:`.
+ */
 function toWindowPrefix(prefix: string): string {
   return prefix.endsWith(':') ? `${prefix}w:` : `${prefix}:w:`;
 }
 
 /**
  * Reset a single key and its violation/window variants to keep state consistent.
+ *
+ * @param params - Reset parameters for a single key or scope-derived key.
+ * @returns Resolves when deletes and reset hooks (if any) complete.
+ * @throws Error when required scope identifiers are missing.
  */
 export async function resetRateLimit(
   params: ResetRateLimitParams,
@@ -127,6 +154,11 @@ export async function resetRateLimit(
 
 /**
  * Reset multiple keys by scope, command name, prefix, or pattern for bulk cleanup.
+ *
+ * @param params - Batch reset parameters, defaulting to an empty config.
+ * @returns Resolves when all matching keys are deleted.
+ * @throws Error when the storage backend lacks required delete helpers.
+ * @throws Error when scope identifiers are missing for scope-based resets.
  */
 export async function resetAllRateLimits(
   params: ResetAllRateLimitsParams = {},
@@ -196,6 +228,10 @@ export async function resetAllRateLimits(
 
 /**
  * Grant a temporary exemption for a scope/id pair.
+ *
+ * @param params - Exemption scope, id, and duration.
+ * @returns Resolves when the exemption key is written.
+ * @throws Error when duration is missing or non-positive.
  */
 export async function grantRateLimitExemption(
   params: RateLimitExemptionGrantParams,
@@ -214,6 +250,9 @@ export async function grantRateLimitExemption(
 
 /**
  * Revoke a temporary exemption for a scope/id pair.
+ *
+ * @param params - Exemption scope and id to revoke.
+ * @returns Resolves when the exemption key is removed.
  */
 export async function revokeRateLimitExemption(
   params: RateLimitExemptionRevokeParams,
@@ -226,6 +265,10 @@ export async function revokeRateLimitExemption(
 
 /**
  * List exemptions by scope and/or id for admin/reporting.
+ *
+ * @param params - Optional scope/id filters and limits.
+ * @returns Exemption info entries that match the requested filters.
+ * @throws Error when scope is required but missing or listing is unsupported.
  */
 export async function listRateLimitExemptions(
   params: RateLimitExemptionListParams = {},
@@ -281,6 +324,13 @@ export async function listRateLimitExemptions(
   return results;
 }
 
+/**
+ * Delete windowed variants for a base key using available storage helpers.
+ *
+ * @param storage - Storage driver to delete from.
+ * @param key - Base key to delete window variants for.
+ * @returns Resolves after window variants are removed.
+ */
 async function deleteWindowVariants(
   storage: RateLimitStorage,
   key: string,

packages/ratelimit/src/augmentation.ts

@@ -1,6 +1,8 @@
-// CommandKit metadata augmentation.
-//
-// Extends CommandKit metadata so commands can declare per-command limits.
+/**
+ * CommandKit metadata augmentation.
+ *
+ * Extends CommandKit metadata so commands can declare per-command limits.
+ */
 
 import type { RateLimitCommandConfig } from './types';
 

packages/ratelimit/src/configure.ts

@@ -1,7 +1,9 @@
-// Runtime configuration for the rate limit plugin.
-//
-// Mirrors configureAI so runtime options can be set outside commandkit.config
-// before the plugin evaluates commands.
+/**
+ * Runtime configuration for the rate limit plugin.
+ *
+ * Mirrors configureAI so runtime options can be set outside commandkit.config
+ * before the plugin evaluates commands.
+ */
 
 import { DEFAULT_LIMITER } from './utils/config';
 import {
@@ -19,6 +21,12 @@ import type {
 const rateLimitConfig: RateLimitPluginOptions = {};
 let configured = false;
 
+/**
+ * Normalize a storage config into a storage driver instance.
+ *
+ * @param config - Storage config or driver.
+ * @returns Storage driver instance or null when not configured.
+ */
 function resolveStorage(
   config: RateLimitStorageConfig,
 ): RateLimitStorage | null {
@@ -29,6 +37,12 @@ function resolveStorage(
   return config;
 }
 
+/**
+ * Apply updated config to the active runtime context.
+ *
+ * @param config - Runtime configuration updates.
+ * @returns Nothing; mutates the active runtime context when present.
+ */
 function updateRuntime(config: RateLimitPluginOptions): void {
   const runtime = getRateLimitRuntime();
   const storageOverride = config.storage
@@ -57,21 +71,29 @@ function updateRuntime(config: RateLimitPluginOptions): void {
 
 /**
  * Returns true once configureRatelimit has been called.
+ *
+ * @returns True when runtime configuration has been initialized.
  */
 export function isRateLimitConfigured(): boolean {
   return configured;
 }
 
 /**
  * Retrieves the current rate limit configuration.
+ *
+ * @returns The current in-memory rate limit config object.
  */
 export function getRateLimitConfig(): RateLimitPluginOptions {
   return rateLimitConfig;
 }
 
 /**
  * Configures the rate limit plugin runtime options.
+ *
  * Call this once during startup (for example in src/ratelimit.ts).
+ *
+ * @param config - Runtime options to merge into the active configuration.
+ * @returns Nothing; updates runtime state in place.
  */
 export function configureRatelimit(
   config: RateLimitPluginOptions = {},

packages/ratelimit/src/constants.ts

@@ -1,13 +1,19 @@
-// Rate limit constants shared across runtime and tests.
-//
-// Keeps key names consistent across storage, runtime, and docs.
+/**
+ * Rate limit constants shared across runtime and tests.
+ *
+ * Keeps key names consistent across storage, runtime, and docs.
+ */
 
 /**
  * Store key used to stash aggregated results in CommandKit envs.
+ *
+ * @default 'ratelimit'
  */
 export const RATELIMIT_STORE_KEY = 'ratelimit';
 
 /**
  * Default prefix for storage keys; can be overridden per config.
+ *
+ * @default 'rl:'
  */
 export const DEFAULT_KEY_PREFIX = 'rl:';