@basic-math/core

Core utilities and type system for the basic-math library, providing branded types for type-safe number validation.

Installation

npm install @basic-math/core

Features

• SafeNumber Branded Type: Compile-time and runtime type safety
• toSafeNumber(): Runtime validation function
• Custom Error Types: TypeViolationError and NumericInvariantError
• Zero Dependencies: Pure TypeScript utilities

Usage

SafeNumber Type

import { SafeNumber, toSafeNumber } from '@basic-math/core';

// Runtime validation
const num: SafeNumber = toSafeNumber(42); // OK
const invalid = toSafeNumber(NaN);        // Throws TypeViolationError

// Type safety at compile time
function process(value: SafeNumber) {
  // value is guaranteed to be a valid number
  return value * 2;
}

process(toSafeNumber(10)); // OK
process(123);              // TypeScript error

Error Handling

import { toSafeNumber, TypeViolationError, NumericInvariantError } from '@basic-math/core';

try {
  const num = toSafeNumber(NaN);
} catch (error) {
  if (error instanceof TypeViolationError) {
    console.log('Invalid number type');
  }
}

API

SafeNumber

A branded type ensuring the value is a valid number (not NaN or Infinity).

toSafeNumber(value: number): SafeNumber

Validates and converts a number to SafeNumber.

Throws:

• TypeViolationError - If value is NaN
• NumericInvariantError - If value is Infinity or -Infinity

Error Types

• TypeViolationError: Thrown when type constraints are violated
• NumericInvariantError: Thrown when numeric invariants are violated

License

MIT