Neurotic Pumpkin Murderer

    f-utility

    3.6.0 • Public • Published

    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) => (!== 0 ? Right(/ 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) => (% 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) => (* 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

    Install

    npm i f-utility

    DownloadsWeekly Downloads

    24

    Version

    3.6.0

    License

    ISC

    Unpacked Size

    389 kB

    Total Files

    53

    Last publish

    Collaborators

    • brekk