gracio 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gglobensky
+
+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,130 @@
+# 📐 Gracio
+
+A high-performance, arbitrary-precision rational arithmetic library for TypeScript and JavaScript. Built for developers who need mathematical certainty without sacrificing execution speed.
+
+## 🚀 Why Gracio?
+
+Standard JavaScript numbers are 64-bit floats (IEEE 754). While fast, they suffer from **precision drift**. For example:
+`0.1 + 0.2 === 0.3` returns `false`.
+
+In critical applications—like financial systems, scientific simulations, or game physics—these tiny errors accumulate into "catastrophic cancellation," leading to bugs like characters clipping through walls or missing cents in a transaction.
+
+`Gracio` solves this by storing numbers as **Ratios (Fractions)** using native `BigInt`. Every operation is mathematically exact.
+
+## ✨ Key Features
+
+- **Absolute Precision**: No rounding errors, ever.
+- **Binary GCD Optimization**: Uses Stein's Algorithm for fast fraction reduction.
+- **Dynamic Simplification**: Only simplifies when numbers reach a critical size, maximizing CPU throughput.
+- **Mutable API**: Designed for high-performance loops to minimize Garbage Collection (GC) pressure.
+- **Zero Dependencies**: Lightweight and focused.
+
+## 🛡️ Managing Computational Overhead
+
+### The "Digit Explosion" Problem
+In pure rational arithmetic, multiplying fractions can cause the number of digits in the numerator and denominator to grow exponentially. In a tight loop, you might quickly end up with numbers that have tens of thousands of digits, leading to severe performance degradation (the "BigInt Tax").
+
+### The Precision Guard (`precisionLimit`)
+To prevent this, `Gracio` introduces an optional `precisionLimit`. When the denominator exceeds this limit, the library automatically triggers a **Rational Approximation** using Continued Fraction convergents. 
+
+This finds the mathematically "best" simpler fraction that maintains the requested precision, capping digit growth without ever falling back to the imprecise IEEE 754 float trap.
+
+## 📦 Installation
+
+```bash
+npm install gracio
+```
+
+## 🛠 Usage
+
+### Basic Setup
+```typescript
+import { Gracio } from 'gracio';
+
+// Create from integers
+const a = Gracio.fromInt(10); // 10/1
+const b = new Gracio(1n, 3n);  // 1/3
+```
+
+### Evaluating Equation Strings
+Gracio includes a built-in Lexer and Parser, making it trivial to build calculators or process equation strings (e.g., from Excel or user input).
+
+```typescript
+import { Lexer, Parser } from 'gracio';
+
+const expr = "1/3 + 1/6";
+const lexer = new Lexer();
+const tokens = lexer.tokenize(expr);
+const parser = new Parser(tokens);
+const result = parser.parse();
+
+console.log(result.toString()); // "1/2"
+```
+
+### Arithmetic (Mutable)
+Operations modify the object in place for maximum performance:
+```typescript
+const val = Gracio.fromInt(5);
+val.add(new Gracio(1n, 2n)); // val is now 11/2
+val.multiply(Gracio.fromInt(2)); // val is now 11/1
+console.log(val.toString()); // "11/1"
+```
+
+### Controlling Growth with precisionLimit
+Prevent digit explosion in chaotic or multiplicative systems:
+```typescript
+const p = Gracio.fromFloat(0.7);
+p.precisionLimit = 50; // Cap denominators at ~50 digits
+// Now, any operation that would cause the denominator to explode 
+// will be approximated to the best possible ratio within 50 digits.
+```
+
+### Advanced Operations
+`Gracio` supports powers and roots while maintaining symbolic precision:
+```typescript
+const base = new Gracio(2n, 1n);
+base.pow(3n); // 8/1
+
+// Calculate the n-th root of a value
+const squareRootOfTwo = Gracio.root(2n, new Gracio(2n, 1n));
+console.log(squareRootOfTwo.toString()); // High-precision rational approximation
+```
+
+### Conversion & Output
+Convert back to standard JavaScript numbers when needed for display or external APIs:
+```typescript
+const ratio = new Gracio(1n, 3n);
+console.log(ratio.toFloat());    // 0.3333333333333333
+console.log(ratio.toString());   // "1/3"
+```
+
+### Preserving Originals (Cloning)
+If you need to keep the original value, use `.clone()`:
+```typescript
+const start = Gracio.fromInt(10);
+const result = start.clone().add(new Gracio(1n, 2n));
+
+console.log(start.toString());    // "10/1" (Unchanged)
+console.log(result.toString());   // "21/2"
+```
+
+## 📈 Performance Comparison
+
+| Metric / Operation | Standard Float | Gracio (Mutable) | big.js / decimal.js | fraction.js |
+| :--- | :--- | :--- | :--- | :--- |
+| **Precision** | Drift $\approx 10^{-16}$ | **Absolute ($\infty$)** | Arbitrary Decimals | Absolute ($\infty$) |
+| **Memory** | Stack/Register | Heap Allocated | Heap Allocated | Heap Allocated |
+| **Additive Chain (1M)** | ~4ms | **~113ms** | 170ms - 430ms | ~256ms |
+| **Multiplicative (1K)** | ~0.2ms | **~5.6ms** (Limit 50) | 4ms - 18ms | $\infty$ (Explosion) |
+| **Chaotic Systems** | Fast / Imprecise | **Stable / Precise** | Variable | Crash/Hang |
+
+### Optimization Secret: Common Denominator Fast-Path
+`Gracio` detects when two ratios share the same denominator during addition or subtraction. In these cases, it skips expensive cross-multiplication entirely, making additive chains nearly as fast as floating-point arithmetic.
+
+## 🎮 Use Cases
+- **Game Physics**: Perfect coordinates for Euclidean spaces to prevent jittering and "ghost" collisions.
+- **FinTech**: Exact currency calculations without rounding errors or the need for arbitrary decimal libraries.
+- **Scientific Tools**: High-precision ratios for mathematical proofs and simulations.
+
+## License
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "gracio",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "A high-performance, arbitrary-precision rational arithmetic library for TypeScript and JavaScript.",
+  "author": "gglobensky",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gglobensky/Gracio.git"
+  },
+  "keywords": [
+    "math",
+    "precision",
+    "rational",
+    "fraction",
+    "bigint"
+  ],
+  "main": "dist/src/library-entry.js",
+  "module": "dist/src/library-entry.js",
+  "types": "dist/src/library-entry.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "bundle": "npx esbuild src/library-entry.ts --bundle --minify --outfile=dist/gracio.bundle.js --format=iife --global-name=GracioLib",
+    "start": "tsx src/demo.ts",
+    "test": "npm run build && mocha dist/**/*.test.js"
+  },
+  "devDependencies": {
+    "@types/chai": "^5.2.3",
+    "@types/mocha": "^10.0.0",
+    "chai": "^4.3.7",
+    "mocha": "^12.0.1",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.23.13",
+    "typescript": "^5.3.3",
+    "big.js": "^7.0.1",
+    "decimal.js": "^10.6.0",
+    "fraction.js": "^5.3.4"
+  },
+  "dependencies": {}
+}