@obinexusmk2/hypernum 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 obnexusmk2
-
-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.
+MIT License
+
+Copyright (c) 2026 obnexusmk2
+
+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

@@ -1,256 +1,355 @@
-# @obinexuscomputing/hypernum - Computing from the Heart
-
-![Logo ](./favicon.svg)
-
-A comprehensive TypeScript/JavaScript library for handling large number operations with BigInt support.
-
-## Features
-
-- High-precision arithmetic operations
-- Bitwise operations
-- Special mathematical functions (factorial, GCD, LCM, etc.)
-- Advanced data structures for large number manipulation
-- Configurable precision and overflow handling
-- Type-safe implementation in TypeScript
-
-## Installation
-
-```bash
-npm install @obinexuscomputing/hypernum
-```
-
-## Basic Usage
-
-```typescript
-import { createHypernum } from '@obinexuscomputing/hypernum';
-
-// Create a Hypernum instance with default configuration
-const hypernum = createHypernum();
-
-// Basic arithmetic operations
-const sum = hypernum.add("12345678901234567890", "98765432109876543210");
-const product = hypernum.multiply(2n, "1000000000000000000");
-```
-
-## Configuration
-
-You can configure Hypernum with various options:
-
-```typescript
-const customHypernum = createHypernum({
-  precision: 10,              // Decimal precision
-  roundingMode: 'HALF_EVEN',  // Rounding strategy
-  checkOverflow: true,        // Enable overflow checking
-  maxSteps: 1000             // Maximum computation steps
-});
-```
-
-## Core Operations
-
-### Arithmetic
-
-```typescript
-const hypernum = createHypernum();
-
-// Addition
-const sum = hypernum.add(a, b);
-
-// Subtraction
-const difference = hypernum.subtract(a, b);
-
-// Multiplication
-const product = hypernum.multiply(a, b);
-
-// Division
-const quotient = hypernum.divide(a, b);
-
-// Modulo
-const remainder = hypernum.mod(a, b);
-```
-
-### Bitwise Operations
-
-```typescript
-// Bitwise AND
-const andResult = hypernum.and(x, y);
-
-// Bitwise OR
-const orResult = hypernum.or(x, y);
-
-// Bitwise XOR
-const xorResult = hypernum.xor(x, y);
-
-// Bitwise NOT
-const notResult = hypernum.not(x);
-```
-
-### Power Operations
-
-```typescript
-// Power
-const powered = hypernum.power(base, exponent);
-
-// Square root
-const sqrt = hypernum.sqrt(value);
-
-// Nth root
-const root = hypernum.nthRoot(value, n);
-```
-
-## Advanced Features
-
-### Data Structures
-
-#### BigArray
-
-A specialized array implementation for handling large numbers efficiently:
-
-```typescript
-import { BigArray } from '@obinexuscomputing/hypernum';
-
-const array = new BigArray<bigint>();
-array.push(12345678901234567890n);
-array.push(98765432109876543210n);
-
-// Range queries
-const max = array.queryRange(0, 1);
-```
-
-#### NumberTree
-
-An AVL tree implementation optimized for large number operations:
-
-```typescript
-import { NumberTree } from '@obinexuscomputing/hypernum';
-
-const tree = new NumberTree();
-tree.insert(12345678901234567890n);
-tree.insert(98765432109876543210n);
-
-// Tree operations
-const found = tree.find(12345678901234567890n);
-const values = tree.traverse('inOrder');
-```
-
-#### PowerTower
-
-Handles power tower (tetration) computations:
-
-```typescript
-import { PowerTower } from '@obinexuscomputing/hypernum';
-
-const tower = new PowerTower();
-tower.build(2n, 4); // Computes 2↑↑4
-const result = tower.evaluate();
-```
-
-#### AckermannStructure
-
-Computes and manages Ackermann function values:
-
-```typescript
-import { AckermannStructure } from '@obinexuscomputing/hypernum';
-
-const ackermann = new AckermannStructure();
-const result = ackermann.computeAckermann(3, 2);
-```
-
-### Special Functions
-
-```typescript
-// Greatest Common Divisor
-const gcd = hypernum.gcd(48n, 18n);
-
-// Least Common Multiple
-const lcm = hypernum.lcm(48n, 18n);
-
-// Factorial
-import { factorial } from '@obinexuscomputing/hypernum';
-const fact = factorial(10n);
-
-// Binomial coefficient
-import { binomial } from '@obinexuscomputing/hypernum';
-const combination = binomial(10n, 5n);
-```
-
-### Number Format Conversions
-
-```typescript
-import { 
-  toBinary,
-  toHexadecimal,
-  toRoman,
-  fromRoman
-} from '@obinexuscomputing/hypernum';
-
-// Convert to different bases
-const binary = toBinary(123456789n);
-const hex = toHexadecimal(123456789n);
-
-// Roman numeral conversion
-const roman = toRoman(3549);
-const number = fromRoman("MMMDXLIX");
-```
-
-## Error Handling
-
-The library provides specific error types for different scenarios:
-
-```typescript
-import {
-  HypernumError,
-  OverflowError,
-  ValidationError
-} from '@obinexuscomputing/hypernum';
-
-try {
-  const result = hypernum.power(2n, 1000n);
-} catch (error) {
-  if (error instanceof OverflowError) {
-    console.error('Computation would overflow');
-  } else if (error instanceof ValidationError) {
-    console.error('Invalid input values');
-  }
-}
-```
-
-## Performance Considerations
-
-- Use BigInt literals (with 'n' suffix) for direct number input
-- Enable overflow checking only when necessary
-- Configure precision based on actual requirements
-- Use appropriate data structures for your use case
-- Consider using the built-in caching mechanisms for repeated computations
-
-## Type Safety
-
-The library is written in TypeScript and provides full type definitions:
-
-```typescript
-import type { 
-  HypernumConfig,
-  NumericInput,
-  OperationOptions
-} from '@obinexuscomputing/hypernum';
-
-// Type-safe configuration
-const config: HypernumConfig = {
-  precision: 10,
-  checkOverflow: true
-};
-
-// Type-safe numeric input
-const input: NumericInput = "12345678901234567890";
-```
-
-## Environment Support
-
-- Node.js ≥ 16.0.0
-- Modern browsers with BigInt support
-- TypeScript ≥ 4.5.0
-
-## License
-
-ISC License
-
-For more information, visit the [GitHub repository](https://github.com/obinexuscomputing/hypernum).
+# @obinexusmk2/hypernum - Computing from the Heart
+
+![Logo](./docs/favicon.png)
+
+A comprehensive TypeScript/JavaScript library for handling large number operations with BigInt support.
+
+## Features
+
+- High-precision arithmetic operations
+- Bitwise operations
+- Special mathematical functions (factorial, GCD, LCM, etc.)
+- Advanced data structures for large number manipulation
+- Configurable precision and overflow handling
+- Type-safe implementation in TypeScript
+
+## Installation
+
+```bash
+# Library dependency
+npm i @obinexusmk2/hypernum
+
+# CLI — run without installing
+npx @obinexusmk2/hypernum --help
+
+# CLI — install globally
+npm i -g @obinexusmk2/hypernum
+hypernum --help
+```
+
+## CLI Usage
+
+Run math operations directly from the terminal without writing code:
+
+```bash
+npx @obinexusmk2/hypernum <command> [args...] [options]
+```
+
+### Arithmetic
+
+| Command | Args | Description |
+|---------|------|-------------|
+| `add` | `<a> <b>` | Add two numbers |
+| `subtract` | `<a> <b>` | Subtract b from a |
+| `multiply` | `<a> <b>` | Multiply two numbers |
+| `divide` | `<a> <b>` | Divide a by b |
+| `mod` | `<a> <b>` | Remainder of a / b |
+| `gcd` | `<a> <b>` | Greatest common divisor |
+| `lcm` | `<a> <b>` | Least common multiple |
+| `abs` | `<n>` | Absolute value |
+| `sign` | `<n>` | Sign (-1, 0, or 1) |
+
+### Power
+
+| Command | Args | Description |
+|---------|------|-------------|
+| `power` | `<base> <exp>` | Exponentiation |
+| `sqrt` | `<n>` | Integer square root |
+| `nthRoot` | `<n> <k>` | k-th root of n |
+
+### Factorial
+
+| Command | Args | Description |
+|---------|------|-------------|
+| `factorial` | `<n>` | Factorial (n!) |
+| `binomial` | `<n> <k>` | Binomial coefficient C(n,k) |
+| `primorial` | `<n>` | Primorial (n#) |
+
+### Conversion
+
+| Command | Args | Description |
+|---------|------|-------------|
+| `toBinary` | `<n>` | Convert to binary |
+| `toOctal` | `<n>` | Convert to octal |
+| `toHex` | `<n>` | Convert to hexadecimal |
+| `toRoman` | `<n>` | Convert to Roman numeral |
+| `fromRoman` | `<str>` | Convert from Roman numeral |
+| `toScientific` | `<n>` | Convert to scientific notation |
+| `toBase` | `<n> <base>` | Convert to arbitrary base |
+
+### Comparison
+
+| Command | Args | Description |
+|---------|------|-------------|
+| `compare` | `<a> <b>` | Compare (-1, 0, 1) |
+| `equals` | `<a> <b>` | Test equality (true/false) |
+| `lessThan` | `<a> <b>` | Test a < b (true/false) |
+| `greaterThan` | `<a> <b>` | Test a > b (true/false) |
+
+### Config
+
+```bash
+npx @obinexusmk2/hypernum --init          # Create hypernum.config.json
+npx @obinexusmk2/hypernum --config        # Show resolved config
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--precision <n>` | Set decimal precision |
+| `--no-overflow` | Disable overflow checking |
+| `--version`, `-v` | Show version |
+| `--help`, `-h` | Show help |
+
+### Examples
+
+```bash
+npx @obinexusmk2/hypernum add 123456789012345678901234567890 987654321098765432109876543210
+npx @obinexusmk2/hypernum factorial 100
+npx @obinexusmk2/hypernum toRoman 2024
+npx @obinexusmk2/hypernum toBase 255 16
+npx @obinexusmk2/hypernum sqrt 144
+```
+
+### Windows Note
+
+`npm link` requires **Developer Mode** on Windows (Settings → Privacy & Security → For Developers → Developer Mode: On).
+
+Without Developer Mode, use `npm install -g @obinexusmk2/hypernum` instead.
+
+## Basic Usage
+
+```typescript
+import { createHypernum } from '@obinexusmk2/hypernum';
+
+// Create a Hypernum instance with default configuration
+const hypernum = createHypernum();
+
+// Basic arithmetic operations
+const sum = hypernum.add("12345678901234567890", "98765432109876543210");
+const product = hypernum.multiply(2n, "1000000000000000000");
+```
+
+## Configuration
+
+You can configure Hypernum with various options:
+
+```typescript
+const customHypernum = createHypernum({
+  precision: 10,              // Decimal precision
+  roundingMode: 'HALF_EVEN',  // Rounding strategy
+  checkOverflow: true,        // Enable overflow checking
+  maxSteps: 1000             // Maximum computation steps
+});
+```
+
+## Core Operations
+
+### Arithmetic
+
+```typescript
+const hypernum = createHypernum();
+
+// Addition
+const sum = hypernum.add(a, b);
+
+// Subtraction
+const difference = hypernum.subtract(a, b);
+
+// Multiplication
+const product = hypernum.multiply(a, b);
+
+// Division
+const quotient = hypernum.divide(a, b);
+
+// Modulo
+const remainder = hypernum.mod(a, b);
+```
+
+### Bitwise Operations
+
+```typescript
+// Bitwise AND
+const andResult = hypernum.and(x, y);
+
+// Bitwise OR
+const orResult = hypernum.or(x, y);
+
+// Bitwise XOR
+const xorResult = hypernum.xor(x, y);
+
+// Bitwise NOT
+const notResult = hypernum.not(x);
+```
+
+### Power Operations
+
+```typescript
+// Power
+const powered = hypernum.power(base, exponent);
+
+// Square root
+const sqrt = hypernum.sqrt(value);
+
+// Nth root
+const root = hypernum.nthRoot(value, n);
+```
+
+## Advanced Features
+
+### Data Structures
+
+#### BigArray
+
+A specialized array implementation for handling large numbers efficiently:
+
+```typescript
+import { BigArray } from '@obinexusmk2/hypernum';
+
+const array = new BigArray<bigint>();
+array.push(12345678901234567890n);
+array.push(98765432109876543210n);
+
+// Range queries
+const max = array.queryRange(0, 1);
+```
+
+#### NumberTree
+
+An AVL tree implementation optimized for large number operations:
+
+```typescript
+import { NumberTree } from '@obinexusmk2/hypernum';
+
+const tree = new NumberTree();
+tree.insert(12345678901234567890n);
+tree.insert(98765432109876543210n);
+
+// Tree operations
+const found = tree.find(12345678901234567890n);
+const values = tree.traverse('inOrder');
+```
+
+#### PowerTower
+
+Handles power tower (tetration) computations:
+
+```typescript
+import { PowerTower } from '@obinexusmk2/hypernum';
+
+const tower = new PowerTower();
+tower.build(2n, 4); // Computes 2↑↑4
+const result = tower.evaluate();
+```
+
+#### AckermannStructure
+
+Computes and manages Ackermann function values:
+
+```typescript
+import { AckermannStructure } from '@obinexusmk2/hypernum';
+
+const ackermann = new AckermannStructure();
+const result = ackermann.computeAckermann(3, 2);
+```
+
+### Special Functions
+
+```typescript
+// Greatest Common Divisor
+const gcd = hypernum.gcd(48n, 18n);
+
+// Least Common Multiple
+const lcm = hypernum.lcm(48n, 18n);
+
+// Factorial
+import { factorial } from '@obinexusmk2/hypernum';
+const fact = factorial(10n);
+
+// Binomial coefficient
+import { binomial } from '@obinexusmk2/hypernum';
+const combination = binomial(10n, 5n);
+```
+
+### Number Format Conversions
+
+```typescript
+import { 
+  toBinary,
+  toHexadecimal,
+  toRoman,
+  fromRoman
+} from '@obinexusmk2/hypernum';
+
+// Convert to different bases
+const binary = toBinary(123456789n);
+const hex = toHexadecimal(123456789n);
+
+// Roman numeral conversion
+const roman = toRoman(3549);
+const number = fromRoman("MMMDXLIX");
+```
+
+## Error Handling
+
+The library provides specific error types for different scenarios:
+
+```typescript
+import {
+  HypernumError,
+  OverflowError,
+  ValidationError
+} from '@obinexusmk2/hypernum';
+
+try {
+  const result = hypernum.power(2n, 1000n);
+} catch (error) {
+  if (error instanceof OverflowError) {
+    console.error('Computation would overflow');
+  } else if (error instanceof ValidationError) {
+    console.error('Invalid input values');
+  }
+}
+```
+
+## Performance Considerations
+
+- Use BigInt literals (with 'n' suffix) for direct number input
+- Enable overflow checking only when necessary
+- Configure precision based on actual requirements
+- Use appropriate data structures for your use case
+- Consider using the built-in caching mechanisms for repeated computations
+
+## Type Safety
+
+The library is written in TypeScript and provides full type definitions:
+
+```typescript
+import type { 
+  HypernumConfig,
+  NumericInput,
+  OperationOptions
+} from '@obinexusmk2/hypernum';
+
+// Type-safe configuration
+const config: HypernumConfig = {
+  precision: 10,
+  checkOverflow: true
+};
+
+// Type-safe numeric input
+const input: NumericInput = "12345678901234567890";
+```
+
+## Environment Support
+
+- Node.js ≥ 16.0.0
+- Modern browsers with BigInt support
+- TypeScript ≥ 4.5.0
+
+## License
+
+ISC License
+
+For more information, visit the [GitHub repository](https://github.com/obinexusmk2/hypernum).