@363045841yyt/klinechart-core 0.8.11-alpha.0 → 0.8.12

package/src/components/mtfOverlay/alignToBaseIndex.ts

@@ -0,0 +1,108 @@
+import { KLineChartError } from '../../errors'
+/**
+ * Forward-fill a higher-timeframe series onto the base bar index, with strict
+ * no-lookahead semantics.
+ *
+ * The rule, restated:
+ *   A higher-tf bar opens at `hbar.timestamp` and covers the half-open
+ *   interval `[hbar.timestamp, hbar.timestamp + targetIntervalMs)`. The
+ *   higher-tf value at that bar is available to every base bar whose
+ *   timestamp falls inside that interval — and only those base bars.
+ *
+ * Forward fill is implicit: because higher-tf bars are contiguous in time
+ * (within the input series), a base bar at time `t` reads the value of the
+ * higher-tf bar whose half-open interval contains `t`. If no such bar exists
+ * (i.e. `t` is before the first higher-tf bar's open), the output is `null`.
+ *
+ * Gap handling: if the higher-tf series has a hole (bar N+1's open is more
+ * than `targetIntervalMs` after bar N's open), base bars in that hole get the
+ * value of bar N. This matches the forward-fill intuition users have — once
+ * a higher-tf value exists, it stays visible until the next bucket opens.
+ *
+ * Lookahead-bias test (spelled out so it survives regressions):
+ *   - hbar opens at 09:00 with value 100, targetIntervalMs = 1h.
+ *   - base bar at 09:00 → value 100 (open of the bucket).
+ *   - base bar at 09:59 → value 100 (still inside the bucket).
+ *   - base bar at 08:55 → null (before the bucket opens — using 100 here
+ *     would be lookahead).
+ *
+ * Performance: O(B + H) using a synced two-pointer walk (both inputs are
+ * sorted by timestamp). Callers typically have B ≫ H (many fine bars per
+ * coarse bar), so we step through `baseBars` linearly while advancing the
+ * higher-tf cursor whenever the next bucket opens at or before `t`.
+ */
+
+/**
+ * @internal — building block used by `createMtfController`. Reachable today
+ *   via the top-level `@klinechart-quant/core` barrel but **NOT
+ *   part of the supported public API**. typedoc / api-extractor
+ *   hide it from generated docs. Prefer the controller factory
+ *   for stable user code. Closes API audit BLOCKER-002.
+ */
+export function alignToBaseIndex<TValue>(
+    baseBars: ReadonlyArray<{ timestamp: number }>,
+    higherTfBars: ReadonlyArray<{ timestamp: number }>,
+    higherTfValues: ReadonlyArray<TValue>,
+    targetIntervalMs: number,
+): ReadonlyArray<TValue | null> {
+    if (!Number.isFinite(targetIntervalMs) || targetIntervalMs <= 0) {
+        throw new KLineChartError(
+            'MTF_CONFIG_INVALID',
+            'alignToBaseIndex: targetIntervalMs must be a positive finite number',
+        )
+    }
+    if (higherTfBars.length !== higherTfValues.length) {
+        throw new KLineChartError(
+            'MTF_CONFIG_INVALID',
+            `alignToBaseIndex: higherTfBars.length (${higherTfBars.length}) must ` +
+                `equal higherTfValues.length (${higherTfValues.length})`,
+        )
+    }
+
+    const B = baseBars.length
+    const H = higherTfBars.length
+    const out: (TValue | null)[] = new Array(B)
+
+    if (B === 0) return out
+    if (H === 0) {
+        for (let i = 0; i < B; i++) out[i] = null
+        return out
+    }
+
+    // Two-pointer walk. `h` is the index of the higher-tf bar that COULD
+    // cover the current base bar — meaning `higherTfBars[h].timestamp <= t`.
+    // We advance `h` greedily as base bars march forward.
+    let h = -1 // -1 ≡ "no higher-tf bar has opened yet"
+
+    for (let i = 0; i < B; i++) {
+        const t = baseBars[i].timestamp
+
+        // Advance `h` to the latest higher-tf bar whose open is ≤ t. This is
+        // the "no lookahead" gate: a bar whose open > t is invisible to us.
+        while (h + 1 < H && higherTfBars[h + 1].timestamp <= t) {
+            h++
+        }
+
+        if (h < 0) {
+            // No higher-tf bar has opened at or before t → leading null.
+            out[i] = null
+            continue
+        }
+
+        // We have a candidate bar `h`. Final check: is t still inside its
+        // half-open interval? If `higherTfBars[h+1]` exists and its open is
+        // ≤ t, the while loop above would have advanced — so we only need to
+        // check the upper bound for the last bar, or in a gap.
+        const bucketStart = higherTfBars[h].timestamp
+        if (t < bucketStart + targetIntervalMs) {
+            out[i] = higherTfValues[h]
+        } else {
+            // t falls into a gap after bar h's closed interval and before
+            // the next bar opens (or after the end of the series). Forward
+            // fill: keep bar h's value visible.
+            out[i] = higherTfValues[h]
+        }
+    }
+
+    return out
+}

package/src/components/mtfOverlay/createMtfController.ts

@@ -0,0 +1,180 @@
+import { KLineChartError } from '../../errors'
+/**
+ * Multi-Timeframe overlay controller.
+ *
+ * Composes `resampleBars` + `alignToBaseIndex` + a user-supplied `compute`
+ * function per series. Holds the base bar buffer + base interval + a Map of
+ * active series, exposes a single reactive `series` signal.
+ *
+ * v1 implementation: full re-resample + full compute on every mutation. The
+ * incremental "only re-do the last bucket on `appendBaseBar`" optimization
+ * is documented as a follow-up — landing it does not change observable
+ * behavior, only frame-time cost. Tests pin the observable shape.
+ */
+
+import { createSignal } from '../../reactivity'
+import type { Signal } from '../../reactivity'
+import { resampleBars } from './resampleBars'
+import { alignToBaseIndex } from './alignToBaseIndex'
+import type {
+    ActiveMtfSeries,
+    BaseBar,
+    MtfController,
+    MtfSeriesDefinition,
+    ResampledBar,
+} from './types'
+
+export interface CreateMtfControllerInit {
+    initialBars?: ReadonlyArray<BaseBar>
+    baseIntervalMs?: number
+}
+
+export function createMtfController(init: CreateMtfControllerInit = {}): MtfController {
+    let disposed = false
+    let baseBars: ReadonlyArray<BaseBar> = init.initialBars ?? []
+    let baseIntervalMs: number | null = init.baseIntervalMs ?? null
+
+    const definitions = new Map<string, MtfSeriesDefinition>()
+    const seriesSignal = createSignal<ReadonlyArray<ActiveMtfSeries>>([])
+
+    const computeOne = (def: MtfSeriesDefinition): ActiveMtfSeries => {
+        // No bars or no base interval set → empty aligned values (length 0,
+        // matching the empty base buffer).
+        if (baseBars.length === 0 || baseIntervalMs === null) {
+            return { definition: def, alignedValues: [] }
+        }
+        const resampled: ReadonlyArray<ResampledBar> = resampleBars(
+            baseBars,
+            baseIntervalMs,
+            def.targetIntervalMs,
+        )
+        const values = def.compute(resampled)
+        if (values.length !== resampled.length) {
+            throw new KLineChartError(
+                'MTF_CONFIG_INVALID',
+                `MtfController: compute fn for series "${def.id}" returned ` +
+                    `${values.length} values for ${resampled.length} resampled bars; ` +
+                    `length must match`,
+            )
+        }
+        const aligned = alignToBaseIndex(
+            baseBars,
+            resampled,
+            values,
+            def.targetIntervalMs,
+        )
+        return { definition: def, alignedValues: aligned }
+    }
+
+    const recomputeAll = (): void => {
+        const all: ActiveMtfSeries[] = []
+        for (const def of definitions.values()) {
+            all.push(computeOne(def))
+        }
+        seriesSignal.set(all)
+    }
+
+    const guard = (): boolean => !disposed
+
+    const validateInterval = (targetMs: number): void => {
+        if (!Number.isFinite(targetMs) || targetMs <= 0) {
+            throw new KLineChartError('MTF_CONFIG_INVALID', 'MtfController: targetIntervalMs must be > 0')
+        }
+        if (baseIntervalMs !== null && targetMs % baseIntervalMs !== 0) {
+            throw new KLineChartError(
+                'MTF_CONFIG_INVALID',
+                `MtfController: targetIntervalMs (${targetMs}) must be an ` +
+                    `integer multiple of baseIntervalMs (${baseIntervalMs})`,
+            )
+        }
+    }
+
+    const inner: {
+        series: Signal<ReadonlyArray<ActiveMtfSeries>>
+        setBaseBars(bars: ReadonlyArray<BaseBar>, intervalMs: number): void
+        addSeries(def: MtfSeriesDefinition): string
+        removeSeries(id: string): boolean
+        updateSeries(id: string, patch: Partial<Omit<MtfSeriesDefinition, 'id'>>): boolean
+        appendBaseBar(bar: BaseBar): void
+        dispose(): void
+    } = {
+        series: seriesSignal,
+
+        setBaseBars(bars: ReadonlyArray<BaseBar>, intervalMs: number): void {
+            if (!guard()) return
+            if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+                throw new KLineChartError('MTF_CONFIG_INVALID', 'MtfController.setBaseBars: baseIntervalMs must be > 0')
+            }
+            // If any series has a target that no longer cleanly divides, throw
+            // up front rather than letting resampleBars throw later.
+            for (const def of definitions.values()) {
+                if (def.targetIntervalMs % intervalMs !== 0) {
+                    throw new KLineChartError(
+                        'MTF_CONFIG_INVALID',
+                        `MtfController.setBaseBars: existing series "${def.id}" ` +
+                            `targetIntervalMs (${def.targetIntervalMs}) does not cleanly ` +
+                            `divide new baseIntervalMs (${intervalMs})`,
+                    )
+                }
+            }
+            baseBars = bars
+            baseIntervalMs = intervalMs
+            recomputeAll()
+        },
+
+        addSeries(def): string {
+            if (!guard()) return def.id
+            if (definitions.has(def.id)) {
+                throw new KLineChartError('MTF_CONFIG_INVALID', `MtfController.addSeries: id "${def.id}" already in use`)
+            }
+            validateInterval(def.targetIntervalMs)
+            definitions.set(def.id, def)
+            recomputeAll()
+            return def.id
+        },
+
+        removeSeries(id): boolean {
+            if (!guard()) return false
+            const had = definitions.delete(id)
+            if (had) recomputeAll()
+            return had
+        },
+
+        updateSeries(id, patch): boolean {
+            if (!guard()) return false
+            const existing = definitions.get(id)
+            if (existing === undefined) return false
+            const next: MtfSeriesDefinition = {
+                ...existing,
+                ...patch,
+                id: existing.id, // protect against accidental id mutation
+            }
+            if (patch.targetIntervalMs !== undefined) {
+                validateInterval(patch.targetIntervalMs)
+            }
+            definitions.set(id, next)
+            recomputeAll()
+            return true
+        },
+
+        appendBaseBar(bar): void {
+            if (!guard()) return
+            baseBars = [...baseBars, bar]
+            recomputeAll()
+        },
+
+        dispose(): void {
+            disposed = true
+            definitions.clear()
+        },
+    }
+
+    // Canonical verbs (API audit BLOCKER-001): `setData` for full
+    // replacement, `append` for single-item extension. Old names
+    // preserved as aliases on the inner object for the deprecation window.
+    return {
+        ...inner,
+        setData: inner.setBaseBars,
+        append: inner.appendBaseBar,
+    }
+}

package/src/components/mtfOverlay/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Multi-Timeframe (MTF) overlay barrel.
+ *
+ * Public surface:
+ *   - `resampleBars`: aggregate base-tf bars into higher-tf buckets
+ *   - `alignToBaseIndex`: forward-fill higher-tf values onto base-bar indices
+ *     (no-lookahead semantics, see file docstring)
+ *   - `createMtfController`: composes the above + a user-supplied `compute`
+ *     into a reactive multi-series controller
+ *
+ * The controller is intentionally indicator-agnostic — any indicator (EMA,
+ * RSI, custom) can be lifted to MTF by passing a `compute` fn that takes
+ * resampled bars and returns one number per bar.
+ */
+
+export type {
+    BaseBar,
+    ResampledBar,
+    MtfSeriesDefinition,
+    ActiveMtfSeries,
+    MtfController,
+} from './types'
+
+export { resampleBars } from './resampleBars'
+export { alignToBaseIndex } from './alignToBaseIndex'
+export { createMtfController, type CreateMtfControllerInit } from './createMtfController'

package/src/components/mtfOverlay/resampleBars.ts

@@ -0,0 +1,134 @@
+import { KLineChartError } from '../../errors'
+/**
+ * Resample a base-timeframe bar series to a higher timeframe.
+ *
+ * Two design choices worth pinning:
+ *
+ * 1. We bucket by **floor(timestamp / targetIntervalMs) * targetIntervalMs**,
+ *    not by counting base bars. This is robust to gaps in the input — a
+ *    1-minute series that skips 09:33 (the bar simply isn't there) will still
+ *    correctly group 09:30..09:34 into one 5m bucket and produce no synthetic
+ *    bar for 09:33.
+ *
+ * 2. The final bucket is allowed to be **partial** (contain fewer base bars
+ *    than `targetIntervalMs / baseIntervalMs`). This is the right default for
+ *    live charts: the forming bar must appear in the output so its EMA / RSI
+ *    can be plotted. Callers that want "closed bars only" should drop the
+ *    last element if `bucketEnd > lastBucketStart + targetIntervalMs - baseIntervalMs`
+ *    (or equivalently, if `sourceEnd - sourceStart + 1 < bucketSize`).
+ *
+ * Aggregation rules:
+ *   - timestamp = floor(firstBar.timestamp / targetIntervalMs) * targetIntervalMs
+ *   - open  = firstBar.open
+ *   - close = lastBar.close
+ *   - high  = max over [start, end]
+ *   - low   = min over [start, end]
+ *   - volume = sum over [start, end]
+ *   - sourceStart, sourceEnd = inclusive base-index range
+ */
+
+import type { BaseBar, ResampledBar } from './types'
+
+/**
+ * @internal — building block used by `createMtfController`. Reachable today
+ *   via the top-level `@klinechart-quant/core` barrel but **NOT
+ *   part of the supported public API**. typedoc / api-extractor
+ *   hide it from generated docs. Prefer the controller factory
+ *   for stable user code. Closes API audit BLOCKER-002.
+ */
+export function resampleBars(
+    bars: ReadonlyArray<BaseBar>,
+    baseIntervalMs: number,
+    targetIntervalMs: number,
+): ReadonlyArray<ResampledBar> {
+    if (!Number.isFinite(baseIntervalMs) || baseIntervalMs <= 0) {
+        throw new KLineChartError('MTF_CONFIG_INVALID', 'resampleBars: baseIntervalMs must be a positive finite number')
+    }
+    if (!Number.isFinite(targetIntervalMs) || targetIntervalMs <= 0) {
+        throw new KLineChartError('MTF_CONFIG_INVALID', 'resampleBars: targetIntervalMs must be a positive finite number')
+    }
+    if (targetIntervalMs % baseIntervalMs !== 0) {
+        throw new KLineChartError(
+            'MTF_CONFIG_INVALID',
+            `resampleBars: targetIntervalMs (${targetIntervalMs}) must be an integer ` +
+                `multiple of baseIntervalMs (${baseIntervalMs}); got remainder ` +
+                `${targetIntervalMs % baseIntervalMs}`,
+        )
+    }
+
+    if (bars.length === 0) return []
+
+    // Fast path: no aggregation required. Caller may still want shape parity
+    // (each base bar gets sourceStart === sourceEnd === its own index), so we
+    // wrap each base bar as a 1-source-bar `ResampledBar`.
+    if (targetIntervalMs === baseIntervalMs) {
+        const out: ResampledBar[] = new Array(bars.length)
+        for (let i = 0; i < bars.length; i++) {
+            const b = bars[i]
+            out[i] = {
+                timestamp: b.timestamp,
+                open: b.open,
+                high: b.high,
+                low: b.low,
+                close: b.close,
+                volume: b.volume,
+                sourceStart: i,
+                sourceEnd: i,
+            }
+        }
+        return out
+    }
+
+    const out: ResampledBar[] = []
+
+    let bucketStart = -1 // inclusive index in `bars`
+    let bucketTs = 0
+    let open = 0
+    let high = -Infinity
+    let low = Infinity
+    let close = 0
+    let volume = 0
+
+    const flush = (endIdx: number): void => {
+        if (bucketStart < 0) return
+        out.push({
+            timestamp: bucketTs,
+            open,
+            high,
+            low,
+            close,
+            volume,
+            sourceStart: bucketStart,
+            sourceEnd: endIdx,
+        })
+    }
+
+    for (let i = 0; i < bars.length; i++) {
+        const bar = bars[i]
+        const ts = Math.floor(bar.timestamp / targetIntervalMs) * targetIntervalMs
+
+        if (bucketStart < 0 || ts !== bucketTs) {
+            // Boundary crossed (or first iteration). Flush the previous bucket.
+            if (bucketStart >= 0) flush(i - 1)
+            bucketStart = i
+            bucketTs = ts
+            open = bar.open
+            high = bar.high
+            low = bar.low
+            close = bar.close
+            volume = bar.volume
+            continue
+        }
+
+        // Same bucket: fold this bar in.
+        if (bar.high > high) high = bar.high
+        if (bar.low < low) low = bar.low
+        close = bar.close
+        volume += bar.volume
+    }
+
+    // Final bucket — may be partial (fewer than targetIntervalMs/baseIntervalMs bars).
+    flush(bars.length - 1)
+
+    return out
+}

package/src/components/mtfOverlay/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Public types for the Multi-Timeframe (MTF) overlay module.
+ *
+ * Naming: "base" = the chart's primary timeframe (e.g. 5m), "higher tf" =
+ * the resampled timeframe an MTF series lives on (e.g. 1h). The module never
+ * downscales — you can only lift values from a coarser tf onto a finer one.
+ *
+ * Time semantics:
+ *   - Every `timestamp` is in milliseconds since the Unix epoch.
+ *   - A base bar's `timestamp` is the OPEN of that bar's interval (aligned
+ *     to `baseIntervalMs` boundary, implicitly).
+ *   - A resampled (higher-tf) bar's `timestamp` is the OPEN of its bucket,
+ *     computed as `floor(firstBaseBar.timestamp / targetIntervalMs) * targetIntervalMs`.
+ *   - A higher-tf bar's interval is `[timestamp, timestamp + targetIntervalMs)`.
+ *
+ * The MTF controller does NOT bring its own indicator math. The caller
+ * supplies a `compute` function that takes resampled bars and returns one
+ * number per resampled bar. Any indicator (EMA, RSI, custom) can be lifted
+ * to MTF by writing such a compute fn.
+ */
+
+import type { Signal } from '../../reactivity'
+
+/**
+ * One bar of the BASE timeframe (the chart's primary candle stream).
+ *
+ * `timestamp` is the bar's OPEN, expected to be aligned to `baseIntervalMs`.
+ * The module does not enforce alignment — it trusts the caller's stream.
+ */
+export interface BaseBar {
+    timestamp: number
+    open: number
+    high: number
+    low: number
+    close: number
+    volume: number
+}
+
+/**
+ * A bar produced by aggregating `[sourceStart, sourceEnd]` (inclusive
+ * indices into the input base-bar array) up to a higher timeframe.
+ *
+ * `sourceEnd === sourceStart` is allowed (single-base-bar bucket) — see
+ * the "partial last bucket" semantics in `resampleBars`.
+ */
+export interface ResampledBar extends BaseBar {
+    /** First base-bar index aggregated into this bucket (inclusive). */
+    sourceStart: number
+    /** Last base-bar index aggregated into this bucket (inclusive). */
+    sourceEnd: number
+}
+
+/**
+ * Definition of one MTF series. The controller owns the resampling and the
+ * alignment; the caller owns the indicator math (`compute`).
+ */
+export interface MtfSeriesDefinition {
+    /** Stable user-facing identifier. Re-using an existing id is rejected. */
+    id: string
+    /** Display label, e.g. `"EMA(20) 1h"`. The controller never reads this. */
+    label: string
+    /** Higher-tf bucket size in ms. Must be a positive multiple of base tf. */
+    targetIntervalMs: number
+    /**
+     * Pure function: resampled bars → per-bar value array of the same length.
+     * Called once per `setBaseBars`, `addSeries`, `updateSeries`, and once per
+     * `appendBaseBar`. MUST NOT mutate the input.
+     */
+    compute: (resampledBars: ReadonlyArray<ResampledBar>) => ReadonlyArray<number>
+}
+
+/**
+ * One active MTF series in the controller's snapshot.
+ *
+ * `alignedValues.length === baseBars.length` always holds after any state
+ * transition. Leading entries are `null` for base bars that fall before the
+ * first higher-tf bucket opens.
+ */
+export interface ActiveMtfSeries {
+    definition: MtfSeriesDefinition
+    /**
+     * Forward-filled values aligned to the base bar index. Same length as the
+     * controller's base-bar buffer. `null` only where no higher-tf bar covers
+     * the base bar's timestamp (i.e. before the first bucket opens).
+     */
+    alignedValues: ReadonlyArray<number | null>
+}
+
+/**
+ * Reactive MTF controller. The `series` signal updates synchronously on every
+ * state-mutating call (`setBaseBars`, `addSeries`, `removeSeries`,
+ * `updateSeries`, `appendBaseBar`). After `dispose()`, mutation calls become
+ * no-ops and the signal stops firing.
+ */
+export interface MtfController {
+    /** Current snapshot of every series with aligned values. */
+    readonly series: Signal<ReadonlyArray<ActiveMtfSeries>>
+
+    /**
+     * Replace the base bar buffer in one shot and recompute every series —
+     * canonical method, aligned with the cross-controller `setData()`
+     * convention (AnchoredVwapController). Closes API audit BLOCKER-001.
+     * `baseIntervalMs` must evenly divide every series' `targetIntervalMs`.
+     */
+    setData(bars: ReadonlyArray<BaseBar>, baseIntervalMs: number): void
+
+    /**
+     * @deprecated since 0.1.0-alpha.1 — use {@link MtfController.setData}.
+     * Preserved as a non-removing alias for at least 6 months.
+     */
+    setBaseBars(bars: ReadonlyArray<BaseBar>, baseIntervalMs: number): void
+
+    /**
+     * Register a new series. Returns the series id.
+     * Throws if `def.id` is already in use or `targetIntervalMs` is not a
+     * positive multiple of the current `baseIntervalMs` (when bars are set).
+     */
+    addSeries(def: MtfSeriesDefinition): string
+
+    /** Remove a series by id. Returns true if removed, false if not found. */
+    removeSeries(id: string): boolean
+
+    /**
+     * Patch a series in place. Returns true if found.
+     * Re-runs `compute` whenever `targetIntervalMs` or `compute` changes.
+     */
+    updateSeries(
+        id: string,
+        patch: Partial<Omit<MtfSeriesDefinition, 'id'>>,
+    ): boolean
+
+    /**
+     * Append one base bar at the tail — canonical method, aligned with the
+     * cross-controller `append()` convention (AnchoredVwapController).
+     * Triggers a single per-series compute over the updated resampled
+     * bars — NOT a from-scratch recompute over the whole base buffer.
+     */
+    append(bar: BaseBar): void
+
+    /**
+     * @deprecated since 0.1.0-alpha.1 — use {@link MtfController.append}.
+     * Preserved as a non-removing alias for at least 6 months.
+     */
+    appendBaseBar(bar: BaseBar): void
+
+    /** Tear down. After this, all mutators are no-ops; the signal stops. */
+    dispose(): void
+}