monkeybars

Task library that provides a simple structure for handling singular, sequential and parallel units of code.

MonkeyBars

A task based library that provides a simple structure for handling singular, sequential and parallel units of code.

The overall architecture is based off of the composite and decorator patterns. These patterns lend themselves very well to a task based library, where tasks can contain other tasks all contributing to the overall flow of an operation.

The library itself has no ties to the browser, and because of this it works both in client side & server side javascript projects. Include monkeybars.min.js for your client side projects or install using npm by running the following command from within your project:

$ npm install monkeybars [-g]

Monkeybars.Task is the simplest form of a task possible. You can override any of the methods provided (granted you must then call the prototype version of the method), but in its simplest form a task only requires the performTask method to be present. For a list of all possible methods and properties available have a look at the documentation.

var task = new MonkeyBars.Task({
    name:"SimpleTask",
    loggingEnabled:true,
    onChange:function(state,error){
        if(state == MonkeyBars.TaskStates.Completed) {
            alert("The 'SimpleTask' is complete");
        }
    },
    performTask:function(){
        this.complete();
    }
});

task.start();

Task groups are a great way to contain and structure both serial and async units of code. There are numerous syntax variations that you can use in order to create and add subtasks to a task group. Have a look at the group, parallel and sequence specs within the tests directory for all of the possible variations.

var group = new MonkeyBars.SequenceTask({
    name:"SimpleTask",
    loggingEnabled:true,
    tasks:[{
        name:"subtask1",
        performTask:function(){
            // run task functionality
            this.complete();
        }
    },
    {
        name:"subtask2",
        performTask:function(){
            // run task functionality
            this.complete();
        }
    }]
});

group.start();

In some cases you may have a need for more specific functionality then what is provided with the simple, parallel and sequence task types. It is very simple to extend the base functionality of a specific task type to bake your own.

var MyCustomGroupTask = MonkeyBars.TaskGroup.extend({
    type:"MyCustomGroupTask",
    start:function(){
        this.customFunction();
        MonkeyBars.TaskGroup.prototype.start.call(this);
    },
    customFunction:function(){
        // custom logic
    }
});

var group = new MyCustomTaskGroup({
    name:"group",
    tasks:[...]
});

group.start(); 

There are three decorators (for, when and where) available for all three types of tasks(simple, parallel, and sequence). If you set a count on a task it will itterate for that count total. If you have a when method as a task attribute the task will only run when that method returns true. And if you have a while method the task will continuously run until that method returns false.

For Decorator

var task = new MonkeyBars.Task({
    ...
    count:3,
    performTask:function(){
        ...
    }
    ...
});

When Decorator

var task = new MonkeyBars.Task({
    ...
    when:function(){
        return something == true;
    },
    performTask:function(){
        ...
    }
    ...
});

When Decorator

var task = new MonkeyBars.Task({
    ...
    while:function(){
        return something == false;
    },
    performTask:function(){
        ...
    }
    ...
});

Full documentation can be seen from within the docs directory of this project.

As stated above the tasks within the library implement the composite design pattern, this simply means that all groups of tasks are themselves tasks. Tasks have the ability to have sub tasks nested within them, turning them into task groups. By default nested tasks run sequentially, unless otherwise specified. Currently the two types of task groups available are sequence and parallel (implementation examples above).

Sequential tasks run sub tasks one after another until all sub tasks complete. When all nested sub tasks are complete the complete state is passed to the task groups change method for handling.

Parallel tasks are task groups who's nested subtasks are executed side by side, executing whenever they can. Just like the sequential task group, when all sub tasks have completed the groups change method will be notified.

There is no limit to the depth of which you nest tasks, which is where the power of the library starts to become apparent. You can view a more complex example of this in the complex example within the examples directory.

Examples for the library can be found in the examples directory of this project.