Support series

zoubin · Dec 10, 2015 · d6f4c65 · d6f4c65
1 parent 4aef4f9
commit d6f4c65
Show file tree

Hide file tree

Showing 11 changed files with 363 additions and 133 deletions.
diff --git a/README.md b/README.md
@@ -56,77 +56,158 @@ function stream() {
 
 ## API
 
-### cb = thunkify(...tasks)
-Return a callback to run the specified tasks in the appearance order.
+```javascript
+var Runner = require('./lib/runner')
+var runner = new Runner({ input: false, output: false })
+
+exports = module.exports = runner.thunkify.bind(runner)
+exports.run = exports.sequence = runner.sequence.bind(runner)
+exports.parallel = runner.parallel.bind(runner)
+exports.series = runner.series.bind(runner)
+exports.Runner = Runner
+
+```
 
-`cb` will return a promise.
+### Runner
+`var runner = Runner(opts)`
+Create a new runner instance.
+
+#### opts
+
+##### input
+Specify whether to pass the results of the previous callback to the next as arguments.
+
+Type: `Boolean`
+
+Default: `true`
 
 ```javascript
-var res = []
-thunkify(
-  function () {
-    res.push(1)
+var Runner = require('callback-sequence').Runner
+
+var runner = Runner({ input: true })
+
+runner.thunkify(
+  function (a, b) {
+    // 3
+    return a + b
   },
-  function (next) {
+  function (sum, next) {
     process.nextTick(function () {
-      res.push(2)
-      next()
+      // 6
+      next(null, sum * 2)
     })
   },
-  function () {
+  function (product) {
     return Promise.resolve().then(function () {
-      res.push(3)
+      // 7
+      return product + 1
     })
   }
-)()
-.then(function () {
-  // [1, 2, 3]
+)(1, 2)
+.then(function (res) {
+  // [7]
   console.log(res)
 })
 
+
 ```
 
-### thunkify.run(tasks)
-It just runs `tasks` like you call the function returned by `thunkify`
+##### output
+Specify whether to deliver results.
+
+Type: `Boolean`
+
+Default: `true`
+
+If `false`, the final results will always be `[]`.
+
+##### run
+Specify a runner function to run each callback.
+
+Type: `Function`, `Object`
+
+Default: `null`
+
+If `Function`, it receives a callback followed by a list of arguments,
+and should return a promise to fetch the results (`Array`).
+
+If `Object`, it is passed to
+[`Runner of run-callback`](https://github.com/zoubin/run-callback#runner--runrunner)
+to create a runner function.
 
-**NOTE**: if some task is an array of sub-tasks, they will be run in parallel.
+
+#### cb = Runner.prototype.thunkify(...tasks)
+Return a callback to run the specified tasks in the appearance order.
 
 ```javascript
-var run = require('callback-sequence').run
+var runner = Runner()
 
-var res = []
-run([
-  function () { res.push(1) },
+runner.thunkify(
+  function (res) {
+    return res + 1
+  },
+  function (res) {
+    return Promise.resolve()
+      .then(function () {
+        return res + 1
+      })
+  },
+  function (res, next) {
+    process.nextTick(function () {
+      next(null, res - 1, res + 1)
+    })
+  }
+)(1)
+.then(function (res) {
+  // [ 2, 4 ]
+  console.log(res)
+})
+
+```
+
+#### Runner.prototype.sequence(tasks)
+Run `tasks` in sequence.
+
+**NOTE**: directly nested array of tasks will be run with `Runner.prototype.parallel`.
+
+```javascript
+var runner = Runner()
+
+runner.sequence([
+  function () { console.log(1) },
   [
     function (cb) {
       setTimeout(function() {
-        res.push(3)
+        console.log(3)
         cb()
       }, 0)
     },
     function () {
       return new Promise(function (resolve) {
         process.nextTick(function () {
-          res.push(2)
+          console.log(2)
           resolve()
         })
       })
     },
   ],
-  function () { res.push(4) },
-]
-)
-.then(function () {
-  // [1, 2, 3, 4]
-  console.log(res)
+  function () { console.log(4) },
+]).then(function () {
+  console.log('DONE')
 })
 
+// 1
+// 2
+// 3
+// 4
+// DONE
+
 ```
 
-Callbacks an be added dynamically:
+Callbacks can be added dynamically:
 
 ```javascript
-var run = require('callback-sequence').run
+var runner = Runner()
 
 var count = 5
 var tasks = []
@@ -141,7 +222,7 @@ function task(next) {
     next()
   })
 }
-run(tasks).then(function () {
+runner.sequence(tasks).then(function () {
   // [5, 4, 3, 2, 1]
   console.log(res)
 })
@@ -150,16 +231,16 @@ tasks.push(task)
 
 ```
 
-### thunkify.parallel(tasks)
+#### Runner.prototype.parallel(tasks)
 Run the specified tasks in parallel.
 
-**NOTE**: if some task is an array of sub-tasks, they will be run in sequence.
+**NOTE**: directly nested array of tasks will be run with `Runner.prototype.sequence`.
 
 ```javascript
-var parallel = require('callback-sequence').parallel
+var runner = Runner()
 
 var res = []
-parallel([
+runner.parallel([
   function () { res.push(1) },
   [
     function () {
@@ -179,82 +260,67 @@ parallel([
     res.push(2)
     cb()
   },
-]
-)
+])
 .then(function () {
   // [1, 2, 4, 5, 3]
   console.log(res)
 })
 
 ```
 
-### Runner = thunkify.Runner(opts)
-Return a new runner instance, with the following methods:
+#### Runner.prototype.series(...tasks)
+Run `tasks` in sequence.
 
-* `sequence`: just like `thunkify.run`
-* `parallel`: just like `thunkify.parallel`
-* `thunkify`: just like `thunkify`
+However, while the results of `sequence` is that of the last task,
+the results of `series` is an array containing all results of the tasks.
 
-#### opts
+In addition, the results of the previous task will not be passed to the next as arguments.
 
-##### input
-Specify whether to pass the results of the previous callback to the next as arguments.
-
-Type: `Boolean`
-
-Default: `true`
+**NOTE**: each element will be passed to `Runner.prototype.sequence`.
 
 ```javascript
-var Runner = require('callback-sequence').Runner
+var runner = Runner()
 
-var runner = Runner({ input: true })
-
-runner.thunkify(
-  function (a, b) {
-    // 3
-    return a + b
-  },
-  function (sum, next) {
-    process.nextTick(function () {
-      // 6
-      next(null, sum * 2)
-    })
+runner.series(
+  function () {
+    console.log(1)
+    return 1
   },
-  function (product) {
-    return Promise.resolve().then(function () {
-      // 7
-      return product + 1
-    })
+  [
+    function () {
+      return Promise.resolve().then(function () {
+        console.log(4)
+        return 4
+      })
+    },
+    function (cb) {
+      setTimeout(function() {
+        console.log(3)
+        cb(null, 3)
+      }, 0)
+    },
+    function () {
+      console.log(5)
+      return 5
+    },
+  ],
+  function (cb) {
+    console.log(2)
+    cb(null, 2)
   }
-)(1, 2)
+)
 .then(function (res) {
-  // [7]
+  // 1
+  // 5
+  // 4
+  // 3
+  // 2
+  // [ [ 1  ], [ [ 4  ], [ 3  ], [ 5  ]  ], [ 2  ]  ]
   console.log(res)
 })
 
-
 ```
 
-##### output
-Specify whether to pass the results of the last callback to the final results.
-
-Type: `Boolean`
-
-Default: `true`
-
-##### run
-Specify a runner function to run each callback.
-
-Type: `Function`, `Object`
-
-Default: `null`
-
-If `Function`, it receives a callback followed by a list of arguments,
-and should return a promise to fetch the results (`Array`).
-
-If `Object`, it is passed to
-[`Runner of run-callback`](https://github.com/zoubin/run-callback#runner--runrunner)
-to create a runner function.
 
 ## [Changelog](changelog.md)
 
diff --git a/example/dynamic.js b/example/dynamic.js
@@ -1,4 +1,5 @@
-var run = require('..').run
+var Runner = require('..').Runner
+var runner = Runner()
 
 var count = 5
 var tasks = []
@@ -13,7 +14,7 @@ function task(next) {
     next()
   })
 }
-run(tasks).then(function () {
+runner.sequence(tasks).then(function () {
   // [5, 4, 3, 2, 1]
   console.log(res)
 })

diff --git a/example/parallel.js b/example/parallel.js
@@ -1,7 +1,8 @@
-var parallel = require('..').parallel
+var Runner = require('..').Runner
+var runner = Runner()
 
 var res = []
-parallel([
+runner.parallel([
   function () { res.push(1) },
   [
     function () {
@@ -21,8 +22,7 @@ parallel([
     res.push(2)
     cb()
   },
-]
-)
+])
 .then(function () {
   // [1, 2, 4, 5, 3]
   console.log(res)