@forgecharts/sdk 1.1.27 → 1.1.29

package/src/datafeed/DatafeedConnector.ts

@@ -1,300 +0,0 @@
-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;
-  }
-}