f-utility

A collection of common, sometimes functional utilities. Uses fast.js + katsu-curry

Changelog

• 3.0.0 - a complete re-imagining of the codebase
• 3.0.1 - fixed exported functions
• 3.0.2 - fixed functor delegation
• 3.0.4 - added sort, keys, freeze, assign, and length
• 3.0.5 - fixed allot, and the partially applied forms grab and take
• 3.0.7 - fixed exports again
• 3.0.8 - added path, pathOr, prop, and propOr
• 3.0.9 - added merge, pathIs, pathEq, propIs, propEq and equals
• 3.1.0 - updated katsu-curry, whose public API changed
• 3.1.1 - added chain
• 3.2.0 - added invert, not, not1, not2, not3 and updated documentation
• 3.2.1 - added toPairs / entries and fromPairs
• 3.2.2 - added ap, fold
• 3.2.3 - added isDistinctObject
• 3.2.4 - added range, speed improvements
• 3.3.0 - optimizations
• 3.3.1 - updated ap spec, added bunch of string prototype methods, and added dont-break for better safety in future upgrades
• 3.6.0 - a number of minor breaking changes have been introduced, more details are available here

API

ap

Apply a list of functions to a list of values

Parameters

• applicative (function | Array<functions>) a single function or array of applicatives
• functor Array an array of values

Examples

import {ap} from 'f-utility'
ap([
  (x) => x.toUppercase(),
  (x) => `${x} batteries`
 ],
 `abc`.split(``)
) // [`A`, `B`, `C`, `a batteries`, `b batteries`, `c batteries`]

Returns Array a concatenated list of all applicatives applied to all values

join

string.prototype.join but curried

Parameters

• delimiter string
• list Array

Examples

import {join} from 'f-utility'
join(`x`, [1,2,3]) // `1x2x3`

Returns string joined

concat

return a new array with some other stuff added to it

Parameters

• null-null Array an array
• null-null Array another array

Returns Array combined array

sort

string.prototype.sort but curried

Parameters

• fn function
• functor Array

Examples

import {sort} from 'f-utility'
sort((x) => x % 2, [1,2,3,4,5,6,7,8]) // [ 0, 2, 4, 6, 8, 9, 7, 5, 3, 1 ]

Returns Array sorted

difference

get the difference between two arrays

Parameters

• bList Array an array
• aList Array an array

Examples

import {difference} from 'f-utility'
difference([1,2,3], [2,4,6]) // [4, 6]
difference([2,4,6], [1,2,3]) // [1, 3]

Returns Array filtered array with differences between the two arrays

symmetricDifference

get both the differences between two arrays, and if one difference is longer, return it

Parameters

• a Array an array
• b Array an array

Examples

import {symmetricDifference} from 'f-utility'
difference([1,2,3], [1,2]) // [3]

Returns Array filtered array with differences between the two arrays

alterIndex

alter the index of a given array input

Parameters

• index number the index to alter
• fn Function the function to describe the alteration
• input Array the input array

Examples

import {alterIndex} from 'f-utility'
const input = `abcde`.split(``)
alterIndex(0, () => `butts`, input) // [`butts`, `b`, `c`, `d`, `e`]
// also works with negative indicies
alterIndex(-1, () => `x`, input) // [`a`, `b`, `c`, `d`, `x`]

Returns Array an altered copy of the original array

chain

functor.chain(fn) but curried and fast

Parameters

• predicate function
• iterable (Array | Monad)

Examples

import {chain} from 'f-utility'
const split = (x) => x.split(``)
const flatSplit = chain(split)
const a = flatSplit([`chain`, `is`, `flatMap`])
console.log(a) // [ 'c', 'h', 'a', 'i', 'n', 'i', 's', 'f', 'l', 'a', 't', 'M', 'a', 'p' ]

Returns (Array | Monad) flat mapped iterable

choice

takes a function that takes two parameters and returns a ternary result

Parameters

• cnFn function
• a any anything
• b any anything

Examples

import {choice} from 'f-utility'
const max = choice((a, b) => a > b)
max(500, 20) // 500
max(20, 500) // 500

Returns any result

fold

a delegatee last function for Either.fold ing

Parameters

• badPath function a function
• goodPath function a function
• either (Right | Left) an Either

Examples

import {I, I, pipe, fold} from 'f-utility'
import {Left, Right} from 'fantasy-eithers'
const saferDivide = (a, b) => (b !== 0 ? Right(a / b) : Left(`Cannot divide by zero`))
fold(I, I, saferDivide(1, 2)) // 0.5
fold(I, I, saferDivide(1, 0)) // `Cannot divide by zero`

Returns any the result of the fold

filter

array.filter(fn) but inverted order, curried and fast

Parameters

• predicate function
• iterable Array

Examples

import {filter} from 'f-utility'
filter((x) => x % 2 === 0, [1,2,3,4,5,6,7,8]) // [2,4,6,8]

Returns Array filtered iterable

flip

take a function, flip the two parameters being passed to it, curry it

Parameters

• fn function a function

Examples

import {flip} from 'f-utility'
const divide = (a, b) => a / b
const ivideday = flip(divide)
divide(1, 5) // 0.2
ivideday(1, 5) // 5

Returns any the result of invoking function with two inverted parameters

fork

a delegatee last function for Future.fork ing

Parameters

• badPath function a function
• goodPath function a function
• future Future

Examples

import {pipe, fork, I} from 'f-utility'
import {trace} from 'xtrace'
import F from 'fluture'
const odd = (x) => (x % 2 === 0 ? F.of(x) : F.reject(`${x} is odd`))
const semiSafeOddity = pipe(
  odd,
  trace(`oddity`),
  fork(console.warn, console.log)
)
semiSafeOddity(5) // console.warn(`5 is odd`)
semiSafeOddity(4) // console.log(4)

Returns any the result of the fork

invert

Parameters

• x any any

Examples

import {pipe, invert} from 'f-utility'
const isOdd = pipe(
  (x) => x % 2 === 0,
  invert
)

Returns boolean !x

not

return the result of inverting a nullary function

Parameters

• fn function a function to invert the result of

Examples

import {not, equal} from 'f-utility'
const ID = 12345
const isntID = not(equal(ID))
isntID(ID) // false
isntID(123) // true

Returns function function

not1

return the result of inverting a unary function

Parameters

• fn function a function to invert the result of
• a any a parameter to pass to the function

Examples

import {not, equal} from 'f-utility'
const ID = 12345
const isntID = not1(equal, ID)
isntID(ID) // false
isntID(123) // true

Returns function inverted function

not2

return the result of inverting a binary function

Parameters

• fn function a function to invert the result of
• a any a parameter to pass to the function
• b any a parameter to pass to the function

Returns function inverted function

not3

return the result of inverting a tertiary function

Parameters

• fn function a function to invert the result of
• a any a parameter to pass to the function
• b any a parameter to pass to the function
• c any a parameter to pass to the function

Returns function inverted function

iterate

call a function x times and aggregate the result

Parameters

• total number a total number of iterations
• fn function a function to invoke x times

Examples

import {iterate} from 'f-utility'
iterate(5, () => `x`) // [`x`, `x`, `x`, `x`, `x`]

Returns Array aggregated values from invoking a given function

map

functor.map(fn) but curried and fast (though will delegate to the functor)

Parameters

• fn function
• functor Array

Examples

import {map} from 'f-utility'
const add1 = map((x) => x + 1)
add1([1,2,3]) // [2,3,4]

Returns Array mapped iterable

equals

=== comparison

Parameters

• a any anything
• b any anything

Examples

import {equals} from 'f-utility'
const SAFE_ID = 123456
const equalsID = equals(SAFE_ID)
equalsID(200) // false
equalsID(SAFE_ID) // true

Returns boolean whether a triple-equals b

greaterThan

comparison but inverted

Parameters

• b any anything
• a any anything

Examples

import {greaterThan, gt} from 'f-utility'
gt(100, 99) // false
gt(100, 100) // false
gt(100, 101) // true

Returns boolean whether a > b

greaterThanOrEqualTo

= comparison but inverted

Parameters

• b any anything
• a any anything

Examples

import {greaterThanOrEqualTo, gte} from 'f-utility'
gte(100, 99) // false
gte(100, 100) // true
gte(100, 101) // true

Returns boolean whether a > b

lessThan

< comparison but inverted

Parameters

• b any anything
• a any anything

Examples

import {lessThan, lt} from 'f-utility'
lt(100, 99) // true
lt(100, 100) // false
lt(100, 101) // false

Returns boolean whether a > b

lessThanOrEqualTo

< comparison but inverted

Parameters

• b any anything
• a any anything

Examples

import {lessThanOrEqualTo, lte} from 'f-utility'
lte(100, 99) // true
lte(100, 100) // true
lte(100, 101) // false

Returns boolean whether a > b

round

convenience method for Math.round

Parameters

• x number a number

Examples

import {round} from 'f-utility'
round(10.3) // 10
round(10.9) // 11

Returns number rounded number

add

add things

Parameters

• a number a number
• b number b number

Examples

import {add} from 'f-utility'
add(4, 2) // 6

Returns number sum

subtract

subtract things

Parameters

• a number a number
• b number b number

Examples

import {subtract} from 'f-utility'
subtract(4, 2) // -2

Returns number subtracted

multiply

multiply things

Parameters

• a number a number
• b number b number

Examples

import {multiply} from 'f-utility'
multiply(4, 2) // 8

Returns number multiplied

divide

divide things

Parameters

• a number a number
• b number b number

Examples

import {divide} from 'f-utility'
divide(4, 2) // 0.5

Returns number divided

pow

exponentiate things

Parameters

• a number a number
• b number b number

Examples

import {pow} from 'f-utility'
pow(4, 2) // 16

Returns number b to the power of a

keys

Object.keys https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys

Parameters

• a Object an object

Examples

import {keys} from 'f-utility'
keys({a: 1, b: 2}) // [`a`, `b`]

Returns Array an array of keys

values

Parameters

• x Object input

Examples

import {values} from 'f-utility'
values({a:1, b: 2, c: 3}) // [1, 2, 3]

Returns Array<Strings> values - an array of properties

freeze

Object.freeze https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze

Parameters

• a Object an object

Examples

import {freeze} from 'f-utility'
const immutable = freeze({a: 1, b: 2})
immutable.a = 5 // throws error

Returns Object a frozen object

assign

Object.assign https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign

Parameters

• a Object any number of objects

Examples

import {assign} from 'f-utility'
assign({c: 3}, {a: 1, b: 2}) // {a: 1, b: 2, c: 3}

Returns Object a merged object

merge

object.assign but enforced as a binary function

Parameters

• a Object object a
• b Object object b

Examples

import {merge} from 'f-utility'
merge({c: 3}, {a: 1, b: 2}) // {a: 1, b: 2, c: 3}

Returns Object c - the results of merging a and b

entries

Object.entries shim https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries

Parameters

• o Object an object

Examples

import {entries} from 'f-utility'
entries({a: 1, b: 2}) // [[`a`, 1], [`b`, 2]]

Returns Array an array of tuples [key, value] pairs

toPairs

An alias of entries https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries

Parameters

• o Object an object

Examples

import {toPairs} from 'f-utility'
toPairs({a: 1, b: 2}) // [[`a`, 1], [`b`, 2]]

Returns Array an array of tuples [key, value] pairs

fromPairs

convert a list of key value pairs into an object

Parameters

• null-null Array a list of [key, value] pairs

Examples

import {fromPairs} from 'f-utility'
fromPairs([[`a`, 1], [`b`, 2]]) // {a: 1, b: 2}

Returns Object merged results

mapTuples

a simple object tuple-mapper

Parameters

• fn Function a function which maps over [key, value] tuples
• o Object object

Examples

import {mapTuples} from 'f-utility'
const input = {
  a: 1,
  b: 2,
  c: 3
}
const fn = ([k, v]) => ([k.toUpperCase(), v * 2])
mapTuples(fn, input) // {A: 2, B: 4, C: 6}

Returns Object a mapped object

mapValues

a simple object value-only tuple-mapper

Parameters

• fn Function a function which maps over values only
• o Object object

Examples

import {mapValues} from 'f-utility'
const input = {
  a: 1,
  b: 2,
  c: 3
}
const fn = (v) => (v * 2)
mapValues(fn, input) // {a: 2, b: 4, c: 6}

Returns Object a mapped object

mapKeys

a simple object key-only tuple-mapper

Parameters

• fn Function a function which maps over values only
• o Object object

Examples

import {mapKeys} from 'f-utility'
const input = {
  a: 1,
  b: 2,
  c: 3
}
const fn = (v) => `__${v}`
mapKeys(fn, input) // {__a: 1, __b: 2, __c: 3}

Returns Object a mapped object

pathOr

Grab a nested value from an object or return a default

Parameters

• def any a default value
• lenses Array<string> a list of nested properties
• input any an object to grab things from

Examples

import {pathOr} from 'f-utility'
pathOr(`default`, [`a`, `b`, `c`], {a: {b: {c: `actual`}}}) // `actual`
pathOr(`default`, [`a`, `b`, `c`], {x: {y: {z: `actual`}}}) // `default`

Returns any a nested value or default

path

Grab a nested value from an object

Parameters

• lenses Array<string> a list of nested properties
• input any an object to grab things from

Examples

import {path} from 'f-utility'
pathOr([`a`, `b`, `c`], {a: {b: {c: `actual`}}}) // `actual`
pathOr([`a`, `b`, `c`], {x: {y: {z: `actual`}}}) // null

Returns any a nested value or null

propOr

Grab a property from an object or return a default

Parameters

• def any a default value
• property string a property
• input any an object to grab things from

Examples

import {propOr} from 'f-utility'
pathOr(`default`, `c`, {c: `actual`}) // `actual`
pathOr(`default`, `c`, {z: `actual`}) // `default`

Returns any a property or default

prop

Grab a property from an object or return null

Parameters

• property string a property
• input any an object to grab things from

Examples

import {prop} from 'f-utility'
path(`c`, {c: `actual`}) // `actual`
path(`c`, {z: `actual`}) // null

Returns any a property or null

pathIs

Grab a property from an object and compare it with a given function

Parameters

• is function an assertion function
• lenses Array<strings> a property
• input any an object to grab things from

Returns boolean a truthy value

pathEq

Grab a property from an object and compare it with a given value via ===

Parameters

• equiv any equivalent value
• lenses Array<strings> a property
• input any an object to grab things from

Returns boolean a truthy value

propEq

Grab a property from an object and compare it with a given function

Parameters

• equiv any equivalent value
• property string a property
• input any an object to grab things from

Returns boolean a truthy value

propEq

Grab a property from an object and compare it with a given value via ===

Parameters

• equiv any equivalent value
• property string a property
• input any an object to grab things from

Returns boolean a truthy value

random.floor

Simple wrap for floor( x * random )

Parameters

• x number a number

Examples

import {random} from 'f-utility'
const {floor} = random
floor(0) // 0

Returns number x - a rounded number

random.floorMin

Simple wrap for floor( x * random ) + min

Parameters

• min number a number to be the minimum
• x number a number to be randomly rounded

Examples

import {random} from 'f-utility'
const {floorMin} = random
floor(0, 0) // 0

Returns number a number that is randomly above the min

random.shuffle

Shuffle the contents of an array

Parameters

• list Array an array to be shuffled

Examples

import {random} from 'f-utility'
const {shuffle} = random
const shuffle(`abcde`.split(``)) // randomly shuffled array 

Returns Array shuffled

random.take

Take values randomly from objects or arrays

Parameters

• encase boolean do we want to return the unwrapped value?
• input mixed an array or object

Examples

import {random} from 'f-utility'
const {take} = random
const a2e = `abcde`.split(``)
const a2eObject = {a: 1, b: 2, c: 3}
take(true, a2e) // [`a`]
take(true, a2e) // [`d`]
take(false, a2e) // `c`
take(false, a2e) // `b`
take(true, a2eObject) // {b: 2}
take(true, a2eObject) // {c: 3}
take(false, a2eObject) // 1
take(false, a2eObject) // 3

Returns mixed either random values from the object.values or the array values, possibly wrapped

random.pick

partially-applied take - pull values randomly from an array or an object

Parameters

• x (Array | Object) something to take values from

Examples

import {random} from 'f-utility'
const {pick} = random
pick(`abcde`.split(``)) // `a`
pick(`abcde`.split(``)) // `d`
pick(`abcde`.split(``)) // `b`

random.grab

partially-applied take - pull values randomly from an array or an object

Parameters

• x (Array | Object) something to take values from

Examples

import {random} from 'f-utility'
const {pick} = random
pick(`abcde`.split(``)) // [`a`]
pick(`abcde`.split(``)) // [`d`]
pick(`abcde`.split(``)) // [`b`]

random.allot

pull some number of values from an array or object

Parameters

• howMany number how many values to take
• ofThing mixed array or object

Examples

import {random} from 'f-utility'
const {allot} = random
const a2e = `abcde`.split(``)
allot(3, a2e) // [`d`, `b`, `c`]
allot(3, a2e) // [`a`, `e`, `c`]
allot(3, a2e) // [`e`, `b`, `a`]
const a2eObject = {a: 1, b: 2, c: 3, d: 4, e: 5}
allot(3, a2eObject) // {d: 4, e: 5, a: 1}
allot(3, a2eObject) // {a: 1, c: 3, a: 1}

Returns Array values

random.wordSource

generate a "word" of some known length

Parameters

• source Array<strings> which characters should be used?
• howLong number how many characters should be used?

Examples

import {random} from 'f-utility'
const {wordSource} = random
const dna = wordSource([`g`, `a`, `t`, `c`])
dna(7) // `gattaca`

Returns string word

random.word

generate a "word" of some known length

Parameters

• x number how many characters should be used?

Examples

import {random} from 'f-utility'
const {word} = random
word(5) // `lrmbs`

Returns string word

random

Simple wrap for round( x * random )

Parameters

• x number a number

Examples

import {random} from 'f-utility'
random(5) // 1
random(5) // 3
random(0) // 0

Returns number x - a rounded and randomized number

reduce

functor.reduce but curried and fast

Parameters

• fn function a reducer
• init any an initial value
• o (Array | Monad) iterable

Examples

import {reduce} from 'f-utility'
const sum = reduce((agg, x) => agg + x, 0)
sum([1, 2, 3, 4, 5]) // 15

Returns any mixed reduction

reject

array.filter((x) => !fn(x)) but inverted order, curried and fast

Parameters

• predicate function
• iterable Array

Examples

import {reject} from 'f-utility'
reject((x) => x % 2 !== 0, [1,2,3,4,5,6,7,8]) // [2,4,6,8]

Returns Array filtered iterable

split

string.split(x) but delegatee last

Parameters

• delimiter string
• string string to split

Examples

import {split} from `f-utility`
split(`x`, `1x2x3`) // [`1`, `2`, `3`]

Returns Array<strings>

replace

string.replace but delegatee last https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace

Parameters

• null-null string a string or a regular expression
• null-null function a string or a function

Returns string string with replacements

trim

string.trim() but delegatee last

Parameters

• string string to trim

Examples

import {trim} from `f-utility`
trim(`     20932 `) // `20932`

Returns string trimmed

ternary

a ternary statement, but curried and lazy

Parameters

• cn any anything to be evaluated as truthy
• a any anything
• b any anything

Examples

import {ternary} from `f-utility`
ternary(true, `a`, `b`) // `a`
ternary(false, `a`, `b`) // `b`

Returns mixed a / b

triplet

a ternary statement, but curried and lazy and where each case is a function

Parameters

• cnFn function anything to be evaluated as truthy
• aFn function a function
• bFn function b function
• o mixed input

Examples

import {triplet} from 'f-utility'
const test = (x) => x % 2 === 0
const double = (x) => x * 2
const half = (x) => x / 2
triplet(test, double, half, 100) // 200
triplet(test, double, half, 5) // 2.5

Returns any anything

isTypeof

returns boolean based on type

Parameters

• type string
• x any anything

Examples

import {isTypeof} from 'f-utility'
isTypeof(`boolean`, true) // true
isTypeof(`boolean`, `nope`) // false

Returns boolean whether x is typeof type

isBoolean

test whether something is a boolean

Parameters

• x any anything

Examples

import {isBoolean} from 'f-utility'
isBoolean(true) // true
isBoolean(1) // false
isBoolean(`a`) // false
isBoolean([`a`]) // false

Returns boolean true if the input is a boolean

isNumber

test whether something is a number

Parameters

• x any anything

Examples

import {isNumber} from 'f-utility'
isNumber(true) // false
isNumber(1) // true
isNumber(`a`) // false
isNumber([`a`]) // false

Returns boolean true if the input is a number

isFunction

test whether something is a function

Parameters

• x any anything

Examples

import {isFunction} from 'f-utility'
isFunction(true) // false
isFunction(1) // false
isFunction(`a`) // false
isFunction([`a`]) // false
isFunction(() => {}) // true

Returns boolean true if the input is a function

isString

test whether something is a string

Parameters

• x any anything

Examples

import {isString} from 'f-utility'
isString(true) // false
isString(1) // false
isString(`a`) // true
isString([`a`]) // false
isString(() => {}) // false

Returns boolean true if the input is a string

isNil

test whether something is null-ish

Parameters

• x any anything

Examples

import {isNil} from 'f-utility'
isNil(true) // false
isNil(1) // false
isNil(`a`) // false
isNil([`a`]) // false
isNil({}) // false
isNil(null) // true
isNil(undefined) // true

Returns boolean true if the input is null-ish

isObject

test whether something is an object

Parameters

• x any anything

Examples

import {isObject} from 'f-utility'
isObject(true) // false
isObject(1) // false
isObject(`a`) // false
isObject([`a`]) // true
isObject({}) // true
isObject(null) // true

Returns boolean true if the input is a object

isArray

test whether something is an array

Parameters

• x any anything

Examples

import {isArray} from 'f-utility'
isArray(true) // false
isArray(1) // false
isArray(`a`) // false
isArray([`a`]) // true
isArray({}) // false
isArray(null) // false
isArray(undefined) // false

Returns boolean true if the input is an array

isDistinctObject

test whether something is a non-null object which isn't an array

Parameters

• x any anything

Examples

import {isDistinctObject} from 'f-utility'
isDistinctObject(true) // false
isDistinctObject(1) // false
isDistinctObject(`a`) // false
isDistinctObject([`a`]) // false
isDistinctObject({}) // true
isDistinctObject(null) // false
isDistinctObject(undefined) // false

Returns boolean true if the input is an object that isn't an array and isn't null

some

array.some(fn) but curried and lazy

Parameters

• predicate function
• iterable Array

Examples

import {some} from 'f-utility'
some((x) => x === `j`, [`j`, `k`, `l`]) // true
some((x) => x === `z`, [`j`, `k`, `l`]) // false

Returns boolean

every

array.every(fn) but curried and lazy

Parameters

• predicate function
• iterable Array

Examples

import {isNumber, every} from 'f-utility'
every(isNumber, [0, 1, 2, 3, 4]) // true
every(isNumber, [0, 1, 2, 3, `four`]) // false

Returns boolean