@symmio/trading-core 1.1.0 → 2.0.0

package/dist/orderbook/sources/binance/fetch-binance-symbol-filters.js

@@ -0,0 +1,39 @@
+import { SymmApiError as e, SymmError as t } from "../../../shared/errors/symm-error.js";
+import { countTickDecimals as n } from "../../tick-size.js";
+import { BINANCE_ORDERBOOK_EXCHANGE_INFO_PATH as r } from "./constants.js";
+import i, { isAxiosError as a } from "axios";
+//#region src/orderbook/sources/binance/fetch-binance-symbol-filters.ts
+function o(e, t) {
+	if (!e) return t;
+	let n = Number(e);
+	return Number.isFinite(n) && n > 0 ? n : t;
+}
+function s(e) {
+	let t = e.filters?.find((e) => e.filterType === "PRICE_FILTER"), r = e.filters?.find((e) => e.filterType === "LOT_SIZE"), i = o(t?.tickSize, 10 ** -(e.pricePrecision ?? 2)), a = o(r?.stepSize, 10 ** -(e.quantityPrecision ?? 3));
+	return {
+		symbol: e.symbol,
+		baseAsset: e.baseAsset ?? "",
+		quoteAsset: e.quoteAsset ?? "",
+		tickSize: i,
+		stepSize: a,
+		pricePrecision: n(i),
+		sizePrecision: n(a)
+	};
+}
+async function c(n, o, c) {
+	let l = `${n}${r[o]}`;
+	try {
+		let e = (await i.get(l, { signal: c })).data?.symbols;
+		if (!Array.isArray(e)) throw new t("api", "FETCH_BINANCE_SYMBOL_FILTERS_FAILED", "Binance exchangeInfo response had no `symbols` array.");
+		return new Map(e.map((e) => [e.symbol.toUpperCase(), s(e)]));
+	} catch (r) {
+		throw r instanceof t ? r : a(r) ? e.fromAxios(r, {
+			code: "FETCH_BINANCE_SYMBOL_FILTERS_FAILED",
+			baseURL: n
+		}) : new t("api", "FETCH_BINANCE_SYMBOL_FILTERS_FAILED", `Failed to fetch Binance exchangeInfo: ${r instanceof Error ? r.message : String(r)}`, { cause: r instanceof Error ? r : void 0 });
+	}
+}
+//#endregion
+export { c as fetchBinanceSymbolFilters };
+
+//# sourceMappingURL=fetch-binance-symbol-filters.js.map

package/dist/orderbook/sources/binance/fetch-binance-symbol-filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-binance-symbol-filters.js","names":[],"sources":["../../../../src/orderbook/sources/binance/fetch-binance-symbol-filters.ts"],"sourcesContent":["import axios, { isAxiosError } from \"axios\";\nimport { SymmApiError, SymmError } from \"../../../shared/errors/symm-error\";\nimport { countTickDecimals } from \"../../tick-size\";\nimport { BINANCE_ORDERBOOK_EXCHANGE_INFO_PATH, type BinanceOrderbookMarket } from \"./constants\";\n\n/**\n * The subset of a Binance `exchangeInfo` symbol entry an order book reads.\n */\ninterface RawBinanceExchangeInfoSymbol {\n  symbol: string;\n  baseAsset?: string;\n  quoteAsset?: string;\n  /** Present on USD-M futures; absent on spot, where precision comes from the filters. */\n  pricePrecision?: number;\n  /** Present on USD-M futures; absent on spot. */\n  quantityPrecision?: number;\n  filters?: { filterType?: string; tickSize?: string; stepSize?: string }[];\n}\n\n/**\n * Trading increments and precisions for one Binance symbol.\n *\n * `tickSize` and `stepSize` are what the venue actually enforces; the two\n * precisions are derived from them so a UI's decimal count can never disagree\n * with the grid the venue quotes on.\n */\nexport interface BinanceSymbolFilters {\n  /** Binance symbol, upper-case. */\n  symbol: string;\n  /** Base asset (e.g. `\"BTC\"`). */\n  baseAsset: string;\n  /** Quote asset (e.g. `\"USDT\"`). */\n  quoteAsset: string;\n  /** Smallest price increment the venue allows. */\n  tickSize: number;\n  /** Smallest quantity increment the venue allows. */\n  stepSize: number;\n  /** Decimal places implied by {@link BinanceSymbolFilters.tickSize}. */\n  pricePrecision: number;\n  /** Decimal places implied by {@link BinanceSymbolFilters.stepSize}. */\n  sizePrecision: number;\n}\n\nfunction toIncrement(value: string | undefined, fallback: number): number {\n  if (!value) return fallback;\n  const parsed = Number(value);\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;\n}\n\nfunction toSymbolFilters(entry: RawBinanceExchangeInfoSymbol): BinanceSymbolFilters {\n  const priceFilter = entry.filters?.find((filter) => filter.filterType === \"PRICE_FILTER\");\n  const lotSize = entry.filters?.find((filter) => filter.filterType === \"LOT_SIZE\");\n\n  /**\n   * The filters are authoritative — they are the increments an order is\n   * rejected for violating. The futures-only `pricePrecision`/`quantityPrecision`\n   * fields are a fallback, and a final default covers a venue that reports\n   * neither.\n   */\n  const tickSize = toIncrement(priceFilter?.tickSize, 10 ** -(entry.pricePrecision ?? 2));\n  const stepSize = toIncrement(lotSize?.stepSize, 10 ** -(entry.quantityPrecision ?? 3));\n\n  return {\n    symbol: entry.symbol,\n    baseAsset: entry.baseAsset ?? \"\",\n    quoteAsset: entry.quoteAsset ?? \"\",\n    tickSize,\n    stepSize,\n    pricePrecision: countTickDecimals(tickSize),\n    sizePrecision: countTickDecimals(stepSize),\n  };\n}\n\n/**\n * Fetch Binance `exchangeInfo` and index each symbol's increments by symbol.\n *\n * Called once per source instance and cached — the response lists every\n * contract on the venue and only changes on a listing or delisting.\n *\n * @param restUrl - REST host, without a trailing slash.\n * @param market - Which Binance market to describe.\n * @param signal - Aborts the request.\n * @returns Increments and precisions keyed by upper-case Binance symbol.\n * @throws {SymmApiError} when the request fails with an HTTP response.\n * @throws {SymmError} when the response has no `symbols` array.\n */\nexport async function fetchBinanceSymbolFilters(\n  restUrl: string,\n  market: BinanceOrderbookMarket,\n  signal?: AbortSignal,\n): Promise<Map<string, BinanceSymbolFilters>> {\n  const url = `${restUrl}${BINANCE_ORDERBOOK_EXCHANGE_INFO_PATH[market]}`;\n\n  try {\n    const response = await axios.get<{ symbols?: RawBinanceExchangeInfoSymbol[] }>(url, { signal });\n    const symbols = response.data?.symbols;\n\n    if (!Array.isArray(symbols)) {\n      throw new SymmError(\n        \"api\",\n        \"FETCH_BINANCE_SYMBOL_FILTERS_FAILED\",\n        \"Binance exchangeInfo response had no `symbols` array.\",\n      );\n    }\n\n    return new Map(symbols.map((entry) => [entry.symbol.toUpperCase(), toSymbolFilters(entry)]));\n  } catch (err) {\n    if (err instanceof SymmError) throw err;\n\n    if (isAxiosError(err)) {\n      throw SymmApiError.fromAxios(err, { code: \"FETCH_BINANCE_SYMBOL_FILTERS_FAILED\", baseURL: restUrl });\n    }\n\n    throw new SymmError(\n      \"api\",\n      \"FETCH_BINANCE_SYMBOL_FILTERS_FAILED\",\n      `Failed to fetch Binance exchangeInfo: ${err instanceof Error ? err.message : String(err)}`,\n      { cause: err instanceof Error ? err : undefined },\n    );\n  }\n}\n"],"mappings":";;;;;AA2CA,SAAS,EAAY,GAA2B,GAA0B;CACxE,IAAI,CAAC,GAAO,OAAO;CACnB,IAAM,IAAS,OAAO,CAAK;CAC3B,OAAO,OAAO,SAAS,CAAM,KAAK,IAAS,IAAI,IAAS;AAC1D;AAEA,SAAS,EAAgB,GAA2D;CAClF,IAAM,IAAc,EAAM,SAAS,MAAM,MAAW,EAAO,eAAe,cAAc,GAClF,IAAU,EAAM,SAAS,MAAM,MAAW,EAAO,eAAe,UAAU,GAQ1E,IAAW,EAAY,GAAa,UAAU,MAAM,EAAE,EAAM,kBAAkB,EAAE,GAChF,IAAW,EAAY,GAAS,UAAU,MAAM,EAAE,EAAM,qBAAqB,EAAE;CAErF,OAAO;EACL,QAAQ,EAAM;EACd,WAAW,EAAM,aAAa;EAC9B,YAAY,EAAM,cAAc;EAChC;EACA;EACA,gBAAgB,EAAkB,CAAQ;EAC1C,eAAe,EAAkB,CAAQ;CAC3C;AACF;AAeA,eAAsB,EACpB,GACA,GACA,GAC4C;CAC5C,IAAM,IAAM,GAAG,IAAU,EAAqC;CAE9D,IAAI;EAEF,IAAM,KAAU,MADO,EAAM,IAAkD,GAAK,EAAE,UAAO,CAAC,GACrE,MAAM;EAE/B,IAAI,CAAC,MAAM,QAAQ,CAAO,GACxB,MAAM,IAAI,EACR,OACA,uCACA,uDACF;EAGF,OAAO,IAAI,IAAI,EAAQ,KAAK,MAAU,CAAC,EAAM,OAAO,YAAY,GAAG,EAAgB,CAAK,CAAC,CAAC,CAAC;CAC7F,SAAS,GAAK;EAOZ,MANI,aAAe,IAAiB,IAEhC,EAAa,CAAG,IACZ,EAAa,UAAU,GAAK;GAAE,MAAM;GAAuC,SAAS;EAAQ,CAAC,IAG/F,IAAI,EACR,OACA,uCACA,yCAAyC,aAAe,QAAQ,EAAI,UAAU,OAAO,CAAG,KACxF,EAAE,OAAO,aAAe,QAAQ,IAAM,KAAA,EAAU,CAClD;CACF;AACF"}

package/dist/orderbook/sources/binance/index.d.ts

@@ -0,0 +1,7 @@
+export * from './constants.js';
+export * from './create-binance-orderbook-source.js';
+export * from './fetch-binance-depth.js';
+export * from './fetch-binance-symbol-filters.js';
+export * from './parse-depth.js';
+export * from './watch-binance-depth.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/orderbook/sources/binance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/orderbook/sources/binance/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mCAAmC,CAAC;AAClD,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC"}

package/dist/orderbook/sources/binance/parse-depth.d.ts

@@ -0,0 +1,70 @@
+import { OrderbookLevel } from '../../types.js';
+/**
+ * A price level as Binance sends it: a `[price, quantity]` pair of decimal
+ * strings, in both the REST snapshot and the diff stream.
+ */
+export type RawBinanceDepthLevel = [price: string, quantity: string];
+/**
+ * The REST depth snapshot.
+ *
+ * `E` and `T` are futures-only; spot returns neither.
+ */
+export interface RawBinanceDepthSnapshot {
+    /** Sequence number the snapshot is current as of. */
+    lastUpdateId: number;
+    /** Event time, unix ms. Futures only. */
+    E?: number;
+    /** Transaction time, unix ms. Futures only. */
+    T?: number;
+    bids: RawBinanceDepthLevel[];
+    asks: RawBinanceDepthLevel[];
+}
+/**
+ * A `depthUpdate` event from the diff stream.
+ *
+ * `pu` is futures-only and is the continuity signal there: it carries the
+ * previous event's `u`. Spot has no `pu` and chains on `U === prev.u + 1`
+ * instead — a rule that does **not** hold on futures, where `U` routinely jumps
+ * hundreds of ids past the previous `u`.
+ */
+export interface RawBinanceDepthEvent {
+    /** Event type; always `"depthUpdate"`. */
+    e?: string;
+    /** Event time, unix ms. */
+    E?: number;
+    /** Transaction time, unix ms. Futures only. */
+    T?: number;
+    /** Symbol, upper-case. */
+    s?: string;
+    /** First update id covered by this event. */
+    U: number;
+    /** Final update id covered by this event. */
+    u: number;
+    /** Final update id of the *previous* event. Futures only. */
+    pu?: number;
+    /** Bid levels to apply. */
+    b?: RawBinanceDepthLevel[];
+    /** Ask levels to apply. */
+    a?: RawBinanceDepthLevel[];
+}
+/**
+ * Convert one raw `[price, quantity]` pair into an {@link OrderbookLevel}.
+ *
+ * Zero-quantity entries are kept rather than filtered: in the diff stream a
+ * zero is the venue's instruction to **remove** that price, and dropping it
+ * here would leave the level resting forever.
+ *
+ * @param level - One entry from a `bids`/`asks` array.
+ * @returns The parsed level.
+ * @throws {SymmError} when the pair is malformed or non-numeric.
+ */
+export declare function parseBinanceDepthLevel(level: RawBinanceDepthLevel): OrderbookLevel;
+/**
+ * Convert an array of raw levels, preserving order and zero-quantity entries.
+ *
+ * @param levels - A `bids` or `asks` array from a snapshot or diff event.
+ * @returns The parsed levels.
+ * @throws {SymmError} when the payload is not an array of valid pairs.
+ */
+export declare function parseBinanceDepthLevels(levels: RawBinanceDepthLevel[] | undefined): OrderbookLevel[];
+//# sourceMappingURL=parse-depth.d.ts.map

package/dist/orderbook/sources/binance/parse-depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-depth.d.ts","sourceRoot":"","sources":["../../../../src/orderbook/sources/binance/parse-depth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,oBAAoB,EAAE,CAAC;IAC7B,IAAI,EAAE,oBAAoB,EAAE,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,6CAA6C;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,6DAA6D;IAC7D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2BAA2B;IAC3B,CAAC,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAC3B,2BAA2B;IAC3B,CAAC,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAC5B;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,cAAc,CAalF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,SAAS,GAAG,cAAc,EAAE,CAYpG"}

package/dist/orderbook/sources/binance/parse-depth.js

@@ -0,0 +1,23 @@
+import { SymmError as e } from "../../../shared/errors/symm-error.js";
+//#region src/orderbook/sources/binance/parse-depth.ts
+function t(t, n) {
+	let r = Number(t);
+	if (!Number.isFinite(r)) throw new e("api", "INVALID_BINANCE_DEPTH", `Binance depth has a non-numeric \`${n}\`: ${t}.`);
+	return r;
+}
+function n(n) {
+	if (!Array.isArray(n) || n.length < 2) throw new e("api", "INVALID_BINANCE_DEPTH", `Binance depth level is not a [price, quantity] pair: ${JSON.stringify(n)}.`);
+	return {
+		price: t(n[0], "price"),
+		size: t(n[1], "quantity")
+	};
+}
+function r(t) {
+	if (t === void 0) return [];
+	if (!Array.isArray(t)) throw new e("api", "INVALID_BINANCE_DEPTH", `Binance depth side is not an array: ${JSON.stringify(t)}.`);
+	return t.map(n);
+}
+//#endregion
+export { n as parseBinanceDepthLevel, r as parseBinanceDepthLevels };
+
+//# sourceMappingURL=parse-depth.js.map

package/dist/orderbook/sources/binance/parse-depth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-depth.js","names":[],"sources":["../../../../src/orderbook/sources/binance/parse-depth.ts"],"sourcesContent":["import { SymmError } from \"../../../shared/errors/symm-error\";\nimport type { OrderbookLevel } from \"../../types\";\n\n/**\n * A price level as Binance sends it: a `[price, quantity]` pair of decimal\n * strings, in both the REST snapshot and the diff stream.\n */\nexport type RawBinanceDepthLevel = [price: string, quantity: string];\n\n/**\n * The REST depth snapshot.\n *\n * `E` and `T` are futures-only; spot returns neither.\n */\nexport interface RawBinanceDepthSnapshot {\n  /** Sequence number the snapshot is current as of. */\n  lastUpdateId: number;\n  /** Event time, unix ms. Futures only. */\n  E?: number;\n  /** Transaction time, unix ms. Futures only. */\n  T?: number;\n  bids: RawBinanceDepthLevel[];\n  asks: RawBinanceDepthLevel[];\n}\n\n/**\n * A `depthUpdate` event from the diff stream.\n *\n * `pu` is futures-only and is the continuity signal there: it carries the\n * previous event's `u`. Spot has no `pu` and chains on `U === prev.u + 1`\n * instead — a rule that does **not** hold on futures, where `U` routinely jumps\n * hundreds of ids past the previous `u`.\n */\nexport interface RawBinanceDepthEvent {\n  /** Event type; always `\"depthUpdate\"`. */\n  e?: string;\n  /** Event time, unix ms. */\n  E?: number;\n  /** Transaction time, unix ms. Futures only. */\n  T?: number;\n  /** Symbol, upper-case. */\n  s?: string;\n  /** First update id covered by this event. */\n  U: number;\n  /** Final update id covered by this event. */\n  u: number;\n  /** Final update id of the *previous* event. Futures only. */\n  pu?: number;\n  /** Bid levels to apply. */\n  b?: RawBinanceDepthLevel[];\n  /** Ask levels to apply. */\n  a?: RawBinanceDepthLevel[];\n}\n\nfunction toFiniteNumber(value: unknown, field: string): number {\n  const parsed = Number(value);\n  if (!Number.isFinite(parsed)) {\n    throw new SymmError(\"api\", \"INVALID_BINANCE_DEPTH\", `Binance depth has a non-numeric \\`${field}\\`: ${value}.`);\n  }\n  return parsed;\n}\n\n/**\n * Convert one raw `[price, quantity]` pair into an {@link OrderbookLevel}.\n *\n * Zero-quantity entries are kept rather than filtered: in the diff stream a\n * zero is the venue's instruction to **remove** that price, and dropping it\n * here would leave the level resting forever.\n *\n * @param level - One entry from a `bids`/`asks` array.\n * @returns The parsed level.\n * @throws {SymmError} when the pair is malformed or non-numeric.\n */\nexport function parseBinanceDepthLevel(level: RawBinanceDepthLevel): OrderbookLevel {\n  if (!Array.isArray(level) || level.length < 2) {\n    throw new SymmError(\n      \"api\",\n      \"INVALID_BINANCE_DEPTH\",\n      `Binance depth level is not a [price, quantity] pair: ${JSON.stringify(level)}.`,\n    );\n  }\n\n  return {\n    price: toFiniteNumber(level[0], \"price\"),\n    size: toFiniteNumber(level[1], \"quantity\"),\n  };\n}\n\n/**\n * Convert an array of raw levels, preserving order and zero-quantity entries.\n *\n * @param levels - A `bids` or `asks` array from a snapshot or diff event.\n * @returns The parsed levels.\n * @throws {SymmError} when the payload is not an array of valid pairs.\n */\nexport function parseBinanceDepthLevels(levels: RawBinanceDepthLevel[] | undefined): OrderbookLevel[] {\n  if (levels === undefined) return [];\n\n  if (!Array.isArray(levels)) {\n    throw new SymmError(\n      \"api\",\n      \"INVALID_BINANCE_DEPTH\",\n      `Binance depth side is not an array: ${JSON.stringify(levels)}.`,\n    );\n  }\n\n  return levels.map(parseBinanceDepthLevel);\n}\n"],"mappings":";;AAsDA,SAAS,EAAe,GAAgB,GAAuB;CAC7D,IAAM,IAAS,OAAO,CAAK;CAC3B,IAAI,CAAC,OAAO,SAAS,CAAM,GACzB,MAAM,IAAI,EAAU,OAAO,yBAAyB,qCAAqC,EAAM,MAAM,EAAM,EAAE;CAE/G,OAAO;AACT;AAaA,SAAgB,EAAuB,GAA6C;CAClF,IAAI,CAAC,MAAM,QAAQ,CAAK,KAAK,EAAM,SAAS,GAC1C,MAAM,IAAI,EACR,OACA,yBACA,wDAAwD,KAAK,UAAU,CAAK,EAAE,EAChF;CAGF,OAAO;EACL,OAAO,EAAe,EAAM,IAAI,OAAO;EACvC,MAAM,EAAe,EAAM,IAAI,UAAU;CAC3C;AACF;AASA,SAAgB,EAAwB,GAA8D;CACpG,IAAI,MAAW,KAAA,GAAW,OAAO,CAAC;CAElC,IAAI,CAAC,MAAM,QAAQ,CAAM,GACvB,MAAM,IAAI,EACR,OACA,yBACA,uCAAuC,KAAK,UAAU,CAAM,EAAE,EAChE;CAGF,OAAO,EAAO,IAAI,CAAsB;AAC1C"}

package/dist/orderbook/sources/binance/watch-binance-depth.d.ts

@@ -0,0 +1,78 @@
+import { SymmError } from '../../../shared/errors/symm-error.js';
+import { WebSocketConstructor } from '../../../shared/types/websocket.js';
+import { Unwatch } from '../../../websocket/notifications/watch-notifications.js';
+import { SocketStatus } from '../../../websocket/socket/index.js';
+import { Orderbook, OrderbookResyncReason } from '../../types.js';
+import { BinanceOrderbookMarket } from './constants.js';
+/**
+ * Parameters for {@link watchBinanceDepth}.
+ */
+export interface WatchBinanceDepthParameters {
+    /** REST host for snapshots, without a trailing slash. */
+    restUrl: string;
+    /** Combined-stream WebSocket endpoint. Must be the market's depth route. */
+    wsUrl: string;
+    /** Which Binance market to read. Decides the continuity rule. */
+    market: BinanceOrderbookMarket;
+    /** Binance symbol, upper-case (e.g. `"BTCUSDT"`). */
+    symbol: string;
+    /** Market name as SYMMIO names it, carried onto every emitted book. */
+    marketName: string;
+    /** Snapshot depth per side. */
+    limit: number;
+    /** Levels per side to emit on each update. */
+    levels: number;
+    /** Diff-stream update speed in ms; part of the stream name. */
+    updateSpeed: number;
+    /** WebSocket implementation to dial with. */
+    webSocketConstructor: WebSocketConstructor;
+    /** Called with a complete book on every applied update. */
+    onOrderbook: (orderbook: Orderbook) => void;
+    /** Called when the book is about to be rebuilt. */
+    onResync?: (reason: OrderbookResyncReason) => void;
+    /** Called whenever the connection status changes. */
+    onStatusChange?: (status: SocketStatus) => void;
+    /** Called on a transport, parse, or snapshot error; does not stop the subscription. */
+    onError?: (error: SymmError) => void;
+}
+/**
+ * Track a Binance order book in real time, correctly synchronized.
+ *
+ * This implements Binance's documented local-order-book procedure end to end:
+ * subscribe first and buffer, then snapshot, discard updates the snapshot
+ * already covers, require the first applied update to straddle the snapshot's
+ * sequence number, apply absolute quantities with zero meaning removal, and
+ * verify every subsequent update chains onto the last. Any break — a missed
+ * update, a reconnect, a snapshot that arrives older than the buffer — throws
+ * the local book away and rebuilds it, announcing the rebuild through
+ * `onResync` so a consumer can show the book as stale rather than trust a
+ * silently diverged ladder.
+ *
+ * Each call opens its own connection. That is deliberate at this scale — one
+ * ladder holds one subscription — and keeps the reconnect and unsubscribe paths
+ * trivially correct. Binance drops idle connections after 24 hours; the
+ * reconnecting socket re-dials, re-sends SUBSCRIBE, and the book resyncs.
+ *
+ * @param parameters - Endpoints, symbol, depth, and handlers.
+ * @returns An unwatch function that closes the connection and cancels any
+ *   in-flight snapshot.
+ *
+ * @example
+ * ```ts
+ * const unwatch = watchBinanceDepth({
+ *   restUrl: "https://fapi.binance.com",
+ *   wsUrl: "wss://fstream.binance.com/public/stream",
+ *   market: "usd-m-futures",
+ *   symbol: "BTCUSDT",
+ *   marketName: "BTCUSDT",
+ *   limit: 1000,
+ *   levels: 20,
+ *   updateSpeed: 500,
+ *   webSocketConstructor: WebSocket,
+ *   onOrderbook: (book) => render(book),
+ *   onResync: (reason) => markStale(reason),
+ * });
+ * ```
+ */
+export declare function watchBinanceDepth(parameters: WatchBinanceDepthParameters): Unwatch;
+//# sourceMappingURL=watch-binance-depth.d.ts.map

package/dist/orderbook/sources/binance/watch-binance-depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-binance-depth.d.ts","sourceRoot":"","sources":["../../../../src/orderbook/sources/binance/watch-binance-depth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sDAAsD,CAAC;AACpF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,KAAK,EAAE,SAAS,EAAkB,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAqC,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAuB7F;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,2DAA2D;IAC3D,WAAW,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;IAC5C,mDAAmD;IACnD,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACnD,qDAAqD;IACrD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAChD,uFAAuF;IACvF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACtC;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,2BAA2B,GAAG,OAAO,CAoPlF"}

package/dist/orderbook/sources/binance/watch-binance-depth.js

@@ -0,0 +1,125 @@
+import { SymmError as e } from "../../../shared/errors/symm-error.js";
+import { createReconnectingSocket as t } from "../../../websocket/socket/create-reconnecting-socket.js";
+import "./constants.js";
+import { parseBinanceDepthLevels as n } from "./parse-depth.js";
+import { fetchBinanceDepth as r } from "./fetch-binance-depth.js";
+//#region src/orderbook/sources/binance/watch-binance-depth.ts
+var i = 1e3, a = 5e3;
+function o(t) {
+	if (t instanceof e) return t;
+	let n = t instanceof Error ? t : void 0;
+	return new e("api", "BINANCE_DEPTH_SOCKET_ERROR", `Binance depth socket error${n ? `: ${n.message}` : "."}`, { cause: n });
+}
+function s(e, t, n) {
+	return e === "usd-m-futures" && typeof t.pu == "number" ? t.pu !== n : t.U > n + 1;
+}
+function c(e) {
+	let { restUrl: c, wsUrl: l, market: u, symbol: d, marketName: f, limit: p, levels: m, updateSpeed: h, webSocketConstructor: g, onOrderbook: _, onResync: v, onStatusChange: y, onError: b } = e, x = `${d.toLowerCase()}@depth@${h}ms`, S = JSON.stringify({
+		method: "SUBSCRIBE",
+		params: [x],
+		id: 1
+	}), C = d.toUpperCase(), w = /* @__PURE__ */ new Map(), T = /* @__PURE__ */ new Map(), E = 0, D = 0, O = "buffering", k = !1, A = [], j = 0, M, N;
+	function P(e, t) {
+		for (let { price: n, size: r } of t) r <= 0 ? e.delete(n) : e.set(n, r);
+	}
+	function F(e, t) {
+		if (e.size <= a) return;
+		let n = I(e, t).slice(0, a), r = new Set(n);
+		for (let t of e.keys()) r.has(t) || e.delete(t);
+	}
+	function I(e, t) {
+		let n = Array.from(e.keys());
+		return n.sort((e, n) => t === "desc" ? n - e : e - n), n;
+	}
+	function L(e, t) {
+		return I(e, t).slice(0, m).map((t) => ({
+			price: t,
+			size: e.get(t)
+		}));
+	}
+	function R() {
+		_({
+			marketName: f,
+			bids: L(w, "desc"),
+			asks: L(T, "asc"),
+			lastUpdateId: E,
+			timestamp: D
+		});
+	}
+	function z(e) {
+		if (e.u < E) return "skipped";
+		if (k) {
+			if (e.U > E) return V("stale-snapshot"), "resyncing";
+			k = !1;
+		} else if (s(u, e, E)) return V("sequence-gap"), "resyncing";
+		return P(w, n(e.b)), P(T, n(e.a)), F(w, "desc"), F(T, "asc"), E = e.u, D = e.T ?? e.E ?? D, "applied";
+	}
+	function B(e) {
+		w.clear(), T.clear();
+		for (let t of e.bids) w.set(t.price, t.size);
+		for (let t of e.asks) T.set(t.price, t.size);
+		E = e.lastUpdateId, D = e.timestamp;
+		let t = A.filter((t) => t.u >= e.lastUpdateId);
+		A = [], O = "live", k = !0;
+		for (let e of t) if (z(e) === "resyncing") return;
+		R();
+	}
+	function V(e) {
+		if (O === "closed") return;
+		O = "buffering", k = !1, v?.(e);
+		let t = ++j;
+		M?.abort();
+		let n = new AbortController();
+		M = n, r({
+			restUrl: c,
+			market: u,
+			symbol: d,
+			marketName: f,
+			limit: p,
+			signal: n.signal
+		}).then((e) => {
+			t !== j || O === "closed" || B(e);
+		}).catch((e) => {
+			t !== j || O === "closed" || n.signal.aborted || (b?.(o(e)), N = setTimeout(() => {
+				N = void 0, O !== "closed" && V("initial");
+			}, i));
+		});
+	}
+	let H = !1, U = t({
+		url: l,
+		webSocketConstructor: g,
+		getOpenMessages: () => [S],
+		onOpen: () => {
+			V(H ? "reconnect" : "initial"), H = !0;
+		},
+		onStatusChange: y,
+		onError: (e) => b?.(o(e)),
+		onMessage: (e) => {
+			if (O === "closed") return;
+			let t;
+			try {
+				t = JSON.parse(String(e));
+			} catch (e) {
+				b?.(o(e));
+				return;
+			}
+			let n = t.data ?? t;
+			if (n.e === "depthUpdate" && n.s?.toUpperCase() === C && !(typeof n.U != "number" || typeof n.u != "number")) try {
+				if (O === "buffering") {
+					A.push(n), A.length > 200 && A.shift();
+					return;
+				}
+				z(n) === "applied" && R();
+			} catch (e) {
+				b?.(o(e));
+			}
+		}
+	});
+	return () => {
+		O = "closed", j += 1, N !== void 0 && clearTimeout(N), N = void 0, M?.abort(), M = void 0, A = [], U.close();
+	};
+}
+//#endregion
+export { c as watchBinanceDepth };
+
+//# sourceMappingURL=watch-binance-depth.js.map

package/dist/orderbook/sources/binance/watch-binance-depth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-binance-depth.js","names":[],"sources":["../../../../src/orderbook/sources/binance/watch-binance-depth.ts"],"sourcesContent":["import { SymmError } from \"../../../shared/errors/symm-error\";\nimport type { WebSocketConstructor } from \"../../../shared/types/websocket\";\nimport type { Unwatch } from \"../../../websocket/notifications/watch-notifications\";\nimport type { SocketStatus } from \"../../../websocket/socket\";\nimport { createReconnectingSocket } from \"../../../websocket/socket/create-reconnecting-socket\";\nimport type { Orderbook, OrderbookLevel, OrderbookResyncReason } from \"../../types\";\nimport { BINANCE_DEPTH_MAX_BUFFERED_EVENTS, type BinanceOrderbookMarket } from \"./constants\";\nimport { fetchBinanceDepth } from \"./fetch-binance-depth\";\nimport { parseBinanceDepthLevels, type RawBinanceDepthEvent } from \"./parse-depth\";\n\n/**\n * Delay before retrying a snapshot that failed.\n *\n * The socket keeps buffering throughout, so a retry resumes from a live buffer\n * rather than a cold start.\n */\nconst SNAPSHOT_RETRY_DELAY_MS = 1_000;\n\n/**\n * Upper bound on levels tracked per side.\n *\n * The book self-cleans — a filled or cancelled level arrives as a zero and is\n * removed — so this never trips in normal operation. It bounds memory against\n * a venue that leaks far-out levels, and dropping the worst-priced levels is\n * safe: a later update removing one is explicitly documented as normal, and\n * only the top {@link WatchBinanceDepthParameters.levels} are ever emitted.\n */\nconst MAX_TRACKED_LEVELS_PER_SIDE = 5_000;\n\n/**\n * Parameters for {@link watchBinanceDepth}.\n */\nexport interface WatchBinanceDepthParameters {\n  /** REST host for snapshots, without a trailing slash. */\n  restUrl: string;\n  /** Combined-stream WebSocket endpoint. Must be the market's depth route. */\n  wsUrl: string;\n  /** Which Binance market to read. Decides the continuity rule. */\n  market: BinanceOrderbookMarket;\n  /** Binance symbol, upper-case (e.g. `\"BTCUSDT\"`). */\n  symbol: string;\n  /** Market name as SYMMIO names it, carried onto every emitted book. */\n  marketName: string;\n  /** Snapshot depth per side. */\n  limit: number;\n  /** Levels per side to emit on each update. */\n  levels: number;\n  /** Diff-stream update speed in ms; part of the stream name. */\n  updateSpeed: number;\n  /** WebSocket implementation to dial with. */\n  webSocketConstructor: WebSocketConstructor;\n  /** Called with a complete book on every applied update. */\n  onOrderbook: (orderbook: Orderbook) => void;\n  /** Called when the book is about to be rebuilt. */\n  onResync?: (reason: OrderbookResyncReason) => void;\n  /** Called whenever the connection status changes. */\n  onStatusChange?: (status: SocketStatus) => void;\n  /** Called on a transport, parse, or snapshot error; does not stop the subscription. */\n  onError?: (error: SymmError) => void;\n}\n\n/** Combined-stream envelope, or the bare event on a raw stream. */\ninterface BinanceDepthFrame {\n  stream?: string;\n  data?: RawBinanceDepthEvent;\n  e?: string;\n  s?: string;\n  U?: number;\n  u?: number;\n}\n\nfunction toDepthError(event: unknown): SymmError {\n  if (event instanceof SymmError) return event;\n  const cause = event instanceof Error ? event : undefined;\n  return new SymmError(\n    \"api\",\n    \"BINANCE_DEPTH_SOCKET_ERROR\",\n    `Binance depth socket error${cause ? `: ${cause.message}` : \".\"}`,\n    {\n      cause,\n    },\n  );\n}\n\n/**\n * Whether an update fails to chain onto the book's current sequence position.\n *\n * The rule is **per market and not interchangeable**. Futures chains on `pu`,\n * which carries the previous event's `u`; its `U` routinely jumps hundreds of\n * ids past the previous `u`, so the spot rule applied to futures reports a gap\n * on essentially every event. Spot has no `pu` and chains on `U`, tolerating\n * overlap (`U <= lastUpdateId + 1`) because two events may cover the same id.\n */\nfunction hasSequenceGap(market: BinanceOrderbookMarket, event: RawBinanceDepthEvent, lastUpdateId: number): boolean {\n  if (market === \"usd-m-futures\" && typeof event.pu === \"number\") {\n    return event.pu !== lastUpdateId;\n  }\n  return event.U > lastUpdateId + 1;\n}\n\n/**\n * Track a Binance order book in real time, correctly synchronized.\n *\n * This implements Binance's documented local-order-book procedure end to end:\n * subscribe first and buffer, then snapshot, discard updates the snapshot\n * already covers, require the first applied update to straddle the snapshot's\n * sequence number, apply absolute quantities with zero meaning removal, and\n * verify every subsequent update chains onto the last. Any break — a missed\n * update, a reconnect, a snapshot that arrives older than the buffer — throws\n * the local book away and rebuilds it, announcing the rebuild through\n * `onResync` so a consumer can show the book as stale rather than trust a\n * silently diverged ladder.\n *\n * Each call opens its own connection. That is deliberate at this scale — one\n * ladder holds one subscription — and keeps the reconnect and unsubscribe paths\n * trivially correct. Binance drops idle connections after 24 hours; the\n * reconnecting socket re-dials, re-sends SUBSCRIBE, and the book resyncs.\n *\n * @param parameters - Endpoints, symbol, depth, and handlers.\n * @returns An unwatch function that closes the connection and cancels any\n *   in-flight snapshot.\n *\n * @example\n * ```ts\n * const unwatch = watchBinanceDepth({\n *   restUrl: \"https://fapi.binance.com\",\n *   wsUrl: \"wss://fstream.binance.com/public/stream\",\n *   market: \"usd-m-futures\",\n *   symbol: \"BTCUSDT\",\n *   marketName: \"BTCUSDT\",\n *   limit: 1000,\n *   levels: 20,\n *   updateSpeed: 500,\n *   webSocketConstructor: WebSocket,\n *   onOrderbook: (book) => render(book),\n *   onResync: (reason) => markStale(reason),\n * });\n * ```\n */\nexport function watchBinanceDepth(parameters: WatchBinanceDepthParameters): Unwatch {\n  const {\n    restUrl,\n    wsUrl,\n    market,\n    symbol,\n    marketName,\n    limit,\n    levels,\n    updateSpeed,\n    webSocketConstructor,\n    onOrderbook,\n    onResync,\n    onStatusChange,\n    onError,\n  } = parameters;\n\n  const streamName = `${symbol.toLowerCase()}@depth@${updateSpeed}ms`;\n  const subscribeMessage = JSON.stringify({ method: \"SUBSCRIBE\", params: [streamName], id: 1 });\n  const upperSymbol = symbol.toUpperCase();\n\n  const bids = new Map<number, number>();\n  const asks = new Map<number, number>();\n\n  let lastUpdateId = 0;\n  let timestamp = 0;\n  let phase: \"buffering\" | \"live\" | \"closed\" = \"buffering\";\n  /**\n   * Set immediately after seeding. The first update applied to a fresh\n   * snapshot is checked against the snapshot's own sequence number rather than\n   * against the previous update — there is no previous update to chain onto.\n   */\n  let expectFirstEvent = false;\n  let buffer: RawBinanceDepthEvent[] = [];\n  /** Invalidates the results of a snapshot request that a newer sync superseded. */\n  let syncToken = 0;\n  let abortController: AbortController | undefined;\n  let retryTimer: ReturnType<typeof setTimeout> | undefined;\n\n  function applyLevels(side: Map<number, number>, updates: readonly OrderbookLevel[]): void {\n    for (const { price, size } of updates) {\n      /** A zero quantity is the venue's instruction to remove the level. */\n      if (size <= 0) side.delete(price);\n      else side.set(price, size);\n    }\n  }\n\n  function pruneSide(side: Map<number, number>, direction: \"desc\" | \"asc\"): void {\n    if (side.size <= MAX_TRACKED_LEVELS_PER_SIDE) return;\n\n    const sorted = sortPrices(side, direction).slice(0, MAX_TRACKED_LEVELS_PER_SIDE);\n    const kept = new Set(sorted);\n    for (const price of side.keys()) {\n      if (!kept.has(price)) side.delete(price);\n    }\n  }\n\n  function sortPrices(side: Map<number, number>, direction: \"desc\" | \"asc\"): number[] {\n    const prices = Array.from(side.keys());\n    prices.sort((a, b) => (direction === \"desc\" ? b - a : a - b));\n    return prices;\n  }\n\n  function topLevels(side: Map<number, number>, direction: \"desc\" | \"asc\"): OrderbookLevel[] {\n    return sortPrices(side, direction)\n      .slice(0, levels)\n      .map((price) => ({ price, size: side.get(price)! }));\n  }\n\n  function emit(): void {\n    onOrderbook({\n      marketName,\n      bids: topLevels(bids, \"desc\"),\n      asks: topLevels(asks, \"asc\"),\n      lastUpdateId,\n      timestamp,\n    });\n  }\n\n  /**\n   * Outcome of offering one update to the book.\n   *\n   * - `applied` — the book moved; emit.\n   * - `skipped` — the update carried nothing new, so re-emitting an identical\n   *   book would only cost the consumer a render.\n   * - `resyncing` — the update could not be trusted; a rebuild is under way and\n   *   the caller must stop draining.\n   */\n  type ApplyOutcome = \"applied\" | \"skipped\" | \"resyncing\";\n\n  function applyEvent(event: RawBinanceDepthEvent): ApplyOutcome {\n    /** Already covered by the snapshot or by an earlier update. */\n    if (event.u < lastUpdateId) return \"skipped\";\n\n    if (expectFirstEvent) {\n      /**\n       * The first update must straddle the snapshot: it has to start at or\n       * before the snapshot's sequence number and end at or after it. An\n       * update starting past the snapshot means the gap between them was never\n       * covered, so the snapshot is unusable.\n       */\n      if (event.U > lastUpdateId) {\n        startSync(\"stale-snapshot\");\n        return \"resyncing\";\n      }\n      expectFirstEvent = false;\n    } else if (hasSequenceGap(market, event, lastUpdateId)) {\n      startSync(\"sequence-gap\");\n      return \"resyncing\";\n    }\n\n    applyLevels(bids, parseBinanceDepthLevels(event.b));\n    applyLevels(asks, parseBinanceDepthLevels(event.a));\n    pruneSide(bids, \"desc\");\n    pruneSide(asks, \"asc\");\n\n    lastUpdateId = event.u;\n    timestamp = event.T ?? event.E ?? timestamp;\n    return \"applied\";\n  }\n\n  function seed(snapshot: Orderbook): void {\n    bids.clear();\n    asks.clear();\n    for (const level of snapshot.bids) bids.set(level.price, level.size);\n    for (const level of snapshot.asks) asks.set(level.price, level.size);\n\n    lastUpdateId = snapshot.lastUpdateId;\n    timestamp = snapshot.timestamp;\n\n    /** Updates the snapshot already reflects carry no information. */\n    const pending = buffer.filter((event) => event.u >= snapshot.lastUpdateId);\n    buffer = [];\n    phase = \"live\";\n    expectFirstEvent = true;\n\n    for (const event of pending) {\n      if (applyEvent(event) === \"resyncing\") return;\n    }\n\n    emit();\n  }\n\n  function startSync(reason: OrderbookResyncReason): void {\n    if (phase === \"closed\") return;\n\n    phase = \"buffering\";\n    expectFirstEvent = false;\n    onResync?.(reason);\n\n    const token = ++syncToken;\n    abortController?.abort();\n    const controller = new AbortController();\n    abortController = controller;\n\n    fetchBinanceDepth({ restUrl, market, symbol, marketName, limit, signal: controller.signal })\n      .then((snapshot) => {\n        /** A newer sync, or an unwatch, superseded this request. */\n        if (token !== syncToken || phase === \"closed\") return;\n        seed(snapshot);\n      })\n      .catch((err: unknown) => {\n        if (token !== syncToken || phase === \"closed\") return;\n        if (controller.signal.aborted) return;\n\n        onError?.(toDepthError(err));\n\n        /**\n         * The socket is still buffering, so a retry resumes from live updates.\n         * `initial` rather than the original reason: from the book's point of\n         * view every retry is another attempt at the same first build.\n         */\n        retryTimer = setTimeout(() => {\n          retryTimer = undefined;\n          if (phase !== \"closed\") startSync(\"initial\");\n        }, SNAPSHOT_RETRY_DELAY_MS);\n      });\n  }\n\n  let hasOpened = false;\n\n  const socket = createReconnectingSocket({\n    url: wsUrl,\n    webSocketConstructor,\n    /** Re-sent on every (re)open, so the subscription survives reconnects. */\n    getOpenMessages: () => [subscribeMessage],\n    onOpen: () => {\n      /**\n       * Subscribe-then-snapshot, in that order. Fetching first — as the\n       * reference implementation this replaces did — leaves the window between\n       * the snapshot and the first buffered update uncovered, and nothing\n       * downstream can detect the hole.\n       */\n      startSync(hasOpened ? \"reconnect\" : \"initial\");\n      hasOpened = true;\n    },\n    onStatusChange,\n    onError: (event) => onError?.(toDepthError(event)),\n    onMessage: (data) => {\n      if (phase === \"closed\") return;\n\n      let frame: BinanceDepthFrame;\n      try {\n        frame = JSON.parse(String(data)) as BinanceDepthFrame;\n      } catch (err) {\n        onError?.(toDepthError(err));\n        return;\n      }\n\n      const event = (frame.data ?? frame) as RawBinanceDepthEvent;\n      if (event.e !== \"depthUpdate\") return;\n      /** Guard against feeding this book from another symbol's stream. */\n      if (event.s?.toUpperCase() !== upperSymbol) return;\n      if (typeof event.U !== \"number\" || typeof event.u !== \"number\") return;\n\n      try {\n        if (phase === \"buffering\") {\n          buffer.push(event);\n          /**\n           * Only reachable if a snapshot never resolves. The oldest events go\n           * first, which is the pair the continuity check will catch — a silent\n           * partial application would be the dangerous outcome, and cannot happen.\n           */\n          if (buffer.length > BINANCE_DEPTH_MAX_BUFFERED_EVENTS) buffer.shift();\n          return;\n        }\n\n        if (applyEvent(event) === \"applied\") emit();\n      } catch (err) {\n        onError?.(toDepthError(err));\n      }\n    },\n  });\n\n  return () => {\n    phase = \"closed\";\n    syncToken += 1;\n    if (retryTimer !== undefined) clearTimeout(retryTimer);\n    retryTimer = undefined;\n    abortController?.abort();\n    abortController = undefined;\n    buffer = [];\n    socket.close();\n  };\n}\n"],"mappings":"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"}

package/dist/orderbook/tick-size.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Decimal places a tick size implies.
+ *
+ * Handles the exponential form small ticks stringify to — `1e-9` is nine
+ * decimals, not the zero a naive `split(".")` would report.
+ *
+ * @param tickSize - A positive price increment.
+ * @returns Decimal places needed to write any multiple of the tick exactly.
+ *
+ * @example
+ * ```ts
+ * countTickDecimals(0.01);  // 2
+ * countTickDecimals(1e-9);  // 9
+ * countTickDecimals(50);    // 0
+ * ```
+ */
+export declare function countTickDecimals(tickSize: number): number;
+/** Which way {@link roundToTick} moves a price that is not already on the grid. */
+export type TickRoundingMode = "down" | "up";
+/**
+ * Snap a price onto a tick grid.
+ *
+ * Bids round **down** and asks round **up**, so a grouped level never claims
+ * liquidity at a better price than actually rests there.
+ *
+ * Division by a decimal tick is not exact in binary floating point —
+ * `63018.1 / 0.1` is `630180.9999999999`, and flooring that loses a whole tick.
+ * The quotient is therefore snapped to a nearby integer before rounding, and
+ * the product is written back at the tick's own precision.
+ *
+ * @param price - The price to snap.
+ * @param tickSize - Grid spacing. Must be positive.
+ * @param mode - Direction to move a price that falls between ticks.
+ * @returns The price on the grid.
+ * @throws {SymmError} when `tickSize` is not a positive finite number.
+ *
+ * @example
+ * ```ts
+ * roundToTick(63018.17, 0.1, "down"); // 63018.1
+ * roundToTick(63018.17, 0.1, "up");   // 63018.2
+ * roundToTick(63018.1, 0.1, "up");    // 63018.1 — already on the grid
+ * ```
+ */
+export declare function roundToTick(price: number, tickSize: number, mode: TickRoundingMode): number;
+/**
+ * Options for {@link suggestOrderbookTickSizes}.
+ */
+export interface SuggestOrderbookTickSizesOptions {
+    /**
+     * Coarsest grouping to offer, as a fraction of the reference price.
+     * Default `0.005` — half a percent, beyond which a ladder collapses into a
+     * handful of rows and stops being readable.
+     */
+    maxFractionOfPrice?: number;
+    /** Most entries to return. Default `8`. */
+    maxSteps?: number;
+}
+/**
+ * Build a grouping ladder from a venue's own tick size.
+ *
+ * Derived rather than hardcoded. A global list of candidate ticks — the
+ * approach a UI reaches for first — offers groupings finer than the venue can
+ * quote (rows that can never be occupied) and, on a low-priced asset, ones so
+ * coarse the whole book lands in one row. Anchoring on the real tick and
+ * stepping 1/2/5/10 keeps every entry both quotable and useful.
+ *
+ * @param tickSize - The venue's smallest price increment.
+ * @param referencePrice - A price to scale against, typically the mid.
+ * @param options - Ladder bounds.
+ * @returns Tick sizes ascending, always starting with `tickSize` itself.
+ *
+ * @example
+ * ```ts
+ * suggestOrderbookTickSizes(0.1, 63_000); // [0.1, 0.2, 0.5, 1, 2, 5, 10, 20]
+ * suggestOrderbookTickSizes(0.0001, 1.25); // [0.0001, 0.0002, 0.0005, 0.001, 0.002]
+ * ```
+ */
+export declare function suggestOrderbookTickSizes(tickSize: number, referencePrice: number, options?: SuggestOrderbookTickSizesOptions): number[];
+//# sourceMappingURL=tick-size.d.ts.map

package/dist/orderbook/tick-size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick-size.d.ts","sourceRoot":"","sources":["../../src/orderbook/tick-size.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa1D;AAED,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAgB3F;AAKD;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,gCAAqC,GAC7C,MAAM,EAAE,CAqBV"}

package/dist/orderbook/tick-size.js

@@ -0,0 +1,46 @@
+import { SymmError as e } from "../shared/errors/symm-error.js";
+//#region src/orderbook/tick-size.ts
+function t(e) {
+	if (!Number.isFinite(e) || e <= 0) return 0;
+	let t = e.toString(), n = t.indexOf("e-");
+	if (n !== -1) {
+		let e = Number(t.slice(n + 2)), r = t.slice(0, n).split(".")[1]?.length ?? 0;
+		return Math.min(100, e + r);
+	}
+	return Math.min(100, t.split(".")[1]?.length ?? 0);
+}
+function n(n, r, i) {
+	if (!Number.isFinite(r) || r <= 0) throw new e("validation", "INVALID_TICK_SIZE", `Tick size must be a positive finite number, got ${r}.`);
+	let a = n / r, o = Math.round(a), s = Math.abs(a - o) < 1e-9 * Math.max(1, Math.abs(a)) ? o : i === "down" ? Math.floor(a) : Math.ceil(a);
+	return Number((s * r).toFixed(t(r)));
+}
+var r = [
+	1,
+	2,
+	5,
+	10,
+	20,
+	50,
+	100,
+	200,
+	500,
+	1e3,
+	2e3,
+	5e3,
+	1e4
+];
+function i(e, n, i = {}) {
+	if (!Number.isFinite(e) || e <= 0) return [];
+	let { maxFractionOfPrice: a = .005, maxSteps: o = 8 } = i, s = t(e), c = Number.isFinite(n) && n > 0 ? n * a : Infinity, l = [];
+	for (let t of r) {
+		if (l.length >= o) break;
+		let n = Number((e * t).toFixed(s));
+		if (t > 1 && n > c) break;
+		l.push(n);
+	}
+	return l;
+}
+//#endregion
+export { t as countTickDecimals, n as roundToTick, i as suggestOrderbookTickSizes };
+
+//# sourceMappingURL=tick-size.js.map

package/dist/orderbook/tick-size.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick-size.js","names":[],"sources":["../../src/orderbook/tick-size.ts"],"sourcesContent":["import { SymmError } from \"../shared/errors/symm-error\";\n\n/**\n * Decimal places a tick size implies.\n *\n * Handles the exponential form small ticks stringify to — `1e-9` is nine\n * decimals, not the zero a naive `split(\".\")` would report.\n *\n * @param tickSize - A positive price increment.\n * @returns Decimal places needed to write any multiple of the tick exactly.\n *\n * @example\n * ```ts\n * countTickDecimals(0.01);  // 2\n * countTickDecimals(1e-9);  // 9\n * countTickDecimals(50);    // 0\n * ```\n */\nexport function countTickDecimals(tickSize: number): number {\n  if (!Number.isFinite(tickSize) || tickSize <= 0) return 0;\n\n  const text = tickSize.toString();\n  const exponentIndex = text.indexOf(\"e-\");\n\n  if (exponentIndex !== -1) {\n    const exponent = Number(text.slice(exponentIndex + 2));\n    const mantissaDecimals = text.slice(0, exponentIndex).split(\".\")[1]?.length ?? 0;\n    return Math.min(100, exponent + mantissaDecimals);\n  }\n\n  return Math.min(100, text.split(\".\")[1]?.length ?? 0);\n}\n\n/** Which way {@link roundToTick} moves a price that is not already on the grid. */\nexport type TickRoundingMode = \"down\" | \"up\";\n\n/**\n * Snap a price onto a tick grid.\n *\n * Bids round **down** and asks round **up**, so a grouped level never claims\n * liquidity at a better price than actually rests there.\n *\n * Division by a decimal tick is not exact in binary floating point —\n * `63018.1 / 0.1` is `630180.9999999999`, and flooring that loses a whole tick.\n * The quotient is therefore snapped to a nearby integer before rounding, and\n * the product is written back at the tick's own precision.\n *\n * @param price - The price to snap.\n * @param tickSize - Grid spacing. Must be positive.\n * @param mode - Direction to move a price that falls between ticks.\n * @returns The price on the grid.\n * @throws {SymmError} when `tickSize` is not a positive finite number.\n *\n * @example\n * ```ts\n * roundToTick(63018.17, 0.1, \"down\"); // 63018.1\n * roundToTick(63018.17, 0.1, \"up\");   // 63018.2\n * roundToTick(63018.1, 0.1, \"up\");    // 63018.1 — already on the grid\n * ```\n */\nexport function roundToTick(price: number, tickSize: number, mode: TickRoundingMode): number {\n  if (!Number.isFinite(tickSize) || tickSize <= 0) {\n    throw new SymmError(\n      \"validation\",\n      \"INVALID_TICK_SIZE\",\n      `Tick size must be a positive finite number, got ${tickSize}.`,\n    );\n  }\n\n  const units = price / tickSize;\n  const nearest = Math.round(units);\n  /** Treat a quotient within float noise of an integer as already on the grid. */\n  const onGrid = Math.abs(units - nearest) < 1e-9 * Math.max(1, Math.abs(units));\n  const snapped = onGrid ? nearest : mode === \"down\" ? Math.floor(units) : Math.ceil(units);\n\n  return Number((snapped * tickSize).toFixed(countTickDecimals(tickSize)));\n}\n\n/** Multipliers applied to the venue tick to build a grouping ladder. */\nconst TICK_LADDER_STEPS = [1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10_000] as const;\n\n/**\n * Options for {@link suggestOrderbookTickSizes}.\n */\nexport interface SuggestOrderbookTickSizesOptions {\n  /**\n   * Coarsest grouping to offer, as a fraction of the reference price.\n   * Default `0.005` — half a percent, beyond which a ladder collapses into a\n   * handful of rows and stops being readable.\n   */\n  maxFractionOfPrice?: number;\n  /** Most entries to return. Default `8`. */\n  maxSteps?: number;\n}\n\n/**\n * Build a grouping ladder from a venue's own tick size.\n *\n * Derived rather than hardcoded. A global list of candidate ticks — the\n * approach a UI reaches for first — offers groupings finer than the venue can\n * quote (rows that can never be occupied) and, on a low-priced asset, ones so\n * coarse the whole book lands in one row. Anchoring on the real tick and\n * stepping 1/2/5/10 keeps every entry both quotable and useful.\n *\n * @param tickSize - The venue's smallest price increment.\n * @param referencePrice - A price to scale against, typically the mid.\n * @param options - Ladder bounds.\n * @returns Tick sizes ascending, always starting with `tickSize` itself.\n *\n * @example\n * ```ts\n * suggestOrderbookTickSizes(0.1, 63_000); // [0.1, 0.2, 0.5, 1, 2, 5, 10, 20]\n * suggestOrderbookTickSizes(0.0001, 1.25); // [0.0001, 0.0002, 0.0005, 0.001, 0.002]\n * ```\n */\nexport function suggestOrderbookTickSizes(\n  tickSize: number,\n  referencePrice: number,\n  options: SuggestOrderbookTickSizesOptions = {},\n): number[] {\n  if (!Number.isFinite(tickSize) || tickSize <= 0) return [];\n\n  const { maxFractionOfPrice = 0.005, maxSteps = 8 } = options;\n  const decimals = countTickDecimals(tickSize);\n  const ceiling =\n    Number.isFinite(referencePrice) && referencePrice > 0\n      ? referencePrice * maxFractionOfPrice\n      : Number.POSITIVE_INFINITY;\n\n  const ladder: number[] = [];\n\n  for (const step of TICK_LADDER_STEPS) {\n    if (ladder.length >= maxSteps) break;\n    const candidate = Number((tickSize * step).toFixed(decimals));\n    /** The venue tick is always offered, even on an asset priced below it. */\n    if (step > 1 && candidate > ceiling) break;\n    ladder.push(candidate);\n  }\n\n  return ladder;\n}\n"],"mappings":";;AAkBA,SAAgB,EAAkB,GAA0B;CAC1D,IAAI,CAAC,OAAO,SAAS,CAAQ,KAAK,KAAY,GAAG,OAAO;CAExD,IAAM,IAAO,EAAS,SAAS,GACzB,IAAgB,EAAK,QAAQ,IAAI;CAEvC,IAAI,MAAkB,IAAI;EACxB,IAAM,IAAW,OAAO,EAAK,MAAM,IAAgB,CAAC,CAAC,GAC/C,IAAmB,EAAK,MAAM,GAAG,CAAa,EAAE,MAAM,GAAG,EAAE,IAAI,UAAU;EAC/E,OAAO,KAAK,IAAI,KAAK,IAAW,CAAgB;CAClD;CAEA,OAAO,KAAK,IAAI,KAAK,EAAK,MAAM,GAAG,EAAE,IAAI,UAAU,CAAC;AACtD;AA6BA,SAAgB,EAAY,GAAe,GAAkB,GAAgC;CAC3F,IAAI,CAAC,OAAO,SAAS,CAAQ,KAAK,KAAY,GAC5C,MAAM,IAAI,EACR,cACA,qBACA,mDAAmD,EAAS,EAC9D;CAGF,IAAM,IAAQ,IAAQ,GAChB,IAAU,KAAK,MAAM,CAAK,GAG1B,IADS,KAAK,IAAI,IAAQ,CAAO,IAAI,OAAO,KAAK,IAAI,GAAG,KAAK,IAAI,CAAK,CAAC,IACpD,IAAU,MAAS,SAAS,KAAK,MAAM,CAAK,IAAI,KAAK,KAAK,CAAK;CAExF,OAAO,QAAQ,IAAU,GAAU,QAAQ,EAAkB,CAAQ,CAAC,CAAC;AACzE;AAGA,IAAM,IAAoB;CAAC;CAAG;CAAG;CAAG;CAAI;CAAI;CAAI;CAAK;CAAK;CAAK;CAAM;CAAM;CAAM;AAAM;AAoCvF,SAAgB,EACd,GACA,GACA,IAA4C,CAAC,GACnC;CACV,IAAI,CAAC,OAAO,SAAS,CAAQ,KAAK,KAAY,GAAG,OAAO,CAAC;CAEzD,IAAM,EAAE,wBAAqB,MAAO,cAAW,MAAM,GAC/C,IAAW,EAAkB,CAAQ,GACrC,IACJ,OAAO,SAAS,CAAc,KAAK,IAAiB,IAChD,IAAiB,IACjB,UAEA,IAAmB,CAAC;CAE1B,KAAK,IAAM,KAAQ,GAAmB;EACpC,IAAI,EAAO,UAAU,GAAU;EAC/B,IAAM,IAAY,QAAQ,IAAW,GAAM,QAAQ,CAAQ,CAAC;EAE5D,IAAI,IAAO,KAAK,IAAY,GAAS;EACrC,EAAO,KAAK,CAAS;CACvB;CAEA,OAAO;AACT"}