fw

About

fw is a tiny library which helps with asynchronous control-flow management in JavaScript environments

It exploits functional-style programming using higher-order functions and other common patterns. You could use it in conjunction with hu, for a better approach

Features

• Support series or parallel control-flow modes
• Collections iterators (each, map...)
• Runs in node and browsers
• Simple and easy-to-use API
• Tiny (~200 SLOC)
• Dependency-free
• Designed to be embedded in libraries or applications

Installation

Node.js

$ npm install fw --save

Browser

Via Bower package manager

$ bower install fw

Or loading the script remotely (just for testing or development)

<script src="//rawgithub.com/h2non/fw/master/fw.js"></script>

Environments

It works properly in any ES5 compliant engine

• Node.js
• Chrome >= 5
• Firefox >= 3
• Safari >= 5
• Opera >= 12
• IE >= 9

API

var fw = require('fw')

series(tasks, callback)

Run the functions in the array in series (sequentially). Each function will be executed only if its previous function has completed

If any functions in the series pass an error to its callback, no more functions are run and callback is immediately called with the value of the error

Arguments

• tasks - An array containing functions to run. Each function is passed a callback(err, result)
• callback - Optional callback to run once all the functions have completed. This function gets an array of results containing all the result arguments passed to the task callbacks. undefined or null values will be omitted from results

fw.series([
  function (next) {
    setTimeout(function () {
      next(null, 1)
    }, 100)
  },
  function (next, result) {
    setTimeout(function () {
      next(null, result + 1)
    }, 100)
  }
], function (err, results) {
  console.log(err) // → undefined
  console.log(results) // → [1, 2]
})

parallel(tasks, callback)

Run the tasks array of functions in parallel, without waiting until the previous function has completed

Once the tasks have completed, the results are passed to the final callback as an array

arguments

• tasks - An array containing functions to run. Each function is passed a callback(err, result)
• callback - Optional callback to run once all the functions have completed. This function gets an array of results containing all the result arguments passed to the task callbacks. undefined or null values will be omitted from results

fw.parallel([
  function (done) {
    setTimeout(function () {
      done(null, 1)
    }, 100)
  },
  function (done) {
    setTimeout(function () {
      done(null, 2)
    }, 150)
  }
], function (err, results) {
  console.log(err) // → undefined
  console.log(results) // → [1, 2]
})

whilst(test, fn, callback)

Repeatedly call a function, while test returns true. Calls callback when stopped or an error occurs

arguments

• test() - synchronous truth test to perform before each execution of fn.
• fn(callback) - A function which is called each time test passes. The function is passed a callback(err), which must be called once it has completed with an optional err argument
• callback(err) - A callback which is called after the test fails and repeated execution of fn has stopped

var count = 0

fw.whilst(
  function () {
    return count < 3
  },
  function (callback) {
    count++
    setTimeout(callback, 1000)
  },
  function (err) {
    // 3 seconds have passed
  }
)

each(arr, iterator, callback)

Alias: map, eachParallel, mapParallel

Applies the function iterator to each item in arr, in parallel. The iterator is called with an item from the list, and a callback for when it has finished

Note that since this function applies iterator to each item in parallel, there is no guarantee that the iterator functions will complete in order

arguments

• arr - An array to iterate over
• iterator(item, callback) - A function to apply to each item in arr. The iterator is passed a callback(err) which must be called once it has completed. If no error has occured, the callback should be run without arguments or with an explicit null argument
• callback(err) - A callback which is called when all iterator functions have finished, or an error occurs

var fs = require('fs')
var files = ['package.json', 'bower.json']

fw.each(files, fs.readFile, function (err, results) {
  console.log(err) // → undefined
  console.log(results) // → [Buffer, Buffer]
})

eachSeries(arr, iterator, callback)

Alias: mapSeries

The same as each(), but only iterator is applied to each item in the array in series

The next iterator is only called once the current one has completed (sequentially)

var fs = require('fs')
var files = ['package.json', 'bower.json']

fw.eachSeries(files, fs.readFile, function (err, results) {
  console.log(err) // → undefined
  console.log(results) // → [Buffer, Buffer]
})

Contributing

Wanna help? Great! It will be really apreciated :)

You must add new test cases for any new feature or refactor you do, always following the same design/code patterns that already exist

Development

Only node.js is required for development

Clone/fork this repository

$ git clone https://github.com/h2non/fw.git && cd fw

Install dependencies

$ npm install

Compile code

$ make compile

Run tests

$ make test

Generate browser sources

$ make browser

License

MIT © Tomas Aparicio