Implement contextSeries - alternative to waterfall

[macobo]

This function is mainly useful as an alternative to watefall in versions of javascript, which support destructing.

Main problem with waterfall is that it becomes hard to debug/refactor after initial write due to needing to passaround arguments in exactly the correct order. This function when used with destructing gets around that problem by allowing to name steps in the series and then each function can grab results it cares about.

Example (in coffeescript):

# Adapted from one of my work scripts

getCurrentShards = (r, callback) -> # ...
cleanupOldShardMoves = ({shardInfo}, callback) -> # ...
createTask = ({shardInfo}, callback) -> # ...
setMoveStatus = (newStatus, {taskId, state}, callback) -> # ...
lockShards = ({taskId, shardInfo}, callback) -> # ...
# etc...

tasks = [
  ['shardInfo', getCurrentShards]
  cleanupOldShardMoves
  ['taskId', createTask]
  ['state', _.partial(setMoveStatus, 'initial')]
  lockShards
  _.partial(setMoveStatus, 'moving')
  moveInBatches
  _.partial(setMoveStatus, 'unlocking')
  unlockShards
  ['timestamp', updateMetadata]
]
async.contextSeries tasks, (err, {timestamp, taskId}) ->
  # ...
  log.info "Shard moves completed successfully at #{format timestamp} for task #{taskId}"

This function can prove to be even more useful by adding an optional seedData object with values which are made available to each task in the contextSeries array. I have omitted that however due to it not really fitting in with the rest of the API.

[aearly]

I don't feel like this is any more useful than auto. Sure, you have guaranteed in-order execution, but you can easily do that in auto by setting your dependencies correctly.

[aearly]

Also, the proposed feature in #635 -- essentially autoLimit -- might also be a way to enforce sequentiality.

[macobo]

I would argue it is more useful than auto for sequential operations because of not needing to specify previous steps name and autos downright weird function argument ordering.

As mentioned before, we're using it as an alternative to waterfall which always is a huge pain to refactor due to having to pass arguments through in the exact correct order.

[aearly]

I hear you about auto's weird parameter ordering. I want to swap the ordering, but need to figure out the best way to phase it in.

In the meantime, I often write a simple combinator that flips the arguments:

function flip(fn) {
  return function (results, cb) {
    return fn(cb, results);
  };
}

function normalAsyncFunction(options, callback) {...}

async.auto({
  //..
  "task": ["dependency", flip(normalAsyncFunction)]
  //..
})