commandkit 1.0.0-dev.20250622124751 → 1.0.0-dev.20250622135945

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

@@ -0,0 +1,227 @@
+//#region src/utils/useful-stuff/semaphore.d.ts
+/**
+ * Async semaphore implementation for controlling access to a limited pool of resources.
+ * Allows a specified number of concurrent operations while blocking additional requests.
+ */
+/**
+ * Interface for semaphore storage implementations.
+ * Provides methods to store, retrieve, and manage semaphore permit data.
+ */
+interface SemaphoreStorage {
+  /**
+   * Attempts to acquire a permit for a given key
+   * @param key - The unique identifier for the semaphore
+   * @param timeout - Optional timeout in milliseconds for permit acquisition
+   * @param signal - Optional AbortSignal for cancelling the acquisition
+   * @returns Promise resolving to true if permit was acquired, false if timeout or no permits available
+   */
+  acquire(key: string, timeout?: number, signal?: AbortSignal): Promise<boolean>;
+  /**
+   * Releases a permit for a given key
+   * @param key - The unique identifier for the semaphore
+   * @returns Promise that resolves when the permit is released
+   */
+  release(key: string): Promise<void>;
+  /**
+   * Gets the number of available permits for a given key
+   * @param key - The unique identifier for the semaphore
+   * @returns Promise resolving to the number of available permits
+   */
+  getAvailablePermits(key: string): Promise<number>;
+  /**
+   * Gets the total number of permits for a given key
+   * @param key - The unique identifier for the semaphore
+   * @returns Promise resolving to the total number of permits
+   */
+  getTotalPermits(key: string): Promise<number>;
+}
+/**
+ * Configuration options for semaphore
+ */
+interface SemaphoreOptions {
+  /** Maximum number of concurrent permits allowed. Default: 1 */
+  permits?: number;
+  /** Default timeout in milliseconds for permit acquisition. Default: 30000 */
+  timeout?: number;
+  /** Storage implementation for persisting semaphore data. Default: {@link MemorySemaphoreStorage} */
+  storage?: SemaphoreStorage;
+}
+/**
+ * In-memory storage implementation for semaphore permits.
+ * Suitable for single-instance applications.
+ */
+declare class MemorySemaphoreStorage implements SemaphoreStorage {
+  private readonly semaphores;
+  /**
+   * Attempts to acquire a permit for a given key
+   * @param key - The unique identifier for the semaphore
+   * @param timeout - Optional timeout in milliseconds for permit acquisition
+   * @param signal - Optional AbortSignal for cancelling the acquisition
+   * @returns Promise resolving to true if permit was acquired, false if timeout or no permits available
+   */
+  acquire(key: string, timeout?: number, signal?: AbortSignal): Promise<boolean>;
+  /**
+   * Releases a permit for a given key
+   * @param key - The unique identifier for the semaphore
+   * @returns Promise that resolves when the permit is released
+   */
+  release(key: string): Promise<void>;
+  /**
+   * Gets the number of available permits for a given key
+   * @param key - The unique identifier for the semaphore
+   * @returns Promise resolving to the number of available permits
+   */
+  getAvailablePermits(key: string): Promise<number>;
+  /**
+   * Gets the total number of permits for a given key
+   * @param key - The unique identifier for the semaphore
+   * @returns Promise resolving to the total number of permits
+   */
+  getTotalPermits(key: string): Promise<number>;
+  /**
+   * Initializes a semaphore with the specified number of permits
+   * @param key - The unique identifier for the semaphore
+   * @param permits - The total number of permits to allocate
+   */
+  initialize(key: string, permits: number): void;
+  private delay;
+}
+/**
+ * Async semaphore implementation that controls access to a limited pool of resources.
+ * Allows a specified number of concurrent operations while blocking additional requests.
+ */
+declare class Semaphore {
+  private storage;
+  private readonly defaultPermits;
+  private readonly defaultTimeout;
+  /**
+   * Creates a new semaphore instance
+   * @param options - Configuration options for the semaphore
+   */
+  constructor(options?: SemaphoreOptions);
+  /**
+   * Sets the storage implementation for the semaphore
+   * @param storage - The storage implementation to use
+   */
+  setStorage(storage: SemaphoreStorage): void;
+  /**
+   * Gets the storage implementation for the semaphore
+   * @returns The storage implementation
+   */
+  getStorage(): SemaphoreStorage;
+  /**
+   * Acquires a permit for the given key
+   * @param key - The unique identifier for the semaphore
+   * @param timeout - Optional timeout in milliseconds for permit acquisition
+   * @param signal - Optional AbortSignal for cancelling the acquisition
+   * @returns Promise resolving to true if permit was acquired, false if timeout
+   */
+  acquire(key: string, timeout?: number, signal?: AbortSignal): Promise<boolean>;
+  /**
+   * Releases a permit for the given key
+   * @param key - The unique identifier for the semaphore
+   * @returns Promise that resolves when the permit is released
+   */
+  release(key: string): Promise<void>;
+  /**
+   * Gets the number of available permits for the given key
+   * @param key - The unique identifier for the semaphore
+   * @returns Promise resolving to the number of available permits
+   */
+  getAvailablePermits(key: string): Promise<number>;
+  /**
+   * Gets the total number of permits for the given key
+   * @param key - The unique identifier for the semaphore
+   * @returns Promise resolving to the total number of permits
+   */
+  getTotalPermits(key: string): Promise<number>;
+  /**
+   * Gets the number of acquired permits for the given key
+   * @param key - The unique identifier for the semaphore
+   * @returns Promise resolving to the number of acquired permits
+   */
+  getAcquiredPermits(key: string): Promise<number>;
+  /**
+   * Executes a function with a permit from the semaphore
+   * @param key - The unique identifier for the semaphore
+   * @param fn - The function to execute with a permit
+   * @param timeout - Optional timeout in milliseconds for permit acquisition
+   * @param signal - Optional AbortSignal for cancelling the permit acquisition
+   * @returns Promise resolving to the result of the function execution
+   * @throws Error if permit acquisition fails or function execution fails
+   */
+  withPermit<T>(key: string, fn: () => Promise<T> | T, timeout?: number, signal?: AbortSignal): Promise<T>;
+  /**
+   * Gets the current configuration of the semaphore
+   * @returns Object containing the current permits and timeout values
+   */
+  getConfig(): Omit<SemaphoreOptions, 'storage'>;
+}
+/**
+ * Default semaphore instance for global use
+ */
+declare const defaultSemaphore: Semaphore;
+/**
+ * Convenience function to execute a function with a permit using the default semaphore.
+ *
+ * @param key - The unique identifier for the semaphore
+ * @param fn - The function to execute with a permit
+ * @param timeout - Optional timeout in milliseconds for permit acquisition
+ * @param signal - Optional AbortSignal for cancelling the permit acquisition
+ * @returns Promise resolving to the result of the function execution
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * const result = await withPermit('database-connection', async () => {
+ *   // This code runs with a permit from the semaphore
+ *   return await executeDatabaseQuery();
+ * }, 30000, controller.signal);
+ * controller.abort(); // Cancels the permit acquisition
+ * ```
+ */
+declare function withPermit<T>(key: string, fn: () => Promise<T> | T, timeout?: number, signal?: AbortSignal): Promise<T>;
+/**
+ * Creates a new semaphore instance with the specified configuration
+ * @param options - Configuration options for the semaphore
+ * @returns New Semaphore instance
+ *
+ * @example
+ * ```typescript
+ * const semaphore = createSemaphore({
+ *   permits: 5,
+ *   timeout: 60000,
+ *   storage: new RedisSemaphoreStorage()
+ * });
+ * ```
+ */
+declare function createSemaphore(options: SemaphoreOptions): Semaphore;
+/**
+ * Acquires a permit using the default semaphore
+ * @param key - The unique identifier for the semaphore
+ * @param timeout - Optional timeout in milliseconds for permit acquisition
+ * @param signal - Optional AbortSignal for cancelling the acquisition
+ * @returns Promise resolving to true if permit was acquired, false if timeout
+ */
+declare function acquirePermit(key: string, timeout?: number, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Releases a permit using the default semaphore
+ * @param key - The unique identifier for the semaphore
+ * @returns Promise that resolves when the permit is released
+ */
+declare function releasePermit(key: string): Promise<void>;
+/**
+ * Gets the number of available permits using the default semaphore
+ * @param key - The unique identifier for the semaphore
+ * @returns Promise resolving to the number of available permits
+ */
+declare function getAvailablePermits(key: string): Promise<number>;
+/**
+ * Gets the number of acquired permits using the default semaphore
+ * @param key - The unique identifier for the semaphore
+ * @returns Promise resolving to the number of acquired permits
+ */
+declare function getAcquiredPermits(key: string): Promise<number>;
+//#endregion
+export { MemorySemaphoreStorage, Semaphore, SemaphoreOptions, SemaphoreStorage, acquirePermit, createSemaphore, defaultSemaphore, getAcquiredPermits, getAvailablePermits, releasePermit, withPermit };
+//# sourceMappingURL=semaphore.d.ts.map

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

@@ -0,0 +1,267 @@
+
+//#region src/utils/useful-stuff/semaphore.ts
+/**
+* In-memory storage implementation for semaphore permits.
+* Suitable for single-instance applications.
+*/
+var MemorySemaphoreStorage = class {
+	semaphores = /* @__PURE__ */ new Map();
+	/**
+	* Attempts to acquire a permit for a given key
+	* @param key - The unique identifier for the semaphore
+	* @param timeout - Optional timeout in milliseconds for permit acquisition
+	* @param signal - Optional AbortSignal for cancelling the acquisition
+	* @returns Promise resolving to true if permit was acquired, false if timeout or no permits available
+	*/
+	async acquire(key, timeout = 3e4, signal) {
+		const startTime = Date.now();
+		while (Date.now() - startTime < timeout) {
+			if (signal === null || signal === void 0 ? void 0 : signal.aborted) throw new Error("Permit acquisition was aborted");
+			const semaphore = this.semaphores.get(key);
+			if (semaphore && semaphore.available > 0) {
+				semaphore.available--;
+				return true;
+			}
+			await this.delay(10);
+		}
+		return false;
+	}
+	/**
+	* Releases a permit for a given key
+	* @param key - The unique identifier for the semaphore
+	* @returns Promise that resolves when the permit is released
+	*/
+	async release(key) {
+		const semaphore = this.semaphores.get(key);
+		if (semaphore && semaphore.available < semaphore.total) semaphore.available++;
+	}
+	/**
+	* Gets the number of available permits for a given key
+	* @param key - The unique identifier for the semaphore
+	* @returns Promise resolving to the number of available permits
+	*/
+	async getAvailablePermits(key) {
+		const semaphore = this.semaphores.get(key);
+		return semaphore ? semaphore.available : 0;
+	}
+	/**
+	* Gets the total number of permits for a given key
+	* @param key - The unique identifier for the semaphore
+	* @returns Promise resolving to the total number of permits
+	*/
+	async getTotalPermits(key) {
+		const semaphore = this.semaphores.get(key);
+		return semaphore ? semaphore.total : 0;
+	}
+	/**
+	* Initializes a semaphore with the specified number of permits
+	* @param key - The unique identifier for the semaphore
+	* @param permits - The total number of permits to allocate
+	*/
+	initialize(key, permits) {
+		this.semaphores.set(key, {
+			total: permits,
+			available: permits
+		});
+	}
+	delay(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+};
+/**
+* Async semaphore implementation that controls access to a limited pool of resources.
+* Allows a specified number of concurrent operations while blocking additional requests.
+*/
+var Semaphore = class {
+	storage;
+	defaultPermits;
+	defaultTimeout;
+	/**
+	* Creates a new semaphore instance
+	* @param options - Configuration options for the semaphore
+	*/
+	constructor(options = {}) {
+		this.storage = options.storage || new MemorySemaphoreStorage();
+		this.defaultPermits = options.permits || 1;
+		this.defaultTimeout = options.timeout || 3e4;
+	}
+	/**
+	* Sets the storage implementation for the semaphore
+	* @param storage - The storage implementation to use
+	*/
+	setStorage(storage) {
+		this.storage = storage;
+	}
+	/**
+	* Gets the storage implementation for the semaphore
+	* @returns The storage implementation
+	*/
+	getStorage() {
+		return this.storage;
+	}
+	/**
+	* Acquires a permit for the given key
+	* @param key - The unique identifier for the semaphore
+	* @param timeout - Optional timeout in milliseconds for permit acquisition
+	* @param signal - Optional AbortSignal for cancelling the acquisition
+	* @returns Promise resolving to true if permit was acquired, false if timeout
+	*/
+	async acquire(key, timeout, signal) {
+		if (this.storage instanceof MemorySemaphoreStorage) {
+			const totalPermits = await this.storage.getTotalPermits(key);
+			if (totalPermits === 0) this.storage.initialize(key, this.defaultPermits);
+		}
+		return this.storage.acquire(key, timeout || this.defaultTimeout, signal);
+	}
+	/**
+	* Releases a permit for the given key
+	* @param key - The unique identifier for the semaphore
+	* @returns Promise that resolves when the permit is released
+	*/
+	async release(key) {
+		return this.storage.release(key);
+	}
+	/**
+	* Gets the number of available permits for the given key
+	* @param key - The unique identifier for the semaphore
+	* @returns Promise resolving to the number of available permits
+	*/
+	async getAvailablePermits(key) {
+		return this.storage.getAvailablePermits(key);
+	}
+	/**
+	* Gets the total number of permits for the given key
+	* @param key - The unique identifier for the semaphore
+	* @returns Promise resolving to the total number of permits
+	*/
+	async getTotalPermits(key) {
+		return this.storage.getTotalPermits(key);
+	}
+	/**
+	* Gets the number of acquired permits for the given key
+	* @param key - The unique identifier for the semaphore
+	* @returns Promise resolving to the number of acquired permits
+	*/
+	async getAcquiredPermits(key) {
+		const total = await this.getTotalPermits(key);
+		const available = await this.getAvailablePermits(key);
+		return total - available;
+	}
+	/**
+	* Executes a function with a permit from the semaphore
+	* @param key - The unique identifier for the semaphore
+	* @param fn - The function to execute with a permit
+	* @param timeout - Optional timeout in milliseconds for permit acquisition
+	* @param signal - Optional AbortSignal for cancelling the permit acquisition
+	* @returns Promise resolving to the result of the function execution
+	* @throws Error if permit acquisition fails or function execution fails
+	*/
+	async withPermit(key, fn, timeout, signal) {
+		const acquired = await this.acquire(key, timeout, signal);
+		if (!acquired) throw new Error(`Failed to acquire permit for key: ${key}`);
+		try {
+			return await fn();
+		} finally {
+			await this.release(key);
+		}
+	}
+	/**
+	* Gets the current configuration of the semaphore
+	* @returns Object containing the current permits and timeout values
+	*/
+	getConfig() {
+		return {
+			permits: this.defaultPermits,
+			timeout: this.defaultTimeout
+		};
+	}
+};
+/**
+* Default semaphore instance for global use
+*/
+const defaultSemaphore = new Semaphore();
+/**
+* Convenience function to execute a function with a permit using the default semaphore.
+*
+* @param key - The unique identifier for the semaphore
+* @param fn - The function to execute with a permit
+* @param timeout - Optional timeout in milliseconds for permit acquisition
+* @param signal - Optional AbortSignal for cancelling the permit acquisition
+* @returns Promise resolving to the result of the function execution
+*
+* @example
+* ```typescript
+* const controller = new AbortController();
+* const result = await withPermit('database-connection', async () => {
+*   // This code runs with a permit from the semaphore
+*   return await executeDatabaseQuery();
+* }, 30000, controller.signal);
+* controller.abort(); // Cancels the permit acquisition
+* ```
+*/
+async function withPermit(key, fn, timeout, signal) {
+	return defaultSemaphore.withPermit(key, fn, timeout, signal);
+}
+/**
+* Creates a new semaphore instance with the specified configuration
+* @param options - Configuration options for the semaphore
+* @returns New Semaphore instance
+*
+* @example
+* ```typescript
+* const semaphore = createSemaphore({
+*   permits: 5,
+*   timeout: 60000,
+*   storage: new RedisSemaphoreStorage()
+* });
+* ```
+*/
+function createSemaphore(options) {
+	return new Semaphore(options);
+}
+/**
+* Acquires a permit using the default semaphore
+* @param key - The unique identifier for the semaphore
+* @param timeout - Optional timeout in milliseconds for permit acquisition
+* @param signal - Optional AbortSignal for cancelling the acquisition
+* @returns Promise resolving to true if permit was acquired, false if timeout
+*/
+async function acquirePermit(key, timeout, signal) {
+	return defaultSemaphore.acquire(key, timeout, signal);
+}
+/**
+* Releases a permit using the default semaphore
+* @param key - The unique identifier for the semaphore
+* @returns Promise that resolves when the permit is released
+*/
+async function releasePermit(key) {
+	return defaultSemaphore.release(key);
+}
+/**
+* Gets the number of available permits using the default semaphore
+* @param key - The unique identifier for the semaphore
+* @returns Promise resolving to the number of available permits
+*/
+async function getAvailablePermits(key) {
+	return defaultSemaphore.getAvailablePermits(key);
+}
+/**
+* Gets the number of acquired permits using the default semaphore
+* @param key - The unique identifier for the semaphore
+* @returns Promise resolving to the number of acquired permits
+*/
+async function getAcquiredPermits(key) {
+	return defaultSemaphore.getAcquiredPermits(key);
+}
+
+//#endregion
+exports.MemorySemaphoreStorage = MemorySemaphoreStorage;
+exports.Semaphore = Semaphore;
+exports.acquirePermit = acquirePermit;
+exports.createSemaphore = createSemaphore;
+exports.defaultSemaphore = defaultSemaphore;
+exports.getAcquiredPermits = getAcquiredPermits;
+exports.getAvailablePermits = getAvailablePermits;
+exports.releasePermit = releasePermit;
+exports.withPermit = withPermit;
+//# sourceMappingURL=semaphore.js.map

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

@@ -0,0 +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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"}

package/dist/{version-CRg5idya.js → version-DfdnkNI2.js}

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

package/dist/{version-CRg5idya.js.map → version-DfdnkNI2.js.map}

@@ -1 +1 @@
-{"version":3,"file":"version-CRg5idya.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-DfdnkNI2.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-CRg5idya.js');
+const require_version = require('./version-DfdnkNI2.js');
 
 exports.version = require_version.version;

package/env.cjs

@@ -0,0 +1,13 @@
+const {
+  COMMANDKIT_BOOTSTRAP_MODE,
+  COMMANDKIT_IS_CLI,
+  COMMANDKIT_IS_DEV,
+  COMMANDKIT_IS_TEST,
+} = require('commandkit');
+
+module.exports = {
+  COMMANDKIT_BOOTSTRAP_MODE,
+  COMMANDKIT_IS_CLI,
+  COMMANDKIT_IS_DEV,
+  COMMANDKIT_IS_TEST,
+};

package/env.d.ts

@@ -0,0 +1,6 @@
+export {
+  COMMANDKIT_BOOTSTRAP_MODE,
+  COMMANDKIT_IS_CLI,
+  COMMANDKIT_IS_DEV,
+  COMMANDKIT_IS_TEST,
+} from 'commandkit';

package/mutex.cjs

@@ -0,0 +1,21 @@
+const {
+  MemoryMutexStorage,
+  Mutex,
+  acquireLock,
+  createMutex,
+  defaultMutex,
+  isLocked,
+  releaseLock,
+  withMutex,
+} = require('./dist/utils/useful-stuff/mutex.js');
+
+module.exports = {
+  MemoryMutexStorage,
+  Mutex,
+  acquireLock,
+  createMutex,
+  defaultMutex,
+  isLocked,
+  releaseLock,
+  withMutex,
+};

package/mutex.d.ts

@@ -0,0 +1 @@
+export * from './dist/utils/useful-stuff/mutex.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "commandkit",
   "description": "Beginner friendly command & event handler for Discord.js",
-  "version": "1.0.0-dev.20250622124751",
+  "version": "1.0.0-dev.20250622135945",
   "license": "MIT",
   "type": "commonjs",
   "main": "./dist/index.js",
@@ -34,7 +34,17 @@
     "./analytics.cjs",
     "./analytics.d.ts",
     "./ai.cjs",
-    "./ai.d.ts"
+    "./ai.d.ts",
+    "./env.cjs",
+    "./env.d.ts",
+    "./async-queue.cjs",
+    "./async-queue.d.ts",
+    "./ratelimit.cjs",
+    "./ratelimit.d.ts",
+    "./semaphore.cjs",
+    "./semaphore.d.ts",
+    "./mutex.cjs",
+    "./mutex.d.ts"
   ],
   "exports": {
     ".": {
@@ -101,6 +111,31 @@
       "require": "./ai.cjs",
       "import": "./ai.cjs",
       "types": "./ai.d.ts"
+    },
+    "./env": {
+      "require": "./env.cjs",
+      "import": "./env.cjs",
+      "types": "./env.d.ts"
+    },
+    "./async-queue": {
+      "require": "./async-queue.cjs",
+      "import": "./async-queue.cjs",
+      "types": "./async-queue.d.ts"
+    },
+    "./ratelimit": {
+      "require": "./ratelimit.cjs",
+      "import": "./ratelimit.cjs",
+      "types": "./ratelimit.d.ts"
+    },
+    "./semaphore": {
+      "require": "./semaphore.cjs",
+      "import": "./semaphore.cjs",
+      "types": "./semaphore.d.ts"
+    },
+    "./mutex": {
+      "require": "./mutex.cjs",
+      "import": "./mutex.cjs",
+      "types": "./mutex.d.ts"
     }
   },
   "repository": {
@@ -136,7 +171,7 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.3",
     "vitest": "^3.0.5",
-    "tsconfig": "0.0.0-dev.20250622124751"
+    "tsconfig": "0.0.0-dev.20250622135945"
   },
   "peerDependencies": {
     "discord.js": "^14"