The purpose of the library is to provide functional wrappers for Array.prototype methods
and provide some additional functions for common tasks.
All wrappers try to mimic original methods as close as possible while providing composable, auto-curried versions of the array methods. One exception is that all functions do not mutate the input arrays (even sort
, reverse
, etc.).
For convenience, some functions have additional methods to execute the most common use cases of the function. For example - sort
function, in addition to the generic form, contains also static methods (that are also auto-curried, pure functions) like sort.num
, sort.numDesc
, etc.
Functions that do not have a native equivalent contain _
suffix. That way we can implement native-like version in the future (if an equivalent method will be added to the language), without potentially breaking backward-compatibility of the library.
The library has built-in type definitions, which provide an excellent IDE support.
Via NPM:
npm i @arrows/array
Via Yarn:
yarn add @arrows/array
All modules can be imported independently (to reduce bundle size), here are some import methods (you can use either CommonJS or ES modules):
import arr from "@arrows/array"
import { filter } from "@arrows/array"
import filter from "@arrows/array/filter"
Adds a value at the end of the array. Similar to Array.prototype.push, but immutable.
value
Additional valuearr
Initial arrayReturns: New array
Creates a new array from the initial one, without the last element.
arr
Initial arrayReturns: New array
Splits the array into chunks of a provided size.
chunkSize
Chunk sizearr
Initial arrayReturns: New array of chunks
Creates a new, empty array.
arr
Initial arrayReturns: New array
Functional wrapper for Array.prototype.concat
Combines two arrays. If the concatenated value is not an array, adds it as a last element.
value
An array or single value to be concatenatedarr
Initial arrayReturns: New array
Functional wrapper for Array.prototype.entries
Creates an iterable of index, value pairs for every entry in the array.
arr
Initial arrayReturns: Iterable of index-value pairs
Functional wrapper for Array.prototype.every
Determines whether all the members of an array satisfy the specified test.
testFn
Test functionarr
Initial arrayReturns: True if all elements satisfy test function, false otherwise
Creates a new array with section identified by start and end index filled with provided value. Have built-in methods for common cases.
startIndex
Start index (if undefined - fill from start)endIndex
End index (if undefined - fill to the end)value
Value with which selected section will be filled.arr
Initial arrayReturns: New array
Fill from the start to the end.
value
Value with which selected section will be filled.arr
Initial arrayReturns: New array
Fill from the start to the specified index.
endIndex
End indexvalue
Value with which selected section will be filled.arr
Initial arrayReturns: New array
Fill from the specified index to the end.
startIndex
Start indexvalue
Value with which selected section will be filled.arr
Initial arrayReturns: New array
Functional wrapper for Array.prototype.filter
Creates a new array from the initial one, without the values that does not meet the condition specified in a filtering function.
fn
Filtering functionarr
Initial arrayReturns: New array
Creates a new array from the initial one, without the values that meet the condition specified in a filtering function.
It is useful when you have a ready-to-use filtering function, that you want to pass as an argument, otherwise you would have to manually wrap it in a function to negate its results.
fn
Filtering functionarr
initial arrayReturns: New array
Functional wrapper for Array.prototype.find
Retrieves the value of the first element in the array where predicate is true, and undefined otherwise.
testFn
Test functionarr
Initial arrayReturns: Item that matches predicate or undefined
Functional wrapper for Array.prototype.findIndex
Retrieves the index of the first element in the array where predicate is true, and -1 otherwise.
testFn
Test functionarr
Initial arrayReturns: Index of the matching element or -1
Retrieves the first element of the array.
arr
Initial arrayReturns: First element
Functional wrapper for Array.prototype.flat with custom depth
Creates a new array with all sub-array elements concatenated into it recursively up to the specified depth.
depth
Maximum recursion deptharr
Initial arrayReturns: New array
Version with default depth (1).
arr
Initial arrayReturns: New array
Functional wrapper for Array.prototype.flatMap
Calls a defined mapping function on each element of an array. Then, flattens the result into a new array. This is identical to a map followed by flat with depth 1.
mappingFn
Mapping functionarr
Initial arrayReturns: New array
Functional wrapper for Array.prototype.forEach
Performs the specified side effect action for each element in an array.
sideEffectFn
Side effect functionarr
Initial arrayReturns: Nothing (undefined)
Retrieves an element at the specific index.
index
Specific indexReturns: Element at the specific index
Creates an object that groups array items by field specified by grouping functions.
groupingFn
Grouping functionarr
Initial array of objectsReturns: New array
Determines whether an array has a certain index, returning true or false as appropriate.
index
Specific indexarr
Initial arrayReturns: True if index exists, false otherwise
Determines whether an array includes a certain element, returning true or false as appropriate.
element
Searched elementarr
Initial arrayReturns: True if element exists, false otherwise
Functional wrapper for Array.prototype.indexOf
Retrieves the index of the first occurrence of a value in an array.
element
The value to locate in the arrayfromIndex
The array index at which to begin the searcharr
Initial arrayReturns: Index of the matching element or -1
Version with implicit fromIndex (0).
element
The value to locate in the arrayarr
Initial arrayReturns: Index of the matching element or -1
Creates a new array with an additional value at the provided index. Shifts old values to the right. If the index is out of bound of the array - adds a value as a last element.
value
Additional valueindex
Specific indexarr
Initial arrayReturns: New array
Functional wrapper for Array.prototype.join
Adds all the elements of an array separated by the specified separator string.
separator
Separatorarr
Initial arrayReturns: String of joined array elements.
Functional wrapper for Array.prototype.keys
Returns an iterable of keys in the array
arr
Initial arrayReturns: Iterator
Retrieves the last element of the array.
arr
Initial arrayReturns: Last element (undefined for an empty array)
Functional wrapper for Array.prototype.lastIndexOf
Retrieves the index of the last occurrence of a specified value in an array. The array is searched backwards, starting at fromIndex.
element
The value to locate in the arrayfromIndex
The array index at which to begin the searcharr
Initial arrayReturns: Index of the matching element or -1
Version with implicit fromIndex (arr.length - 1).
element
The value to locate in the arrayarr
Initial arrayReturns: Index of the matching element or -1
Functional wrapper for Array.prototype.map
Calls a defined mapping function on each element of an array, and returns an array that contains the results.
mappingFn
Mapping functionarr
Initial arrayReturns: New array
Adds a value at the beginning of the array. Similar to Array.prototype.unshift, but immutable.
value
Additional valuearr
Initial arrayReturns: New array
Creates an array of numbers in a provided range - ascending or descending.
from
Starting number (included)to
Ending number (excluded)step
Step (must be greater than zero) (optional, default 1
)Returns: Range array
Functional wrapper for Array.prototype.reduce
Calls the specified reducing function for all the elements in an array. The return value of the reducing function is the accumulated result, and is provided as an argument in the next call to the reducing function.
reducingFn
Reducing functioninitialValue
Initial value of the accumulatorarr
Initial arrayReturns: Final accumulator value
Reduce without initializer. The first element of the array will be used as an initial accumulator.
reducingFn
Reducing functionarr
Initial arrayReturns: Final accumulator value
Functional wrapper for Array.prototype.reduceRight
Calls the specified callback function for all the elements in an array, in descending order. The return value of the reducing function is the accumulated result, and is provided as an argument in the next call to the reducing function.
reducingFn
Reducing functioninitialValue
Initial value of the accumulatorarr
Initial arrayReturns: Final accumulator value
Reduce without initializer. The last element of the array will be used as an initial accumulator.
reducingFn
Reducing functionarr
Initial arrayReturns: Final accumulator value
Creates a new array without an item at the provided index.
index
Specific indexarr
Initial arrayReturns: New array
Creates new array without the first element.
arr
Initial arrayReturns: New array
Creates a new array with reversed elements.
arr
Initial arrayReturns: New array
Creates a new array with a new value at the provided index.
If the index is out of bound of the array throws an error.
value
New valueindex
Specific indexarr
Initial arrayReturns: New array
Creates a new array trimmed/extended to a provided size. If the new array is longer than the initial one, additional indexes will be set to undefined.
size
Required sizearr
Initial arrayReturns: New array
Retrieves the size (length) of the array.
arr
Initial arrayReturns: Array size (length)
Functional wrapper for Array.prototype.slice
Creates a new array as a a section of an initial array.
from
The beginning of the specified portion of the array.to
The end of the specified portion of the array.arr
Initial arrayReturns: New array
Version with implicit end index (arr.length).
from
The beginning of the specified portion of the array.arr
Initial arrayReturns: New array
Version with implicit start index (0).
to
The end of the specified portion of the array.arr
Initial arrayReturns: New array
Functional wrapper for Array.prototype.some
Determines whether the specified test function returns true for any element of an array.
testFn
Test functionarr
Initial arrayReturns: True if any element satisfies test function, false otherwise
Creates a new, sorted array. Have built-in methods for sorting numerical and string arrays.
compareFn
Compare functionarr
Initial arrayReturns: New array
Sorts numerical arrays in an ascending order.
arr
Initial arrayReturns: New array
Sorts numerical arrays in a descending order.
arr
Initial arrayReturns: New array
Sorts string arrays in an ascending order using comparison operators.
arr
Initial arrayReturns: New array
Sorts string arrays in a descending order using comparison operators.
arr
Initial arrayReturns: New array
Sorts string arrays in an ascending order using String.prototype.localeCompare
.
arr
Initial arrayReturns: New array
Sorts string arrays in a descending order using String.prototype.localeCompare
.
arr
Initial arrayReturns: New array
Creates a new, sorted array. Accepts mapping function that maps values before comparing (mapping does not affect actual values of the array). Have built-in methods for sorting numerical and alphabetical sorting.
compareFn
Compare functionmappingFn
Mapping functionarr
Initial arrayReturns: New array
Sorts numerical arrays in an ascending order.
mappingFn
Mapping functionarr
Initial arrayReturns: New array
Sorts numerical arrays in a descending order.
mappingFn
Mapping functionarr
Initial arrayReturns: New array
Sorts string arrays in an ascending order using comparison operators.
mappingFn
Mapping functionarr
Initial arrayReturns: New array
Sorts string arrays in a descending order using comparison operators.
mappingFn
Mapping functionarr
Initial arrayReturns: New array
Sorts string arrays in an ascending order using String.prototype.localeCompare
.
mappingFn
Mapping functionarr
Initial arrayReturns: New array
Sorts string arrays in a descending order using String.prototype.localeCompare
.
mappingFn
Mapping functionarr
Initial arrayReturns: New array
Functional wrapper for Array.prototype.toLocaleString
Creates a string representation of an array. The elements are converted to string using their toLocalString methods.
arr
Initial arrayReturns: String representation
Functional wrapper for Array.prototype.toString
Creates a string representation of an array.
arr
Initial arrayReturns: String representation
Creates a new array with a new value at the provided index, calculated by updater function that maps an old value into a new one.
If the index is out of bound of the array throws an error.
value
New valueindex
Specific indexarr
Initial arrayReturns: New array
Functional wrapper for Array.prototype.values
Creates an iterable of values in the array.
arr
Initial arrayReturns: Iterator
Zips two arrays creating an array of pairs containing values on corresponding indexes. Zips until the length of the shorter array is reached.
otherArr
Array that you want to zip with initial arrayarr
Initial arrayReturns: New, zipped array
Zips until the length of the longer array is reached.
otherArr
Array that you want to zip with initial arrayarr
Initial arrayReturns: New, zipped array
Zips two arrays producing new values with a zipping function, that takes elements with the same indexes. Zips until the length of the shorter array is reached.
zippingFn
Zipping functionotherArr
Array that you want to zip with initial arrayarr
Initial arrayReturns: New, zipped array
Zips until the length of the longer array is reached.
zippingFn
Zipping functionotherArr
Array that you want to zip with initial arrayarr
Initial arrayReturns: New, zipped array
Project is under open, non-restrictive ISC license.