hybridables/always-done

View on GitHub
.verb.md

Summary

Maintainability
Test Coverage
<p align="center">
  <a href="https://github.com/hybridables">
    <img height="250" width="250" src="https://avatars1.githubusercontent.com/u/10666022?v=3&s=250">
  </a>
</p>

# [{%= name %}][author-www-url] [![npmjs.com][npmjs-img]][npmjs-url] [![The MIT License][license-img]][license-url] [![npm downloads][downloads-img]][downloads-url] 

> {%= description %}

[![code climate][codeclimate-img]][codeclimate-url] [![standard code style][standard-img]][standard-url] [![travis build status][travis-img]][travis-url] [![coverage status][coveralls-img]][coveralls-url] [![dependency status][david-img]][david-url]

## Table of Contents
<!-- toc -->

## Install
> Install with [npm](https://www.npmjs.com/)

```sh
$ npm i {%= name %} --save
```

## Usage
> For more use-cases see the [tests](./test.js)

```js
const fs = require('fs')
const {%= varname %} = require('{%= name %}')

{%= varname %}((cb) => {
  fs.readFile('./package.json', 'utf8', cb)
}, (err, res) => {
  if (err) return console.error(err)

  let json = JSON.parse(res)
  console.log(json.name) // => '{%= name %}'
})
```


## Background

Behind the scenes we use just good plain old `try/catch` block. Sounds you strange? See what "hard" job is done on [try-catch-callback][] and [try-catch-core][].

In the first one, we just calls a function inside try/catch and calls `done` callback with error or result of that function.

About second one, there we wraps the `done` callback with [once][] and [dezalgo][] to ensure it will be called in the next tick.

Here, in `always-done`, we just give a `callback` to that [try-catch-core][] package and "listen" what is the result. Actually we not listening anything, we just make a few checks to understand what the incoming value is - promise, child process, stream, observable and etc.

## Resolution

Nothing so magical. Try/catch block for most of the things works briliant. And [on-stream-end][] module (which is drop-in replacement for [end-of-stream][]) for streams and child processes.

**[back to top](#readme)**

## API
{%= apidocs('index.js') %}

**[back to top](#readme)**

## Supports
> Handles completion and errors of async/await, synchronous and asynchronous (callback) functions, also functions that returns streams, promises, child process and observables.

### Handles `async/await` completion

```js
alwaysDone(async function () {
  return await Promise.resolve('foobar')
}, function done (e, res) {
  console.log(res) // => 'foobar'
})
```

**[back to top](#readme)**

### Callbacks completion

```js
var alwaysDone = require('always-done')

alwaysDone(function (cb) {
  fs.readFile('./package.json', 'utf8', cb)
}, function done (err, res) {
  if (err) return console.log(err)
 
  var pkg = JSON.parse(res)
  console.log(pkg.name) // => 'always-done'
})
```

**[back to top](#readme)**

### Completion of synchronous functions

#### Returning a value

```js
alwaysDone(function () {
  return 123
}, function done (e, res) {
  console.log(res) // => 123
})
```

#### Returning an error

```js
alwaysDone(function () {
  return new Error('qux bar')
}, function done (err) {
  console.log(err.message) // => 'qux bar'
})
```

**[back to top](#readme)**

### Completion of Promises

#### Returning a resolved Promise

```js
alwaysDone(function () {
  return Promise.resolve(12345)
}, function done (e, res) {
  console.log(res) // => 12345
})
```

#### Returning a rejected Promise

```js
alwaysDone(function () {
  return Promise.reject(new Error('foo bar'))
}, function done (err) {
  console.log(err.message) // => 'foo bar
})
```

**[back to top](#readme)**

### Streams completion
> Using [on-stream-end][] and [stream-exhaust][]

#### Unpiped streams

```js
alwaysDone(function () {
  return fs.createReadStream('./package.json')
}, function done (e) {
  console.log('stream completed')
})
```

#### Failing unpiped streams

```js
alwaysDone(function () {
  return fs.createReadStream('foo bar')
}, function done (err) {
  console.log(err.code) // => ENOENT
  console.log(err.message) // => No such file or directory
})
```

#### Failing piped streams

```js
alwaysDone(function () {
  var read = fs.createReadStream('foo bar')
  return read.pipe(through2())
}, function done (err) {
  console.log(err.code) // => ENOENT
  console.log(err.message) // => No such file or directory
})
```

**[back to top](#readme)**

### Handles completion of Observables
> Using `.subscribe` method of the observable

#### Empty observable
```js
var Observable = require('rx').Observable

alwaysDone(function () {
  return Observable.empty()
}, function done (e, res) {
  console.log(e, res) // => null, undefined
})
```

#### Successful observable

```js
alwaysDone(function () {
  return Observable.return([1, 2, 3])
}, function done (e, res) {
  console.log(res) // => [1, 2, 3]
})
```

#### Failing observable

```js
alwaysDone(function () {
  return Observable.throw(new Error('observable error'))
}, function done (err) {
  console.log(err.message) // => 'observable error'
})
```

**[back to top](#readme)**

### Completion of Child Process
> Basically, they are streams, so completion is handled using [on-stream-end][] which is drop-in replacement for [end-of-stream][]

#### Successful exec

```js
var cp = require('child_process')

alwaysDone(function () {
  return cp.exec('echo hello world')
}, function done (e, res) {
  console.log(res) // => 'hello world'
})
```

#### Failing exec

```js
var cp = require('child_process')

alwaysDone(function () {
  return cp.exec('foo-bar-baz sasa')
}, function done (err) {
  console.log(err.message) // => 'exited with error code: 12'
})
```

#### Failing spawn

```js
var cp = require('child_process')

alwaysDone(function () {
  return cp.spawn('foo-bar-baz', ['hello world'])
}, function done (err) {
  console.log(err.code) // => ENOENT
})
```

**[back to top](#readme)**

### Handling errors

#### uncaught exceptions

```js
alwaysDone(function () {
  foo // ReferenceError
  return 55
}, function (err) {
  console.log(err.name)
  // => ReferenceError: foo is not defined
})
```

#### thrown errors

```js
alwaysDone(function () {
  JSON.parse('{"foo":')
}, function (err) {
  console.log(err)
  // => SyntaxError: Unexpected end of JSON input
})
```

**[back to top](#readme)**

### Always completes
> It may looks strange, but it's logical. If you pass empty function it just completes with `undefined` result and `null` error.

**Example**

```js
// passing empty function
alwaysDone(function () {}, function (err, res) {
  console.log(err, res) // => null, undefined
})
```

**[back to top](#readme)**

### Passing custom context

```js
var {%= varname %} = require('{%= name %}')
var opts = {
  context: { foo: 'bar' }
}

{%= varname %}(function () {
  console.log(this.foo) // => 'bar'
}, opts, function done () {
  console.log('end')
})
```

**[back to top](#readme)**

### Passing custom arguments
> It may be strange, but this allows you to pass more arguments to that first function and the last argument always will be "callback" until `fn` is async or sync but with `passCallback: true` option.

```js
var {%= varname %} = require('{%= name %}')
var options = {
  args: [1, 2]
}

{%= varname %}(function (a, b) {
  console.log(arguments.length) // => 2
  console.log(a) // => 1
  console.log(b) // => 2

  return a + b + 3
}, options, function done (e, res) {
  console.log(res) // => 9
})
```

**[back to top](#readme)**

### Returning a thunk
> Can be used as _thunkify_ lib without problems, just don't pass a done callback.

```js
var fs = require('fs')
var {%= varname %} = require('{%= name %}')
var readFileThunk = {%= varname %}(function (cb) {
  fs.readFile('./package.json', cb)
})

readFileThunk(function done (err, res) {
  console.log(err, res) // => null, Buffer
})
```

**[back to top](#readme)**
{% if (verb.related && verb.related.list && verb.related.list.length) { %}
## Related
{%= related(verb.related.list, {words: 12}) %}
{% } %}

## Contributing
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/{%= repository %}/issues/new).  
But before doing anything, please read the [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines.

## [Charlike Make Reagent](http://j.mp/1stW47C) [![new message to charlike][new-message-img]][new-message-url] [![freenode #charlike][freenode-img]][freenode-url]

[![{%= author.username %}.tk][author-www-img]][author-www-url] [![keybase {%= author.username %}][keybase-img]][keybase-url] [![{%= author.username %} npm][author-npm-img]][author-npm-url] [![{%= author.username %} twitter][author-twitter-img]][author-twitter-url] [![{%= author.username %} github][author-github-img]][author-github-url]

{%= reflinks(verb.reflinks) %}

[npmjs-url]: https://www.npmjs.com/package/{%= name %}
[npmjs-img]: https://img.shields.io/npm/v/{%= name %}.svg?label={%= name %}

[license-url]: https://github.com/{%= repository %}/blob/master/LICENSE
[license-img]: https://img.shields.io/npm/l/{%= name %}.svg

[downloads-url]: https://www.npmjs.com/package/{%= name %}
[downloads-img]: https://img.shields.io/npm/dm/{%= name %}.svg


[codeclimate-url]: https://codeclimate.com/github/{%= repository %}
[codeclimate-img]: https://img.shields.io/codeclimate/github/{%= repository %}.svg

[travis-url]: https://travis-ci.org/{%= repository %}
[travis-img]: https://img.shields.io/travis/{%= repository %}/master.svg

[coveralls-url]: https://coveralls.io/r/{%= repository %}
[coveralls-img]: https://img.shields.io/coveralls/{%= repository %}.svg

[david-url]: https://david-dm.org/{%= repository %}
[david-img]: https://img.shields.io/david/{%= repository %}.svg

[standard-url]: https://github.com/feross/standard
[standard-img]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg


[author-www-url]: http://www.{%= author.username.toLowerCase() %}.tk
[author-www-img]: https://img.shields.io/badge/www-{%= author.username.toLowerCase() %}.tk-fe7d37.svg

[keybase-url]: https://keybase.io/{%= author.username.toLowerCase() %}
[keybase-img]: https://img.shields.io/badge/keybase-{%= author.username.toLowerCase() %}-8a7967.svg

[author-npm-url]: https://www.npmjs.com/~{%= author.username.toLowerCase() %}
[author-npm-img]: https://img.shields.io/badge/npm-~{%= author.username.toLowerCase() %}-cb3837.svg

[author-twitter-url]: https://twitter.com/{%= author.username %}
[author-twitter-img]: https://img.shields.io/badge/twitter-@{%= author.username %}-55acee.svg

[author-github-url]: https://github.com/{%= author.username %}
[author-github-img]: https://img.shields.io/badge/github-@{%= author.username %}-4183c4.svg

[freenode-url]: http://webchat.freenode.net/?channels=charlike
[freenode-img]: https://img.shields.io/badge/freenode-%23charlike-5654a4.svg

[new-message-url]: https://github.com/{%= author.username %}/ama
[new-message-img]: https://img.shields.io/badge/ask%20me-anything-green.svg