mathfuse 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to mathfuse will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-30
+
+### Added
+
+#### `mathfuse/stats`
+- `mean`, `geometricMean`, `harmonicMean`, `median`, `mode`, `weightedMean`
+- `variance`, `stdDev`, `range`, `iqr`, `mad`
+- `percentile`, `fiveNumberSummary`
+- `skewness`, `kurtosis`
+- `pearsonCorrelation`, `spearmanCorrelation`, `covariance`
+- `zScore`, `minMaxNormalize`
+- `linearRegression` with R², slope, intercept, and predict function
+
+#### `mathfuse/algebra`
+- Vector: `vadd`, `vsub`, `vscale`, `vdot`, `vnorm`, `vnormalize`, `vdistance`, `cosineSimilarity`, `cross3d`, `vhadamard`
+- Matrix: `mzeros`, `midentity`, `mtranspose`, `madd`, `mscale`, `mmul`, `mvmul`, `mdet`, `minverse`, `mtrace`, `mrank`, `msolve`
+
+#### `mathfuse/number-theory`
+- Primes: `isPrime` (Miller-Rabin), `primesUpTo` (sieve), `nextPrime`, `primeFactors`
+- GCD/LCM: `gcd`, `gcdMany`, `lcm`, `lcmMany`
+- Combinatorics: `factorial`, `binomial`, `permutations`
+- Modular: `modPow`, `eulerTotient`
+- Sequences: `fibonacci`, `nthFibonacci` (fast doubling), `collatz`, `digitalRoot`
+
+#### `mathfuse/numerical`
+- Root finding: `bisection`, `newtonRaphson`, `brent`
+- Differentiation: `derivative`, `secondDerivative`, `gradient`
+- Integration: `integrate` (adaptive Simpson), `gaussLegendre`
+- Interpolation: `lerp`, `inverseLerp`, `tableInterpolate`, `lagrange`
+- Utilities: `clamp`, `roundTo`, `approxEqual`, `remap`, `kahanSum`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scientist Maths
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# mathfuse
+
+[![CI](https://github.com/Avinashvelu03/mathfuse/actions/workflows/ci.yml/badge.svg)](https://github.com/Avinashvelu03/mathfuse/actions)
+[![npm version](https://img.shields.io/npm/v/mathfuse.svg)](https://www.npmjs.com/package/mathfuse)
+[![npm downloads](https://img.shields.io/npm/dm/mathfuse.svg)](https://www.npmjs.com/package/mathfuse)
+[![Coverage](https://codecov.io/gh/Avinashvelu03/mathfuse/branch/main/graph/badge.svg)](https://codecov.io/gh/Avinashvelu03/mathfuse)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/mathfuse)](https://bundlephobia.com/package/mathfuse)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+
+**A modern, zero-dependency TypeScript math utility library.**  
+Tree-shakeable · ESM + CJS · Browser & Node.js · Fully typed
+
+---
+
+## Features
+
+| Module | What's included |
+|--------|----------------|
+| **`stats`** | Mean, median, mode, std dev, variance, percentiles, IQR, MAD, skewness, kurtosis, Pearson/Spearman correlation, covariance, z-score, min-max normalization, linear regression |
+| **`algebra`** | Vector ops (add, dot, norm, normalize, cosine similarity, cross product), matrix ops (multiply, determinant, inverse, rank, transpose, solve) |
+| **`number-theory`** | Miller-Rabin primality, Sieve of Eratosthenes, GCD/LCM, factorial, binomial, permutations, modular exponentiation, Euler's totient, Fibonacci, Collatz |
+| **`numerical`** | Bisection, Newton-Raphson, Brent's method, numerical derivative/gradient, adaptive Simpson integration, Gauss-Legendre quadrature, Lagrange interpolation, Kahan summation |
+
+---
+
+## Install
+
+```bash
+npm install mathfuse
+# or
+yarn add mathfuse
+# or
+pnpm add mathfuse
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { mean, stdDev, linearRegression } from 'mathfuse';
+// or tree-shake specific modules:
+import { mean, stdDev } from 'mathfuse/stats';
+import { isPrime, fibonacci } from 'mathfuse/number-theory';
+import { newtonRaphson, integrate } from 'mathfuse/numerical';
+import { mmul, mdet, msolve } from 'mathfuse/algebra';
+```
+
+---
+
+## API Reference
+
+### 📊 Statistics (`mathfuse/stats`)
+
+#### Central Tendency
+
+```typescript
+import { mean, median, mode, geometricMean, harmonicMean, weightedMean } from 'mathfuse/stats';
+
+mean([1, 2, 3, 4, 5])              // 3
+median([3, 1, 4, 1, 5])            // 3
+mode([1, 2, 2, 3, 3])              // [2, 3]
+geometricMean([1, 2, 4, 8])        // 2.828...
+harmonicMean([1, 2, 4])            // 1.714...
+weightedMean([1, 2, 3], [1, 2, 3]) // 2.333...
+```
+
+#### Spread & Dispersion
+
+```typescript
+import { variance, stdDev, range, iqr, mad } from 'mathfuse/stats';
+
+variance([2, 4, 4, 4, 5, 5, 7, 9])           // 4.571 (sample)
+variance([2, 4, 4, 4, 5, 5, 7, 9], true)      // 4.0   (population)
+stdDev([2, 4, 4, 4, 5, 5, 7, 9], true)        // 2.0
+iqr([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])          // 4.5
+mad([1, 1, 2, 2, 4, 6, 9])                    // 1.0
+```
+
+#### Percentiles
+
+```typescript
+import { percentile, fiveNumberSummary } from 'mathfuse/stats';
+
+percentile([1,2,3,4,5,6,7,8,9,10], 90) // 9.1
+fiveNumberSummary([1,2,3,4,5])          // [1, 1.5, 3, 4.5, 5]
+```
+
+#### Correlation & Regression
+
+```typescript
+import { pearsonCorrelation, spearmanCorrelation, linearRegression } from 'mathfuse/stats';
+
+const x = [1, 2, 3, 4, 5];
+const y = [2, 4, 5, 4, 5];
+
+pearsonCorrelation(x, y)   // 0.8320...
+spearmanCorrelation(x, y)  // 0.8207...
+
+const reg = linearRegression(x, y);
+reg.slope      // 0.7
+reg.intercept  // 1.7
+reg.r2         // 0.6923
+reg.predict(6) // 5.9
+```
+
+#### Normalization
+
+```typescript
+import { zScore, minMaxNormalize } from 'mathfuse/stats';
+
+zScore([1, 2, 3, 4, 5])          // [-1.41, -0.71, 0, 0.71, 1.41]
+minMaxNormalize([1, 2, 3, 4, 5]) // [0, 0.25, 0.5, 0.75, 1]
+```
+
+---
+
+### 🔢 Number Theory (`mathfuse/number-theory`)
+
+```typescript
+import { isPrime, primesUpTo, nextPrime, primeFactors } from 'mathfuse/number-theory';
+
+isPrime(999_983)       // true  (Miller-Rabin)
+primesUpTo(20)         // [2, 3, 5, 7, 11, 13, 17, 19]
+nextPrime(100)         // 101
+primeFactors(360)      // [2, 2, 2, 3, 3, 5]
+```
+
+```typescript
+import { gcd, lcm, factorial, binomial, fibonacci } from 'mathfuse/number-theory';
+
+gcd(48, 18)            // 6
+lcm(4, 6)              // 12
+factorial(10)          // 3_628_800
+binomial(10, 3)        // 120
+fibonacci(8)           // [0, 1, 1, 2, 3, 5, 8, 13]
+nthFibonacci(50)       // 12586269025
+```
+
+---
+
+### 🧮 Linear Algebra (`mathfuse/algebra`)
+
+#### Vectors
+
+```typescript
+import { vadd, vdot, vnorm, cosineSimilarity, cross3d } from 'mathfuse/algebra';
+
+vadd([1,2,3], [4,5,6])              // [5, 7, 9]
+vdot([1,2,3], [4,5,6])              // 32
+vnorm([3, 4])                       // 5
+cosineSimilarity([1,0], [1,1])      // 0.7071...
+cross3d([1,0,0], [0,1,0])           // [0, 0, 1]
+```
+
+#### Matrices
+
+```typescript
+import { mmul, mdet, minverse, msolve } from 'mathfuse/algebra';
+
+const A = [[2,1], [-1,3]];
+mdet(A)           // 7
+minverse(A)       // [[0.428, -0.142], [0.142, 0.285]]
+msolve(A, [5,0])  // [3, 1]  (solves Ax = b)
+```
+
+---
+
+### 📐 Numerical Methods (`mathfuse/numerical`)
+
+#### Root Finding
+
+```typescript
+import { bisection, newtonRaphson, brent } from 'mathfuse/numerical';
+
+const f = (x: number) => x ** 2 - 2;  // root at √2
+
+bisection(f, 1, 2).root       // 1.4142135623...
+newtonRaphson(f, 1.5).root    // 1.4142135623...
+brent(f, 1, 2).root           // 1.4142135623...
+```
+
+#### Calculus
+
+```typescript
+import { derivative, integrate } from 'mathfuse/numerical';
+
+derivative(Math.sin, Math.PI / 4)   // ≈ cos(π/4) ≈ 0.7071
+integrate(Math.sin, 0, Math.PI)     // ≈ 2.0  (exact: 2)
+integrate(x => x ** 2, 0, 1)        // ≈ 0.333 (exact: 1/3)
+```
+
+#### Interpolation
+
+```typescript
+import { lerp, tableInterpolate, lagrange } from 'mathfuse/numerical';
+
+lerp(0, 100, 0.3)                         // 30
+tableInterpolate([0,1,2,3], [0,1,4,9], 1.5) // 2.5
+lagrange([0, 1, 2], [0, 1, 4], 1.5)       // 2.25
+```
+
+---
+
+## Tree Shaking
+
+mathfuse is fully tree-shakeable. Import only what you need:
+
+```typescript
+// ✅ Only the functions you import will be bundled
+import { mean, stdDev } from 'mathfuse/stats';
+import { isPrime } from 'mathfuse/number-theory';
+```
+
+---
+
+## Browser Support
+
+mathfuse targets ES2020 and works in all modern browsers and Node.js ≥ 16.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and open an issue before submitting a PR for large changes.
+
+```bash
+git clone https://github.com/Avinashvelu03/mathfuse.git
+cd mathfuse
+npm install
+npm test
+```
+
+---
+
+## License
+
+[MIT](LICENSE) © Scientist Maths

package/dist/cjs/algebra/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @module algebra
+ * Vector and matrix operations using plain JS arrays.
+ * All operations return new values — inputs are never mutated.
+ */
+export type Vector = number[];
+export type Matrix = number[][];
+/**
+ * Vector addition: a + b
+ */
+export declare function vadd(a: Vector, b: Vector): Vector;
+/**
+ * Vector subtraction: a − b
+ */
+export declare function vsub(a: Vector, b: Vector): Vector;
+/**
+ * Scalar multiplication: c * v
+ */
+export declare function vscale(v: Vector, c: number): Vector;
+/**
+ * Dot product: a · b
+ */
+export declare function vdot(a: Vector, b: Vector): number;
+/**
+ * L2 (Euclidean) norm of a vector.
+ */
+export declare function vnorm(v: Vector, p?: number): number;
+/**
+ * Normalized unit vector (direction only).
+ */
+export declare function vnormalize(v: Vector): Vector;
+/**
+ * Euclidean distance between two vectors.
+ */
+export declare function vdistance(a: Vector, b: Vector): number;
+/**
+ * Cosine similarity between two vectors: (a · b) / (|a| |b|)
+ */
+export declare function cosineSimilarity(a: Vector, b: Vector): number;
+/**
+ * Cross product of two 3D vectors.
+ */
+export declare function cross3d(a: Vector, b: Vector): Vector;
+/**
+ * Element-wise (Hadamard) product.
+ */
+export declare function vhadamard(a: Vector, b: Vector): Vector;
+/**
+ * Create an n×m matrix filled with a value (default 0).
+ */
+export declare function mzeros(n: number, m: number): Matrix;
+/**
+ * Create an n×n identity matrix.
+ */
+export declare function midentity(n: number): Matrix;
+/**
+ * Transpose a matrix.
+ */
+export declare function mtranspose(m: Matrix): Matrix;
+/**
+ * Matrix addition.
+ */
+export declare function madd(a: Matrix, b: Matrix): Matrix;
+/**
+ * Matrix scalar multiplication.
+ */
+export declare function mscale(m: Matrix, c: number): Matrix;
+/**
+ * Matrix multiplication (naive O(n³)).
+ */
+export declare function mmul(a: Matrix, b: Matrix): Matrix;
+/**
+ * Matrix-vector product: m · v
+ */
+export declare function mvmul(m: Matrix, v: Vector): Vector;
+/**
+ * Determinant via LU decomposition (in-place, returns sign + value).
+ * @example mdet([[1,2],[3,4]]) // -2
+ */
+export declare function mdet(m: Matrix): number;
+/**
+ * Matrix inverse via Gauss-Jordan elimination.
+ * Throws if the matrix is singular.
+ */
+export declare function minverse(m: Matrix): Matrix;
+/**
+ * Matrix trace — sum of diagonal elements.
+ */
+export declare function mtrace(m: Matrix): number;
+/**
+ * Matrix rank via Gaussian elimination.
+ */
+export declare function mrank(m: Matrix): number;
+/**
+ * Solve Ax = b using Gauss-Jordan elimination.
+ * @returns solution vector x
+ */
+export declare function msolve(A: Matrix, b: Vector): Vector;
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/algebra/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/algebra/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;AAC9B,MAAM,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;AAUhC;;GAEG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,SAAI,GAAG,MAAM,CAK9C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CASpD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtD;AAsBD;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK5C;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAajD;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAMlD;AAID;;;GAGG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CA6BtC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CA4B1C;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxC;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAsBvC;AAID;;;GAGG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAyBnD"}