Array

A collection of functions to manipulate readonly arrays.

@example

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

const array = Array.of(2, 1, 3);
const reversed = Array.reversed(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
• indexOf
• insertAt
• lastIndexOf
• map
• reduce
• reduceRight
• reverse
• setAt
• slice
• sort
• splice

Accessor

at

• at<Item>(array: ArrayLike<Item>, index: number): 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

  ---

  Type parameters

  • Item

size

• size(array: ArrayLike<unknown>): 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() // []

  ---

  Type parameters

  • Item = never

generate

• generate<Value>(length: number, mapFn: (index: Int) => Value): 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]

  ---

  Type parameters

  • Value

of

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

• Returns a new array from a set of items.

  @example

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

  ---

  Type parameters

  • Item

Predicate

every

• every<Item, RefinedItem>(array: Array<Item>, predicate: (item: Item, index: Int, array: Array<Item>) => item is RefinedItem): array is Array<RefinedItem>
• every<Item>(array: Array<Item>, predicate: (item: Item, index: Int, array: Array<Item>) => boolean): 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

  ---

  Type parameters

  • Item
  • RefinedItem

includes

• includes<Item>(array: Array<Item>, searchItem: Item, fromIndex?: number): 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

  ---

  Type parameters

  • Item

isEmpty

• isEmpty(array: ArrayLike<unknown>): boolean

• Return true if the size of the array is 0

  @example

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

some

• some<Item>(array: Array<Item>, predicate: (item: Item, index: Int, array: Array<Item>) => boolean): 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 parameters

  • Item

Type

hasInstance

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

• Alias to Array.isArray()

  @example

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

Other

concat

• concat<Item>(array: Array<Item>, ...extensions: Array<Item>[]): 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]

  ---

  Type parameters

  • Item

deleteAt

• deleteAt<Item>(array: Array<Item>, index: number): Array<Item>

• Return an array excluding the item at the index

  @example

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

  ---

  Type parameters

  • Item

filter

• filter<Item, RefinedItem>(array: Array<Item>, predicate: (item: Item) => item is RefinedItem): Array<RefinedItem>
• filter<Item>(array: Array<Item>, predicate: (item: Item, index: Int, array: Array<Item>) => boolean): 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]

  ---

  Type parameters

  • Item
  • RefinedItem

find

• find<Item, RefinedItem>(array: Array<Item>, predicate: (value: Item, index: Int, array: Array<Item>) => value is RefinedItem): Option<RefinedItem>
• find<Item>(array: Array<Item>, predicate: (value: Item, index: Int, array: Array<Item>) => boolean): 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

  ---

  Type parameters

  • Item
  • RefinedItem

findIndex

• findIndex<Item>(array: Array<Item>, predicate: (value: Item, index: Int, array: Array<Item>) => boolean): 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

  ---

  Type parameters

  • Item

findLast

• findLast<Item, RefinedItem>(array: Array<Item>, predicate: (value: Item, index: Int, array: Array<Item>) => value is RefinedItem): Option<RefinedItem>
• findLast<Item>(array: Array<Item>, predicate: (value: Item, index: Int, array: Array<Item>) => boolean): 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

  ---

  Type parameters

  • Item
  • RefinedItem

findLastIndex

• findLastIndex<Item>(array: Array<Item>, predicate: (value: Item, index: Int, array: Array<Item>) => boolean): 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

  ---

  Type parameters

  • Item

flatMap

• flatMap<FromItem, ToItem>(array: Array<FromItem>, mapFn: (item: FromItem, index: Int, array: Array<FromItem>) => Array<ToItem>): 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']

  ---

  Type parameters

  • FromItem
  • ToItem

indexOf

• indexOf<Item>(array: Array<Item>, searchItem: Item, fromIndex?: number): 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(

  ---

  Type parameters

  • Item

insertAt

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

• Add item at the index in the array

  @example

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

  ---

  Type parameters

  • Item

lastIndexOf

• lastIndexOf<Item>(array: Array<Item>, searchItem: Item, fromIndex?: number): 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

  ---

  Type parameters

  • Item

map

• map<FromItem, ToItem>(array: Array<FromItem>, mapFn: (item: FromItem, index: Int, array: Array<FromItem>) => ToItem): 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]

  ---

  Type parameters

  • FromItem
  • ToItem

reduce

• reduce<Item, ReturnValue>(array: Array<Item>, reduceFn: (previousValue: ReturnValue, currentItem: Item, currentIndex: Int, array: Array<Item>) => ReturnValue, initialValue: ReturnValue): 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'

  ---

  Type parameters

  • Item
  • ReturnValue

reduceRight

• reduceRight<Item, ReturnValue>(array: Array<Item>, reduceFn: (previousValue: ReturnValue, currentItem: Item, currentIndex: Int, array: Array<Item>) => ReturnValue, initialValue: ReturnValue): 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'

  ---

  Type parameters

  • Item
  • ReturnValue

reverse

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

• Return a reversed array

  @example

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

  ---

  Type parameters

  • Item

setAt

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

• Replace item at the index in the array

  @example

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

  ---

  Type parameters

  • Item

slice

• slice<Item>(array: Array<Item>, start?: Option<number>, end?: Option<number>): Array<Item>

• Returns a section of an array.

  @example

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

  ---

  Type parameters

  • Item

sort

• sort<Item>(array: Array<Item>, compareFn: (a: Item, b: Item) => number): Array<Item>

• Return a sorted array using compareFn

  @example

  Array.sort([11, 2, 22, 1], (a, b) => a - b);// [1, 2, 11, 22]

  ---

  Type parameters

  • Item

splice

• splice<Item>(array: Array<Item>, start: number, deleteCount: number, ...items: Item[]): 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']

  ---

  Type parameters

  • Item