array

Functional utilities for arrays.

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(array: T[], value: 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(array: 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(array: T[], offset: number, fallback: U): T | 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(
    array: T[],
    offset: number,
    fallback: (array: T[]) => U
): T | 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(array: T[], offset: number): T

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(array: 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(array: T[]): T[]

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(array: T[], source: 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(
    array: T[],
    predicate: (value: T, index: number, array: 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(
    target: Iterable<T> | ArrayLike<T>,
    map?: (value: T, index: number) => U
): U[]

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(array: T[], amount: number): 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(array: T[], amount: number): 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(
    array: T[],
    predicate: (value: T, index: number, array: 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean
): 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(
    array: T[],
    predicate: (value: T, index: number, array: 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(
    array: T[],
    predicate: (value: T, index: number, array: 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: (array: 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(
    array: T[],
    predicate: (value: T, index: number, array: 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(
    array: T[],
    predicate: (value: T, index: number, array: 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(
    array: T[],
    predicate: (value: T, index: number, array: 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: (array: 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(
    array: T[],
    predicate: (value: T, index: number, array: 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: U
): T | U

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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: (array: T[]) => U
): T | U

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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean
): T

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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    mapper: (value: T, index: number, array: T[]) => U
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    mapper: (value: T, index: number, array: T[]) => U
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    mapper: (value: T, index: number, array: T[]) => U
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    mapper: (value: T, index: number, array: T[]) => U,
    fallback: V
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    mapper: (value: T, index: number, array: T[]) => U,
    fallback: (array: T[]) => V
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    mapper: (value: T, index: number, array: T[]) => U
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    mapper: (value: T, index: number, array: T[]) => U,
    fallback: V
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    mapper: (value: T, index: number, array: T[]) => U,
    fallback: (array: T[]) => V
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    mapper: (value: T, index: number, array: T[]) => U
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: U
): T | U

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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: (array: T[]) => U
): T | U

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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean
): T

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(
    array: T[],
    predicate: (value: T, index: number, array: 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.

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(
    array: T[],
    predicate: (value: T, index: number, array: 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.

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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: (array: 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(
    array: T[],
    predicate: (value: T, index: number, array: 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    fallback: (array: 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(
    array: T[],
    predicate: (value: T, index: number, array: 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    value: U
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    value: U
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    value: U,
    fallback: V
): T[] | V

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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    value: U,
    fallback: (array: T[]) => V
): T[] | V

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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    value: U
): 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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    value: U,
    fallback: V
): T[] | V

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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    value: U,
    fallback: (array: T[]) => V
): T[] | V

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(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean,
    value: U
): 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(array: 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(array: T[], fallback: U): T | 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(array: T[], fallback: (array: T[]) => U): T | 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(array: T[]): T

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(
    array: T[],
    mapper: (value: T, index: number, array: T[]) => U[]
): 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(
    array: T[],
    callback: (value: T, index: number, array: T[]) => void
): 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(
    array: T[],
    callback: (value: T, index: number, array: T[]) => void
): 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(
    array: T[],
    keySelector: (value: T, index: number, array: T[]) => string
): Record<string, 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(array: T[], value: 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(array: T[], values: 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(array: T[], values: 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(array: T[], values: 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(
    array: T[],
    keySelector: (value: T, index: number, array: T[]) => string
): Record<string, 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(array: T[], value: 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(array: T[], value: T, fallback: 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(
    array: T[],
    value: T,
    fallback: (array: 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(array: T[], value: 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(array: T[], index: number, values: U[]): 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(
    array: T[],
    index: number,
    values: U[],
    fallback: V
): T[] | V

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(
    array: T[],
    index: number,
    values: U[],
    fallback: (array: T[]) => V
): T[] | V

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(array: T[], index: number, values: U[]): 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(array: T[], index: number, value: U): 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(array: T[], index: number, value: U, fallback: V): T[] | V

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(
    array: T[],
    index: number,
    value: U,
    fallback: (array: T[]) => V
): T[] | V

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(array: T[], index: number, value: U): 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(value: unknown): boolean

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(array: 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(target: T[], source: T[]): boolean

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(array: 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(array: 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(array: T[], value: 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(array: T[], value: T, fallback: 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(
    array: T[],
    value: T,
    fallback: (array: 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(array: T[], value: 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(array: T[], fallback: U): T | 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(array: T[], fallback: (array: T[]) => U): T | 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(array: T[]): T

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(array: 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(
    array: T[],
    index: number,
    mapper: (value: T, index: number, array: T[]) => U
): 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(
    array: T[],
    index: number,
    mapper: (value: T, index: number, array: T[]) => U,
    fallback: V
): T[] | V

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(
    array: T[],
    index: number,
    mapper: (value: T, index: number, array: T[]) => U,
    fallback: (array: T[]) => V
): T[] | V

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 { Array } from "@monstermann/array";

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

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

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

mapAtOrThrow

function Array.mapAtOrThrow(
    array: T[],
    index: number,
    mapper: (value: T, index: number, array: T[]) => U
): T[]

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

Example

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

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

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

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

mapEach

function Array.mapEach(
    array: T[],
    mapper: (value: T, index: number, array: T[]) => U
): U[]

Applies the mapper function to each element in array, returning a new array with the mapped elements.

Example

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

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

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

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

maxOr

function Array.maxOr(array: number[], fallback: U): number | U

Returns the maximum value in the number array, or fallback if the array is empty.

Example

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

Array.maxOr([1, 3, 2, 5], 0); // 5

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

pipe([1, 3, 2, 5], Array.maxOr(0)); // 5

maxOrElse

function Array.maxOrElse(
    array: number[],
    fallback: (array: number[]) => U
): number | U

Returns the maximum value from array, or calls orElse if the array is empty.

Example

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

Array.maxOrElse([1, 5, 3], () => 0); // 5
Array.maxOrElse([], () => 0); // 0

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

pipe(
    [1, 5, 3],
    Array.maxOrElse(() => 0),
); // 5

pipe(
    [],
    Array.maxOrElse(() => 0),
); // 0

maxOrThrow

function Array.maxOrThrow(array: number[]): number

Returns the maximum value from array, or throws an error if the array is empty.

Example

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

Array.maxOrThrow([1, 5, 3]); // 5
Array.maxOrThrow([]); // throws FnError

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

pipe([1, 5, 3], Array.maxOrThrow()); // 5
pipe([], Array.maxOrThrow()); // throws FnError

meanOr

function Array.meanOr(array: number[], fallback: U): number | U

Returns the mean (average) value of the number array, or fallback if the array is empty.

Example

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

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

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

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

meanOrElse

function Array.meanOrElse(
    array: number[],
    fallback: (array: number[]) => U
): number | U

Returns the mean (average) value from array, or calls orElse if the array is empty.

Example

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

Array.meanOrElse([1, 2, 3], () => 0); // 2
Array.meanOrElse([], () => 0); // 0

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

pipe(
    [1, 2, 3],
    Array.meanOrElse(() => 0),
); // 2

pipe(
    [],
    Array.meanOrElse(() => 0),
); // 0

meanOrThrow

function Array.meanOrThrow(array: number[]): number

Returns the mean (average) value from array, or throws an error if the array is empty.

Example

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

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

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

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

medianOr

function Array.medianOr(array: number[], fallback: U): number | U

Returns the median value of the number array, or fallback if the array is empty.

Example

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

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

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

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

medianOrElse

function Array.medianOrElse(
    array: number[],
    fallback: (array: number[]) => U
): number | U

Returns the median value from array, or calls orElse if the array is empty.

Example

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

Array.medianOrElse([1, 3, 5], () => 0); // 3
Array.medianOrElse([1, 2, 3, 4], () => 0); // 2.5
Array.medianOrElse([], () => 0); // 0

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

pipe(
    [1, 3, 5],
    Array.medianOrElse(() => 0),
); // 3

pipe(
    [1, 2, 3, 4],
    Array.medianOrElse(() => 0),
); // 2.5

pipe(
    [],
    Array.medianOrElse(() => 0),
); // 0

medianOrThrow

function Array.medianOrThrow(array: number[]): number

Returns the median value from array, or throws an error if the array is empty.

Example

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

Array.medianOrThrow([1, 3, 5]); // 3
Array.medianOrThrow([1, 2, 3, 4]); // 2.5
Array.medianOrThrow([]); // throws FnError

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

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

minOr

function Array.minOr(array: number[], fallback: U): number | U

Returns the minimum value in the number array, or fallback if the array is empty.

Example

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

Array.minOr([5, 1, 3, 2], 0); // 1

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

pipe([5, 1, 3, 2], Array.minOr(0)); // 1

minOrElse

function Array.minOrElse(
    array: number[],
    fallback: (array: number[]) => U
): number | U

Returns the minimum value from target array, or calls orElse if the array is empty.

Example

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

Array.minOrElse([5, 2, 8, 1], () => 0); // 1
Array.minOrElse([], () => 0); // 0

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

pipe(
    [5, 2, 8, 1],
    Array.minOrElse(() => 0),
); // 1

pipe(
    [],
    Array.minOrElse(() => 0),
); // 0

minOrThrow

function Array.minOrThrow(array: number[]): number

Returns the minimum value from target array, or throws an error if the array is empty.

Example

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

Array.minOrThrow([5, 2, 8, 1]); // 1
Array.minOrThrow([]); // throws FnError

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

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

none

function Array.none(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean
): boolean

Returns true if no elements in array satisfy the provided predicate function, otherwise returns false.

Example

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

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

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

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

partition

function Array.partition(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean
): [T[], T[]]

Splits array into two arrays based on the predicate function, returning a tuple where the first array contains elements that satisfy the predicate and the second contains those that don't.

Example

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

Array.partition([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [[2, 4], [1, 3, 5]]

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

pipe(
    [1, 2, 3, 4, 5],
    Array.partition((x) => x % 2 === 0),
); // [[2, 4], [1, 3, 5]]

prepend

function Array.prepend(array: T[], value: U): T[]

Adds value to the beginning of array.

Example

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

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

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

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

random

function Array.random(array: T[]): T | undefined

Returns a random element from array, or undefined if the array is empty.

Example

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

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

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

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

randomOr

function Array.randomOr(array: T[], fallback: U): T | U

Returns a random element from array, or fallback if the array is empty.

Example

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

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

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

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

randomOrElse

function Array.randomOrElse(array: T[], fallback: (array: T[]) => U): T | U

Returns a random element from array, or the result of calling callback with the array if the array is empty.

Example

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

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

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

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

reduce

function Array.reduce(
    array: T[],
    reducer: (acc: U, value: T, index: number, array: T[]) => U,
    initial: U
): U

Reduces array to a single value by executing the reducer function on each element, starting with the initial accumulator value.

Example

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

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

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

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

reject

function Array.reject(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean
): T[]

Returns a new array with elements from array that do not satisfy the provided predicate function.

Example

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

Array.reject([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [1, 3, 5]

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

pipe(
    [1, 2, 3, 4, 5],
    Array.reject((x) => x % 2 === 0),
); // [1, 3, 5]

remove

function Array.remove(array: T[], value: U): T[]

Removes the first occurrence of value from target array. If the value is not found, returns the original array unchanged.

Example

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

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

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

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

removeAll

function Array.removeAll(array: T[], values: Iterable<T>): T[]

Removes all occurrences of each value in values from target array. If no values are found, returns the original array unchanged.

Example

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

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

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

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

removeAt

function Array.removeAt(array: T[], index: number): T[]

Removes the element at index idx from target array. Supports negative indices to count from the end. If the index is out of bounds, returns the original array unchanged.

Example

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

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

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

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

removeAtOr

function Array.removeAtOr(array: T[], index: number, fallback: U): T[] | U

Removes the element at index idx from target array. Supports negative indices to count from the end. If the index is out of bounds, returns the fallback value or.

Example

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

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

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

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

removeAtOrElse

function Array.removeAtOrElse(
    array: T[],
    index: number,
    fallback: (array: T[]) => U
): T[] | U

Removes the element at index idx from target array. Supports negative indices to count from the end. If the index is out of bounds, calls the orElse function with the original array and returns its result.

Example

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

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

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

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

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

removeAtOrThrow

function Array.removeAtOrThrow(array: T[], index: number): T[]

Removes the element at index idx from target array. Supports negative indices to count from the end. If the index is out of bounds, throws an error.

Example

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

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

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

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

removeLast

function Array.removeLast(array: T[], value: U): T[]

Removes the last occurrence of value from target array. If the value is not found, returns the original array unchanged.

Example

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

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

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

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

removeLastOr

function Array.removeLastOr(array: T[], value: U, fallback: V): T[] | V

Removes the last occurrence of value from target array. If the value is not found, returns the fallback value or.

Example

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

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

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

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

removeLastOrElse

function Array.removeLastOrElse(
    array: T[],
    value: U,
    fallback: (array: T[]) => V
): T[] | V

Removes the last occurrence of value from target array. If the value is not found, calls the orElse function with the original array and returns its result.

Example

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

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

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

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

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

removeLastOrThrow

function Array.removeLastOrThrow(array: T[], value: U): T[]

Removes the last occurrence of value from target array. If the value is not found, throws an error.

Example

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

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

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

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

removeOrElse

function Array.removeOrElse(
    array: T[],
    value: U,
    fallback: (array: T[]) => V
): T[] | V

Removes the first occurrence of value from target array. If the value is not found, calls the orElse function with the original array and returns its result.

Example

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

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

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

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

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

removeOrThrow

function Array.removeOrThrow(array: T[], value: U): T[]

Removes the first occurrence of value from target array. If the value is not found, throws an error.

Example

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

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

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

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

replace

function Array.replace(array: T[], oldValue: U, newValue: V): T[]

Replaces the first occurrence of value with replacement in target array. If the value is not found or if value and replacement are the same, returns the original array unchanged.

Example

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

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

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

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

replaceLast

function Array.replaceLast(array: T[], oldValue: U, newValue: V): T[]

Replaces the last occurrence of value with replacement in target array. If the value is not found or if value and replacement are the same, returns the original array unchanged.

Example

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

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

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

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

replaceLastOr

function Array.replaceLastOr(
    array: T[],
    oldValue: U,
    newValue: V,
    fallback: W
): T[] | W

Replaces the last occurrence of value with replacement in target array. If the value is not found, returns the fallback value or. If value and replacement are the same, returns the original array unchanged.

Example

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

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

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

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

replaceLastOrElse

function Array.replaceLastOrElse(
    array: T[],
    oldValue: U,
    newValue: V,
    fallback: (array: T[]) => W
): T[] | W

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

Example

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

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

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

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

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

replaceLastOrThrow

function Array.replaceLastOrThrow(array: T[], oldValue: U, newValue: V): T[]

Replaces the last occurrence of value in target with replacement. If value is not found, throws an error.

Example

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

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

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

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

replaceOr

function Array.replaceOr(
    array: T[],
    oldValue: U,
    newValue: V,
    fallback: W
): T[] | W

Replaces the first occurrence of value in target with replacement. If value is not found, returns or.

Example

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

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

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

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

replaceOrElse

function Array.replaceOrElse(
    array: T[],
    oldValue: U,
    newValue: V,
    fallback: (array: T[]) => W
): T[] | W

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

Example

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

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

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

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

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

replaceOrThrow

function Array.replaceOrThrow(array: T[], oldValue: U, newValue: V): T[]

Replaces the first occurrence of value in target with replacement. If value is not found, throws an error.

Example

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

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

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

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

setAt

function Array.setAt(array: T[], index: number, value: U): T[]

Sets the value at the specified idx in target to value. Returns the original array if the index is out of bounds or the value is already the same.

Example

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

Array.setAt([1, 2, 3], 1, 9); // [1, 9, 3]
Array.setAt([1, 2, 3], -1, 9); // [1, 2, 9]
Array.setAt([1, 2, 3], 5, 9); // [1, 2, 3]

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

pipe([1, 2, 3], Array.setAt(1, 9)); // [1, 9, 3]
pipe([1, 2, 3], Array.setAt(-1, 9)); // [1, 2, 9]
pipe([1, 2, 3], Array.setAt(5, 9)); // [1, 2, 3]

setAtOr

function Array.setAtOr(array: T[], index: number, value: U, fallback: V): T[] | V

Sets the value at the specified idx in target to value. If the index is out of bounds, returns or.

Example

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

Array.setAtOr([1, 2, 3], 1, 9, []); // [1, 9, 3]
Array.setAtOr([1, 2, 3], -1, 9, []); // [1, 2, 9]
Array.setAtOr([1, 2, 3], 5, 9, []); // []

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

pipe([1, 2, 3], Array.setAtOr(1, 9, [])); // [1, 9, 3]
pipe([1, 2, 3], Array.setAtOr(-1, 9, [])); // [1, 2, 9]
pipe([1, 2, 3], Array.setAtOr(5, 9, [])); // []

setAtOrElse

function Array.setAtOrElse(
    array: T[],
    index: number,
    value: U,
    fallback: (array: T[]) => V
): T[] | V

Sets the value at the specified idx in target to value. If the index is out of bounds, calls orElse with the original array.

Example

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

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

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

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

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

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

setAtOrThrow

function Array.setAtOrThrow(
    array: T[],
    index: number,
    value: U
): T[]

Sets the value at the specified idx in target to value. If the index is out of bounds, throws an error.

Example

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

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

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

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

shuffle

function Array.shuffle(array: T[]): T[]

Returns a new array with the elements of array randomly shuffled.

Example

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

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

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

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

slice

function Array.slice(array: T[], start?: number, end?: number): T[]

Extracts a section of target array from start index to end index (exclusive). If end is not provided, extracts to the end of the array.

Example

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

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

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

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

some

function Array.some(
    array: T[],
    predicate: (value: T, index: number, array: T[]) => boolean
): boolean

Returns true if at least one element in array satisfies the provided predicate function, otherwise returns false.

Example

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

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

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

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

sort

function Array.sort(array: T[], compareFn?: (a: T, b: T) => number): T[]

Returns a new array with the elements of target sorted using the provided comparator function.

Example

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

Array.sort([3, 1, 4, 2], (a, b) => a - b); // [1, 2, 3, 4]
Array.sort(["c", "a", "b"], (a, b) => a.localeCompare(b)); // ['a', 'b', 'c']

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

pipe(
    [3, 1, 4, 2],
    Array.sort((a, b) => a - b),
); // [1, 2, 3, 4]

pipe(
    ["c", "a", "b"],
    Array.sort((a, b) => a.localeCompare(b)),
); // ['a', 'b', 'c']

sum

function Array.sum(array: number[]): number

Returns the sum of all numbers in array.

Example

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

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

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

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

take

function Array.take(array: T[], count: number): T[]

Returns a new array containing the first amount elements from array.

Example

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

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

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

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

takeLast

function Array.takeLast(array: T[], count: number): T[]

Returns a new array containing the last amount elements from array.

Example

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

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

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

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

union

function Array.union(target: T[], source: T[]): T[]

Returns a new array containing all unique elements from both target and source. Elements from source that are not already in target are added to the result.

Example

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

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

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

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

unique

function Array.unique(array: T[]): T[]

Returns a new array with only the unique elements from target, preserving the order of first occurrence.

Example

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

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

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github/workflows		.github/workflows
benchmarks		benchmarks
docs		docs
packages		packages
playground		playground
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
barrels.config.ts		barrels.config.ts
bun.lock		bun.lock
eslint.config.js		eslint.config.js
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

MichaelOstermann/array

Folders and files

Latest commit

History

Repository files navigation

array

Features

Installation

Tree-shaking

Installation

Usage

Array

append

Example

at

Example

atOr

Example

atOrElse

Example

atOrThrow

Example

clone

Example

compact

Example

concat

Example

countBy

Example

create

Example

drop

Example

dropLast

Example

empty

Example

every

Example

filter

Example

find

Example

findIndex

Example

findIndexOr

Example

findIndexOrElse

Example

findIndexOrThrow

Example

findLast

Example

findLastIndex

Example

findLastIndexOr

Example

findLastIndexOrElse

Example

findLastIndexOrThrow

Example

findLastOr

Example

findLastOrElse

Example

findLastOrThrow

Example

findMap

Example

findMapAll

Example

findMapLast

Example

findMapLastOr

Example

findMapLastOrElse

Example

findMapLastOrThrow