Functional utilities for arrays.

Documentation

Features

• Opt-in mutability with remmi
• Reference preservation (filter(array, () => true) === array)
• Pipe-friendly (pipe(filter(() => true))(array))
• Graceful failure handling (at(), atOr(), atOrElse(), atOrThrow())

Installation

npm install @monstermann/array

pnpm add @monstermann/array

yarn add @monstermann/array

bun add @monstermann/array

Tree-shaking

Installation

npm install -D @monstermann/unplugin-array

pnpm -D add @monstermann/unplugin-array

yarn -D add @monstermann/unplugin-array

bun -D add @monstermann/unplugin-array

Usage

// vite.config.ts
import array from "@monstermann/unplugin-array/vite";

export default defineConfig({
    plugins: [array()],
});

// rollup.config.js
import array from "@monstermann/unplugin-array/rollup";

export default {
    plugins: [array()],
};

// rolldown.config.js
import array from "@monstermann/unplugin-array/rolldown";

export default {
    plugins: [array()],
};

// webpack.config.js
const array = require("@monstermann/unplugin-array/webpack");

module.exports = {
    plugins: [array()],
};

// rspack.config.js
const array = require("@monstermann/unplugin-array/rspack");

module.exports = {
    plugins: [array()],
};

// esbuild.config.js
import { build } from "esbuild";
import array from "@monstermann/unplugin-array/esbuild";

build({
    plugins: [array()],
});

Array

append

function Array.append<T>(
    target: readonly T[],
    value: NoInfer<T>,
): T[]

Appends value to the end of array.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

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

at

function Array.at<T>(
    target: readonly T[],
    offset: number,
): T | undefined

Returns the value at the specified offset.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3], Array.at(-1)); // 3

atOr

function Array.atOr<T, U>(
    target: readonly T[],
    offset: number,
    or: U,
): Exclude<T, null | undefined> | U

Returns the value at the specified offset. Returns fallback if the offset was out of range, or the retrieved value was nullable.

Example

import { Array } from "@monstermann/array";

Array.atOr([1, null], -1, 2); // 2

import { Array } from "@monstermann/array";

pipe([1, null], Array.atOr(-1, 2)); // 2

atOrElse

function Array.atOrElse<T, U>(
    target: readonly T[],
    offset: number,
    orElse: (target: readonly NoInfer<T>[]) => U,
): Exclude<T, null | undefined> | U

Returns the value at the specified offset. Calls fallback if the offset was out of range, or the retrieved value was nullable.

Example

import { Array } from "@monstermann/array";

Array.atOrElse([1, null], -1, (array) => array.length); // 2

import { Array } from "@monstermann/array";

pipe(
    [1, null],
    Array.atOrElse(-1, (array) => array.length),
); // 2

atOrThrow

function Array.atOrThrow<T>(
    target: readonly T[],
    offset: number,
): Exclude<T, null | undefined>

Returns the value at the specified offset, throws an exception if the offset was out of range, or the retrieved value was nullable.

Example

import { Array } from "@monstermann/array";

Array.atOrThrow([1, null], -1); // Error

import { Array } from "@monstermann/array";

pipe([1, null], Array.atOrThrow(-1)); // Error

clone

function Array.clone<T>(target: readonly T[]): T[]

Creates a shallow copy of array, unless marked as mutable with markAsMutable inside a mutation context (see @monstermann/remmi).

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

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

compact

function Array.compact<T>(
    target: readonly T[],
): readonly Exclude<T, null | undefined>[]

Removes all nullable values from array.

Example

import { Array } from "@monstermann/array";

Array.compact([1, null, undefined]); // [1]

import { Array } from "@monstermann/array";

pipe([1, null, undefined], Array.compact()); // [1]

concat

function Array.concat<T>(target: T[], source: NoInfer<T>[]): T[]

Concatenates source array to the end of array, returning a new array with the combined elements.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

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

countBy

function Array.countBy<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): number

Counts the number of elements in the target array satisfy the provided predicate function.

Example

import { Array } from "@monstermann/array";

const isEven = (n) => n % 2 === 0;
Array.countBy([1, 2, 3, 4, 5], isEven); // 2

import { Array } from "@monstermann/array";

const isEven = (n) => n % 2 === 0;
pipe([1, 2, 3, 4, 5], Array.countBy(isEven)); // 2

create

function Array.create(...args: any): any

An alias for Array.from(target, map?).

Example

import { Array } from "@monstermann/array";

Array.create({ length: 3 }, (_, i) => i); // [0, 1, 2]

drop

function Array.drop<T>(
    target: readonly T[],
    amount: number,
): readonly T[]

Removes the first amount elements from array.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 4, 5], Array.drop(2)); // [3, 4, 5]

dropLast

function Array.dropLast<T>(
    target: readonly T[],
    amount: number,
): readonly T[]

Removes amount of elements from the end of the target array.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 4, 5], Array.dropLast(2)); // [1, 2, 3]

empty

const Array.empty: []

A reference to an empty array - useful if you want to clear an array, but want any === checks to pass if it already was empty.

Example

import { Array } from "@monstermann/array";

empty; // []

every

function Array.every<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): boolean

Tests whether all elements in the array pass the test implemented by the predicate function. It returns true if all elements pass, otherwise false.

Example

import { Array } from "@monstermann/array";

const isEven = (n: number) => n % 2 === 0;

Array.every([2, 4, 6], isEven); // true
Array.every([2, 4, 7], isEven); // false

import { Array } from "@monstermann/array";

const isEven = (n: number) => n % 2 === 0;

pipe([2, 4, 6], Array.every(isEven)); // true
pipe([2, 4, 7], Array.every(isEven)); // false

filter

function Array.filter<T>(
    target: readonly T[],
    by: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): readonly T[]

Filters elements from target array based on the predicate function by.

Example

import { Array } from "@monstermann/array";

Array.filter([1, 2, 3, 4], (x) => x > 2); // [3, 4]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.filter((x) => x > 2),
); // [3, 4]

find

function Array.find<T>(
    target: T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): T | undefined

Returns the first element in array that satisfies the provided predicate function, or undefined if no element is found.

Example

import { Array } from "@monstermann/array";

Array.find([1, 2, 3, 4], (x) => x > 2); // 3

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.find((x) => x > 2),
); // 3

findIndex

function Array.findIndex<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): number

Returns the index of the first element in array that satisfies the provided predicate function, or -1 if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findIndex([1, 2, 3, 4], (x) => x > 2); // 2

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findIndex((x) => x > 2),
); // 2

findIndexOr

function Array.findIndexOr<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    or: U,
): number | U

Returns the index of the first element in target that satisfies the provided predicate function. If no element satisfies the predicate, returns or.

Example

import { Array } from "@monstermann/array";

Array.findIndexOr([1, 2, 3, 4], (x) => x > 2, -1); // 2
Array.findIndexOr([1, 2, 3, 4], (x) => x > 5, -1); // -1

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findIndexOr((x) => x > 2, -1),
); // 2

pipe(
    [1, 2, 3, 4],
    Array.findIndexOr((x) => x > 5, -1),
); // -1

findIndexOrElse

function Array.findIndexOrElse<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    orElse: (target: readonly NoInfer<T>[]) => U,
): number | U

Returns the index of the first element in target that satisfies the provided predicate function. If no element satisfies the predicate, calls orElse with the original array.

Example

import { Array } from "@monstermann/array";

Array.findIndexOrElse(
    [1, 2, 3, 4],
    (x) => x > 2,
    () => -1,
); // 2

Array.findIndexOrElse(
    [1, 2, 3, 4],
    (x) => x > 5,
    (arr) => arr.length,
); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findIndexOrElse(
        (x) => x > 2,
        () => -1,
    ),
); // 2

pipe(
    [1, 2, 3, 4],
    Array.findIndexOrElse(
        (x) => x > 5,
        (arr) => arr.length,
    ),
); // 4

findIndexOrThrow

function Array.findIndexOrThrow<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): number

Returns the index of the first element in target that satisfies the provided predicate function. If no element satisfies the predicate, throws an error.

Example

import { Array } from "@monstermann/array";

Array.findIndexOrThrow([1, 2, 3, 4], (x) => x > 2); // 2
Array.findIndexOrThrow([1, 2, 3, 4], (x) => x > 5); // throws FnError

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findIndexOrThrow((x) => x > 2),
); // 2

pipe(
    [1, 2, 3, 4],
    Array.findIndexOrThrow((x) => x > 5),
); // throws FnError

findLast

function Array.findLast<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): T | undefined

Returns the last element in array that satisfies the provided predicate function, or undefined if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findLast([1, 2, 3, 4], (x) => x > 2); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findLast((x) => x > 2),
); // 4

findLastIndex

function Array.findLastIndex<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): number

Returns the index of the last element in array that satisfies the provided predicate function, or -1 if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findLastIndex([1, 2, 3, 4], (x) => x > 2); // 3

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findLastIndex((x) => x > 2),
); // 3

findLastIndexOr

function Array.findLastIndexOr<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    or: U,
): number | U

Returns the index of the last element in target that satisfies the provided predicate function. If no element satisfies the predicate, returns or.

Example

import { Array } from "@monstermann/array";

Array.findLastIndexOr([1, 3, 2, 4], (x) => x > 2, -1); // 3
Array.findLastIndexOr([1, 2, 3, 4], (x) => x > 5, -1); // -1

import { Array } from "@monstermann/array";

pipe(
    [1, 3, 2, 4],
    Array.findLastIndexOr((x) => x > 2, -1),
); // 3

pipe(
    [1, 2, 3, 4],
    Array.findLastIndexOr((x) => x > 5, -1),
); // -1

findLastIndexOrElse

function Array.findLastIndexOrElse<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    orElse: (target: readonly NoInfer<T>[]) => U,
): number | U

Returns the index of the last element in target that satisfies the provided predicate function. If no element satisfies the predicate, calls orElse with the original array.

Example

import { Array } from "@monstermann/array";

Array.findLastIndexOrElse(
    [1, 3, 2, 4],
    (x) => x > 2,
    () => -1,
); // 3

Array.findLastIndexOrElse(
    [1, 2, 3, 4],
    (x) => x > 5,
    (arr) => arr.length,
); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 3, 2, 4],
    Array.findLastIndexOrElse(
        (x) => x > 2,
        () => -1,
    ),
); // 3

pipe(
    [1, 2, 3, 4],
    Array.findLastIndexOrElse(
        (x) => x > 5,
        (arr) => arr.length,
    ),
); // 4

findLastIndexOrThrow

function Array.findLastIndexOrThrow<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): number

Returns the index of the last element in target that satisfies the provided predicate function. If no element satisfies the predicate, throws an error.

Example

import { Array } from "@monstermann/array";

Array.findLastIndexOrThrow([1, 3, 2, 4], (x) => x > 2); // 3
Array.findLastIndexOrThrow([1, 2, 3, 4], (x) => x > 5); // throws FnError

import { Array } from "@monstermann/array";

pipe(
    [1, 3, 2, 4],
    Array.findLastIndexOrThrow((x) => x > 2),
); // 3

pipe(
    [1, 2, 3, 4],
    Array.findLastIndexOrThrow((x) => x > 5),
); // throws FnError

findLastOr

function Array.findLastOr<T, V>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    or: V,
): Exclude<T, null | undefined> | V

Returns the last element in array that satisfies the provided predicate function, or fallback if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findLastOr([1, 2, 3, 4], (x) => x > 10, 0); // 0

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findLastOr((x) => x > 10, 0),
); // 0

findLastOrElse

function Array.findLastOrElse<T, V>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    orElse: (target: readonly NoInfer<T>[]) => V,
): Exclude<T, null | undefined> | V

Returns the last element in array that satisfies the provided predicate function, or the result of calling callback with the array if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findLastOrElse(
    [1, 2, 3, 4],
    (x) => x > 10,
    (arr) => arr.length,
); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findLastOrElse(
        (x) => x > 10,
        (arr) => arr.length,
    ),
); // 4

findLastOrThrow

function Array.findLastOrThrow<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): Exclude<T, null | undefined>

Returns the last element in array that satisfies the provided predicate function, or throws an error if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findLastOrThrow([1, 2, 3, 4], (x) => x > 2); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findLastOrThrow((x) => x > 2),
); // 4

findMap

function Array.findMap<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    mapper: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
): readonly T[]

Finds the first element in array that satisfies the provided predicate function and applies the mapper function to it, returning a new array with the mapped element.

Example

import { Array } from "@monstermann/array";

Array.findMap(
    [1, 2, 3, 4],
    (x) => x > 2,
    (x) => x * 10,
); // [1, 2, 30, 4]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findMap(
        (x) => x > 2,
        (x) => x * 10,
    ),
); // [1, 2, 30, 4]

findMapAll

function Array.findMapAll<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    mapper: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
): readonly T[]

Finds all elements in array that satisfy the provided predicate function and applies the mapper function to each of them, returning a new array with the mapped elements.

Example

import { Array } from "@monstermann/array";

Array.findMapAll(
    [1, 2, 3, 4],
    (x) => x > 2,
    (x) => x * 10,
); // [1, 2, 30, 40]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findMapAll(
        (x) => x > 2,
        (x) => x * 10,
    ),
); // [1, 2, 30, 40]

findMapLast

function Array.findMapLast<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    mapper: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
): readonly T[]

Finds the last element in array that satisfies the provided predicate function and applies the mapper function to it, returning a new array with the mapped element.

Example

import { Array } from "@monstermann/array";

Array.findMapLast(
    [1, 2, 3, 4],
    (x) => x > 2,
    (x) => x * 10,
); // [1, 2, 3, 40]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findMapLast(
        (x) => x > 2,
        (x) => x * 10,
    ),
); // [1, 2, 3, 40]

findMapLastOr

function Array.findMapLastOr<T, V>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    mapper: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
    or: V,
): readonly T[] | V

Finds the last element in array that satisfies the provided predicate function and applies the mapper function to it, returning a new array with the mapped element, or fallback if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findMapLastOr(
    [1, 2, 3, 4],
    (x) => x > 10,
    (x) => x * 10,
    [],
); // []

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findMapLastOr(
        (x) => x > 10,
        (x) => x * 10,
        [],
    ),
); // []

findMapLastOrElse

function Array.findMapLastOrElse<T, V>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    mapper: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
    orElse: (target: readonly NoInfer<T>[]) => V,
): readonly T[] | V

Finds the last element in array that satisfies the provided predicate function and applies the mapper function to it, returning a new array with the mapped element, or the result of calling callback with the array if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findMapLastOrElse(
    [1, 2, 3, 4],
    (x) => x > 10,
    (x) => x * 10,
    (arr) => arr.length,
); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findMapLastOrElse(
        (x) => x > 10,
        (x) => x * 10,
        (arr) => arr.length,
    ),
); // 4

findMapLastOrThrow

function Array.findMapLastOrThrow<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    mapper: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
): readonly T[]

Finds the last element in array that satisfies the provided predicate function and applies the mapper function to it, returning a new array with the mapped element, or throws an error if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findMapLastOrThrow(
    [1, 2, 3, 4],
    (x) => x > 2,
    (x) => x * 10,
); // [1, 2, 3, 40]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findMapLastOrThrow(
        (x) => x > 2,
        (x) => x * 10,
    ),
); // [1, 2, 3, 40]

findMapOr

function Array.findMapOr<T, V>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    mapper: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
    or: V,
): readonly T[] | V

Finds the first element in array that satisfies the provided predicate function and applies the mapper function to it, returning a new array with the mapped element, or fallback if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findMapOr(
    [1, 2, 3, 4],
    (x) => x > 10,
    (x) => x * 10,
    [],
); // []

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findMapOr(
        (x) => x > 10,
        (x) => x * 10,
        [],
    ),
); // []

findMapOrElse

function Array.findMapOrElse<T, V>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    mapper: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
    orElse: (target: readonly NoInfer<T>[]) => V,
): readonly T[] | V

Finds the first element in array that satisfies the provided predicate function and applies the mapper function to it, returning a new array with the mapped element, or the result of calling callback with the array if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findMapOrElse(
    [1, 2, 3, 4],
    (x) => x > 10,
    (x) => x * 10,
    (arr) => arr.length,
); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findMapOrElse(
        (x) => x > 10,
        (x) => x * 10,
        (arr) => arr.length,
    ),
); // 4

findMapOrThrow

function Array.findMapOrThrow<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    mapper: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
): readonly T[]

Finds the first element in array that satisfies the provided predicate function and applies the mapper function to it, returning a new array with the mapped element, or throws an error if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findMapOrThrow(
    [1, 2, 3, 4],
    (x) => x > 2,
    (x) => x * 10,
); // [1, 2, 30, 4]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findMapOrThrow(
        (x) => x > 2,
        (x) => x * 10,
    ),
); // [1, 2, 30, 4]

findOr

function Array.findOr<T, V>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    or: V,
): Exclude<T, null | undefined> | V

Returns the first element in array that satisfies the provided predicate function, or fallback if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findOr([1, 2, 3, 4], (x) => x > 10, 0); // 0

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findOr((x) => x > 10, 0),
); // 0

findOrElse

function Array.findOrElse<T, V>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    orElse: (target: readonly NoInfer<T>[]) => V,
): Exclude<T, null | undefined> | V

Returns the first element in array that satisfies the provided predicate function, or the result of calling callback with the array if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findOrElse(
    [1, 2, 3, 4],
    (x) => x > 10,
    (arr) => arr.length,
); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findOrElse(
        (x) => x > 10,
        (arr) => arr.length,
    ),
); // 4

findOrThrow

function Array.findOrThrow<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): Exclude<T, null | undefined>

Returns the first element in array that satisfies the provided predicate function, or throws an error if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findOrThrow([1, 2, 3, 4], (x) => x > 2); // 3

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findOrThrow((x) => x > 2),
); // 3

findRemove

function Array.findRemove<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): readonly T[]

Finds the first element in array that satisfies the provided predicate function and removes it, returning a new array without the removed element.

Example

import { Array } from "@monstermann/array";

Array.findRemove([1, 2, 3, 4], (x) => x > 2); // [1, 2, 4]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findRemove((x) => x > 2),
); // [1, 2, 4]

findRemoveLast

function Array.findRemoveLast<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): readonly T[]

Finds the last element in array that satisfies the provided predicate function and removes it, returning a new array without the removed element.

Example

import { Array } from "@monstermann/array";

Array.findRemoveLast([1, 2, 3, 4], (x) => x > 2); // [1, 2, 3]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findRemoveLast((x) => x > 2),
); // [1, 2, 3]

findRemoveLastOr

function Array.findRemoveLastOr<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    or: U,
): T[] | U

Finds the last element in array that satisfies the provided predicate function and removes it, returning a new array without the removed element, or fallback if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findRemoveLastOr([1, 2, 3, 4], (x) => x > 10, []); // []

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findRemoveLastOr((x) => x > 10, []),
); // []

findRemoveLastOrElse

function Array.findRemoveLastOrElse<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    orElse: (target: readonly NoInfer<T>[]) => U,
): T[] | U

Finds the last element in array that satisfies the provided predicate function and removes it, returning a new array without the removed element, or the result of calling callback with the array if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findRemoveLastOrElse(
    [1, 2, 3, 4],
    (x) => x > 10,
    (arr) => arr.length,
); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findRemoveLastOrElse(
        (x) => x > 10,
        (arr) => arr.length,
    ),
); // 4

findRemoveLastOrThrow

function Array.findRemoveLastOrThrow<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): T[]

Finds the last element in array that satisfies the provided predicate function and removes it, returning a new array without the removed element, or throws an error if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findRemoveLastOrThrow([1, 2, 3, 4], (x) => x > 2); // [1, 2, 3]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findRemoveLastOrThrow((x) => x > 2),
); // [1, 2, 3]

findRemoveOr

function Array.findRemoveOr<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    or: U,
): T[] | U

Finds the first element in array that satisfies the provided predicate function and removes it, returning a new array without the removed element, or fallback if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findRemoveOr([1, 2, 3, 4], (x) => x > 10, []); // []

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findRemoveOr((x) => x > 10, []),
); // []

findRemoveOrElse

function Array.findRemoveOrElse<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    orElse: (target: readonly NoInfer<T>[]) => U,
): T[] | U

Finds the first element in array that satisfies the provided predicate function and removes it, returning a new array without the removed element, or the result of calling callback with the array if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findRemoveOrElse(
    [1, 2, 3, 4],
    (x) => x > 10,
    (arr) => arr.length,
); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findRemoveOrElse(
        (x) => x > 10,
        (arr) => arr.length,
    ),
); // 4

findRemoveOrThrow

function Array.findRemoveOrThrow<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
): T[]

Finds the first element in array that satisfies the provided predicate function and removes it, returning a new array without the removed element, or throws an error if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findRemoveOrThrow([1, 2, 3, 4], (x) => x > 2); // [1, 2, 4]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findRemoveOrThrow((x) => x > 2),
); // [1, 2, 4]

findReplace

function Array.findReplace<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    replacement: NoInfer<T>,
): readonly T[]

Finds the first element in array that satisfies the provided predicate function and replaces it with replacement, returning a new array with the replaced element.

Example

import { Array } from "@monstermann/array";

Array.findReplace([1, 2, 3, 4], (x) => x > 2, 10); // [1, 2, 10, 4]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findReplace((x) => x > 2, 10),
); // [1, 2, 10, 4]

findReplaceLast

function Array.findReplaceLast<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    replacement: NoInfer<T>,
): readonly T[]

Finds the last element in array that satisfies the provided predicate function and replaces it with replacement, returning a new array with the replaced element.

Example

import { Array } from "@monstermann/array";

Array.findReplaceLast([1, 2, 3, 4], (x) => x > 2, 10); // [1, 2, 3, 10]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findReplaceLast((x) => x > 2, 10),
); // [1, 2, 3, 10]

findReplaceLastOr

function Array.findReplaceLastOr<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    replacement: NoInfer<T>,
    or: U,
): readonly T[] | U

Finds the last element in array that satisfies the provided predicate function and replaces it with replacement, returning a new array with the replaced element, or fallback if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findReplaceLastOr([1, 2, 3, 4], (x) => x > 10, 99, []); // []

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findReplaceLastOr((x) => x > 10, 99, []),
); // []

findReplaceLastOrElse

function Array.findReplaceLastOrElse<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    replacement: NoInfer<T>,
    orElse: (target: readonly NoInfer<T>[]) => U,
): readonly T[] | U

Finds the last element in array that satisfies the provided predicate function and replaces it with replacement, returning a new array with the replaced element, or the result of calling callback with the array if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findReplaceLastOrElse(
    [1, 2, 3, 4],
    (x) => x > 10,
    99,
    (arr) => arr.length,
); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findReplaceLastOrElse(
        (x) => x > 10,
        99,
        (arr) => arr.length,
    ),
); // 4

findReplaceLastOrThrow

function Array.findReplaceLastOrThrow<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    replacement: NoInfer<T>,
): readonly T[]

Finds the last element in array that satisfies the provided predicate function and replaces it with replacement, returning a new array with the replaced element, or throws an error if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findReplaceLastOrThrow([1, 2, 3, 4], (x) => x > 2, 99); // [1, 2, 3, 99]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findReplaceLastOrThrow((x) => x > 2, 99),
); // [1, 2, 3, 99]

findReplaceOr

function Array.findReplaceOr<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    replacement: NoInfer<T>,
    or: U,
): readonly T[] | U

Finds the first element in array that satisfies the provided predicate function and replaces it with replacement, returning a new array with the replaced element, or fallback if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findReplaceOr([1, 2, 3, 4], (x) => x > 10, 99, []); // []

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findReplaceOr((x) => x > 10, 99, []),
); // []

findReplaceOrElse

function Array.findReplaceOrElse<T, U>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    replacement: NoInfer<T>,
    orElse: (target: readonly NoInfer<T>[]) => U,
): readonly T[] | U

Finds the first element in array that satisfies the provided predicate function and replaces it with replacement, returning a new array with the replaced element, or the result of calling callback with the array if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findReplaceOrElse(
    [1, 2, 3, 4],
    (x) => x > 10,
    99,
    (arr) => arr.length,
); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findReplaceOrElse(
        (x) => x > 10,
        99,
        (arr) => arr.length,
    ),
); // 4

findReplaceOrThrow

function Array.findReplaceOrThrow<T>(
    target: readonly T[],
    predicate: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => boolean,
    replacement: NoInfer<T>,
): readonly T[]

Finds the first element in array that satisfies the provided predicate function and replaces it with replacement, returning a new array with the replaced element, or throws an error if no element is found.

Example

import { Array } from "@monstermann/array";

Array.findReplaceOrThrow([1, 2, 3, 4], (x) => x > 2, 99); // [1, 2, 99, 4]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.findReplaceOrThrow((x) => x > 2, 99),
); // [1, 2, 99, 4]

first

function Array.first<T>(target: readonly T[]): T | undefined

Returns the first element of array, or undefined if the array is empty.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

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

firstOr

function Array.firstOr<T, U>(
    target: readonly T[],
    or: U,
): Exclude<T, null | undefined> | U

Returns the first element of array, or fallback if the array is empty.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 4], Array.firstOr(0)); // 1

firstOrElse

function Array.firstOrElse<T, U>(
    target: readonly T[],
    orElse: (target: readonly NoInfer<T>[]) => U,
): Exclude<T, null | undefined> | U

Returns the first element of array, or the result of calling callback with the array if the array is empty.

Example

import { Array } from "@monstermann/array";

Array.firstOrElse([1, 2, 3, 4], (arr) => arr.length); // 1

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.firstOrElse((arr) => arr.length),
); // 1

firstOrThrow

function Array.firstOrThrow<T>(
    target: readonly T[],
): Exclude<T, null | undefined>

Returns the first element of array, or throws an error if the array is empty.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

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

flatMap

function Array.flatMap<T, U>(
    target: readonly T[],
    mapper: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => U[],
): readonly U[]

Maps each element in array using the mapper function and flattens the result by one level.

Example

import { Array } from "@monstermann/array";

Array.flatMap([1, 2, 3], (x) => [x, x * 2]); // [1, 2, 2, 4, 3, 6]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3],
    Array.flatMap((x) => [x, x * 2]),
); // [1, 2, 2, 4, 3, 6]

forEach

function Array.forEach<T>(
    target: readonly T[],
    callback: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => any,
): readonly T[]

Executes the provided callback function once for each element in array and returns the original array.

Example

import { Array } from "@monstermann/array";

Array.forEach([1, 2, 3], (x) => console.log(x)); // [1, 2, 3]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3],
    Array.forEach((x) => console.log(x)),
); // [1, 2, 3]

forEachRight

function Array.forEachRight<T>(
    target: readonly T[],
    callback: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => any,
): readonly T[]

Executes the provided callback function once for each element in array in reverse order and returns the original array.

Example

import { Array } from "@monstermann/array";

Array.forEachRight([1, 2, 3], (x) => console.log(x)); // [1, 2, 3]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3],
    Array.forEachRight((x) => console.log(x)),
); // [1, 2, 3]

groupBy

function Array.groupBy<T extends object, U extends PropertyKey>(
    target: readonly T[],
    by: (
        value: NoInfer<T>,
        idx: number,
        target: readonly NoInfer<T>[],
    ) => U,
): Record<U, T[]>

Groups elements in array by the result of calling grouper function on each element, optionally transforming each element with transform, returning an object with keys as group values and values as arrays of elements.

Example

import { Array } from "@monstermann/array";

Array.groupBy(
    [1, 2, 3, 4],
    (x) => (x % 2 === 0 ? "even" : "odd"),
    (x) => x * 10,
); // { even: [20, 40], odd: [10, 30] }

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.groupBy(
        (x) => (x % 2 === 0 ? "even" : "odd"),
        (x) => x * 10,
    ),
); // { even: [20, 40], odd: [10, 30] }

includes

function Array.includes<T>(
    target: readonly T[],
    value: NoInfer<T>,
): boolean

Returns true if array contains value, otherwise returns false.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 4], Array.includes(3)); // true

includesAll

function Array.includesAll<T>(
    target: readonly T[],
    values: Iterable<NoInfer<T>>,
): boolean

Returns true if array contains all values, otherwise returns false. Supports iterables for the values parameter.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 4], Array.includesAll([2, 3])); // true

includesAny

function Array.includesAny<T>(
    target: readonly T[],
    values: Iterable<NoInfer<T>>,
): boolean

Returns true if array contains any of the values, otherwise returns false. Supports iterables for the values parameter.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 4], Array.includesAny([5, 6, 2])); // true

includesNone

function Array.includesNone<T>(
    target: readonly T[],
    values: Iterable<NoInfer<T>>,
): boolean

Returns true if array contains none of the values, otherwise returns false. Supports iterables for the values parameter.

Example

import { Array } from "@monstermann/array";

Array.includesNone([1, 2, 3, 4], [5, 6, 7]); // true

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 4], Array.includesNone([5, 6, 7])); // true

indexBy

function Array.indexBy<T extends object, U extends PropertyKey>(
    target: readonly T[],
    by: (
        value: NoInfer<T>,
        idx: number,
        target: readonly NoInfer<T>[],
    ) => U,
): Record<U, T>

Creates a record by indexing the target array using the by function to generate keys. Optionally transforms values using the transform function.

Example

import { Array } from "@monstermann/array";

const users = [
    { id: 1, name: "Alice" },
    { id: 2, name: "Bob" },
];

Array.indexBy(users, (user) => user.id);
// { 1: { id: 1, name: 'Alice' }, 2: { id: 2, name: 'Bob' } }

Array.indexBy(
    users,
    (user) => user.id,
    (user) => user.name,
); // { 1: "Alice", 2: "Bob" }

import { Array } from "@monstermann/array";

pipe(
    users,
    Array.indexBy((user) => user.id),
); // { 1: { id: 1, name: 'Alice' }, 2: { id: 2, name: 'Bob' } }

pipe(
    users,
    Array.indexBy(
        (user) => user.id,
        (user) => user.name,
    ),
); // { 1: "Alice", 2: "Bob" }

indexOf

function Array.indexOf<T>(
    target: readonly T[],
    value: NoInfer<T>,
): number

Returns the first index at which value can be found in array, or -1 if it is not present.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

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

indexOfOr

function Array.indexOfOr<T, U>(
    target: readonly T[],
    value: NoInfer<T>,
    or: U,
): number | U

Returns the index of the first occurrence of value in target. If value is not found, returns or.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 2], Array.indexOfOr(2, -1)); // 1
pipe([1, 2, 3], Array.indexOfOr(4, -1)); // -1

indexOfOrElse

function Array.indexOfOrElse<T, U>(
    target: readonly T[],
    value: NoInfer<T>,
    orElse: (target: readonly NoInfer<T>[]) => U,
): number | U

Returns the index of the first occurrence of value in target. If value is not found, calls orElse with the original array.

Example

import { Array } from "@monstermann/array";

Array.indexOfOrElse([1, 2, 3, 2], 2, () => -1); // 1
Array.indexOfOrElse([1, 2, 3], 4, (arr) => arr.length); // 3

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 2],
    Array.indexOfOrElse(2, () => -1),
); // 1

pipe(
    [1, 2, 3],
    Array.indexOfOrElse(4, (arr) => arr.length),
); // 3

indexOfOrThrow

function Array.indexOfOrThrow<T>(
    target: readonly T[],
    value: NoInfer<T>,
): number

Returns the index of the first occurrence of value in target. If value is not found, throws an error.

Example

import { Array } from "@monstermann/array";

Array.indexOfOrThrow([1, 2, 3, 2], 2); // 1
Array.indexOfOrThrow([1, 2, 3], 4); // throws FnError

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 2], Array.indexOfOrThrow(2)); // 1
pipe([1, 2, 3], Array.indexOfOrThrow(4)); // throws FnError

insertAllAt

function Array.insertAllAt<T>(
    target: readonly T[],
    idx: number,
    values: Iterable<NoInfer<T>>,
): readonly T[]

Inserts all elements from values at the specified index in array, returning a new array with the inserted elements. Supports iterables for the values parameter.

Example

import { Array } from "@monstermann/array";

Array.insertAllAt([1, 2, 3], 1, [10, 20]); // [1, 10, 20, 2, 3]

import { Array } from "@monstermann/array";

pipe([1, 2, 3], Array.insertAllAt(1, [10, 20])); // [1, 10, 20, 2, 3]

insertAllAtOr

function Array.insertAllAtOr<T, U>(
    target: readonly T[],
    idx: number,
    values: Iterable<NoInfer<T>>,
    or: U,
): readonly T[] | U

Inserts all values at the specified idx in target. If the index is out of bounds, returns or. Supports iterables.

Example

import { Array } from "@monstermann/array";

Array.insertAllAtOr([1, 2, 3], 1, [8, 9], []); // [1, 8, 9, 2, 3]
Array.insertAllAtOr([1, 2, 3], 5, [8, 9], []); // []

import { Array } from "@monstermann/array";

pipe([1, 2, 3], Array.insertAllAtOr(1, [8, 9], [])); // [1, 8, 9, 2, 3]
pipe([1, 2, 3], Array.insertAllAtOr(5, [8, 9], [])); // []

insertAllAtOrElse

function Array.insertAllAtOrElse<T, U>(
    target: readonly T[],
    idx: number,
    values: Iterable<NoInfer<T>>,
    orElse: (target: readonly NoInfer<T>[]) => U,
): readonly T[] | U

Inserts all values at the specified idx in target. If the index is out of bounds, calls orElse with the original array. Supports iterables.

Example

import { Array } from "@monstermann/array";

Array.insertAllAtOrElse([1, 2, 3], 1, [8, 9], () => []); // [1, 8, 9, 2, 3]
Array.insertAllAtOrElse([1, 2, 3], 5, [8, 9], (arr) => arr); // [1, 2, 3]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3],
    Array.insertAllAtOrElse(1, [8, 9], () => []),
); // [1, 8, 9, 2, 3]

pipe(
    [1, 2, 3],
    Array.insertAllAtOrElse(5, [8, 9], (arr) => arr),
); // [1, 2, 3]

insertAllAtOrThrow

function Array.insertAllAtOrThrow<T>(
    target: readonly T[],
    idx: number,
    values: Iterable<NoInfer<T>>,
): readonly T[]

Inserts all values at the specified idx in target. If the index is out of bounds, throws an error. Supports iterables.

Example

import { Array } from "@monstermann/array";

Array.insertAllAtOrThrow([1, 2, 3], 1, [8, 9]); // [1, 8, 9, 2, 3]
Array.insertAllAtOrThrow([1, 2, 3], 5, [8, 9]); // throws FnError

import { Array } from "@monstermann/array";

pipe([1, 2, 3], Array.insertAllAtOrThrow(1, [8, 9])); // [1, 8, 9, 2, 3]
pipe([1, 2, 3], Array.insertAllAtOrThrow(5, [8, 9])); // throws FnError

insertAt

function Array.insertAt<T>(
    target: readonly T[],
    idx: number,
    value: NoInfer<T>,
): readonly T[]

Inserts value at the specified index in array, returning a new array with the inserted element.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3], Array.insertAt(1, 10)); // [1, 10, 2, 3]

insertAtOr

function Array.insertAtOr<T, U>(
    target: readonly T[],
    idx: number,
    value: NoInfer<T>,
    or: U,
): T[] | U

Inserts value at the specified index in array, returning a new array with the inserted element, or fallback if the index is out of bounds.

Example

import { Array } from "@monstermann/array";

Array.insertAtOr([1, 2, 3], 10, 99, []); // []

import { Array } from "@monstermann/array";

pipe([1, 2, 3], Array.insertAtOr(10, 99, [])); // []

insertAtOrElse

function Array.insertAtOrElse<T, U>(
    target: readonly T[],
    idx: number,
    value: NoInfer<T>,
    orElse: (target: readonly NoInfer<T>[]) => U,
): T[] | U

Inserts value at the specified index in array, returning a new array with the inserted element, or the result of calling callback with the array if the index is out of bounds.

Example

import { Array } from "@monstermann/array";

Array.insertAtOrElse([1, 2, 3], 10, 99, (arr) => arr.length); // 3

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3],
    Array.insertAtOrElse(10, 99, (arr) => arr.length),
); // 3

insertAtOrThrow

function Array.insertAtOrThrow<T>(
    target: readonly T[],
    idx: number,
    value: NoInfer<T>,
): T[]

Inserts value at the specified index in array, returning a new array with the inserted element, or throws an error if the index is out of bounds.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3], Array.insertAtOrThrow(1, 10)); // [1, 10, 2, 3]

is

function Array.is(target: unknown): target is readonly unknown[]

Returns true if value is an array, otherwise returns false.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3], Array.is()); // true

isEmpty

function Array.isEmpty<T>(target: readonly T[]): boolean

Returns true if array has no elements, otherwise returns false.

Example

import { Array } from "@monstermann/array";

Array.isEmpty([]); // true

import { Array } from "@monstermann/array";

pipe([], Array.isEmpty()); // true

isShallowEqual

function Array.isShallowEqual<T, U extends T>(
    target: readonly T[],
    source: readonly U[],
): target is readonly U[]

Returns true if target and source have the same length and their elements are equal using shallow comparison, otherwise returns false.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3], Array.isShallowEqual([1, 2, 3])); // true

join

function Array.join<T>(
    target: readonly T[],
    separator: string,
): string

Joins all elements of array into a string, separated by the specified separator.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3], Array.join(", ")); // "1, 2, 3"

last

function Array.last<T>(target: readonly T[]): T | undefined

Returns the last element of array, or undefined if the array is empty.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

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

lastIndexOf

function Array.lastIndexOf<T>(
    target: readonly T[],
    value: NoInfer<T>,
): number

Returns the last index at which value can be found in array, or -1 if it is not present.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

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

lastIndexOfOr

function Array.lastIndexOfOr<T, U>(
    target: readonly T[],
    value: NoInfer<T>,
    or: U,
): number | U

Returns the index of the last occurrence of value in target. If value is not found, returns or.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 2], Array.lastIndexOfOr(2, -1)); // 3
pipe([1, 2, 3], Array.lastIndexOfOr(4, -1)); // -1

lastIndexOfOrElse

function Array.lastIndexOfOrElse<T, U>(
    target: readonly T[],
    value: NoInfer<T>,
    orElse: (target: readonly NoInfer<T>[]) => U,
): number | U

Returns the index of the last occurrence of value in target. If value is not found, calls orElse with the original array.

Example

import { Array } from "@monstermann/array";

Array.lastIndexOfOrElse([1, 2, 3, 2], 2, () => -1); // 3
Array.lastIndexOfOrElse([1, 2, 3], 4, (arr) => arr.length); // 3

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 2],
    Array.lastIndexOfOrElse(2, () => -1),
); // 3

pipe(
    [1, 2, 3],
    Array.lastIndexOfOrElse(4, (arr) => arr.length),
); // 3

lastIndexOfOrThrow

function Array.lastIndexOfOrThrow<T>(
    target: readonly T[],
    value: NoInfer<T>,
): number

Returns the index of the last occurrence of value in target. If value is not found, throws an error.

Example

import { Array } from "@monstermann/array";

Array.lastIndexOfOrThrow([1, 2, 3, 2], 2); // 3
Array.lastIndexOfOrThrow([1, 2, 3], 4); // throws FnError

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 2], Array.lastIndexOfOrThrow(2)); // 3
pipe([1, 2, 3], Array.lastIndexOfOrThrow(4)); // throws FnError

lastOr

function Array.lastOr<T, U>(
    target: readonly T[],
    or: U,
): Exclude<T, null | undefined> | U

Returns the last element of array, or fallback if the array is empty.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

pipe([1, 2, 3, 4], Array.lastOr(0)); // 4

lastOrElse

function Array.lastOrElse<T, U>(
    target: readonly T[],
    orElse: (target: readonly NoInfer<T>[]) => U,
): Exclude<T, null | undefined> | U

Returns the last element of array, or the result of calling callback with the array if the array is empty.

Example

import { Array } from "@monstermann/array";

Array.lastOrElse([1, 2, 3, 4], (arr) => arr.length); // 4

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.lastOrElse((arr) => arr.length),
); // 4

lastOrThrow

function Array.lastOrThrow<T>(
    target: readonly T[],
): Exclude<T, null | undefined>

Returns the last element of array, or throws an error if the array is empty.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

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

length

function Array.length<T>(target: readonly T[]): number

Returns the number of elements in array.

Example

import { Array } from "@monstermann/array";

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

import { Array } from "@monstermann/array";

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

mapAt

function Array.mapAt<T>(
    target: readonly T[],
    idx: number,
    map: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
): readonly T[]

Applies the mapper function to the element at the specified index in array, returning a new array with the mapped element.

Example

import { Array } from "@monstermann/array";

Array.mapAt([1, 2, 3, 4], 1, (x) => x * 10); // [1, 20, 3, 4]

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3, 4],
    Array.mapAt(1, (x) => x * 10),
); // [1, 20, 3, 4]

mapAtOr

function Array.mapAtOr<T, U>(
    target: readonly T[],
    idx: number,
    map: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
    or: U,
): readonly T[] | U

Applies the mapper function to the element at the specified index in array, returning a new array with the mapped element, or fallback if the index is out of bounds.

Example

import { Array } from "@monstermann/array";

Array.mapAtOr([1, 2, 3], 10, (x) => x * 10, []); // []

import { Array } from "@monstermann/array";

pipe(
    [1, 2, 3],
    Array.mapAtOr(10, (x) => x * 10, []),
); // []

mapAtOrElse

function Array.mapAtOrElse<T, U>(
    target: readonly T[],
    idx: number,
    map: (
        value: NoInfer<T>,
        index: number,
        target: readonly NoInfer<T>[],
    ) => T,
    orElse: (target: readonly NoInfer<T>[]) => U,
): readonly T[] | U

Applies the mapper function to the element at the specified index in array, returning a new array with the mapped element, or the result of calling callback with the array if the index is out of bounds.

Example

import