@363045841yyt/klinechart-core 0.8.13 → 0.8.14-alpha.1

package/src/data-fetchers/dataBuffer.ts

@@ -1,8 +1,9 @@
-import { createSignal, type Signal } from '../reactivity/signal'
-import type { DataFetcher, KLineData, SymbolSpec } from '../controllers/types'
-import type { DataBufferLike } from './dataBufferTypes'
 import { Effect, pipe } from 'effect'
 import type { Effect as EffectType } from 'effect/Effect'
+
+import type { DataFetcher, KLineData, SymbolSpec } from '../controllers/types'
+import { createSignal, type Signal } from '../reactivity/signal'
+
 import {
   fetchKLine,
   KLineFetchService,
@@ -10,55 +11,31 @@ import {
   formatDate,
   MS_PER_DAY,
 } from './dataBuffer.effects'
-
-export interface DataWindow {
-  earliestTs: number
-  latestTs: number
-}
-
-function mergeSortedData(existing: KLineData[], incoming: KLineData[]): KLineData[] {
-  if (existing.length === 0) return [...incoming]
-  if (incoming.length === 0) return [...existing]
-
-  const tsSet = new Set<number>(existing.map((d) => d.timestamp))
-  const unique = incoming.filter((d) => !tsSet.has(d.timestamp))
-  if (unique.length === 0) return existing
-
-  const merged = [...existing, ...unique]
-  merged.sort((a, b) => a.timestamp - b.timestamp)
-  return merged
-}
-
-export class DataBuffer implements DataBufferLike {
-  private _data: KLineData[] = []
-  private _dataSignal: Signal<ReadonlyArray<KLineData>>
-  private _loadingSignal: Signal<boolean>
+import type { DataBufferLike, DataWindow, DataChange, KLineBuffer } from './dataBufferTypes'
+import { FetchScheduler } from './fetchScheduler'
+import { KLineDataStore } from './kLineDataStore'
+import { TimeKeyIndex } from './timeKeyIndex'
+
+export class DataBuffer implements KLineBuffer {
+  private _store = new KLineDataStore()
+  private _scheduler = new FetchScheduler()
+  private _keyIndex = new TimeKeyIndex()
   private _fetcher: DataFetcher | null = null
   private _requestFetch:
     | ((spec: SymbolSpec, startTs: number, endTs: number) => Promise<ReadonlyArray<KLineData>>)
     | null = null
   private _currentSpec: SymbolSpec | null = null
-  private _loadedWindow: DataWindow | null = null
-  private _pendingFetch: Promise<void> | null = null
-  private _disposed = false
-  // 已尝试请求过的边界时间戳集合，防止同一个时间段重复请求
   private _attemptedBoundaries: Set<number> = new Set()
-  private _monthKeys: Int32Array | null = null
-  private _dayKeys: Int32Array | null = null
-
-  onPrepend: ((count: number) => void) | null = null
+  private _disposed = false
 
-  constructor() {
-    this._dataSignal = createSignal<ReadonlyArray<KLineData>>([])
-    this._loadingSignal = createSignal<boolean>(false)
-  }
+  constructor() {}
 
-  get data(): Signal<ReadonlyArray<unknown>> {
-    return this._dataSignal as Signal<ReadonlyArray<unknown>>
+  get data(): Signal<DataChange> {
+    return this._store.data
   }
 
   get loading(): Signal<boolean> {
-    return this._loadingSignal
+    return this._scheduler.loading
   }
 
   get currentSpec(): SymbolSpec | null {
@@ -66,39 +43,19 @@ export class DataBuffer implements DataBufferLike {
   }
 
   get loadedWindow(): DataWindow | null {
-    return this._loadedWindow
+    return this._store.loadedWindow
   }
 
   getRawData(): KLineData[] {
-    return this._data
+    return this._store.getRawData()
   }
 
   getMonthKeys(): Int32Array | null {
-    return this._monthKeys
+    return this._keyIndex.monthKeys
   }
 
   getDayKeys(): Int32Array | null {
-    return this._dayKeys
-  }
-
-  private _precomputeKeys(): void {
-    const n = this._data.length
-    if (n === 0) {
-      this._monthKeys = null
-      this._dayKeys = null
-      return
-    }
-    const monthKeys = new Int32Array(n)
-    const dayKeys = new Int32Array(n)
-    for (let i = 0; i < n; i++) {
-      const d = new Date(this._data[i]!.timestamp)
-      monthKeys[i] = d.getFullYear() * 12 + d.getMonth()
-      const yearStart = new Date(d.getFullYear(), 0, 0)
-      dayKeys[i] =
-        d.getFullYear() * 366 + Math.floor((d.getTime() - yearStart.getTime()) / 86400000)
-    }
-    this._monthKeys = monthKeys
-    this._dayKeys = dayKeys
+    return this._keyIndex.dayKeys
   }
 
   setFetcher(fetcher: DataFetcher | null): void {
@@ -115,16 +72,14 @@ export class DataBuffer implements DataBufferLike {
 
   setSymbol(spec: SymbolSpec, initialStartTs?: number): void {
     this._currentSpec = spec
-    this._data = []
-    this._loadedWindow = null
+    this._store.reset()
+    this._scheduler.reset()
+    this._keyIndex.reset()
     this._attemptedBoundaries.clear()
-    this._monthKeys = null
-    this._dayKeys = null
-    this._dataSignal.set([])
     if (initialStartTs !== undefined) {
-      this.loadInitialRange(initialStartTs, Date.now())
+      this._loadInitialRange(initialStartTs, Date.now())
     } else {
-      this.loadInitial()
+      this._loadInitial()
     }
   }
 
@@ -132,171 +87,119 @@ export class DataBuffer implements DataBufferLike {
     if (this._disposed || (!this._requestFetch && !this._fetcher) || !this._currentSpec) return
     if (this._currentSpec.incremental === false) return
     if (!this._currentSpec.source) return
-    if (!this._loadedWindow) return
+    const window = this._store.loadedWindow
+    if (!window) return
 
-    if (requestStartTs >= this._loadedWindow.earliestTs) return
-
-    const incrementalEnd = this._loadedWindow.earliestTs
+    if (requestStartTs >= window.earliestTs) return
 
+    const incrementalEnd = window.earliestTs
     if (this._attemptedBoundaries.has(incrementalEnd)) return
 
     this._attemptedBoundaries.add(incrementalEnd)
-    this.fetchRange(requestStartTs, incrementalEnd)
+    this._fetchAndMerge(requestStartTs, incrementalEnd)
+  }
+
+  setInlineData(data: unknown[]): void {
+    if (this._disposed) return
+    this._store.setInlineData(data as KLineData[])
+    this._scheduler.reset()
+    this._attemptedBoundaries.clear()
+    this._keyIndex.recompute(this._store.getRawData())
+  }
+
+  setCurrentSpec(spec: SymbolSpec): void {
+    this._currentSpec = spec
   }
 
-  private loadInitial(): void {
+  dispose(): void {
+    this._disposed = true
+    this._scheduler.dispose()
+    this._store.reset()
+    this._keyIndex.reset()
+    this._attemptedBoundaries.clear()
+  }
+
+  // ── Private ──
+
+  private _loadInitial(): void {
     if ((!this._requestFetch && !this._fetcher) || !this._currentSpec || this._disposed) return
     if (!this._currentSpec.source) return
 
     const now = Date.now()
     const days = getPeriodDays(this._currentSpec.period)
     const startDate = now - days * MS_PER_DAY
-    const endDate = now
 
-    this.fetchRange(startDate, endDate)
+    this._fetchAndMerge(startDate, now)
   }
 
-  private loadInitialRange(startTs: number, endTs: number): void {
+  private _loadInitialRange(startTs: number, endTs: number): void {
     if ((!this._requestFetch && !this._fetcher) || !this._currentSpec || this._disposed) return
     if (!this._currentSpec.source) return
-    this.fetchRange(startTs, endTs)
+    this._fetchAndMerge(startTs, endTs)
   }
 
-  private fetchRange(startTs: number, endTs: number): void {
+  private _fetchAndMerge(startTs: number, endTs: number): void {
     if ((!this._requestFetch && !this._fetcher) || !this._currentSpec || this._disposed) return
     if (this._currentSpec.incremental === false) return
 
-    if (this._pendingFetch) {
-      this._pendingFetch = this._pendingFetch.then(() => {
-        if (this._disposed) return
-        return this.fetchRange(startTs, endTs)
-      })
-      return
-    }
-
     const spec = this._currentSpec
-    this._loadingSignal.set(true)
-
-    const service: {
-      readonly fetch: (
-        spec: SymbolSpec,
-        startTs: number,
-        endTs: number,
-      ) => EffectType<ReadonlyArray<KLineData>, unknown>
-    } = {
-      fetch: (s, start, end) =>
-        Effect.tryPromise({
-          try: () => {
-            if (!s.source) {
-              return Promise.reject(
-                new Error(`[DataBuffer] source is required for symbol "${s.symbol}"`),
-              )
-            }
-            if (this._requestFetch) {
-              return this._requestFetch(s, start, end)
-            }
-            return (this._fetcher as NonNullable<DataFetcher>)(s.source, {
-              symbol: s.symbol,
-              startDate: formatDate(start),
-              endDate: formatDate(end),
-              period: s.period ?? 'daily',
-              adjust: s.adjust ?? 'none',
-              exchange: s.exchange,
-            })
-          },
-          catch: (e) => e,
-        }),
+    const requestFetch = this._requestFetch
+    const fetcher = this._fetcher
+    const disposed = (): boolean => this._disposed
+
+    const fetchEffect = (): Promise<ReadonlyArray<KLineData>> => {
+      const service: {
+        readonly fetch: (
+          s: SymbolSpec,
+          start: number,
+          end: number,
+        ) => EffectType<ReadonlyArray<KLineData>, unknown>
+      } = {
+        fetch: (s, start, end) =>
+          Effect.tryPromise({
+            try: () => {
+              if (!s.source) {
+                return Promise.reject(
+                  new Error(`[DataBuffer] source is required for symbol "${s.symbol}"`),
+                )
+              }
+              if (requestFetch) {
+                return requestFetch(s, start, end)
+              }
+              return (fetcher as NonNullable<DataFetcher>)(s.source, {
+                symbol: s.symbol,
+                startDate: formatDate(start),
+                endDate: formatDate(end),
+                period: s.period ?? 'daily',
+                adjust: s.adjust ?? 'none',
+                exchange: s.exchange,
+              })
+            },
+            catch: (e) => e,
+          }),
+      }
+
+      return pipe(
+        fetchKLine(spec, startTs, endTs),
+        Effect.provideService(KLineFetchService, service),
+        Effect.runPromise,
+      )
     }
 
-    this._pendingFetch = pipe(
-      fetchKLine(spec, startTs, endTs),
-      Effect.provideService(KLineFetchService, service),
-      Effect.runPromise, // 链式传递返回值, Effect -> Promise -> run
-    )
+    this._scheduler
+      .run(fetchEffect)
       .then((incoming) => {
-        if (this._disposed) return
-
-        const oldLength = this._data.length
-        const oldEarliestTs = oldLength > 0 ? this._data[0]!.timestamp : null
-        const merged = mergeSortedData(this._data, [...incoming])
-        const newEarliestTs = merged[0]?.timestamp ?? null
-        const advancedEarliest =
-          oldEarliestTs !== null && newEarliestTs !== null && newEarliestTs < oldEarliestTs
-
-        if (oldLength > 0 && merged.length > oldLength && advancedEarliest) {
-          const prependCount = merged.findIndex((d) => d.timestamp === oldEarliestTs)
-          if (prependCount > 0) {
-            this.onPrepend?.(prependCount)
-          }
-        }
+        if (disposed()) return
 
-        if (oldLength > 0 && !advancedEarliest) {
-          this._attemptedBoundaries.delete(endTs)
-        }
+        const result = this._store.merge(incoming)
+        this._keyIndex.recompute(this._store.getRawData())
 
-        this._data = merged
-        this._dataSignal.set([...merged])
-        this._precomputeKeys()
-
-        if (merged.length > 0) {
-          const newEarliest = merged[0]!.timestamp
-          const newLatest = merged[merged.length - 1]!.timestamp
-          if (!this._loadedWindow) {
-            this._loadedWindow = { earliestTs: newEarliest, latestTs: newLatest }
-          } else {
-            this._loadedWindow = {
-              earliestTs: Math.min(this._loadedWindow.earliestTs, newEarliest),
-              latestTs: Math.max(this._loadedWindow.latestTs, newLatest),
-            }
-          }
+        if (!result.advancedEarliest) {
+          this._attemptedBoundaries.delete(endTs)
         }
       })
       .catch(() => {
         this._attemptedBoundaries.delete(endTs)
       })
-      .finally(() => {
-        this._pendingFetch = null
-        if (!this._disposed) {
-          this._loadingSignal.set(false)
-        }
-      })
-  }
-
-  /**
-   * Put the buffer in inline mode — use the provided data directly
-   * instead of fetching. Sets data signal and tracks loadedWindow.
-   */
-  setInlineData(data: unknown[]): void {
-    if (this._disposed) return
-    const kData = data as KLineData[]
-    this._data = [...kData]
-    this._dataSignal.set([...kData])
-    if (data.length > 0) {
-      this._loadedWindow = {
-        earliestTs: kData[0]!.timestamp,
-        latestTs: kData[kData.length - 1]!.timestamp,
-      }
-    } else {
-      this._loadedWindow = null
-    }
-    this._attemptedBoundaries.clear()
-    this._precomputeKeys()
-  }
-
-  /**
-   * Update just the spec metadata without triggering any fetch.
-   */
-  setCurrentSpec(spec: SymbolSpec): void {
-    this._currentSpec = spec
-  }
-
-  dispose(): void {
-    this._disposed = true
-    this._pendingFetch = null
-    this._data = []
-    this._loadedWindow = null
-    this._attemptedBoundaries.clear()
-    this._monthKeys = null
-    this._dayKeys = null
   }
 }

package/src/data-fetchers/dataBufferTypes.ts

@@ -1,11 +1,51 @@
+import type { KLineData, SymbolSpec, DataFetcher } from '../controllers/types'
 import type { Signal } from '../reactivity/signal'
-import type { DataWindow } from './dataBuffer'
+import type { TimeShareData } from '../types/price'
+
+import type { TimeShareFetcherFn } from './types'
+
+export interface DataWindow {
+  earliestTs: number
+  latestTs: number
+}
+
+/** 数据变更描述：在一次数据更新中携带数据本身和变更元数据 */
+export interface DataChange {
+  readonly data: ReadonlyArray<unknown>
+  /** 本次新增了多少根 K 线到头部（向左滚动加载的历史数据） */
+  readonly prependedCount: number
+}
 
 export interface DataBufferLike {
-  readonly data: Signal<ReadonlyArray<unknown>>
+  readonly data: Signal<DataChange>
   readonly loading: Signal<boolean>
   readonly loadedWindow: DataWindow | null
   getRawData(): unknown[]
   setInlineData(data: unknown[]): void
   dispose(): void
 }
+
+export interface KLineBuffer extends DataBufferLike {
+  readonly currentSpec: SymbolSpec | null
+  getRawData(): KLineData[]
+  getMonthKeys(): Int32Array | null
+  getDayKeys(): Int32Array | null
+  setFetcher(fetcher: DataFetcher | null): void
+  setRequestFetch(
+    fn:
+      | ((spec: SymbolSpec, startTs: number, endTs: number) => Promise<ReadonlyArray<KLineData>>)
+      | null,
+  ): void
+  setSymbol(spec: SymbolSpec, initialStartTs?: number): void
+  setCurrentSpec(spec: SymbolSpec): void
+  ensureRange(requestStartTs: number, requestEndTs: number): void
+}
+
+export interface TimeShareBuffer extends DataBufferLike {
+  getRawData(): TimeShareData[]
+  setFetcher(fetcher: TimeShareFetcherFn | null): void
+  setQueryDate(date: number): void
+  getFetcher(): TimeShareFetcherFn | null
+  getQueryDate(): number
+  load(spec: SymbolSpec): void
+}

package/src/data-fetchers/depthConnector.ts

@@ -12,9 +12,10 @@
  * ```
  */
 
-import type { DepthSource, DepthDelta, DepthSnapshot } from './depthTypes'
 import type { HeatmapController, HeatmapControllerConfig } from '../components/orderBookHeatmap'
 
+import type { DepthSource, DepthDelta, DepthSnapshot } from './depthTypes'
+
 export interface DepthConnectorOptions {
   /** Initial config passed to each controller created by addController */
   defaultConfig?: Partial<HeatmapControllerConfig>

package/src/data-fetchers/fetchScheduler.ts

@@ -0,0 +1,53 @@
+import { createSignal, type Signal } from '../reactivity/signal'
+
+export class FetchScheduler {
+  private _chain: Promise<void> | null = null
+  private _loadingSignal: Signal<boolean>
+  private _disposed = false
+
+  constructor() {
+    this._loadingSignal = createSignal<boolean>(false)
+  }
+
+  get loading(): Signal<boolean> {
+    return this._loadingSignal
+  }
+
+  run<T>(task: () => Promise<T>): Promise<T> {
+    if (this._disposed) {
+      return Promise.reject(new Error('FetchScheduler disposed'))
+    }
+
+    const execute = async (): Promise<T> => {
+      this._loadingSignal.set(true)
+      try {
+        return await task()
+      } finally {
+        this._chain = null
+        if (!this._disposed) this._loadingSignal.set(false)
+      }
+    }
+
+    if (this._chain) {
+      return new Promise<T>((resolve, reject) => {
+        this._chain = this._chain!.then(() => {
+          execute().then(resolve, reject)
+        })
+      })
+    }
+
+    const promise = execute()
+    this._chain = promise.then(() => undefined, () => undefined)
+    return promise
+  }
+
+  reset(): void {
+    this._chain = null
+    this._loadingSignal.set(false)
+  }
+
+  dispose(): void {
+    this._disposed = true
+    this._chain = null
+  }
+}

package/src/data-fetchers/fetcherDefinitionRegistry.ts

@@ -1,4 +1,5 @@
 import { KLineChartError } from '../errors'
+
 import type {
   DataFetcherDefinitionConfig,
   DataFetcherDefinition,
@@ -7,28 +8,38 @@ import type {
 } from './types'
 
 type DataFetcherClass = {
-  new (...args: never[]): unknown
+  new(...args: never[]): unknown
   fetcher: DataFetcherFn
   timeShareFetcher?: TimeShareFetcherFn
 }
 
 const definitions = new Map<string, DataFetcherDefinition>()
 
+/**
+ * 数据源注册装饰器
+ * 通过类装饰器将数据源自动注册到全局 definitions Map
+ * 使用 `import './xxx'` 副作用导入即可触发注册，无需显式引用类
+ */
 export function DataFetcher(config: DataFetcherDefinitionConfig) {
   return function <T extends DataFetcherClass>(value: T, context: ClassDecoratorContext<T>): T {
+    // addInitializer 在类实例化时执行回调
     context.addInitializer(function (this: T) {
+      // 校验：注册的数据源必须暴露静态 fetcher 方法
       if (typeof this.fetcher !== 'function') {
         throw new KLineChartError(
           'NOT_REGISTERED',
           `[DataFetcher] '${config.name}' definition must expose static fetcher`,
         )
       }
+      // 将数据源名称 -> 配置 + fetcher 函数写入全局注册表
+      // 之后业务代码通过 routerDataFetcher(config.name) 按名称查询
       definitions.set(config.name, {
         ...config,
         fetcher: this.fetcher,
         timeShareFetcher: this.timeShareFetcher,
       })
     })
+    // 返回原类，不改变类本身
     return value
   }
 }
@@ -38,11 +49,11 @@ export function getRegisteredFetcher(name: string): DataFetcherDefinition | unde
 }
 
 export function getRegisteredFetcherNames(): string[] {
-  return Array.from(definitions.keys())
+  return [...definitions.keys()]
 }
 
 function getRegisteredFetchers(): DataFetcherDefinition[] {
-  return Array.from(definitions.values())
+  return [...definitions.values()]
 }
 
 function fetcherHasCapability(name: string, capability: string): boolean {

package/src/data-fetchers/gotdx.ts

@@ -1,5 +1,6 @@
 import type { KLineData, TimeShareData } from '../controllers/types'
 import { KLineChartError } from '../errors'
+
 import { DataFetcher } from './fetcherDefinitionRegistry'
 import type { FetchConfig, TimeShareFetchConfig } from './types'
 

package/src/data-fetchers/hundred-mock.ts

@@ -1,4 +1,5 @@
 import type { KLineData } from '../controllers/types'
+
 import { DataFetcher } from './fetcherDefinitionRegistry'
 import type { FetchConfig } from './types'
 

package/src/data-fetchers/index.ts

@@ -3,7 +3,7 @@ export { thousandMockDataFetcher } from './thousand-mock'
 export { baostockDataFetcher } from './baostock'
 export { routerDataFetcher, routerTimeShareFetcher } from './router'
 export { DataBuffer } from './dataBuffer'
-export type { DataWindow } from './dataBuffer'
+export type { DataWindow } from './dataBufferTypes'
 export { TimeShareBuffer } from './timeShareBuffer'
 export type { DataBufferLike } from './dataBufferTypes'
 export {