@danielsimonjr/mathts-core 0.1.1 → 0.1.3

package/README.md

@@ -11,17 +11,19 @@ npm install @danielsimonjr/mathts-core
 ## Usage
 
 ```typescript
-import { createConfig, isNumeric, isMatrix, VERSION } from '@danielsimonjr/mathts-core';
+import { DEFAULT_CONFIG, isNumber, isMatrix, VERSION } from '@danielsimonjr/mathts-core';
 
-// Create custom configuration
-const config = createConfig({
-  backend: 'wasm',
-  autoBackend: true,
-});
+// Default configuration
+const config = { ...DEFAULT_CONFIG, backend: 'wasm' };
 
 // Type guards
-console.log(isNumeric(42));        // true
-console.log(isMatrix([[1, 2], [3, 4]])); // true
+console.log(isNumber(42)); // true
+console.log(
+  isMatrix([
+    [1, 2],
+    [3, 4],
+  ])
+); // true
 ```
 
 ## API
@@ -34,8 +36,8 @@ console.log(isMatrix([[1, 2], [3, 4]])); // true
 
 ### Functions
 
-- `createConfig(overrides?)` - Create configuration with defaults
-- `isNumeric(value)` - Type guard for numbers
+- `DEFAULT_CONFIG` - Default configuration object
+- `isNumber(value)` - Type guard for numbers
 - `isComplex(value)` - Type guard for complex numbers
 - `isMatrix(value)` - Type guard for matrices
 

package/dist/index.d.ts

@@ -655,6 +655,12 @@ type RoundingMode = 'up' | 'down' | 'ceil' | 'floor' | 'halfUp' | 'halfDown' | '
  */
 declare class BigNumber implements MathTSValue {
     readonly type = "BigNumber";
+    /**
+     * Duck-typing marker for Decimal.js / mathjs formatter compatibility.
+     * Allows external code that checks `obj.isBigNumber === true` to identify
+     * this class without an `instanceof` check.
+     */
+    readonly isBigNumber = true;
     private readonly _sign;
     private readonly _coefficient;
     private readonly _exponent;
@@ -694,13 +700,25 @@ declare class BigNumber implements MathTSValue {
     static compare(a: BigNumber, b: BigNumber): number;
     private static compareMagnitude;
     valueOf(): number;
+    /**
+     * Convert to a JS number.
+     * Alias for `valueOf()` — provided for Decimal.js / mathjs formatter
+     * duck-typing compatibility.
+     */
+    toNumber(): number;
     toString(): string;
     toJSON(): {
         mathjs: string;
         value: string;
     };
     /**
-     * Convert to fixed-point notation
+     * Convert to fixed-point notation.
+     *
+     * When called with no argument (or `undefined`) returns the full fixed-point
+     * string representation without rounding — matching Decimal.js semantics where
+     * `toFixed()` is equivalent to a lossless fixed-point stringify.
+     * When called with a non-negative integer `decimalPlaces`, rounds and formats
+     * to exactly that many digits after the decimal point.
      */
     toFixed(decimalPlaces?: number): string;
     private toFixedInternal;
@@ -724,10 +742,18 @@ declare class BigNumber implements MathTSValue {
      * Subtraction
      */
     subtract(other: Scalar | BigNumber | number | string): BigNumber;
+    /**
+     * Alias for subtract — mathjs / Decimal.js compatibility.
+     */
+    sub(other: Scalar | BigNumber | number | string): BigNumber;
     /**
      * Multiplication
      */
     multiply(other: Scalar | BigNumber | number | string): BigNumber;
+    /**
+     * Alias for multiply — mathjs / Decimal.js compatibility.
+     */
+    mul(other: Scalar | BigNumber | number | string): BigNumber;
     /**
      * Division
      */
@@ -755,6 +781,12 @@ declare class BigNumber implements MathTSValue {
     greaterThanOrEqual(other: BigNumber): boolean;
     compareTo(other: BigNumber): number;
     compare(other: BigNumber): number;
+    /**
+     * Returns true iff this > other.
+     * Accepts the same argument types as `add`/`multiply` (BigNumber, number, or string).
+     * Named `gt` for Decimal.js / mathjs formatter compatibility.
+     */
+    gt(other: BigNumber | number | string): boolean;
     /**
      * Round to specified decimal places
      */
@@ -767,6 +799,29 @@ declare class BigNumber implements MathTSValue {
     floor(): BigNumber;
     ceil(): BigNumber;
     trunc(): BigNumber;
+    /**
+     * Round to `n` significant decimal digits and return a new BigNumber.
+     * Delegates to `roundToPrecision`, using the global rounding mode unless
+     * an explicit `roundingMode` is supplied.
+     *
+     * Named `toSignificantDigits` for Decimal.js / mathjs formatter compatibility.
+     * When `n` is undefined the value is returned unchanged (no rounding).
+     */
+    toSignificantDigits(n?: number, roundingMode?: RoundingMode): BigNumber;
+    /**
+     * The decimal exponent of this number: `floor(log10(|x|))`.
+     *
+     * Matches Decimal.js semantics:
+     *   - `12345` → `4`   (5 digits → the most-significant place is 10^4)
+     *   - `0.0123` → `-2`  (first significant digit is at 10^-2)
+     *   - `100` → `2`
+     *   - `0.01` → `-2`
+     *   - `0` → `0`        (by convention; `isZero()` can be used to distinguish)
+     *
+     * For special values (NaN, ±Infinity) returns 0 — callers check
+     * `isFinite()` / `isNaN()` before using `.e`.
+     */
+    get e(): number;
     /**
      * Modulo (remainder after division)
      * Result has the same sign as the dividend (this).
@@ -906,6 +961,285 @@ declare const BIGNUMBER_E: BigNumber;
 declare const BIGNUMBER_LN2: BigNumber;
 declare const BIGNUMBER_LN10: BigNumber;
 
+/**
+ * Unit definitions for the Unit type.
+ *
+ * The seven SI base units, plus common derived and imperial units. Each
+ * definition stores its multiplicative factor (to base SI) and dimensional
+ * exponents. Temperatures carry an additive offset for the K↔°C↔°F
+ * conversions.
+ *
+ * @module @danielsimonjr/mathts-core/types/unit-definitions
+ */
+/**
+ * The seven SI base dimensions, expressed as a vector of (possibly fractional)
+ * exponents.
+ */
+interface Dimensions {
+    /** Length, base unit metre */
+    length: number;
+    /** Mass, base unit kilogram */
+    mass: number;
+    /** Time, base unit second */
+    time: number;
+    /** Electric current, base unit ampere */
+    current: number;
+    /** Thermodynamic temperature, base unit kelvin */
+    temperature: number;
+    /** Amount of substance, base unit mole */
+    amount: number;
+    /** Luminous intensity, base unit candela */
+    luminosity: number;
+}
+/**
+ * The zero-dimensional vector (a dimensionless quantity).
+ */
+declare const DIMENSIONLESS: Dimensions;
+/**
+ * Construct a Dimensions record from a partial spec.
+ *
+ * Missing fields default to 0, so `dim({ length: 1 })` returns the dimension
+ * vector for length.
+ */
+declare function dim(partial: Partial<Dimensions>): Dimensions;
+/**
+ * Definition of a single named unit.
+ */
+interface UnitDef {
+    /** Multiplicative factor: value-in-base = input * multiplier (+ offset). */
+    multiplier: number;
+    /** Additive offset, used for non-multiplicative units like °C and °F. */
+    offset?: number;
+    /** Dimensional signature. */
+    dimensions: Dimensions;
+    /** Whether SI prefixes (k, M, µ, …) may be applied to this notation. */
+    prefixable?: boolean;
+}
+/**
+ * The seven SI base units.
+ */
+declare const BASE_UNITS: Record<string, UnitDef>;
+/**
+ * Common derived units (SI named units, imperial units, and convenience units).
+ *
+ * This is *not* exhaustive — it covers the most common ~40 units needed for
+ * dimensional-analysis tests. Add more as needed by downstream callers.
+ */
+declare const DERIVED_UNITS: Record<string, UnitDef>;
+/**
+ * Combined registry — both base and derived units in one map.
+ */
+declare const ALL_UNITS: Record<string, UnitDef>;
+/**
+ * Convenience aliases mapping common Unicode/ASCII variants to the canonical
+ * notation key. Used by the parser; not part of the registered notation set.
+ */
+declare const UNIT_ALIASES: Record<string, string>;
+/**
+ * Lookup an exact (non-prefixed) unit definition.
+ */
+declare function getUnitDef(name: string): UnitDef | undefined;
+
+/**
+ * Unit type — dimensional analysis, composition, conversion, and pretty-print.
+ *
+ * A {@link Unit} couples a numeric magnitude to a dimensional signature derived
+ * from a registry of named units (see {@link ./unit-definitions}). Units are
+ * **immutable**: every operation returns a new instance. The canonical
+ * representation always stores the value in SI base units, regardless of how
+ * the unit was constructed — so `new Unit(5, 'km').value === 5000` (metres).
+ * The original notation is preserved on the instance for round-trip display.
+ *
+ * Design notes (intentional differences from mathjs's `Unit` class):
+ * - **Immutable value semantics** instead of mutable JS prototype-class style.
+ * - **No closure over a `math` instance.** Unit is self-contained — no
+ *   dependency on `addScalar`, `format`, `BigNumber`, etc. Values are plain
+ *   JS numbers.
+ * - **`dimensions` is a struct** (a record over the seven SI bases) rather
+ *   than mathjs's array indexed by `BASE_DIMENSIONS`. Cheaper to work with in
+ *   TS, and lets the field be `Readonly<Dimensions>`.
+ * - **Temperature offsets are honoured only for single-temperature-degree
+ *   units** (e.g. `°C` alone, not `°C/s`), matching mathjs but stated
+ *   explicitly here.
+ *
+ * @module @danielsimonjr/mathts-core/types/unit
+ */
+
+/**
+ * Thrown when a unit operation requires matching dimensions but the operands
+ * disagree. Carries the offending dimension vectors for debugging.
+ */
+declare class DimensionMismatchError extends Error {
+    readonly left: Dimensions;
+    readonly right: Dimensions;
+    readonly name = "DimensionMismatchError";
+    constructor(left: Dimensions, right: Dimensions, op: string);
+}
+/** Thrown when a notation string cannot be parsed against the registry. */
+declare class UnitParseError extends Error {
+    readonly name = "UnitParseError";
+    constructor(notation: string, reason: string);
+}
+/**
+ * A physical quantity: a numeric magnitude paired with a dimensional
+ * signature derived from named units.
+ *
+ * Construction examples:
+ * ```ts
+ * new Unit(5, 'm');        // 5 metres
+ * new Unit(3.5, 'km/h');   // 3.5 km/h
+ * new Unit(20, '°C');      // 20 °C
+ * new Unit(1, 'kg·m/s²');  // 1 newton (composed)
+ * ```
+ *
+ * All instances are immutable; every operation returns a new {@link Unit}.
+ * The `value` field is always in SI base units, so:
+ *
+ * ```ts
+ * new Unit(5, 'km').value;  // 5000  (canonical metres)
+ * new Unit(20, '°C').value; // 293.15 (canonical kelvin)
+ * ```
+ */
+declare class Unit {
+    /** Discriminator (matches the prototype-flag convention). */
+    readonly type = "Unit";
+    /** Used by `isUnit()` and typed-function dispatch. */
+    readonly isUnit = true;
+    /** Numeric magnitude in **SI base units**. */
+    readonly value: number;
+    /** Dimensional signature. */
+    readonly dimensions: Readonly<Dimensions>;
+    /** Original notation string, preserved for `toString()` round-trip. */
+    readonly notation: string;
+    /**
+     * Construct a Unit from a numeric value and a notation string.
+     *
+     * The notation is parsed against the registered unit definitions in
+     * {@link ./unit-definitions}. SI prefixes are applied automatically when
+     * the bare notation doesn't match a registered unit. Compound expressions
+     * like `"m/s²"`, `"kg·m/s²"`, and `"1/s"` are supported.
+     *
+     * @throws {UnitParseError} if `notation` cannot be parsed against the
+     *   registered unit definitions.
+     */
+    constructor(value: number, notation: string);
+    /**
+     * Internal construction shortcut from already-canonical fields. **Not
+     * intended for direct use** — most callers should use the `(value,
+     * notation)` form.
+     */
+    constructor(value: number, dimensions: Readonly<Dimensions>, notation: string);
+    /**
+     * Add two units. Requires identical dimensions.
+     *
+     * @throws {DimensionMismatchError} if dimensions differ.
+     */
+    add(other: Unit): Unit;
+    /**
+     * Subtract two units. Requires identical dimensions.
+     *
+     * @throws {DimensionMismatchError} if dimensions differ.
+     */
+    sub(other: Unit): Unit;
+    /**
+     * Multiply by another unit or a scalar. Dimensions add when multiplying by
+     * another unit; unchanged when multiplying by a scalar.
+     */
+    mul(other: Unit | number): Unit;
+    /**
+     * Divide by another unit or a scalar. Dimensions subtract when dividing by
+     * another unit; unchanged when dividing by a scalar.
+     */
+    div(other: Unit | number): Unit;
+    /**
+     * Raise to an integer or rational power. Dimensions scale by `n`.
+     */
+    pow(n: number): Unit;
+    /**
+     * Convert to a target unit. Dimensions must match.
+     *
+     * @throws {DimensionMismatchError} if `targetNotation`'s dimensions differ
+     *   from this unit's.
+     */
+    to(targetNotation: string): Unit;
+    /**
+     * Pick a unit (with SI prefix) that gives a magnitude closest to 1.
+     *
+     * Searches the unit registry for entries matching this unit's dimensions,
+     * then applies each SI prefix in {@link BEST_PREFIXES} to find the
+     * representation minimising `|log10(displayed value)|`.
+     *
+     * If no registered unit matches the dimensions, falls back to a synthetic
+     * notation describing the dimensional vector.
+     */
+    toBest(): Unit;
+    /** True iff dimensions and canonical value are equal. */
+    equals(other: Unit): boolean;
+    /** True iff dimensions match (values may differ). */
+    dimensionsEqual(other: Unit): boolean;
+    /**
+     * Pretty-print. If `notation` is set (the common case), display the value
+     * in that notation — otherwise emit a dimensional signature.
+     */
+    toString(): string;
+    /** JSON-serialisable record. */
+    toJSON(): {
+        mathts: 'Unit';
+        value: number;
+        notation: string;
+    };
+    /**
+     * Rehydrate from a JSON record produced by {@link toJSON}.
+     *
+     * @throws {UnitParseError} if `json.notation` cannot be parsed.
+     */
+    static fromJSON(json: {
+        value: number;
+        notation: string;
+    }): Unit;
+    /**
+     * Parse a full unit expression (with optional leading numeric coefficient).
+     *
+     * Example: `Unit.parse('5 km/h')`.
+     */
+    static parse(input: string): Unit;
+}
+
+/**
+ * Duck-typing guard for {@link Unit}. Mirrors the convention used by
+ * {@link Complex}, {@link Fraction}, and {@link BigNumber}.
+ */
+declare function isUnit$1(value: unknown): value is Unit;
+
+/**
+ * SI prefixes for the Unit type.
+ *
+ * Maps single- and double-letter prefixes to their multiplicative factor in
+ * base units. The full SI prefix range (from y = 1e-24 to Y = 1e24) is
+ * supported, plus the binary prefixes used for digital information units.
+ *
+ * @module @danielsimonjr/mathts-core/types/unit-prefixes
+ */
+/**
+ * Standard SI prefixes (mass/length/energy/etc.).
+ *
+ * Note the ambiguity-resolution priority: longer prefixes (e.g. `da`)
+ * must be tried before single-letter ones (`d`, `a`) in parsers.
+ */
+declare const SI_PREFIXES: Record<string, number>;
+/**
+ * Set of "good" prefixes to use in `toBest()` selection.
+ *
+ * Excludes `h`, `da`, `d`, `c` (commonly only used for centimeters and similar
+ * legacy notations); using these in `toBest()` would produce awkward outputs
+ * like "0.4 hg" instead of "40 g".
+ */
+declare const BEST_PREFIXES: ReadonlyArray<string>;
+/**
+ * Look up an SI prefix multiplier. Returns `undefined` if not a known prefix.
+ */
+declare function getPrefix(name: string): number | undefined;
+
 /**
  * MathTS typed-function Integration
  *
@@ -975,6 +1309,10 @@ declare const isDenseMatrix: (x: unknown) => boolean;
 declare const isSparseMatrix: (x: unknown) => boolean;
 /**
  * Check if value is a Unit
+ *
+ * Recognises both the native {@link Unit} class (which exposes `value`,
+ * `dimensions`, and `notation`) and the legacy duck-typed shape used by
+ * mathjs-compatibility shims (`{ value, unit, type }`).
  */
 declare const isUnit: (x: unknown) => boolean;
 /**
@@ -1233,4 +1571,4 @@ declare const math: {
 
 declare const VERSION = "0.1.0";
 
-export { BIGNUMBER_E, BIGNUMBER_LN10, BIGNUMBER_LN2, BIGNUMBER_NEG_ONE, BIGNUMBER_ONE, BIGNUMBER_PI, BIGNUMBER_TEN, BIGNUMBER_ZERO, type BackendType, BigNumber, type BigNumberConfig, COMPLEX_NEG_ONE, COMPLEX_ONE, COMPLEX_ZERO, Complex, type ConversionDef, DEFAULT_CONFIG, FRACTION_HALF, FRACTION_NEG_ONE, FRACTION_ONE, FRACTION_QUARTER, FRACTION_THIRD, FRACTION_ZERO, type FactoryDependencies, type FactoryFunction, type FactoryImport, Fraction, FunctionRegistry, I, type IBigNumber, type IComplex, type IFraction, type IMatrix, MATHTS_CONVERSIONS, MATHTS_TYPES, type MathTSConfig, type MathTSValue, type MatrixBackend, type MatrixDimensions, type NumericType, type RoundingMode, type Scalar, type TypeDef, TypeRegistry, VERSION, createFactory, createMathTSTyped, createTypedFunction, initTypedWasm, isArray, isBigInt, isBigNumber, isBoolean, isComplex, isDenseMatrix, isFraction, isFunction, isMatrix, isNull, isNumber, isObject, isSparseMatrix, isString, isTypedWasmAvailable, isUndefined, isUnit, math, mathTyped, registerNativeTypes, registry };
+export { ALL_UNITS, BASE_UNITS, BEST_PREFIXES, BIGNUMBER_E, BIGNUMBER_LN10, BIGNUMBER_LN2, BIGNUMBER_NEG_ONE, BIGNUMBER_ONE, BIGNUMBER_PI, BIGNUMBER_TEN, BIGNUMBER_ZERO, type BackendType, BigNumber, type BigNumberConfig, COMPLEX_NEG_ONE, COMPLEX_ONE, COMPLEX_ZERO, Complex, type ConversionDef, DEFAULT_CONFIG, DERIVED_UNITS, DIMENSIONLESS, DimensionMismatchError, type Dimensions, FRACTION_HALF, FRACTION_NEG_ONE, FRACTION_ONE, FRACTION_QUARTER, FRACTION_THIRD, FRACTION_ZERO, type FactoryDependencies, type FactoryFunction, type FactoryImport, Fraction, FunctionRegistry, I, type IBigNumber, type IComplex, type IFraction, type IMatrix, MATHTS_CONVERSIONS, MATHTS_TYPES, type MathTSConfig, type MathTSValue, type MatrixBackend, type MatrixDimensions, type NumericType, type RoundingMode, SI_PREFIXES, type Scalar, type TypeDef, TypeRegistry, UNIT_ALIASES, Unit, type UnitDef, UnitParseError, VERSION, createFactory, createMathTSTyped, createTypedFunction, dim, getPrefix, getUnitDef, initTypedWasm, isArray, isBigInt, isBigNumber, isBoolean, isComplex, isDenseMatrix, isFraction, isFunction, isMatrix, isNull, isNumber, isObject, isSparseMatrix, isString, isTypedWasmAvailable, isUndefined, isUnit, isUnit$1 as isUnitValue, math, mathTyped, registerNativeTypes, registry };