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

package/src/components/anchoredVwap/createAnchoredVwapController.ts

@@ -0,0 +1,358 @@
+/**
+ * Anchored VWAP controller — framework-agnostic, signal-based, multi-anchor.
+ *
+ * Mirrors the dispose-guard pattern from
+ * `createIndicatorSelectorController` and `createVolumeProfileController` so
+ * React/Vue/Angular adapters bridge identically. The controller is pure
+ * data — no DOM, no rendering, no canvas.
+ *
+ * Why multi-anchor with per-anchor running sums:
+ *   TradingView's lower tiers cap the number of simultaneous anchors at
+ *   3 because each AVWAP is recomputed from scratch on every new bar. By
+ *   keeping per-anchor `sumVwp` / `sumVol` / `sumSqDev` totals we drop
+ *   `appendBar` from O(bars-since-anchor) to O(1) per anchor — anchors
+ *   become cheap enough to keep many open at once.
+ *
+ * Equivalence guarantee:
+ *   The point produced by `appendBar` is bit-for-bit identical (to
+ *   floating-point precision) to the point that `computeAnchoredVwap`
+ *   would produce on the same bar at the same anchor — same operands
+ *   added in the same order. The controller test
+ *   `appendBar incrementally matches full recompute` pins this.
+ */
+
+import { createSignal, type Signal } from '../../reactivity'
+import { computeAnchoredVwap } from './computeAnchoredVwap'
+import type {
+    ActiveAnchor,
+    AnchorDefinition,
+    AnchoredVwapController,
+    AVWAPBar,
+    AVWAPPoint,
+} from './types'
+
+// ---------------------------------------------------------------------------
+// Internal state per anchor
+// ---------------------------------------------------------------------------
+
+/**
+ * Mutable per-anchor scratch. We keep this separate from `ActiveAnchor` so
+ * the public signal value only exposes the immutable view (definition +
+ * series) and consumers can rely on structural sharing where it matters.
+ */
+interface AnchorState {
+    definition: AnchorDefinition
+    // Running cumulative sums from the anchor up to and including the last
+    // bar processed. These are what make `appendBar` O(1).
+    sumVwp: number
+    sumVol: number
+    sumSqDev: number
+    // The series produced so far. Each `appendBar` pushes one new point.
+    // Held mutable internally; surfaced as ReadonlyArray.
+    series: AVWAPPoint[]
+}
+
+export interface AnchoredVwapControllerInit {
+    initialBars?: ReadonlyArray<AVWAPBar>
+}
+
+export function createAnchoredVwapController(
+    opts?: AnchoredVwapControllerInit,
+): AnchoredVwapController {
+    // -------------------------------------------------------------------
+    // Internal mutable state — never exposed directly.
+    // -------------------------------------------------------------------
+    // Defensive copy: the caller may reuse the array they pass us. We
+    // capture a snapshot so `appendBar` can extend it without surprising
+    // the caller.
+    let bars: AVWAPBar[] = opts?.initialBars
+        ? opts.initialBars.slice()
+        : []
+    const anchorStates = new Map<string, AnchorState>()
+
+    // -------------------------------------------------------------------
+    // Public signal — re-emitted on every structural change.
+    // -------------------------------------------------------------------
+    const anchors: Signal<ReadonlyArray<ActiveAnchor>> = createSignal<
+        ReadonlyArray<ActiveAnchor>
+    >([])
+
+    /**
+     * Rebuild the public signal value from the current `anchorStates`. We
+     * pass a fresh array reference each time so `Object.is` in
+     * `signal.set` triggers a notify.
+     */
+    function publish(): void {
+        const next: ActiveAnchor[] = []
+        for (const a of anchorStates.values()) {
+            next.push({
+                definition: a.definition,
+                // Snapshot the series so consumers see an immutable
+                // view; future `appendBar` mutations on `a.series` will
+                // only be observed by the next `publish`.
+                series: a.series.slice(),
+            })
+        }
+        anchors.set(next)
+    }
+
+    // -------------------------------------------------------------------
+    // Math helpers — share one definition of the per-bar arithmetic so
+    // `appendBar` and `recomputeAnchor` cannot drift.
+    // -------------------------------------------------------------------
+
+    /**
+     * Recompute an anchor's series from scratch by walking the bars from
+     * `definition.barIndex`. Also resets the running sums so subsequent
+     * `appendBar` calls extend the same totals.
+     *
+     * `null` is a sentinel meaning "anchor is out of range for the
+     * current bars" — the caller drops a point-free entry.
+     */
+    function recomputeAnchor(state: AnchorState): void {
+        const def = state.definition
+        // Out-of-range anchor: leave the running sums at zero and emit an
+        // empty series. We deliberately do NOT throw — callers might be
+        // mid-stream and an out-of-range anchor is a valid transient
+        // state (e.g. user dragged the anchor past the loaded window).
+        if (
+            bars.length === 0 ||
+            def.barIndex < 0 ||
+            def.barIndex >= bars.length
+        ) {
+            state.sumVwp = 0
+            state.sumVol = 0
+            state.sumSqDev = 0
+            state.series = []
+            return
+        }
+
+        // Use the shared pure function so behaviour stays identical.
+        const series = computeAnchoredVwap(
+            bars,
+            def.barIndex,
+            def.includeBands,
+        )
+        // Reconstruct the running sums by replaying the same arithmetic
+        // — we need them for the next `appendBar`. This is the only
+        // place where the controller duplicates the math; the cost is
+        // unavoidable because `computeAnchoredVwap` does not expose its
+        // internal sums.
+        let sumVwp = 0
+        let sumVol = 0
+        let sumSqDev = 0
+        for (let i = def.barIndex; i < bars.length; i++) {
+            const bar = bars[i]
+            if (bar === undefined) continue
+            const v = bar.volume
+            if (v > 0) {
+                const tp = (bar.high + bar.low + bar.close) / 3
+                sumVwp += tp * v
+                sumVol += v
+                // Prevailing AVWAP at this bar — same operands as the
+                // pure function, same addition order.
+                if (def.includeBands && sumVol > 0) {
+                    const vwap = sumVwp / sumVol
+                    const diff = tp - vwap
+                    sumSqDev += diff * diff * v
+                }
+            }
+        }
+        state.sumVwp = sumVwp
+        state.sumVol = sumVol
+        state.sumSqDev = sumSqDev
+        state.series = series.slice()
+    }
+
+    /**
+     * Extend an anchor's series by one bar incrementally — O(1) per call.
+     * The new bar's absolute index in `bars` is the caller's
+     * responsibility to compute; we take it as a parameter so
+     * `appendBar` can be straight-line.
+     */
+    function extendAnchorByOne(
+        state: AnchorState,
+        bar: AVWAPBar,
+        absIndex: number,
+    ): void {
+        const def = state.definition
+        // Skip anchors that haven't started yet (anchor is in the future
+        // relative to this new bar).
+        if (absIndex < def.barIndex) return
+        // Skip anchors with no anchor inside the loaded window.
+        if (def.barIndex < 0) return
+
+        const v = bar.volume
+        const tp = (bar.high + bar.low + bar.close) / 3
+
+        if (v > 0) {
+            state.sumVwp += tp * v
+            state.sumVol += v
+        }
+
+        let vwap = Number.NaN
+        if (state.sumVol > 0) {
+            vwap = state.sumVwp / state.sumVol
+        }
+
+        // Bands: prevailing AVWAP at this bar — same arithmetic as
+        // `recomputeAnchor` and `computeAnchoredVwap`.
+        if (
+            def.includeBands &&
+            v > 0 &&
+            state.sumVol > 0 &&
+            Number.isFinite(vwap)
+        ) {
+            const diff = tp - vwap
+            state.sumSqDev += diff * diff * v
+        }
+
+        let upper1 = vwap
+        let lower1 = vwap
+        let upper2 = vwap
+        let lower2 = vwap
+        if (
+            def.includeBands &&
+            state.sumVol > 0 &&
+            Number.isFinite(vwap)
+        ) {
+            const variance = state.sumSqDev / state.sumVol
+            const stdDev = Math.sqrt(variance > 0 ? variance : 0)
+            upper1 = vwap + stdDev
+            lower1 = vwap - stdDev
+            upper2 = vwap + 2 * stdDev
+            lower2 = vwap - 2 * stdDev
+        }
+
+        state.series.push({
+            barIndex: absIndex,
+            vwap,
+            upper1,
+            lower1,
+            upper2,
+            lower2,
+            cumulativeVolume: state.sumVol,
+        })
+    }
+
+    // -------------------------------------------------------------------
+    // Lifecycle — kick off any initial anchors (none today, but reserved).
+    // -------------------------------------------------------------------
+    if (bars.length > 0) {
+        // No anchors yet — publish empty so subscribers see a defined
+        // starting value.
+        publish()
+    }
+
+    // -------------------------------------------------------------------
+    // Public mutators
+    // -------------------------------------------------------------------
+
+    function setBars(nextBars: ReadonlyArray<AVWAPBar>): void {
+        bars = nextBars.slice()
+        for (const state of anchorStates.values()) {
+            recomputeAnchor(state)
+        }
+        publish()
+    }
+
+    function addAnchor(def: AnchorDefinition): string | null {
+        // Replace-in-place on id collision. The brief allows either
+        // semantics; we choose replace because UIs that drag an anchor
+        // onto an existing one expect the existing one to update, not
+        // to throw.
+        const state: AnchorState = {
+            definition: { ...def },
+            sumVwp: 0,
+            sumVol: 0,
+            sumSqDev: 0,
+            series: [],
+        }
+        recomputeAnchor(state)
+        anchorStates.set(def.id, state)
+        publish()
+        return def.id
+    }
+
+    function removeAnchor(id: string): boolean {
+        const existed = anchorStates.delete(id)
+        if (existed) publish()
+        return existed
+    }
+
+    function updateAnchor(
+        id: string,
+        patch: Partial<Omit<AnchorDefinition, 'id'>>,
+    ): boolean {
+        const state = anchorStates.get(id)
+        if (state === undefined) return false
+
+        const prev = state.definition
+        // Merge into a fresh definition object — never mutate the
+        // existing one (immutability convention).
+        const nextDef: AnchorDefinition = {
+            ...prev,
+            ...patch,
+            id: prev.id,
+        }
+        state.definition = nextDef
+
+        // Recompute only when the math-affecting fields change.
+        const mathDirty =
+            (patch.barIndex !== undefined &&
+                patch.barIndex !== prev.barIndex) ||
+            (patch.includeBands !== undefined &&
+                patch.includeBands !== prev.includeBands)
+        if (mathDirty) {
+            recomputeAnchor(state)
+        }
+        publish()
+        return true
+    }
+
+    function appendBar(bar: AVWAPBar): void {
+        const absIndex = bars.length
+        bars.push(bar)
+        for (const state of anchorStates.values()) {
+            extendAnchorByOne(state, bar, absIndex)
+        }
+        publish()
+    }
+
+    // -------------------------------------------------------------------
+    // Dispose — silence mutators (same pattern as the rest of the codebase)
+    // -------------------------------------------------------------------
+    let disposed = false
+    function dispose(): void {
+        if (disposed) return
+        disposed = true
+    }
+
+    function guard<T extends (...args: never[]) => unknown>(
+        fn: T,
+        fallback: ReturnType<T>,
+    ): T {
+        return ((...args: Parameters<T>): ReturnType<T> => {
+            if (disposed) return fallback
+            return fn(...args) as ReturnType<T>
+        }) as T
+    }
+
+    const guardedSetBars = guard(setBars, undefined as void)
+    const guardedAppendBar = guard(appendBar, undefined as void)
+
+    return {
+        anchors,
+        // Canonical verbs (API audit BLOCKER-001 harmonisation): `setData`
+        // for full replacement + `append` for single-item extension. Old
+        // names preserved as aliases for the deprecation window.
+        setData: guardedSetBars,
+        append: guardedAppendBar,
+        setBars: guardedSetBars,
+        addAnchor: guard(addAnchor, null),
+        removeAnchor: guard(removeAnchor, false),
+        updateAnchor: guard(updateAnchor, false),
+        appendBar: guardedAppendBar,
+        dispose,
+    }
+}

package/src/components/anchoredVwap/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Public surface of the Anchored VWAP module.
+ *
+ * Consumers should import from this barrel. The barrel is re-exported from
+ * `packages/core/src/index.ts` so the public package surface stays a single
+ * import line.
+ */
+
+export { computeAnchoredVwap } from './computeAnchoredVwap'
+export { createAnchoredVwapController } from './createAnchoredVwapController'
+export type {
+    ActiveAnchor,
+    AnchorDefinition,
+    AnchoredVwapController,
+    AVWAPBar,
+    AVWAPPoint,
+} from './types'

package/src/components/anchoredVwap/types.ts

@@ -0,0 +1,187 @@
+/**
+ * Anchored VWAP — public type contract.
+ *
+ * Anchored VWAP (AVWAP) is a volume-weighted average price calculation that
+ * starts from a specific, user-chosen anchor bar rather than rolling over a
+ * fixed window. Institutional traders anchor to earnings prints, swing
+ * highs/lows, session opens, or macro events and read the resulting line as
+ * a "fair price" reference from that moment forward. The ±1σ / ±2σ bands
+ * around the AVWAP form a volume-weighted standard-deviation envelope that
+ * is widely used for mean-reversion entries and exits.
+ *
+ * TradingView restricts the **number** of simultaneous AVWAP anchors on
+ * lower tiers; this controller is multi-anchor by design — every anchor
+ * tracks its own cumulative sums so incremental `appendBar` is O(1) per
+ * anchor per bar.
+ *
+ * This module owns the **data model + math only**. Rendering belongs to the
+ * `@klinechart-quant/core` Renderer/Scene layer (or a Vue/React adapter).
+ *
+ * See `docs/ROADMAP.md` §3 for the broader controller layering this fits
+ * into. The dispose-guard pattern follows
+ * `createIndicatorSelectorController.ts`.
+ */
+
+import type { Signal } from '../../reactivity'
+
+/**
+ * Minimum bar shape consumed by `computeAnchoredVwap`. Matches the
+ * cross-renderer KLineData subset used elsewhere in core. We intentionally
+ * do NOT require `open` or `timestamp` so callers can stream from any
+ * source.
+ */
+export interface AVWAPBar {
+    high: number
+    low: number
+    close: number
+    volume: number
+}
+
+/**
+ * A single point of an Anchored VWAP series — one entry per bar from the
+ * anchor index (inclusive) through the end of the input.
+ *
+ * `barIndex` is the absolute bar index in the original input array (NOT a
+ * series-relative offset). Renderers map it directly onto their X-axis.
+ *
+ * When bands are disabled (`includeBands: false`) the four band fields are
+ * set equal to `vwap` so consumers do not need a `null` check.
+ *
+ * When a bar contributes no volume and there is no prior AVWAP (i.e. the
+ * anchor bar itself has `volume === 0`), every numeric field of the
+ * resulting point is `NaN`. See `computeAnchoredVwap.ts` for the
+ * carry-forward rules.
+ */
+export interface AVWAPPoint {
+    /** Absolute bar index in the input series. */
+    barIndex: number
+    /** Volume-weighted average price from anchor up to this bar. */
+    vwap: number
+    /** vwap + 1σ. Equals vwap when bands are disabled. */
+    upper1: number
+    /** vwap − 1σ. Equals vwap when bands are disabled. */
+    lower1: number
+    /** vwap + 2σ. Equals vwap when bands are disabled. */
+    upper2: number
+    /** vwap − 2σ. Equals vwap when bands are disabled. */
+    lower2: number
+    /** Running sum of volume from the anchor to this bar. Useful for
+     *  diagnostics, exhaustion checks, and adapter overlays. */
+    cumulativeVolume: number
+}
+
+/**
+ * Definition of an anchor instance. Multiple anchors can be active at the
+ * same time (e.g. one per session, one per earnings, one per swing low).
+ *
+ * `id` must be unique within the controller; the controller treats a
+ * collision on `addAnchor` as a replace-in-place to keep the API
+ * idempotent.
+ */
+export interface AnchorDefinition {
+    /** Stable id. Caller-supplied; treat as opaque. */
+    id: string
+    /** Human-readable label (e.g. "Earnings Beat 2024-Q1"). */
+    label: string
+    /** Anchor position as an index into the controller's bar series. */
+    barIndex: number
+    /** Optional colour hint for the adapter — not used by the math. */
+    color?: string
+    /** Whether to compute the ±1σ / ±2σ bands for this anchor. */
+    includeBands: boolean
+}
+
+/**
+ * An anchor together with its computed AVWAP series. The series is a
+ * snapshot — calling `setBars`, `appendBar`, or `updateAnchor` produces a
+ * fresh array (immutability convention).
+ */
+export interface ActiveAnchor {
+    definition: AnchorDefinition
+    series: ReadonlyArray<AVWAPPoint>
+}
+
+/**
+ * Framework-agnostic controller — mirrors the shape of
+ * `VolumeProfileController` and `IndicatorSelectorController` (signals for
+ * state, plain functions for mutations, idempotent `dispose`).
+ *
+ * Why this design:
+ *  - Multi-anchor: every anchor tracks its own running sums so
+ *    `appendBar` is O(anchors) per tick, not O(anchors × bars).
+ *  - Signal-based: any adapter (React `useSyncExternalStore`, Vue effect,
+ *    Angular `toSignal`) can bridge without coupling to a framework.
+ *  - Dispose-guard: mutators become silent no-ops after `dispose`, so a
+ *    component that unmounts mid-stream cannot leak updates into a stale
+ *    listener.
+ */
+export interface AnchoredVwapController {
+    /** All currently active anchors with their up-to-date series. */
+    readonly anchors: Signal<ReadonlyArray<ActiveAnchor>>
+
+    /**
+     * Replace the underlying bar series and recompute every active anchor
+     * from scratch — canonical method, aligned with the cross-controller
+     * `setData()` convention (MtfController). Closes API audit BLOCKER-001
+     * (5-verb intake proliferation).
+     */
+    setData(bars: ReadonlyArray<AVWAPBar>): void
+
+    /**
+     * @deprecated since 0.1.0-alpha.1 — use {@link AnchoredVwapController.setData}.
+     * Preserved as a non-removing alias for at least 6 months.
+     */
+    setBars(bars: ReadonlyArray<AVWAPBar>): void
+
+    /**
+     * Add an anchor and compute its series immediately. Returns the
+     * anchor's id (the same one passed in `def.id`). If an anchor with the
+     * same id already exists it is **replaced** — that keeps the API
+     * idempotent and matches what UIs expect when the user drags an anchor
+     * onto an existing one.
+     *
+     * Returns `null` after dispose.
+     */
+    addAnchor(def: AnchorDefinition): string | null
+
+    /**
+     * Remove an anchor by id. Returns `true` when an anchor was actually
+     * removed, `false` when the id was unknown (or after dispose).
+     */
+    removeAnchor(id: string): boolean
+
+    /**
+     * Patch an anchor in place. Any of `label`, `barIndex`, `color`, and
+     * `includeBands` may change; the series is recomputed whenever
+     * `barIndex` or `includeBands` changes (a pure label change is a
+     * lightweight metadata swap).
+     *
+     * Returns `false` when the id is unknown (or after dispose).
+     */
+    updateAnchor(
+        id: string,
+        patch: Partial<Omit<AnchorDefinition, 'id'>>,
+    ): boolean
+
+    /**
+     * Append a single new bar — canonical method, aligned with the
+     * cross-controller `append()` convention (MtfController). Each anchor's
+     * series is extended **incrementally** by one point — the running
+     * cumulative sums make this O(1) per anchor per call. A full
+     * `computeAnchoredVwap` after N appends produces the same result; see
+     * the controller test that pins this equivalence.
+     */
+    append(bar: AVWAPBar): void
+
+    /**
+     * @deprecated since 0.1.0-alpha.1 — use {@link AnchoredVwapController.append}.
+     * Preserved as a non-removing alias for at least 6 months.
+     */
+    appendBar(bar: AVWAPBar): void
+
+    /**
+     * Stop emitting. Subsequent mutator calls are silent no-ops; previously
+     * attached subscribers receive no further notifications. Idempotent.
+     */
+    dispose(): void
+}