@chriscdn/promise-semaphore 1.0.9 → 2.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Christopher Meyer
+Copyright (c) 2021-2023 Christopher Meyer
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -16,16 +16,20 @@ Using yarn:
 $ yarn add @chriscdn/promise-semaphore
 ```
 
+## Updating v1 to v2
+
+Version 2 adds TypeScript and better inline documentation. The API remains the same, and doesn't introduce any breaking changes.
+
 ## API
 
 ### Create an instance
 
 ```js
-const Semaphore = require('@chriscdn/promise-semaphore')
+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*).  Use an integer value greater than one to limit how many times the code block can be simultaneously executing from separate iterations of the event loop.
+The `maxConcurrent` parameter is optional, and defaults to `1` (making it an exclusive lock or _binary semaphore_). Use an integer value greater than one to limit how many times the code block can be simultaneously executing from separate iterations of the event loop.
 
 ### Acquire a lock
 
@@ -33,7 +37,7 @@ The `maxConcurrent` parameter is optional, and defaults to `1` (making it an exc
 semaphore.acquire([key])
 ```
 
-This returns a `Promise`, which resolves once a lock has been acquired.  The `key` parameter is optional and permits the same `Semaphore` instance to be used in different contexts.  See the second example.
+This returns a `Promise`, which resolves once a lock has been acquired. The `key` parameter is optional and permits the same `Semaphore` instance to be used in different contexts. See the second example.
 
 ### Release a lock
 
@@ -57,14 +61,14 @@ This method is synchronous, and returns `true` if a lock can be immediately acqu
 const results = await semaphore.request(fn [,key])
 ```
 
-This function reduces boilerplate when using `acquire` and `release`.  It returns a promise, which resolves once `fn` has completed.  It is functionally equivalent to:
+This function reduces boilerplate when using `acquire` and `release`. It returns a promise, which resolves once `fn` has completed. It is functionally equivalent to:
 
 ```js
 try {
-	await semaphore.acquire([key])
-	const results = await fn()
+  await semaphore.acquire([key])
+  const results = await fn()
 } finally {
-	semaphore.release([key])
+  semaphore.release([key])
 }
 ```
 
@@ -84,99 +88,88 @@ const results = semaphore.canAcquire([key] ?
 	null
 ```
 
-This is useful in situations where only one instance of a function block should run at a time, while discarding other attempts to execute the block.  E.g., a button that is being repeatedly tapped or clicked by the user.
+This is useful in situations where only one instance of a function block should run at a time, while discarding other attempts to execute the block. E.g., a button is repeatedly clicked.
 
 ## Example 1
 
 ```js
-const Semaphore = require('@chriscdn/promise-semaphore')
+import Semaphore from '@chriscdn/promise-semaphore'
 const semaphore = new Semaphore()
 
 // using promises
-semaphore.acquire()
-	.then(() => {
-		// This block executes once a lock has been acquired.  If already 
-		// locked then this block will wait and execute once all preceeding
-		// locks have been released.
-		
-		// do your critical stuff here
-		
-	})
-	.finally(() => {
-		// release the lock permitting the next queued block to continue
-		semaphore.release()
-	})
-
+semaphore
+  .acquire()
+  .then(() => {
+    // This block executes once a lock is acquired.  If already locked,
+    // then wait and execute once all preceeding locks have been released.
+    //
+    // do your critical stuff here
+  })
+  .finally(() => {
+    // release the lock permitting the next queued block to continue
+    semaphore.release()
+  })
 
 // or, using async/await
 try {
-	await semaphore.acquire()
-	
-	// do your critical stuff here
-	
+  await semaphore.acquire()
+
+  // do your critical stuff here
 } finally {
-	semaphore.release()
+  semaphore.release()
 }
 
-
 // or, using the request function
 semaphore.request(() => {
-
-	// do your critical stuff here
-
+  // do your critical stuff here
 })
-
 ```
 
 ## Example 2
 
-Say you have an asynchronous function to download a file and save it to disk
+Say you have an asynchronous function to download a file and save it to disk:
 
 ```js
 async function downloadAndSave(url) {
+  const filePath = urlToFilePath(url)
 
-	const filePath = urlToFilePath(url)
+  if (await pathExists(filePath)) {
+    // the file is on disk, so no action is required
+  } else {
+    await downloadAndSaveToFilepath(url, filePath)
+  }
 
-	if (await pathExists(filePath)) {
-		// the file is on disk, so no action is required
-	} else {
-		await downloadToFile(url, filePath)
-	}
-
-	return filePath
+  return filePath
 }
 ```
 
-This works until a process calls `downloadAndSave()` in short succession with the same `url` parameter. This can cause multiple simultaneous downloads that attempt to write to the same file.
+This works until a process calls `downloadAndSave()` multiple times in short succession with the same `url`. This can cause multiple simultaneous downloads that attempt to write to the same file at the same time.
 
 This can be resolved with a `Semaphore` instance using the `key` parameter:
 
 ```js
-const Semaphore = require('@chriscdn/promise-semaphore')
+import Semaphore from '@chriscdn/promise-semaphore'
 const semaphore = new Semaphore()
 
 async function downloadAndSave(url) {
+  try {
+    await semaphore.acquire(url)
 
-	try {
-	
-		await semaphore.acquire(url)
+    // This block continues once a lock on url is acquired.  This
+    // permits multiple simulataneous downloads for different urls.
 
-		// This block continues once a lock on url is acquired.  This permits
-		// multiple simulataneous downloads for each unique url.
-	
-		const filePath = urlToFilePath(url)
-	
-		if (await pathExists(filePath)) {
-			// the file is on disk, so no action is required
-		} else {
-			await downloadToFile(url, filePath)
-		}
-	
-		return filePath
+    const filePath = urlToFilePath(url)
 
-	} finally {
-		semaphore.release(url)
-	}
+    if (await pathExists(filePath)) {
+      // the file is on disk, so no action is required
+    } else {
+      await downloadAndSaveToFilepath(url, filePath)
+    }
+
+    return filePath
+  } finally {
+    semaphore.release(url)
+  }
 }
 ```
 
@@ -187,14 +180,14 @@ async function downloadAndSave(url) {
 
 	return semaphore.request(() => {
 		const filePath = urlToFilePath(url)
-	
+
 		if (await pathExists(filePath)) {
 			// the file is on disk, so no action is required
 		} else {
-			await downloadToFile(url, filePath)
+			await downloadAndSaveToFilepath(url, filePath)
 		}
-	
-		return filePath	
+
+		return filePath
 	}, url)
 
 }
@@ -202,4 +195,4 @@ async function downloadAndSave(url) {
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE)

package/__tests__/semaphore.test.ts

@@ -0,0 +1,143 @@
+import Semaphore from '../src/index'
+
+const pause = async (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+test('Acquire & Release Basic', async () => {
+  const semaphore = new Semaphore()
+  expect(semaphore.canAcquire()).toBe(true)
+  await semaphore.acquire()
+  expect(semaphore.canAcquire()).toBe(false)
+  expect(semaphore.hasTasks()).toBe(true)
+  expect(semaphore.count()).toBe(1)
+  semaphore.release()
+  expect(semaphore.canAcquire()).toBe(true)
+  expect(semaphore.count()).toBe(0)
+})
+
+test('Semaphore 1', async () => {
+  const semaphore = new Semaphore()
+
+  semaphore
+    .acquire()
+    .then(async () => await pause(1000))
+    .finally(() => semaphore.release())
+
+  expect(semaphore.canAcquire()).toBe(false)
+
+  await pause(600)
+
+  expect(semaphore.canAcquire()).toBe(false)
+
+  await pause(600)
+
+  expect(semaphore.canAcquire()).toBe(true)
+})
+
+test('Semaphore 2', async () => {
+  const semaphore = new Semaphore()
+
+  let tester = 0
+
+  semaphore
+    .acquire()
+    .then(() => pause(1000))
+    .then(() => (tester = 10))
+    .finally(() => semaphore.release())
+
+  // tests acquire waits for previous to complete
+  await semaphore
+    .acquire()
+    .then(() => expect(tester).toBe(10))
+    .finally(() => semaphore.release())
+})
+
+test('Semaphore 3', async () => {
+  const semaphore = new Semaphore(2)
+
+  let tester = 0
+
+  semaphore
+    .acquire()
+    .then(() => pause(1000))
+    .then(() => (tester = 20))
+    .finally(() => semaphore.release())
+
+  semaphore
+    .acquire()
+    .then(() => pause(500))
+    .then(() => (tester = 10))
+    .finally(() => semaphore.release())
+
+  expect(semaphore.count()).toBe(2)
+  expect(semaphore.hasTasks()).toBe(true)
+
+  // expect 10 since this next block will run before the first has completed
+  await semaphore
+    .acquire()
+    .then(() => expect(tester).toBe(10))
+    .finally(() => semaphore.release())
+
+  expect(semaphore.count()).toBe(1)
+  expect(semaphore.hasTasks()).toBe(true)
+  expect(semaphore.canAcquire()).toBe(true)
+})
+
+test('Request 1', async () => {
+  const semaphore = new Semaphore()
+
+  let tester = 0
+
+  semaphore.request(async () => {
+    await pause(1000)
+    tester = 20
+  })
+
+  semaphore.request(async () => {
+    await pause(500)
+    tester = 10
+  })
+
+  await semaphore.request(async () => {
+    expect(tester).toBe(10)
+  })
+})
+
+test('Request 2', async () => {
+  const semaphore = new Semaphore(2)
+
+  let tester = 0
+
+  semaphore.request(async () => {
+    await pause(1000)
+    tester = 20
+  })
+
+  semaphore.request(async () => {
+    await pause(500)
+    tester = 10
+  })
+
+  await semaphore.request(async () => {
+    expect(tester).toBe(10)
+  })
+})
+
+test('Request 3', async () => {
+  const semaphore = new Semaphore(3)
+
+  let tester = 0
+
+  semaphore.request(async () => {
+    await pause(1000)
+    tester = 20
+  })
+
+  semaphore.request(async () => {
+    await pause(500)
+    tester = 10
+  })
+
+  await semaphore.request(async () => {
+    expect(tester).toBe(0)
+  })
+})

package/jest.config.js

@@ -0,0 +1,5 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+};

package/lib/index.cjs.js

@@ -1,101 +1,139 @@
 'use strict';
 
 class SemaphoreItem {
-  constructor(max) {
+  queue;
+  maxConcurrent;
+  /**
+   * The number of locks.
+   */
+  count;
+  constructor(maxConcurrent) {
     this.queue = [];
-    this.max = max;
+    this.maxConcurrent = maxConcurrent;
     this.count = 0;
   }
-
   get canAcquire() {
-    return this.count < this.max
+    return this.count < this.maxConcurrent;
   }
-
   acquire() {
     if (this.canAcquire) {
       this.count++;
-      return Promise.resolve()
+      return Promise.resolve();
     } else {
-      return new Promise((resolve) => {
-        this.queue.push(resolve);
-      })
+      return new Promise((resolve) => this.queue.push(resolve));
     }
   }
-
   release() {
     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.count--;
     }
   }
 }
-
-const defaultKey = '_default';
-
+const defaultKey = "_default";
 class Semaphore {
-  constructor(max = 1) {
-    this.semaphoreItems = {};
-    this.max = max;
+  semaphoreInstances;
+  maxConcurrent;
+  /**
+   *
+   * @param {number} [maxConcurrent] The maximum number of concurrent locks.
+   */
+  constructor(maxConcurrent = 1) {
+    this.semaphoreInstances = {};
+    this.maxConcurrent = maxConcurrent;
   }
-
-  _getSemaphoreInstance(key = defaultKey) {
-    if (!this.semaphoreItems[key]) {
-      this.semaphoreItems[key] = new SemaphoreItem(this.max);
+  hasSemaphoreInstance(key = defaultKey) {
+    return Boolean(this.semaphoreInstances[key]);
+  }
+  getSemaphoreInstance(key = defaultKey) {
+    if (!this.hasSemaphoreInstance(key)) {
+      this.semaphoreInstances[key] = new SemaphoreItem(this.maxConcurrent);
     }
-    return this.semaphoreItems[key]
+    return this.semaphoreInstances[key];
   }
-
-  _tidy(key = defaultKey) {
-    if (this._getSemaphoreInstance(key).count == 0) {
-      delete this.semaphoreItems[key];
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   */
+  tidy(key = defaultKey) {
+    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 = defaultKey) {
-    return this._getSemaphoreInstance(key).canAcquire
+    return this.getSemaphoreInstance(key).canAcquire;
   }
-
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   */
   acquire(key = defaultKey) {
-    return this._getSemaphoreInstance(key).acquire()
+    return this.getSemaphoreInstance(key).acquire();
   }
-
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   */
   release(key = defaultKey) {
-    this._getSemaphoreInstance(key).release();
-    this._tidy(key);
+    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 = defaultKey) {
-    if (this.semaphoreItems[key]) {
-      return this.semaphoreItems[key].count
+    if (this.hasSemaphoreInstance(key)) {
+      return this.getSemaphoreInstance(key).count;
     } else {
-      return 0
+      return 0;
     }
   }
-
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   * @returns {boolean} True if the semaphore and key has locks, false otherwise.
+   */
   hasTasks(key = defaultKey) {
-    return this.count(key) > 0
+    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(fn, key = defaultKey) {
     try {
       await this.acquire(key);
-      return await fn()
+      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(fn, key = defaultKey) {
     if (this.canAcquire(key)) {
-      return this.request(fn, key)
+      return this.request(fn, key);
     } else {
-      // Use canAcquire if you need to know if a function will be dismissed due
-      // to an existing lock.
-      return null
+      return null;
     }
   }
 }

package/lib/index.d.ts

@@ -0,0 +1,64 @@
+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 as default };

package/lib/index.es.js

@@ -1,103 +1,139 @@
 class SemaphoreItem {
-  constructor(max) {
+  queue;
+  maxConcurrent;
+  /**
+   * The number of locks.
+   */
+  count;
+  constructor(maxConcurrent) {
     this.queue = [];
-    this.max = max;
+    this.maxConcurrent = maxConcurrent;
     this.count = 0;
   }
-
   get canAcquire() {
-    return this.count < this.max
+    return this.count < this.maxConcurrent;
   }
-
   acquire() {
     if (this.canAcquire) {
       this.count++;
-      return Promise.resolve()
+      return Promise.resolve();
     } else {
-      return new Promise((resolve) => {
-        this.queue.push(resolve);
-      })
+      return new Promise((resolve) => this.queue.push(resolve));
     }
   }
-
   release() {
     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.count--;
     }
   }
 }
-
-const defaultKey = '_default';
-
+const defaultKey = "_default";
 class Semaphore {
-  constructor(max = 1) {
-    this.semaphoreItems = {};
-    this.max = max;
+  semaphoreInstances;
+  maxConcurrent;
+  /**
+   *
+   * @param {number} [maxConcurrent] The maximum number of concurrent locks.
+   */
+  constructor(maxConcurrent = 1) {
+    this.semaphoreInstances = {};
+    this.maxConcurrent = maxConcurrent;
   }
-
-  _getSemaphoreInstance(key = defaultKey) {
-    if (!this.semaphoreItems[key]) {
-      this.semaphoreItems[key] = new SemaphoreItem(this.max);
+  hasSemaphoreInstance(key = defaultKey) {
+    return Boolean(this.semaphoreInstances[key]);
+  }
+  getSemaphoreInstance(key = defaultKey) {
+    if (!this.hasSemaphoreInstance(key)) {
+      this.semaphoreInstances[key] = new SemaphoreItem(this.maxConcurrent);
     }
-    return this.semaphoreItems[key]
+    return this.semaphoreInstances[key];
   }
-
-  _tidy(key = defaultKey) {
-    if (this._getSemaphoreInstance(key).count == 0) {
-      delete this.semaphoreItems[key];
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   */
+  tidy(key = defaultKey) {
+    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 = defaultKey) {
-    return this._getSemaphoreInstance(key).canAcquire
+    return this.getSemaphoreInstance(key).canAcquire;
   }
-
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   */
   acquire(key = defaultKey) {
-    return this._getSemaphoreInstance(key).acquire()
+    return this.getSemaphoreInstance(key).acquire();
   }
-
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   */
   release(key = defaultKey) {
-    this._getSemaphoreInstance(key).release();
-    this._tidy(key);
+    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 = defaultKey) {
-    if (this.semaphoreItems[key]) {
-      return this.semaphoreItems[key].count
+    if (this.hasSemaphoreInstance(key)) {
+      return this.getSemaphoreInstance(key).count;
     } else {
-      return 0
+      return 0;
     }
   }
-
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   * @returns {boolean} True if the semaphore and key has locks, false otherwise.
+   */
   hasTasks(key = defaultKey) {
-    return this.count(key) > 0
+    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(fn, key = defaultKey) {
     try {
       await this.acquire(key);
-      return await fn()
+      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(fn, key = defaultKey) {
     if (this.canAcquire(key)) {
-      return this.request(fn, key)
+      return this.request(fn, key);
     } else {
-      // Use canAcquire if you need to know if a function will be dismissed due
-      // to an existing lock.
-      return null
+      return null;
     }
   }
 }
 
-var src = Semaphore;
-
-export { src as default };
+export { Semaphore as default };

package/package.json

@@ -1,23 +1,34 @@
 {
   "name": "@chriscdn/promise-semaphore",
-  "version": "1.0.9",
+  "version": "2.0.1",
   "description": "Limit or throttle the simultaneous execution of asynchronous code in separate iterations of the event loop.",
   "main": "lib/index.cjs.js",
   "module": "lib/index.es.js",
+  "types": "lib/index.d.ts",
   "repository": "https://github.com/chriscdn/promise-semaphore",
   "author": "Christopher Meyer <chris@schwiiz.org>",
   "license": "MIT",
   "scripts": {
-    "build": "rollup -c"
+    "build": "rollup -c",
+    "watch": "rollup -c --watch",
+    "test": "jest"
   },
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^21.0.2"
+    "@types/jest": "^29.4.0",
+    "esbuild": "^0.17.10",
+    "jest": "^29.4.3",
+    "rollup": "^3.17.3",
+    "rollup-plugin-dts": "^5.2.0",
+    "rollup-plugin-esbuild": "^5.0.0",
+    "ts-jest": "^29.0.5",
+    "typescript": "^4.9.5"
   },
   "keywords": [
     "promise",
     "semaphore",
     "lock",
     "mutex",
-    "async"
+    "async",
+    "throttle"
   ]
 }

package/rollup.config.mjs

@@ -0,0 +1,40 @@
+import pkg from './package.json' assert { type: 'json' }
+import dts from 'rollup-plugin-dts'
+import esbuild from 'rollup-plugin-esbuild'
+
+const input = 'src/index.ts'
+
+export default [
+  {
+    input,
+    plugins: [esbuild()],
+    output: [
+      {
+        file: pkg.main,
+        format: 'cjs',
+        // sourcemap: true,
+        // exports: 'default',
+      },
+    ],
+  },
+  {
+    input,
+    plugins: [esbuild()],
+    output: [
+      {
+        file: pkg.module,
+        format: 'es',
+        // sourcemap: true,
+        // exports: 'default',
+      },
+    ],
+  },
+  {
+    input,
+    plugins: [dts()],
+    output: {
+      file: 'lib/index.d.ts',
+      format: 'es',
+    },
+  },
+]

package/src/index.ts

@@ -0,0 +1,168 @@
+class SemaphoreItem {
+  private queue: Array<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
+  }
+
+  acquire(): Promise<void> {
+    if (this.canAcquire) {
+      this.count++
+      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)
+      // resolveFunc()
+    } else {
+      this.count--
+    }
+  }
+}
+
+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.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 default Semaphore

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "esModuleInterop": true
+  }
+}

package/rollup.config.js

@@ -1,19 +0,0 @@
-import pkg from './package.json'
-import commonjs from '@rollup/plugin-commonjs'
-
-export default [{
-	input: 'src/index.js',
-	output: [{
-		file: pkg.main,
-		format: 'cjs'
-	}]
-}, {
-	input: 'src/index.js',
-	output: [{
-		file: pkg.module,
-		format: 'es'
-	}],
-	plugins: [
-		commonjs()
-	]
-}]

package/src/index.js

@@ -1,101 +0,0 @@
-class SemaphoreItem {
-  constructor(max) {
-    this.queue = []
-    this.max = max
-    this.count = 0
-  }
-
-  get canAcquire() {
-    return this.count < this.max
-  }
-
-  acquire() {
-    if (this.canAcquire) {
-      this.count++
-      return Promise.resolve()
-    } else {
-      return new Promise((resolve) => {
-        this.queue.push(resolve)
-      })
-    }
-  }
-
-  release() {
-    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.count--
-    }
-  }
-}
-
-const defaultKey = '_default'
-
-class Semaphore {
-  constructor(max = 1) {
-    this.semaphoreItems = {}
-    this.max = max
-  }
-
-  _getSemaphoreInstance(key = defaultKey) {
-    if (!this.semaphoreItems[key]) {
-      this.semaphoreItems[key] = new SemaphoreItem(this.max)
-    }
-    return this.semaphoreItems[key]
-  }
-
-  _tidy(key = defaultKey) {
-    if (this._getSemaphoreInstance(key).count == 0) {
-      delete this.semaphoreItems[key]
-    }
-  }
-
-  canAcquire(key = defaultKey) {
-    return this._getSemaphoreInstance(key).canAcquire
-  }
-
-  acquire(key = defaultKey) {
-    return this._getSemaphoreInstance(key).acquire()
-  }
-
-  release(key = defaultKey) {
-    this._getSemaphoreInstance(key).release()
-    this._tidy(key)
-  }
-
-  count(key = defaultKey) {
-    if (this.semaphoreItems[key]) {
-      return this.semaphoreItems[key].count
-    } else {
-      return 0
-    }
-  }
-
-  hasTasks(key = defaultKey) {
-    return this.count(key) > 0
-  }
-
-  async request(fn, key = defaultKey) {
-    try {
-      await this.acquire(key)
-      return await fn()
-    } finally {
-      this.release(key)
-    }
-  }
-
-  async requestIfAvailable(fn, key = defaultKey) {
-    if (this.canAcquire(key)) {
-      return this.request(fn, key)
-    } else {
-      // Use canAcquire if you need to know if a function will be dismissed due
-      // to an existing lock.
-      return null
-    }
-  }
-}
-
-module.exports = Semaphore