@arrows/array

Table of contents

1. Introduction
2. Installation
3. API reference
4. License

Introduction

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.

Installation

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"

API reference

Index

• append_
• butLast_
• chunk_
• clear_
• concat
• entries
• every
• fill
• fill.all
• fill.end
• fill.start
• filter
• filterNot_
• find
• findIndex
• first_
• flat
• flat.one
• flatMap
• forEach
• get_
• groupBy_
• has_
• includes
• indexOf
• indexOf.all
• insert_
• join
• keys
• last_
• lastIndexOf
• lastIndexOf.all
• map
• prepend_
• range_
• reduce
• reduce.first
• reduceRight
• reduceRight.first
• remove_
• rest_
• reverse
• set_
• setSize_
• size_
• slice
• slice.from
• slice.to
• some
• sort
• sort.num
• sort.numDesc
• sort.str
• sort.strDesc
• sort.locale
• sort.localeDesc
• sortBy_
• sortBy_.num
• sortBy_.numDesc
• sortBy_.str
• sortBy_.strDesc
• sortBy_.locale
• sortBy_.localeDesc
• toLocaleString
• toString
• update_
• values
• zip_
• zip_.all
• zipWith_
• zipWith_.all

append_

Adds a value at the end of the array. Similar to Array.prototype.push, but immutable.

Parameters

• value Additional value
• arr Initial array

Returns: New array

butLast_

Creates a new array from the initial one, without the last element.

Parameters

• arr Initial array

Returns: New array

chunk_

Splits the array into chunks of a provided size.

Parameters

• chunkSize Chunk size
• arr Initial array

Returns: New array of chunks

clear_

Creates a new, empty array.

Parameters

• arr Initial array

Returns: New array

concat

Functional wrapper for Array.prototype.concat

Combines two arrays. If the concatenated value is not an array, adds it as a last element.

Parameters

• value An array or single value to be concatenated
• arr Initial array

Returns: New array

entries

Functional wrapper for Array.prototype.entries

Creates an iterable of index, value pairs for every entry in the array.

Parameters

• arr Initial array

Returns: Iterable of index-value pairs

every

Functional wrapper for Array.prototype.every

Determines whether all the members of an array satisfy the specified test.

Parameters

• testFn Test function
• arr Initial array

Returns: True if all elements satisfy test function, false otherwise

fill

Creates a new array with section identified by start and end index filled with provided value. Have built-in methods for common cases.

Parameters

• 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 array

Returns: New array

fill.all

Fill from the start to the end.

Parameters

• value Value with which selected section will be filled.
• arr Initial array

Returns: New array

fill.end

Fill from the start to the specified index.

Parameters

• endIndex End index
• value Value with which selected section will be filled.
• arr Initial array

Returns: New array

fill.start

Fill from the specified index to the end.

Parameters

• startIndex Start index
• value Value with which selected section will be filled.
• arr Initial array

Returns: New array

filter

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.

Parameters

• fn Filtering function
• arr Initial array

Returns: New array

filterNot_

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.

Parameters

• fn Filtering function
• arr initial array

Returns: New array

find

Functional wrapper for Array.prototype.find

Retrieves the value of the first element in the array where predicate is true, and undefined otherwise.

Parameters

• testFn Test function
• arr Initial array

Returns: Item that matches predicate or undefined

findIndex

Functional wrapper for Array.prototype.findIndex

Retrieves the index of the first element in the array where predicate is true, and -1 otherwise.

Parameters

• testFn Test function
• arr Initial array

Returns: Index of the matching element or -1

first_

Retrieves the first element of the array.

Parameters

• arr Initial array

Returns: First element

flat

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.

Parameters

• depth Maximum recursion depth
• arr Initial array

Returns: New array

flat.one

Version with default depth (1).

Parameters

• arr Initial array

Returns: New array

flatMap

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.

Parameters

• mappingFn Mapping function
• arr Initial array

Returns: New array

forEach

Functional wrapper for Array.prototype.forEach

Performs the specified side effect action for each element in an array.

Parameters

• sideEffectFn Side effect function
• arr Initial array

Returns: Nothing (undefined)

get_

Retrieves an element at the specific index.

Parameters

• index Specific index

Returns: Element at the specific index

groupBy_

Creates an object that groups array items by field specified by grouping functions.

Parameters

• groupingFn Grouping function
• arr Initial array of objects

Returns: New array

has_

Determines whether an array has a certain index, returning true or false as appropriate.

Parameters

• index Specific index
• arr Initial array

Returns: True if index exists, false otherwise

includes

Determines whether an array includes a certain element, returning true or false as appropriate.

Parameters

• element Searched element
• arr Initial array

Returns: True if element exists, false otherwise

indexOf

Functional wrapper for Array.prototype.indexOf

Retrieves the index of the first occurrence of a value in an array.

Parameters

• element The value to locate in the array
• fromIndex The array index at which to begin the search
• arr Initial array

Returns: Index of the matching element or -1

indexOf.all

Version with implicit fromIndex (0).

Parameters

• element The value to locate in the array
• arr Initial array

Returns: Index of the matching element or -1

insert_

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.

Parameters

• value Additional value
• index Specific index
• arr Initial array

Returns: New array

join

Functional wrapper for Array.prototype.join

Adds all the elements of an array separated by the specified separator string.

Parameters

• separator Separator
• arr Initial array

Returns: String of joined array elements.

keys

Functional wrapper for Array.prototype.keys

Returns an iterable of keys in the array

Parameters

• arr Initial array

Returns: Iterator

last_

Retrieves the last element of the array.

Parameters

• arr Initial array

Returns: Last element (undefined for an empty array)

lastIndexOf

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.

Parameters

• element The value to locate in the array
• fromIndex The array index at which to begin the search
• arr Initial array

Returns: Index of the matching element or -1

lastIndexOf.all

Version with implicit fromIndex (arr.length - 1).

Parameters

• element The value to locate in the array
• arr Initial array

Returns: Index of the matching element or -1

map

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.

Parameters

• mappingFn Mapping function
• arr Initial array

Returns: New array

prepend_

Adds a value at the beginning of the array. Similar to Array.prototype.unshift, but immutable.

Parameters

• value Additional value
• arr Initial array

Returns: New array

range_

Creates an array of numbers in a provided range - ascending or descending.

Parameters

• from Starting number (included)
• to Ending number (excluded)
• step Step (must be greater than zero) (optional, default 1)

Returns: Range array

reduce

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.

Parameters

• reducingFn Reducing function
• initialValue Initial value of the accumulator
• arr Initial array

Returns: Final accumulator value

reduce.first

Reduce without initializer. The first element of the array will be used as an initial accumulator.

Parameters

• reducingFn Reducing function
• arr Initial array

Returns: Final accumulator value

reduceRight

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.

Parameters

• reducingFn Reducing function
• initialValue Initial value of the accumulator
• arr Initial array

Returns: Final accumulator value

reduceRight.first

Reduce without initializer. The last element of the array will be used as an initial accumulator.

Parameters

• reducingFn Reducing function
• arr Initial array

Returns: Final accumulator value

remove_

Creates a new array without an item at the provided index.

Parameters

• index Specific index
• arr Initial array

Returns: New array

rest_

Creates new array without the first element.

Parameters

• arr Initial array

Returns: New array

reverse

Creates a new array with reversed elements.

Parameters

• arr Initial array

Returns: New array

set_

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.

Parameters

• value New value
• index Specific index
• arr Initial array

Returns: New array

setSize_

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.

Parameters

• size Required size
• arr Initial array

Returns: New array

size_

Retrieves the size (length) of the array.

Parameters

• arr Initial array

Returns: Array size (length)

slice

Functional wrapper for Array.prototype.slice

Creates a new array as a a section of an initial array.

Parameters

• from The beginning of the specified portion of the array.
• to The end of the specified portion of the array.
• arr Initial array

Returns: New array

slice.from

Version with implicit end index (arr.length).

Parameters

• from The beginning of the specified portion of the array.
• arr Initial array

Returns: New array

slice.to

Version with implicit start index (0).

Parameters

• to The end of the specified portion of the array.
• arr Initial array

Returns: New array

some

Functional wrapper for Array.prototype.some

Determines whether the specified test function returns true for any element of an array.

Parameters

• testFn Test function
• arr Initial array

Returns: True if any element satisfies test function, false otherwise

sort

Creates a new, sorted array. Have built-in methods for sorting numerical and string arrays.

Parameters

• compareFn Compare function
• arr Initial array

Returns: New array

sort.num

Sorts numerical arrays in an ascending order.

Parameters

• arr Initial array

Returns: New array

sort.numDesc

Sorts numerical arrays in a descending order.

Parameters

• arr Initial array

Returns: New array

sort.str

Sorts string arrays in an ascending order using comparison operators.

Parameters

• arr Initial array

Returns: New array

sort.strDesc

Sorts string arrays in a descending order using comparison operators.

Parameters

• arr Initial array

Returns: New array

sort.locale

Sorts string arrays in an ascending order using String.prototype.localeCompare.

Parameters

• arr Initial array

Returns: New array

sort.localeDesc

Sorts string arrays in a descending order using String.prototype.localeCompare.

Parameters

• arr Initial array

Returns: New array

sortBy_

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.

Parameters

• compareFn Compare function
• mappingFn Mapping function
• arr Initial array

Returns: New array

sortBy_.num

Sorts numerical arrays in an ascending order.

Parameters

• mappingFn Mapping function
• arr Initial array

Returns: New array

sortBy_.numDesc

Sorts numerical arrays in a descending order.

Parameters

• mappingFn Mapping function
• arr Initial array

Returns: New array

sortBy_.str

Sorts string arrays in an ascending order using comparison operators.

Parameters

• mappingFn Mapping function
• arr Initial array

Returns: New array

sortBy_.strDesc

Sorts string arrays in a descending order using comparison operators.

Parameters

• mappingFn Mapping function
• arr Initial array

Returns: New array

sortBy_.locale

Sorts string arrays in an ascending order using String.prototype.localeCompare.

Parameters

• mappingFn Mapping function
• arr Initial array

Returns: New array

sortBy_.localeDesc

Sorts string arrays in a descending order using String.prototype.localeCompare.

Parameters

• mappingFn Mapping function
• arr Initial array

Returns: New array

toLocaleString

Functional wrapper for Array.prototype.toLocaleString

Creates a string representation of an array. The elements are converted to string using their toLocalString methods.

Parameters

• arr Initial array

Returns: String representation

toString

Functional wrapper for Array.prototype.toString

Creates a string representation of an array.

Parameters

• arr Initial array

Returns: String representation

update_

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.

Parameters

• value New value
• index Specific index
• arr Initial array

Returns: New array

values

Functional wrapper for Array.prototype.values

Creates an iterable of values in the array.

Parameters

• arr Initial array

Returns: Iterator

zip_

Zips two arrays creating an array of pairs containing values on corresponding indexes. Zips until the length of the shorter array is reached.

Parameters

• otherArr Array that you want to zip with initial array
• arr Initial array

Returns: New, zipped array

zip_.all

Zips until the length of the longer array is reached.

Parameters

• otherArr Array that you want to zip with initial array
• arr Initial array

Returns: New, zipped array

zipWith_

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.

Parameters

• zippingFn Zipping function
• otherArr Array that you want to zip with initial array
• arr Initial array

Returns: New, zipped array

zipWith_.all

Zips until the length of the longer array is reached.

Parameters

• zippingFn Zipping function
• otherArr Array that you want to zip with initial array
• arr Initial array

Returns: New, zipped array

License

Project is under open, non-restrictive ISC license.