@363045841yyt/klinechart-core 0.8.14 → 0.9.0-alpha.0

package/src/alerts/createAlertController.ts

@@ -1,294 +0,0 @@
-/**
- * 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]
-    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()]
-    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()]
-      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/types.ts

@@ -1,177 +0,0 @@
-/**
- * Alert rule engine — public types.
- *
- * Why we build our own (vs. relying on TradingView's alert engine):
- *   - TV alerts are closed, server-side, capped (60 free + paid tiers).
- *   - TV alerts are limited to TV's built-in indicator outputs.
- *   - We need to alert on differentiating signals TV simply cannot see —
- *     Volume Profile POC touch, Order Book wall appearance, Footprint
- *     imbalance hit. These predicates are first-class here.
- *
- * Engine shape:
- *   - Predicate-based (discriminated union, schema-driven).
- *   - Rules are pure data and serialisable (see `ruleSchema.ts`) so they
- *     survive page reloads and can be shared between users/agents/servers.
- *   - The controller is a tiny state machine over rules + recent events;
- *     evaluation is O(rules) per call, O(1) per rule, safe to run in a
- *     per-frame loop.
- *
- * The `custom` predicate is an escape hatch for callers that need ad-hoc
- * logic without forking the schema. It carries an in-memory function that
- * is intentionally NOT serialisable — see `ruleSchema.ts` for the reasoning.
- */
-
-import type { Signal } from '../reactivity/signal'
-
-// ---------------------------------------------------------------------------
-// MarketSnapshot — the read-only input fed into every predicate.
-// ---------------------------------------------------------------------------
-
-/**
- * A snapshot of "the chart right now" that all predicates evaluate against.
- *
- * Callers are expected to populate as much as they have. A predicate that
- * needs a sub-field absent from the snapshot must return `false` (no spurious
- * fires from missing data).
- */
-export interface MarketSnapshot {
-  /** Latest closed bar; `null` for an empty stream. */
-  bar: {
-    timestamp: number
-    open: number
-    high: number
-    low: number
-    close: number
-    volume: number
-  } | null
-  /** Latest scalar value per indicator id (keyed by your indicator instance id). */
-  indicators: Readonly<Record<string, number>>
-  /**
-   * Average volume across the last N bars, keyed by N. Required for the
-   * `volume-spike` predicate to be O(1) — the caller maintains the rolling
-   * mean elsewhere.
-   */
-  rollingVolume: Readonly<Record<number, number>>
-  /** Optional advanced components (filled only when those components are mounted). */
-  volumeProfile?: { poc: number; vah: number; val: number }
-  orderBook?: {
-    medianBidSize: number
-    medianAskSize: number
-    maxBidSize: number
-    maxAskSize: number
-  }
-  footprint?: {
-    latestBarMaxImbalanceRatio: number
-    latestBarImbalanceCount: number
-  }
-}
-
-// ---------------------------------------------------------------------------
-// AlertPredicate — discriminated union of supported predicate kinds.
-// ---------------------------------------------------------------------------
-
-export type CrossDirection = 'up' | 'down' | 'any'
-export type IndicatorCrossPairDirection = 'a-above-b' | 'a-below-b' | 'any'
-
-/**
- * Predicate kinds. Add new kinds by extending the union — the controller's
- * switch in `predicates.ts` will give a TS exhaustiveness error if you forget
- * to handle it.
- */
-export type AlertPredicate =
-  | { kind: 'price-cross'; price: number; direction: CrossDirection }
-  | { kind: 'price-in-range'; min: number; max: number }
-  | { kind: 'price-out-of-range'; min: number; max: number }
-  | {
-      kind: 'indicator-cross'
-      indicatorId: string
-      threshold: number
-      direction: CrossDirection
-    }
-  | {
-      kind: 'indicator-cross-indicator'
-      aId: string
-      bId: string
-      direction: IndicatorCrossPairDirection
-    }
-  | { kind: 'volume-spike'; multipleOfAvg: number; lookbackBars: number }
-  | { kind: 'volume-profile-poc-touch'; bandPercent: number }
-  | { kind: 'order-book-wall'; sizeMultipleOfMedian: number }
-  | {
-      kind: 'footprint-imbalance'
-      minImbalanceRatio: number
-      consecutivePriceLevels: number
-    }
-  /**
-   * Escape hatch. The `evaluate` function runs INSIDE a try/catch in the
-   * controller — a throwing custom predicate must not crash the alert pass.
-   * Custom predicates CANNOT be serialised; see `ruleSchema.ts`.
-   */
-  | { kind: 'custom'; evaluate: (snapshot: MarketSnapshot) => boolean }
-
-export type AlertPredicateKind = AlertPredicate['kind']
-
-// ---------------------------------------------------------------------------
-// AlertRule + AlertEvent
-// ---------------------------------------------------------------------------
-
-export interface AlertRule {
-  id: string
-  name: string
-  predicate: AlertPredicate
-  enabled: boolean
-  /** Fire once and then auto-disable. */
-  oneShot: boolean
-  /**
-   * For non-oneShot rules, suppress re-fires within this window (ms after
-   * the last fire). Undefined / 0 = no cooldown.
-   */
-  cooldownMs?: number
-  /** Free-form metadata propagated onto fired events. */
-  metadata?: Readonly<Record<string, unknown>>
-}
-
-export interface AlertEvent {
-  ruleId: string
-  ruleName: string
-  /** ms since epoch, passed in by the caller as `now`. */
-  triggeredAt: number
-  /** Snapshot of the bar that triggered the rule (copied, not referenced). */
-  snapshotBar: MarketSnapshot['bar']
-  metadata?: Readonly<Record<string, unknown>>
-}
-
-// ---------------------------------------------------------------------------
-// AlertController — the public, framework-agnostic facade.
-// ---------------------------------------------------------------------------
-
-export interface AlertController {
-  /** Current rules, in insertion order. Reactive. */
-  readonly rules: Signal<ReadonlyArray<AlertRule>>
-  /** Bounded ring of recent events, newest last. Reactive. */
-  readonly events: Signal<ReadonlyArray<AlertEvent>>
-
-  /** Add a rule; returns false if a rule with the same id already exists. */
-  addRule(rule: AlertRule): boolean
-  removeRule(id: string): boolean
-  setRuleEnabled(id: string, enabled: boolean): boolean
-  /** Patch any field except `id`. Returns false if the id is unknown. */
-  updateRule(id: string, patch: Partial<Omit<AlertRule, 'id'>>): boolean
-
-  /**
-   * Evaluate every enabled rule against the snapshot. Returns the events
-   * fired on this call (also appended to the `events` signal).
-   */
-  evaluate(snapshot: MarketSnapshot, now: number): ReadonlyArray<AlertEvent>
-
-  clearEvents(): void
-  /** Per-fire listener; returns an unsubscribe. */
-  onEvent(listener: (event: AlertEvent) => void): () => void
-
-  dispose(): void
-}
-
-export interface AlertControllerOptions {
-  /** Maximum size of the `events` ring buffer. Default 100. */
-  maxEvents?: number
-}