@chriscdn/promise-semaphore 1.0.4 → 1.0.9

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 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

@@ -33,7 +33,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.
+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
 
@@ -41,7 +41,52 @@ This returns a `Promise`, which resolves once a lock has been acquired.  The `ke
 semaphore.release([key])
 ```
 
-## Example
+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 that is being repeatedly tapped or clicked by the user.
+
+## Example 1
 
 ```js
 const Semaphore = require('@chriscdn/promise-semaphore')
@@ -50,23 +95,109 @@ 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.
+		// 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 process to continue
+		// release the lock permitting the next queued block to continue
 		semaphore.release()
 	})
 
-// or, using async/await
-await semaphore.acquire()
 
+// or, using async/await
 try {
-	// do your stuff here
+	await semaphore.acquire()
+	
+	// do your critical stuff here
+	
 } finally {
 	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 save it to disk
+
+```js
+async function downloadAndSave(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
+}
+```
+
+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 can be resolved with a `Semaphore` instance using the `key` parameter:
+
+```js
+const Semaphore = require('@chriscdn/promise-semaphore')
+const semaphore = new Semaphore()
+
+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 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
+
+	} finally {
+		semaphore.release(url)
+	}
+}
+```
+
+Alternatively, this can be accomplished with the `request` function:
+
+```js
+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)
+		}
+	
+		return filePath	
+	}, url)
+
+}
 ```
 
 ## License

package/lib/index.cjs.js

@@ -1,76 +1,103 @@
 '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--;
-		}
-	}
+  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];
-		}
-	}
-
-	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
-	}
+  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;

package/lib/index.es.js

@@ -1,76 +1,103 @@
 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--;
-		}
-	}
+  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];
-		}
-	}
-
-	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
-	}
+  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
+    }
+  }
 }
 
 var src = Semaphore;
 
-export default src;
+export { src as default };

package/package.json

@@ -1,22 +1,23 @@
 {
-	"name": "@chriscdn/promise-semaphore",
-	"version": "1.0.4",
-	"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": "^13.0.0"
-	},
-	"keywords": [
-		"semeaphore",
-		"lock",
-		"mutex",
-		"async"
-	]
+  "name": "@chriscdn/promise-semaphore",
+  "version": "1.0.9",
+  "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": "^21.0.2"
+  },
+  "keywords": [
+    "promise",
+    "semaphore",
+    "lock",
+    "mutex",
+    "async"
+  ]
 }

package/src/index.js

@@ -1,74 +1,101 @@
 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--
-		}
-	}
+  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]
-		}
-	}
-
-	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
-	}
+  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
+module.exports = Semaphore