https://github.com/fluture-js/fluture-hooks
Fantasy Land Monad and Alternative instances for Fluture's hook
https://github.com/fluture-js/fluture-hooks
fantasy-land fluture monad resource-management
Last synced: 7 months ago
JSON representation
Fantasy Land Monad and Alternative instances for Fluture's hook
- Host: GitHub
- URL: https://github.com/fluture-js/fluture-hooks
- Owner: fluture-js
- License: mit
- Created: 2019-01-18T11:27:45.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2021-04-06T08:21:57.000Z (over 4 years ago)
- Last Synced: 2025-03-24T11:44:47.933Z (8 months ago)
- Topics: fantasy-land, fluture, monad, resource-management
- Language: JavaScript
- Size: 127 KB
- Stars: 19
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Fluture Hooks
Fantasy Land Monad and Alternative instances for return values from
[Fluture's `hook`][hook].
[hook]: https://github.com/fluture-js/Fluture#hook
## Usage
### Node
```console
$ 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](https://cdn.skypack.dev/fluture-hooks@2.1.3)
- [JSPM](https://jspm.dev/fluture-hooks@2.1.3)
- [jsDelivr](https://cdn.jsdelivr.net/npm/fluture-hooks@2.1.3/+esm)
### Old Browsers and Code Pens
There's a [UMD][] file included in the NPM package, also available via
jsDelivr: https://cdn.jsdelivr.net/npm/fluture-hooks@2.1.3/dist/umd.js
This file adds `flutureHooks` to the global scope, or use CommonJS/AMD
when available.
### Usage Example
```js
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`][hook]) as a "Hook".
`Hook a` has Monad instance with sequential behaviour in its Applicative.
```js
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`](#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)`.
[esm]: https://github.com/standard-things/esm
[UMD]: https://github.com/umdjs/umd