kestrel.markets/dist/frame/format.js

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

/**
 * # frame/format — the shared token-cheap formatting primitives (invents no value)
 *
 * The tiny, PURE display primitives shared by the non-configurable cockpit kernel
 * ({@link ./render.ts}) and the catalog body panes ({@link ./pane-catalog.ts}). Extracted here so
 * BOTH the kernel and the pane catalog format numbers identically — one definition, never a second
 * one that could drift a `—` here from a `—` there.
 *
 * ## The invariant these live inside (ADR-0009)
 * **Invents no value.** An absent/`null`/non-finite value renders as the explicit unknown glyph
 * {@link DASH} (`—`), never a guessed default. Layout (padding widths, fixed precision) is computed;
 * a *value* never is. No wall clock, no RNG — a byte-stable function of the input.
 */
/** The explicit unknown glyph — an absent/`null` value is shown as unknown, never filled in. */
export const DASH = "—";
/** A price/level: integer stays integer, else 2dp. `null`/`undefined` ⇒ `—`. Small numbers by
 * construction (prices, strikes) — never epoch-shaped, keeping the date-blind grep clean. */
export function px(x) {
    if (x === null || x === undefined || !Number.isFinite(x))
        return DASH;
    return Number.isInteger(x) ? String(x) : x.toFixed(2);
}
/** A fixed-precision number (`prec` dp). Non-finite ⇒ `—` (an unknown is shown as unknown). */
export function num(x, prec = 2) {
    if (x === null || x === undefined || !Number.isFinite(x))
        return DASH;
    return x.toFixed(prec);
}
/** Signed dollars, 2dp (`+120.00`, `-45.00`). `null`/`undefined` ⇒ `—`. */
export function money(x) {
    if (x === null || x === undefined || !Number.isFinite(x))
        return DASH;
    return (x >= 0 ? "+" : "") + x.toFixed(2);
}
/** Signed dollars carrying an EXPLICIT `$` (`-$25.97`, `+$392.00`) — the unmistakable-DOLLARS glyph
 * for a running P&L, so a reader can never mistake it for cents (the kestrel-c11 100× mis-scale).
 * `null`/`undefined`/non-finite ⇒ `—` (an unknown P&L is shown as unknown, never a fabricated 0). */
export function usd(x) {
    if (x === null || x === undefined || !Number.isFinite(x))
        return DASH;
    return (x < 0 ? "-$" : "+$") + Math.abs(x).toFixed(2);
}
/** Signed integer with an explicit sign (a signed position qty: `+2`, `-1`). */
export function signedInt(n) {
    return (n >= 0 ? "+" : "") + String(n);
}
/** A position/order/fill leg is EQUITY/SPOT iff it carries NEITHER a strike NOR a right — the ADR-0017
 * spot instrument has neither (an option carries BOTH; a fictional zero-strike is never written). The
 * shared predicate the percept branches on so a spot leg renders as `<instrument> shares` WITHOUT any
 * option chrome (no `<right>@<strike>`, no `fair` column) — a phantom zero-strike CALL (`0C`, `—null`,
 * `—undefined`) is not a real contract and confused a live model (kestrel-orx). One definition, shared
 * by the kernel ({@link ./render.ts}) and the pane catalog ({@link ./pane-catalog.ts}), so the spot/option
 * boundary can never drift between the two surfaces. Mirrors the engine convention (`orgfacts.legKey`,
 * `kernelOf`): BOTH absent ⇒ spot. Invents no value — a pure function of the leg's presence bits. */
export function isSpotLeg(leg) {
    return leg.strike === undefined || leg.right === undefined || leg.strike === null || leg.right === null;
}
/** `T-92m to close` — minutes-to-close, relative only. `null` ⇒ `T-— to close`. */
export function toClose(min) {
    return `T-${min === null || !Number.isFinite(min) ? DASH : String(Math.round(min))}m to close`;
}
/** Right-pad to width (left-aligned text column). */
export function pad(s, w) {
    return s.length >= w ? s : s + " ".repeat(w - s.length);
}