You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 4-6.RSVP
Socket
Book a DemoInstallSign in
Socket

f-utility

Package Overview
Dependencies
Maintainers
1
Versions
48
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

f-utility

functional utilities

3.6.0
latest
Source
npmnpm
Version published
Weekly downloads
0
Maintainers
1
Weekly downloads
 
Created
Source

f-utility

CircleCI npm npm npm

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

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

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

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

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

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

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

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

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

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

Examples

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

Returns number rounded number

add

add things

Parameters

Examples

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

Returns number sum

subtract

subtract things

Parameters

Examples

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

Returns number subtracted

multiply

multiply things

Parameters

Examples

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

Returns number multiplied

divide

divide things

Parameters

Examples

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

Returns number divided

pow

exponentiate things

Parameters

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

Examples

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

Returns Array an array of keys

values

Parameters

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Keywords

functional programming

FAQs

Package last updated on 07 Apr 2019

Did you know?

Socket

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.

Install

Related posts