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

package/src/alerts/createAlertController.ts

@@ -0,0 +1,312 @@
+/**
+ * AlertController — framework-agnostic, signal-based.
+ *
+ * Same dispose-guard pattern as the other core controllers (volume-profile,
+ * indicator-selector). Adapters (React/Vue/Angular) subscribe to the
+ * `rules` and `events` signals via their native reactivity.
+ *
+ * Per-rule prev-snapshot:
+ *   Cross-style predicates compare prev vs. curr. Rather than asking the
+ *   caller to thread that state, the controller stashes the previous
+ *   evaluation snapshot per rule id and feeds it back into the predicate.
+ *   When a rule is added or re-enabled, its prev is reset — that prevents
+ *   a spurious fire on first evaluation (a newly-added "price-cross 100"
+ *   rule should NOT fire just because the current close happens to be 105).
+ *
+ * Cooldown:
+ *   For non-oneShot rules we record `lastFiredAt` and suppress re-fires
+ *   within `cooldownMs`. oneShot ignores cooldown — it just flips
+ *   `enabled` to false on first fire.
+ *
+ * Crash safety:
+ *   `kind: 'custom'` predicates run inside try/catch. A throwing predicate
+ *   is caught, marked internally, and skipped for this pass; the rest of
+ *   the rules continue to evaluate. Errors are swallowed at the boundary
+ *   (no console.* per coding-style.md) — observability hooks are a future
+ *   addition (`onError` listener on the controller).
+ */
+
+import { createSignal, type Signal } from '../reactivity/signal'
+import { evaluatePredicate } from './predicates'
+import type {
+    AlertController,
+    AlertControllerOptions,
+    AlertEvent,
+    AlertRule,
+    MarketSnapshot,
+} from './types'
+
+const DEFAULT_MAX_EVENTS = 100
+
+interface RuleRuntimeState {
+    /** Snapshot from the previous evaluation, for cross-style predicates. */
+    prev: MarketSnapshot | null
+    /** ms timestamp of last fire (for cooldown). undefined = never fired. */
+    lastFiredAt: number | undefined
+}
+
+export function createAlertController(
+    opts?: AlertControllerOptions,
+): AlertController {
+    const maxEvents = (() => {
+        const raw = opts?.maxEvents
+        if (raw === undefined) return DEFAULT_MAX_EVENTS
+        if (!Number.isFinite(raw) || raw < 1) return DEFAULT_MAX_EVENTS
+        return Math.floor(raw)
+    })()
+
+    // -----------------------------------------------------------------------
+    // Signals — frozen arrays so React/Vue see new identity on every change.
+    // -----------------------------------------------------------------------
+    const rules: Signal<ReadonlyArray<AlertRule>> = createSignal<
+        ReadonlyArray<AlertRule>
+    >([])
+    const events: Signal<ReadonlyArray<AlertEvent>> = createSignal<
+        ReadonlyArray<AlertEvent>
+    >([])
+
+    // -----------------------------------------------------------------------
+    // Private state
+    // -----------------------------------------------------------------------
+    const runtime = new Map<string, RuleRuntimeState>()
+    const listeners = new Set<(event: AlertEvent) => void>()
+
+    let disposed = false
+
+    function findIndex(id: string): number {
+        const arr = rules.peek()
+        for (let i = 0; i < arr.length; i++) {
+            if (arr[i]!.id === id) return i
+        }
+        return -1
+    }
+
+    function replaceAt(arr: ReadonlyArray<AlertRule>, i: number, next: AlertRule): ReadonlyArray<AlertRule> {
+        const copy = arr.slice()
+        copy[i] = next
+        return copy
+    }
+
+    // -----------------------------------------------------------------------
+    // addRule / removeRule / setRuleEnabled / updateRule
+    // -----------------------------------------------------------------------
+
+    function addRule(rule: AlertRule): boolean {
+        if (findIndex(rule.id) >= 0) return false
+        // Defensive shallow copy so external mutation of the caller's object
+        // does not affect controller state.
+        const stored: AlertRule = {
+            ...rule,
+            metadata:
+                rule.metadata !== undefined ? { ...rule.metadata } : undefined,
+        }
+        rules.set([...rules.peek(), stored])
+        runtime.set(rule.id, { prev: null, lastFiredAt: undefined })
+        return true
+    }
+
+    function removeRule(id: string): boolean {
+        const idx = findIndex(id)
+        if (idx < 0) return false
+        const copy = rules.peek().slice()
+        copy.splice(idx, 1)
+        rules.set(copy)
+        runtime.delete(id)
+        return true
+    }
+
+    function setRuleEnabled(id: string, enabled: boolean): boolean {
+        const idx = findIndex(id)
+        if (idx < 0) return false
+        const cur = rules.peek()[idx]!
+        if (cur.enabled === enabled) return true // no-op but reports success
+        const next: AlertRule = { ...cur, enabled }
+        rules.set(replaceAt(rules.peek(), idx, next))
+        // Re-enabling resets prev — a freshly enabled cross rule should not
+        // fire on the first eval just because the level is already broken.
+        if (enabled) {
+            runtime.set(id, { prev: null, lastFiredAt: undefined })
+        }
+        return true
+    }
+
+    function updateRule(
+        id: string,
+        patch: Partial<Omit<AlertRule, 'id'>>,
+    ): boolean {
+        const idx = findIndex(id)
+        if (idx < 0) return false
+        const cur = rules.peek()[idx]!
+        const next: AlertRule = {
+            ...cur,
+            ...patch,
+            id: cur.id, // id is invariant
+            metadata:
+                patch.metadata !== undefined
+                    ? { ...patch.metadata }
+                    : cur.metadata,
+        }
+        rules.set(replaceAt(rules.peek(), idx, next))
+        // Changing the predicate invalidates prev — different predicates may
+        // need different prev fields, and a stale prev could cause a spurious
+        // fire on next eval.
+        if (patch.predicate !== undefined) {
+            runtime.set(id, { prev: null, lastFiredAt: undefined })
+        }
+        return true
+    }
+
+    // -----------------------------------------------------------------------
+    // evaluate — the hot path. Safe to call every frame.
+    // -----------------------------------------------------------------------
+
+    function evaluate(
+        snapshot: MarketSnapshot,
+        now: number,
+    ): ReadonlyArray<AlertEvent> {
+        const fired: AlertEvent[] = []
+        const currentRules = rules.peek()
+
+        // We may need to flip oneShot rules off — collect indices and apply
+        // once at the end to avoid mutating `currentRules` mid-loop.
+        const toDisable: number[] = []
+
+        for (let i = 0; i < currentRules.length; i++) {
+            const rule = currentRules[i]!
+            if (!rule.enabled) continue
+
+            const rt = runtime.get(rule.id) ?? {
+                prev: null,
+                lastFiredAt: undefined,
+            }
+            // Cooldown gate (applies to non-oneShot rules; oneShot rules
+            // can only fire once anyway).
+            if (
+                !rule.oneShot &&
+                rule.cooldownMs !== undefined &&
+                rule.cooldownMs > 0 &&
+                rt.lastFiredAt !== undefined &&
+                now - rt.lastFiredAt < rule.cooldownMs
+            ) {
+                // Still update prev so the next eval after cooldown has the
+                // right reference point for cross detection.
+                rt.prev = snapshot
+                runtime.set(rule.id, rt)
+                continue
+            }
+
+            // Evaluate. Custom predicates can throw — wrap.
+            let hit = false
+            try {
+                hit = evaluatePredicate(rule.predicate, snapshot, rt.prev)
+            } catch {
+                // Swallow per crash-safety contract. Do NOT fire. Continue.
+                hit = false
+            }
+
+            if (hit) {
+                const event: AlertEvent = {
+                    ruleId: rule.id,
+                    ruleName: rule.name,
+                    triggeredAt: now,
+                    snapshotBar:
+                        snapshot.bar !== null ? { ...snapshot.bar } : null,
+                    metadata: rule.metadata,
+                }
+                fired.push(event)
+                rt.lastFiredAt = now
+                if (rule.oneShot) {
+                    toDisable.push(i)
+                }
+            }
+
+            rt.prev = snapshot
+            runtime.set(rule.id, rt)
+        }
+
+        if (fired.length > 0) {
+            // Append fired events to the ring, capped at maxEvents.
+            const prevEvents = events.peek()
+            const merged = prevEvents.concat(fired)
+            const trimmed =
+                merged.length > maxEvents
+                    ? merged.slice(merged.length - maxEvents)
+                    : merged
+            events.set(trimmed)
+
+            // Notify per-event listeners. Copy first so a listener that
+            // unsubscribes during fire-out doesn't mutate the iteration.
+            const snapshotListeners = [...listeners]
+            for (const ev of fired) {
+                for (const l of snapshotListeners) {
+                    try {
+                        l(ev)
+                    } catch {
+                        // listener errors are isolated — never leak across.
+                    }
+                }
+            }
+        }
+
+        if (toDisable.length > 0) {
+            const copy = rules.peek().slice()
+            for (const i of toDisable) {
+                const r = copy[i]
+                if (r !== undefined) copy[i] = { ...r, enabled: false }
+            }
+            rules.set(copy)
+        }
+
+        return fired
+    }
+
+    // -----------------------------------------------------------------------
+    // events / listener management
+    // -----------------------------------------------------------------------
+
+    function clearEvents(): void {
+        if (events.peek().length === 0) return
+        events.set([])
+    }
+
+    function onEvent(listener: (event: AlertEvent) => void): () => void {
+        listeners.add(listener)
+        return () => {
+            listeners.delete(listener)
+        }
+    }
+
+    // -----------------------------------------------------------------------
+    // dispose
+    // -----------------------------------------------------------------------
+
+    function dispose(): void {
+        if (disposed) return
+        disposed = true
+        listeners.clear()
+        runtime.clear()
+    }
+
+    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
+    }
+
+    return {
+        rules,
+        events,
+        addRule: guard(addRule, false as boolean) as AlertController['addRule'],
+        removeRule: guard(removeRule, false as boolean) as AlertController['removeRule'],
+        setRuleEnabled: guard(setRuleEnabled, false as boolean) as AlertController['setRuleEnabled'],
+        updateRule: guard(updateRule, false as boolean) as AlertController['updateRule'],
+        evaluate: guard(evaluate, [] as ReadonlyArray<AlertEvent>) as AlertController['evaluate'],
+        clearEvents: guard(clearEvents, undefined as void) as AlertController['clearEvents'],
+        onEvent: guard(onEvent, (() => undefined) as () => void) as AlertController['onEvent'],
+        dispose,
+    }
+}

package/src/alerts/index.ts

@@ -0,0 +1,18 @@
+export type {
+    AlertController,
+    AlertControllerOptions,
+    AlertEvent,
+    AlertPredicate,
+    AlertPredicateKind,
+    AlertRule,
+    CrossDirection,
+    IndicatorCrossPairDirection,
+    MarketSnapshot,
+} from './types'
+export { createAlertController } from './createAlertController'
+export { evaluatePredicate } from './predicates'
+export {
+    AlertRuleSchemaError,
+    deserializeRule,
+    serializeRule,
+} from './ruleSchema'

package/src/alerts/predicates.ts

@@ -0,0 +1,231 @@
+/**
+ * Built-in predicate kit.
+ *
+ * Each predicate is a pure function over `(predicate, curr, prev)`:
+ *   - `curr` is the snapshot at the current evaluation.
+ *   - `prev` is the snapshot from the previous evaluation of the SAME rule
+ *     (the controller threads it through). For cross-style predicates the
+ *     prev value is what makes "just-crossed" detectable vs. "is above".
+ *   - When `prev` is null (first evaluation), cross predicates must NOT fire —
+ *     we cannot distinguish "already above" from "just crossed up" without a
+ *     reference point.
+ *
+ * All predicates are O(1) — no scanning of history. The caller pre-computes
+ * any rolling state (e.g. `rollingVolume[N]`).
+ *
+ * Defensive: predicates return `false` for any required field that is null,
+ * undefined, or non-finite. We never throw — a bad snapshot must not crash
+ * an entire alert pass.
+ */
+
+import type {
+    AlertPredicate,
+    CrossDirection,
+    IndicatorCrossPairDirection,
+    MarketSnapshot,
+} from './types'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function isFiniteNumber(x: unknown): x is number {
+    return typeof x === 'number' && Number.isFinite(x)
+}
+
+/**
+ * Generic numeric cross check.
+ *   - up   : prev < threshold && curr >= threshold
+ *   - down : prev > threshold && curr <= threshold
+ *   - any  : either
+ *
+ * Returns false if either side is non-finite. The `>=` / `<=` on the curr side
+ * is intentional — a value landing exactly on the threshold counts as a cross
+ * the instant it arrives (matches trader intuition: "alert me when price hits
+ * 100" should fire at 100, not require 100.01).
+ */
+function crossed(
+    prevValue: number | null,
+    currValue: number,
+    threshold: number,
+    direction: CrossDirection,
+): boolean {
+    if (prevValue === null || !isFiniteNumber(prevValue)) return false
+    if (!isFiniteNumber(currValue) || !isFiniteNumber(threshold)) return false
+    const up = prevValue < threshold && currValue >= threshold
+    const down = prevValue > threshold && currValue <= threshold
+    if (direction === 'up') return up
+    if (direction === 'down') return down
+    return up || down
+}
+
+/**
+ * Cross of two series A vs B (indicator vs indicator). Direction:
+ *   - a-above-b : A was <= B and is now > B (A crossed UP through B)
+ *   - a-below-b : A was >= B and is now < B (A crossed DOWN through B)
+ *   - any       : either
+ *
+ * Note the asymmetric strictness vs. `crossed`: here we use strict inequality
+ * on the post side because equality of two floats is rare and ambiguous — we
+ * wait for the next tick of separation.
+ */
+function crossedPair(
+    prevA: number | null,
+    prevB: number | null,
+    currA: number,
+    currB: number,
+    direction: IndicatorCrossPairDirection,
+): boolean {
+    if (prevA === null || prevB === null) return false
+    if (!isFiniteNumber(prevA) || !isFiniteNumber(prevB)) return false
+    if (!isFiniteNumber(currA) || !isFiniteNumber(currB)) return false
+    const aAboveB = prevA <= prevB && currA > currB
+    const aBelowB = prevA >= prevB && currA < currB
+    if (direction === 'a-above-b') return aAboveB
+    if (direction === 'a-below-b') return aBelowB
+    return aAboveB || aBelowB
+}
+
+// ---------------------------------------------------------------------------
+// evaluatePredicate — the dispatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` iff the predicate fires for this (prev, curr) pair.
+ *
+ * The controller wraps `kind: 'custom'` in its own try/catch — but we still
+ * defensively guard against the function being missing here.
+ */
+export function evaluatePredicate(
+    predicate: AlertPredicate,
+    curr: MarketSnapshot,
+    prev: MarketSnapshot | null,
+): boolean {
+    switch (predicate.kind) {
+        case 'price-cross': {
+            const cBar = curr.bar
+            const pBar = prev?.bar ?? null
+            if (cBar === null || !isFiniteNumber(cBar.close)) return false
+            const prevClose =
+                pBar !== null && isFiniteNumber(pBar.close) ? pBar.close : null
+            return crossed(prevClose, cBar.close, predicate.price, predicate.direction)
+        }
+
+        case 'price-in-range': {
+            const cBar = curr.bar
+            if (cBar === null || !isFiniteNumber(cBar.close)) return false
+            const { min, max } = predicate
+            if (!isFiniteNumber(min) || !isFiniteNumber(max)) return false
+            return cBar.close >= min && cBar.close <= max
+        }
+
+        case 'price-out-of-range': {
+            const cBar = curr.bar
+            if (cBar === null || !isFiniteNumber(cBar.close)) return false
+            const { min, max } = predicate
+            if (!isFiniteNumber(min) || !isFiniteNumber(max)) return false
+            return cBar.close < min || cBar.close > max
+        }
+
+        case 'indicator-cross': {
+            const id = predicate.indicatorId
+            const cVal = curr.indicators[id]
+            if (cVal === undefined || !isFiniteNumber(cVal)) return false
+            const pRaw = prev?.indicators[id]
+            const pVal = pRaw !== undefined && isFiniteNumber(pRaw) ? pRaw : null
+            return crossed(pVal, cVal, predicate.threshold, predicate.direction)
+        }
+
+        case 'indicator-cross-indicator': {
+            const { aId, bId, direction } = predicate
+            const cA = curr.indicators[aId]
+            const cB = curr.indicators[bId]
+            if (
+                cA === undefined ||
+                cB === undefined ||
+                !isFiniteNumber(cA) ||
+                !isFiniteNumber(cB)
+            ) {
+                return false
+            }
+            const pARaw = prev?.indicators[aId]
+            const pBRaw = prev?.indicators[bId]
+            const pA = pARaw !== undefined && isFiniteNumber(pARaw) ? pARaw : null
+            const pB = pBRaw !== undefined && isFiniteNumber(pBRaw) ? pBRaw : null
+            return crossedPair(pA, pB, cA, cB, direction)
+        }
+
+        case 'volume-spike': {
+            const cBar = curr.bar
+            if (cBar === null || !isFiniteNumber(cBar.volume)) return false
+            const avg = curr.rollingVolume[predicate.lookbackBars]
+            // Missing avg or zero avg → no useful baseline; do not fire.
+            if (avg === undefined || !isFiniteNumber(avg) || avg <= 0) return false
+            if (!isFiniteNumber(predicate.multipleOfAvg)) return false
+            return cBar.volume >= avg * predicate.multipleOfAvg
+        }
+
+        case 'volume-profile-poc-touch': {
+            const cBar = curr.bar
+            const vp = curr.volumeProfile
+            if (cBar === null || !isFiniteNumber(cBar.close)) return false
+            if (vp === undefined || !isFiniteNumber(vp.poc) || vp.poc === 0) return false
+            if (!isFiniteNumber(predicate.bandPercent)) return false
+            const distance = Math.abs(cBar.close - vp.poc) / Math.abs(vp.poc)
+            return distance <= predicate.bandPercent
+        }
+
+        case 'order-book-wall': {
+            const ob = curr.orderBook
+            if (ob === undefined) return false
+            const { sizeMultipleOfMedian: k } = predicate
+            if (!isFiniteNumber(k)) return false
+            const bidHit =
+                isFiniteNumber(ob.medianBidSize) &&
+                isFiniteNumber(ob.maxBidSize) &&
+                ob.medianBidSize > 0 &&
+                ob.maxBidSize >= ob.medianBidSize * k
+            const askHit =
+                isFiniteNumber(ob.medianAskSize) &&
+                isFiniteNumber(ob.maxAskSize) &&
+                ob.medianAskSize > 0 &&
+                ob.maxAskSize >= ob.medianAskSize * k
+            return bidHit || askHit
+        }
+
+        case 'footprint-imbalance': {
+            const fp = curr.footprint
+            if (fp === undefined) return false
+            if (
+                !isFiniteNumber(fp.latestBarMaxImbalanceRatio) ||
+                !isFiniteNumber(fp.latestBarImbalanceCount)
+            ) {
+                return false
+            }
+            return (
+                fp.latestBarMaxImbalanceRatio >= predicate.minImbalanceRatio &&
+                fp.latestBarImbalanceCount >= predicate.consecutivePriceLevels
+            )
+        }
+
+        case 'custom': {
+            if (typeof predicate.evaluate !== 'function') return false
+            // The controller also wraps this call in try/catch; the inner
+            // guard here protects callers that invoke predicates directly
+            // (e.g. tests or third-party tooling).
+            try {
+                return predicate.evaluate(curr) === true
+            } catch {
+                return false
+            }
+        }
+
+        default: {
+            // Exhaustiveness check — adding a new kind without a case here
+            // will surface as a TS error on this line.
+            const _exhaustive: never = predicate
+            void _exhaustive
+            return false
+        }
+    }
+}

package/src/alerts/rollingVolume.ts

@@ -0,0 +1,51 @@
+import type { MarketSnapshot } from './types'
+
+export class RollingVolumeCalculator {
+  private buffer: number[]
+  private sum = 0
+  private cursor = 0
+  private filled = false
+
+  constructor(public readonly size: number) {
+    this.buffer = new Array(size)
+  }
+
+  push(volume: number): number {
+    if (this.filled) {
+      this.sum -= this.buffer[this.cursor]!
+    }
+    this.buffer[this.cursor] = volume
+    this.sum += volume
+    this.cursor = (this.cursor + 1) % this.size
+    if (!this.filled && this.cursor === 0) {
+      this.filled = true
+    }
+    return this.mean
+  }
+
+  get mean(): number {
+    const count = this.filled ? this.size : this.cursor
+    return count > 0 ? this.sum / count : 0
+  }
+}
+
+export type VolumeLookbacks = Map<number, RollingVolumeCalculator>
+
+export function createVolumeLookbacks(sizes: number[]): VolumeLookbacks {
+  const map = new Map<number, RollingVolumeCalculator>()
+  for (const size of sizes) {
+    map.set(size, new RollingVolumeCalculator(size))
+  }
+  return map
+}
+
+export function pushToVolumeLookbacks(
+  lookbacks: VolumeLookbacks,
+  volume: number,
+): MarketSnapshot['rollingVolume'] {
+  const result: Record<number, number> = {}
+  for (const [size, calc] of lookbacks) {
+    result[size] = calc.push(volume)
+  }
+  return result
+}