commandkit 1.0.0-dev.20250722021811 → 1.0.0-dev.20250723021937

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

@@ -1 +1 @@
-{"version":3,"file":"semaphore.js","names":[],"sources":["../../../src/utils/useful-stuff/semaphore.ts"],"sourcesContent":["/**\n * Async semaphore implementation for controlling access to a limited pool of resources.\n * Allows a specified number of concurrent operations while blocking additional requests.\n */\n\n/**\n * Interface for semaphore storage implementations.\n * Provides methods to store, retrieve, and manage semaphore permit data.\n */\nexport interface SemaphoreStorage {\n  /**\n   * Attempts to acquire a permit for a given key\n   * @param key - The unique identifier for the semaphore\n   * @param timeout - Optional timeout in milliseconds for permit acquisition\n   * @param signal - Optional AbortSignal for cancelling the acquisition\n   * @returns Promise resolving to true if permit was acquired, false if timeout or no permits available\n   */\n  acquire(\n    key: string,\n    timeout?: number,\n    signal?: AbortSignal,\n  ): Promise<boolean>;\n\n  /**\n   * Releases a permit for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise that resolves when the permit is released\n   */\n  release(key: string): Promise<void>;\n\n  /**\n   * Gets the number of available permits for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the number of available permits\n   */\n  getAvailablePermits(key: string): Promise<number>;\n\n  /**\n   * Gets the total number of permits for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the total number of permits\n   */\n  getTotalPermits(key: string): Promise<number>;\n}\n\n/**\n * Configuration options for semaphore\n */\nexport interface SemaphoreOptions {\n  /** Maximum number of concurrent permits allowed. Default: 1 */\n  permits?: number;\n  /** Default timeout in milliseconds for permit acquisition. Default: 30000 */\n  timeout?: number;\n  /** Storage implementation for persisting semaphore data. Default: {@link MemorySemaphoreStorage} */\n  storage?: SemaphoreStorage;\n}\n\n/**\n * In-memory storage implementation for semaphore permits.\n * Suitable for single-instance applications.\n */\nexport class MemorySemaphoreStorage implements SemaphoreStorage {\n  private readonly semaphores = new Map<\n    string,\n    { total: number; available: number }\n  >();\n\n  /**\n   * Attempts to acquire a permit for a given key\n   * @param key - The unique identifier for the semaphore\n   * @param timeout - Optional timeout in milliseconds for permit acquisition\n   * @param signal - Optional AbortSignal for cancelling the acquisition\n   * @returns Promise resolving to true if permit was acquired, false if timeout or no permits available\n   */\n  async acquire(\n    key: string,\n    timeout: number = 30000,\n    signal?: AbortSignal,\n  ): Promise<boolean> {\n    const startTime = Date.now();\n\n    while (Date.now() - startTime < timeout) {\n      // Check if aborted\n      if (signal?.aborted) {\n        throw new Error('Permit acquisition was aborted');\n      }\n\n      const semaphore = this.semaphores.get(key);\n      if (semaphore && semaphore.available > 0) {\n        semaphore.available--;\n        return true;\n      }\n      await this.delay(10);\n    }\n\n    return false;\n  }\n\n  /**\n   * Releases a permit for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise that resolves when the permit is released\n   */\n  async release(key: string): Promise<void> {\n    const semaphore = this.semaphores.get(key);\n    if (semaphore && semaphore.available < semaphore.total) {\n      semaphore.available++;\n    }\n  }\n\n  /**\n   * Gets the number of available permits for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the number of available permits\n   */\n  async getAvailablePermits(key: string): Promise<number> {\n    const semaphore = this.semaphores.get(key);\n    return semaphore ? semaphore.available : 0;\n  }\n\n  /**\n   * Gets the total number of permits for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the total number of permits\n   */\n  async getTotalPermits(key: string): Promise<number> {\n    const semaphore = this.semaphores.get(key);\n    return semaphore ? semaphore.total : 0;\n  }\n\n  /**\n   * Initializes a semaphore with the specified number of permits\n   * @param key - The unique identifier for the semaphore\n   * @param permits - The total number of permits to allocate\n   */\n  initialize(key: string, permits: number): void {\n    this.semaphores.set(key, { total: permits, available: permits });\n  }\n\n  private delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n\n/**\n * Async semaphore implementation that controls access to a limited pool of resources.\n * Allows a specified number of concurrent operations while blocking additional requests.\n */\nexport class Semaphore {\n  private storage: SemaphoreStorage;\n  private readonly defaultPermits: number;\n  private readonly defaultTimeout: number;\n\n  /**\n   * Creates a new semaphore instance\n   * @param options - Configuration options for the semaphore\n   */\n  public constructor(options: SemaphoreOptions = {}) {\n    this.storage = options.storage || new MemorySemaphoreStorage();\n    this.defaultPermits = options.permits || 1;\n    this.defaultTimeout = options.timeout || 30000;\n  }\n\n  /**\n   * Sets the storage implementation for the semaphore\n   * @param storage - The storage implementation to use\n   */\n  public setStorage(storage: SemaphoreStorage) {\n    this.storage = storage;\n  }\n\n  /**\n   * Gets the storage implementation for the semaphore\n   * @returns The storage implementation\n   */\n  public getStorage(): SemaphoreStorage {\n    return this.storage;\n  }\n\n  /**\n   * Acquires a permit for the given key\n   * @param key - The unique identifier for the semaphore\n   * @param timeout - Optional timeout in milliseconds for permit acquisition\n   * @param signal - Optional AbortSignal for cancelling the acquisition\n   * @returns Promise resolving to true if permit was acquired, false if timeout\n   */\n  public async acquire(\n    key: string,\n    timeout?: number,\n    signal?: AbortSignal,\n  ): Promise<boolean> {\n    // Initialize semaphore if it doesn't exist\n    if (this.storage instanceof MemorySemaphoreStorage) {\n      const totalPermits = await this.storage.getTotalPermits(key);\n      if (totalPermits === 0) {\n        (this.storage as MemorySemaphoreStorage).initialize(\n          key,\n          this.defaultPermits,\n        );\n      }\n    }\n\n    return this.storage.acquire(key, timeout || this.defaultTimeout, signal);\n  }\n\n  /**\n   * Releases a permit for the given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise that resolves when the permit is released\n   */\n  public async release(key: string): Promise<void> {\n    return this.storage.release(key);\n  }\n\n  /**\n   * Gets the number of available permits for the given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the number of available permits\n   */\n  public async getAvailablePermits(key: string): Promise<number> {\n    return this.storage.getAvailablePermits(key);\n  }\n\n  /**\n   * Gets the total number of permits for the given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the total number of permits\n   */\n  public async getTotalPermits(key: string): Promise<number> {\n    return this.storage.getTotalPermits(key);\n  }\n\n  /**\n   * Gets the number of acquired permits for the given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the number of acquired permits\n   */\n  public async getAcquiredPermits(key: string): Promise<number> {\n    const total = await this.getTotalPermits(key);\n    const available = await this.getAvailablePermits(key);\n    return total - available;\n  }\n\n  /**\n   * Executes a function with a permit from the semaphore\n   * @param key - The unique identifier for the semaphore\n   * @param fn - The function to execute with a permit\n   * @param timeout - Optional timeout in milliseconds for permit acquisition\n   * @param signal - Optional AbortSignal for cancelling the permit acquisition\n   * @returns Promise resolving to the result of the function execution\n   * @throws Error if permit acquisition fails or function execution fails\n   */\n  public async withPermit<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 permit 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 semaphore\n   * @returns Object containing the current permits and timeout values\n   */\n  public getConfig(): Omit<SemaphoreOptions, 'storage'> {\n    return {\n      permits: this.defaultPermits,\n      timeout: this.defaultTimeout,\n    };\n  }\n}\n\n/**\n * Default semaphore instance for global use\n */\nexport const defaultSemaphore = new Semaphore();\n\n/**\n * Convenience function to execute a function with a permit using the default semaphore.\n *\n * @param key - The unique identifier for the semaphore\n * @param fn - The function to execute with a permit\n * @param timeout - Optional timeout in milliseconds for permit acquisition\n * @param signal - Optional AbortSignal for cancelling the permit 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 withPermit('database-connection', async () => {\n *   // This code runs with a permit from the semaphore\n *   return await executeDatabaseQuery();\n * }, 30000, controller.signal);\n * controller.abort(); // Cancels the permit acquisition\n * ```\n */\nexport async function withPermit<T>(\n  key: string,\n  fn: () => Promise<T> | T,\n  timeout?: number,\n  signal?: AbortSignal,\n): Promise<T> {\n  return defaultSemaphore.withPermit(key, fn, timeout, signal);\n}\n\n/**\n * Creates a new semaphore instance with the specified configuration\n * @param options - Configuration options for the semaphore\n * @returns New Semaphore instance\n *\n * @example\n * ```typescript\n * const semaphore = createSemaphore({\n *   permits: 5,\n *   timeout: 60000,\n *   storage: new RedisSemaphoreStorage()\n * });\n * ```\n */\nexport function createSemaphore(options: SemaphoreOptions): Semaphore {\n  return new Semaphore(options);\n}\n\n/**\n * Acquires a permit using the default semaphore\n * @param key - The unique identifier for the semaphore\n * @param timeout - Optional timeout in milliseconds for permit acquisition\n * @param signal - Optional AbortSignal for cancelling the acquisition\n * @returns Promise resolving to true if permit was acquired, false if timeout\n */\nexport async function acquirePermit(\n  key: string,\n  timeout?: number,\n  signal?: AbortSignal,\n): Promise<boolean> {\n  return defaultSemaphore.acquire(key, timeout, signal);\n}\n\n/**\n * Releases a permit using the default semaphore\n * @param key - The unique identifier for the semaphore\n * @returns Promise that resolves when the permit is released\n */\nexport async function releasePermit(key: string): Promise<void> {\n  return defaultSemaphore.release(key);\n}\n\n/**\n * Gets the number of available permits using the default semaphore\n * @param key - The unique identifier for the semaphore\n * @returns Promise resolving to the number of available permits\n */\nexport async function getAvailablePermits(key: string): Promise<number> {\n  return defaultSemaphore.getAvailablePermits(key);\n}\n\n/**\n * Gets the number of acquired permits using the default semaphore\n * @param key - The unique identifier for the semaphore\n * @returns Promise resolving to the number of acquired permits\n */\nexport async function getAcquiredPermits(key: string): Promise<number> {\n  return defaultSemaphore.getAcquiredPermits(key);\n}\n"],"mappings":"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"}
+{"version":3,"file":"semaphore.js","names":[],"sources":["../../../src/utils/useful-stuff/semaphore.ts"],"sourcesContent":["/**\n * Async semaphore implementation for controlling access to a limited pool of resources.\n * Allows a specified number of concurrent operations while blocking additional requests.\n */\n\n/**\n * Interface for semaphore storage implementations.\n * Provides methods to store, retrieve, and manage semaphore permit data.\n */\nexport interface SemaphoreStorage {\n  /**\n   * Attempts to acquire a permit for a given key\n   * @param key - The unique identifier for the semaphore\n   * @param timeout - Optional timeout in milliseconds for permit acquisition\n   * @param signal - Optional AbortSignal for cancelling the acquisition\n   * @returns Promise resolving to true if permit was acquired, false if timeout or no permits available\n   */\n  acquire(\n    key: string,\n    timeout?: number,\n    signal?: AbortSignal,\n  ): Promise<boolean>;\n\n  /**\n   * Releases a permit for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise that resolves when the permit is released\n   */\n  release(key: string): Promise<void>;\n\n  /**\n   * Gets the number of available permits for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the number of available permits\n   */\n  getAvailablePermits(key: string): Promise<number>;\n\n  /**\n   * Gets the total number of permits for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the total number of permits\n   */\n  getTotalPermits(key: string): Promise<number>;\n}\n\n/**\n * Configuration options for semaphore\n */\nexport interface SemaphoreOptions {\n  /** Maximum number of concurrent permits allowed. Default: 1 */\n  permits?: number;\n  /** Default timeout in milliseconds for permit acquisition. Default: 30000 */\n  timeout?: number;\n  /** Storage implementation for persisting semaphore data. Default: {@link MemorySemaphoreStorage} */\n  storage?: SemaphoreStorage;\n}\n\n/**\n * In-memory storage implementation for semaphore permits.\n * Suitable for single-instance applications.\n */\nexport class MemorySemaphoreStorage implements SemaphoreStorage {\n  private readonly semaphores = new Map<\n    string,\n    { total: number; available: number }\n  >();\n\n  /**\n   * Attempts to acquire a permit for a given key\n   * @param key - The unique identifier for the semaphore\n   * @param timeout - Optional timeout in milliseconds for permit acquisition\n   * @param signal - Optional AbortSignal for cancelling the acquisition\n   * @returns Promise resolving to true if permit was acquired, false if timeout or no permits available\n   */\n  async acquire(\n    key: string,\n    timeout: number = 30000,\n    signal?: AbortSignal,\n  ): Promise<boolean> {\n    const startTime = Date.now();\n\n    while (Date.now() - startTime < timeout) {\n      // Check if aborted\n      if (signal?.aborted) {\n        throw new Error('Permit acquisition was aborted');\n      }\n\n      const semaphore = this.semaphores.get(key);\n      if (semaphore && semaphore.available > 0) {\n        semaphore.available--;\n        return true;\n      }\n      await this.delay(10);\n    }\n\n    return false;\n  }\n\n  /**\n   * Releases a permit for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise that resolves when the permit is released\n   */\n  async release(key: string): Promise<void> {\n    const semaphore = this.semaphores.get(key);\n    if (semaphore && semaphore.available < semaphore.total) {\n      semaphore.available++;\n    }\n  }\n\n  /**\n   * Gets the number of available permits for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the number of available permits\n   */\n  async getAvailablePermits(key: string): Promise<number> {\n    const semaphore = this.semaphores.get(key);\n    return semaphore ? semaphore.available : 0;\n  }\n\n  /**\n   * Gets the total number of permits for a given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the total number of permits\n   */\n  async getTotalPermits(key: string): Promise<number> {\n    const semaphore = this.semaphores.get(key);\n    return semaphore ? semaphore.total : 0;\n  }\n\n  /**\n   * Initializes a semaphore with the specified number of permits\n   * @param key - The unique identifier for the semaphore\n   * @param permits - The total number of permits to allocate\n   */\n  initialize(key: string, permits: number): void {\n    this.semaphores.set(key, { total: permits, available: permits });\n  }\n\n  private delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n\n/**\n * Async semaphore implementation that controls access to a limited pool of resources.\n * Allows a specified number of concurrent operations while blocking additional requests.\n */\nexport class Semaphore {\n  private storage: SemaphoreStorage;\n  private readonly defaultPermits: number;\n  private readonly defaultTimeout: number;\n\n  /**\n   * Creates a new semaphore instance\n   * @param options - Configuration options for the semaphore\n   */\n  public constructor(options: SemaphoreOptions = {}) {\n    this.storage = options.storage || new MemorySemaphoreStorage();\n    this.defaultPermits = options.permits || 1;\n    this.defaultTimeout = options.timeout || 30000;\n  }\n\n  /**\n   * Sets the storage implementation for the semaphore\n   * @param storage - The storage implementation to use\n   */\n  public setStorage(storage: SemaphoreStorage) {\n    this.storage = storage;\n  }\n\n  /**\n   * Gets the storage implementation for the semaphore\n   * @returns The storage implementation\n   */\n  public getStorage(): SemaphoreStorage {\n    return this.storage;\n  }\n\n  /**\n   * Acquires a permit for the given key\n   * @param key - The unique identifier for the semaphore\n   * @param timeout - Optional timeout in milliseconds for permit acquisition\n   * @param signal - Optional AbortSignal for cancelling the acquisition\n   * @returns Promise resolving to true if permit was acquired, false if timeout\n   */\n  public async acquire(\n    key: string,\n    timeout?: number,\n    signal?: AbortSignal,\n  ): Promise<boolean> {\n    // Initialize semaphore if it doesn't exist\n    if (this.storage instanceof MemorySemaphoreStorage) {\n      const totalPermits = await this.storage.getTotalPermits(key);\n      if (totalPermits === 0) {\n        (this.storage as MemorySemaphoreStorage).initialize(\n          key,\n          this.defaultPermits,\n        );\n      }\n    }\n\n    return this.storage.acquire(key, timeout || this.defaultTimeout, signal);\n  }\n\n  /**\n   * Releases a permit for the given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise that resolves when the permit is released\n   */\n  public async release(key: string): Promise<void> {\n    return this.storage.release(key);\n  }\n\n  /**\n   * Gets the number of available permits for the given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the number of available permits\n   */\n  public async getAvailablePermits(key: string): Promise<number> {\n    return this.storage.getAvailablePermits(key);\n  }\n\n  /**\n   * Gets the total number of permits for the given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the total number of permits\n   */\n  public async getTotalPermits(key: string): Promise<number> {\n    return this.storage.getTotalPermits(key);\n  }\n\n  /**\n   * Gets the number of acquired permits for the given key\n   * @param key - The unique identifier for the semaphore\n   * @returns Promise resolving to the number of acquired permits\n   */\n  public async getAcquiredPermits(key: string): Promise<number> {\n    const total = await this.getTotalPermits(key);\n    const available = await this.getAvailablePermits(key);\n    return total - available;\n  }\n\n  /**\n   * Executes a function with a permit from the semaphore\n   * @param key - The unique identifier for the semaphore\n   * @param fn - The function to execute with a permit\n   * @param timeout - Optional timeout in milliseconds for permit acquisition\n   * @param signal - Optional AbortSignal for cancelling the permit acquisition\n   * @returns Promise resolving to the result of the function execution\n   * @throws Error if permit acquisition fails or function execution fails\n   */\n  public async withPermit<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 permit 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 semaphore\n   * @returns Object containing the current permits and timeout values\n   */\n  public getConfig(): Omit<SemaphoreOptions, 'storage'> {\n    return {\n      permits: this.defaultPermits,\n      timeout: this.defaultTimeout,\n    };\n  }\n}\n\n/**\n * Default semaphore instance for global use\n */\nexport const defaultSemaphore = new Semaphore();\n\n/**\n * Convenience function to execute a function with a permit using the default semaphore.\n *\n * @param key - The unique identifier for the semaphore\n * @param fn - The function to execute with a permit\n * @param timeout - Optional timeout in milliseconds for permit acquisition\n * @param signal - Optional AbortSignal for cancelling the permit 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 withPermit('database-connection', async () => {\n *   // This code runs with a permit from the semaphore\n *   return await executeDatabaseQuery();\n * }, 30000, controller.signal);\n * controller.abort(); // Cancels the permit acquisition\n * ```\n */\nexport async function withPermit<T>(\n  key: string,\n  fn: () => Promise<T> | T,\n  timeout?: number,\n  signal?: AbortSignal,\n): Promise<T> {\n  return defaultSemaphore.withPermit(key, fn, timeout, signal);\n}\n\n/**\n * Creates a new semaphore instance with the specified configuration\n * @param options - Configuration options for the semaphore\n * @returns New Semaphore instance\n *\n * @example\n * ```typescript\n * const semaphore = createSemaphore({\n *   permits: 5,\n *   timeout: 60000,\n *   storage: new RedisSemaphoreStorage()\n * });\n * ```\n */\nexport function createSemaphore(options: SemaphoreOptions): Semaphore {\n  return new Semaphore(options);\n}\n\n/**\n * Acquires a permit using the default semaphore\n * @param key - The unique identifier for the semaphore\n * @param timeout - Optional timeout in milliseconds for permit acquisition\n * @param signal - Optional AbortSignal for cancelling the acquisition\n * @returns Promise resolving to true if permit was acquired, false if timeout\n */\nexport async function acquirePermit(\n  key: string,\n  timeout?: number,\n  signal?: AbortSignal,\n): Promise<boolean> {\n  return defaultSemaphore.acquire(key, timeout, signal);\n}\n\n/**\n * Releases a permit using the default semaphore\n * @param key - The unique identifier for the semaphore\n * @returns Promise that resolves when the permit is released\n */\nexport async function releasePermit(key: string): Promise<void> {\n  return defaultSemaphore.release(key);\n}\n\n/**\n * Gets the number of available permits using the default semaphore\n * @param key - The unique identifier for the semaphore\n * @returns Promise resolving to the number of available permits\n */\nexport async function getAvailablePermits(key: string): Promise<number> {\n  return defaultSemaphore.getAvailablePermits(key);\n}\n\n/**\n * Gets the number of acquired permits using the default semaphore\n * @param key - The unique identifier for the semaphore\n * @returns Promise resolving to the number of acquired permits\n */\nexport async function getAcquiredPermits(key: string): Promise<number> {\n  return defaultSemaphore.getAcquiredPermits(key);\n}\n"],"mappings":"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"}

package/dist/utils/utilities.js

@@ -1,7 +1,7 @@
 require('../colors-Cd4Oz-r-.js');
 require('../ActionRow-CmTHbo2t.js');
 require('../error-codes-C-ViHyu-.js');
-const require_commandkit = require('../commandkit-DYYj5_OH.js');
+const require_commandkit = require('../commandkit-CUFTPuzm.js');
 require('../common-CcfjYnPG.js');
 require('../common-vnMIelAE.js');
 require('../container-DCjIgp-B.js');

package/dist/utils/warn-unstable.js.map

@@ -1 +1 @@
-{"version":3,"file":"warn-unstable.js","names":[],"sources":["../../src/utils/warn-unstable.ts"],"sourcesContent":["const WARNED_KEYS = new Set<string>();\n\n/**\n * Emit a warning message to the console as a CommandKitWarning.\n * @param message - The warning message to emit.\n * @param code - The warning code (default is 'CommandKitWarning').\n */\nexport function emitWarning(message: string, code = 'CommandKitWarning') {\n  process.emitWarning(message, { code });\n}\n\n/**\n * Emit a warning for unstable features in CommandKit.\n * @param name - The name of the unstable feature.\n * @example warnUnstable('MyUnstableFeature');\n */\nexport function warnUnstable(name: string) {\n  if (WARNED_KEYS.has(name)) return;\n\n  WARNED_KEYS.add(name);\n\n  emitWarning(\n    `${name} is unstable and may change in future versions.`,\n    'CommandKitUnstableWarning',\n  );\n}\n"],"mappings":";;AAAA,MAAM,8BAAc,IAAI;;;;;;AAOxB,SAAgB,YAAY,SAAiB,OAAO,qBAAqB;AACvE,SAAQ,YAAY,SAAS,EAAE,KAAM,EAAC;AACxC;;;;;;AAOA,SAAgB,aAAa,MAAc;AACzC,KAAI,YAAY,IAAI,KAAK,CAAE;AAE3B,aAAY,IAAI,KAAK;AAErB,gBACK,KAAK,kDACR,4BACD;AACH"}
+{"version":3,"file":"warn-unstable.js","names":[],"sources":["../../src/utils/warn-unstable.ts"],"sourcesContent":["const WARNED_KEYS = new Set<string>();\n\n/**\n * Emit a warning message to the console as a CommandKitWarning.\n * @param message - The warning message to emit.\n * @param code - The warning code (default is 'CommandKitWarning').\n */\nexport function emitWarning(message: string, code = 'CommandKitWarning') {\n  process.emitWarning(message, { code });\n}\n\n/**\n * Emit a warning for unstable features in CommandKit.\n * @param name - The name of the unstable feature.\n * @example warnUnstable('MyUnstableFeature');\n */\nexport function warnUnstable(name: string) {\n  if (WARNED_KEYS.has(name)) return;\n\n  WARNED_KEYS.add(name);\n\n  emitWarning(\n    `${name} is unstable and may change in future versions.`,\n    'CommandKitUnstableWarning',\n  );\n}\n"],"mappings":";;AAAA,MAAM,8BAAc,IAAI;;;;;;AAOxB,SAAgB,YAAY,SAAiB,OAAO,qBAAqB;CACvE,QAAQ,YAAY,SAAS,EAAE,KAAM,EAAC;AACxC;;;;;;AAOA,SAAgB,aAAa,MAAc;AACzC,KAAI,YAAY,IAAI,KAAK,CAAE;CAE3B,YAAY,IAAI,KAAK;CAErB,YACE,GAAG,KAAK,+CAA+C,CAAC,EACxD,4BACD;AACH"}

package/dist/utils-n4MoGDDR.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils-n4MoGDDR.js","names":[],"sources":["../src/cli/utils.ts"],"sourcesContent":["import type { Ora } from 'ora';\n\nlet ora: typeof import('ora') | undefined;\n\n/**\n * @private\n * @internal\n */\nexport async function createSpinner(text: string): Promise<Ora> {\n  if (!ora) {\n    ora = await import('ora');\n  }\n\n  return (ora.default || ora)({\n    text,\n    color: 'cyan',\n  });\n}\n"],"mappings":";;AAEA,IAAI;;;;;AAMJ,eAAsB,cAAc,MAA4B;AAC9D,MAAK,IACH,OAAM,MAAM,OAAO;AAGrB,QAAO,CAAC,IAAI,WAAW,KAAK;EAC1B;EACA,OAAO;CACR,EAAC;AACJ"}
+{"version":3,"file":"utils-n4MoGDDR.js","names":[],"sources":["../src/cli/utils.ts"],"sourcesContent":["import type { Ora } from 'ora';\n\nlet ora: typeof import('ora') | undefined;\n\n/**\n * @private\n * @internal\n */\nexport async function createSpinner(text: string): Promise<Ora> {\n  if (!ora) {\n    ora = await import('ora');\n  }\n\n  return (ora.default || ora)({\n    text,\n    color: 'cyan',\n  });\n}\n"],"mappings":";;AAEA,IAAI;;;;;AAMJ,eAAsB,cAAc,MAA4B;AAC9D,KAAI,CAAC,KACH,MAAM,MAAM,OAAO;AAGrB,SAAQ,IAAI,WAAW,KAAK;EAC1B;EACA,OAAO;CACR,EAAC;AACJ"}

package/dist/{version-c0OD-7y_.js → version-DrMgT0Vo.js}

@@ -6,7 +6,7 @@
 /**
 * The current version of CommandKit.
 */
-const version = "1.0.0-dev.20250722021811";
+const version = "1.0.0-dev.20250723021937";
 
 //#endregion
 Object.defineProperty(exports, 'version', {
@@ -15,4 +15,4 @@ Object.defineProperty(exports, 'version', {
     return version;
   }
 });
-//# sourceMappingURL=version-c0OD-7y_.js.map
+//# sourceMappingURL=version-DrMgT0Vo.js.map

package/dist/{version-c0OD-7y_.js.map → version-DrMgT0Vo.js.map}

@@ -1 +1 @@
-{"version":3,"file":"version-c0OD-7y_.js","names":[],"sources":["../src/version.ts"],"sourcesContent":["/**\n * @private\n */\nfunction $version(): string {\n  'use macro';\n  return require('../package.json').version;\n}\n\n/**\n * The current version of CommandKit.\n */\nexport const version: string = $version();\n"],"mappings":";;;;;;;;AAWA,MAAa,UAA4B"}
+{"version":3,"file":"version-DrMgT0Vo.js","names":[],"sources":["../src/version.ts"],"sourcesContent":["/**\n * @private\n */\nfunction $version(): string {\n  'use macro';\n  return require('../package.json').version;\n}\n\n/**\n * The current version of CommandKit.\n */\nexport const version: string = $version();\n"],"mappings":";;;;;;;;AAWA,MAAa,UAA4B"}

package/dist/version.js

@@ -1,3 +1,3 @@
-const require_version = require('./version-c0OD-7y_.js');
+const require_version = require('./version-DrMgT0Vo.js');
 
 exports.version = require_version.version;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "commandkit",
   "description": "Beginner friendly command & event handler for Discord.js",
-  "version": "1.0.0-dev.20250722021811",
+  "version": "1.0.0-dev.20250723021937",
   "license": "MIT",
   "type": "commonjs",
   "main": "./dist/index.js",
@@ -167,7 +167,7 @@
     "picocolors": "^1.1.1",
     "rfdc": "^1.3.1",
     "rimraf": "^6.0.0",
-    "tsdown": "^0.12.9",
+    "tsdown": "^0.13.0",
     "use-macro": "^1.1.0"
   },
   "devDependencies": {
@@ -178,7 +178,7 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.3",
     "vitest": "^3.0.5",
-    "tsconfig": "0.0.0-dev.20250722021811"
+    "tsconfig": "0.0.0-dev.20250723021937"
   },
   "engines": {
     "node": ">=24"