segue

v2.1.0

Published

2 years ago

Enqueue functions, and call them in series.

Downloads

0High
0Medium
0Low

yuanqing

async asynchronous callback control curried currying flow queue sequential serial series sync synchronous waterfall

Segue.js

Enqueue functions, and call them in series.

Features

Enqueue asynchronous functions to be called in series
Pause or resume the calling of functions in the queue
Optionally repeat the entire sequence of function calls indefinitely
Small as it gets; 0.67 KB minified, or 0.41 KB minified and gzipped
Error handling

Quick start

There is a simple, runnable example you can play with:

$ git clone https://github.com/yuanqing/segue
$ cd segue
$ node example/index.js

There are also tests.

Example

We first initialise our queue of functions by calling segue, passing in a doneCb callback:

var segue = require('segue');

var doneCb = function(err) {
  if (err) {
    throw err;
  }
};

var queue = segue(doneCb);

doneCb is called when all the functions in queue have run, or if an error had occurred in one of the functions.

Suppose that we have two functions, x and y…

var x = function(cb, a) {
  console.log(a); //=> 1
  setTimeout(function() {
    cb();
  }, 100);
};

var y = function(cb, a, b) {
  console.log(a, b); //=> 2, 3
  cb();
};

…which we add into the queue via push():

queue.push(x, 1)
     .push(y, 2, 3);

Then, call run() to kick off the sequence of function calls:

queue.run();

The function x will be called with the argument 1. After 100 milliseconds, x finishes execution, and function y is called with the arguments 2 and 3.

Note that every function added into the queue takes a cb callback as the first argument. Each function must call cb to signal that it has finished execution. As is convention, cb takes an err as its first argument. If err is truthy, the doneCb callback is called with said err, and no more functions in the queue are run.

Pause, resume

We can pause the calling of functions in the queue on-the-fly by calling pause(). This method takes an optional callback that is called when the currently-running function has finished execution:

queue.pause(function() {
  console.log(queue.isRunning()); //=> false
});

See that here, we’ve also used the isRunning() method.

To resume the calling of functions, call run():

queue.run();
console.log(queue.isRunning()); //=> true

Repeat

Finally, note that we can also repeat the entire sequence of function calls indefinitely. Simply pass in opts with opts.repeat set to true when initialising the queue:

var queue = segue(doneCb, { repeat: true });

API

var segue = require('segue');

See Usage.

var queue = segue([doneCb, opts])

Initialises the function queue.

The doneCb callback is called when all the functions in queue have run, or if an error had occurred in one of the function calls. The signature of doneCb is (err).
Set opts.repeat to true to repeat the sequence of function calls indefinitely.

queue.push(fn [, arg1, arg2, …])

Adds a function fn into the queue, and returns the queue. The fn will be called with a cb callback, followed by the arguments specified here. In other words, the signature fn is (cb, [, arg1, arg2, ...]).

fn must call cb to signal that it has finished execution. If err is truthy, the doneCb callback is called with said err, and no more functions in the queue are run.

queue.run()

Starts (or resumes) the sequence of function calls, and returns the queue.

queue.pause([pauseCb])

Pauses the sequence of function calls, and returns the queue. Calls the optional pauseCb callback when the queue is paused.

queue.isRunning()

Returns true if a function in the queue is running, else returns false.

Installation

Install via npm:

$ npm i --save segue

Install via bower:

$ bower i --save yuanqing/segue

To use Segue in the browser, include the minified script in your HTML:

<body>
  <script src="path/to/segue.min.js"></script>
  <script>
    // `segue` available here
  </script>
</body>

License

MIT