@schukai/monster/source/util/processing.mjs

Monster is a simple library for creating fast, robust and lightweight websites.

/**
 * Copyright © Volker Schukai and all contributing authors, {{copyRightYear}}. All rights reserved.
 * Node module: @schukai/monster
 *
 * This source code is licensed under the GNU Affero General Public License version 3 (AGPLv3).
 * The full text of the license can be found at: https://www.gnu.org/licenses/agpl-3.0.en.html
 *
 * For those who do not wish to adhere to the AGPLv3, a commercial license is available.
 * Acquiring a commercial license allows you to use this software without complying with the AGPLv3 terms.
 * For more information about purchasing a commercial license, please contact Volker Schukai.
 *
 * SPDX-License-Identifier: AGPL-3.0
 */

import { internalSymbol } from "../constants.mjs";
import { Base } from "../types/base.mjs";
import { isFunction, isInteger } from "../types/is.mjs";
import { Queue } from "../types/queue.mjs";
import { Callback } from "./processing/callback.mjs";

export { Processing };

/**
 * This class allows executing several functions in order.
 *
 * Functions and timeouts can be passed. If a timeout is passed, it applies to all further functions.
 * In the example
 *
 * `timeout1, function1, function2, function3, timeout2, function4`
 *
 * the timeout1 is valid for the functions 1, 2 and 3 and the timeout2 for the function4.
 *
 * So the execution time is timeout1+timeout1+timeout1+timeout2
 *
 * The result of `run()` is a promise.
 *
 * @example /examples/libraries/util/processing/simple/ A simple example
 *
 * @copyright Volker Schukai
 * @license AGPLv3
 * @since 1.21.0
 * @summary Class to be able to execute function chains
 */
class Processing extends Base {
	/**
	 * Create new Processing
	 *
	 * Functions and timeouts can be passed. If a timeout is passed, it applies to all further functions.
	 * In the example
	 *
	 * `timeout1, function1, function2, function3, timeout2, function4`
	 *
	 * the timeout1 is valid for the functions 1, 2 and 3 and the timeout2 for the function4.
	 *
	 * So the execution time is timeout1+timeout1+timeout1+timeout2
	 *
	 * @throw {TypeError} the arguments must be either integer or functions
	 * @param {...(int|function)} args
	 */
	constructor(...args) {
		super();

		this[internalSymbol] = {
			queue: new Queue(),
		};

		let time = 0;

		if (typeof args !== "object" || args[0] === null) {
			throw new TypeError("the arguments must be either integer or functions");
		}

		for (const [, arg] of Object.entries(args)) {
			if (isInteger(arg) && arg >= 0) {
				time = arg;
			} else if (isFunction(arg)) {
				this[internalSymbol].queue.add(new Callback(arg, time));
			} else {
				throw new TypeError(
					"the arguments must be either integer or functions",
				);
			}
		}
	}

	/**
	 * Adds a function with the desired timeout
	 * If no timeout is specified, the timeout of the previous function is used.
	 *
	 * @param {function} callback
	 * @param {int|undefined} time
	 * @throws {TypeError} value is not a function
	 * @throws {TypeError} value is not an integer
	 */
	add(callback, time) {
		this[internalSymbol].queue.add(new Callback(callback, time));
		return this;
	}

	/**
	 * Executes the defined functions in order.
	 *
	 * @param {*} data
	 * @return {Promise}
	 */
	run(data) {
		if (this[internalSymbol].queue.isEmpty()) {
			return Promise.resolve(data);
		}

		const callback = this[internalSymbol].queue.poll();

		if (callback === null || callback === undefined) {
			return Promise.resolve(data);
		}

		return callback.run(data).then((result) => {
			return this.run(result);
		});
	}
}