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

package/src/data-fetchers/__tests__/depthConnector.test.ts

@@ -0,0 +1,259 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { DepthConnector } from '../depthConnector'
+import type { DepthDelta, DepthSnapshot, DepthSource, DepthSourceStatus } from '../depthTypes'
+import type { HeatmapController, HeatmapControllerConfig } from '../../components/orderBookHeatmap'
+
+// ---------------------------------------------------------------------------
+// Fake DepthSource — controllable callbacks
+// ---------------------------------------------------------------------------
+function createFakeSource(): DepthSource & {
+  triggerDelta: (deltas: ReadonlyArray<DepthDelta>) => void
+  triggerSnapshot: (snap: DepthSnapshot) => void
+  triggerError: (err: Error) => void
+  triggerStatus: (s: DepthSourceStatus) => void
+} {
+  const deltaCbs: Array<(d: ReadonlyArray<DepthDelta>) => void> = []
+  const snapshotCbs: Array<(s: DepthSnapshot) => void> = []
+  const errorCbs: Array<(e: Error) => void> = []
+  const statusCbs: Array<(s: DepthSourceStatus) => void> = []
+
+  return {
+    exchange: 'test',
+    symbol: 'test-symbol',
+    onDelta: (cb) => {
+      deltaCbs.push(cb)
+      return () => {
+        const idx = deltaCbs.indexOf(cb)
+        if (idx >= 0) deltaCbs.splice(idx, 1)
+      }
+    },
+    onSnapshot: (cb) => {
+      snapshotCbs.push(cb)
+      return () => {
+        const idx = snapshotCbs.indexOf(cb)
+        if (idx >= 0) snapshotCbs.splice(idx, 1)
+      }
+    },
+    onError: (cb) => {
+      errorCbs.push(cb)
+      return () => {
+        const idx = errorCbs.indexOf(cb)
+        if (idx >= 0) errorCbs.splice(idx, 1)
+      }
+    },
+    onStatus: (cb) => {
+      statusCbs.push(cb)
+      return () => {
+        const idx = statusCbs.indexOf(cb)
+        if (idx >= 0) statusCbs.splice(idx, 1)
+      }
+    },
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+    destroy: vi.fn(),
+    triggerDelta: (deltas) => {
+      for (const cb of deltaCbs) cb(deltas)
+    },
+    triggerSnapshot: (snap) => {
+      for (const cb of snapshotCbs) cb(snap)
+    },
+    triggerError: (err) => {
+      for (const cb of errorCbs) cb(err)
+    },
+    triggerStatus: (s) => {
+      for (const cb of statusCbs) cb(s)
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fake HeatmapController
+// ---------------------------------------------------------------------------
+function createFakeController(): HeatmapController & {
+  calls: { ingest: DepthDelta[]; resetBook: DepthSnapshot[] }
+} {
+  const calls: { ingest: DepthDelta[]; resetBook: DepthSnapshot[] } = {
+    ingest: [],
+    resetBook: [],
+  }
+  return {
+    state: null as never,
+    ingest: (d: DepthDelta) => calls.ingest.push(d),
+    ingestDelta: () => {},
+    forceSnapshot: () => {},
+    replay: () => [],
+    resetBook: (s: DepthSnapshot) => calls.resetBook.push(s),
+    setConfig: () => {},
+    dispose: vi.fn(),
+    calls,
+  }
+}
+
+describe('DepthConnector', () => {
+  let source: ReturnType<typeof createFakeSource>
+  let connector: DepthConnector
+
+  beforeEach(() => {
+    source = createFakeSource()
+    connector = new DepthConnector(source)
+  })
+
+  describe('start / stop', () => {
+    it('start() subscribes to source events and calls source.connect()', () => {
+      connector.start()
+      expect(source.connect).toHaveBeenCalledOnce()
+    })
+
+    it('start() is idempotent — second call does nothing', () => {
+      connector.start()
+      connector.start()
+      expect(source.connect).toHaveBeenCalledOnce()
+    })
+
+    it('stop() unsubscribes and calls source.disconnect()', () => {
+      connector.start()
+      connector.stop()
+      expect(source.disconnect).toHaveBeenCalledOnce()
+    })
+
+    it('stop() is idempotent', () => {
+      connector.stop()
+      connector.stop()
+      expect(source.disconnect).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('delta forwarding', () => {
+    it('forwards deltas from source to controller.ingest()', () => {
+      const ctrl = createFakeController()
+      connector.addController(ctrl)
+      connector.start()
+
+      const d1: DepthDelta = { side: 'bid', price: 100, size: 5, timestamp: 1000 }
+      const d2: DepthDelta = { side: 'ask', price: 101, size: 3, timestamp: 1000 }
+      source.triggerDelta([d1, d2])
+
+      expect(ctrl.calls.ingest).toEqual([d1, d2])
+      connector.destroy()
+    })
+
+    it('forwards deltas to all controllers', () => {
+      const ctrl1 = createFakeController()
+      const ctrl2 = createFakeController()
+      connector.addController(ctrl1)
+      connector.addController(ctrl2)
+      connector.start()
+
+      const d: DepthDelta = { side: 'bid', price: 100, size: 1, timestamp: 1 }
+      source.triggerDelta([d])
+
+      expect(ctrl1.calls.ingest).toEqual([d])
+      expect(ctrl2.calls.ingest).toEqual([d])
+      connector.destroy()
+    })
+
+    it('removed controller stops receiving deltas', () => {
+      const ctrl1 = createFakeController()
+      const ctrl2 = createFakeController()
+      connector.addController(ctrl1)
+      connector.addController(ctrl2)
+      connector.start()
+
+      const d1: DepthDelta = { side: 'bid', price: 100, size: 1, timestamp: 1 }
+      source.triggerDelta([d1])
+      expect(ctrl1.calls.ingest).toHaveLength(1)
+
+      connector.removeController(ctrl1)
+      const d2: DepthDelta = { side: 'ask', price: 101, size: 1, timestamp: 2 }
+      source.triggerDelta([d2])
+      expect(ctrl1.calls.ingest).toHaveLength(1)
+      expect(ctrl2.calls.ingest).toHaveLength(2)
+      connector.destroy()
+    })
+  })
+
+  describe('snapshot forwarding', () => {
+    it('forwards snapshot from source to controller.resetBook()', () => {
+      const ctrl = createFakeController()
+      connector.addController(ctrl)
+      connector.start()
+
+      const snap: DepthSnapshot = { bids: [[100, 5]], asks: [[101, 3]], timestamp: 5000 }
+      source.triggerSnapshot(snap)
+
+      expect(ctrl.calls.resetBook).toEqual([snap])
+      connector.destroy()
+    })
+
+    it('forwards snapshot to all controllers', () => {
+      const ctrl1 = createFakeController()
+      const ctrl2 = createFakeController()
+      connector.addController(ctrl1)
+      connector.addController(ctrl2)
+      connector.start()
+
+      const snap: DepthSnapshot = { bids: [[100, 5]], asks: [], timestamp: 1 }
+      source.triggerSnapshot(snap)
+
+      expect(ctrl1.calls.resetBook).toHaveLength(1)
+      expect(ctrl2.calls.resetBook).toHaveLength(1)
+      connector.destroy()
+    })
+  })
+
+  describe('error handling', () => {
+    it('catches source errors without throwing (logs to console)', () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+      connector.start()
+      source.triggerError(new Error('test error'))
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('[DepthConnector] test test-symbol:'),
+        expect.stringContaining('test error'),
+      )
+      consoleSpy.mockRestore()
+      connector.destroy()
+    })
+  })
+
+  describe('destroy', () => {
+    it('destroy() stops connector and disposes all controllers and source', () => {
+      const ctrl1 = createFakeController()
+      const ctrl2 = createFakeController()
+      connector.addController(ctrl1)
+      connector.addController(ctrl2)
+      connector.start()
+
+      connector.destroy()
+
+      expect(source.disconnect).toHaveBeenCalled()
+      expect(ctrl1.dispose).toHaveBeenCalledOnce()
+      expect(ctrl2.dispose).toHaveBeenCalledOnce()
+      expect(source.destroy).toHaveBeenCalledOnce()
+      expect(connector.getControllerCount()).toBe(0)
+    })
+  })
+
+  describe('addController before start', () => {
+    it('controllers added before start still receive events', () => {
+      const ctrl = createFakeController()
+      connector.addController(ctrl)
+      connector.start()
+
+      source.triggerDelta([{ side: 'bid', price: 100, size: 1, timestamp: 1 }])
+      expect(ctrl.calls.ingest).toHaveLength(1)
+      connector.destroy()
+    })
+  })
+
+  describe('getControllerCount', () => {
+    it('reports correct controller count', () => {
+      expect(connector.getControllerCount()).toBe(0)
+      connector.addController(createFakeController())
+      expect(connector.getControllerCount()).toBe(1)
+      connector.addController(createFakeController())
+      expect(connector.getControllerCount()).toBe(2)
+      connector.destroy()
+      expect(connector.getControllerCount()).toBe(0)
+    })
+  })
+})

package/src/data-fetchers/__tests__/fetcherRegistry.test.ts

@@ -49,7 +49,9 @@ describe('DataFetcher registry', () => {
 
   it('fetcherSupportsPeriod returns true for exact match', () => {
     @DataFetcher({ name: 'test', displayName: 'Test', capabilities: ['daily', 'weekly'] })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
     expect(fetcherSupportsPeriod('test', 'daily')).toBe(true)
@@ -58,7 +60,9 @@ describe('DataFetcher registry', () => {
 
   it('fetcherSupportsPeriod returns false for unsupported period', () => {
     @DataFetcher({ name: 'test', displayName: 'Test', capabilities: ['weekly'] })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
     expect(fetcherSupportsPeriod('test', 'daily')).toBe(false)
@@ -67,7 +71,9 @@ describe('DataFetcher registry', () => {
 
   it('fetcherSupportsPeriod accepts wildcard * for any period', () => {
     @DataFetcher({ name: 'test', displayName: 'Test', capabilities: ['*'] })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
     expect(fetcherSupportsPeriod('test', 'daily')).toBe(true)
@@ -77,7 +83,9 @@ describe('DataFetcher registry', () => {
 
   it('fetcherSupportsPeriod returns false for empty capabilities', () => {
     @DataFetcher({ name: 'test', displayName: 'Test', capabilities: [] })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
     expect(fetcherSupportsPeriod('test', 'daily')).toBe(false)
@@ -85,7 +93,9 @@ describe('DataFetcher registry', () => {
 
   it('fetcherSupportsPeriod returns false when capabilities not set', () => {
     @DataFetcher({ name: 'test', displayName: 'Test' })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
     expect(fetcherSupportsPeriod('test', 'daily')).toBe(false)
@@ -97,7 +107,9 @@ describe('DataFetcher registry', () => {
 
   it('clearRegisteredFetchersForTest removes all definitions', () => {
     @DataFetcher({ name: 'test', displayName: 'Test', capabilities: ['daily'] })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
     expect(getRegisteredFetcher('test')).toBeDefined()
@@ -113,11 +125,15 @@ describe('routerDataFetcher capability check', () => {
   })
 
   it('passes through request when period is supported', async () => {
-    const data: KLineData[] = [{ timestamp: 1000, open: 100, high: 110, low: 90, close: 105, volume: 1000 }]
+    const data: KLineData[] = [
+      { timestamp: 1000, open: 100, high: 110, low: 90, close: 105, volume: 1000 },
+    ]
     mockFetch.mockResolvedValue(data)
 
     @DataFetcher({ name: 'test', displayName: 'Test', capabilities: ['daily'] })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
     const result = await routerDataFetcher('test', defaultConfig)
@@ -126,11 +142,15 @@ describe('routerDataFetcher capability check', () => {
   })
 
   it('passes through request when capabilities are wildcard', async () => {
-    const data: KLineData[] = [{ timestamp: 1000, open: 100, high: 110, low: 90, close: 105, volume: 1000 }]
+    const data: KLineData[] = [
+      { timestamp: 1000, open: 100, high: 110, low: 90, close: 105, volume: 1000 },
+    ]
     mockFetch.mockResolvedValue(data)
 
     @DataFetcher({ name: 'test', displayName: 'Test', capabilities: ['*'] })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
     const result = await routerDataFetcher('test', { ...defaultConfig, period: '5min' })
@@ -139,54 +159,69 @@ describe('routerDataFetcher capability check', () => {
 
   it('throws when period is not in capabilities', async () => {
     @DataFetcher({ name: 'test', displayName: 'Test', capabilities: ['weekly'] })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
-    await expect(
-      routerDataFetcher('test', defaultConfig),
-    ).rejects.toThrow(/does not support period/)
+    await expect(routerDataFetcher('test', defaultConfig)).rejects.toThrow(
+      /does not support period/,
+    )
   })
 
   it('throws with error message listing supported capabilities', async () => {
     @DataFetcher({ name: 'test', displayName: 'Test', capabilities: ['weekly', 'monthly'] })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
-    await expect(
-      routerDataFetcher('test', { ...defaultConfig, period: '5min' }),
-    ).rejects.toThrow(/weekly, monthly/)
+    await expect(routerDataFetcher('test', { ...defaultConfig, period: '5min' })).rejects.toThrow(
+      /weekly, monthly/,
+    )
   })
 
   it('throws when capabilities is empty array', async () => {
     @DataFetcher({ name: 'test', displayName: 'Test', capabilities: [] })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
-    await expect(
-      routerDataFetcher('test', defaultConfig),
-    ).rejects.toThrow(/does not support period/)
+    await expect(routerDataFetcher('test', defaultConfig)).rejects.toThrow(
+      /does not support period/,
+    )
   })
 
   it('throws when capabilities is not set', async () => {
     @DataFetcher({ name: 'test', displayName: 'Test' })
-    class TestFetcher { static fetcher = fetchFn }
+    class TestFetcher {
+      static fetcher = fetchFn
+    }
     void TestFetcher
 
-    await expect(
-      routerDataFetcher('test', defaultConfig),
-    ).rejects.toThrow(/does not support period/)
+    await expect(routerDataFetcher('test', defaultConfig)).rejects.toThrow(
+      /does not support period/,
+    )
   })
 
   it('falls back to registered baostock for unknown source', async () => {
-    const data: KLineData[] = [{ timestamp: 2000, open: 200, high: 210, low: 190, close: 205, volume: 2000 }]
+    const data: KLineData[] = [
+      { timestamp: 2000, open: 200, high: 210, low: 190, close: 205, volume: 2000 },
+    ]
     const baostockFn = vi.fn<DataFetcherFn>().mockResolvedValue(data)
 
     @DataFetcher({ name: 'baostock', displayName: 'BaoStock', capabilities: ['*'] })
-    class BaoStockStub { static fetcher = baostockFn }
+    class BaoStockStub {
+      static fetcher = baostockFn
+    }
     void BaoStockStub
 
     const result = await routerDataFetcher('nonexistent', defaultConfig)
     expect(result).toBe(data)
-    expect(baostockFn).toHaveBeenCalledWith('nonexistent', expect.objectContaining({ period: 'daily' }))
+    expect(baostockFn).toHaveBeenCalledWith(
+      'nonexistent',
+      expect.objectContaining({ period: 'daily' }),
+    )
   })
 })

package/src/data-fetchers/baostock.ts

@@ -28,7 +28,10 @@ async function fetchBaoStock(
   try {
     const res = await fetch(url)
     if (!res.ok) {
-      throw new KLineChartError('FETCH_FAILED', `[baostock] fetch failed: ${res.status} ${res.statusText}`)
+      throw new KLineChartError(
+        'FETCH_FAILED',
+        `[baostock] fetch failed: ${res.status} ${res.statusText}`,
+      )
     }
     const json = await res.json()
     return (json.data ?? json).map(

package/src/data-fetchers/binance.ts

@@ -0,0 +1,130 @@
+import { KLineChartError } from '../errors'
+import type { DepthDelta, DepthSnapshot, DepthSource, DepthSourceStatus } from './depthTypes'
+
+export const DEFAULT_BINANCE_SSE_URL = 'http://localhost:8081/api/biance/depth-events'
+
+/**
+ * SSE-based depth source for Binance.
+ *
+ * Connects to the Go backend's SSE endpoint, which internally proxies
+ * Binance's WebSocket `depthUpdate` stream and pushes deltas as SSE events.
+ *
+ * EventSource natively handles reconnection — no manual reconnect logic needed.
+ */
+export class BinanceSSESource implements DepthSource {
+  readonly exchange = 'binance'
+
+  private es: EventSource | null = null
+  private deltaCbs = new Set<(deltas: ReadonlyArray<DepthDelta>) => void>()
+  private snapshotCbs = new Set<(snapshot: DepthSnapshot) => void>()
+  private statusCbs = new Set<(status: DepthSourceStatus) => void>()
+  private errorCbs = new Set<(err: Error) => void>()
+  private destroyed = false
+
+  constructor(
+    readonly symbol: string,
+    private readonly baseUrl: string = DEFAULT_BINANCE_SSE_URL,
+    private readonly esFactory?: (url: string) => EventSource,
+  ) {}
+
+  private get url(): string {
+    return `${this.baseUrl}?symbol=${this.symbol}`
+  }
+
+  onDelta(cb: (deltas: ReadonlyArray<DepthDelta>) => void): () => void {
+    this.deltaCbs.add(cb)
+    return () => this.deltaCbs.delete(cb)
+  }
+
+  onSnapshot(cb: (snapshot: DepthSnapshot) => void): () => void {
+    this.snapshotCbs.add(cb)
+    return () => this.snapshotCbs.delete(cb)
+  }
+
+  onStatus(cb: (status: DepthSourceStatus) => void): () => void {
+    this.statusCbs.add(cb)
+    return () => this.statusCbs.delete(cb)
+  }
+
+  onError(cb: (err: Error) => void): () => void {
+    this.errorCbs.add(cb)
+    return () => this.errorCbs.delete(cb)
+  }
+
+  connect(): void {
+    if (this.destroyed) return
+    this.disconnect()
+    this.emitStatus('connecting')
+
+    const factory = this.esFactory ?? ((url: string) => new EventSource(url))
+    this.es = factory(this.url)
+
+    this.es.onopen = () => {
+      if (this.destroyed) return
+      this.emitStatus('connected')
+    }
+
+    this.es.onerror = () => {
+      if (this.destroyed) return
+      this.emitStatus('disconnected')
+      // EventSource auto-reconnects — no explicit reconnect needed
+    }
+
+    this.es.onmessage = (event: MessageEvent) => {
+      if (this.destroyed) return
+      const raw = event.data as string
+      if (raw === '' || raw.startsWith(':')) return // keepalive
+
+      try {
+        const msg = JSON.parse(raw) as {
+          type: string
+          bids?: ReadonlyArray<readonly [number, number]>
+          asks?: ReadonlyArray<readonly [number, number]>
+          entries?: ReadonlyArray<DepthDelta>
+          timestamp?: number
+        }
+
+        if (msg.type === 'snapshot' && msg.bids && msg.asks && msg.timestamp !== undefined) {
+          const snapshot: DepthSnapshot = {
+            bids: msg.bids,
+            asks: msg.asks,
+            timestamp: msg.timestamp,
+          }
+          for (const cb of this.snapshotCbs) cb(snapshot)
+        } else if (msg.type === 'delta' && Array.isArray(msg.entries)) {
+          for (const cb of this.deltaCbs) cb(msg.entries)
+        }
+      } catch (e) {
+        const err =
+          e instanceof KLineChartError
+            ? e
+            : new KLineChartError(
+                'DEPTH_SOURCE_ERROR',
+                `BinanceSSE parse error: ${(e as Error).message}`,
+              )
+        for (const cb of this.errorCbs) cb(err)
+      }
+    }
+  }
+
+  disconnect(): void {
+    if (this.es) {
+      this.es.close()
+      this.es = null
+      this.emitStatus('disconnected')
+    }
+  }
+
+  destroy(): void {
+    this.destroyed = true
+    this.disconnect()
+    this.deltaCbs.clear()
+    this.snapshotCbs.clear()
+    this.statusCbs.clear()
+    this.errorCbs.clear()
+  }
+
+  private emitStatus(status: DepthSourceStatus): void {
+    for (const cb of this.statusCbs) cb(status)
+  }
+}

package/src/data-fetchers/dataBuffer.effects.ts

@@ -16,16 +16,19 @@ export class KLineFetchService extends Context.Tag('@klc/KLineFetchService')<
       endTs: number,
     ) => EffectType<ReadonlyArray<KLineData>, unknown>
   }
->() { }
+>() {}
 
 // ── TimeShare fetch service tag ──
 
 export class TimeShareFetchService extends Context.Tag('@klc/TimeShareFetchService')<
   TimeShareFetchService,
   {
-    readonly fetch: (spec: SymbolSpec, date?: number) => EffectType<ReadonlyArray<TimeShareData>, unknown>
+    readonly fetch: (
+      spec: SymbolSpec,
+      date?: number,
+    ) => EffectType<ReadonlyArray<TimeShareData>, unknown>
   }
->() { }
+>() {}
 
 // ── Constants ──
 
@@ -78,10 +81,7 @@ export const fetchKLine = (
   pipe(
     Effect.gen(function* () {
       const { fetch } = yield* KLineFetchService // 获取 Service 实例
-      const data = yield* pipe(
-        fetch(spec, startTs, endTs),
-        Effect.timeout(REQUEST_TIMEOUT),
-      )
+      const data = yield* pipe(fetch(spec, startTs, endTs), Effect.timeout(REQUEST_TIMEOUT))
       if (data.length === 0) {
         return yield* Effect.fail(
           new KLineChartError(
@@ -107,10 +107,7 @@ export const fetchTimeShare = (
   pipe(
     Effect.gen(function* () {
       const { fetch } = yield* TimeShareFetchService // 获取服务实例
-      const data = yield* pipe(
-        fetch(spec, date),
-        Effect.timeout(REQUEST_TIMEOUT),
-      )
+      const data = yield* pipe(fetch(spec, date), Effect.timeout(REQUEST_TIMEOUT))
       return data
     }),
     Effect.retry(retrySchedule),