TaskRunner, Task class and index

Author: dasiux

index.js

@@ -0,0 +1,8 @@
+/**
+ * Task runner and task constructors
+ * @type {{Task: Task, TaskRunner: TaskRunner}}
+ */
+module.exports = {
+    Task : require( './src/classes/Task' ),
+    TaskRunner : require( './src/classes/TaskRunner' ),
+};

src/classes/Task.js

@@ -0,0 +1,97 @@
+/**
+ * Requires
+ */
+const { Exception, Timer, strand } = require( '@squirrel-forge/node-util' );
+const { isPojo, cloneObject, mergeObject } = require( '@squirrel-forge/node-objection' );
+
+/**
+ * Task exception
+ * @class
+ */
+class TaskException extends Exception {}
+
+/**
+ * Task class
+ * @abstract
+ * @class
+ */
+class Task {
+
+    /**
+     * Constructor
+     * @constructor
+     * @param {TaskRunner} runner - Runner instance
+     * @param {null|Object} options - Task options object
+     * @param {Object} defaults - Task default options
+     */
+    constructor( runner, options = null, defaults = {} ) {
+
+        // Require task id
+        if ( !defaults.id ) {
+            defaults.id = strand();
+        }
+
+        /**
+         * Timer
+         * @public
+         * @type {Timer}
+         */
+        this.timer = new Timer();
+
+        /**
+         * Runner instance
+         * @public
+         * @property
+         * @type {TaskRunner}
+         */
+        this.runner = runner;
+
+        /**
+         * Options defults
+         * @protected
+         * @property
+         * @type {Object}
+         */
+        this._defaults = defaults;
+
+        /**
+         * Options
+         * @protected
+         * @property
+         * @type {Object}
+         */
+        this._ = cloneObject( this._defaults, true );
+
+        // Apply custom options
+        if ( options && isPojo( options ) ) {
+            mergeObject( this._, options, true, true, true, true );
+        }
+    }
+
+    /**
+     * Generate stats object
+     * @param {Object} data - Stats data
+     * @return {Object} - Stats data
+     */
+    stats( data = {} ) {
+
+        // Force id and set processing time
+        data.id = this._.id;
+        data.time = this.timer.end( 'construct' );
+        return data;
+    }
+
+    /**
+     * Run task
+     * @public
+     * @abstract
+     * @return {Promise<null|Object>} - Null on fail, stats object on success
+     */
+    async run() {
+        throw new TaskException( 'Task must implement a run method' );
+    }
+}
+
+// Export Exception as static property constructor
+Task.TaskException = TaskException;
+module.exports = Task;

src/classes/TaskRunner.js

@@ -0,0 +1,224 @@
+/**
+ * Requires
+ */
+const { Exception } = require( '@squirrel-forge/node-util' );
+const { isPojo } = require( '@squirrel-forge/node-objection' );
+
+/**
+ * TaskRunner exception
+ * @class
+ */
+class TaskRunnerException extends Exception {}
+
+/**
+ * @typedef {Object|Array} TaskMap
+ */
+
+/**
+ * TaskRunner class
+ * @class
+ */
+class TaskRunner {
+
+    /**
+     * Constructor
+     * @constructor
+     * @param {boolean} strict - Strict mode, default: true
+     * @param {Function} notify - Notification callback for non strict mode
+     * @param {Function} taskParser - Parses task data before processing
+     */
+    constructor( strict = true, notify = null, taskParser = null ) {
+
+        /**
+         * Strict mode
+         * @protected
+         * @property
+         * @type {boolean}
+         */
+        this._strict = strict;
+
+        /**
+         * Notify in non strict callback
+         * @protected
+         * @property
+         * @type {Function}
+         */
+        this._notify = notify;
+
+        /**
+         * Parse/modify task data before construction
+         * @protected
+         * @property
+         * @type {Function}
+         */
+        this._parser = taskParser;
+
+        /**
+         * Available task types
+         * @protected
+         * @property
+         * @type {Object}
+         */
+        this._types = {};
+    }
+
+    /**
+     * Throw or notify on error
+     * @public
+     * @param {TaskRunnerException} err - Exception instance
+     * @throws {TaskRunnerException|TaskException}
+     * @return {void}
+     */
+    error( err ) {
+        if ( this._strict ) throw err;
+        if ( this._notify ) this._notify( err );
+    }
+
+    /**
+     * Register task constructor
+     * @public
+     * @param {string} name Task type
+     * @param {Function} TaskConstructor - Task constructor
+     * @param {boolean} replace - Replace existing task constructor
+     * @return {void}
+     */
+    register( name, TaskConstructor, replace = false ) {
+        if ( typeof TaskConstructor !== 'function' ) {
+            this.error( new TaskRunnerException( 'Task constructor must be a constructor: ' + name ) );
+            return;
+        }
+        if ( !replace && this._types[ name ] ) {
+            this.error( new TaskRunnerException( 'Task constructor already defined: ' + name ) );
+        } else {
+            this._types[ name ] = TaskConstructor;
+        }
+    }
+
+    /**
+     * Get constructor
+     * @public
+     * @param {string} name - Task type
+     * @return {null|Function} - Task constructor if available
+     */
+    getTaskConstructor( name ) {
+        if ( this._types[ name ] ) {
+            return this._types[ name ];
+        }
+        return null;
+    }
+
+    /**
+     * Run tasks in parallel
+     * @public
+     * @param {Array<Task|TaskMap>} taskMap - Task map
+     * @return {Promise<Object[]>} - Array of nulls and stats objects
+     */
+    parallel( taskMap ) {
+        const tasks = [];
+
+        // Run in parallel and collect promises
+        for ( let i = 0; i < taskMap.length; i++ ) {
+            tasks.push( this.run( taskMap[ i ] ) );
+        }
+        return Promise.all( tasks );
+    }
+
+    /**
+     * Run tasks in sequence
+     * @public
+     * @param {Object} taskMap - Task map
+     * @return {Promise<Object>} - Object of nulls and stats objects
+     */
+    async sequence( taskMap ) {
+        const stats = {};
+        const entries = Object.entries( taskMap );
+
+        // Process each map/task in order
+        for ( let i = 0; i < entries.length; i++ ) {
+            const [ name, value ] = entries[ i ];
+            stats[ name ] = await this.run( value );
+        }
+        return stats;
+    }
+
+    /**
+     * Construct and run task
+     * @public
+     * @param {Object} taskData - Task data object
+     * @return {Promise<null|Object>} - Null or stats object
+     */
+    async task( taskData ) {
+
+        // Allow external parser to modify the taskData object
+        if ( this._parser ) {
+            this._parser( taskData );
+        }
+
+        // Use custom id if set, useful when when running the same task type multiple times
+        if ( taskData.id ) {
+            taskData.options.id = taskData.id;
+        }
+
+        // Get the task constructor
+        const TaskConstructor = this.getTaskConstructor( taskData.type );
+        if ( !TaskConstructor ) {
+            this.error( new TaskRunnerException( 'Invalid or unknown task type: ' + taskData.type ) );
+            return null;
+        }
+
+        // Attempt to create task
+        let stats = null, task;
+        try {
+            task = new TaskConstructor( this, taskData.options );
+        } catch ( e ) {
+            this.error( new TaskRunnerException( 'Failed to construct task: ' + taskData.type, e ) );
+            return null;
+        }
+
+        // Attempt to run task
+        try {
+            stats = await task.run( ...taskData.args );
+        } catch ( e ) {
+            this.error( new TaskRunnerException( 'Failed to run task: ' + taskData.type, e ) );
+            return null;
+        }
+        return stats;
+    }
+
+    /**
+     * Run task map
+     * @public
+     * @param {TaskMap} taskMap - Task map
+     * @return {Promise<any[]|null|Object>} - Null, stats object or Array/Object map of nulls and stats objects
+     */
+    async run( taskMap ) {
+        let stats;
+
+        // Arrays are run in parallel, order does not matter
+        if ( taskMap instanceof Array ) {
+            stats = await this.parallel( taskMap );
+        } else if ( isPojo( taskMap ) ) {
+
+            // Assume it's a task if it has a type property
+            if ( taskMap.type ) {
+                stats = await this.task( taskMap );
+            } else {
+
+                // All other objects are assumed sequence maps and are processed in order
+                stats = await this.sequence( taskMap );
+            }
+        } else {
+
+            // If we have invalid data we might break
+            this.error( new TaskRunnerException( 'Invalid taskMap type: ' + typeof taskMap ) );
+            return null;
+        }
+
+        // Return stats object
+        return stats;
+    }
+}
+
+// Export Exception as static property constructor
+TaskRunner.TaskRunnerException = TaskRunnerException;
+module.exports = TaskRunner;