@forgecharts/sdk 1.1.23 → 1.1.28

package/dist/datafeed/DatafeedConnector.d.ts

@@ -0,0 +1,89 @@
+import type { IDatafeed, OHLCV, Timeframe } from '@forgecharts/types';
+import type { ISeries } from '../types/ISeries';
+/**
+ * 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 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 declare class DatafeedConnector {
+    private readonly _datafeed;
+    private readonly _series;
+    private readonly _cb;
+    /**
+     * UID of the outstanding subscription.
+     * `null` means nothing is subscribed / all responses for older UIDs are stale.
+     */
+    private _activeUID;
+    private _activeEngine;
+    private _destroyed;
+    /** True while an async `loadMoreHistory()` request is in-flight. */
+    private _isLoadingMore;
+    /** True once the datafeed returned 0 bars for a backwards page — no point fetching older. */
+    private _noMoreHistory;
+    constructor(datafeed: IDatafeed, series: ISeries, callbacks: ConnectorCallbacks);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Convenience shorthand: `disconnect()` then `connect()`.
+     * Use this for symbol or timeframe changes.
+     */
+    reconnect(symbol: string, timeframe: Timeframe): void;
+    /**
+     * Permanently deactivates the connector.
+     * Any subscription or in-flight request is cancelled; subsequent calls to
+     * `connect()` / `reconnect()` are no-ops.
+     */
+    destroy(): void;
+    /**
+     * 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;
+    private _cancelActive;
+}
+//# sourceMappingURL=DatafeedConnector.d.ts.map

package/dist/datafeed/DatafeedConnector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatafeedConnector.d.ts","sourceRoot":"","sources":["../../src/datafeed/DatafeedConnector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAoEhD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACnE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAClE,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CACjC,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IAEzC;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,UAAU,CAAS;IAE3B,oEAAoE;IACpE,OAAO,CAAC,cAAc,CAAS;IAC/B,6FAA6F;IAC7F,OAAO,CAAC,cAAc,CAAS;gBAEnB,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,kBAAkB;IAQ/E;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IA0EnD;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAIlB;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAKrD;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAOf;;;;;;;OAOG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAgC3D,OAAO,CAAC,aAAa;CAgBtB"}

package/dist/datafeed/DatafeedConnector.js

@@ -0,0 +1,268 @@
+import { CandleEngine } from '../engine/CandleEngine';
+/** Strip engine-only fields so the value is a plain OHLCV the chart series accepts. */
+function toOHLCV(bar) {
+    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 = {
+    // 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 = {
+    '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;
+// ─── 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 {
+    _datafeed;
+    _series;
+    _cb;
+    /**
+     * UID of the outstanding subscription.
+     * `null` means nothing is subscribed / all responses for older UIDs are stale.
+     */
+    _activeUID = null;
+    _activeEngine = null;
+    _destroyed = false;
+    /** True while an async `loadMoreHistory()` request is in-flight. */
+    _isLoadingMore = false;
+    /** True once the datafeed returned 0 bars for a backwards page — no point fetching older. */
+    _noMoreHistory = false;
+    constructor(datafeed, series, callbacks) {
+        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, timeframe) {
+        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);
+                })
+                    .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, 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) => {
+                if (this._activeUID === uid) {
+                    engine.applyLiveUpdate(bar);
+                }
+            }, uid);
+        })
+            .catch((err) => {
+            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() {
+        this._cancelActive();
+    }
+    /**
+     * Convenience shorthand: `disconnect()` then `connect()`.
+     * Use this for symbol or timeframe changes.
+     */
+    reconnect(symbol, timeframe) {
+        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() {
+        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, timeframe) {
+        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);
+            }
+        })
+            .catch(() => {
+            // Non-fatal — user can scroll again to retry
+        })
+            .finally(() => {
+            if (this._activeUID === uid)
+                this._isLoadingMore = false;
+        });
+    }
+    _cancelActive() {
+        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;
+    }
+}
+//# sourceMappingURL=DatafeedConnector.js.map

package/dist/datafeed/DatafeedConnector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatafeedConnector.js","sourceRoot":"","sources":["../../src/datafeed/DatafeedConnector.ts"],"names":[],"mappings":"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"}

package/dist/engine/CandleEngine.d.ts

@@ -0,0 +1,207 @@
+/**
+ * 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';
+/**
+ * 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;
+}
+export declare class CandleEngine {
+    /** Authoritative ordered bar array. Only the rightmost bar may be open. */
+    private _bars;
+    private _timeframe;
+    private _intervalMs;
+    private readonly _opts;
+    constructor(options?: CandleEngineOptions);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Returns a readonly view of the authoritative bar array.
+     * Do not mutate — call `applyLiveUpdate`, `backfillGap`, etc. instead.
+     */
+    getBars(): readonly CandleBar[];
+    /** Returns the most recent (possibly still live) bar, or null if empty. */
+    getLastBar(): CandleBar | 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;
+    /**
+     * Clear all state.
+     * Call before switching symbol or timeframe, or on a hard disconnect.
+     */
+    reset(): void;
+    private _debugLog;
+}
+//# sourceMappingURL=CandleEngine.d.ts.map

package/dist/engine/CandleEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CandleEngine.d.ts","sourceRoot":"","sources":["../../src/engine/CandleEngine.ts"],"names":[],"mappings":"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"}