better-lock 3.1.0 → 3.3.0

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;
@@ -189,9 +190,12 @@ export class BetterLock {
     const job = new LockJob(keys, executor, callback, effectiveJobOptions);
 
     // Set incoming stack
-    if (effectiveJobOptions.extend_stack_traces) {
+    if (
+      effectiveJobOptions.extend_stack_traces &&
+      typeof (Error as any).captureStackTrace === 'function'
+    ) {
       const tempErr = new Error();
-      Error.captureStackTrace(tempErr, this.acquire);
+      (Error as any).captureStackTrace(tempErr, this.acquire);
       job.incoming_stack = tempErr.stack;
     }
 
@@ -224,6 +228,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.
    */
@@ -275,7 +359,7 @@ export class BetterLock {
     // 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(() => {
+    setTimeout(() => {
       // Make sure job hasn't been ended in the meantime
       if (job.executed_at || job.ended_at) {
         return;
@@ -336,7 +420,7 @@ export class BetterLock {
         // "promise" is just some random value. We don't have to wait
         lockDone(null, executorResult);
       }
-    });
+    }, 0);
   }
 
   private onWaitTimeout(job: LockJob<any>) {
@@ -403,7 +487,7 @@ export class BetterLock {
       job.callback.apply(null, callbackArgs);
     } finally {
       // Whatever happens, schedule a queue update
-      setImmediate(() => this.update(queuesToUpdate));
+      setTimeout(() => this.update(queuesToUpdate), 0);
     }
   }
 

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>;

package/tsconfig.build.json

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": []
+  }
+}

package/tsconfig.json

@@ -2,6 +2,7 @@
   "compilerOptions": {
     "target": "es5",
     "module": "commonjs",
+    "lib": ["es2018", "dom"],
     "declaration": true,
     "outDir": "./dist",
     "strict": false,