feat: order-book microstructure indicators (part 1 of 4) (#112)

* feat(core): add microstructure input types (OrderBook, Trade, TradeQuote) New non-OHLCV value types for the order-book / trade-flow indicator family: Level, OrderBook (sorted, uncrossed depth snapshot), Side, Trade (with aggressor side), and TradeQuote (trade paired with prevailing mid). Each has a validating constructor plus a new_unchecked hot-path constructor, with full unit coverage. Adds InvalidOrderBook / InvalidTrade error variants. * feat(core): add 5 order-book microstructure indicators OrderBookImbalanceTop1/TopN/Full (signed depth imbalance), Microprice (size-weighted fair value), and QuotedSpread (top-of-book spread in bps). All consume the OrderBook snapshot type, emit f64, are stateless and ready after the first snapshot, with full unit coverage. Registers a new Microstructure family in the taxonomy. * feat(bindings): expose order-book microstructure indicators Python, Node, and WASM bindings for OrderBookImbalanceTop1/TopN/Full, Microprice and QuotedSpread. Each takes a depth snapshot via four equal-length (bid_px, bid_sz, ask_px, ask_sz) arrays. Python and Node expose a batch over a list of snapshots; WASM exposes per-snapshot update (the streaming model that fits a browser book feed). Regenerates node index.d.ts/.js and registers the new InvalidOrderBook/InvalidTrade arms in the Python error mapping. * test(bindings,fuzz): cover order-book microstructure indicators Python: smoke, reference values, streaming-vs-batch, lifecycle/repr and input validation (mismatched lengths, crossed book, misordered levels, zero levels) for all five order-book indicators. Node: reference values, streaming-vs-batch, and rejection cases. Adds an indicator_update_orderbook fuzz target driving every order-book indicator over arbitrary (incl. degenerate) snapshots. * bench(microstructure): synthetic order-book benchmarks Add a bench_orderbook_input harness and synthesise a five-level book around each candle close (no order-book dataset ships with the repo). Benches the cheapest (top-of-book imbalance) and most-expensive (full-depth imbalance) plus microprice, matching the curated cheapest/expensive-per-family approach. * docs: add Microstructure family + bump indicator counter to 224 README gains the Microstructure family row (order-book imbalance, microprice, quoted spread) and the indicator counter goes 219 -> 224 across seventeen families; CHANGELOG records the new order-book indicators and value types.
2026-06-01 16:06:22 +02:00
parent 498b74a5ae
commit 2be21df803
27 changed files with 2189 additions and 21 deletions
@@ -8754,6 +8754,166 @@ node_candle_pattern!(SpinningTopNode, wc::SpinningTop, "SpinningTop");
 node_candle_pattern!(ThreeInsideNode, wc::ThreeInside, "ThreeInside");
 node_candle_pattern!(ThreeOutsideNode, wc::ThreeOutside, "ThreeOutside");

+// ============================== Microstructure: Order Book ==============================
+//
+// Order-book indicators consume a depth snapshot rather than OHLCV. Streaming
+// `update(bidPx, bidSz, askPx, askSz)` takes four equal-length arrays for one
+// snapshot (bids best-first = descending price, asks best-first = ascending
+// price); `batch` takes an array of `{ bidPx, bidSz, askPx, askSz }` snapshots
+// and returns one value per snapshot.
+
+/// One order-book depth snapshot for batch evaluation.
+#[napi(object)]
+pub struct ObSnapshot {
+    pub bid_px: Vec<f64>,
+    pub bid_sz: Vec<f64>,
+    pub ask_px: Vec<f64>,
+    pub ask_sz: Vec<f64>,
+}
+
+fn build_order_book(
+    bid_px: &[f64],
+    bid_sz: &[f64],
+    ask_px: &[f64],
+    ask_sz: &[f64],
+) -> napi::Result<wc::OrderBook> {
+    if bid_px.len() != bid_sz.len() || ask_px.len() != ask_sz.len() {
+        return Err(NapiError::from_reason(
+            "bid/ask price and size arrays must be equal length".to_string(),
+        ));
+    }
+    let bids = bid_px
+        .iter()
+        .zip(bid_sz)
+        .map(|(&p, &s)| wc::Level::new_unchecked(p, s))
+        .collect();
+    let asks = ask_px
+        .iter()
+        .zip(ask_sz)
+        .map(|(&p, &s)| wc::Level::new_unchecked(p, s))
+        .collect();
+    wc::OrderBook::new(bids, asks).map_err(map_err)
+}
+
+macro_rules! node_ob_indicator {
+    ($node:ident, $inner:ty, $js:literal) => {
+        #[napi(js_name = $js)]
+        pub struct $node {
+            inner: $inner,
+        }
+
+        impl Default for $node {
+            fn default() -> Self {
+                Self::new()
+            }
+        }
+
+        #[napi]
+        impl $node {
+            #[napi(constructor)]
+            pub fn new() -> Self {
+                Self {
+                    inner: <$inner>::new(),
+                }
+            }
+            #[napi]
+            pub fn update(
+                &mut self,
+                bid_px: Vec<f64>,
+                bid_sz: Vec<f64>,
+                ask_px: Vec<f64>,
+                ask_sz: Vec<f64>,
+            ) -> napi::Result<Option<f64>> {
+                let book = build_order_book(&bid_px, &bid_sz, &ask_px, &ask_sz)?;
+                Ok(self.inner.update(book))
+            }
+            #[napi]
+            pub fn batch(&mut self, snapshots: Vec<ObSnapshot>) -> napi::Result<Vec<f64>> {
+                let mut out = Vec::with_capacity(snapshots.len());
+                for snap in &snapshots {
+                    let book =
+                        build_order_book(&snap.bid_px, &snap.bid_sz, &snap.ask_px, &snap.ask_sz)?;
+                    out.push(self.inner.update(book).unwrap_or(f64::NAN));
+                }
+                Ok(out)
+            }
+            #[napi]
+            pub fn reset(&mut self) {
+                self.inner.reset();
+            }
+            #[napi(js_name = "isReady")]
+            pub fn is_ready(&self) -> bool {
+                self.inner.is_ready()
+            }
+            #[napi(js_name = "warmupPeriod")]
+            pub fn warmup_period(&self) -> u32 {
+                self.inner.warmup_period() as u32
+            }
+        }
+    };
+}
+
+node_ob_indicator!(
+    OrderBookImbalanceTop1Node,
+    wc::OrderBookImbalanceTop1,
+    "OrderBookImbalanceTop1"
+);
+node_ob_indicator!(
+    OrderBookImbalanceFullNode,
+    wc::OrderBookImbalanceFull,
+    "OrderBookImbalanceFull"
+);
+node_ob_indicator!(MicropriceNode, wc::Microprice, "Microprice");
+node_ob_indicator!(QuotedSpreadNode, wc::QuotedSpread, "QuotedSpread");
+
+// Top-N imbalance carries a `levels` parameter, so it is hand-written.
+#[napi(js_name = "OrderBookImbalanceTopN")]
+pub struct OrderBookImbalanceTopNNode {
+    inner: wc::OrderBookImbalanceTopN,
+}
+
+#[napi]
+impl OrderBookImbalanceTopNNode {
+    #[napi(constructor)]
+    pub fn new(levels: u32) -> napi::Result<Self> {
+        Ok(Self {
+            inner: wc::OrderBookImbalanceTopN::new(levels as usize).map_err(map_err)?,
+        })
+    }
+    #[napi]
+    pub fn update(
+        &mut self,
+        bid_px: Vec<f64>,
+        bid_sz: Vec<f64>,
+        ask_px: Vec<f64>,
+        ask_sz: Vec<f64>,
+    ) -> napi::Result<Option<f64>> {
+        let book = build_order_book(&bid_px, &bid_sz, &ask_px, &ask_sz)?;
+        Ok(self.inner.update(book))
+    }
+    #[napi]
+    pub fn batch(&mut self, snapshots: Vec<ObSnapshot>) -> napi::Result<Vec<f64>> {
+        let mut out = Vec::with_capacity(snapshots.len());
+        for snap in &snapshots {
+            let book = build_order_book(&snap.bid_px, &snap.bid_sz, &snap.ask_px, &snap.ask_sz)?;
+            out.push(self.inner.update(book).unwrap_or(f64::NAN));
+        }
+        Ok(out)
+    }
+    #[napi]
+    pub fn reset(&mut self) {
+        self.inner.reset();
+    }
+    #[napi(js_name = "isReady")]
+    pub fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    #[napi(js_name = "warmupPeriod")]
+    pub fn warmup_period(&self) -> u32 {
+        self.inner.warmup_period() as u32
+    }
+}
+
 // ============================== Family 15: Risk / Performance ==============================

 // Risk metrics with fallible `new` (most need `period >= 2`), so each wrapper