better-lock 1.0.0 → 2.0.1-beta

package/src/better_lock.js

@@ -1,400 +0,0 @@
-const tools = require('./tools');
-
-const { LockJob, KeyQueue } = require('./types');
-const {
-	BetterLockInternalError,
-	InvalidArgumentError,
-	WaitTimeoutError,
-	ExecutionTimeoutError,
-	QueueOverflowError,
-	JobAbortedError,
-} = require('./errors');
-const { BetterLockOptions, LockJobOptions, DEFAULT_OPTIONS } = require('./options');
-
-/**
- * Create a better lock object.
- * @constructor
- * @param {BetterLockOptions} options
- */
-function BetterLock(options) {
-	options = new BetterLockOptions([BetterLock.DEFAULT_OPTIONS, options]);
-
-	const log = tools.makeLog(options.name, options.log);
-
-	/** @type {Object.<string, KeyQueue>} */
-	const _queues = {};
-
-	Object.assign(
-		this,
-		/** @lends {BetterLock.prototype} */ {
-			canAcquire,
-			acquire,
-			abort,
-			abortAll,
-		}
-	);
-
-	// *******************************************************************************************************************
-
-	/**
-	 * Return or create a key queue for given key
-	 * @return {KeyQueue}
-	 */
-	function getQueue(key) {
-		if (key === undefined || key === null) {
-			key = KeyQueue.DEFAULT_QUEUE_KEY;
-		}
-		let queue = _queues[key];
-		if (!queue) {
-			queue = _queues[key] = new KeyQueue(key);
-		}
-		return queue;
-	}
-
-	/**
-	 * Returns true if the caller can *immediately* acquire the lock. There is nothing holding the key and nothing in the queue.
-	 * @param key
-	 */
-	function canAcquire(key) {
-		const queue = getQueue(key);
-		return !queue.active && !queue.jobs.length;
-	}
-
-	function normalizeAndValidateKey(key) {
-		if (key === undefined) {
-			return undefined;
-		}
-		if (key === null) {
-			return undefined;
-		}
-		if (tools.isString(key)) {
-			return key;
-		}
-		if (tools.isNumber(key)) {
-			return String(key);
-		}
-		// Invalid key value
-		throw new InvalidArgumentError(
-			options.name,
-			'key',
-			'a string, number, undefined, null, or an array of these types',
-			key
-		);
-	}
-
-	/**
-	 * 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.
-	 *
-	 * 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.
-	 *
-	 * Return values from your executor will be passed to callback (or the resulting promise).
-	 * @template T
-	 * @param {string|Number|Array|undefined} [key] Named key or array of keys for this particular call. Calls with different keys will be run in parallel. Not required.
-	 * @param {function(done):Promise<T>} executor Function that will run inside the lock. Required.
-	 * @param {function} [callback] Function to be called after the executor finishes or if we never enter the lock (timeout, queue depletion). Leave out to use promises.
-	 * @param {LockJobOptions} [jobOptions] Options to be applied on this job only
-	 * @return {Promise<T>}
-	 */
-	function acquire(key, executor, callback = undefined, jobOptions = undefined) {
-		if (tools.isFunction(key) || tools.isObject(key)) {
-			// Presume we weren't given a key
-			jobOptions = callback;
-			callback = executor;
-			executor = key;
-			key = undefined;
-		}
-
-		// Repackage "key" into an array of keys
-		const keys = [];
-		if (tools.isArray(key)) {
-			// Make sure we don't add duplicates
-			const seenKeys = {};
-			for (let i = 0; i < key.length; i++) {
-				const normalizedKey = normalizeAndValidateKey(key[i]);
-				if (!seenKeys[normalizedKey]) {
-					keys.push(normalizedKey);
-					seenKeys[normalizedKey] = true;
-				}
-			}
-		} else {
-			keys.push(normalizeAndValidateKey(key));
-		}
-
-		// Create callback wrapper for promise interface
-		if (!tools.isFunction(callback)) {
-			if (jobOptions === undefined) {
-				jobOptions = callback;
-			}
-
-			callback = tools.callbackWithPromise();
-		}
-
-		// Validate other options
-		if (!tools.isFunction(executor)) {
-			throw new InvalidArgumentError(options.name, 'executor', 'a function', executor);
-		}
-		if (!tools.isFunction(callback)) {
-			throw new InvalidArgumentError(options.name, 'callback', 'a function', callback);
-		}
-
-		// Prepare job options
-		const effectiveJobOptions = jobOptions
-			? new LockJobOptions([options, jobOptions])
-			: // No need to create new object since these will be read-only and are subset of global options
-			  options;
-
-		const job = new LockJob(keys, executor, callback, effectiveJobOptions);
-
-		// Set incoming stack
-		if (effectiveJobOptions.extend_stack_traces) {
-			const tempErr = new Error();
-			Error.captureStackTrace(tempErr, acquire);
-			job.incoming_stack = tempErr.stack;
-		}
-
-		// Add job to its key queues
-		const queuesToUpdate = [];
-		for (let i = 0; i < keys.length; i++) {
-			const queue = getQueue(keys[i]);
-			queue.jobs.push(job);
-			queuesToUpdate.push(queue);
-		}
-
-		// Start wait timer, if enabled
-		if (tools.isNumber(job.options.wait_timeout)) {
-			job.wait_timeout_id = setTimeout(onWaitTimeout.bind(null, job), job.options.wait_timeout);
-
-			// NOTE: timeout of 0 will NOT trigger error if lock can be acquired immediately.
-		}
-
-		log(`Enqueued ${job}`);
-
-		// Perform update of queues this job has modified. We don't do this in next tick or something,
-		// because we want canAcquire to immediately return false
-		update(queuesToUpdate);
-
-		return callback.promise;
-	}
-
-	/**
-	 * Update state of given list of queues.
-	 * @param {KeyQueue[]} queues
-	 */
-	function update(queues) {
-		for (let i = 0; i < queues.length; i++) {
-			const queue = queues[i];
-
-			// If key is available, have next job grab it
-			if (!queue.active && queue.jobs.length) {
-				/** @type {LockJob} */
-				const job = queue.jobs.splice(0, 1)[0];
-				queue.active = job;
-				job.waiting_count--;
-
-				if (job.waiting_count <= 0) {
-					// This job can be executed now.
-					executeJob(job);
-				}
-			}
-
-			// Handle wait queue overflow
-			if (tools.isNumber(options.queue_size) && options.queue_size < queue.jobs.length) {
-				// Overflow. Reject the most recent job
-				const mostRecentJob = queue.jobs[queue.jobs.length - 1];
-				log(
-					`${queue.toString()} has overflown, so most recent job (${mostRecentJob}) was kicked out`
-				);
-
-				endJob(mostRecentJob, [
-					new QueueOverflowError(options.name, queue.key, queue.jobs.length, mostRecentJob),
-				]);
-			}
-		}
-	}
-
-	/**
-	 * @param {LockJob} job
-	 */
-	function executeJob(job) {
-		log(`Executing ${job}`);
-
-		// Clear wait timeout
-		clearTimeout(job.wait_timeout_id);
-		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(() => {
-			// 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 (let i = 0; i < job.keys.length; i++) {
-				const queue = getQueue(job.keys[i]);
-				if (queue.active !== job) {
-					// This should never happen
-					return endJob(job, [
-						new BetterLockInternalError(
-							options.name,
-							`Corrupted wait queue state for ${queue.key}`
-						),
-					]);
-				}
-			}
-
-			// Mark job as having started executing
-			job.executed_at = new Date();
-
-			if (tools.isNumber(job.options.execution_timeout)) {
-				job.execution_timeout_id = setTimeout(
-					onExecutionTimeout.bind(null, job),
-					job.options.execution_timeout
-				);
-			}
-
-			if (job.executor.length > 0) {
-				// Callback interface
-				job.executor(lockDone);
-				return;
-			}
-
-			// Promise interface
-			let executorResult;
-			try {
-				executorResult = job.executor();
-			} catch (err) {
-				// Error thrown directly from executor
-				lockDone(err);
-			}
-
-			// Promise sniffing
-			// TODO if (options.promise_tester(promise)) {
-			if (executorResult && executorResult.then && executorResult.catch) {
-				executorResult.then(res => lockDone(null, res), err => lockDone(err));
-			} else {
-				// "promise" is just some random value. We don't have to wait
-				lockDone(null, executorResult);
-			}
-
-			function lockDone() {
-				log(`Done called for ${job}`);
-
-				endJob(job, arguments);
-			}
-		});
-	}
-
-	/**
-	 * @param {LockJob} job
-	 */
-	function onWaitTimeout(job) {
-		log(`${job} has timed out after waiting in queue for ${new Date() - job.enqueued_at}ms`);
-
-		endJob(job, [new WaitTimeoutError(options.name, job)]);
-	}
-
-	/**
-	 * @param {LockJob} job
-	 */
-	function onExecutionTimeout(job) {
-		log(`${job} has timed out after executing for ${new Date() - job.executed_at}ms`);
-
-		endJob(job, [new ExecutionTimeoutError(options.name, job)]);
-	}
-
-	/**
-	 * @param {LockJob} job
-	 * @param {*[]|Array|IArguments} callbackArgs
-	 */
-	function endJob(job, callbackArgs) {
-		if (job.ended_at) {
-			log(
-				`WARNING: ${job} is trying to end, but it has already ended at ${job.ended_at.toISOString()}. Called with arguments: ${callbackArgs}`
-			);
-			return;
-		}
-
-		clearTimeout(job.wait_timeout_id);
-		job.wait_timeout_id = null;
-
-		clearTimeout(job.execution_timeout_id);
-		job.execution_timeout_id = null;
-
-		job.ended_at = new Date();
-
-		const queuesToUpdate = [];
-		for (let i = 0; i < job.keys.length; i++) {
-			const queue = getQueue(job.keys[i]);
-			queuesToUpdate.push(queue);
-
-			if (queue.active === job) {
-				// This job was holding on the queue's key
-				queue.active = null;
-			} else {
-				// This job was still in wait list for this queue
-				const index = queue.jobs.indexOf(job);
-				if (index >= 0) {
-					// Remove from queue
-					queue.jobs.splice(index, 1);
-				} else {
-					// Something is wrong. Where did this job come from?
-					log(
-						`WARNING: ${job} is ending, but it is not found anywhere in the queue for ${queue.key}`
-					);
-				}
-			}
-		}
-
-		// Call the callback
-		try {
-			job.callback.apply(null, callbackArgs);
-		} finally {
-			// Whatever happens, schedule a queue update
-			setImmediate(update, queuesToUpdate);
-		}
-	}
-
-	/**
-	 * 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.
-	 * @param [key]
-	 */
-	function abort(key = undefined) {
-		const queue = getQueue(key);
-		queue.jobs.slice().forEach(job => {
-			endJob(job, [new JobAbortedError(options.name, job)]);
-		});
-		if (queue.active && !queue.active.executed_at) {
-			// If we have a job holding this queue that hasn't been executed yet, abort it as well
-			endJob(queue.active, [new JobAbortedError(options.name, queue.active)]);
-		}
-	}
-
-	/**
-	 * Abort all pending jobs from all queues.
-	 * Currently executing jobs will not be interrupted.
-	 */
-	function abortAll() {
-		abort(undefined);
-		for (const key in _queues) {
-			// noinspection JSUnfilteredForInLoop
-			abort(key);
-		}
-	}
-}
-
-/**
- * Default options to be used when creating BetterLock instances.
- */
-BetterLock.DEFAULT_OPTIONS = DEFAULT_OPTIONS;
-
-module.exports = {
-	BetterLock,
-};

package/src/errors.js

@@ -1,81 +0,0 @@
-class BetterLockError extends Error {
-	constructor(name, message, incomingStack = null) {
-		if (name) {
-			super(`[${name}] ${message}`);
-		} else {
-			super(message);
-		}
-		this.lock_name = name;
-
-		if (incomingStack) {
-			const withoutFirstLine = incomingStack
-				.split('\n')
-				.slice(1)
-				.join('\n');
-			this.stack =
-				this.stack +
-				'\n    --------------------------------------------------------------------------------\n' +
-				withoutFirstLine;
-		}
-	}
-}
-
-class BetterLockInternalError extends BetterLockError {
-	constructor(name, message) {
-		const lastChar = message[message.length - 1];
-		if (lastChar !== '.' && lastChar !== '!' && lastChar !== '?') {
-			message += '.';
-		}
-		super(name, message + ' This is probably a bug inside "better-lock" library');
-	}
-}
-
-class InvalidArgumentError extends BetterLockError {
-	constructor(name, argument, expected, actual) {
-		super(name, `Argument "${argument}" must be ${expected} (got: "${actual}")`);
-		this.argument = argument;
-	}
-}
-
-class WaitTimeoutError extends BetterLockError {
-	constructor(name, job) {
-		const message = `${job} has timed out after ${new Date() - job.enqueued_at}ms in wait queue`;
-		super(name, message, job.incoming_stack);
-		this.job = job;
-	}
-}
-
-class ExecutionTimeoutError extends BetterLockError {
-	constructor(name, job) {
-		const message = `${job} has timed out after ${new Date() - job.executed_at}ms of execution`;
-		super(name, message, job.incoming_stack);
-		this.job = job;
-	}
-}
-
-class QueueOverflowError extends BetterLockError {
-	constructor(name, key, count, job) {
-		const message = `Too many jobs (${count}) waiting for ${key}. The most recent job (${job}) was kicked out`;
-		super(name, message, job.incoming_stack);
-		this.key = key;
-		this.count = count;
-		this.job = job;
-	}
-}
-
-class JobAbortedError extends BetterLockError {
-	constructor(name, job) {
-		super(name, `${job} has been aborted by the user`, job.incoming_stack);
-		this.job = job;
-	}
-}
-
-module.exports = {
-	BetterLockError,
-	BetterLockInternalError,
-	InvalidArgumentError,
-	WaitTimeoutError,
-	ExecutionTimeoutError,
-	QueueOverflowError,
-	JobAbortedError,
-};

package/src/options.js

@@ -1,104 +0,0 @@
-const { assign } = require('./tools');
-
-const ALIASES = {
-	waitTimeout: 'wait_timeout',
-	executionTimeout: 'execution_timeout',
-	queueSize: 'queue_size',
-	overflowStrategy: 'overflow_strategy',
-	extendStackTraces: 'extend_stack_traces',
-};
-
-/**
- * Options that apply on BetterLock instance
- */
-class BetterLockOptions {
-	constructor(/** BetterLockOptions|BetterLockOptions[] */ sources) {
-		/**
-		 * How long can jobs wait in queue before timing out. Null to disable timeout.
-		 * @type {Number|null}
-		 */
-		this.wait_timeout = undefined;
-
-		/**
-		 * 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.
-		 * @type {Number|null}
-		 */
-		this.execution_timeout = undefined;
-
-		/**
-		 * Max queue size for waiting jobs.
-		 * @type {Number|null}
-		 */
-		this.queue_size = undefined;
-
-		/**
-		 * Lock name. This will be written in all logs and error messages, to help you distinguish between different locks
-		 * @type {string}
-		 */
-		this.name = undefined;
-
-		/**
-		 * Whether to log the internal actions. Set to true to use console.log. Alternatively, provide your own function
-		 * @type {boolean|function}
-		 */
-		this.log = undefined;
-
-		/**
-		 * In any error produced by BetterLock, extend the stack trace to include incoming trace
-		 * @type {boolean}
-		 */
-		this.extend_stack_traces = undefined;
-
-		/**
-		 * 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.
-		 * @type {function(p)}
-		 */
-		this.promise_tester = p => p && typeof p.then === 'function';
-
-		this.assign(sources);
-	}
-
-	assign(sources) {
-		assign(this, sources, ALIASES);
-	}
-}
-
-/**
- * Options that apply on LockJob
- */
-class LockJobOptions {
-	constructor(/** LockJobOptions|LockJobOptions[] */ sources) {
-		/**
-		 * How long can jobs wait in queue before timing out. Overrides BetterLockOptions value.
-		 * @type {Number|null}
-		 */
-		this.wait_timeout = undefined;
-
-		/**
-		 * How long can a job be executing before timing out. Null to disable timeout. Overrides BetterLockOptions value.
-		 * @type {Number|null}
-		 */
-		this.execution_timeout = undefined;
-
-		/**
-		 * In any error produced by BetterLock, extend the stack trace to include incoming trace. Overrides BetterLockOptions value.
-		 * @type {boolean}
-		 */
-		this.extend_stack_traces = undefined;
-
-		this.assign(sources);
-	}
-
-	assign(sources) {
-		assign(this, sources, ALIASES);
-	}
-}
-
-const DEFAULT_OPTIONS = new BetterLockOptions({
-	extend_stack_traces: true,
-});
-
-module.exports = { BetterLockOptions, LockJobOptions, DEFAULT_OPTIONS };

package/src/tools.js

@@ -1,125 +0,0 @@
-function isString(val) {
-	return typeof val === 'string';
-}
-
-function isFunction(val) {
-	return typeof val === 'function';
-}
-
-function isObject(val) {
-	return typeof val === 'object' && val !== null && !Array.isArray(val);
-}
-
-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;
-}
-
-function isArray(val) {
-	return Array.isArray(val);
-}
-
-function noop() {}
-
-function makeLog(name, doLog) {
-	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);
-		}
-	};
-}
-
-function callbackWithPromise() {
-	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 {object|Array} sources One or more source objects which will provide properties
- * @param {object} aliases Lookup mapping aliased properties from sources to properties on target
- */
-function assign(target, sources, aliases) {
-	if (!isArray(sources)) {
-		sources = [sources];
-	}
-
-	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 targetKey = (aliases && aliases[key]) || key;
-			const targetValue = target[targetKey];
-
-			if (isObject(sourceValue) && isObject(targetValue)) {
-				// Merge deep.
-				const cloneRoot = targetValue.constructor ? new targetValue.constructor() : {};
-				target[targetKey] = assign(cloneRoot, targetValue, sourceValue);
-				continue;
-			}
-
-			// In all other cases, copy by reference
-			target[targetKey] = sourceValue;
-		}
-	}
-
-	return target;
-}
-
-module.exports = {
-	isString,
-	isFunction,
-	isObject,
-	isNumber,
-	isArray,
-	noop,
-	makeLog,
-	callbackWithPromise,
-	assign,
-};