array
 
**Functional utilities for arrays.**
[Documentation](https://MichaelOstermann.github.io/array)
## Features
- Opt-in mutability with [`remmi`](https://michaelostermann.github.io/remmi/)
- Reference preservation (`filter(array, () => true) === array`)
- Pipe-friendly (`pipe(filter(() => true))(array)`)
- Graceful failure handling (`at()`, `atOr()`, `atOrElse()`, `atOrThrow()`)
## Installation
```sh [npm]
npm install @monstermann/array
```
```sh [pnpm]
pnpm add @monstermann/array
```
```sh [yarn]
yarn add @monstermann/array
```
```sh [bun]
bun add @monstermann/array
```
## Tree-shaking
### Installation
```sh [npm]
npm install -D @monstermann/unplugin-array
```
```sh [pnpm]
pnpm -D add @monstermann/unplugin-array
```
```sh [yarn]
yarn -D add @monstermann/unplugin-array
```
```sh [bun]
bun -D add @monstermann/unplugin-array
```
### Usage
```ts [Vite]
// vite.config.ts
import array from "@monstermann/unplugin-array/vite";
export default defineConfig({
plugins: [array()],
});
```
```ts [Rollup]
// rollup.config.js
import array from "@monstermann/unplugin-array/rollup";
export default {
plugins: [array()],
};
```
```ts [Rolldown]
// rolldown.config.js
import array from "@monstermann/unplugin-array/rolldown";
export default {
plugins: [array()],
};
```
```ts [Webpack]
// webpack.config.js
const array = require("@monstermann/unplugin-array/webpack");
module.exports = {
plugins: [array()],
};
```
```ts [Rspack]
// rspack.config.js
const array = require("@monstermann/unplugin-array/rspack");
module.exports = {
plugins: [array()],
};
```
```ts [ESBuild]
// esbuild.config.js
import { build } from "esbuild";
import array from "@monstermann/unplugin-array/esbuild";
build({
plugins: [array()],
});
```
## Array
### append
```ts
function Array.append(
target: readonly T[],
value: NoInfer,
): T[]
```
Appends `value` to the end of `array`.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.append([1, 2, 3], 4); // [1, 2, 3, 4]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3], Array.append(4)); // [1, 2, 3, 4]
```
### at
```ts
function Array.at(
target: readonly T[],
offset: number,
): T | undefined
```
Returns the value at the specified `offset`.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.at([1, 2, 3], -1); // 3
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3], Array.at(-1)); // 3
```
### atOr
```ts
function Array.atOr(
target: readonly T[],
offset: number,
or: U,
): Exclude | U
```
Returns the value at the specified `offset`. Returns `fallback` if the `offset` was out of range, or the retrieved value was nullable.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.atOr([1, null], -1, 2); // 2
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, null], Array.atOr(-1, 2)); // 2
```
### atOrElse
```ts
function Array.atOrElse(
target: readonly T[],
offset: number,
orElse: (target: readonly NoInfer[]) => U,
): Exclude | U
```
Returns the value at the specified `offset`. Calls `fallback` if the `offset` was out of range, or the retrieved value was nullable.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.atOrElse([1, null], -1, (array) => array.length); // 2
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, null],
Array.atOrElse(-1, (array) => array.length),
); // 2
```
### atOrThrow
```ts
function Array.atOrThrow(
target: readonly T[],
offset: number,
): Exclude
```
Returns the value at the specified `offset`, throws an exception if the `offset` was out of range, or the retrieved value was nullable.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.atOrThrow([1, null], -1); // Error
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, null], Array.atOrThrow(-1)); // Error
```
### clone
```ts
function Array.clone(target: readonly T[]): T[]
```
Creates a shallow copy of `array`, unless marked as mutable with `markAsMutable` inside a mutation context (see [@monstermann/remmi](https://michaelostermann.github.io/remmi/#clonearray-array)).
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.clone([1, 2, 3, 4]); // [1, 2, 3, 4]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 4], Array.clone()); // [1, 2, 3, 4]
```
### compact
```ts
function Array.compact(
target: readonly T[],
): readonly Exclude[]
```
Removes all nullable values from `array`.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.compact([1, null, undefined]); // [1]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, null, undefined], Array.compact()); // [1]
```
### concat
```ts
function Array.concat(target: T[], source: NoInfer[]): T[]
```
Concatenates `source` array to the end of `array`, returning a new array with the combined elements.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.concat([1, 2], [3, 4]); // [1, 2, 3, 4]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2], Array.concat([3, 4])); // [1, 2, 3, 4]
```
### countBy
```ts
function Array.countBy(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
): number
```
Counts the number of elements in the `target` array satisfy the provided `predicate` function.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
const isEven = (n) => n % 2 === 0;
Array.countBy([1, 2, 3, 4, 5], isEven); // 2
```
```ts [data-last]
import { Array } from "@monstermann/array";
const isEven = (n) => n % 2 === 0;
pipe([1, 2, 3, 4, 5], Array.countBy(isEven)); // 2
```
### create
```ts
function Array.create(...args: any): any
```
An alias for `Array.from(target, map?)`.
#### Example
```ts
import { Array } from "@monstermann/array";
Array.create({ length: 3 }, (_, i) => i); // [0, 1, 2]
```
### drop
```ts
function Array.drop(
target: readonly T[],
amount: number,
): readonly T[]
```
Removes the first `amount` elements from `array`.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.drop([1, 2, 3, 4, 5], 2); // [3, 4, 5]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 4, 5], Array.drop(2)); // [3, 4, 5]
```
### dropLast
```ts
function Array.dropLast(
target: readonly T[],
amount: number,
): readonly T[]
```
Removes `amount` of elements from the end of the `target` array.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.dropLast([1, 2, 3, 4, 5], 2); // [1, 2, 3]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 4, 5], Array.dropLast(2)); // [1, 2, 3]
```
### empty
```ts
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
```ts
import { Array } from "@monstermann/array";
empty; // []
```
### every
```ts
function Array.every(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
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
```
```ts [data-last]
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
```ts
function Array.filter(
target: readonly T[],
by: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
): readonly T[]
```
Filters elements from `target` array based on the predicate function `by`.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.filter([1, 2, 3, 4], (x) => x > 2); // [3, 4]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.filter((x) => x > 2),
); // [3, 4]
```
### find
```ts
function Array.find(
target: T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
): T | undefined
```
Returns the first element in `array` that satisfies the provided `predicate` function, or `undefined` if no element is found.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.find([1, 2, 3, 4], (x) => x > 2); // 3
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.find((x) => x > 2),
); // 3
```
### findIndex
```ts
function Array.findIndex(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findIndex([1, 2, 3, 4], (x) => x > 2); // 2
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findIndex((x) => x > 2),
); // 2
```
### findIndexOr
```ts
function Array.findIndexOr(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
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
```
```ts [data-last]
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
```ts
function Array.findIndexOrElse(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
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
```
```ts [data-last]
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
```ts
function Array.findIndexOrThrow(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
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
```
```ts [data-last]
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
```ts
function Array.findLast(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
): T | undefined
```
Returns the last element in `array` that satisfies the provided `predicate` function, or `undefined` if no element is found.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findLast([1, 2, 3, 4], (x) => x > 2); // 4
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findLast((x) => x > 2),
); // 4
```
### findLastIndex
```ts
function Array.findLastIndex(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findLastIndex([1, 2, 3, 4], (x) => x > 2); // 3
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findLastIndex((x) => x > 2),
); // 3
```
### findLastIndexOr
```ts
function Array.findLastIndexOr(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
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
```
```ts [data-last]
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
```ts
function Array.findLastIndexOrElse(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
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
```
```ts [data-last]
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
```ts
function Array.findLastIndexOrThrow(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
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
```
```ts [data-last]
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
```ts
function Array.findLastOr(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
or: V,
): Exclude | V
```
Returns the last element in `array` that satisfies the provided `predicate` function, or `fallback` if no element is found.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findLastOr([1, 2, 3, 4], (x) => x > 10, 0); // 0
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findLastOr((x) => x > 10, 0),
); // 0
```
### findLastOrElse
```ts
function Array.findLastOrElse(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
orElse: (target: readonly NoInfer[]) => V,
): Exclude | 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findLastOrElse(
[1, 2, 3, 4],
(x) => x > 10,
(arr) => arr.length,
); // 4
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findLastOrElse(
(x) => x > 10,
(arr) => arr.length,
),
); // 4
```
### findLastOrThrow
```ts
function Array.findLastOrThrow(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
): Exclude
```
Returns the last element in `array` that satisfies the provided `predicate` function, or throws an error if no element is found.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findLastOrThrow([1, 2, 3, 4], (x) => x > 2); // 4
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findLastOrThrow((x) => x > 2),
); // 4
```
### findMap
```ts
function Array.findMap(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
mapper: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findMap(
[1, 2, 3, 4],
(x) => x > 2,
(x) => x * 10,
); // [1, 2, 30, 4]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findMap(
(x) => x > 2,
(x) => x * 10,
),
); // [1, 2, 30, 4]
```
### findMapAll
```ts
function Array.findMapAll(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
mapper: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findMapAll(
[1, 2, 3, 4],
(x) => x > 2,
(x) => x * 10,
); // [1, 2, 30, 40]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findMapAll(
(x) => x > 2,
(x) => x * 10,
),
); // [1, 2, 30, 40]
```
### findMapLast
```ts
function Array.findMapLast(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
mapper: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findMapLast(
[1, 2, 3, 4],
(x) => x > 2,
(x) => x * 10,
); // [1, 2, 3, 40]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findMapLast(
(x) => x > 2,
(x) => x * 10,
),
); // [1, 2, 3, 40]
```
### findMapLastOr
```ts
function Array.findMapLastOr(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
mapper: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findMapLastOr(
[1, 2, 3, 4],
(x) => x > 10,
(x) => x * 10,
[],
); // []
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findMapLastOr(
(x) => x > 10,
(x) => x * 10,
[],
),
); // []
```
### findMapLastOrElse
```ts
function Array.findMapLastOrElse(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
mapper: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => T,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findMapLastOrElse(
[1, 2, 3, 4],
(x) => x > 10,
(x) => x * 10,
(arr) => arr.length,
); // 4
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findMapLastOrElse(
(x) => x > 10,
(x) => x * 10,
(arr) => arr.length,
),
); // 4
```
### findMapLastOrThrow
```ts
function Array.findMapLastOrThrow(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
mapper: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findMapLastOrThrow(
[1, 2, 3, 4],
(x) => x > 2,
(x) => x * 10,
); // [1, 2, 3, 40]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findMapLastOrThrow(
(x) => x > 2,
(x) => x * 10,
),
); // [1, 2, 3, 40]
```
### findMapOr
```ts
function Array.findMapOr(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
mapper: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findMapOr(
[1, 2, 3, 4],
(x) => x > 10,
(x) => x * 10,
[],
); // []
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findMapOr(
(x) => x > 10,
(x) => x * 10,
[],
),
); // []
```
### findMapOrElse
```ts
function Array.findMapOrElse(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
mapper: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => T,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findMapOrElse(
[1, 2, 3, 4],
(x) => x > 10,
(x) => x * 10,
(arr) => arr.length,
); // 4
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findMapOrElse(
(x) => x > 10,
(x) => x * 10,
(arr) => arr.length,
),
); // 4
```
### findMapOrThrow
```ts
function Array.findMapOrThrow(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
mapper: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findMapOrThrow(
[1, 2, 3, 4],
(x) => x > 2,
(x) => x * 10,
); // [1, 2, 30, 4]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findMapOrThrow(
(x) => x > 2,
(x) => x * 10,
),
); // [1, 2, 30, 4]
```
### findOr
```ts
function Array.findOr(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
or: V,
): Exclude | V
```
Returns the first element in `array` that satisfies the provided `predicate` function, or `fallback` if no element is found.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findOr([1, 2, 3, 4], (x) => x > 10, 0); // 0
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findOr((x) => x > 10, 0),
); // 0
```
### findOrElse
```ts
function Array.findOrElse(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
orElse: (target: readonly NoInfer[]) => V,
): Exclude | 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findOrElse(
[1, 2, 3, 4],
(x) => x > 10,
(arr) => arr.length,
); // 4
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findOrElse(
(x) => x > 10,
(arr) => arr.length,
),
); // 4
```
### findOrThrow
```ts
function Array.findOrThrow(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
): Exclude
```
Returns the first element in `array` that satisfies the provided `predicate` function, or throws an error if no element is found.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findOrThrow([1, 2, 3, 4], (x) => x > 2); // 3
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findOrThrow((x) => x > 2),
); // 3
```
### findRemove
```ts
function Array.findRemove(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findRemove([1, 2, 3, 4], (x) => x > 2); // [1, 2, 4]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findRemove((x) => x > 2),
); // [1, 2, 4]
```
### findRemoveLast
```ts
function Array.findRemoveLast(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findRemoveLast([1, 2, 3, 4], (x) => x > 2); // [1, 2, 3]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findRemoveLast((x) => x > 2),
); // [1, 2, 3]
```
### findRemoveLastOr
```ts
function Array.findRemoveLastOr(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findRemoveLastOr([1, 2, 3, 4], (x) => x > 10, []); // []
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findRemoveLastOr((x) => x > 10, []),
); // []
```
### findRemoveLastOrElse
```ts
function Array.findRemoveLastOrElse(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findRemoveLastOrElse(
[1, 2, 3, 4],
(x) => x > 10,
(arr) => arr.length,
); // 4
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findRemoveLastOrElse(
(x) => x > 10,
(arr) => arr.length,
),
); // 4
```
### findRemoveLastOrThrow
```ts
function Array.findRemoveLastOrThrow(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findRemoveLastOrThrow([1, 2, 3, 4], (x) => x > 2); // [1, 2, 3]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findRemoveLastOrThrow((x) => x > 2),
); // [1, 2, 3]
```
### findRemoveOr
```ts
function Array.findRemoveOr(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findRemoveOr([1, 2, 3, 4], (x) => x > 10, []); // []
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findRemoveOr((x) => x > 10, []),
); // []
```
### findRemoveOrElse
```ts
function Array.findRemoveOrElse(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findRemoveOrElse(
[1, 2, 3, 4],
(x) => x > 10,
(arr) => arr.length,
); // 4
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findRemoveOrElse(
(x) => x > 10,
(arr) => arr.length,
),
); // 4
```
### findRemoveOrThrow
```ts
function Array.findRemoveOrThrow(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findRemoveOrThrow([1, 2, 3, 4], (x) => x > 2); // [1, 2, 4]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findRemoveOrThrow((x) => x > 2),
); // [1, 2, 4]
```
### findReplace
```ts
function Array.findReplace(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
replacement: NoInfer,
): 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findReplace([1, 2, 3, 4], (x) => x > 2, 10); // [1, 2, 10, 4]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findReplace((x) => x > 2, 10),
); // [1, 2, 10, 4]
```
### findReplaceLast
```ts
function Array.findReplaceLast(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
replacement: NoInfer,
): 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findReplaceLast([1, 2, 3, 4], (x) => x > 2, 10); // [1, 2, 3, 10]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findReplaceLast((x) => x > 2, 10),
); // [1, 2, 3, 10]
```
### findReplaceLastOr
```ts
function Array.findReplaceLastOr(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
replacement: NoInfer,
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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findReplaceLastOr([1, 2, 3, 4], (x) => x > 10, 99, []); // []
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findReplaceLastOr((x) => x > 10, 99, []),
); // []
```
### findReplaceLastOrElse
```ts
function Array.findReplaceLastOrElse(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
replacement: NoInfer,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findReplaceLastOrElse(
[1, 2, 3, 4],
(x) => x > 10,
99,
(arr) => arr.length,
); // 4
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findReplaceLastOrElse(
(x) => x > 10,
99,
(arr) => arr.length,
),
); // 4
```
### findReplaceLastOrThrow
```ts
function Array.findReplaceLastOrThrow(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
replacement: NoInfer,
): 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findReplaceLastOrThrow([1, 2, 3, 4], (x) => x > 2, 99); // [1, 2, 3, 99]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findReplaceLastOrThrow((x) => x > 2, 99),
); // [1, 2, 3, 99]
```
### findReplaceOr
```ts
function Array.findReplaceOr(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
replacement: NoInfer,
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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findReplaceOr([1, 2, 3, 4], (x) => x > 10, 99, []); // []
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findReplaceOr((x) => x > 10, 99, []),
); // []
```
### findReplaceOrElse
```ts
function Array.findReplaceOrElse(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
replacement: NoInfer,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findReplaceOrElse(
[1, 2, 3, 4],
(x) => x > 10,
99,
(arr) => arr.length,
); // 4
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findReplaceOrElse(
(x) => x > 10,
99,
(arr) => arr.length,
),
); // 4
```
### findReplaceOrThrow
```ts
function Array.findReplaceOrThrow(
target: readonly T[],
predicate: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => boolean,
replacement: NoInfer,
): 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.findReplaceOrThrow([1, 2, 3, 4], (x) => x > 2, 99); // [1, 2, 99, 4]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.findReplaceOrThrow((x) => x > 2, 99),
); // [1, 2, 99, 4]
```
### first
```ts
function Array.first(target: readonly T[]): T | undefined
```
Returns the first element of `array`, or `undefined` if the array is empty.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.first([1, 2, 3, 4]); // 1
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 4], Array.first()); // 1
```
### firstOr
```ts
function Array.firstOr(
target: readonly T[],
or: U,
): Exclude | U
```
Returns the first element of `array`, or `fallback` if the array is empty.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.firstOr([1, 2, 3, 4], 0); // 1
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 4], Array.firstOr(0)); // 1
```
### firstOrElse
```ts
function Array.firstOrElse(
target: readonly T[],
orElse: (target: readonly NoInfer[]) => U,
): Exclude | U
```
Returns the first element of `array`, or the result of calling `callback` with the array if the array is empty.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.firstOrElse([1, 2, 3, 4], (arr) => arr.length); // 1
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3, 4],
Array.firstOrElse((arr) => arr.length),
); // 1
```
### firstOrThrow
```ts
function Array.firstOrThrow(
target: readonly T[],
): Exclude
```
Returns the first element of `array`, or throws an error if the array is empty.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.firstOrThrow([1, 2, 3, 4]); // 1
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 4], Array.firstOrThrow()); // 1
```
### flatMap
```ts
function Array.flatMap(
target: readonly T[],
mapper: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => U[],
): readonly U[]
```
Maps each element in `array` using the `mapper` function and flattens the result by one level.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.flatMap([1, 2, 3], (x) => [x, x * 2]); // [1, 2, 2, 4, 3, 6]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3],
Array.flatMap((x) => [x, x * 2]),
); // [1, 2, 2, 4, 3, 6]
```
### forEach
```ts
function Array.forEach(
target: readonly T[],
callback: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => any,
): readonly T[]
```
Executes the provided `callback` function once for each element in `array` and returns the original array.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.forEach([1, 2, 3], (x) => console.log(x)); // [1, 2, 3]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3],
Array.forEach((x) => console.log(x)),
); // [1, 2, 3]
```
### forEachRight
```ts
function Array.forEachRight(
target: readonly T[],
callback: (
value: NoInfer,
index: number,
target: readonly NoInfer[],
) => any,
): readonly T[]
```
Executes the provided `callback` function once for each element in `array` in reverse order and returns the original array.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.forEachRight([1, 2, 3], (x) => console.log(x)); // [1, 2, 3]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3],
Array.forEachRight((x) => console.log(x)),
); // [1, 2, 3]
```
### groupBy
```ts
function Array.groupBy(
target: readonly T[],
by: (
value: NoInfer,
idx: number,
target: readonly NoInfer[],
) => U,
): Record
```
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
```ts [data-first]
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] }
```
```ts [data-last]
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
```ts
function Array.includes(
target: readonly T[],
value: NoInfer,
): boolean
```
Returns `true` if `array` contains `value`, otherwise returns `false`.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.includes([1, 2, 3, 4], 3); // true
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 4], Array.includes(3)); // true
```
### includesAll
```ts
function Array.includesAll(
target: readonly T[],
values: Iterable>,
): boolean
```
Returns `true` if `array` contains all `values`, otherwise returns `false`. Supports iterables for the `values` parameter.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.includesAll([1, 2, 3, 4], [2, 3]); // true
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 4], Array.includesAll([2, 3])); // true
```
### includesAny
```ts
function Array.includesAny(
target: readonly T[],
values: Iterable>,
): boolean
```
Returns `true` if `array` contains any of the `values`, otherwise returns `false`. Supports iterables for the `values` parameter.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.includesAny([1, 2, 3, 4], [5, 6, 2]); // true
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 4], Array.includesAny([5, 6, 2])); // true
```
### includesNone
```ts
function Array.includesNone(
target: readonly T[],
values: Iterable>,
): boolean
```
Returns `true` if `array` contains none of the `values`, otherwise returns `false`. Supports iterables for the `values` parameter.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.includesNone([1, 2, 3, 4], [5, 6, 7]); // true
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 4], Array.includesNone([5, 6, 7])); // true
```
### indexBy
```ts
function Array.indexBy(
target: readonly T[],
by: (
value: NoInfer,
idx: number,
target: readonly NoInfer[],
) => U,
): Record
```
Creates a record by indexing the `target` array using the `by` function to generate keys. Optionally transforms values using the `transform` function.
#### Example
```ts [data-first]
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" }
```
```ts [data-last]
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
```ts
function Array.indexOf(
target: readonly T[],
value: NoInfer,
): number
```
Returns the first index at which `value` can be found in `array`, or -1 if it is not present.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.indexOf([1, 2, 3, 2, 4], 2); // 1
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 2, 4], Array.indexOf(2)); // 1
```
### indexOfOr
```ts
function Array.indexOfOr(
target: readonly T[],
value: NoInfer,
or: U,
): number | U
```
Returns the index of the first occurrence of `value` in `target`. If `value` is not found, returns `or`.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.indexOfOr([1, 2, 3, 2], 2, -1); // 1
Array.indexOfOr([1, 2, 3], 4, -1); // -1
```
```ts [data-last]
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
```ts
function Array.indexOfOrElse(
target: readonly T[],
value: NoInfer,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.indexOfOrElse([1, 2, 3, 2], 2, () => -1); // 1
Array.indexOfOrElse([1, 2, 3], 4, (arr) => arr.length); // 3
```
```ts [data-last]
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
```ts
function Array.indexOfOrThrow(
target: readonly T[],
value: NoInfer,
): number
```
Returns the index of the first occurrence of `value` in `target`. If `value` is not found, throws an error.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.indexOfOrThrow([1, 2, 3, 2], 2); // 1
Array.indexOfOrThrow([1, 2, 3], 4); // throws FnError
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3, 2], Array.indexOfOrThrow(2)); // 1
pipe([1, 2, 3], Array.indexOfOrThrow(4)); // throws FnError
```
### insertAllAt
```ts
function Array.insertAllAt(
target: readonly T[],
idx: number,
values: Iterable>,
): 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.insertAllAt([1, 2, 3], 1, [10, 20]); // [1, 10, 20, 2, 3]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3], Array.insertAllAt(1, [10, 20])); // [1, 10, 20, 2, 3]
```
### insertAllAtOr
```ts
function Array.insertAllAtOr(
target: readonly T[],
idx: number,
values: Iterable>,
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
```ts [data-first]
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], []); // []
```
```ts [data-last]
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
```ts
function Array.insertAllAtOrElse(
target: readonly T[],
idx: number,
values: Iterable>,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
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]
```
```ts [data-last]
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
```ts
function Array.insertAllAtOrThrow(
target: readonly T[],
idx: number,
values: Iterable>,
): readonly T[]
```
Inserts all `values` at the specified `idx` in `target`. If the index is out of bounds, throws an error. Supports iterables.
#### Example
```ts [data-first]
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
```
```ts [data-last]
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
```ts
function Array.insertAt(
target: readonly T[],
idx: number,
value: NoInfer,
): readonly T[]
```
Inserts `value` at the specified `index` in `array`, returning a new array with the inserted element.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.insertAt([1, 2, 3], 1, 10); // [1, 10, 2, 3]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3], Array.insertAt(1, 10)); // [1, 10, 2, 3]
```
### insertAtOr
```ts
function Array.insertAtOr(
target: readonly T[],
idx: number,
value: NoInfer,
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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.insertAtOr([1, 2, 3], 10, 99, []); // []
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3], Array.insertAtOr(10, 99, [])); // []
```
### insertAtOrElse
```ts
function Array.insertAtOrElse(
target: readonly T[],
idx: number,
value: NoInfer,
orElse: (target: readonly NoInfer[]) => 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.insertAtOrElse([1, 2, 3], 10, 99, (arr) => arr.length); // 3
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe(
[1, 2, 3],
Array.insertAtOrElse(10, 99, (arr) => arr.length),
); // 3
```
### insertAtOrThrow
```ts
function Array.insertAtOrThrow(
target: readonly T[],
idx: number,
value: NoInfer,
): 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
```ts [data-first]
import { Array } from "@monstermann/array";
Array.insertAtOrThrow([1, 2, 3], 1, 10); // [1, 10, 2, 3]
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3], Array.insertAtOrThrow(1, 10)); // [1, 10, 2, 3]
```
### is
```ts
function Array.is(target: unknown): target is readonly unknown[]
```
Returns `true` if `value` is an array, otherwise returns `false`.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.is([1, 2, 3]); // true
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([1, 2, 3], Array.is()); // true
```
### isEmpty
```ts
function Array.isEmpty(target: readonly T[]): boolean
```
Returns `true` if `array` has no elements, otherwise returns `false`.
#### Example
```ts [data-first]
import { Array } from "@monstermann/array";
Array.isEmpty([]); // true
```
```ts [data-last]
import { Array } from "@monstermann/array";
pipe([], Array.isEmpty()); // true
```
### isShallowEqual
```ts
function Array.isShallowEqual