better-lock 1.0.0 → 2.0.1-beta

package/src/internals.ts

@@ -0,0 +1,118 @@
+import { ILockJobOptions } from './options';
+import { ICallback, IExecutor } from './types';
+
+/**
+ * Class that represents one scheduled job and its state. This is created every time user calls "acquire"
+ */
+export class LockJob<TResult> {
+  static _lastId = 0;
+
+  /** ID to uniquely identify this particular job */
+  public id = undefined;
+
+  /**
+   * List of keys that will be locked. Always an array
+   */
+  public keys: Array<string | null>;
+
+  /**
+   * Number of keys which this job is waiting on. Once this reaches 0, job will be executed
+   */
+  public waiting_count: number;
+
+  /**
+   * Function that will be called inside the lock
+   */
+  public executor: IExecutor<TResult>;
+
+  /**
+   * Function that will be called once job is done, whether it succeeds or times out.
+   * This is supplied by user in callback API, and generated internally otherwise.
+   */
+  public callback: ICallback<TResult>;
+
+  /**
+   * Timestamp when job was created
+   */
+  public enqueued_at: Date = new Date();
+
+  /**
+   * Timestamp when job was executed
+   */
+  public executed_at: Date = null;
+
+  /**
+   * This is set when job ends, in case something holds a reference to it
+   */
+  public ended_at: Date = null;
+
+  /**
+   * Options that apply to this particular job
+   */
+  public options: ILockJobOptions;
+
+  /**
+   * Id of the wait timer
+   */
+  public wait_timeout_id = null;
+
+  /**
+   * Id of the execution timer
+   */
+  public execution_timeout_id = null;
+
+  /**
+   * Saved incoming stack, for the purpose of extending stack traces
+   */
+  public incoming_stack: string = null;
+
+  constructor(
+    keys: Array<string | null>,
+    executor: IExecutor<TResult>,
+    callback: ICallback<TResult>,
+    options: ILockJobOptions
+  ) {
+    LockJob._lastId++;
+    this.id = LockJob._lastId;
+    this.keys = keys;
+    this.waiting_count = keys.length;
+    this.executor = executor;
+    this.callback = callback;
+    this.options = options;
+  }
+
+  toString() {
+    return `Job #${this.id} [${this.keys.join(', ')}]`;
+  }
+}
+
+// *********************************************************************************************************************
+
+/**
+ * Class to hold pending, holding and executing jobs for one key
+ */
+export class KeyQueue {
+  // We will use this key when user doesn't supply anything
+  static readonly DEFAULT_QUEUE_KEY = '___DEFAULT_QUEUE_KEY___';
+
+  public key: string;
+
+  /**
+   * Queue of jobs waiting to be executed.
+   * Jobs in this state are governed by the wait_timeout.
+   */
+  public jobs: LockJob<any>[] = [];
+
+  /**
+   * Active job that is holding this key. This job could be waiting on other keys or executing.
+   */
+  public active: LockJob<any> = null;
+
+  constructor(key?: string) {
+    this.key = key;
+  }
+
+  toString() {
+    return this.key === KeyQueue.DEFAULT_QUEUE_KEY ? 'JobQueue' : `JobQueue<${this.key}>`;
+  }
+}

package/src/options.ts

@@ -0,0 +1,63 @@
+/**
+ * Options that apply on LockJob
+ */
+export interface ILockJobOptions {
+  /**
+   * How long can jobs wait in queue before timing out. Overrides BetterLockOptions value.
+   */
+  wait_timeout?: number | null;
+
+  /**
+   * How long can a job be executing before timing out. Null to disable timeout. Overrides BetterLockOptions value.
+   */
+  execution_timeout?: number | null;
+
+  /**
+   * In any error produced by BetterLock, extend the stack trace to include incoming trace. Overrides BetterLockOptions value.
+   */
+  extend_stack_traces?: boolean;
+}
+
+/**
+ * Options that apply on BetterLock instance
+ */
+export interface IOptions extends ILockJobOptions {
+  /**
+   * How long can jobs wait in queue before timing out. Null to disable timeout.
+   */
+  wait_timeout?: number | null;
+
+  /**
+   * How long can a job be executing before timing out. Null to disable timeout.
+   * If you do that, though, and you have a swallowed callback, the lock can remain locked permanently.
+   */
+  execution_timeout?: number | null;
+
+  /**
+   * Max queue size for waiting jobs.
+   */
+  queue_size?: number | null;
+
+  /**
+   * Lock name. This will be written in all logs and error messages, to help you distinguish between different locks
+   */
+  name?: string;
+
+  /**
+   * Whether to log the internal actions. Set to true to use console.log. Alternatively, provide your own function
+   */
+  log?: boolean | ((msg: string) => void);
+
+  /**
+   * In any error produced by BetterLock, extend the stack trace to include incoming trace.
+   * Defaults to true.
+   */
+  extend_stack_traces?: boolean;
+
+  /**
+   * Function that detects whether value returned by executor is a promise.
+   * This will ducktype-sniff the returned value. Depending on your Promise library of choice,
+   * you might want to tighten or loosen this bit.
+   */
+  promise_tester?: (maybePromise: any) => boolean;
+}

package/src/tools.ts

@@ -0,0 +1,111 @@
+import { ICallback } from './types';
+
+export function isString(val) {
+  return typeof val === 'string';
+}
+
+export function isFunction(val) {
+  return typeof val === 'function';
+}
+
+export function isObject(val) {
+  return typeof val === 'object' && val !== null && !Array.isArray(val);
+}
+
+export function isNumber(val, includeInfinity = false, includeNaN = false) {
+  if (typeof val !== 'number') {
+    return false;
+  }
+  if (!includeInfinity && (val === Number.POSITIVE_INFINITY || val === Number.NEGATIVE_INFINITY)) {
+    return false;
+  }
+  if (!includeNaN && isNaN(val)) {
+    return false;
+  }
+  return true;
+}
+
+export function noop() {
+  // Nothing
+}
+
+export function makeLog(name, doLog): (msg: string) => void {
+  if (!doLog) {
+    return noop;
+  }
+
+  if (doLog === true) {
+    doLog = console.log.bind(console);
+  }
+
+  if (name) {
+    name = '[' + name + '] ';
+  }
+
+  return function log(msg) {
+    if (name) {
+      doLog(name + msg);
+    } else {
+      doLog(msg);
+    }
+  };
+}
+
+/**
+ * Create a wrapped promise + callback construct
+ */
+export function callbackWithPromise<TResult = any>(): Promise<TResult> & {
+  callback: ICallback<TResult>;
+} {
+  let callback;
+  const promise = new Promise((resolve, reject) => {
+    callback = (err, result) => {
+      if (err) {
+        reject(err);
+      } else {
+        resolve(result);
+      }
+    };
+  });
+  callback.promise = promise;
+  return callback;
+}
+
+/**
+ * Assign properties from sources to target, skipping over undefined-s
+ * @param target Target object which will be mutated
+ * @param sources One or more source objects which will provide properties
+ */
+export function assign<T>(target: T, sources: T[]): T {
+  for (const source of sources) {
+    if (!isObject(source)) {
+      // We must have an object to assign
+      continue;
+    }
+
+    for (const key in source) {
+      if (!source.hasOwnProperty(key)) {
+        continue;
+      }
+
+      const sourceValue = source[key];
+      if (sourceValue === undefined) {
+        // Do not overwrite undefineds
+        continue;
+      }
+
+      const targetValue = target[key];
+      if (isObject(sourceValue) && isObject(targetValue)) {
+        // Merge deep.
+        const cloneRoot = targetValue.constructor ? new (targetValue.constructor as any)() : {};
+        target[key] = assign(cloneRoot, [targetValue, sourceValue]);
+        continue;
+      }
+
+      // In all other cases, copy by reference
+      target[key] = sourceValue;
+    }
+  }
+
+  return target;
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+import * as errors from './errors';
+
+type IErrorExports = typeof errors;
+
+/**
+ * All error names that we can emit
+ */
+export type IErrorName = keyof IErrorExports;
+
+/**
+ * User-supplied callback. We support a "canonical" callback, with just error and result,
+ * but also old-school callbacks, with varargs return values.
+ */
+export type ICallback<TResult> = TResult extends any[]
+  ? (err?: Error, ...result: TResult) => void
+  : (err?: Error, result?: TResult) => void;
+
+/**
+ * Function that user will supply as the thing that will be running inside lock.
+ * It can either accept a done() function, or return a promise.
+ */
+export type ICallbackExecutor<TResult> = (lockDone: ICallback<TResult>) => void;
+export type IPromiseExecutor<TResult> = () => Promise<TResult>;
+export type IExecutor<TResult> = ICallbackExecutor<TResult> | IPromiseExecutor<TResult>;
+
+/**
+ * Key types that can be used for a lock.
+ */
+export type ILockKey = string | number | null | undefined;

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": false,
+    "noImplicitAny": false,
+		"sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "**/__tests__/*"]
+}

package/.idea/markdown-navigator/profiles_settings.xml

@@ -1,3 +0,0 @@
-<component name="MarkdownNavigator.ProfileManager">
-  <settings default="" pdf-export="" />
-</component>

package/.idea/markdown-navigator.xml

@@ -1,78 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="MarkdownProjectSettings" wasCopied="false">
-    <PreviewSettings splitEditorLayout="SPLIT" splitEditorPreview="PREVIEW" useGrayscaleRendering="false" zoomFactor="1.25" maxImageWidth="0" showGitHubPageIfSynced="false" allowBrowsingInPreview="false" synchronizePreviewPosition="true" highlightPreviewType="NONE" highlightFadeOut="5" highlightOnTyping="true" synchronizeSourcePosition="true" verticallyAlignSourceAndPreviewSyncPosition="true" showSearchHighlightsInPreview="false" showSelectionInPreview="true" openRemoteLinks="true" replaceUnicodeEmoji="false" lastLayoutSetsDefault="false">
-      <PanelProvider>
-        <provider providerId="com.vladsch.idea.multimarkdown.editor.swing.html.panel" providerName="Default - Swing" />
-      </PanelProvider>
-    </PreviewSettings>
-    <ParserSettings gitHubSyntaxChange="false" emojiShortcuts="1" emojiImages="0">
-      <PegdownExtensions>
-        <option name="ABBREVIATIONS" value="false" />
-        <option name="ANCHORLINKS" value="true" />
-        <option name="ASIDE" value="false" />
-        <option name="ATXHEADERSPACE" value="true" />
-        <option name="AUTOLINKS" value="true" />
-        <option name="DEFINITIONS" value="false" />
-        <option name="DEFINITION_BREAK_DOUBLE_BLANK_LINE" value="false" />
-        <option name="FENCED_CODE_BLOCKS" value="true" />
-        <option name="FOOTNOTES" value="false" />
-        <option name="HARDWRAPS" value="false" />
-        <option name="HTML_DEEP_PARSER" value="false" />
-        <option name="INSERTED" value="false" />
-        <option name="QUOTES" value="false" />
-        <option name="RELAXEDHRULES" value="true" />
-        <option name="SMARTS" value="false" />
-        <option name="STRIKETHROUGH" value="true" />
-        <option name="SUBSCRIPT" value="false" />
-        <option name="SUPERSCRIPT" value="false" />
-        <option name="SUPPRESS_HTML_BLOCKS" value="false" />
-        <option name="SUPPRESS_INLINE_HTML" value="false" />
-        <option name="TABLES" value="true" />
-        <option name="TASKLISTITEMS" value="true" />
-        <option name="TOC" value="false" />
-        <option name="WIKILINKS" value="true" />
-      </PegdownExtensions>
-      <ParserOptions>
-        <option name="ADMONITION_EXT" value="false" />
-        <option name="ATTRIBUTES_EXT" value="false" />
-        <option name="COMMONMARK_LISTS" value="true" />
-        <option name="DUMMY" value="false" />
-        <option name="EMOJI_SHORTCUTS" value="true" />
-        <option name="ENUMERATED_REFERENCES_EXT" value="false" />
-        <option name="FLEXMARK_FRONT_MATTER" value="false" />
-        <option name="GFM_LOOSE_BLANK_LINE_AFTER_ITEM_PARA" value="false" />
-        <option name="GFM_TABLE_RENDERING" value="true" />
-        <option name="GITBOOK_URL_ENCODING" value="false" />
-        <option name="GITHUB_LISTS" value="false" />
-        <option name="GITHUB_WIKI_LINKS" value="true" />
-        <option name="HEADER_ID_NO_DUPED_DASHES" value="false" />
-        <option name="JEKYLL_FRONT_MATTER" value="false" />
-        <option name="NO_TEXT_ATTRIBUTES" value="false" />
-        <option name="PARSE_HTML_ANCHOR_ID" value="false" />
-        <option name="SIM_TOC_BLANK_LINE_SPACER" value="true" />
-      </ParserOptions>
-    </ParserSettings>
-    <HtmlSettings headerTopEnabled="false" headerBottomEnabled="false" bodyTopEnabled="false" bodyBottomEnabled="false" embedUrlContent="false" addPageHeader="true" embedImages="false" embedHttpImages="false" imageUriSerials="false">
-      <GeneratorProvider>
-        <provider providerId="com.vladsch.idea.multimarkdown.editor.swing.html.generator" providerName="Default Swing HTML Generator" />
-      </GeneratorProvider>
-      <headerTop />
-      <headerBottom />
-      <bodyTop />
-      <bodyBottom />
-    </HtmlSettings>
-    <CssSettings previewScheme="UI_SCHEME" cssUri="" isCssUriEnabled="false" isCssUriSerial="true" isCssTextEnabled="false" isDynamicPageWidth="true">
-      <StylesheetProvider>
-        <provider providerId="com.vladsch.idea.multimarkdown.editor.swing.html.css" providerName="Default Swing Stylesheet" />
-      </StylesheetProvider>
-      <ScriptProviders />
-      <cssText />
-      <cssUriHistory />
-    </CssSettings>
-    <HtmlExportSettings updateOnSave="false" parentDir="" targetDir="" cssDir="" scriptDir="" plainHtml="false" imageDir="" copyLinkedImages="false" imageUniquifyType="0" targetExt="" useTargetExt="false" noCssNoScripts="false" linkToExportedHtml="true" exportOnSettingsChange="true" regenerateOnProjectOpen="false" linkFormatType="HTTP_ABSOLUTE" />
-    <LinkMapSettings>
-      <textMaps />
-    </LinkMapSettings>
-  </component>
-</project>

package/.idea/misc.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="JavaScriptSettings">
-    <option name="languageLevel" value="ES6" />
-  </component>
-</project>

package/.idea/watcherTasks.xml

@@ -1,8 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="ProjectTasksOptions" suppressed-tasks="Babel">
-    <enabled-global>
-      <option value="Prettier on save (js)" />
-    </enabled-global>
-  </component>
-</project>

package/index.js

@@ -1,19 +0,0 @@
-const { BetterLock } = require('./src/better_lock');
-const errors = require('./src/errors');
-const { LockJob } = require('./src/types');
-const { BetterLockOptions } = require('./src/options');
-
-BetterLock.BetterLock = BetterLock;
-
-BetterLock.BetterLockError = errors.BetterLockError;
-BetterLock.BetterLockInternalError = errors.BetterLockInternalError;
-BetterLock.InvalidArgumentError = errors.InvalidArgumentError;
-BetterLock.WaitTimeoutError = errors.WaitTimeoutError;
-BetterLock.ExecutionTimeoutError = errors.ExecutionTimeoutError;
-BetterLock.QueueOverflowError = errors.QueueOverflowError;
-BetterLock.JobAbortedError = errors.JobAbortedError;
-
-BetterLock.LockJob = LockJob;
-BetterLock.Options = BetterLockOptions;
-
-module.exports = BetterLock;