Array

Helper functions that have to do with arrays.

Functions

arrayCopyTwoDimensional()

function arrayCopyTwoDimensional<T>(array): readonly (readonly T[][]);

Defined in: functions/array.ts:17

Helper function to copy a two-dimensional array. Note that the sub-arrays will only be shallow copied (using the spread operator).

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
array	readonly readonly T[][]

Returns

readonly readonly T[][]

---

arrayEquals()

function arrayEquals<T>(array1, array2): boolean;

Defined in: functions/array.ts:27

Helper function for determining if two arrays contain the exact same elements. Note that this only performs a shallow comparison.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
array1	readonly T[]
array2	readonly T[]

Returns

boolean

---

arrayRemove()

function arrayRemove<T>(originalArray, ...elementsToRemove): readonly T[];

Defined in: functions/array.ts:50

Builds a new array based on the original array without the specified element(s). Returns the new array. If the specified element(s) are not found in the array, it will simply return a shallow copy of the array.

If there is more than one matching element in the array, this function will remove all of them.

This function is variadic, meaning that you can specify N arguments to remove N elements.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
originalArray	readonly T[]
…elementsToRemove	readonly T[]

Returns

readonly T[]

---

arrayRemoveAllInPlace()

function arrayRemoveAllInPlace<T>(array, ...elementsToRemove): boolean;

Defined in: functions/array.ts:78

Removes all of the specified element(s) from the array. If the specified element(s) are not found in the array, this function will do nothing.

This function is variadic, meaning that you can specify N arguments to remove N elements.

If there is more than one matching element in the array, this function will remove every matching element. If you want to only remove the first matching element, use the arrayRemoveInPlace function instead.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
array	T[]
…elementsToRemove	readonly T[]

Returns

boolean

True if one or more elements were removed, false otherwise.

---

arrayRemoveInPlace()

function arrayRemoveInPlace<T>(array, ...elementsToRemove): readonly T[];

Defined in: functions/array.ts:110

Removes the specified element(s) from the array. If the specified element(s) are not found in the array, this function will do nothing.

This function is variadic, meaning that you can specify N arguments to remove N elements.

If there is more than one matching element in the array, this function will only remove the first one. If you want to remove all of the elements, use the arrayRemoveAllInPlace function instead.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
array	T[]
…elementsToRemove	readonly T[]

Returns

readonly T[]

The removed elements. This will be an empty array if no elements were removed.

---

emptyArray()

function emptyArray(array): void;

Defined in: functions/array.ts:130

Helper function to remove all of the elements in an array in-place.

Parameters

Parameter	Type
array	unknown[]

Returns

void

---

filterAsync()

function filterAsync<T>(array, predicate): Promise<readonly T[]>;

Defined in: functions/array.ts:147

Helper function to perform an asynchronous filter. The vanilla Array.filter method does not wait for promises (and treats them as truthy), so this function runs the predicate on all elements concurrently, awaits the results, and then filters the original array.

Usage:

const results = await filterAsync(
  things,
  async (thing) => await filterFunc(thing),
);

(This is an abstraction around Promise.all.)

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
array	readonly T[]
predicate	(element, index, array) => Promise<boolean>

Returns

Promise<readonly T[]>

---

filterMap()

function filterMap<OldT, NewT>(array, predicate): readonly NewT[];

Defined in: functions/array.ts:173

Helper function to perform a filter and a map at the same time. Similar to Array.map, provide a function that transforms a value, but return undefined if the value should be skipped. (Thus, this function cannot be used in situations where undefined can be a valid array element.)

This function is useful because the Array.map method will always produce an array with the same amount of elements as the original array.

This is named filterMap after the Rust function: https://doc.rust-lang.org/std/iter/struct.FilterMap.html

Type Parameters

Type Parameter
OldT
NewT

Parameters

Parameter	Type
array	readonly OldT[]
predicate	(element) => NewT | undefined

Returns

readonly NewT[]

---

filterMapAsync()

function filterMapAsync<OldT, NewT>(array, predicate): Promise<readonly NewT[]>;

Defined in: functions/array.ts:208

Helper function to perform a filter and a map at the same time. Similar to Array.map, provide a function that transforms a value, but return undefined if the value should be skipped. (Thus, this function cannot be used in situations where undefined can be a valid array element.)

This function is useful because the Array.map method will always produce an array with the same amount of elements as the original array.

This is named filterMap after the Rust function: https://doc.rust-lang.org/std/iter/struct.FilterMap.html

This is the asynchronous version, which can be used like this:

const results = await asyncFilterMap(things, someFunc);

(This is an abstraction around Promise.all.)

Type Parameters

Type Parameter
OldT
NewT

Parameters

Parameter	Type
array	readonly OldT[]
predicate	(element, index, array) => Promise<NewT | undefined>

Returns

Promise<readonly NewT[]>

---

getRandomArrayElement()

function getRandomArrayElement<T>(array, exceptions?): T;

Defined in: functions/array.ts:232

Helper function to get a random element from the provided array.

Note that this will only work with arrays that do not contain values of undefined, since the function uses undefined as an indication that the corresponding element does not exist.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Default value	Description
array	readonly T[]	undefined	The array to get an element from.
exceptions	readonly T[]	[]	Optional. An array of elements to skip over if selected.

Returns

T

---

getRandomArrayIndex()

function getRandomArrayIndex(array, exceptions?): number;

Defined in: functions/array.ts:261

Helper function to get a random index from the provided array.

Parameters

Parameter	Type	Default value	Description
array	readonly unknown[]	undefined	The array to get the index from.
exceptions	readonly number[]	[]	Optional. An array of indexes that will be skipped over when getting the random index. Default is an empty array.

Returns

number

---

includes()

function includes<T, TupleElement>(
  array,
  searchElement,
): searchElement is TupleElement;

Defined in: functions/array.ts:280

Similar to the Array.includes method, but works on a widened version of the array.

This is useful when the normal Array.includes produces a type error from an array that uses an as const assertion.

Type Parameters

Type Parameter
T
TupleElement

Parameters

Parameter	Type
array	readonly TupleElement[]
searchElement	WidenLiteral<T>

Returns

searchElement is TupleElement

---

includesAny()

function includesAny<T>(array, ...searchElements): boolean;

Defined in: functions/array.ts:293

Similar to the Array.includes method, but accepts a variadic amount of search elements.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
array	readonly T[]
…searchElements	readonly T[]

Returns

boolean

True if any of the elements are found, false otherwise.

---

isArray()

function isArray(variable): variable is unknown[];

Defined in: functions/array.ts:301

A wrapper around Array.isArray that narrows to unknown[] instead of any[].

Parameters

Parameter	Type
variable	unknown

Returns

variable is unknown[]

---

isArrayBoolean()

function isArrayBoolean(variable): variable is boolean[];

Defined in: functions/array.ts:306

Helper function to check every value of an array to see if it is a boolean.

Parameters

Parameter	Type
variable	unknown

Returns

variable is boolean[]

---

isArrayNumber()

function isArrayNumber(variable): variable is number[];

Defined in: functions/array.ts:315

Helper function to check every value of an array to see if it is a number.

Parameters

Parameter	Type
variable	unknown

Returns

variable is number[]

---

isArrayObject()

function isArrayObject(variable): variable is Record<string, unknown>[];

Defined in: functions/array.ts:324

Helper function to check every value of an array to see if it is an object.

Parameters

Parameter	Type
variable	unknown

Returns

variable is Record<string, unknown>[]

---

isArrayString()

function isArrayString(variable): variable is string[];

Defined in: functions/array.ts:335

Helper function to check every value of an array to see if it is a string.

Parameters

Parameter	Type
variable	unknown

Returns

variable is string[]

---

mapAsync()

function mapAsync<T, U>(array, callback): Promise<readonly U[]>;

Defined in: functions/array.ts:359

Helper function to perform an asynchronous map. The vanilla Array.map method does not wait for promises, resulting in an array of promises rather than the resolved values. This function runs the callback on all elements concurrently, awaits the results, and returns the mapped array.

You can also use this function to simply run an asynchronous function on each element of an array concurrently.

Usage:

const results = await mapAsync(things, async (thing) => await mapFunc(thing));

(This is an abstraction around Promise.all.)

Type Parameters

Type Parameter
T
U

Parameters

Parameter	Type
array	readonly T[]
callback	(element, index, array) => Promise<U>

Returns

Promise<readonly U[]>

---

newArray()

function newArray<T>(length, value): readonly T[];

Defined in: functions/array.ts:370

Initializes an array with all elements containing the specified default value.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
length	number
value	T

Returns

readonly T[]

---

sumArray()

function sumArray(array): number;

Defined in: functions/array.ts:375

Helper function to sum every value in an array together.

Parameters

Parameter	Type
array	readonly number[]

Returns

number

---

unique()

function unique<T>(array): readonly T[];

Defined in: functions/array.ts:383

Helper function to filter out non-unique elements from an array and sort it. Under the hood, this converts the array to a Set and then back to an sorted array.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
array	readonly T[]

Returns

readonly T[]