Fluture

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][S].
• A pleasant debugging experience.

For more information:

• API documentation
• [Article: Introduction to Fluture - A Functional Alternative to Promises][10]
• [Wiki: Compare Futures to Promises][wiki:promises]
• [Wiki: Compare Fluture to similar libraries][wiki:similar]
• [Video: Monad a Day - Futures by @DrBoolean][5]

Installation

With NPM

$ npm install --save fluture

Bundled from a CDN

To load Fluture directly into a browser, a code pen, or [Deno][], use one of the following downloads from the JSDelivr content delivery network. These are single files that come with all of Fluture's dependencies pre-bundled.

• Fluture Script: A JavaScript file that adds Fluture to the global scope. Ideal for older browsers and code pens.
• Fluture Script Minified: The same as above, but minified.
• Fluture Module: An EcmaScript module with named exports. Ideal for Deno or modern browsers.
• Fluture Module Minified: A minified EcmaScript module without TypeScript typings. Not recommended for Deno.

Usage

EcmaScript Module

Fluture is written as modular JavaScript.

• On Node 12 and up, Fluture can be loaded directly with import 'fluture'.
• On some older (minor) Node versions, you may need to import from 'fluture/index.js' instead, and/or pass --experimental-modules to node.
• On Node versions below 12, the [esm loader][esm] can be used. Alternatively, there is a CommonJS Module available.
• Modern browsers can run Fluture directly. If you'd like to try this out, I recommend installing Fluture with [Pika][] or [Snowpack][]. You can also try the bundled module to avoid a package manager.
• For older browsers, use a bundler such as [Rollup][] or WebPack. Besides the module system, Fluture uses purely ES5-compatible syntax, so the source does not have to be transpiled after bundling. Alternatively, there is a CommonJS Module available.

import {readFile} from 'fs'
import {node, encase, chain, map, fork} from 'fluture'

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))

CommonJS Module

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

On older environments one or more of the following functions may need to be polyfilled: [Object.create][JS:Object.create], [Object.assign][JS:Object.assign] and [Array.isArray][JS:Array.isArray].

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))

Documentation

Table of contents

• Installation instructions
• Usage instructions
• About the Fluture project
• On interoperability with other libraries
• How to read the type signatures
• How cancellation works
• On stack safety
• Debugging with Fluture
• Casting Futures to String
• Usage with Sanctuary
• Using multiple versions of Fluture alongside each other

• Future: Create a possibly cancellable Future
• resolve: Create a resolved Future
• reject: Create a rejected Future
• after: Create a Future that resolves after a timeout
• rejectAfter: Create a Future that rejects after a timeout
• go: Create a "coroutine" using a generator function
• attempt: Create a Future using a possibly throwing function
• attemptP: Create a Future using a Promise-returning function
• node: Create a Future using a Node-style callback
• encase: Convert a possibly throwing function to a Future function
• encaseP: Convert a Promise-returning function to a Future function

• node: Create a Future using a Node-style callback
• done: Consume a Future by providing a Nodeback

• attemptP: Create a Future using a Promise-returning function
• encaseP: Convert a Promise-returning function to a Future function
• promise: Convert a Future to a Promise

• pipe: Apply a function to a Future in a fluent method chain
• map: Synchronously process the success value in a Future
• bimap: Synchronously process the success or failure value in a Future
• chain: Asynchronously process the success value in a Future
• bichain: Asynchronously process the success or failure value in a Future
• swap: Swap the success with the failure value
• mapRej: Synchronously process the failure value in a Future
• chainRej: Asynchronously process the failure value in a Future
• coalesce: Coerce success and failure values into the same success value
• ap: Combine the success values of multiple Futures using a function
• pap: Combine the success values of multiple Futures in parallel using a function
• and: Logical and for Futures
• alt: Logical or for Futures
• lastly: Run a Future after the previous settles
• race: Race two Futures against each other
• both: Await both success values from two Futures
• parallel: Await all success values from many Futures

• fork: Standard way to run a Future and get at its result
• forkCatch: Fork with exception recovery
• value: Shorter variant of fork for Futures sure to succeed
• done: Nodeback style fork
• promise: Convert a Future to a Promise

• pap: Combine the success values of multiple Futures in parallel using a function
• race: Race two Futures against each other
• both: Await both success values from two Futures
• parallel: Await all success values from many Futures
• ConcurrentFuture: A separate data-type for doing algebraic concurrency
• alt: Behaves like race on ConcurrentFuture instances

• hook: Safely create and dispose resources
• lastly: Run a Future after the previous settles

• pipe: Apply a function to a Future in a fluent method chain
• cache: Cache a Future so that it can be forked multiple times
• isFuture: Determine whether a value is a Fluture compatible Future
• never: A Future that never settles
• debugMode: Configure Fluture's debug mode
• context: The debugging context of a Future instance

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.

Interoperability

[][FL]

• Future implements [Fantasy Land][FL] 1.0+ -compatible Alt, Bifunctor, Monad, and ChainRec (of, ap, alt, map, bimap, chain, chainRec).
• Future.Par implements [Fantasy Land 3][FL] -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].

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][Guide:currying], the "output" of a function is often another function. In Hindley-Milner that's simply written as InputType -> 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][Guide:HM] 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][7] and have a rejection reason of type a and a resolution value of type b.
• Nodeback a b - A Node-style callback; A function o