es-toolkit 1.31.0-dev.999 → 1.32.0-dev.1003

package/dist/promise/mutex.mjs

@@ -0,0 +1,16 @@
+import { Semaphore } from './semaphore.mjs';
+
+class Mutex {
+    semaphore = new Semaphore(1);
+    get isLocked() {
+        return this.semaphore.available === 0;
+    }
+    async acquire() {
+        return this.semaphore.acquire();
+    }
+    release() {
+        this.semaphore.release();
+    }
+}
+
+export { Mutex };

package/dist/promise/semaphore.d.mts

@@ -0,0 +1,81 @@
+/**
+ * A counting semaphore for async functions that manages available permits.
+ * Semaphores are mainly used to limit the number of concurrent async tasks.
+ *
+ * Each `acquire` operation takes a permit or waits until one is available.
+ * Each `release` operation adds a permit, potentially allowing a waiting task to proceed.
+ *
+ * The semaphore ensures fairness by maintaining a FIFO (First In, First Out) order for acquirers.
+ *
+ * @example
+ * const sema = new Semaphore(2);
+ *
+ * async function task() {
+ *   await sema.acquire();
+ *   try {
+ *     // This code can only be executed by two tasks at the same time
+ *   } finally {
+ *     sema.release();
+ *   }
+ * }
+ *
+ * task();
+ * task();
+ * task(); // This task will wait until one of the previous tasks releases the semaphore.
+ */
+declare class Semaphore {
+    /**
+     * The maximum number of concurrent operations allowed.
+     * @type {number}
+     */
+    capacity: number;
+    /**
+     * The number of available permits.
+     * @type {number}
+     */
+    available: number;
+    private deferredTasks;
+    /**
+     * Creates an instance of Semaphore.
+     * @param {number} capacity - The maximum number of concurrent operations allowed.
+     *
+     * @example
+     * const sema = new Semaphore(3); // Allows up to 3 concurrent operations.
+     */
+    constructor(capacity: number);
+    /**
+     * Acquires a semaphore, blocking if necessary until one is available.
+     * @returns {Promise<void>} A promise that resolves when the semaphore is acquired.
+     *
+     * @example
+     * const sema = new Semaphore(1);
+     *
+     * async function criticalSection() {
+     *   await sema.acquire();
+     *   try {
+     *     // This code section cannot be executed simultaneously
+     *   } finally {
+     *     sema.release();
+     *   }
+     * }
+     */
+    acquire(): Promise<void>;
+    /**
+     * Releases a semaphore, allowing one more operation to proceed.
+     *
+     * @example
+     * const sema = new Semaphore(1);
+     *
+     * async function task() {
+     *   await sema.acquire();
+     *   try {
+     *     // This code can only be executed by two tasks at the same time
+     *   } finally {
+     *     sema.release(); // Allows another waiting task to proceed.
+     *   }
+     * }
+     */
+    release(): void;
+}
+
+export { Semaphore };

package/dist/promise/semaphore.d.ts

@@ -0,0 +1,81 @@
+/**
+ * A counting semaphore for async functions that manages available permits.
+ * Semaphores are mainly used to limit the number of concurrent async tasks.
+ *
+ * Each `acquire` operation takes a permit or waits until one is available.
+ * Each `release` operation adds a permit, potentially allowing a waiting task to proceed.
+ *
+ * The semaphore ensures fairness by maintaining a FIFO (First In, First Out) order for acquirers.
+ *
+ * @example
+ * const sema = new Semaphore(2);
+ *
+ * async function task() {
+ *   await sema.acquire();
+ *   try {
+ *     // This code can only be executed by two tasks at the same time
+ *   } finally {
+ *     sema.release();
+ *   }
+ * }
+ *
+ * task();
+ * task();
+ * task(); // This task will wait until one of the previous tasks releases the semaphore.
+ */
+declare class Semaphore {
+    /**
+     * The maximum number of concurrent operations allowed.
+     * @type {number}
+     */
+    capacity: number;
+    /**
+     * The number of available permits.
+     * @type {number}
+     */
+    available: number;
+    private deferredTasks;
+    /**
+     * Creates an instance of Semaphore.
+     * @param {number} capacity - The maximum number of concurrent operations allowed.
+     *
+     * @example
+     * const sema = new Semaphore(3); // Allows up to 3 concurrent operations.
+     */
+    constructor(capacity: number);
+    /**
+     * Acquires a semaphore, blocking if necessary until one is available.
+     * @returns {Promise<void>} A promise that resolves when the semaphore is acquired.
+     *
+     * @example
+     * const sema = new Semaphore(1);
+     *
+     * async function criticalSection() {
+     *   await sema.acquire();
+     *   try {
+     *     // This code section cannot be executed simultaneously
+     *   } finally {
+     *     sema.release();
+     *   }
+     * }
+     */
+    acquire(): Promise<void>;
+    /**
+     * Releases a semaphore, allowing one more operation to proceed.
+     *
+     * @example
+     * const sema = new Semaphore(1);
+     *
+     * async function task() {
+     *   await sema.acquire();
+     *   try {
+     *     // This code can only be executed by two tasks at the same time
+     *   } finally {
+     *     sema.release(); // Allows another waiting task to proceed.
+     *   }
+     * }
+     */
+    release(): void;
+}
+
+export { Semaphore };

package/dist/promise/semaphore.mjs

@@ -0,0 +1,30 @@
+class Semaphore {
+    capacity;
+    available;
+    deferredTasks = [];
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.available = capacity;
+    }
+    async acquire() {
+        if (this.available > 0) {
+            this.available--;
+            return;
+        }
+        return new Promise(resolve => {
+            this.deferredTasks.push(resolve);
+        });
+    }
+    release() {
+        const deferredTask = this.deferredTasks.shift();
+        if (deferredTask != null) {
+            deferredTask();
+            return;
+        }
+        if (this.available < this.capacity) {
+            this.available++;
+        }
+    }
+}
+
+export { Semaphore };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "es-toolkit",
   "description": "A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.",
-  "version": "1.31.0-dev.999+3aba4da5",
+  "version": "1.32.0-dev.1003+2241152e",
   "homepage": "https://es-toolkit.slash.page",
   "bugs": "https://github.com/toss/es-toolkit/issues",
   "repository": {