danlafeir / pico-lambda

pico sized functional library

pico-lambda

λ

Arrays the functional way

A 460b functional library based on native array methods

Proudly supported by...

why pico-lambda

• Pico: weighs less than 460 bytes gzipped.
• Useful: takes most native JavaScript array methods and makes them immutable, curried, and composable.
• Familiar: same names just curried and composable JavaScript Array.
• Degrades Gracefully: a small set of these functions are not available in every browser. When not available in the browser it will not be available in Pico Lambda.

Pico-lambda was made for the ES2015 Javascript Runtime. It has no dependencies.

---

Example

After installing via npm install:

const {
  concat,
  filter,
  map,
  reduce,
  compose
} = require('pico-lambda')

//concat
const arrayOne = [1, 2, 3];
const addTwo = concat([4, 5])
const result = addTwo(arrayOne)

// We can compose instead of chaining
compose(
  reduce((acc, val) => val + acc, 0),
  map(x => x * 2),
  filter(x => x > 5),
  concat([6, 7, 8])
)([1, 2, 3, 4, 5])

---

functions

Here be a table showing compatibility for each of the functions available. If you wish to have full compatibility you can use a transpiler like babel.

Table of Compatibility

Function	Android 5.1+	Chrome 52+	Edge 13+	FF 45+	iOS 9+	Safari 9+
compose	✅	✅	✅	✅	✅	✅
concat	✅	✅	✅	✅	✅	✅
copyWithin	❌	✅	✅	✅	✅	✅
entries	✅	✅	✅	✅	✅	✅
every	✅	✅	✅	✅	✅	✅
fill	✅	✅	✅	✅	✅	✅
filter	✅	✅	✅	✅	✅	✅
find	❌	✅	✅	✅	✅	✅
findIndex	❌	✅	✅	✅	✅	✅
includes	❌	✅	✅	✅	✅	✅
indexOf	✅	✅	✅	✅	✅	✅
join	✅	✅	✅	✅	✅	✅
keys	✅	✅	✅	✅	✅	✅
lastIndexOf	✅	✅	✅	✅	✅	✅
map	✅	✅	✅	✅	✅	✅
pipe	✅	✅	✅	✅	✅	✅
pop	✅	✅	✅	✅	✅	✅
push	✅	✅	✅	✅	✅	✅
reduce	✅	✅	✅	✅	✅	✅
reduceRight	✅	✅	✅	✅	✅	✅
reverse	✅	✅	✅	✅	✅	✅
shift	✅	✅	✅	✅	✅	✅
slice	✅	✅	✅	✅	✅	✅
splice	✅	✅	✅	✅	✅	✅
some	✅	✅	✅	✅	✅	✅
sort	✅	✅	✅	✅	✅	✅
toLocaleString	✅	✅	✅	✅	✅	✅
toString	✅	✅	✅	✅	✅	✅
unshift	✅	✅	✅	✅	✅	✅

API

compose :: ((e -> f), ..., (b -> c), (a -> b)) -> a -> f

Evaluates the provided functions, right to left, passing the return value of each function to the next in line. The initial function is passed the initial value provided to compose. The output of the final function, in the above case (e->f), is returned.

compose(
  map(x => x + 1),  // (c -> d)
  map(x => x + 1),  // (b -> c)
  map(x => x + 1)   // (a -> b)
)([0]) // (-> a) => 3

concat :: [a] -> ([a], ..., [a]) -> [a]

Concatenates two or more arrays

concat([4, 5])([1,2,3]) // => [1, 2, 3, 4, 5]
concat([4, 5])([1,2], [3]) // => [1, 2, 3, 4, 5]

See Array.concat (MDN)

copyWithin :: (Int, Int, Int) -> [a] -> [a] | (Int, Int) -> [a] -> [a]

Makes a shallow copy of part of an array and overwrites another location in the same with the copy. Size is kept constant.

• The first Int is the target index to write the copy to.
• The second Int is the index to start the copy from.
• The third, optional, Int specifies the end of the range to copy (exclusive of the end index). If not provided, it goes to the end of the array.

const arr = [1, 2, 3, 4, 5]
copyWithin(3, 1)(arr) // => [1, 2, 3, 2, 3]
copyWithin(3, 1, 2)(arr) // => [1, 2, 3, 2, 5]

See Array.copyWithin (MDN)

entries:: [a] -> [b]

Return an iterator over key, value pairs from the array.

const iterator = entries([1, 2, 3, 4, 5])
iterator.next()) // => { value: [0, 1], done: false }

See Array.entries (MDN)

every :: ((a, Int, [a]) -> Boolean) -> [a] -> Boolean

Applies predicate to all elements in array and returns false if any fail. The predicate function must at least take one parameter for each element but may optionally take an index and the entire array as 2nd and 3rd parameters, respectively.

const predicate = x => x < 4
every(predicate)([1, 2, 3]) // => true
every(predicate)([1, 2, 3, 4, 5]) // => false

See Array.every (MDN)

fill :: (a, Int, Int) -> [a] -> [a] | (a) -> [a] -> [a]

Fills a portion of the given array putting the same new value into each slot.

• The first parameters (a) is the element to add into the array
• The second parameter (Int) is the first index to start filling at. If not supplied it starts at 0.
• The third parameter (Int) is the index to stop filling before (i.e., exclusive). If not supplied fill goes to the end of the array.

const arr = [1, 2, 3, 4, 5]
fill(1)(arr) // => [1, 1, 1, 1, 1]
fill(1, 2, 4)(arr) // => [1, 2, 1, 1, 5]

See Array.fill (MDN)

filter :: ((a, Int, [a]) -> Boolean) -> [a] -> [a]

Returns a new array containing only those elements of the given array that pass the given predicate.

const predicate = x => x < 3
filter(predicate)([1, 2, 3, 4, 5]) // => [1, 2]

See Array.filter (MDN)

find :: (a -> Boolean) -> [a] -> a | undefined

Finds and returns the first element in the given array that matches the given predicate. If no element passes, undefined is returned.

const predicate = x => x === 3
find(predicate)([1, 2, 3]) // => 3
find(predicate)([1, 2]) // => undefined

See Array.find (MDN)

findIndex :: (a -> Boolean) -> [a] -> Int

Returns the index of the first element in the given array that matches the given predicate. If no element passes, -1 is returned.

const arr = [1, 2, 3, 4, 5]
const findIndex = x => x === 3
find(x => x > 3)(arr) // => 3
find(x => x > 80)(arr]) // => -1

See Array.findIndex (MDN)

includes :: a -> [a] -> Boolean

Returns true if the given element is in the given array, otherwise false.

const animals = ['dog', 'cat', 'ferret', 'hamster']
const hasCat = includes('cat')
const hasUnicorn = includes('unicorn')

hasCat(animals) // true
hasUnicorn(animals) // false

See Array.includes (MDN)

indexOf :: (a, Int) -> [a] -> Int | (a) -> [a] -> Int

Returns the index of the given element if it is in the given array, otherwise -1. The 2nd parameter can be used to change where it starts looking.

indexOf(3)([1, 2, 3, 4, 5]) // => 2
indexOf(3, 3)([[1, 2, 3, 4, 5, 3]) // => 3

See Array.indexOf (MDN)

join :: String -> [a] -> String

Converts each element of the array to a string and concatenates them together with the given string as a delimiter.

join('-')([1, 2, 3]) // => '1-2-3'

See Array.join (MDN)

keys :: [a] -> [Int]

Return an iterator over keys from the array.

const iterator = keys([1, 2, 3, 4, 5])
iterator.next() // => { value: 0, done: false }

See Array.keys (MDN)

lastIndexOf :: (a, Int) -> [a] -> Int | (a) -> [a] -> Int

Works like indexOf but starts at the end and works backwards. The 2nd parameter can be used to tell it where to start working backwards from.

lastIndexOf(1)([1, 2, 3, 1]) // => 3
lastIndexOf(1, -2)([1, 2, 3, 1]) // => 0

See Array.lastIndexOf (MDN)

map :: (a -> b) -> [a] -> [b]

Applies a function over each element in the given array, returning a new array with each function call's results.

map(x => x * 2)([1, 2, 3]) // => 2, 4, 6

See Array.map (MDN)

pipe :: ((a -> b), (b -> c), ..., (e -> f)) -> a -> f

Takes an initial value that is passed to the first function in the parameter list. The return value of each subsequent function is passed to the following function. The return value of the last function is returned from pipe.

const arr = [1, 2, 3, 4, 5]
pipe(
  unshift(0),        // (a -> b)
  concat([6, 7, 8])  // (b -> c)
)(arr) // => [0, 1, 2, 3, 4, 5, 6, 7, 8]

See Array.pipe (MDN)

pop :: [a] -> [a]

Returns a new array without the last item

pop([1, 2, 3, 4, 5]) // => [1, 2, 3, 4]

See Array.pop (MDN)

push :: a -> [a] -> [a]

Returns a new array with the new element appended to the end of the original array.

push(5)([1, 2, 3, 4]) // => [1, 2, 3, 4, 5]

See Array.push (MDN)

reduce :: ((a, b) -> a) -> a -> [b] -> a

Applies a function against an accumulator and each value of the array (from left-to-right), then returning the accumulator.

const sum = reduce((acc, val) => acc + val, 99)
sum([2, 3, 4]) // => 108

See Array.reduce (MDN)

reduceRight :: ((a, b) -> a) -> a -> [b] -> a

Applies a function against an accumulator and each value of the array (from right-to-left), then returning the accumulator.

const sum = reduceRight((acc, val) => acc + val, 99)
sum([2, 3, 4]) // => 90

See Array.reduceRight (MDN)

reverse :: [a] -> [a]

Returns a new array with the elements in reverse order.

reverse([1, 2, 3, 4, 5]) // => [5, 4, 3, 2, 1]

See Array.reverse (MDN)

shift :: [a] -> [a]

Returns a new array with the first element removed.

shift([1, 2, 3, 4, 5]) // => [2, 3, 4, 5]

See Array.shift (MDN)

slice :: (int, int) -> [a] -> [a]

Takes a slice from a given array and returns it as a new array.

const removeFirst = slice(1)
removeFirst([2, 3, 4]) // => [3, 4]

See Array.slice (MDN)

splice :: (int, int, [a]) -> [a] -> [a]

Returns a new array with the indicated elements removed. An optional set of new elements can be inserted in their place.

const takeTwo = splice(2)
takeTwo([1, 2, 3, 4, 5]) // => [1, 2]

See Array.splice (MDN)

some :: (a -> Boolean) -> [a] -> Boolean

Returns true if any element in the given array matches the given predicate.

const lessThanFour = some(x => x < 4)
lessThanFour([1, 2, 3, 4, 5]) // => true

See Array.some (MDN)

sort :: ((a, a) -> int) -> [a] -> [a]

Returns a copy of the original array with the values sorted. If a comparator function is provided it should return -1, 0 or 1 depending on whether the first element is less than, equal to or greater than the second, respectively. If no comparator is given, lexical sorting is used.

const numComp = (a, b) => (a < b) ? -1 : (a === b) ? 0 : 1
const sortBy = sort(numComp)
sortBy([20, 1, 3, 4, 2]) // => [1, 2, 3, 4, 20]

See Array.sort (MDN)

toLocaleString :: (String, Obj) -> [a] -> String

Converts each element of an array into a string based on current locale settings or locale options passed in. The resulting strings are appended together using commas.

const toYen = toLocaleString('ja-JP', { style: 'currency', currency: 'JPY' })
toYen(["￥7", 500, 8123, 12]) // => ￥7,500,8,123,12

See Array.toLocaleString (MDN)

toString :: [a] -> String

Converts each element of an array into a string and appends them together with a comma.

toString([1, 2, 3, 4, 5]) // => '1,2,3,4,5'

See Array.toString (MDN)

unshift :: [a] -> [a]

Returns a new copy of an array with the first element removed.

const addOne = unshift(1)
addOne([2, 3]) // => [1, 2, 3]

See Array.unshift (MDN)

Where are ...?

• length - This is a property, not a method, so it doesn't really belong here.
• forEach - This is inherently side-effect-y, it adds nothing that can't be done with filter, map and reduce.

If you don't agree with anything above that's great! Just log an issue so we can discuss.