better-lock 3.3.0 → 4.0.0

package/dist/errors.js

@@ -15,7 +15,7 @@ var __extends = (this && this.__extends) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isAcquisitionFailureError = exports.BetterLockJobAbortedError = exports.BetterLockQueueOverflowError = exports.BetterLockExecutionTimeoutError = exports.BetterLockWaitTimeoutError = exports.BetterLockInvalidArgumentError = exports.BetterLockInternalError = exports.BetterLockError = void 0;
+exports.isAcquisitionFailureError = exports.BetterLockReentrancyError = exports.BetterLockJobAbortedError = exports.BetterLockQueueOverflowError = exports.BetterLockExecutionTimeoutError = exports.BetterLockWaitTimeoutError = exports.BetterLockInvalidArgumentError = exports.BetterLockInternalError = exports.BetterLockError = void 0;
 var internals_1 = require("./internals");
 var BetterLockError = /** @class */ (function (_super) {
     __extends(BetterLockError, _super);
@@ -127,6 +127,24 @@ var BetterLockJobAbortedError = /** @class */ (function (_super) {
     return BetterLockJobAbortedError;
 }(BetterLockError));
 exports.BetterLockJobAbortedError = BetterLockJobAbortedError;
+var BetterLockReentrancyError = /** @class */ (function (_super) {
+    __extends(BetterLockReentrancyError, _super);
+    function BetterLockReentrancyError(lockName, keys, heldKeys) {
+        var _this = this;
+        var describe = function (list) {
+            return list.map(function (key) { return (key === null ? '<default>' : "\"".concat(key, "\"")); }).join(', ');
+        };
+        var message = heldKeys.length < keys.length
+            ? "Caller holds only some of the requested keys (".concat(describe(heldKeys), " of ").concat(describe(keys), "). Waiting for the rest while holding these could deadlock")
+            : "Reentrant acquire of ".concat(describe(keys), " is not allowed (reentrancy: \"error\")");
+        _this = _super.call(this, lockName, message) || this;
+        _this.keys = keys;
+        _this.held_keys = heldKeys;
+        return _this;
+    }
+    return BetterLockReentrancyError;
+}(BetterLockError));
+exports.BetterLockReentrancyError = BetterLockReentrancyError;
 function isAcquisitionFailureError(err) {
     return ((err && err instanceof BetterLockQueueOverflowError) ||
         err instanceof BetterLockWaitTimeoutError ||

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { BetterLock as BetterLockUnadorned } from './better_lock';
-import { BetterLockError, BetterLockExecutionTimeoutError, BetterLockInternalError, BetterLockInvalidArgumentError, BetterLockJobAbortedError, BetterLockQueueOverflowError, BetterLockWaitTimeoutError } from './errors';
-import { ILockJobOptions as BetterLockJobOptions, IOptions as BetterLockOptions, IQueueEjectionStrategy as BetterLockQueueEjectionStrategy } from './options';
+import { BetterLockError, BetterLockExecutionTimeoutError, BetterLockInternalError, BetterLockInvalidArgumentError, BetterLockJobAbortedError, BetterLockQueueOverflowError, BetterLockReentrancyError, BetterLockWaitTimeoutError } from './errors';
+import { ILockJobOptions as BetterLockJobOptions, IOptions as BetterLockOptions, IQueueEjectionStrategy as BetterLockQueueEjectionStrategy, IReentrancyMode as BetterLockReentrancyMode } from './options';
 import { IErrorName as BetterLockErrorName, IExecutor as BetterLockExecutor, ILockKey as BetterLockKey } from './types';
-export { BetterLockOptions, BetterLockQueueEjectionStrategy, BetterLockJobOptions, BetterLockExecutor, BetterLockKey, BetterLockErrorName, BetterLockError, BetterLockExecutionTimeoutError, BetterLockInternalError, BetterLockInvalidArgumentError, BetterLockJobAbortedError, BetterLockQueueOverflowError, BetterLockWaitTimeoutError, };
+export { BetterLockOptions, BetterLockQueueEjectionStrategy, BetterLockReentrancyMode, BetterLockJobOptions, BetterLockExecutor, BetterLockKey, BetterLockErrorName, BetterLockError, BetterLockExecutionTimeoutError, BetterLockInternalError, BetterLockInvalidArgumentError, BetterLockJobAbortedError, BetterLockQueueOverflowError, BetterLockReentrancyError, BetterLockWaitTimeoutError, };
 export declare const BetterLock: typeof BetterLockUnadorned & {
     BetterLock: typeof BetterLockUnadorned;
     Error: typeof BetterLockError;
@@ -12,5 +12,6 @@ export declare const BetterLock: typeof BetterLockUnadorned & {
     ExecutionTimeoutError: typeof BetterLockExecutionTimeoutError;
     QueueOverflowError: typeof BetterLockQueueOverflowError;
     JobAbortedError: typeof BetterLockJobAbortedError;
+    ReentrancyError: typeof BetterLockReentrancyError;
 };
 export default BetterLock;

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BetterLock = exports.BetterLockWaitTimeoutError = exports.BetterLockQueueOverflowError = exports.BetterLockJobAbortedError = exports.BetterLockInvalidArgumentError = exports.BetterLockInternalError = exports.BetterLockExecutionTimeoutError = exports.BetterLockError = void 0;
+exports.BetterLock = exports.BetterLockWaitTimeoutError = exports.BetterLockReentrancyError = exports.BetterLockQueueOverflowError = exports.BetterLockJobAbortedError = exports.BetterLockInvalidArgumentError = exports.BetterLockInternalError = exports.BetterLockExecutionTimeoutError = exports.BetterLockError = void 0;
 var better_lock_1 = require("./better_lock");
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "BetterLockError", { enumerable: true, get: function () { return errors_1.BetterLockError; } });
@@ -9,6 +9,7 @@ Object.defineProperty(exports, "BetterLockInternalError", { enumerable: true, ge
 Object.defineProperty(exports, "BetterLockInvalidArgumentError", { enumerable: true, get: function () { return errors_1.BetterLockInvalidArgumentError; } });
 Object.defineProperty(exports, "BetterLockJobAbortedError", { enumerable: true, get: function () { return errors_1.BetterLockJobAbortedError; } });
 Object.defineProperty(exports, "BetterLockQueueOverflowError", { enumerable: true, get: function () { return errors_1.BetterLockQueueOverflowError; } });
+Object.defineProperty(exports, "BetterLockReentrancyError", { enumerable: true, get: function () { return errors_1.BetterLockReentrancyError; } });
 Object.defineProperty(exports, "BetterLockWaitTimeoutError", { enumerable: true, get: function () { return errors_1.BetterLockWaitTimeoutError; } });
 function attachExports(target, exports) {
     Object.assign(target, exports);
@@ -23,6 +24,7 @@ exports.BetterLock = attachExports(better_lock_1.BetterLock, {
     ExecutionTimeoutError: errors_1.BetterLockExecutionTimeoutError,
     QueueOverflowError: errors_1.BetterLockQueueOverflowError,
     JobAbortedError: errors_1.BetterLockJobAbortedError,
+    ReentrancyError: errors_1.BetterLockReentrancyError,
 });
 exports.default = exports.BetterLock;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6CAAkE;AAClE,mCAQkB;AAgBhB,gGAvBA,wBAAe,OAuBA;AACf,gHAvBA,wCAA+B,OAuBA;AAC/B,wGAvBA,gCAAuB,OAuBA;AACvB,+GAvBA,uCAA8B,OAuBA;AAC9B,0GAvBA,kCAAyB,OAuBA;AACzB,6GAvBA,qCAA4B,OAuBA;AAC5B,2GAvBA,mCAA0B,OAuBA;AAG5B,SAAS,aAAa,CACpB,MAAe,EACf,OAAiB;IAEjB,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,MAAa,CAAC;AACvB,CAAC;AAEY,QAAA,UAAU,GAAG,aAAa,CAAC,wBAAmB,EAAE;IAC3D,UAAU,EAAE,wBAAmB;IAE/B,KAAK,EAAE,wBAAe;IACtB,aAAa,EAAE,gCAAuB;IACtC,oBAAoB,EAAE,uCAA8B;IACpD,gBAAgB,EAAE,mCAA0B;IAC5C,qBAAqB,EAAE,wCAA+B;IACtD,kBAAkB,EAAE,qCAA4B;IAChD,eAAe,EAAE,kCAAyB;CAC3C,CAAC,CAAC;AAEH,kBAAe,kBAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6CAAkE;AAClE,mCASkB;AAiBhB,gGAzBA,wBAAe,OAyBA;AACf,gHAzBA,wCAA+B,OAyBA;AAC/B,wGAzBA,gCAAuB,OAyBA;AACvB,+GAzBA,uCAA8B,OAyBA;AAC9B,0GAzBA,kCAAyB,OAyBA;AACzB,6GAzBA,qCAA4B,OAyBA;AAC5B,0GAzBA,kCAAyB,OAyBA;AACzB,2GAzBA,mCAA0B,OAyBA;AAG5B,SAAS,aAAa,CACpB,MAAe,EACf,OAAiB;IAEjB,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,MAAa,CAAC;AACvB,CAAC;AAEY,QAAA,UAAU,GAAG,aAAa,CAAC,wBAAmB,EAAE;IAC3D,UAAU,EAAE,wBAAmB;IAE/B,KAAK,EAAE,wBAAe;IACtB,aAAa,EAAE,gCAAuB;IACtC,oBAAoB,EAAE,uCAA8B;IACpD,gBAAgB,EAAE,mCAA0B;IAC5C,qBAAqB,EAAE,wCAA+B;IACtD,kBAAkB,EAAE,qCAA4B;IAChD,eAAe,EAAE,kCAAyB;IAC1C,eAAe,EAAE,kCAAyB;CAC3C,CAAC,CAAC;AAEH,kBAAe,kBAAU,CAAC"}

package/dist/internals.d.ts

@@ -1,3 +1,4 @@
+import { IAsyncResource } from './async_context';
 import { ILockJobOptions } from './options';
 import { ICallback, IExecutor } from './types';
 /**
@@ -52,6 +53,15 @@ export declare class LockJob<TResult> {
      * Saved incoming stack, for the purpose of extending stack traces
      */
     incoming_stack: string;
+    /**
+     * Async context of the acquire() call. Executor and callback run in it. Undefined if the runtime doesn't support it.
+     */
+    async_context: IAsyncResource | undefined;
+    /**
+     * Set for reentrant jobs: the executing jobs (from the caller's async context) that hold this job's keys.
+     * A reentrant job doesn't enter key queues. It runs while these jobs hold the keys.
+     */
+    reentrant_holders: LockJob<any>[] | null;
     constructor(keys: Array<string | null>, executor: IExecutor<TResult>, callback: ICallback<TResult>, options: ILockJobOptions);
     toString(): string;
 }

package/dist/internals.js

@@ -32,6 +32,15 @@ var LockJob = /** @class */ (function () {
          * Saved incoming stack, for the purpose of extending stack traces
          */
         this.incoming_stack = null;
+        /**
+         * Async context of the acquire() call. Executor and callback run in it. Undefined if the runtime doesn't support it.
+         */
+        this.async_context = undefined;
+        /**
+         * Set for reentrant jobs: the executing jobs (from the caller's async context) that hold this job's keys.
+         * A reentrant job doesn't enter key queues. It runs while these jobs hold the keys.
+         */
+        this.reentrant_holders = null;
         LockJob._lastId++;
         this.id = LockJob._lastId;
         this.keys = keys;

package/dist/internals.js.map

@@ -1 +1 @@
-{"version":3,"file":"internals.js","sourceRoot":"","sources":["../src/internals.ts"],"names":[],"mappings":";;;AAGA;;GAEG;AACH;IA8DE,iBACE,IAA0B,EAC1B,QAA4B,EAC5B,QAA4B,EAC5B,OAAwB;QA/D1B,kDAAkD;QAC3C,OAAE,GAAG,SAAS,CAAC;QAuBtB;;WAEG;QACI,gBAAW,GAAS,IAAI,IAAI,EAAE,CAAC;QAEtC;;WAEG;QACI,gBAAW,GAAS,IAAI,CAAC;QAEhC;;WAEG;QACI,aAAQ,GAAS,IAAI,CAAC;QAO7B;;WAEG;QACI,oBAAe,GAAG,IAAI,CAAC;QAE9B;;WAEG;QACI,yBAAoB,GAAG,IAAI,CAAC;QAEnC;;WAEG;QACI,mBAAc,GAAW,IAAI,CAAC;QAQnC,OAAO,CAAC,OAAO,EAAE,CAAC;QAClB,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,0BAAQ,GAAR;QACE,OAAO,eAAQ,IAAI,CAAC,EAAE,eAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAG,CAAC;IACrD,CAAC;IA9EM,eAAO,GAAG,CAAC,CAAC;IA+ErB,cAAC;CAAA,AAhFD,IAgFC;AAhFY,0BAAO;AAkFpB,wHAAwH;AAExH;;GAEG;AACH;IAiBE,kBAAY,GAAY;QAXxB;;;WAGG;QACI,SAAI,GAAmB,EAAE,CAAC;QAEjC;;WAEG;QACI,WAAM,GAAiB,IAAI,CAAC;QAGjC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,2BAAQ,GAAR;QACE,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,mBAAY,IAAI,CAAC,GAAG,MAAG,CAAC;IACxF,CAAC;IAtBD,yDAAyD;IACzC,0BAAiB,GAAG,yBAAyB,CAAC;IAsBhE,eAAC;CAAA,AAxBD,IAwBC;AAxBY,4BAAQ"}
+{"version":3,"file":"internals.js","sourceRoot":"","sources":["../src/internals.ts"],"names":[],"mappings":";;;AAIA;;GAEG;AACH;IAyEE,iBACE,IAA0B,EAC1B,QAA4B,EAC5B,QAA4B,EAC5B,OAAwB;QA1E1B,kDAAkD;QAC3C,OAAE,GAAG,SAAS,CAAC;QAuBtB;;WAEG;QACI,gBAAW,GAAS,IAAI,IAAI,EAAE,CAAC;QAEtC;;WAEG;QACI,gBAAW,GAAS,IAAI,CAAC;QAEhC;;WAEG;QACI,aAAQ,GAAS,IAAI,CAAC;QAO7B;;WAEG;QACI,oBAAe,GAAG,IAAI,CAAC;QAE9B;;WAEG;QACI,yBAAoB,GAAG,IAAI,CAAC;QAEnC;;WAEG;QACI,mBAAc,GAAW,IAAI,CAAC;QAErC;;WAEG;QACI,kBAAa,GAA+B,SAAS,CAAC;QAE7D;;;WAGG;QACI,sBAAiB,GAA0B,IAAI,CAAC;QAQrD,OAAO,CAAC,OAAO,EAAE,CAAC;QAClB,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,0BAAQ,GAAR;QACE,OAAO,eAAQ,IAAI,CAAC,EAAE,eAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAG,CAAC;IACrD,CAAC;IAzFM,eAAO,GAAG,CAAC,CAAC;IA0FrB,cAAC;CAAA,AA3FD,IA2FC;AA3FY,0BAAO;AA6FpB,wHAAwH;AAExH;;GAEG;AACH;IAiBE,kBAAY,GAAY;QAXxB;;;WAGG;QACI,SAAI,GAAmB,EAAE,CAAC;QAEjC;;WAEG;QACI,WAAM,GAAiB,IAAI,CAAC;QAGjC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,2BAAQ,GAAR;QACE,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,mBAAY,IAAI,CAAC,GAAG,MAAG,CAAC;IACxF,CAAC;IAtBD,yDAAyD;IACzC,0BAAiB,GAAG,yBAAyB,CAAC;IAsBhE,eAAC;CAAA,AAxBD,IAwBC;AAxBY,4BAAQ"}

package/dist/options.d.ts

@@ -21,8 +21,17 @@ export interface ILockJobOptions {
      * Overrides BetterLockOptions value.
      */
     lock_condition?: (key: ILockKey | Array<ILockKey>) => boolean;
+    /**
+     * What to do when acquire is called from code that already holds all the requested keys. Overrides BetterLockOptions value.
+     */
+    reentrancy?: IReentrancyMode;
 }
 export declare type IQueueEjectionStrategy = 'oldest' | 'newest';
+/**
+ * - 'allow': run the executor without waiting for the keys the caller already holds.
+ * - 'error': fail with BetterLockReentrancyError.
+ */
+export declare type IReentrancyMode = 'allow' | 'error';
 /**
  * Options that apply on BetterLock instance
  */
@@ -49,6 +58,18 @@ export interface IOptions extends ILockJobOptions {
      * This can be used to more conveniently opt out of locking, without duplicating or extracting the executor.
      */
     lock_condition?: (key: ILockKey | Array<ILockKey>) => boolean;
+    /**
+     * What to do when acquire is called from code that already holds all the requested keys (inside the executor, or
+     * in async work the executor started and that runs before it finishes). 'allow' runs the executor without
+     * waiting, 'error' fails with BetterLockReentrancyError. Defaults to 'allow'.
+     *
+     * Holding only some of the requested keys always fails with BetterLockReentrancyError, because waiting for the rest
+     * while holding these could deadlock.
+     *
+     * Requires Node.js AsyncLocalStorage, looked up through process.getBuiltinModule (Node.js 20.16+ or 22.3+).
+     * In other runtimes, this option has no effect and nested acquire calls wait in the queue like any other.
+     */
+    reentrancy?: IReentrancyMode;
     /**
      * Lock name. This will be written in all logs and error messages, to help you distinguish between different locks
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-lock",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "description": "A (better) node.js lock library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/spec/async_context.spec.ts

@@ -0,0 +1,379 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+import BetterLock from '../src/index';
+
+describe('BetterLock async context', () => {
+  const store = new AsyncLocalStorage<string>();
+
+  it('runs a contended executor in the context of its own acquire call', async () => {
+    const lock = new BetterLock();
+    const seen: Record<string, string> = {};
+
+    await Promise.all([
+      store.run('first', () =>
+        lock.acquire(async () => {
+          await waitPromise(20);
+          seen.first = store.getStore();
+        })
+      ),
+      store.run('second', () =>
+        lock.acquire(async () => {
+          seen.second = store.getStore();
+        })
+      ),
+      store.run('third', () =>
+        lock.acquire(done => {
+          seen.third = store.getStore();
+          done(null);
+        })
+      ),
+    ]);
+
+    expect(seen).toEqual({ first: 'first', second: 'second', third: 'third' });
+  });
+
+  it('calls the callback in the context of its own acquire call', testDone => {
+    const lock = new BetterLock({ queue_size: 1 });
+
+    store.run('first', () => lock.acquire(waitCallback(20), () => {}));
+    store.run('second', () =>
+      lock.acquire(waitCallback(0), err => {
+        // Kicked out by the third acquire, from its context
+        expect(err).toBeInstanceOf(BetterLock.QueueOverflowError);
+        expect(store.getStore()).toEqual('second');
+        testDone();
+      })
+    );
+    store.run('third', () => lock.acquire(waitCallback(0), () => {}));
+  });
+
+  it('leaves the uncontended path unchanged', async () => {
+    const lock = new BetterLock();
+    const startedAt = Date.now();
+
+    const result = await store.run('only', () => {
+      const promise = lock.acquire(async () => store.getStore());
+      expect(lock.canAcquire()).toBeFalsy();
+      return promise;
+    });
+
+    expect(result).toEqual('only');
+    expectMs(Date.now() - startedAt, 0);
+    expect(lock.canAcquire()).toBeTruthy();
+  });
+});
+
+describe('BetterLock reentrancy', () => {
+  it('runs a reentrant acquire immediately, when the caller holds all keys', async () => {
+    const lock = new BetterLock({ wait_timeout: 50 });
+    const startedAt = Date.now();
+
+    const result = await lock.acquire(['a', 'b'], async () => {
+      expect(lock.canAcquire('a')).toBeTruthy();
+      const inner = await lock.acquire(['b', 'a'], async () => {
+        return lock.acquire('a', async () => 'innermost');
+      });
+      const viaCallback = await new Promise((resolve, reject) => {
+        lock.acquire(
+          'b',
+          done => done(null, 'callback'),
+          (err, res) => (err ? reject(err) : resolve(res))
+        );
+      });
+      return [inner, viaCallback];
+    });
+
+    expect(result).toEqual(['innermost', 'callback']);
+    expectMs(Date.now() - startedAt, 0);
+    expect(lock.canAcquire('a')).toBeTruthy();
+    expect(lock.canAcquire('b')).toBeTruthy();
+  });
+
+  it('treats the default key as a key', async () => {
+    const lock = new BetterLock({ wait_timeout: 50 });
+
+    const result = await lock.acquire(() => lock.acquire(() => Promise.resolve('nested')));
+
+    expect(result).toEqual('nested');
+  });
+
+  it('counts keys held by all executing jobs in the context', async () => {
+    const lock = new BetterLock({ wait_timeout: 50 });
+
+    const result = await lock.acquire('a', () =>
+      lock.acquire('b', () => lock.acquire(['a', 'b'], async () => 'both'))
+    );
+
+    expect(result).toEqual('both');
+  });
+
+  it('lets parallel branches of the holder both pass as reentrant', async () => {
+    const lock = new BetterLock({ wait_timeout: 50 });
+    let running = 0;
+    let maxRunning = 0;
+
+    const branch = () =>
+      lock.acquire('a', async () => {
+        running++;
+        maxRunning = Math.max(maxRunning, running);
+        await waitPromise(10);
+        running--;
+      });
+
+    await lock.acquire('a', () => Promise.all([branch(), branch()]));
+
+    expect(maxRunning).toEqual(2);
+  });
+
+  it('applies the execution timeout to the reentrant job', async () => {
+    const lock = new BetterLock({ execution_timeout: 200 });
+
+    const result = await lock.acquire('a', async () => {
+      const err = await lock
+        .acquire('a', () => waitPromise(50), { execution_timeout: 10 })
+        .catch(err => err);
+      return err;
+    });
+
+    expect(result).toBeInstanceOf(BetterLock.ExecutionTimeoutError);
+  });
+
+  it('can abort a reentrant job that has not started yet', async () => {
+    const lock = new BetterLock();
+    let called = false;
+
+    const result = await lock.acquire('a', async () => {
+      const promise = lock.acquire('a', async () => {
+        called = true;
+      });
+      lock.abort('a');
+      return promise.catch(err => err);
+    });
+
+    expect(result).toBeInstanceOf(BetterLock.JobAbortedError);
+    expect(called).toBeFalsy();
+  });
+
+  it('does not share held keys between lock instances', async () => {
+    const lock1 = new BetterLock();
+    const lock2 = new BetterLock({ wait_timeout: 20 });
+
+    const blocker = lock2.acquire('a', () => waitPromise(50));
+    const result = await lock1.acquire('a', () =>
+      lock2.acquire('a', async () => 'ok').catch(err => err)
+    );
+    await blocker;
+
+    expect(result).toBeInstanceOf(BetterLock.WaitTimeoutError);
+  });
+
+  it('rejects when the caller holds only some of the requested keys', async () => {
+    const lock = new BetterLock({ wait_timeout: 50 });
+    let called = false;
+
+    const err = await lock.acquire('a', () =>
+      lock
+        .acquire(['a', 'b'], async () => {
+          called = true;
+        })
+        .catch(err => err)
+    );
+
+    expect(err).toBeInstanceOf(BetterLock.ReentrancyError);
+    expect(err.keys).toEqual(['a', 'b']);
+    expect(err.held_keys).toEqual(['a']);
+    expect(err.stack).toContain('async_context.spec');
+    expect(called).toBeFalsy();
+    expect(lock.canAcquire('a')).toBeTruthy();
+    expect(lock.canAcquire('b')).toBeTruthy();
+  });
+
+  it('passes the reentrancy error to the callback, on a later tick', testDone => {
+    const lock = new BetterLock();
+
+    lock.acquire('a', async () => {
+      let returned = false;
+      lock.acquire(
+        ['a', 'b'],
+        done => done(null),
+        err => {
+          expect(returned).toBeTruthy();
+          expect(err).toBeInstanceOf(BetterLock.ReentrancyError);
+          testDone();
+        }
+      );
+      returned = true;
+    });
+  });
+
+  it('rejects acquireOr with the reentrancy error instead of returning the failure result', async () => {
+    const lock = new BetterLock();
+
+    const result = await lock.acquire('a', () =>
+      lock.acquireOr(['a', 'b'], 'failure', async () => 'never').catch(err => err)
+    );
+
+    expect(result).toBeInstanceOf(BetterLock.ReentrancyError);
+  });
+
+  it('rejects any reentrant acquire in "error" mode', async () => {
+    const lock = new BetterLock({ reentrancy: 'error' });
+
+    const results = await lock.acquire('a', async () => {
+      expect(lock.canAcquire('a')).toBeFalsy();
+      return Promise.all([
+        lock.acquire('a', async () => null).catch(err => err),
+        lock.acquire(['a'], async () => null).catch(err => err),
+        // Not reentrant, so allowed
+        lock.acquire('b', async () => 'other key'),
+      ]);
+    });
+
+    expect(results[0]).toBeInstanceOf(BetterLock.ReentrancyError);
+    expect(results[0].held_keys).toEqual(['a']);
+    expect(results[1]).toBeInstanceOf(BetterLock.ReentrancyError);
+    expect(results[2]).toEqual('other key');
+  });
+
+  it('can switch to "error" mode per job', async () => {
+    const lock = new BetterLock();
+
+    const err = await lock.acquire('a', () =>
+      lock.acquire('a', async () => null, { reentrancy: 'error' }).catch(err => err)
+    );
+
+    expect(err).toBeInstanceOf(BetterLock.ReentrancyError);
+  });
+
+  it('does not count detached work that runs after the holder has finished', async () => {
+    const lock = new BetterLock({ wait_timeout: 500 });
+    const events: string[] = [];
+    let detached: Promise<any>;
+
+    await lock.acquire('a', async () => {
+      setTimeout(() => {
+        detached = lock.acquire('a', async () => {
+          events.push('detached');
+        });
+      }, 20);
+    });
+
+    // Someone else grabs the key before the detached work runs
+    const other = lock.acquire('a', async () => {
+      await waitPromise(50);
+      events.push('other');
+    });
+
+    await other;
+    await detached;
+
+    expect(events).toEqual(['other', 'detached']);
+  });
+
+  it('queues a reentrant acquire normally if its holder ends before it starts', async () => {
+    const lock = new BetterLock({ wait_timeout: 500 });
+    const events: string[] = [];
+    let unawaited: Promise<any>;
+
+    const holder = lock.acquire('a', () => {
+      // Returns synchronously, so the holder ends before the nested executor starts
+      unawaited = lock.acquire('a', async () => {
+        events.push('unawaited');
+      });
+    });
+    const waiter = lock.acquire('a', async () => {
+      await waitPromise(20);
+      events.push('waiter');
+    });
+
+    await Promise.all([holder, waiter]);
+    await unawaited;
+
+    expect(events).toEqual(['waiter', 'unawaited']);
+  });
+
+  it('skips reentrancy when lock_condition rejects the key', async () => {
+    const lock = new BetterLock({ reentrancy: 'error', lock_condition: key => key !== 'free' });
+
+    const result = await lock.acquire('a', () => lock.acquire('free', async () => 'unlocked'));
+
+    expect(result).toEqual('unlocked');
+  });
+});
+
+describe('BetterLock without async_hooks', () => {
+  let FallbackLock: typeof BetterLock;
+
+  beforeAll(() => {
+    const processObject = globalThis.process as any;
+    const original = processObject.getBuiltinModule;
+    processObject.getBuiltinModule = () => undefined;
+    try {
+      jest.isolateModules(() => {
+        FallbackLock = require('../src/index').default;
+      });
+    } finally {
+      processObject.getBuiltinModule = original;
+    }
+  });
+
+  it('runs a contended executor in the context of the previous holder, as before', async () => {
+    const store = new AsyncLocalStorage<string>();
+    const lock = new FallbackLock();
+    let seen: string;
+
+    await Promise.all([
+      store.run('first', () => lock.acquire(() => waitPromise(20))),
+      store.run('second', () =>
+        lock.acquire(async () => {
+          seen = store.getStore();
+        })
+      ),
+    ]);
+
+    expect(seen).toEqual('first');
+  });
+
+  it('makes a nested acquire wait for itself, as before', async () => {
+    const lock = new FallbackLock({ wait_timeout: 20, reentrancy: 'error' });
+    expect(FallbackLock.ReentrancyError).toBeDefined();
+
+    const result = await lock.acquire('a', async () => {
+      expect(lock.canAcquire('a')).toBeFalsy();
+      return lock.acquire('a', async () => 'never').catch(err => err);
+    });
+
+    expect(result).toBeInstanceOf(FallbackLock.WaitTimeoutError);
+  });
+
+  it('does not reject partially held keys, as before', async () => {
+    const lock = new FallbackLock({ wait_timeout: 20 });
+
+    const result = await lock.acquire('a', () =>
+      lock.acquire(['a', 'b'], async () => 'never').catch(err => err)
+    );
+
+    expect(result).toBeInstanceOf(FallbackLock.WaitTimeoutError);
+  });
+});
+
+function waitCallback(ms: number, ...args): (done: (...args: any) => void) => void {
+  return function (done) {
+    setTimeout(() => {
+      done(...args);
+    }, ms);
+  };
+}
+
+function waitPromise(ms, result?) {
+  return new Promise(resolve => {
+    setTimeout(() => {
+      resolve(result);
+    }, ms);
+  });
+}
+
+function expectMs(actual, expected, lowerBound = 5, upperBound = 80) {
+  expect(actual).toBeGreaterThanOrEqual(expected - lowerBound);
+  expect(actual).toBeLessThan(expected + upperBound);
+}

package/src/async_context.ts

@@ -0,0 +1,86 @@
+import { LockJob } from './internals';
+
+/**
+ * The subset of Node.js AsyncResource we use. Declared locally, so the package (and its type declarations)
+ * don't depend on Node.js types and keep working in browsers.
+ */
+export interface IAsyncResource {
+  runInAsyncScope<TResult>(fn: (...args: any[]) => TResult, thisArg?: any, ...args: any[]): TResult;
+}
+
+/**
+ * The subset of Node.js AsyncLocalStorage we use.
+ */
+interface IAsyncLocalStorage<TStore> {
+  getStore(): TStore | undefined;
+  run<TResult>(store: TStore, fn: () => TResult): TResult;
+}
+
+interface IAsyncHooksModule {
+  AsyncResource: new (type: string) => IAsyncResource;
+  AsyncLocalStorage: new <TStore>() => IAsyncLocalStorage<TStore>;
+}
+
+/**
+ * Jobs whose executors are currently running, in the current async context. Jobs from all lock instances
+ * share one list; a job only ever matches the queues of the lock that created it.
+ */
+type IHeldJobs = ReadonlyArray<LockJob<any>>;
+
+/**
+ * Look up Node.js async_hooks at runtime, without a static import, so bundlers and browsers never see it.
+ * Requires Node.js 20.16+ or 22.3+. Returns undefined everywhere else.
+ */
+function lookupAsyncHooks(): IAsyncHooksModule | undefined {
+  try {
+    const asyncHooks = (globalThis as any).process?.getBuiltinModule?.('node:async_hooks');
+    if (
+      asyncHooks &&
+      typeof asyncHooks.AsyncResource === 'function' &&
+      typeof asyncHooks.AsyncLocalStorage === 'function'
+    ) {
+      return asyncHooks;
+    }
+  } catch (err) {
+    // Unsupported runtime
+  }
+  return undefined;
+}
+
+const asyncHooks = lookupAsyncHooks();
+
+const lockContext: IAsyncLocalStorage<IHeldJobs> | undefined = asyncHooks
+  ? new asyncHooks.AsyncLocalStorage<IHeldJobs>()
+  : undefined;
+
+/**
+ * Capture the current async context, so a job can later run in it. Undefined if the runtime doesn't support it.
+ */
+export function captureAsyncContext(): IAsyncResource | undefined {
+  return asyncHooks ? new asyncHooks.AsyncResource('BetterLock') : undefined;
+}
+
+/**
+ * Jobs that are executing in the current async context (the caller is inside their executors).
+ * Ended jobs can still be listed here (eg. detached work that outlived its job), so check `ended_at`.
+ */
+export function getHeldJobs(): IHeldJobs | undefined {
+  return lockContext ? lockContext.getStore() : undefined;
+}
+
+/**
+ * Run fn with the given job added to the jobs held in the current async context.
+ */
+export function runHoldingJob<TResult>(job: LockJob<any>, fn: () => TResult): TResult {
+  if (!lockContext) {
+    return fn();
+  }
+  return lockContext.run(withHeldJob(lockContext.getStore(), job), fn);
+}
+
+function withHeldJob(heldJobs: IHeldJobs | undefined, job: LockJob<any>): IHeldJobs {
+  // Drop ended jobs, so the list doesn't grow when each executor schedules the next acquire
+  const result = heldJobs ? heldJobs.filter(heldJob => !heldJob.ended_at) : [];
+  result.push(job);
+  return result;
+}