@obinexusmk2/hypernum 0.1.0

package/src/utils/precision.ts

@@ -0,0 +1,217 @@
+/**
+ * Precision utilities for Hypernum library
+ * Provides functions for handling decimal precision and rounding operations
+ */
+
+import { ValidationError } from './validation';
+
+/**
+ * Rounding modes for decimal operations
+ */
+export enum RoundingMode {
+  FLOOR = 'FLOOR',           // Round towards negative infinity
+  CEIL = 'CEIL',             // Round towards positive infinity
+  DOWN = 'DOWN',             // Round towards zero
+  UP = 'UP',                 // Round away from zero
+  HALF_EVEN = 'HALF_EVEN',   // Round to nearest even number when tied (Banker's rounding)
+  HALF_UP = 'HALF_UP',       // Round up when tied
+  HALF_DOWN = 'HALF_DOWN',   // Round down when tied
+}
+
+/**
+ * Scale a bigint by a power of 10
+ */
+export const scaleByPowerOfTen = (value: bigint, power: number): bigint => {
+  if (power === 0) return value;
+  if (power > 0) {
+    return value * (BigInt(10) ** BigInt(power));
+  }
+  return value / (BigInt(10) ** BigInt(-power));
+};
+
+/**
+ * Round a number according to specified mode and precision
+ */
+export const round = (
+  value: bigint,
+  precision: number = 0,
+  mode: RoundingMode = RoundingMode.HALF_EVEN
+): bigint => {
+  if (precision < 0) {
+    throw new ValidationError('Precision must be non-negative');
+  }
+
+  if (precision === 0) {
+    return value;
+  }
+
+  const scale = BigInt(10) ** BigInt(precision);
+  const scaled = value / scale;
+  const remainder = value % scale;
+
+  switch (mode) {
+    case RoundingMode.FLOOR:
+      return scaled * scale;
+
+    case RoundingMode.CEIL:
+      return remainder > 0n ? (scaled + 1n) * scale : scaled * scale;
+
+    case RoundingMode.DOWN:
+      return value >= 0n ? scaled * scale : (scaled - 1n) * scale;
+
+    case RoundingMode.UP:
+      return value >= 0n ? (scaled + 1n) * scale : scaled * scale;
+
+    case RoundingMode.HALF_UP:
+      return remainder >= scale / 2n ? (scaled + 1n) * scale : scaled * scale;
+
+    case RoundingMode.HALF_DOWN:
+      return remainder > scale / 2n ? (scaled + 1n) * scale : scaled * scale;
+
+    case RoundingMode.HALF_EVEN:
+      if (remainder === scale / 2n) {
+        return scaled % 2n === 0n ? scaled * scale : (scaled + 1n) * scale;
+      }
+      return remainder > scale / 2n ? (scaled + 1n) * scale : scaled * scale;
+
+    default:
+      throw new ValidationError('Invalid rounding mode');
+  }
+};
+
+/**
+ * Calculate precision required to represent a number without loss
+ */
+export const calculateRequiredPrecision = (value: bigint): number => {
+  if (value === 0n) return 0;
+  
+  const str = value.toString();
+  const nonZeroIndex = str.split('').reverse().findIndex(char => char !== '0');
+  return nonZeroIndex === -1 ? 0 : nonZeroIndex;
+};
+
+/**
+ * Normalize two numbers to the same precision
+ */
+export const normalizePrecision = (
+  a: bigint,
+  b: bigint,
+  precisionA: number,
+  precisionB: number
+): [bigint, bigint] => {
+  const targetPrecision = Math.max(precisionA, precisionB);
+  
+  const scaledA = scaleByPowerOfTen(a, targetPrecision - precisionA);
+  const scaledB = scaleByPowerOfTen(b, targetPrecision - precisionB);
+  
+  return [scaledA, scaledB];
+};
+
+/**
+ * Scale a division operation to achieve desired precision
+ */
+export const scaledDivision = (
+  numerator: bigint,
+  denominator: bigint,
+  precision: number,
+  roundingMode: RoundingMode = RoundingMode.HALF_EVEN
+): bigint => {
+  if (denominator === 0n) {
+    throw new ValidationError('Division by zero');
+  }
+
+  if (precision < 0) {
+    throw new ValidationError('Precision must be non-negative');
+  }
+
+  // Scale up numerator to handle desired precision
+  const scaledNumerator = scaleByPowerOfTen(numerator, precision);
+  const quotient = scaledNumerator / denominator;
+  
+  return round(quotient, 0, roundingMode);
+};
+
+/**
+ * Calculate the number of significant digits
+ */
+export const significantDigits = (value: bigint): number => {
+  const nonZeroPattern = /[1-9]/;
+  const str = value.toString();
+  const firstSignificant = str.search(nonZeroPattern);
+  if (firstSignificant === -1) return 0;
+  
+  const lastSignificant = str.split('').reverse().findIndex(char => char !== '0');
+  return str.length - firstSignificant - (lastSignificant === -1 ? 0 : lastSignificant);
+};
+
+/**
+ * Truncate to specified number of significant digits
+ */
+export const truncateToSignificantDigits = (
+  value: bigint,
+  digits: number,
+  roundingMode: RoundingMode = RoundingMode.HALF_EVEN
+): bigint => {
+  if (digits <= 0) {
+    throw new ValidationError('Number of significant digits must be positive');
+  }
+
+  const currentDigits = significantDigits(value);
+  
+  if (currentDigits <= digits) {
+    return value;
+  }
+
+  const scale = currentDigits - digits;
+  return round(value, scale, roundingMode);
+};
+
+/**
+ * Check if two numbers are equal within a specified precision
+ */
+export const equalWithinPrecision = (
+  a: bigint,
+  b: bigint,
+  precision: number
+): boolean => {
+  const diff = a - b;
+  const tolerance = BigInt(10) ** BigInt(precision);
+  return diff.toString().length <= tolerance.toString().length;
+};
+
+/**
+ * Get the fractional part of a number at a given precision
+ */
+export const getFractionalPart = (
+  value: bigint,
+  precision: number
+): bigint => {
+  if (precision <= 0) return 0n;
+  
+  const scale = BigInt(10) ** BigInt(precision);
+  return value % scale;
+};
+
+/**
+ * Format a number with exact precision (no rounding)
+ */
+export const toExactPrecision = (value: bigint, precision: number): string => {
+  if (precision < 0) {
+    throw new ValidationError('Precision must be non-negative');
+  }
+
+  let str = value.toString();
+  const isNegative = str.startsWith('-');
+  if (isNegative) {
+    str = str.slice(1);
+  }
+
+  while (str.length <= precision) {
+    str = '0' + str;
+  }
+
+  const integerPart = str.slice(0, -precision) || '0';
+  const fractionalPart = str.slice(-precision);
+
+  return `${isNegative ? '-' : ''}${integerPart}.${fractionalPart}`;
+};

package/src/utils/validation.ts

@@ -0,0 +1,183 @@
+/**
+ * Validation utilities for Hypernum library
+ * Provides type checking and validation functions for large number operations
+ */
+
+// Custom error types for validation
+export class ValidationError extends Error {
+    constructor(message: string) {
+      super(message);
+      this.name = 'ValidationError';
+    }
+  }
+  
+  export class OverflowError extends Error {
+    constructor(message: string) {
+      super(message);
+      this.name = 'OverflowError';
+    }
+  }
+  
+  // Type guards
+  export const isBigInt = (value: unknown): value is bigint => {
+    return typeof value === 'bigint';
+  };
+  
+  export const isValidNumberString = (value: string): boolean => {
+    return /^-?\d+$/.test(value);
+  };
+  
+  export const isValidNumber = (value: unknown): value is number => {
+    return typeof value === 'number' && !isNaN(value) && isFinite(value);
+  };
+  
+  // Type conversions with validation
+  export const toBigInt = (value: unknown): bigint => {
+    if (isBigInt(value)) {
+      return value;
+    }
+    
+    if (typeof value === 'string') {
+      if (!isValidNumberString(value)) {
+        throw new ValidationError(`Invalid number string: ${value}`);
+      }
+      return BigInt(value);
+    }
+    
+    if (isValidNumber(value)) {
+      if (!Number.isInteger(value)) {
+        throw new ValidationError('Cannot convert non-integer number to BigInt');
+      }
+      return BigInt(value);
+    }
+    
+    throw new ValidationError(`Cannot convert ${typeof value} to BigInt`);
+  };
+  
+  // Range validation
+  export const validateRange = (value: bigint, min?: bigint, max?: bigint): void => {
+    if (min !== undefined && value < min) {
+      throw new ValidationError(`Value ${value} is below minimum ${min}`);
+    }
+    if (max !== undefined && value > max) {
+      throw new ValidationError(`Value ${value} exceeds maximum ${max}`);
+    }
+  };
+  
+  // Operation safety checks
+  export const checkAdditionOverflow = (a: bigint, b: bigint): void => {
+    // Check if addition would overflow
+    if (b > 0 && a > BigInt(Number.MAX_SAFE_INTEGER) - b) {
+      throw new OverflowError('Addition would overflow');
+    }
+    if (b < 0 && a < BigInt(Number.MIN_SAFE_INTEGER) - b) {
+      throw new OverflowError('Addition would underflow');
+    }
+  };
+  
+  export const checkMultiplicationOverflow = (a: bigint, b: bigint): void => {
+    // Check if multiplication would overflow
+    if (a !== BigInt(0) && b !== BigInt(0)) {
+      const maxValue = BigInt(Number.MAX_SAFE_INTEGER);
+      const minValue = BigInt(Number.MIN_SAFE_INTEGER);
+      
+      if (a > maxValue / b || a < minValue / b) {
+        throw new OverflowError('Multiplication would overflow');
+      }
+    }
+  };
+  
+  export const checkPowerOverflow = (base: bigint, exponent: bigint): void => {
+    // Basic overflow checks for exponentiation
+    if (exponent < BigInt(0)) {
+      throw new ValidationError('Negative exponents not supported for integers');
+    }
+    
+    if (base === BigInt(0) && exponent === BigInt(0)) {
+      throw new ValidationError('Zero raised to zero is undefined');
+    }
+    
+    if (exponent > BigInt(1000)) {
+      throw new OverflowError('Exponent too large, computation would overflow');
+    }
+  };
+  
+  // Array and data structure validation
+  export const validateArrayLength = (length: number): void => {
+    if (!Number.isInteger(length) || length < 0) {
+      throw new ValidationError('Array length must be a non-negative integer');
+    }
+    if (length > Number.MAX_SAFE_INTEGER) {
+      throw new ValidationError('Array length exceeds maximum safe integer');
+    }
+  };
+  
+  export const validateArrayIndex = (index: number, length: number): void => {
+    if (!Number.isInteger(index)) {
+      throw new ValidationError('Array index must be an integer');
+    }
+    if (index < 0 || index >= length) {
+      throw new ValidationError('Array index out of bounds');
+    }
+  };
+  
+  // Tree validation
+  export const validateTreeNode = (value: unknown): void => {
+    try {
+      toBigInt(value);
+    } catch (error) {
+      throw new ValidationError('Invalid tree node value');
+    }
+  };
+  
+  // Heap validation
+  export const validateHeapProperty = <T>(
+    value: T,
+    parent: T | undefined,
+    comparator: (a: T, b: T) => -1 | 0 | 1,
+    isMinHeap: boolean
+  ): void => {
+    if (!parent) return;
+    
+    const comparison = comparator(value, parent);
+    if (isMinHeap && comparison < 0) {
+      throw new ValidationError('Min heap property violated');
+    }
+    if (!isMinHeap && comparison > 0) {
+      throw new ValidationError('Max heap property violated');
+    }
+  };
+  
+  // Ackermann function validation
+  export const validateAckermannInput = (m: number, n: number): void => {
+    if (!Number.isInteger(m) || !Number.isInteger(n)) {
+      throw new ValidationError('Ackermann inputs must be integers');
+    }
+    if (m < 0 || n < 0) {
+      throw new ValidationError('Ackermann inputs must be non-negative');
+    }
+    if (m > 4) {
+      throw new ValidationError('First Ackermann parameter too large for computation');
+    }
+  };
+  
+  // General numeric validation utilities
+  export const isInRange = (value: bigint, min: bigint, max: bigint): boolean => {
+    return value >= min && value <= max;
+  };
+  
+  export const isPowerOfTwo = (value: bigint): boolean => {
+    return value > BigInt(0) && (value & (value - BigInt(1))) === BigInt(0);
+  };
+  
+  export const validatePositive = (value: bigint): void => {
+    if (value <= BigInt(0)) {
+      throw new ValidationError('Value must be positive');
+    }
+  };
+  
+  export const validateNonNegative = (value: bigint): void => {
+    if (value < BigInt(0)) {
+      throw new ValidationError('Value must be non-negative');
+    }
+  };

package/tsconfig.json

@@ -0,0 +1,84 @@
+{
+  "compilerOptions": {
+    // Target and Module Settings
+    "target": "es2020",
+    "module": "esnext",
+    "lib": ["es2020", "dom"],
+    "moduleResolution": "node",
+    "types": ["node"],
+    // Module Resolution
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@core/*": ["src/core/*"],
+      "@operations/*": ["src/operations/*"],
+      "@structures/*": ["src/structures/*"],
+      "@utils/*": ["src/utils/*"],
+      "@types/*": ["src/types/*"]
+    },
+    
+    // Strict Type Checking
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "useUnknownInCatchVariables": true,
+    "alwaysStrict": true,
+    
+    // Additional Checks
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    
+    // Module Features
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    
+    // Emit Configuration
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "removeComments": false,
+    "importHelpers": true,
+    
+    // Advanced Options
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "preserveWatchOutput": true,
+    
+    // Experimental Features
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    
+    // JSX (for future web components)
+    "jsx": "preserve"
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/**/*.json"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    "coverage",
+    "jest.config.ts"
+  ],
+  "ts-node": {
+    "compilerOptions": {
+      "module": "CommonJS"
+    }
+  }
+}