@forgecharts/sdk 1.1.23 → 1.1.28

package/src/engine/__tests__/CandleEngine.test.ts

@@ -1,402 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { CandleEngine } from '../CandleEngine';
-import type { CandleBar, RawOHLCV, UpdateResult, GapInfo } from '../CandleEngine';
-import { timeframeToMs, getBucketStart } from '../timeframeUtils';
-import { getMissingBarCount, mergeBars } from '../mergeUtils';
-
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
-/** Build a minimal raw bar with time in seconds. */
-function rawBar(
-  timeSec: number,
-  open: number,
-  high: number,
-  low: number,
-  close: number,
-  volume = 1,
-  isClosed = false,
-): RawOHLCV {
-  return { time: timeSec, open, high, low, close, volume, isClosed };
-}
-
-/** Build a raw bar with time in milliseconds. */
-function rawBarMs(timeSec: number, open: number, high: number, low: number, close: number): RawOHLCV {
-  return { time: timeSec * 1000, open, high, low, close, volume: 1 };
-}
-
-// 1-minute boundary: 2024-07-03T10:00:00Z = 1719997200 seconds
-const T0 = 1_719_997_200;
-const T1 = T0 + 60;
-const T2 = T0 + 120;
-const T3 = T0 + 180;
-const T4 = T0 + 240;
-
-// ─── 1. Same-candle update ────────────────────────────────────────────────────
-
-describe('same-candle update (3 ticks, same bucket)', () => {
-  it('produces exactly one candle with correct O/H/L/C', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
-    engine.applyLiveUpdate(rawBar(T0, 100, 108, 96, 107)); // high rises, low drops
-    engine.applyLiveUpdate(rawBar(T0, 100, 107, 97, 106)); // high recedes — not applied
-
-    expect(engine.getBars().length).toBe(1);
-
-    const bar = engine.getLastBar()!;
-    expect(bar.open).toBe(100);   // open preserved from first tick
-    expect(bar.high).toBe(108);   // max of all ticks
-    expect(bar.low).toBe(96);     // min of all ticks
-    expect(bar.close).toBe(106);  // close from latest tick
-  });
-
-  it('returns UpdateResult type "update" for same-candle ticks', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    const r1 = engine.applyLiveUpdate(rawBar(T0, 100, 100, 100, 100));
-    const r2 = engine.applyLiveUpdate(rawBar(T0, 100, 110, 90, 105));
-
-    expect(r1.type).toBe('append');  // first tick is an append
-    expect(r2.type).toBe('update');
-  });
-
-  it('high can never decrease within a candle', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBar(T0, 50, 120, 40, 100));
-    engine.applyLiveUpdate(rawBar(T0, 50,  80, 60,  90)); // high=80 < 120
-
-    expect(engine.getLastBar()!.high).toBe(120);
-  });
-
-  it('low can never increase within a candle', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBar(T0, 50, 120, 40, 100));
-    engine.applyLiveUpdate(rawBar(T0, 50, 110, 75, 105)); // low=75 > 40
-
-    expect(engine.getLastBar()!.low).toBe(40);
-  });
-});
-
-// ─── 2. New-candle append ─────────────────────────────────────────────────────
-
-describe('new-candle append (time advances)', () => {
-  it('appends a second candle and marks first as closed', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
-    const result = engine.applyLiveUpdate(rawBar(T1, 103, 110, 101, 108));
-
-    expect(result.type).toBe('append');
-    expect(engine.getBars().length).toBe(2);
-    expect(engine.getBars()[0]!.isClosed).toBe(true);
-    expect(engine.getBars()[1]!.isClosed).toBe(false);
-  });
-
-  it('appended candle uses the new tick\'s open price', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
-    engine.applyLiveUpdate(rawBar(T1, 200, 210, 195, 205));
-
-    expect(engine.getBars()[1]!.open).toBe(200);
-  });
-});
-
-// ─── 3. Out-of-order discard ──────────────────────────────────────────────────
-
-describe('out-of-order ticks', () => {
-  it('discards ticks older than the current live candle', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBar(T1, 103, 110, 100, 107));  // at T1
-    const result = engine.applyLiveUpdate(rawBar(T0, 100, 120, 95, 115)); // T0 < T1
-
-    expect(result.type).toBe('ignore');
-    expect(engine.getBars().length).toBe(1);
-    expect(engine.getLastBar()!.time).toBe(T1);
-  });
-
-  it('does not change any OHLCV values after discarding', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBar(T1, 103, 110, 100, 107));
-    const snapBefore = { ...engine.getLastBar()! };
-
-    engine.applyLiveUpdate(rawBar(T0, 999, 999, 1, 999));
-
-    expect(engine.getLastBar()!.open).toBe(snapBefore.open);
-    expect(engine.getLastBar()!.high).toBe(snapBefore.high);
-    expect(engine.getLastBar()!.low).toBe(snapBefore.low);
-    expect(engine.getLastBar()!.close).toBe(snapBefore.close);
-  });
-});
-
-// ─── 4. Gap detection ─────────────────────────────────────────────────────────
-
-describe('gap detection', () => {
-  it('fires onGapDetected when a bucket is skipped', () => {
-    const gaps: GapInfo[] = [];
-
-    const engine = new CandleEngine({ onGapDetected: (g) => gaps.push(g) });
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
-    // Jump 3 minutes — T1 and T2 are missing
-    engine.applyLiveUpdate(rawBar(T3, 110, 115, 108, 113));
-
-    expect(gaps.length).toBe(1);
-    expect(gaps[0]!.missingCount).toBe(2);
-    expect(gaps[0]!.fromTimeMs).toBe(T0 * 1000);
-    expect(gaps[0]!.toTimeMs).toBe(T3 * 1000);
-  });
-
-  it('returns UpdateResult type "gap" when a gap occurs', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
-    const result = engine.applyLiveUpdate(rawBar(T4, 103, 108, 101, 106));
-
-    expect(result.type).toBe('gap');
-    if (result.type === 'gap') {
-      expect(result.missingCount).toBe(3);
-    }
-  });
-
-  it('does not fire onGapDetected for consecutive candles', () => {
-    const gapFn = vi.fn();
-    const engine = new CandleEngine({ onGapDetected: gapFn });
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBar(T0, 100, 105, 98, 103));
-    engine.applyLiveUpdate(rawBar(T1, 103, 108, 101, 106));
-
-    expect(gapFn).not.toHaveBeenCalled();
-  });
-});
-
-// ─── 5. Reconnect reconciliation ─────────────────────────────────────────────
-
-describe('handleReconnect', () => {
-  it('deduplicates bars correctly when there is overlap', () => {
-    const engine = new CandleEngine();
-    engine.initialize([
-      rawBar(T0, 100, 105, 98, 103, 10, true),
-      rawBar(T1, 103, 108, 101, 106, 12, true),
-      rawBar(T2, 106, 110, 104, 109, 8,  false), // live
-    ], '1m');
-
-    // Reconnect brings T1 and T2 with corrected values
-    engine.handleReconnect([
-      rawBar(T1, 103, 112, 99, 111, 15, true),   // corrected T1
-      rawBar(T2, 106, 111, 103, 110, 9, false),   // corrected T2 (live)
-    ]);
-
-    expect(engine.getBars().length).toBe(3);
-    expect(engine.getBars()[1]!.high).toBe(112);   // T1 updated
-    expect(engine.getBars()[2]!.high).toBe(111);   // T2 updated
-  });
-
-  it('fires onResync after handleReconnect', () => {
-    const resyncFn = vi.fn();
-    const engine = new CandleEngine({ onResync: resyncFn });
-    engine.initialize([rawBar(T0, 100, 105, 98, 103)], '1m');
-
-    engine.handleReconnect([rawBar(T0, 100, 107, 96, 104)]);
-
-    expect(resyncFn).toHaveBeenCalledOnce();
-  });
-});
-
-// ─── 6. ms → s timestamp conversion ─────────────────────────────────────────
-
-describe('millisecond vs second timestamp normalisation', () => {
-  it('converts ms timestamps to seconds correctly', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    // T0 in ms
-    engine.applyLiveUpdate(rawBarMs(T0, 100, 105, 98, 103));
-
-    const bar = engine.getLastBar()!;
-    expect(bar.time).toBe(T0);              // chart field = seconds
-    expect(bar.timeMs).toBe(T0 * 1000);     // engine field = ms
-  });
-
-  it('handles both ms and s inputs in the same session without corruption', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    engine.applyLiveUpdate(rawBarMs(T0, 100, 105, 98, 103));   // ms
-    engine.applyLiveUpdate(rawBar(T0, 100, 110, 95, 108));      // seconds, same bucket
-
-    expect(engine.getBars().length).toBe(1);  // same bucket → still one candle
-    expect(engine.getLastBar()!.high).toBe(110);
-  });
-
-  it('floors ms timestamp to candle boundary', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    // T0 + 30s (mid-candle) in ms → should still map to T0 bucket
-    engine.applyLiveUpdate({ time: (T0 + 30) * 1000, open: 100, high: 105, low: 98, close: 103 });
-
-    expect(engine.getLastBar()!.time).toBe(T0);
-  });
-});
-
-// ─── 7. Custom timeframe aggregation (timeframeUtils) ────────────────────────
-
-describe('timeframeUtils helpers', () => {
-  it('timeframeToMs returns correct durations', () => {
-    expect(timeframeToMs('1m')).toBe(60_000);
-    expect(timeframeToMs('5m')).toBe(300_000);
-    expect(timeframeToMs('1h')).toBe(3_600_000);
-    expect(timeframeToMs('4h')).toBe(14_400_000);
-    expect(timeframeToMs('1d')).toBe(86_400_000);
-    // 1w and 1M are calendar timeframes — no fixed ms duration.
-    // timeframeUtils returns the 60_000 compat fallback so CandleEngine
-    // always receives a finite number (calendar alignment is handled separately).
-    expect(timeframeToMs('1w')).toBe(60_000);
-  });
-
-  it('timeframeToMs falls back to 60_000 for unknown labels', () => {
-    // '3h' and '8h' are orphaned (excluded from canonical registry) → 60_000 fallback.
-    // '2m' is now registered (120_000) — use genuinely unknown keys here.
-    expect(timeframeToMs('3h')).toBe(60_000);
-    expect(timeframeToMs('')).toBe(60_000);
-  });
-
-  it('getBucketStart floors to candle boundary', () => {
-    expect(getBucketStart(62_000, 60_000)).toBe(60_000);        // 1m01s → 1m00s
-    expect(getBucketStart(3_720_000, 3_600_000)).toBe(3_600_000); // 1h02m → 1h00m
-    expect(getBucketStart(0, 60_000)).toBe(0);
-  });
-
-  it('5m candle engine buckets a mid-bar tick to the 5m open', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '5m');
-
-    const T5m = getBucketStart(T0 * 1000, timeframeToMs('5m')); // floor T0 to 5m
-    const mid  = T5m / 1000 + 120; // 2 minutes into the 5m bucket
-
-    engine.applyLiveUpdate({ time: mid, open: 50, high: 55, low: 48, close: 52 });
-
-    expect(engine.getLastBar()!.timeMs).toBe(T5m);
-  });
-});
-
-// ─── 8. mergeUtils helpers ────────────────────────────────────────────────────
-
-describe('mergeUtils helpers', () => {
-  const makeBar = (timeSec: number, close: number, isClosed: boolean): CandleBar => ({
-    timeMs: timeSec * 1000,
-    time: timeSec,
-    open: 100, high: 110, low: 90, close,
-    volume: 1, isClosed,
-  });
-
-  it('getMissingBarCount returns 0 for consecutive bars', () => {
-    expect(getMissingBarCount(T0 * 1000, T1 * 1000, 60_000)).toBe(0);
-  });
-
-  it('getMissingBarCount returns correct count for gap', () => {
-    expect(getMissingBarCount(T0 * 1000, T3 * 1000, 60_000)).toBe(2); // T1 and T2
-    expect(getMissingBarCount(T0 * 1000, T4 * 1000, 60_000)).toBe(3); // T1, T2, T3
-  });
-
-  it('mergeBars deduplicates by timeMs with incoming winning', () => {
-    const existing = [makeBar(T0, 103, true), makeBar(T1, 106, true)];
-    const incoming = [makeBar(T1, 999, true), makeBar(T2, 110, false)]; // T1 override
-
-    const merged = mergeBars(existing, incoming);
-
-    expect(merged.length).toBe(3);
-    expect(merged[1]!.close).toBe(999); // incoming wins for closed bar
-    expect(merged[2]!.time).toBe(T2);
-  });
-
-  it('mergeBars preserves existing live candle when incoming is also live and same time', () => {
-    const existing = [makeBar(T0, 103, false)]; // live, close=103
-    const incoming = [makeBar(T0, 107, false)]; // fresher live tick, close=107
-
-    const merged = mergeBars(existing, incoming);
-
-    // Live bar: incoming wins because it is the freshest tick
-    expect(merged[0]!.close).toBe(107);
-  });
-
-  it('mergeBars sorts output by timeMs', () => {
-    const bars = [makeBar(T2, 100, true), makeBar(T0, 100, true), makeBar(T1, 100, true)];
-    const sorted = mergeBars(bars, []);
-    expect(sorted.map(b => b.time)).toEqual([T0, T1, T2]);
-  });
-});
-
-// ─── 9. backfillGap ───────────────────────────────────────────────────────────
-
-describe('backfillGap', () => {
-  it('fills missing buckets and fires onResync', () => {
-    const resyncFn = vi.fn();
-
-    const engine = new CandleEngine({ onResync: resyncFn });
-    engine.initialize([
-      rawBar(T0, 100, 105, 98, 103),
-      rawBar(T3, 110, 115, 108, 113),  // gap: T1, T2 missing
-    ], '1m');
-
-    engine.backfillGap([
-      rawBar(T1, 103, 108, 101, 106),
-      rawBar(T2, 106, 110, 104, 109),
-    ]);
-
-    expect(engine.getBars().length).toBe(4);
-    expect(resyncFn).toHaveBeenCalledOnce();
-
-    const times = engine.getBars().map(b => b.time);
-    expect(times).toEqual([T0, T1, T2, T3]);
-  });
-});
-
-// ─── 10. CandleEngine lifecycle ──────────────────────────────────────────────
-
-describe('lifecycle', () => {
-  it('reset() clears all bars', () => {
-    const engine = new CandleEngine();
-    engine.initialize([rawBar(T0, 100, 105, 98, 103)], '1m');
-
-    engine.reset();
-
-    expect(engine.getBars().length).toBe(0);
-    expect(engine.getLastBar()).toBeNull();
-  });
-
-  it('handles initialize() with empty history', () => {
-    const engine = new CandleEngine();
-    engine.initialize([], '1m');
-
-    expect(engine.getBars().length).toBe(0);
-    expect(engine.getLastBar()).toBeNull();
-  });
-
-  it('handles duplicate historical bars (keeps last per timeMs)', () => {
-    const engine = new CandleEngine();
-    engine.initialize([
-      rawBar(T0, 100, 105, 98, 103),
-      rawBar(T0, 100, 110, 96, 108), // same time, last should win
-    ], '1m');
-
-    expect(engine.getBars().length).toBe(1);
-    expect(engine.getLastBar()!.high).toBe(110);
-  });
-});

package/src/engine/candleInvariants.ts

@@ -1,172 +0,0 @@
-/**
- * Candle Invariant Guards
- *
- * Defensive assertions for the CandleEngine update pipeline.
- * All guards are no-ops in production (`NODE_ENV === 'production'`).
- *
- * Design principles:
- *   - Each guard checks exactly ONE invariant and logs a descriptive warning.
- *   - Guards never throw by default — they warn so streaming data is never blocked.
- *   - Call sites pass a `context` string that identifies where the check ran.
- *   - A test harness can replace `_reporter` to assert on violations.
- *
- * Usage:
- *   import { assertOhlcRelationships, assertNotFinalized } from './candleInvariants';
- */
-
-import type { CandleBar } from './CandleEngine';
-import { getCalendarBucketStart } from './timeframeUtils';
-
-// ─── Reporter (swappable in tests) ───────────────────────────────────────────
-
-/** Called for every invariant violation.  Replaced in unit tests. */
-export let _reporter: (message: string) => void = (msg) => console.warn(msg);
-
-/** Replace the violation reporter (for unit-test assertions). */
-export function _setReporter(fn: (message: string) => void): void {
-  _reporter = fn;
-}
-
-/** Re-install the default console.warn reporter. */
-export function _resetReporter(): void {
-  _reporter = (msg) => console.warn(msg);
-}
-
-// ─── Dev guard ───────────────────────────────────────────────────────────────
-
-function isDevMode(): boolean {
-  // Access process via globalThis to avoid relying on @types/node in browser builds
-  const nodeEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } })
-    .process?.env?.['NODE_ENV'];
-  return nodeEnv !== 'production';
-}
-
-function violation(context: string, message: string): void {
-  _reporter(`[CANDLE_INVARIANT] ${context}: ${message}`);
-}
-
-// ─── Guards ───────────────────────────────────────────────────────────────────
-
-/**
- * Verify that `high >= open, close, low` and `low <= open, close`.
- *
- * Floats from external feeds can occasionally violate these due to rounding.
- * This guard surfaces them immediately rather than silently corrupting the chart.
- */
-export function assertOhlcRelationships(bar: CandleBar, context: string): void {
-  if (!isDevMode()) return;
-
-  const { open, high, low, close, timeMs } = bar;
-
-  if (high < open)  violation(context, `high(${high}) < open(${open})  at timeMs=${timeMs}`);
-  if (high < close) violation(context, `high(${high}) < close(${close}) at timeMs=${timeMs}`);
-  if (high < low)   violation(context, `high(${high}) < low(${low})   at timeMs=${timeMs}`);
-  if (low  > open)  violation(context, `low(${low}) > open(${open})   at timeMs=${timeMs}`);
-  if (low  > close) violation(context, `low(${low}) > close(${close}) at timeMs=${timeMs}`);
-}
-
-/**
- * Verify that `bar.timeMs` is exactly equal to the candle-open boundary for the
- * given timeframe.  If it is not, `normalizeOhlcv` or `getCalendarBucketStart`
- * has a bug.
- */
-export function assertBucketAlignment(bar: CandleBar, tf: string, context: string): void {
-  if (!isDevMode()) return;
-
-  const expected = getCalendarBucketStart(bar.timeMs, tf);
-  if (bar.timeMs !== expected) {
-    violation(
-      context,
-      `timeMs(${bar.timeMs}) ≠ bucketStart(${expected}) for tf=${tf} ` +
-      `(delta=${bar.timeMs - expected} ms)`,
-    );
-  }
-}
-
-/**
- * Verify that we are NOT about to mutate a candle that has already been finalised
- * (`isClosed === true`).  Mutating a closed candle corrupts the historical record.
- *
- * Triggers on: same-bucket update landing on a bar already marked closed.
- */
-export function assertNotFinalized(bar: CandleBar, context: string): void {
-  if (!isDevMode()) return;
-
-  if (bar.isClosed) {
-    violation(
-      context,
-      `attempted to mutate a finalized (isClosed=true) candle at timeMs=${bar.timeMs}`,
-    );
-  }
-}
-
-/**
- * Verify that a same-bucket update did NOT silently overwrite the candle's `open`.
- *
- * The first tick's open is authoritative; subsequent updates for the same bucket
- * must preserve it.  Call this AFTER the in-place mutation with the captured
- * `prevOpen` value.
- */
-export function assertOpenImmutability(
-  prevOpen: number,
-  bar: CandleBar,
-  context: string,
-): void {
-  if (!isDevMode()) return;
-
-  if (bar.open !== prevOpen) {
-    violation(
-      context,
-      `open changed from ${prevOpen} → ${bar.open} on same-bucket update ` +
-      `at timeMs=${bar.timeMs} — first-tick open is authoritative`,
-    );
-  }
-}
-
-/**
- * Verify that a same-bucket update does NOT append a new bar instead of
- * updating the existing one.
- *
- * Call after an in-place update with the pre- and post-update bar counts.
- */
-export function assertNoDuplicateAppend(
-  prevCount: number,
-  nextCount: number,
-  context: string,
-): void {
-  if (!isDevMode()) return;
-
-  if (nextCount > prevCount) {
-    violation(
-      context,
-      `same-bucket update incremented bar count from ${prevCount} → ${nextCount} ` +
-      `(should have updated in-place, not appended)`,
-    );
-  }
-}
-
-/**
- * Verify that a new-bucket append does NOT reduce the bar count or silently
- * overwrite a finalized candle (would require bar count to stay the same while
- * the last bar's timeMs changes, which the engine never does).
- *
- * Call after appending a new bar with the previous last bar for comparison.
- */
-export function assertFinalizedUnchanged(
-  prevLastBar: Readonly<CandleBar>,
-  currentBars: readonly CandleBar[],
-  context: string,
-): void {
-  if (!isDevMode()) return;
-
-  const prevIndex = currentBars.findIndex(b => b.timeMs === prevLastBar.timeMs);
-  if (prevIndex === -1) return; // bar may have been legitimately removed by merge
-
-  const preserved = currentBars[prevIndex]!;
-  if (!preserved.isClosed) {
-    violation(
-      context,
-      `bar at timeMs=${prevLastBar.timeMs} should be isClosed=true after new-bucket append`,
-    );
-  }
-}