Array

A collection of functions to manipulate readonly arrays.

@example

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

  @example

  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

  @example

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

Constructor

empty

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

• Always returns an empty array

  @example

  Array.empty() // []

generate

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

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

  @example

  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.

  @example

  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.

  @example

  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.

  @example

  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

  @example

  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.

  @example

  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()

  @example

  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], ...],

  @example

  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

  @example

  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.

  @example

  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.

  @example

  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.

  @example

  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.

  @example

  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.

  @example

  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.

  @example

  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.

  @example

  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.

  @example

  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

  @example

  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.

  @example

  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.

  @example

  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.

  @example

  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.

  @example

  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

  @example

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

setAt

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

• Replace item at the index in the array

  @example

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

slice

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

• Returns a section of an array.

  @example

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

sort

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

• Return a sorted array using compareFn

  @example

  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

  @example

  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']