futils.operation - futils docs

(static) alt(o, a) → {Alt}

The alt function allows to swap any data structure which might be invalid with a fallback data structure of the same type

Since:

3.1.0

Source:

operation/alt.js, line 16

Parameters:

Name	Type	Description
`o`	`Alt`	The optional Alt
`a`	`Alt`	The Alt which might be invalid

Returns:

Type:: Alt

A new instance of the Alt

Example

const {Maybe} = require('futils').data;
const {alt} = require('futils').operation;

alt(Maybe.of(1), Maybe.empty()); // -> Some(1)

(static) ap(af, a) → {Functor|Promise}

The ap function allows to apply a function inside a Applicative to a value in another Functor. Because the .then function of a Promise flattens a returned Promise, ap can be used with Promise, too

Source:

operation/ap.js, line 16

Parameters:

Name	Type	Description
`af`	`Applicative` \| `Array` \| `Promise`	The Applicative, Array or Promise to apply
`a`	`Functor` \| `Promise`	A Functor or Promise of the same type as af

Returns:

Type:: Functor | Promise

A new instance of the Functor or Promise

Example

const {Id} = require('futils').data;
const {ap} = require('futils').operation;

const upper = Id.of((a) => a.toUpperCase());
const calc = [(a) => a + 1, (a) => a * 2];

ap(upper, Id.of('a')); // -> Id('A')
ap(upper);             // -> (Functor -> Functor)
ap(calc, [1, 2]);      // -> [4, 6]

(static) biMap(f, g, B) → {BiFunctor}

The biMap function is useful when working with BiFunctor implementing types

Version:

3.1.0

Source:

operation/biMap.js, line 16

Parameters:

Name	Type	Description
`f`	`function`	A failure/lhs handling function
`g`	`function`	A success/rhs handling function
`B`	`BiFunctor`	The BiFunctor to biMap over

Returns:

Type:: BiFunctor

A new instance of the BiFunctor

Example

const {biMap} = require('futils').operation;
const {Maybe} = require('futils').data;

const err = () => 'No value';
const succ = a => `Value: ${a}`;

biMap(err, succ, Maybe.of(1));  // -> Some('Value: 1')
biMap(err, succ, Maybe.None()); // -> Some('No value')

(static) caseOf(a, b) → {any}

The caseOf function is useful to apply pattern matching to a type. This allows for various uses, like functions which work differently in regards to the type of the given value. Also have a look at the examples below.

Version:

3.1.0

Source:

operation/caseOf.js, line 30

Parameters:

Name	Type	Description
`a`	`Object`	A mapping of types to functions
`b`	`any`	The value to pattern match against

Returns:

Type:: any

Returns the result of the matching function

Examples

Function handling different types of arguments
const {caseOf} = require('futils').operation;

const reverse = caseOf({
  Array: a => [...a].reverse(),
  String: a => a.split('').reverse().join(''),
  _: a => a
});


const nums = [1, 2, 3, 4];
const text = 'Hello!';

reverse(nums); // -> [4, 3, 2, 1]
reverse(text); // -> '!olleH'

Usage with a custom union type
const {caseOf} = require('futils').operation;
const {UnionType} = require('futils').adt;

const Num = UnionType('Num', { OK: ['value'], Err: ['desc'] });
const {OK, Err} = Num;


const divBy = a => caseOf({
  OK: b => a === 0 ? Err('ZeroDivision: ${b}/${a}') : OK(b / a),
  Err: b => Err(b),
  _: _ => _
});


const nums = [2, 0, 3];

const div18ByNums = nums.map(divBy).reduce((a, f) => f(a), 18);

div18ByNums; // -> Err({ desc: 'ZeroDivison 9 / 0' })

(static) concat(a, b) → {Semigroup|Promise}

The concat function is used to combine two Semigroup instances. This also works for Promises and will result in a Promise where the first resolving/rejecting promise succeeds/fails, meaning it acts like Promise.race

Source:

operation/concat.js, line 30

Parameters:

Name	Type	Description
`a`	`Semigroup` \| `Promise`	The Semigroup to concat
`b`	`Semigroup` \| `Promise`	The Semigroup to concatenate with

Returns:

Type:: Semigroup | Promise

Both Semigroup instances combined

Example

const {concat} = require('futils').operation;

const nums = [1, 2, 3];

concat([4, 5, 6], nums); // -> [1, 2, 3, 4, 5, 6]
concat([4, 5, 6]);       // -> (Semigroup -> Semigroup)

(static) doM(f) → {any}

The doM function, inspired by Haskell do notation. Works with all Monads as well as with Promises

Source:

operation/doM.js, line 17

Parameters:

Name	Type	Description
`f`	`Generator`	A generator function describing the computations

Returns:

Type:: any

The result of the computation

Example

const {Id} = require('futils').data;
const {doM} = require('futils').operation;

const result = doM(function * () {
    const a = yield Id.of(1);
    const b = yield Id.of(2 + a);
    return Id.of(b);
});

result.value; // -> 3

(static) drop(n, a) → {Array|Nil}

The drop function

Source:

operation/drop.js, line 23

Parameters:

Name	Type	Description
`n`	`Number`	Number of items to drop
`a`	`Array` \| `Cons`	The collection to drop the items from

Returns:

Type:: Array | Nil

Result of the drop

Example

const {drop} = require('futils').operation;

drop(1, ['a', 'b']); // -> ['b']
drop(1);             // -> (Array/Cons -> Array/Cons)

(static) equals(a, b) → {Boolean}

The equals function

Source:

operation/equals.js, line 16

Parameters:

Name	Type	Description
`a`	`any`	The first value to check for equality
`b`	`any`	The second value to check against

Returns:

Type:: Boolean

True if both are equal

Example

const {equals} = require('futils').operation;

equals(null, null);           // -> true
equals(1, 1);                 // -> true
equals([1, 2, 3], [1, 2, 3]); // -> true
equals(1, 2);                 // -> false
equals(null, 0);              // -> false
equals([4, 5, 6], [1, 2, 3]); // -> false
equals(1);                    // -> (a -> 1 == a)

(static) filter(f, a) → {Filterable}

The filter function. Filter takes a function which returns a Boolean and a Filterable collection and keeps only the items for which the function returns true.

Source:

operation/filter.js, line 15

Parameters:

Name	Type	Description
`f`	`function`	The function to filter with
`a`	`Filterable`	A Filterable interface implementing type

Returns:

Type:: Filterable

A new instance of the Filterable

Example

const {filter} = require('futils').operation;

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

filter(even, [1, 2, 3]); // -> [2]
filter(even);            // -> (Filterable -> Filterable)

(static) find(f, a) → {any|null}

The find function. It takes a predicate function and a Filterable implementing type and returns either the first element for which the predicate returns true or it returns null if the no element fulfills the predicate

Source:

operation/find.js, line 23

Parameters:

Name	Type	Description
`f`	`function`	The function to find with
`a`	`Filterable`	A Filterable interface implementing type

Returns:

Type:: any | null

Either the first found value or null

Example

const {find} = require('futils').operation;

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

find(even, [1, 2, 3]); // -> 2
find(even);            // -> (Filterable -> any)

(static) flat(f, a) → {Monad|Array}

The flat function. It can be used to flatten a nested data structure one level down

Source:

operation/flat.js, line 17

Parameters:

Name	Type	Description
`f`	`function`	The function to flat with
`a`	`Monad` \| `Array`	Any Array and/or Monad interface implementing type

Returns:

Type:: Monad | Array

A new instance of the Array or Monad

Example

const {flat} = require('futils').operation;

flat([['a'], ['b']]); // -> ['a', 'b']

(static) flatMap(f, a) → {Monad|Array|Promise}

The flatMap function which maps a function which returns a data structure over a structure of the same type and flattens the result one level. This is the natural behaviour of Promises when using the .then function, because if you return a Promise, the returned Promise has only a single level.

Source:

operation/flatMap.js, line 16

Parameters:

Name	Type	Description
`f`	`function`	The function to flatMap with
`a`	`Monad` \| `Array` \| `Promise`	Any Array and/or Monad interface implementing type, as well as Promise

Returns:

Type:: Monad | Array | Promise

A new instance of the Array or Monad or Promise

Example

const {flatMap} = require('futils').operation;

flatMap((a) => [a.toUpperCase()], ['a', 'b']); // -> ['A', 'B']
flatMap((a) => [a.toUpperCase()]);             // -> (Monad -> Monad)

(static) fold(A, a) → {Monoid}

The fold function. Usually fold is used to combine a set of values into a Monoid structure

Source:

operation/fold.js, line 16

Parameters:

Name	Type	Description
`A`	`Monoid`	The Monoid type constructor to fold into
`a`	`Foldable`	The values to fold

Returns:

Type:: Monoid

All values folded into the Monoid

Example

const {Sum} = require('futils').monoid;
const {fold} = require('futils').operation;

fold(Sum, [1, 2, 3, 4]); // -> Sum(10)
fold(Sum);               // -> (Foldable -> Sum)

(static) foldMap(A, a) → {Semigroup}

The foldMap function

Source:

operation/foldMap.js, line 16

Parameters:

Name	Type	Description
`A`	`function`	function returning a Semigroup to fold into
`a`	`Foldable`	The values to fold

Returns:

Type:: Semigroup

All values folded into the Semigroup

Example

const {Sum} = require('futils').monoid;
const {foldMap} = require('futils').operation;

const sum = (n) => n <= 0 ? Sum.empty() : Sum.of(n);

foldMap(sum, [1, -2, 3, 4]); // -> Sum(8)
foldMap(sum);                // -> (Foldable -> Sum)

(static) head(a) → {any|null}

The head function. It takes the first element from a List, Series or Array and returns it. If the the first element is either null or undefined, it returns null

Source:

operation/head.js, line 23

Parameters:

Name	Type	Description
`a`	`Array` \| `Cons`	The collection to take the head from

Returns:

Type:: any | null

Either the head or null

Example

const {head} = require('futils').operation;

head(['a', 'b']); // -> 'a'
head([]);         // -> null

(static) liftA(f, …a) → {Apply}

The liftA function. Use liftA to lift a curried function to 2 or more Apply implementing data structures

Source:

operation/liftA.js, line 16

Parameters:

Name	Type	Attributes	Description
`f`	`function`		The function to lift
`a`	`Apply`	<repeatable>	Applys to apply the function to

Returns:

Type:: Apply

A new instance of the Apply

Example

const {Id} = require('futils').data;
const {liftA} = require('futils').operation;

const add = (a) => (b) => (c) => a + b + c;

liftA(add, Id.of(1), Id.of(2), Id.of(3)); // -> Id(6)
liftA(add);                               // -> (Apply -> Apply -> Apply -> Apply)

(static) map(f, a) → {Functor|Promise}

The map function. Map takes a function and maps it over the value(s) of a data structure. It returns a new structure of the same type. This is the natural behaviour of Promises when using the .then function, except that if you return a Promise with the value inside it, the returned Promise has only a single level (it naturally flattens).

Source:

operation/map.js, line 16

Parameters:

Name	Type	Description
`f`	`function`	The function to map with
`a`	`Functor` \| `Promise`	A Functor interface implementing type or a Promise

Returns:

Type:: Functor | Promise

A new instance of the Functor or Promise

Example

const {map} = require('futils').operation;

map((a) => a.toUpperCase(), ['a', 'b']); // -> ['A', 'B']
map((a) => a.toUpperCase());             // -> (Functor -> Functor)

(static) nub(a) → {Array|Cons|Nil}

The nub function removes duplicates from either a List or an Array

Source:

operation/nub.js, line 18

Parameters:

Name	Type	Description
`a`	`Array` \| `Cons` \| `Nil`	The collection to remove duplicates from

Returns:

Type:: Array | Cons | Nil

A new collection with all duplicates removed

Example

const {nub} = require('futils').operation;

nub(['a', 'b', 'a']); // -> ['a', 'b']
nub([]);              // -> []

(static) nubBy(f, a) → {Array|Cons|Nil}

The nubBy function, which removes duplicates from either a List or an Array with a predicate function. The predicate function has to return true for elements which should be removed

Source:

operation/nubby.js, line 20

Parameters:

Name	Type	Description
`f`	`function`	The predicate function
`a`	`Array` \| `Cons` \| `Nil`	The collection to remove duplicates from

Returns:

Type:: Array | Cons | Nil

A new collection with all duplicates removed

Example

const {nubBy} = require('futils').operation;

const eq = (a, b) => a === b;

nubBy(eq, ['a', 'b', 'a']); // -> ['a', 'b']
nubBy(eq, []);              // -> []

(static) proMap(f, g, B) → {ProFunctor|function}

The proMap function is useful when working with ProFunctor implementing types

Version:

3.1.0

Source:

operation/proMap.js, line 17

Parameters:

Name	Type	Description
`f`	`function`	A failure/lhs handling function
`g`	`function`	A success/rhs handling function
`B`	`ProFunctor` \| `function`	The ProFunctor to proMap over

Returns:

Type:: ProFunctor | function

A new instance of the ProFunctor

Example

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


// strToChars :: String -> [Char]
const strToChars = a => a.split('');

// countChars :: [Char] -> Number
const countChars = as => as.length;

// removeChars :: [Char] -> [Char] -> [Char]
const removeChars = bs -> as -> as.filter(a => bs.every(b => a !== b));

// prog :: IO([Char] -> [Char])
const prog = IO(removeChars(['a', 'e', 'i', 'o', 'u']));

proMap(strToChars, countChars, prog);  // -> IO(String -> Number)

(static) prop(a, b) → {any|null}

The prop function, which allows to extract properties or indexes. If the property or index is missing, prop returns null

Source:

operation/prop.js, line 20

Parameters:

Name	Type	Description
`a`	`String` \| `Number`	The key or index to get
`b`	`Object` \| `Array` \| `Map`	The structure to extract from

Returns:

Type:: any | null

Value of the property or index

Example

const {prop} = require('futils').operation;

const obj = {a: 1, b: 2, c: 3};
const arr = [1, 2, 3];
const map = new Map([['a', 1], ['b', 2], ['c', 3]]);

prop('a', obj); // -> 1
prop('a', map); // -> 1
prop(0, arr);   // -> 1
prop('a');      // -> (b -> b.a)

(static) reduce(f, a, a) → {any}

The reduce function. Reduces the values inside a structure to a single value

Source:

operation/reduce.js, line 16

Parameters:

Name	Type	Description
`f`	`function`	The function to reduce with
`a`	`any`	A value to reduce into
`a`	`Foldable`	A Foldable interface implementing type

Returns:

Type:: any

All values reduced into one value

Example

const {reduce} = require('futils').operation;

reduce((a, b) => a + b, '', ['a', 'b']); // -> 'ab'
reduce((a, b) => a + b);                 // -> (a -> Foldable -> a)

(static) reduceRight(f, a, a) → {any}

The reduceRight function. Reduces the values inside a structure to a single value. Starts with the last value

Source:

operation/reducer.js, line 16

Parameters:

Name	Type	Description
`f`	`function`	The function to reduce with
`a`	`any`	A value to reduce into
`a`	`Foldable`	A Foldable interface implementing type

Returns:

Type:: any

All values reduced into one value

Example

const {reduceRight} = require('futils').operation;

reduceRight((a, b) => a + b, '', ['a', 'b']); // -> 'ba'
reduceRight((a, b) => a + b);                 // -> (a -> Foldable -> a)

(static) sequence(A, a) → {Applicative}

The sequence function

Source:

operation/sequence.js, line 16

Parameters:

Name	Type	Description
`A`	`Applicative`	Applicative type constructor to sequence into
`a`	`Traversable` \| `Array`	A type that implements the Traversable interface

Returns:

Type:: Applicative

A new Applicative

Example

const {Id} = require('futils').data;
const {sequence} = require('futils').operation;

const ids = [Id.of(1), Id.of(2), Id.of(3)];

sequence(Id, ids); // -> Id([1, 2, 3])
sequence(Id);      // -> (Traversable -> Applicative)

(static) tail(a) → {Array|Cons|Nil}

The tail function. It takes all but the first element from a List, Series or Array(-like) and returns it

Source:

operation/tail.js, line 22

Parameters:

Name	Type	Description
`a`	`Array` \| `Cons`	The collection to take the tail from

Returns:

Type:: Array | Cons | Nil

Either the tail or a Array

Example

const {tail} = require('futils').operation;

tail(['a', 'b']); // -> ['b']
tail([]);         // -> []

(static) take(n, a) → {Array|Nil}

The take function

Source:

operation/take.js, line 20

Parameters:

Name	Type	Description
`n`	`Number`	Number of items to take
`a`	`Array` \| `Cons`	The collection to take the items from

Returns:

Type:: Array | Nil

Result of the take

Example

const {take} = require('futils').operation;

take(1, ['a', 'b']); // -> ['a']
take(1);             // -> (Array/Cons -> Array/Cons)

(static) traverse(f, A, a) → {Applicative}

The traverse function

Source:

operation/traverse.js, line 16

Parameters:

Name	Type	Description
`f`	`function`	The function to traverse with
`A`	`Applicative`	Applicative type constructor to traverse into
`a`	`Traversable` \| `Array`	A type that implements the Traversable interface

Returns:

Type:: Applicative

A new Applicative

Example

const {Id} = require('futils').data;
const {traverse} = require('futils').operation;

const even = (n) => Id.of(n % 2 === 0);

traverse(even, Id, [1, 2, 3]); // -> Id([false, true, false])
traverse(even);                // -> (Applicative -> Traversable -> Applicative)

(static) zip(a, b) → {Array}

The zip function combines the contents of two arrays into pairs of a single array.

Since:

3.1.2

Source:

operation/zip.js, line 18

Parameters:

Name	Type	Description
`a`	`Array`	The first array of values
`b`	`Array`	The second array of values

Returns:

Type:: Array

A new array of combined values from a and b

Example

const {zip} = require('futils').operation;

zip([1, 2], [3, 4, 5]); // -> [[1, 3], [2, 4]]
zip([1, 2]);                 // -> (Array a -> Array [Number, a]

(static) zipWith(f, a, b) → {Array}

The zipWith function allows to combine the contents of two arrays with the help of a combiner function.

Since:

3.1.2

Source:

operation/zipWith.js, line 28

Parameters:

Name	Type	Description
`f`	`function`	The function to map with
`a`	`Array`	The first array of values
`b`	`Array`	The second array of values

Returns:

Type:: Array

A new array of combined values from a and b

Example

const {zipWith} = require('futils').operation;

const zipper = (a, b) => a + b;

zipWith(zipper, [1, 2], [3, 4]); // -> [4, 6]
zipWith(zipper);                 // -> (Array a -> Array b -> Array c)

operation

Methods

(static) alt(o, a) → {Alt}

Parameters:

Returns:

Example

(static) ap(af, a) → {Functor|Promise}

Parameters:

Returns:

Example

(static) biMap(f, g, B) → {BiFunctor}

Parameters:

Returns:

Example

(static) caseOf(a, b) → {any}

Parameters:

Returns:

Examples

(static) concat(a, b) → {Semigroup|Promise}

Parameters:

Returns:

Example

(static) doM(f) → {any}

Parameters:

Returns:

Example

(static) drop(n, a) → {Array|Nil}

Parameters:

Returns:

Example

(static) equals(a, b) → {Boolean}

Parameters:

Returns:

Example

(static) filter(f, a) → {Filterable}

Parameters:

Returns:

Example

(static) find(f, a) → {any|null}

Parameters:

Returns:

Example

(static) flat(f, a) → {Monad|Array}

Parameters:

Returns:

Example

(static) flatMap(f, a) → {Monad|Array|Promise}

Parameters:

Returns:

Example

(static) fold(A, a) → {Monoid}

Parameters:

Returns:

Example

(static) foldMap(A, a) → {Semigroup}

Parameters:

Returns:

Example

(static) head(a) → {any|null}

Parameters:

Returns:

Example

(static) liftA(f, …a) → {Apply}

Parameters:

Returns:

Example

(static) map(f, a) → {Functor|Promise}

Parameters:

Returns:

Example

(static) nub(a) → {Array|Cons|Nil}

Parameters:

Returns:

Example

(static) nubBy(f, a) → {Array|Cons|Nil}

Parameters:

Returns:

Example

(static) proMap(f, g, B) → {ProFunctor|function}

Parameters: