A collection of common, sometimes functional utilities. Uses fast.js + katsu-curry
sort, keys, freeze, assign, and lengthallot, and the partially applied forms grab and takepath, pathOr, prop, and propOrmerge, pathIs, pathEq, propIs, propEq and equalskatsu-curry, whose public API changedchaininvert, not, not1, not2, not3 and updated documentationtoPairs / entries and fromPairsap, foldisDistinctObjectrange, speed improvementsap spec, added bunch of string prototype methods, and added dont-break for better safety in future upgradesApply 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 valuesExamples
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
string.prototype.join but curried
Parameters
Examples
import {join} from 'f-utility'
join(`x`, [1,2,3]) // `1x2x3`
Returns string joined
return a new array with some other stuff added to it
Parameters
Returns Array combined array
string.prototype.sort but curried
Parameters
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
get the difference between two arrays
Parameters
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
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]) // [3]
Returns Array filtered array with differences between the two arrays
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 arrayExamples
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
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) // [ 'c', 'h', 'a', 'i', 'n', 'i', 's', 'f', 'l', 'a', 't', 'M', 'a', 'p' ]
Returns (Array | Monad) flat mapped iterable
takes a function that takes two parameters and returns a ternary result
Parameters
cnFn functiona any anythingb any anythingExamples
import {choice} from 'f-utility'
const max = choice((a, b) => a > b)
max(500, 20) // 500
max(20, 500) // 500
Returns any result
a delegatee last function for Either.fold ing
Parameters
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
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]) // [2,4,6,8]
Returns Array filtered iterable
take a function, flip the two parameters being passed to it, curry it
Parameters
fn function a functionExamples
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
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) // console.warn(`5 is odd`)
semiSafeOddity(4) // console.log(4)
Returns any the result of the fork
Parameters
x any anyExamples
import {pipe, invert} from 'f-utility'
const isOdd = pipe(
(x) => x % 2 === 0,
invert
)
Returns boolean !x
return the result of inverting a nullary function
Parameters
fn function a function to invert the result ofExamples
import {not, equal} from 'f-utility'
const ID = 12345
const isntID = not(equal(ID))
isntID(ID) // false
isntID(123) // true
Returns function function
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 functionExamples
import {not, equal} from 'f-utility'
const ID = 12345
const isntID = not1(equal, ID)
isntID(ID) // false
isntID(123) // true
Returns function inverted function
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 functionReturns function inverted function
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 functionReturns function inverted function
call a function x times and aggregate the result
Parameters
Examples
import {iterate} from 'f-utility'
iterate(5, () => `x`) // [`x`, `x`, `x`, `x`, `x`]
Returns Array aggregated values from invoking a given function
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]) // [2,3,4]
Returns Array mapped iterable
=== comparison
Parameters
a any anythingb any anythingExamples
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
comparison but inverted
Parameters
b any anythinga any anythingExamples
import {greaterThan, gt} from 'f-utility'
gt(100, 99) // false
gt(100, 100) // false
gt(100, 101) // true
Returns boolean whether a > b
= comparison but inverted
Parameters
b any anythinga any anythingExamples
import {greaterThanOrEqualTo, gte} from 'f-utility'
gte(100, 99) // false
gte(100, 100) // true
gte(100, 101) // true
Returns boolean whether a > b
< comparison but inverted
Parameters
b any anythinga any anythingExamples
import {lessThan, lt} from 'f-utility'
lt(100, 99) // true
lt(100, 100) // false
lt(100, 101) // false
Returns boolean whether a > b
< comparison but inverted
Parameters
b any anythinga any anythingExamples
import {lessThanOrEqualTo, lte} from 'f-utility'
lte(100, 99) // true
lte(100, 100) // true
lte(100, 101) // false
Returns boolean whether a > b
convenience method for Math.round
Parameters
x number a numberExamples
import {round} from 'f-utility'
round(10.3) // 10
round(10.9) // 11
Returns number rounded number
add things
Parameters
Examples
import {add} from 'f-utility'
add(4, 2) // 6
Returns number sum
subtract things
Parameters
Examples
import {subtract} from 'f-utility'
subtract(4, 2) // -2
Returns number subtracted
multiply things
Parameters
Examples
import {multiply} from 'f-utility'
multiply(4, 2) // 8
Returns number multiplied
divide things
Parameters
Examples
import {divide} from 'f-utility'
divide(4, 2) // 0.5
Returns number divided
exponentiate things
Parameters
Examples
import {pow} from 'f-utility'
pow(4, 2) // 16
Returns number b to the power of a
Object.keys https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys
Parameters
a Object an objectExamples
import {keys} from 'f-utility'
keys({a: 1, b: 2}) // [`a`, `b`]
Returns Array an array of keys
Parameters
x Object inputExamples
import {values} from 'f-utility'
values({a:1, b: 2, c: 3}) // [1, 2, 3]
Returns Array<Strings> values - an array of properties
Object.freeze https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze
Parameters
a Object an objectExamples
import {freeze} from 'f-utility'
const immutable = freeze({a: 1, b: 2})
immutable.a = 5 // throws error
Returns Object a frozen object
Object.assign https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign
Parameters
a Object any number of objectsExamples
import {assign} from 'f-utility'
assign({c: 3}, {a: 1, b: 2}) // {a: 1, b: 2, c: 3}
Returns Object a merged object
object.assign but enforced as a binary function
Parameters
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
Object.entries shim https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries
Parameters
o Object an objectExamples
import {entries} from 'f-utility'
entries({a: 1, b: 2}) // [[`a`, 1], [`b`, 2]]
Returns Array an array of tuples [key, value] pairs
An alias of entries
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries
Parameters
o Object an objectExamples
import {toPairs} from 'f-utility'
toPairs({a: 1, b: 2}) // [[`a`, 1], [`b`, 2]]
Returns Array an array of tuples [key, value] pairs
convert a list of key value pairs into an object
Parameters
null-null Array a list of [key, value] pairsExamples
import {fromPairs} from 'f-utility'
fromPairs([[`a`, 1], [`b`, 2]]) // {a: 1, b: 2}
Returns Object merged results
a simple object tuple-mapper
Parameters
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
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) // {a: 2, b: 4, c: 6}
Returns Object a mapped object
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) // {__a: 1, __b: 2, __c: 3}
Returns Object a mapped object
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 fromExamples
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
Grab a nested value from an object
Parameters
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
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 fromExamples
import {propOr} from 'f-utility'
pathOr(`default`, `c`, {c: `actual`}) // `actual`
pathOr(`default`, `c`, {z: `actual`}) // `default`
Returns any a property or default
Grab a property from an object or return null
Parameters
property string a propertyinput any an object to grab things fromExamples
import {prop} from 'f-utility'
path(`c`, {c: `actual`}) // `actual`
path(`c`, {z: `actual`}) // null
Returns any a property or null
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 fromReturns boolean a truthy value
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 fromReturns boolean a truthy value
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 fromReturns boolean a truthy value
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 fromReturns boolean a truthy value
Simple wrap for floor( x * random )
Parameters
x number a numberExamples
import {random} from 'f-utility'
const {floor} = random
floor(0) // 0
Returns number x - a rounded number
Simple wrap for floor( x * random ) + min
Parameters
Examples
import {random} from 'f-utility'
const {floorMin} = random
floor(0, 0) // 0
Returns number a number that is randomly above the min
Shuffle the contents of an array
Parameters
list Array an array to be shuffledExamples
import {random} from 'f-utility'
const {shuffle} = random
const shuffle(`abcde`.split(``)) // randomly shuffled array
Returns Array shuffled
Take values randomly from objects or arrays
Parameters
encase boolean do we want to return the unwrapped value?input mixed an array or objectExamples
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
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(``)) // `a`
pick(`abcde`.split(``)) // `d`
pick(`abcde`.split(``)) // `b`
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(``)) // [`a`]
pick(`abcde`.split(``)) // [`d`]
pick(`abcde`.split(``)) // [`b`]
pull some number of values from an array or object
Parameters
howMany number how many values to takeofThing mixed array or objectExamples
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
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
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
Simple wrap for round( x * random )
Parameters
x number a numberExamples
import {random} from 'f-utility'
random(5) // 1
random(5) // 3
random(0) // 0
Returns number x - a rounded and randomized number
functor.reduce but curried and fast
Parameters
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
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]) // [2,4,6,8]
Returns Array filtered iterable
string.split(x) but delegatee last
Parameters
Examples
import {split} from `f-utility`
split(`x`, `1x2x3`) // [`1`, `2`, `3`]
Returns Array<strings>
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
string.trim() but delegatee last
Parameters
string string to trimExamples
import {trim} from `f-utility`
trim(` 20932 `) // `20932`
Returns string trimmed
a ternary statement, but curried and lazy
Parameters
cn any anything to be evaluated as truthya any anythingb any anythingExamples
import {ternary} from `f-utility`
ternary(true, `a`, `b`) // `a`
ternary(false, `a`, `b`) // `b`
Returns mixed a / b
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 inputExamples
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
returns boolean based on type
Parameters
type stringx any anythingExamples
import {isTypeof} from 'f-utility'
isTypeof(`boolean`, true) // true
isTypeof(`boolean`, `nope`) // false
Returns boolean whether x is typeof type
test whether something is a boolean
Parameters
x any anythingExamples
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
test whether something is a number
Parameters
x any anythingExamples
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
test whether something is a function
Parameters
x any anythingExamples
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
test whether something is a string
Parameters
x any anythingExamples
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
test whether something is null-ish
Parameters
x any anythingExamples
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
test whether something is an object
Parameters
x any anythingExamples
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
test whether something is an array
Parameters
x any anythingExamples
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
test whether something is a non-null object which isn't an array
Parameters
x any anythingExamples
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
array.some(fn) but curried and lazy
Parameters
Examples
import {some} from 'f-utility'
some((x) => x === `j`, [`j`, `k`, `l`]) // true
some((x) => x === `z`, [`j`, `k`, `l`]) // false
Returns boolean
array.every(fn) but curried and lazy
Parameters
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
FAQs
functional utilities
We found that f-utility demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Threat actors hijacked Toptal’s GitHub org, publishing npm packages with malicious payloads that steal tokens and attempt to wipe victim systems.
Research
/Security News
Socket researchers investigate 4 malicious npm and PyPI packages with 56,000+ downloads that install surveillance malware.
Security News
The ongoing npm phishing campaign escalates as attackers hijack the popular 'is' package, embedding malware in multiple versions.