@obinexusmk2/hypernum 0.1.0

package/src/core/errors.ts

@@ -0,0 +1,203 @@
+/**
+ * Custom error types for Hypernum library
+ * Provides specific error classes for different types of errors that can occur
+ * during mathematical operations and data structure manipulations
+ */
+
+import { ERROR_MESSAGES } from './constants';
+
+/**
+ * Base error class for Hypernum library
+ * All other error classes inherit from this
+ */
+export class HypernumError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'HypernumError';
+    Object.setPrototypeOf(this, HypernumError.prototype);
+  }
+}
+
+/**
+ * Error for validation failures
+ */
+export class ValidationError extends HypernumError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+    Object.setPrototypeOf(this, ValidationError.prototype);
+  }
+}
+
+/**
+ * Error for arithmetic overflow conditions
+ */
+export class OverflowError extends HypernumError {
+  constructor(message: string = ERROR_MESSAGES.OVERFLOW) {
+    super(message);
+    this.name = 'OverflowError';
+    Object.setPrototypeOf(this, OverflowError.prototype);
+  }
+}
+
+/**
+ * Error for arithmetic underflow conditions
+ */
+export class UnderflowError extends HypernumError {
+  constructor(message: string = ERROR_MESSAGES.UNDERFLOW) {
+    super(message);
+    this.name = 'UnderflowError';
+    Object.setPrototypeOf(this, UnderflowError.prototype);
+  }
+}
+
+/**
+ * Error for division by zero
+ */
+export class DivisionByZeroError extends HypernumError {
+  constructor(message: string = ERROR_MESSAGES.DIVISION_BY_ZERO) {
+    super(message);
+    this.name = 'DivisionByZeroError';
+    Object.setPrototypeOf(this, DivisionByZeroError.prototype);
+  }
+}
+
+/**
+ * Error for precision-related issues
+ */
+export class PrecisionError extends HypernumError {
+  constructor(message: string = ERROR_MESSAGES.INVALID_PRECISION) {
+    super(message);
+    this.name = 'PrecisionError';
+    Object.setPrototypeOf(this, PrecisionError.prototype);
+  }
+}
+
+/**
+ * Error for computation limits exceeded
+ */
+export class ComputationLimitError extends HypernumError {
+  constructor(message: string = ERROR_MESSAGES.COMPUTATION_LIMIT) {
+    super(message);
+    this.name = 'ComputationLimitError';
+    Object.setPrototypeOf(this, ComputationLimitError.prototype);
+  }
+}
+
+/**
+ * Error for invalid operations on data structures
+ */
+export class DataStructureError extends HypernumError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DataStructureError';
+    Object.setPrototypeOf(this, DataStructureError.prototype);
+  }
+}
+
+/**
+ * Error for heap property violations
+ */
+export class HeapPropertyError extends DataStructureError {
+  constructor(message: string = ERROR_MESSAGES.INVALID_HEAP_PROPERTY) {
+    super(message);
+    this.name = 'HeapPropertyError';
+    Object.setPrototypeOf(this, HeapPropertyError.prototype);
+  }
+}
+
+/**
+ * Error for tree-related issues
+ */
+export class TreeError extends DataStructureError {
+  constructor(message: string = ERROR_MESSAGES.TREE_DEPTH_EXCEEDED) {
+    super(message);
+    this.name = 'TreeError';
+    Object.setPrototypeOf(this, TreeError.prototype);
+  }
+}
+
+/**
+ * Error for array index out of bounds
+ */
+export class IndexError extends DataStructureError {
+  constructor(message: string = ERROR_MESSAGES.NEGATIVE_INDEX) {
+    super(message);
+    this.name = 'IndexError';
+    Object.setPrototypeOf(this, IndexError.prototype);
+  }
+}
+
+/**
+ * Error for invalid number format or conversion
+ */
+export class FormatError extends HypernumError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'FormatError';
+    Object.setPrototypeOf(this, FormatError.prototype);
+  }
+}
+
+/**
+ * Error for invalid Roman numeral operations
+ */
+export class RomanNumeralError extends FormatError {
+  constructor(message: string = ERROR_MESSAGES.INVALID_ROMAN) {
+    super(message);
+    this.name = 'RomanNumeralError';
+    Object.setPrototypeOf(this, RomanNumeralError.prototype);
+  }
+}
+
+/**
+ * Type guard to check if an error is a Hypernum error
+ */
+export function isHypernumError(error: unknown): error is HypernumError {
+  return error instanceof HypernumError;
+}
+
+/**
+ * Helper function to wrap unknown errors into HypernumError
+ */
+export function wrapError(error: unknown): HypernumError {
+  if (isHypernumError(error)) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new HypernumError(error.message);
+  }
+  return new HypernumError('An unknown error occurred');
+}
+
+/**
+ * Helper function to create an appropriate error from a message and optional type
+ */
+export function createError(message: string, type?: string): HypernumError {
+  switch (type) {
+    case 'validation':
+      return new ValidationError(message);
+    case 'overflow':
+      return new OverflowError(message);
+    case 'underflow':
+      return new UnderflowError(message);
+    case 'division':
+      return new DivisionByZeroError(message);
+    case 'precision':
+      return new PrecisionError(message);
+    case 'computation':
+      return new ComputationLimitError(message);
+    case 'heap':
+      return new HeapPropertyError(message);
+    case 'tree':
+      return new TreeError(message);
+    case 'index':
+      return new IndexError(message);
+    case 'format':
+      return new FormatError(message);
+    case 'roman':
+      return new RomanNumeralError(message);
+    default:
+      return new HypernumError(message);
+  }
+}

package/src/core/hypernum.ts

@@ -0,0 +1,241 @@
+/**
+ * Main Hypernum class that provides a high-level interface to all library functionality
+ */
+
+
+import {
+  DEFAULT_OPTIONS,
+  FEATURES,
+  MAX_PRECISION,
+  MAX_COMPUTATION_STEPS
+} from './constants';
+import { 
+  HypernumError, 
+  ValidationError, 
+  OverflowError 
+} from './errors';
+
+
+// Import all operations and structures
+import * as arithmetic from '../operations/arithmetic';
+import * as bitwise from '../operations/bitwise';
+import * as power from '../operations/power';
+import { BigArray, NumberTree, AckermannStructure } from '../structures';
+import * as formatting from '../utils/formatting';
+import * as validation from '../utils/validation';
+import * as precision from '../utils/precision';
+import { MinHeap, MaxHeap } from '@/storage';
+/**
+ * Configuration options for Hypernum instance
+ */
+export interface HypernumConfig {
+  precision?: number;
+  roundingMode?: precision.RoundingMode;
+  checkOverflow?: boolean;
+  maxSteps?: number;
+  debug?: boolean;
+}
+
+export class Hypernum {
+  private readonly config: Required<HypernumConfig>;
+  private readonly structures: {
+    arrays: Map<string, BigArray<bigint>>;
+    trees: Map<string, NumberTree>;
+    heaps: Map<string, MinHeap<bigint> | MaxHeap<bigint>>;
+  };
+
+  constructor(config: HypernumConfig = {}) {
+    this.config = {
+      precision: config.precision ?? DEFAULT_OPTIONS.precision,
+      roundingMode: config.roundingMode ?? DEFAULT_OPTIONS.roundingMode as precision.RoundingMode,
+      checkOverflow: config.checkOverflow ?? DEFAULT_OPTIONS.checkOverflow,
+      maxSteps: config.maxSteps ?? DEFAULT_OPTIONS.maxSteps,
+      debug: config.debug ?? FEATURES.DEBUG_MODE
+    };
+
+    // Validate configuration
+    if (this.config.precision < 0 || this.config.precision > MAX_PRECISION) {
+      throw new ValidationError(`Precision must be between 0 and ${MAX_PRECISION}`);
+    }
+    if (this.config.maxSteps < 1 || this.config.maxSteps > MAX_COMPUTATION_STEPS) {
+      throw new ValidationError(`Max steps must be between 1 and ${MAX_COMPUTATION_STEPS}`);
+    }
+
+    // Initialize data structure storage
+    this.structures = {
+      arrays: new Map(),
+      trees: new Map(),
+      heaps: new Map()
+    };
+  }
+
+  // Arithmetic Operations
+  public add(a: bigint | string | number, b: bigint | string | number): bigint {
+    return arithmetic.add(a, b, this.config);
+  }
+
+  public subtract(a: bigint | string | number, b: bigint | string | number): bigint {
+    return arithmetic.subtract(a, b, this.config);
+  }
+
+  public multiply(a: bigint | string | number, b: bigint | string | number): bigint {
+    return arithmetic.multiply(a, b, this.config);
+  }
+
+  public divide(a: bigint | string | number, b: bigint | string | number): bigint {
+    return arithmetic.divide(a, b, this.config);
+  }
+
+  public mod(a: bigint | string | number, b: bigint | string | number): bigint {
+    return arithmetic.remainder(a, b, this.config);
+  }
+
+  // Power Operations
+  public power(base: bigint | string | number, exponent: bigint | string | number): bigint {
+    return power.power(base, exponent, this.config);
+  }
+
+  public sqrt(value: bigint | string | number): bigint {
+    return power.sqrt(value, this.config);
+  }
+
+  public nthRoot(value: bigint | string | number, n: bigint | string | number): bigint {
+    return power.nthRoot(value, n, this.config);
+  }
+
+  // Bitwise Operations
+  public and(a: bigint | string | number, b: bigint | string | number): bigint {
+    return bitwise.and(a, b);
+  }
+
+  public or(a: bigint | string | number, b: bigint | string | number): bigint {
+    return bitwise.or(a, b);
+  }
+
+  public xor(a: bigint | string | number, b: bigint | string | number): bigint {
+    return bitwise.xor(a, b);
+  }
+
+  public not(value: bigint | string | number): bigint {
+    return bitwise.not(value);
+  }
+ /**
+   * Calculates the greatest common divisor of two numbers
+   */
+ public gcd(a: bigint | string | number, b: bigint | string | number): bigint {
+  return arithmetic.gcd(a, b);
+}
+
+/**
+ * Calculates the least common multiple of two numbers
+ */
+public lcm(a: bigint | string | number, b: bigint | string | number): bigint {
+  return arithmetic.lcm(a, b);
+}
+  // Data Structure Management
+  public createArray(id: string): BigArray<bigint> {
+    if (this.structures.arrays.has(id)) {
+      throw new ValidationError(`Array with id '${id}' already exists`);
+    }
+    const array = new BigArray<bigint>();
+    this.structures.arrays.set(id, array);
+    return array;
+  }
+
+  public getArray(id: string): BigArray<bigint> {
+    const array = this.structures.arrays.get(id);
+    if (!array) {
+      throw new ValidationError(`Array with id '${id}' not found`);
+    }
+    return array;
+  }
+
+  public createTree(id: string): NumberTree {
+    if (this.structures.trees.has(id)) {
+      throw new ValidationError(`Tree with id '${id}' already exists`);
+    }
+    const tree = new NumberTree();
+    this.structures.trees.set(id, tree);
+    return tree;
+  }
+
+  public getTree(id: string): NumberTree {
+    const tree = this.structures.trees.get(id);
+    if (!tree) {
+      throw new ValidationError(`Tree with id '${id}' not found`);
+    }
+    return tree;
+  }
+
+  public createHeap(id: string, isMinHeap: boolean = true): MinHeap<bigint> | MaxHeap<bigint> {
+    if (this.structures.heaps.has(id)) {
+      throw new ValidationError(`Heap with id '${id}' already exists`);
+    }
+    const heap = isMinHeap ? new MinHeap<bigint>(this.compareValues) : new MaxHeap<bigint>(this.compareValues);
+    this.structures.heaps.set(id, heap);
+    return heap;
+  }
+
+  public getHeap(id: string): MinHeap<bigint> | MaxHeap<bigint> {
+    const heap = this.structures.heaps.get(id);
+    if (!heap) {
+      throw new ValidationError(`Heap with id '${id}' not found`);
+    }
+    return heap;
+  }
+
+  // Special Functions
+  public createAckermannStructure(): AckermannStructure {
+    return new AckermannStructure();
+  }
+
+  // Formatting and Validation
+  public format(value: bigint | string | number, options?: formatting.FormatOptions): string {
+    const bigValue = validation.toBigInt(value);
+    return formatting.formatBigInt(bigValue, options);
+  }
+
+  public validate(value: unknown): boolean {
+    try {
+      validation.toBigInt(value);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // Configuration Management
+  public updateConfig(newConfig: Partial<HypernumConfig>): void {
+    Object.assign(this.config, newConfig);
+  }
+
+  public getConfig(): Readonly<Required<HypernumConfig>> {
+    return { ...this.config };
+  }
+
+  // Utility Functions
+  private compareValues(a: bigint, b: bigint): -1 | 0 | 1 {
+    if (a < b) return -1;
+    if (a > b) return 1;
+    return 0;
+  }
+
+  // Cleanup
+  public dispose(): void {
+    this.structures.arrays.clear();
+    this.structures.trees.clear();
+    this.structures.heaps.clear();
+  }
+}
+
+// Export additional types and utilities
+export {
+  HypernumError,
+  ValidationError,
+  OverflowError,
+  precision,
+  formatting,
+  validation
+};
+
+export default Hypernum;

package/src/core/index.ts

@@ -0,0 +1,5 @@
+export * from './config';
+export * from './errors';
+export * from './constants';
+export { Hypernum } from './hypernum';
+export * from './common';

package/src/index.ts

@@ -0,0 +1,183 @@
+/**
+ * Hypernum - A TypeScript/JavaScript library for large number operations
+ */
+import { HypernumConfig, mergeConfig, validateConfig } from './core';
+import { Hypernum } from './core/hypernum';
+import { RoundingMode } from './utils/precision';
+
+// Version
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../package.json');
+const { version: VERSION } = JSON.parse(fs.readFileSync(packagePath, 'utf-8'));
+
+// Core exports
+export { Hypernum } from './core/hypernum';
+export * from './core/constants';
+export * from './core/common';
+export * from './core/config';
+
+// Re-export errors with explicit names to avoid conflicts
+export { 
+  HypernumError,
+  ComputationLimitError,
+  DataStructureError,
+  DivisionByZeroError,
+  FormatError,
+  HeapPropertyError,
+  IndexError,
+  PrecisionError,
+  RomanNumeralError,
+  TreeError,
+  UnderflowError
+} from './core/errors';
+
+// Data structures with explicit imports and exports
+export { AckermannStructure } from './structures/ackermann';
+export { BigArray, type BigArrayOptions } from './structures/big-array';
+export { NumberTree } from './structures/number-tree';
+export { PowerTower } from './structures/power-tower';
+export { MinHeap, MaxHeap, type Comparator } from './storage/';
+
+// Operations with explicit exports
+export {
+  add,
+  subtract,
+  multiply,
+  divide,
+  remainder,
+  abs,
+  sign,
+  gcd,
+  lcm
+} from './operations/arithmetic';
+
+export {
+  and,
+  or,
+  xor,
+  not,
+  leftShift,
+  rightShift,
+  unsignedRightShift,
+  rotateLeft,
+  rotateRight,
+  popCount,
+  trailingZeros,
+  leadingZeros,
+  getBit,
+  setBit,
+  clearBit,
+  toggleBit
+} from './operations/bitwise';
+
+export {
+  compare,
+  equals,
+  lessThan,
+  lessThanOrEqual,
+  greaterThan,
+  greaterThanOrEqual,
+  between,
+  max,
+  min,
+  clamp,
+  allEqual,
+  isAscending,
+  isDescending,
+  createComparator
+} from './operations/comparison';
+
+export {
+  toBinary,
+  toOctal,
+  toHexadecimal,
+  toBase,
+  fromBase,
+  toFraction,
+  fromFraction,
+  fromScientific,
+  toScientific,
+  fromRoman,
+  toRoman
+} from './operations/conversion';
+
+export {
+  factorial,
+  binomial,
+  subfactorial,
+  risingFactorial,
+  fallingFactorial,
+  multiFactorial,
+  primorial
+} from './operations/factorial';
+
+export {
+  power,
+  sqrt,
+  nthRoot,
+  tetration,
+  superRoot
+} from './operations/power';
+
+// Utils with explicit exports
+export {
+  toBigInt,
+  validateNonNegative,
+  validatePositive,
+  checkAdditionOverflow,
+  checkMultiplicationOverflow,
+  checkPowerOverflow
+} from './utils/validation';
+
+export {
+  formatBigInt,
+  parseBigIntString,
+  normalizeNumberString
+} from './utils/formatting';
+
+export {
+  RoundingMode,
+  round,
+  scaleByPowerOfTen,
+  scaledDivision,
+  normalizePrecision
+} from './utils/precision';
+
+/**
+ * Creates a new Hypernum instance with custom configuration
+ */
+export function createHypernum(config?: Partial<HypernumConfig>): Hypernum {
+  const mergedConfig = mergeConfig(config || {});
+  validateConfig(mergedConfig);
+  
+  const instanceConfig = {
+    precision: 'arithmetic' in mergedConfig 
+      ? mergedConfig.arithmetic.defaultPrecision 
+      : mergedConfig.precision ?? 0,
+    roundingMode: 'arithmetic' in mergedConfig 
+      ? mergedConfig.arithmetic.defaultRoundingMode 
+      : (mergedConfig.roundingMode as RoundingMode) ?? RoundingMode.HALF_EVEN,
+    checkOverflow: 'arithmetic' in mergedConfig 
+      ? mergedConfig.arithmetic.checkOverflow 
+      : mergedConfig.checkOverflow ?? true,
+    maxSteps: 'arithmetic' in mergedConfig 
+      ? mergedConfig.arithmetic.maxComputationSteps 
+      : mergedConfig.maxSteps ?? 1000,
+    debug: 'debug' in mergedConfig && typeof mergedConfig.debug === 'object' 
+      ? mergedConfig.debug.verbose 
+      : false
+  };
+  
+  return new Hypernum(instanceConfig);
+}
+
+// Default instance
+export const defaultHypernum = createHypernum();
+
+// Export version
+export { VERSION };
+
+// Default export
+export default Hypernum;