README.md

Fluture Hooks

Fantasy Land Monad and Alternative instances for return values from Fluture's hook.

Usage

Node

$ npm install --save fluture-hooks

On Node 12 and up, this module can be loaded directly with import or require. On Node versions below 12, require or the esm-loader can be used.

Deno and Modern Browsers

You can load the EcmaScript module from various content delivery networks:

• Skypack
• JSPM
• jsDelivr

Old Browsers and Code Pens

There's a UMD file included in the NPM package, also available via jsDelivr: https://cdn.jsdelivr.net/npm/[email protected]/dist/umd.js

This file adds flutureHooks to the global scope, or use CommonJS/AMD when available.

Usage Example

import {Future, node, fork} from 'fluture/index.js';
import {hook, hookAll, runHook} from 'fluture-hooks/index.js';

const acquirePostgres = (
  node (done => require ('imaginary-postgres').connect (done))
);

const acquireRedis = (
  node (done => require ('imaginary-redis').connect (done))
);

const closeConnection = connection => (
  node (done => connection.end (done))
);

const postgresHook = hook (acquirePostgres) (closeConnection);
const redisHook = hook (acquireRedis) (closeConnection);
const servicesHook = hookAll ([postgresHook, redisHook]);

const withServices = runHook (servicesHook);

fork (console.error)
     (console.log)
     (withServices (([postgres, redis]) => Future ((rej, res) => {
       /* consume postgres and redis */
     })));

API

Hook :: ((b -⁠> a) -⁠> a) -⁠> Hook a b

Tags a function awaiting a callback (such as the value returned by Fluture's hook) as a "Hook".

Hook a has Monad instance with sequential behaviour in its Applicative.

Hook (Future.hook (myResourceAcquisition) (myResourceDisposal));

hook :: Future a b -⁠> (b -⁠> Future c d) -⁠> Hook (Future a e) b

hook (m) (f) is the equivalent of Hook (Future.hook (m) (f)).

acquire :: Future a b -⁠> Hook (Future a d) b

Creates a Hook without the need for a disposal function.

runHook :: Hook b a -⁠> (a -⁠> b) -⁠> b

Given a Hook and a callback, runs the Hook, returning the callbacks' return value. For Hooks created from Fluture's hook, this means a Future is retured.

This function can also be thought of as "untagging" a Hook: runHook (Hook (h)) = h.

ParallelHook :: Hook a b -⁠> ParallelHook a b

Construct a ParallelHook using a Hook.

ParallelHook a has a Functor instance, and ParallelHook (Future a b) has an Applicative instance with parallel behaviour.

sequential :: ParallelHook a b -⁠> Hook a b

Converts a ParallelHook to a normal Hook.

hookAll :: Array (Hook (Future a b) c) -⁠> Hook (Future a b) (Array c)

Combines resources from many hooks into a single hook in parallel, given that the eventual consumption of this new hook will return a Future.

hookAll (hooks) is the equivalent of sequential (sequence (ParallelHook) (map (ParallelHook) (hooks))) for all hooks :: Array (Hook (Future a b) c).