futils.IO - futils docs

new IO()

The IO data structure is used to describe computations that perform unpure interactions with the outer world

Version:

3.0.0

Source:

data/IO.js, line 19

Example

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

const envA = (key) => IO(() => process[key]);
const envB = IO((key) => process[key]);
const envC = (key) => IO((data) => data[key]);

envA('arch').run();        // -> <architecture>
envB.run('arch');          // -> <architecture>
envC('arch').run(process); // -> <architecture>

Methods

(static) empty() → {IO}

Monoid implementation for IO. Returns a IO that returns what is passed to it

Source:

data/IO.js, line 54

Returns:

Type:: IO

A IO

Example

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

IO.empty(); // -> IO(a -> a)

(static) from(a) → {IO}

Lifts a value into a IO. Similiar to IO.of, but if the value is a function it is used as computation basis

Source:

data/IO.js, line 67

Parameters:

Name	Type	Description
`a`	`any`	The value to lift

Returns:

Type:: IO

A IO

Example

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

const inc = (n) => n + 1;

IO.from(1);   // -> IO(_ -> 1)
IO.from(inc); // -> IO(n -> n + 1)

(static) fromEither(a) → {IO}

A natural transformation from an Either.Left or Either.Right into a IO

Source:

data/IO.js, line 85

Parameters:

Name	Type	Description
`a`	`Left` \| `Right`	The Either to transform

Returns:

Type:: IO

A IO with the value of the Either

Example

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

const l = Either.Left('a left');
const r = Either.Right('a right');

IO.fromEither(l); // -> IO(_ -> 'a left')
IO.fromEither(r); // -> IO(_ -> 'a right')

(static) fromId(a) → {IO}

A natural transformation from an Id into a IO

Source:

data/IO.js, line 139

Parameters:

Name	Type	Description
`a`	`Id`	The Id to transform

Returns:

Type:: IO

A IO with the value of the Id

Example

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

const id = Id.of(1);

IO.fromId(id); // -> IO(_ -> 1)

(static) fromList(a) → {IO}

A natural transformation from a List into a IO. Please note that this transformation looses data, because only the first element of the list is taken

Source:

data/IO.js, line 121

Parameters:

Name	Type	Description
`a`	`List`	The List to transform

Returns:

Type:: IO

A IO with the first value

Example

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

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

IO.fromList(ls); // -> IO(_ -> 1)

(static) fromMaybe(a) → {IO}

A natural transformation from a Maybe.Some or Maybe.None into a IO

Source:

data/IO.js, line 103

Parameters:

Name	Type	Description
`a`	`Some` \| `None`	The Maybe to transform

Returns:

Type:: IO

A IO with the value of the Maybe.Some or null

Example

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

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

IO.fromMaybe(some); // -> IO(_ -> 'a some')
IO.fromMaybe(none); // -> IO(_ -> null)

(static) of(a) → {IO}

Lifts a value into a IO

Source:

data/IO.js, line 40

Parameters:

Name	Type	Description
`a`	`any`	The value to lift

Returns:

Type:: IO

The value wrapped into a IO

Example

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

IO.of(1); // -> IO(_ -> 1)

ap(a) → {IO}

Applies a function in an IO to a value in another IO

Source:

data/IO.js, line 237

Parameters:

Name	Type	Description
`a`	`IO`	The IO that holds the value

Returns:

Type:: IO

IO which contains the result of applying the function

Example

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

const io = IO.of(1);

const mInc = IO.of((n) => n + 1);

mInc.ap(io); // -> IO(_ -> 2)

concat(a) → {IO}

Concatenates a IO with another

Source:

data/IO.js, line 158

Parameters:

Name	Type	Description
`a`	`IO`	The IO to concatenate with

Returns:

Type:: IO

Result of concatening the IO with the given one

Example

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

const ioProcess = IO.of(process);
const ioArch = IO((p) => p.arch);

ioProcess.concat(ioArch); // -> IO(_ -> <architecture>)

contraMap(f) → {IO}

Contravariant functor implementation, contramaps a function over the value passed into the IO

Source:

data/IO.js, line 257

Parameters:

Name	Type	Description
`f`	`function`	The function to contramap with

Returns:

Type:: IO

A new IO

Example

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

const io = IO.empty();

const len = (xs) => xs.length;

io.contraMap(len).run([1, 2]); // -> 2

flat() → {IO}

Flattens a nested IO by one level

Source:

data/IO.js, line 200

Returns:

Type:: IO

A flattened IO

Example

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

cons io = IO.of(IO.of(1));

io.flat(); // -> IO(_ -> 1)

flatMap(f) → {IO}

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

Source:

data/IO.js, line 217

Parameters:

Name	Type	Description
`f`	`function`	A IO returning function to map

Returns:

Type:: IO

A new IO

Example

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

const io = IO.of(1);

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

io.flatMap(inc); // -> IO(_ -> 2)

map(f) → {IO}

Maps a function over the value in a IO

Source:

data/IO.js, line 180

Parameters:

Name	Type	Description
`f`	`function`	The function to map

Returns:

Type:: IO

A IO

Example

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

const io = IO.of(1);

const inc = (n) => n + 1;

io.map(inc); // -> IO(_ -> 2)

proMap(f, g) → {IO}

Profunctor implementation, contramaps the first function over the value given into the IO and maps the second function over the result

Source:

data/IO.js, line 278

Parameters:

Name	Type	Description
`f`	`function`	The function to contramap
`g`	`function`	The function to map

Returns:

Type:: IO

A new IO

Example

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

const io = IO.empty();

const even = (n) => n % 2 === 0;

const len = (xs) => xs.length;

io.proMap(len, even).run([1, 2]); // -> true