commandkit 1.2.0-rc.12 → 1.2.0-rc.13

package/dist/utils/useful-stuff/mutex.d.ts

@@ -9,24 +9,24 @@
  */
 interface MutexStorage {
   /**
-   * Attempts to acquire a lock for a given key
-   * @param key - The unique identifier for the mutex lock
-   * @param timeout - Optional timeout in milliseconds for the lock
-   * @param signal - Optional AbortSignal for cancelling the acquisition
-   * @returns Promise resolving to true if lock was acquired, false if timeout or already locked
-   */
+       * Attempts to acquire a lock for a given key
+       * @param key - The unique identifier for the mutex lock
+       * @param timeout - Optional timeout in milliseconds for the lock
+       * @param signal - Optional AbortSignal for cancelling the acquisition
+       * @returns Promise resolving to true if lock was acquired, false if timeout or already locked
+       */
   acquire(key: string, timeout?: number, signal?: AbortSignal): Promise<boolean>;
   /**
-   * Releases the lock for a given key
-   * @param key - The unique identifier for the mutex lock
-   * @returns Promise that resolves when the lock is released
-   */
+       * Releases the lock for a given key
+       * @param key - The unique identifier for the mutex lock
+       * @returns Promise that resolves when the lock is released
+       */
   release(key: string): Promise<void>;
   /**
-   * Checks if a lock is currently held for a given key
-   * @param key - The unique identifier for the mutex lock
-   * @returns Promise resolving to true if the lock is held, false otherwise
-   */
+       * Checks if a lock is currently held for a given key
+       * @param key - The unique identifier for the mutex lock
+       * @returns Promise resolving to true if the lock is held, false otherwise
+       */
   isLocked(key: string): Promise<boolean>;
 }
 /**
@@ -45,24 +45,24 @@ interface MutexOptions {
 declare class MemoryMutexStorage implements MutexStorage {
   private readonly locks;
   /**
-   * Attempts to acquire a lock for a given key
-   * @param key - The unique identifier for the mutex lock
-   * @param timeout - Optional timeout in milliseconds for the lock
-   * @param signal - Optional AbortSignal for cancelling the acquisition
-   * @returns Promise resolving to true if lock was acquired, false if timeout or already locked
-   */
+       * Attempts to acquire a lock for a given key
+       * @param key - The unique identifier for the mutex lock
+       * @param timeout - Optional timeout in milliseconds for the lock
+       * @param signal - Optional AbortSignal for cancelling the acquisition
+       * @returns Promise resolving to true if lock was acquired, false if timeout or already locked
+       */
   acquire(key: string, timeout?: number, signal?: AbortSignal): Promise<boolean>;
   /**
-   * Releases the lock for a given key
-   * @param key - The unique identifier for the mutex lock
-   * @returns Promise that resolves when the lock is released
-   */
+       * Releases the lock for a given key
+       * @param key - The unique identifier for the mutex lock
+       * @returns Promise that resolves when the lock is released
+       */
   release(key: string): Promise<void>;
   /**
-   * Checks if a lock is currently held for a given key
-   * @param key - The unique identifier for the mutex lock
-   * @returns Promise resolving to true if the lock is held, false otherwise
-   */
+       * Checks if a lock is currently held for a given key
+       * @param key - The unique identifier for the mutex lock
+       * @returns Promise resolving to true if the lock is held, false otherwise
+       */
   isLocked(key: string): Promise<boolean>;
   private generateHolderId;
   private delay;
@@ -75,54 +75,54 @@ declare class Mutex {
   private storage;
   private readonly defaultTimeout;
   /**
-   * Creates a new mutex instance
-   * @param options - Configuration options for the mutex
-   */
+       * Creates a new mutex instance
+       * @param options - Configuration options for the mutex
+       */
   constructor(options?: MutexOptions);
   /**
-   * Sets the storage implementation for the mutex
-   * @param storage - The storage implementation to use
-   */
+       * Sets the storage implementation for the mutex
+       * @param storage - The storage implementation to use
+       */
   setStorage(storage: MutexStorage): void;
   /**
-   * Gets the storage implementation for the mutex
-   * @returns The storage implementation
-   */
+       * Gets the storage implementation for the mutex
+       * @returns The storage implementation
+       */
   getStorage(): MutexStorage;
   /**
-   * Acquires a lock for the given key
-   * @param key - The unique identifier for the mutex lock
-   * @param timeout - Optional timeout in milliseconds for lock acquisition
-   * @param signal - Optional AbortSignal for cancelling the acquisition
-   * @returns Promise resolving to true if lock was acquired, false if timeout
-   */
+       * Acquires a lock for the given key
+       * @param key - The unique identifier for the mutex lock
+       * @param timeout - Optional timeout in milliseconds for lock acquisition
+       * @param signal - Optional AbortSignal for cancelling the acquisition
+       * @returns Promise resolving to true if lock was acquired, false if timeout
+       */
   acquire(key: string, timeout?: number, signal?: AbortSignal): Promise<boolean>;
   /**
-   * Releases the lock for the given key
-   * @param key - The unique identifier for the mutex lock
-   * @returns Promise that resolves when the lock is released
-   */
+       * Releases the lock for the given key
+       * @param key - The unique identifier for the mutex lock
+       * @returns Promise that resolves when the lock is released
+       */
   release(key: string): Promise<void>;
   /**
-   * Checks if a lock is currently held for the given key
-   * @param key - The unique identifier for the mutex lock
-   * @returns Promise resolving to true if the lock is held, false otherwise
-   */
+       * Checks if a lock is currently held for the given key
+       * @param key - The unique identifier for the mutex lock
+       * @returns Promise resolving to true if the lock is held, false otherwise
+       */
   isLocked(key: string): Promise<boolean>;
   /**
-   * Executes a function with exclusive access to the resource
-   * @param key - The unique identifier for the mutex lock
-   * @param fn - The function to execute with exclusive access
-   * @param timeout - Optional timeout in milliseconds for lock acquisition
-   * @param signal - Optional AbortSignal for cancelling the lock acquisition
-   * @returns Promise resolving to the result of the function execution
-   * @throws Error if lock acquisition fails or function execution fails
-   */
+       * Executes a function with exclusive access to the resource
+       * @param key - The unique identifier for the mutex lock
+       * @param fn - The function to execute with exclusive access
+       * @param timeout - Optional timeout in milliseconds for lock acquisition
+       * @param signal - Optional AbortSignal for cancelling the lock acquisition
+       * @returns Promise resolving to the result of the function execution
+       * @throws Error if lock acquisition fails or function execution fails
+       */
   withLock<T>(key: string, fn: () => Promise<T> | T, timeout?: number, signal?: AbortSignal): Promise<T>;
   /**
-   * Gets the current configuration of the mutex
-   * @returns Object containing the current timeout value
-   */
+       * Gets the current configuration of the mutex
+       * @returns Object containing the current timeout value
+       */
   getConfig(): Omit<MutexOptions, 'storage'>;
 }
 /**

package/dist/utils/useful-stuff/ratelimiter.d.ts

@@ -13,23 +13,23 @@ declare const DEFAULT_MAX_REQUESTS = 10;
  */
 interface RateLimitStorage {
   /**
-   * Retrieves the current request count for a given key
-   * @param key - The unique identifier for the rate limit entry
-   * @returns Promise resolving to the current request count
-   */
+       * Retrieves the current request count for a given key
+       * @param key - The unique identifier for the rate limit entry
+       * @returns Promise resolving to the current request count
+       */
   get(key: string): Promise<number>;
   /**
-   * Sets the request count for a given key
-   * @param key - The unique identifier for the rate limit entry
-   * @param value - The request count to store
-   * @returns Promise that resolves when the value is stored
-   */
+       * Sets the request count for a given key
+       * @param key - The unique identifier for the rate limit entry
+       * @param value - The request count to store
+       * @returns Promise that resolves when the value is stored
+       */
   set(key: string, value: number): Promise<void>;
   /**
-   * Deletes the rate limit entry for a given key
-   * @param key - The unique identifier for the rate limit entry
-   * @returns Promise that resolves when the entry is deleted
-   */
+       * Deletes the rate limit entry for a given key
+       * @param key - The unique identifier for the rate limit entry
+       * @returns Promise that resolves when the entry is deleted
+       */
   delete(key: string): Promise<void>;
 }
 /**
@@ -50,23 +50,23 @@ interface RateLimitOptions {
 declare class MemoryRateLimitStorage implements RateLimitStorage {
   private readonly store;
   /**
-   * Retrieves the current request count for a given key
-   * @param key - The unique identifier for the rate limit entry
-   * @returns Promise resolving to the current request count or 0 if not found
-   */
+       * Retrieves the current request count for a given key
+       * @param key - The unique identifier for the rate limit entry
+       * @returns Promise resolving to the current request count or 0 if not found
+       */
   get(key: string): Promise<number>;
   /**
-   * Sets the request count for a given key
-   * @param key - The unique identifier for the rate limit entry
-   * @param value - The request count to store
-   * @returns Promise that resolves immediately
-   */
+       * Sets the request count for a given key
+       * @param key - The unique identifier for the rate limit entry
+       * @param value - The request count to store
+       * @returns Promise that resolves immediately
+       */
   set(key: string, value: number): Promise<void>;
   /**
-   * Deletes the rate limit entry for a given key
-   * @param key - The unique identifier for the rate limit entry
-   * @returns Promise that resolves immediately
-   */
+       * Deletes the rate limit entry for a given key
+       * @param key - The unique identifier for the rate limit entry
+       * @returns Promise that resolves immediately
+       */
   delete(key: string): Promise<void>;
 }
 /**
@@ -81,50 +81,50 @@ declare class RateLimiter {
   private readonly lastReset;
   private readonly resetInterval;
   /**
-   * Creates a new rate limiter instance
-   * @param maxRequests - Maximum number of requests allowed per interval (default: 10)
-   * @param interval - Time interval in milliseconds for the rate limit window (default: 60000)
-   * @param storage - Optional storage implementation (default: MemoryRateLimitStorage)
-   */
+       * Creates a new rate limiter instance
+       * @param maxRequests - Maximum number of requests allowed per interval (default: 10)
+       * @param interval - Time interval in milliseconds for the rate limit window (default: 60000)
+       * @param storage - Optional storage implementation (default: MemoryRateLimitStorage)
+       */
   constructor(maxRequests?: number, interval?: number, storage?: RateLimitStorage);
   /**
-   * Sets the storage implementation for the rate limiter
-   * @param storage - The storage implementation to use
-   */
+       * Sets the storage implementation for the rate limiter
+       * @param storage - The storage implementation to use
+       */
   setStorage(storage: RateLimitStorage): void;
   /**
-   * Gets the storage implementation for the rate limiter
-   * @returns The storage implementation
-   */
+       * Gets the storage implementation for the rate limiter
+       * @returns The storage implementation
+       */
   getStorage(): RateLimitStorage;
   /**
-   * Checks if a request is allowed for the given key and increments the counter if allowed
-   * @param key - The unique identifier for the rate limit entry
-   * @returns Promise resolving to true if the request is allowed, false if rate limited
-   */
+       * Checks if a request is allowed for the given key and increments the counter if allowed
+       * @param key - The unique identifier for the rate limit entry
+       * @returns Promise resolving to true if the request is allowed, false if rate limited
+       */
   limit(key: string): Promise<boolean>;
   /**
-   * Gets the remaining requests allowed for a given key
-   * @param key - The unique identifier for the rate limit entry
-   * @returns Promise resolving to the number of remaining requests
-   */
+       * Gets the remaining requests allowed for a given key
+       * @param key - The unique identifier for the rate limit entry
+       * @returns Promise resolving to the number of remaining requests
+       */
   getRemaining(key: string): Promise<number>;
   /**
-   * Gets the time until the rate limit resets for a given key
-   * @param key - The unique identifier for the rate limit entry
-   * @returns Promise resolving to the time in milliseconds until reset, or 0 if no limit is active
-   */
+       * Gets the time until the rate limit resets for a given key
+       * @param key - The unique identifier for the rate limit entry
+       * @returns Promise resolving to the time in milliseconds until reset, or 0 if no limit is active
+       */
   getResetTime(key: string): Promise<number>;
   /**
-   * Resets the rate limit for a given key
-   * @param key - The unique identifier for the rate limit entry
-   * @returns Promise that resolves when the reset is complete
-   */
+       * Resets the rate limit for a given key
+       * @param key - The unique identifier for the rate limit entry
+       * @returns Promise that resolves when the reset is complete
+       */
   reset(key: string): Promise<void>;
   /**
-   * Gets the current configuration of the rate limiter
-   * @returns Object containing the current maxRequests and interval values
-   */
+       * Gets the current configuration of the rate limiter
+       * @returns Object containing the current maxRequests and interval values
+       */
   getConfig(): Omit<RateLimitOptions, 'storage'>;
 }
 /**

package/dist/utils/useful-stuff/ratelimiter.js.map

@@ -1 +1 @@
-{"version":3,"file":"ratelimiter.js","names":[],"sources":["../../../src/utils/useful-stuff/ratelimiter.ts"],"sourcesContent":["/**\n * Default timeout interval for rate limiting in milliseconds\n */\nexport const DEFAULT_TIMEOUT = 60000;\n\n/**\n * Default maximum number of requests allowed per interval\n */\nexport const DEFAULT_MAX_REQUESTS = 10;\n\n/**\n * Interface for rate limit storage implementations.\n * Provides methods to store, retrieve, and delete rate limit data.\n */\nexport interface RateLimitStorage {\n  /**\n   * Retrieves the current request count for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise resolving to the current request count\n   */\n  get(key: string): Promise<number>;\n\n  /**\n   * Sets the request count for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @param value - The request count to store\n   * @returns Promise that resolves when the value is stored\n   */\n  set(key: string, value: number): Promise<void>;\n\n  /**\n   * Deletes the rate limit entry for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise that resolves when the entry is deleted\n   */\n  delete(key: string): Promise<void>;\n}\n\n/**\n * Configuration options for rate limiting\n */\nexport interface RateLimitOptions {\n  /** Maximum number of requests allowed per interval. Default: 10 */\n  maxRequests?: number;\n  /** Time interval in milliseconds for the rate limit window. Default: 60000 */\n  interval?: number;\n  /** Storage implementation for persisting rate limit data. Default: {@link MemoryRateLimitStorage} */\n  storage?: RateLimitStorage;\n}\n\n/**\n * In-memory storage implementation for rate limiting.\n * Suitable for single-instance applications.\n */\nexport class MemoryRateLimitStorage implements RateLimitStorage {\n  private readonly store = new Map<string, number>();\n\n  /**\n   * Retrieves the current request count for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise resolving to the current request count or 0 if not found\n   */\n  async get(key: string): Promise<number> {\n    return this.store.get(key) || 0;\n  }\n\n  /**\n   * Sets the request count for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @param value - The request count to store\n   * @returns Promise that resolves immediately\n   */\n  async set(key: string, value: number): Promise<void> {\n    this.store.set(key, value);\n  }\n\n  /**\n   * Deletes the rate limit entry for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise that resolves immediately\n   */\n  async delete(key: string): Promise<void> {\n    this.store.delete(key);\n  }\n}\n\n/**\n * Rate limiter implementation that enforces request limits per key.\n * Supports configurable request limits and time intervals.\n */\nexport class RateLimiter {\n  private readonly limits: Map<string, number> = new Map();\n  private readonly lastReset: Map<string, number> = new Map();\n  private readonly resetInterval: number;\n\n  /**\n   * Creates a new rate limiter instance\n   * @param maxRequests - Maximum number of requests allowed per interval (default: 10)\n   * @param interval - Time interval in milliseconds for the rate limit window (default: 60000)\n   * @param storage - Optional storage implementation (default: MemoryRateLimitStorage)\n   */\n  public constructor(\n    private readonly maxRequests: number = DEFAULT_MAX_REQUESTS,\n    private readonly interval: number = DEFAULT_TIMEOUT,\n    private storage: RateLimitStorage = new MemoryRateLimitStorage(),\n  ) {\n    this.resetInterval = interval;\n  }\n\n  /**\n   * Sets the storage implementation for the rate limiter\n   * @param storage - The storage implementation to use\n   */\n  public setStorage(storage: RateLimitStorage) {\n    this.storage = storage;\n  }\n\n  /**\n   * Gets the storage implementation for the rate limiter\n   * @returns The storage implementation\n   */\n  public getStorage(): RateLimitStorage {\n    return this.storage;\n  }\n\n  /**\n   * Checks if a request is allowed for the given key and increments the counter if allowed\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise resolving to true if the request is allowed, false if rate limited\n   */\n  public async limit(key: string): Promise<boolean> {\n    const now = Date.now();\n    const lastReset = this.lastReset.get(key) || 0;\n    const timeSinceReset = now - lastReset;\n\n    // Reset counter if interval has passed\n    if (timeSinceReset > this.resetInterval) {\n      await this.storage.delete(key);\n      this.lastReset.set(key, now);\n      this.limits.set(key, 0);\n    }\n\n    // Get current count from storage\n    const currentCount = await this.storage.get(key);\n\n    // Check if limit exceeded\n    if (currentCount >= this.maxRequests) {\n      return false;\n    }\n\n    // Increment counter\n    const newCount = currentCount + 1;\n    await this.storage.set(key, newCount);\n    this.limits.set(key, newCount);\n\n    return true;\n  }\n\n  /**\n   * Gets the remaining requests allowed for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise resolving to the number of remaining requests\n   */\n  public async getRemaining(key: string): Promise<number> {\n    const currentCount = await this.storage.get(key);\n    return Math.max(0, this.maxRequests - currentCount);\n  }\n\n  /**\n   * Gets the time until the rate limit resets for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise resolving to the time in milliseconds until reset, or 0 if no limit is active\n   */\n  public async getResetTime(key: string): Promise<number> {\n    const lastReset = this.lastReset.get(key) || 0;\n    const now = Date.now();\n    const timeSinceReset = now - lastReset;\n\n    if (timeSinceReset >= this.resetInterval) {\n      return 0;\n    }\n\n    return this.resetInterval - timeSinceReset;\n  }\n\n  /**\n   * Resets the rate limit for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise that resolves when the reset is complete\n   */\n  public async reset(key: string): Promise<void> {\n    await this.storage.delete(key);\n    this.limits.delete(key);\n    this.lastReset.delete(key);\n  }\n\n  /**\n   * Gets the current configuration of the rate limiter\n   * @returns Object containing the current maxRequests and interval values\n   */\n  public getConfig(): Omit<RateLimitOptions, 'storage'> {\n    return {\n      maxRequests: this.maxRequests,\n      interval: this.interval,\n    };\n  }\n}\n\n/**\n * Default rate limiter instance for global use\n */\nexport const defaultRateLimiter = new RateLimiter();\n\n/**\n * Convenience function to check if a request is allowed for a given key.\n * Uses the default rate limiter instance.\n *\n * @param key - The unique identifier for the rate limit entry\n * @returns Promise resolving to true if the request is allowed, false if rate limited\n *\n * @example\n * ```typescript\n * const allowed = await ratelimit('user:123');\n * // update the default rate limiter config\n * import { defaultRateLimiter } from 'commandkit/ratelimit';\n *\n * // update max allowed requests\n * defaultRateLimiter.setMaxRequests(10);\n *\n * // update the timeout interval\n * defaultRateLimiter.setInterval(30000);\n *\n * // update the storage implementation\n * defaultRateLimiter.setStorage(new RedisStorage());\n * ```\n */\nexport async function ratelimit(key: string): Promise<boolean> {\n  return defaultRateLimiter.limit(key);\n}\n\n/**\n * Creates a new rate limiter instance with the specified configuration\n * @param options - Configuration options for the rate limiter\n * @returns New RateLimiter instance\n *\n * @example\n * ```typescript\n * const limiter = createRateLimiter({\n *   maxRequests: 5,\n *   interval: 30000,\n *   storage: new CustomStorage()\n * });\n * ```\n */\nexport function createRateLimiter(options: RateLimitOptions): RateLimiter {\n  return new RateLimiter(\n    options.maxRequests,\n    options.interval,\n    options.storage,\n  );\n}\n\n/**\n * Gets the remaining requests for a key using the default rate limiter\n * @param key - The unique identifier for the rate limit entry\n * @returns Promise resolving to the number of remaining requests\n */\nexport async function getRemainingRequests(key: string): Promise<number> {\n  return defaultRateLimiter.getRemaining(key);\n}\n\n/**\n * Gets the reset time for a key using the default rate limiter\n * @param key - The unique identifier for the rate limit entry\n * @returns Promise resolving to the time in milliseconds until reset\n */\nexport async function getResetTime(key: string): Promise<number> {\n  return defaultRateLimiter.getResetTime(key);\n}\n\n/**\n * Resets the rate limit for a key using the default rate limiter\n * @param key - The unique identifier for the rate limit entry\n * @returns Promise that resolves when the reset is complete\n */\nexport async function resetRateLimit(key: string): Promise<void> {\n  return defaultRateLimiter.reset(key);\n}\n"],"mappings":";;;;;AAGA,MAAa,kBAAkB;;;;AAK/B,MAAa,uBAAuB;;;;;AA8CpC,IAAa,yBAAb,MAAgE;CAC9D,AAAiB,wBAAQ,IAAI,KAAqB;;;;;;CAOlD,MAAM,IAAI,KAA8B;AACtC,SAAO,KAAK,MAAM,IAAI,IAAI,IAAI;;;;;;;;CAShC,MAAM,IAAI,KAAa,OAA8B;AACnD,OAAK,MAAM,IAAI,KAAK,MAAM;;;;;;;CAQ5B,MAAM,OAAO,KAA4B;AACvC,OAAK,MAAM,OAAO,IAAI;;;;;;;AAQ1B,IAAa,cAAb,MAAyB;CACvB,AAAiB,yBAA8B,IAAI,KAAK;CACxD,AAAiB,4BAAiC,IAAI,KAAK;CAC3D,AAAiB;;;;;;;CAQjB,AAAO,YACP,AAAiB,cAAsB,sBACvC,AAAiB,WAAmB,iBACpC,AAAQ,UAA4B,IAAI,wBAAwB,EAChE;EAHiB;EACA;EACT;AAEN,OAAK,gBAAgB;;;;;;CAOvB,AAAO,WAAW,SAA2B;AAC3C,OAAK,UAAU;;;;;;CAOjB,AAAO,aAA+B;AACpC,SAAO,KAAK;;;;;;;CAQd,MAAa,MAAM,KAA+B;EAChD,MAAM,MAAM,KAAK,KAAK;AAKtB,MAHuB,OADL,KAAK,UAAU,IAAI,IAAI,IAAI,KAIxB,KAAK,eAAe;AACvC,SAAM,KAAK,QAAQ,OAAO,IAAI;AAC9B,QAAK,UAAU,IAAI,KAAK,IAAI;AAC5B,QAAK,OAAO,IAAI,KAAK,EAAE;;EAIzB,MAAM,eAAe,MAAM,KAAK,QAAQ,IAAI,IAAI;AAGhD,MAAI,gBAAgB,KAAK,YACvB,QAAO;EAIT,MAAM,WAAW,eAAe;AAChC,QAAM,KAAK,QAAQ,IAAI,KAAK,SAAS;AACrC,OAAK,OAAO,IAAI,KAAK,SAAS;AAE9B,SAAO;;;;;;;CAQT,MAAa,aAAa,KAA8B;EACtD,MAAM,eAAe,MAAM,KAAK,QAAQ,IAAI,IAAI;AAChD,SAAO,KAAK,IAAI,GAAG,KAAK,cAAc,aAAa;;;;;;;CAQrD,MAAa,aAAa,KAA8B;EACtD,MAAM,YAAY,KAAK,UAAU,IAAI,IAAI,IAAI;EAE7C,MAAM,iBADM,KAAK,KAAK,GACO;AAE7B,MAAI,kBAAkB,KAAK,cACzB,QAAO;AAGT,SAAO,KAAK,gBAAgB;;;;;;;CAQ9B,MAAa,MAAM,KAA4B;AAC7C,QAAM,KAAK,QAAQ,OAAO,IAAI;AAC9B,OAAK,OAAO,OAAO,IAAI;AACvB,OAAK,UAAU,OAAO,IAAI;;;;;;CAO5B,AAAO,YAA+C;AACpD,SAAO;GACL,aAAa,KAAK;GAClB,UAAU,KAAK;GAChB;;;;;;AAOL,MAAa,qBAAqB,IAAI,aAAa;;;;;;;;;;;;;;;;;;;;;;;;AAyBnD,eAAsB,UAAU,KAA+B;AAC7D,QAAO,mBAAmB,MAAM,IAAI;;;;;;;;;;;;;;;;AAiBtC,SAAgB,kBAAkB,SAAwC;AACxE,QAAO,IAAI,YACT,QAAQ,aACR,QAAQ,UACR,QAAQ,QACT;;;;;;;AAQH,eAAsB,qBAAqB,KAA8B;AACvE,QAAO,mBAAmB,aAAa,IAAI;;;;;;;AAQ7C,eAAsB,aAAa,KAA8B;AAC/D,QAAO,mBAAmB,aAAa,IAAI;;;;;;;AAQ7C,eAAsB,eAAe,KAA4B;AAC/D,QAAO,mBAAmB,MAAM,IAAI"}
+{"version":3,"file":"ratelimiter.js","names":[],"sources":["../../../src/utils/useful-stuff/ratelimiter.ts"],"sourcesContent":["/**\n * Default timeout interval for rate limiting in milliseconds\n */\nexport const DEFAULT_TIMEOUT = 60000;\n\n/**\n * Default maximum number of requests allowed per interval\n */\nexport const DEFAULT_MAX_REQUESTS = 10;\n\n/**\n * Interface for rate limit storage implementations.\n * Provides methods to store, retrieve, and delete rate limit data.\n */\nexport interface RateLimitStorage {\n  /**\n   * Retrieves the current request count for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise resolving to the current request count\n   */\n  get(key: string): Promise<number>;\n\n  /**\n   * Sets the request count for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @param value - The request count to store\n   * @returns Promise that resolves when the value is stored\n   */\n  set(key: string, value: number): Promise<void>;\n\n  /**\n   * Deletes the rate limit entry for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise that resolves when the entry is deleted\n   */\n  delete(key: string): Promise<void>;\n}\n\n/**\n * Configuration options for rate limiting\n */\nexport interface RateLimitOptions {\n  /** Maximum number of requests allowed per interval. Default: 10 */\n  maxRequests?: number;\n  /** Time interval in milliseconds for the rate limit window. Default: 60000 */\n  interval?: number;\n  /** Storage implementation for persisting rate limit data. Default: {@link MemoryRateLimitStorage} */\n  storage?: RateLimitStorage;\n}\n\n/**\n * In-memory storage implementation for rate limiting.\n * Suitable for single-instance applications.\n */\nexport class MemoryRateLimitStorage implements RateLimitStorage {\n  private readonly store = new Map<string, number>();\n\n  /**\n   * Retrieves the current request count for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise resolving to the current request count or 0 if not found\n   */\n  async get(key: string): Promise<number> {\n    return this.store.get(key) || 0;\n  }\n\n  /**\n   * Sets the request count for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @param value - The request count to store\n   * @returns Promise that resolves immediately\n   */\n  async set(key: string, value: number): Promise<void> {\n    this.store.set(key, value);\n  }\n\n  /**\n   * Deletes the rate limit entry for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise that resolves immediately\n   */\n  async delete(key: string): Promise<void> {\n    this.store.delete(key);\n  }\n}\n\n/**\n * Rate limiter implementation that enforces request limits per key.\n * Supports configurable request limits and time intervals.\n */\nexport class RateLimiter {\n  private readonly limits: Map<string, number> = new Map();\n  private readonly lastReset: Map<string, number> = new Map();\n  private readonly resetInterval: number;\n\n  /**\n   * Creates a new rate limiter instance\n   * @param maxRequests - Maximum number of requests allowed per interval (default: 10)\n   * @param interval - Time interval in milliseconds for the rate limit window (default: 60000)\n   * @param storage - Optional storage implementation (default: MemoryRateLimitStorage)\n   */\n  public constructor(\n    private readonly maxRequests: number = DEFAULT_MAX_REQUESTS,\n    private readonly interval: number = DEFAULT_TIMEOUT,\n    private storage: RateLimitStorage = new MemoryRateLimitStorage(),\n  ) {\n    this.resetInterval = interval;\n  }\n\n  /**\n   * Sets the storage implementation for the rate limiter\n   * @param storage - The storage implementation to use\n   */\n  public setStorage(storage: RateLimitStorage) {\n    this.storage = storage;\n  }\n\n  /**\n   * Gets the storage implementation for the rate limiter\n   * @returns The storage implementation\n   */\n  public getStorage(): RateLimitStorage {\n    return this.storage;\n  }\n\n  /**\n   * Checks if a request is allowed for the given key and increments the counter if allowed\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise resolving to true if the request is allowed, false if rate limited\n   */\n  public async limit(key: string): Promise<boolean> {\n    const now = Date.now();\n    const lastReset = this.lastReset.get(key) || 0;\n    const timeSinceReset = now - lastReset;\n\n    // Reset counter if interval has passed\n    if (timeSinceReset > this.resetInterval) {\n      await this.storage.delete(key);\n      this.lastReset.set(key, now);\n      this.limits.set(key, 0);\n    }\n\n    // Get current count from storage\n    const currentCount = await this.storage.get(key);\n\n    // Check if limit exceeded\n    if (currentCount >= this.maxRequests) {\n      return false;\n    }\n\n    // Increment counter\n    const newCount = currentCount + 1;\n    await this.storage.set(key, newCount);\n    this.limits.set(key, newCount);\n\n    return true;\n  }\n\n  /**\n   * Gets the remaining requests allowed for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise resolving to the number of remaining requests\n   */\n  public async getRemaining(key: string): Promise<number> {\n    const currentCount = await this.storage.get(key);\n    return Math.max(0, this.maxRequests - currentCount);\n  }\n\n  /**\n   * Gets the time until the rate limit resets for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise resolving to the time in milliseconds until reset, or 0 if no limit is active\n   */\n  public async getResetTime(key: string): Promise<number> {\n    const lastReset = this.lastReset.get(key) || 0;\n    const now = Date.now();\n    const timeSinceReset = now - lastReset;\n\n    if (timeSinceReset >= this.resetInterval) {\n      return 0;\n    }\n\n    return this.resetInterval - timeSinceReset;\n  }\n\n  /**\n   * Resets the rate limit for a given key\n   * @param key - The unique identifier for the rate limit entry\n   * @returns Promise that resolves when the reset is complete\n   */\n  public async reset(key: string): Promise<void> {\n    await this.storage.delete(key);\n    this.limits.delete(key);\n    this.lastReset.delete(key);\n  }\n\n  /**\n   * Gets the current configuration of the rate limiter\n   * @returns Object containing the current maxRequests and interval values\n   */\n  public getConfig(): Omit<RateLimitOptions, 'storage'> {\n    return {\n      maxRequests: this.maxRequests,\n      interval: this.interval,\n    };\n  }\n}\n\n/**\n * Default rate limiter instance for global use\n */\nexport const defaultRateLimiter = new RateLimiter();\n\n/**\n * Convenience function to check if a request is allowed for a given key.\n * Uses the default rate limiter instance.\n *\n * @param key - The unique identifier for the rate limit entry\n * @returns Promise resolving to true if the request is allowed, false if rate limited\n *\n * @example\n * ```typescript\n * const allowed = await ratelimit('user:123');\n * // update the default rate limiter config\n * import { defaultRateLimiter } from 'commandkit/ratelimit';\n *\n * // update max allowed requests\n * defaultRateLimiter.setMaxRequests(10);\n *\n * // update the timeout interval\n * defaultRateLimiter.setInterval(30000);\n *\n * // update the storage implementation\n * defaultRateLimiter.setStorage(new RedisStorage());\n * ```\n */\nexport async function ratelimit(key: string): Promise<boolean> {\n  return defaultRateLimiter.limit(key);\n}\n\n/**\n * Creates a new rate limiter instance with the specified configuration\n * @param options - Configuration options for the rate limiter\n * @returns New RateLimiter instance\n *\n * @example\n * ```typescript\n * const limiter = createRateLimiter({\n *   maxRequests: 5,\n *   interval: 30000,\n *   storage: new CustomStorage()\n * });\n * ```\n */\nexport function createRateLimiter(options: RateLimitOptions): RateLimiter {\n  return new RateLimiter(\n    options.maxRequests,\n    options.interval,\n    options.storage,\n  );\n}\n\n/**\n * Gets the remaining requests for a key using the default rate limiter\n * @param key - The unique identifier for the rate limit entry\n * @returns Promise resolving to the number of remaining requests\n */\nexport async function getRemainingRequests(key: string): Promise<number> {\n  return defaultRateLimiter.getRemaining(key);\n}\n\n/**\n * Gets the reset time for a key using the default rate limiter\n * @param key - The unique identifier for the rate limit entry\n * @returns Promise resolving to the time in milliseconds until reset\n */\nexport async function getResetTime(key: string): Promise<number> {\n  return defaultRateLimiter.getResetTime(key);\n}\n\n/**\n * Resets the rate limit for a key using the default rate limiter\n * @param key - The unique identifier for the rate limit entry\n * @returns Promise that resolves when the reset is complete\n */\nexport async function resetRateLimit(key: string): Promise<void> {\n  return defaultRateLimiter.reset(key);\n}\n"],"mappings":";;;;;AAGA,MAAa,kBAAkB;;;;AAK/B,MAAa,uBAAuB;;;;;AA8CpC,IAAa,yBAAb,MAAgE;CAC9D,AAAiB,wBAAQ,IAAI,KAAqB;;;;;;CAOlD,MAAM,IAAI,KAA8B;AACtC,SAAO,KAAK,MAAM,IAAI,IAAI,IAAI;;;;;;;;CAShC,MAAM,IAAI,KAAa,OAA8B;AACnD,OAAK,MAAM,IAAI,KAAK,MAAM;;;;;;;CAQ5B,MAAM,OAAO,KAA4B;AACvC,OAAK,MAAM,OAAO,IAAI;;;;;;;AAQ1B,IAAa,cAAb,MAAyB;CACvB,AAAiB,yBAA8B,IAAI,KAAK;CACxD,AAAiB,4BAAiC,IAAI,KAAK;CAC3D,AAAiB;;;;;;;CAQjB,AAAO,YACP,AAAU,cAA6B,sBACvC,AAAU,WAA0B,iBACpC,AAAE,UAAkC,IAAE,wBAA0B,EAChE;EAHU;EACA;EACR;AAEA,OAAK,gBAAgB;;;;;;CAOvB,AAAO,WAAW,SAA2B;AAC3C,OAAK,UAAU;;;;;;CAOjB,AAAO,aAA+B;AACpC,SAAO,KAAK;;;;;;;CAQd,MAAa,MAAM,KAA+B;EAChD,MAAM,MAAM,KAAK,KAAK;AAKtB,MAHuB,OADL,KAAK,UAAU,IAAI,IAAI,IAAI,KAIxB,KAAK,eAAe;AACvC,SAAM,KAAK,QAAQ,OAAO,IAAI;AAC9B,QAAK,UAAU,IAAI,KAAK,IAAI;AAC5B,QAAK,OAAO,IAAI,KAAK,EAAE;;EAIzB,MAAM,eAAe,MAAM,KAAK,QAAQ,IAAI,IAAI;AAGhD,MAAI,gBAAgB,KAAK,YACvB,QAAO;EAIT,MAAM,WAAW,eAAe;AAChC,QAAM,KAAK,QAAQ,IAAI,KAAK,SAAS;AACrC,OAAK,OAAO,IAAI,KAAK,SAAS;AAE9B,SAAO;;;;;;;CAQT,MAAa,aAAa,KAA8B;EACtD,MAAM,eAAe,MAAM,KAAK,QAAQ,IAAI,IAAI;AAChD,SAAO,KAAK,IAAI,GAAG,KAAK,cAAc,aAAa;;;;;;;CAQrD,MAAa,aAAa,KAA8B;EACtD,MAAM,YAAY,KAAK,UAAU,IAAI,IAAI,IAAI;EAE7C,MAAM,iBADM,KAAK,KAAK,GACO;AAE7B,MAAI,kBAAkB,KAAK,cACzB,QAAO;AAGT,SAAO,KAAK,gBAAgB;;;;;;;CAQ9B,MAAa,MAAM,KAA4B;AAC7C,QAAM,KAAK,QAAQ,OAAO,IAAI;AAC9B,OAAK,OAAO,OAAO,IAAI;AACvB,OAAK,UAAU,OAAO,IAAI;;;;;;CAO5B,AAAO,YAA+C;AACpD,SAAO;GACL,aAAa,KAAK;GAClB,UAAU,KAAK;GAChB;;;;;;AAOL,MAAa,qBAAqB,IAAI,aAAa;;;;;;;;;;;;;;;;;;;;;;;;AAyBnD,eAAsB,UAAU,KAA+B;AAC7D,QAAO,mBAAmB,MAAM,IAAI;;;;;;;;;;;;;;;;AAiBtC,SAAgB,kBAAkB,SAAwC;AACxE,QAAO,IAAI,YACT,QAAQ,aACR,QAAQ,UACR,QAAQ,QACT;;;;;;;AAQH,eAAsB,qBAAqB,KAA8B;AACvE,QAAO,mBAAmB,aAAa,IAAI;;;;;;;AAQ7C,eAAsB,aAAa,KAA8B;AAC/D,QAAO,mBAAmB,aAAa,IAAI;;;;;;;AAQ7C,eAAsB,eAAe,KAA4B;AAC/D,QAAO,mBAAmB,MAAM,IAAI"}

package/dist/utils/useful-stuff/semaphore.d.ts

@@ -9,30 +9,30 @@
  */
 interface SemaphoreStorage {
   /**
-   * Attempts to acquire a permit for a given key
-   * @param key - The unique identifier for the semaphore
-   * @param timeout - Optional timeout in milliseconds for permit acquisition
-   * @param signal - Optional AbortSignal for cancelling the acquisition
-   * @returns Promise resolving to true if permit was acquired, false if timeout or no permits available
-   */
+       * Attempts to acquire a permit for a given key
+       * @param key - The unique identifier for the semaphore
+       * @param timeout - Optional timeout in milliseconds for permit acquisition
+       * @param signal - Optional AbortSignal for cancelling the acquisition
+       * @returns Promise resolving to true if permit was acquired, false if timeout or no permits available
+       */
   acquire(key: string, timeout?: number, signal?: AbortSignal): Promise<boolean>;
   /**
-   * Releases a permit for a given key
-   * @param key - The unique identifier for the semaphore
-   * @returns Promise that resolves when the permit is released
-   */
+       * Releases a permit for a given key
+       * @param key - The unique identifier for the semaphore
+       * @returns Promise that resolves when the permit is released
+       */
   release(key: string): Promise<void>;
   /**
-   * Gets the number of available permits for a given key
-   * @param key - The unique identifier for the semaphore
-   * @returns Promise resolving to the number of available permits
-   */
+       * Gets the number of available permits for a given key
+       * @param key - The unique identifier for the semaphore
+       * @returns Promise resolving to the number of available permits
+       */
   getAvailablePermits(key: string): Promise<number>;
   /**
-   * Gets the total number of permits for a given key
-   * @param key - The unique identifier for the semaphore
-   * @returns Promise resolving to the total number of permits
-   */
+       * Gets the total number of permits for a given key
+       * @param key - The unique identifier for the semaphore
+       * @returns Promise resolving to the total number of permits
+       */
   getTotalPermits(key: string): Promise<number>;
 }
 /**
@@ -53,36 +53,36 @@ interface SemaphoreOptions {
 declare class MemorySemaphoreStorage implements SemaphoreStorage {
   private readonly semaphores;
   /**
-   * Attempts to acquire a permit for a given key
-   * @param key - The unique identifier for the semaphore
-   * @param timeout - Optional timeout in milliseconds for permit acquisition
-   * @param signal - Optional AbortSignal for cancelling the acquisition
-   * @returns Promise resolving to true if permit was acquired, false if timeout or no permits available
-   */
+       * Attempts to acquire a permit for a given key
+       * @param key - The unique identifier for the semaphore
+       * @param timeout - Optional timeout in milliseconds for permit acquisition
+       * @param signal - Optional AbortSignal for cancelling the acquisition
+       * @returns Promise resolving to true if permit was acquired, false if timeout or no permits available
+       */
   acquire(key: string, timeout?: number, signal?: AbortSignal): Promise<boolean>;
   /**
-   * Releases a permit for a given key
-   * @param key - The unique identifier for the semaphore
-   * @returns Promise that resolves when the permit is released
-   */
+       * Releases a permit for a given key
+       * @param key - The unique identifier for the semaphore
+       * @returns Promise that resolves when the permit is released
+       */
   release(key: string): Promise<void>;
   /**
-   * Gets the number of available permits for a given key
-   * @param key - The unique identifier for the semaphore
-   * @returns Promise resolving to the number of available permits
-   */
+       * Gets the number of available permits for a given key
+       * @param key - The unique identifier for the semaphore
+       * @returns Promise resolving to the number of available permits
+       */
   getAvailablePermits(key: string): Promise<number>;
   /**
-   * Gets the total number of permits for a given key
-   * @param key - The unique identifier for the semaphore
-   * @returns Promise resolving to the total number of permits
-   */
+       * Gets the total number of permits for a given key
+       * @param key - The unique identifier for the semaphore
+       * @returns Promise resolving to the total number of permits
+       */
   getTotalPermits(key: string): Promise<number>;
   /**
-   * Initializes a semaphore with the specified number of permits
-   * @param key - The unique identifier for the semaphore
-   * @param permits - The total number of permits to allocate
-   */
+       * Initializes a semaphore with the specified number of permits
+       * @param key - The unique identifier for the semaphore
+       * @param permits - The total number of permits to allocate
+       */
   initialize(key: string, permits: number): void;
   private delay;
 }
@@ -95,66 +95,66 @@ declare class Semaphore {
   private readonly defaultPermits;
   private readonly defaultTimeout;
   /**
-   * Creates a new semaphore instance
-   * @param options - Configuration options for the semaphore
-   */
+       * Creates a new semaphore instance
+       * @param options - Configuration options for the semaphore
+       */
   constructor(options?: SemaphoreOptions);
   /**
-   * Sets the storage implementation for the semaphore
-   * @param storage - The storage implementation to use
-   */
+       * Sets the storage implementation for the semaphore
+       * @param storage - The storage implementation to use
+       */
   setStorage(storage: SemaphoreStorage): void;
   /**
-   * Gets the storage implementation for the semaphore
-   * @returns The storage implementation
-   */
+       * Gets the storage implementation for the semaphore
+       * @returns The storage implementation
+       */
   getStorage(): SemaphoreStorage;
   /**
-   * Acquires a permit for the given key
-   * @param key - The unique identifier for the semaphore
-   * @param timeout - Optional timeout in milliseconds for permit acquisition
-   * @param signal - Optional AbortSignal for cancelling the acquisition
-   * @returns Promise resolving to true if permit was acquired, false if timeout
-   */
+       * Acquires a permit for the given key
+       * @param key - The unique identifier for the semaphore
+       * @param timeout - Optional timeout in milliseconds for permit acquisition
+       * @param signal - Optional AbortSignal for cancelling the acquisition
+       * @returns Promise resolving to true if permit was acquired, false if timeout
+       */
   acquire(key: string, timeout?: number, signal?: AbortSignal): Promise<boolean>;
   /**
-   * Releases a permit for the given key
-   * @param key - The unique identifier for the semaphore
-   * @returns Promise that resolves when the permit is released
-   */
+       * Releases a permit for the given key
+       * @param key - The unique identifier for the semaphore
+       * @returns Promise that resolves when the permit is released
+       */
   release(key: string): Promise<void>;
   /**
-   * Gets the number of available permits for the given key
-   * @param key - The unique identifier for the semaphore
-   * @returns Promise resolving to the number of available permits
-   */
+       * Gets the number of available permits for the given key
+       * @param key - The unique identifier for the semaphore
+       * @returns Promise resolving to the number of available permits
+       */
   getAvailablePermits(key: string): Promise<number>;
   /**
-   * Gets the total number of permits for the given key
-   * @param key - The unique identifier for the semaphore
-   * @returns Promise resolving to the total number of permits
-   */
+       * Gets the total number of permits for the given key
+       * @param key - The unique identifier for the semaphore
+       * @returns Promise resolving to the total number of permits
+       */
   getTotalPermits(key: string): Promise<number>;
   /**
-   * Gets the number of acquired permits for the given key
-   * @param key - The unique identifier for the semaphore
-   * @returns Promise resolving to the number of acquired permits
-   */
+       * Gets the number of acquired permits for the given key
+       * @param key - The unique identifier for the semaphore
+       * @returns Promise resolving to the number of acquired permits
+       */
   getAcquiredPermits(key: string): Promise<number>;
   /**
-   * Executes a function with a permit from the semaphore
-   * @param key - The unique identifier for the semaphore
-   * @param fn - The function to execute with a permit
-   * @param timeout - Optional timeout in milliseconds for permit acquisition
-   * @param signal - Optional AbortSignal for cancelling the permit acquisition
-   * @returns Promise resolving to the result of the function execution
-   * @throws Error if permit acquisition fails or function execution fails
-   */
+       * Executes a function with a permit from the semaphore
+       * @param key - The unique identifier for the semaphore
+       * @param fn - The function to execute with a permit
+       * @param timeout - Optional timeout in milliseconds for permit acquisition
+       * @param signal - Optional AbortSignal for cancelling the permit acquisition
+       * @returns Promise resolving to the result of the function execution
+       * @throws Error if permit acquisition fails or function execution fails
+       */
   withPermit<T>(key: string, fn: () => Promise<T> | T, timeout?: number, signal?: AbortSignal): Promise<T>;
   /**
-   * Gets the current configuration of the semaphore
-   * @returns Object containing the current permits and timeout values
-   */
+       * Gets the current configuration of the semaphore
+       * @returns Object containing the current permits and timeout values
+       */
   getConfig(): Omit<SemaphoreOptions, 'storage'>;
 }
 /**