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
, andlength
- 3.0.5 - fixed
allot
, and the partially applied formsgrab
andtake
- 3.0.7 - fixed exports again
- 3.0.8 - added
path
,pathOr
,prop
, andpropOr
- 3.0.9 - added
merge
,pathIs
,pathEq
,propIs
,propEq
andequals
- 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
andfromPairs
- 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 addeddont-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 applicativesfunctor
Array an array of values
Examples
// [`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
Examples
// `1x2x3`
Returns string joined
concat
return a new array with some other stuff added to it
Parameters
Returns Array combined array
sort
string.prototype.sort but curried
Parameters
Examples
// [ 0, 2, 4, 6, 8, 9, 7, 5, 3, 1 ]
Returns Array sorted
difference
get the difference between two arrays
Parameters
Examples
// [4, 6] // [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
Examples
// [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 alterfn
Function the function to describe the alterationinput
Array the input array
Examples
const input = `abcde` // [`butts`, `b`, `c`, `d`, `e`]// also works with negative indicies // [`a`, `b`, `c`, `d`, `x`]
Returns Array an altered copy of the original array
chain
functor.chain(fn) but curried and fast
Parameters
Examples
const split = xconst flatSplit = const a = console // [ '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
functiona
any anythingb
any anything
Examples
const max = // 500 // 500
Returns any result
fold
a delegatee last function for Either.fold ing
Parameters
Examples
const saferDivide = b !== 0 ? : // 0.5 // `Cannot divide by zero`
Returns any the result of the fold
filter
array.filter(fn) but inverted order, curried and fast
Parameters
Examples
// [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
const divide = a / bconst ivideday = // 0.2 // 5
Returns any the result of invoking function with two inverted parameters
fork
a delegatee last function for Future.fork ing
Parameters
Examples
const odd = x % 2 === 0 ? F : Fconst semiSafeOddity = // console.warn(`5 is odd`) // console.log(4)
Returns any the result of the fork
invert
Parameters
x
any any
Examples
const isOdd =
Returns boolean !x
not
return the result of inverting a nullary function
Parameters
fn
function a function to invert the result of
Examples
const ID = 12345const isntID = // false // true
Returns function function
not1
return the result of inverting a unary function
Parameters
fn
function a function to invert the result ofa
any a parameter to pass to the function
Examples
const ID = 12345const isntID = // false // true
Returns function inverted function
not2
return the result of inverting a binary function
Parameters
fn
function a function to invert the result ofa
any a parameter to pass to the functionb
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 ofa
any a parameter to pass to the functionb
any a parameter to pass to the functionc
any a parameter to pass to the function
Returns function inverted function
iterate
call a function x times and aggregate the result
Parameters
Examples
// [`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
Examples
const add1 = // [2,3,4]
Returns Array mapped iterable
equals
=== comparison
Parameters
a
any anythingb
any anything
Examples
const SAFE_ID = 123456const equalsID = // false // true
Returns boolean whether a triple-equals b
greaterThan
comparison but inverted
Parameters
b
any anythinga
any anything
Examples
// false // false // true
Returns boolean whether a > b
greaterThanOrEqualTo
= comparison but inverted
Parameters
b
any anythinga
any anything
Examples
// false // true // true
Returns boolean whether a > b
lessThan
< comparison but inverted
Parameters
b
any anythinga
any anything
Examples
// true // false // false
Returns boolean whether a > b
lessThanOrEqualTo
< comparison but inverted
Parameters
b
any anythinga
any anything
Examples
// true // true // false
Returns boolean whether a > b
round
convenience method for Math.round
Parameters
x
number a number
Examples
// 10 // 11
Returns number rounded number
add
add things
Parameters
Examples
// 6
Returns number sum
subtract
subtract things
Parameters
Examples
// -2
Returns number subtracted
multiply
multiply things
Parameters
Examples
// 8
Returns number multiplied
divide
divide things
Parameters
Examples
// 0.5
Returns number divided
pow
exponentiate things
Parameters
Examples
// 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
// [`a`, `b`]
Returns Array an array of keys
values
Parameters
x
Object input
Examples
// [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
const immutable = immutablea = 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
// {a: 1, b: 2, c: 3}
Returns Object a merged object
merge
object.assign but enforced as a binary function
Parameters
Examples
// {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
// [[`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
// [[`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
// {a: 1, b: 2}
Returns Object merged results
mapTuples
a simple object tuple-mapper
Parameters
Examples
const input = a: 1 b: 2 c: 3const fn = k v * 2 // {A: 2, B: 4, C: 6}
Returns Object a mapped object
mapValues
a simple object value-only tuple-mapper
Parameters
Examples
const input = a: 1 b: 2 c: 3const fn = v * 2 // {a: 2, b: 4, c: 6}
Returns Object a mapped object
mapKeys
a simple object key-only tuple-mapper
Parameters
Examples
const input = a: 1 b: 2 c: 3const fn = `__` // {__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 valuelenses
Array<string> a list of nested propertiesinput
any an object to grab things from
Examples
// `actual` // `default`
Returns any a nested value or default
path
Grab a nested value from an object
Parameters
Examples
// `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 valueproperty
string a propertyinput
any an object to grab things from
Examples
// `actual` // `default`
Returns any a property or default
prop
Grab a property from an object or return null
Parameters
property
string a propertyinput
any an object to grab things from
Examples
// `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 functionlenses
Array<strings> a propertyinput
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 valuelenses
Array<strings> a propertyinput
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 valueproperty
string a propertyinput
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 valueproperty
string a propertyinput
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
const floor = random // 0
Returns number x - a rounded number
random.floorMin
Simple wrap for floor( x * random ) + min
Parameters
Examples
const floorMin = random // 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
const shuffle = randomconst 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
const take = randomconst a2e = `abcde`const a2eObject = a: 1 b: 2 c: 3 // [`a`] // [`d`] // `c` // `b` // {b: 2} // {c: 3} // 1 // 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
Examples
const pick = random // `a` // `d` // `b`
random.grab
partially-applied take - pull values randomly from an array or an object
Parameters
Examples
const pick = random // [`a`] // [`d`] // [`b`]
random.allot
pull some number of values from an array or object
Parameters
howMany
number how many values to takeofThing
mixed array or object
Examples
const allot = randomconst a2e = `abcde` // [`d`, `b`, `c`] // [`a`, `e`, `c`] // [`e`, `b`, `a`]const a2eObject = a: 1 b: 2 c: 3 d: 4 e: 5 // {d: 4, e: 5, a: 1} // {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
const wordSource = randomconst dna = // `gattaca`
Returns string word
random.word
generate a "word" of some known length
Parameters
x
number how many characters should be used?
Examples
const word = random // `lrmbs`
Returns string word
random
Simple wrap for round( x * random )
Parameters
x
number a number
Examples
// 1 // 3 // 0
Returns number x - a rounded and randomized number
reduce
functor.reduce but curried and fast
Parameters
Examples
const sum = // 15
Returns any mixed reduction
reject
array.filter((x) => !fn(x)) but inverted order, curried and fast
Parameters
Examples
// [2,4,6,8]
Returns Array filtered iterable
split
string.split(x) but delegatee last
Parameters
Examples
// [`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
Returns string string with replacements
trim
string.trim() but delegatee last
Parameters
string
string to trim
Examples
// `20932`
Returns string trimmed
ternary
a ternary statement, but curried and lazy
Parameters
cn
any anything to be evaluated as truthya
any anythingb
any anything
Examples
// `a` // `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 truthyaFn
function a functionbFn
function b functiono
mixed input
Examples
const test = x % 2 === 0const double = x * 2const half = x / 2 // 200 // 2.5
Returns any anything
isTypeof
returns boolean based on type
Parameters
type
stringx
any anything
Examples
// true // false
Returns boolean whether x is typeof type
isBoolean
test whether something is a boolean
Parameters
x
any anything
Examples
// true // false // false // false
Returns boolean true if the input is a boolean
isNumber
test whether something is a number
Parameters
x
any anything
Examples
// false // true // false // false
Returns boolean true if the input is a number
isFunction
test whether something is a function
Parameters
x
any anything
Examples
// false // false // false // false // true
Returns boolean true if the input is a function
isString
test whether something is a string
Parameters
x
any anything
Examples
// false // false // true // false // false
Returns boolean true if the input is a string
isNil
test whether something is null-ish
Parameters
x
any anything
Examples
// false // false // false // false // false // true // true
Returns boolean true if the input is null-ish
isObject
test whether something is an object
Parameters
x
any anything
Examples
// false // false // false // true // true // true
Returns boolean true if the input is a object
isArray
test whether something is an array
Parameters
x
any anything
Examples
// false // false // false // true // false // false // 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
// false // false // false // false // true // false // 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
Examples
// true // false
Returns boolean
every
array.every(fn) but curried and lazy
Parameters
Examples
// true // false
Returns boolean