@0xmonaco/core 1.1.5-develop.129b2c6 → 1.1.5

package/dist/api/websocket/local-book.js

@@ -1,423 +0,0 @@
-/**
- * Local depth book and BBO state for the market-data `depth` / `bbo`
- * WebSocket channels (0XM-3551).
- *
- * Handoff rules (the server enforces them; the client checks defensively):
- * - A Snapshot replaces the local state, including mid-stream.
- * - A frame with `book_seq <=` the current sequence is stale or a duplicate
- *   and is dropped.
- * - Every kept frame must have `prev_book_seq <=` the current sequence (the
- *   snapshot's for the first frame, else the last applied frame's): a delta
- *   restates every level changed since its link, so it may link below the
- *   previous frame. A frame that links above it means a lost frame: rebuild
- *   from a new snapshot.
- * - A BBO frame carries the whole top of book, so any frame newer than the
- *   state applies without a link check.
- * - Frames that arrive before the snapshot are buffered and replayed through
- *   the same rules once it lands.
- * - On a side whose snapshot was not complete, levels beyond its deepest
- *   returned level are unknown, so the book keeps only levels at or better
- *   than that boundary.
- *
- * Sequences are u64 durable-log positions, held as decimal strings and
- * compared as `BigInt`.
- */
-/** Frames buffered before a snapshot; past it the oldest are dropped (the link check catches the hole). */
-const MAX_BUFFERED_FRAMES = 10_000;
-const SEQUENCE_KEYS = ["book_seq", "prev_book_seq"];
-// A whole integer only: a fractional or exponent value is left as it is, so
-// `JSON.parse` still reads it and the lenient readers leave it unset.
-const SEQUENCE_KEY_PATTERN = new RegExp(`"(${SEQUENCE_KEYS.join("|")})"\\s*:\\s*(\\d+)(?![\\d.eE])`, "g");
-/**
- * Quote the market-data sequence numbers in a raw frame before `JSON.parse`,
- * so a u64 above `Number.MAX_SAFE_INTEGER` survives exactly. Only the
- * unescaped `"book_seq":` / `"prev_book_seq":` keys followed by an integer are
- * touched; inside a JSON string those quotes would be escaped.
- */
-export function quoteSequenceNumbers(raw) {
-    if (!raw.includes("book_seq"))
-        return raw;
-    return raw.replace(SEQUENCE_KEY_PATTERN, '"$1":"$2"');
-}
-function asRecord(value, what) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error(`Invalid ${what}: must be an object`);
-    }
-    return value;
-}
-/** A u64 sequence as a decimal string: a quoted integer, or a JSON number that is still exact. */
-function readSequence(data, key) {
-    const sequence = tryReadSequence(data, key);
-    if (sequence === undefined)
-        throw new Error(`Invalid ${key}: must be a non-negative integer`);
-    return sequence;
-}
-/**
- * {@link readSequence} that leaves an absent or malformed value `undefined`
- * instead of throwing. A JSON number counts only while it is still exact (a
- * quoted integer always does), so a rounded u64 never passes for a precise one.
- */
-export function tryReadSequence(data, key) {
-    const value = data[key];
-    if (typeof value === "string" && /^\d+$/.test(value))
-        return value;
-    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
-        return String(value);
-    return undefined;
-}
-function readString(data, key) {
-    const value = data[key];
-    if (typeof value !== "string")
-        throw new Error(`Invalid ${key}: must be a string`);
-    return value;
-}
-/*
- * Value fields parse leniently (packages/core/AGENTS.md: an over-strict value
- * check drops the whole frame, and here a dropped frame costs a rebuild):
- * numbers and numeric strings are interchangeable, an absent flag takes its
- * safe default. Identity and sequence fields stay strict.
- */
-/**
- * A non-negative number as plain decimal digits: `String(1e-7)` is exponent
- * notation, which the decimal compare cannot order, so the exponent is
- * expanded into the digits (the number's shortest round-trip form).
- */
-function plainDecimal(value) {
-    const text = String(value);
-    const match = /^(\d+)(?:\.(\d+))?e([+-]\d+)$/i.exec(text);
-    if (!match)
-        return text;
-    const [, whole = "0", fraction = "", exponentText = "0"] = match;
-    const digits = whole + fraction;
-    const point = whole.length + Number(exponentText);
-    if (point <= 0)
-        return `0.${"0".repeat(-point)}${digits}`.replace(/\.?0+$/, "") || "0";
-    if (point >= digits.length)
-        return digits + "0".repeat(point - digits.length);
-    return `${digits.slice(0, point)}.${digits.slice(point)}`;
-}
-/** A decimal value as a string: a string as sent, a finite number as plain digits. */
-function readDecimal(data, key) {
-    const value = data[key];
-    if (typeof value === "string")
-        return value;
-    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
-        return plainDecimal(value);
-    throw new Error(`Invalid ${key}: must be a decimal`);
-}
-function readNullableDecimal(data, key) {
-    const value = data[key];
-    if (value === null || value === undefined)
-        return null;
-    return readDecimal(data, key);
-}
-/** A boolean, or `fallback` when absent or not a boolean. */
-function readFlag(data, key, fallback) {
-    const value = data[key];
-    return typeof value === "boolean" ? value : fallback;
-}
-/** A number, or a numeric string; `fallback` otherwise. */
-function readLenientNumber(data, key, fallback) {
-    const value = data[key];
-    const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
-    return Number.isFinite(parsed) ? parsed : fallback;
-}
-/** A level's order count: a number or numeric string, required (it decides removals). */
-function readOrderCount(level) {
-    const parsed = readLenientNumber(level, "order_count", Number.NaN);
-    if (!Number.isFinite(parsed) || parsed < 0)
-        throw new Error("Invalid order_count: must be a non-negative number");
-    return Math.trunc(parsed);
-}
-function readLevels(data, key) {
-    const value = data[key];
-    if (value === undefined || value === null)
-        return [];
-    if (!Array.isArray(value))
-        throw new Error(`Invalid ${key}: must be an array`);
-    return value.map((raw) => {
-        const level = asRecord(raw, `${key} level`);
-        return {
-            price: readDecimal(level, "price"),
-            quantity: readDecimal(level, "quantity"),
-            orderCount: readOrderCount(level),
-        };
-    });
-}
-export function parseDepthSnapshot(raw) {
-    const data = asRecord(raw, "depth snapshot");
-    return {
-        tradingPairId: readString(data, "trading_pair_id"),
-        tradingMode: readString(data, "trading_mode"),
-        bookSeq: readSequence(data, "book_seq"),
-        bids: readLevels(data, "bids"),
-        asks: readLevels(data, "asks"),
-        // Absent means unknown: treat the side as incomplete (the safe reading).
-        bidsComplete: readFlag(data, "bids_complete", false),
-        asksComplete: readFlag(data, "asks_complete", false),
-    };
-}
-export function parseDepthDelta(raw) {
-    const data = asRecord(raw, "depth frame");
-    return {
-        tradingPairId: readString(data, "trading_pair_id"),
-        tradingMode: readString(data, "trading_mode"),
-        bookSeq: readSequence(data, "book_seq"),
-        prevBookSeq: readSequence(data, "prev_book_seq"),
-        timestampMs: readLenientNumber(data, "timestamp_ms", 0),
-        bids: readLevels(data, "bids"),
-        asks: readLevels(data, "asks"),
-        stale: readFlag(data, "stale", false),
-    };
-}
-export function parseBboSnapshot(raw) {
-    const data = asRecord(raw, "bbo snapshot");
-    return {
-        tradingPairId: readString(data, "trading_pair_id"),
-        tradingMode: readString(data, "trading_mode"),
-        bookSeq: readSequence(data, "book_seq"),
-        bestBid: readNullableDecimal(data, "best_bid"),
-        bidQty: readNullableDecimal(data, "bid_qty"),
-        bestAsk: readNullableDecimal(data, "best_ask"),
-        askQty: readNullableDecimal(data, "ask_qty"),
-    };
-}
-export function parseBboEvent(raw) {
-    const data = asRecord(raw, "bbo frame");
-    return {
-        ...parseBboSnapshot(data),
-        prevBookSeq: readSequence(data, "prev_book_seq"),
-        timestampMs: readLenientNumber(data, "timestamp_ms", 0),
-        stale: readFlag(data, "stale", false),
-    };
-}
-/** Canonical form of a decimal price, so "64250.50" and "64250.5" are one level. */
-function priceKey(price) {
-    const trimmed = price.trim();
-    const [integer = "0", fraction = ""] = trimmed.split(".");
-    const int = integer.replace(/^0+(?=\d)/, "") || "0";
-    const frac = fraction.replace(/0+$/, "");
-    return frac ? `${int}.${frac}` : int;
-}
-/** Compare two canonical (`priceKey`) non-negative decimals numerically. */
-function compareCanonical(a, b) {
-    const [ai = "0", af = ""] = a.split(".");
-    const [bi = "0", bf = ""] = b.split(".");
-    if (ai.length !== bi.length)
-        return ai.length - bi.length;
-    if (ai !== bi)
-        return ai < bi ? -1 : 1;
-    const width = Math.max(af.length, bf.length);
-    const ap = af.padEnd(width, "0");
-    const bp = bf.padEnd(width, "0");
-    if (ap === bp)
-        return 0;
-    return ap < bp ? -1 : 1;
-}
-/** Compare two non-negative decimal strings numerically. */
-export function compareDecimal(a, b) {
-    return compareCanonical(priceKey(a), priceKey(b));
-}
-/** A zero quantity, or zero orders, removes the level (the server sends both together). */
-function isRemoval(level) {
-    return level.orderCount === 0 || compareDecimal(level.quantity, "0") === 0;
-}
-/**
- * An incomplete side is refreshed once its known levels fall below this
- * fraction of what its snapshot held: deltas never bring back the levels
- * beyond its boundary, so a thinned side would otherwise understate the book.
- */
-const THIN_SIDE_FRACTION = 0.5;
-/** The deepest a side is kept, matching the server's book mirror and snapshots. */
-const MAX_LEVELS_PER_SIDE = 1000;
-/** One side of the book: levels keyed by canonical price, with an optional boundary. */
-class BookSide {
-    bestFirst;
-    levels = new Map();
-    /** Canonical price of the deepest known level on an incomplete side; levels beyond it are unknown. */
-    boundary = null;
-    /** Whether the side's snapshot was incomplete. */
-    incomplete = false;
-    /** Known levels below which an incomplete side needs a fresh snapshot. */
-    thinBelow = 0;
-    /** Whether every level of the side is known. */
-    get complete() {
-        return !this.incomplete;
-    }
-    /** `bestFirst` orders canonical prices best first (negative when `a` is better). */
-    constructor(bestFirst) {
-        this.bestFirst = bestFirst;
-    }
-    reset(levels, complete) {
-        this.levels.clear();
-        for (const level of levels) {
-            if (!isRemoval(level))
-                this.levels.set(priceKey(level.price), level);
-        }
-        this.incomplete = !complete;
-        const known = [...this.levels.keys()].sort(this.bestFirst);
-        this.boundary = complete ? null : (known.at(-1) ?? null);
-        this.thinBelow = complete ? 0 : Math.max(1, Math.ceil(known.length * THIN_SIDE_FRACTION));
-    }
-    apply(levels) {
-        for (const level of levels) {
-            const key = priceKey(level.price);
-            // Beyond the boundary of an incomplete side nothing is known.
-            if (this.boundary !== null && this.bestFirst(key, this.boundary) > 0)
-                continue;
-            if (isRemoval(level)) {
-                this.levels.delete(key);
-            }
-            else {
-                this.levels.set(key, level);
-            }
-        }
-        // Like the server's mirror, keep at most MAX_LEVELS_PER_SIDE after each
-        // frame: the worst levels go, and the side becomes incomplete at the new
-        // deepest level.
-        if (this.levels.size > MAX_LEVELS_PER_SIDE) {
-            const kept = [...this.levels.keys()].sort(this.bestFirst);
-            for (const key of kept.slice(MAX_LEVELS_PER_SIDE))
-                this.levels.delete(key);
-            this.boundary = kept[MAX_LEVELS_PER_SIDE - 1] ?? null;
-            if (!this.incomplete) {
-                this.incomplete = true;
-                this.thinBelow = Math.ceil(MAX_LEVELS_PER_SIDE * THIN_SIDE_FRACTION);
-            }
-        }
-    }
-    /**
-     * An incomplete side that has thinned below its refresh threshold (or came
-     * back with no level at all): what lies beyond its boundary is unknown and
-     * may now be near the top, so it needs a fresh snapshot.
-     */
-    exhausted() {
-        return this.incomplete && this.levels.size < this.thinBelow;
-    }
-    /** The side, best first, sorted once on the canonical keys. */
-    view() {
-        return [...this.levels.entries()].sort(([a], [b]) => this.bestFirst(a, b)).map(([, level]) => level);
-    }
-}
-/**
- * The sequence guard shared by `depth` and `bbo`: snapshot replaces, stale
- * frames drop, a frame linking above the current sequence is a gap, frames
- * before the snapshot buffer.
- */
-class SequencedState {
-    current = null;
-    buffered = [];
-    /**
-     * Whether a frame must link to the current state. Depth deltas carry only
-     * changed levels, so a frame past a lost one is a gap; a BBO frame carries
-     * the whole top of book, so any newer one is complete on its own.
-     */
-    checksLinks = true;
-    /** Whether a snapshot has been applied since the last reset. */
-    get ready() {
-        return this.current !== null;
-    }
-    /** Whether the state can no longer be trusted past its known levels (see `"truncated"`). */
-    truncated() {
-        return false;
-    }
-    /** Replace the state with `snapshot`, then replay buffered frames. Returns `"gap"` if a buffered frame does not link. */
-    applySnapshot(snapshot) {
-        this.resetFrom(snapshot);
-        this.current = BigInt(snapshot.bookSeq);
-        const pending = this.buffered;
-        this.buffered = [];
-        for (const frame of pending) {
-            const outcome = this.offer(frame);
-            if (outcome === "gap" || outcome === "truncated")
-                return outcome;
-        }
-        // An incomplete side that came back with no level is unusable as sent.
-        return this.truncated() ? "truncated" : "applied";
-    }
-    /** Offer a live frame. */
-    offer(frame) {
-        if (this.current === null) {
-            this.buffered.push(frame);
-            if (this.buffered.length > MAX_BUFFERED_FRAMES)
-                this.buffered.shift();
-            return "buffered";
-        }
-        const seq = BigInt(frame.bookSeq);
-        if (seq <= this.current)
-            return "dropped";
-        if (this.checksLinks && BigInt(frame.prevBookSeq) > this.current)
-            return "gap";
-        this.applyFrame(frame);
-        this.current = seq;
-        return this.truncated() ? "truncated" : "applied";
-    }
-    /** Discard everything; the next snapshot starts over. */
-    reset() {
-        this.current = null;
-        this.buffered = [];
-    }
-}
-/** The local depth book for one `depth` channel. */
-export class LocalDepthBook extends SequencedState {
-    bids = new BookSide((a, b) => compareCanonical(b, a));
-    asks = new BookSide((a, b) => compareCanonical(a, b));
-    header = null;
-    resetFrom(snapshot) {
-        this.bids.reset(snapshot.bids, snapshot.bidsComplete);
-        this.asks.reset(snapshot.asks, snapshot.asksComplete);
-        this.header = {
-            tradingPairId: snapshot.tradingPairId,
-            tradingMode: snapshot.tradingMode,
-            bookSeq: snapshot.bookSeq,
-            bidsComplete: snapshot.bidsComplete,
-            asksComplete: snapshot.asksComplete,
-            stale: false,
-        };
-    }
-    applyFrame(frame) {
-        this.bids.apply(frame.bids);
-        this.asks.apply(frame.asks);
-        if (this.header) {
-            this.header = { ...this.header, bookSeq: frame.bookSeq, stale: frame.stale, timestampMs: frame.timestampMs };
-        }
-    }
-    truncated() {
-        return this.bids.exhausted() || this.asks.exhausted();
-    }
-    reset() {
-        super.reset();
-        this.header = null;
-    }
-    /** The current book, or `null` before a snapshot. */
-    view() {
-        if (!this.ready || !this.header)
-            return null;
-        return {
-            ...this.header,
-            bids: this.bids.view(),
-            asks: this.asks.view(),
-            bidsComplete: this.bids.complete,
-            asksComplete: this.asks.complete,
-        };
-    }
-}
-/** The local top of book for one `bbo` channel. */
-export class LocalBbo extends SequencedState {
-    checksLinks = false;
-    state = null;
-    resetFrom(snapshot) {
-        this.state = { ...snapshot, stale: false };
-    }
-    applyFrame(frame) {
-        const { prevBookSeq: _prev, ...rest } = frame;
-        this.state = { ...rest };
-    }
-    reset() {
-        super.reset();
-        this.state = null;
-    }
-    view() {
-        return this.ready && this.state ? { ...this.state } : null;
-    }
-}