plugin-tasks

The tasks plugin is used to register functionality to be executed at specific points in time, recurring or not. This plugin is useful for a worker-like microservice that can process items in the background.

By default, the plugin will create the folder app/tasks where you should save all your task definitions. They will be automatically loaded and registered by the application.

Installation and usage
npm i --save thorin-plugin-tasks@1.x
'use strict';
// app.js entry file
const thorin = require('thorin');

thorin.addPlugin(require('thorin-plugin-tasks'));   // <- add this line
thorin.run((err) => {});

#update config/app.js with your configuration
# run to setup the plugin
node app.js --setup=plugin.tasks
Default configuration
  • enabledboolean, true setting this to false will disable any scheduled tasks to execute.
  • debugboolean, true enable task debugging and logging
  • persiststring, thorin.root + config/.task_dumpthe file used to persist task entry timers.
Plugin functionality
pluginObj.Task : TaskEntry
The task entry definition class, see below.
pluginObj.addTask(taskName, opt) : TaskEntry instance
Registers a new task entry to the system.
pluginObj.getTask(name) : TaskEntry instance
Returns the task entry instance by its name.
pluginObj.stopTasks(fn)
Stops all the registered task entries from execution.
pluginObj.stopTask(name, fn)
Stops a single task entry from execution.
The TaskEntry class

You use the task entry to define what and when gets executed.

entryObj.prepare(fn)
Registers a callback function that will be called right before the entry starts executing. Your callback will have access to the current context and should prepare all the required information.
entryObj.action(name, fn)
Registers a new action that can be later scheduled to run with the given context. A task action should encapsulate specific functionality that other actions might use.
entryObj.schedule(actions, opt)
Given an array of actions, it will schedule their execution in the specified order. This will defined what and when gets executed.
  • actionsarray(string) an array of action names that were previously registered, to be executed in the specific order
  • opt.delaystring the amount of time to delay the execution of the task since the application boot.
  • opt.timerstringthe amount of time between task re-execution. This essentially marks the task as recurring.
  • opt.atstringthe fixed point in time when the action should be executed. (hh:mm:ss)
  • opt.onstring, month-start, month-endthe date when the task should be executed. Currently only month-start and month-end.
  • opt.timeoutstringhow much time to pass before we consider the action timed out and failed
Time representation has the hh:mm:ss format or {days}d {hours}h {minutes}m {seconds}s and can be found below:
delay: '2m' delays next execution by 2 minutes
timer: '10s' executes the task every 10 seconds
at: '10:30' executes the task every day at 10:30
timer: '2h30m' executes the task every 2 hours and 10 minutes
entryObj.handle(event, fn)
Registers a callback handler for the given task event. Task events ara explained bellow
  • failed - triggered when the task has encountered an error.
  • completed - triggered when the task has completed all its scheduled actions.
  • timeout - triggered when the action failed to complete before the given timeout period
  • stop - triggered when the action was programatically stopped from the context.
entryObj.start(delay)
Manually start the task's scheduled actions.
entryObj.stop()
Stops the task from executing any further.
entryObj.runAction(name)
Manually runs the given action name with an empty context, internal function.
entryObj.createContext(names, opt)
Creates a new context and runs it through the specified actions, internal function.
The TaskContext class

You use the task context to attach context-specific information about your currently running task.

contextObj.took() : Number
Returns the number of milliseconds the context was active
contextObj.stop()
Stops the context from running further. Any action that was scheduled to run after this, will no longer do so.
contextObj.delay(sec)
Delays the next execution of the task with the given number of seconds.
Example
'use strict';
const taskPlugin = thorin.plugin('tasks');
const myTask = taskPlugin.addTask('my.task.right.here');

myTask
   .prepare((context) => {
      // Set any context information.
      context.items = [];
      context.processed = 0;
   })
   .action('dequeue', (context) => {   // Return a promise to signal the action completion.
      return new Promise((resolve, reject) => {
         log.info('Should dequeue');
         context.items.push("myItem");
         resolve();
      });
   })
   .action('process', (context) => {   // If returns undefined, go to next action automatically.
      if(context.items.length === 0) return;
      context.items.forEach((item) => {
         log.info('Processing item ', item);
         context.processed++;
      });
   })
   .action('release', (context) => {
      if(context.processed === 0) return;
      log.info('Releasing items');
      context.items = [];
   });
// Schedule the way our actions will be executed and when
myTask.schedule([
   'dequeue',
   'process',
   'release'
], {
   delay: '2s',
   timer: '40s',
   timeout: '30s'
});
// Listen for any events.
myTask
   .handle('completed', (context) => {
      log.info('Processed: ', context.processed);
   })
   .handle('failed', (context, err) => {
      log.warn(`Failed to finalize task`, err);
   });
Do you have a question or is something missing?

You can always create a new issue on GitHub or contact one of the core founders by chat.