# [](#butterfly)
[![Build Status][]](https://travis-ci.org/fluture-js/Fluture)
[![Code Coverage][]](https://codecov.io/gh/fluture-js/Fluture/branch/master)
[![Dependency Status][]](https://david-dm.org/fluture-js/Fluture)
[![NPM Package][]](https://www.npmjs.com/package/fluture)
[![Gitter Chat][]](https://gitter.im/fluture-js/Fluture)
[![Questions and Answers][]](https://stackoverflow.com/questions/tagged/fluture)
[Build Status]: https://img.shields.io/travis/fluture-js/Fluture/master.svg
[Code Coverage]: https://img.shields.io/codecov/c/github/fluture-js/Fluture/master.svg
[Dependency Status]: https://img.shields.io/david/fluture-js/Fluture.svg
[NPM Package]: https://img.shields.io/npm/v/fluture.svg
[Gitter Chat]: https://img.shields.io/gitter/room/fluture-js/Fluture.svg?colorB=blue
[Questions and Answers]: https://img.shields.io/stackexchange/stackoverflow/t/fluture.svg?label=questions&colorB=blue
Fluture offers a control structure similar to Promises, Tasks, Deferreds, and
what-have-you. Let's call them Futures.
Much like Promises, Futures represent the value arising from the success or
failure of an asynchronous operation (I/O). Though unlike Promises, Futures are
*lazy* and adhere to [the *monadic* interface](#interoperability).
Some of the features provided by Fluture include:
* [Cancellation](#cancellation).
* [Resource management utilities](#resource-management).
* [Stack safe composition and recursion](#stack-safety).
* [Integration](#sanctuary) with [Sanctuary][S].
* [A pleasant debugging experience](#debugging).
For more information:
* [API documentation](#documentation)
* [Wiki: Compare Futures to Promises][wiki:promises]
* [Article: Why Promises shouldn't be used][10]
* [Wiki: Compare Fluture to similar libraries][wiki:similar]
* [Video: Monad a Day - Futures by @DrBoolean][5]
## Usage
> `npm install --save fluture`
On older environments you may need to polyfill one or more of the following
functions: [`Object.create`][JS:Object.create],
[`Object.assign`][JS:Object.assign] and [`Array.isArray`][JS:Array.isArray].
### EcmaScript Module
Fluture is written as modular JavaScript (`.mjs`). It can be loaded directly
by Node 9 and up using `--experimental-modules`, with the [esm loader][esm], or
with TypeScript (typings included).
Besides the module system, no other ES5+ features are used in Fluture's source,
which means that no transpilation is needed after concatenation.
```js
import {readFile} from 'fs';
import {node, encase} from 'fluture';
var getPackageName = file =>
node(done => { readFile(file, 'utf8', done) })
.chain(encase(JSON.parse))
.map(x => x.name);
getPackageName('package.json')
.fork(console.error, console.log);
//> "fluture"
```
### CommonJS Module
Although the Fluture source uses the EcmaScript module system, versions
downloaded from the npm registry include a CommonJS build, which will
automatically be used when loading Fluture with `require`.
```js
var fs = require('fs');
var Future = require('fluture');
var getPackageName = function(file){
return Future.node(function(done){ fs.readFile(file, 'utf8', done) })
.chain(Future.encase(JSON.parse))
.map(function(x){ return x.name });
};
getPackageName('package.json')
.fork(console.error, console.log);
//> "fluture"
```
### Global Bundle (CDN)
Fluture is hosted in full with all of its dependencies at
https://cdn.jsdelivr.net/gh/fluture-js/Fluture@11.0.1/dist/bundle.js
This script will add `Fluture` to the global scope.
## Interoperability
[
][FL]
[
][6]
* `Future` implements [Fantasy Land][FL] and [Static Land][6] -compatible
`Alt`, `Bifunctor`, `Monad`, and `ChainRec`
(`of`, `ap`, `alt`, `map`, `bimap`, `chain`, `chainRec`).
All versions of Fantasy Land are supported.
* `Future.Par` implements [Fantasy Land 3][FL] and [Static Land][6] -compatible
`Alternative` (`of`, `zero`, `map`, `ap`, `alt`).
* The Future and ConcurrentFuture representatives contain `@@type` properties
for [Sanctuary Type Identifiers][STI].
* The Future and ConcurrentFuture instances contain `@@show` properties for
[Sanctuary Show][SS].
## Butterfly
The name "Fluture" is a conjunction of "FL" (the acronym to [Fantasy Land][FL])
and "future". Fluture means butterfly in Romanian: A creature one might expect
to see in Fantasy Land.
Credit goes to Erik Fuente for styling the logo, and [WEAREREASONABLEPEOPLE][9]
for sponsoring the project.
## Documentation
### Table of contents
General
- [How to read the type signatures](#type-signatures)
- [How cancellation works](#cancellation)
- [On stack safety](#stack-safety)
- [Debugging with Fluture](#debugging)
- [Usage with Sanctuary](#sanctuary)
- [Using multiple versions of Fluture](#casting-futures)
Creating new Futures
- [`Future`: Create a possibly cancellable Future](#future)
- [`of`: Create a resolved Future](#of)
- [`reject`: Create a rejected Future](#reject)
- [`after`: Create a Future that resolves after a timeout](#after)
- [`rejectAfter`: Create a Future that rejects after a timeout](#rejectafter)
- [`do`: Create a "coroutine" using a generator function](#do)
- [`try`: Create a Future using a possibly throwing function](#try)
- [`tryP`: Create a Future using a Promise-returning function](#tryp)
- [`node`: Create a Future using a Node-style callback](#node)
- [`encase`: Convert a possibly throwing function to a Future function](#encase)
- [`encaseP`: Convert a Promise-returning function to a Future function](#encasep)
- [`encaseN`: Convert a Nodeback function to a Future function](#encasen)
Converting between Nodeback APIs and Futures
- [`node`: Create a Future using a Node-style callback](#node)
- [`encaseN`: Convert a Nodeback function to a Future function](#encasen)
- [`done`: Consume a Future by providing a Nodeback](#done)
Converting between Promises and Futures
- [`tryP`: Create a Future using a Promise-returning function](#tryp)
- [`encaseP`: Convert a Promise-returning function to a Future function](#encasep)
- [`promise`: Convert a Future to a Promise](#promise)
Transforming and combining Futures
- [`pipe`: Apply a function to a Future in a fluent method chain](#pipe)
- [`map`: Synchronously process the success value in a Future](#map)
- [`bimap`: Synchronously process the success or failure value in a Future](#bimap)
- [`chain`: Asynchronously process the success value in a Future](#chain)
- [`swap`: Swap the success with the failure value](#swap)
- [`mapRej`: Synchronously process the failure value in a Future](#maprej)
- [`chainRej`: Asynchronously process the failure value in a Future](#chainrej)
- [`fold`: Coerce success and failure values into the same success value](#fold)
- [`ap`: Combine the success values of multiple Futures using a function](#ap)
- [`and`: Logical *and* for Futures](#and)
- [`alt`: Logical *or* for Futures](#alt)
- [`finally`: Run a Future after the previous settles](#finally)
- [`race`: Race two Futures against each other](#race)
- [`both`: Await both success values from two Futures](#both)
- [`parallel`: Await all success values from many Futures](#parallel)
Consuming/forking Futures
- [`fork`: Standard way to run a Future and get at its result](#fork)
- [`forkCatch`: Fork with exception recovery](#forkcatch)
- [`value`: Shorter variant of `fork` for Futures sure to succeed](#value)
- [`done`: Nodeback style `fork`](#done)
- [`promise`: Convert a Future to a Promise](#promise)
Concurrency related utilities and data structures
- [`race`: Race two Futures against each other](#race)
- [`both`: Await both success values from two Futures](#both)
- [`parallel`: Await all success values from many Futures](#parallel)
- [`ConcurrentFuture`: A separate data-type for doing algebraic concurrency](#concurrentfuture)
- [`alt`: Behaves like `race` on `ConcurrentFuture` instances](#alt)
Resource management
- [`hook`: Safely create and dispose resources](#hook)
- [`finally`: Run a Future after the previous settles](#finally)
Other utilities
- [`pipe`: Apply a function to a Future in a fluent method chain](#pipe)
- [`cache`: Cache a Future so that it can be forked multiple times](#cache)
- [`isFuture`: Determine whether a value is a Fluture compatible Future](#isfuture)
- [`never`: A Future that never settles](#never)
- [`debugMode`: Configure Fluture's debug mode](#debugmode)
- [`context`: The debugging context of a Future instance](#context)
Future :: ((a -> Undefined, b -> Undefined) -> Cancel) -> Future a b
```hs
Future :: ((a -> Undefined, b -> Undefined) -> Cancel) -> Future a b
```
of :: b -> Future a b
```hs
of :: b -> Future a b
resolve :: b -> Future a b
Future.of :: b -> Future a b
Future.resolve :: b -> Future a b
```
reject :: a -> Future a b
```hs
reject :: a -> Future a b
Future.reject :: a -> Future a b
```
after :: Number -> b -> Future a b
```hs
after :: Number -> b -> Future a b
```
rejectAfter :: Number -> a -> Future a b
```hs
rejectAfter :: Number -> a -> Future a b
```
do :: (() -> Iterator) -> Future a b
```hs
do :: (() -> Iterator) -> Future a b
go :: (() -> Iterator) -> Future a b
```
try :: Catchable e (() -> r) -> Future e r
```hs
try :: Catchable e (() -> r) -> Future e r
attempt :: Catchable e (() -> r) -> Future e r
```
tryP :: (() -> Promise e r) -> Future e r
```hs
tryP :: (() -> Promise e r) -> Future e r
```
node :: (Nodeback e r -> x) -> Future e r
```hs
node :: (Nodeback e r -> x) -> Future e r
```
encase :: (Catchable e (a -> r)) -> a -> Future e r
```hs
encase :: (Catchable e ((a ) -> r)) -> a -> Future e r
encase2 :: (Catchable e ((a, b ) -> r)) -> a -> b -> Future e r
encase3 :: (Catchable e ((a, b, c) -> r)) -> a -> b -> c -> Future e r
```
encaseP :: ((a) -> Promise e r) -> a -> Future e r
```hs
encaseP :: ((a) -> Promise e r) -> a -> Future e r
encaseP2 :: ((a, b) -> Promise e r) -> a -> b -> Future e r
encaseP3 :: ((a, b, c) -> Promise e r) -> a -> b -> c -> Future e r
```
encaseN :: ((a, Nodeback e r) -> x) -> a -> Future e r
```hs
encaseN :: ((a, Nodeback e r) -> x) -> a -> Future e r
encaseN2 :: ((a, b, Nodeback e r) -> x) -> a -> b -> Future e r
encaseN3 :: ((a, b, c, Nodeback e r) -> x) -> a -> b -> c -> Future e r
```
Future.chainRec :: ((a -> Next a, b -> Done b, a) -> Future e (Next a | Done b), a) -> Future e b
```hs
Future.chainRec :: ((a -> Next a, b -> Done b, a) -> Future e (Next a | Done b), a) -> Future e b
```
map :: Functor m => (a -> b) -> m a -> m b
```hs
map :: Functor m => (a -> b) -> m a -> m b
Future.map :: Functor m => (a -> b) -> m a -> m b
Par.map :: Functor m => (a -> b) -> m a -> m b
Future.prototype.map :: Future e a ~> (a -> b) -> Future e b
```
bimap :: Bifunctor m => (a -> c) -> (b -> d) -> m a b -> m c d
```hs
bimap :: Bifunctor m => (a -> c) -> (b -> d) -> m a b -> m c d
Future.bimap :: Bifunctor m => (a -> c) -> (b -> d) -> m a b -> m c d
Future.prototype.bimap :: Future a b ~> (a -> c, b -> d) -> Future c d
```
chain :: Chain m => (a -> m b) -> m a -> m b
```hs
chain :: Chain m => (a -> m b) -> m a -> m b
Future.chain :: Chain m => (a -> m b) -> m a -> m b
Future.prototype.chain :: Future e a ~> (a -> Future e b) -> Future e b
```
swap :: Future a b -> Future b a
```hs
swap :: Future a b -> Future b a
Future.prototype.swap :: Future a b ~> Future b a
```
mapRej :: (a -> c) -> Future a b -> Future c b
```hs
mapRej :: (a -> c) -> Future a b -> Future c b
Future.prototype.mapRej :: Future a b ~> (a -> c) -> Future c b
```
chainRej :: (a -> Future c b) -> Future a b -> Future c b
```hs
chainRej :: (a -> Future c b) -> Future a b -> Future c b
Future.prototype.chainRej :: Future a b ~> (a -> Future c b) -> Future c b
```
fold :: (a -> c) -> (b -> c) -> Future a b -> Future d c
```hs
fold :: (a -> c) -> (b -> c) -> Future a b -> Future d c
Future.prototype.fold :: Future a b ~> (a -> c, b -> c) -> Future d c
```
ap :: Apply m => m (a -> b) -> m a -> m b
```hs
ap :: Apply m => m (a -> b) -> m a -> m b
Future.ap :: Apply m => m (a -> b) -> m a -> m b
Par.ap :: Apply m => m (a -> b) -> m a -> m b
Future.prototype.ap :: Future e (a -> b) ~> Future e a -> Future e b
```
and :: Future a b -> Future a c -> Future a c
```hs
and :: Future a b -> Future a c -> Future a c
Future.prototype.and :: Future a b ~> Future a c -> Future a c
```
alt :: Alt f => f a -> f a -> f a
```hs
alt :: Alt f => f a -> f a -> f a
or :: Alt f => f a -> f a -> f a
Future.alt :: Alt f => f a -> f a -> f a
Par.alt :: Alt f => f a -> f a -> f a
Future.prototype.alt :: Future a b ~> Future a b -> Future a b
Future.prototype.or :: Future a b ~> Future a b -> Future a b
```
finally :: Future a c -> Future a b -> Future a b
```hs
finally :: Future a c -> Future a b -> Future a b
lastly :: Future a c -> Future a b -> Future a b
Future.prototype.finally :: Future a b ~> Future a c -> Future a b
Future.prototype.lastly :: Future a b ~> Future a c -> Future a b
```
fork :: (a -> Any) -> (b -> Any) -> Future a b -> Cancel
```hs
fork :: (a -> Any) -> (b -> Any) -> Future a b -> Cancel
Future.prototype.fork :: Future a b ~> (a -> Any, b -> Any) -> Cancel
```
forkCatch :: (Error -> Any) -> (a -> Any) -> (b -> Any) -> Future a b -> Cancel
```hs
forkCatch :: (Error -> Any) -> (a -> Any) -> (b -> Any) -> Future a b -> Cancel
Future.prototype.forkCatch :: Future a b ~> (Error -> Any, a -> Any, b -> Any) -> Cancel
```
value :: (b -> x) -> Future a b -> Cancel
```hs
value :: (b -> x) -> Future a b -> Cancel
Future.prototype.value :: Future a b ~> (b -> x) -> Cancel
```
done :: Nodeback a b -> Future a b -> Cancel
```hs
done :: Nodeback a b -> Future a b -> Cancel
Future.prototype.done :: Future a b ~> Nodeback a b -> Cancel
```
promise :: Future a b -> Promise b a
```hs
promise :: Future a b -> Promise b a
Future.prototype.promise :: Future a b ~> Promise b a
```
race :: Future a b -> Future a b -> Future a b
```hs
race :: Future a b -> Future a b -> Future a b
Future.prototype.race :: Future a b ~> Future a b -> Future a b
```
both :: Future a b -> Future a c -> Future a (Pair b c)
```hs
both :: Future a b -> Future a c -> Future a (Pair b c)
Future.prototype.both :: Future a b ~> Future a c -> Future a (Pair b c)
```
parallel :: PositiveInteger -> Array (Future a b) -> Future a (Array b)
```hs
parallel :: PositiveInteger -> Array (Future a b) -> Future a (Array b)
```
Par :: Future a b -> ConcurrentFuture a b
```hs
Par :: Future a b -> ConcurrentFuture a b
```
Par.of :: b -> ConcurrentFuture a b
```hs
Par.of :: b -> ConcurrentFuture a b
```
Par.zero :: () -> ConcurrentFuture a a
```hs
Par.zero :: () -> ConcurrentFuture a a
```
seq :: ConcurrentFuture a b -> Future a b
```hs
seq :: ConcurrentFuture a b -> Future a b
```
hook :: Future a b -> (b -> Future c d) -> (b -> Future a e) -> Future a e
```hs
hook :: Future a b -> (b -> Future c d) -> (b -> Future a e) -> Future a e
```
pipe :: Future a b ~> (Future a b -> c) -> c
```hs
Future.prototype.pipe :: Future a b ~> (Future a b -> c) -> c
```
cache :: Future a b -> Future a b
```hs
cache :: Future a b -> Future a b
```
isFuture :: a -> Boolean
```hs
isFuture :: a -> Boolean
```
never :: Future a a
```hs
never :: Future a a
```
isNever :: a -> Boolean
```hs
isNever :: a -> Boolean
```
extractLeft :: Future a b -> Array a
```hs
extractLeft :: Future a b -> Array a
Future.prototype.extractLeft :: Future a b ~> () -> Array a
```
extractRight :: Future a b -> Array b
```hs
extractRight :: Future a b -> Array b
Future.prototype.extractRight :: Future a b ~> () -> Array b
```
debugMode :: Boolean -> Undefined
```hs
debugMode :: Boolean -> Undefined
```