A lightweight JavaScript utility library for array operations, statistics, number theory, and common mathematical calculations.

ArrayMath provides a simple, consistent API for working with arrays and numbers without needing to repeatedly write common mathematical logic yourself.

Features

• 📦 Flatten deeply nested arrays
• 📊 Analyze arrays with one method
• ➕ Calculate sums and averages
• 📈 Find minimum, maximum, and range
• ✖️ Multiply numbers and calculate array products
• 🔢 Find factors and divisors
• 🧮 Calculate factorials
• 🔍 Check whether a number is prime
• 📐 Calculate GCD and LCM
• 📊 Calculate median and mode
• 🔄 Reduce arrays
• ⚡ Calculate powers and absolute values
• 🛡️ Built-in input validation

Installation

Install ArrayMath using npm:

npm install arraymath

Or with other package managers:

yarn add arraymath

pnpm add arraymath

Importing ArrayMath

ArrayMath uses ES Modules.

import ArrayMath from "arraymath";

You can then call its methods directly:

const numbers = [10, 20, 30, 40, 50];

console.log(ArrayMath.sum(numbers));
console.log(ArrayMath.average(numbers));

Quick Start

import ArrayMath from "arraymath";

const numbers = [10, 20, 30, 40, 50];

console.log(ArrayMath.sum(numbers));
// 150

console.log(ArrayMath.average(numbers));
// 30

console.log(ArrayMath.min(numbers));
// 10

console.log(ArrayMath.max(numbers));
// 50

console.log(ArrayMath.range(numbers));
// 40

API Reference

"flatten(array)"

Flattens a nested array into a one-dimensional array.

Syntax

ArrayMath.flatten(array);

Example

const numbers = [
    1,
    [2, 3],
    [4, [5, 6]],
    [[7, 8], [9, [10]]]
];

const result = ArrayMath.flatten(numbers);

console.log(result);

Output:

[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

ArrayMath can handle arrays nested to multiple levels.

Array Analysis

"analyze(array, options)"

Analyzes an array and returns several statistics at once.

Syntax

ArrayMath.analyze(array, options);

Example:

const numbers = [10, 5, 20, 15, 8];

const result = ArrayMath.analyze(numbers);

console.log(result);

Output:

{
    min: 5,
    max: 20,
    minIndex: 1,
    maxIndex: 2,
    range: 15,
    sum: 58,
    average: 11.6,
    count: 5
}

%Options**

The second argument is optional.

{
    flatten: true,
    ignoreNaN: true,
    ignoreNonNumbers: true
}

For example:

const data = [
    10,
    20,
    "hello",
    NaN,
    30
];

const result = ArrayMath.analyze(data);

console.log(result);

Non-numbers and "NaN" are ignored by default.

"min(array)"

Returns the smallest numeric value in an array.

ArrayMath.min([10, 5, 20, 3]);

Output:

3

"max(array)"

Returns the largest numeric value in an array.

ArrayMath.max([10, 5, 20, 3]);

Output:

20

"sum(array)"

Returns the sum of all numeric values.

ArrayMath.sum([10, 20, 30]);

Output:

60

Nested arrays are supported:

ArrayMath.sum([10, [20, 30], [40]]);

Output:

100

"average(array)"

Returns the arithmetic mean of the values.

ArrayMath.average([10, 20, 30]);

Output:

20

The formula is:

average = sum of values / number of values

"range(array)"

Returns the difference between the largest and smallest values.

ArrayMath.range([10, 5, 20, 15]);

Output:

15

Because:

20 - 5 = 15

"sizeOfArray(array)"

Returns the number of valid numeric values.

ArrayMath.sizeOfArray([10, 20, 30]);

Output:

3

Nested arrays are flattened automatically.

ArrayMath.sizeOfArray([ 1, [2, 3], [4, [5]] ]);

Output:

5

Mathematical Operations

"multiply(a, b)"

Multiplies two numbers.

ArrayMath.multiply(12, 5);

Output:

60

"product(array)"

Multiplies every numeric value in an array.

ArrayMath.product([2, 3, 4]);

Output:

24

This is equivalent to:

2 × 3 × 4 = 24

Nested arrays are supported:

ArrayMath.product([2, [3, 4]]);

Output:

24

"power(base, exponent)"

Raises a number to a power.

ArrayMath.power(2, 8);

Output:

256

Equivalent to:

2⁸ = 256

"absolute(number)"

Returns the absolute value of a number.

ArrayMath.absolute(-25);

Output:

25

Factorials

"factorial(number)"

Calculates the factorial of a non-negative integer.

ArrayMath.factorial(5);

Output:

120

Because:

5! = 5 × 4 × 3 × 2 × 1 = 120

Special case:

ArrayMath.factorial(0);

Output:

1

Important

The current implementation limits factorial calculations to "18!" because JavaScript's "Number" type cannot safely represent larger integer results.

ArrayMath.factorial(18);

is supported.

For larger factorials, consider using "BigInt" or a dedicated arbitrary-precision mathematics library.

Prime Numbers

"isPrime(number)"

Determines whether an integer is a prime number.

ArrayMath.isPrime(17);

Output:

true

ArrayMath.isPrime(20);

Output:

false

What is a prime number?

A prime number is an integer greater than "1" that has exactly two positive divisors:

1 and itself

Examples:

2, 3, 5, 7, 11, 13, 17, 19...

ArrayMath uses an efficient square-root-based approach rather than checking every integer below the number.

Factors and Divisors

"factors(number)"

Returns all positive factors of a number.

ArrayMath.factors(12);

Output:

[1, 2, 3, 4, 6, 12]

Because:

1 × 12 = 12 2 × 6 = 12 3 × 4 = 12

The returned factors are sorted in ascending order.

"divisors(number)"

Returns the positive divisors of a number.

ArrayMath.divisors(24);

Output:

[1, 2, 3, 4, 6, 8, 12, 24]

Factors vs divisors

In this package, factors and positive divisors refer to the same set of numbers, so:

ArrayMath.factors(12);

and:

ArrayMath.divisors(12);

return the same result.

GCD and LCM

"gcd(a, b)"

Calculates the Greatest Common Divisor of two integers.

ArrayMath.gcd(48, 18);

Output:

6

Because "6" is the largest integer that divides both "48" and "18".

"lcm(a, b)"

Calculates the Least Common Multiple of two integers.

ArrayMath.lcm(12, 18);

Output:

36

Because:

Multiples of 12: 12, 24, 36, 48...

Multiples of 18: 18, 36, 54...

LCM = 36

Median

"median(array)"

Calculates the median of an array.

The values are sorted before calculating the median.

Odd number of values

ArrayMath.median([10, 2, 8, 4, 6]);

Sorted:

2, 4, 6, 8, 10

Output:

6

Even number of values

ArrayMath.median([10, 20, 30, 40]);

The two middle values are "20" and "30".

(20 + 30) / 2 = 25

Output:

25

Mode

"mode(array)"

Returns the most frequently occurring value or values.

ArrayMath.mode([1, 2, 2, 3, 3, 3, 4]);

Output:

[3]

Multiple modes

A dataset can have more than one mode.

ArrayMath.mode([1, 1, 2, 2, 3]);

Output:

[1, 2]

No mode

If every value appears exactly once:

ArrayMath.mode([1, 2, 3, 4]);

Output:

[]

Reduce

"reduce(array, callback, initialValue)"

ArrayMath includes its own implementation of the standard JavaScript "reduce()" behavior.

Sum

const result = ArrayMath.reduce( [1, 2, 3, 4], (total, value) => total + value, 0 );

console.log(result);

Output:

10

Multiplication

const result = ArrayMath.reduce( [2, 3, 4], (total, value) => total * value, 1 );

console.log(result);

Output:

24

Callback parameters

The callback receives:

(accumulator, currentValue, index, array)

For example:

ArrayMath.reduce( [10, 20, 30], (total, value, index, array) => { console.log(index); return total + value; }, 0 );

Working With Nested Arrays

Most ArrayMath array methods support nested arrays.

For example:

const data = [ 10, [20, 30], [40, [50, 60]] ];

console.log(ArrayMath.sum(data)); console.log(ArrayMath.average(data)); console.log(ArrayMath.min(data)); console.log(ArrayMath.max(data));

The data is effectively treated as:

[10, 20, 30, 40, 50, 60]

Error Handling

ArrayMath performs input validation and throws errors when invalid values are provided.

For example:

ArrayMath.isPrime(2.5);

throws a "TypeError" because prime numbers are defined for integers.

Similarly:

ArrayMath.factorial(-5);

throws a "RangeError".

And:

ArrayMath.sum([]);

throws an error because there are no valid numeric values to analyze.

You can handle errors with "try...catch":

try { const result = ArrayMath.factorial(-5);

console.log(result);

} catch (error) { console.error(error.message); }

Complete API

Method| Description "flatten(array)"| Flatten nested arrays "analyze(array, options)"| Analyze an array "min(array)"| Find minimum value "max(array)"| Find maximum value "sum(array)"| Calculate sum "average(array)"| Calculate average "range(array)"| Calculate range "sizeOfArray(array)"| Count numeric values "multiply(a, b)"| Multiply two numbers "product(array)"| Multiply all values "reduce(array, callback, initialValue)"| Reduce an array "isPrime(number)"| Check if a number is prime "factors(number)"| Find factors "divisors(number)"| Find divisors "gcd(a, b)"| Calculate GCD "lcm(a, b)"| Calculate LCM "factorial(number)"| Calculate factorial "power(base, exponent)"| Calculate a power "absolute(number)"| Calculate absolute value "median(array)"| Calculate median "mode(array)"| Find mode(s)

Example Project

import ArrayMath from "arraymath";

const numbers = [ 10, 20, [30, 40], [50, [60]] ];

console.log("Flattened:", ArrayMath.flatten(numbers));

console.log("Minimum:", ArrayMath.min(numbers));

console.log("Maximum:", ArrayMath.max(numbers));

console.log("Sum:", ArrayMath.sum(numbers));

console.log("Average:", ArrayMath.average(numbers));

console.log("Range:", ArrayMath.range(numbers));

console.log("Count:", ArrayMath.sizeOfArray(numbers));

console.log("Product:", ArrayMath.product([2, 3, 4]));

console.log("Median:", ArrayMath.median(numbers));

console.log("Mode:", ArrayMath.mode([1, 2, 2, 3]));

console.log("Prime:", ArrayMath.isPrime(97));

console.log("Factors:", ArrayMath.factors(24));

console.log("GCD:", ArrayMath.gcd(48, 18));

console.log("LCM:", ArrayMath.lcm(12, 18));

console.log("Factorial:", ArrayMath.factorial(5));

Browser / Node.js / React

ArrayMath is designed to work with modern JavaScript environments that support ES Modules.

You can use it in:

• Node.js
• React
• React Native
• Vite
• Modern browsers with module support
• Other JavaScript applications that support ES Modules

Example:

import ArrayMath from "arraymath";

Why ArrayMath?

JavaScript already provides many built-in mathematical and array utilities. ArrayMath is intended to provide a single, consistent API for common array and mathematical operations.

Instead of repeatedly implementing:

Math.min(...numbers);

numbers.reduce((a, b) => a + b, 0);

or custom factor/prime/factorial logic, you can use:

ArrayMath.min(numbers); ArrayMath.sum(numbers); ArrayMath.isPrime(number); ArrayMath.factorial(number);

This makes common operations easier to discover and reuse.

Contributing

Contributions, suggestions, bug reports, and improvements are welcome.

If you find a bug or have an idea for a new mathematical utility, feel free to open an issue or submit a pull request.

Before submitting a pull request, make sure your changes:

• Are readable and maintainable
• Include appropriate validation
• Do not unnecessarily break the existing API
• Include tests where appropriate
• Are documented in this README when introducing new public functionality

License

MIT License

Copyright © 2026

Author

Created by BeastDev ❤️

If you find ArrayMath useful, consider giving the project a ⭐ on GitHub.