# f-utility

> functional utilities

Latest version **3.6.0** (published 2019-04-07) · ISC license · 0 weekly downloads

## Install

```sh
npm install f-utility
pnpm add f-utility
yarn add f-utility
bun add f-utility
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.6.0 |
| Published | 2019-04-07 |
| First published | 2016-09-17 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 379.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | brekk |
| Maintainers | brekk |
| Keywords | functional programming, functional, pattern, fp, utility, composable, hoc, tool, toolbelt |

## Links

- npm: https://www.npmjs.com/package/f-utility
- Repository: https://github.com/brekk/f-utility
- npm.io page: https://npm.io/package/f-utility

## Dependencies (5)

- [entrust](https://npm.io/package/entrust.md) ^0.0.21
- [fast.js](https://npm.io/package/fast.js.md) ^0.1.1
- [katsu-curry](https://npm.io/package/katsu-curry.md) ^0.7.8
- [fantasy-land](https://npm.io/package/fantasy-land.md) 3.4.0
- [flatmap-fast](https://npm.io/package/flatmap-fast.md) ^3.0.0

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 3.6.0 (latest) — 2019-04-07
- 4.0.0-alpha.4 (alpha) — 2020-07-02
- 4.0.0-alpha.3 — 2020-06-22
- 4.0.0-alpha.2 — 2020-06-22
- 4.0.0-alpha.1 — 2020-06-22
- 3.5.8 — 2018-10-16
- 3.5.7 — 2018-10-13
- 3.5.6 — 2018-02-16
- 3.5.5 — 2018-02-12
- 3.5.4 — 2018-02-12
- 3.5.3 — 2018-02-12
- 3.5.2 — 2018-01-26
- 3.5.1 — 2017-11-02
- 3.4.1 — 2017-10-25
- 3.4.0 — 2017-10-24
- … 33 more at https://npm.io/package/f-utility/versions

## README

# f-utility

[![CircleCI](https://circleci.com/gh/brekk/f-utility.svg?style=shield&circle-token=a9ccfc426e684dc0537090caee2e300a4ad52c78)](https://circleci.com/gh/brekk/f-utility/tree/master)
[![npm](https://img.shields.io/npm/dw/f-utility.svg)](https://github.com/brekk/f-utility)
[![npm](https://img.shields.io/npm/l/f-utility.svg)](https://www.npmjs.com/package/f-utility)
[![npm](https://img.shields.io/github/tag/brekk/f-utility.svg)](https://github.com/brekk/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](https://gitlab.com/brekk/f-utility/wikis/Breaking-Changes-for-3.6.0)

# API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## ap

Apply a list of functions to a list of values

**Parameters**

-   `applicative` **([function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) \| [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;functions>)** a single function or array of applicatives
-   `functor` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array of values

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** a concatenated list of all applicatives applied to all values

## join

string.prototype.join but curried

**Parameters**

-   `delimiter` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `list` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** 

**Examples**

```javascript
import {join} from 'f-utility'
join(`x`, [1,2,3]) // `1x2x3`
```

Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** joined

## concat

return a new array with some other stuff added to it

**Parameters**

-   `null-null` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array
-   `null-null` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** another array

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** combined array

## sort

string.prototype.sort but curried

**Parameters**

-   `fn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** 
-   `functor` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** 

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** sorted

## difference

get the difference between two arrays

**Parameters**

-   `bList` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array
-   `aList` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array
-   `b` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array

**Examples**

```javascript
import {symmetricDifference} from 'f-utility'
difference([1,2,3], [1,2]) // [3]
```

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** filtered array with differences between the two arrays

## alterIndex

alter the index of a given array input

**Parameters**

-   `index` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the index to alter
-   `fn` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** the function to describe the alteration
-   `input` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** the input array

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an altered copy of the original array

## chain

functor.chain(fn) but curried and fast

**Parameters**

-   `predicate` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** 
-   `iterable` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | Monad)** 

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | Monad)** flat mapped iterable

## choice

takes a function that takes two parameters and returns a ternary result

**Parameters**

-   `cnFn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** 
-   `a` **any** anything
-   `b` **any** anything

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function
-   `goodPath` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function
-   `either` **(Right | Left)** an Either

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** 
-   `iterable` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** 

**Examples**

```javascript
import {filter} from 'f-utility'
filter((x) => x % 2 === 0, [1,2,3,4,5,6,7,8]) // [2,4,6,8]
```

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** filtered iterable

## flip

take a function, flip the two parameters being passed to it, curry it

**Parameters**

-   `fn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function
-   `goodPath` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function
-   `future` **Future** 

**Examples**

```javascript
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**

```javascript
import {pipe, invert} from 'f-utility'
const isOdd = pipe(
  (x) => x % 2 === 0,
  invert
)
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** !x

## not

return the result of inverting a nullary function

**Parameters**

-   `fn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function to invert the result of

**Examples**

```javascript
import {not, equal} from 'f-utility'
const ID = 12345
const isntID = not(equal(ID))
isntID(ID) // false
isntID(123) // true
```

Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** function

## not1

return the result of inverting a unary function

**Parameters**

-   `fn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function to invert the result of
-   `a` **any** a parameter to pass to the function

**Examples**

```javascript
import {not, equal} from 'f-utility'
const ID = 12345
const isntID = not1(equal, ID)
isntID(ID) // false
isntID(123) // true
```

Returns **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** inverted function

## not2

return the result of inverting a binary function

**Parameters**

-   `fn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** inverted function

## not3

return the result of inverting a tertiary function

**Parameters**

-   `fn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** inverted function

## iterate

call a function x times and aggregate the result

**Parameters**

-   `total` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a total number of iterations
-   `fn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function to invoke x times

**Examples**

```javascript
import {iterate} from 'f-utility'
iterate(5, () => `x`) // [`x`, `x`, `x`, `x`, `x`]
```

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** 
-   `functor` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** 

**Examples**

```javascript
import {map} from 'f-utility'
const add1 = map((x) => x + 1)
add1([1,2,3]) // [2,3,4]
```

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** mapped iterable

## equals

=== comparison

**Parameters**

-   `a` **any** anything
-   `b` **any** anything

**Examples**

```javascript
import {equals} from 'f-utility'
const SAFE_ID = 123456
const equalsID = equals(SAFE_ID)
equalsID(200) // false
equalsID(SAFE_ID) // true
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether a triple-equals b

## greaterThan

> comparison but inverted

**Parameters**

-   `b` **any** anything
-   `a` **any** anything

**Examples**

```javascript
import {greaterThan, gt} from 'f-utility'
gt(100, 99) // false
gt(100, 100) // false
gt(100, 101) // true
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether a > b

## greaterThanOrEqualTo

> = comparison but inverted

**Parameters**

-   `b` **any** anything
-   `a` **any** anything

**Examples**

```javascript
import {greaterThanOrEqualTo, gte} from 'f-utility'
gte(100, 99) // false
gte(100, 100) // true
gte(100, 101) // true
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether a > b

## lessThan

&lt; comparison but inverted

**Parameters**

-   `b` **any** anything
-   `a` **any** anything

**Examples**

```javascript
import {lessThan, lt} from 'f-utility'
lt(100, 99) // true
lt(100, 100) // false
lt(100, 101) // false
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether a > b

## lessThanOrEqualTo

&lt; comparison but inverted

**Parameters**

-   `b` **any** anything
-   `a` **any** anything

**Examples**

```javascript
import {lessThanOrEqualTo, lte} from 'f-utility'
lte(100, 99) // true
lte(100, 100) // true
lte(100, 101) // false
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether a > b

## round

convenience method for Math.round

**Parameters**

-   `x` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number

**Examples**

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

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** rounded number

## add

add things

**Parameters**

-   `a` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number
-   `b` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** b number

**Examples**

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

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** sum

## subtract

subtract things

**Parameters**

-   `a` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number
-   `b` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** b number

**Examples**

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

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** subtracted

## multiply

multiply things

**Parameters**

-   `a` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number
-   `b` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** b number

**Examples**

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

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** multiplied

## divide

divide things

**Parameters**

-   `a` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number
-   `b` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** b number

**Examples**

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

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** divided

## pow

exponentiate things

**Parameters**

-   `a` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number
-   `b` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** b number

**Examples**

```javascript
import {pow} from 'f-utility'
pow(4, 2) // 16
```

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** an object

**Examples**

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

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array of keys

## values

**Parameters**

-   `x` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** input

**Examples**

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

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** an object

**Examples**

```javascript
import {freeze} from 'f-utility'
const immutable = freeze({a: 1, b: 2})
immutable.a = 5 // throws error
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** a frozen object

## assign

Object.assign
<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign>

**Parameters**

-   `a` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** any number of objects

**Examples**

```javascript
import {assign} from 'f-utility'
assign({c: 3}, {a: 1, b: 2}) // {a: 1, b: 2, c: 3}
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** a merged object

## merge

object.assign but enforced as a binary function

**Parameters**

-   `a` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** object a
-   `b` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** object b

**Examples**

```javascript
import {merge} from 'f-utility'
merge({c: 3}, {a: 1, b: 2}) // {a: 1, b: 2, c: 3}
```

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** an object

**Examples**

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

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** an object

**Examples**

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

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array of tuples [key, value] pairs

## fromPairs

convert a list of key value pairs into an object

**Parameters**

-   `null-null` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** a list of [key, value] pairs

**Examples**

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

Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** merged results

## mapTuples

a simple object tuple-mapper

**Parameters**

-   `fn` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function which maps over [key, value] tuples
-   `o` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** object

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** a mapped object

## mapValues

a simple object value-only tuple-mapper

**Parameters**

-   `fn` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function which maps over values only
-   `o` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** object

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** a mapped object

## mapKeys

a simple object key-only tuple-mapper

**Parameters**

-   `fn` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function which maps over values only
-   `o` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** object

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** a mapped object

## pathOr

Grab a nested value from an object or return a default

**Parameters**

-   `def` **any** a default value
-   `lenses` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** a list of nested properties
-   `input` **any** an object to grab things from

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** a list of nested properties
-   `input` **any** an object to grab things from

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** a property
-   `input` **any** an object to grab things from

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** a property
-   `input` **any** an object to grab things from

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** an assertion function
-   `lenses` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;strings>** a property
-   `input` **any** an object to grab things from

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;strings>** a property
-   `input` **any** an object to grab things from

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** a property
-   `input` **any** an object to grab things from

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** a property
-   `input` **any** an object to grab things from

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** a truthy value

## random.floor

Simple wrap for floor( x \* random )

**Parameters**

-   `x` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number

**Examples**

```javascript
import {random} from 'f-utility'
const {floor} = random
floor(0) // 0
```

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** x - a rounded number

## random.floorMin

Simple wrap for floor( x \* random ) + min

**Parameters**

-   `min` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number to be the minimum
-   `x` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number to be randomly rounded

**Examples**

```javascript
import {random} from 'f-utility'
const {floorMin} = random
floor(0, 0) // 0
```

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number that is randomly above the min

## random.shuffle

Shuffle the contents of an array

**Parameters**

-   `list` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** an array to be shuffled

**Examples**

```javascript
import {random} from 'f-utility'
const {shuffle} = random
const shuffle(`abcde`.split(``)) // randomly shuffled array
```

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** shuffled

## random.take

Take values randomly from objects or arrays

**Parameters**

-   `encase` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** do we want to return the unwrapped value?
-   `input` **mixed** an array or object

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** something to take values from

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** something to take values from

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** how many values to take
-   `ofThing` **mixed** array or object

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** values

## random.wordSource

generate a "word" of some known length

**Parameters**

-   `source` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;strings>** which characters should be used?
-   `howLong` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** how many characters should be used?

**Examples**

```javascript
import {random} from 'f-utility'
const {wordSource} = random
const dna = wordSource([`g`, `a`, `t`, `c`])
dna(7) // `gattaca`
```

Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** word

## random.word

generate a "word" of some known length

**Parameters**

-   `x` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** how many characters should be used?

**Examples**

```javascript
import {random} from 'f-utility'
const {word} = random
word(5) // `lrmbs`
```

Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** word

## random

Simple wrap for round( x \* random )

**Parameters**

-   `x` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** a number

**Examples**

```javascript
import {random} from 'f-utility'
random(5) // 1
random(5) // 3
random(0) // 0
```

Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** x - a rounded and randomized number

## reduce

functor.reduce but curried and fast

**Parameters**

-   `fn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a reducer
-   `init` **any** an initial value
-   `o` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | Monad)** iterable

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** 
-   `iterable` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** 

**Examples**

```javascript
import {reject} from 'f-utility'
reject((x) => x % 2 !== 0, [1,2,3,4,5,6,7,8]) // [2,4,6,8]
```

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** filtered iterable

## split

string.split(x) but delegatee last

**Parameters**

-   `delimiter` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `string` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** to split

**Examples**

```javascript
import {split} from `f-utility`
split(`x`, `1x2x3`) // [`1`, `2`, `3`]
```

Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** a string or a regular expression
-   `null-null` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a string or a function

Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** string with replacements

## trim

string.trim() but delegatee last

**Parameters**

-   `string` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** to trim

**Examples**

```javascript
import {trim} from `f-utility`
trim(`     20932 `) // `20932`
```

Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** anything to be evaluated as truthy
-   `aFn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a function
-   `bFn` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** b function
-   `o` **mixed** input

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
-   `x` **any** anything

**Examples**

```javascript
import {isTypeof} from 'f-utility'
isTypeof(`boolean`, true) // true
isTypeof(`boolean`, `nope`) // false
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether x is typeof type

## isBoolean

test whether something is a boolean

**Parameters**

-   `x` **any** anything

**Examples**

```javascript
import {isBoolean} from 'f-utility'
isBoolean(true) // true
isBoolean(1) // false
isBoolean(`a`) // false
isBoolean([`a`]) // false
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if the input is a boolean

## isNumber

test whether something is a number

**Parameters**

-   `x` **any** anything

**Examples**

```javascript
import {isNumber} from 'f-utility'
isNumber(true) // false
isNumber(1) // true
isNumber(`a`) // false
isNumber([`a`]) // false
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if the input is a number

## isFunction

test whether something is a function

**Parameters**

-   `x` **any** anything

**Examples**

```javascript
import {isFunction} from 'f-utility'
isFunction(true) // false
isFunction(1) // false
isFunction(`a`) // false
isFunction([`a`]) // false
isFunction(() => {}) // true
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if the input is a function

## isString

test whether something is a string

**Parameters**

-   `x` **any** anything

**Examples**

```javascript
import {isString} from 'f-utility'
isString(true) // false
isString(1) // false
isString(`a`) // true
isString([`a`]) // false
isString(() => {}) // false
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if the input is a string

## isNil

test whether something is null-ish

**Parameters**

-   `x` **any** anything

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if the input is null-ish

## isObject

test whether something is an object

**Parameters**

-   `x` **any** anything

**Examples**

```javascript
import {isObject} from 'f-utility'
isObject(true) // false
isObject(1) // false
isObject(`a`) // false
isObject([`a`]) // true
isObject({}) // true
isObject(null) // true
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if the input is a object

## isArray

test whether something is an array

**Parameters**

-   `x` **any** anything

**Examples**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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**

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** 
-   `iterable` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** 

**Examples**

```javascript
import {some} from 'f-utility'
some((x) => x === `j`, [`j`, `k`, `l`]) // true
some((x) => x === `z`, [`j`, `k`, `l`]) // false
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** 

## every

array.every(fn) but curried and lazy

**Parameters**

-   `predicate` **[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** 
-   `iterable` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** 

**Examples**

```javascript
import {isNumber, every} from 'f-utility'
every(isNumber, [0, 1, 2, 3, 4]) // true
every(isNumber, [0, 1, 2, 3, `four`]) // false
```

Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)**

---
_Source: https://npm.io/package/f-utility · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._