@jarenjs/core 0.9.2 → 0.34.2

package/dist/types/math/float64.d.ts

@@ -5,6 +5,20 @@ export declare const mathf64_sin: (x: number) => number;
 export declare const mathf64_cos: (x: number) => number;
 export declare const mathf64_atan2: (y: number, x: number) => number;
 export declare const mathf64_asin: (x: number) => number;
+export declare const mathf64_tan: (x: number) => number;
+export declare const mathf64_acos: (x: number) => number;
+export declare const mathf64_atan: (x: number) => number;
+export declare const mathf64_sinh: (x: number) => number;
+export declare const mathf64_cosh: (x: number) => number;
+export declare const mathf64_tanh: (x: number) => number;
+export declare const mathf64_cbrt: (x: number) => number;
+export declare const mathf64_log: (x: number) => number;
+export declare const mathf64_log2: (x: number) => number;
+export declare const mathf64_log10: (x: number) => number;
+export declare const mathf64_exp: (x: number) => number;
+export declare const mathf64_expm1: (x: number) => number;
+export declare const mathf64_hypot: (...values: number[]) => number;
+export declare const mathf64_sign: (x: number) => number;
 export declare const mathf64_ceil: (x: number) => number;
 export declare const mathf64_floor: (x: number) => number;
 export declare const mathf64_round: (x: number) => number;
@@ -13,6 +27,10 @@ export declare const mathf64_max: (...values: number[]) => number;
 export declare const mathf64_random: () => number;
 export declare const mathf64_EPSILON = 0.000001;
 export declare const mathf64_SQRTFIVE: number;
+export declare const mathf64_E: number;
+export declare const mathf64_LN2: number;
+export declare const mathf64_LN10: number;
+export declare const mathf64_PHI: number;
 export declare const mathf64_PI: number;
 export declare const mathf64_PI2: number;
 export declare const mathf64_PI1H: number;
@@ -79,8 +97,6 @@ export declare class Float64 {
     static fib(n?: number): number;
     static fib2(value?: number): number;
     static norm(value?: number, min?: number, max?: number): number;
-    static lerp(norm?: number, min?: number, max?: number): number;
-    static map(value?: number, smin?: number, smax?: number, dmin?: number, dmax?: number): number;
     /**
      * Clamps a value between a checked boundary.
      * and can therefor handle swapped min/max arguments
@@ -111,11 +127,118 @@ export declare class Float64 {
     static sinLpEx(r?: number): number;
     static sinLp(r?: number): number;
     static cosLp(r?: number): number;
-    static cosHp(r?: number): void;
+    static cosHp(r?: number): number;
     static sinMpEx(r?: number): number;
     static sinMp(r?: number): number;
     static cosMp(r?: number): number;
     static theta(x?: number, y?: number): number;
     static angle(x?: number, y?: number): number;
     static phi(y?: number, len?: number): number;
+    /**
+     * The base-e logarithm of `x` in an arbitrary base.
+     * @param {number} base
+     * @param {number} x
+     * @returns {number}
+     */
+    static logBase(base?: number, x?: number): number;
+    /**
+     * The sign of `x` (-1, 0 or +1); preserves ±0 and NaN like `Math.sign`.
+     * @param {number} x
+     * @returns {number}
+     */
+    static sign(x?: number): number;
+    /**
+     * The Euclidean length of any number of components, overflow-safe.
+     * @param {...number} args
+     * @returns {number}
+     */
+    static hypot(...args: number[]): number;
+    /**
+     * The real `n`-th root of `x` (odd roots of negatives handled).
+     * @param {number} x
+     * @param {number} n
+     * @returns {number}
+     */
+    static nthroot(x?: number, n?: number): number;
+    /**
+     * Round `value` to `digits` decimal places (banker-free, half-up).
+     * @param {number} value
+     * @param {number} [digits]
+     * @returns {number}
+     */
+    static roundTo(value?: number, digits?: number): number;
+    /**
+     * Round `value` to `digits` significant figures (1–100) — the numeric
+     * value of `Number.prototype.toPrecision`, without its exponential
+     * string formatting.
+     * @param {number} value
+     * @param {number} [digits]
+     * @returns {number}
+     */
+    static roundToPrecision(value?: number, digits?: number): number;
+    /**
+     * The Lanczos approximation of the Gamma function, valid for the whole
+     * real line (poles at non-positive integers return ±Infinity/NaN).
+     * @param {number} x
+     * @returns {number}
+     */
+    static gamma(x?: number): number;
+    /**
+     * The factorial `n!`. Integer `n` uses an exact product; non-integers
+     * are lifted to `gamma(n + 1)`. Negative integers return NaN.
+     * @param {number} n
+     * @returns {number}
+     */
+    static factorial(n?: number): number;
 }
+/**
+ * Linear remap of `v` from the source range `[smin, smax]` to the destination
+ * range `[dmin, dmax]`: `dmin + t·(dmax - dmin)` with
+ * `t = (v - smin)/(smax - smin)`. A degenerate source range collapses to
+ * `dmin` rather than dividing by zero, so a constant-valued axis still maps to
+ * a drawable coordinate. Inverted destination ranges are supported, which is
+ * what screen-space y-flips need.
+ *
+ * @param {number} v
+ * @param {number} smin
+ * @param {number} smax
+ * @param {number} dmin
+ * @param {number} dmax
+ * @returns {number}
+ */
+export declare function remap(v: number, smin: number, smax: number, dmin: number, dmax: number): number;
+/**
+ * The "nice" axis step — 1, 2 or 5 times a power of ten — that covers `span`
+ * in roughly `count` steps, so a tick sequence reads as 0/2/4/6 rather than
+ * 0/1.7/3.4. `count` is floored at 1; pass a pre-divided per-step span and
+ * leave it at its default to get the ladder alone.
+ *
+ * The ladder is pure arithmetic with no domain guard: it is the caller who
+ * knows what a non-positive or non-finite `span` means for its axis, and
+ * different axes answer that differently.
+ *
+ * @param {number} span the domain span to cover
+ * @param {number} [count] desired number of steps (floored at 1)
+ * @returns {number}
+ */
+export declare function niceStep(span: number, count?: number): number;
+/**
+ * Clamp a value into the unit interval `[0, 1]` — the fraction every
+ * unit-space geometry stage emits. `NaN` passes through as `NaN` rather
+ * than collapsing to a boundary, so a non-finite input stays visible to
+ * the caller instead of silently rendering at an edge; callers that want a
+ * drawable coordinate regardless guard with `Number.isFinite` first.
+ *
+ * @param {number} v
+ * @returns {number}
+ */
+export declare function clamp01(v: number): number;
+/**
+ * Geometric mean — the honest average of ratios (a 10× and a 0.1×
+ * average to parity, where an arithmetic mean would claim 5×).
+ * Non-finite and non-positive entries are skipped; `null` when nothing
+ * usable remains.
+ * @param {number[]} values
+ * @returns {number|null}
+ */
+export declare function geoMean(values: number[]): number | null;

package/dist/types/math/format.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @file Number formatting and parsing. The
+ * one place the suite formats a number for display: notation control
+ * (auto/fixed/sci/eng), thousands grouping and radix output, plus a
+ * radix-aware `parseNumber`. Radix I/O delegates to `math/word.js` so
+ * base conversion is never re-implemented.
+ */
+export type FormatOptions = {
+    /**
+     * default 'auto'
+     */
+    notation?: 'auto' | 'fixed' | 'sci' | 'eng';
+    /**
+     * significant/decimal digits (notation-dependent)
+     */
+    precision?: number;
+    /**
+     * thousands separator: true → ',', or a custom string
+     */
+    group?: boolean | string;
+    /**
+     * 2..36; when not 10, `value` is formatted as an integer word
+     */
+    radix?: number;
+    /**
+     * decimal mark, default '.'
+     */
+    decimal?: string;
+};
+/**
+ * Format a number for display.
+ *
+ * `notation: 'auto'` (the default) is NOT a drop-in for a fixed-unit
+ * readout: the auto branch escapes to exponential once
+ * `abs(value) >= 1e21` or `abs(value) < 1e-6`, so
+ * `formatNumber(v, { precision: 3 })` is not interchangeable with a
+ * plain `Number(v.toPrecision(3))`. A caller that appends its own unit
+ * - `"0.0509 ms"` - wants the value never to become `5.09e-5`, and must
+ * either pass `notation: 'fixed'` or keep its own rounder. See
+ * packages/core/docs/MATH.md.
+ * @param {number} value
+ * @param {FormatOptions} [opts]
+ * @returns {string}
+ */
+export declare function formatNumber(value: number, opts?: FormatOptions): string;
+/**
+ * Parse a numeric string, radix-aware. Recognizes `0x`/`0o`/`0b`
+ * prefixes, an explicit `radix` option, grouping separators (`,`/`_`/
+ * space) and base-10 scientific notation. Returns `NaN` on failure
+ * rather than throwing.
+ *
+ * @param {string} str
+ * @param {{ radix?: number }} [opts]
+ * @returns {number}
+ */
+export declare function parseNumber(str: string, opts?: {
+    radix?: number;
+}): number;

package/dist/types/math/index.d.ts

@@ -3,3 +3,8 @@ export * from './vec2i32.js';
 export * from './float64.js';
 export * from './vec2f64.js';
 export * from './vec3f64.js';
+export * from './word.js';
+export * from './solve.js';
+export * from './mat4.js';
+export * from './project.js';
+export * from './format.js';

package/dist/types/math/mat4.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @file A minimal 4×4 matrix kernel for the x·y·z plotter and
+ * any future 3D consumer (Mermaid 3D is a candidate — see ROADMAP).
+ *
+ * Matrices are `Float64Array(16)` in **column-major** order (the WebGL /
+ * glMatrix convention): element `m[col * 4 + row]`. Every factory returns
+ * a fresh array; `multiply` composes right-to-left like linear algebra
+ * (`multiply(a, b)` applies `b` then `a` to a column vector).
+ */
+export type Mat4Array = Float64Array;
+/** @typedef {Float64Array} Mat4Array */
+export declare class Mat4 {
+    /** @returns {Mat4Array} the 4×4 identity. */
+    static identity(): Mat4Array;
+    /**
+     * `a · b` (column-major). Neither operand is mutated.
+     * @param {Mat4Array} a @param {Mat4Array} b
+     * @returns {Mat4Array}
+     */
+    static multiply(a: Mat4Array, b: Mat4Array): Mat4Array;
+    /** @param {number} rad @returns {Mat4Array} */
+    static rotationX(rad: number): Mat4Array;
+    /** @param {number} rad @returns {Mat4Array} */
+    static rotationY(rad: number): Mat4Array;
+    /** @param {number} rad @returns {Mat4Array} */
+    static rotationZ(rad: number): Mat4Array;
+    /** @param {number} tx @param {number} ty @param {number} tz @returns {Mat4Array} */
+    static translation(tx: number, ty: number, tz: number): Mat4Array;
+    /** @param {number} sx @param {number} sy @param {number} sz @returns {Mat4Array} */
+    static scaling(sx: number, sy: number, sz: number): Mat4Array;
+    /**
+     * Orthographic projection.
+     * @param {number} l @param {number} r @param {number} b @param {number} t
+     * @param {number} n @param {number} f
+     * @returns {Mat4Array}
+     */
+    static ortho(l: number, r: number, b: number, t: number, n: number, f: number): Mat4Array;
+    /**
+     * Perspective projection (right-handed, clip space z in [-1, 1]).
+     * @param {number} fovy vertical field of view, radians
+     * @param {number} aspect width / height
+     * @param {number} n near plane (> 0)
+     * @param {number} f far plane
+     * @returns {Mat4Array}
+     */
+    static perspective(fovy: number, aspect: number, n: number, f: number): Mat4Array;
+    /**
+     * Transform a 3D point (implicit w = 1) by `m`, returning the
+     * perspective-divided `{ x, y, z, w }` (w is the pre-divide clip w, so
+     * callers can reject points behind the camera).
+     * @param {Mat4Array} m @param {number} x @param {number} y @param {number} z
+     * @returns {{ x: number, y: number, z: number, w: number }}
+     */
+    static transformPoint(m: Mat4Array, x: number, y: number, z: number): {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+}

package/dist/types/math/project.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file 3D → 2D projection helpers, built on `Mat4` and the
+ * existing `Vec3f64`. Used by the x·y·z plotter to turn a rotated grid
+ * of surface points into screen coordinates and to shade faces.
+ */
+export type Viewport = {
+    /**
+     * left edge in pixels
+     */
+    x: number;
+    /**
+     * top edge in pixels
+     */
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * @typedef {object} Viewport
+ * @property {number} x left edge in pixels
+ * @property {number} y top edge in pixels
+ * @property {number} width
+ * @property {number} height
+ */
+/**
+ * Project a 3D point through `mat` (model·view·projection) and map the
+ * resulting normalized device coordinates into `viewport` pixels. The Y
+ * axis is flipped so that +Y is up in world space but down in screen
+ * space, as SVG expects.
+ *
+ * @param {{ x: number, y: number, z: number } | import('./vec3f64.js').Vec3f64} point3
+ * @param {import('./mat4.js').Mat4Array} mat
+ * @param {Viewport} viewport
+ * @returns {{ x: number, y: number, z: number, w: number }}
+ */
+export declare function project3dTo2d(point3: {
+    x: number;
+    y: number;
+    z: number;
+} | import('./vec3f64.js').Vec3f64, mat: import('./mat4.js').Mat4Array, viewport: Viewport): {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+};
+/**
+ * The (un-normalized) surface normal of triangle `a→b→c`, right-hand
+ * winding. Returns a `Vec3f64`.
+ * @param {import('./vec3f64.js').Vec3f64} a
+ * @param {import('./vec3f64.js').Vec3f64} b
+ * @param {import('./vec3f64.js').Vec3f64} c
+ * @returns {import('./vec3f64.js').Vec3f64}
+ */
+export declare function surfaceNormal(a: import('./vec3f64.js').Vec3f64, b: import('./vec3f64.js').Vec3f64, c: import('./vec3f64.js').Vec3f64): import('./vec3f64.js').Vec3f64;

package/dist/types/math/solve.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file Generic, domain-free numeric root finders. No finance
+ * or geometry lives here; `@jarenjs/core/finance` builds NPV/IRR/rate on
+ * top of these, the calculator's equation helpers on top of them too.
+ *
+ * Each solver returns a `{ root, iterations, converged }` record instead
+ * of throwing on non-convergence — callers decide how to react (finance
+ * falls back from Newton to bisection, for example).
+ */
+export type SolveResult = {
+    /**
+     * the best estimate found
+     */
+    root: number;
+    /**
+     * iterations actually run
+     */
+    iterations: number;
+    /**
+     * whether `tol` was reached
+     */
+    converged: boolean;
+};
+/**
+ * Newton–Raphson using an explicit derivative. Falls back to reporting
+ * non-convergence (rather than diverging silently) when the derivative
+ * vanishes or the step explodes.
+ *
+ * @param {(x: number) => number} f
+ * @param {(x: number) => number} df
+ * @param {number} x0
+ * @param {{ tol?: number, maxIter?: number }} [opts]
+ * @returns {SolveResult}
+ */
+export declare function newtonRaphson(f: (x: number) => number, df: (x: number) => number, x0: number, opts?: {
+    tol?: number;
+    maxIter?: number;
+}): SolveResult;
+/**
+ * Bisection on a sign-changing bracket `[a, b]`. Guaranteed to converge
+ * when `f(a)` and `f(b)` straddle a root; returns `converged: false` if
+ * the bracket does not (rather than throwing).
+ *
+ * @param {(x: number) => number} f
+ * @param {number} a
+ * @param {number} b
+ * @param {{ tol?: number, maxIter?: number }} [opts]
+ * @returns {SolveResult}
+ */
+export declare function bisect(f: (x: number) => number, a: number, b: number, opts?: {
+    tol?: number;
+    maxIter?: number;
+}): SolveResult;
+/**
+ * The secant method (Newton without an explicit derivative). Needs two
+ * starting points.
+ *
+ * @param {(x: number) => number} f
+ * @param {number} x0
+ * @param {number} x1
+ * @param {{ tol?: number, maxIter?: number }} [opts]
+ * @returns {SolveResult}
+ */
+export declare function secant(f: (x: number) => number, x0: number, x1: number, opts?: {
+    tol?: number;
+    maxIter?: number;
+}): SolveResult;

package/dist/types/math/word.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file BigInt fixed-width word math. The programmer-calculator
+ * kernel: two's-complement integers of a fixed bit width (8/16/32/64),
+ * signed or unsigned, with the bitwise/shift/rotate operators and
+ * radix-string I/O a HEX/DEC/OCT/BIN calculator needs.
+ *
+ * Everything is native `BigInt` — zero dependencies, exact at any width.
+ * Values crossing the module boundary are plain `BigInt`s already reduced
+ * to the requested word (mask + sign-extend), so operators compose
+ * without re-normalizing.
+ */
+/** Supported word sizes, in bits. */
+export declare const WORD_BITS: readonly number[];
+/**
+ * The unsigned mask for a word of `bits` bits: `2**bits - 1`.
+ * @param {number} bits
+ * @returns {bigint}
+ */
+export declare function wordMask(bits: number): bigint;
+/**
+ * Reduce any integer to a fixed-width word. Unsigned words wrap into
+ * `[0, 2**bits)`; signed words are the two's-complement interpretation,
+ * so the high bit becomes the sign and the result lands in
+ * `[-2**(bits-1), 2**(bits-1))`.
+ *
+ * @param {bigint|number|string} value
+ * @param {number} [bits]
+ * @param {boolean} [signed]
+ * @returns {bigint}
+ */
+export declare function toWord(value: bigint | number | string, bits?: number, signed?: boolean): bigint;
+/** @param {bigint} a @param {bigint} b @param {number} [bits] @param {boolean} [signed] */
+export declare function wAnd(a: bigint, b: bigint, bits?: number, signed?: boolean): bigint;
+/** @param {bigint} a @param {bigint} b @param {number} [bits] @param {boolean} [signed] */
+export declare function wOr(a: bigint, b: bigint, bits?: number, signed?: boolean): bigint;
+/** @param {bigint} a @param {bigint} b @param {number} [bits] @param {boolean} [signed] */
+export declare function wXor(a: bigint, b: bigint, bits?: number, signed?: boolean): bigint;
+/** @param {bigint} a @param {number} [bits] @param {boolean} [signed] */
+export declare function wNot(a: bigint, bits?: number, signed?: boolean): bigint;
+/** @param {bigint} a @param {bigint} n @param {number} [bits] @param {boolean} [signed] */
+export declare function wShl(a: bigint, n: bigint, bits?: number, signed?: boolean): bigint;
+/**
+ * Logical right shift (zero fill) over the unsigned representation, then
+ * reinterpreted per `signed`.
+ * @param {bigint} a @param {bigint} n @param {number} [bits] @param {boolean} [signed]
+ */
+export declare function wShr(a: bigint, n: bigint, bits?: number, signed?: boolean): bigint;
+/** Rotate left. @param {bigint} a @param {bigint} n @param {number} [bits] @param {boolean} [signed] */
+export declare function wRol(a: bigint, n: bigint, bits?: number, signed?: boolean): bigint;
+/** Rotate right. @param {bigint} a @param {bigint} n @param {number} [bits] @param {boolean} [signed] */
+export declare function wRor(a: bigint, n: bigint, bits?: number, signed?: boolean): bigint;
+/**
+ * Euclidean-flavoured modulo that follows the sign of the divisor,
+ * reduced back into the word.
+ * @param {bigint} a @param {bigint} b @param {number} [bits] @param {boolean} [signed]
+ */
+export declare function wMod(a: bigint, b: bigint, bits?: number, signed?: boolean): bigint;
+/**
+ * Format an integer as a radix string (no prefix). Groups digits with an
+ * optional separator and left-pads to `pad` digits.
+ *
+ * @param {bigint|number} int
+ * @param {number} [radix] 2..36
+ * @param {{ group?: number, sep?: string, pad?: number, upper?: boolean }} [opts]
+ * @returns {string}
+ */
+export declare function toBase(int: bigint | number, radix?: number, opts?: {
+    group?: number;
+    sep?: string;
+    pad?: number;
+    upper?: boolean;
+}): string;
+/**
+ * Parse a radix string back to a BigInt. Tolerates group separators
+ * (space/underscore), a leading sign, and an optional `0x`/`0o`/`0b`
+ * prefix (which must agree with `radix` when both are given).
+ *
+ * @param {string} str
+ * @param {number} [radix] 2..36
+ * @returns {bigint}
+ */
+export declare function fromBase(str: string, radix?: number): bigint;

package/dist/types/message.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Human-message templating: the shared half of every message catalog in
+ * the suite.
+ *
+ * A catalog is a plain flat object keyed by a stable message id, whose
+ * entries are either render closures or template strings. Compiling one
+ * turns every template string into a closure, so the consumer only ever
+ * calls `catalog[msgid](params)` — the two-stage house rule applied to
+ * messages: parse the template once, render many times.
+ *
+ * This lives in `@jarenjs/core` so that packages which must not depend on
+ * each other can still speak the identical catalog contract. That is what
+ * lets one locale pack service both the validator's document voice ("must
+ * have required property 'x'") and the form layer's field voice ("This
+ * field is required") without either package importing the other.
+ */
+/**
+ * Render one interpolated parameter: `String(v)` for primitives,
+ * `JSON.stringify(v)` for objects and arrays.
+ *
+ * @param {unknown} value - The parameter value
+ * @returns {string} The rendered value
+ */
+export declare function formatTemplateParam(value: unknown): string;
+/**
+ * Render a JSON value for quotation inside a message: strings keep their
+ * quotes so an empty or space-padded value is visible, everything else is
+ * JSON.
+ *
+ * @param {unknown} value - The value to render
+ * @returns {string}
+ */
+export declare function formatMessageValue(value: unknown): string;
+/**
+ * Compile a message template into a render closure. Template syntax:
+ * `{name}` substitutes the params member `name`; an unknown name leaves
+ * the placeholder literally (so a catalog typo shows up in the output
+ * instead of rendering as `undefined`); `{{` escapes a literal `{`.
+ *
+ * @param {string} template - The template text
+ * @returns {(params: object, error?: object) => string} The compiled render closure
+ */
+export declare function compileMessageTemplate(template: string): (params: object, error?: object) => string;
+/**
+ * Compile a catalog-like object into a functions-only frozen catalog.
+ * Entries may be render closures (kept as-is) or template strings
+ * (compiled through {@link compileMessageTemplate}).
+ *
+ * @param {Record<string, string | ((params: object, error?: object) => string)>} catalogLike - The catalog to compile
+ * @returns {Readonly<Record<string, (params: object, error?: object) => string>>} The compiled catalog
+ */
+export declare function compileMessageCatalog(catalogLike: Record<string, string | ((params: object, error?: object) => string)>): Readonly<Record<string, (params: object, error?: object) => string>>;