serialchain

0.0.8 • Public • Published

SerialChain Build Status

NPM

Description

SerialChain is a module I wrote to so that I could write pretty code.

I like writing chains and really wanted to be able to do it with asynch code. There are a couple other options out there that already do this, but I wanted to learn how to write my own so I made this one.

Installation

npm install serialchain

npm install ben-bradley/serialchain

Concepts & Use

  • You create a chain:
var chain = new SerialChain({ methodA: function(a, done) {
  // do something
  done(err, a);
}})
  • You add() links to the chain.
chain.add('methodB', function(b, done) {
  // do something else
  done(err, b);
});
  • You can then compose and execute your chain
chain
  .methodB('xyz')
  .methodA('abc').timeout(1500)
  .done(function(err, results) {
    if (err)
      throw err;
    console.log(results); // => [ 'xyz', 'abc' ]
  });

this.locals

I found that I needed to have an easy way to pass variables between my chained methods so I added the locals property/namespace to the chain.

var chain = new SerialChain();
 
chain.add('methodA', function (done) {
  var locals = this.locals;
  // do something async to produce a value to pass to the next method
  setTimeout(function() {
    locals.a = 'produced value';
  }, 100);
  done(); // nothing is returned
});
 
chain.add('methodB', function (done) {
  if (this.locals.a)
    this.locals.b = 'methodA() was called first';
  else
    this.locals.b = 'methodB() was called first';
  done(); // nothing is returned
});
 
chain
  .methodB()
  .methodA()
  .done(function (err, results) {
    console.log(results); // => [] because neither returned anything
    console.log(this.locals); // =>
    // { a: 'produced value', b: 'methodB() was called first' }
  });

Built-in Methods

  • SerialChain()

    • Returns a new chain.
    • Accepts an Object to add to the chain:
    var chain = new SerialChain({ methodName: callback });
    
    • Added method callbacks have the signature:
    function([arguments, from, chain, call, ]done) {
      // ...
    }
    
  • add()

    • This method adds other methods (links) to your chain
    • Accepts arguments as an Object:
    chain.add({ methodName: callback });
    
    • Also accepts String and Function
    chain.add('methodName', callback);
    
    • Added method callbacks have the signature:
    function([arguments, from, chain, call, ]done) {
      // ...
    }
    
  • timeout()

    • Calling this method after an add()ed method will set a timeout on the previously called method.
    • Arguments are a Number of ms to wait
      chain
        .methodA('a').timeout(1000) // will wait 1 second and bail
        .methodB('b')
        .done(function(err, results) {
          // ...
        });
    
  • done()

    • This method triggers the execution of the chain.
    • Arguments are a callback:
      chain
        .methodA('a')
        .methodB('b')
        .done(function(err, results) {
          // ...
        })
    

Example

var SerialChain = require('serialchain');
 
var chain = new SerialChain({
  thingOne: function (a, done) {
    setTimeout(function () {
      done(null, a + '-thingOne');
    }, 100);
  },
  makeError: function (err, done) {
    done(new Error(err));
  }
});
 
chain.add('returnOne', function (a, done) {
  setTimeout(function () {
    done(null, a);
  }, 500);
});
 
chain.add('returnTwoThree', function (a, b, done) {
  setTimeout(function () {
    done(null, a + b);
  }, 1500);
});
 
chain.add({
  blargh: function (done) {
    done(null, 'honk');
  }
});
 
chain
  .returnOne('one')
  // thingOne() will complete in 100ms so this timeout will pass
  .thingOne('1').timeout(1000)
  .blargh()
  .returnTwoThree('two', 'three')
  .done(function (err, results) {
    console.log(arguments);
  });

Tests

$ npm install && npm test

Version History

  • 0.0.8 - Ensured that errors are promoted to be a new Error()
  • 0.0.7 - Added code to clean up _chain when done() is called
  • 0.0.6 - Added locals namespace to pass vars between methods
  • 0.0.5 - Calling done() without args in an add()ed method doesn't populate results.
  • 0.0.4 - Version bump, added Travis-CI.
  • 0.0.3 - Added timeout().
  • 0.0.2 - Refactored to serialchain.
  • 0.0.1 - Removed async dependency.
  • 0.0.0 - Initial drop.

Other Options

Readme

Keywords

Package Sidebar

Install

npm i serialchain

Weekly Downloads

0

Version

0.0.8

License

MIT

Last publish

Collaborators

  • ben-bradley