@md-mh/easy-calculator

A small npm package providing a comprehensive suite of mathematical utilities organised as separate, focused modules — arithmetic, algebra, geometry, trigonometry, statistics, calculus, matrices, number theory, combinatorics, complex numbers, and vectors.

Installation

npm install @md-mh/easy-calculator

Quick start

// Named imports (recommended)
import {
  arithmetic,
  algebra,
  geometry,
  statistics,
  matrix,
} from '@md-mh/easy-calculator';

arithmetic.divide(10, 2); // 5
algebra.solveQuadratic(1, -3, 2); // [2, 1]
geometry.triangleArea(3, 4, 5); // 6
statistics.standardDeviation([1, 2, 3, 4]); // ~1.29
matrix.determinant([
  [1, 2],
  [3, 4],
]); // -2

Or grab everything as a namespace:

import * as calc from '@md-mh/easy-calculator';

calc.trigonometry.sinDeg(90); // 1
calc.numberTheory.factorial(5); // 120

You can also import a single module directly:

import * as stats from '@md-mh/easy-calculator/src/statistics';
stats.mean([1, 2, 3, 4, 5]); // 3

Using CommonJS? const { arithmetic } = require('@md-mh/easy-calculator'); works too.

arithmetic

Basic operations with safer error semantics than raw JavaScript operators.

| Function | Description | | ------------------ | --------------------------------------------- | | add(a, b) | Returns a + b. | | subtract(a, b) | Returns a - b. | | multiply(a, b) | Returns a * b. | | divide(a, b) | Returns a / b. Throws if b === 0. | | modulo(a, b) | Non-negative remainder (mathematical modulo). | | power(base, exp) | Returns base ** exp. | | sqrt(n) | Square root. Throws for negative input. | | abs(n) | Absolute value. |

import { arithmetic } from '@md-mh/easy-calculator';

arithmetic.add(2, 3); // 5
arithmetic.subtract(10, 4); // 6
arithmetic.multiply(4, 5); // 20
arithmetic.divide(10, 2); // 5
arithmetic.divide(1, 0); // throws: "Division by zero"
arithmetic.modulo(-7, 3); // 2  (JS would return -1)
arithmetic.power(2, 10); // 1024
arithmetic.sqrt(16); // 4
arithmetic.abs(-7); // 7

algebra

Equation solvers and polynomial evaluation.

| Function | Description | | ------------------------------- | ------------------------------------------------------------------------- | | solveLinear(a, b) | Solves ax + b = 0. Returns the root. | | solveQuadratic(a, b, c) | Solves ax² + bx + c = 0. Returns real roots, or {re, im} for complex. | | solveCubic(a, b, c, d) | Solves ax³ + bx² + cx + d = 0 via Cardano. Returns real roots. | | evaluatePolynomial(coeffs, x) | Evaluates a polynomial at x using Horner's method. |

import { algebra } from '@md-mh/easy-calculator';

// 2x - 4 = 0  ->  x = 2
algebra.solveLinear(2, -4); // 2

// x² - 3x + 2 = 0  ->  x = 1, 2
algebra.solveQuadratic(1, -3, 2); // [2, 1]

// x² + 1 = 0  ->  complex roots
algebra.solveQuadratic(1, 0, 1);
// [{ re: 0, im: 1 }, { re: 0, im: -1 }]

// x³ - 6x² + 11x - 6 = 0  ->  x = 1, 2, 3
algebra.solveCubic(1, -6, 11, -6); // [1, 2, 3] (order may vary)

// Coefficients highest-degree-first: 2x² + 3x + 1 at x = 2
algebra.evaluatePolynomial([2, 3, 1], 2); // 15

geometry

Area, perimeter, volume, and distance for common 2D and 3D shapes.

| Function | Description | | ----------------------------------- | --------------------------------------------------- | | circleArea(radius) | π·r² | | circleCircumference(radius) | 2·π·r | | rectangleArea(width, height) | width × height | | rectanglePerimeter(width, height) | 2·(width + height) | | triangleArea(a, b, c) | Heron's formula. Validates the triangle inequality. | | trapezoidArea(a, b, h) | ((a + b) / 2) · h | | sphereVolume(radius) | (4/3)·π·r³ | | sphereSurfaceArea(radius) | 4·π·r² | | cylinderVolume(radius, height) | π·r²·h | | coneVolume(radius, height) | (1/3)·π·r²·h | | boxVolume(length, width, height) | l × w × h | | distance(point1, point2) | Euclidean distance, any number of dimensions. |

import { geometry } from '@md-mh/easy-calculator';

geometry.circleArea(5); // 78.539...
geometry.circleCircumference(5); // 31.415...
geometry.rectangleArea(4, 6); // 24
geometry.triangleArea(3, 4, 5); // 6
geometry.trapezoidArea(3, 5, 4); // 16
geometry.sphereVolume(3); // 113.097...
geometry.sphereSurfaceArea(3); // 113.097...
geometry.cylinderVolume(2, 5); // 62.831...
geometry.coneVolume(2, 6); // 25.132...
geometry.boxVolume(2, 3, 4); // 24
geometry.distance([0, 0, 0], [1, 2, 2]); // 3

trigonometry

Degree-aware trig and triangle-solving helpers.

| Function | Description | | ------------------------------- | ----------------------------------------------------------- | | degreesToRadians(degrees) | Convert degrees → radians. | | radiansToDegrees(radians) | Convert radians → degrees. | | sinDeg(degrees) | Sine of an angle expressed in degrees. | | cosDeg(degrees) | Cosine of an angle expressed in degrees. | | tanDeg(degrees) | Tangent of an angle expressed in degrees. | | hypotenuse(a, b) | √(a² + b²) using overflow-safe Math.hypot. | | lawOfCosines(a, b, angleC) | Side opposite angleC (radians) given the other two sides. | | lawOfSines(a, angleA, angleB) | Side b from a / sin(A) = b / sin(B) (radians). |

import { trigonometry } from '@md-mh/easy-calculator';

trigonometry.degreesToRadians(180); // 3.14159...
trigonometry.radiansToDegrees(Math.PI); // 180
trigonometry.sinDeg(90); // 1
trigonometry.cosDeg(0); // 1
trigonometry.tanDeg(45); // ~1
trigonometry.hypotenuse(3, 4); // 5
trigonometry.lawOfCosines(5, 7, Math.PI / 3); // ~6.24
trigonometry.lawOfSines(5, Math.PI / 6, Math.PI / 3); // ~8.66

statistics

Descriptive statistics over numeric arrays.

| Function | Description | | ---------------------------------------- | ----------------------------------------------------------------------- | | mean(values) | Arithmetic mean. | | median(values) | Median (averages the two middle values for even-length input). | | mode(values) | Array of most-frequent values (handles multimodal data). | | variance(values, sample=true) | Sample variance (n-1) by default; pass false for population variance. | | standardDeviation(values, sample=true) | √variance, same sample flag. | | min(values) / max(values) | Smallest / largest value. | | range(values) | max - min. | | percentile(values, p) | Linearly-interpolated percentile (NumPy "type 7"). p in [0, 100]. | | correlation(x, y) | Pearson correlation in [-1, 1]. |

import { statistics } from '@md-mh/easy-calculator';
const data = [1, 2, 3, 4, 5];

statistics.mean(data); // 3
statistics.median(data); // 3
statistics.median([1, 2, 3, 4]); // 2.5
statistics.mode([1, 2, 2, 3, 3]); // [2, 3]
statistics.variance(data); // 2.5 (sample)
statistics.variance(data, false); // 2   (population)
statistics.standardDeviation(data); // 1.581...
statistics.min(data); // 1
statistics.max(data); // 5
statistics.range(data); // 4
statistics.percentile([1, 2, 3, 4], 50); // 2.5
statistics.correlation([1, 2, 3], [2, 4, 6]); // 1

calculus

Numerical differentiation, integration, and root-finding.

| Function | Description | | ----------------------------------------------- | ---------------------------------------------------------------------- | | derivative(fn, x, h=1e-6) | f'(x) via centred difference, O(h²) error. | | secondDerivative(fn, x, h=1e-4) | f''(x) via 3-point stencil. | | integrateTrapezoid(fn, a, b, n=1000) | ∫ₐᵇ fn dx via composite trapezoid rule. | | integrateSimpson(fn, a, b, n=1000) | ∫ₐᵇ fn dx via Simpson's rule (O(1/n⁴)). n must be even. | | newtonRaphson(fn, x0, tol=1e-10, maxIter=100) | Root near x0 via Newton-Raphson. Throws if it fails to converge. | | bisection(fn, a, b, tol=1e-10, maxIter=1000) | Root in [a, b]. Requires fn(a) and fn(b) to have opposite signs. |

import { calculus } from '@md-mh/easy-calculator';

// d/dx (x²) at x = 3  ->  6
calculus.derivative((x) => x * x, 3); // ~6

// d²/dx² (x³) at x = 2  ->  12
calculus.secondDerivative((x) => x ** 3, 2); // ~12

// ∫₀¹ x² dx  =  1/3
calculus.integrateTrapezoid((x) => x * x, 0, 1, 100); // ~0.3333
calculus.integrateSimpson((x) => x * x, 0, 1, 100); // ~0.3333

// Root of x² - 2  =  √2
calculus.newtonRaphson((x) => x * x - 2, 1); // ~1.41421
calculus.bisection((x) => x * x - 2, 0, 2); // ~1.41421

matrix

Matrix operations on number[][] (row-major).

| Function | Description | | -------------------------------- | ------------------------------------------------------------------- | | add(a, b) | Element-wise sum. Requires matching shapes. | | subtract(a, b) | Element-wise difference. | | scalarMultiply(matrix, scalar) | Multiply every entry by a number. | | multiply(a, b) | Standard matrix product. Inner dimensions must agree. | | transpose(matrix) | Swap rows and columns. | | identity(n) | n × n identity matrix. | | determinant(matrix) | Determinant via cofactor expansion (small matrices). | | inverse(matrix) | Inverse via Gauss-Jordan with partial pivoting. Throws if singular. | | trace(matrix) | Sum of the diagonal entries. |

import { matrix } from '@md-mh/easy-calculator';

const A = [
  [1, 2],
  [3, 4],
];
const B = [
  [5, 6],
  [7, 8],
];

matrix.add(A, B); // [[6, 8], [10, 12]]
matrix.subtract(B, A); // [[4, 4], [4, 4]]
matrix.scalarMultiply(A, 2); // [[2, 4], [6, 8]]
matrix.multiply(A, B); // [[19, 22], [43, 50]]
matrix.transpose(A); // [[1, 3], [2, 4]]
matrix.identity(3); // [[1,0,0],[0,1,0],[0,0,1]]
matrix.determinant(A); // -2
matrix.inverse(A); // [[-2, 1], [1.5, -0.5]]
matrix.trace(A); // 5

numberTheory

Integer-only utilities.

| Function | Description | | -------------------- | -------------------------------------------------- | | factorial(n) | n! — iterative; throws for negative n. | | gcd(a, b) | Greatest common divisor (Euclidean algorithm). | | lcm(a, b) | Least common multiple. | | isPrime(n) | Primality test up to √n. | | primeFactors(n) | Sorted array of prime factors (with multiplicity). | | primesUpTo(n) | Every prime ≤ n via the Sieve of Eratosthenes. | | fibonacci(n) | Nth Fibonacci number, iterative. | | isPerfectSquare(n) | true if n is a perfect square. |

import { numberTheory } from '@md-mh/easy-calculator';

numberTheory.factorial(5); // 120
numberTheory.gcd(12, 18); // 6
numberTheory.lcm(4, 6); // 12
numberTheory.isPrime(97); // true
numberTheory.isPrime(15); // false
numberTheory.primeFactors(60); // [2, 2, 3, 5]
numberTheory.primesUpTo(20); // [2, 3, 5, 7, 11, 13, 17, 19]
numberTheory.fibonacci(10); // 55
numberTheory.isPerfectSquare(49); // true

combinatorics

Counting and enumeration.

| Function | Description | | -------------------------------- | ----------------------------------------------------- | | permutations(n, r) | P(n, r) — number of ordered selections. | | combinations(n, r) | C(n, r) — number of unordered selections. | | binomial(n, r) | Alias for combinations(n, r). | | generatePermutations(items) | Every ordering of items. Output size n!. | | generateCombinations(items, r) | Every r-sized subset of items. Output size C(n, r). |

import { combinatorics } from '@md-mh/easy-calculator';

combinatorics.permutations(5, 2); // 20
combinatorics.combinations(5, 2); // 10
combinatorics.binomial(6, 3); // 20

combinatorics.generatePermutations([1, 2, 3]);
// [[1,2,3], [1,3,2], [2,1,3], [2,3,1], [3,1,2], [3,2,1]]

combinatorics.generateCombinations(['a', 'b', 'c', 'd'], 2);
// [['a','b'], ['a','c'], ['a','d'], ['b','c'], ['b','d'], ['c','d']]

complex

Complex number arithmetic. Numbers are plain { re, im } objects so they're JSON-serialisable.

| Function | Description | | --------------------- | ------------------------------------------------------ | | complex(re, im=0) | Construct a complex number. | | add(a, b) | (a.re + b.re) + (a.im + b.im)i | | subtract(a, b) | (a.re − b.re) + (a.im − b.im)i | | multiply(a, b) | (ac − bd) + (ad + bc)i | | divide(a, b) | Multiply by conjugate of b. Throws on division by 0. | | conjugate(c) | Flip the sign of the imaginary part. | | magnitude(c) | √(re² + im²) | | argument(c) | Angle in radians, range (-π, π]. | | fromPolar(r, theta) | Build a complex number from polar form. | | toString(c) | Human-readable string, e.g. "3 - 2i". |

import { complex } from '@md-mh/easy-calculator';

const a = complex.complex(3, 2); // 3 + 2i
const b = complex.complex(1, 4); // 1 + 4i

complex.add(a, b); // { re: 4, im: 6 }
complex.subtract(a, b); // { re: 2, im: -2 }
complex.multiply(a, b); // { re: -5, im: 14 }
complex.divide(a, b); // { re: 0.647..., im: -0.588... }
complex.conjugate(a); // { re: 3, im: -2 }
complex.magnitude(complex.complex(3, 4)); // 5
complex.argument(complex.complex(0, 1)); // 1.5707... (π/2)
complex.fromPolar(2, Math.PI / 4); // { re: 1.414..., im: 1.414... }
complex.toString(a); // "3 + 2i"

vector

Operations on arrays of numbers (any dimension; cross product is 3D only).

| Function | Description | | ----------------------- | ------------------------------------------------------------------------ | | add(a, b) | Element-wise sum. | | subtract(a, b) | Element-wise difference. | | scale(vector, scalar) | Multiply every component by a scalar. | | dot(a, b) | Dot product Σ aᵢbᵢ. | | cross(a, b) | 3D cross product. Throws if either input is not length 3. | | magnitude(vector) | √(Σ vᵢ²). | | normalize(vector) | Unit vector in the same direction. Throws on the zero vector. | | angleBetween(a, b) | Angle in radians via acos((a·b) / (‖a‖·‖b‖)). | | project(a, b) | Vector projection of a onto b. |

import { vector } from '@md-mh/easy-calculator';

vector.add([1, 2, 3], [4, 5, 6]); // [5, 7, 9]
vector.subtract([4, 5, 6], [1, 2, 3]); // [3, 3, 3]
vector.scale([1, 2, 3], 2); // [2, 4, 6]
vector.dot([1, 2, 3], [4, 5, 6]); // 32
vector.cross([1, 0, 0], [0, 1, 0]); // [0, 0, 1]
vector.magnitude([3, 4]); // 5
vector.normalize([3, 4]); // [0.6, 0.8]
vector.angleBetween([1, 0], [0, 1]); // 1.5707... (π/2)
vector.project([3, 4], [1, 0]); // [3, 0]

License

MIT