@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, Tasks 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 Tasks 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;