ƒp

Functional programming utilities for JavaScript.

Install

npm install @bitmap/fp

Functions

Arrays

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

Objects

• prop
• pluck
• pick
• omit

Strings

• split
• join
• reverse
• trim

Math

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

Utilities

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

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

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]

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']

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]

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]

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]

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]

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]

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]

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]

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]]

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'

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]

first

Returns first item in a list.

first(list);

Example

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

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

first(list); // -> 1

last

Returns last item in a list.

last(list);

Example

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

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

last(list); // -> 4

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]

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]

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]

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]

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

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

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

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

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

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

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 = const foods = [
    {
      category: "fruits",
      value: "apple",
    },
    {
      category: "fruits",
      value: "banana",
    },
    {
      category: "vegetable",
      value: "spinach",
    },
    {
      category: "fruits",
      value: "orange",
    },
    {
      category: "vegetable",
      value: "broccoli",
    },
  ];

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

aperture

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

apeture(size, list);

Example

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

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

const aperture2 = aperture(2, list) // -> [[1, 2], [2, 3], [3, 4], [4, 5]]
const aperture2 = aperture(3, list) // -> [[1, 2, 3], [2, 3, 4], [3, 4, 5]]

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'

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']

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' }

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' }

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']

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'

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

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

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

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

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

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

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

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

remainder

Returns remainder of two operands. remainder args are curried.

remainder(a, n);

Example

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

remainder(6, 5); // -> 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

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

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

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.

idendity(value);

Example

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

const id = idenity("hello, world"); // -> 'hello, world'

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

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

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

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