@chriscdn/promise-semaphore 1.0.6 → 2.0.0

package/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "semi": false,
+  "singleQuote": true
+}

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 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
 
@@ -43,82 +47,152 @@ semaphore.release([key])
 
 The `release` call should be executed from a `finally` block (whether using promises or a try/catch block) to guarantee it gets called.
 
+### Check if a lock can be acquired
+
+```js
+semaphore.canAcquire([key])
+```
+
+This method is synchronous, and returns `true` if a lock can be immediately acquired, `false` otherwise.
+
+### request function
+
+```js
+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:
+
+```js
+try {
+  await semaphore.acquire([key])
+  const results = await fn()
+} finally {
+  semaphore.release([key])
+}
+```
+
+See the examples below.
+
+### requestIfAvailable function
+
+```js
+const results = await semaphore.requestIfAvailable(fn [,key])
+```
+
+This is functionally equivalent to:
+
+```js
+const results = semaphore.canAcquire([key] ?
+	await semaphore.request(fn, [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 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 locks preceeding it have been
-		// released.
-	})
-	.finally(() => {
-		// release the lock permitting the next queued process 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
-await semaphore.acquire()
-
 try {
-	// do your 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
+})
 ```
 
 ## Example 2
 
-Say you have an asynchronous function to download a file and cache it to disk:
+Say you have an asynchronous function to download a file and save it to disk:
 
 ```js
-async function downloadAndCache(url) {
-
-	// cacheFilePath could be based on a hash of the url
-	const cacheFilePath = getCacheFilePath(url)
+async function downloadAndSave(url) {
+  const filePath = urlToFilePath(url)
 
-	if (!await pathExists(cacheFilePath)) {
-		await downloadToFile(url, cacheFilePath)
-	}
+  if (await pathExists(filePath)) {
+    // the file is on disk, so no action is required
+  } else {
+    await downloadAndSaveToFilepath(url, filePath)
+  }
 
-	return cacheFilePath
+  return filePath
 }
 ```
 
-This works until a process calls `downloadAndCache()` in short succession with the same `url` parameter. This can cause multiple simultaneous downloads that attempt to write to the same cached 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 downloadAndCache(url) {
+async function downloadAndSave(url) {
+  try {
+    await semaphore.acquire(url)
+
+    // This block continues once a lock on url is acquired.  This
+    // permits multiple simulataneous downloads for different urls.
 
-	await semaphore.acquire(url)
+    const filePath = urlToFilePath(url)
 
-	// This block continues once a lock on url is acquired.  This permits
-	// multiple simulataneous downloads for unique url values.
+    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)
+  }
+}
+```
+
+Alternatively, this can be accomplished with the `request` function:
+
+```js
+async function downloadAndSave(url) {
 
-	try {
-		const cacheFileName = getCacheFilePath(url)
+	return semaphore.request(() => {
+		const filePath = urlToFilePath(url)
 
-		if (!await pathExists(cacheFilePath)) {
-			await downloadToFile(url, cacheFilePath)	
+		if (await pathExists(filePath)) {
+			// the file is on disk, so no action is required
+		} else {
+			await downloadAndSaveToFilepath(url, filePath)
 		}
 
-		return cacheFilePath
+		return filePath
+	}, url)
 
-	} finally {
-		semaphore.release(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,76 +1,141 @@
 'use strict';
 
 class SemaphoreItem {
-	constructor(max) {
-		this.queue = [];
-		this.max = max;
-		this.count = 0;
-	}
-
-	acquire() {
-		if (this.count < this.max) {
-			this.count++;
-			return Promise.resolve()
-		} else {
-			return new Promise(resolve => {
-				this.queue.push(resolve);
-			})
-		}
-	}
-
-	release() {
-		let resolveFunc = this.queue.shift();
-
-		if (resolveFunc) {
-			// Give the micro task queue a small break instead of calling resoleFunc() directly
-			setTimeout(resolveFunc, 0);
-		} else {
-			this.count--;
-		}
-	}
+  queue;
+  maxConcurrent;
+  /**
+   * The number of locks.
+   */
+  count;
+  constructor(maxConcurrent) {
+    this.queue = [];
+    this.maxConcurrent = maxConcurrent;
+    this.count = 0;
+  }
+  get canAcquire() {
+    return this.count < this.maxConcurrent;
+  }
+  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) {
+      setTimeout(resolveFunc, 0);
+    } else {
+      this.count--;
+    }
+  }
 }
-
-const defaultKey = '_default';
-
+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];
-		}
-	}
-
-	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
-	}
+  semaphoreInstances;
+  maxConcurrent;
+  /**
+   *
+   * @param {number} [maxConcurrent] The maximum number of concurrent locks.
+   */
+  constructor(maxConcurrent = 1) {
+    this.semaphoreInstances = {};
+    this.maxConcurrent = maxConcurrent;
+  }
+  hasSemaphoreInstance(key = defaultKey) {
+    return Boolean(this.semaphoreInstances[key]);
+  }
+  getSemaphoreInstance(key = defaultKey) {
+    if (!this.hasSemaphoreInstance(key)) {
+      this.semaphoreInstances[key] = new SemaphoreItem(this.maxConcurrent);
+    }
+    return this.semaphoreInstances[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;
+  }
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   */
+  acquire(key = defaultKey) {
+    return this.getSemaphoreInstance(key).acquire();
+  }
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   */
+  release(key = defaultKey) {
+    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.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 = defaultKey) {
+    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();
+    } 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);
+    } else {
+      return null;
+    }
+  }
 }
 
 module.exports = Semaphore;

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,76 +1,139 @@
 class SemaphoreItem {
-	constructor(max) {
-		this.queue = [];
-		this.max = max;
-		this.count = 0;
-	}
-
-	acquire() {
-		if (this.count < this.max) {
-			this.count++;
-			return Promise.resolve()
-		} else {
-			return new Promise(resolve => {
-				this.queue.push(resolve);
-			})
-		}
-	}
-
-	release() {
-		let resolveFunc = this.queue.shift();
-
-		if (resolveFunc) {
-			// Give the micro task queue a small break instead of calling resoleFunc() directly
-			setTimeout(resolveFunc, 0);
-		} else {
-			this.count--;
-		}
-	}
+  queue;
+  maxConcurrent;
+  /**
+   * The number of locks.
+   */
+  count;
+  constructor(maxConcurrent) {
+    this.queue = [];
+    this.maxConcurrent = maxConcurrent;
+    this.count = 0;
+  }
+  get canAcquire() {
+    return this.count < this.maxConcurrent;
+  }
+  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) {
+      setTimeout(resolveFunc, 0);
+    } else {
+      this.count--;
+    }
+  }
 }
-
-const defaultKey = '_default';
-
+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];
-		}
-	}
-
-	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
-	}
+  semaphoreInstances;
+  maxConcurrent;
+  /**
+   *
+   * @param {number} [maxConcurrent] The maximum number of concurrent locks.
+   */
+  constructor(maxConcurrent = 1) {
+    this.semaphoreInstances = {};
+    this.maxConcurrent = maxConcurrent;
+  }
+  hasSemaphoreInstance(key = defaultKey) {
+    return Boolean(this.semaphoreInstances[key]);
+  }
+  getSemaphoreInstance(key = defaultKey) {
+    if (!this.hasSemaphoreInstance(key)) {
+      this.semaphoreInstances[key] = new SemaphoreItem(this.maxConcurrent);
+    }
+    return this.semaphoreInstances[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;
+  }
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   */
+  acquire(key = defaultKey) {
+    return this.getSemaphoreInstance(key).acquire();
+  }
+  /**
+   *
+   * @param {string | number} [key]- Optional, the semaphore key.
+   */
+  release(key = defaultKey) {
+    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.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 = defaultKey) {
+    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();
+    } 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);
+    } else {
+      return null;
+    }
+  }
 }
 
-var src = Semaphore;
-
-export default src;
+export { Semaphore as default };

package/package.json

@@ -1,23 +1,34 @@
 {
-	"name": "@chriscdn/promise-semaphore",
-	"version": "1.0.6",
-	"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",
-	"repository": "https://github.com/chriscdn/promise-semaphore",
-	"author": "Christopher Meyer <chris@schwiiz.org>",
-	"license": "MIT",
-	"scripts": {
-		"build": "rollup -c"
-	},
-	"devDependencies": {
-		"@rollup/plugin-commonjs": "^15.1.0"
-	},
-	"keywords": [
-		"promise",
-		"semaphore",
-		"lock",
-		"mutex",
-		"async"
-	]
+  "name": "@chriscdn/promise-semaphore",
+  "version": "2.0.0",
+  "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",
+    "watch": "rollup -c --watch",
+    "test": "jest"
+  },
+  "devDependencies": {
+    "@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",
+    "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,74 +0,0 @@
-class SemaphoreItem {
-	constructor(max) {
-		this.queue = []
-		this.max = max
-		this.count = 0
-	}
-
-	acquire() {
-		if (this.count < this.max) {
-			this.count++
-			return Promise.resolve()
-		} else {
-			return new Promise(resolve => {
-				this.queue.push(resolve)
-			})
-		}
-	}
-
-	release() {
-		let resolveFunc = this.queue.shift()
-
-		if (resolveFunc) {
-			// Give the micro task queue a small break instead of calling resoleFunc() 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]
-		}
-	}
-
-	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
-	}
-}
-
-module.exports = Semaphore