commandkit 1.2.0-rc.11 → 1.2.0-rc.13

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.d.ts

@@ -1,2 +1,113 @@
-import { JsonSerialize, SimpleProxy, createProxy, debounce, defer, devOnly, findAppDirectory, getCurrentDirectory, getSourceDirectories } from "../utilities-DtdPlr4c.js";
-export { JsonSerialize, SimpleProxy, createProxy, debounce, defer, devOnly, findAppDirectory, getCurrentDirectory, getSourceDirectories };
+//#region src/utils/utilities.d.ts
+/**
+ * Returns the current working directory of the CommandKit application.
+ * This is typically the directory where the source code is located.
+ */
+declare function getCurrentDirectory(): string;
+/**
+ * Returns the possible source directories for the CommandKit application.
+ * This includes the `src`, `.commandkit`, and the distribution directory.
+ * @returns An array of possible source directories.
+ */
+declare function getSourceDirectories(): string[];
+/**
+ * Returns the path to the app directory.
+ * @returns The path to the app directory or `null` if not found.
+ */
+declare function findAppDirectory(): string | null;
+/**
+ * Debounces a function.
+ * @param fn The function to debounce.
+ * @param ms The debounce time in milliseconds.
+ * @returns The debounced function.
+ * @example
+ * const debouncedFn = debounce(() => {
+ *   console.log('Debounced function called');
+ * }, 300);
+ *
+ * debouncedFn(); // Will only execute after 300ms of inactivity
+ * debouncedFn(); // Will reset the timer
+ * debouncedFn(); // Will reset the timer again
+ */
+declare function debounce<R, F extends (...args: any[]) => R>(fn: F, ms: number): F;
+/**
+ * Defers the execution of a function.
+ * @param fn The function to defer.
+ * @param timeout The time in milliseconds to wait before executing the function. Defaults to 0.
+ * @example
+ * defer(() => {
+ *   console.log('This will run after a delay');
+ * });
+ *
+ * console.log('This will run immediately');
+ */
+declare function defer<T>(fn: () => T, timeout?: number): void;
+/**
+ * Serializes a value to JSON.
+ * @param value The value to serialize.
+ * @param defaultValue The default value to return if the value is not serializable.
+ * @returns The serialized value.
+ */
+declare function JsonSerialize<R = any>(value: any, defaultValue?: R): R;
+/**
+ * Creates a function from the given function that runs only in development mode.
+ * @param fn The function to run in development mode.
+ * @returns The function that runs only in development mode.
+ * @example
+ * ```ts
+ * const devOnlyFn = devOnly(() => {
+ *   console.log('This function runs only in development mode');
+ * });
+ * devOnlyFn(); // This will log the message only in development mode
+ * ```
+ */
+declare function devOnly<T extends (...args: any[]) => any>(fn: T): T;
+/**
+ * Creates a function from the given function that runs only in build mode.
+ * @param fn The function to run in build mode.
+ * @returns The function that runs only in build mode.
+ * @example
+ * ```ts
+ * const buildOnlyFn = buildOnly(() => {
+ *   console.log('This function runs only in build mode');
+ * });
+ * buildOnlyFn(); // This will log the message only in build mode
+ * ```
+ */
+declare function buildOnly<T extends (...args: any[]) => any>(fn: T): T;
+/**
+ * Creates a function from the given function that runs only outside of build mode.
+ * @param fn The function to run outside of build mode.
+ * @returns The function that runs only outside of build mode.
+ * @example
+ * ```ts
+ * const noBuildOnlyFn = noBuildOnly(() => {
+ *   console.log('This function runs only outside of build mode');
+ * });
+ * noBuildOnlyFn(); // This will log the message only outside of build mode
+ * ```
+ */
+declare function noBuildOnly<T extends (...args: any[]) => any>(fn: T): T;
+/**
+ * Represents a simple proxy object that mirrors a target object.
+ */
+interface SimpleProxy<T extends object> {
+  /**
+       * The proxied object that mirrors the target.
+       */
+  proxy: T;
+  /**
+       * Sets a new target object for the proxy.
+       * @param newTarget The new target object to set.
+       */
+  setTarget(newTarget: T): void;
+}
+/**
+ * Creates a simple proxy object that mirrors the target object.
+ * @param target The target object to proxy.
+ * @returns The proxied object.
+ */
+declare function createProxy<T extends object>(target: T): SimpleProxy<T>;
+//#endregion
+export { JsonSerialize, SimpleProxy, buildOnly, createProxy, debounce, defer, devOnly, findAppDirectory, getCurrentDirectory, getSourceDirectories, noBuildOnly };
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utils/utilities.js

@@ -1,45 +1,35 @@
-require('../colors-DL3ucTiT.js');
-require('../ActionRow-CbdGFWMT.js');
-require('../error-codes-Ds0bnPvT.js');
-const require_commandkit = require('../commandkit-ZoBBh0Q_.js');
-require('../common-CcfjYnPG.js');
-require('../common-vnMIelAE.js');
-require('../container-C6GtfAPW.js');
-require('../file-DVOELoNv.js');
-require('../media-gallery-zDtJ3kxb.js');
-require('../section-DlvrDoJK.js');
-require('../separator-DL6QH5H1.js');
-require('../text-display-DbMumig_.js');
-require('../v2-DofkPKHs.js');
-require('../element-Bak9llw_.js');
-require('../types-CUZOquUl.js');
-require('../EventInterceptor-CQEXyUTp.js');
-require('../constants-B5_Ta7PR.js');
-require('../PluginCommon-Cvl5yYM_.js');
-require('../CompilerPlugin-M8r3yNAl.js');
-require('../RuntimePlugin-BUecuBIU.js');
-require('../types-q0Nm882H.js');
-require('../resolve-file-url-ChIyw-Vf.js');
-require('../runtime-DB9CiPfe.js');
-require('../utils-KsNof0Xz.js');
-require('../types-package-BWArjyBF.js');
-require('../constants-BOOGN85p.js');
-require('../EventWorkerContext-Dq29tieI.js');
-require('../signals-ChFMD7mB.js');
-require('../helpers-Dl8wW6aO.js');
-require('../MessageCommandParser-Dl0xxtdr.js');
-require('../CommandsRouter-Dmzw-ikm.js');
-require('../EventsRouter-3Gygh-km.js');
-require('../router-Dn35v30f.js');
-require('../common-CrqwC-sx.js');
-require('../CommandKitEventsChannel-BtRzr3Tz.js');
-require('../store-CM6pWVZh.js');
+require('../colors-Csc0X4QJ.js');
+require('../ActionRow-CSN_UKmM.js');
+const require_commandkit = require('../commandkit-SIjTLD2R.js');
+require('../container-DCPljKVH.js');
+require('../file-Ca1kpEtE.js');
+require('../media-gallery-u3gjX7yD.js');
+require('../section-BC8LF-B2.js');
+require('../separator-BUTiW7uz.js');
+require('../text-display-DANahMN3.js');
+require('../label-B6vXvwLM.js');
+require('../poll-CFe8yvoJ.js');
+require('../display-WDb9wMCv.js');
+require('../constants-CxkFFZ7p.js');
+require('../types-package-CsTNfvv2.js');
+require('../constants-Cw8VjCVz.js');
+require('../EventWorkerContext-Dfhgv329.js');
+require('../signals-B8z1wJ6W.js');
+require('../helpers-Btx1FSZx.js');
+require('../MessageCommandParser-Bs9fimmd.js');
+require('../CommandsRouter-C_HLsrGX.js');
+require('../EventsRouter-DZYIha6m.js');
+require('../router-BvamdzoF.js');
+require('../common-DSRs_mfw.js');
+require('../store-D8r_hryO.js');
 
 exports.JsonSerialize = require_commandkit.JsonSerialize;
+exports.buildOnly = require_commandkit.buildOnly;
 exports.createProxy = require_commandkit.createProxy;
 exports.debounce = require_commandkit.debounce;
 exports.defer = require_commandkit.defer;
 exports.devOnly = require_commandkit.devOnly;
 exports.findAppDirectory = require_commandkit.findAppDirectory;
 exports.getCurrentDirectory = require_commandkit.getCurrentDirectory;
-exports.getSourceDirectories = require_commandkit.getSourceDirectories;
+exports.getSourceDirectories = require_commandkit.getSourceDirectories;
+exports.noBuildOnly = require_commandkit.noBuildOnly;

package/dist/utils/{warn-unstable.d.ts → warning.d.ts}

@@ -1,4 +1,4 @@
-//#region src/utils/warn-unstable.d.ts
+//#region src/utils/warning.d.ts
 /**
  * Emit a warning message to the console as a CommandKitWarning.
  * @param message - The warning message to emit.
@@ -11,6 +11,15 @@ declare function emitWarning(message: string, code?: string): void;
  * @example warnUnstable('MyUnstableFeature');
  */
 declare function warnUnstable(name: string): void;
+declare function warnDeprecated({
+  what,
+  message,
+  where
+}: {
+  what: string;
+  where?: string;
+  message?: string;
+}): void;
 //#endregion
-export { emitWarning, warnUnstable };
-//# sourceMappingURL=warn-unstable.d.ts.map
+export { emitWarning, warnDeprecated, warnUnstable };
+//# sourceMappingURL=warning.d.ts.map

package/dist/utils/warning.js

@@ -0,0 +1,5 @@
+const require_warning = require('../warning-CszH8HeS.js');
+
+exports.emitWarning = require_warning.emitWarning;
+exports.warnDeprecated = require_warning.warnDeprecated;
+exports.warnUnstable = require_warning.warnUnstable;

package/dist/{utils-KsNof0Xz.js → utils-Br3eenD1.js}

@@ -31,4 +31,4 @@ Object.defineProperty(exports, 'mergeDeep', {
     return mergeDeep;
   }
 });
-//# sourceMappingURL=utils-KsNof0Xz.js.map
+//# sourceMappingURL=utils-Br3eenD1.js.map

package/dist/{utils-KsNof0Xz.js.map → utils-Br3eenD1.js.map}

@@ -1 +1 @@
-{"version":3,"file":"utils-KsNof0Xz.js","names":[],"sources":["../src/config/utils.ts"],"sourcesContent":["import { CommandKitConfig } from './types';\n\n/**\n * @private\n */\nexport type DeepRequired<T, OptionalKeys extends keyof T = never> = {\n  [P in keyof T]-?: P extends OptionalKeys ? Partial<T[P]> : DeepRequired<T[P]>;\n};\n\n/**\n * @private\n */\nexport type DeepPartial<T> = {\n  [P in keyof T]?: DeepPartial<T[P]>;\n};\n\n/**\n * @private\n * @example\n * ```ts\n * const target = { a: 1, b: { c: 2 } };\n * const source = { b: { d: 3 } };\n * const result = mergeDeep(target, source);\n * // result = { a: 1, b: { c: 2, d: 3 } }\n * ```\n */\nexport const mergeDeep = <T extends Record<string, any>>(\n  target: T,\n  source?: T,\n  tracker = new WeakMap<object, boolean>(),\n): T => {\n  if (!source) return target;\n  const isObject = (obj: unknown) =>\n    obj && typeof obj === 'object' && !Array.isArray(obj);\n\n  // Prevent infinite recursion\n  if (tracker.has(target)) {\n    return target;\n  }\n\n  // Mark the target as visited\n  tracker.set(target, true);\n\n  const output: T = { ...target };\n  if (isObject(target) && isObject(source)) {\n    Object.keys(source).forEach((key) => {\n      if (isObject(source[key])) {\n        if (!(key in target)) {\n          Object.assign(output, { [key]: source[key] });\n        } else {\n          output[key as keyof T] = mergeDeep(target[key], source[key], tracker);\n        }\n      } else {\n        Object.assign(output, { [key]: source[key] });\n      }\n    });\n  }\n\n  return output as T;\n};\n\nexport type ResolvedCommandKitConfig = DeepRequired<\n  CommandKitConfig,\n  'compilerOptions'\n>;\n"],"mappings":";;;;;;;;;;;;AA0BA,MAAa,aACb,QACA,QACA,0BAAU,IAAI,SAA0B,KACjC;AACL,KAAI,CAAC,OAAQ,QAAO;CACpB,MAAM,YAAY,QAClB,OAAO,OAAO,QAAQ,YAAY,CAAC,MAAM,QAAQ,IAAI;AAGrD,KAAI,QAAQ,IAAI,OAAO,CACrB,QAAO;AAIT,SAAQ,IAAI,QAAQ,KAAK;CAEzB,MAAM,SAAY,EAAE,GAAG,QAAQ;AAC/B,KAAI,SAAS,OAAO,IAAI,SAAS,OAAO,CACtC,QAAO,KAAK,OAAO,CAAC,SAAS,QAAQ;AACnC,MAAI,SAAS,OAAO,KAAK,CACvB,KAAI,EAAE,OAAO,QACX,QAAO,OAAO,QAAQ,GAAG,MAAM,OAAO,MAAM,CAAC;MAE7C,QAAO,OAAkB,UAAU,OAAO,MAAM,OAAO,MAAM,QAAQ;MAGvE,QAAO,OAAO,QAAQ,GAAG,MAAM,OAAO,MAAM,CAAC;GAE/C;AAGJ,QAAO"}
+{"version":3,"file":"utils-Br3eenD1.js","names":[],"sources":["../src/config/utils.ts"],"sourcesContent":["import { CommandKitConfig } from './types';\n\n/**\n * @private\n */\nexport type DeepRequired<T, OptionalKeys extends keyof T = never> = {\n  [P in keyof T]-?: P extends OptionalKeys ? Partial<T[P]> : DeepRequired<T[P]>;\n};\n\n/**\n * @private\n */\nexport type DeepPartial<T> = {\n  [P in keyof T]?: DeepPartial<T[P]>;\n};\n\n/**\n * @private\n * @example\n * ```ts\n * const target = { a: 1, b: { c: 2 } };\n * const source = { b: { d: 3 } };\n * const result = mergeDeep(target, source);\n * // result = { a: 1, b: { c: 2, d: 3 } }\n * ```\n */\nexport const mergeDeep = <T extends Record<string, any>>(\n  target: T,\n  source?: T,\n  tracker = new WeakMap<object, boolean>(),\n): T => {\n  if (!source) return target;\n  const isObject = (obj: unknown) =>\n    obj && typeof obj === 'object' && !Array.isArray(obj);\n\n  // Prevent infinite recursion\n  if (tracker.has(target)) {\n    return target;\n  }\n\n  // Mark the target as visited\n  tracker.set(target, true);\n\n  const output: T = { ...target };\n  if (isObject(target) && isObject(source)) {\n    Object.keys(source).forEach((key) => {\n      if (isObject(source[key])) {\n        if (!(key in target)) {\n          Object.assign(output, { [key]: source[key] });\n        } else {\n          output[key as keyof T] = mergeDeep(target[key], source[key], tracker);\n        }\n      } else {\n        Object.assign(output, { [key]: source[key] });\n      }\n    });\n  }\n\n  return output as T;\n};\n\nexport type ResolvedCommandKitConfig = DeepRequired<\n  CommandKitConfig,\n  'compilerOptions'\n>;\n"],"mappings":";;;;;;;;;;;;AA0BA,MAAa,aACb,QACA,QACA,0BAAU,IAAE,SAA4B,KACjC;AACL,KAAI,CAAC,OAAQ,QAAO;CACpB,MAAM,YAAY,QAClB,OAAO,OAAE,QAAa,YAAY,CAAC,MAAE,QAAM,IAAQ;AAGnD,KAAI,QAAQ,IAAI,OAAO,CACrB,QAAO;AAIT,SAAQ,IAAI,QAAQ,KAAK;CAEzB,MAAM,SAAY,EAAE,GAAG,QAAQ;AAC/B,KAAI,SAAS,OAAO,IAAI,SAAS,OAAO,CACtC,QAAO,KAAK,OAAO,CAAC,SAAS,QAAQ;AACnC,MAAI,SAAS,OAAO,KAAK,CACvB,KAAI,EAAE,OAAO,QACX,QAAO,OAAO,QAAQ,GAAG,MAAM,OAAO,MAAM,CAAC;MAE7C,QAAO,OAAkB,UAAU,OAAO,MAAM,OAAO,MAAM,QAAQ;MAGvE,QAAO,OAAO,QAAQ,GAAG,MAAM,OAAO,MAAM,CAAC;GAE/C;AAGJ,QAAO"}

package/dist/version.d.ts

@@ -1,2 +1,8 @@
-import { version } from "./version-CtJtBJXI.js";
-export { version };
+//#region src/version.d.ts
+/**
+ * The current version of CommandKit.
+ */
+declare const version: string;
+//#endregion
+export { version };
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,13 @@
-const require_version = require('./version--Q1nmlBz.js');
 
-exports.version = require_version.version;
+//#region src/version.ts
+/**
+* @private
+*/
+/**
+* The current version of CommandKit.
+*/
+const version = "1.2.0-rc.13";
+
+//#endregion
+exports.version = version;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.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/warning-CszH8HeS.js

@@ -0,0 +1,53 @@
+
+//#region src/utils/warning.ts
+const WARNED_KEYS = /* @__PURE__ */ new Set();
+const DEPRECATED_KEYS = /* @__PURE__ */ new Set();
+/**
+* Emit a warning message to the console as a CommandKitWarning.
+* @param message - The warning message to emit.
+* @param code - The warning code (default is 'CommandKitWarning').
+*/
+function emitWarning(message, code = "CommandKitWarning") {
+	process.emitWarning(message, { code });
+}
+/**
+* Emit a warning for unstable features in CommandKit.
+* @param name - The name of the unstable feature.
+* @example warnUnstable('MyUnstableFeature');
+*/
+function warnUnstable(name) {
+	if (WARNED_KEYS.has(name)) return;
+	WARNED_KEYS.add(name);
+	emitWarning(`${name} is unstable and may change in future versions.`, "CommandKitUnstableWarning");
+}
+function warnDeprecated({ what, message, where }) {
+	const name = `${what}:${where}`;
+	if (DEPRECATED_KEYS.has(name)) return;
+	DEPRECATED_KEYS.add(name);
+	emitWarning([
+		`${what} is deprecated`,
+		where ? `in ${where}` : "",
+		message || "and may be removed in future versions."
+	].filter(Boolean).join(" "), "CommandKitDeprecatedWarning");
+}
+
+//#endregion
+Object.defineProperty(exports, 'emitWarning', {
+  enumerable: true,
+  get: function () {
+    return emitWarning;
+  }
+});
+Object.defineProperty(exports, 'warnDeprecated', {
+  enumerable: true,
+  get: function () {
+    return warnDeprecated;
+  }
+});
+Object.defineProperty(exports, 'warnUnstable', {
+  enumerable: true,
+  get: function () {
+    return warnUnstable;
+  }
+});
+//# sourceMappingURL=warning-CszH8HeS.js.map

package/dist/warning-CszH8HeS.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warning-CszH8HeS.js","names":[],"sources":["../src/utils/warning.ts"],"sourcesContent":["const WARNED_KEYS = new Set<string>();\nconst DEPRECATED_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}\nexport function warnDeprecated({\n  what,\n  message,\n  where,\n}: {\n  what: string;\n  where?: string;\n  message?: string;\n}) {\n  const name = `${what}:${where}`;\n\n  if (DEPRECATED_KEYS.has(name)) return;\n\n  DEPRECATED_KEYS.add(name);\n\n  emitWarning(\n    [\n      `${what} is deprecated`,\n      where ? `in ${where}` : '',\n      message || 'and may be removed in future versions.',\n    ]\n      .filter(Boolean)\n      .join(' '),\n    'CommandKitDeprecatedWarning',\n  );\n}\n"],"mappings":";;AAAA,MAAM,8BAAc,IAAI,KAAa;AACrC,MAAM,kCAAkB,IAAI,KAAa;;;;;;AAOzC,SAAgB,YAAY,SAAiB,OAAO,qBAAqB;AACvE,SAAQ,YAAY,SAAS,EAAE,MAAM,CAAC;;;;;;;AAQxC,SAAgB,aAAa,MAAc;AACzC,KAAI,YAAY,IAAI,KAAK,CAAE;AAE3B,aAAY,IAAI,KAAK;AAErB,aACE,GAAG,KAAK,kDACR,4BACD;;AAEH,SAAgB,eAAe,EAC7B,MACA,SACA,SAKC;CACD,MAAM,OAAO,GAAG,KAAK,GAAG;AAExB,KAAI,gBAAgB,IAAI,KAAK,CAAE;AAE/B,iBAAgB,IAAI,KAAK;AAEzB,aACE;EACA,GAAG,KAAE;EACL,QAAQ,MAAM,UAAU;EACxB,WAAW;EAAyC,CAEpD,OAAG,QAAO,CACV,KAAG,IAAM,EACT,8BACD"}

package/hooks.cjs

@@ -9,11 +9,18 @@ const {
 } = require('./dist/app/events/EventWorkerContext.js');
 
 function useAnyEnvironment() {
-  const commandCtx = getContext();
-  if (commandCtx) return commandCtx;
+  try {
+    const commandCtx = getContext();
+    if (commandCtx) return commandCtx;
+  } catch {}
+
+  try {
+    const eventWorkerCtx = getEventWorkerContext();
+    if (eventWorkerCtx) return eventWorkerCtx;
+  } catch {}
 
-  const eventWorkerCtx = getEventWorkerContext();
-  if (eventWorkerCtx) return eventWorkerCtx;
+  const maybeCommandKit = getCommandKit();
+  if (maybeCommandKit) return { commandkit: maybeCommandKit };
 
   throw new Error(
     'No environment found. This hook must be used within a CommandKit environment.',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "commandkit",
   "description": "Beginner friendly command & event handler for Discord.js",
-  "version": "1.2.0-rc.11",
+  "version": "1.2.0-rc.13",
   "license": "GPL-3.0-only",
   "type": "commonjs",
   "main": "./dist/index.js",
@@ -46,7 +46,9 @@
     "./mutex.cjs",
     "./mutex.d.ts",
     "./kv.cjs",
-    "./kv.d.ts"
+    "./kv.d.ts",
+    "./cli.cjs",
+    "./cli.d.ts"
   ],
   "exports": {
     ".": {
@@ -143,11 +145,16 @@
       "require": "./semaphore.cjs",
       "import": "./semaphore.cjs",
       "types": "./semaphore.d.ts"
+    },
+    "./cli": {
+      "require": "./cli.cjs",
+      "import": "./cli.cjs",
+      "types": "./cli.d.ts"
     }
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/underctrl-io/commandkit",
+    "url": "https://github.com/neplextech/commandkit",
     "directory": "packages/commandkit"
   },
   "homepage": "https://commandkit.dev",
@@ -169,18 +176,18 @@
     "picocolors": "^1.1.1",
     "rfdc": "^1.3.1",
     "rimraf": "^6.0.0",
-    "tsdown": "^0.15.2",
+    "tsdown": "^0.20.0-beta.3",
     "use-macro": "^1.1.0"
   },
   "devDependencies": {
     "@types/ms": "^2.0.0",
     "@types/node": "^22.10.2",
     "@types/yargs": "^17.0.32",
-    "discord.js": "^14.22.1",
+    "discord.js": "^14.24.0",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.3",
+    "typescript": "^5.9.3",
     "vitest": "^3.0.5",
-    "tsconfig": "0.0.0-rc.11"
+    "tsconfig": "0.0.0-rc.13"
   },
   "engines": {
     "node": ">=24"

package/dist/ActionRow-CbdGFWMT.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ActionRow-CbdGFWMT.js","names":[],"sources":["../src/components/v1/action-row/ActionRow.ts"],"sourcesContent":["import { ActionRowBuilder } from 'discord.js';\nimport { AnyCommandKitElement, CommandKitElement } from '../../common/element';\n\n/**\n * The properties for the action row component.\n */\nexport interface ActionRowProps {\n  children?: AnyCommandKitElement[] | AnyCommandKitElement;\n}\n\n/**\n * The action row component.\n * @param props The action row properties.\n * @returns The commandkit element.\n * @example <ActionRow><Button label=\"Click me\" style={ButtonStyle.Primary} customId=\"click_me\" /></ActionRow>\n */\nexport function ActionRow(\n  props: ActionRowProps,\n): CommandKitElement<'action-row'> {\n  const row = new ActionRowBuilder();\n\n  if (Array.isArray(props.children)) {\n    // @ts-ignore\n    row.setComponents(...props.children);\n  } else if (props.children) {\n    // @ts-ignore\n    row.setComponents(props.children);\n  }\n\n  return row;\n}\n"],"mappings":";;;;;;;;;;;AAgBA,SAAgB,UAChB,OACkC;CAChC,MAAM,MAAM,IAAI,6BAAkB;AAElC,KAAI,MAAM,QAAQ,MAAM,SAAS,CAE/B,KAAI,cAAc,GAAG,MAAM,SAAS;UAC3B,MAAM,SAEf,KAAI,cAAc,MAAM,SAAS;AAGnC,QAAO"}

package/dist/ChannelSelectMenuKit-BrXvBYNH.d.ts

@@ -1,67 +0,0 @@
-import { EventInterceptorErrorHandler } from "./EventInterceptor-x-R2qshQ.js";
-import { CommandKitSelectMenuBuilderInteractionCollectorDispatch, CommandKitSelectMenuBuilderInteractionCollectorDispatchContextData, CommandKitSelectMenuBuilderOnEnd, OnSelectMenuKitSubmit, SelectMenuKitPredicate } from "./common-DOCvOVC4.js";
-import { ChannelSelectMenuBuilder, ChannelSelectMenuInteraction } from "discord.js";
-
-//#region src/components/v1/select-menu/ChannelSelectMenuKit.d.ts
-
-/**
- * Type for the handler function that is called when the channel select menu is submitted.
- */
-type OnChannelSelectMenuKitSubmit = OnSelectMenuKitSubmit<ChannelSelectMenuInteraction, ChannelSelectMenuKit>;
-/**
- * Type for the predicate function that filters channel select menu interactions.
- * It receives a ChannelSelectMenuInteraction and returns a boolean or a Promise that resolves to a boolean.
- */
-type ChannelSelectMenuKitPredicate = SelectMenuKitPredicate<ChannelSelectMenuInteraction>;
-/**
- * A builder for creating channel select menus with additional features like interaction collectors and event handling.
- * This class extends the ChannelSelectMenuBuilder from discord.js and adds methods for handling interactions.
- * It allows you to set a handler for when the channel select menu is submitted, filter interactions, and handle the end of the interaction collector.
- */
-declare class ChannelSelectMenuKit extends ChannelSelectMenuBuilder {
-  #private;
-  /**
-   * Sets the handler to run when the modal is submitted.
-   * @param handler - The handler to run when the modal is submitted.
-   * @param data - The context data for the interaction collector.
-   * @returns This instance of the modal builder.
-   * @example
-   * ```ts
-   * const modal = new ChannelSelectMenuKit()
-   *  .setTitle('My Modal')
-   *  .setCustomId('my-modal')
-   *  .filter((interaction) => interaction.Channel.id === '1234567890')
-   *  .onSelect(async (interaction) => {
-   *     await interaction.reply('You submitted the modal!');
-   *   })
-   *   .addComponents(actionRow1, actionRow2);
-   * ```
-   */
-  onSelect(handler: CommandKitSelectMenuBuilderInteractionCollectorDispatch<ChannelSelectMenuInteraction, ChannelSelectMenuKit>, data?: CommandKitSelectMenuBuilderInteractionCollectorDispatchContextData): this;
-  /**
-   * Sets the handler to run when the interaction collector ends.
-   * @param handler - The handler to run when the interaction collector ends.
-   * @returns This instance of the modal builder.
-   */
-  onEnd(handler: CommandKitSelectMenuBuilderOnEnd): this;
-  /**
-   * Sets the handler to run when the interaction collector ends.
-   * @param handler - The handler to run when the interaction collector ends.
-   * @returns This instance of the modal builder.
-   */
-  onError(handler: EventInterceptorErrorHandler): this;
-  /**
-   * Sets a filter for the interaction collector.
-   * @param predicate - The filter to use for the interaction collector.
-   * @returns This instance of the modal builder.
-   */
-  filter(predicate: SelectMenuKitPredicate<ChannelSelectMenuInteraction>): this;
-  private get customId();
-  /**
-   * Cleans up the interaction collector and removes the handler.
-   */
-  dispose(): this;
-}
-//#endregion
-export { ChannelSelectMenuKit, ChannelSelectMenuKitPredicate, OnChannelSelectMenuKitSubmit };
-//# sourceMappingURL=ChannelSelectMenuKit-BrXvBYNH.d.ts.map

package/dist/DefaultLogger-XCOl5nLd.d.ts

@@ -1,67 +0,0 @@
-import { ILogger } from "./ILogger-BW8GM-YZ.js";
-
-//#region src/logger/DefaultLogger.d.ts
-
-/**
- * Default logger implementation that logs messages to the console.
- * It formats the log messages with timestamps, log levels, and context information.
- */
-declare class DefaultLogger implements ILogger {
-  stdout: NodeJS.WriteStream & {
-    fd: 1;
-  };
-  stderr: NodeJS.WriteStream & {
-    fd: 2;
-  };
-  private logger;
-  /**
-   * Creates a new instance of DefaultLogger.
-   * @param stdout The output stream for standard messages (default: process.stdout).
-   * @param stderr The output stream for error messages (default: process.stderr).
-   */
-  constructor(stdout?: NodeJS.WriteStream & {
-    fd: 1;
-  }, stderr?: NodeJS.WriteStream & {
-    fd: 2;
-  });
-  private _formatTime;
-  private _getContext;
-  private _getLevelLabel;
-  private _getPrefix;
-  private _log;
-  private _logTemplate;
-  /**
-   * Logs a debug message.
-   * @param message The message to log.
-   */
-  debug(message: any): void;
-  debug(strings: TemplateStringsArray, ...values: any[]): void;
-  /**
-   * Logs an error message.
-   * @param message The error message to log.
-   */
-  error(message: any): void;
-  error(strings: TemplateStringsArray, ...values: any[]): void;
-  /**
-   * Logs a default message.
-   * @param message The message to log.
-   */
-  log(message: any): void;
-  log(strings: TemplateStringsArray, ...values: any[]): void;
-  /**
-   * Logs an info message.
-   * @param message The informational message to log.
-   */
-  info(message: any): void;
-  info(strings: TemplateStringsArray, ...values: any[]): void;
-  /**
-   * Logs a warning message.
-   * @param message The warning message to log.
-   */
-  warn(message: any): void;
-  warn(strings: TemplateStringsArray, ...values: any[]): void;
-  private _isTemplateStringsArray;
-}
-//#endregion
-export { DefaultLogger };
-//# sourceMappingURL=DefaultLogger-XCOl5nLd.d.ts.map

package/dist/EventWorkerContext-Dq29tieI.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"EventWorkerContext-Dq29tieI.js","names":[],"sources":["../src/app/events/EventWorkerContext.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport { ParsedEvent } from '../router';\nimport { CommandKit } from '../../commandkit';\n\n/**\n * Context object containing information about the currently executing event.\n */\nexport interface EventWorkerContext {\n  event: string;\n  namespace: string | null;\n  data: ParsedEvent;\n  commandkit: CommandKit;\n  arguments: any[];\n  variables: Map<string, any>;\n}\n\n/**\n * @private\n * @internal\n */\nconst kEventWorker = Symbol('commandkitEventWorker');\n\n/**\n * Async local storage for event worker context.\n */\nexport const eventWorkerContext = new AsyncLocalStorage<EventWorkerContext>();\n\n/**\n * Runs a callback within an event worker context.\n * @param context - The event worker context\n * @param callback - The callback to execute\n * @returns The result of the callback\n */\nexport function runInEventWorkerContext<T>(\n  context: EventWorkerContext,\n  callback: () => T,\n): T {\n  Reflect.set(context, kEventWorker, true);\n\n  return eventWorkerContext.run(context, callback);\n}\n\n/**\n * Gets the current event worker context.\n * @returns The current event worker context\n * @throws Error if no context is found\n */\nexport function getEventWorkerContext(): EventWorkerContext {\n  const context = eventWorkerContext.getStore();\n\n  if (!context) {\n    throw new Error('Event worker context not found');\n  }\n\n  return context;\n}\n\n/**\n * Type guard to check if an object is an event worker context.\n * @param worker - The object to check\n * @returns True if the object is an event worker context\n */\nexport function isEventWorkerContext(\n  worker: any,\n): worker is EventWorkerContext {\n  return worker && Reflect.get(worker, kEventWorker) === true;\n}\n"],"mappings":";;;;;;;;;AAoBA,MAAM,eAAe,OAAO,wBAAwB;;;;AAKpD,MAAa,qBAAqB,IAAI,oCAAuC;;;;;;;AAQ7E,SAAgB,wBAChB,SACA,UACI;AACF,SAAQ,IAAI,SAAS,cAAc,KAAK;AAExC,QAAO,mBAAmB,IAAI,SAAS,SAAS;;;;;;;AAQlD,SAAgB,wBAA4C;CAC1D,MAAM,UAAU,mBAAmB,UAAU;AAE7C,KAAI,CAAC,QACH,OAAM,IAAI,MAAM,iCAAiC;AAGnD,QAAO;;;;;;;AAQT,SAAgB,qBAChB,QAC+B;AAC7B,QAAO,UAAU,QAAQ,IAAI,QAAQ,aAAa,KAAK"}