tiny-exact-math 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brent Buffham
+
+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,81 @@
+# tiny-exact-math
+
+Minimal rational arithmetic library for exact geometric predicates in pure JavaScript. Zero dependencies — uses native `BigInt`.
+
+## Install
+
+```bash
+npm install tiny-exact-math
+```
+
+## Usage
+
+```js
+import { Rational, fromNumber, determinant, determinant3 } from 'tiny-exact-math';
+
+// Create rationals
+const a = new Rational(1n, 3n);       // 1/3
+const b = fromNumber(0.1);            // exact representation of 0.1
+
+// Arithmetic
+a.add(b);        // returns new Rational
+a.subtract(b);
+a.multiply(b);
+a.divide(b);
+
+// 2D orientation test (sign of 2×2 determinant)
+// Returns +1 (counter-clockwise), -1 (clockwise), or 0 (collinear)
+determinant(
+  { x: 0, y: 0 },
+  { x: 1, y: 0 },
+  { x: 0, y: 1 }
+); // +1
+
+// 3D plane-side test (sign of 3×3 determinant)
+// Returns +1 (above plane), -1 (below), or 0 (coplanar)
+determinant3(
+  { x: 0, y: 0, z: 0 },
+  { x: 1, y: 0, z: 0 },
+  { x: 0, y: 1, z: 0 },
+  { x: 0, y: 0, z: 1 }
+); // +1
+```
+
+## API
+
+### `new Rational(numerator, denominator?)`
+
+Create a rational number from BigInt or number values. Automatically normalised to lowest terms with a positive denominator.
+
+### `fromNumber(n)`
+
+Convert a JavaScript `number` (integer or float) to an exact `Rational`. Uses the shortest decimal round-trip representation to avoid precision loss.
+
+### `gcd(a, b)`
+
+Greatest common divisor of two `BigInt` values.
+
+### Rational instance methods
+
+| Method | Description |
+|--------|-------------|
+| `add(other)` | Addition |
+| `subtract(other)` | Subtraction |
+| `multiply(other)` | Multiplication |
+| `divide(other)` | Division |
+| `sign()` | Returns `-1`, `0`, or `1` |
+| `isZero()` | Returns `true` if zero |
+| `toNumber()` | Convert to JS `number` (may lose precision) |
+| `toString()` | Human-readable string (`"1/3"`) |
+
+### `determinant(p1, p2, p3)`
+
+Exact 2D orientation test. Returns the sign of the 2×2 determinant formed by three `{x, y}` points.
+
+### `determinant3(p1, p2, p3, p4)`
+
+Exact 3D plane-side test. Returns the sign of the 3×3 determinant formed by four `{x, y, z}` points.
+
+## License
+
+MIT

package/Rational.js

@@ -0,0 +1,296 @@
+/**
+ * tiny-exact-math
+ * Minimal rational arithmetic library for exact geometric predicates.
+ */
+
+/**
+ * Compute the greatest common divisor of two BigInts using the Euclidean
+ * algorithm. The result is always non-negative.
+ *
+ * @param {bigint} a
+ * @param {bigint} b
+ * @returns {bigint}
+ */
+export function gcd(a, b) {
+  a = a < 0n ? -a : a;
+  b = b < 0n ? -b : b;
+  while (b !== 0n) {
+    const t = b;
+    b = a % b;
+    a = t;
+  }
+  return a;
+}
+
+/**
+ * Convert a JavaScript number (integer or floating-point) to a Rational.
+ *
+ * Strategy: use `String(n)`, which produces the *shortest* decimal
+ * representation that round-trips back to the same IEEE 754 double (Grisu /
+ * Ryu algorithm in V8).  Parse the resulting decimal string into a
+ * numerator/denominator pair, handling the sign, fractional part, and
+ * optional scientific-notation exponent separately to avoid BigInt parsing
+ * errors (e.g. BigInt("-05") would throw).
+ *
+ * @param {number} n
+ * @returns {Rational}
+ */
+export function fromNumber(n) {
+  if (!isFinite(n)) {
+    throw new RangeError("Cannot convert non-finite number to Rational");
+  }
+  if (n === 0) return new Rational(0n, 1n);
+
+  const str = String(n);
+  const negative = str.charCodeAt(0) === 45; // '-'
+  const abs = negative ? str.slice(1) : str;
+
+  // Handle scientific notation produced for very large / very small values
+  // e.g. "1.5e-7" or "1e+21"
+  const eIdx = abs.indexOf("e");
+  if (eIdx !== -1) {
+    const base = abs.slice(0, eIdx);
+    const exp = parseInt(abs.slice(eIdx + 1), 10);
+    const r = _parseDecimalString(base, negative);
+    const pow = 10n ** BigInt(Math.abs(exp));
+    return exp >= 0
+      ? new Rational(r.numerator * pow, r.denominator)
+      : new Rational(r.numerator, r.denominator * pow);
+  }
+
+  return _parseDecimalString(abs, negative);
+}
+
+/**
+ * Parse a plain decimal string (no sign, no exponent) into a Rational.
+ * @param {string} abs  – digits with optional "."
+ * @param {boolean} negative
+ * @returns {Rational}
+ */
+function _parseDecimalString(abs, negative) {
+  const dotIndex = abs.indexOf(".");
+  if (dotIndex === -1) {
+    const num = negative ? -BigInt(abs) : BigInt(abs);
+    return new Rational(num, 1n);
+  }
+
+  const intDigits = abs.slice(0, dotIndex) || "0";
+  const fracDigits = abs.slice(dotIndex + 1);
+  const combined = intDigits + fracDigits; // sign removed, safe for BigInt
+  const num = negative ? -BigInt(combined) : BigInt(combined);
+  const den = 10n ** BigInt(fracDigits.length);
+  return new Rational(num, den);
+}
+
+/**
+ * A rational number stored as two BigInts (numerator and denominator).
+ * The value is always kept in lowest terms with a non-negative denominator.
+ */
+export class Rational {
+  /**
+   * @param {bigint|number} numerator
+   * @param {bigint|number} denominator
+   */
+  constructor(numerator, denominator = 1n) {
+    let num = BigInt(numerator);
+    let den = BigInt(denominator);
+
+    if (den === 0n) {
+      throw new RangeError("Denominator must not be zero");
+    }
+
+    // Normalise: keep denominator positive
+    if (den < 0n) {
+      num = -num;
+      den = -den;
+    }
+
+    const g = gcd(num < 0n ? -num : num, den);
+    this.numerator = num / g;
+    this.denominator = den / g;
+  }
+
+  // ── Arithmetic ────────────────────────────────────────────────────────────
+
+  /**
+   * Return a new Rational equal to this + other.
+   * @param {Rational} other
+   * @returns {Rational}
+   */
+  add(other) {
+    return new Rational(
+      this.numerator * other.denominator + other.numerator * this.denominator,
+      this.denominator * other.denominator
+    );
+  }
+
+  /**
+   * Return a new Rational equal to this - other.
+   * @param {Rational} other
+   * @returns {Rational}
+   */
+  subtract(other) {
+    return new Rational(
+      this.numerator * other.denominator - other.numerator * this.denominator,
+      this.denominator * other.denominator
+    );
+  }
+
+  /**
+   * Return a new Rational equal to this * other.
+   * @param {Rational} other
+   * @returns {Rational}
+   */
+  multiply(other) {
+    return new Rational(
+      this.numerator * other.numerator,
+      this.denominator * other.denominator
+    );
+  }
+
+  /**
+   * Return a new Rational equal to this / other.
+   * @param {Rational} other
+   * @returns {Rational}
+   */
+  divide(other) {
+    if (other.numerator === 0n) {
+      throw new RangeError("Division by zero");
+    }
+    return new Rational(
+      this.numerator * other.denominator,
+      this.denominator * other.numerator
+    );
+  }
+
+  // ── Comparison ────────────────────────────────────────────────────────────
+
+  /**
+   * Return the sign of this rational: -1, 0, or 1.
+   * @returns {number}
+   */
+  sign() {
+    if (this.numerator === 0n) return 0;
+    return this.numerator > 0n ? 1 : -1;
+  }
+
+  /**
+   * Return true if this rational equals zero.
+   * @returns {boolean}
+   */
+  isZero() {
+    return this.numerator === 0n;
+  }
+
+  /**
+   * Convert to a JavaScript number (may lose precision).
+   * @returns {number}
+   */
+  toNumber() {
+    return Number(this.numerator) / Number(this.denominator);
+  }
+
+  /**
+   * Human-readable string representation.
+   * @returns {string}
+   */
+  toString() {
+    if (this.denominator === 1n) return String(this.numerator);
+    return `${this.numerator}/${this.denominator}`;
+  }
+}
+
+// ── Geometric predicate ──────────────────────────────────────────────────────
+
+/**
+ * Compute the orientation (sign of the 2×2 determinant) of three 2-D points.
+ *
+ * Given points p1, p2, p3 each with numeric `x` and `y` properties, the
+ * determinant is:
+ *
+ *   | p2.x - p1.x   p3.x - p1.x |
+ *   | p2.y - p1.y   p3.y - p1.y |
+ *
+ * = (p2.x - p1.x)(p3.y - p1.y) - (p3.x - p1.x)(p2.y - p1.y)
+ *
+ * All coordinates are converted to exact Rationals before the computation so
+ * the result is free of floating-point rounding error.
+ *
+ * @param {{ x: number, y: number }} p1
+ * @param {{ x: number, y: number }} p2
+ * @param {{ x: number, y: number }} p3
+ * @returns {-1 | 0 | 1}  sign of the determinant
+ */
+export function determinant(p1, p2, p3) {
+  const x1 = fromNumber(p1.x);
+  const y1 = fromNumber(p1.y);
+  const x2 = fromNumber(p2.x);
+  const y2 = fromNumber(p2.y);
+  const x3 = fromNumber(p3.x);
+  const y3 = fromNumber(p3.y);
+
+  const dx2 = x2.subtract(x1);
+  const dy2 = y2.subtract(y1);
+  const dx3 = x3.subtract(x1);
+  const dy3 = y3.subtract(y1);
+
+  // det = dx2*dy3 - dx3*dy2
+  const det = dx2.multiply(dy3).subtract(dx3.multiply(dy2));
+
+  return det.sign();
+}
+
+/**
+ * Compute the orientation (sign of the 3×3 determinant) of four 3-D points.
+ *
+ * Given points p1, p2, p3, p4 each with numeric `x`, `y`, and `z`
+ * properties, the determinant is:
+ *
+ *   | p2.x-p1.x  p3.x-p1.x  p4.x-p1.x |
+ *   | p2.y-p1.y  p3.y-p1.y  p4.y-p1.y |
+ *   | p2.z-p1.z  p3.z-p1.z  p4.z-p1.z |
+ *
+ * Returns +1 if p4 is above the plane defined by p1→p2→p3 (right-hand rule),
+ * -1 if below, and 0 if coplanar.
+ *
+ * All coordinates are converted to exact Rationals before the computation so
+ * the result is free of floating-point rounding error.
+ *
+ * @param {{ x: number, y: number, z: number }} p1
+ * @param {{ x: number, y: number, z: number }} p2
+ * @param {{ x: number, y: number, z: number }} p3
+ * @param {{ x: number, y: number, z: number }} p4
+ * @returns {-1 | 0 | 1}  sign of the determinant
+ */
+export function determinant3(p1, p2, p3, p4) {
+  const x1 = fromNumber(p1.x);
+  const y1 = fromNumber(p1.y);
+  const z1 = fromNumber(p1.z);
+  const x2 = fromNumber(p2.x);
+  const y2 = fromNumber(p2.y);
+  const z2 = fromNumber(p2.z);
+  const x3 = fromNumber(p3.x);
+  const y3 = fromNumber(p3.y);
+  const z3 = fromNumber(p3.z);
+  const x4 = fromNumber(p4.x);
+  const y4 = fromNumber(p4.y);
+  const z4 = fromNumber(p4.z);
+
+  // Column vectors relative to p1
+  const a = x2.subtract(x1);
+  const b = x3.subtract(x1);
+  const c = x4.subtract(x1);
+  const d = y2.subtract(y1);
+  const e = y3.subtract(y1);
+  const f = y4.subtract(y1);
+  const g = z2.subtract(z1);
+  const h = z3.subtract(z1);
+  const i = z4.subtract(z1);
+
+  // det = a(ei - fh) - b(di - fg) + c(dh - eg)
+  const det = a.multiply(e.multiply(i).subtract(f.multiply(h)))
+    .subtract(b.multiply(d.multiply(i).subtract(f.multiply(g))))
+    .add(c.multiply(d.multiply(h).subtract(e.multiply(g))));
+
+  return det.sign();
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "tiny-exact-math",
+  "version": "0.0.1",
+  "description": "Minimal rational arithmetic library for exact geometric predicates in pure JavaScript",
+  "type": "module",
+  "main": "Rational.js",
+  "exports": {
+    ".": "./Rational.js"
+  },
+  "files": [
+    "Rational.js"
+  ],
+  "keywords": [
+    "rational",
+    "exact-arithmetic",
+    "bigint",
+    "determinant",
+    "geometric-predicates",
+    "orientation",
+    "mesh",
+    "boolean",
+    "trimesh"
+  ],
+  "author": "Brent Buffham",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brentbuffham/tiny-exact-math.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brentbuffham/tiny-exact-math/issues"
+  },
+  "homepage": "https://github.com/brentbuffham/tiny-exact-math#readme"
+}