better-lock 3.0.0 → 3.2.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;
@@ -133,23 +134,6 @@ export class BetterLock {
       key = null;
     }
 
-    // Repackage "key" into an array of keys
-    const keys = [];
-    if (Array.isArray(key)) {
-      const arrayOfKeys = key;
-      // Make sure we don't add duplicates
-      const seenKeys = new Set();
-      for (let i = 0; i < arrayOfKeys.length; i++) {
-        const normalizedKey = this.normalizeAndValidateKey(arrayOfKeys[i]);
-        if (!seenKeys.has(normalizedKey)) {
-          keys.push(normalizedKey);
-          seenKeys.add(normalizedKey);
-        }
-      }
-    } else {
-      keys.push(this.normalizeAndValidateKey(key));
-    }
-
     // Create callback wrapper for promise interface
     if (!tools.isFunction(callback)) {
       if (jobOptions === undefined) {
@@ -159,6 +143,32 @@ export class BetterLock {
       callback = tools.callbackWithPromise();
     }
 
+    // Prepare job options
+    const effectiveJobOptions = jobOptions
+      ? tools.assign({} as IOptions, [this.options, jobOptions])
+      : // No need to create new object since these will be read-only and are subset of global options
+        this.options;
+
+    // Repackage "key" into an array of keys, but only if lock_condition allows it.
+    // Otherwise, it stays an array and gets executed immediately.
+    const keys = [];
+    if (!effectiveJobOptions.lock_condition || effectiveJobOptions.lock_condition(key)) {
+      if (Array.isArray(key)) {
+        const arrayOfKeys = key;
+        // Make sure we don't add duplicates
+        const seenKeys = new Set();
+        for (let i = 0; i < arrayOfKeys.length; i++) {
+          const normalizedKey = this.normalizeAndValidateKey(arrayOfKeys[i]);
+          if (!seenKeys.has(normalizedKey)) {
+            keys.push(normalizedKey);
+            seenKeys.add(normalizedKey);
+          }
+        }
+      } else {
+        keys.push(this.normalizeAndValidateKey(key));
+      }
+    }
+
     // Validate other options
     if (!tools.isFunction(executor)) {
       throw new BetterLockInvalidArgumentError(
@@ -177,12 +187,6 @@ export class BetterLock {
       );
     }
 
-    // Prepare job options
-    const effectiveJobOptions = jobOptions
-      ? tools.assign({}, [this.options, jobOptions])
-      : // No need to create new object since these will be read-only and are subset of global options
-        this.options;
-
     const job = new LockJob(keys, executor, callback, effectiveJobOptions);
 
     // Set incoming stack
@@ -221,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/options.ts

@@ -1,3 +1,5 @@
+import { ILockKey } from './types';
+
 /**
  * Options that apply on LockJob
  */
@@ -16,6 +18,13 @@ export interface ILockJobOptions {
    * In any error produced by BetterLock, extend the stack trace to include incoming trace. Overrides BetterLockOptions value.
    */
   extend_stack_traces?: boolean;
+
+  /**
+   * Before acquiring lock, call this function with the given key. If condition is rejected, the executor is immediately called, without locking.
+   * This can be used to more conveniently opt out of locking, without duplicating or extracting the executor.
+   * Overrides BetterLockOptions value.
+   */
+  lock_condition?: (key: ILockKey | Array<ILockKey>) => boolean;
 }
 
 export type IQueueEjectionStrategy = 'oldest' | 'newest';
@@ -45,6 +54,12 @@ export interface IOptions extends ILockJobOptions {
    */
   queue_ejection_strategy?: IQueueEjectionStrategy;
 
+  /**
+   * Before acquiring lock, call this function with the given key. If condition is rejected, the executor is immediately called, without locking.
+   * This can be used to more conveniently opt out of locking, without duplicating or extracting the executor.
+   */
+  lock_condition?: (key: ILockKey | Array<ILockKey>) => boolean;
+
   /**
    * Lock name. This will be written in all logs and error messages, to help you distinguish between different locks
    */

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