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