add test, documents

Author: zensh

.gitignore

@@ -25,3 +25,5 @@ build/Release
 # Dependency directory
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
 node_modules
+
+debug

.travis.yml

@@ -1,7 +1,5 @@
 language: node_js
 node_js:
-  - "0.10"
-  - "0.12"
   - "4"
   - "5"
 sudo: false

README.md

@@ -1,27 +1,26 @@
 thunk-loop
 ====
-Asynchronous tasks loop.
+Asynchronous tasks loop (while (true) { ... }).
 
 [![NPM version][npm-image]][npm-url]
 [![Build Status][travis-image]][travis-url]
 
 ## [thunks](https://github.com/thunks/thunks)
 
 ## Demo
-
+**Infinite Clock:**
 ```js
 const thunk = require('thunks')()
 const thunkLoop = require('..')
 
-var count = 10
+var i = 0
 thunkLoop(function *() {
   yield thunk.delay(1000)
-  if (!--count) throw new Error('End!')
-  console.log(': ' + count)
-
+  i = ++i % 60
+  console.log(i)
   return true
-})(function (err, res) {
-  console.log(err, res)
+})(function (_) {
+  // will never reach here.
 })
 ```
 
@@ -33,6 +32,82 @@ const thunkLoop = require('thunk-loop')
 
 ### thunkLoop(iter[, errorHandle])
 
+return thunk function. You should run the thunk function because of thunk's lazy evaluation. If iter is infinite, you will not get the last result except error occured.
+
+- `iter`: {Function}, it is your task loop, can be sync or async task. If `iter`'s result is `true`, the loop will continue, otherwise the loop will terminate.
+
+  **Sync function:**
+  ```js
+  var i = 1000
+  thunkLoop(function () {
+    if (--i) return true
+    return 'OK'
+  })(function (err, res) {
+    console.log(err, res, i) // null, 'OK', 0
+  })
+  ```
+
+  **Promise:**
+  ```js
+  var i = 1000
+  thunkLoop(function () {
+    if (--i) return Promise.resolve(true)
+    return Promise.resolve('OK')
+  })(function (err, res) {
+    console.log(err, res, i) // null, 'OK', 0
+  })
+  ```
+
+  **Generator function:**
+  ```js
+  var i = 1000
+  thunkLoop(function *() {
+    // yield thunk or promise
+    if (--i) return yield thunk(true)
+    return yield Promise.resolve('OK')
+  })(function (err, res) {
+    console.log(err, res, i) // null, 'OK', 0
+  })
+  ```
+
+- `errorHandle`: {Function}, it is optional, can be sync or async function. It is used to catch the exception from `iter`.
+
+  If `errorHandle` omit. the exception from `iter` will terminate loop:
+  ```js
+  thunkLoop(function *() {
+    throw new Error('error!')
+  })(function (err, res) {
+    console.log(err.message, ) 'error!'
+  })
+  ```
+
+  If `errorHandle` return `true`. the exception from `iter` will ignore and loop will continue:
+  ```js
+  var i = 1000
+  thunkLoop(function () {
+    if (--i) throw new Error('test')
+    return 'OK'
+  }, function (err) {
+    console.log(err.message) // 'test'
+    return true
+  })(function (err, res) {
+    console.log(err, res, i) // null, 'OK', 0
+  })
+  ```
+
+  If `errorHandle` throw error:
+  ```js
+  var i = 1000
+  thunkLoop(function () {
+    if (--i) throw new Error('test')
+    return 'OK'
+  }, function (err) {
+    console.log(err.message) // 'test'
+    throw new Error('errorHandle error')
+  })(function (err, res) {
+    console.log(err.message, i) // 'errorHandle error', 999
+  })
+  ```
 
 [npm-url]: https://npmjs.org/package/thunk-loop
 [npm-image]: http://img.shields.io/npm/v/thunk-loop.svg

examples/clock.js

@@ -0,0 +1,13 @@
+'use strict'
+const thunk = require('thunks')()
+const thunkLoop = require('..')
+
+var i = 0
+thunkLoop(function *() {
+  yield thunk.delay(1000)
+  i = ++i % 60
+  console.log(i)
+  return true
+})(function (_) {
+  // will never reach here.
+})

examples/errorhandle-loop.js

@@ -0,0 +1,22 @@
+const thunkLoop = require('..')
+
+var i = 1000
+thunkLoop(function () {
+  if (--i) throw new Error('test')
+  return 'OK'
+}, function (err) {
+  console.log(err.message)
+  return true
+})(function (err, res) {
+  console.log(err, res, i) // null, 'OK', 0
+})
+
+// thunkLoop(function () {
+//   if (--i) throw new Error('test')
+//   return 'OK'
+// }, function (err) {
+//   console.log(err.message) // 'test'
+//   throw new Error('errorHandle error')
+// })(function (err, res) {
+//   console.log(err, res, i) // null, 'OK', 0
+// })

examples/generator-loop.js

@@ -0,0 +1,11 @@
+const thunkLoop = require('..')
+const thunk = require('thunks')()
+
+var i = 1000
+thunkLoop(function *() {
+  // yield thunk or promise
+  if (--i) return yield thunk(true)
+  return yield Promise.resolve('OK')
+})(function (err, res) {
+  console.log(err, res, i) // null, 'OK', 0
+})

examples/promise-loop.js

@@ -0,0 +1,9 @@
+const thunkLoop = require('..')
+
+var i = 1000
+thunkLoop(function () {
+  if (--i) return Promise.resolve(true)
+  return Promise.resolve('OK')
+})(function (err, res) {
+  console.log(err, res, i) // null, 'OK', 0
+})

examples/sync-loop.js

@@ -0,0 +1,9 @@
+const thunkLoop = require('..')
+
+var i = 1000
+thunkLoop(function () {
+  if (--i) return true
+  return 'OK'
+})(function (err, res) {
+  console.log(err, res, i) // null, 'OK', 0
+})

index.js

@@ -11,10 +11,15 @@ module.exports = thunkLoop.loop = thunkLoop
 
 function thunkLoop (iter, errorHandle) {
   errorHandle = errorHandle || nOop
-  let handle = (err, res) => err == null ? res : thunk(errorHandle(err))
+
   return thunk(function *() {
     while (true) {
-      let res = yield thunk(iter())(handle)
+      let res = null
+      try {
+        res = yield iter()
+      } catch (e) {
+        res = yield errorHandle(e)
+      }
       if (res !== true) return res
     }
   })

package.json

@@ -1,7 +1,7 @@
 {
   "name": "thunk-loop",
-  "version": "0.1.0",
-  "description": "Asynchronous tasks loop.",
+  "version": "1.0.0",
+  "description": "Asynchronous tasks loop (while (true) { ... }).",
   "authors": [
     "Yan Qing <admin@zensh.com>"
   ],
@@ -19,6 +19,9 @@
     "thunk",
     "task"
   ],
+  "engines": {
+    "node": ">= 4.0"
+  },
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/thunks/thunk-loop/issues"