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.

Some of the features provided by Fluture include:

• Cancellation.
• Resource management utilities.
• Stack safe composition and recursion.
• Integration with Sanctuary.
• A pleasant debugging experience.

For more information:

• API documentation
• Wiki: Compare Futures to Promises
• Article: Why Promises shouldn't be used
• Wiki: Compare Fluture to similar libraries
• Video: Monad a Day - Futures by @DrBoolean

Usage

npm install --save fluture

On older environments you may need to polyfill one or more of the following functions: Object.create, Object.assign and Array.isArray.

CommonJS Module

Although the Fluture source uses the EcmaScript module system, the main file points to a CommonJS version of Fluture.

const fs = require ('fs')
const Future = require ('fluture')
 
const getPackageName = function (file) {
  return Future.node (function (done) { fs.readFile (file, 'utf8', done) })
  .pipe (Future.chain (Future.encase (JSON.parse)))
  .pipe (Future.map (function (x) { return x.name }))
}
 
getPackageName ('package.json')
.pipe (Future.fork (console.error) (console.log))

EcmaScript Module

Fluture is written as modular JavaScript. It can be loaded directly by Node 12 and up using --experimental-modules, or with the esm loader. Note that the ESM code lives at fluture/index.js, which is not the main file and must be imported explicitly.

Besides the module system, no other ES5+ features are used in Fluture's source, which means that no transpilation is needed after concatenation.

import {readFile} from 'fs'
import {node, encase, chain, map, fork} from 'fluture/index.js'
 
const getPackageName = file => (
  node (done => { readFile (file, 'utf8', done) })
  .pipe (chain (encase (JSON.parse)))
  .pipe (map (x => x.name))
)
 
getPackageName ('package.json')
.pipe (fork (console.error) (console.log))

Global Bundle (CDN)

Fluture is hosted in full with all of its dependencies at https://cdn.jsdelivr.net/gh/fluture-js/Fluture@12.1.1/dist/bundle.js

This script will add Fluture to the global scope.

Interoperability

• Future implements Fantasy Land 1.0+ -compatible Alt, Bifunctor, Monad, and ChainRec (of, ap, alt, map, bimap, chain, chainRec).
• Future.Par implements Fantasy Land 3 -compatible Alternative (of, zero, map, ap, alt).
• The Future and ConcurrentFuture representatives contain @@type properties for Sanctuary Type Identifiers.
• The Future and ConcurrentFuture instances contain @@show properties for Sanctuary Show.

Butterfly

The name "Fluture" is a conjunction of "FL" (the acronym to Fantasy Land) 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 for sponsoring the project.

Documentation

Table of contents

Type signatures

The various function signatures are provided in a small language referred to as Hindley-Milner notation.

In summary, the syntax is as follows: InputType -> OutputType. Now, because functions in Fluture are curried, the "output" of a function is often another function. In Hindley-Milner that's simply written as InputputType -> InputToSecondFunction -> OutputType and so forth.

By convention, types starting with an upper-case letter are concrete types. When they start with a lower-case letter they're type variables. You can think of these type variables as generic types. So a -> b denotes a function from generic type a to generic type b.

Finally, through so-called constraints, type variables can be forced to conform to an "interface" (or Type Class in functional jargon). For example, MyInterface a => a -> b, denotes a function from generic type a to generic type b, where a must implement MyInterface.

You can read in depth about Hindley-Milner in JavaScript here.

Types

The concrete types you will encounter throughout this documentation:

• Future - Instances of Future provided by compatible versions of Fluture.
• ConcurrentFuture - Futures wrapped with (Future.Par).
• Promise a b - Values which conform to the Promises/A+ specification and have a rejection reason of type a and a resolution value of type b.
• Nodeback a b - A Node-style callback; A function of signature (a | Nil, b) -> x.
• Pair a b - An array with exactly two elements: [a, b].
• Iterator - Objects with next-methods which conform to the Iterator protocol.
• Cancel - The nullary cancellation functions returned from computations.
• Throwing e a b - A function from a to b that may throw an exception e.
• List - Fluture's internal linked-list structure: { head :: Any, tail :: List }.
• Context - Fluture's internal debugging context object: { tag :: String, name :: String, stack :: String }.

Type classes

Some signatures contain constrained type variables. Generally, these constraints express that some value must conform to a Fantasy Land-specified interface.

• Functor - Fantasy Land Functor conformant values.
• Bifunctor - Fantasy Land Bifunctor conformant values.
• Chain - Fantasy Land Chain conformant values.
• Apply - Fantasy Land Apply conformant values.
• Alt - Fantasy Land Alt conformant values.

Cancellation

Cancellation is a system whereby running Futures get an opportunity to stop what they're doing and release resources that they were holding, when the consumer indicates it is no longer interested in the result.

To cancel a Future, it must be unsubscribed from. Most of the consumption functions return an unsubscribe function. Calling it signals that we are no longer interested in the result. After calling unsubscribe, Fluture guarantees that our callbacks will not be called; but more importantly: a cancellation signal is sent upstream.

The cancellation signal travels all the way back to the source (with the exception of cached Futures - see cache), allowing all parties along the way to clean up.

With the Future constructor, we can provide a custom cancellation handler by returning it from the computation. Let's see what this looks like:

// We use the Future constructor to create a Future instance.
const eventualAnswer = Future (function computeTheAnswer (rej, res) {
 
  // We give the computer time to think about the answer, which is 42.
  const timeoutId = setTimeout (res, 60000, 42)
 
  // Here is how we handle cancellation. This signal is received when nobody
  // is interested in the answer any more.
  return function onCancel () {
    // Clearing the timeout releases the resources we were holding.
    clearTimeout (timeoutId)
  }
 
})
 
// Now, let's fork our computation and wait for an answer. Forking gives us
// the unsubscribe function.
const unsubscribe = fork (log ('rejection')) (log ('resolution')) (eventualAnswer)
 
// After some time passes, we might not care about the answer any more.
// Calling unsubscribe will send a cancellation signal back to the source,
// and trigger the onCancel function.
unsubscribe ()

Many natural sources in Fluture have cancellation handlers of their own. after, for example, does exactly what we've done just now: calling clearTimeout.

Finally, Fluture unsubscribes from Futures that it forks for us, when it no longer needs the result. For example, both Futures passed into race are forked, but once one of them produces a result, the other is unsubscribed from, triggering cancellation. This means that generally, unsubscription and cancellation is fully managed for us behind the scenes.

Stack safety

Fluture interprets our transformations in a stack safe way. This means that none of the following operations result in a RangeError: Maximum call stack size exceeded:

> const add1 = x => x + 1
 
> let m = resolve (1)
 
> for (let i = 0; i < 100000; i++) {
.   m = map (add1) (m)
. }
 
> fork (log ('rejection')) (log ('resolution')) (m)
[resolution]: 100001

> const m = (function recur (x) {
.   const mx = resolve (x + 1)
.   return x < 100000 ? chain (recur) (mx) : mx
. }(1))
 
> fork (log ('rejection')) (log ('resolution')) (m)
[resolution]: 100001

To learn more about memory and stack usage under different types of recursion, see (or execute) scripts/test-mem.

Debugging

First and foremost, Fluture type-checks all of its input and throws TypeErrors when incorrect input is provided. The messages they carry are designed to provide enough insight to figure out what went wrong.

Secondly, Fluture catches exceptions that are thrown asynchronously, and exposes them to you in one of two ways:

1. By throwing an Error when it happens.
2. By calling your exception handler with an Error.

The original exception isn't used because it might have been any value. Instead, a regular JavaScript Error instance whose properties are based on the original exception is created. Its properties are as follows:

• name: Always just "Error".
• message: The original error message, or a message describing the value.
• reason: The original value that was caught by Fluture.
• context: A linked list of "context" objects. This is used to create the stack property, and you generally don't need to look at it. If debug mode is not enabled, the list is always empty.
• stack: The stack trace of the original exception if it had one, or the Error's own stack trace otherwise. If debug mode (see below) is enabled, additional stack traces from the steps leading up to the crash are included.
• future: The instance of Future that was being consumed when the exception happened. Often printing it as a String can yield useful information. You can also try to consume it in isolation to better identify what's going wrong.

Finally, as mentioned, Fluture has a debug mode wherein additional contextual information across multiple JavaScript ticks is collected, included as an extended "async stack trace" on Errors, and exposed on Future instances.

Debug mode can have a significant impact on performance, and uses up memory, so I would advise against using it in production.

Casting Futures to String

There are multiple ways to print a Future to String. Let's take a simple computation as an example:

const add = a => b => a + b;
const eventualAnswer = ap (resolve (22)) (map (add) (resolve (20)));

1. Casting it to String directly by calling String(eventualAnswer) or eventualAnswer.toString() will yield an approximation of the code that was used to create the Future. In this case:

   "ap (resolve (22)) (map (a => b => a + b) (resolve (20)))"

2. Casting it to String using JSON.stringify(eventualAnswer, null, 2) will yield a kind of abstract syntax tree.

   {
     "$": "fluture/Future@5",
     "kind": "interpreter",
     "type": "transform",
     "args": [
       {
         "$": "fluture/Future@5",
         "kind": "interpreter",
         "type": "resolve",
         "args": [
           20
         ]
       },
       [
         {
           "$": "fluture/Future@5",
           "kind": "transformation",
           "type": "ap",
           "args": [
             {
               "$": "fluture/Future@5",
               "kind": "interpreter",
               "type": "resolve",
               "args": [
                 22
               ]
             }
           ]
         },
         {
           "$": "fluture/Future@5",
           "kind": "transformation",
           "type": "map",
           "args": [
             null
           ]
         }
       ]
     ]
   }

Sanctuary

When using this module with Sanctuary Def (and Sanctuary by extension) one might run into the following issue:

> import S from 'sanctuary'
 
> import {resolve} from 'fluture'
 
> S.I (resolve (1))
! TypeError: Since there is no type of which all the above values are members,
. the type-variable constraint has been violated.

This happens because Sanctuary Def needs to know about the types created by Fluture to determine whether the type-variables are consistent.

To let Sanctuary know about these types, we can obtain the type definitions from fluture-sanctuary-types and pass them to S.create:

> import sanctuary from 'sanctuary'
 
> import {env as flutureEnv} from 'fluture-sanctuary-types'
 
> import {resolve} from 'fluture'
 
> const S = sanctuary.create ({checkTypes: true, env: env.concat (flutureEnv)})
 
> fork (log ('rejection'))
.      (log ('resolution'))
.      (S.I (resolve (42)))
[resolution]: 42

Casting Futures

Sometimes we may need to convert one Future to another, for example when the Future was created by another package, or an incompatible version of Fluture.

When isFuture returns false, a conversion is necessary. Usually the most concise way of doing this is as follows:

> const NoFuture = require ('incompatible-future')
 
> const incompatible = NoFuture.of ('Hello')
 
> const compatible = Future (incompatible.fork.bind (incompatible))
 
> fork (log ('rejection'))
.      (log ('resolution'))
.      (both (compatible) (resolve ('world')))
[resolution]: ["Hello", "world"]

Creating Futures

Future

Future :: ((a -> Undefined, b -> Undefined) -> Cancel) -> Future a b

Creates a Future with the given computation. A computation is a function which takes two callbacks. Both are continuations for the computation. The first is reject, commonly abbreviated to rej; The second is resolve, or res. When the computation is finished (possibly asynchronously) it may call the appropriate continuation with a failure or success value.

Additionally, the computation must return a nullary function containing cancellation logic. See Cancellation.

If you find that there is no way to cancel your computation, you can return a noop function as a cancellation function. However, at this point there is usually a more fitting way to create that Future (like for example via node).

> fork (log ('rejection'))
.      (log ('resolution'))
.      (Future (function computation (reject, resolve) {
.        const t = setTimeout (resolve, 20, 42)
.        return () => clearTimeout (t)
.      }))
[resolution]: 42

resolve

resolve :: b -> Future a b

Creates a Future which immediately resolves with the given value.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (resolve (42))
[answer]: 42

reject

reject :: a -> Future a b

Creates a Future which immediately rejects with the given value.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (reject ('It broke!'))
[rejection]: "It broke!"

after

after :: Number -> b -> Future a b

Creates a Future which resolves with the given value after the given number of milliseconds.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (after (20) (42))
[resolution]: 42

rejectAfter

rejectAfter :: Number -> a -> Future a b

Creates a Future which rejects with the given reason after the given number of milliseconds.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (rejectAfter (20) ('It broke!'))
[rejection]: "It broke!"

go

go :: (() -> Iterator) -> Future a b

A way to do async/await with Futures, similar to Promise Coroutines or Haskell Do-notation.

Takes a function which returns an Iterator, commonly a generator-function, and chains every produced Future over the previous.

> fork (log ('rejection')) (log ('resolution')) (go (function*() {
.   const thing = yield after (20) ('world')
.   const message = yield after (20) ('Hello ' + thing)
.   return message + '!'
. }))
[resolution]: "Hello world!"

A rejected Future short-circuits the whole coroutine.

> fork (log ('rejection')) (log ('resolution')) (go (function*() {
.   const thing = yield reject ('It broke!')
.   const message = yield after (20) ('Hello ' + thing)
.   return message + '!'
. }))
[rejection]: "It broke!"

To handle rejections inside the coroutine, we need to coalesce the error into our control domain.

I recommend using coalesce with an Either.

> const control = coalesce (S.Left) (S.Right)
 
> fork (log ('rejection')) (log ('resolution')) (go (function*() {
.   const thing = yield control (reject ('It broke!'))
.   return S.either (x => `Oh no! ${x}`)
.                   (x => `Yippee! ${x}`)
.                   (thing)
. }))
[resolution]: "Oh no! It broke!"

attempt

attempt :: Throwing e Undefined r -> Future e r

Creates a Future which resolves with the result of calling the given function, or rejects with the error thrown by the given function.

Short for encase (f) (undefined).

> const data = {foo: 'bar'}
 
> fork (log ('rejection'))
.      (log ('resolution'))
.      (attempt (() => data.foo.bar.baz))
[rejection]: new TypeError ("Cannot read property 'baz' of undefined")

attemptP

attemptP :: (Undefined -> Promise a b) -> Future a b

Create a Future which when forked spawns a Promise using the given function and resolves with its resolution value, or rejects with its rejection reason.

Short for encaseP (f) (undefined).

> fork (log ('rejection'))
.      (log ('resolution'))
.      (attemptP (() => Promise.resolve (42)))
[resolution]: 42

node

node :: (Nodeback e r -> x) -> Future e r

Creates a Future which rejects with the first argument given to the function, or resolves with the second if the first is not present.

Note that this function does not support cancellation.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (node (done => done (null, 42)))
[resolution]: 42

encase

encase :: Throwing e a r -> a -> Future e r

Takes a function and a value, and returns a Future which when forked calls the function with the value and resolves with the result. If the function throws an exception, it is caught and the Future will reject with the exception.

Applying encase with a function f creates a "safe" version of f. Instead of throwing exceptions, the encased version always returns a Future.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (encase (JSON.parse) ('{"foo" = "bar"}'))
[rejection]: new SyntaxError ('Unexpected token =')

encaseP

encaseP :: (a -> Promise e r) -> a -> Future e r

Turns Promise-returning functions into Future-returning functions.

Takes a function which returns a Promise, and a value, and returns a Future. When forked, the Future calls the function with the value to produce the Promise, and resolves with its resolution value, or rejects with its rejection reason.

> encaseP (fetch) ('https://api.github.com/users/Avaq')
. .pipe (chain (encaseP (res => res.json ())))
. .pipe (map (user => user.name))
. .pipe (fork (log ('rejection')) (log ('resolution')))
[resolution]: "Aldwin Vlasblom"

Transforming Futures

map

map :: Functor m => (a -> b) -> m a -> m b

Transforms the resolution value inside the Future or Functor, and returns a Future or Functor with the new value. The transformation is only applied to the resolution branch: if the Future is rejected, the transformation is ignored.

See also chain and mapRej.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (map (x => x + 1) (resolve (41)))
[resolution]: 42

For comparison, an approximation with Promises is:

> Promise.resolve (41)
. .then (x => x + 1)
. .then (log ('resolution'), log ('rejection'))
[resolution]: 42

bimap

bimap :: Bifunctor m => (a -> c) -> (b -> d) -> m a b -> m c d

Maps the left function over the rejection reason, or the right function over the resolution value, depending on which is present. Can be used on any Bifunctor.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (bimap (x => x + '!') (x => x + 1) (resolve (41)))
[resolution]: 42
 
> fork (log ('rejection'))
.      (log ('resolution'))
.      (bimap (x => x + '!') (x => x + 1) (reject ('It broke!')))
[rejection]: "It broke!!"

For comparison, an approximation with Promises is:

> Promise.resolve (41)
. .then (x => x + 1, x => Promise.reject (x + '!'))
. .then (log ('resolution'), log ('rejection'))
[resolution]: 42
 
> Promise.reject ('It broke!')
. .then (x => x + 1, x => Promise.reject (x + '!'))
. .then (log ('resolution'), log ('rejection'))
[rejection]: "It broke!!"

chain

chain :: Chain m => (a -> m b) -> m a -> m b

Sequence a new Future or Chain using the resolution value from another. Similarly to map, chain expects a function. But instead of returning the new value, chain expects a Future (or instance of the same Chain) to be returned.

The transformation is only applied to the resolution branch: if the Future is rejected, the transformation is ignored.

See also chainRej.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (chain (x => resolve (x + 1)) (resolve (41)))
[resolution]: 42

For comparison, an approximation with Promises is:

> Promise.resolve (41)
. .then (x => Promise.resolve (x + 1))
. .then (log ('resolution'), log ('rejection'))
[resolution]: 42

swap

swap :: Future a b -> Future b a

Swap the rejection and resolution branches.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (swap (resolve (42)))
[rejection]: 42
 
> fork (log ('rejection'))
.      (log ('resolution'))
.      (swap (reject (42)))
[resolution]: 42

mapRej

mapRej :: (a -> c) -> Future a b -> Future c b

Map over the rejection reason of the Future. This is like map, but for the rejection branch.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (mapRej (s => `Oh no! ${s}`) (reject ('It broke!')))
[rejection]: "Oh no! It broke!"

For comparison, an approximation with Promises is:

> Promise.reject ('It broke!')
. .then (null, s => Promise.reject (`Oh no! ${s}`))
. .then (log ('resolution'), log ('rejection'))
[rejection]: "Oh no! It broke!"

chainRej

chainRej :: (a -> Future c b) -> Future a b -> Future c b

Chain over the rejection reason of the Future. This is like chain, but for the rejection branch.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (chainRej (s => resolve (`${s} But it's all good.`)))
[resolution]: "It broke! But it's all good."

For comparison, an approximation with Promises is:

> Promise.reject ('It broke!')
. .then (null, s => `${s} But it's all good.`)
. .then (log ('resolution'), log ('rejection'))
[resolution]: "It broke! But it's all good."

coalesce

coalesce :: (a -> c) -> (b -> c) -> Future a b -> Future d c

Applies the left function to the rejection value, or the right function to the resolution value, depending on which is present, and resolves with the result.

This provides a convenient means to ensure a Future is always resolved. It can be used with other type constructors, like S.Either, to maintain a representation of failure.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (coalesce (S.Left) (S.Right) (resolve ('hello'))
[resolution]: Right ("hello")
 
> fork (log ('rejection'))
.      (log ('resolution'))
.      (coalesce (S.Left) (S.Right) (reject ('It broke!'))
[resolution]: Left ("It broke!")

For comparison, an approximation with Promises is:

> Promise.resolve ('hello')
. .then (S.Right, S.Left)
. .then (log ('resolution'), log ('rejection'))
[resolution]: Right ("hello")
 
> Promise.reject ('It broke!')
. .then (S.Right, S.Left)
. .then (log ('resolution'), log ('rejection'))
[resolution]: Left ("It broke!")

Combining Futures

ap

ap :: Apply m => m a -> m (a -> b) -> m b

Applies the function contained in the right-hand Future or Apply to the value contained in the left-hand Future or Apply. This process can be repeated to gradually fill out multiple function arguments of a curried function, as shown below.

Note that the Futures will be executed in sequence - not in parallel* - because of the Monadic nature of Futures. The execution order is, as specified by Fantasy Land, m (a -> b) first followed by m a. So that's right before left.

* Have a look at pap for an ap function that runs its arguments in parallel. If you must use ap (because you're creating a generalized function), but still want Futures passed into it to run in parallel, then you could use ConcurrentFuture instead.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (ap (resolve (7)) (ap (resolve (49)) (resolve (x => y => x - y))))
[resolution]: 42

pap

pap :: Future a b -> Future a (b -> c) -> Future a c

Has the same signature and function as ap, but runs the two Futures given to it in parallel. See also ConcurrentFuture for a more general way to achieve this.

> fork (log ('rejection'))
.      (log ('resolution'))
.      (pap (resolve (7)) (pap (resolve (49)) (resolve (x => y => x - y))))
[resolution]: 42