pico-lambda
640b
functional library based on native methods
why pico-lambda
- Pico: weighs less than 640 bytes when minified and gzipped.
- Useful: takes most native JavaScript array and string methods and makes them immutable, curried, and composable.
- Functional: Curry, compose and pipe, Oh My!
- Familiar: same names just curried and composable. See JavaScript Array and JavaScript String.
- Degrades Gracefully: a small set of these functions are not available in every browser/environment. 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 parray pcore = const concat filter map reduce = parrayconst compose } = pcore //concatconst arrayOne = 1 2 3;const addTwo = const result = // We can compose instead of chaining1 2 3 4 5
functions
This table shows compatibility for each of the functions available by browser. Currently only array functions are listed. String will be added soon. 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
The api is broken up into three sections:
- pcore - Basic functional capabilities like curry and compose
- parray - The standard Array.prototype methods setup for functional use
- pstring - The standard String.prototype methods setup for functional use
One note, parray and pstring have some overlapping function names:
- length
- toString
- slice
- indexOf
- lastIndexOf
- includes
- concat
Be aware of this when importing these into your global namespace.
pcore
((a -> b), (b -> c), ..., (e -> f)) -> a -> f
pipe :: 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 5arr // => [0, 1, 2, 3, 4, 5, 6, 7, 8]
((e -> f), ..., (b -> c), (a -> b)) -> a -> f
compose :: 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.
0 // (-> a) => 3
(fn) -> fn
curry :: Takes a function and curries the arguments.
Take note that rest parameters are only partially supported using curry. JS only reports expected parameters, optional and rest parameters are not reported. As a result, there is no way to determine when to expect them. What this means, in practice, is that you can pass rest and/or optional parameters along with the last required param, but you cannot pass them on their own in a new set of parens. See the example below for an illustration of this.
{ console} const curriedLog = //=> Outputs: 1 2 3 4234 //=> Outputs: 1 2 3 42 34 //=> Outputs: 1 2 3 4234 //=> Outputs: 1 2 3 43 4 //=> Outputs: 1 2 3 44 //=> Outputs: 1 2 3 4//You get the idea..... const partialLog = //=> Outputs: 1 2 3 4 //=> Outputs: 1 2 3 5 //Using Rest parameters { console}const curriedLogMore = //=> Outputs: 1 2 3 //=> Outputs: 1 2 3 43 //=> Outputs: 1 2 33 4 //=> Outputs: 1 2 3 4//However, the following all result in an error234 //Throws: TypeError('curriedLogMore(...)(...)(...) is not a function')2 34 //Throws: TypeError('curriedLogMore(...)(...)(...) is not a function')234 //Throws: TypeError('curriedLogMore(...)(...)(...) is not a function')4 //Throws: TypeError('curriedLogMore(...)(...)(...) is not a function')//This is because the curry function calls the original function after the third param and the result is then called as a function with the last grouping, '(4)' in this case
a -> a
identity :: Takes an argument and returns that arugment. This can be quite useful when composing many functions together.
console //Outputs: hi
parray
[a] -> ([a], ..., [a]) -> [a]
concat :: Concatenates two or more arrays
123 // => [1, 2, 3, 4, 5]12 3 // => [1, 2, 3, 4, 5]
(Int, Int, Int) -> [a] -> [a]
| (Int, Int) -> [a] -> [a]
copyWithin :: 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 5arr // => [1, 2, 3, 2, 3]arr // => [1, 2, 3, 2, 5]
[a] -> [b]
entries:: Return an iterator over key, value pairs from the array.
const iterator = iteratornext) // => { value: [0, 1], done: false }
((a, Int, [a]) -> Boolean) -> [a] -> Boolean
every :: 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 < 41 2 3 // => true1 2 3 4 5 // => false
(a, Int, Int) -> [a] -> [a]
| (a) -> [a] -> [a]
fill :: 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 5arr // => [1, 1, 1, 1, 1]arr // => [1, 2, 1, 1, 5]
See Array.fill (MDN)
((a, Int, [a]) -> Boolean) -> [a] -> [a]
filter :: Returns a new array containing only those elements of the given array that pass the given predicate.
const predicate = x < 31 2 3 4 5 // => [1, 2]
(a -> Boolean) -> [a] -> a | undefined
find :: 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 === 31 2 3 // => 31 2 // => undefined
See Array.find (MDN)
(a -> Boolean) -> [a] -> Int
findIndex :: 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 5const findIndex = x === 3arr // => 3arr // => -1
a -> [a] -> Boolean
includes :: Returns true if the given element is in the given array, otherwise false.
const animals = 'dog' 'cat' 'ferret' 'hamster'const hasCat = const hasUnicorn = // true // false
(a, Int) -> [a] -> Int
| (a) -> [a] -> Int
indexOf :: 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.
1 2 3 4 5 // => 21 2 3 4 5 3 // => 3
String -> [a] -> String
join :: Converts each element of the array to a string and concatenates them together with the given string as a delimiter.
1 2 3 // => '1-2-3'
See Array.join (MDN)
[a] -> [Int]
keys :: Return an iterator over keys from the array.
const iterator = iteratornext // => { value: 0, done: false }
See Array.keys (MDN)
(a, Int) -> [a] -> Int
| (a) -> [a] -> Int
lastIndexOf :: 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.
1 2 3 1 // => 31 2 3 1 // => 0
(a -> b) -> [a] -> [b]
map :: Applies a function over each element in the given array, returning a new array with each function call's results.
1 2 3 // => 2, 4, 6
See Array.map (MDN)
[a] -> [a]
pop :: Returns a new array without the last item
// => [1, 2, 3, 4]
See Array.pop (MDN)
a -> [a] -> [a]
push :: Returns a new array with the new element appended to the end of the original array.
1 2 3 4 // => [1, 2, 3, 4, 5]
See Array.push (MDN)
((a, b) -> a) -> a -> [b] -> a
reduce :: Applies a function against an accumulator and each value of the array (from left-to-right), then returning the accumulator.
const sum = // => 108
((a, b) -> a) -> a -> [b] -> a
reduceRight :: Applies a function against an accumulator and each value of the array (from right-to-left), then returning the accumulator.
const sum = // => 90
[a] -> [a]
reverse :: Returns a new array with the elements in reverse order.
// => [5, 4, 3, 2, 1]
[a] -> [a]
shift :: Returns a new array with the first element removed.
// => [2, 3, 4, 5]
(int, int) -> [a] -> [a]
slice :: Takes a slice from a given array and returns it as a new array.
const removeFirst = // => [3, 4]
(int, int, [a]) -> [a] -> [a]
splice :: Returns a new array with the indicated elements removed. An optional set of new elements can be inserted in their place.
const takeTwo = // => [1, 2]
(a -> Boolean) -> [a] -> Boolean
some :: Returns true if any element in the given array matches the given predicate.
const lessThanFour = // => true
See Array.some (MDN)
((a, a) -> int) -> [a] -> [a]
sort :: 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 ? -1 : a === b ? 0 : 1const sortBy = // => [1, 2, 3, 4, 20]
See Array.sort (MDN)
(String, Obj) -> [a] -> String
toLocaleString :: 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 = // => ¥7,500,8,123,12
[a] -> String
toString :: Converts each element of an array into a string and appends them together with a comma.
// => '1,2,3,4,5'
a -> [a] -> [a]
unshift :: Returns a new copy of an array with the given element added to the front.
const addOne = // => [1, 2, 3]
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 withfilter
,map
andreduce
.
If you don't agree with anything above that's great! Just log an issue so we can discuss.
pstring
Int -> String -> String
charAt :: Returns the character at the given position in the string.
"123") //=> "3"
Int -> String -> Int
charCodeAt :: Returns the character code at the given position in the string.
"123") //=> 51
Int -> String -> Int
codePointAt :: Returns the unicode code point at the given index.
"\uD800\uDC00") //=> 65536
(String, ...String) -> String -> String
concat :: Returns a new string combining the given strings. Multiple strings can be passed to the initial call.
const stringOne = "123"const addTwo = const result = //result = "1234567"
String -> String -> Boolean
| (String, Int) -> String -> String
endsWith :: Returns true if the second string ends with the characters in the first. If the integer parameter is passed, the second string is considered to be only that long (or the length of the second string itself whichever is shorter)
"abc" //=> true"abc" //=> false"abcd" //=> false
String -> String -> Boolean
| (String, Int) -> String -> Boolean
includes :: Returns true if the characters from the first string appear together as a substring in the second. If the integer is provided it indicates where to start searching in the second string.
"To be, or not to be, that is the question." //=> true"To be, or not to be, that is the question." //=> false"To be, or not to be, that is the question." //=> false
String -> String -> Int
| (String, Int) -> String -> Int
indexOf :: Returns the first index where the second string appears as a substring of the first. Optionally you can provide a starting index and the search will start there. If the first string is not found it returns -1
"abc") //=> 0"abc") //=> 1"abc") //=> 2"abc") //=> -1
String -> String -> Int
| (String, Int) -> String -> Int
lastIndexOf :: Works like index of but starting at the end and working forward.
"abc") //=> 0"abc") //=> 1"abc") //=> 2"abc") //=> -1
String -> String -> Int
| (String, String) -> String -> Int
| (String, String, Object) -> String -> Int
localeCompare :: Compares two strings taking the locale into account. The return value will be negative if the second string comes before the first. Positive if it comes later. And zero if they are equal. The additional, optional parameters allow a locale and other options to be specified.
"a") //=> <0"b") //=> >0"a") //=> 0'ä') //=> 0
Regexp -> String -> [String]
match :: Returns an array of strings for the value matched by the regular expression as well as all matching groups defined therein.
const str = 'For more information, see Chapter 3.4.5.1'const re = /see /istr //=> ["see Chapter 3.4.5.1", "Chapter 3.4.5.1", ".1"]
String -> String
normalize :: Returns the Unicode Normalization Form of a string.
'\u1E9B\u0323' //=> '\u1E69'
Int -> String -> String
repeat :: Returns string comprised of the given number of repeats of the given string.
'abc') //=> 'abcabc'
(Regexp, String) -> String -> String
replace :: Replaces all locations in the second string that match the given regular expression with the value in the first string. Back references in the first string will be filled appropriately.
'Twas the night before Xmas...') //=> 'Twas the night before Christmas...'
Regexp -> String -> String
search :: Returns the first position where given regular expression matches in the second string. If it doesn't match, -1 is returned.
'Twas the night before Xmas...') //=> 22
Int -> String -> String
| (Int, Int) -> String -> String
slice :: Returns a substring of the second string defined by the given index and optional end index. Either may be negative to count from the end of the string.
'Twas the night before Xmas...' //=> ' the night before Xmas.'
String -> String -> [String]
| (String, Int) -> String -> [String]
split :: Splits a string into an array of substrings that are separated by the first string given. If the integer parameter is provided the split will stop at the given limit.
"1,2" //=> ['1', '2']"1,2,3,4" //=> ['1', '2']
String -> String -> Boolean
| (String, Int) -> String -> Boolean
startsWith :: Returns true if the second string starts with the characters in the first. If the integer parameter is passed, the second string is considered to start at that position
"abc" //=> true"abcd" //=> false
Int -> String
| (Int, Int) -> String
substr :: Returns the characters in a string beginning at the specified location through the specified number of characters.
"abcde" //=> 'cde'"abcde" //=> 'cd'
Int -> String
| (Int, Int) -> String
substring :: Returns a subset of a string between one index and another, or through the end of the string.
"abcde" //=> 'cde'"abcde" //=> 'cd'
String -> String
toLocaleLowerCase :: Returns the primitive value of a string.
String -> String
toLocaleUpperCase :: Returns the calling string value converted to lower case, according to any locale-specific case mappings.
//=> 'abc'
String -> String
toLowerCase :: Returns the primitive value of a string.
//=> 'abc'
String -> String
toString :: Returns the calling string value converted to upper case, according to any locale-specific case mappings.
//=> 'ABC'
String -> String
toUpperCase :: Returns the calling string value converted to upper case.
//=> 'ABC'
String -> String
trim :: Removes whitespace from both ends of a string. Whitespace in this context is all the whitespace characters (space, tab, no-break space, etc.) and all the line terminator characters (LF, CR, etc.).
//=> 'abc'
String -> String
trimLeft :: Removes whitespace from the left end of a string. Whitespace in this context is all the whitespace characters (space, tab, no-break space, etc.) and all the line terminator characters (LF, CR, etc.).
//=> 'abc '
String -> String
trimRight :: Removes whitespace from the left end of a string. Whitespace in this context is all the whitespace characters (space, tab, no-break space, etc.) and all the line terminator characters (LF, CR, etc.).
//=> ' abc'
String -> String
valueOf :: Returns the primitive value of a string.
//=> 'abc'