F-utility NPM | npm.io

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

functional programming functional pattern fp utility composable hoc tool toolbelt

@everything-registry/sub-chunk-1641 @zalastax/nolb-f-@infinitebrahmanuniverse/nolb-f-safety-net phantomscript gitparty glass-menagerie eslint-plugin-delorean

5 years ago

5 years ago

5 years ago

5 years ago

7 years ago

7 years ago

7 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

9 years ago

9 years ago

9 years ago

9 years ago

9 years ago

9 years ago

9 years ago

9 years ago

9 years ago

9 years ago