matrix-lite 0.1.0

package/README.md

@@ -0,0 +1,272 @@
+# matrix-lite
+
+**matrixlite** is a tiny, dependency-free JavaScript library for basic matrix operations.
+It is designed to be simple, explicit, and predictable, without TypeScript, classes, or hidden magic.
+
+Matrices are represented as plain 2D arrays (`number[][]`).
+
+## Features
+
+* Works in Node.js (CommonJS & ESM compatible)
+* Simple and explicit API
+* Predictable data structures (plain arrays)
+* Safe shape validation with clear errors
+* Floating-point comparison with epsilon support
+
+### Supported operations:
+
+* Matrix creation (zeros, identity)
+* Shape inspection (shape)
+* Matrix arithmetic (add, sub, scale, mul)
+* Transformations (transpose)
+* Vector math (dot, row, col)
+* Utilities (clone, map, eq)
+
+## Installation
+
+```bash
+npm install matrixlite
+```
+
+## Importing
+
+### CommonJS (Node.js)
+
+```js
+const M = require('matrixlite');
+```
+
+### ES Modules
+
+```js
+import * as M from 'matrixlite';
+```
+
+## Matrix Representation
+
+A matrix is a rectangular 2D array of numbers:
+
+```js
+const A = [
+  [1, 2, 3],
+  [4, 5, 6]
+];
+```
+
+### Rules
+
+* All rows must have the same length
+* Matrices must be non-empty
+* All values should be numbers
+
+## API Reference
+
+`shape(matrix)`
+
+Returns matrix dimensions as `[rows, cols]`.
+
+```js
+M.shape([[1, 2], [3, 4]]);
+// → [2, 2]
+```
+
+Throws if the matrix is invalid or ragged.
+
+`zeros(rows, cols)`
+
+Creates a matrix filled with zeros.
+
+```js
+M.zeros(2, 3);
+// [
+//   [0, 0, 0],
+//   [0, 0, 0]
+// ]
+```
+
+`identity(n)`
+
+Creates an `n × n` identity matrix.
+
+```js
+M.identity(3);
+// [
+//   [1, 0, 0],
+//   [0, 1, 0],
+//   [0, 0, 1]
+// ]
+```
+
+`clone(matrix)`
+
+Returns a deep copy of a matrix.
+
+```js
+const B = M.clone(A);
+```
+
+`map(matrix, fn)`
+
+Applies a function to each element.
+
+```js
+M.map(A, v => v * 2);
+```
+
+Callback signature:
+
+```js
+(value, rowIndex, colIndex) => number
+```
+
+`add(A, B)`
+
+Element-wise matrix addition.
+
+```js
+M.add([[1, 2]], [[3, 4]]);
+// [[4, 6]]
+```
+
+Matrices must have the same shape.
+
+`sub(A, B)`
+
+Element-wise subtraction.
+
+```js
+M.sub([[5, 5]], [[2, 3]]);
+// [[3, 2]]
+```
+
+`scale(matrix, k)`
+
+Multiplies every element by a scalar.
+
+```js
+M.scale([[1, 2]], 10);
+// [[10, 20]]
+```
+
+`transpose(matrix)`
+
+Transposes a matrix.
+
+```js
+M.transpose([
+  [1, 2, 3],
+  [4, 5, 6]
+]);
+// [
+//   [1, 4],
+//   [2, 5],
+//   [3, 6]
+// ]
+```
+
+`mul(A, B)`
+
+Matrix multiplication (`A × B`).
+
+```js
+const A = [
+  [1, 2, 3],
+  [4, 5, 6]
+];
+
+const B = [
+  [7, 8],
+  [9, 10],
+  [11, 12]
+];
+
+M.mul(A, B);
+// [
+//   [58, 64],
+//   [139, 154]
+// ]
+```
+
+### Rules:
+
+* `A.cols === B.rows`
+* Uses classic O(n³) multiplication
+* Optimized loop order for cache friendliness
+
+`dot(a, b)`
+
+Dot product of two vectors.
+
+```js
+M.dot([1, 2, 3], [4, 5, 6]);
+// 32
+```
+
+Vectors must have equal length.
+
+`row(matrix, index)`
+
+Returns a copy of a matrix row.
+
+```js
+M.row(A, 0);
+// [1, 2, 3]
+```
+
+`col(matrix, index)`
+
+Returns a column as a vector.
+
+```js
+M.col(A, 1);
+// [2, 5]
+```
+
+`eq(A, B, eps = 0)`
+
+Checks matrix equality with optional tolerance.
+
+```js
+M.eq([[1, 1.001]], [[1, 1.002]], 0.01);
+// true
+```
+
+Useful for floating-point comparisons.
+
+## Error Handling
+
+All functions:
+
+* Validate matrix shape
+* Throw meaningful TypeError or RangeError
+* Never silently fix invalid input
+
+Example:
+```js
+M.add([[1, 2]], [[1]]);
+// RangeError: shape mismatch
+```
+
+## Performance Notes
+
+* Intended for small to medium matrices
+* Not optimized for large-scale numerical computing
+* No SIMD, WASM, or GPU acceleration
+* Perfect for:
+  * Education 
+  * Prototyping 
+  * Small math utilities 
+  * Backend logic
+
+What This Library Is NOT
+
+* ❌ A NumPy replacement 
+* ❌ A linear algebra research toolkit 
+* ❌ A GPU-accelerated math engine 
+* ❌ A TypeScript-heavy framework
+
+This is a minimalist utility library.
+
+
+## License
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "matrix-lite",
+  "version": "0.1.0",
+  "description": "Simple matrix utilities (JS only)",
+  "keywords": [
+    "matrix",
+    "math",
+    "linear-algebra"
+  ],
+  "license": "MIT",
+  "author": "",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "import": "./src/index.js"
+    }
+  },
+  "type": "commonjs",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/basic.test.js"
+  },
+  "dependencies": {
+    "bignumber.js": "^9.3.1",
+    "fast-math": "^1.0.2",
+    "fraction.js": "^5.3.4",
+    "gl-matrix": "^3.4.4",
+    "micro-math": "^0.10.0",
+    "ml-matrix": "^6.12.1",
+    "numeric": "^1.2.6",
+    "simple-statistics": "^7.8.8",
+    "tinyparrot": "^0.0.18"
+  }
+}

package/src/index.js

@@ -0,0 +1,178 @@
+'use strict';
+
+/**
+ * Matrix is represented as Array<Array<number>> (rows).
+ */
+
+function isMatrix(A) {
+  return Array.isArray(A) && A.length > 0 && A.every(r => Array.isArray(r) && r.length > 0);
+}
+
+function shape(A) {
+  if (!isMatrix(A)) throw new TypeError('Expected a non-empty 2D array');
+  const rows = A.length;
+  const cols = A[0].length;
+  for (let i = 1; i < rows; i++) {
+    if (A[i].length !== cols) throw new TypeError('Ragged matrix (rows have different lengths)');
+  }
+  return [rows, cols];
+}
+
+function clone(A) {
+  shape(A);
+  return A.map(r => r.slice());
+}
+
+function zeros(rows, cols) {
+  if (!Number.isInteger(rows) || !Number.isInteger(cols) || rows <= 0 || cols <= 0) {
+    throw new TypeError('rows/cols must be positive integers');
+  }
+  const out = new Array(rows);
+  for (let i = 0; i < rows; i++) {
+    const row = new Array(cols);
+    for (let j = 0; j < cols; j++) row[j] = 0;
+    out[i] = row;
+  }
+  return out;
+}
+
+function identity(n) {
+  if (!Number.isInteger(n) || n <= 0) throw new TypeError('n must be a positive integer');
+  const I = zeros(n, n);
+  for (let i = 0; i < n; i++) I[i][i] = 1;
+  return I;
+}
+
+function map(A, fn) {
+  const [r, c] = shape(A);
+  const out = new Array(r);
+  for (let i = 0; i < r; i++) {
+    const row = new Array(c);
+    for (let j = 0; j < c; j++) row[j] = fn(A[i][j], i, j);
+    out[i] = row;
+  }
+  return out;
+}
+
+function add(A, B) {
+  const [ar, ac] = shape(A);
+  const [br, bc] = shape(B);
+  if (ar !== br || ac !== bc) throw new RangeError('add: shape mismatch');
+  const out = new Array(ar);
+  for (let i = 0; i < ar; i++) {
+    const row = new Array(ac);
+    for (let j = 0; j < ac; j++) row[j] = A[i][j] + B[i][j];
+    out[i] = row;
+  }
+  return out;
+}
+
+function sub(A, B) {
+  const [ar, ac] = shape(A);
+  const [br, bc] = shape(B);
+  if (ar !== br || ac !== bc) throw new RangeError('sub: shape mismatch');
+  const out = new Array(ar);
+  for (let i = 0; i < ar; i++) {
+    const row = new Array(ac);
+    for (let j = 0; j < ac; j++) row[j] = A[i][j] - B[i][j];
+    out[i] = row;
+  }
+  return out;
+}
+
+function scale(A, k) {
+  if (typeof k !== 'number' || !Number.isFinite(k)) throw new TypeError('k must be a finite number');
+  return map(A, v => v * k);
+}
+
+function transpose(A) {
+  const [r, c] = shape(A);
+  const out = new Array(c);
+  for (let j = 0; j < c; j++) {
+    const row = new Array(r);
+    for (let i = 0; i < r; i++) row[i] = A[i][j];
+    out[j] = row;
+  }
+  return out;
+}
+
+function mul(A, B) {
+  const [ar, ac] = shape(A);
+  const [br, bc] = shape(B);
+  if (ac !== br) throw new RangeError('mul: shape mismatch (A cols must equal B rows)');
+  const out = zeros(ar, bc);
+
+  // classic O(n^3) with a cache-friendly loop order
+  for (let i = 0; i < ar; i++) {
+    const Ai = A[i];
+    const outi = out[i];
+    for (let k = 0; k < ac; k++) {
+      const aik = Ai[k];
+      const Bk = B[k];
+      for (let j = 0; j < bc; j++) {
+        outi[j] += aik * Bk[j];
+      }
+    }
+  }
+  return out;
+}
+
+function dot(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length === 0 || b.length === 0) {
+    throw new TypeError('dot: expected non-empty arrays');
+  }
+  if (a.length !== b.length) throw new RangeError('dot: length mismatch');
+  let s = 0;
+  for (let i = 0; i < a.length; i++) s += a[i] * b[i];
+  return s;
+}
+
+function row(A, i) {
+  const [r] = shape(A);
+  if (!Number.isInteger(i) || i < 0 || i >= r) throw new RangeError('row: index out of range');
+  return A[i].slice();
+}
+
+function col(A, j) {
+  const [r, c] = shape(A);
+  if (!Number.isInteger(j) || j < 0 || j >= c) throw new RangeError('col: index out of range');
+  const out = new Array(r);
+  for (let i = 0; i < r; i++) out[i] = A[i][j];
+  return out;
+}
+
+function eq(A, B, eps = 0) {
+  const [ar, ac] = shape(A);
+  const [br, bc] = shape(B);
+  if (ar !== br || ac !== bc) return false;
+  if (typeof eps !== 'number' || eps < 0) throw new TypeError('eps must be a non-negative number');
+  for (let i = 0; i < ar; i++) {
+    for (let j = 0; j < ac; j++) {
+      const d = Math.abs(A[i][j] - B[i][j]);
+      if (d > eps) return false;
+    }
+  }
+  return true;
+}
+
+module.exports = {
+  // constructors
+  zeros,
+  identity,
+
+  // validators / helpers
+  shape,
+  clone,
+  map,
+  row,
+  col,
+  eq,
+
+  // ops
+  add,
+  sub,
+  scale,
+  transpose,
+  mul,
+  dot
+};