https://github.com/atlassubbed/atlas-waterfall

https://github.com/atlassubbed/atlas-waterfall

Last synced: 21 days ago
JSON representation

• Host: GitHub
• URL: https://github.com/atlassubbed/atlas-waterfall
• Owner: atlassubbed
• License: other
• Created: 2018-07-14T04:54:52.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2018-07-14T06:36:17.000Z (over 6 years ago)
• Last Synced: 2024-10-01T09:18:43.871Z (3 months ago)
• Language: JavaScript
• Size: 9.77 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.md

Awesome Lists containing this project

README

        
# atlas-waterfall

Run async functions in a "waterfall" series with an onDone callback.

[![Travis](https://img.shields.io/travis/atlassubbed/atlas-waterfall.svg)](https://travis-ci.org/atlassubbed/atlas-waterfall)

---

## install 

```

npm install --save atlas-waterfall

```

## why

If you want to avoid promises, you can use a waterfall instead. It will run an array of `N` async functions in serial, passing the `(err, ...results)` from one function to the next. The `allDone` callback receives the `(err, ...results)` from the very last function. See examples below.

## examples

#### array of jobs

The following will run `reddit.post` with the results/error from `email.send`, and the final callback with the results from `reddit.post`:

```javascript

const waterfall = require("atlas-waterfall");

waterfall([

  done => email.send("[email protected]", "hello", (emailErr, isSuccess, id) => {

    // can pass many results to next job in the waterfall

    if (emailErr) return done(emailErr, "failed early...")

    done(null, isSuccess, id)

  }),

  (done, isSuccess, id) => {

    const subreddit = isSuccess ? "mildlyinteresting" : "mildlyinfuriating"

    reddit.post("atlassubbed.png", subreddit, postErr => {

      done(postErr, "tried", "all tasks");

    })

  }

], (err, ...res) => {

  // if email failed: err === emailErr, res === ["failed early..."]

  // if post failed: err === postErr, res === ["tried", "all tasks"]

  // if no errors: err === null, res === ["tried", "all tasks"]

})

```

## caveats

If any function in the sequence returns an error, the remainder of the sequence will be skipped, and the `allDone` callback will be called with the error. Sometimes, a task will fail but you will still need to run the remaining functions -- in this case, simply handle the error instead of passing it as the first argument to the task's `done` callback.

## todo

Passing initial args might be useful:

```javascript

waterfall(...args, [

  (done, ...args) => {

  },

  ...otherJobs

], allDone)

```

It would be more symmetric and aesthetic to allow initial args to be passed to the first job, since the last job's results are passed to `allDone`. Of course, this can easily be done with a jobs factory, so I don't think it's *needed*:

```javascript

waterfall(getJobs(...args), allDone)

```