@recubed/async
Minimal set of functional async primitives.
A set of functional utilities designed with purity, laziness, safety and simplicity in mind.
Mostly here to support my incoming Redux
REST
client but can definitely be used as a stand-alone utility library.
Option
Failure | Completed a
The very basic type Task
's operate on. Represents two possible results - completion and failure, forming a tagged union over a tag
property. Can be created with Faulted
and Completed
constructors. Unless manually crafted will always be wrapped in an array to ensure consistent continuation handling.
Task
(Thenable | Lazy Promise) a -> Lazy Thenable [ Completed a | Faulted ]
Task constructor accepts both eager and lazy promises. It will return a thunk
-ed version of the promise regardless of the input type. Lazy ones will not get started until task function returns.
// Creation
const task = Task(Promise.resolve(42));
// or
const task = Task(() => Promise.resolve(42));
// or
const task = complete(42);
// or
const task = complete(Promise.resolve(42));
task().then(console.log);
// [ { tag: 'completed', value: 42, meta: { args: [] } } ]
task().then(console.log);
// [ { tag: 'completed', value: 42, meta: { args: [] } } ]
Unlike promises, Task
s do not reject. Rejections are handled internally and wrapped in Faulted
option. This brings some advantages to the table, i.e. purity, branching reduction and unhandled rejections problem trivialisation.
const task = Task(() => Promise.reject(42));
task().then(console.log);
// [ { tag: 'faulted', fault: 42, meta: { args: [] } } ]
Lazy tasks may optionally accept arguments. These will be returned within the result object, under meta.args
. May turn out useful in distributed context where promises are passed around and it is not immediately obvious what the failure reason was for the consuming code. Think of complex effectful procedures, i.e. Redux-Saga
fetching REST
resources.
const task = Task(url => fetch(url).then(resp => resp.json()))(
'https://non.existent'
);
task().then(([fault]) => console.log(fault.meta.args));
// [ 'https://non.existent' ]
Additionally, Task
module exposes a set of constructors to simplify task creation.
// Create a task of 'faulted' type
const task = fail(42);
task().then(console.log);
// [ { tag: 'faulted', fault: 42, meta: { args: [] } } ]
// Create a task from a 'completed' option
const task = from(Completed(42));
task().then(console.log);
// [ { tag: 'completed', value: 42, meta: {} } ]
// Create a task from a 'faulted' option
const task = from(Faulted(42));
task().then(console.log);
// [ { tag: 'completed', fault: 42, meta: {} } ]
Parallel
[ Lazy Thenable Completed a | Faulted ] -> Lazy Thenable [ Completed a | Faulted ]
The 'Parallel' module is a functional wrapper over native Promise.all
api, ceteris paribus. Design approach is similar to that of Task
, except that it only accepts Task
s as input parameters. TypeScript
signature restricts it to operate on thunk
-ed, Option
-returning promises. It is advised to only use built-in Task
constructors for the input functions. No guarantees in regards to control flow (read - rejections) are given otherwise. This will be optimised once Promise.allSettled
lands in official runtimes.
const all = Parallel(complete(42), fail(9001));
all().then(console.log);
// [ { tag: 'completed', value: 42, meta: { args: [] } },
// { tag: 'faulted', fault: 9001, meta: { args: [] } } ]
Continuation
Continuation Task a -> Continuation Task b
Task
's themselves do not modify the native promise continuation flow meaning once then
method of a completed task is entered we're back in the world of rejections. This is where Continuation
comonad comes handy as it:
- will return the first faulty set of results to the caller (while ignoring further continuations);
- won't expose native
then
method until the last continuation returns; - ensures options are used as result types (at
TypeScript
level);
map: Completion a -> Lazy Thenable [ Completed a | Faulted ]
const piped = await Continuation(complete(10))
.map(_ => fail(12))
.map(_ => complete(9001))();
console.log(piped);
// [ { tag: 'faulted', fault: 12, meta: { args: [] } } ]
Because map
is eager (will trigger continuations even if the last one does not return)...
Continuation(complete(10))
.map(_ => {
console.log(42);
return complete(42);
})
.map(_ => {
console.log(9001);
return fail(9001);
});
// 42
// 9001
...Continuation does also expose (lazy) extend
method.
const piped = await Continuation(complete(10))
.extend(wa => wa().then(apply(([x]) => Task(Promise.resolve(x.value + 5)))))
.extend(wa => wa().then(apply(([x]) => Task(Promise.resolve(x.value + 6)))))
.extend(wa => wa().then(apply(([x]) => complete(x.value * 2))))();
console.log(piped);
// [ { tag: 'completed', value: 42, meta: { args: [] } } ]
This is quite verbose, I admit... Without the apply
helper it would get even longer in addition to having some nasty typings problems. Unless a full control of current calculation context is required pipe
should be used instead...
const piped = await Continuation(complete(10))
.extend(pipe(([x]) => Task(Promise.resolve(x.value + 6))))
.extend(pipe(([x]) => Task(Promise.resolve(x.value + 5))))
.extend(pipe(([x]) => Task(Promise.resolve(x.value * 2))))();
console.log(piped);
// 42
...for convenience pipe
is also exposed as a chainable method on Continuation
object instances.
const piped = await Continuation(complete(10))
.pipe(([x]) => Task(Promise.resolve(x.value + 6)))
.pipe(([x]) => Task(Promise.resolve(x.value + 5)))
.pipe(([x]) => Task(Promise.resolve(x.value * 2)))();
console.log(piped);
// 42
incoming
- Free Continuation (trampoline);
- Retry;
- Race;