Task

data. Task

new Task()

The Task data structure. Use Task to encapsulate asynchronous logic to avoid having to deal with callback hell. In contrast to a Promise, a Task is evaluated lazy

Version:
  • 3.0.0
Source:
Example
const {Task} = require('futils').data;

const one = Task((rej, res) => res(1));

one.run(
    (err) => { console.error(err); },
    (num) => { console.log(num); }
)

Extends

Methods

(static) empty() → {Task}

Monoid implementation for Task. Returns a Task which neither resolves nor rejects

Source:
Returns:
Type:
Task

A Task that is pending forever

Example
const {Task} = require('futils').data;

Task.empty(); // -> Task(?, ?)

(static) fromEither(a) → {Task}

A natural transformation from a Either.Right or Either.Left into a Task. If the Either is a Either.Left, the resulting Task rejects

Source:
Parameters:
Name Type Description
a Right | Left

The Either structure
Returns:
Type:
Task

A Task which rejects Either.Left and resolves Either.Right

Example
const {Task, Either} = require('futils').data;

const r = Either.Right('a value');
const l = Either.Left('fallback');

Task.fromEither(r); // -> Task(_, 'a value')
Task.fromEither(l); // -> Task('fallback', _)

(static) fromId(a) → {Task}

A natural transformation from an Id into a Task

Source:
Parameters:
Name Type Description
a Id

The Id to transform
Returns:
Type:
Task

The Task which resolves to the value of the Id

Example
const {Task, Id} = require('futils').data;

const id = Id('a value');

Task.fromId(id); // -> Task(_, 'a value')

(static) fromIO(a) → {Task}

A natural transformation from an IO into a Task. If the IO results in an Error, the resulting Task fails with the exception

Source:
Parameters:
Name Type Description
a IO

The IO structure
Returns:
Type:
Task

A Task which resolves with the result of the IO

Example
const {Task, IO} = require('futils').data;

const env = k => IO(() => process[k]);

Task.fromIO(env('arch')); // -> Task(_, <architecture>)

(static) fromList(a) → {Task}

A natural transformation from a List into a Task. Please note that this transformation looses data, because only the first element of the list is taken. If the first element is null or undefined, a rejecting Task is returned

Source:
Parameters:
Name Type Description
a List

The List structure
Returns:
Type:
Task

A Task of the first element

Example
const {Task, List} = require('futils').data;

const ls = List.of(2).cons(1);

Task.fromList(ls); // -> Task(_, 1)

(static) fromMaybe(a) → {Task}

A natural transformation from a Maybe.Some or Maybe.None into a Task. If the Maybe is a Maybe.None, the resulting Task rejects

Source:
Parameters:
Name Type Description
a Some | None

The Maybe structure
Returns:
Type:
Task

A Task which rejects Maybe.None and resolves Maybe.Some

Example
const {Task, Maybe} = require('futils').data;

const some = Maybe.Some('a value');
const none = Maybe.None();

Task.fromMaybe(some); // -> Task(_, 'a value')
Task.fromMaybe(none); // -> Task(null, _)

(static) fromNodeFunction(f) → {function}

Converts a Node style continuation passing function into a Task returning form

Source:
Parameters:
Name Type Description
f function

A function in the Node CPS form
Returns:
Type:
function

A function which returns a Task

Example
const {Task} = require('futils').data;
const fs = require('fs');

const readFile = Task.fromNodeFunction(fs.readFile.bind(fs));

readFile('example.txt', 'utf8'); // -> Task(Error, String)

(static) fromPromiseFunction(f) → {function}

Converts a Promise returning function into a Task returning form

Source:
Parameters:
Name Type Description
f function

A function which returns a Promise
Returns:
Type:
function

A function which returns a Task

Example
const {Task} = require('futils').data;
const fs = require('fs').promises;

const readFile = Task.fromPromiseFunction(fs.readFile.bind(fs));

readFile('example.txt', 'utf8'); // -> Task(Error, String)

(static) of(a) → {Task}

Lifts a value into a Task. The resulting Task always resolves with the given value

Source:
Parameters:
Name Type Description
a any

The value to lift
Returns:
Type:
Task

The value wrapped in a Task

Example
const {Task} = require('futils').data;

Task.of(1); // -> Task(_, 1)

(static) reject(a) → {Task}

Lifts a value into a Task. The resulting Task always fails with the given value

Source:
Parameters:
Name Type Description
a any

The value to lift
Returns:
Type:
Task

The value wrapped in a Task

Example
const {Task} = require('futils').data;

Task.reject(1); // -> Task(1, _)

(static) resolve(a) → {Task}

Lifts a value into a Task. The resulting Task always resolves with the given value

Source:
Parameters:
Name Type Description
a any

The value to lift
Returns:
Type:
Task

The value wrapped in a Task

Example
const {Task} = require('futils').data;

Task.resolve(1); // -> Task(_, 1)

(static) timeout(ms, f) → {Task}

Creates a Task which resolves a function after the given amount of milliseconds

Source:
Parameters:
Name Type Description
ms Number

Delay in milliseconds
f function

The function to call after the timeout
Returns:
Type:
Task

A Task that resolves with the result of the function

Example
const {Task} = require('futils').data;

const delayed = () => 1;

Task.timeout(400, delayed); // -> Task(_, 1)

alt(a) → {Task}

Alt implementation, allows to swap a failing Task

Source:
Parameters:
Name Type Description
a Task

An optional Task
Returns:
Type:
Task

A new Task

Example
const {Task} = require('futils').data;

Task.reject(0).alt(Task.of(1)); // -> Task(_, 1)

ap(a) → {Task}

Applies a Task with a function to another Task. Resolves when both resolve or fails if either of both fails

Source:
Parameters:
Name Type Description
a Task

Task with a value
Returns:
Type:
Task

A new Task

Example
const {Task} = require('futils').data;

const task = Task.of(1);

const apply = Task.of((n) => n + 1);

apply.ap(task); // -> Task(_, 2)

biMap(f, g) → {Task}

Bifunctor interface, maps either of two functions over the value inside a Task

Source:
Parameters:
Name Type Description
f function

The mapping function for a rejecting Task
g function

The mapping function for a resolving Task
Returns:
Type:
Task

A new Task

Example
const {Task, Either} = require('futils').data;
const {Left, Right} = Either;

const errToLeft = err =>
    err instanceof Error
        ? Left(err.message)
        : Left(err)

const failure = Task.reject(new Error('Should fail'));
const success = Task.of(1);

failure.biMap(errToLeft, Right); // -> Task(Left('Should fail'), _)
success.biMap(errToLeft, Right); // -> Task(_, Right(1))

concat(a) → {Task}

Concatenates a Task with another. Resolves with the Task which resolves faster or rejects if either of both fail

Source:
Parameters:
Name Type Description
a Task

The Task to concatenate with
Returns:
Type:
Task

Result of the concatenation

Example
const {Task} = require('futils').data;

const ms300 = Task.timeout(300, () => 1);
const ms500 = Task.timeout(500, () => 2);

ms500.concat(ms300); // -> Task(_, 1)

flat() → {Task}

Flattens a nested Task one level

Source:
Returns:
Type:
Task

A Task flattened

Example
const {Task} = require('futils').data;

const tasks = Task.of(Task.of(1));

tasks.flat(); // -> Task(_, 1)

flatMap(f) → {Task}

Maps a Task returning function over a Task and flattens the result

Source:
Parameters:
Name Type Description
f function

The function to map
Returns:
Type:
Task

A new Task

Example
const {Task} = require('futils').data;

const task = Task.of(1);

const inc = (n) => Task.of(n + 1);

task.flatMap(inc); // -> Task(_, 2)

map(f) → {Task}

Maps a function over the value and resolves with the result

Source:
Parameters:
Name Type Description
f function

The function to map
Returns:
Type:
Task

A new Task

Example
const {Task} = require('futils').data;

const one = Task.of(1);

one.map((n) => n + 1); // -> Task(_, 2)

swap() → {Task}

Swaps the disjunction of a Task, meaning if it normally resolves it fails and if it normally fails it resolves

Source:
Returns:
Type:
Task

A new Task

Example
const {Task} = require('futils').data;

const ok = Task.of(1);
const fail = Task.reject(1);

ok.swap(); // -> Task(1, _)
fail.swap(); // -> Task(_, 1)

toPromise() → {Promise}

A natural transformation from a Task into a Promise

Source:
Returns:
Type:
Promise

A Promise which runs the Task

Example
const {Task} = require('futils').data;

Task.of(1).toPromise(); // -> Promise(1)