@obinexusmk2/hypernum 0.1.0

package/src/types/core.d.ts

@@ -0,0 +1,161 @@
+
+import { RoundingMode } from '../utils/precision';
+import { 
+  CacheConfig,
+  MathConstantsConfig,
+  FormatOptions,
+  DebugConfig
+} 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: {
+    minExponent: number;
+    maxSignificantDigits: number;
+    exponentSeparator: string;
+  };
+  /** Engineering notation configuration */
+  engineering: {
+    useSIPrefixes: boolean;
+    customUnits?: Map<number, string>;
+  };
+  /** Localization settings */
+  localization: {
+    locale: string;
+    numberFormat?: Intl.NumberFormatOptions;
+    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: {
+    warnThresholdMs: number;
+    errorThresholdMs: number;
+    maxMemoryBytes: number;
+  };
+  /** Metrics collection configuration */
+  metrics: {
+    timing: boolean;
+    memory: boolean;
+    cache: boolean;
+    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;
+}
+
+/**
+ * Complete configuration interface
+ */
+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;
+}
+
+/**
+ * Combined configuration type that can be either basic or full
+ */
+export type HypernumConfig = BasicConfig | FullConfig;

package/src/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './common';
+export * from './core'

package/src/utils/formatting.ts

@@ -0,0 +1,246 @@
+/**
+ * Formatting utilities for Hypernum library
+ * Provides functions for formatting large numbers and converting between different representations
+ */
+
+import { ValidationError } from './validation';
+
+// Types for formatting options
+export interface FormatOptions {
+  notation?: 'standard' | 'scientific' | 'engineering' | 'compact';
+  precision?: number;
+  grouping?: boolean;
+  groupSize?: number;
+  decimalSeparator?: string;
+  groupSeparator?: string;
+}
+
+export interface ScientificNotation {
+  coefficient: string;
+  exponent: number;
+}
+
+export interface ScientificNotation {
+  coefficient: string;
+  exponent: number;
+}
+
+// Default formatting options
+const DEFAULT_OPTIONS: Required<FormatOptions> = {
+  notation: 'standard',
+  precision: 0,
+  grouping: true,
+  groupSize: 3,
+  decimalSeparator: '.',
+  groupSeparator: ',',
+};
+
+/**
+ * Formats a BigInt value according to specified options
+ */
+export const formatBigInt = (value: bigint, options: FormatOptions = {}): string => {
+  const opts: Required<FormatOptions> = { ...DEFAULT_OPTIONS, ...options };
+  
+  // Handle negative numbers
+  const isNegative = value < BigInt(0);
+  const absValue = isNegative ? -value : value;
+  
+  let result: string;
+  switch (opts.notation) {
+    case 'scientific':
+      result = formatScientific(absValue, opts).coefficient + 'e' + 
+               formatScientific(absValue, opts).exponent;
+      break;
+    case 'engineering':
+      result = formatEngineering(absValue, opts);
+      break;
+    case 'compact':
+      result = formatCompact(absValue, opts);
+      break;
+    default:
+      result = formatStandard(absValue, opts);
+  }
+  
+  return isNegative ? '-' + result : result;
+};
+
+/**
+ * Formats a number in standard notation with grouping
+ */
+const formatStandard = (value: bigint, options: Required<FormatOptions>): string => {
+  let str = value.toString();
+  
+  if (!options.grouping) {
+    return str;
+  }
+  
+  // Apply grouping from the right
+  const result: string[] = [];
+  let position = str.length;
+  
+  while (position > 0) {
+    const start = Math.max(0, position - options.groupSize);
+    result.unshift(str.slice(start, position));
+    position = start;
+  }
+  
+  return result.join(options.groupSeparator);
+};
+
+/**
+ * Converts a number to scientific notation
+ */
+const formatScientific = (value: bigint, options: Required<FormatOptions>): ScientificNotation => {
+  if (value === BigInt(0)) {
+    return { coefficient: '0', exponent: 0 };
+  }
+  
+  const str = value.toString();
+  const exponent = str.length - 1;
+  
+  let coefficient = str[0] || '';
+  coefficient += options.decimalSeparator + str.slice(1, options.precision + 1);
+  
+  return {
+    coefficient: coefficient,
+    exponent: exponent,
+  };
+};
+
+/**
+ * Formats a number in engineering notation (exponents divisible by 3)
+ */
+const formatEngineering = (value: bigint, options: Required<FormatOptions>): string => {
+  if (value === BigInt(0)) {
+    return '0';
+  }
+  
+  const str = value.toString();
+  const len = str.length;
+  const exponent = Math.floor((len - 1) / 3) * 3;
+  
+  let coefficient = '';
+  const digitsBeforePoint = len - exponent;
+  
+  for (let i = 0; i < Math.min(len, digitsBeforePoint + options.precision); i++) {
+    if (i === digitsBeforePoint && i < len) {
+      coefficient += options.decimalSeparator;
+    }
+    coefficient += str[i];
+  }
+  
+  return `${coefficient}e${exponent}`;
+};
+
+/**
+ * Formats a number in compact notation (K, M, B, T)
+ */
+const formatCompact = (value: bigint, options: Required<FormatOptions>): string => {
+  const suffixes = ['', 'K', 'M', 'B', 'T', 'Q'];
+  const str = value.toString();
+  const len = str.length;
+  
+  if (len <= 3) {
+    return formatStandard(value, options);
+  }
+  
+  const suffixIndex = Math.min(Math.floor((len - 1) / 3), suffixes.length - 1);
+  const suffix = suffixes[suffixIndex];
+  
+  const scale = BigInt(10) ** BigInt(suffixIndex * 3);
+  const scaledValue = value / scale;
+  
+  let result = scaledValue.toString();
+  if (options.precision > 0) {
+    const remainder = value % scale;
+    if (remainder > BigInt(0)) {
+      const decimalPart = remainder.toString().padStart(3, '0').slice(0, options.precision);
+      result += options.decimalSeparator + decimalPart;
+    }
+  }
+  
+  return result + suffix;
+};
+
+/**
+ * Parses a formatted string back to BigInt
+ */
+export const parseBigIntString = (str: string, options: FormatOptions = {}): bigint => {
+  const opts: Required<FormatOptions> = { ...DEFAULT_OPTIONS, ...options };
+  
+  // Remove grouping separators
+  let cleanStr = str.replace(new RegExp(`\\${opts.groupSeparator}`, 'g'), '');
+  
+  // Handle scientific notation
+  if (cleanStr.toLowerCase().includes('e')) {
+    const [coefficient, exponent] = cleanStr.toLowerCase().split('e');
+    const base = BigInt(10);
+    const exp = BigInt(exponent || '0');
+    return BigInt(Math.floor(Number(coefficient))) * (base ** exp);
+  }
+  
+  // Handle suffixes
+  const suffixMap = new Map([
+    ['k', BigInt(1000)],
+    ['m', BigInt(1000000)],
+    ['b', BigInt(1000000000)],
+    ['t', BigInt(1000000000000)],
+    ['q', BigInt(1000000000000000)],
+  ]);
+  
+  const suffix = cleanStr.slice(-1).toLowerCase();
+  const multiplier = suffixMap.get(suffix);
+  if (multiplier) {
+    cleanStr = cleanStr.slice(0, -1);
+    const value = BigInt(Math.floor(Number(cleanStr)));
+    return value * multiplier;
+  }
+  
+  // Handle regular numbers
+  return BigInt(cleanStr);
+};
+
+/**
+ * Normalizes a string representation for comparison
+ */
+export const normalizeNumberString = (str: string): string => {
+  // Remove all spaces and separators
+  str = str.replace(/[\s,]/g, '');
+  
+  // Handle scientific notation
+  if (str.toLowerCase().includes('e')) {
+    const [coefficient, exponent] = str.toLowerCase().split('e');
+    const exp = parseInt(exponent || '0');
+    const coef = parseFloat(coefficient || '0');
+    return (coef * Math.pow(10, exp)).toString();
+  }
+  
+  return str;
+};
+
+/**
+ * Formats a number for display in a tree structure
+ */
+export const formatTreeValue = (value: bigint, depth: number = 0): string => {
+  const indent = '  '.repeat(depth);
+  return `${indent}${formatBigInt(value, { notation: 'compact' })}`;
+};
+
+/**
+ * Formats a range of numbers for display
+ */
+export const formatRange = (start: bigint, end: bigint, options: FormatOptions = {}): string => {
+  return `[${formatBigInt(start, options)} ... ${formatBigInt(end, options)}]`;
+};
+
+/**
+ * Formats a percentage
+ */
+export const formatPercentage = (value: bigint, total: bigint, precision: number = 2): string => {
+  if (total === BigInt(0)) {
+    throw new ValidationError('Cannot calculate percentage with zero total');
+  }
+  
+  const percentage = (Number(value) * 100) / Number(total);
+  return `${percentage.toFixed(precision)}%`;
+};

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from './validation'
+export * from './precision'
+export * from './formatting'
+export * from './parser'

package/src/utils/parser.ts

@@ -0,0 +1,245 @@
+/**
+ * Parser utilities for Hypernum library
+ * Provides functions for parsing various number formats and notations
+ */
+
+import { ValidationError } from './validation';
+import { RoundingMode } from './precision';
+
+/**
+ * Supported number format types
+ */
+export enum NumberFormat {
+  STANDARD = 'STANDARD',         // Regular decimal notation
+  SCIENTIFIC = 'SCIENTIFIC',     // Scientific notation (e.g., 1.23e4)
+  ENGINEERING = 'ENGINEERING',   // Engineering notation (e.g., 1.23e6)
+  COMPACT = 'COMPACT',          // Compact notation with suffixes (e.g., 1.23M)
+  FRACTION = 'FRACTION',        // Fractional notation (e.g., 1/3)
+  PERCENTAGE = 'PERCENTAGE',    // Percentage notation (e.g., 12.3%)
+  HEXADECIMAL = 'HEXADECIMAL',  // Hex notation (e.g., 0xFF)
+  BINARY = 'BINARY',           // Binary notation (e.g., 0b1010)
+  OCTAL = 'OCTAL'             // Octal notation (e.g., 0o777)
+}
+
+/**
+ * Options for parsing numbers
+ */
+export interface ParseOptions {
+  format?: NumberFormat;
+  base?: number;
+  allowFractions?: boolean;
+  rounding?: RoundingMode;
+  precision?: number;
+  strict?: boolean;
+}
+
+const DEFAULT_PARSE_OPTIONS: Required<ParseOptions> = {
+  format: NumberFormat.STANDARD,
+  base: 10,
+  allowFractions: false,
+  rounding: RoundingMode.HALF_EVEN,
+  precision: 0,
+  strict: true
+};
+
+/**
+ * Parse any supported number format to BigInt
+ */
+export const parseNumber = (input: string, options: ParseOptions = {}): bigint => {
+  const opts: Required<ParseOptions> = { ...DEFAULT_PARSE_OPTIONS, ...options };
+  
+  // Remove whitespace if not in strict mode
+  const str = opts.strict ? input : input.trim();
+  
+  if (str === '') {
+    throw new ValidationError('Empty string cannot be parsed as a number');
+  }
+  
+  try {
+    switch (opts.format) {
+      case NumberFormat.SCIENTIFIC:
+      case NumberFormat.ENGINEERING:
+        return parseScientificNotation(str);
+      case NumberFormat.COMPACT:
+        return parseCompactNotation(str);
+      case NumberFormat.FRACTION:
+        return parseFraction(str, opts.rounding, opts.precision);
+      case NumberFormat.PERCENTAGE:
+        return parsePercentage(str);
+      case NumberFormat.HEXADECIMAL:
+        return parseBaseNotation(str, 16);
+      case NumberFormat.BINARY:
+        return parseBaseNotation(str, 2);
+      case NumberFormat.OCTAL:
+        return parseBaseNotation(str, 8);
+      default:
+        return parseStandardNotation(str);
+    }
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      throw error;
+    }
+    throw new ValidationError(`Failed to parse number: ${input}`);
+  }
+};
+
+/**
+ * Parse standard decimal notation
+ */
+const parseStandardNotation = (str: string): bigint => {
+  // Remove commas and validate format
+  const cleanStr = str.replace(/,/g, '');
+  if (!/^-?\d+$/.test(cleanStr)) {
+    throw new ValidationError('Invalid standard notation format');
+  }
+  
+  return BigInt(cleanStr);
+};
+
+/**
+ * Parse scientific notation (e.g., 1.23e4)
+ */
+const parseScientificNotation = (str: string): bigint => {
+  const match = str.match(/^(-?\d*\.?\d+)e([+-]?\d+)$/i);
+  if (!match) {
+    throw new ValidationError('Invalid scientific notation format');
+  }
+  
+  const [, coefficient, exponent] = match;
+  if (!coefficient) {
+    throw new ValidationError('Invalid scientific notation format');
+  }
+  const [intPart, fracPart = ''] = coefficient.split('.');
+  const normalizedCoef = intPart + fracPart;
+  const adjustedExp = parseInt(exponent || '0') - fracPart.length;
+  
+  if (adjustedExp >= 0) {
+    return BigInt(normalizedCoef) * (BigInt(10) ** BigInt(adjustedExp));
+  } else {
+    return BigInt(normalizedCoef) / (BigInt(10) ** BigInt(-adjustedExp));
+  }
+};
+
+/**
+ * Parse compact notation with suffixes (e.g., 1.23M)
+ */
+const parseCompactNotation = (str: string): bigint => {
+  const match = str.match(/^(-?\d*\.?\d+)\s*([KMBTQ])$/i);
+  if (!match) {
+    throw new ValidationError('Invalid compact notation format');
+  }
+  
+  const [, number, suffix] = match;
+  const value = parseFloat(number || '0');
+  
+  const multipliers = {
+    K: 1000n,
+    M: 1000000n,
+    B: 1000000000n,
+    T: 1000000000000n,
+    Q: 1000000000000000n
+  };
+  
+  if (!suffix) {
+    throw new ValidationError('Invalid compact notation format');
+  }
+  
+  const multiplier = multipliers[suffix.toUpperCase() as keyof typeof multipliers];
+  return BigInt(Math.round(value * Number(multiplier)));
+};
+
+/**
+ * Parse fraction notation (e.g., 1/3)
+ */
+const parseFraction = (
+  str: string,
+  rounding: RoundingMode = RoundingMode.HALF_EVEN,
+  precision: number = 0
+): bigint => {
+  const [numerator, denominator] = str.split('/');
+  if (!numerator || !denominator) {
+    throw new ValidationError('Invalid fraction format');
+  }
+  
+  const num = BigInt(numerator);
+  const den = BigInt(denominator);
+  
+  if (den === 0n) {
+    throw new ValidationError('Division by zero in fraction');
+  }
+  
+  const scale = BigInt(10) ** BigInt(precision);
+  const scaledResult = (num * scale) / den;
+  
+  // Apply rounding if needed
+  if (rounding === RoundingMode.FLOOR) {
+    return scaledResult;
+  } else if (rounding === RoundingMode.CEIL) {
+    return scaledResult + (num * scale % den === 0n ? 0n : 1n);
+  }
+  
+  return scaledResult;
+};
+
+/**
+ * Parse percentage notation (e.g., 12.3%)
+ */
+const parsePercentage = (str: string): bigint => {
+  const match = str.match(/^(-?\d*\.?\d+)%$/);
+  if (!match) {
+    throw new ValidationError('Invalid percentage format');
+  }
+  
+  const value = parseFloat(match[1] || '0');
+  return BigInt(Math.round(value * 100));
+};
+
+/**
+ * Parse number in different bases (binary, octal, hex)
+ */
+const parseBaseNotation = (str: string, base: number): bigint => {
+  let cleanStr = str.toLowerCase();
+  
+  // Remove prefix if present
+  const prefixes: Record<number, string> = {
+    2: '0b',
+    8: '0o',
+    16: '0x'
+  };
+  
+  const prefix = prefixes[base];
+  if (prefix && cleanStr.startsWith(prefix)) {
+    cleanStr = cleanStr.slice(2);
+  }
+  
+  // Validate characters based on base
+  const validChars = {
+    2: /^[01]+$/,
+    8: /^[0-7]+$/,
+    16: /^[0-9a-f]+$/
+  };
+  
+  if (!validChars[base as keyof typeof validChars].test(cleanStr)) {
+    throw new ValidationError(`Invalid ${base}-base number format`);
+  }
+  
+  return BigInt(`0${prefixes[base]}${cleanStr}`);
+};
+
+/**
+ * Detect number format from string
+ */
+export const detectNumberFormat = (str: string): NumberFormat => {
+  const cleanStr = str.trim();
+  
+  if (/^-?\d+$/.test(cleanStr)) return NumberFormat.STANDARD;
+  if (/^-?\d*\.?\d+e[+-]?\d+$/i.test(cleanStr)) return NumberFormat.SCIENTIFIC;
+  if (/^-?\d*\.?\d+[KMBTQ]$/i.test(cleanStr)) return NumberFormat.COMPACT;
+  if (/^-?\d+\/\d+$/.test(cleanStr)) return NumberFormat.FRACTION;
+  if (/^-?\d*\.?\d+%$/.test(cleanStr)) return NumberFormat.PERCENTAGE;
+  if (/^(0x|0X)[0-9a-fA-F]+$/.test(cleanStr)) return NumberFormat.HEXADECIMAL;
+  if (/^(0b|0B)[01]+$/.test(cleanStr)) return NumberFormat.BINARY;
+  if (/^(0o|0O)[0-7]+$/.test(cleanStr)) return NumberFormat.OCTAL;
+  
+  throw new ValidationError('Unable to detect number format');
+};