@chriscdn/promise-semaphore 3.0.0 → 3.0.1

package/README.md

@@ -1,6 +1,7 @@
 # @chriscdn/promise-semaphore
 
-Limit or throttle the simultaneous execution of asynchronous code in separate iterations of the event loop.
+Limit or throttle the concurrent execution of asynchronous code in separate
+iterations of the event loop.
 
 ## Installing
 
@@ -16,21 +17,28 @@ Using yarn:
 yarn add @chriscdn/promise-semaphore
 ```
 
-## Upgrade to v3
+## Version 3
 
-Change
+Version 3 introduces two main changes:
+
+- A new `GroupSemaphore` class has been added. It allows multiple tasks within
+  the same group (identified by a key) to run concurrently while ensuring that
+  only one group's tasks are active at a time. See below for documentation.
+- The default export has been replaced with a named export.
+
+Change:
 
 ```ts
 import Semaphore from "@chriscdn/promise-semaphore";
 ```
 
-to
+to:
 
 ```ts
 import { Semaphore } from "@chriscdn/promise-semaphore";
 ```
 
-## API
+## API - Semaphore
 
 ### Create an instance
 
@@ -39,7 +47,10 @@ import { Semaphore } from "@chriscdn/promise-semaphore";
 const semaphore = new Semaphore([maxConcurrent]);
 ```
 
-The `maxConcurrent` parameter is optional and defaults to `1` (making it an exclusive lock or _binary semaphore_). An integer greater than `1` can be used to allow multiple concurrent executions from separate iterations of the event loop.
+The `maxConcurrent` parameter is optional and defaults to `1` (making it an
+exclusive lock or _binary semaphore_). An integer greater than `1` can be used
+to allow multiple concurrent executions from separate iterations of the event
+loop.
 
 ### Acquire a lock
 
@@ -47,7 +58,9 @@ The `maxConcurrent` parameter is optional and defaults to `1` (making it an excl
 semaphore.acquire([key]);
 ```
 
-This returns a `Promise` that resolves once a lock is acquired. The `key` parameter is optional and allows the same `Semaphore` instance to manage locks in different contexts. Additional details are provided in the second example.
+This returns a `Promise` that resolves once a lock is acquired. The `key`
+parameter is optional and allows the same `Semaphore` instance to manage locks
+in different contexts. Additional details are provided in the second example.
 
 ### Release a lock
 
@@ -55,7 +68,8 @@ This returns a `Promise` that resolves once a lock is acquired. The `key` parame
 semaphore.release([key]);
 ```
 
-The `release` method should be called within a `finally` block (whether using promises or a `try/catch` block) to ensure the lock is released.
+The `release` method should be called within a `finally` block (whether using
+promises or a `try/catch` block) to ensure the lock is released.
 
 ### Check if a lock can be acquired
 
@@ -63,7 +77,8 @@ The `release` method should be called within a `finally` block (whether using pr
 semaphore.canAcquire([key]);
 ```
 
-This synchronous method returns `true` if a lock can be immediately acquired, and `false` otherwise.
+This synchronous method returns `true` if a lock can be immediately acquired,
+and `false` otherwise.
 
 ### `count`
 
@@ -71,7 +86,7 @@ This synchronous method returns `true` if a lock can be immediately acquired, an
 semaphore.count([key]);
 ```
 
-This synchronous function returns the current number of locks.
+This function is synchronous, and returns the current number of locks.
 
 ### `request` method
 
@@ -79,12 +94,13 @@ This synchronous function returns the current number of locks.
 const results = await semaphore.request(fn [, key]);
 ```
 
-This function reduces boilerplate when using `acquire` and `release`. It returns a promise that resolves when `fn` completes. It is functionally equivalent to:
+This function reduces boilerplate when using `acquire` and `release`. It returns
+a promise that resolves when `fn` completes. It is functionally equivalent to:
 
 ```js
 try {
   await semaphore.acquire([key]);
-  const results = await fn();
+  return await fn();
 } finally {
   semaphore.release([key]);
 }
@@ -99,12 +115,12 @@ const results = await semaphore.requestIfAvailable(fn [, key]);
 This is functionally equivalent to:
 
 ```js
-const results = semaphore.canAcquire([key])
-  ? await semaphore.request(fn, [key])
-  : null;
+return semaphore.canAcquire([key]) ? await semaphore.request(fn, [key]) : null;
 ```
 
-This is useful in scenarios where only one instance of a function block should run while discarding additional attempts. For example, handling repeated button clicks.
+This is useful in scenarios where only one instance of a function block should
+run while discarding additional attempts. For example, handling repeated button
+clicks.
 
 ## Example 1
 
@@ -119,7 +135,7 @@ semaphore
     // This block executes once a lock is acquired.
     // If already locked, it waits and executes after all preceding locks are released.
     //
-    // Critical operations are performed here.
+    // Critical operations
   })
   .finally(() => {
     // The lock is released, allowing the next queued block to proceed.
@@ -130,14 +146,14 @@ semaphore
 try {
   await semaphore.acquire();
 
-  // Critical operations are performed here.
+  // Critical operations
 } finally {
   semaphore.release();
 }
 
 // Using the request function
 await semaphore.request(() => {
-  // Critical operations are performed here.
+  // Critical operations
 });
 ```
 
@@ -159,7 +175,10 @@ const downloadAndSave = async (url) => {
 };
 ```
 
-This approach works as expected until `downloadAndSave()` is called multiple times with the same `url` in quick succession. Without control, it could initiate simultaneous downloads that attempt to write to the same file at the same time.
+This approach works as expected until `downloadAndSave()` is called multiple
+times with the same `url` in quick succession. Without control, it could
+initiate simultaneous downloads that attempt to write to the same file at the
+same time.
 
 This issue can be resolved by using a `Semaphore` with the `key` parameter:
 
@@ -172,7 +191,7 @@ const downloadAndSave = async (url) => {
     await semaphore.acquire(url);
 
     // This block continues once a lock on url is acquired. This
-    // permits multiple simulataneous downloads for different urls.
+    // permits multiple simultaneous downloads for different urls.
 
     const filePath = urlToFilePath(url);
 
@@ -198,16 +217,58 @@ const downloadAndSave = (url) => {
 
     if (await pathExists(filePath)) {
       // The file is already on disk, so no action is required.
-      return filePath;
+    } else {
+      await downloadAndSaveToFilepath(url, filePath);
     }
-
-    await downloadAndSaveToFilepath(url, filePath);
-
     return filePath;
   }, url);
 };
 ```
 
+## API - GroupSemaphore
+
+The `GroupSemaphore` class manages a semaphore for different groups of tasks. A
+group is identified by a key, and the semaphore ensures that only one group can
+run its tasks at a time. The tasks within a group can run concurrently.
+
+The `GroupSemaphore` class exposes `acquire` and `release` methods, which have
+the same interface as `Semaphore`. The only difference is that the `key`
+parameter is required.
+
+### Example
+
+```ts
+import { GroupSemaphore } from "@chriscdn/promise-semaphore";
+
+const groupSemaphore = new GroupSemaphore();
+
+const RunA = async () => {
+  try {
+    await groupSemaphore.acquire("GroupA");
+
+    // Perform asynchronous operations for group A
+  } finally {
+    groupSemaphore.release("GroupA");
+  }
+};
+
+const RunB = async () => {
+  try {
+    await groupSemaphore.acquire("GroupB");
+
+    // Perform asynchronous operations for group B
+  } finally {
+    groupSemaphore.release("GroupB");
+  }
+};
+```
+
+This setup allows `RunA` to be called multiple times, and will run concurrently.
+However, calling `RunB` will wait until all `GroupA` tasks are completed before
+acquiring the lock for `GroupB`. As soon as `GroupB` acquires the lock, any
+subsequent calls to `RunA` will wait until `GroupB` releases the lock before it
+executes.
+
 ## License
 
 [MIT](LICENSE)

package/lib/group-semaphore.d.ts

@@ -0,0 +1,25 @@
+/**
+ * GroupSemaphore manages a shared semaphore for different groups of tasks. Each
+ * group is identified by a unique key, and the semaphore ensures only one group
+ * can run its tasks concurrently.
+ *
+ * - acquire(key): Increments the active count for the given group. If it's the
+ *   first task for the group (active count is 0), it acquires the global
+ *   semaphore, ensuring only one group's tasks can proceed at a time.
+ *   Subsequent calls in the group increment the count and are permitted to run.
+ * - release(key): Decrements the active count for the group. If the last task
+ *   for that group is released, it releases the global semaphore, allowing
+ *   other groups to proceed.
+ *
+ * This ensures that only one group can execute concurrently, but multiple tasks
+ * within the same group can run as long as no other tasks from different groups
+ * are active.
+ */
+declare class GroupSemaphore {
+    private _semaphore;
+    private _activeCounts;
+    private _groupWaiters;
+    acquire(key: string): Promise<void>;
+    release(key: string): void;
+}
+export { GroupSemaphore };

package/lib/index.d.ts

@@ -1,57 +1,2 @@
-declare class Semaphore {
-    private semaphoreInstances;
-    private maxConcurrent;
-    /**
-     * @param {number} [maxConcurrent] The maximum number of concurrent locks.
-     */
-    constructor(maxConcurrent?: number);
-    private hasSemaphoreInstance;
-    private getSemaphoreInstance;
-    /**
-     * @param {string | number} [key]- Optional, the semaphore key.
-     */
-    private tidy;
-    /**
-     * A synchronous function to determine whether a lock can be acquired.
-     *
-     * @param {string | number} [key]- Optional, the semaphore key.
-     * @returns {boolean} Returns true if the lock on `key` can be acquired, false
-     * otherwise.
-     */
-    canAcquire(key?: string | number): boolean;
-    /**
-     * @param {string | number} [key]- Optional, the semaphore key.
-     */
-    acquire(key?: string | number): Promise<void>;
-    /**
-     * @param {string | number} [key]- Optional, the semaphore key.
-     */
-    release(key?: string | number): void;
-    /**
-     * The number of active locks.  Will always be less or equal to `max`.
-     *
-     * @param {string | number} [key]- Optional, the semaphore key.
-     */
-    count(key?: string | number): number;
-    /**
-     * @param {string | number} [key]- Optional, the semaphore key.
-     * @returns {boolean} True if the semaphore and key has locks, false otherwise.
-     */
-    hasTasks(key?: string | number): boolean;
-    /**
-     * @param {Function<T>} fn The function to execute.
-     * @param {string | number} [key]- Optional, the semaphore key.
-     * @returns {Promise<T>}
-     */
-    request<T>(fn: Function, key?: string | number): Promise<T>;
-    /**
-     * Asynchronously executes `fn` if a lock can be immediately acquired.
-     * Otherwise, returns null.
-     *
-     * @param {Function<T>} fn The function to execute.
-     * @param {string | number} [key]- Optional, the semaphore key.
-     * @returns {Promise<T>}
-     */
-    requestIfAvailable<T>(fn: Function, key?: string | number): Promise<T | null>;
-}
-export { Semaphore };
+export { Semaphore } from "./semaphore";
+export { GroupSemaphore } from "./group-semaphore";

package/lib/promise-semaphore.cjs

@@ -1,2 +1,2 @@
-function e(e){var t=function(e){if("object"!=typeof e||!e)return e;var t=e[Symbol.toPrimitive];if(void 0!==t){var n=t.call(e,"string");if("object"!=typeof n)return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return String(e)}(e);return"symbol"==typeof t?t:t+""}var t=/*#__PURE__*/function(){function t(e){this.queue=void 0,this.maxConcurrent=void 0,this.count=void 0,this.queue=[],this.maxConcurrent=e,this.count=0}var n,r,i=t.prototype;return i.incrementCount=function(){this.count++},i.decrementCount=function(){this.count--},i.acquire=function(){var e=this;return this.canAcquire?(this.incrementCount(),Promise.resolve()):new Promise(function(t){return e.queue.push(t)})},i.release=function(){var e=this.queue.shift();e?setTimeout(e,0):this.decrementCount()},n=t,(r=[{key:"canAcquire",get:function(){return this.count<this.maxConcurrent}}])&&function(t,n){for(var r=0;r<n.length;r++){var i=n[r];i.enumerable=i.enumerable||!1,i.configurable=!0,"value"in i&&(i.writable=!0),Object.defineProperty(t,e(i.key),i)}}(n.prototype,r),Object.defineProperty(n,"prototype",{writable:!1}),n}(),n="_default";exports.Semaphore=/*#__PURE__*/function(){function e(e){void 0===e&&(e=1),this.semaphoreInstances=void 0,this.maxConcurrent=void 0,this.semaphoreInstances={},this.maxConcurrent=e}var r=e.prototype;return r.hasSemaphoreInstance=function(e){return void 0===e&&(e=n),Boolean(this.semaphoreInstances[e])},r.getSemaphoreInstance=function(e){return void 0===e&&(e=n),this.hasSemaphoreInstance(e)||(this.semaphoreInstances[e]=new t(this.maxConcurrent)),this.semaphoreInstances[e]},r.tidy=function(e){void 0===e&&(e=n),this.hasSemaphoreInstance(e)&&0===this.getSemaphoreInstance(e).count&&delete this.semaphoreInstances[e]},r.canAcquire=function(e){return void 0===e&&(e=n),!this.hasSemaphoreInstance(e)||this.getSemaphoreInstance(e).canAcquire},r.acquire=function(e){return void 0===e&&(e=n),this.getSemaphoreInstance(e).acquire()},r.release=function(e){void 0===e&&(e=n),this.getSemaphoreInstance(e).release(),this.tidy(e)},r.count=function(e){return void 0===e&&(e=n),this.hasSemaphoreInstance(e)?this.getSemaphoreInstance(e).count:0},r.hasTasks=function(e){return void 0===e&&(e=n),this.count(e)>0},r.request=function(e,t){void 0===t&&(t=n);try{var r=this;return Promise.resolve(function(n,i){try{var o=Promise.resolve(r.acquire(t)).then(function(){return Promise.resolve(e())})}catch(e){return i(!0,e)}return o&&o.then?o.then(i.bind(null,!1),i.bind(null,!0)):i(!1,o)}(0,function(e,n){if(r.release(t),e)throw n;return n}))}catch(e){return Promise.reject(e)}},r.requestIfAvailable=function(e,t){void 0===t&&(t=n);try{return this.canAcquire(t)?Promise.resolve(this.request(e,t)):Promise.resolve(null)}catch(e){return Promise.reject(e)}},e}();
+function e(e){var t=function(e){if("object"!=typeof e||!e)return e;var t=e[Symbol.toPrimitive];if(void 0!==t){var n=t.call(e,"string");if("object"!=typeof n)return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return String(e)}(e);return"symbol"==typeof t?t:t+""}var t=/*#__PURE__*/function(){function t(e){this.queue=void 0,this.maxConcurrent=void 0,this.count=void 0,this.queue=[],this.maxConcurrent=e,this.count=0}var n,r,i=t.prototype;return i.incrementCount=function(){this.count++},i.decrementCount=function(){this.count--},i.acquire=function(){var e=this;return this.canAcquire?(this.incrementCount(),Promise.resolve()):new Promise(function(t){return e.queue.push(t)})},i.release=function(){var e=this.queue.shift();e?setTimeout(e,0):this.decrementCount()},n=t,(r=[{key:"canAcquire",get:function(){return this.count<this.maxConcurrent}}])&&function(t,n){for(var r=0;r<n.length;r++){var i=n[r];i.enumerable=i.enumerable||!1,i.configurable=!0,"value"in i&&(i.writable=!0),Object.defineProperty(t,e(i.key),i)}}(n.prototype,r),Object.defineProperty(n,"prototype",{writable:!1}),n}(),n="_default",r=/*#__PURE__*/function(){function e(e){void 0===e&&(e=1),this.semaphoreInstances=void 0,this.maxConcurrent=void 0,this.semaphoreInstances={},this.maxConcurrent=e}var r=e.prototype;return r.hasSemaphoreInstance=function(e){return void 0===e&&(e=n),Boolean(this.semaphoreInstances[e])},r.getSemaphoreInstance=function(e){return void 0===e&&(e=n),this.hasSemaphoreInstance(e)||(this.semaphoreInstances[e]=new t(this.maxConcurrent)),this.semaphoreInstances[e]},r.tidy=function(e){void 0===e&&(e=n),this.hasSemaphoreInstance(e)&&0===this.getSemaphoreInstance(e).count&&delete this.semaphoreInstances[e]},r.canAcquire=function(e){return void 0===e&&(e=n),!this.hasSemaphoreInstance(e)||this.getSemaphoreInstance(e).canAcquire},r.acquire=function(e){return void 0===e&&(e=n),this.getSemaphoreInstance(e).acquire()},r.release=function(e){void 0===e&&(e=n),this.getSemaphoreInstance(e).release(),this.tidy(e)},r.count=function(e){return void 0===e&&(e=n),this.hasSemaphoreInstance(e)?this.getSemaphoreInstance(e).count:0},r.hasTasks=function(e){return void 0===e&&(e=n),this.count(e)>0},r.request=function(e,t){void 0===t&&(t=n);try{var r=this;return Promise.resolve(function(n,i){try{var o=Promise.resolve(r.acquire(t)).then(function(){return Promise.resolve(e())})}catch(e){return i(!0,e)}return o&&o.then?o.then(i.bind(null,!1),i.bind(null,!0)):i(!1,o)}(0,function(e,n){if(r.release(t),e)throw n;return n}))}catch(e){return Promise.reject(e)}},r.requestIfAvailable=function(e,t){void 0===t&&(t=n);try{return this.canAcquire(t)?Promise.resolve(this.request(e,t)):Promise.resolve(null)}catch(e){return Promise.reject(e)}},e}();exports.GroupSemaphore=/*#__PURE__*/function(){function e(){this._semaphore=new r,this._activeCounts={},this._groupWaiters={}}var t=e.prototype;return t.acquire=function(e){try{var t,n,r=this,i=null!=(t=r._activeCounts[e])?t:0;r._activeCounts[e]=i+1;var o=null!=(n=r._groupWaiters[e])?n:r._semaphore.acquire();return r._groupWaiters[e]=o,Promise.resolve(o).then(function(){})}catch(e){return Promise.reject(e)}},t.release=function(e){var t=this._activeCounts[e];1===t?(this._semaphore.release(),delete this._activeCounts[e],delete this._groupWaiters[e]):this._activeCounts[e]=t-1},e}(),exports.Semaphore=r;
 //# sourceMappingURL=promise-semaphore.cjs.map

package/lib/promise-semaphore.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"promise-semaphore.cjs","sources":["../src/index.ts"],"sourcesContent":["class SemaphoreItem {\n  private queue: Function[];\n  private maxConcurrent: number;\n\n  /**\n   * The number of locks.\n   */\n  public count: number;\n\n  constructor(maxConcurrent: number) {\n    this.queue = [];\n    this.maxConcurrent = maxConcurrent;\n    this.count = 0;\n  }\n\n  get canAcquire(): boolean {\n    return this.count < this.maxConcurrent;\n  }\n\n  private incrementCount() {\n    this.count++;\n  }\n\n  private decrementCount() {\n    this.count--;\n  }\n\n  acquire(): Promise<void> {\n    if (this.canAcquire) {\n      this.incrementCount();\n      return Promise.resolve();\n    } else {\n      return new Promise((resolve) => this.queue.push(resolve));\n    }\n  }\n\n  release(): void {\n    const resolveFunc = this.queue.shift();\n\n    if (resolveFunc) {\n      // Give the micro task queue a small break instead of calling resolveFunc() directly\n      setTimeout(resolveFunc, 0);\n    } else {\n      this.decrementCount();\n    }\n  }\n}\n\nconst defaultKey = \"_default\";\n\nclass Semaphore {\n  private semaphoreInstances: Record<string | number, SemaphoreItem>;\n  private maxConcurrent: number;\n\n  /**\n   * @param {number} [maxConcurrent] The maximum number of concurrent locks.\n   */\n  constructor(maxConcurrent: number = 1) {\n    this.semaphoreInstances = {};\n    this.maxConcurrent = maxConcurrent;\n  }\n\n  private hasSemaphoreInstance(key: string | number = defaultKey) {\n    return Boolean(this.semaphoreInstances[key]);\n  }\n\n  private getSemaphoreInstance(key: string | number = defaultKey) {\n    if (!this.hasSemaphoreInstance(key)) {\n      this.semaphoreInstances[key] = new SemaphoreItem(this.maxConcurrent);\n    }\n    return this.semaphoreInstances[key];\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  private tidy(key: string | number = defaultKey): void {\n    if (\n      this.hasSemaphoreInstance(key) &&\n      this.getSemaphoreInstance(key).count === 0\n    ) {\n      delete this.semaphoreInstances[key];\n    }\n  }\n\n  /**\n   * A synchronous function to determine whether a lock can be acquired.\n   *\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {boolean} Returns true if the lock on `key` can be acquired, false\n   * otherwise.\n   */\n  canAcquire(key: string | number = defaultKey): boolean {\n    return !this.hasSemaphoreInstance(key) ||\n      this.getSemaphoreInstance(key).canAcquire;\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  acquire(key: string | number = defaultKey) {\n    return this.getSemaphoreInstance(key).acquire();\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  release(key: string | number = defaultKey): void {\n    this.getSemaphoreInstance(key).release();\n    this.tidy(key);\n  }\n\n  /**\n   * The number of active locks.  Will always be less or equal to `max`.\n   *\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  count(key: string | number = defaultKey): number {\n    if (this.hasSemaphoreInstance(key)) {\n      return this.getSemaphoreInstance(key).count;\n    } else {\n      return 0;\n    }\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {boolean} True if the semaphore and key has locks, false otherwise.\n   */\n  hasTasks(key: string | number = defaultKey): boolean {\n    return this.count(key) > 0;\n  }\n\n  /**\n   * @param {Function<T>} fn The function to execute.\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {Promise<T>}\n   */\n  async request<T>(\n    fn: Function,\n    key: string | number = defaultKey,\n  ): Promise<T> {\n    try {\n      await this.acquire(key);\n      return await fn();\n    } finally {\n      this.release(key);\n    }\n  }\n\n  /**\n   * Asynchronously executes `fn` if a lock can be immediately acquired.\n   * Otherwise, returns null.\n   *\n   * @param {Function<T>} fn The function to execute.\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {Promise<T>}\n   */\n  async requestIfAvailable<T>(\n    fn: Function,\n    key: string | number = defaultKey,\n  ): Promise<T | null> {\n    if (this.canAcquire(key)) {\n      return this.request(fn, key);\n    } else {\n      return null;\n    }\n  }\n}\n\nexport { Semaphore };\n"],"names":["SemaphoreItem","maxConcurrent","queue","this","count","_proto","prototype","incrementCount","decrementCount","acquire","_this","canAcquire","Promise","resolve","push","release","resolveFunc","shift","setTimeout","key","get","defaultKey","Semaphore","semaphoreInstances","_proto2","hasSemaphoreInstance","Boolean","getSemaphoreInstance","tidy","hasTasks","request","fn","_this2","then","_finallyRethrows","_wasThrown","_result","e","reject","requestIfAvailable"],"mappings":"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"}
+{"version":3,"file":"promise-semaphore.cjs","sources":["../src/semaphore.ts","../src/group-semaphore.ts"],"sourcesContent":["class SemaphoreItem {\n    private queue: Function[];\n    private maxConcurrent: number;\n\n    /**\n     * The number of locks.\n     */\n    public count: number;\n\n    constructor(maxConcurrent: number) {\n        this.queue = [];\n        this.maxConcurrent = maxConcurrent;\n        this.count = 0;\n    }\n\n    get canAcquire(): boolean {\n        return this.count < this.maxConcurrent;\n    }\n\n    private incrementCount() {\n        this.count++;\n    }\n\n    private decrementCount() {\n        this.count--;\n    }\n\n    acquire(): Promise<void> {\n        if (this.canAcquire) {\n            this.incrementCount();\n            return Promise.resolve();\n        } else {\n            return new Promise((resolve) => this.queue.push(resolve));\n        }\n    }\n\n    release(): void {\n        const resolveFunc = this.queue.shift();\n\n        if (resolveFunc) {\n            // Give the micro task queue a small break instead of calling resolveFunc() directly\n            setTimeout(resolveFunc, 0);\n        } else {\n            this.decrementCount();\n        }\n    }\n}\n\nconst defaultKey = \"_default\";\n\nclass Semaphore {\n    private semaphoreInstances: Record<string | number, SemaphoreItem>;\n    private maxConcurrent: number;\n\n    /**\n     * @param {number} [maxConcurrent] The maximum number of concurrent locks.\n     */\n    constructor(maxConcurrent: number = 1) {\n        this.semaphoreInstances = {};\n        this.maxConcurrent = maxConcurrent;\n    }\n\n    private hasSemaphoreInstance(key: string | number = defaultKey) {\n        return Boolean(this.semaphoreInstances[key]);\n    }\n\n    private getSemaphoreInstance(key: string | number = defaultKey) {\n        if (!this.hasSemaphoreInstance(key)) {\n            this.semaphoreInstances[key] = new SemaphoreItem(\n                this.maxConcurrent,\n            );\n        }\n        return this.semaphoreInstances[key];\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    private tidy(key: string | number = defaultKey): void {\n        if (\n            this.hasSemaphoreInstance(key) &&\n            this.getSemaphoreInstance(key).count === 0\n        ) {\n            delete this.semaphoreInstances[key];\n        }\n    }\n\n    /**\n     * A synchronous function to determine whether a lock can be acquired.\n     *\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {boolean} Returns true if the lock on `key` can be acquired, false\n     * otherwise.\n     */\n    canAcquire(key: string | number = defaultKey): boolean {\n        return !this.hasSemaphoreInstance(key) ||\n            this.getSemaphoreInstance(key).canAcquire;\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    acquire(key: string | number = defaultKey) {\n        return this.getSemaphoreInstance(key).acquire();\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    release(key: string | number = defaultKey): void {\n        this.getSemaphoreInstance(key).release();\n        this.tidy(key);\n    }\n\n    /**\n     * The number of active locks.  Will always be less or equal to `max`.\n     *\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    count(key: string | number = defaultKey): number {\n        if (this.hasSemaphoreInstance(key)) {\n            return this.getSemaphoreInstance(key).count;\n        } else {\n            return 0;\n        }\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {boolean} True if the semaphore and key has locks, false otherwise.\n     */\n    hasTasks(key: string | number = defaultKey): boolean {\n        return this.count(key) > 0;\n    }\n\n    /**\n     * @param {Function<T>} fn The function to execute.\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {Promise<T>}\n     */\n    async request<T>(\n        fn: Function,\n        key: string | number = defaultKey,\n    ): Promise<T> {\n        try {\n            await this.acquire(key);\n            return await fn();\n        } finally {\n            this.release(key);\n        }\n    }\n\n    /**\n     * Asynchronously executes `fn` if a lock can be immediately acquired.\n     * Otherwise, returns null.\n     *\n     * @param {Function<T>} fn The function to execute.\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {Promise<T>}\n     */\n    async requestIfAvailable<T>(\n        fn: Function,\n        key: string | number = defaultKey,\n    ): Promise<T | null> {\n        if (this.canAcquire(key)) {\n            return this.request(fn, key);\n        } else {\n            return null;\n        }\n    }\n}\n\nexport { Semaphore };\n","import { Semaphore } from \"./semaphore\";\n\n/**\n * GroupSemaphore manages a shared semaphore for different groups of tasks. Each\n * group is identified by a unique key, and the semaphore ensures only one group\n * can run its tasks concurrently.\n *\n * - acquire(key): Increments the active count for the given group. If it's the\n *   first task for the group (active count is 0), it acquires the global\n *   semaphore, ensuring only one group's tasks can proceed at a time.\n *   Subsequent calls in the group increment the count and are permitted to run.\n * - release(key): Decrements the active count for the group. If the last task\n *   for that group is released, it releases the global semaphore, allowing\n *   other groups to proceed.\n *\n * This ensures that only one group can execute concurrently, but multiple tasks\n * within the same group can run as long as no other tasks from different groups\n * are active.\n */\nclass GroupSemaphore {\n    private _semaphore = new Semaphore();\n    private _activeCounts: Record<string, number> = {};\n    private _groupWaiters: Record<string, Promise<void>> = {};\n\n    async acquire(key: string) {\n        const activeCount = this._activeCounts[key] ?? 0;\n        this._activeCounts[key] = activeCount + 1;\n        const waiter = this._groupWaiters[key] ?? this._semaphore.acquire();\n        this._groupWaiters[key] = waiter;\n        await waiter;\n    }\n\n    release(key: string) {\n        const activeCount = this._activeCounts[key];\n\n        if (activeCount === 1) {\n            this._semaphore.release();\n            delete this._activeCounts[key];\n            delete this._groupWaiters[key];\n        } else {\n            this._activeCounts[key] = activeCount - 1;\n        }\n    }\n}\n\nexport { GroupSemaphore };\n"],"names":["SemaphoreItem","maxConcurrent","queue","this","count","_proto","prototype","incrementCount","decrementCount","acquire","_this","canAcquire","Promise","resolve","push","release","resolveFunc","shift","setTimeout","key","get","defaultKey","Semaphore","semaphoreInstances","_proto2","hasSemaphoreInstance","Boolean","getSemaphoreInstance","tidy","hasTasks","request","fn","_this2","then","_finallyRethrows","_wasThrown","_result","e","reject","requestIfAvailable","GroupSemaphore","_semaphore","_activeCounts","_groupWaiters","_this$_activeCounts$k","_this$_groupWaiters$k","activeCount","waiter"],"mappings":"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"}

package/lib/promise-semaphore.modern.js

@@ -1,2 +1,2 @@
-class e{constructor(e){this.queue=void 0,this.maxConcurrent=void 0,this.count=void 0,this.queue=[],this.maxConcurrent=e,this.count=0}get canAcquire(){return this.count<this.maxConcurrent}incrementCount(){this.count++}decrementCount(){this.count--}acquire(){return this.canAcquire?(this.incrementCount(),Promise.resolve()):new Promise(e=>this.queue.push(e))}release(){const e=this.queue.shift();e?setTimeout(e,0):this.decrementCount()}}const t="_default";class s{constructor(e=1){this.semaphoreInstances=void 0,this.maxConcurrent=void 0,this.semaphoreInstances={},this.maxConcurrent=e}hasSemaphoreInstance(e=t){return Boolean(this.semaphoreInstances[e])}getSemaphoreInstance(s=t){return this.hasSemaphoreInstance(s)||(this.semaphoreInstances[s]=new e(this.maxConcurrent)),this.semaphoreInstances[s]}tidy(e=t){this.hasSemaphoreInstance(e)&&0===this.getSemaphoreInstance(e).count&&delete this.semaphoreInstances[e]}canAcquire(e=t){return!this.hasSemaphoreInstance(e)||this.getSemaphoreInstance(e).canAcquire}acquire(e=t){return this.getSemaphoreInstance(e).acquire()}release(e=t){this.getSemaphoreInstance(e).release(),this.tidy(e)}count(e=t){return this.hasSemaphoreInstance(e)?this.getSemaphoreInstance(e).count:0}hasTasks(e=t){return this.count(e)>0}async request(e,s=t){try{return await this.acquire(s),await e()}finally{this.release(s)}}async requestIfAvailable(e,s=t){return this.canAcquire(s)?this.request(e,s):null}}export{s as Semaphore};
+class e{constructor(e){this.queue=void 0,this.maxConcurrent=void 0,this.count=void 0,this.queue=[],this.maxConcurrent=e,this.count=0}get canAcquire(){return this.count<this.maxConcurrent}incrementCount(){this.count++}decrementCount(){this.count--}acquire(){return this.canAcquire?(this.incrementCount(),Promise.resolve()):new Promise(e=>this.queue.push(e))}release(){const e=this.queue.shift();e?setTimeout(e,0):this.decrementCount()}}const t="_default";class s{constructor(e=1){this.semaphoreInstances=void 0,this.maxConcurrent=void 0,this.semaphoreInstances={},this.maxConcurrent=e}hasSemaphoreInstance(e=t){return Boolean(this.semaphoreInstances[e])}getSemaphoreInstance(s=t){return this.hasSemaphoreInstance(s)||(this.semaphoreInstances[s]=new e(this.maxConcurrent)),this.semaphoreInstances[s]}tidy(e=t){this.hasSemaphoreInstance(e)&&0===this.getSemaphoreInstance(e).count&&delete this.semaphoreInstances[e]}canAcquire(e=t){return!this.hasSemaphoreInstance(e)||this.getSemaphoreInstance(e).canAcquire}acquire(e=t){return this.getSemaphoreInstance(e).acquire()}release(e=t){this.getSemaphoreInstance(e).release(),this.tidy(e)}count(e=t){return this.hasSemaphoreInstance(e)?this.getSemaphoreInstance(e).count:0}hasTasks(e=t){return this.count(e)>0}async request(e,s=t){try{return await this.acquire(s),await e()}finally{this.release(s)}}async requestIfAvailable(e,s=t){return this.canAcquire(s)?this.request(e,s):null}}class n{constructor(){this._semaphore=new s,this._activeCounts={},this._groupWaiters={}}async acquire(e){var t,s;const n=null!=(t=this._activeCounts[e])?t:0;this._activeCounts[e]=n+1;const r=null!=(s=this._groupWaiters[e])?s:this._semaphore.acquire();this._groupWaiters[e]=r,await r}release(e){const t=this._activeCounts[e];1===t?(this._semaphore.release(),delete this._activeCounts[e],delete this._groupWaiters[e]):this._activeCounts[e]=t-1}}export{n as GroupSemaphore,s as Semaphore};
 //# sourceMappingURL=promise-semaphore.modern.js.map

package/lib/promise-semaphore.modern.js.map

@@ -1 +1 @@
-{"version":3,"file":"promise-semaphore.modern.js","sources":["../src/index.ts"],"sourcesContent":["class SemaphoreItem {\n  private queue: Function[];\n  private maxConcurrent: number;\n\n  /**\n   * The number of locks.\n   */\n  public count: number;\n\n  constructor(maxConcurrent: number) {\n    this.queue = [];\n    this.maxConcurrent = maxConcurrent;\n    this.count = 0;\n  }\n\n  get canAcquire(): boolean {\n    return this.count < this.maxConcurrent;\n  }\n\n  private incrementCount() {\n    this.count++;\n  }\n\n  private decrementCount() {\n    this.count--;\n  }\n\n  acquire(): Promise<void> {\n    if (this.canAcquire) {\n      this.incrementCount();\n      return Promise.resolve();\n    } else {\n      return new Promise((resolve) => this.queue.push(resolve));\n    }\n  }\n\n  release(): void {\n    const resolveFunc = this.queue.shift();\n\n    if (resolveFunc) {\n      // Give the micro task queue a small break instead of calling resolveFunc() directly\n      setTimeout(resolveFunc, 0);\n    } else {\n      this.decrementCount();\n    }\n  }\n}\n\nconst defaultKey = \"_default\";\n\nclass Semaphore {\n  private semaphoreInstances: Record<string | number, SemaphoreItem>;\n  private maxConcurrent: number;\n\n  /**\n   * @param {number} [maxConcurrent] The maximum number of concurrent locks.\n   */\n  constructor(maxConcurrent: number = 1) {\n    this.semaphoreInstances = {};\n    this.maxConcurrent = maxConcurrent;\n  }\n\n  private hasSemaphoreInstance(key: string | number = defaultKey) {\n    return Boolean(this.semaphoreInstances[key]);\n  }\n\n  private getSemaphoreInstance(key: string | number = defaultKey) {\n    if (!this.hasSemaphoreInstance(key)) {\n      this.semaphoreInstances[key] = new SemaphoreItem(this.maxConcurrent);\n    }\n    return this.semaphoreInstances[key];\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  private tidy(key: string | number = defaultKey): void {\n    if (\n      this.hasSemaphoreInstance(key) &&\n      this.getSemaphoreInstance(key).count === 0\n    ) {\n      delete this.semaphoreInstances[key];\n    }\n  }\n\n  /**\n   * A synchronous function to determine whether a lock can be acquired.\n   *\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {boolean} Returns true if the lock on `key` can be acquired, false\n   * otherwise.\n   */\n  canAcquire(key: string | number = defaultKey): boolean {\n    return !this.hasSemaphoreInstance(key) ||\n      this.getSemaphoreInstance(key).canAcquire;\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  acquire(key: string | number = defaultKey) {\n    return this.getSemaphoreInstance(key).acquire();\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  release(key: string | number = defaultKey): void {\n    this.getSemaphoreInstance(key).release();\n    this.tidy(key);\n  }\n\n  /**\n   * The number of active locks.  Will always be less or equal to `max`.\n   *\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  count(key: string | number = defaultKey): number {\n    if (this.hasSemaphoreInstance(key)) {\n      return this.getSemaphoreInstance(key).count;\n    } else {\n      return 0;\n    }\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {boolean} True if the semaphore and key has locks, false otherwise.\n   */\n  hasTasks(key: string | number = defaultKey): boolean {\n    return this.count(key) > 0;\n  }\n\n  /**\n   * @param {Function<T>} fn The function to execute.\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {Promise<T>}\n   */\n  async request<T>(\n    fn: Function,\n    key: string | number = defaultKey,\n  ): Promise<T> {\n    try {\n      await this.acquire(key);\n      return await fn();\n    } finally {\n      this.release(key);\n    }\n  }\n\n  /**\n   * Asynchronously executes `fn` if a lock can be immediately acquired.\n   * Otherwise, returns null.\n   *\n   * @param {Function<T>} fn The function to execute.\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {Promise<T>}\n   */\n  async requestIfAvailable<T>(\n    fn: Function,\n    key: string | number = defaultKey,\n  ): Promise<T | null> {\n    if (this.canAcquire(key)) {\n      return this.request(fn, key);\n    } else {\n      return null;\n    }\n  }\n}\n\nexport { Semaphore };\n"],"names":["SemaphoreItem","constructor","maxConcurrent","this","queue","count","canAcquire","incrementCount","decrementCount","acquire","Promise","resolve","push","release","resolveFunc","shift","setTimeout","defaultKey","Semaphore","semaphoreInstances","hasSemaphoreInstance","key","Boolean","getSemaphoreInstance","tidy","hasTasks","request","fn","requestIfAvailable"],"mappings":"AAAA,MAAMA,EASJC,WAAAA,CAAYC,GAAqBC,KARzBC,WAAK,EAAAD,KACLD,mBAAa,EAAAC,KAKdE,WAGL,EAAAF,KAAKC,MAAQ,GACbD,KAAKD,cAAgBA,EACrBC,KAAKE,MAAQ,CACf,CAEA,cAAIC,GACF,OAAOH,KAAKE,MAAQF,KAAKD,aAC3B,CAEQK,cAAAA,GACNJ,KAAKE,OACP,CAEQG,cAAAA,GACNL,KAAKE,OACP,CAEAI,OAAAA,GACE,OAAIN,KAAKG,YACPH,KAAKI,iBACEG,QAAQC,WAER,IAAID,QAASC,GAAYR,KAAKC,MAAMQ,KAAKD,GAEpD,CAEAE,OAAAA,GACE,MAAMC,EAAcX,KAAKC,MAAMW,QAE3BD,EAEFE,WAAWF,EAAa,GAExBX,KAAKK,gBAET,EAGF,MAAMS,EAAa,WAEnB,MAAMC,EAOJjB,WAAAA,CAAYC,EAAwB,GAACC,KAN7BgB,wBAAkB,EAAAhB,KAClBD,mBAAa,EAMnBC,KAAKgB,mBAAqB,CAAA,EAC1BhB,KAAKD,cAAgBA,CACvB,CAEQkB,oBAAAA,CAAqBC,EAAuBJ,GAClD,OAAOK,QAAQnB,KAAKgB,mBAAmBE,GACzC,CAEQE,oBAAAA,CAAqBF,EAAuBJ,GAIlD,OAHKd,KAAKiB,qBAAqBC,KAC7BlB,KAAKgB,mBAAmBE,GAAO,IAAIrB,EAAcG,KAAKD,gBAE7CC,KAACgB,mBAAmBE,EACjC,CAKQG,IAAAA,CAAKH,EAAuBJ,GAEhCd,KAAKiB,qBAAqBC,IACe,IAAzClB,KAAKoB,qBAAqBF,GAAKhB,cAExBF,KAAKgB,mBAAmBE,EAEnC,CASAf,UAAAA,CAAWe,EAAuBJ,GAChC,OAAQd,KAAKiB,qBAAqBC,IAChClB,KAAKoB,qBAAqBF,GAAKf,UACnC,CAKAG,OAAAA,CAAQY,EAAuBJ,GAC7B,OAAWd,KAACoB,qBAAqBF,GAAKZ,SACxC,CAKAI,OAAAA,CAAQQ,EAAuBJ,GAC7Bd,KAAKoB,qBAAqBF,GAAKR,UAC/BV,KAAKqB,KAAKH,EACZ,CAOAhB,KAAAA,CAAMgB,EAAuBJ,GAC3B,OAAId,KAAKiB,qBAAqBC,GACrBlB,KAAKoB,qBAAqBF,GAAKhB,MAGvC,CACH,CAMAoB,QAAAA,CAASJ,EAAuBJ,GAC9B,OAAWd,KAACE,MAAMgB,GAAO,CAC3B,CAOA,aAAMK,CACJC,EACAN,EAAuBJ,GAEvB,IAEE,aADUd,KAACM,QAAQY,SACNM,GACd,CAAA,QACCxB,KAAKU,QAAQQ,EACd,CACH,CAUA,wBAAMO,CACJD,EACAN,EAAuBJ,GAEvB,OAAId,KAAKG,WAAWe,GACPlB,KAACuB,QAAQC,EAAIN,GAEjB,IAEX"}
+{"version":3,"file":"promise-semaphore.modern.js","sources":["../src/semaphore.ts","../src/group-semaphore.ts"],"sourcesContent":["class SemaphoreItem {\n    private queue: Function[];\n    private maxConcurrent: number;\n\n    /**\n     * The number of locks.\n     */\n    public count: number;\n\n    constructor(maxConcurrent: number) {\n        this.queue = [];\n        this.maxConcurrent = maxConcurrent;\n        this.count = 0;\n    }\n\n    get canAcquire(): boolean {\n        return this.count < this.maxConcurrent;\n    }\n\n    private incrementCount() {\n        this.count++;\n    }\n\n    private decrementCount() {\n        this.count--;\n    }\n\n    acquire(): Promise<void> {\n        if (this.canAcquire) {\n            this.incrementCount();\n            return Promise.resolve();\n        } else {\n            return new Promise((resolve) => this.queue.push(resolve));\n        }\n    }\n\n    release(): void {\n        const resolveFunc = this.queue.shift();\n\n        if (resolveFunc) {\n            // Give the micro task queue a small break instead of calling resolveFunc() directly\n            setTimeout(resolveFunc, 0);\n        } else {\n            this.decrementCount();\n        }\n    }\n}\n\nconst defaultKey = \"_default\";\n\nclass Semaphore {\n    private semaphoreInstances: Record<string | number, SemaphoreItem>;\n    private maxConcurrent: number;\n\n    /**\n     * @param {number} [maxConcurrent] The maximum number of concurrent locks.\n     */\n    constructor(maxConcurrent: number = 1) {\n        this.semaphoreInstances = {};\n        this.maxConcurrent = maxConcurrent;\n    }\n\n    private hasSemaphoreInstance(key: string | number = defaultKey) {\n        return Boolean(this.semaphoreInstances[key]);\n    }\n\n    private getSemaphoreInstance(key: string | number = defaultKey) {\n        if (!this.hasSemaphoreInstance(key)) {\n            this.semaphoreInstances[key] = new SemaphoreItem(\n                this.maxConcurrent,\n            );\n        }\n        return this.semaphoreInstances[key];\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    private tidy(key: string | number = defaultKey): void {\n        if (\n            this.hasSemaphoreInstance(key) &&\n            this.getSemaphoreInstance(key).count === 0\n        ) {\n            delete this.semaphoreInstances[key];\n        }\n    }\n\n    /**\n     * A synchronous function to determine whether a lock can be acquired.\n     *\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {boolean} Returns true if the lock on `key` can be acquired, false\n     * otherwise.\n     */\n    canAcquire(key: string | number = defaultKey): boolean {\n        return !this.hasSemaphoreInstance(key) ||\n            this.getSemaphoreInstance(key).canAcquire;\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    acquire(key: string | number = defaultKey) {\n        return this.getSemaphoreInstance(key).acquire();\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    release(key: string | number = defaultKey): void {\n        this.getSemaphoreInstance(key).release();\n        this.tidy(key);\n    }\n\n    /**\n     * The number of active locks.  Will always be less or equal to `max`.\n     *\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    count(key: string | number = defaultKey): number {\n        if (this.hasSemaphoreInstance(key)) {\n            return this.getSemaphoreInstance(key).count;\n        } else {\n            return 0;\n        }\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {boolean} True if the semaphore and key has locks, false otherwise.\n     */\n    hasTasks(key: string | number = defaultKey): boolean {\n        return this.count(key) > 0;\n    }\n\n    /**\n     * @param {Function<T>} fn The function to execute.\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {Promise<T>}\n     */\n    async request<T>(\n        fn: Function,\n        key: string | number = defaultKey,\n    ): Promise<T> {\n        try {\n            await this.acquire(key);\n            return await fn();\n        } finally {\n            this.release(key);\n        }\n    }\n\n    /**\n     * Asynchronously executes `fn` if a lock can be immediately acquired.\n     * Otherwise, returns null.\n     *\n     * @param {Function<T>} fn The function to execute.\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {Promise<T>}\n     */\n    async requestIfAvailable<T>(\n        fn: Function,\n        key: string | number = defaultKey,\n    ): Promise<T | null> {\n        if (this.canAcquire(key)) {\n            return this.request(fn, key);\n        } else {\n            return null;\n        }\n    }\n}\n\nexport { Semaphore };\n","import { Semaphore } from \"./semaphore\";\n\n/**\n * GroupSemaphore manages a shared semaphore for different groups of tasks. Each\n * group is identified by a unique key, and the semaphore ensures only one group\n * can run its tasks concurrently.\n *\n * - acquire(key): Increments the active count for the given group. If it's the\n *   first task for the group (active count is 0), it acquires the global\n *   semaphore, ensuring only one group's tasks can proceed at a time.\n *   Subsequent calls in the group increment the count and are permitted to run.\n * - release(key): Decrements the active count for the group. If the last task\n *   for that group is released, it releases the global semaphore, allowing\n *   other groups to proceed.\n *\n * This ensures that only one group can execute concurrently, but multiple tasks\n * within the same group can run as long as no other tasks from different groups\n * are active.\n */\nclass GroupSemaphore {\n    private _semaphore = new Semaphore();\n    private _activeCounts: Record<string, number> = {};\n    private _groupWaiters: Record<string, Promise<void>> = {};\n\n    async acquire(key: string) {\n        const activeCount = this._activeCounts[key] ?? 0;\n        this._activeCounts[key] = activeCount + 1;\n        const waiter = this._groupWaiters[key] ?? this._semaphore.acquire();\n        this._groupWaiters[key] = waiter;\n        await waiter;\n    }\n\n    release(key: string) {\n        const activeCount = this._activeCounts[key];\n\n        if (activeCount === 1) {\n            this._semaphore.release();\n            delete this._activeCounts[key];\n            delete this._groupWaiters[key];\n        } else {\n            this._activeCounts[key] = activeCount - 1;\n        }\n    }\n}\n\nexport { GroupSemaphore };\n"],"names":["SemaphoreItem","constructor","maxConcurrent","this","queue","count","canAcquire","incrementCount","decrementCount","acquire","Promise","resolve","push","release","resolveFunc","shift","setTimeout","defaultKey","Semaphore","semaphoreInstances","hasSemaphoreInstance","key","Boolean","getSemaphoreInstance","tidy","hasTasks","request","fn","requestIfAvailable","GroupSemaphore","_semaphore","_activeCounts","_groupWaiters","_this$_activeCounts$k","_this$_groupWaiters$k","activeCount","waiter"],"mappings":"AAAA,MAAMA,EASFC,WAAAA,CAAYC,GAAqBC,KARzBC,WAAK,EAAAD,KACLD,mBAAa,EAAAC,KAKdE,WAGH,EAAAF,KAAKC,MAAQ,GACbD,KAAKD,cAAgBA,EACrBC,KAAKE,MAAQ,CACjB,CAEA,cAAIC,GACA,OAAOH,KAAKE,MAAQF,KAAKD,aAC7B,CAEQK,cAAAA,GACJJ,KAAKE,OACT,CAEQG,cAAAA,GACJL,KAAKE,OACT,CAEAI,OAAAA,GACI,OAAIN,KAAKG,YACLH,KAAKI,iBACEG,QAAQC,WAER,IAAID,QAASC,GAAYR,KAAKC,MAAMQ,KAAKD,GAExD,CAEAE,OAAAA,GACI,MAAMC,EAAcX,KAAKC,MAAMW,QAE3BD,EAEAE,WAAWF,EAAa,GAExBX,KAAKK,gBAEb,EAGJ,MAAMS,EAAa,WAEnB,MAAMC,EAOFjB,WAAAA,CAAYC,EAAwB,GAACC,KAN7BgB,wBAAkB,EAAAhB,KAClBD,mBAAa,EAMjBC,KAAKgB,mBAAqB,CAAA,EAC1BhB,KAAKD,cAAgBA,CACzB,CAEQkB,oBAAAA,CAAqBC,EAAuBJ,GAChD,OAAOK,QAAQnB,KAAKgB,mBAAmBE,GAC3C,CAEQE,oBAAAA,CAAqBF,EAAuBJ,GAMhD,OALKd,KAAKiB,qBAAqBC,KAC3BlB,KAAKgB,mBAAmBE,GAAO,IAAIrB,EAC/BG,KAAKD,gBAGFC,KAACgB,mBAAmBE,EACnC,CAKQG,IAAAA,CAAKH,EAAuBJ,GAE5Bd,KAAKiB,qBAAqBC,IACe,IAAzClB,KAAKoB,qBAAqBF,GAAKhB,cAExBF,KAAKgB,mBAAmBE,EAEvC,CASAf,UAAAA,CAAWe,EAAuBJ,GAC9B,OAAQd,KAAKiB,qBAAqBC,IAC9BlB,KAAKoB,qBAAqBF,GAAKf,UACvC,CAKAG,OAAAA,CAAQY,EAAuBJ,GAC3B,OAAWd,KAACoB,qBAAqBF,GAAKZ,SAC1C,CAKAI,OAAAA,CAAQQ,EAAuBJ,GAC3Bd,KAAKoB,qBAAqBF,GAAKR,UAC/BV,KAAKqB,KAAKH,EACd,CAOAhB,KAAAA,CAAMgB,EAAuBJ,GACzB,OAAId,KAAKiB,qBAAqBC,GACnBlB,KAAKoB,qBAAqBF,GAAKhB,MAGzC,CACL,CAMAoB,QAAAA,CAASJ,EAAuBJ,GAC5B,OAAWd,KAACE,MAAMgB,GAAO,CAC7B,CAOA,aAAMK,CACFC,EACAN,EAAuBJ,GAEvB,IAEI,aADUd,KAACM,QAAQY,SACNM,GAChB,CAAA,QACGxB,KAAKU,QAAQQ,EAChB,CACL,CAUA,wBAAMO,CACFD,EACAN,EAAuBJ,GAEvB,OAAId,KAAKG,WAAWe,GACLlB,KAACuB,QAAQC,EAAIN,GAEjB,IAEf,ECtJJ,MAAMQ,EAAc5B,WAAAA,GAAAE,KACR2B,WAAa,IAAIZ,OACjBa,cAAwC,CAAE,OAC1CC,cAA+C,CAAA,CAAE,CAEzD,aAAMvB,CAAQY,GAAW,IAAAY,EAAAC,EACrB,MAAMC,EAAqCF,OAA1BA,EAAG9B,KAAK4B,cAAcV,IAAIY,EAAI,EAC/C9B,KAAK4B,cAAcV,GAAOc,EAAc,EACxC,MAAMC,EAAgC,OAA1BF,EAAG/B,KAAK6B,cAAcX,IAAIa,EAAI/B,KAAK2B,WAAWrB,UAC1DN,KAAK6B,cAAcX,GAAOe,QACpBA,CACV,CAEAvB,OAAAA,CAAQQ,GACJ,MAAMc,EAAchC,KAAK4B,cAAcV,GAEnB,IAAhBc,GACAhC,KAAK2B,WAAWjB,iBACTV,KAAK4B,cAAcV,UACnBlB,KAAK6B,cAAcX,IAE1BlB,KAAK4B,cAAcV,GAAOc,EAAc,CAEhD"}

package/lib/promise-semaphore.module.js

@@ -1,2 +1,2 @@
-function e(e){var t=function(e){if("object"!=typeof e||!e)return e;var t=e[Symbol.toPrimitive];if(void 0!==t){var n=t.call(e,"string");if("object"!=typeof n)return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return String(e)}(e);return"symbol"==typeof t?t:t+""}var t=/*#__PURE__*/function(){function t(e){this.queue=void 0,this.maxConcurrent=void 0,this.count=void 0,this.queue=[],this.maxConcurrent=e,this.count=0}var n,r,i=t.prototype;return i.incrementCount=function(){this.count++},i.decrementCount=function(){this.count--},i.acquire=function(){var e=this;return this.canAcquire?(this.incrementCount(),Promise.resolve()):new Promise(function(t){return e.queue.push(t)})},i.release=function(){var e=this.queue.shift();e?setTimeout(e,0):this.decrementCount()},n=t,(r=[{key:"canAcquire",get:function(){return this.count<this.maxConcurrent}}])&&function(t,n){for(var r=0;r<n.length;r++){var i=n[r];i.enumerable=i.enumerable||!1,i.configurable=!0,"value"in i&&(i.writable=!0),Object.defineProperty(t,e(i.key),i)}}(n.prototype,r),Object.defineProperty(n,"prototype",{writable:!1}),n}(),n="_default",r=/*#__PURE__*/function(){function e(e){void 0===e&&(e=1),this.semaphoreInstances=void 0,this.maxConcurrent=void 0,this.semaphoreInstances={},this.maxConcurrent=e}var r=e.prototype;return r.hasSemaphoreInstance=function(e){return void 0===e&&(e=n),Boolean(this.semaphoreInstances[e])},r.getSemaphoreInstance=function(e){return void 0===e&&(e=n),this.hasSemaphoreInstance(e)||(this.semaphoreInstances[e]=new t(this.maxConcurrent)),this.semaphoreInstances[e]},r.tidy=function(e){void 0===e&&(e=n),this.hasSemaphoreInstance(e)&&0===this.getSemaphoreInstance(e).count&&delete this.semaphoreInstances[e]},r.canAcquire=function(e){return void 0===e&&(e=n),!this.hasSemaphoreInstance(e)||this.getSemaphoreInstance(e).canAcquire},r.acquire=function(e){return void 0===e&&(e=n),this.getSemaphoreInstance(e).acquire()},r.release=function(e){void 0===e&&(e=n),this.getSemaphoreInstance(e).release(),this.tidy(e)},r.count=function(e){return void 0===e&&(e=n),this.hasSemaphoreInstance(e)?this.getSemaphoreInstance(e).count:0},r.hasTasks=function(e){return void 0===e&&(e=n),this.count(e)>0},r.request=function(e,t){void 0===t&&(t=n);try{var r=this;return Promise.resolve(function(n,i){try{var o=Promise.resolve(r.acquire(t)).then(function(){return Promise.resolve(e())})}catch(e){return i(!0,e)}return o&&o.then?o.then(i.bind(null,!1),i.bind(null,!0)):i(!1,o)}(0,function(e,n){if(r.release(t),e)throw n;return n}))}catch(e){return Promise.reject(e)}},r.requestIfAvailable=function(e,t){void 0===t&&(t=n);try{return this.canAcquire(t)?Promise.resolve(this.request(e,t)):Promise.resolve(null)}catch(e){return Promise.reject(e)}},e}();export{r as Semaphore};
+function e(e){var t=function(e){if("object"!=typeof e||!e)return e;var t=e[Symbol.toPrimitive];if(void 0!==t){var n=t.call(e,"string");if("object"!=typeof n)return n;throw new TypeError("@@toPrimitive must return a primitive value.")}return String(e)}(e);return"symbol"==typeof t?t:t+""}var t=/*#__PURE__*/function(){function t(e){this.queue=void 0,this.maxConcurrent=void 0,this.count=void 0,this.queue=[],this.maxConcurrent=e,this.count=0}var n,r,i=t.prototype;return i.incrementCount=function(){this.count++},i.decrementCount=function(){this.count--},i.acquire=function(){var e=this;return this.canAcquire?(this.incrementCount(),Promise.resolve()):new Promise(function(t){return e.queue.push(t)})},i.release=function(){var e=this.queue.shift();e?setTimeout(e,0):this.decrementCount()},n=t,(r=[{key:"canAcquire",get:function(){return this.count<this.maxConcurrent}}])&&function(t,n){for(var r=0;r<n.length;r++){var i=n[r];i.enumerable=i.enumerable||!1,i.configurable=!0,"value"in i&&(i.writable=!0),Object.defineProperty(t,e(i.key),i)}}(n.prototype,r),Object.defineProperty(n,"prototype",{writable:!1}),n}(),n="_default",r=/*#__PURE__*/function(){function e(e){void 0===e&&(e=1),this.semaphoreInstances=void 0,this.maxConcurrent=void 0,this.semaphoreInstances={},this.maxConcurrent=e}var r=e.prototype;return r.hasSemaphoreInstance=function(e){return void 0===e&&(e=n),Boolean(this.semaphoreInstances[e])},r.getSemaphoreInstance=function(e){return void 0===e&&(e=n),this.hasSemaphoreInstance(e)||(this.semaphoreInstances[e]=new t(this.maxConcurrent)),this.semaphoreInstances[e]},r.tidy=function(e){void 0===e&&(e=n),this.hasSemaphoreInstance(e)&&0===this.getSemaphoreInstance(e).count&&delete this.semaphoreInstances[e]},r.canAcquire=function(e){return void 0===e&&(e=n),!this.hasSemaphoreInstance(e)||this.getSemaphoreInstance(e).canAcquire},r.acquire=function(e){return void 0===e&&(e=n),this.getSemaphoreInstance(e).acquire()},r.release=function(e){void 0===e&&(e=n),this.getSemaphoreInstance(e).release(),this.tidy(e)},r.count=function(e){return void 0===e&&(e=n),this.hasSemaphoreInstance(e)?this.getSemaphoreInstance(e).count:0},r.hasTasks=function(e){return void 0===e&&(e=n),this.count(e)>0},r.request=function(e,t){void 0===t&&(t=n);try{var r=this;return Promise.resolve(function(n,i){try{var o=Promise.resolve(r.acquire(t)).then(function(){return Promise.resolve(e())})}catch(e){return i(!0,e)}return o&&o.then?o.then(i.bind(null,!1),i.bind(null,!0)):i(!1,o)}(0,function(e,n){if(r.release(t),e)throw n;return n}))}catch(e){return Promise.reject(e)}},r.requestIfAvailable=function(e,t){void 0===t&&(t=n);try{return this.canAcquire(t)?Promise.resolve(this.request(e,t)):Promise.resolve(null)}catch(e){return Promise.reject(e)}},e}(),i=/*#__PURE__*/function(){function e(){this._semaphore=new r,this._activeCounts={},this._groupWaiters={}}var t=e.prototype;return t.acquire=function(e){try{var t,n,r=this,i=null!=(t=r._activeCounts[e])?t:0;r._activeCounts[e]=i+1;var o=null!=(n=r._groupWaiters[e])?n:r._semaphore.acquire();return r._groupWaiters[e]=o,Promise.resolve(o).then(function(){})}catch(e){return Promise.reject(e)}},t.release=function(e){var t=this._activeCounts[e];1===t?(this._semaphore.release(),delete this._activeCounts[e],delete this._groupWaiters[e]):this._activeCounts[e]=t-1},e}();export{i as GroupSemaphore,r as Semaphore};
 //# sourceMappingURL=promise-semaphore.module.js.map

package/lib/promise-semaphore.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"promise-semaphore.module.js","sources":["../src/index.ts"],"sourcesContent":["class SemaphoreItem {\n  private queue: Function[];\n  private maxConcurrent: number;\n\n  /**\n   * The number of locks.\n   */\n  public count: number;\n\n  constructor(maxConcurrent: number) {\n    this.queue = [];\n    this.maxConcurrent = maxConcurrent;\n    this.count = 0;\n  }\n\n  get canAcquire(): boolean {\n    return this.count < this.maxConcurrent;\n  }\n\n  private incrementCount() {\n    this.count++;\n  }\n\n  private decrementCount() {\n    this.count--;\n  }\n\n  acquire(): Promise<void> {\n    if (this.canAcquire) {\n      this.incrementCount();\n      return Promise.resolve();\n    } else {\n      return new Promise((resolve) => this.queue.push(resolve));\n    }\n  }\n\n  release(): void {\n    const resolveFunc = this.queue.shift();\n\n    if (resolveFunc) {\n      // Give the micro task queue a small break instead of calling resolveFunc() directly\n      setTimeout(resolveFunc, 0);\n    } else {\n      this.decrementCount();\n    }\n  }\n}\n\nconst defaultKey = \"_default\";\n\nclass Semaphore {\n  private semaphoreInstances: Record<string | number, SemaphoreItem>;\n  private maxConcurrent: number;\n\n  /**\n   * @param {number} [maxConcurrent] The maximum number of concurrent locks.\n   */\n  constructor(maxConcurrent: number = 1) {\n    this.semaphoreInstances = {};\n    this.maxConcurrent = maxConcurrent;\n  }\n\n  private hasSemaphoreInstance(key: string | number = defaultKey) {\n    return Boolean(this.semaphoreInstances[key]);\n  }\n\n  private getSemaphoreInstance(key: string | number = defaultKey) {\n    if (!this.hasSemaphoreInstance(key)) {\n      this.semaphoreInstances[key] = new SemaphoreItem(this.maxConcurrent);\n    }\n    return this.semaphoreInstances[key];\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  private tidy(key: string | number = defaultKey): void {\n    if (\n      this.hasSemaphoreInstance(key) &&\n      this.getSemaphoreInstance(key).count === 0\n    ) {\n      delete this.semaphoreInstances[key];\n    }\n  }\n\n  /**\n   * A synchronous function to determine whether a lock can be acquired.\n   *\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {boolean} Returns true if the lock on `key` can be acquired, false\n   * otherwise.\n   */\n  canAcquire(key: string | number = defaultKey): boolean {\n    return !this.hasSemaphoreInstance(key) ||\n      this.getSemaphoreInstance(key).canAcquire;\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  acquire(key: string | number = defaultKey) {\n    return this.getSemaphoreInstance(key).acquire();\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  release(key: string | number = defaultKey): void {\n    this.getSemaphoreInstance(key).release();\n    this.tidy(key);\n  }\n\n  /**\n   * The number of active locks.  Will always be less or equal to `max`.\n   *\n   * @param {string | number} [key]- Optional, the semaphore key.\n   */\n  count(key: string | number = defaultKey): number {\n    if (this.hasSemaphoreInstance(key)) {\n      return this.getSemaphoreInstance(key).count;\n    } else {\n      return 0;\n    }\n  }\n\n  /**\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {boolean} True if the semaphore and key has locks, false otherwise.\n   */\n  hasTasks(key: string | number = defaultKey): boolean {\n    return this.count(key) > 0;\n  }\n\n  /**\n   * @param {Function<T>} fn The function to execute.\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {Promise<T>}\n   */\n  async request<T>(\n    fn: Function,\n    key: string | number = defaultKey,\n  ): Promise<T> {\n    try {\n      await this.acquire(key);\n      return await fn();\n    } finally {\n      this.release(key);\n    }\n  }\n\n  /**\n   * Asynchronously executes `fn` if a lock can be immediately acquired.\n   * Otherwise, returns null.\n   *\n   * @param {Function<T>} fn The function to execute.\n   * @param {string | number} [key]- Optional, the semaphore key.\n   * @returns {Promise<T>}\n   */\n  async requestIfAvailable<T>(\n    fn: Function,\n    key: string | number = defaultKey,\n  ): Promise<T | null> {\n    if (this.canAcquire(key)) {\n      return this.request(fn, key);\n    } else {\n      return null;\n    }\n  }\n}\n\nexport { Semaphore };\n"],"names":["SemaphoreItem","maxConcurrent","queue","this","count","_proto","prototype","incrementCount","decrementCount","acquire","_this","canAcquire","Promise","resolve","push","release","resolveFunc","shift","setTimeout","key","get","defaultKey","Semaphore","semaphoreInstances","_proto2","hasSemaphoreInstance","Boolean","getSemaphoreInstance","tidy","hasTasks","request","fn","_this2","then","_finallyRethrows","_wasThrown","_result","e","reject","requestIfAvailable"],"mappings":"mSAAMA,eAAa,WASjB,SAAAA,EAAYC,GARJC,KAAAA,kBACAD,mBAAa,EAAAE,KAKdC,WAGL,EAAAD,KAAKD,MAAQ,GACbC,KAAKF,cAAgBA,EACrBE,KAAKC,MAAQ,CACf,CAAC,QAAAC,EAAAL,EAAAM,iBAAAD,EAMOE,eAAA,WACNJ,KAAKC,OACP,EAACC,EAEOG,eAAA,WACNL,KAAKC,OACP,EAACC,EAEDI,QAAA,WAAOC,IAAAA,OACL,OAAIP,KAAKQ,YACPR,KAAKI,iBACEK,QAAQC,eAEJD,QAAQ,SAACC,UAAYH,EAAKR,MAAMY,KAAKD,EAAQ,EAE5D,EAACR,EAEDU,QAAA,WACE,IAAMC,EAAcb,KAAKD,MAAMe,QAE3BD,EAEFE,WAAWF,EAAa,GAExBb,KAAKK,gBAET,IAACR,KAAAmB,CAAAA,CAAAA,iBAAAC,IA9BD,WACE,OAAOjB,KAAKC,MAAQD,KAAKF,aAC3B,iPA+BF,CAhDmB,GAgDboB,EAAa,WAEbC,eAAS,WAOb,SAAAA,EAAYrB,YAAAA,IAAAA,EAAwB,GAACE,KAN7BoB,wBACAtB,EAAAA,KAAAA,qBAMNE,KAAKoB,mBAAqB,CAAA,EAC1BpB,KAAKF,cAAgBA,CACvB,CAAC,IAAAuB,EAAAF,EAAAhB,iBAAAkB,EAEOC,qBAAA,SAAqBN,GAC3B,gBAD2BA,IAAAA,EAAuBE,GAC3CK,QAAQvB,KAAKoB,mBAAmBJ,GACzC,EAACK,EAEOG,qBAAA,SAAqBR,GAI3B,gBAJ2BA,IAAAA,EAAuBE,GAC7ClB,KAAKsB,qBAAqBN,KAC7BhB,KAAKoB,mBAAmBJ,GAAO,IAAInB,EAAcG,KAAKF,gBAEjDE,KAAKoB,mBAAmBJ,EACjC,EAACK,EAKOI,KAAA,SAAKT,YAAAA,IAAAA,EAAuBE,GAEhClB,KAAKsB,qBAAqBN,IACe,IAAzChB,KAAKwB,qBAAqBR,GAAKf,mBAEnBmB,mBAAmBJ,EAEnC,EAACK,EASDb,WAAA,SAAWQ,GACT,gBADSA,IAAAA,EAAuBE,IACxBlB,KAAKsB,qBAAqBN,IAChChB,KAAKwB,qBAAqBR,GAAKR,UACnC,EAACa,EAKDf,QAAA,SAAQU,GACN,gBADMA,IAAAA,EAAuBE,GACtBlB,KAAKwB,qBAAqBR,GAAKV,SACxC,EAACe,EAKDT,QAAA,SAAQI,QAAAA,IAAAA,IAAAA,EAAuBE,GAC7BlB,KAAKwB,qBAAqBR,GAAKJ,UAC/BZ,KAAKyB,KAAKT,EACZ,EAACK,EAODpB,MAAA,SAAMe,GACJ,YADIA,IAAAA,IAAAA,EAAuBE,GACvBlB,KAAKsB,qBAAqBN,GACjBhB,KAACwB,qBAAqBR,GAAKf,MAE/B,CAEX,EAACoB,EAMDK,SAAA,SAASV,GACP,gBADOA,IAAAA,EAAuBE,GACvBlB,KAAKC,MAAMe,GAAO,CAC3B,EAACK,EAOKM,iBACJC,EACAZ,QAAAA,IAAAA,IAAAA,EAAuBE,GAAU,QAAAW,EAGzB7B,KAAIS,OAAAA,QAAAC,gCADRD,QAAAC,QACImB,EAAKvB,QAAQU,IAAIc,uBAAArB,QAAAC,QACVkB,IAAI,4FADPG,CADR,EAGHC,SAAAA,EAAAC,GACmB,GAAlBJ,EAAKjB,QAAQI,GAAKgB,EAAAC,MAAAA,SAAAA,CAAA,GAEtB,CAAC,MAAAC,UAAAzB,QAAA0B,OAAAD,KAAAb,EAUKe,mBAAA,SACJR,EACAZ,QAAAA,IAAAA,IAAAA,EAAuBE,GAAU,IAEjC,OAAIlB,KAAKQ,WAAWQ,GAClBP,QAAAC,QADEV,KACU2B,QAAQC,EAAIZ,IAExBP,QAAAC,QAAO,KAEX,CAAC,MAAAwB,UAAAzB,QAAA0B,OAAAD,KAAAf,CAAA,CArHY"}
+{"version":3,"file":"promise-semaphore.module.js","sources":["../src/semaphore.ts","../src/group-semaphore.ts"],"sourcesContent":["class SemaphoreItem {\n    private queue: Function[];\n    private maxConcurrent: number;\n\n    /**\n     * The number of locks.\n     */\n    public count: number;\n\n    constructor(maxConcurrent: number) {\n        this.queue = [];\n        this.maxConcurrent = maxConcurrent;\n        this.count = 0;\n    }\n\n    get canAcquire(): boolean {\n        return this.count < this.maxConcurrent;\n    }\n\n    private incrementCount() {\n        this.count++;\n    }\n\n    private decrementCount() {\n        this.count--;\n    }\n\n    acquire(): Promise<void> {\n        if (this.canAcquire) {\n            this.incrementCount();\n            return Promise.resolve();\n        } else {\n            return new Promise((resolve) => this.queue.push(resolve));\n        }\n    }\n\n    release(): void {\n        const resolveFunc = this.queue.shift();\n\n        if (resolveFunc) {\n            // Give the micro task queue a small break instead of calling resolveFunc() directly\n            setTimeout(resolveFunc, 0);\n        } else {\n            this.decrementCount();\n        }\n    }\n}\n\nconst defaultKey = \"_default\";\n\nclass Semaphore {\n    private semaphoreInstances: Record<string | number, SemaphoreItem>;\n    private maxConcurrent: number;\n\n    /**\n     * @param {number} [maxConcurrent] The maximum number of concurrent locks.\n     */\n    constructor(maxConcurrent: number = 1) {\n        this.semaphoreInstances = {};\n        this.maxConcurrent = maxConcurrent;\n    }\n\n    private hasSemaphoreInstance(key: string | number = defaultKey) {\n        return Boolean(this.semaphoreInstances[key]);\n    }\n\n    private getSemaphoreInstance(key: string | number = defaultKey) {\n        if (!this.hasSemaphoreInstance(key)) {\n            this.semaphoreInstances[key] = new SemaphoreItem(\n                this.maxConcurrent,\n            );\n        }\n        return this.semaphoreInstances[key];\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    private tidy(key: string | number = defaultKey): void {\n        if (\n            this.hasSemaphoreInstance(key) &&\n            this.getSemaphoreInstance(key).count === 0\n        ) {\n            delete this.semaphoreInstances[key];\n        }\n    }\n\n    /**\n     * A synchronous function to determine whether a lock can be acquired.\n     *\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {boolean} Returns true if the lock on `key` can be acquired, false\n     * otherwise.\n     */\n    canAcquire(key: string | number = defaultKey): boolean {\n        return !this.hasSemaphoreInstance(key) ||\n            this.getSemaphoreInstance(key).canAcquire;\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    acquire(key: string | number = defaultKey) {\n        return this.getSemaphoreInstance(key).acquire();\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    release(key: string | number = defaultKey): void {\n        this.getSemaphoreInstance(key).release();\n        this.tidy(key);\n    }\n\n    /**\n     * The number of active locks.  Will always be less or equal to `max`.\n     *\n     * @param {string | number} [key]- Optional, the semaphore key.\n     */\n    count(key: string | number = defaultKey): number {\n        if (this.hasSemaphoreInstance(key)) {\n            return this.getSemaphoreInstance(key).count;\n        } else {\n            return 0;\n        }\n    }\n\n    /**\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {boolean} True if the semaphore and key has locks, false otherwise.\n     */\n    hasTasks(key: string | number = defaultKey): boolean {\n        return this.count(key) > 0;\n    }\n\n    /**\n     * @param {Function<T>} fn The function to execute.\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {Promise<T>}\n     */\n    async request<T>(\n        fn: Function,\n        key: string | number = defaultKey,\n    ): Promise<T> {\n        try {\n            await this.acquire(key);\n            return await fn();\n        } finally {\n            this.release(key);\n        }\n    }\n\n    /**\n     * Asynchronously executes `fn` if a lock can be immediately acquired.\n     * Otherwise, returns null.\n     *\n     * @param {Function<T>} fn The function to execute.\n     * @param {string | number} [key]- Optional, the semaphore key.\n     * @returns {Promise<T>}\n     */\n    async requestIfAvailable<T>(\n        fn: Function,\n        key: string | number = defaultKey,\n    ): Promise<T | null> {\n        if (this.canAcquire(key)) {\n            return this.request(fn, key);\n        } else {\n            return null;\n        }\n    }\n}\n\nexport { Semaphore };\n","import { Semaphore } from \"./semaphore\";\n\n/**\n * GroupSemaphore manages a shared semaphore for different groups of tasks. Each\n * group is identified by a unique key, and the semaphore ensures only one group\n * can run its tasks concurrently.\n *\n * - acquire(key): Increments the active count for the given group. If it's the\n *   first task for the group (active count is 0), it acquires the global\n *   semaphore, ensuring only one group's tasks can proceed at a time.\n *   Subsequent calls in the group increment the count and are permitted to run.\n * - release(key): Decrements the active count for the group. If the last task\n *   for that group is released, it releases the global semaphore, allowing\n *   other groups to proceed.\n *\n * This ensures that only one group can execute concurrently, but multiple tasks\n * within the same group can run as long as no other tasks from different groups\n * are active.\n */\nclass GroupSemaphore {\n    private _semaphore = new Semaphore();\n    private _activeCounts: Record<string, number> = {};\n    private _groupWaiters: Record<string, Promise<void>> = {};\n\n    async acquire(key: string) {\n        const activeCount = this._activeCounts[key] ?? 0;\n        this._activeCounts[key] = activeCount + 1;\n        const waiter = this._groupWaiters[key] ?? this._semaphore.acquire();\n        this._groupWaiters[key] = waiter;\n        await waiter;\n    }\n\n    release(key: string) {\n        const activeCount = this._activeCounts[key];\n\n        if (activeCount === 1) {\n            this._semaphore.release();\n            delete this._activeCounts[key];\n            delete this._groupWaiters[key];\n        } else {\n            this._activeCounts[key] = activeCount - 1;\n        }\n    }\n}\n\nexport { GroupSemaphore };\n"],"names":["SemaphoreItem","maxConcurrent","queue","this","count","_proto","prototype","incrementCount","decrementCount","acquire","_this","canAcquire","Promise","resolve","push","release","resolveFunc","shift","setTimeout","key","get","defaultKey","Semaphore","semaphoreInstances","_proto2","hasSemaphoreInstance","Boolean","getSemaphoreInstance","tidy","hasTasks","request","fn","_this2","then","_finallyRethrows","_wasThrown","_result","e","reject","requestIfAvailable","GroupSemaphore","_semaphore","_activeCounts","_groupWaiters","_this$_activeCounts$k","_this$_groupWaiters$k","activeCount","waiter"],"mappings":"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"}

package/lib/semaphore.d.ts

@@ -0,0 +1,57 @@
+declare class Semaphore {
+    private semaphoreInstances;
+    private maxConcurrent;
+    /**
+     * @param {number} [maxConcurrent] The maximum number of concurrent locks.
+     */
+    constructor(maxConcurrent?: number);
+    private hasSemaphoreInstance;
+    private getSemaphoreInstance;
+    /**
+     * @param {string | number} [key]- Optional, the semaphore key.
+     */
+    private tidy;
+    /**
+     * A synchronous function to determine whether a lock can be acquired.
+     *
+     * @param {string | number} [key]- Optional, the semaphore key.
+     * @returns {boolean} Returns true if the lock on `key` can be acquired, false
+     * otherwise.
+     */
+    canAcquire(key?: string | number): boolean;
+    /**
+     * @param {string | number} [key]- Optional, the semaphore key.
+     */
+    acquire(key?: string | number): Promise<void>;
+    /**
+     * @param {string | number} [key]- Optional, the semaphore key.
+     */
+    release(key?: string | number): void;
+    /**
+     * The number of active locks.  Will always be less or equal to `max`.
+     *
+     * @param {string | number} [key]- Optional, the semaphore key.
+     */
+    count(key?: string | number): number;
+    /**
+     * @param {string | number} [key]- Optional, the semaphore key.
+     * @returns {boolean} True if the semaphore and key has locks, false otherwise.
+     */
+    hasTasks(key?: string | number): boolean;
+    /**
+     * @param {Function<T>} fn The function to execute.
+     * @param {string | number} [key]- Optional, the semaphore key.
+     * @returns {Promise<T>}
+     */
+    request<T>(fn: Function, key?: string | number): Promise<T>;
+    /**
+     * Asynchronously executes `fn` if a lock can be immediately acquired.
+     * Otherwise, returns null.
+     *
+     * @param {Function<T>} fn The function to execute.
+     * @param {string | number} [key]- Optional, the semaphore key.
+     * @returns {Promise<T>}
+     */
+    requestIfAvailable<T>(fn: Function, key?: string | number): Promise<T | null>;
+}
+export { Semaphore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chriscdn/promise-semaphore",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Limit or throttle the simultaneous execution of asynchronous code in separate iterations of the event loop.",
   "repository": "https://github.com/chriscdn/promise-semaphore",
   "author": "Christopher Meyer <chris@schwiiz.org>",

package/src/group-semaphore.ts

@@ -0,0 +1,46 @@
+import { Semaphore } from "./semaphore";
+
+/**
+ * GroupSemaphore manages a shared semaphore for different groups of tasks. Each
+ * group is identified by a unique key, and the semaphore ensures only one group
+ * can run its tasks concurrently.
+ *
+ * - acquire(key): Increments the active count for the given group. If it's the
+ *   first task for the group (active count is 0), it acquires the global
+ *   semaphore, ensuring only one group's tasks can proceed at a time.
+ *   Subsequent calls in the group increment the count and are permitted to run.
+ * - release(key): Decrements the active count for the group. If the last task
+ *   for that group is released, it releases the global semaphore, allowing
+ *   other groups to proceed.
+ *
+ * This ensures that only one group can execute concurrently, but multiple tasks
+ * within the same group can run as long as no other tasks from different groups
+ * are active.
+ */
+class GroupSemaphore {
+    private _semaphore = new Semaphore();
+    private _activeCounts: Record<string, number> = {};
+    private _groupWaiters: Record<string, Promise<void>> = {};
+
+    async acquire(key: string) {
+        const activeCount = this._activeCounts[key] ?? 0;
+        this._activeCounts[key] = activeCount + 1;
+        const waiter = this._groupWaiters[key] ?? this._semaphore.acquire();
+        this._groupWaiters[key] = waiter;
+        await waiter;
+    }
+
+    release(key: string) {
+        const activeCount = this._activeCounts[key];
+
+        if (activeCount === 1) {
+            this._semaphore.release();
+            delete this._activeCounts[key];
+            delete this._groupWaiters[key];
+        } else {
+            this._activeCounts[key] = activeCount - 1;
+        }
+    }
+}
+
+export { GroupSemaphore };

package/src/index.ts

@@ -1,171 +1,2 @@
-class SemaphoreItem {
-  private queue: Function[];
-  private maxConcurrent: number;
-
-  /**
-   * The number of locks.
-   */
-  public count: number;
-
-  constructor(maxConcurrent: number) {
-    this.queue = [];
-    this.maxConcurrent = maxConcurrent;
-    this.count = 0;
-  }
-
-  get canAcquire(): boolean {
-    return this.count < this.maxConcurrent;
-  }
-
-  private incrementCount() {
-    this.count++;
-  }
-
-  private decrementCount() {
-    this.count--;
-  }
-
-  acquire(): Promise<void> {
-    if (this.canAcquire) {
-      this.incrementCount();
-      return Promise.resolve();
-    } else {
-      return new Promise((resolve) => this.queue.push(resolve));
-    }
-  }
-
-  release(): void {
-    const resolveFunc = this.queue.shift();
-
-    if (resolveFunc) {
-      // Give the micro task queue a small break instead of calling resolveFunc() directly
-      setTimeout(resolveFunc, 0);
-    } else {
-      this.decrementCount();
-    }
-  }
-}
-
-const defaultKey = "_default";
-
-class Semaphore {
-  private semaphoreInstances: Record<string | number, SemaphoreItem>;
-  private maxConcurrent: number;
-
-  /**
-   * @param {number} [maxConcurrent] The maximum number of concurrent locks.
-   */
-  constructor(maxConcurrent: number = 1) {
-    this.semaphoreInstances = {};
-    this.maxConcurrent = maxConcurrent;
-  }
-
-  private hasSemaphoreInstance(key: string | number = defaultKey) {
-    return Boolean(this.semaphoreInstances[key]);
-  }
-
-  private getSemaphoreInstance(key: string | number = defaultKey) {
-    if (!this.hasSemaphoreInstance(key)) {
-      this.semaphoreInstances[key] = new SemaphoreItem(this.maxConcurrent);
-    }
-    return this.semaphoreInstances[key];
-  }
-
-  /**
-   * @param {string | number} [key]- Optional, the semaphore key.
-   */
-  private tidy(key: string | number = defaultKey): void {
-    if (
-      this.hasSemaphoreInstance(key) &&
-      this.getSemaphoreInstance(key).count === 0
-    ) {
-      delete this.semaphoreInstances[key];
-    }
-  }
-
-  /**
-   * A synchronous function to determine whether a lock can be acquired.
-   *
-   * @param {string | number} [key]- Optional, the semaphore key.
-   * @returns {boolean} Returns true if the lock on `key` can be acquired, false
-   * otherwise.
-   */
-  canAcquire(key: string | number = defaultKey): boolean {
-    return !this.hasSemaphoreInstance(key) ||
-      this.getSemaphoreInstance(key).canAcquire;
-  }
-
-  /**
-   * @param {string | number} [key]- Optional, the semaphore key.
-   */
-  acquire(key: string | number = defaultKey) {
-    return this.getSemaphoreInstance(key).acquire();
-  }
-
-  /**
-   * @param {string | number} [key]- Optional, the semaphore key.
-   */
-  release(key: string | number = defaultKey): void {
-    this.getSemaphoreInstance(key).release();
-    this.tidy(key);
-  }
-
-  /**
-   * The number of active locks.  Will always be less or equal to `max`.
-   *
-   * @param {string | number} [key]- Optional, the semaphore key.
-   */
-  count(key: string | number = defaultKey): number {
-    if (this.hasSemaphoreInstance(key)) {
-      return this.getSemaphoreInstance(key).count;
-    } else {
-      return 0;
-    }
-  }
-
-  /**
-   * @param {string | number} [key]- Optional, the semaphore key.
-   * @returns {boolean} True if the semaphore and key has locks, false otherwise.
-   */
-  hasTasks(key: string | number = defaultKey): boolean {
-    return this.count(key) > 0;
-  }
-
-  /**
-   * @param {Function<T>} fn The function to execute.
-   * @param {string | number} [key]- Optional, the semaphore key.
-   * @returns {Promise<T>}
-   */
-  async request<T>(
-    fn: Function,
-    key: string | number = defaultKey,
-  ): Promise<T> {
-    try {
-      await this.acquire(key);
-      return await fn();
-    } finally {
-      this.release(key);
-    }
-  }
-
-  /**
-   * Asynchronously executes `fn` if a lock can be immediately acquired.
-   * Otherwise, returns null.
-   *
-   * @param {Function<T>} fn The function to execute.
-   * @param {string | number} [key]- Optional, the semaphore key.
-   * @returns {Promise<T>}
-   */
-  async requestIfAvailable<T>(
-    fn: Function,
-    key: string | number = defaultKey,
-  ): Promise<T | null> {
-    if (this.canAcquire(key)) {
-      return this.request(fn, key);
-    } else {
-      return null;
-    }
-  }
-}
-
-export { Semaphore };
+export { Semaphore } from "./semaphore";
+export { GroupSemaphore } from "./group-semaphore";

package/src/semaphore.ts

@@ -0,0 +1,173 @@
+class SemaphoreItem {
+    private queue: Function[];
+    private maxConcurrent: number;
+
+    /**
+     * The number of locks.
+     */
+    public count: number;
+
+    constructor(maxConcurrent: number) {
+        this.queue = [];
+        this.maxConcurrent = maxConcurrent;
+        this.count = 0;
+    }
+
+    get canAcquire(): boolean {
+        return this.count < this.maxConcurrent;
+    }
+
+    private incrementCount() {
+        this.count++;
+    }
+
+    private decrementCount() {
+        this.count--;
+    }
+
+    acquire(): Promise<void> {
+        if (this.canAcquire) {
+            this.incrementCount();
+            return Promise.resolve();
+        } else {
+            return new Promise((resolve) => this.queue.push(resolve));
+        }
+    }
+
+    release(): void {
+        const resolveFunc = this.queue.shift();
+
+        if (resolveFunc) {
+            // Give the micro task queue a small break instead of calling resolveFunc() directly
+            setTimeout(resolveFunc, 0);
+        } else {
+            this.decrementCount();
+        }
+    }
+}
+
+const defaultKey = "_default";
+
+class Semaphore {
+    private semaphoreInstances: Record<string | number, SemaphoreItem>;
+    private maxConcurrent: number;
+
+    /**
+     * @param {number} [maxConcurrent] The maximum number of concurrent locks.
+     */
+    constructor(maxConcurrent: number = 1) {
+        this.semaphoreInstances = {};
+        this.maxConcurrent = maxConcurrent;
+    }
+
+    private hasSemaphoreInstance(key: string | number = defaultKey) {
+        return Boolean(this.semaphoreInstances[key]);
+    }
+
+    private getSemaphoreInstance(key: string | number = defaultKey) {
+        if (!this.hasSemaphoreInstance(key)) {
+            this.semaphoreInstances[key] = new SemaphoreItem(
+                this.maxConcurrent,
+            );
+        }
+        return this.semaphoreInstances[key];
+    }
+
+    /**
+     * @param {string | number} [key]- Optional, the semaphore key.
+     */
+    private tidy(key: string | number = defaultKey): void {
+        if (
+            this.hasSemaphoreInstance(key) &&
+            this.getSemaphoreInstance(key).count === 0
+        ) {
+            delete this.semaphoreInstances[key];
+        }
+    }
+
+    /**
+     * A synchronous function to determine whether a lock can be acquired.
+     *
+     * @param {string | number} [key]- Optional, the semaphore key.
+     * @returns {boolean} Returns true if the lock on `key` can be acquired, false
+     * otherwise.
+     */
+    canAcquire(key: string | number = defaultKey): boolean {
+        return !this.hasSemaphoreInstance(key) ||
+            this.getSemaphoreInstance(key).canAcquire;
+    }
+
+    /**
+     * @param {string | number} [key]- Optional, the semaphore key.
+     */
+    acquire(key: string | number = defaultKey) {
+        return this.getSemaphoreInstance(key).acquire();
+    }
+
+    /**
+     * @param {string | number} [key]- Optional, the semaphore key.
+     */
+    release(key: string | number = defaultKey): void {
+        this.getSemaphoreInstance(key).release();
+        this.tidy(key);
+    }
+
+    /**
+     * The number of active locks.  Will always be less or equal to `max`.
+     *
+     * @param {string | number} [key]- Optional, the semaphore key.
+     */
+    count(key: string | number = defaultKey): number {
+        if (this.hasSemaphoreInstance(key)) {
+            return this.getSemaphoreInstance(key).count;
+        } else {
+            return 0;
+        }
+    }
+
+    /**
+     * @param {string | number} [key]- Optional, the semaphore key.
+     * @returns {boolean} True if the semaphore and key has locks, false otherwise.
+     */
+    hasTasks(key: string | number = defaultKey): boolean {
+        return this.count(key) > 0;
+    }
+
+    /**
+     * @param {Function<T>} fn The function to execute.
+     * @param {string | number} [key]- Optional, the semaphore key.
+     * @returns {Promise<T>}
+     */
+    async request<T>(
+        fn: Function,
+        key: string | number = defaultKey,
+    ): Promise<T> {
+        try {
+            await this.acquire(key);
+            return await fn();
+        } finally {
+            this.release(key);
+        }
+    }
+
+    /**
+     * Asynchronously executes `fn` if a lock can be immediately acquired.
+     * Otherwise, returns null.
+     *
+     * @param {Function<T>} fn The function to execute.
+     * @param {string | number} [key]- Optional, the semaphore key.
+     * @returns {Promise<T>}
+     */
+    async requestIfAvailable<T>(
+        fn: Function,
+        key: string | number = defaultKey,
+    ): Promise<T | null> {
+        if (this.canAcquire(key)) {
+            return this.request(fn, key);
+        } else {
+            return null;
+        }
+    }
+}
+
+export { Semaphore };