better-lock 3.2.0 → 4.0.0

package/README.md

@@ -9,6 +9,8 @@ A (better) node.js lock library.
 - Queue and execution timeouts
 - Queue size limit
 - Lock on multiple keys
+- Reentrancy, with deadlock prevention (Node.js)
+- Executors run in the caller's async context, preserving `AsyncLocalStorage` stores (Node.js)
 - Extended stack traces
 - Promise and callback interface
 - JSDoc annotations
@@ -24,6 +26,27 @@ npm install --save better-lock
 yarn add better-lock
 ```
 
+### Browser usage
+
+Better Lock can be bundled for frontend use. A lock coordinates asynchronous work only within the
+current JavaScript context; it is not shared between tabs, workers, or other devices.
+
+```typescript
+import BetterLock from 'better-lock';
+
+const lock = new BetterLock();
+```
+
+The published package is CommonJS, so use it through a frontend bundler such as Vite or webpack. It
+cannot be loaded directly from a browser `<script type="module">` tag.
+
+Extended stack traces are enabled by default when the runtime supports `Error.captureStackTrace`.
+In browsers without that API, Better Lock automatically skips stack extension and otherwise works
+normally.
+
+[Async context](#async-context) and [reentrancy](#reentrancy) require Node.js `async_hooks`, so they are unavailable in
+browsers. See [Runtime support](#runtime-support).
+
 ### Documentation
 
 Full docs: <https://panta82.github.io/better-lock/>
@@ -132,15 +155,13 @@ lock.acquire(
 );
 ```
 
-You can see a bunch more usage examples in the spec file, [here](spec/better_lock.spec.ts);
-
 ### API
 
 - `new BetterLock(options)`  
   Create a new instance of `BetterLock`. Options should match interface `BetterLockOptions`. See below for details.
 
 - `BetterLock.acquire([key], executor, [callback], [jobOptions])`  
-  The main method you'll want to call. For each `key`, given `executor` will be called only one at a time. If you don't provide `callback`, it will return a promise that will be resolved with whatever `executor` returns.
+  The main method you'll want to call. For each `key`, given `executor` will be called only one at a time. If you don't provide `callback`, it will return a promise that will be resolved with whatever `executor` returns. If the caller already holds the keys, the executor runs without waiting (see [Reentrancy](#reentrancy)).
 
   - `key`: Arbitrary string under which to lock. It allows you to use the same lock instance for multiple parallel concerns. Eg. this might be a database record id or filename.
   - `executor`: Function that will be called within the lock. This function should have one of two forms.
@@ -154,7 +175,7 @@ You can see a bunch more usage examples in the spec file, [here](spec/better_loc
   an error, the lock will resolve/callback with the provided failureResult value (for example, a `null`).
 
 - `BetterLock.canAcquire([key])`  
-  Returns true if given key can be acquired.
+  Returns true if the given key can be acquired immediately: nothing holds it and nothing waits for it, or the caller already holds it and reentrancy is allowed.
 
 - `BetterLock.abort([key])`  
   Abort all jobs for a given key (or from the default job queue, if no key is given). Job executors will not be called. Callbacks will be called with `JobAbortedError`. Currently executing job will not be interrupted.
@@ -188,6 +209,9 @@ Most commonly used options are:
 - `queue_size`  
   Max queue size for waiting jobs.
 
+- `reentrancy`
+  `'allow'` (default) or `'error'`. What to do when the caller already holds all the requested keys. See [Reentrancy](#reentrancy).
+
 Default options are a static member `DEFAULT_OPTIONS` on the `BetterLock` class. During runtime, you can change the defaults like this:
 
 ```javascript
@@ -196,6 +220,47 @@ import BetterLock from 'better-lock';
 BetterLock.DEFAULT_OPTIONS.wait_timeout = 1000;
 ```
 
+### Reentrancy
+
+Reentrancy means you can re-take the same lock from within the lock. This uses node's [AsyncLocalStorage](https://beta.docs.nodejs.org/async_context#class-asynclocalstorage) under the hood.
+
+```javascript
+const lock = new BetterLock();
+
+async function saveUser(user) {
+  return lock.acquire(user.id, () => db.save(user));
+}
+
+async function renameUser(id, name) {
+  return lock.acquire(id, async () => {
+    const user = await db.load(id);
+    user.name = name;
+    // Holds `id` already, so this doesn't wait
+    return saveUser(user);
+  });
+}
+```
+
+If you use multi-keys, the reentrancy will only work if you already hold _all_ the requested keys. Otherwise, the acquire fails with `BetterLockReentrancyError` (passed to the callback, or rejected from the promise), to prevent deadlocks. `acquireOr` passes it on too, instead of returning `failureResult`.
+
+Reentrant acquire works transparently. You'll get an immediate callback in the next tick, without taking any extra slots. `canAcquire(key)` returns true. If `lock_condition` rejects the key, nothing is locked, so there is nothing to reenter.
+
+### Async context
+
+Executors and callbacks run in the async context of the `acquire` call. If you use `AsyncLocalStorage` (eg. for request ids in logs), code inside the executor sees the store of whoever called `acquire`, even if it had to wait for another caller to release the lock.
+
+```javascript
+const requestContext = new AsyncLocalStorage();
+
+requestContext.run({ requestId: 1 }, () => lock.acquire(() => slowTask()));
+requestContext.run({ requestId: 2 }, () =>
+  lock.acquire(() => {
+    // Runs after request 1 releases the lock, but still sees request 2's store
+    console.log(requestContext.getStore().requestId); // 2
+  })
+);
+```
+
 ### When to use
 
 This library is a good fit if:
@@ -205,15 +270,23 @@ This library is a good fit if:
 - You like good error messages, with full stack traces.
 - You like good types, either through typescript or JSDoc comments
 
-The library is not a good fit if:
+The library is not a good fit if you need a **shared lock between different processes**. BetterLock is single process only.
 
-- **You need lock reentrancy.**  
-  There is no good solution for this in node.js that I know of. And this library doesn't offer any.
+### Change log
 
-- **You need a shared lock between different nodes**  
-  This library is a single process only. If you need to coordinate multiple apps or services, you need a different library.
+#### **4.0.0** (_2026/11/09_)
 
-### Change log
+- Added **reentrancy**, You can now acquire the same lock again from within the lock. Set `options.reentrancy` to `"error"` to fail with `BetterLockReentrancyError` instead of re-locking the keys.
+- Executors and callbacks run in the async context of their `acquire` call, so `AsyncLocalStorage` stores no longer leak from the previous lock holder.
+- Both features require `process.getBuiltinModule` (Node.js 20.16+ or 22.3+). In other runtimes, the lock behaves as before.
+
+#### **3.3.0** (_2026/08/25_)
+
+Make the library compatible with browsers.
+
+#### **3.2.0** (_2024/06/21_)
+
+Add new api `canAcquire`. A helper for "best effort" lock acquisition.
 
 #### **3.2.0** (_2024/06/21_)
 

package/dist/async_context.d.ts

@@ -0,0 +1,27 @@
+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;
+}
+/**
+ * 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.
+ */
+declare type IHeldJobs = ReadonlyArray<LockJob<any>>;
+/**
+ * Capture the current async context, so a job can later run in it. Undefined if the runtime doesn't support it.
+ */
+export declare function captureAsyncContext(): IAsyncResource | 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 declare function getHeldJobs(): IHeldJobs | undefined;
+/**
+ * Run fn with the given job added to the jobs held in the current async context.
+ */
+export declare function runHoldingJob<TResult>(job: LockJob<any>, fn: () => TResult): TResult;
+export {};

package/dist/async_context.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHoldingJob = exports.getHeldJobs = exports.captureAsyncContext = void 0;
+/**
+ * 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() {
+    var _a, _b;
+    try {
+        var asyncHooks_1 = (_b = (_a = globalThis.process) === null || _a === void 0 ? void 0 : _a.getBuiltinModule) === null || _b === void 0 ? void 0 : _b.call(_a, 'node:async_hooks');
+        if (asyncHooks_1 &&
+            typeof asyncHooks_1.AsyncResource === 'function' &&
+            typeof asyncHooks_1.AsyncLocalStorage === 'function') {
+            return asyncHooks_1;
+        }
+    }
+    catch (err) {
+        // Unsupported runtime
+    }
+    return undefined;
+}
+var asyncHooks = lookupAsyncHooks();
+var lockContext = asyncHooks
+    ? new asyncHooks.AsyncLocalStorage()
+    : undefined;
+/**
+ * Capture the current async context, so a job can later run in it. Undefined if the runtime doesn't support it.
+ */
+function captureAsyncContext() {
+    return asyncHooks ? new asyncHooks.AsyncResource('BetterLock') : undefined;
+}
+exports.captureAsyncContext = captureAsyncContext;
+/**
+ * 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`.
+ */
+function getHeldJobs() {
+    return lockContext ? lockContext.getStore() : undefined;
+}
+exports.getHeldJobs = getHeldJobs;
+/**
+ * Run fn with the given job added to the jobs held in the current async context.
+ */
+function runHoldingJob(job, fn) {
+    if (!lockContext) {
+        return fn();
+    }
+    return lockContext.run(withHeldJob(lockContext.getStore(), job), fn);
+}
+exports.runHoldingJob = runHoldingJob;
+function withHeldJob(heldJobs, job) {
+    // Drop ended jobs, so the list doesn't grow when each executor schedules the next acquire
+    var result = heldJobs ? heldJobs.filter(function (heldJob) { return !heldJob.ended_at; }) : [];
+    result.push(job);
+    return result;
+}
+//# sourceMappingURL=async_context.js.map

package/dist/async_context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async_context.js","sourceRoot":"","sources":["../src/async_context.ts"],"names":[],"mappings":";;;AA6BA;;;GAGG;AACH,SAAS,gBAAgB;;IACvB,IAAI;QACF,IAAM,YAAU,GAAG,MAAA,MAAC,UAAkB,CAAC,OAAO,0CAAE,gBAAgB,mDAAG,kBAAkB,CAAC,CAAC;QACvF,IACE,YAAU;YACV,OAAO,YAAU,CAAC,aAAa,KAAK,UAAU;YAC9C,OAAO,YAAU,CAAC,iBAAiB,KAAK,UAAU,EAClD;YACA,OAAO,YAAU,CAAC;SACnB;KACF;IAAC,OAAO,GAAG,EAAE;QACZ,sBAAsB;KACvB;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,IAAM,UAAU,GAAG,gBAAgB,EAAE,CAAC;AAEtC,IAAM,WAAW,GAA8C,UAAU;IACvE,CAAC,CAAC,IAAI,UAAU,CAAC,iBAAiB,EAAa;IAC/C,CAAC,CAAC,SAAS,CAAC;AAEd;;GAEG;AACH,SAAgB,mBAAmB;IACjC,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7E,CAAC;AAFD,kDAEC;AAED;;;GAGG;AACH,SAAgB,WAAW;IACzB,OAAO,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC;AAFD,kCAEC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAU,GAAiB,EAAE,EAAiB;IACzE,IAAI,CAAC,WAAW,EAAE;QAChB,OAAO,EAAE,EAAE,CAAC;KACb;IACD,OAAO,WAAW,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;AACvE,CAAC;AALD,sCAKC;AAED,SAAS,WAAW,CAAC,QAA+B,EAAE,GAAiB;IACrE,0FAA0F;IAC1F,IAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAA,OAAO,IAAI,OAAA,CAAC,OAAO,CAAC,QAAQ,EAAjB,CAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/better_lock.d.ts

@@ -11,6 +11,10 @@ export declare class BetterLock {
     private readonly options;
     private readonly log;
     private readonly queues;
+    /**
+     * Reentrant jobs that haven't started executing yet. They are not in any key queue, so we track them here for abort().
+     */
+    private readonly pendingReentrantJobs;
     /**
      * Create a better lock instance
      */
@@ -20,9 +24,20 @@ export declare class BetterLock {
      */
     private getQueue;
     /**
-     * Returns true if the caller can *immediately* acquire the lock. There is nothing holding the key and nothing in the queue.
+     * Returns true if the caller can *immediately* acquire the lock. There is nothing holding the key and nothing in the queue,
+     * or the caller already holds the key and reentrancy is allowed.
      */
     canAcquire(key?: string): boolean;
+    /**
+     * True if the given queue's key is held by a job that is executing in the caller's async context.
+     * Ended jobs don't count, so detached work that outlives its job doesn't skip the lock.
+     */
+    private isHeldByCaller;
+    /**
+     * Find which of the given keys the caller already holds, and the jobs holding them.
+     * Returns null if the caller holds none of them.
+     */
+    private findHeldKeys;
     private normalizeAndValidateKey;
     acquire<TResult extends IValidResult>(executor: IPromiseExecutor<TResult>, jobOptions?: ILockJobOptions): Promise<TResult>;
     acquire<TResult extends IValidResult>(executor: ICallbackExecutor<TResult>, jobOptions?: ILockJobOptions): Promise<TResult>;
@@ -30,6 +45,10 @@ export declare class BetterLock {
     acquire<TResult extends IValidResult>(key: ILockKey | Array<ILockKey>, executor: IPromiseExecutor<TResult>, jobOptions?: ILockJobOptions): Promise<TResult>;
     acquire<TResult extends IValidResult>(key: ILockKey | Array<ILockKey>, executor: ICallbackExecutor<TResult>, jobOptions?: ILockJobOptions): Promise<TResult>;
     acquire<TResult extends IValidResult>(key: ILockKey | Array<ILockKey>, executor: ICallbackExecutor<TResult>, callback: ICallback<TResult>, jobOptions?: ILockJobOptions): void;
+    /**
+     * Add job to its key queues and start waiting for the keys
+     */
+    private enqueueJob;
     acquireOr<TResult extends IValidResult>(failureResult: TResult, executor: IPromiseExecutor<TResult>, jobOptions?: ILockJobOptions): Promise<TResult>;
     acquireOr<TResult extends IValidResult>(failureResult: TResult, executor: ICallbackExecutor<TResult>, jobOptions?: ILockJobOptions): Promise<TResult>;
     acquireOr<TResult extends IValidResult>(failureResult: TResult, executor: ICallbackExecutor<TResult>, callback: ICallback<TResult>, jobOptions?: ILockJobOptions): void;
@@ -51,6 +70,7 @@ export declare class BetterLock {
      * @param [key]
      */
     abort(key?: ILockKey): void;
+    private removePendingReentrantJob;
     /**
      * Abort all pending jobs from all queues.
      * Currently executing jobs will not be interrupted.

package/dist/better_lock.js

@@ -10,6 +10,7 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BetterLock = void 0;
+var async_context_1 = require("./async_context");
 var errors_1 = require("./errors");
 var internals_1 = require("./internals");
 var tools = require("./tools");
@@ -21,6 +22,10 @@ var BetterLock = /** @class */ (function () {
      * Create a better lock instance
      */
     function BetterLock(options) {
+        /**
+         * Reentrant jobs that haven't started executing yet. They are not in any key queue, so we track them here for abort().
+         */
+        this.pendingReentrantJobs = [];
         this.options = tools.assign({}, [BetterLock.DEFAULT_OPTIONS, options]);
         this.log = tools.makeLog(this.options.name, this.options.log);
         this.queues = {};
@@ -39,11 +44,43 @@ var BetterLock = /** @class */ (function () {
         return queue;
     };
     /**
-     * Returns true if the caller can *immediately* acquire the lock. There is nothing holding the key and nothing in the queue.
+     * Returns true if the caller can *immediately* acquire the lock. There is nothing holding the key and nothing in the queue,
+     * or the caller already holds the key and reentrancy is allowed.
      */
     BetterLock.prototype.canAcquire = function (key) {
         var queue = this.getQueue(key);
-        return !queue.active && !queue.jobs.length;
+        if (!queue.active && !queue.jobs.length) {
+            return true;
+        }
+        return this.options.reentrancy !== 'error' && this.isHeldByCaller(queue, (0, async_context_1.getHeldJobs)());
+    };
+    /**
+     * True if the given queue's key is held by a job that is executing in the caller's async context.
+     * Ended jobs don't count, so detached work that outlives its job doesn't skip the lock.
+     */
+    BetterLock.prototype.isHeldByCaller = function (queue, heldJobs) {
+        var holder = queue.active;
+        return !!(heldJobs && holder && !holder.ended_at && heldJobs.indexOf(holder) >= 0);
+    };
+    /**
+     * Find which of the given keys the caller already holds, and the jobs holding them.
+     * Returns null if the caller holds none of them.
+     */
+    BetterLock.prototype.findHeldKeys = function (keys) {
+        var heldJobs = (0, async_context_1.getHeldJobs)();
+        if (!heldJobs || !keys.length) {
+            return null;
+        }
+        var holders = [];
+        var heldKeys = [];
+        for (var i = 0; i < keys.length; i++) {
+            var queue = this.getQueue(keys[i]);
+            if (this.isHeldByCaller(queue, heldJobs)) {
+                holders.push(queue.active);
+                heldKeys.push(keys[i]);
+            }
+        }
+        return holders.length ? { holders: holders, heldKeys: heldKeys } : null;
     };
     BetterLock.prototype.normalizeAndValidateKey = function (key) {
         if (key === undefined) {
@@ -65,6 +102,10 @@ var BetterLock = /** @class */ (function () {
      * Acquire the lock for given key or list of keys. If waiting on a list, keys will be acquired in order,
      * as they become free. Any deadlock prevention must be handled by the caller.
      *
+     * If the caller already holds all the keys (it runs inside an executor holding them), the executor runs
+     * without waiting. If it holds only some of the keys, or the "reentrancy" option is set to "error", the
+     * callback (or the promise) gets BetterLockReentrancyError. Reentrancy requires Node.js AsyncLocalStorage.
+     *
      * Once the lock is acquired, we will call the executor function, with a "done" method.
      * You must call "done" to release the lock. Alternatively, return a Promise; lock will be released
      * once promise resolves or rejects.
@@ -77,7 +118,6 @@ var BetterLock = /** @class */ (function () {
      * @param jobOptions Options to be applied on this job only
      */
     BetterLock.prototype.acquire = function (key, executor, callback, jobOptions) {
-        var _this = this;
         if (tools.isFunction(key)) {
             // Presume we weren't given a key (first form)
             jobOptions = callback;
@@ -124,17 +164,49 @@ var BetterLock = /** @class */ (function () {
         if (!tools.isFunction(callback)) {
             throw new errors_1.BetterLockInvalidArgumentError(this.options.name, 'callback', 'a function', callback);
         }
+        // Invalid arguments throw above. Reentrancy errors depend on where acquire is called from,
+        // so they are reported like other lock errors: through the callback or promise.
+        var held = this.findHeldKeys(keys);
+        if (held &&
+            // Waiting for the remaining keys while holding these could deadlock
+            (held.heldKeys.length < keys.length || effectiveJobOptions.reentrancy === 'error')) {
+            var err_1 = new errors_1.BetterLockReentrancyError(this.options.name, keys, held.heldKeys);
+            this.log(err_1.message);
+            // Never call back synchronously from acquire
+            setTimeout(function () { return callback(err_1); }, 0);
+            return callback.promise;
+        }
+        var reentrantHolders = held ? held.holders : null;
         var job = new internals_1.LockJob(keys, executor, callback, effectiveJobOptions);
+        // Executor and callback will run in the caller's async context, not the context of whoever releases the lock
+        job.async_context = (0, async_context_1.captureAsyncContext)();
         // Set incoming stack
-        if (effectiveJobOptions.extend_stack_traces) {
+        if (effectiveJobOptions.extend_stack_traces &&
+            typeof Error.captureStackTrace === 'function') {
             var tempErr = new Error();
             Error.captureStackTrace(tempErr, this.acquire);
             job.incoming_stack = tempErr.stack;
         }
-        // Add job to its key queues
+        if (reentrantHolders) {
+            // The caller holds all the keys. Run without entering the queues.
+            job.reentrant_holders = reentrantHolders;
+            this.pendingReentrantJobs.push(job);
+            this.log("Reentering ".concat(job));
+            this.executeJob(job);
+        }
+        else {
+            this.enqueueJob(job);
+        }
+        return callback.promise;
+    };
+    /**
+     * Add job to its key queues and start waiting for the keys
+     */
+    BetterLock.prototype.enqueueJob = function (job) {
+        var _this = this;
         var queuesToUpdate = [];
-        for (var i = 0; i < keys.length; i++) {
-            var queue = this.getQueue(keys[i]);
+        for (var i = 0; i < job.keys.length; i++) {
+            var queue = this.getQueue(job.keys[i]);
             queue.jobs.push(job);
             queuesToUpdate.push(queue);
         }
@@ -153,7 +225,6 @@ var BetterLock = /** @class */ (function () {
             // Special case. We are given empty list of keys. We will immediately execute jobs like this.
             this.executeJob(job);
         }
-        return callback.promise;
     };
     /**
      * The same as acquire, except if the lock can't be acquired (the executor never gets called), instead of throwing
@@ -235,19 +306,32 @@ var BetterLock = /** @class */ (function () {
         job.wait_timeout_id = null;
         // We want to do the rest of this in a separate context, because we don't want user executor code
         // to ever interfere with the code calling acquire().
-        setImmediate(function () {
+        setTimeout(function () {
             // Make sure job hasn't been ended in the meantime
             if (job.executed_at || job.ended_at) {
                 return;
             }
-            // Validate this job is holding all queues it needs
-            for (var i = 0; i < job.keys.length; i++) {
-                var queue = _this.getQueue(job.keys[i]);
-                if (queue.active !== job) {
-                    // This should never happen
-                    return _this.endJob(job, [
-                        new errors_1.BetterLockInternalError(_this.options.name, "Corrupted wait queue state for ".concat(queue.key)),
-                    ]);
+            if (job.reentrant_holders) {
+                _this.removePendingReentrantJob(job);
+                if (job.reentrant_holders.some(function (holder) { return holder.ended_at; })) {
+                    // The holder released the keys before this job could start (eg. the reentrant acquire wasn't awaited).
+                    // Wait for the keys like any other job.
+                    _this.log("".concat(job, " is no longer reentrant because its holder has ended"));
+                    job.reentrant_holders = null;
+                    _this.enqueueJob(job);
+                    return;
+                }
+            }
+            else {
+                // Validate this job is holding all queues it needs
+                for (var i = 0; i < job.keys.length; i++) {
+                    var queue = _this.getQueue(job.keys[i]);
+                    if (queue.active !== job) {
+                        // This should never happen
+                        return _this.endJob(job, [
+                            new errors_1.BetterLockInternalError(_this.options.name, "Corrupted wait queue state for ".concat(queue.key)),
+                        ]);
+                    }
                 }
             }
             // Mark job as having started executing
@@ -263,29 +347,43 @@ var BetterLock = /** @class */ (function () {
                 _this.log("Done called for ".concat(job));
                 _this.endJob(job, args);
             };
-            if (job.executor.length > 0) {
-                // Callback interface
-                job.executor(lockDone);
-                return;
-            }
-            // Promise interface
-            var executorResult;
-            try {
-                executorResult = job.executor();
-            }
-            catch (err) {
-                // Error thrown directly from executor
-                lockDone(err);
+            var runExecutor = function () {
+                if (job.executor.length > 0) {
+                    // Callback interface
+                    job.executor(lockDone);
+                    return;
+                }
+                // Promise interface
+                var executorResult;
+                try {
+                    executorResult = job.executor();
+                }
+                catch (err) {
+                    // Error thrown directly from executor
+                    lockDone(err);
+                }
+                // Promise sniffing
+                if (_this.options.promise_tester(executorResult)) {
+                    executorResult.then(function (res) { return lockDone(null, res); }, function (err) { return lockDone(err); });
+                }
+                else {
+                    // "promise" is just some random value. We don't have to wait
+                    lockDone(null, executorResult);
+                }
+            };
+            if (!job.async_context) {
+                // No async context support in this runtime
+                runExecutor();
             }
-            // Promise sniffing
-            if (_this.options.promise_tester(executorResult)) {
-                executorResult.then(function (res) { return lockDone(null, res); }, function (err) { return lockDone(err); });
+            else if (job.reentrant_holders) {
+                // The caller's context already records the holders
+                job.async_context.runInAsyncScope(runExecutor);
             }
             else {
-                // "promise" is just some random value. We don't have to wait
-                lockDone(null, executorResult);
+                // Restore the caller's context first, then record this job as holding its keys inside it
+                job.async_context.runInAsyncScope(function () { return (0, async_context_1.runHoldingJob)(job, runExecutor); });
             }
-        });
+        }, 0);
     };
     BetterLock.prototype.onWaitTimeout = function (job) {
         this.log("".concat(job, " has timed out after waiting in queue for ").concat(new Date().valueOf() - job.enqueued_at.valueOf(), "ms"));
@@ -296,6 +394,7 @@ var BetterLock = /** @class */ (function () {
         this.endJob(job, [new errors_1.BetterLockExecutionTimeoutError(this.options.name, job)]);
     };
     BetterLock.prototype.endJob = function (job, callbackArgs) {
+        var _a;
         var _this = this;
         if (job.ended_at) {
             this.log("WARNING: ".concat(job, " is trying to end, but it has already ended at ").concat(job.ended_at.toISOString(), ". Called with arguments: ").concat(callbackArgs));
@@ -306,9 +405,14 @@ var BetterLock = /** @class */ (function () {
         clearTimeout(job.execution_timeout_id);
         job.execution_timeout_id = null;
         job.ended_at = new Date();
+        // Reentrant jobs never enter key queues, so they have nothing to release
+        var keysToRelease = job.reentrant_holders ? [] : job.keys;
+        if (job.reentrant_holders) {
+            this.removePendingReentrantJob(job);
+        }
         var queuesToUpdate = [];
-        for (var i = 0; i < job.keys.length; i++) {
-            var queue = this.getQueue(job.keys[i]);
+        for (var i = 0; i < keysToRelease.length; i++) {
+            var queue = this.getQueue(keysToRelease[i]);
             queuesToUpdate.push(queue);
             if (queue.active === job) {
                 // This job was holding on the queue's key
@@ -329,11 +433,16 @@ var BetterLock = /** @class */ (function () {
         }
         // Call the callback
         try {
-            job.callback.apply(null, callbackArgs);
+            if (job.async_context) {
+                (_a = job.async_context).runInAsyncScope.apply(_a, __spreadArray([job.callback, null], callbackArgs, false));
+            }
+            else {
+                job.callback.apply(null, callbackArgs);
+            }
         }
         finally {
             // Whatever happens, schedule a queue update
-            setImmediate(function () { return _this.update(queuesToUpdate); });
+            setTimeout(function () { return _this.update(queuesToUpdate); }, 0);
         }
     };
     /**
@@ -352,6 +461,18 @@ var BetterLock = /** @class */ (function () {
             // If we have a job holding this queue that hasn't been executed yet, abort it as well
             this.endJob(queue.active, [new errors_1.BetterLockJobAbortedError(this.options.name, queue.active)]);
         }
+        // Reentrant jobs for this key that haven't started yet
+        this.pendingReentrantJobs.slice().forEach(function (job) {
+            if (job.keys.some(function (jobKey) { return _this.getQueue(jobKey) === queue; })) {
+                _this.endJob(job, [new errors_1.BetterLockJobAbortedError(_this.options.name, job)]);
+            }
+        });
+    };
+    BetterLock.prototype.removePendingReentrantJob = function (job) {
+        var index = this.pendingReentrantJobs.indexOf(job);
+        if (index >= 0) {
+            this.pendingReentrantJobs.splice(index, 1);
+        }
     };
     /**
      * Abort all pending jobs from all queues.
@@ -370,6 +491,7 @@ var BetterLock = /** @class */ (function () {
     BetterLock.DEFAULT_OPTIONS = {
         extend_stack_traces: true,
         promise_tester: function (p) { return p && typeof p.then === 'function'; },
+        reentrancy: 'allow',
     };
     return BetterLock;
 }());