npm:task-registry

README

task-registry

The hierarchical task registry collects tasks to execute synchronously or asynchronously.

It could register/unregister a task.
It could define the attributes of the task.
It chould set/change the attributes' default value of the task.
It chould pass an options object as argument into the task to execute.
It could get a task via path name or relative name.
It could execute a task synchronously or asynchronously.
It could be hierarchical tasks.
It could iterate all tasks via forEach.

Note: the registered name is case-sensitive.

Usage

Create a Task via the function

var Task      = require('task-registry')

// create a task via the non-params synchronous function.
Task.defineFunction('SayHiTask', function(){return 'hi'})
Task('SayHi').executeSync()
//=hi

// create a task via the synchronous function with params.
function echo(value) {return value}
Task.defineFunction(['EchoTask', 'echo', 'ping'], {params:['value'], fnSync: echo})
Task('ping').executeSync({value: 'hi world!'})
//=hi world!


// create a task via the function with params.
function add(a,b, done) {done(null, a+b)}
function addSync(a,b) {return a+b}
Task.defineFunction('AddTask', {params:[{name:'a',type:'Number'},{name:'b',type:'Number'}]
  , fnSync: addSync, fn: add})
Task('Add').execute({a:1,b:10}, function(err,result){
  console.log(result)
})
//=11

// create a task via the method.
Array.prototype.sum = function(){
  return this.reduce(function(a,b){return a+b}, 0)
}
Task.defineFunction('SumTask', {fnSync: Array.prototype.sum, self: [1,10]})
Task('Sum').execute(function(err,result){
  console.log(result)
})
//=11
Task('Sum').executeSync({_self:[1,2]})
//=3

Create a Task class

Task      = require 'task-registry'
register  = Task.register
aliases   = Task.aliases
defineProperties = Task.defineProperties

class SimpleTask
  register SimpleTask # the registered name is '/Simple'(excludes 'Task')
  aliases SimpleTask, 'simple', 'single'
  constructor: -> return super

  # (optional) define attributes of this task
  defineProperties SimpleTask,
    one:
      type: 'Number'
      value: 1 # the default value of the attribute.

  # (required)the task execution synchronously.
  # the aOptions argument is optional.
  _executeSync: (aOptions)->aOptions.one+1

  # (optional)the task execution asynchronously.
  # the default is used `executeSync` to execute asynchronously.
  #_execute: (aOptions, done)->

simpleTask = Task('Simple', one:3) #change the default value of the attr to 3.
sTask = Task('Simple')
assert.strictEqual sTask, simpleTask
assert.strictEqual simpleTask.one, 3

result = simpleTask.executeSync()
assert.equal result, 4

result = simpleTask.executeSync(one: 5) # override the default value.
assert.equal result, 6

the following is javascript:

var Task = require('task-registry');
var register = Task.register;
var aliases = Task.aliases;
var defineProperties = Task.defineProperties

//the class SimpleTask
function SimpleTask() {
  return SimpleTask.__super__.constructor.apply(this, arguments);
}

register(SimpleTask);
aliases(SimpleTask, 'simple', 'single');

defineProperties(SimpleTask, {
  one: {
    type: 'Number',
    value: 1
  }
});

SimpleTask.prototype._executeSync = function(aOptions) {
  return aOptions.one + 1;
};


var simpleTask = Task('Simple', {
  one: 3
});

var sTask = Task('Simple');

assert.strictEqual(sTask, simpleTask);

assert.strictEqual(simpleTask.one, 3);

var result = simpleTask.executeSync();
assert.equal(result, 4);

result = simpleTask.executeSync({
  one: 5
});
assert.equal(result, 6);

the hierarchical task:

class A1Task
  register A1Task, SimpleTask # register the A1Task to the SimpleTask
  #or SimpleTask.register A1Task

class A2Task
  register A2Task, SimpleTask # register the A2Task to the SimpleTask
  #or SimpleTask.register A2Task

a1Task = SimpleTask 'A1' # or simpleTask.get('A1')
assert.equal abcTask, Task '/Simple/A1'
a2Task = SimpleTask 'A2'
assert.equal abcTask, Task '/Simple/A2'

the following is javacript:

function A1Task() {}
register(A1Task, SimpleTask);

function A2Task() {}
register(A2Task, SimpleTask);

var a1Task = SimpleTask('A1');
assert.equal(abcTask, Task('/Simple/A1'));

var a2Task = SimpleTask('A2');
assert.equal(abcTask, Task('/Simple/A2'));

API

the derived task should overwrite these methods to execute a task:

_executeSync(aOptions): execute synchronously.
_execute(aOptions, callback): execute asynchronously (optional).
- It will call _executeSync to execute asynchronously if not exists.

Methods

class/static methods
- register(aTaskClass[[, aParentClass=Task], aOptions]): register the aTaskClass to the Task registry.
  - aOptions (object|string): It will use the aOptions as default options to create instance.
    - it is the customized registered name if aOptions is string.
    - name: use the name instead of the class name to register if any. or it will use the class name(remove the last factory name if exists) to register.
    - createOnDemand (boolean): create the task item instance on demand or create it immediately. defaults to true.
- unregister(aName|aClass): unregister the class or name from the Task registry.
- alias/aliases(aClass, aliases...): create aliases to the aClass.
- constructor(aName, aOptions): get a singleton task instance.
- constructor(aOptions): get a singleton task instance.
  - aOptions: (object)
    - name: the task item name. defaults to the constructor's name
- constructor(aInstance, aOptions): apply(re-initialize) the aOptions to the task aInstance.
- create(aName, aOptions): create a new task instance always.
- get(aName, aOptions): get the singleton task instance via aName and apply(re-initialize) the aOptions to the task.
- forEach(callback): iterate all the singleton task instances to callback.
  - callback function(instance, name)
- defineFunction(aName, aOptions, aParentTask = Task): define a function as a new task quickly.
  - aName String|ArrayOf String: the Task Class name to define. required
    - if it's array, the first is the task class name, and the others are the aliases.
  - aOptions Object|Function: the opitions object or the function synchronously. required
    - fnSync Function: execute the function synchronously. required
    - fn Function: execute the function asynchronously. optional
    - params Array: the parameters of this function [{name:'', type:'', value:''},{}]
      - [{name:'', type:'', value:''},{}] or
      - ['theParamName',...]
      - Note: the first char of the param name should not be '_'
    - self: (optional) the self object to call the function
    - alias String|ArrayOf String: the task aliases.
  - aParentTask Class: (optional) register to the class, defaults to the Task class.
  - return: the defined task class if successful.
instance methods
- get(aName, aOptions): get the singleton task instance via aName and apply(re-initialize) the aOptions to the task.
- register(aClass[, aOptions]): register a class to itself.
- unregister(aName|aClass): same as the unregister class/static method.
- execute([aOptions][, aName=this.name], callback): execute the task asynchronously.
  - aOptions (object):
    1. apply the default value of the task to the aOptions
    2. pass the aOptions object argument to the _execute method
  - aName (string): execute the specified task if any, defaults to itself.
  - callback function(error, result)
- executeSync([aOptions][, aName=this.name]): execute the task synchronously and return the result.
  - aOptions (object):
    1. apply the default value of the task to the aOptions
    2. pass the aOptions object argument to the _executeSync method
  - aName (string): execute the specified task if any, defaults to itself.

Note:

The Task Factory('root') will hold all the registered tasks.
The 'non-root' task will hold the tasks which registered to it.

TODO

License

MIT

Usage no npm install needed!