superlock 1.2.9 → 1.3.0

package/README.md

@@ -48,6 +48,26 @@ console.log(executions)
 
 Just call `withLock(n)` being `n` the maximum of concurrency desired for the lock.
 
+### with cancellation
+
+Pass an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to drop an acquisition that is still waiting in the queue — handy for shedding work whose caller already gave up (a timed-out request, a disconnected client):
+
+```js
+const { withLock } = require('superlock')
+
+const lock = withLock()
+const controller = new AbortController()
+
+const pending = lock(() => doWork(), controller.signal)
+
+// caller no longer needs the result: give the queued slot back
+controller.abort()
+
+await pending // resolves `undefined`; `doWork` never runs
+```
+
+If the signal aborts **before** the slot is granted, the acquisition is dropped: it never takes a slot and the wrapped function never runs. Aborting **after** the slot is granted is a no-op (the work is already running). Aborting is silent — it resolves instead of throwing — so shedding a lot of queued work never produces rejections to handle.
+
 ## API
 
 ### withLock([concurrency=1])
@@ -66,6 +86,16 @@ await lock(() => {
 
 The lock will be automatically released after your code execution is done even if an error occurred, avoiding [deadlock](https://en.wikipedia.org/wiki/Deadlock) situations.
 
+It also accepts an optional `AbortSignal` as second argument:
+
+```js
+await lock(() => {
+  /* your code execution */
+}, signal)
+```
+
+If `signal` aborts while the call is still queued, the function is skipped and the call resolves `undefined` instead of running. Aborting after the slot is granted has no effect.
+
 #### concurrency
 
 Type: `number`<br>
@@ -73,6 +103,12 @@ Default: `1`
 
 It sets the maximum of concurrency allowed for the lock.
 
+#### signal
+
+Type: `AbortSignal`
+
+When provided, aborting it drops the acquisition while it is still waiting in the queue: no slot is taken and the wrapped function never runs.
+
 ### .isLocked()
 
 Type: `boolean`

package/package.json

@@ -2,7 +2,7 @@
   "name": "superlock",
   "description": "The most simple mutex/semaphore implementation",
   "homepage": "https://github.com/Kikobeats/superlock",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "types": "src/index.d.ts",
   "main": "src/index.js",
   "exports": {
@@ -14,7 +14,12 @@
     "name": "Kiko Beats",
     "url": "https://kikobeats.com"
   },
-  "contributors": [],
+  "contributors": [
+    {
+      "name": "Tycho Bokdam",
+      "email": "tycho@palmtreecoding.com"
+    }
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Kikobeats/superlock.git"
@@ -52,19 +57,6 @@
   "files": [
     "src"
   ],
-  "scripts": {
-    "clean": "rm -rf node_modules",
-    "contributors": "(npx git-authors-cli && npx finepack && git add package.json && git commit -m 'build: contributors' --no-verify) || true",
-    "coverage": "c8 report --reporter=text-lcov > coverage/lcov.info",
-    "lint": "standard",
-    "postrelease": "npm run release:tags && npm run release:github && (ci-publish || npm publish --access=public)",
-    "prerelease": "npm run contributors",
-    "pretest": "npm run lint",
-    "release": "standard-version -a",
-    "release:github": "github-generate-release",
-    "release:tags": "git push --follow-tags origin HEAD:master",
-    "test": "c8 ava"
-  },
   "license": "MIT",
   "ava": {
     "files": [
@@ -94,5 +86,18 @@
   "simple-git-hooks": {
     "commit-msg": "npx commitlint --edit",
     "pre-commit": "npx nano-staged"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules",
+    "contributors": "(npx git-authors-cli && npx finepack && git add package.json && git commit -m 'build: contributors' --no-verify) || true",
+    "coverage": "c8 report --reporter=text-lcov > coverage/lcov.info",
+    "lint": "standard",
+    "postrelease": "npm run release:tags && npm run release:github && (ci-publish || npm publish --access=public)",
+    "prerelease": "npm run contributors",
+    "pretest": "npm run lint",
+    "release": "standard-version -a",
+    "release:github": "github-generate-release",
+    "release:tags": "git push --follow-tags origin HEAD:master",
+    "test": "c8 ava"
   }
-}
+}

package/src/create.js

@@ -7,43 +7,42 @@ class Node {
 }
 
 class LinkedList {
+  constructor () {
+    this.length = 0
+  }
+
   enqueue (data) {
-    if (!this.head) {
-      this.head = new Node(data)
-    } else {
-      let current = this.head
-      while (current.next) {
-        current = current.next
-      }
-      current.next = new Node(data)
-    }
+    const node = new Node(data)
+    if (this.head) this.tail.next = node
+    else this.head = node
+    this.tail = node
+    this.length++
   }
 
   dequeue () {
     if (!this.head) return
     const data = this.head.data
     this.head = this.head.next
+    this.length--
     return data
   }
 
   size () {
-    let count = 0
-    let current = this.head
-    while (current) {
-      count++
-      current = current.next
-    }
-    return count
+    return this.length
   }
 }
 
 module.exports = (slots = 1) => {
   const queue = new LinkedList()
+  let cancelled = 0
 
   const release = () => {
     ++slots
-    const fn = queue.dequeue()
-    if (fn !== undefined) fn()
+    let waiter
+    while ((waiter = queue.dequeue()) !== undefined) {
+      if (waiter.cancelled) --cancelled
+      else return waiter.acquire()
+    }
   }
 
   const acquire = resolve => {
@@ -51,14 +50,32 @@ module.exports = (slots = 1) => {
     resolve(release)
   }
 
-  const lock = () =>
-    new Promise(resolve =>
-      lock.isLocked() ? queue.enqueue(() => acquire(resolve)) : acquire(resolve)
-    )
+  const lock = signal =>
+    new Promise(resolve => {
+      if (signal?.aborted) return resolve(null)
+      if (!lock.isLocked()) return acquire(resolve)
+
+      const waiter = { cancelled: false, acquire: () => acquire(resolve) }
+
+      if (signal !== undefined) {
+        const onAbort = () => {
+          waiter.cancelled = true
+          ++cancelled
+          resolve(null)
+        }
+        waiter.acquire = () => {
+          signal.removeEventListener('abort', onAbort)
+          acquire(resolve)
+        }
+        signal.addEventListener('abort', onAbort, { once: true })
+      }
+
+      queue.enqueue(waiter)
+    })
 
   lock.isLocked = () => slots === 0
 
-  lock.awaiting = () => queue.size()
+  lock.awaiting = () => queue.size() - cancelled
 
   return lock
 }

package/src/index.d.ts

@@ -1,17 +1,19 @@
 declare type Release = () => void;
 declare type Acquire = (resolve: (release: Release) => void) => void;
-declare type Lock = () => Promise<Release>;
+declare type Lock = (signal?: AbortSignal) => Promise<Release | null>;
 
 interface LockInterface extends Lock {
   isLocked: () => boolean;
+  awaiting: () => number;
 }
 
 declare function createLock(slots?: number): LockInterface;
 
-declare type WithLock = <T>(fn: () => Promise<T>) => Promise<T>;
+declare type WithLock = <T>(fn: () => Promise<T>, signal?: AbortSignal) => Promise<T | undefined>;
 
 interface WithLockInterface extends WithLock {
   isLocked: () => boolean;
+  awaiting: () => number;
 }
 
 declare function withLock(opts?: number): WithLockInterface;

package/src/index.js

@@ -5,8 +5,9 @@ const createLock = require('./create')
 const withLock = opts => {
   const lock = createLock(opts)
 
-  const withLock = async fn => {
-    const release = await lock()
+  const withLock = async (fn, signal) => {
+    const release = await lock(signal)
+    if (!release) return
     try {
       return await fn()
     } finally {