taskling

Small simple async function series with prepend/append/clear during run.

Features:

1. Provides a shared object to each task function
2. execution ends when a task provides an error to the callback
3. mutable task queue via prepend(), append(), clear()
4. Task arrays provided will be flattened.
5. early termination by providing an error.
6. last task can provide a result for the done callback.
7. uses process.nextTick by default, can specify setImmediate or a custom executor.

Install

npm install --save taskling

Usage

const tasks = require('taskling')

// create a shared object to hold data usable by all task functions:
const shared = {}

// create an array of functions (tasks) to run:
const array = [
  // must always call the first arg, next(), when done.
  function first(next) { next() },

  // second arg is the `shared` we provide to tasks()
  function second(next, sharedObject) { next() },

  // the `this` context is a "control" object with helper functions:
  function controlled(next, _, control) {
    // prepend/append:
    //   - require an array argument.
    //   - accept nested arrays.

    // add array of functions to run *next*,
    // so they go in the front of the queue/array:
    control.prepend([/* ... */])

    // same as prepend() except they are added to the end.
    control.append([/* ... */])

    // empty the tasks array:
    control.clear()

    next()  // always call next()
    // last function can provide a result like this:
    //   next(null, theResult)
    // the first arg is null for error.
  },
]

// a "done" function is called when tasks are done.
// if an error is provided by a task then execution stops
// and the "done" callback is called with the error as first arg.
// if no error is provided, ever, then "done" is called last.
function done(error, result) {
  // do something with error, if it exists...
  // otherwise, it was a success.
  // get your results from the `sharedObject`,
  // or, the last task can provide a `result` as the 2nd arg.
}

// now, use those three things to run the tasks:
tasks(shared, array, done)

// NOTE:
//  tasks() will always return immediately before it begins execution.
//  this is the standard behavior for asynchronous API's.
//  by default it calls each task via `process.nextTick()`.
//  to override that with setImmediate, pass it as the fourth arg.
tasks(shared, array, done, setImmediate)


// Succinct use:
require('taskling')({
    // the shared object
  }, [
    // the tasks array
  ],
  function(error, result) {
    // the "done" callback
  }
)

map+require

I usually separate out my task functions into separate modules. Then, instead of writing require() every for each one I use map(require) on the array.

var array = [
  'some-package',     // some published package providing a task function
  './some/module.js', // some local module providing a task function
].map(require)

// or in the whole thing as "succinct" version:
require('taskling')({
  // shared object
}, [
  'some-package',
  './some/module.js',
].map(require), function(error) {
  // all done...
})

MIT License

2.0.0 - 2021/06/28

1. update deps
2. switch to tap from mocha
3. remove test for optimizability
4. always use @flatten/array
5. store their task arrays in our array instead of push()'ing their fn's into our array.
6. reverse() their array so we can pop() off the next fn.
7. move tiny external functions into main function as closures.
8. list each component in a const list.
9. update tests for new algorithm.
10. change Travis CI to travis-ci.com and use a single VM.

1.3.0 - 2019/06/02

1. apply array flatten to task array given to main taskling function (it was already flattening those to prepend/append).
2. uses the new builtin Array.flat() of node 12, when available (pass Infinity for depth).
3. tweak some tests to be tougher (more depth/complexity in the arrays to flatten).

1.2.0 - 2019/05/18

1. added ability to specify which function will run the tasks so setImmediate can be used instead of process.nextTick.
2. updated README to explain new option
3. update deps
4. drop node 6

1.1.1 - 2019/04/29

1. switch node 11 to 12
2. update deps

1.1.0 - 2019/01/07

1. add strict mode
2. use const
3. reformat for spacing and put comments on line above code line.
4. accept a result to iterator so it can be provided to the done callback.
5. add 2019 to license.
6. drop node 4, add node 10 and 11.
7. update deps

1.0.2 - 2017/06/22

1. fix main file inclusion by removing 'lib/' in package.json

1.0.1 - 2017/06/18

1. added section to README about using map(require) to pull packages/modules into task array.

1.0.0 - 2017/06/18

1. initial working version with tests and 100% code coverage