commandkit 1.0.0-dev.20250622061654 → 1.0.0-dev.20250622135945

package/dist/utils/useful-stuff/mutex.js

@@ -0,0 +1,214 @@
+
+//#region src/utils/useful-stuff/mutex.ts
+/**
+* In-memory storage implementation for mutex locks.
+* Suitable for single-instance applications.
+*/
+var MemoryMutexStorage = class {
+	locks = /* @__PURE__ */ new Map();
+	/**
+	* 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
+	*/
+	async acquire(key, timeout = 3e4, signal) {
+		const holder = this.generateHolderId();
+		const startTime = Date.now();
+		while (Date.now() - startTime < timeout) {
+			if (signal === null || signal === void 0 ? void 0 : signal.aborted) throw new Error("Lock acquisition was aborted");
+			if (!this.locks.has(key)) {
+				this.locks.set(key, {
+					holder,
+					acquiredAt: Date.now()
+				});
+				return true;
+			}
+			await this.delay(10);
+		}
+		return false;
+	}
+	/**
+	* 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
+	*/
+	async release(key) {
+		this.locks.delete(key);
+	}
+	/**
+	* 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
+	*/
+	async isLocked(key) {
+		return this.locks.has(key);
+	}
+	generateHolderId() {
+		return `holder_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+	}
+	delay(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+};
+/**
+* Async mutex implementation that provides mutual exclusion for shared resources.
+* Ensures only one task can access a protected resource at a time.
+*/
+var Mutex = class {
+	storage;
+	defaultTimeout;
+	/**
+	* Creates a new mutex instance
+	* @param options - Configuration options for the mutex
+	*/
+	constructor(options = {}) {
+		this.storage = options.storage || new MemoryMutexStorage();
+		this.defaultTimeout = options.timeout || 3e4;
+	}
+	/**
+	* Sets the storage implementation for the mutex
+	* @param storage - The storage implementation to use
+	*/
+	setStorage(storage) {
+		this.storage = storage;
+	}
+	/**
+	* Gets the storage implementation for the mutex
+	* @returns The storage implementation
+	*/
+	getStorage() {
+		return this.storage;
+	}
+	/**
+	* 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
+	*/
+	async acquire(key, timeout, signal) {
+		return this.storage.acquire(key, timeout || this.defaultTimeout, signal);
+	}
+	/**
+	* 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
+	*/
+	async release(key) {
+		return this.storage.release(key);
+	}
+	/**
+	* 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
+	*/
+	async isLocked(key) {
+		return this.storage.isLocked(key);
+	}
+	/**
+	* 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
+	*/
+	async withLock(key, fn, timeout, signal) {
+		const acquired = await this.acquire(key, timeout, signal);
+		if (!acquired) throw new Error(`Failed to acquire lock for key: ${key}`);
+		try {
+			return await fn();
+		} finally {
+			await this.release(key);
+		}
+	}
+	/**
+	* Gets the current configuration of the mutex
+	* @returns Object containing the current timeout value
+	*/
+	getConfig() {
+		return { timeout: this.defaultTimeout };
+	}
+};
+/**
+* Default mutex instance for global use
+*/
+const defaultMutex = new Mutex();
+/**
+* Convenience function to execute a function with exclusive access using the default mutex.
+*
+* @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
+*
+* @example
+* ```typescript
+* const controller = new AbortController();
+* const result = await withMutex('shared-resource', async () => {
+*   // This code runs with exclusive access
+*   return await updateSharedResource();
+* }, 30000, controller.signal);
+* controller.abort(); // Cancels the lock acquisition
+* ```
+*/
+async function withMutex(key, fn, timeout, signal) {
+	return defaultMutex.withLock(key, fn, timeout, signal);
+}
+/**
+* Creates a new mutex instance with the specified configuration
+* @param options - Configuration options for the mutex
+* @returns New Mutex instance
+*
+* @example
+* ```typescript
+* const mutex = createMutex({
+*   timeout: 60000,
+*   storage: new RedisMutexStorage()
+* });
+* ```
+*/
+function createMutex(options) {
+	return new Mutex(options);
+}
+/**
+* Acquires a lock using the default mutex
+* @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
+*/
+async function acquireLock(key, timeout, signal) {
+	return defaultMutex.acquire(key, timeout, signal);
+}
+/**
+* Releases a lock using the default mutex
+* @param key - The unique identifier for the mutex lock
+* @returns Promise that resolves when the lock is released
+*/
+async function releaseLock(key) {
+	return defaultMutex.release(key);
+}
+/**
+* Checks if a lock is held using the default mutex
+* @param key - The unique identifier for the mutex lock
+* @returns Promise resolving to true if the lock is held, false otherwise
+*/
+async function isLocked(key) {
+	return defaultMutex.isLocked(key);
+}
+
+//#endregion
+exports.MemoryMutexStorage = MemoryMutexStorage;
+exports.Mutex = Mutex;
+exports.acquireLock = acquireLock;
+exports.createMutex = createMutex;
+exports.defaultMutex = defaultMutex;
+exports.isLocked = isLocked;
+exports.releaseLock = releaseLock;
+exports.withMutex = withMutex;
+//# sourceMappingURL=mutex.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.js","names":[],"sources":["../../../src/utils/useful-stuff/mutex.ts"],"sourcesContent":["/**\n * Async mutex implementation for coordinating access to shared resources.\n * Provides mutual exclusion to ensure only one task can access a resource at a time.\n */\n\n/**\n * Interface for mutex storage implementations.\n * Provides methods to store, retrieve, and delete mutex lock data.\n */\nexport interface MutexStorage {\n  /**\n   * Attempts to acquire a lock for a given key\n   * @param key - The unique identifier for the mutex lock\n   * @param timeout - Optional timeout in milliseconds for the lock\n   * @param signal - Optional AbortSignal for cancelling the acquisition\n   * @returns Promise resolving to true if lock was acquired, false if timeout or already locked\n   */\n  acquire(\n    key: string,\n    timeout?: number,\n    signal?: AbortSignal,\n  ): Promise<boolean>;\n\n  /**\n   * Releases the lock for a given key\n   * @param key - The unique identifier for the mutex lock\n   * @returns Promise that resolves when the lock is released\n   */\n  release(key: string): Promise<void>;\n\n  /**\n   * Checks if a lock is currently held for a given key\n   * @param key - The unique identifier for the mutex lock\n   * @returns Promise resolving to true if the lock is held, false otherwise\n   */\n  isLocked(key: string): Promise<boolean>;\n}\n\n/**\n * Configuration options for mutex\n */\nexport interface MutexOptions {\n  /** Default timeout in milliseconds for lock acquisition. Default: 30000 */\n  timeout?: number;\n  /** Storage implementation for persisting mutex data. Default: {@link MemoryMutexStorage} */\n  storage?: MutexStorage;\n}\n\n/**\n * In-memory storage implementation for mutex locks.\n * Suitable for single-instance applications.\n */\nexport class MemoryMutexStorage implements MutexStorage {\n  private readonly locks = new Map<\n    string,\n    { holder: string; acquiredAt: number }\n  >();\n\n  /**\n   * Attempts to acquire a lock for a given key\n   * @param key - The unique identifier for the mutex lock\n   * @param timeout - Optional timeout in milliseconds for the lock\n   * @param signal - Optional AbortSignal for cancelling the acquisition\n   * @returns Promise resolving to true if lock was acquired, false if timeout or already locked\n   */\n  async acquire(\n    key: string,\n    timeout: number = 30000,\n    signal?: AbortSignal,\n  ): Promise<boolean> {\n    const holder = this.generateHolderId();\n    const startTime = Date.now();\n\n    while (Date.now() - startTime < timeout) {\n      // Check if aborted\n      if (signal?.aborted) {\n        throw new Error('Lock acquisition was aborted');\n      }\n\n      if (!this.locks.has(key)) {\n        this.locks.set(key, { holder, acquiredAt: Date.now() });\n        return true;\n      }\n      await this.delay(10);\n    }\n\n    return false;\n  }\n\n  /**\n   * Releases the lock for a given key\n   * @param key - The unique identifier for the mutex lock\n   * @returns Promise that resolves when the lock is released\n   */\n  async release(key: string): Promise<void> {\n    this.locks.delete(key);\n  }\n\n  /**\n   * Checks if a lock is currently held for a given key\n   * @param key - The unique identifier for the mutex lock\n   * @returns Promise resolving to true if the lock is held, false otherwise\n   */\n  async isLocked(key: string): Promise<boolean> {\n    return this.locks.has(key);\n  }\n\n  private generateHolderId(): string {\n    return `holder_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;\n  }\n\n  private delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n\n/**\n * Async mutex implementation that provides mutual exclusion for shared resources.\n * Ensures only one task can access a protected resource at a time.\n */\nexport class Mutex {\n  private storage: MutexStorage;\n  private readonly defaultTimeout: number;\n\n  /**\n   * Creates a new mutex instance\n   * @param options - Configuration options for the mutex\n   */\n  public constructor(options: MutexOptions = {}) {\n    this.storage = options.storage || new MemoryMutexStorage();\n    this.defaultTimeout = options.timeout || 30000;\n  }\n\n  /**\n   * Sets the storage implementation for the mutex\n   * @param storage - The storage implementation to use\n   */\n  public setStorage(storage: MutexStorage) {\n    this.storage = storage;\n  }\n\n  /**\n   * Gets the storage implementation for the mutex\n   * @returns The storage implementation\n   */\n  public getStorage(): MutexStorage {\n    return this.storage;\n  }\n\n  /**\n   * Acquires a lock for the given key\n   * @param key - The unique identifier for the mutex lock\n   * @param timeout - Optional timeout in milliseconds for lock acquisition\n   * @param signal - Optional AbortSignal for cancelling the acquisition\n   * @returns Promise resolving to true if lock was acquired, false if timeout\n   */\n  public async acquire(\n    key: string,\n    timeout?: number,\n    signal?: AbortSignal,\n  ): Promise<boolean> {\n    return this.storage.acquire(key, timeout || this.defaultTimeout, signal);\n  }\n\n  /**\n   * Releases the lock for the given key\n   * @param key - The unique identifier for the mutex lock\n   * @returns Promise that resolves when the lock is released\n   */\n  public async release(key: string): Promise<void> {\n    return this.storage.release(key);\n  }\n\n  /**\n   * Checks if a lock is currently held for the given key\n   * @param key - The unique identifier for the mutex lock\n   * @returns Promise resolving to true if the lock is held, false otherwise\n   */\n  public async isLocked(key: string): Promise<boolean> {\n    return this.storage.isLocked(key);\n  }\n\n  /**\n   * Executes a function with exclusive access to the resource\n   * @param key - The unique identifier for the mutex lock\n   * @param fn - The function to execute with exclusive access\n   * @param timeout - Optional timeout in milliseconds for lock acquisition\n   * @param signal - Optional AbortSignal for cancelling the lock acquisition\n   * @returns Promise resolving to the result of the function execution\n   * @throws Error if lock acquisition fails or function execution fails\n   */\n  public async withLock<T>(\n    key: string,\n    fn: () => Promise<T> | T,\n    timeout?: number,\n    signal?: AbortSignal,\n  ): Promise<T> {\n    const acquired = await this.acquire(key, timeout, signal);\n    if (!acquired) {\n      throw new Error(`Failed to acquire lock for key: ${key}`);\n    }\n\n    try {\n      return await fn();\n    } finally {\n      await this.release(key);\n    }\n  }\n\n  /**\n   * Gets the current configuration of the mutex\n   * @returns Object containing the current timeout value\n   */\n  public getConfig(): Omit<MutexOptions, 'storage'> {\n    return {\n      timeout: this.defaultTimeout,\n    };\n  }\n}\n\n/**\n * Default mutex instance for global use\n */\nexport const defaultMutex = new Mutex();\n\n/**\n * Convenience function to execute a function with exclusive access using the default mutex.\n *\n * @param key - The unique identifier for the mutex lock\n * @param fn - The function to execute with exclusive access\n * @param timeout - Optional timeout in milliseconds for lock acquisition\n * @param signal - Optional AbortSignal for cancelling the lock acquisition\n * @returns Promise resolving to the result of the function execution\n *\n * @example\n * ```typescript\n * const controller = new AbortController();\n * const result = await withMutex('shared-resource', async () => {\n *   // This code runs with exclusive access\n *   return await updateSharedResource();\n * }, 30000, controller.signal);\n * controller.abort(); // Cancels the lock acquisition\n * ```\n */\nexport async function withMutex<T>(\n  key: string,\n  fn: () => Promise<T> | T,\n  timeout?: number,\n  signal?: AbortSignal,\n): Promise<T> {\n  return defaultMutex.withLock(key, fn, timeout, signal);\n}\n\n/**\n * Creates a new mutex instance with the specified configuration\n * @param options - Configuration options for the mutex\n * @returns New Mutex instance\n *\n * @example\n * ```typescript\n * const mutex = createMutex({\n *   timeout: 60000,\n *   storage: new RedisMutexStorage()\n * });\n * ```\n */\nexport function createMutex(options: MutexOptions): Mutex {\n  return new Mutex(options);\n}\n\n/**\n * Acquires a lock using the default mutex\n * @param key - The unique identifier for the mutex lock\n * @param timeout - Optional timeout in milliseconds for lock acquisition\n * @param signal - Optional AbortSignal for cancelling the acquisition\n * @returns Promise resolving to true if lock was acquired, false if timeout\n */\nexport async function acquireLock(\n  key: string,\n  timeout?: number,\n  signal?: AbortSignal,\n): Promise<boolean> {\n  return defaultMutex.acquire(key, timeout, signal);\n}\n\n/**\n * Releases a lock using the default mutex\n * @param key - The unique identifier for the mutex lock\n * @returns Promise that resolves when the lock is released\n */\nexport async function releaseLock(key: string): Promise<void> {\n  return defaultMutex.release(key);\n}\n\n/**\n * Checks if a lock is held using the default mutex\n * @param key - The unique identifier for the mutex lock\n * @returns Promise resolving to true if the lock is held, false otherwise\n */\nexport async function isLocked(key: string): Promise<boolean> {\n  return defaultMutex.isLocked(key);\n}\n"],"mappings":";;;;;;AAoDA,IAAa,qBAAb,MAAwD;CACtD,AAAiB,wBAAQ,IAAI;;;;;;;;CAY7B,MAAM,QACN,KACA,UAAkB,KAClB,QACmB;EACjB,MAAM,SAAS,KAAK,kBAAkB;EACtC,MAAM,YAAY,KAAK,KAAK;AAE5B,SAAO,KAAK,KAAK,GAAG,YAAY,SAAS;AAEvC,uDAAI,OAAQ,QACV,OAAM,IAAI,MAAM;AAGlB,QAAK,KAAK,MAAM,IAAI,IAAI,EAAE;AACxB,SAAK,MAAM,IAAI,KAAK;KAAE;KAAQ,YAAY,KAAK,KAAK;IAAE,EAAC;AACvD,WAAO;GACT;AACA,SAAM,KAAK,MAAM,GAAG;EACtB;AAEA,SAAO;CACT;;;;;;CAOA,MAAM,QAAQ,KAA4B;AACxC,OAAK,MAAM,OAAO,IAAI;CACxB;;;;;;CAOA,MAAM,SAAS,KAA+B;AAC5C,SAAO,KAAK,MAAM,IAAI,IAAI;CAC5B;CAEA,AAAQ,mBAA2B;AACjC,UAAQ,SAAS,KAAK,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,SAAS,GAAG,CAAC,OAAO,GAAG,EAAE,CAAC;CACzE;CAEA,AAAQ,MAAM,IAA2B;AACvC,SAAO,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,GAAG;CACzD;AACF;;;;;AAMA,IAAa,QAAb,MAAmB;CACjB,AAAQ;CACR,AAAiB;;;;;CAMjB,AAAO,YAAY,UAAwB,CAAE,GAAE;AAC7C,OAAK,UAAU,QAAQ,WAAW,IAAI;AACtC,OAAK,iBAAiB,QAAQ,WAAW;CAC3C;;;;;CAMA,AAAO,WAAW,SAAuB;AACvC,OAAK,UAAU;CACjB;;;;;CAMA,AAAO,aAA2B;AAChC,SAAO,KAAK;CACd;;;;;;;;CASA,MAAa,QACb,KACA,SACA,QACmB;AACjB,SAAO,KAAK,QAAQ,QAAQ,KAAK,WAAW,KAAK,gBAAgB,OAAO;CAC1E;;;;;;CAOA,MAAa,QAAQ,KAA4B;AAC/C,SAAO,KAAK,QAAQ,QAAQ,IAAI;CAClC;;;;;;CAOA,MAAa,SAAS,KAA+B;AACnD,SAAO,KAAK,QAAQ,SAAS,IAAI;CACnC;;;;;;;;;;CAWA,MAAa,SACb,KACA,IACA,SACA,QACa;EACX,MAAM,WAAW,MAAM,KAAK,QAAQ,KAAK,SAAS,OAAO;AACzD,OAAK,SACH,OAAM,IAAI,OAAO,kCAAkC,IAAI;AAGzD,MAAI;AACF,UAAO,MAAM,IAAI;EAClB,UAAS;AACR,SAAM,KAAK,QAAQ,IAAI;EACzB;CACF;;;;;CAMA,AAAO,YAA2C;AAChD,SAAO,EACL,SAAS,KAAK,eACf;CACH;AACF;;;;AAKA,MAAa,eAAe,IAAI;;;;;;;;;;;;;;;;;;;;AAqBhC,eAAsB,UACtB,KACA,IACA,SACA,QACa;AACX,QAAO,aAAa,SAAS,KAAK,IAAI,SAAS,OAAO;AACxD;;;;;;;;;;;;;;AAeA,SAAgB,YAAY,SAA8B;AACxD,QAAO,IAAI,MAAM;AACnB;;;;;;;;AASA,eAAsB,YACtB,KACA,SACA,QACmB;AACjB,QAAO,aAAa,QAAQ,KAAK,SAAS,OAAO;AACnD;;;;;;AAOA,eAAsB,YAAY,KAA4B;AAC5D,QAAO,aAAa,QAAQ,IAAI;AAClC;;;;;;AAOA,eAAsB,SAAS,KAA+B;AAC5D,QAAO,aAAa,SAAS,IAAI;AACnC"}

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

@@ -0,0 +1,193 @@
+//#region src/utils/useful-stuff/ratelimiter.d.ts
+/**
+ * Default timeout interval for rate limiting in milliseconds
+ */
+declare const DEFAULT_TIMEOUT = 60000;
+/**
+ * Default maximum number of requests allowed per interval
+ */
+declare const DEFAULT_MAX_REQUESTS = 10;
+/**
+ * Interface for rate limit storage implementations.
+ * Provides methods to store, retrieve, and delete rate limit data.
+ */
+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
+   */
+  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
+   */
+  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
+   */
+  delete(key: string): Promise<void>;
+}
+/**
+ * Configuration options for rate limiting
+ */
+interface RateLimitOptions {
+  /** Maximum number of requests allowed per interval. Default: 10 */
+  maxRequests?: number;
+  /** Time interval in milliseconds for the rate limit window. Default: 60000 */
+  interval?: number;
+  /** Storage implementation for persisting rate limit data. Default: {@link MemoryRateLimitStorage} */
+  storage?: RateLimitStorage;
+}
+/**
+ * In-memory storage implementation for rate limiting.
+ * Suitable for single-instance applications.
+ */
+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
+   */
+  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
+   */
+  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
+   */
+  delete(key: string): Promise<void>;
+}
+/**
+ * Rate limiter implementation that enforces request limits per key.
+ * Supports configurable request limits and time intervals.
+ */
+declare class RateLimiter {
+  private readonly maxRequests;
+  private readonly interval;
+  private storage;
+  private readonly limits;
+  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)
+   */
+  constructor(maxRequests?: number, interval?: number, storage?: RateLimitStorage);
+  /**
+   * 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
+   */
+  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
+   */
+  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
+   */
+  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
+   */
+  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
+   */
+  reset(key: string): Promise<void>;
+  /**
+   * Gets the current configuration of the rate limiter
+   * @returns Object containing the current maxRequests and interval values
+   */
+  getConfig(): Omit<RateLimitOptions, 'storage'>;
+}
+/**
+ * Default rate limiter instance for global use
+ */
+declare const defaultRateLimiter: RateLimiter;
+/**
+ * Convenience function to check if a request is allowed for a given key.
+ * Uses the default rate limiter instance.
+ *
+ * @param key - The unique identifier for the rate limit entry
+ * @returns Promise resolving to true if the request is allowed, false if rate limited
+ *
+ * @example
+ * ```typescript
+ * const allowed = await ratelimit('user:123');
+ * // update the default rate limiter config
+ * import { defaultRateLimiter } from 'commandkit/ratelimit';
+ *
+ * // update max allowed requests
+ * defaultRateLimiter.setMaxRequests(10);
+ *
+ * // update the timeout interval
+ * defaultRateLimiter.setInterval(30000);
+ *
+ * // update the storage implementation
+ * defaultRateLimiter.setStorage(new RedisStorage());
+ * ```
+ */
+declare function ratelimit(key: string): Promise<boolean>;
+/**
+ * Creates a new rate limiter instance with the specified configuration
+ * @param options - Configuration options for the rate limiter
+ * @returns New RateLimiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createRateLimiter({
+ *   maxRequests: 5,
+ *   interval: 30000,
+ *   storage: new CustomStorage()
+ * });
+ * ```
+ */
+declare function createRateLimiter(options: RateLimitOptions): RateLimiter;
+/**
+ * Gets the remaining requests for a key using the default rate limiter
+ * @param key - The unique identifier for the rate limit entry
+ * @returns Promise resolving to the number of remaining requests
+ */
+declare function getRemainingRequests(key: string): Promise<number>;
+/**
+ * Gets the reset time for a key using the default rate limiter
+ * @param key - The unique identifier for the rate limit entry
+ * @returns Promise resolving to the time in milliseconds until reset
+ */
+declare function getResetTime(key: string): Promise<number>;
+/**
+ * Resets the rate limit for a key using the default rate limiter
+ * @param key - The unique identifier for the rate limit entry
+ * @returns Promise that resolves when the reset is complete
+ */
+declare function resetRateLimit(key: string): Promise<void>;
+//#endregion
+export { DEFAULT_MAX_REQUESTS, DEFAULT_TIMEOUT, MemoryRateLimitStorage, RateLimitOptions, RateLimitStorage, RateLimiter, createRateLimiter, defaultRateLimiter, getRemainingRequests, getResetTime, ratelimit, resetRateLimit };
+//# sourceMappingURL=ratelimiter.d.ts.map

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

@@ -0,0 +1,223 @@
+
+//#region src/utils/useful-stuff/ratelimiter.ts
+/**
+* Default timeout interval for rate limiting in milliseconds
+*/
+const DEFAULT_TIMEOUT = 6e4;
+/**
+* Default maximum number of requests allowed per interval
+*/
+const DEFAULT_MAX_REQUESTS = 10;
+/**
+* In-memory storage implementation for rate limiting.
+* Suitable for single-instance applications.
+*/
+var MemoryRateLimitStorage = class {
+	store = /* @__PURE__ */ new Map();
+	/**
+	* 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
+	*/
+	async get(key) {
+		return this.store.get(key) || 0;
+	}
+	/**
+	* 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
+	*/
+	async set(key, value) {
+		this.store.set(key, value);
+	}
+	/**
+	* Deletes the rate limit entry for a given key
+	* @param key - The unique identifier for the rate limit entry
+	* @returns Promise that resolves immediately
+	*/
+	async delete(key) {
+		this.store.delete(key);
+	}
+};
+/**
+* Rate limiter implementation that enforces request limits per key.
+* Supports configurable request limits and time intervals.
+*/
+var RateLimiter = class {
+	limits = /* @__PURE__ */ new Map();
+	lastReset = /* @__PURE__ */ new Map();
+	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)
+	*/
+	constructor(maxRequests = DEFAULT_MAX_REQUESTS, interval = DEFAULT_TIMEOUT, storage = new MemoryRateLimitStorage()) {
+		this.maxRequests = maxRequests;
+		this.interval = interval;
+		this.storage = storage;
+		this.resetInterval = interval;
+	}
+	/**
+	* Sets the storage implementation for the rate limiter
+	* @param storage - The storage implementation to use
+	*/
+	setStorage(storage) {
+		this.storage = storage;
+	}
+	/**
+	* Gets the storage implementation for the rate limiter
+	* @returns The storage implementation
+	*/
+	getStorage() {
+		return this.storage;
+	}
+	/**
+	* 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
+	*/
+	async limit(key) {
+		const now = Date.now();
+		const lastReset = this.lastReset.get(key) || 0;
+		const timeSinceReset = now - lastReset;
+		if (timeSinceReset > this.resetInterval) {
+			await this.storage.delete(key);
+			this.lastReset.set(key, now);
+			this.limits.set(key, 0);
+		}
+		const currentCount = await this.storage.get(key);
+		if (currentCount >= this.maxRequests) return false;
+		const newCount = currentCount + 1;
+		await this.storage.set(key, newCount);
+		this.limits.set(key, newCount);
+		return true;
+	}
+	/**
+	* 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
+	*/
+	async getRemaining(key) {
+		const currentCount = await this.storage.get(key);
+		return Math.max(0, this.maxRequests - currentCount);
+	}
+	/**
+	* 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
+	*/
+	async getResetTime(key) {
+		const lastReset = this.lastReset.get(key) || 0;
+		const now = Date.now();
+		const timeSinceReset = now - lastReset;
+		if (timeSinceReset >= this.resetInterval) return 0;
+		return this.resetInterval - timeSinceReset;
+	}
+	/**
+	* 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
+	*/
+	async reset(key) {
+		await this.storage.delete(key);
+		this.limits.delete(key);
+		this.lastReset.delete(key);
+	}
+	/**
+	* Gets the current configuration of the rate limiter
+	* @returns Object containing the current maxRequests and interval values
+	*/
+	getConfig() {
+		return {
+			maxRequests: this.maxRequests,
+			interval: this.interval
+		};
+	}
+};
+/**
+* Default rate limiter instance for global use
+*/
+const defaultRateLimiter = new RateLimiter();
+/**
+* Convenience function to check if a request is allowed for a given key.
+* Uses the default rate limiter instance.
+*
+* @param key - The unique identifier for the rate limit entry
+* @returns Promise resolving to true if the request is allowed, false if rate limited
+*
+* @example
+* ```typescript
+* const allowed = await ratelimit('user:123');
+* // update the default rate limiter config
+* import { defaultRateLimiter } from 'commandkit/ratelimit';
+*
+* // update max allowed requests
+* defaultRateLimiter.setMaxRequests(10);
+*
+* // update the timeout interval
+* defaultRateLimiter.setInterval(30000);
+*
+* // update the storage implementation
+* defaultRateLimiter.setStorage(new RedisStorage());
+* ```
+*/
+async function ratelimit(key) {
+	return defaultRateLimiter.limit(key);
+}
+/**
+* Creates a new rate limiter instance with the specified configuration
+* @param options - Configuration options for the rate limiter
+* @returns New RateLimiter instance
+*
+* @example
+* ```typescript
+* const limiter = createRateLimiter({
+*   maxRequests: 5,
+*   interval: 30000,
+*   storage: new CustomStorage()
+* });
+* ```
+*/
+function createRateLimiter(options) {
+	return new RateLimiter(options.maxRequests, options.interval, options.storage);
+}
+/**
+* Gets the remaining requests for a key using the default rate limiter
+* @param key - The unique identifier for the rate limit entry
+* @returns Promise resolving to the number of remaining requests
+*/
+async function getRemainingRequests(key) {
+	return defaultRateLimiter.getRemaining(key);
+}
+/**
+* Gets the reset time for a key using the default rate limiter
+* @param key - The unique identifier for the rate limit entry
+* @returns Promise resolving to the time in milliseconds until reset
+*/
+async function getResetTime(key) {
+	return defaultRateLimiter.getResetTime(key);
+}
+/**
+* Resets the rate limit for a key using the default rate limiter
+* @param key - The unique identifier for the rate limit entry
+* @returns Promise that resolves when the reset is complete
+*/
+async function resetRateLimit(key) {
+	return defaultRateLimiter.reset(key);
+}
+
+//#endregion
+exports.DEFAULT_MAX_REQUESTS = DEFAULT_MAX_REQUESTS;
+exports.DEFAULT_TIMEOUT = DEFAULT_TIMEOUT;
+exports.MemoryRateLimitStorage = MemoryRateLimitStorage;
+exports.RateLimiter = RateLimiter;
+exports.createRateLimiter = createRateLimiter;
+exports.defaultRateLimiter = defaultRateLimiter;
+exports.getRemainingRequests = getRemainingRequests;
+exports.getResetTime = getResetTime;
+exports.ratelimit = ratelimit;
+exports.resetRateLimit = resetRateLimit;
+//# sourceMappingURL=ratelimiter.js.map

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

@@ -0,0 +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;;;;;;CAO7B,MAAM,IAAI,KAA8B;AACtC,SAAO,KAAK,MAAM,IAAI,IAAI,IAAI;CAChC;;;;;;;CAQA,MAAM,IAAI,KAAa,OAA8B;AACnD,OAAK,MAAM,IAAI,KAAK,MAAM;CAC5B;;;;;;CAOA,MAAM,OAAO,KAA4B;AACvC,OAAK,MAAM,OAAO,IAAI;CACxB;AACF;;;;;AAMA,IAAa,cAAb,MAAyB;CACvB,AAAiB,yBAA8B,IAAI;CACnD,AAAiB,4BAAiC,IAAI;CACtD,AAAiB;;;;;;;CAQjB,AAAO,YACU,cAAsB,sBACtB,WAAmB,iBAC5B,UAA4B,IAAI,0BACxC;EAHiB;EACA;EACT;AAEN,OAAK,gBAAgB;CACvB;;;;;CAMA,AAAO,WAAW,SAA2B;AAC3C,OAAK,UAAU;CACjB;;;;;CAMA,AAAO,aAA+B;AACpC,SAAO,KAAK;CACd;;;;;;CAOA,MAAa,MAAM,KAA+B;EAChD,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,YAAY,KAAK,UAAU,IAAI,IAAI,IAAI;EAC7C,MAAM,iBAAiB,MAAM;AAG7B,MAAI,iBAAiB,KAAK,eAAe;AACvC,SAAM,KAAK,QAAQ,OAAO,IAAI;AAC9B,QAAK,UAAU,IAAI,KAAK,IAAI;AAC5B,QAAK,OAAO,IAAI,KAAK,EAAE;EACzB;EAGA,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;CACT;;;;;;CAOA,MAAa,aAAa,KAA8B;EACtD,MAAM,eAAe,MAAM,KAAK,QAAQ,IAAI,IAAI;AAChD,SAAO,KAAK,IAAI,GAAG,KAAK,cAAc,aAAa;CACrD;;;;;;CAOA,MAAa,aAAa,KAA8B;EACtD,MAAM,YAAY,KAAK,UAAU,IAAI,IAAI,IAAI;EAC7C,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,iBAAiB,MAAM;AAE7B,MAAI,kBAAkB,KAAK,cACzB,QAAO;AAGT,SAAO,KAAK,gBAAgB;CAC9B;;;;;;CAOA,MAAa,MAAM,KAA4B;AAC7C,QAAM,KAAK,QAAQ,OAAO,IAAI;AAC9B,OAAK,OAAO,OAAO,IAAI;AACvB,OAAK,UAAU,OAAO,IAAI;CAC5B;;;;;CAMA,AAAO,YAA+C;AACpD,SAAO;GACL,aAAa,KAAK;GAClB,UAAU,KAAK;EAChB;CACH;AACF;;;;AAKA,MAAa,qBAAqB,IAAI;;;;;;;;;;;;;;;;;;;;;;;;AAyBtC,eAAsB,UAAU,KAA+B;AAC7D,QAAO,mBAAmB,MAAM,IAAI;AACtC;;;;;;;;;;;;;;;AAgBA,SAAgB,kBAAkB,SAAwC;AACxE,QAAO,IAAI,YACT,QAAQ,aACR,QAAQ,UACR,QAAQ;AAEZ;;;;;;AAOA,eAAsB,qBAAqB,KAA8B;AACvE,QAAO,mBAAmB,aAAa,IAAI;AAC7C;;;;;;AAOA,eAAsB,aAAa,KAA8B;AAC/D,QAAO,mBAAmB,aAAa,IAAI;AAC7C;;;;;;AAOA,eAAsB,eAAe,KAA4B;AAC/D,QAAO,mBAAmB,MAAM,IAAI;AACtC"}