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

package/src/alerts/ruleSchema.ts

@@ -0,0 +1,278 @@
+/**
+ * Serialisable alert rule schema.
+ *
+ * Why a schema separate from `AlertRule`:
+ *   - `AlertRule` can contain `kind: 'custom'`, whose `evaluate` is an
+ *     in-memory function. Functions cannot be JSON-encoded, and we
+ *     deliberately refuse to do anything clever (e.g. `Function(string)`)
+ *     to bring them back — that would let a malicious shared rule execute
+ *     arbitrary code on a victim's browser the moment they imported it.
+ *   - All other predicate kinds are plain data and round-trip cleanly.
+ *
+ * SECURITY:
+ *   `deserializeRule` is strictly data-driven. It NEVER calls `eval`,
+ *   `Function(...)`, dynamic `import`, or `vm` — even if a malicious payload
+ *   claims `kind: 'custom'` with a `source` string, we throw. The output is
+ *   always a structurally-validated `AlertRule` whose predicate is one of
+ *   the known data-only kinds.
+ *
+ * The schema is *minimal* on purpose — we do field-by-field validation
+ * inline rather than pulling Zod into the core bundle. Core has a strict
+ * size budget (30 KB gzip per package.json size-limit) and these rules are
+ * small.
+ */
+
+import type {
+    AlertPredicate,
+    AlertPredicateKind,
+    AlertRule,
+    CrossDirection,
+    IndicatorCrossPairDirection,
+} from './types'
+
+// ---------------------------------------------------------------------------
+// Error type — callers can catch and report cleanly.
+// ---------------------------------------------------------------------------
+
+export class AlertRuleSchemaError extends Error {
+    constructor(message: string) {
+        super(message)
+        this.name = 'AlertRuleSchemaError'
+    }
+}
+
+// ---------------------------------------------------------------------------
+// serializeRule
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialise a rule to a JSON string. Throws `AlertRuleSchemaError` if the
+ * rule contains a `custom` predicate — these are never serialisable, by
+ * security design.
+ */
+export function serializeRule(rule: AlertRule): string {
+    if (rule.predicate.kind === 'custom') {
+        throw new AlertRuleSchemaError(
+            "Cannot serialise rule with 'custom' predicate: custom predicates carry " +
+                'an in-memory function. Serialising them would force deserialise to ' +
+                'evaluate user-supplied code, which is a remote-code-execution vector. ' +
+                'Use a built-in predicate kind for shareable rules.',
+        )
+    }
+    // Everything else is plain data — JSON.stringify handles it directly.
+    // We omit `undefined` fields naturally via JSON.
+    const payload = {
+        id: rule.id,
+        name: rule.name,
+        predicate: rule.predicate,
+        enabled: rule.enabled,
+        oneShot: rule.oneShot,
+        ...(rule.cooldownMs !== undefined ? { cooldownMs: rule.cooldownMs } : {}),
+        ...(rule.metadata !== undefined ? { metadata: rule.metadata } : {}),
+        // Schema version pin — bumps if we make a breaking change.
+        schemaVersion: 1,
+    }
+    return JSON.stringify(payload)
+}
+
+// ---------------------------------------------------------------------------
+// deserializeRule
+// ---------------------------------------------------------------------------
+
+const SERIALISABLE_KINDS: ReadonlySet<AlertPredicateKind> = new Set([
+    'price-cross',
+    'price-in-range',
+    'price-out-of-range',
+    'indicator-cross',
+    'indicator-cross-indicator',
+    'volume-spike',
+    'volume-profile-poc-touch',
+    'order-book-wall',
+    'footprint-imbalance',
+] as const)
+
+const CROSS_DIRECTIONS: ReadonlySet<CrossDirection> = new Set(['up', 'down', 'any'])
+const PAIR_DIRECTIONS: ReadonlySet<IndicatorCrossPairDirection> = new Set([
+    'a-above-b',
+    'a-below-b',
+    'any',
+])
+
+function isObj(x: unknown): x is Record<string, unknown> {
+    return typeof x === 'object' && x !== null && !Array.isArray(x)
+}
+
+function reqString(obj: Record<string, unknown>, key: string): string {
+    const v = obj[key]
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new AlertRuleSchemaError(`Field '${key}' must be a non-empty string`)
+    }
+    return v
+}
+
+function reqBool(obj: Record<string, unknown>, key: string): boolean {
+    const v = obj[key]
+    if (typeof v !== 'boolean') {
+        throw new AlertRuleSchemaError(`Field '${key}' must be a boolean`)
+    }
+    return v
+}
+
+function reqFiniteNumber(obj: Record<string, unknown>, key: string): number {
+    const v = obj[key]
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new AlertRuleSchemaError(`Field '${key}' must be a finite number`)
+    }
+    return v
+}
+
+function optFiniteNumber(
+    obj: Record<string, unknown>,
+    key: string,
+): number | undefined {
+    const v = obj[key]
+    if (v === undefined) return undefined
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new AlertRuleSchemaError(`Field '${key}' must be a finite number when set`)
+    }
+    return v
+}
+
+function reqEnum<T extends string>(
+    obj: Record<string, unknown>,
+    key: string,
+    allowed: ReadonlySet<T>,
+): T {
+    const v = obj[key]
+    if (typeof v !== 'string' || !allowed.has(v as T)) {
+        throw new AlertRuleSchemaError(
+            `Field '${key}' must be one of: ${[...allowed].join(', ')}`,
+        )
+    }
+    return v as T
+}
+
+function parsePredicate(raw: unknown): AlertPredicate {
+    if (!isObj(raw)) throw new AlertRuleSchemaError('predicate must be an object')
+    const kind = raw.kind
+    if (typeof kind !== 'string') {
+        throw new AlertRuleSchemaError("predicate.kind must be a string")
+    }
+    if (kind === 'custom') {
+        throw new AlertRuleSchemaError(
+            "Refusing to deserialise 'custom' predicate. Custom predicates are " +
+                'never serialised — accepting one here would mean evaluating user-' +
+                'supplied code (RCE). Custom predicates must be added in-process by ' +
+                'the application.',
+        )
+    }
+    if (!SERIALISABLE_KINDS.has(kind as AlertPredicateKind)) {
+        throw new AlertRuleSchemaError(`Unknown predicate.kind: ${kind}`)
+    }
+
+    switch (kind as Exclude<AlertPredicateKind, 'custom'>) {
+        case 'price-cross':
+            return {
+                kind: 'price-cross',
+                price: reqFiniteNumber(raw, 'price'),
+                direction: reqEnum(raw, 'direction', CROSS_DIRECTIONS),
+            }
+        case 'price-in-range':
+            return {
+                kind: 'price-in-range',
+                min: reqFiniteNumber(raw, 'min'),
+                max: reqFiniteNumber(raw, 'max'),
+            }
+        case 'price-out-of-range':
+            return {
+                kind: 'price-out-of-range',
+                min: reqFiniteNumber(raw, 'min'),
+                max: reqFiniteNumber(raw, 'max'),
+            }
+        case 'indicator-cross':
+            return {
+                kind: 'indicator-cross',
+                indicatorId: reqString(raw, 'indicatorId'),
+                threshold: reqFiniteNumber(raw, 'threshold'),
+                direction: reqEnum(raw, 'direction', CROSS_DIRECTIONS),
+            }
+        case 'indicator-cross-indicator':
+            return {
+                kind: 'indicator-cross-indicator',
+                aId: reqString(raw, 'aId'),
+                bId: reqString(raw, 'bId'),
+                direction: reqEnum(raw, 'direction', PAIR_DIRECTIONS),
+            }
+        case 'volume-spike':
+            return {
+                kind: 'volume-spike',
+                multipleOfAvg: reqFiniteNumber(raw, 'multipleOfAvg'),
+                lookbackBars: reqFiniteNumber(raw, 'lookbackBars'),
+            }
+        case 'volume-profile-poc-touch':
+            return {
+                kind: 'volume-profile-poc-touch',
+                bandPercent: reqFiniteNumber(raw, 'bandPercent'),
+            }
+        case 'order-book-wall':
+            return {
+                kind: 'order-book-wall',
+                sizeMultipleOfMedian: reqFiniteNumber(raw, 'sizeMultipleOfMedian'),
+            }
+        case 'footprint-imbalance':
+            return {
+                kind: 'footprint-imbalance',
+                minImbalanceRatio: reqFiniteNumber(raw, 'minImbalanceRatio'),
+                consecutivePriceLevels: reqFiniteNumber(raw, 'consecutivePriceLevels'),
+            }
+    }
+}
+
+/**
+ * Parse a JSON string back into an `AlertRule`. Throws `AlertRuleSchemaError`
+ * for malformed JSON, unknown predicate kinds, or any field that fails type
+ * validation.
+ *
+ * Tolerates missing optional fields (`cooldownMs`, `metadata`).
+ */
+export function deserializeRule(json: string): AlertRule {
+    let raw: unknown
+    try {
+        raw = JSON.parse(json)
+    } catch (err) {
+        throw new AlertRuleSchemaError(
+            `Malformed JSON: ${err instanceof Error ? err.message : String(err)}`,
+        )
+    }
+    if (!isObj(raw)) {
+        throw new AlertRuleSchemaError('Top-level payload must be an object')
+    }
+
+    const id = reqString(raw, 'id')
+    const name = reqString(raw, 'name')
+    const enabled = reqBool(raw, 'enabled')
+    const oneShot = reqBool(raw, 'oneShot')
+    const cooldownMs = optFiniteNumber(raw, 'cooldownMs')
+    const predicate = parsePredicate(raw.predicate)
+
+    // Metadata is a free-form object; we only check that it is an object if
+    // present, and we freeze it lazily by spreading the keys we got.
+    let metadata: Readonly<Record<string, unknown>> | undefined
+    if (raw.metadata !== undefined) {
+        if (!isObj(raw.metadata)) {
+            throw new AlertRuleSchemaError('metadata must be an object when set')
+        }
+        metadata = { ...raw.metadata }
+    }
+
+    const rule: AlertRule = {
+        id,
+        name,
+        predicate,
+        enabled,
+        oneShot,
+        ...(cooldownMs !== undefined ? { cooldownMs } : {}),
+        ...(metadata !== undefined ? { metadata } : {}),
+    }
+    return rule
+}

package/src/alerts/types.ts

@@ -0,0 +1,177 @@
+/**
+ * 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
+}

package/src/chartTypes/__tests__/heikinAshi.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest'
+import { createHeikinAshi } from '../heikinAshi'
+import type { OHLCV } from '../types'
+
+const bar = (i: number, o: number, h: number, l: number, c: number, v = 100): OHLCV => ({
+    timestamp: 1_700_000_000_000 + i * 60_000,
+    open: o,
+    high: h,
+    low: l,
+    close: c,
+    volume: v,
+})
+
+describe('heikinAshi', () => {
+    it('seeds HA_open[0] = (open + close) / 2', () => {
+        const ha = createHeikinAshi()
+        const [out] = ha.transform([bar(0, 100, 110, 90, 108)], {})
+        expect(out).toBeDefined()
+        expect(out!.open).toBeCloseTo((100 + 108) / 2, 10)
+        expect(out!.close).toBeCloseTo((100 + 110 + 90 + 108) / 4, 10)
+    })
+
+    it('subsequent bars use HA_open = (prevHAOpen + prevHAClose) / 2', () => {
+        const ha = createHeikinAshi()
+        const out = ha.transform([bar(0, 100, 110, 90, 108), bar(1, 108, 120, 105, 118)], {})
+        const prev = out[0]!
+        const cur = out[1]!
+        expect(cur.open).toBeCloseTo((prev.open + prev.close) / 2, 10)
+        expect(cur.close).toBeCloseTo((108 + 120 + 105 + 118) / 4, 10)
+    })
+
+    it('HA_high >= max(HA_open, HA_close) and HA_high >= input high', () => {
+        const ha = createHeikinAshi()
+        const out = ha.transform(
+            [bar(0, 100, 110, 90, 108), bar(1, 108, 120, 105, 118), bar(2, 118, 125, 116, 120)],
+            {},
+        )
+        for (const b of out) {
+            expect(b.high).toBeGreaterThanOrEqual(Math.max(b.open, b.close))
+            expect(b.low).toBeLessThanOrEqual(Math.min(b.open, b.close))
+        }
+    })
+
+    it('strong uptrend in input produces consecutive bullish HA bars (close >= open)', () => {
+        const ha = createHeikinAshi()
+        const series: OHLCV[] = []
+        for (let i = 0; i < 10; i++) {
+            const base = 100 + i * 5
+            // Strong up bars: open near low, close at high.
+            series.push(bar(i, base, base + 6, base - 1, base + 5))
+        }
+        const out = ha.transform(series, {})
+        // The first bar may be ambiguous; expect the trend to dominate the tail.
+        const bullishTail = out.slice(2).every((b) => b.close >= b.open)
+        expect(bullishTail).toBe(true)
+    })
+
+    it('incremental mode produces identical output to batch mode over a random series', () => {
+        const series: OHLCV[] = []
+        let price = 100
+        // Deterministic pseudo-random walk for repeatability.
+        let seed = 12345
+        const rand = () => {
+            seed = (seed * 1103515245 + 12345) & 0x7fffffff
+            return seed / 0x7fffffff
+        }
+        for (let i = 0; i < 30; i++) {
+            const open = price
+            const drift = (rand() - 0.5) * 4
+            const close = open + drift
+            const high = Math.max(open, close) + rand() * 2
+            const low = Math.min(open, close) - rand() * 2
+            series.push(bar(i, open, high, low, close, Math.floor(rand() * 1000)))
+            price = close
+        }
+        const haBatch = createHeikinAshi()
+        const batched = haBatch.transform(series, {})
+
+        const haInc = createHeikinAshi()
+        const incremental = series.flatMap((b) => Array.from(haInc.appendBar!(b)))
+        expect(incremental.length).toBe(batched.length)
+        for (let i = 0; i < batched.length; i++) {
+            const a = batched[i]!
+            const b = incremental[i]!
+            expect(a.open).toBeCloseTo(b.open, 10)
+            expect(a.high).toBeCloseTo(b.high, 10)
+            expect(a.low).toBeCloseTo(b.low, 10)
+            expect(a.close).toBeCloseTo(b.close, 10)
+            expect(a.timestamp).toBe(b.timestamp)
+            expect(a.volume).toBe(b.volume)
+            expect(a.sourceBarIndexStart).toBe(b.sourceBarIndexStart)
+        }
+    })
+
+    it('reset() clears state so the next appendBar uses the seed formula', () => {
+        const ha = createHeikinAshi()
+        ha.appendBar!(bar(0, 100, 110, 90, 108))
+        ha.appendBar!(bar(1, 108, 115, 105, 112))
+        ha.reset!()
+        const [first] = ha.appendBar!(bar(2, 200, 210, 190, 205))
+        expect(first!.open).toBeCloseTo((200 + 205) / 2, 10)
+        expect(first!.sourceBarIndexStart).toBe(0)
+    })
+
+    it('handles single-bar input cleanly', () => {
+        const ha = createHeikinAshi()
+        const out = ha.transform([bar(0, 50, 55, 45, 52)], {})
+        expect(out).toHaveLength(1)
+        expect(out[0]!.open).toBeCloseTo((50 + 52) / 2, 10)
+        expect(out[0]!.high).toBeGreaterThanOrEqual(55)
+        expect(out[0]!.volume).toBe(100)
+    })
+
+    it('preserves source bar indices 1:1', () => {
+        const ha = createHeikinAshi()
+        const out = ha.transform([bar(0, 100, 110, 90, 108), bar(1, 108, 120, 105, 118)], {})
+        expect(out[0]!.sourceBarIndexStart).toBe(0)
+        expect(out[0]!.sourceBarIndexEnd).toBe(0)
+        expect(out[1]!.sourceBarIndexStart).toBe(1)
+        expect(out[1]!.sourceBarIndexEnd).toBe(1)
+    })
+})