Array

A collection of functions to manipulate readonly arrays.

import { Array } from '@w5s/collection';

const array = Array.of(2, 1, 3);
const reversed = Array.reverse(array);// [3, 1, 2]
const sorted = Array.sort(array, (left, right) => left === right ? 0 : left < right ? -1 : 1);// [1, 2, 3]

Index

Accessor

• at
• size

Constructor

• empty
• generate
• of

Predicate

• every
• includes
• isEmpty
• some

Type

• hasInstance

Other

• concat
• deleteAt
• filter
• find
• findIndex
• findLast
• findLastIndex
• flatMap
• fromAsync
• indexOf
• insertAt
• lastIndexOf
• map
• reduce
• reduceRight
• reverse
• setAt
• slice
• sort
• splice

Accessor

at

• at<Item>(self, index): Option<Item>

• Return an item at the index position

  const array = ['foo', 'bar', 'baz'];
  Array.at(array, 1) // Option.Some('bar')
  Array.at(array, -1) //  Option.Some('baz') i.e. the last
  Array.at(array, 99) // Option.None

size

• size(self): Int

• Return the length of the array

  Array.size([]) // 0
  Array.size(['foo', 'bar']) // 2

Constructor

empty

• empty<Item>(): Array<Item>

• Always returns an empty array

  Array.empty() // []

generate

• generate<Value>(length, mapFn): Array<Value>

• Generate an array of length using mapFn(index) on each element

  Array.generate(3, () => 'a');// == ['a', 'a', 'a']
  Array.generate(3, (index) => index * 2);// == [0, 2, 4]

of

• of<Item>(...items): Array<Item>

• Returns a new array from a set of items.

  Array.of(1, 2, 3);// [1, 2, 3]

Predicate

every

• every<Item, RefinedItem>(self, predicate): self is Array<RefinedItem>
• every<Item>(self, predicate): boolean

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

  const isEven = (_: number) => _ % 2 === 0;
  Array.every([1, 2, 3], isEven); // false
  Array.every([2, 4], isEven); // true
  Array.every([], (value) => false); // true

includes

• includes<Item>(self, searchItem, fromIndex): boolean

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

  Array.includes(['a', '', 'a'], 'a'); // true
  Array.includes(['a', '', 'a',  '', 'a'], 'a', 1); // true
  Array.includes(['a', 'b'], 'absent'); // false

isEmpty

• isEmpty(self): boolean

• Return true if the size of the array is 0

  Array.isEmpty([]);// true
  Array.isEmpty(['a', 'b', 'c']);// false

some

• some<Item>(self, predicate): boolean

• Determines whether the specified callback function returns true for any item of an array.

  const isEven = (_: number) => _ % 2 === 0;
  Array.some([1, 2, 3], isEven); // true
  Array.some([1, 3], isEven); // false
  Array.some([], (value) => true); // false

Type

hasInstance

• hasInstance(anyValue): anyValue is Array<unknown>

• Alias to Array.isArray()

  Array.hasInstance(Array.empty()) // true
  Array.hasInstance(null)) // false

Other

concat

• concat<Item>(self, ...extensions): Array<Item>

• Concatenate all elements of arrays Equivalent to [...array, ...extension[0], ...extension[1], ...],

  Array.concat([1, 2], [3, 4], [5, 6]);// [1, 2, 3, 4, 5, 6]

deleteAt

• deleteAt<Item>(self, index): Array<Item>

• Return an array excluding the item at the index

  Array.deletedAt([1, 2, 3, 4], 1);// [1, 3, 4]

filter

• filter<Item, RefinedItem>(self, predicate): Array<RefinedItem>
• filter<Item>(self, predicate): Array<Item>

• Returns the items of an array that meet the condition specified in a callback function.

  const array = [1, 2, 3, 4];
  const isEven = (_: number) => _ % 2 === 0;
  Array.filter(array, isEven); // [2, 4]

find

• find<Item, RefinedItem>(self, predicate): Option<RefinedItem>
• find<Item>(self, predicate): Option<Item>

• Returns the value of the first element in the array where predicate is true, and Option.None otherwise.

  Array.find(['aa', 'ab', 'abc'], (value) => (value[1] === 'b'));// Option.Some('ab')
  Array.find(['a', 'b', 'a'], (value) => false);// Option.None

findIndex

• findIndex<Item>(self, predicate): Option<Int>

• Returns the index of the first element in the array where predicate is true, and Option.None otherwise.

  Array.findIndex(['a', 'b', 'a'], (value) => (value === 'a'));// Option.Some(0)
  Array.findIndex(['a', 'b', 'a'], (value) => false);// Option.None

findLast

• findLast<Item, RefinedItem>(self, predicate): Option<RefinedItem>
• findLast<Item>(self, predicate): Option<Item>

• Returns the value of the last element in the array where predicate is true, and Option.None otherwise.

  Array.findLast(['aa', 'ab', 'abc'], (value) => (value[1] === 'b'));// Option.Some('abc')
  Array.findLast(['a', 'b', 'a'], (value) => false);// Option.None

findLastIndex

• findLastIndex<Item>(self, predicate): Option<Int>

• Returns the index of the last element in the array where predicate is true, and Option.None otherwise.

  Array.findLastIndex(['a', 'b', 'a'], (value) => (value === 'a'));// Option.Some(2)
  Array.findLastIndex(['a', 'b', 'a'], (value) => false);// Option.None

flatMap

• flatMap<FromItem, ToItem>(self, mapFn): Array<ToItem>

• Calls a defined callback function on each item of an array. Each calls should return an array. The final result is the concatenation of each arrays.

  const array = ['a', 'b', 'c'];
  const concat = (_: string) => [_ + '_1', _ + '_2'];
  Array.flatMap(array, concat); // ['a_1', 'a_2', 'b_1', 'b_2', 'c_1', 'c_2']

fromAsync

• fromAsync<T>(iterableOrArrayLike): Promise<Array<T>>
• fromAsync<T, U>(iterableOrArrayLike, mapFn): Promise<Array<Awaited<U>>>

• Creates an array from an async iterator or iterable object.

  await Array.fromAsync(function* () {
    let index = 0;
    while (index < 5) {
      yield Promise.resolve(index);*
      index += 1;
    }
  });// [0, 1, 2, 3, 4]

indexOf

• indexOf<Item>(self, searchItem, fromIndex): Option<Int>

• Returns the index of the first occurrence of searchItem in an array.

  Array.indexOf(['a', '', 'a'], 'a'); // Option.Some(0)
  Array.indexOf(['a', '', 'a',  '', 'a'], 'a', 1); // Option.Some(2)
  Array.indexOf(['a', 'b'], 'absent'); // Option.Some(

insertAt

• insertAt<Item>(self, index, item): Array<Item>

• Add item at the index in the array

  Array.insertAt(['a', 'b', 'c'], 1, '$');// ['a', '$', 'b', 'c']

lastIndexOf

• lastIndexOf<Item>(self, searchItem, fromIndex): Option<Int>

• Returns the index of the last occurrence of a specified searchItem in an array.

  Array.lastIndexOf(['a', 'b', 'a'], 'a') // Option.Some(2)
  Array.lastIndexOf(['a', 'b', 'a', 'b', 'a'], 'a', 4); // Option.Some(2)
  Array.lastIndexOf(['a', 'b'], 'absent') // Option.None

map

• map<FromItem, ToItem>(self, mapFn): Array<ToItem>

• Calls a defined callback function on each item of an array, and returns an array that contains the results.

  const array = [1, 2, 3];
  const double = (_: number) => _ * 2;
  Array.map(array, double); // [2, 4, 6]

reduce

• reduce<Item, ReturnValue>(self, reduceFn, initialValue): ReturnValue

• Calls the specified callback function for all the items in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

  const array = ['foo', 'bar', 'baz'];
  const concat = (_: string, item: string) => _ + ':' + item;
  Array.reduce(array, concat, '$') // '$foo:bar:baz'

reduceRight

• reduceRight<Item, ReturnValue>(self, reduceFn, initialValue): ReturnValue

• Calls the specified callback function for all the items in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

  const array = ['foo', 'bar', 'baz'];
  const concat = (_: string, item: string) => _ + ':' + item;
  Array.reduceRight(array, concat, '$') // '$baz:bar:foo'

reverse

• reverse<Item>(self): Array<Item>

• Return a reversed array

  Array.reverse([1, 2, 3]);// [3, 2, 1]

setAt

• setAt<Item>(self, index, item): Array<Item>

• Replace item at the index in the array

  Array.setAt(['a', 'b', 'c'], 1, '$');// ['a', '$', 'c']

slice

• slice<Item>(self, start, end): Array<Item>

• Returns a section of an array.

  Array.sort([1, 2, 3, 4], 1, 3);// [2, 3]

sort

• sort<Item>(self, compareFn): Array<Item>

• Return a sorted array using compareFn

  Array.sort([11, 2, 22, 1], Number.compare);// [1, 2, 11, 22]

splice

• splice<Item>(self, start, deleteCount, ...items): Array<Item>

• Add item at the index in the array

  const array = ['a', 'b', 'c', 'd', 'e'];
  // Remove 2 items starting at index 1
  splice(array, 1, 2); // ['a', 'd', 'e']
  // Insert items at index 2
  splice(array, 2, 0, 'x', 'y'); // ['a', 'b', 'x', 'y', 'c', 'd', 'e']
  // Replace items at index 1
  splice(array, 1, 2, 'u', 'v'); // ['a', 'u', 'v', 'd', 'e']