@obinexusmk2/hypernum - Computing from the Heart

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

# 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:

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

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

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

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:

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

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

// 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

// 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:

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:

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:

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:

import { AckermannStructure } from '@obinexusmk2/hypernum';

const ackermann = new AckermannStructure();
const result = ackermann.computeAckermann(3, 2);

Special Functions

// 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

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:

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:

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.