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(``)
)
Returns Array a concatenated list of all applicatives applied to all values
join
string.prototype.join but curried
Parameters
Examples
import {join} from 'f-utility'
join(`x`, [1,2,3])
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
Examples
import {sort} from 'f-utility'
sort((x) => x % 2, [1,2,3,4,5,6,7,8])
Returns Array sorted
difference
get the difference between two arrays
Parameters
Examples
import {difference} from 'f-utility'
difference([1,2,3], [2,4,6])
difference([2,4,6], [1,2,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
Examples
import {symmetricDifference} from 'f-utility'
difference([1,2,3], [1,2])
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)
alterIndex(-1, () => `x`, input)
Returns Array an altered copy of the original array
chain
functor.chain(fn) but curried and fast
Parameters
Examples
import {chain} from 'f-utility'
const split = (x) => x.split(``)
const flatSplit = chain(split)
const a = flatSplit([`chain`, `is`, `flatMap`])
console.log(a)
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)
max(20, 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))
fold(I, I, saferDivide(1, 0))
Returns any the result of the fold
filter
array.filter(fn) but inverted order, curried and fast
Parameters
Examples
import {filter} from 'f-utility'
filter((x) => x % 2 === 0, [1,2,3,4,5,6,7,8])
Returns Array filtered iterable
flip
take a function, flip the two parameters being passed to it, curry it
Parameters
Examples
import {flip} from 'f-utility'
const divide = (a, b) => a / b
const ivideday = flip(divide)
divide(1, 5)
ivideday(1, 5)
Returns any the result of invoking function with two inverted parameters
fork
a delegatee last function for Future.fork ing
Parameters
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)
semiSafeOddity(4)
Returns any the result of the fork
invert
Parameters
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)
isntID(123)
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)
isntID(123)
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`)
Returns Array aggregated values from invoking a given function
map
functor.map(fn) but curried and fast (though will delegate to the functor)
Parameters
Examples
import {map} from 'f-utility'
const add1 = map((x) => x + 1)
add1([1,2,3])
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)
equalsID(SAFE_ID)
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)
gt(100, 100)
gt(100, 101)
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)
gte(100, 100)
gte(100, 101)
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)
lt(100, 100)
lt(100, 101)
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)
lte(100, 100)
lte(100, 101)
Returns boolean whether a > b
round
convenience method for Math.round
Parameters
Examples
import {round} from 'f-utility'
round(10.3)
round(10.9)
Returns number rounded number
add
add things
Parameters
Examples
import {add} from 'f-utility'
add(4, 2)
Returns number sum
subtract
subtract things
Parameters
Examples
import {subtract} from 'f-utility'
subtract(4, 2)
Returns number subtracted
multiply
multiply things
Parameters
Examples
import {multiply} from 'f-utility'
multiply(4, 2)
Returns number multiplied
divide
divide things
Parameters
Examples
import {divide} from 'f-utility'
divide(4, 2)
Returns number divided
pow
exponentiate things
Parameters
Examples
import {pow} from 'f-utility'
pow(4, 2)
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
Examples
import {keys} from 'f-utility'
keys({a: 1, b: 2})
Returns Array an array of keys
values
Parameters
Examples
import {values} from 'f-utility'
values({a:1, b: 2, c: 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
Examples
import {freeze} from 'f-utility'
const immutable = freeze({a: 1, b: 2})
immutable.a = 5
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})
Returns Object a merged object
merge
object.assign but enforced as a binary function
Parameters
Examples
import {merge} from 'f-utility'
merge({c: 3}, {a: 1, b: 2})
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
Examples
import {entries} from 'f-utility'
entries({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
Examples
import {toPairs} from 'f-utility'
toPairs({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]])
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)
Returns Object a mapped object
mapValues
a simple object value-only tuple-mapper
Parameters
Examples
import {mapValues} from 'f-utility'
const input = {
a: 1,
b: 2,
c: 3
}
const fn = (v) => (v * 2)
mapValues(fn, input)
Returns Object a mapped object
mapKeys
a simple object key-only tuple-mapper
Parameters
Examples
import {mapKeys} from 'f-utility'
const input = {
a: 1,
b: 2,
c: 3
}
const fn = (v) => `__${v}`
mapKeys(fn, input)
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`}}})
pathOr(`default`, [`a`, `b`, `c`], {x: {y: {z: `actual`}}})
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`}}})
pathOr([`a`, `b`, `c`], {x: {y: {z: `actual`}}})
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`})
pathOr(`default`, `c`, {z: `actual`})
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`})
path(`c`, {z: `actual`})
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
Examples
import {random} from 'f-utility'
const {floor} = random
floor(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)
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(``))
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)
take(true, a2e)
take(false, a2e)
take(false, a2e)
take(true, a2eObject)
take(true, a2eObject)
take(false, a2eObject)
take(false, a2eObject)
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
Examples
import {random} from 'f-utility'
const {pick} = random
pick(`abcde`.split(``))
pick(`abcde`.split(``))
pick(`abcde`.split(``))
random.grab
partially-applied take - pull values randomly from an array or an object
Parameters
Examples
import {random} from 'f-utility'
const {pick} = random
pick(`abcde`.split(``))
pick(`abcde`.split(``))
pick(`abcde`.split(``))
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)
allot(3, a2e)
allot(3, a2e)
const a2eObject = {a: 1, b: 2, c: 3, d: 4, e: 5}
allot(3, a2eObject)
allot(3, a2eObject)
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)
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)
Returns string word
random
Simple wrap for round( x * random )
Parameters
Examples
import {random} from 'f-utility'
random(5)
random(5)
random(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])
Returns any mixed reduction
reject
array.filter((x) => !fn(x)) but inverted order, curried and fast
Parameters
Examples
import {reject} from 'f-utility'
reject((x) => x % 2 !== 0, [1,2,3,4,5,6,7,8])
Returns Array filtered iterable
split
string.split(x) but delegatee last
Parameters
Examples
import {split} from `f-utility`
split(`x`, `1x2x3`)
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
Examples
import {trim} from `f-utility`
trim(` 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`)
ternary(false, `a`, `b`)
Returns mixed a / b
triplet
a ternary statement, but curried and lazy and where each case is a function
Parameters
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)
triplet(test, double, half, 5)
Returns any anything
isTypeof
returns boolean based on type
Parameters
Examples
import {isTypeof} from 'f-utility'
isTypeof(`boolean`, true)
isTypeof(`boolean`, `nope`)
Returns boolean whether x is typeof type
isBoolean
test whether something is a boolean
Parameters
Examples
import {isBoolean} from 'f-utility'
isBoolean(true)
isBoolean(1)
isBoolean(`a`)
isBoolean([`a`])
Returns boolean true if the input is a boolean
isNumber
test whether something is a number
Parameters
Examples
import {isNumber} from 'f-utility'
isNumber(true)
isNumber(1)
isNumber(`a`)
isNumber([`a`])
Returns boolean true if the input is a number
isFunction
test whether something is a function
Parameters
Examples
import {isFunction} from 'f-utility'
isFunction(true)
isFunction(1)
isFunction(`a`)
isFunction([`a`])
isFunction(() => {})
Returns boolean true if the input is a function
isString
test whether something is a string
Parameters
Examples
import {isString} from 'f-utility'
isString(true)
isString(1)
isString(`a`)
isString([`a`])
isString(() => {})
Returns boolean true if the input is a string
isNil
test whether something is null-ish
Parameters
Examples
import {isNil} from 'f-utility'
isNil(true)
isNil(1)
isNil(`a`)
isNil([`a`])
isNil({})
isNil(null)
isNil(undefined)
Returns boolean true if the input is null-ish
isObject
test whether something is an object
Parameters
Examples
import {isObject} from 'f-utility'
isObject(true)
isObject(1)
isObject(`a`)
isObject([`a`])
isObject({})
isObject(null)
Returns boolean true if the input is a object
isArray
test whether something is an array
Parameters
Examples
import {isArray} from 'f-utility'
isArray(true)
isArray(1)
isArray(`a`)
isArray([`a`])
isArray({})
isArray(null)
isArray(undefined)
Returns boolean true if the input is an array
isDistinctObject
test whether something is a non-null object which isn't an array
Parameters
Examples
import {isDistinctObject} from 'f-utility'
isDistinctObject(true)
isDistinctObject(1)
isDistinctObject(`a`)
isDistinctObject([`a`])
isDistinctObject({})
isDistinctObject(null)
isDistinctObject(undefined)
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
Examples
import {some} from 'f-utility'
some((x) => x === `j`, [`j`, `k`, `l`])
some((x) => x === `z`, [`j`, `k`, `l`])
Returns boolean
every
array.every(fn) but curried and lazy
Parameters
Examples
import {isNumber, every} from 'f-utility'
every(isNumber, [0, 1, 2, 3, 4])
every(isNumber, [0, 1, 2, 3, `four`])
Returns boolean