@forgecharts/sdk 1.1.23

package/src/datafeed/DatafeedConnector.ts

@@ -0,0 +1,300 @@
+import type { IDatafeed, OHLCV, Timeframe } from '@forgecharts/types';
+import type { ISeries } from '../types/ISeries';
+import { CandleEngine } from '../engine/CandleEngine';
+import type { CandleBar, RawOHLCV } from '../engine/CandleEngine';
+
+/** Strip engine-only fields so the value is a plain OHLCV the chart series accepts. */
+function toOHLCV(bar: CandleBar): OHLCV {
+  return { time: bar.time, open: bar.open, high: bar.high, low: bar.low, close: bar.close, volume: bar.volume };
+}
+
+/**
+ * Initial history window per timeframe — controls how much data the chart
+ * requests on first connect.
+ *
+ * TWO-LAYER ARCHITECTURE — these two concerns are independent:
+ *  • CLIENT (this table): how many bars are fetched and held in memory for the
+ *    initial view + scroll buffer.  Larger = more data in the browser.
+ *  • SERVER DB fill (bars.ts MAX_DB_SECONDS): the server always fills a full
+ *    12 months of 1m data (and all available daily history) into the DB cache
+ *    in the background, regardless of the client window size.  This means
+ *    scroll-left lazy-loading hits the DB, not the upstream TV API.
+ *
+ * For sub-hour timeframes a large display window is impractical:
+ *   12 months of 1m = 525 600 bars — impossible to render, slow to transfer.
+ * For 4h and above, 12 months is a manageable bar count so we load it all
+ * upfront; the server will have it cached or will fill it synchronously.
+ */
+const HISTORY_WINDOWS: Partial<Record<Timeframe, number>> = {
+  // Sub-hour: small display window; DB fills 12 months in background for scrollback.
+  '1m':  3   * 24 * 3600,   //   3 days  → ~4 320 bars
+  '3m':  7   * 24 * 3600,   //   7 days  → ~3 360 bars
+  '5m':  10  * 24 * 3600,   //  10 days  → ~2 880 bars
+  '15m': 30  * 24 * 3600,   //  30 days  → ~2 880 bars
+  '30m': 60  * 24 * 3600,   //  60 days  → ~2 880 bars
+  '1h':  90  * 24 * 3600,   //  90 days  → ~2 160 bars
+  // 4h and above: 12 months — bar counts are small enough to load in full.
+  '2h':  365 * 86400,       // 12 months → ~4 380 bars
+  '4h':  365 * 86400,       // 12 months → ~2 190 bars
+  '6h':  365 * 86400,       // 12 months → ~1 460 bars
+  '12h': 365 * 86400,       // 12 months →   ~730 bars
+  '1d':  365 * 86400,       // 12 months →   ~365 bars
+  '3d':  365 * 86400,       // 12 months →   ~122 bars
+  '1w':  365 * 86400,       // 12 months →    ~52 bars
+  '1M':  365 * 86400,       // 12 months →    ~12 bars
+};
+const DEFAULT_HISTORY_WINDOW = 90 * 24 * 3600; // 90-day fallback (~200 bars at 1h)
+
+/**
+ * How many seconds of history to fetch per lazy-load page (~500 candles).
+ * Used by `loadMoreHistory()` when the user pans past the oldest loaded bar.
+ */
+const PAGE_SIZES: Partial<Record<Timeframe, number>> = {
+  '1m':  500 * 60,
+  '5m':  500 * 300,
+  '15m': 500 * 900,
+  '30m': 500 * 1800,
+  '1h':  500 * 3600,
+  '4h':  500 * 4  * 3600,
+  '1d':  500 * 86400,
+  '1w':  500 * 7  * 86400,
+  '1M':  500 * 30 * 86400,
+};
+const DEFAULT_PAGE_SIZE = 500 * 3600;
+
+/** Monotonic counter so every subscriber UID is unique within the process. */
+let _uidCounter = 0;
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+/**
+ * Lifecycle callbacks injected by TChart so it can relay data-load state
+ * as EventBus events without coupling DatafeedConnector to the bus.
+ */
+export type ConnectorCallbacks = {
+  onLoading(symbol: string, interval: Timeframe): void;
+  onLoaded(symbol: string, interval: Timeframe, count: number): void;
+  onError(symbol: string, interval: Timeframe, error: string): void;
+  /** Called on every real-time tick after the series is updated. Optional. */
+  onUpdate?: (bar: OHLCV) => void;
+};
+
+// ─── DatafeedConnector ────────────────────────────────────────────────────────
+
+/**
+ * DatafeedConnector wires an {@link IDatafeed} to an {@link ISeries}.
+ *
+ * Responsibilities:
+ * - Generates stable, unique subscriber UIDs (`forgecharts-<symbol>-<tf>-<n>`).
+ * - Calls `getHistoricalBars` and pushes the result into `series.setData()`.
+ * - Calls `subscribeBars` so real-time ticks flow into `series.update()`.
+ * - Guards against stale async responses after a reconnect or destroy.
+ * - Tears down the active subscription cleanly on `disconnect()` / `destroy()`.
+ *
+ * @example
+ * ```ts
+ * const connector = new DatafeedConnector(datafeed, series, {
+ *   onLoading: (s, tf) => console.log('loading', s, tf),
+ *   onLoaded:  (s, tf, n) => console.log('loaded', n, 'bars'),
+ *   onError:   (s, tf, e) => console.error(e),
+ * });
+ *
+ * connector.connect('BTCUSDT', '1h');
+ * // ...later, on symbol change:
+ * connector.reconnect('ETHUSDT', '1h');
+ * // ...on unmount:
+ * connector.destroy();
+ * ```
+ */
+export class DatafeedConnector {
+  private readonly _datafeed: IDatafeed;
+  private readonly _series: ISeries;
+  private readonly _cb: ConnectorCallbacks;
+
+  /**
+   * UID of the outstanding subscription.
+   * `null` means nothing is subscribed / all responses for older UIDs are stale.
+   */
+  private _activeUID: string | null = null;
+  private _activeEngine: CandleEngine | null = null;
+  private _destroyed = false;
+
+  /** True while an async `loadMoreHistory()` request is in-flight. */
+  private _isLoadingMore = false;
+  /** True once the datafeed returned 0 bars for a backwards page — no point fetching older. */
+  private _noMoreHistory = false;
+
+  constructor(datafeed: IDatafeed, series: ISeries, callbacks: ConnectorCallbacks) {
+    this._datafeed = datafeed;
+    this._series = series;
+    this._cb = callbacks;
+  }
+
+  // ─── Public API ───────────────────────────────────────────────────────────────
+
+  /**
+   * Loads historical bars then subscribes for real-time updates.
+   * Safe to call while a previous subscription is still active — it will be
+   * cancelled first (same as calling `disconnect()` then `connect()`).
+   */
+  connect(symbol: string, timeframe: Timeframe): void {
+    if (this._destroyed) return;
+
+    // Cancel any in-flight request / active subscription before starting fresh
+    this._cancelActive();
+
+    const uid = `forgecharts-${symbol}-${timeframe}-${++_uidCounter}`;
+    this._activeUID = uid;
+
+    this._cb.onLoading(symbol, timeframe);
+
+    const to   = Math.floor(Date.now() / 1000);
+    const from = to - (HISTORY_WINDOWS[timeframe] ?? DEFAULT_HISTORY_WINDOW);
+
+    // Build the engine for this subscription. Close over `uid` for stale-guard.
+    const engine = new CandleEngine({
+      // Every live tick mutates the engine's bar array and the chart series.
+      onBarUpdated: (bar) => {
+        if (this._activeUID !== uid) return;
+        const ohlcv = toOHLCV(bar);
+        this._series.update(ohlcv);
+        this._cb.onUpdate?.(ohlcv);
+      },
+      // When a gap is detected, fetch the missing range from REST and backfill.
+      // backfillGap() will call onResync which re-syncs the full chart series.
+      onGapDetected: (gapInfo) => {
+        if (this._activeUID !== uid) return;
+        const gapFrom = Math.floor(gapInfo.fromTimeMs / 1000);
+        const gapTo   = Math.ceil(gapInfo.toTimeMs   / 1000);
+        this._datafeed.getHistoricalBars(symbol, timeframe, gapFrom, gapTo)
+          .then(({ bars }) => {
+            if (this._activeUID !== uid) return;
+            engine.backfillGap(bars as RawOHLCV[]);
+          })
+          .catch(() => {
+            // Gap backfill errors are non-fatal — chart continues with live data
+          });
+      },
+      // Full re-paint after gap fill or reconnect reconciliation.
+      onResync: (bars) => {
+        if (this._activeUID !== uid) return;
+        this._series.setData(bars.map(toOHLCV));
+      },
+    });
+
+    this._activeEngine = engine;
+
+    this._datafeed
+      .getHistoricalBars(symbol, timeframe, from, to)
+      .then((result) => {
+        // Guard: another connect() / destroy() may have superseded this request
+        if (this._activeUID !== uid) return;
+
+        engine.initialize(result.bars as RawOHLCV[], timeframe);
+        this._series.setData(engine.getBars().map(toOHLCV));
+        this._cb.onLoaded(symbol, timeframe, engine.getBars().length);
+
+        // Double-check still active before subscribing (setData callback could
+        // have triggered a synchronous reconnect in pathological code)
+        if (this._activeUID !== uid) return;
+
+        this._datafeed.subscribeBars(symbol, timeframe, (bar: OHLCV) => {
+          if (this._activeUID === uid) {
+            engine.applyLiveUpdate(bar as RawOHLCV);
+          }
+        }, uid);
+      })
+      .catch((err: unknown) => {
+        if (this._activeUID !== uid) return;
+        const message = err instanceof Error ? err.message : String(err);
+        this._cb.onError(symbol, timeframe, message);
+      });
+  }
+
+  /**
+   * Cancels the active subscription without starting a new one.
+   * Historical-bar `Promise` results arriving after this call are silently
+   * discarded via the UID guard.
+   */
+  disconnect(): void {
+    this._cancelActive();
+  }
+
+  /**
+   * Convenience shorthand: `disconnect()` then `connect()`.
+   * Use this for symbol or timeframe changes.
+   */
+  reconnect(symbol: string, timeframe: Timeframe): void {
+    this.disconnect();
+    this.connect(symbol, timeframe);
+  }
+
+  /**
+   * Permanently deactivates the connector.
+   * Any subscription or in-flight request is cancelled; subsequent calls to
+   * `connect()` / `reconnect()` are no-ops.
+   */
+  destroy(): void {
+    this._cancelActive();
+    this._destroyed = true;
+  }
+
+  // ─── Private ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Fetches a page of older history (up to ~500 candles) and prepends it to
+   * the loaded dataset. Safe to call on every pan event — it is internally
+   * debounced by the `_isLoadingMore` flag and stops permanently once the
+   * datafeed signals no more history (`_noMoreHistory = true`).
+   *
+   * The series is updated automatically via the engine's `onResync` callback.
+   */
+  loadMoreHistory(symbol: string, timeframe: Timeframe): void {
+    if (this._destroyed || this._isLoadingMore || this._noMoreHistory) return;
+    if (!this._activeEngine || !this._activeUID) return;
+
+    const engine = this._activeEngine;
+    const oldest = engine.getBars()[0];
+    if (!oldest) return;
+
+    const uid  = this._activeUID;
+    const to   = Math.floor(oldest.timeMs / 1000);
+    const page = PAGE_SIZES[timeframe] ?? DEFAULT_PAGE_SIZE;
+    const from = to - page;
+
+    this._isLoadingMore = true;
+
+    this._datafeed.getHistoricalBars(symbol, timeframe, from, to - 1)
+      .then(({ bars }) => {
+        if (this._activeUID !== uid) return;
+        if (bars.length === 0) {
+          this._noMoreHistory = true;
+        } else {
+          engine.prependHistory(bars as RawOHLCV[]);
+        }
+      })
+      .catch(() => {
+        // Non-fatal — user can scroll again to retry
+      })
+      .finally(() => {
+        if (this._activeUID === uid) this._isLoadingMore = false;
+      });
+  }
+
+  private _cancelActive(): void {
+    if (this._activeUID !== null) {
+      try {
+        this._datafeed.unsubscribeBars(this._activeUID);
+      } catch {
+        // Best-effort teardown — datafeed may already be closed
+      }
+      this._activeUID = null;
+    }
+    if (this._activeEngine !== null) {
+      this._activeEngine.reset();
+      this._activeEngine = null;
+    }
+    this._isLoadingMore = false;
+    this._noMoreHistory = false;
+  }
+}