@forgecharts/sdk 1.1.23

package/src/engine/CandleEngine.ts

@@ -0,0 +1,458 @@
+/**
+ * CandleEngine — the single source of truth for live candle data.
+ *
+ * Architecture:
+ *
+ *   WebSocket feed
+ *       ↓
+ *   Market Data Normalizer  (normalizeOhlcv — handles strings, ms vs s)
+ *       ↓
+ *   CandleEngine            (applyCandleUpdate — O(1) update path)
+ *       ↓
+ *   Chart Update Adapter    (onBarUpdated / onResync callbacks)
+ *       ↓
+ *   Chart Library           (series.update / series.setData)
+ *
+ * Guarantees:
+ *   - open  is never overwritten on an existing live candle
+ *   - high  can only increase within a candle
+ *   - low   can only decrease within a candle
+ *   - close updates on every tick
+ *   - out-of-order ticks are silently discarded
+ *   - gaps are detected and reported for async REST backfill
+ *   - the engine is framework-agnostic (no DOM, React, or chart-lib imports)
+ */
+
+import type { Timeframe } from '@forgecharts/types';
+import { timeframeToMs, getBucketStart, getCalendarBucketStart } from './timeframeUtils';
+import { getMissingBarCount, mergeBars } from './mergeUtils';
+import {
+  assertOhlcRelationships,
+  assertBucketAlignment,
+  assertNotFinalized,
+  assertOpenImmutability,
+  assertNoDuplicateAppend,
+  assertFinalizedUnchanged,
+} from './candleInvariants';
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+/**
+ * Normalised candle shape used throughout the engine.
+ *
+ * `timeMs`  — millisecond timestamp (used for bucket identity comparisons)
+ * `time`    — second timestamp (used for chart library rendering)
+ */
+export interface CandleBar {
+  /** Candle open-time in milliseconds — the primary bucket key. */
+  timeMs: number;
+  /** Candle open-time in seconds — passed directly to the chart library. */
+  time: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
+  /** True once the next candle has started and this bar is fully formed. */
+  isClosed: boolean;
+}
+
+/**
+ * Raw OHLCV input accepted by the engine.
+ * Values may be number or numeric string; `time` may be milliseconds or seconds.
+ */
+export interface RawOHLCV {
+  time: number | string;
+  open: number | string;
+  high: number | string;
+  low: number | string;
+  close: number | string;
+  volume?: number | string;
+  isClosed?: boolean;
+}
+
+/** Describes what the engine did with a live update. */
+export type UpdateResult =
+  | { type: 'update'; bar: CandleBar }
+  | { type: 'append'; bar: CandleBar; previousBarClosed: boolean }
+  | { type: 'gap';    bar: CandleBar; missingCount: number }
+  | { type: 'ignore' };
+
+/** Gap information emitted via `onGapDetected`. */
+export interface GapInfo {
+  fromTimeMs: number;
+  toTimeMs: number;
+  missingCount: number;
+}
+
+export interface CandleEngineOptions {
+  /**
+   * Enable structured debug logging to the console.
+   * Log every incoming tick with action, timestamps, and resulting OHLCV.
+   */
+  debug?: boolean;
+
+  /**
+   * Fired when the live stream skips one or more candle buckets.
+   * Use this to trigger an async REST backfill; do not block the live stream.
+   */
+  onGapDetected?: (info: GapInfo) => void;
+
+  /**
+   * Fired after every bar mutation (update or append).
+   * The chart adapter should call `series.update(bar)` here.
+   */
+  onBarUpdated?: (bar: CandleBar, result: UpdateResult) => void;
+
+  /** Fired when a candle is finalised — the next candle's first tick arrived. */
+  onBarClosed?: (bar: CandleBar) => void;
+
+  /**
+   * Fired after the full bar array changes (backfillGap / handleReconnect).
+   * The chart adapter should call `series.setData(bars)` here to fully resync.
+   */
+  onResync?: (bars: readonly CandleBar[]) => void;
+}
+
+// ─── Internal normalizer ─────────────────────────────────────────────────────
+
+/**
+ * Normalise a raw OHLCV object into a CandleBar.
+ *
+ * - Coerces all fields to `number` (handles numeric strings from the feed).
+ * - Auto-detects ms vs s timestamps: values > 1e12 are treated as milliseconds.
+ * - Aligns `timeMs` to the correct candle-open boundary, with calendar
+ *   alignment for `1w` (Monday) and `1M` (first of month).
+ *
+ * Never use `Date.now()` for candle time — always use the feed-provided value.
+ */
+function normalizeOhlcv(raw: RawOHLCV, intervalMs: number, tf: string): CandleBar {
+  const rawTime = Number(raw.time);
+
+  // Auto-detect: Unix ms timestamps are > 1e12 (year 2001+).
+  // If the value is smaller, treat it as seconds and convert.
+  const timeMs = rawTime > 1e12 ? rawTime : rawTime * 1000;
+
+  // Calendar-aware bucket alignment (handles 1w/1M specially)
+  const bucketMs = getCalendarBucketStart(timeMs, tf);
+  const timeSec  = Math.floor(bucketMs / 1000);
+
+  return {
+    timeMs:   bucketMs,
+    time:     timeSec,
+    open:     Number(raw.open),
+    high:     Number(raw.high),
+    low:      Number(raw.low),
+    close:    Number(raw.close),
+    volume:   Number(raw.volume ?? 0),
+    isClosed: raw.isClosed ?? false,
+  };
+}
+
+// ─── CandleEngine ─────────────────────────────────────────────────────────────
+
+export class CandleEngine {
+  /** Authoritative ordered bar array. Only the rightmost bar may be open. */
+  private _bars: CandleBar[] = [];
+  private _timeframe: Timeframe = '1m';
+  private _intervalMs: number = 60_000;
+  private readonly _opts: CandleEngineOptions;
+
+  constructor(options: CandleEngineOptions = {}) {
+    this._opts = options;
+  }
+
+  // ── Initialisation ──────────────────────────────────────────────────────────
+
+  /**
+   * Seed the engine with historical bars and set the active timeframe.
+   * All existing bars are replaced.
+   *
+   * Historical bars loaded from REST are assumed closed, except possibly
+   * the last one (which may represent the still-forming candle).
+   *
+   * @param history   Raw bars from a REST endpoint (oldest → newest).
+   * @param timeframe The active timeframe label (e.g. '1m', '1h').
+   */
+  initialize(history: RawOHLCV[], timeframe: Timeframe): void {
+    this._timeframe  = timeframe;
+    this._intervalMs = timeframeToMs(timeframe);
+
+    // Normalise, deduplicate by timeMs (latest entry wins), sort newest-last
+    const seen = new Map<number, CandleBar>();
+    for (const raw of history) {
+      const bar = normalizeOhlcv(raw, this._intervalMs, this._timeframe);
+      seen.set(bar.timeMs, bar);
+    }
+    this._bars = Array.from(seen.values()).sort((a, b) => a.timeMs - b.timeMs);
+
+    // Mark all bars except the last as closed
+    for (let i = 0; i < this._bars.length - 1; i++) {
+      this._bars[i]!.isClosed = true;
+    }
+
+    this._debugLog('initialize', {
+      timeframe,
+      intervalMs: this._intervalMs,
+      barCount:   this._bars.length,
+      firstTime:  this._bars[0]?.timeMs,
+      lastTime:   this._bars[this._bars.length - 1]?.timeMs,
+    });
+  }
+
+  // ── Live updates ────────────────────────────────────────────────────────────
+
+  /**
+   * Process a single live OHLCV tick from the WebSocket feed.
+   *
+   * Algorithm (mirrors TradingView / Binance candle engine behaviour):
+   *
+   *  1. Normalise: coerce strings to numbers, detect ms vs s, align to bucket.
+   *  2. Empty array → append as first bar.
+   *  3. incoming.timeMs === last.timeMs  → SAME CANDLE (update in-place):
+   *       open   = unchanged               (first tick's open is authoritative)
+   *       high   = max(last.high, inc.high, inc.close)
+   *       low    = min(last.low,  inc.low,  inc.close)
+   *       close  = inc.close
+   *       volume = inc.volume
+   *  4. incoming.timeMs  > last.timeMs  → NEW CANDLE:
+   *       - Detect and report any gap (missing buckets between last and incoming).
+   *       - Mark last bar as closed, fire onBarClosed.
+   *       - Append incoming as a fresh live candle.
+   *  5. incoming.timeMs  < last.timeMs  → OUT-OF-ORDER: discard silently.
+   *
+   * @returns UpdateResult indicating what was done — the chart adapter uses
+   *   this to choose between series.update() and series.setData().
+   */
+  applyLiveUpdate(raw: RawOHLCV): UpdateResult {
+    const incoming = normalizeOhlcv(raw, this._intervalMs, this._timeframe);
+
+    // Invariant: incoming bar must be bucket-aligned and OHLC-valid
+    assertBucketAlignment(incoming, this._timeframe, 'applyLiveUpdate:normalize');
+    assertOhlcRelationships(incoming, 'applyLiveUpdate:normalize');
+
+    // ── First bar ever ─────────────────────────────────────────────────────
+    if (this._bars.length === 0) {
+      this._bars.push(incoming);
+      const result: UpdateResult = { type: 'append', bar: incoming, previousBarClosed: false };
+      this._debugLog('append:first', incoming);
+      this._opts.onBarUpdated?.(incoming, result);
+      return result;
+    }
+
+    const last = this._bars[this._bars.length - 1]!;
+
+    // ── Same candle: update in-place (O(1)) ────────────────────────────────
+    if (incoming.timeMs === last.timeMs) {
+      // Invariant: must not mutate a finalized candle
+      assertNotFinalized(last, 'applyLiveUpdate:same-bucket');
+
+      const prevOpen  = last.open;
+      const prevCount = this._bars.length;
+
+      // open is intentionally not updated — the first tick's open is correct
+      last.high   = Math.max(last.high,  incoming.high,  incoming.close);
+      last.low    = Math.min(last.low,   incoming.low,   incoming.close);
+      last.close  = incoming.close;
+      last.volume = incoming.volume;
+
+      // Invariant: open must be unchanged, no spurious append must have occurred
+      assertOpenImmutability(prevOpen, last, 'applyLiveUpdate:same-bucket');
+      assertOhlcRelationships(last, 'applyLiveUpdate:same-bucket');
+      assertNoDuplicateAppend(prevCount, this._bars.length, 'applyLiveUpdate:same-bucket');
+
+      const result: UpdateResult = { type: 'update', bar: last };
+      this._debugLog('update', last);
+      this._opts.onBarUpdated?.(last, result);
+      return result;
+    }
+
+    // ── Out-of-order: older than the current live candle ──────────────────
+    if (incoming.timeMs < last.timeMs) {
+      this._debugLog('ignore', {
+        incomingTimeMs: incoming.timeMs,
+        lastTimeMs:     last.timeMs,
+        delta:          last.timeMs - incoming.timeMs,
+      });
+      return { type: 'ignore' };
+    }
+
+    // ── New candle (incoming.timeMs > last.timeMs) ─────────────────────────
+
+    // Gap detection: how many candle buckets are missing between last and new?
+    const missingCount = getMissingBarCount(last.timeMs, incoming.timeMs, this._intervalMs);
+    if (missingCount > 0) {
+      const gapInfo: GapInfo = { fromTimeMs: last.timeMs, toTimeMs: incoming.timeMs, missingCount };
+      this._debugLog('gap', gapInfo);
+      this._opts.onGapDetected?.(gapInfo);
+    }
+
+    // Finalise the previous live candle
+    const prevLastBar = { ...last }; // snapshot for post-append invariant check
+    last.isClosed = true;
+    this._opts.onBarClosed?.(last);
+
+    // Append the new candle
+    this._bars.push(incoming);
+
+    // Invariant: previous bar must be closed and not mutated after the append
+    assertFinalizedUnchanged(prevLastBar, this._bars, 'applyLiveUpdate:new-bucket');
+    assertOhlcRelationships(incoming, 'applyLiveUpdate:new-bucket');
+
+    const result: UpdateResult = missingCount > 0
+      ? { type: 'gap',    bar: incoming, missingCount }
+      : { type: 'append', bar: incoming, previousBarClosed: true };
+
+    this._debugLog(result.type, incoming);
+    this._opts.onBarUpdated?.(incoming, result);
+    return result;
+  }
+
+  // ── Gap backfill ────────────────────────────────────────────────────────────
+
+  /**
+   * Merge REST-fetched bars into the engine to fill a detected gap.
+   *
+   * Incoming bars are treated as authoritative closed candles.
+   * The current live candle is preserved if present.
+   *
+   * After calling this, `onResync` fires — the chart adapter must call
+   * `series.setData(engine.getBars())` to fully resync the chart.
+   *
+   * @param rawBars  Historical bars from the REST endpoint covering the gap.
+   */
+  backfillGap(rawBars: RawOHLCV[]): void {
+    const incoming = rawBars.map(r => {
+      const bar = normalizeOhlcv(r, this._intervalMs, this._timeframe);
+      bar.isClosed = true; // REST bars are closed and authoritative
+      return bar;
+    });
+
+    // Preserve the live candle's open state after merge
+    const liveBefore = this._bars[this._bars.length - 1];
+
+    this._bars = mergeBars(this._bars, incoming);
+
+    // Re-apply live candle's isClosed=false if it survived the merge
+    if (liveBefore && !liveBefore.isClosed) {
+      const last = this._bars[this._bars.length - 1];
+      if (last && last.timeMs === liveBefore.timeMs) {
+        last.isClosed = false;
+      }
+    }
+
+    this._debugLog('backfillGap', { filled: rawBars.length, totalBars: this._bars.length });
+    this._opts.onResync?.(this._bars);
+  }
+
+  // ── Reconnect reconciliation ────────────────────────────────────────────────
+
+  /**
+   * Reconcile after a WebSocket reconnect.
+   *
+   * Fetch a rolling overlap window from REST (e.g. last 50 bars or 2 hours)
+   * and pass them here. The engine merges them with the existing bar array,
+   * correcting any candles that were missed or corrupted during the outage.
+   *
+   * After reconciliation, `onResync` fires so the chart adapter can resync
+   * the chart series with `series.setData(engine.getBars())`.
+   *
+   * @param recentBars  REST bars covering the reconnect overlap window.
+   */
+  handleReconnect(recentBars: RawOHLCV[]): void {
+    const incoming = recentBars.map(r => normalizeOhlcv(r, this._intervalMs, this._timeframe));
+    this._bars = mergeBars(this._bars, incoming);
+    this._debugLog('handleReconnect', { count: recentBars.length, totalBars: this._bars.length });
+    this._opts.onResync?.(this._bars);
+  }
+
+  // ── Trade-tick stub ─────────────────────────────────────────────────────────
+
+  /**
+   * Stub for future tick/trade-based candle construction.
+   *
+   * When implemented, this will:
+   *   - Assign the trade to its bucket using `getBucketStart(timeMs, intervalMs)`.
+   *   - Create a new candle if the bucket is absent.
+   *   - Update OHLCV: open/close from trade price, high/low expanded, volume summed.
+   *
+   * Not yet implemented — structure is in place for future extension.
+   */
+  applyTradeTick(
+    _trade: { time: number | string; price: number | string; size?: number | string },
+  ): void {
+    // TODO: implement tick-based candle construction
+  }
+
+  // ── Read access ─────────────────────────────────────────────────────────────
+
+  /**
+   * Returns a readonly view of the authoritative bar array.
+   * Do not mutate — call `applyLiveUpdate`, `backfillGap`, etc. instead.
+   */
+  getBars(): readonly CandleBar[] {
+    return this._bars;
+  }
+
+  /** Returns the most recent (possibly still live) bar, or null if empty. */
+  getLastBar(): CandleBar | null {
+    return this._bars[this._bars.length - 1] ?? null;
+  }
+
+  /**
+   * Prepend older historical bars fetched during a lazy scroll-left page load.
+   * Only bars older than the current oldest bar are accepted; duplicates and
+   * out-of-range bars are silently dropped.
+   * Fires `onResync` so the chart adapter updates the series with `setData`.
+   *
+   * @param rawBars  Historical bars from the REST endpoint, oldest → newest.
+   */
+  prependHistory(rawBars: RawOHLCV[]): void {
+    const oldest = this._bars[0];
+    const cutoff = oldest ? oldest.timeMs : Infinity;
+
+    const incoming = rawBars
+      .map(r => {
+        const bar = normalizeOhlcv(r, this._intervalMs, this._timeframe);
+        bar.isClosed = true;
+        return bar;
+      })
+      .filter(bar => bar.timeMs < cutoff);
+
+    if (incoming.length === 0) return;
+
+    incoming.sort((a, b) => a.timeMs - b.timeMs);
+    this._bars = [...incoming, ...this._bars];
+
+    this._debugLog('prependHistory', {
+      prepended: incoming.length,
+      firstTime: this._bars[0]?.timeMs,
+    });
+
+    this._opts.onResync?.(this._bars);
+  }
+
+  /**
+   * Clear all state.
+   * Call before switching symbol or timeframe, or on a hard disconnect.
+   */
+  reset(): void {
+    this._bars = [];
+    this._debugLog('reset', { timeframe: this._timeframe });
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────────────────
+
+  private _debugLog(action: string, data: object): void {
+    if (!this._opts.debug) return;
+    console.debug('[CANDLE_ENGINE]', {
+      action,
+      timeframe:  this._timeframe,
+      barCount:   this._bars.length,
+      liveBar:    this._bars[this._bars.length - 1]
+        ? { open: this._bars[this._bars.length - 1]!.open, high: this._bars[this._bars.length - 1]!.high, low: this._bars[this._bars.length - 1]!.low, close: this._bars[this._bars.length - 1]!.close }
+        : null,
+      ...data,
+    });
+  }
+}