@chriscdn/promise-semaphore 1.0.6 → 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

@@ -43,6 +43,49 @@ 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 that is being repeatedly tapped or clicked by the user.
+
 ## Example 1
 
 ```js
@@ -52,44 +95,59 @@ 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 cache it to disk:
+Say you have an asynchronous function to download a file and save it to disk
 
 ```js
-async function downloadAndCache(url) {
+async function downloadAndSave(url) {
 
-	// cacheFilePath could be based on a hash of the url
-	const cacheFilePath = getCacheFilePath(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 downloadToFile(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()` 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:
 
@@ -97,21 +155,24 @@ This can be resolved with a `Semaphore` instance using the `key` parameter:
 const Semaphore = require('@chriscdn/promise-semaphore')
 const semaphore = new Semaphore()
 
-async function downloadAndCache(url) {
-
-	await semaphore.acquire(url)
-
-	// This block continues once a lock on url is acquired.  This permits
-	// multiple simulataneous downloads for unique url values.
+async function downloadAndSave(url) {
 
 	try {
-		const cacheFileName = getCacheFilePath(url)
-
-		if (!await pathExists(cacheFilePath)) {
-			await downloadToFile(url, cacheFilePath)	
+	
+		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 cacheFilePath
+	
+		return filePath
 
 	} finally {
 		semaphore.release(url)
@@ -119,6 +180,26 @@ async function downloadAndCache(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
 
 [MIT](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,23 +1,23 @@
 {
-	"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": "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