@danielsimonjr/mathts-core 0.3.1 → 0.4.1

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { U as Unit, a as UnitInstance, i as isUnitValue } from './index-DpOizJsa.js';
 import { TypedInstance, ReferTo, ReferToSelf, TypedFunction, SignatureFunction } from 'typed-function';
 export { ReferTo, ReferToSelf, SignatureFunction, TypedFunction, TypedInstance, create, default as typed } from 'typed-function';
 
@@ -416,19 +417,6 @@ declare const COMPLEX_ZERO: Complex;
 declare const COMPLEX_ONE: Complex;
 declare const COMPLEX_NEG_ONE: Complex;
 
-/**
- * Dual number for forward-mode automatic differentiation.
- *
- * A dual number `a + b·ε` (with ε² = 0) carries a value and its first
- * derivative. Evaluating a function built from the overloaded elementary
- * operations on `Dual.variable(x)` propagates the derivative automatically:
- *
- *   derivative(x => multiply(sin(x), x), 2)
- *     // sin(2)·1 + 2·cos(2)  — exact, no finite differences
- *
- * The derivative rules live here as methods so the typed-function signatures in
- * the `functions` package are one-liners (e.g. `Dual: (a) => a.sin()`).
- */
 declare class Dual {
     /** Function value (the real part). */
     readonly value: number;
@@ -448,6 +436,7 @@ declare class Dual {
     powConst(k: number): Dual;
     /** General power a^b: d = a^b·(b'·ln a + b·a'/a). */
     pow(o: Dual): Dual;
+    private unary;
     sin(): Dual;
     cos(): Dual;
     tan(): Dual;
@@ -464,6 +453,135 @@ declare class Dual {
 /** Type guard for {@link Dual}. */
 declare function isDual(x: unknown): x is Dual;
 
+/**
+ * Canonical elementary-function derivative rules for forward-mode automatic
+ * differentiation. This is the single source of truth for the chain rules,
+ * shared by the scalar {@link Dual} (core) and the tensor `DualTensor`
+ * (autograd) so neither reinvents them.
+ *
+ * Each rule is a pair of pure `number → number` functions:
+ *   - `primal(x)` — f(x)
+ *   - `deriv(x, y)` — f′(x), given both x and the already-computed y = f(x),
+ *     so output-reusing derivatives (exp, tanh, sqrt, cbrt, expm1) stay cheap.
+ *
+ * Keeping these as plain scalar functions (no `Dual`/`Tensor` allocation) is
+ * what lets autograd's `Float64Array` element-wise loop stay allocation-free.
+ * It is also the propagation path: a future accelerated `primal` in the
+ * standard layer (WASM/SIMD batch kernels) can be swapped in here and every
+ * consumer inherits the speedup without touching this contract.
+ */
+/** A forward-mode derivative rule for a unary elementary function. */
+interface DualUnaryRule {
+    /** f(x). */
+    readonly primal: (x: number) => number;
+    /** f′(x), given x and y = f(x) (y lets exp/tanh/sqrt/… avoid recomputation). */
+    readonly deriv: (x: number, y: number) => number;
+}
+/**
+ * The canonical table. Derivatives are stated in the cheapest exact form
+ * (reusing y where that avoids a redundant transcendental call).
+ */
+declare const DUAL_UNARY_RULES: {
+    exp: {
+        primal: (x: number) => number;
+        deriv: (_x: number, y: number) => number;
+    };
+    expm1: {
+        primal: (x: number) => number;
+        deriv: (_x: number, y: number) => number;
+    };
+    log: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    log2: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    log10: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    log1p: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    sin: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    cos: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    tan: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    asin: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    acos: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    atan: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    sinh: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    cosh: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    tanh: {
+        primal: (x: number) => number;
+        deriv: (_x: number, y: number) => number;
+    };
+    asinh: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    acosh: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    atanh: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    sqrt: {
+        primal: (x: number) => number;
+        deriv: (_x: number, y: number) => number;
+    };
+    cbrt: {
+        primal: (x: number) => number;
+        deriv: (_x: number, y: number) => number;
+    };
+    square: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    reciprocal: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    abs: {
+        primal: (x: number) => number;
+        deriv: (x: number) => number;
+    };
+    sign: {
+        primal: (x: number) => number;
+        deriv: () => number;
+    };
+};
+/** Name of a rule in {@link DUAL_UNARY_RULES}. */
+type DualUnaryRuleName = keyof typeof DUAL_UNARY_RULES;
+
 /**
  * Named mathematical constants (plain `number`).
  *
@@ -512,7 +630,7 @@ declare class Fraction implements IFraction {
     readonly type = "Fraction";
     readonly numerator: bigint;
     readonly denominator: bigint;
-    constructor(numerator: bigint | number | string, denominator?: bigint | number | string);
+    constructor(numerator: bigint | number | string | Fraction, denominator?: bigint | number | string | Fraction);
     /**
      * Create a Fraction from a number (with optional precision)
      */
@@ -861,10 +979,18 @@ declare class BigNumber implements MathTSValue {
      * Alias for multiply — mathjs / Decimal.js compatibility.
      */
     mul(other: Scalar | BigNumber | number | string): BigNumber;
+    /**
+     * Alias for multiply — Decimal.js calling convention (used by the Unit).
+     */
+    times(other: Scalar | BigNumber | number | string): BigNumber;
     /**
      * Division
      */
     divide(other: Scalar | BigNumber | number | string): BigNumber;
+    /**
+     * Alias for divide — Decimal.js calling convention (used by the Unit).
+     */
+    div(other: Scalar | BigNumber | number | string): BigNumber;
     /**
      * Negation
      */
@@ -1068,6 +1194,77 @@ declare const BIGNUMBER_E: BigNumber;
 declare const BIGNUMBER_LN2: BigNumber;
 declare const BIGNUMBER_LN10: BigNumber;
 
+/** Any scalar core can do arithmetic on. */
+type NumericScalar = number | bigint | Complex | Fraction | BigNumber;
+/** Add two scalar values, `x + y`. */
+declare function addScalar(x: NumericScalar, y: NumericScalar): NumericScalar;
+/** Subtract two scalar values, `x − y` (order preserved through promotion). */
+declare function subtractScalar(x: NumericScalar, y: NumericScalar): NumericScalar;
+/** Multiply two scalar values, `x · y`. */
+declare function multiplyScalar(x: NumericScalar, y: NumericScalar): NumericScalar;
+/** Divide two scalar values, `x ÷ y` (order preserved through promotion). */
+declare function divideScalar(x: NumericScalar, y: NumericScalar): NumericScalar;
+/**
+ * Raise `base` to the power `exp`, treating `exp` as a real exponent.
+ *
+ * The exact `.pow()` of an exact type (Fraction/BigNumber) only supports INTEGER
+ * exponents. A non-integer exponent of an exact base is generally irrational, so
+ * it cannot stay exact — those cases fall back to double-precision `Math.pow`,
+ * returning a plain `number`. (Without this guard, `BigNumber.pow(0.5)` silently
+ * returned 1 and `Fraction.pow(0.5)` threw `BigInt(0.5)`.)
+ */
+declare function pow(base: NumericScalar, exp: NumericScalar): NumericScalar;
+/** Absolute value. `abs(Complex)` returns the magnitude (a real number). */
+declare function abs(x: NumericScalar): NumericScalar;
+/** Round toward zero (truncate). Complex components are truncated independently. */
+declare function fix(x: NumericScalar): NumericScalar;
+/**
+ * Round to the nearest integer, half toward +∞ — matching `Math.round` and
+ * `Fraction.round`. `BigNumber.round` defaults to half-away-from-zero, so it is
+ * given `'halfCeil'` explicitly; otherwise negative half-integers would round
+ * type-dependently (`round(-2.5)` = −2 for number/Fraction but −3 for BigNumber).
+ * Complex components are rounded independently.
+ */
+declare function round(x: NumericScalar): NumericScalar;
+/**
+ * Equality. Floating-point operands compare with the configured tolerance
+ * (`relTol`/`absTol`); exact types (Fraction, BigNumber) compare exactly —
+ * tolerance is meaningless for an exact rational/decimal.
+ */
+declare function equal(x: NumericScalar, y: NumericScalar, relTol?: number, absTol?: number): boolean;
+/**
+ * True for values math treats as real-numeric: `number`, `bigint`, `boolean`,
+ * `Fraction`, `BigNumber`. Mirrors mathjs semantics — `boolean` counts (it
+ * coerces to 0/1), while `Complex` is intentionally NOT numeric (callers test it
+ * separately), so `isNumeric(complex)` is `false`. The relocated Unit uses this as
+ * its value-type gate (`isNumeric(value) || isComplex(value)`), and mathjs accepts
+ * `new Unit(true)` — so booleans must pass.
+ */
+declare function isNumeric(x: unknown): boolean;
+/**
+ * Convert any scalar to a plain JS `number`. A non-real `Complex` (nonzero
+ * imaginary part) has no real-number value and throws.
+ */
+declare function number(x: NumericScalar): number;
+
+/**
+ * Typed error classes for the Unit. Kept in their own module (with no Unit
+ * imports) so both the merged `Unit` (`Unit.ts`) and the `core/src/types/unit.ts`
+ * compatibility surface can import them without a circular dependency, and so
+ * callers can `catch (e) { if (e instanceof UnitParseError) … }` as before the
+ * two Unit implementations merged.
+ */
+/** Thrown when a unit notation string cannot be parsed against the registry. */
+declare class UnitParseError extends Error {
+    readonly name = "UnitParseError";
+    constructor(message: string);
+}
+/** Thrown when an operation requires two units to share a base dimension and they do not. */
+declare class DimensionMismatchError extends Error {
+    readonly name = "DimensionMismatchError";
+    constructor(message: string);
+}
+
 /**
  * Unit definitions for the Unit type.
  *
@@ -1147,177 +1344,6 @@ declare const UNIT_ALIASES: Record<string, string>;
  */
 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.
  *
@@ -1713,4 +1739,4 @@ declare const math: {
 
 declare const VERSION = "0.1.0";
 
-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, Dual, E, 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, LN10, LN2, LOG10E, LOG2E, MATHTS_CONVERSIONS, MATHTS_TYPES, type MathTSConfig, type MathTSValue, type MatrixBackend, type MatrixDimensions, type NumericType, PHI, PI, type RoundingMode, SI_PREFIXES, SQRT1_2, SQRT2, type Scalar, TAU, type TypeDef, TypeRegistry, UNIT_ALIASES, Unit, type UnitDef, UnitParseError, VERSION, createFactory, createMathTSTyped, createTypedFunction, dim, getPrefix, getUnitDef, initTypedWasm, isArray, isBigInt, isBigNumber, isBoolean, isComplex, isDenseMatrix, isDual, isFraction, isFunction, isMatrix, isNull, isNumber, isObject, isSparseMatrix, isString, isTypedWasmAvailable, isUndefined, isUnit, isUnit$1 as isUnitValue, 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, DUAL_UNARY_RULES, DimensionMismatchError, type Dimensions, Dual, type DualUnaryRule, type DualUnaryRuleName, E, 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, LN10, LN2, LOG10E, LOG2E, MATHTS_CONVERSIONS, MATHTS_TYPES, type MathTSConfig, type MathTSValue, type MatrixBackend, type MatrixDimensions, type NumericScalar, type NumericType, PHI, PI, type RoundingMode, SI_PREFIXES, SQRT1_2, SQRT2, type Scalar, TAU, type TypeDef, TypeRegistry, UNIT_ALIASES, type UnitDef, UnitParseError, VERSION, abs, addScalar, createFactory, createMathTSTyped, createTypedFunction, dim, divideScalar, equal, fix, getPrefix, getUnitDef, initTypedWasm, isArray, isBigInt, isBigNumber, isBoolean, isComplex, isDenseMatrix, isDual, isFraction, isFunction, isMatrix, isNull, isNumber, isNumeric, isObject, isSparseMatrix, isString, isTypedWasmAvailable, isUndefined, isUnit, math, mathTyped, multiplyScalar, number, pow, registerNativeTypes, registry, round, subtractScalar };