better-lock 3.1.0 → 3.2.0

package/docs/types/_internal_.ICallback.html

@@ -23,7 +23,7 @@ but also old-school callbacks, with varargs return values.</p>
 <li>
 <h4>TResult</h4></li></ul><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/panta82/better-lock/blob/336aa4f/src/types.ts#L14">types.ts:14</a></li></ul></aside></div>
+<li>Defined in <a href="https://github.com/panta82/better-lock/blob/91aeb2b/src/types.ts#L14">types.ts:14</a></li></ul></aside></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">

package/docs/types/_internal_.ICallbackExecutor.html

@@ -37,7 +37,7 @@ It can either accept a done() function, or return a promise.</p>
 <h5>lockDone: <a href="_internal_.ICallback.html" class="tsd-signature-type" data-tsd-kind="Type alias">ICallback</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type" data-tsd-kind="Type parameter">TResult</span><span class="tsd-signature-symbol">&gt;</span></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4></li></ul></li></ul></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/panta82/better-lock/blob/336aa4f/src/types.ts#L22">types.ts:22</a></li></ul></aside></div>
+<li>Defined in <a href="https://github.com/panta82/better-lock/blob/91aeb2b/src/types.ts#L22">types.ts:22</a></li></ul></aside></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">

package/docs/types/_internal_.IErrorExports.html

@@ -16,7 +16,7 @@
 <h1>Type alias IErrorExports</h1></div>
 <div class="tsd-signature">IError<wbr/>Exports<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">typeof </span><a href="../modules/_internal_.__home_panta_dev_pantas_better_lock_src_errors_.html" class="tsd-signature-type" data-tsd-kind="Namespace">&quot;/home/panta/dev/pantas/better-lock/src/errors&quot;</a></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/panta82/better-lock/blob/336aa4f/src/types.ts#L3">types.ts:3</a></li></ul></aside></div>
+<li>Defined in <a href="https://github.com/panta82/better-lock/blob/91aeb2b/src/types.ts#L3">types.ts:3</a></li></ul></aside></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">

package/docs/types/_internal_.IPromiseExecutor.html

@@ -29,7 +29,7 @@
 <li class="tsd-description">
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type" data-tsd-kind="Type parameter">TResult</span><span class="tsd-signature-symbol">&gt;</span></h4></li></ul></li></ul></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/panta82/better-lock/blob/336aa4f/src/types.ts#L23">types.ts:23</a></li></ul></aside></div>
+<li>Defined in <a href="https://github.com/panta82/better-lock/blob/91aeb2b/src/types.ts#L23">types.ts:23</a></li></ul></aside></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">

package/docs/variables/BetterLock.html

@@ -15,7 +15,7 @@
 <h1>Variable BetterLock<code class="tsd-tag ts-flagConst">Const</code> </h1></div>
 <div class="tsd-signature">Better<wbr/>Lock<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">typeof </span><a href="../modules/_internal_.html" class="tsd-signature-type" data-tsd-kind="Namespace">&lt;internal&gt;</a><span class="tsd-signature-symbol">.</span><a href="../classes/_internal_.BetterLock.html" class="tsd-signature-type" data-tsd-kind="Class">BetterLock</a><span class="tsd-signature-symbol"> &amp; </span><span class="tsd-signature-symbol">{ </span>BetterLock<span class="tsd-signature-symbol">: </span><span class="tsd-signature-symbol">typeof </span><a href="../modules/_internal_.html" class="tsd-signature-type" data-tsd-kind="Namespace">&lt;internal&gt;</a><span class="tsd-signature-symbol">.</span><a href="../classes/_internal_.BetterLock.html" class="tsd-signature-type" data-tsd-kind="Class">BetterLock</a><span class="tsd-signature-symbol">; </span>Error<span class="tsd-signature-symbol">: </span><span class="tsd-signature-symbol">typeof </span><a href="../classes/BetterLockError.html" class="tsd-signature-type" data-tsd-kind="Class">BetterLockError</a><span class="tsd-signature-symbol">; </span>ExecutionTimeoutError<span class="tsd-signature-symbol">: </span><span class="tsd-signature-symbol">typeof </span><a href="../classes/BetterLockExecutionTimeoutError.html" class="tsd-signature-type" data-tsd-kind="Class">BetterLockExecutionTimeoutError</a><span class="tsd-signature-symbol">; </span>InternalError<span class="tsd-signature-symbol">: </span><span class="tsd-signature-symbol">typeof </span><a href="../classes/BetterLockInternalError.html" class="tsd-signature-type" data-tsd-kind="Class">BetterLockInternalError</a><span class="tsd-signature-symbol">; </span>InvalidArgumentError<span class="tsd-signature-symbol">: </span><span class="tsd-signature-symbol">typeof </span><a href="../classes/BetterLockInvalidArgumentError.html" class="tsd-signature-type" data-tsd-kind="Class">BetterLockInvalidArgumentError</a><span class="tsd-signature-symbol">; </span>JobAbortedError<span class="tsd-signature-symbol">: </span><span class="tsd-signature-symbol">typeof </span><a href="../classes/BetterLockJobAbortedError.html" class="tsd-signature-type" data-tsd-kind="Class">BetterLockJobAbortedError</a><span class="tsd-signature-symbol">; </span>QueueOverflowError<span class="tsd-signature-symbol">: </span><span class="tsd-signature-symbol">typeof </span><a href="../classes/BetterLockQueueOverflowError.html" class="tsd-signature-type" data-tsd-kind="Class">BetterLockQueueOverflowError</a><span class="tsd-signature-symbol">; </span>WaitTimeoutError<span class="tsd-signature-symbol">: </span><span class="tsd-signature-symbol">typeof </span><a href="../classes/BetterLockWaitTimeoutError.html" class="tsd-signature-type" data-tsd-kind="Class">BetterLockWaitTimeoutError</a><span class="tsd-signature-symbol"> }</span><span class="tsd-signature-symbol"> = ...</span></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/panta82/better-lock/blob/336aa4f/src/index.ts#L43">index.ts:43</a></li></ul></aside></div>
+<li>Defined in <a href="https://github.com/panta82/better-lock/blob/91aeb2b/src/index.ts#L43">index.ts:43</a></li></ul></aside></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">

package/package.json

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

package/spec/better_lock.spec.ts

@@ -686,6 +686,106 @@ describe('BetterLock', () => {
       ]);
     });
   });
+
+  describe('acquireOr', () => {
+    describe('will correctly handle failureResults', () => {
+      it('from QueueOverflowError', testDone => {
+        const lock = new BetterLock({
+          wait_timeout: 200, // should never trigger
+          execution_timeout: 300, // should never trigger
+          queue_size: 2,
+        });
+
+        let cbCount = 0;
+        lock.acquireOr(0, waitCallback(25, null, 1), (err, res) => {
+          // The executing one
+          cbCount++;
+          expect(cbCount).toEqual(2);
+          expect(err).toBeNull();
+          expect(res).toEqual(1);
+        });
+        lock.acquireOr(0, waitCallback(5, null, 2), (err, res) => {
+          // This is the one that will get kicked out
+          cbCount++;
+          expect(cbCount).toEqual(1);
+          expect(err).toBeNull();
+          expect(res).toEqual(0);
+        });
+        lock.acquireOr(0, waitCallback(5, null, 3), (err, res) => {
+          cbCount++;
+          expect(cbCount).toEqual(3);
+          expect(err).toBeNull();
+          expect(res).toEqual(3);
+          testDone();
+        });
+        lock.acquireOr(0, waitCallback(5, null, 4), (err, res) => {
+          // This one will trigger the kicking out.
+          cbCount++;
+          expect(cbCount).toEqual(4);
+          expect(err).toBeNull();
+          expect(res).toEqual(4);
+        });
+      });
+
+      it('from WaitTimeoutError', async () => {
+        const lock = new BetterLock({
+          wait_timeout: 50,
+          execution_timeout: 100, // should never trigger
+        });
+
+        const promise1 = lock.acquireOr('fail1', waitCallback(75, null, 'ok1'));
+        const promise2 = lock.acquireOr('fail2', waitCallback(200000, null, 'ok2'));
+
+        // Enqueue after some time, this one should run
+        await waitPromise(50);
+        const promise3 = lock.acquireOr('fail3', waitCallback(50, null, 'ok3'));
+
+        const results = await Promise.all([promise1, promise2, promise3]);
+
+        expect(results).toEqual(['ok1', 'fail2', 'ok3']);
+      });
+
+      it('from AbortedError', async () => {
+        const lock = new BetterLock();
+
+        let noCallCount = 0;
+        const noCall = () => {
+          noCallCount++;
+        };
+
+        let cbCount = 0;
+        const callback = (err, res) => {
+          cbCount++;
+          expect(err).toBeNull();
+          expect(res).toEqual('fail');
+        };
+
+        lock.acquireOr('fail', noCall, callback);
+        lock.acquireOr('a', 'fail', noCall, callback);
+        lock.acquireOr('b', 'fail', noCall, callback);
+
+        lock.abortAll();
+
+        expect(lock.canAcquire()).toBeTruthy();
+        expect(lock.canAcquire('a')).toBeTruthy();
+        expect(lock.canAcquire('b')).toBeTruthy();
+        expect(noCallCount).toEqual(0);
+        expect(cbCount).toEqual(3);
+      });
+    });
+
+    it('will correctly pass other errors ', async () => {
+      const lock = new BetterLock({
+        execution_timeout: 10,
+      });
+
+      await expect(
+        lock.acquireOr('fail', async () => {
+          await waitPromise(20); // Should cause ExecutionTimeoutError.
+        })
+      ).rejects.toBeInstanceOf(BetterLock.ExecutionTimeoutError);
+    });
+  });
 });
 
 function waitCallback(ms: number, ...args): (done: (...args: any) => void) => void {

package/src/better_lock.ts

@@ -5,11 +5,12 @@ import {
   BetterLockJobAbortedError,
   BetterLockQueueOverflowError,
   BetterLockWaitTimeoutError,
+  isAcquisitionFailureError,
 } from './errors';
 import { KeyQueue, LockJob } from './internals';
 import { ILockJobOptions, IOptions } from './options';
 import * as tools from './tools';
-import { ICallback, ICallbackExecutor, ILockKey, IPromiseExecutor } from './types';
+import { ICallback, ICallbackExecutor, ILockKey, IPromiseExecutor, IValidResult } from './types';
 
 /**
  * Main better lock class.
@@ -80,30 +81,30 @@ export class BetterLock {
     );
   }
 
-  public acquire<TResult>(
+  public acquire<TResult extends IValidResult>(
     executor: IPromiseExecutor<TResult>,
     jobOptions?: ILockJobOptions
   ): Promise<TResult>;
-  public acquire<TResult>(
+  public acquire<TResult extends IValidResult>(
     executor: ICallbackExecutor<TResult>,
     jobOptions?: ILockJobOptions
   ): Promise<TResult>;
-  public acquire<TResult>(
+  public acquire<TResult extends IValidResult>(
     executor: ICallbackExecutor<TResult>,
     callback: ICallback<TResult>,
     jobOptions?: ILockJobOptions
   ): void;
-  public acquire<TResult>(
+  public acquire<TResult extends IValidResult>(
     key: ILockKey | Array<ILockKey>,
     executor: IPromiseExecutor<TResult>,
     jobOptions?: ILockJobOptions
   ): Promise<TResult>;
-  public acquire<TResult>(
+  public acquire<TResult extends IValidResult>(
     key: ILockKey | Array<ILockKey>,
     executor: ICallbackExecutor<TResult>,
     jobOptions?: ILockJobOptions
   ): Promise<TResult>;
-  public acquire<TResult>(
+  public acquire<TResult extends IValidResult>(
     key: ILockKey | Array<ILockKey>,
     executor: ICallbackExecutor<TResult>,
     callback: ICallback<TResult>,
@@ -125,7 +126,7 @@ export class BetterLock {
    * @param jobOptions Options to be applied on this job only
    */
   public acquire(key, executor?, callback?, jobOptions?) {
-    if (tools.isFunction(key) || tools.isObject(key)) {
+    if (tools.isFunction(key)) {
       // Presume we weren't given a key (first form)
       jobOptions = callback;
       callback = executor;
@@ -224,6 +225,86 @@ export class BetterLock {
     return (callback as any).promise;
   }
 
+  public acquireOr<TResult extends IValidResult>(
+    failureResult: TResult,
+    executor: IPromiseExecutor<TResult>,
+    jobOptions?: ILockJobOptions
+  ): Promise<TResult>;
+  public acquireOr<TResult extends IValidResult>(
+    failureResult: TResult,
+    executor: ICallbackExecutor<TResult>,
+    jobOptions?: ILockJobOptions
+  ): Promise<TResult>;
+  public acquireOr<TResult extends IValidResult>(
+    failureResult: TResult,
+    executor: ICallbackExecutor<TResult>,
+    callback: ICallback<TResult>,
+    jobOptions?: ILockJobOptions
+  ): void;
+  public acquireOr<TResult extends IValidResult>(
+    key: ILockKey | Array<ILockKey>,
+    failureResult: TResult,
+    executor: IPromiseExecutor<TResult>,
+    jobOptions?: ILockJobOptions
+  ): Promise<TResult>;
+  public acquireOr<TResult extends IValidResult>(
+    key: ILockKey | Array<ILockKey>,
+    failureResult: TResult,
+    executor: ICallbackExecutor<TResult>,
+    jobOptions?: ILockJobOptions
+  ): Promise<TResult>;
+  public acquireOr<TResult extends IValidResult>(
+    key: ILockKey | Array<ILockKey>,
+    failureResult: TResult,
+    executor: ICallbackExecutor<TResult>,
+    callback: ICallback<TResult>,
+    jobOptions?: ILockJobOptions
+  ): void;
+  /**
+   * The same as acquire, except if the lock can't be acquired (the executor never gets called), instead of throwing
+   * an error, the lock will resolve/callback with the provided failureResult value (for example, a `null`).
+   * @param key Named key or array of keys for this particular call. Calls with different keys will be run in parallel. Not required.
+   * @param failureResult The value to return if the executor never get called. This happens instead of rejecting.
+   * @param executor Function that will run inside the lock. Required.
+   * @param callback Function to be called after the executor finishes, or there is an execution timeout. Leave out to use promises.
+   * @param jobOptions Options to be applied on this job only
+   */
+  public acquireOr(key, failureResult, executor?, callback?, jobOptions?) {
+    if (tools.isFunction(failureResult)) {
+      // There is no key given. Reshuffle.
+      jobOptions = callback;
+      callback = executor;
+      executor = failureResult;
+      failureResult = key;
+      key = null;
+    }
+
+    if (tools.isFunction(callback)) {
+      const originalCallback = callback;
+      callback = (err, ...results) => {
+        if (isAcquisitionFailureError(err)) {
+          originalCallback(null, failureResult);
+        } else {
+          originalCallback(err, ...results);
+        }
+      };
+    }
+
+    // noinspection JSVoidFunctionReturnValueUsed
+    let promiseResult = this.acquire(key, executor, callback, jobOptions) as any;
+
+    if (typeof promiseResult !== 'undefined') {
+      promiseResult = promiseResult.catch(err => {
+        if (isAcquisitionFailureError(err)) {
+          return failureResult;
+        }
+        throw err;
+      });
+    }
+
+    return promiseResult;
+  }
+
   /**
    * Update state of given list of queues.
    */

package/src/errors.ts

@@ -51,7 +51,12 @@ export class BetterLockInternalError extends BetterLockError {
 }
 
 export class BetterLockInvalidArgumentError extends BetterLockError {
-  constructor(lockName, public argument, expected, actual) {
+  constructor(
+    lockName,
+    public argument,
+    expected,
+    actual
+  ) {
     super(lockName, `Argument "${argument}" must be ${expected} (got: "${actual}")`);
     this.argument = argument;
   }
@@ -125,3 +130,11 @@ export class BetterLockJobAbortedError extends BetterLockError {
     this.keys = job.keys;
   }
 }
+
+export function isAcquisitionFailureError(err) {
+  return (
+    (err && err instanceof BetterLockQueueOverflowError) ||
+    err instanceof BetterLockWaitTimeoutError ||
+    err instanceof BetterLockJobAbortedError
+  );
+}

package/src/types.ts

@@ -27,3 +27,8 @@ export type IExecutor<TResult> = ICallbackExecutor<TResult> | IPromiseExecutor<T
  * Key types that can be used for a lock.
  */
 export type ILockKey = string | number | null | undefined;
+
+/**
+ * Valid results are anything except functions
+ */
+export type IValidResult = Exclude<any, (...args: any[]) => any>;