@363045841yyt/klinechart-core 0.8.11-alpha.0 → 0.8.12

package/src/components/footprint/__tests__/controller.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Footprint controller integration tests — trade ingestion, bar bucketing,
+ * classifier composition, cumulativeDelta wiring, dispose semantics.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { createFootprintController } from '../createFootprintController'
+import type { FootprintController, FootprintConfig } from '../types'
+
+const baseConfig: FootprintConfig = {
+    tickSize: 0.01,
+    barIntervalMs: 60_000, // 1m bars
+    imbalanceRatio: 3,
+    fallbackClassifier: 'tick-rule',
+}
+
+function makeController(patch: Partial<FootprintConfig> = {}): FootprintController {
+    return createFootprintController({ ...baseConfig, ...patch })
+}
+
+describe('createFootprintController — single trade ingestion', () => {
+    it('single explicit-flag trade → 1 bar, 1 cell with correct direction', () => {
+        const c = makeController()
+        c.ingestTrade({ timestamp: 1_000_000, price: 100.05, size: 10, isBuyerMaker: false })
+        // buy aggressor → askVol increments at the quantized price
+        const bars = c.bars()
+        expect(bars).toHaveLength(1)
+        expect(bars[0]?.cells).toHaveLength(1)
+        const cell = bars[0]!.cells[0]!
+        expect(cell.price).toBeCloseTo(100.05, 6)
+        expect(cell.askVol).toBe(10)
+        expect(cell.bidVol).toBe(0)
+    })
+
+    it('same-bar trades at same price → cells aggregate', () => {
+        const c = makeController()
+        c.ingestTrade({ timestamp: 1_000_000, price: 100.05, size: 10, isBuyerMaker: false })
+        c.ingestTrade({ timestamp: 1_000_500, price: 100.05, size: 5, isBuyerMaker: true })
+        const bars = c.bars()
+        expect(bars).toHaveLength(1)
+        const cell = bars[0]!.cells[0]!
+        expect(cell.askVol).toBe(10) // first trade buy
+        expect(cell.bidVol).toBe(5) // second trade sell
+    })
+
+    it('crossing the bar interval boundary → new bar', () => {
+        const c = makeController({ barIntervalMs: 1000 })
+        c.ingestTrade({ timestamp: 1_000_000, price: 100, size: 10, isBuyerMaker: false })
+        c.ingestTrade({ timestamp: 1_001_000, price: 100, size: 10, isBuyerMaker: false })
+        const bars = c.bars()
+        expect(bars).toHaveLength(2)
+    })
+})
+
+describe('createFootprintController — classifier fallback chain', () => {
+    it('uses explicit flag when present, ignoring fallbackClassifier', () => {
+        const c = makeController({ fallbackClassifier: 'tick-rule' })
+        c.ingestTrade({ timestamp: 1_000_000, price: 100, size: 5, isBuyerMaker: true })
+        // explicit says sell aggressor → bidVol += 5
+        const cell = c.bars()[0]!.cells[0]!
+        expect(cell.bidVol).toBe(5)
+        expect(cell.askVol).toBe(0)
+    })
+
+    it('falls back to tick rule when flag is absent', () => {
+        const c = makeController({ fallbackClassifier: 'tick-rule' })
+        // first trade → tick rule returns unknown; controller drops it from aggregate
+        c.ingestTrade({ timestamp: 1_000_000, price: 100, size: 5 })
+        c.ingestTrade({ timestamp: 1_000_100, price: 101, size: 5 }) // uptick → buy
+        // The first trade was unknown (dropped). The second is buy at price 101.
+        const cells = c.bars()[0]!.cells
+        const cellAt101 = cells.find((x) => Math.abs(x.price - 101) < 1e-6)
+        expect(cellAt101?.askVol).toBe(5)
+    })
+
+    it('Lee-Ready fallback uses bid/ask when provided', () => {
+        const c = makeController({ fallbackClassifier: 'lee-ready' })
+        c.ingestTrade({ timestamp: 1_000_000, price: 100.6, size: 5 }, 100, 101)
+        // mid = 100.5, price > mid → buy
+        const cell = c.bars()[0]!.cells[0]!
+        expect(cell.askVol).toBe(5)
+    })
+})
+
+describe('createFootprintController — derived stats', () => {
+    it('bar.delta updates as trades accumulate', () => {
+        const c = makeController()
+        c.ingestTrade({ timestamp: 1_000_000, price: 100, size: 10, isBuyerMaker: false })
+        c.ingestTrade({ timestamp: 1_000_100, price: 100, size: 4, isBuyerMaker: true })
+        const bar = c.bars()[0]!
+        expect(bar.delta).toBe(6) // 10 ask - 4 bid
+        expect(bar.totalVolume).toBe(14)
+    })
+
+    it('cumulativeDelta signal emits running sum across bars', () => {
+        const c = makeController({ barIntervalMs: 1000 })
+        c.ingestTrade({ timestamp: 1_000_000, price: 100, size: 10, isBuyerMaker: false }) // +10
+        c.ingestTrade({ timestamp: 1_001_000, price: 100, size: 4, isBuyerMaker: true }) //  -4
+        c.ingestTrade({ timestamp: 1_002_000, price: 100, size: 8, isBuyerMaker: false }) // +8
+        expect(c.cumulativeDelta()).toEqual([10, 6, 14])
+    })
+})
+
+describe('createFootprintController — config + lifecycle', () => {
+    it('setConfig with new barIntervalMs invalidates existing bars', () => {
+        const c = makeController({ barIntervalMs: 60_000 })
+        c.ingestTrade({ timestamp: 1_000_000, price: 100, size: 5, isBuyerMaker: false })
+        expect(c.bars()).toHaveLength(1)
+        c.setConfig({ barIntervalMs: 1000 })
+        expect(c.bars()).toHaveLength(0)
+    })
+
+    it('reset clears all bars and cumulativeDelta', () => {
+        const c = makeController()
+        c.ingestTrade({ timestamp: 1_000_000, price: 100, size: 5, isBuyerMaker: false })
+        c.reset()
+        expect(c.bars()).toEqual([])
+        expect(c.cumulativeDelta()).toEqual([])
+    })
+
+    it('dispose silences subsequent mutators and signal emissions', () => {
+        const c = makeController()
+        const listener = vi.fn()
+        c.bars.subscribe(listener)
+        c.dispose()
+        c.ingestTrade({ timestamp: 1_000_000, price: 100, size: 5, isBuyerMaker: false })
+        expect(listener).not.toHaveBeenCalled()
+        expect(c.bars()).toEqual([])
+    })
+})

package/src/components/footprint/__tests__/perBarStats.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Per-bar statistics tests — delta / cumulativeDelta / diagonal imbalance.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+    computeDelta,
+    computeCumulativeDelta,
+    computeDiagonalImbalances,
+    type FootprintBarCell,
+} from '../perBarStats'
+
+const cell = (price: number, askVol: number, bidVol: number): FootprintBarCell => ({
+    price,
+    askVol,
+    bidVol,
+})
+
+describe('computeDelta', () => {
+    it('pure buy bar → positive delta equals total ask volume', () => {
+        const cells = [cell(100, 50, 0), cell(101, 30, 0)]
+        expect(computeDelta(cells)).toBe(80)
+    })
+
+    it('pure sell bar → negative delta', () => {
+        const cells = [cell(100, 0, 50), cell(101, 0, 30)]
+        expect(computeDelta(cells)).toBe(-80)
+    })
+
+    it('balanced bar → 0', () => {
+        const cells = [cell(100, 25, 25), cell(101, 25, 25)]
+        expect(computeDelta(cells)).toBe(0)
+    })
+
+    it('empty cells → 0', () => {
+        expect(computeDelta([])).toBe(0)
+    })
+})
+
+describe('computeCumulativeDelta', () => {
+    it('all positive deltas → strictly monotonic increasing', () => {
+        expect(computeCumulativeDelta([10, 20, 30])).toEqual([10, 30, 60])
+    })
+
+    it('mixed signs → correct running sum', () => {
+        expect(computeCumulativeDelta([10, -5, 8, -3])).toEqual([10, 5, 13, 10])
+    })
+
+    it('empty input → []', () => {
+        expect(computeCumulativeDelta([])).toEqual([])
+    })
+
+    it('single delta → [delta]', () => {
+        expect(computeCumulativeDelta([42])).toEqual([42])
+    })
+})
+
+describe('computeDiagonalImbalances', () => {
+    it('buy imbalance detected when ask[i] >= 3 * bid[i-1] and bid[i-1] > 0', () => {
+        // cells sorted ascending: i=0 at price 100, i=1 at price 101
+        // ask[1]=30, bid[0]=10 → ratio 3, triggers
+        const cells = [cell(100, 5, 10), cell(101, 30, 5)]
+        const imb = computeDiagonalImbalances(cells, 3)
+        const buy = imb.find((x) => x.direction === 'buy-imbalance')
+        expect(buy).toBeDefined()
+        expect(buy?.priceIndex).toBe(1)
+        expect(buy?.ratio).toBeCloseTo(3, 6)
+    })
+
+    it('NOT triggered at ratio 2.9x', () => {
+        const cells = [cell(100, 5, 10), cell(101, 29, 5)]
+        const imb = computeDiagonalImbalances(cells, 3)
+        expect(imb.find((x) => x.direction === 'buy-imbalance')).toBeUndefined()
+    })
+
+    it('sell imbalance detected when bid[i] >= 3 * ask[i+1] and ask[i+1] > 0', () => {
+        const cells = [cell(100, 5, 30), cell(101, 10, 5)]
+        // bid[0]=30, ask[1]=10 → ratio 3, sell imbalance at i=0
+        const imb = computeDiagonalImbalances(cells, 3)
+        const sell = imb.find((x) => x.direction === 'sell-imbalance')
+        expect(sell).toBeDefined()
+        expect(sell?.priceIndex).toBe(0)
+        expect(sell?.ratio).toBeCloseTo(3, 6)
+    })
+
+    it('handles boundary cells without crashing (no neighbour above for last, below for first)', () => {
+        const cells = [cell(100, 10, 10)]
+        expect(() => computeDiagonalImbalances(cells, 3)).not.toThrow()
+        expect(computeDiagonalImbalances(cells, 3)).toEqual([])
+    })
+
+    it('cell with zero bid/ask does not trigger imbalance (divide-by-zero guard)', () => {
+        const cells = [cell(100, 0, 0), cell(101, 100, 0)]
+        // bid[0]=0 means we can't compute ask[1]/bid[0] → no buy imbalance
+        const imb = computeDiagonalImbalances(cells, 3)
+        expect(imb.find((x) => x.direction === 'buy-imbalance')).toBeUndefined()
+    })
+
+    it('multiple imbalances in one bar are all reported', () => {
+        const cells = [
+            cell(100, 5, 10),
+            cell(101, 100, 5), // buy imb at 1 (100 / 10 = 10x)
+            cell(102, 5, 100), // sell imb at 2 (next ask=10? need cell 3); test:
+            cell(103, 10, 5), // sell imb at 2: bid[2]=100, ask[3]=10 → 10x
+        ]
+        const imb = computeDiagonalImbalances(cells, 3)
+        expect(imb.some((x) => x.direction === 'buy-imbalance' && x.priceIndex === 1)).toBe(true)
+        expect(imb.some((x) => x.direction === 'sell-imbalance' && x.priceIndex === 2)).toBe(true)
+    })
+
+    it('empty cells → empty imbalances', () => {
+        expect(computeDiagonalImbalances([], 3)).toEqual([])
+    })
+})

package/src/components/footprint/aggressor.ts

@@ -0,0 +1,165 @@
+/**
+ * Aggressor classification — three heuristics for tagging a print as
+ * buyer-initiated ("buy", aggressor lifted the ASK) or seller-initiated
+ * ("sell", aggressor hit the BID).
+ *
+ * Future hook: Bulk Volume Classification (BVC) by Easley/Lopez de Prado/O'Hara
+ * 2012 is more robust in HFT-fragmented markets where the tick rule's serial
+ * correlation assumptions break. BVC is planned as a v2 classifier under the
+ * same `AggressorResult` interface.
+ *
+ * Each classifier exports the same `AggressorResult` shape so the controller
+ * can compose them in a fallback chain (explicit → heuristic) without
+ * branching on classifier identity.
+ *
+ * See `docs/ROADMAP.md` §3.3 for the rationale — order of preference is
+ * always explicit > Lee-Ready > tick rule.
+ */
+
+import type { AggressorSide, Trade, TradeWithFlag } from './types'
+
+/**
+ * Output of every classifier.
+ *
+ * `side` is `'unknown'` only when there is genuinely no information to act
+ * on (e.g. the first trade in a tick-rule sequence). The controller should
+ * treat `'unknown'` as "drop this trade from the aggregate", NOT as a
+ * silent default to 'buy' or 'sell'.
+ *
+ * `inferred=false` means the side came from an exchange flag (zero error).
+ * `inferred=true` means it was estimated; downstream UI should mark such
+ * bars as approximate.
+ */
+export type { AggressorSide, Trade, TradeWithFlag }
+export interface AggressorResult {
+    side: AggressorSide | 'unknown'
+    inferred: boolean
+}
+
+// ---------------------------------------------------------------------------
+// 1. Explicit (exchange-provided flag)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read Binance-style `isBuyerMaker`. When the buyer is the maker (passive),
+ * the seller was the aggressor — so we report `'sell'`. When the buyer is
+ * NOT the maker, the buyer was the aggressor — `'buy'`.
+ *
+ * Returns `null` (not an `AggressorResult`) when the flag is missing so the
+ * caller can distinguish "no data" from "we classified it as unknown". This
+ * lets the controller fall back to the configured heuristic only when truly
+ * needed.
+ */
+export function classifyExplicit(
+    trade: TradeWithFlag,
+): AggressorResult | null {
+    if (trade.isBuyerMaker === undefined) return null
+    return {
+        side: trade.isBuyerMaker ? 'sell' : 'buy',
+        inferred: false,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 2. Tick rule
+// ---------------------------------------------------------------------------
+
+/**
+ * State carried across consecutive trades for the tick rule. The classifier
+ * MUTATES this in place — callers should keep one instance per stream
+ * (per-symbol if multiplexing).
+ */
+export interface TickRuleState {
+    prevPrice: number | null
+    prevSide: AggressorSide | null
+}
+
+/**
+ * Classic tick test (Lee & Ready 1991 §2):
+ *
+ *   price > prevPrice → 'buy'     (uptick)
+ *   price < prevPrice → 'sell'    (downtick)
+ *   price == prevPrice → repeats prevSide  (zero-tick)
+ *   first trade (prevPrice null) → 'unknown'
+ *
+ * The state is MUTATED so subsequent calls inherit the running context.
+ */
+export function classifyTickRule(
+    state: TickRuleState,
+    trade: Trade,
+): AggressorResult {
+    const prev = state.prevPrice
+    let side: AggressorSide | 'unknown'
+
+    if (prev === null) {
+        side = 'unknown'
+    } else if (trade.price > prev) {
+        side = 'buy'
+    } else if (trade.price < prev) {
+        side = 'sell'
+    } else {
+        // zero-tick: inherit previous decision; 'unknown' if no prior side.
+        side = state.prevSide ?? 'unknown'
+    }
+
+    // Update running state. We commit a known side; we deliberately do NOT
+    // overwrite `prevSide` with 'unknown', otherwise a single missing-price
+    // trade would poison the carry-over for the rest of the stream.
+    state.prevPrice = trade.price
+    if (side === 'buy' || side === 'sell') state.prevSide = side
+
+    return { side, inferred: true }
+}
+
+// ---------------------------------------------------------------------------
+// 3. Lee-Ready (quote-rule with tick-rule tiebreak)
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee-Ready uses the same carry-over fields as the tick rule — the two
+ * heuristics can share a single state record because Lee-Ready falls back
+ * to the tick rule on a quote-mid hit.
+ */
+export interface LeeReadyState extends TickRuleState {}
+
+/**
+ * Lee-Ready (1991) quote test:
+ *
+ *   If bid and ask are both finite:
+ *     mid = (bid + ask) / 2
+ *     price > mid → 'buy'
+ *     price < mid → 'sell'
+ *     price == mid → tick-rule fallback (zero spread or mid-cross)
+ *   Else (bid/ask missing or non-finite) → tick-rule fallback.
+ *
+ * The state MUTATES exactly like `classifyTickRule` — when the quote test
+ * resolves, we still update `prevPrice`/`prevSide` so a subsequent
+ * tick-rule fallback has the latest context.
+ */
+export function classifyLeeReady(
+    state: LeeReadyState,
+    trade: Trade,
+    bid: number,
+    ask: number,
+): AggressorResult {
+    const quotesUsable = Number.isFinite(bid) && Number.isFinite(ask)
+
+    if (!quotesUsable) {
+        return classifyTickRule(state, trade)
+    }
+
+    const mid = (bid + ask) / 2
+
+    if (trade.price > mid) {
+        state.prevPrice = trade.price
+        state.prevSide = 'buy'
+        return { side: 'buy', inferred: true }
+    }
+    if (trade.price < mid) {
+        state.prevPrice = trade.price
+        state.prevSide = 'sell'
+        return { side: 'sell', inferred: true }
+    }
+    // price == mid → fall back to tick rule (which updates state).
+    return classifyTickRule(state, trade)
+}