ƒp

Functional programming utilities for JavaScript.

Install

npm install @bitmap/fp

Functions

Arrays

• all
• any
• aperture
• append
• chunk
• compact
• concat
• copy
• drop
• dropFirst
• dropLast
• dropRight
• excludes
• filter
• filterMap
• find
• findLast
• first
• flat
• flatMap
• groupBy
• includes
• includesFrom
• insert
• insertAll
• last
• map
• position
• positionLast
• prepend
• range
• reduce
• reduceRight
• reject
• rejectMap
• reverse
• slice
• sort
• take
• takeRight
• unique
• zip

Objects

• omit
• pick
• pluck
• prop

Strings

• join
• reverse
• split
• trim

Math

• add
• clamp
• divide
• divideBy
• max
• mean
• median
• min
• mode
• modulo
• multiply
• product
• remainder
• subtract
• subtractBy
• sum

Utilities

• compose
• curry
• identity
• isArray
• isEmpty
• isEqual
• isNull
• isTypeOf
  • isBigInt
  • isBoolean
  • isFunction
  • isNumber
  • isObject
  • isString
  • isSymbol
  • isUndefined
• not
• pipe
• reverseArgs

all

Returns true if all item in list meet the condition. all args are curried.

all(predicate, list);

Example

import { all } from "@bitmap/fp";

const greaterThanTen = (x) => x > 10;
const allGreaterThanTen = all(greaterThanTen);

allGreaterThanTen([3, 5, 7, 9]); // -> false
allGreaterThanTen([5, 20, 100]); // -> false
allGreaterThanTen([50, 15, 99]); // -> true

any

Returns true if any item in list meet the condition. any args are curried.

any(predicate, list);

Example

import { any } from "@bitmap/fp";

const greaterThanTen = (x) => x > 10;
const anyGreaterThanTen = any(greaterThanTen);

anyGreaterThanTen([3, 5, 7, 9]); // -> false
anyGreaterThanTen([5, 20, 100]); // -> true

aperture

Returns a new list, composed of n-tuples of consecutive elements. aperture args are curried.

aperture(size, list);

Example

import { aperture } from "@bitmap/fp";

const list = [1, 2, 3, 4, 5];

aperture(2, list); // -> [[1, 2], [2, 3], [3, 4], [4, 5]]
aperture(3, list); // -> [[1, 2, 3], [2, 3, 4], [3, 4, 5]]

append

Appends item to the end of a list. Unlike Array.prototype.push, doesn't mutate target. append args are curried.

append(item, list);

Example

import { append } from "@bitmap/fp";

const list = [1, 2];

append(3, list); // -> [1, 2, 3]

chunk

Splits a collection into slices of the specified length. chunk args are curried.

chunk(size, list);

Example

import { chunk } from "@bitmap/fp";

const list = [1, 2, 3, 4, 5];

chunk(2, list); // -> [[1, 2], [3, 4], [5]]
chunk(3, list); // -> [[1, 2, 3], [4, 5]]

compact

Returns list with all falsey values removed.

compact(list);

Example

import { compact } from "@bitmap/fp";

compact([0, 1, 2]); // -> [1, 2]
compact(["", "hello", "", "world", ""]); // -> ["hello", "world"]

concat

Concat n lists into one list.

concat(...lists);

Example

import { concat } from "@bitmap/fp";

const a = [1, 2, 3];
const b = [4, 5, 6];

concat(a, b); // -> [1, 2, 3, 4, 5, 6]

copy

Returns a new copy of the list

copy(list);

Example

import { copy } from "@bitmap/fp";

const list = [1, 2, 3];

copy(list); // -> [1, 2, 3]

drop

Drops n items from left. drop args are curried.

drop(n, list);

Example

import { drop } from "@bitmap/fp";

const list = [1, 2, 3, 4];

drop(2, list); // -> [3, 4]

dropFirst

Drops first item from list.

dropFirst(list);

Example

import { dropFirst } from "@bitmap/fp";

const list = [1, 2, 3, 4];

dropFirst(list); // -> [2, 3, 4]

dropLast

Drops last item from list.

dropLast(list);

Example

import { dropLast } from "@bitmap/fp";

const list = [1, 2, 3, 4];

dropLast(list); // -> [1, 2, 3]

dropRight

Drops n items from right. dropRight args are curried.

dropRight(n, list);

Example

import { dropRight } from "@bitmap/fp";

const list = [1, 2, 3, 4];

dropRight(2, list); // -> [1, 2]

excludes

Returns true if item is not in the list. excludes args are curried.

excludes(value, list);

Example

import { excludes } from "@bitmap/fp";

const hasApple = excludes("apple");

hasApple(["orange", "banana", "pear"]); // -> true
hasApple(["kiwi", "apple", "coconut"]); // -> false

filter

Filter items from a list, and return a new list. filter args are curried.

filter(predicate, list);

Example

import { filter } from "@bitmap/fp";

const isOdd = (n) => n % 2 !== 0;
const filterOdds = filter(isOdd);

filterOdds([1, 2, 3, 4]); // -> [1, 3]

filterMap

Apply filter and map to a list, and return a new list. filterMap args are curried.

filterMap(predicate, mapFunction, list);

Example

import { filterMap } from "@bitmap/fp";

const isOdd = (n) => n % 2 !== 0;
const double = (n) => n * 2;
const doubleOdds = filterMap(isOdd, double);

doubleOdds([1, 2, 3, 4]); // -> [3, 6]

find

Returns first item from list that meets predicate. find args are curried.

find(predicate, list);

Example

import { find } from "@bitmap/fp";

const greaterThanTen = (x) => x > 10;
const findGreaterThanTen = find(greaterThanTen);

findGreaterThanTen([3, 5, 7, 9]); // -> undefined
findGreaterThanTen([5, 20, 100]); // -> 20

findLast

Returns last item from list that meets predicate. findLast args are curried.

findLast(predicate, list);

Example

import { findLast } from "@bitmap/fp";

const greaterThanTen = (x) => x > 10;
const findLastGreaterThanTen = findLast(greaterThanTen);

findLastGreaterThanTen([3, 5, 7, 9]); // -> undefined
findLastGreaterThanTen([5, 20, 100]); // -> 100

first

Returns first item in a list.

first(list);

Example

import { first } from "@bitmap/fp";

const list = [1, 2, 3, 4];

first(list); // -> 1

flat

Return a flattened list.

flat(list);

Example

import { flat } from "@bitmap/fp";

flat([0, [1, 2], [3, 4], [5]]); // -> [0, 1, 2, 3, 4, 5]
flat([0, [1, 2, [3, 4, [5]]]]); // -> [0, 1, 2, 3, 4, 5]

flatMap

Apply function to each items in a list, and return a flattened list. flatMap args are curried.

flatMap(flatMapFunction, list);

Example

import { flatMap } from "@bitmap/fp";

const users = ["@cabe", "@bitmap"];
const indexUsers = flatMap((user, index) => [index, user]);

indexUsers(users); // -> [0, '@cabe', 1, '@bitmap']

groupBy

Returns an object with keys being the result of the given function and values being arrays of the items in the original array that produced the key.

groupBy(selector, list);

Example

import { groupBy } from "@bitmap/fp";

const foods = [
  { category: "fruits", value: "apple" },
  { category: "fruits", value: "banana" },
  { category: "vegetable", value: "spinach" },
  { category: "fruits", value: "orange" },
  { category: "vegetable", value: "broccoli" },
];

groupBy((obj) => obj.category, foods); /* -> {
  fruits: [
    { category: "fruits", value: "apple" },
    { category: "fruits", value: "banana" },
    { category: "fruits", value: "orange" },
  ],
  vegetable: [
    { category: "vegetable", value: "spinach" },
    { category: "vegetable", value: "broccoli" },
  ],
} */

includes

Returns true if item is in the list. includes args are curried.

includes(value, list);

Example

import { includes } from "@bitmap/fp";

const hasApple = includes("apple");

hasApple(["orange", "banana", "pear"]); // -> false
hasApple(["kiwi", "apple", "coconut"]); // -> true

includesFrom

Starts searching from specified index, and returns true if the item is in list. includesFrom args are curried.

includesFrom(fromIndex, value, list);

Example

import { includesFrom } from "@bitmap/fp";

const hasApple = includesFrom(2, "apple");

hasApple(["grape", "kiwi", "banana", "apple"]); // -> true
hasApple(["apple", "kiwi", "banana", "grape"]); // -> false

insert

Insert item into a list. Unlike Array.prototype.splice, doesn't mutate target. insert args are curried.

insert(start, item, list);

Example

import { insert } from "@bitmap/fp";

const list = [1, 3];

insert(1, 2, list); // -> [1, 2, 3]

insertAll

Insert items into a list. Unlike Array.prototype.splice, doesn't mutate target. insertAll args are curried.

insertAll(start, items, list);

Example

import { insertAll } from "@bitmap/fp";

const list = [1, 4];

insertAll(1, [2, 3], list); // -> [1, 2, 3, 4]

last

Returns last item in a list.

last(list);

Example

import { last } from "@bitmap/fp";

const list = [1, 2, 3, 4];

last(list); // -> 4

map

Apply function to each items in a list, and return a new list. map args are curried.

map(mapFunction, list);

Example

import { map } from "@bitmap/fp";

const double = (n) => n * 2;
const doubleAll = map(double);

doubleAll([1, 2, 3]); // -> [2, 4, 6]

position

Return index of first found item in list. If arg is a predicate function, returns index of the first item in a list that meets the condition. If no item meets the criteria, it returns -1. position args are curried.

position(value, list);
position(predicate, list);

Example

import { position } from "@bitmap/fp";

const firstAppleIndex = position("apple");

firstAppleIndex(["orange", "banana", "pear", "lemon"]); // -> -1
firstAppleIndex(["kiwi", "apple", "coconut", "apple"]); // -> 1

positionLast

Return index of last found item in list. If arg is a predicate function, returns index of the last item in a list that meets the condition. If no item meets the criteria, it returns -1. positionLast args are curried.

positionLast(value, list);
positionLast(predicate, list);

Example

import { positionLast } from "@bitmap/fp";

const lastAppleIndex = positionLast("apple");

lastAppleIndex(["orange", "banana", "pear", "lemon"]); // -> -1
lastAppleIndex(["kiwi", "apple", "coconut", "apple"]); // -> 3

prepend

Prepends item to the beginning of a list. Unlike Array.prototype.unshift, doesn't mutate target. prepend args are curried.

prepend(item, list);

Example

import { prepend } from "@bitmap/fp";

const list = [1, 2];

prepend(0, list); // -> [0, 1, 2]

range

Returns a sequence of integers from start (inclusive) to end (exclusive). Counts down when start is greater than end, and returns an empty array when they are equal. Throws if either value is not an integer.

range(start, end);

Example

import { range } from "@bitmap/fp";

range(1, 6); // -> [1, 2, 3, 4, 5]
range(5, 0); // -> [5, 4, 3, 2, 1]
range(3, 3); // -> []

for (const i of range(0, 4)) {
  // 0, 1, 2, 3
}

reduce

Reduce values in a list according to a reducer function. reduce args are curried.

reduce(reducer, initialValue, list);

Example

import { reduce } from "@bitmap/fp";

const sum = (a, b) => a + b;
const items = [1, 2, 3, 4];

reduce(sum, 0, items); // -> 10

reduceRight

Reduce values in a list according to a reducer function in reverse order. reduceRight args are curried.

reduceRight(reducer, initialValue, list);

Example

import { reduceRight } from "@bitmap/fp";

const sum = (a, b) => a + b;
const items = [1, 2, 3, 4];

reduceRight(sum, 0, items); // -> 10

reject

Reject items from a list, and return a new list. The opposite of filter. reject args are curried.

reject(predicate, list);

Example

import { reject } from "@bitmap/fp";

const isOdd = (n) => n % 2 !== 0;
const rejectOdds = reject(isOdd);

rejectOdds([1, 2, 3, 4]); // -> [2, 4]

rejectMap

Apply reject and map to a list, and return a new list. rejectMap args are curried.

rejectMap(predicate, mapFunction, list);

Example

import { rejectMap } from "@bitmap/fp";

const isOdd = (n) => n % 2 !== 0;
const double = (n) => n * 2;
const doubleEvens = rejectMap(isOdd, double);

doubleEvens([1, 2, 3, 4]); // -> [4, 8]

reverse

Reverse a string or items in a list. Unlike Array.prototype.reverse, doesn't mutate target.

reverse(list);

Example

import { reverse } from "@bitmap/fp";

const list = [1, 2, 3, 4];

reverse(list); // -> [4, 3, 2, 1]

const string = "functional";

reverse(string); // -> 'lanoitcnuf'

slice

Return a sliced list. slice args are curried.

slice(start, end, list);

Example

import { slice } from "@bitmap/fp";

const list = [1, 2, 3, 4, 5, 6];

slice(2, 5, list); // -> [3, 4, 5]

sort

Sorts items in a list according to comparator function. Unlike Array.prototype.sort, doesn't mutate target.

sort(compareFunction, list);

Example

import { sort } from "@bitmap/fp";

const sortAscending = (a, b) => a - b;
const list = [40, 21, 32, 17];

sort(sortAscending, list); // -> [17, 21, 32, 40]

take

Takes n items from left. take args are curried.

take(n, list);

Example

import { take } from "@bitmap/fp";

const list = [1, 2, 3, 4];

take(2, list); // -> [1, 2]

takeRight

Takes n items from right. takeRight args are curried.

takeRight(n, list);

Example

import { takeRight } from "@bitmap/fp";

const list = [1, 2, 3, 4];

takeRight(2, list); // -> [3, 4]

unique

Returns a new array with duplicate values removed, keeping the first occurrence. unique args are curried.

unique(array);

Example

import { unique } from "@bitmap/fp";

const arr = [1, 2, 2, 3, 1, 4];
const result = unique(arr); // -> [1, 2, 3, 4]

zip

Combine multiple arrays into tuples. The length of the result is the minimum length of the input arrays. zip args are curried.

zip(listA, listB);

Example

import { zip } from "@bitmap/fp";

zip([1, 2, 3], ['a', 'b', 'c']); // -> [[1, 'a'], [2, 'b'], [3, 'c']]
zip([1, 2, 3], ['a', 'b']); // -> [[1, 'a'], [2, 'b']]

omit

Returns copy of object with supplied keys omitted. Opposite of pick. omit args are curried.

omit(keys, object);

Example

import { omit } from "@bitmap/fp";

const data = {
  name: "Cabe",
  age: 32,
  position: "Developer",
  state: "NY",
  city: "New York",
};

omit(["age", "state", "city"], data); // -> { name: 'Cabe', position: 'Developer' }

pick

Returns copy of object with supplied keys and all other properties omitted. pick args are curried.

pick(keys, object);

Example

import { pick } from "@bitmap/fp";

const data = {
  name: "Cabe",
  age: 32,
  position: "Developer",
  state: "NY",
  city: "New York",
};

pick(["name", "position"], data); // -> { name: 'Cabe', position: 'Developer' }

pluck

Returns map of key values from a list of objects. pluck args are curried.

pluck(key, list);

Example

import { pluck } from "@bitmap/fp";

const data = [
  {
    city: "New York",
    state: "NY",
  },
  {
    city: "San Francisco",
    state: "CA",
  },
  {
    city: "Portland",
    state: "OR",
  },
];

pluck("state", data); // -> ['NY', 'CA', 'OR']

prop

Returns the value of key in object. prop args are curried.

prop(key, object);

Example

import { prop } from "@bitmap/fp";

const data = {
  name: "Cabe",
  username: "bitmap",
  title: "Developer",
};

prop("username", data); // -> 'bitmap'

join

Joins a list into a string, seperating each item by specified delimiter. join args are curried.

join(delimiter, list);

Example

import { join } from "@bitmap/fp";

join("|", [1, 2, 3, 4]); // -> '1|2|3|4'

split

Splits a string by delimiter into a list. split args are curried.

split(delimiter, string);

Example

import { split } from "@bitmap/fp";

split(":", "name:Cabe"); // -> ['name', 'Cabe']

trim

Trims whitespace from both ends of a string.

trim(string);

Example

import { trim } from "@bitmap/fp";

trim("    hello, world    "); // -> hello, world

add

Add two numbers together. add args are curried.

add(a, b);

Example

import { add } from "@bitmap/fp";

add(1, 1); // -> 2

const add5 = add(5);
const nine = add5(4); // -> 9

clamp

Clips value in mix/max range. clamp args are curried.

clamp(min, max, value);

Example

import { clamp } from "@bitmap/fp";

const percent = clamp(0, 1);
percent(-1); // -> 0
percent(0.5); // -> 0.5
percent(1.5); // -> 1

divide

Divides first value by second value. divide args are curried.

divide(a, b);

Example

import { divide } from "@bitmap/fp";

divide(12, 3); // -> 4

divideBy

Divides second value by first value. divideBy args are curried.

divideBy(a, b);

Example

import { divideBy } from "@bitmap/fp";

const half = divideBy(2);
const value = half(10); // -> 5

max

Returns maximum value of all arguments. Throws if called with no arguments.

max(a, b, c, ...)

Example

import { max } from "@bitmap/fp";

max(5, 3, 9); // -> 9
max(...[0, 1, 1, 2, 3, 5, 8]); // -> 8

mean

Returns mean (average) of all arguments.

mean(a, b, c, ...)

Example

import { mean } from "@bitmap/fp";

mean(6, 11, 7); // -> 8

median

Returns median of all arguments.

median(a, b, c, ...)

Example

import { median } from "@bitmap/fp";

median(3, 5, 7); // -> 5
median(19, 21, 23, 25); // -> 22

min

Returns minimum value of all arguments. Throws if called with no arguments.

min(a, b, c, ...)

Example

import { min } from "@bitmap/fp";

min(5, 3, 9); // -> 3
min(...[0, 1, 1, 2, 3, 5, 8]); // -> 0

mode

Returns mode (most frequent occuring value) of all arguments.

mode(a, b, c, ...)

Example

import { mode } from "@bitmap/fp";

mode(3, 1, 2, 1, 3, 2, 1, 1, 2); // -> 1

modulo

Returns modulo of two operands. Note that this is different than the remainder (%) operator is JavaScript, and behaves like the mathmatical definition of modulo or the % operator in Python. modulo args are curried.

modulo(a, n);

Example

import { modulo } from "@bitmap/fp";

modulo(5, 2); // -> 1

multiply

Multiples two numbers. multiply args are curried.

multiply(a, b);

Example

import { multiply } from "@bitmap/fp";

multiply(12, 5); // -> 60

const double = multiply(2);
const triple = multiply(3);
double(10); // -> 20
triple(double(10)); // -> 60

product

Returns product of all arguments.

product(a, b, c, ...)

Example

import { product } from "@bitmap/fp";

product(1, 2, 3, 4); // -> 24

const values = [17, 18, 11, -4];

product(...values); // -> -13464

remainder

Returns remainder of two operands. remainder args are curried.

remainder(a, n);

Example

import { remainder } from "@bitmap/fp";

remainder(6, 5); // -> 1

subtract

Subracts second value from first. subtract args are curried.

subtract(a, b);

Example

import { subtract } from "@bitmap/fp";

subtract(8, 5); // -> 3

subtractBy

Subracts first value from second. subtractBy args are curried.

subtractBy(a, b);

Example

import { subtractBy } from "@bitmap/fp";

const minus5 = subtractBy(5);
const value = minus5(10); // -> 5

sum

Returns sum of all arguments.

sum(a, b, c, ...)

Example

import { sum } from "@bitmap/fp";

sum(1, 2, 3, 4); // -> 10

const values = [17, 18, 11, -4];

sum(...values); // -> 42

compose

Compose functions from right to left.

compose(...functions)(value);

Example

import { compose } from "@bitmap/fp";

const addOne = (n) => n + 1;
const double = (n) => n * 2;

const addOneThenDouble = compose(double, addOne);

addOneThenDouble(20); // 42

curry

Curry a function to allow it to be called partially.

curry(function)

Example

import { curry } from "@bitmap/fp";

const sum = curry((a, b, c) => a + b + c);

sum(1)(2)(3); // -> 6

identity

Pass input as output.

identity(value);

Example

import { identity } from "@bitmap/fp";

identity("hello, world"); // -> 'hello, world'

isArray

Returns true if value is of the Array class.

isArray(value);

Example

import { isArray } from "@bitmap/fp";

isArray([1, 2, 3]); // -> true
isArray({ length: 3, 0: 1, 1: 2, 2: 3 }); // -> false

isEmpty

Checks if supplied value is its type's empty value and returns a boolean. Supports arrays, objects, strings, Maps, and Sets.

isEmpty(value);

Example

import { isEmpty } from "@bitmap/fp";

isEmpty(""); // -> true
isEmpty("hello"); // -> false

isEmpty([]); // -> true
isEmpty([1, 2, 3]); // -> false

isEmpty({}); // -> true
isEmpty({ a: 1 }); // -> false

isEmpty(new Map()); // -> true
isEmpty(new Set()); // -> true

isEqual

Compares two items and returns true if equal. isEqual args are curried.

isEqual(a, b);

Example

import { isEqual } from "@bitmap/fp";

isEqual(2, 2); // -> true
isEqual(2, 3); // -> false

isNull

Returns true if value is null

isNull(value);

Example

import { isNull } from "@bitmap/fp";

let value = null;
isNull(value); // -> true

value = "hello, world";
isNull(value); // -> false

isTypeOf

Evaluate the returned string from an operand. The first arguement type must be a valid value of JavaScript's typeof function: undefined, function, boolean, string, number, bigint, symbol, or object.

Note: Additional helper functions isUndefined, isFunction, isBoolean, isString, isNumber, isBigInt, isSymbol, and isObject are also exported for convenience.

isTypeOf(type, value);

Example

import { isTypeOf } from "@bitmap/fp";

isTypeOf("string", "hello world"); // -> true
isTypeOf("object", []); // -> true
isTypeOf("object", {}); // -> true
isTypeOf("object", null); // -> true
isTypeOf("number", 138); // -> true
isTypeOf("number", "2"); // -> false
isTypeOf("function", (x) => x * x); // -> true

not

Returns a negated version of a predicate function.

not(predicate);

Example

import { not, isNull, isEmpty } from "@bitmap/fp";

const isNotNull = not(isNull);
const isNotEmpty = not(isEmpty);

isNotNull(null); // -> false
isNotNull("hello"); // -> true

isNotEmpty([]); // -> false
isNotEmpty([1, 2, 3]); // -> true

pipe

Compose functions from left to right.

pipe(...functions)(value);

Example

import { pipe } from "@bitmap/fp";

const addOne = (n) => n + 1;
const double = (n) => n * 2;

const doubleThenAddOne = pipe(double, addOne);

doubleThenAddOne(20); // 41

reverseArgs

Returns a function that calls the original function with reversed argument order.

reverseArgs(function);

Example

import { reverseArgs, clamp } from "@bitmap/fp";

// clamp normally takes (min, max, value)
const clampReversed = reverseArgs(clamp);

// Now it takes (value, max, min)
clampReversed(10, 5, 0); // -> 5