<commit_before>[![NPM][npm-image]][npm-url]
[![Build Status][travis-image]][travis-url]
[![Coverage Status][coveralls-image]][coveralls-url]
[![Dependency Status][dependency-image]][dependency-url]
[![devDependency Status][devDependency-image]][devDependency-url]
[![gratipay][gratipay-image]][gratipay-url]

# Attempt

abstract asynchronous tasks

## License

Copyright (c) 2015 [<NAME>](mailto:<EMAIL>)
Licensed under the [MIT license](https://raw.githubusercontent.com/jaubourg/wires/master/LICENSE-MIT).

[coveralls-image]: https://img.shields.io/coveralls/jaubourg/attempt-js.svg
[coveralls-url]: https://coveralls.io/r/jaubourg/attempt-js
[dependency-image]: https://david-dm.org/jaubourg/attempt-js.svg
[dependency-url]: https://david-dm.org/jaubourg/attempt-js
[devDependency-image]: https://david-dm.org/jaubourg/attempt-js/dev-status.svg
[devDependency-url]: https://david-dm.org/jaubourg/attempt-js#info=devDependencies
[gratipay-image]: https://img.shields.io/gratipay/jaubourg.svg
[gratipay-url]: https://gratipay.com/jaubourg/
[npm-image]: https://img.shields.io/npm/v/attempt-js.svg
[npm-url]: https://npmjs.org/package/attempt-js
[travis-image]: https://travis-ci.org/jaubourg/attempt-js.svg
[travis-url]: https://travis-ci.org/jaubourg/attempt-js<commit_msg>Basic documentation through examples<commit_after>[![NPM][npm-image]][npm-url]
[![Build Status][travis-image]][travis-url]
[![Coverage Status][coveralls-image]][coveralls-url]
[![Dependency Status][dependency-image]][dependency-url]
[![devDependency Status][devDependency-image]][devDependency-url]
[![gratipay][gratipay-image]][gratipay-url]

# Attempt

Utility objects to represent and interact with asynchronous operations.

## Install and use in Node

1. Add the dependency: `npm install attempt-js --save`
2. Import in your code and create new objects:
   ```js
   var Attempt = require( "attempt-js" );

   var myAttempt = new Attempt( /* ... */ );
   ```

## Install and use in the Browser

Use a tool like [Browserify](http://browserify.org/) or [webpack](http://webpack.github.io/).

## Quick overview through code examples
```js
new Attempt( function( notifySuccess, notifyFailure, notifyProgress ) {
    firstAsync( function( error ) {
        notifyProgress( "first done" );
        if ( error ) {
            notifyFailure( error );
        } else {
            secondAsync( function( error, value ) {
                notifyProgress( "second done" );
                if ( error ) {
                    notifyFailure( error );
                } else {
                    notifySuccess( "first done" );
                }
            } );
        }
    } );
} ).progress( function( string ) {
    // the progress string as notified
} ).success( function( value ) {
    // the value from secondAsync if successful
} ).failure( function( error ) {
    // the error otherwise
} ).always( function() {
    // always called (for successes AND failures)
} );
```

### Chain

```js
var attempt = new Attempt( function( notifySuccess ) {
    setTimeout( notifySuccess, 1000, 72 );
} );

attempt.success( function( value ) {
    value === 72;
} );

attempt.chain( function( value ) {
    return value * 2;
} ).success( function( value ) {
    value === 144;
} );

attempt.chain( function( value ) {
    return new Attempt( function( notifySuccess ) {
        setTimeout( notifySuccess, 1000, value * 2 );
    } );
} ).success( function( value ) {
    value === 144;
} );
```

### Join

```js
var helloWorld = new Attempt( function( notifySuccess ) {
    notifySuccess( "hello", "world" );
} );

var sixteen = new Attempt( function( notifySuccess ) {
    notifySuccess( 16 );
} );

Attempt.join( helloWorld, sixteen, true ).success( function( a, b, c ) {
    // a is [ "hello", "world" ]
    // b is 16
    // c is true
} );

var failed = new Attempt( function( _, notifyFailure ) {
    notifyFailure( "woops" );
} );

Attempt.join( helloWorld, failed ).failure( function( error ) {
    error === "woops";
} );
```

### Utilities

```js
var helloWorld = Attempt.success( "hello", "world" );

helloWorld.success( function( a, b ) {
    a === "hello";
    b === "world";
} );

var failed = Attempt.failure( "woops" );

failed.failure( function( arg ) {
    arg === "woops";
} );
````

### Consume Promises

```js
var promise = new Promise( function( resolve ) {
    resolve( "YEAH!" );
} );

new Attempt( promise ).success( function( value ) {
    value === "YEAH!";
} );
```

### Produce Promises

```js
var attempt = new Attempt( function( notifySuccess ) {
    notifySuccess( "YAWP!" );
} );

attempt.promise().then( function( value ) {
    value === "YAWP!";
} );
```

## License

Copyright (c) 2015 [<NAME>](mailto:<EMAIL>)
Licensed under the [MIT license](https://raw.githubusercontent.com/jaubourg/wires/master/LICENSE-MIT).

[coveralls-image]: https://img.shields.io/coveralls/jaubourg/attempt-js.svg
[coveralls-url]: https://coveralls.io/r/jaubourg/attempt-js
[dependency-image]: https://david-dm.org/jaubourg/attempt-js.svg
[dependency-url]: https://david-dm.org/jaubourg/attempt-js
[devDependency-image]: https://david-dm.org/jaubourg/attempt-js/dev-status.svg
[devDependency-url]: https://david-dm.org/jaubourg/attempt-js#info=devDependencies
[gratipay-image]: https://img.shields.io/gratipay/jaubourg.svg
[gratipay-url]: https://gratipay.com/jaubourg/
[npm-image]: https://img.shields.io/npm/v/attempt-js.svg
[npm-url]: https://npmjs.org/package/attempt-js
[travis-image]: https://travis-ci.org/jaubourg/attempt-js.svg
[travis-url]: https://travis-ci.org/jaubourg/attempt-js
{'fraction_non_alphanumeric': 0.17748606365761554, 'fraction_numerical': 0.006114008271893544, 'mean_word_length': 3.6661073825503356, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 26, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1388786', 'n_tokens_mistral': 1983, 'n_tokens_neox': 1838, 'n_words': 376}