async-base-iterator

Basic iterator for async library that handles async and synchronous functions, also emits beforeEach, afterEach and error events. Using async-simple-iterator and used in async-control.

Install

npm i async-base-iterator --save

Usage

For more use-cases see the tests

var base = require('async-base-iterator')
// or get constructor
var AsyncBaseIterator = require('async-base-iterator').AsyncBaseIterator

API

AsyncBaseIterator

Initialize AsyncBaseIterator with options, see also async-simple-iterator.

Params

• options {Object=}: Pass beforeEach, afterEach and error hooks or settle option.

Example

var ctrl = require('async')
var AsyncBaseIterator = require('async-base-iterator').AsyncBaseIterator

var fs = require('fs')
var base = new AsyncBaseIterator({
  settle: true,
  beforeEach: function (fn) {
    console.log('before each:', fn.name)
  },
  error: function (err, res, fn) {
    console.log('on error:', fn.name)
  }
})
var iterator = base.makeIterator({
  afterEach: function (err, res, fn) {
    console.log('after each:', err, res, fn.name)
  }
})

ctrl.mapSeries([
  function one () { return 1 },
  function two (done) { done(null, 2) },
  function three () { return 3 },
], iterator, function (err, results) {
  // => `err` will always be null, if `settle:true`
  // => `results` is [1, 2, 3]
})

.makeIterator

Make iterator to be passed to async lib.

Params

• [options] {Object=}: Pass beforeEach, afterEach and error hooks or settle option.
• returns {Function}: Iterator that can be passed to any async method.

Events

• emits: beforeEach with signature fn, next
• emits: afterEach with signature err, res, fn, next
• emits: error with signature err, res, fn, next

Example

var ctrl = require('async')
var base = require('async-simple-iterator')

base
  .on('afterEach', function (err, res, fn) {
    console.log('after each:', err, res, fn.name)
  })
  .on('error', function (err, res, fn) {
    console.log('on error:', err, res, fn.name)
  })

var iterator = base.makeIterator({
  settle: true,
  beforeEach: function (fn) {
    console.log('before each:', fn.name)
  }
})

function throwError () {
  throw new Error('two err')
}

ctrl.mapSeries([
  function one () { return 1 },
  function two () {
    throwError()
    return 2
  },
  function three (cb) { cb(null, 3) }
], iterator, function (err, res) {
  // `err` is always `null` when `settle: true`
  console.log(err) // => null
  console.log(res) // => [1, [Error: two err], 3]
})

.doneCallback

Helper, wrapper function. Use it to wrap you final callback function which you pass to async lib. This may be needed if you want to catch if error happens in the final callback function, because actually it is executed in promise as the other functions in stack. There's just no other way to handle errors from final callback, it is rare case, but sometimes it may be needed. Be aware of that.

Params

• <fn> {Function}: called with arguments passed to the returned callback
• [done] {Function=}: optional
• returns {Function}: callback function that you can pass to async methods

Example

var base = require('async-base-iterator')
var ctrl = require('async')
var assert = require('assert')

ctrl.mapSeries([function () {
  return 123
}], base.makeIterator(), base.doneCallback(function (err, res) {
  console.log(err) // => null
  console.log(res) // => 123
  assert.strictEqual(res, 555) // intentionally
}, function (err) {
  console.log(err) // => AssertionError
}))

Related

• async: Higher-order functions and common patterns for asynchronous code | homepage
• async-control: Ultimate asynchronous control flow goodness with built-in hook system and compose, series, define and parallel methods. Uses async.map and async.mapSeries methods. Allows passing custom iterator function. | homepage
• async-simple-iterator: Making simple iterator for async lib that adds beforeEach, afterEach, error hooks and support for settling. It also emits beforeEach, afterEach and error events. | homepage
• iterator-async: Iterate over a stack of async functions. | homepage
• iterator-promise: Iterate over a stack of functions. | homepage
• letta: Let's move to promises! Drop-in replacement for co@4 (passing 100% tests), but on steroids. Accepts sync, async and generator functions. | homepage
• relike: Simple promisify a callback-style function with sane defaults. Support promisify-ing sync functions. | homepage
• then-callback: Wrap a promise to allow passing callback to .then of given promise, also works as normal .then | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
But before doing anything, please read the CONTRIBUTING.md guidelines.

Charlike Make Reagent