@obinexusmk2/hypernum 0.1.0

package/src/core/common.ts

@@ -0,0 +1,185 @@
+/**
+ * Common type definitions for Hypernum library
+ * Contains shared types used throughout the library's modules
+ */
+
+import { RoundingMode } from '../utils/precision';
+
+/**
+ * Valid input types for numeric values
+ */
+export type NumericInput = bigint | string | number;
+
+/**
+ * Result type for operations that may fail
+ */
+export type Result<T> = {
+  /** Whether the operation succeeded */
+  success: boolean;
+  /** The operation result if successful */
+  value?: T;
+  /** Error message if operation failed */
+  error?: string;
+};
+
+/**
+ * Base options interface for operations
+ */
+export interface BaseOptions {
+  /** Decimal precision for operations */
+  precision?: number;
+  /** Rounding mode for decimal operations */
+  roundingMode?: RoundingMode;
+  /** Whether to check for overflow */
+  checkOverflow?: boolean;
+}
+
+/**
+ * Options for number formatting
+ */
+export interface FormatOptions extends BaseOptions {
+  /** Number notation style */
+  notation?: 'standard' | 'scientific' | 'engineering' | 'compact';
+  /** Enable grouping separators */
+  grouping?: boolean;
+  /** Size of digit groups */
+  groupSize?: number;
+  /** Decimal point character */
+  decimalSeparator?: string;
+  /** Grouping separator character */
+  groupSeparator?: string;
+  /** Convert to uppercase (for special formats) */
+  uppercase?: boolean;
+}
+
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+  /** Maximum number of entries */
+  maxSize: number;
+  /** Time-to-live in milliseconds */
+  ttl?: number;
+  /** Eviction policy */
+  evictionPolicy?: 'LRU' | 'LFU' | 'FIFO';
+}
+
+/**
+ * Mathematical constants configuration
+ */
+export interface MathConstantsConfig {
+  /** Precision for constant calculations */
+  precision: number;
+  /** Enable caching of computed values */
+  cache?: boolean;
+  /** Custom calculation algorithm */
+  algorithm?: 'series' | 'iteration' | 'approximation';
+}
+
+/**
+ * Debug configuration
+ */
+export interface DebugConfig {
+  /** Enable detailed logging */
+  verbose: boolean;
+  /** Track operation performance */
+  trackPerformance: boolean;
+  /** Log level */
+  logLevel: 'error' | 'warn' | 'info' | 'debug';
+}
+
+/**
+ * Numeric range specification
+ */
+export interface NumericRange {
+  /** Start of range (inclusive) */
+  start: bigint;
+  /** End of range (inclusive) */
+  end: bigint;
+  /** Step size for iteration */
+  step?: bigint;
+}
+
+/**
+ * Operation status monitoring
+ */
+export interface OperationStatus {
+  /** Current phase of operation */
+  phase: string;
+  /** Percentage complete (0-100) */
+  progress: number;
+  /** Estimated time remaining (ms) */
+  estimatedTimeRemaining?: number;
+  /** Memory usage in bytes */
+  memoryUsage?: number;
+  /** Computation steps completed */
+  steps: number;
+}
+
+/**
+ * Performance metrics
+ */
+export interface PerformanceMetrics {
+  /** Operation execution time (ms) */
+  executionTime: number;
+  /** Number of computation steps */
+  steps: number;
+  /** Peak memory usage (bytes) */
+  peakMemory: number;
+  /** Cache hit rate (0-1) */
+  cacheHitRate?: number;
+}
+
+/**
+ * Comparison function type
+ * Returns:
+ *  -1: a < b
+ *   0: a = b
+ *   1: a > b
+ */
+export type Comparator<T> = (a: T, b: T) => -1 | 0 | 1;
+
+/**
+ * Progress callback type
+ */
+export type ProgressCallback = (status: OperationStatus) => void;
+
+/**
+ * Error callback type
+ */
+export type ErrorCallback = (error: Error, phase: string) => void;
+
+/**
+ * Value validation function type
+ */
+export type Validator<T> = (value: T) => boolean;
+
+/**
+ * Node statistics interface
+ */
+export interface NodeStats {
+  /** Node height in tree */
+  height: number;
+  /** Subtree size */
+  size: number;
+  /** Sum of subtree values */
+  sum: bigint;
+  /** Minimum value in subtree */
+  min: bigint;
+  /** Maximum value in subtree */
+  max: bigint;
+}
+
+/**
+ * Operation options interface
+ */
+export interface OperationOptions extends BaseOptions {
+  /** Maximum computation steps */
+  maxSteps?: number;
+  /** Progress callback */
+  onProgress?: ProgressCallback;
+  /** Error callback */
+  onError?: ErrorCallback;
+  /** Value validator */
+  validator?: Validator<bigint>;
+}

package/src/core/config.ts

@@ -0,0 +1,393 @@
+/**
+ * Configuration type definitions for Hypernum library
+ * Defines all configuration options and their default values
+ */
+
+import { RoundingMode } from '../utils/precision';
+import { 
+  FormatOptions,
+  DebugConfig,
+  CacheConfig,
+  MathConstantsConfig
+} from './common';
+
+/**
+ * Basic configuration options for simple usage
+ */
+export interface BasicConfig {
+  /** Decimal precision for operations */
+  precision?: number;
+  /** Rounding mode for decimal operations */
+  roundingMode?: RoundingMode;
+  /** Whether to check for overflow */
+  checkOverflow?: boolean;
+  /** Maximum allowed computation steps */
+  maxSteps?: number;
+  /** Enable debug mode */
+  debug?: boolean;
+}
+
+/**
+ * Configuration for arithmetic operations
+ */
+export interface ArithmeticConfig {
+  /** Default precision for decimal operations */
+  defaultPrecision: number;
+  /** Default rounding mode */
+  defaultRoundingMode: RoundingMode;
+  /** Whether to check for overflow by default */
+  checkOverflow: boolean;
+  /** Maximum steps for iterative calculations */
+  maxComputationSteps: number;
+  /** Configure automatic precision adjustment */
+  autoPrecision: {
+    enabled: boolean;
+    maxPrecision: number;
+    minPrecision: number;
+  };
+  /** Constants calculation configuration */
+  constants: MathConstantsConfig;
+}
+
+/**
+ * Configuration for data structures
+ */
+export interface DataStructuresConfig {
+  /** Array configuration */
+  array: {
+    initialCapacity: number;
+    growthFactor: number;
+    maxSize: number;
+  };
+  /** Tree configuration */
+  tree: {
+    maxDepth: number;
+    autoBalance: boolean;
+    nodeLimit: number;
+  };
+  /** Heap configuration */
+  heap: {
+    initialCapacity: number;
+    growthPolicy: 'double' | 'linear' | 'fibonacci';
+    validatePropertyOnOperation: boolean;
+  };
+  /** Cache configuration */
+  cache: CacheConfig & {
+    enabled: boolean;
+    persistToDisk: boolean;
+    compressionEnabled: boolean;
+  };
+}
+
+/**
+ * Configuration for number formatting
+ */
+export interface FormattingConfig extends FormatOptions {
+  /** Scientific notation configuration */
+  scientific: {
+    /** Minimum exponent to trigger scientific notation */
+    minExponent: number;
+    /** Maximum significant digits */
+    maxSignificantDigits: number;
+    /** Exponent separator character */
+    exponentSeparator: string;
+  };
+  /** Engineering notation configuration */
+  engineering: {
+    /** Use SI prefixes */
+    useSIPrefixes: boolean;
+    /** Custom unit definitions */
+    customUnits?: Map<number, string>;
+  };
+  /** Localization settings */
+  localization: {
+    /** Locale identifier */
+    locale: string;
+    /** Custom number formatting */
+    numberFormat?: Intl.NumberFormatOptions;
+    /** Use locale-specific grouping */
+    useLocaleGrouping: boolean;
+  };
+}
+
+/**
+ * Configuration for performance monitoring
+ */
+export interface PerformanceConfig {
+  /** Enable performance tracking */
+  enableTracking: boolean;
+  /** Sampling rate for metrics (0-1) */
+  samplingRate: number;
+  /** Performance thresholds */
+  thresholds: {
+    /** Warning threshold in milliseconds */
+    warnThresholdMs: number;
+    /** Error threshold in milliseconds */
+    errorThresholdMs: number;
+    /** Maximum allowed memory usage in bytes */
+    maxMemoryBytes: number;
+  };
+  /** Metrics collection configuration */
+  metrics: {
+    /** Enable detailed operation timing */
+    timing: boolean;
+    /** Track memory usage */
+    memory: boolean;
+    /** Track cache performance */
+    cache: boolean;
+    /** Custom metrics to track */
+    custom?: Map<string, (operation: any) => number>;
+  };
+}
+
+/**
+ * Feature flags for optional functionality
+ */
+export interface FeatureFlags {
+  /** Enable experimental features */
+  experimentalFeatures: boolean;
+  /** Use WebAssembly implementations when available */
+  useWasm: boolean;
+  /** Enable worker thread support */
+  workerThreads: boolean;
+  /** Enable SharedArrayBuffer support */
+  sharedArrayBuffer: boolean;
+  /** Enable BigInt64Array support */
+  bigIntTypedArrays: boolean;
+}
+
+/**
+ * Full configuration interface with all options
+ */
+export interface FullConfig {
+  /** Arithmetic operation configuration */
+  arithmetic: ArithmeticConfig;
+  /** Data structure configuration */
+  dataStructures: DataStructuresConfig;
+  /** Formatting configuration */
+  formatting: FormattingConfig;
+  /** Performance configuration */
+  performance: PerformanceConfig;
+  /** Debug configuration */
+  debug: DebugConfig;
+  /** Feature flags */
+  features: FeatureFlags;
+  /** Custom configuration options */
+  custom?: Map<string, any>;
+}
+
+/**
+ * Converts FullConfig to BasicConfig if necessary
+ */
+export function convertToBasicConfig(config: HypernumConfig): BasicConfig {
+  if (isBasicConfig(config)) {
+    return config;
+  }
+  return {
+    precision: config.arithmetic.defaultPrecision,
+    roundingMode: config.arithmetic.defaultRoundingMode,
+    checkOverflow: config.arithmetic.checkOverflow,
+    maxSteps: config.arithmetic.maxComputationSteps,
+    debug: config.debug.verbose
+  };
+}
+
+/**
+ * Combined configuration type that can be either basic or full
+ */
+export type HypernumConfig = BasicConfig | FullConfig;
+
+/**
+ * Default configuration values for basic config
+ */
+export const DEFAULT_BASIC_CONFIG: Required<BasicConfig> = {
+  precision: 0,
+  roundingMode: RoundingMode.HALF_EVEN,
+  checkOverflow: true,
+  maxSteps: 1000,
+  debug: false
+};
+
+/**
+ * Full default configuration values
+ */
+export const DEFAULT_FULL_CONFIG: FullConfig = {
+  arithmetic: {
+    defaultPrecision: 0,
+    defaultRoundingMode: RoundingMode.HALF_EVEN,
+    checkOverflow: true,
+    maxComputationSteps: 1000,
+    autoPrecision: {
+      enabled: true,
+      maxPrecision: 100,
+      minPrecision: 0
+    },
+    constants: {
+      precision: 50,
+      cache: true,
+      algorithm: 'series'
+    }
+  },
+  dataStructures: {
+    array: {
+      initialCapacity: 16,
+      growthFactor: 2,
+      maxSize: 1_000_000
+    },
+    tree: {
+      maxDepth: 1000,
+      autoBalance: true,
+      nodeLimit: 1_000_000
+    },
+    heap: {
+      initialCapacity: 16,
+      growthPolicy: 'double',
+      validatePropertyOnOperation: true
+    },
+    cache: {
+      enabled: true,
+      maxSize: 1000,
+      ttl: 3600000, // 1 hour
+      evictionPolicy: 'LRU',
+      persistToDisk: false,
+      compressionEnabled: false
+    }
+  },
+  formatting: {
+    notation: 'standard',
+    precision: 0,
+    grouping: true,
+    groupSize: 3,
+    decimalSeparator: '.',
+    groupSeparator: ',',
+    uppercase: false,
+    scientific: {
+      minExponent: 6,
+      maxSignificantDigits: 6,
+      exponentSeparator: 'e'
+    },
+    engineering: {
+      useSIPrefixes: true
+    },
+    localization: {
+      locale: 'en-US',
+      useLocaleGrouping: false
+    }
+  },
+  performance: {
+    enableTracking: false,
+    samplingRate: 0.1,
+    thresholds: {
+      warnThresholdMs: 100,
+      errorThresholdMs: 1000,
+      maxMemoryBytes: 1024 * 1024 * 1024 // 1GB
+    },
+    metrics: {
+      timing: true,
+      memory: true,
+      cache: true
+    }
+  },
+  debug: {
+    verbose: false,
+    trackPerformance: false,
+    logLevel: 'error'
+  },
+  features: {
+    experimentalFeatures: false,
+    useWasm: false,
+    workerThreads: false,
+    sharedArrayBuffer: false,
+    bigIntTypedArrays: true
+  }
+};
+
+/**
+ * Type guard to check if config is a full configuration
+ */
+export function isFullConfig(config: HypernumConfig): config is FullConfig {
+  return 'arithmetic' in config && 'dataStructures' in config;
+}
+
+/**
+ * Type guard to check if config is a basic configuration
+ */
+export function isBasicConfig(config: HypernumConfig): config is BasicConfig {
+  return !isFullConfig(config);
+}
+
+/**
+ * Validates configuration values
+ */
+export function validateConfig(config: HypernumConfig): void {
+  if (isFullConfig(config)) {
+    validateFullConfig(config);
+  } else {
+    validateBasicConfig(config);
+  }
+}
+
+/**
+ * Validates basic configuration values
+ */
+function validateBasicConfig(config: BasicConfig): void {
+  if (config.precision !== undefined && config.precision < 0) {
+    throw new Error('Precision cannot be negative');
+  }
+  if (config.maxSteps !== undefined && config.maxSteps <= 0) {
+    throw new Error('Maximum steps must be positive');
+  }
+  if (config.debug !== undefined && typeof config.debug !== 'boolean') {
+    throw new Error('Debug flag must be a boolean');
+  }
+}
+
+/**
+ * Validates full configuration values
+ */
+function validateFullConfig(config: FullConfig): void {
+  if (config.arithmetic.defaultPrecision < 0) {
+    throw new Error('Default precision cannot be negative');
+  }
+  if (config.arithmetic.maxComputationSteps <= 0) {
+    throw new Error('Max computation steps must be positive');
+  }
+  if (config.dataStructures.array.initialCapacity <= 0) {
+    throw new Error('Initial capacity must be positive');
+  }
+  if (config.dataStructures.array.growthFactor <= 1) {
+    throw new Error('Growth factor must be greater than 1');
+  }
+  if (config.performance.samplingRate < 0 || config.performance.samplingRate > 1) {
+    throw new Error('Sampling rate must be between 0 and 1');
+  }
+}
+
+/**
+ * Merges configuration with appropriate defaults
+ */
+export function mergeConfig(custom: Partial<HypernumConfig> = {}): HypernumConfig {
+  if (isFullConfig(custom  as FullConfig)) {
+    const fullConfig = custom as FullConfig;
+    return {
+      ...DEFAULT_FULL_CONFIG,
+      ...fullConfig,
+      arithmetic: { ...DEFAULT_FULL_CONFIG.arithmetic, ...fullConfig.arithmetic },
+      dataStructures: { ...DEFAULT_FULL_CONFIG.dataStructures, ...fullConfig.dataStructures },
+      formatting: { ...DEFAULT_FULL_CONFIG.formatting, ...fullConfig.formatting },
+      performance: { ...DEFAULT_FULL_CONFIG.performance, ...fullConfig.performance },
+      debug: { ...DEFAULT_FULL_CONFIG.debug, ...fullConfig.debug },
+      features: { ...DEFAULT_FULL_CONFIG.features, ...fullConfig.features }
+    };
+  }
+  
+  const basicConfig: BasicConfig = {
+    precision: (custom as Partial<BasicConfig>).precision ?? DEFAULT_BASIC_CONFIG.precision,
+    roundingMode: (custom as Partial<BasicConfig>).roundingMode ?? DEFAULT_BASIC_CONFIG.roundingMode,
+    checkOverflow: (custom as Partial<BasicConfig>).checkOverflow ?? DEFAULT_BASIC_CONFIG.checkOverflow,
+    maxSteps: (custom as Partial<BasicConfig>).maxSteps ?? DEFAULT_BASIC_CONFIG.maxSteps,
+    debug: (custom as Partial<BasicConfig>).debug ?? DEFAULT_BASIC_CONFIG.debug
+  };
+
+  return basicConfig;
+}

package/src/core/constants.ts

@@ -0,0 +1,102 @@
+/**
+ * Core constants for Hypernum library
+ * Defines fundamental values and limits used across the library
+ */
+
+// Numerical limits
+export const MAX_SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
+export const MIN_SAFE_INTEGER = BigInt(Number.MIN_SAFE_INTEGER);
+export const MAX_PRECISION = 100;
+export const MAX_COMPUTATION_STEPS = 1000;
+export const MAX_BITS = 1024;
+
+// Commonly used values
+export const ZERO = BigInt(0);
+export const ONE = BigInt(1);
+export const TWO = BigInt(2);
+export const TEN = BigInt(10);
+export const NEGATIVE_ONE = BigInt(-1);
+
+// Power operation limits
+export const MAX_POWER_BASE = BigInt(2) ** BigInt(53);
+export const MAX_POWER_EXPONENT = BigInt(1000);
+export const MAX_TETRATION_HEIGHT = BigInt(4);
+export const MAX_FACTORIAL_INPUT = BigInt(1000);
+
+// Tree and heap configuration
+export const DEFAULT_TREE_MAX_DEPTH = 1000;
+export const DEFAULT_HEAP_INITIAL_CAPACITY = 16;
+export const DEFAULT_ARRAY_GROWTH_FACTOR = 2;
+export const MIN_ARRAY_CAPACITY = 16;
+
+// Formatting configuration
+export const DEFAULT_DECIMAL_SEPARATOR = '.';
+export const DEFAULT_GROUP_SEPARATOR = ',';
+export const DEFAULT_GROUP_SIZE = 3;
+export const MAX_GROUP_SIZE = 10;
+
+// Roman numeral limits
+export const MIN_ROMAN_VALUE = 1;
+export const MAX_ROMAN_VALUE = 3999;
+
+// Ackermann function limits
+export const MAX_ACKERMANN_M = 4;
+export const MAX_ACKERMANN_N = 1000;
+
+// Cache configuration
+export const DEFAULT_CACHE_SIZE = 1000;
+export const MAX_CACHE_SIZE = 10000;
+
+// Error messages
+export const ERROR_MESSAGES = {
+  OVERFLOW: 'Operation would result in overflow',
+  UNDERFLOW: 'Operation would result in underflow',
+  NEGATIVE_ROOT: 'Cannot compute root of negative number',
+  NEGATIVE_EXPONENT: 'Negative exponents not supported for integers',
+  DIVISION_BY_ZERO: 'Division by zero',
+  INVALID_PRECISION: 'Precision must be non-negative and not exceed MAX_PRECISION',
+  INVALID_BASE: 'Base must be a positive integer',
+  INVALID_ROMAN: 'Invalid Roman numeral',
+  COMPUTATION_LIMIT: 'Computation exceeded maximum allowed steps',
+  NEGATIVE_INDEX: 'Array index cannot be negative',
+  TREE_DEPTH_EXCEEDED: 'Maximum tree depth exceeded',
+  INVALID_HEAP_PROPERTY: 'Heap property violation detected'
+} as const;
+
+// Feature flags for optional functionality
+export const FEATURES = {
+  OVERFLOW_CHECKING: true,
+  AUTOMATIC_PRECISION: true,
+  MEMOIZATION: true,
+  TREE_BALANCING: true,
+  DEBUG_MODE: false
+} as const;
+
+// Default options for various operations
+export const DEFAULT_OPTIONS = {
+  precision: 0,
+  roundingMode: 'HALF_EVEN',
+  checkOverflow: true,
+  maxSteps: MAX_COMPUTATION_STEPS,
+  grouping: true,
+  uppercase: false,
+  cache: true
+} as const;
+
+// Units for number formatting (powers of 1000)
+export const NUMBER_UNITS = [
+  { value: 1n, symbol: '' },
+  { value: 1000n, symbol: 'K' },
+  { value: 1000000n, symbol: 'M' },
+  { value: 1000000000n, symbol: 'B' },
+  { value: 1000000000000n, symbol: 'T' },
+  { value: 1000000000000000n, symbol: 'Q' }
+] as const;
+
+// Performance monitoring thresholds
+export const PERFORMANCE = {
+  WARN_THRESHOLD_MS: 100,
+  ERROR_THRESHOLD_MS: 1000,
+  MAX_ARRAY_SIZE: 1000000,
+  MAX_TREE_SIZE: 1000000
+} as const;