@razomy/array

Npm | Npmx | GitHub | Io

🚀 Start

Install

npm i @razomy/array

Import

import * as array from "@razomy/array";
// or
import { addMut } from "@razomy/array";

📑 Table of Contents

Functions

• addMut
• chunk
• countBy
• create
• createByIndexAndSize
• difference
• drop
• every
• filter
• find
• findIndex
• flat
• getFirst
• getLast
• groupBy
• hasArray
• includes
• insertMut
• intersection
• isArray
• isEmpty
• map
• reduce
• removeAllMut
• removeAtMut
• removeFirstMut
• removeLast
• reverse
• reverseMut
• set
• setLastMut
• some
• sortBy
• sortByArrayMut
• sortByFrequencyAndUnique
• take
• toggle
• tryFirstEqual
• tryGetLast
• tryGetLastEqual
• union
• uniq
• zip

📚 Documentation

Functions

addMut

addMut(array: T[], value: T): T[]

Add an element to the end of an array, modifying the original array.

Examples

const array = [1, 2];
addMut(array, 3);
array; // [1, 2, 3]

const array = ['a']
addMut(array, 'b');
array; // [a, b]

const array = [{ id: 1 }];
addMut(array, { id: 2 });
array; // [{ id: 1 }, { id: 2 }]

chunk

chunk(array: T[], size: number): T[][]

Splits an array into smaller arrays (chunks) of a specified size.

The last chunk may be smaller than the size.

Examples

chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]

chunk(['a', 'b', 'c', 'd', 'e', 'f'], 3); // [[a, b, c], [d, e, f]]

chunk([true, false], 5); // [[true, false]]

countBy

countBy(array: readonly T[], predicate: (value: T) => any): Record<string, number>

Count occurrences of elements grouped by a predicate.

Groups array elements by the result of a predicate function and counts occurrences of each group key.

Examples

countBy([6.1, 4.2, 6.3], Math.floor); // { 4: 1, 6: 2 }

countBy(['one', 'two', 'three'], (v) => v.length); // { 3: 2, 5: 1 }

countBy([true, false, true, true], (v) => v); // { true: 3, false: 1 }

create

create(size: number, value: T): T[]

Create an array of specific size filled with a value.

Examples

create(3, 0); // [0, 0, 0]

create(2, 'x'); // [x, x]

create(4, true); // [true, true, true, true]

createByIndexAndSize

createByIndexAndSize(index: number, size: number): number[]

Create an array of a specific size with the value 1 at the specified index.

Examples

createByIndexAndSize(0, 2); // [1, 0]

createByIndexAndSize(1, 3); // [0, 1, 0]

createByIndexAndSize(3, 4); // [0, 0, 0, 1]

difference

difference(source: T[], other: T[]): T[]

Computes the difference between two arrays.

Returns a new array with elements that are in the first array but not in the second array. The order of elements in the result is determined by the order in the first array.

Examples

difference([1, 2, 3], [2, 4]); // [1, 3]

difference(['apple', 'banana', 'orange'], ['orange', 'grape']); // [apple, banana]

difference([1, 2, 3, 4, 5], [2, 3, 4]); // [1, 5]

drop

drop(array: T[], count: number): T[]

Creates a slice of array with n elements dropped from the beginning.

Examples

drop([1, 2, 3], 1); // [2, 3]

drop([1, 2, 3], 2); // [3]

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

every

every(array: T[], predicate: (item: T, index: number, array: T[]) => boolean): boolean

Checks if all elements in the array satisfy the provided testing function.

Examples

every([2, 4, 6], (n) => n % 2 === 0); // true

every([2, 4, 7], (n) => n % 2 === 0); // false

every([], (n) => n > 5); // true

filter

filter(array: T[], predicate: (item: T, index: number, array: T[]) => boolean): T[]

Creates a new array with all elements that pass the test implemented by the provided function.

Examples

filter([1, 2, 3, 4], (n) => n % 2 === 0); // [2, 4]

filter([{ id: 1 }, { id: 2 }], (item) => item.id === 1); // [{ id: 1 }]

filter(['a', 'b', 'c'], (_, index) => index !== 1); // [a, c]

find

find(array: T[], predicate: (item: T, index: number, array: T[]) => boolean): T

Find an item in an array that matches the predicate. Throws an error if no item is found.

Examples

find([1, 2, 3], (n) => n === 2); // 2

find([{ id: 1 }, { id: 2 }], (o) => o.id === 1); // { id: 1 }

find([1, 2, 3], (n) => n === 4); // Error: Item not found.

findIndex

findIndex(array: T[], predicate: (item: T, index: number, array: T[]) => boolean): number

Returns the index of the first element in the array that satisfies the provided testing function.

Examples

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

findIndex(['a', 'b', 'c'], (x) => x !== 'b'); // 0

findIndex([1, 2, 3], (x) => x > 5); // -1

flat

flat(array: readonly (T | readonly T[])[]): T[]

Flattens an array of nested arrays by one level.

Examples

flat([[1, 2], [3, 4]]); // [1, 2, 3, 4]

flat([1, 2, [3, [4]]]); // [1, 2, 3, [4]]

flat([['a'], 'b']); // [a, b]

getFirst

getFirst(array: T[]): T

Get the first element of an array.

Examples

getFirst([1, 2, 3]); // 1

getFirst(['a', 'b', 'c']); // a

getFirst([]); // Error: Array is empty

getLast

getLast(array: T[], offset: number): T

Retrieves the last element of an array.

Optionally accepts an offset to retrieve preceding elements. Throws an error if the element is not found (e.g., empty array or out of bounds).

Examples

getLast([1, 2, 3]); // 3

getLast(['a', 'b', 'c'], 1); // b

getLast([1, 2, 3], 10); // Error: Element at offset 10 does not exist.

groupBy

groupBy(array: T[], iteratee: (item: T) => K): Record<K, T[]>

Groups the elements of an array according to the result of the iteratee function.

Examples

groupBy([6.1, 4.2, 6.3], Math.floor); // { 4: [4.2], 6: [6.1, 6.3] }

groupBy(['one', 'two', 'three'], (s) => s.length); // { 3: [one, two], 5: [three] }

groupBy([{ k: 'a', v: 1 }, { k: 'b', v: 2 }], (o) => o.k); // { a: [{ k: a, v: 1 }], b: [{ k: b, v: 2 }] }

hasArray

hasArray(source: T[], array: T[]): boolean

Check if the source array contains all elements of the sub array in the same relative order.

Examples

hasArray([1, 2, 3, 4], [2, 4]); // true

hasArray(['a', 'b', 'c'], ['c', 'a']); // false

hasArray([true, false], []); // true

includes

includes(array: T[], value: T, fromIndex: number | undefined): boolean

Checks if value is in array.

Examples

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

includes([1, 2, 3], 4); // false

includes(['a', 'b', 'c'], 'c', 1); // true

insertMut

insertMut(array: T[], index: number, item: T): T[]

Inserts an item into an array at the specified index by mutating the array.

Examples

insertMut([1, 3], 1, 2); // [1, 2, 3]

insertMut(['a', 'c'], 1, 'b'); // [a, b, c]

insertMut([{ id: 1 }], 1, { id: 2 }); // [{ id: 1 }, { id: 2 }]

intersection

intersection(source: T[], target: T[]): T[]

Create an array of unique values that are included in both given arrays.

Examples

intersection([1, 2], [2, 3]); // [2]

intersection(['a', 'b'], ['a', 'c']); // [a]

intersection([1, 2], [3, 4]); // []

isArray

isArray(value: unknown): boolean

Check if a value is an array.

Determines whether the provided value is an array using Array.isArray.

Examples

isArray([1, 2, 3]); // true

isArray('hello'); // false

isArray([]); // true

isEmpty

isEmpty(array: readonly T[]): boolean

Check if array is empty.

Examples

isEmpty([]); // true

isEmpty([1]); // false

isEmpty(['a', 'b']); // false

map

map(array: T[], iteratee: (element: T, index: number, array: T[]) => U): U[]

Creates a new array populated with the results of calling a provided function on every element in the input array.

Examples

map([1, 2, 3], (n) => n * 2); // [2, 4, 6]

map([1, 2, 3], String); // [1, 2, 3]

map(['a', 'b'], (char, index) => char + index); // [a0, b1]

reduce

reduce(array: T[], reducer: (accumulator: A, value: T, index: number, array: T[]) => A, initialValue: A): A

Executes a reducer function on each element of the array, resulting in a single output value.

Examples

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

reduce([['a', 1], ['b', 2]], (acc, [key, val]) => ({ ...acc, [key]: val }), {}); // { a: 1, b: 2 }

reduce([1, 2, 3], (acc, val) => { acc.push(val * 2); return acc; }, []); // [2, 4, 6]

removeAllMut

removeAllMut(): void

Examples

removeAtMut

removeAtMut(array: T[], index: number): T | undefined

Remove an element at a specific index from an array in place.

Examples

const items = ['a', 'b', 'c'];
removeAtMut(items, 1); // b

const numbers = [10, 20, 30];
removeAtMut(numbers, -1); // 30

const empty = [];
removeAtMut(empty, 0); // undefined

removeFirstMut

removeFirstMut(array: T[], value: T): void

Remove the first occurrence of a value from an array in place.

Mutates the given array by removing the first element that matches the provided value using strict equality. If the value is not found, the array remains unchanged.

Examples

const array = [1, 2, 3, 2];
removeFirstMut(array, 2);
array; // [1, 3, 2]

const array = ['a', 'b', 'c'];
removeFirstMut(array, 'a');
array; // [b, c]

const array = [1, 2, 3];
removeFirstMut(array, 99);
array; // [1, 2, 3]

removeLast

removeLast(arr: readonly T[], deltaIndex: number): T[]

Remove elements from the end of an array.

Returns a new array with the last element(s) removed. An optional deltaIndex adjusts how many elements are kept relative to removing just the last one.

Examples

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

removeLast([1, 2, 3], -1); // [1]

removeLast(['a', 'b', 'c', 'd'], 0); // [a, b, c]

reverse

reverse(array: T[]): T[]

Creates a new array with the elements in reverse order.

Examples

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

reverse(['y', 'z']); // [z, y]

reverse([]); // []

reverseMut

reverseMut(array: T[]): T[]

Reverses an array in place.

Examples

const array = [1, 2, 3];
reverseMut(array);
array; // [3, 2, 1]

const array = ['a', 'b'];
reverseMut(array);
array; // [b, a]

set

set(array: readonly T[], index: number, value: T): T[]

Creates a new array with the element at the specified index replaced with the given value.

Examples

set(['a', 'b', 'c'], 1, 'x'); // [a, x, c]

set([1, 2, 3], -1, 99); // [1, 2, 99]

set([0, 1, 0], 1, 0); // [0, 0, 0]

setLastMut

setLastMut(array: T[], value: T, offset: number): T[]

Sets the value of the last element of an array mutably, with an optional offset.

Examples

setLastMut([1, 2, 3], 4); // [1, 2, 4]

setLastMut(['a', 'b'], 'c'); // [a, c]

setLastMut([1, 2, 3], 5, -1); // [1, 5, 3]

some

some(array: T[], predicate: (item: T, index: number, array: T[]) => boolean): boolean

Checks if at least one element in the array satisfies the provided testing function.

Examples

some([1, 2, 3, 4], (n) => n % 2 === 0); // true

some([1, 3, 5, 7], (n) => n % 2 === 0); // false

some(['a', 'bc', 'd'], (s) => s.length > 1); // true

sortBy

sortBy(array: T[], iteratee: (item: T) => string | number): T[]

This function performs a stable sort and does not mutate the original array.

Creates a new array of elements sorted in ascending order by the results of running an iteratee on each element.

Examples

sortBy([3, 1, 2], (n) => n); // [1, 2, 3]

sortBy(['bb', 'ccc', 'a'], (s) => s.length); // [a, bb, ccc]

sortBy([{ user: 'fred', age: 40 }, { user: 'barney', age: 36 }], (u) => u.age); // [{ user: barney, age: 36 }, { user: fred, age: 40 }]

sortByArrayMut

sortByArrayMut(oldOrder: T[], newOrder: T[]): T[]

Sort an array in place based on the order defined by another array.

Mutably sorts oldOrder so that its elements appear in the same relative order as they do in newOrder. Elements not found in newOrder are pushed to the end in their original relative order (via Infinity fallback).

Examples

sortByArrayMut(['c', 'b', 'a'], ['a', 'b', 'c']); // [a, b, c]

sortByArrayMut(['x', 'y', 'z'], ['z', 'x', 'y']); // [z, x, y]

sortByArrayMut(['d', 'a', 'b'], ['b', 'a']); // [b, a, d]

sortByFrequencyAndUnique

sortByFrequencyAndUnique(array: T[]): T[]

Creates an array of unique values from the input array, sorted by their frequency of occurrence in descending order.

Examples

sortByFrequencyAndUnique([1, 2, 2, 2, 1]); // [2, 1]

sortByFrequencyAndUnique(['a', 'a', 'a', 'b', 'b', 'c']); // [a, b, c]

sortByFrequencyAndUnique([10, 20, 10, 10, 20]); // [10, 20]

take

take(array: T[], n: number): T[]

Creates a slice of array with n elements taken from the beginning.

Examples

take([1, 2, 3], 1); // [1]

take([1, 2, 3], 2); // [1, 2]

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

toggle

toggle(array: T[], item: T): T[]

Toggles the presence of an item in an array.

If the item exists, it is removed. Otherwise, it is appended.

Examples

toggle([1, 2], 3); // [1, 2, 3]

toggle(['a', 'b', 'c'], 'b'); // [a, c]

toggle([], true); // [true]

tryFirstEqual

tryFirstEqual(array1: T[], array2: T[]): T | null

Find the first element in array2 that also exists in array1.

Iterates through array2 and for each element checks if it exists in array1 using strict equality. Returns the first matching element, or null if no match is found.

Examples

tryFirstEqual([1, 2, 3], [4, 2, 3]); // 2

tryFirstEqual(['a', 'b'], ['c', 'd']); // null

tryFirstEqual([10, 20, 30], [30, 20, 10]); // 30

tryGetLast

tryGetLast(arr: T[], deltaIndex: number): T | null

Retrieves the last element of an array or an element relative to the end.

Returns null if the index is out of bounds.

Examples

tryGetLast(['a', 'b', 'c']); // c

tryGetLast(['a', 'b', 'c'], -1); // b

tryGetLast([]); // null

tryGetLastEqual

tryGetLastEqual(arrayA: T[], arrayB: U[], predicate: (itemA: T, itemB: U) => boolean): [T, U] | null

Returns the last pair of elements from two arrays that satisfy the provided predicate.

Iterates through both arrays in reverse order.

Examples

tryLastEqual([1, 2, 3], [3, 4, 5], (a, b) => a === b); // [3, 3]

tryLastEqual(['a', 'b'], ['A', 'B'], (a, b) => a.toUpperCase() === b); // [b, B]

tryLastEqual([1, 2], [3, 4], (a, b) => a === b); // null

union

union(arrays: T[][]): T[]

Create an array of unique values, in order, from all given arrays.

Examples

union([2], [1, 2]); // [2, 1]

union(['a'], ['b'], ['a']); // [a, b]

union([1, 2], [2, 3]); // [1, 2, 3]

uniq

uniq(array: readonly T[]): T[]

Creates a duplicate-free version of an array.

Examples

uniq([1, 2, 1]); // [1, 2]

uniq(['a', 'b', 'a']); // [a, b]

uniq([1, '1', 1]); // [1, 1]

zip

zip(arrays: T[][]): T[][]

Creates an array of grouped elements, the first of which contains the first elements of the given arrays, the second of which contains the second elements of the given arrays, and so on.

Examples

zip(['a', 'b'], [1, 2]); // [[a, 1], [b, 2]]

zip(['a', 'b'], [1]); // [[a, 1]]

zip([], [1, 2]); // []

🕊️ Vision

"Razomy" means Together—you and me.
We act as catalysts, turning natural chaos into clarity through open collaboration.
By building honest, reliable systems, we empower humanity and create a foundation for peace.
We foster a borderless environment driven by quality code and mutual support.
Join us to build this future—one commit at a time.

💖 Fuel Our Shared Future

We can't build this without you. If this library has saved you time or helped turn chaos into clarity in your own projects, please consider backing the developers behind it. Building reliable, open-source tools takes immense time and energy. Your sponsorship isn't just a donation; it’s the fuel that keeps this project actively maintained, bug-free, and thriving for everyone who relies on it.

Help us keep the momentum going. Choose how you want to light the way:

• ✨ Spark of Creativity
• 🌟 Flame of Innovation (Recommended)
• 🔥 Torch of Progress
• 🚀 Beacon of Excellence

🤝 Contributing

Contributions, issues and feature requests are welcome! Feel free to check issues page.

📝 License

Copyright © 2026 Razomy. This project is MIT licensed.

🐛 Reporting Issues

We use GitHub Issues as the official bug tracker for this project.

Before opening a new issue, please check if your problem has already been reported. If it hasn't, please open a new issue here: GitHub Issues: razomy/js

When reporting a bug, please include:

• A brief description of the issue.
• Steps to reproduce the bug.
• Your current environment (Node version, OS, etc.).