<commit_before># Fluture

[![NPM Version](https://badge.fury.io/js/fluture.svg)](https://www.npmjs.com/package/fluture)
[![Dependencies](https://david-dm.org/avaq/fluture.svg)](https://david-dm.org/avaq/fluture)
[![Build Status](https://travis-ci.org/Avaq/Fluture.svg?branch=master)](https://travis-ci.org/Avaq/Fluture)
[![Code Coverage](https://codecov.io/github/Avaq/Fluture/coverage.svg?branch=develop)](https://codecov.io/github/Avaq/Fluture/fluture.js?branch=develop)
[![Code Quality](https://www.bithound.io/github/Avaq/Fluture/badges/score.svg)](https://www.bithound.io/github/Avaq/Fluture)

A complete [Fantasy Land][1] compatible Future library.

> `npm install --save fluture` <sup>Requires a node 5.0.0 compatible environment
  like modern browsers, transpilers or Node 5+</sup>


## Usage

Using the low level, high performance [method API](#method-api):

```js
const Future = require('fluture');
const program = file =>
  Future.node(done => fs.readFile(file, 'utf8', done))
  .chain(Future.encase(JSON.parse))
  .map(x => x.name)
  .fork(console.error, console.log);
program('package.json');
//> "fluture"
```

Or use the high level, fully curried, [functional dispatch API](#dispatcher-api)
for function composition using composers like [`S.pipe`][2]:

```js
const {node, chain, encase, map, fork} = require('fluture');
const program = S.pipe([
  file => node(fs.readFile.bind(fs, file, 'utf8')),
  chain(encase(JSON.parse)),
  map(x => x.name),
  fork(console.error, console.log)
]);
program('package.json')
//> "fluture"
```

## Motivation

I've always liked Promises, and I've come to like Futures even more. Existing
implementations are a pain to debug though. I made this library in an effort to
provide **great error messages** when something goes wrong. I didn't want these
to come at the cost of performance though, so I made sure Fluture operates at
**high performance**. Throughout my work with Future's, I've created a lot of
**async control utilities** which I've decided to bundle with this library.

## Documentation

### Type signatures

I'm using [Hindley-Milner][9] type signatures to document functions. A list of
all types I'll use within these signatures follows:

- **Forkable** - Any Object with a `fork` method that takes at least two
  arguments. This includes instances of Fluture, instances of Task from
  [`data.task`][10] or instances of Future from [`ramda-fantasy`][11].
- **Future** - Instances of Future provided by Fluture.
- **Functor** - Any object that has a `map` method which satisfies the
  [Fantasy Land Functor specification][12].
- **Chain** - Any object that has a `chain` method which satisfies the
  [Fantasy Land Chain specification][13].
- **Apply** - Any object that has an `ap` method which satisfies the
  [Fantasy Land Apply specification][14].

### Constructors

#### `Future :: ((a -> Void), (b -> Void) -> Void) -> Future a b`<commit_msg>Stop referring to "I" in the documentation<commit_after># Fluture

[![NPM Version](https://badge.fury.io/js/fluture.svg)](https://www.npmjs.com/package/fluture)
[![Dependencies](https://david-dm.org/avaq/fluture.svg)](https://david-dm.org/avaq/fluture)
[![Build Status](https://travis-ci.org/Avaq/Fluture.svg?branch=master)](https://travis-ci.org/Avaq/Fluture)
[![Code Coverage](https://codecov.io/github/Avaq/Fluture/coverage.svg?branch=develop)](https://codecov.io/github/Avaq/Fluture/fluture.js?branch=develop)
[![Code Quality](https://www.bithound.io/github/Avaq/Fluture/badges/score.svg)](https://www.bithound.io/github/Avaq/Fluture)

A complete [Fantasy Land][1] compatible Future library.

> `npm install --save fluture` <sup>Requires a node 5.0.0 compatible environment
  like modern browsers, transpilers or Node 5+</sup>


## Usage

Using the low level, high performance [method API](#method-api):

```js
const Future = require('fluture');
const program = file =>
  Future.node(done => fs.readFile(file, 'utf8', done))
  .chain(Future.encase(JSON.parse))
  .map(x => x.name)
  .fork(console.error, console.log);
program('package.json');
//> "fluture"
```

Or use the high level, fully curried, [functional dispatch API](#dispatcher-api)
for function composition using composers like [`S.pipe`][2]:

```js
const {node, chain, encase, map, fork} = require('fluture');
const program = S.pipe([
  file => node(fs.readFile.bind(fs, file, 'utf8')),
  chain(encase(JSON.parse)),
  map(x => x.name),
  fork(console.error, console.log)
]);
program('package.json')
//> "fluture"
```

## Motivation

Existing implementations of Future are a pain to debug. This library was made in
an effort to provide **great error messages** when something goes wrong. The
library also comes bundled with many **async control utilities**. To prevent
these features from coming at the cost of performance, Fluture was optimized to
operate at **high performance**.

## Documentation

### Type signatures

[Hindley-Milner][9] type signatures are used to document functions. A list of
all types used within these signatures follows:

- **Forkable** - Any Object with a `fork` method that takes at least two
  arguments. This includes instances of Fluture, instances of Task from
  [`data.task`][10] or instances of Future from [`ramda-fantasy`][11].
- **Future** - Instances of Future provided by Fluture.
- **Functor** - Any object that has a `map` method which satisfies the
  [Fantasy Land Functor specification][12].
- **Chain** - Any object that has a `chain` method which satisfies the
  [Fantasy Land Chain specification][13].
- **Apply** - Any object that has an `ap` method which satisfies the
  [Fantasy Land Apply specification][14].

### Constructors

#### `Future :: ((a -> Void), (b -> Void) -> Void) -> Future a b`
{'fraction_non_alphanumeric': 0.15377886634009796, 'fraction_numerical': 0.006648005598320504, 'mean_word_length': 4.75730110775428, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 31, 'https://': 20, 'lorem ipsum': 0, 'www.': 6, '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': '2781122', 'n_tokens_mistral': 1884, 'n_tokens_neox': 1793, 'n_words': 566}