Task

basic specification

Perform an arbitrary task.

A valid node-task module is any object with a run property whose value is a method with the following signature: run(logger, config, input). The run method must return a promise which resolves when the task has completed. If a task fails it must reject the promise. All other properties listed below are optional.

description

A short description of the job the task will perform.

version

A valid semver string.

options

If a task allows options, they must be enumerated under this property as an object where the key is the option name and the value is an object which contains, at a minimum, key/value pairs for description and defaultValue. This property is primarily intended for task runner introspection, but authors are encouraged to use it for applying default values in parseConfig.

run(logger, config, input)

Execute a task, returning a promise representing its completion. Logger should be an object presenting a valid Logger API. Config should be an object holding the task configuration. If a task has input, it must arrive in a valid File Input Format.

parseConfig(config)

Normalize task configuration, returning the modified config with any defaults from options applied. This method must be synchronous.

setup(config)

Pre-task operations, if any, occur here.

teardown(config)

Post-task operations, if any, occur here.

Examples

While the following examples meet the requirements of the basic spec, they should not be considered the only correct way to implement a compliant module. Developers will undoubtedly provide builders to facilitate the creation of tasks. See a sample generator here.

A minimal compliant module:

var when = require('when');
MyTask = {};
MyTask.run = function (logger, config) {
  return when(true);
};
module.exports = Task;

A more comprehensive implementation:

var when = require('when');
var _ = require('lodash');

var MyTask = {}
MyTask.description = 'fake task using all spec properties and methods';
MyTask.version = '0.1.0';
MyTask.options = {
  debug: {
    description: "debug mode",
    defaultValue: false
  },
  fake: {
    description: "a fake option",
    defaultValue: 1
  }
};
MyTask.parseConfig = function (config) {
  var defaults = _.merge({}, this.options||{}, function(d, o) {
    return o.defaultValue;
  });
  return _.extend(defaults, config);
};
MyTask.run = function (logger, config, input) {
  var runConfig = this.parseConfig(config);
  return when(true);
};
MyTask.setup = function (config) {};
MyTask.teardown = function (config) {};

module.exports = Task;