Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    stepuppublic

    stepup

    A simple control-flow library for node.js that makes parallel execution, serial execution, and error handling painless.

    Install

    npm install stepup
    

    Basic Usage

    For a complete overview of functionality, see the unit tests.

    stepup exports a single function:

    var $$ = require('stepup')
    $$(steps, [options], [callback])
    

    Which can be used to execute an array of functions or "steps"

    $$([
      function stepOne($) {
        var valueOne = 'a synchronous value'
        return valueOne
      }
    , function stepTwo($, valueOne) {
        fs.readFile('someFile.txt', $.first())
      }
    , function stepThree($, someFileTxt) {
        // ...
      }
    ])
    

    The first argument is the context object, $. $ contains functions for generating callbacks. When all generated callbacks have been called, synchronously or asynchronously, the next step will be called.

    Note:

    • Any number of callbacks may be generated in a given step.
    • If no callbacks are generated (e.g., a value is returned), the next step will proceed.

    Additionally, there are many types of generator functions

    $$([
      function($) {
        // Pass the first non-error argument
        $.first()(null, 'firstValue')
        
        // Pass all arguments as an array
        $.collapse()(null, 'collapseA', 'collapseB', 'collapseC')
        
        // Pass the first argument from an event (error-less) handler
        $.event()('eventValue')
                
        // Don't pass any arguments
        $.none()(null, 'noneA', 'noneB')
        
        // Don't pass any arguments AND ignore the error value
        $.ignore()(new Error('Don't care.'), 'ignoreA', 'ignoreB')
        
        // Pass all arguments spread across multiple values
        $.spread()(null, 'spreadA', 'spreadB')
      }
    , function($, firstValue, collapseValues, eventValue, spreadA, spreadB) {
        // collapseValues === ['collapseA', 'collapseB', 'collapseC']
        
    	// Errors will be passed to the callback and remaining steps will be skipped
    	$.first()(null, 'This value will never be seen.')
    	$.first()(new Error('Pass this to the callback'))
      }
    , function ignoredStep($) {
        // Skipped because error was passed
      }
    ], function callback(err) {
      // err.message === 'Pass this to the callback'
    })
    

    The group generator is convenient for waiting on a set of async calls

    $$([
      function($) {
        var files = ['A.txt', 'B.txt', 'C.txt', 'D.txt']
        // Create a group generator, type is optional and defaults to 'first'
        // (e.g., 'first', 'collapse', 'event', 'none', etc...)
        var group = $.group('first')
        
        files.forEach(function(fileName) {
          // Generate a callback for each file in the list
          fs.readFile(fileName, group())
        )
      }
    , function($, groupValues) {
        // ...
      }
    ])
    

    Error Handling

    The first error is always passed to the callback, with all remaining results, errors, or steps ignored. If you this is undesirable, considering using $.ignore or wrapping a callback

    $$([
      function($) {
        var next = $.first()
        
        fs.readFile(fileName, function(err, data) {
          // Ignore the error if it exists
          next(null, data)
        })
      }
      // ...
    ])
    

    Additionally, stepup uses the trycatch async try/catch library to catch all errors. To disable, call $.config({useAsyncTrycatch: false})

    Extras

    $.end

    Useful for skipping the remaining steps and passing values to the callback

    $$([
      function($) {
        if (cachedValue) {
          return $.end(null, cachedValue)
        }
        fs.readFile('someFile.txt', $.first())
      }
    , function($, someFileTxt) {
        // Skipped when cachedValue is truthy
      }
    ], callback)
    

    $.data

    Is an object useful for storing state across steps

    $$([
      function($) {
        $.data.foo = true
        fs.readFile('someFile.txt', $.first())
      }
    , function($, someFileTxt) {
        // $.data.foo === true
      }
    ], callback)
    

    $.run

    Is a convenience function for nesting steps

    $$([
      function($) {
        $.run([
          function(_$) {
            // ...
          }
        , function(_$) {
            // ...
          }
        ], $.first())
        
        fs.readFile('someFile.txt', $.first())
      }
    , function($, subStepResult, someFileTxt) {
        // ...
      }
    ], callback)
    

    Options

    timeout

    Use to guarantee a callback is called after a timeout period

    $$([
      function($) {
        var next = $.first()
    
        setTimeout(function() {
          next()
        }, 2000)
      }
    , function($) {
        // Never called because of timeout
      }
    ], {timeout: 1000}, callback)

    Keywords

    none

    install

    npm i stepup

    Downloadslast 7 days

    12

    version

    1.1.2

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar