Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
The true solution to callback hell. Robust, simple, and consistent. Group together synchronous and asynchronous tasks and execute them with support for concurrency, naming, and nesting.
CoffeeScript

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src
.gitignore
.npmignore
.travis.yml
Cakefile
History.md
LICENSE.md
README.md
example.js
package.json

README.md

Task Group

Build Status NPM version Flattr this project

Group together synchronous and asynchronous tasks and execute them with support for concurrency, naming, and nesting.

Install

Backend

  1. Install Node.js
  2. npm install --save taskgroup

Frontend

  1. See Browserify

Usage

Example

// Import
var TaskGroup = require('taskgroup').TaskGroup;

// Create our new group
var group = new TaskGroup();

// Define what should happen once the group has completed
group.once('complete', function(err,results){
    // Log the error that has occured
    console.log(err);
    // => null

    // Log the results that our group received from the executing items
    console.log(JSON.stringify(results));
    /*  =>
        [
            [null, 'first', 'task'],
            [null, 'second task'],
            [null, [
                [null, 'sub second task'],
                [null, 'sub first', 'task']
            ]]
        ]
    */
});

// Add an asynchronous task that gives the result to the completion callback
group.addTask(function(complete){
    setTimeout(function(){
        complete(null, 'first', 'task');
    },500);
});

// Add a synchronous task that returns the result
// Errors should be returned, though if an error is thrown we will catch it
group.addTask(function(){
    return 'second task';
});

// Add a sub-group to our exiting group
group.addGroup(function(addGroup,addTask){
    // Tell this sub-group to execute in parallel (all at once) by setting its concurrency to unlimited
    // by default the concurrency for all groups is set to 1
    // which means that they execute in serial fashion (one after the other, instead of all at once)
    this.setConfig({concurrency:0});

    // Add an asynchronous task that gives its result to the completion callback
    addTask(function(complete){
        setTimeout(function(){
            complete(null, 'sub first', 'task');
        },500);
    });

    // Add a synchronous task that returns its result
    addTask(function(){
        return 'sub second task';
    });
});

// Execute our group
group.run();

TaskGroup API

new (require('taskgroup')).TaskGroup()
  • Available methods:
    • constructor(name?,fn?) - create our new group, the arguments name and fn are optional, refer to their entries in configuration
    • setConfig(config) - set the configuration for the group, returns chain
    • addTask(args...) - create a new task item with the arguments and adds it to the group, returns the new task item
    • addGroup(args...) - create a new group item with the arguments and adds it to the group, returns the new group item
    • getTotals() - returns counts for the following {running,remaining,completed,total}
    • clear() - remove the remaining items to be executed
    • pause() - pause the execution of the items
    • stop() - clear and pause
    • exit(err) - stop and complete, err if specified is sent to the completion event when fired
    • complete() - will fire the completion event if we are already complete, useful if you're binding your listeners after run
    • run() - start/resume executing the items, returns chain
    • All those of EventEmitter2
  • Available configuration:
    • name, no default - allows us to assign a name to the group, useful for debugging
    • fn(addGroup,addTask,complete?), no default - allows us to use an inline and self-executing style for defining groups, useful for nesting
    • concurrency, defaults to 1 - how many items shall we allow to be run at the same time, set to 0 to allow unlimited
    • pauseOnError, defaults to true - if an error occurs in one of our items, should we stop executing any remaining items?
      • setting to false will continue with execution with the other items even if an item experiences an error
  • Available events:
    • run() - fired just before we execute the items
    • complete(err, results) - fired when all our items have completed
    • task.run(task) - fired just before a task item executes
    • task.complete(task, err, args...) - fired when a task item has completed
    • group.run(group) - fired just before a group item executes
    • group.complete(group, err, results) - fired when a group item has completed
    • item.run(item) - fired just before an item executes (fired for both sub-tasks and sub-groups)
    • item.complete(item, err, args...) - fired when an item has completed (fired for both sub-task and sub-groups)

Task API

new (require('taskgroup')).Task()
  • Available methods:
    • constructor(name?,fn?) - create our new task, the arguments name and fn are optional though fn must be set at some point, refer to their entries in configuration
    • setConfig(config) - set the configuration for the group, returns chain
    • complete() - will fire the completion event if we are already complete, useful if you're binding your listeners after run
    • run() - execute the task
  • Available configuration:
    • name, no default - allows us to assign a name to the group, useful for debugging
    • fn(complete?), no default - must be set at some point, it is the function to execute for the task, if it is asynchronous it should use the completion callback provided
    • args, no default - an array of arguments that you would like to precede the completion callback when executing fn
  • Available events:
    • run() - fired just before we execute the task
    • complete(err, args...) - fired when the task has completed

History

You can discover the history inside the History.md file

License

Licensed under the incredibly permissive MIT License
Copyright © 2013+ Bevry Pty Ltd
Copyright © 2011-2012 Benjamin Arthur Lupton

Something went wrong with that request. Please try again.