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

package/src/chartTypes/renko.ts

@@ -0,0 +1,311 @@
+import { KLineChartError } from '../errors'
+/**
+ * Renko bricks — price-based bars that ignore time.
+ *
+ * A Renko chart drops a fixed-size "brick" every time price advances by one
+ * brick-size from the previous brick's close. Time is collapsed: a quiet hour
+ * may produce zero bricks, a volatile minute may produce ten.
+ *
+ * ## Modes
+ *
+ *  - **Fixed brick size** (`{ brickSize }`): the classic chart. Brick height
+ *    is constant across the entire series.
+ *  - **ATR-adaptive brick size** (`{ useATR: { period } }`): brick size is the
+ *    rolling ATR(period) over the *input* OHLCV series. We compute the full
+ *    ATR series upfront and then use, for each candidate brick, the **trailing
+ *    ATR at the source bar that triggered it**. This means brick height varies
+ *    along the chart — wider in volatile regimes, tighter in quiet ones —
+ *    which is the whole point of ATR mode.
+ *
+ *    Trade-off (documented because it's a real one): ATR bricks are NOT
+ *    uniform-height, so the chart loses the "every step is the same size"
+ *    visual property that classical Renko has. In return, the brick rhythm
+ *    adapts to volatility — a feature TradingView only offers in a separate
+ *    chart-type ("ATR Renko") and which requires the user to reload the
+ *    series to change. Our implementation supports flipping `useATR` on a
+ *    live transform incrementally — see §"Enhancements over TradingView".
+ *
+ * ## Classic reversal rule (the 2× brick-size requirement)
+ *
+ * Once a column of up-bricks has been emitted, a single brick-size reverse
+ * move is NOT enough to start a down-column — it must travel **2 × brickSize**
+ * in the opposite direction from the last brick's close. This is the
+ * "classic" Nison/Steve Nison rule. Without the 2× requirement the chart
+ * "flutters" — every wiggle near the brick-size threshold flips direction.
+ *
+ * In code:
+ *   - Continuation (same direction as last brick): need ≥ 1 × brickSize.
+ *   - Reversal (opposite direction): need ≥ 2 × brickSize.
+ *
+ * The very first brick has no "previous direction", so it uses the 1× rule.
+ *
+ * ## Brick shape
+ *
+ * Each brick is OHLCV-shaped to fit the candle renderer:
+ *
+ *     up-brick:   open = lastBrickClose
+ *                 close = lastBrickClose + brickSize
+ *                 high = close, low = open
+ *
+ *     down-brick: open = lastBrickClose
+ *                 close = lastBrickClose - brickSize
+ *                 high = open, low = close
+ *
+ * `volume` is the sum of input-bar volumes assigned to this brick. We use a
+ * simple rule: each input bar contributes all of its volume to **the first
+ * brick** it triggers in that bar. When one bar triggers N bricks (a gap),
+ * the bar's full volume goes on the first brick and the rest carry zero. This
+ * matches TradingView; the alternative (split evenly) creates phantom volume
+ * spikes when ATR mode changes brick sizes between bricks.
+ *
+ * ## Meta
+ *
+ * `meta.direction` is `'up'` or `'down'` for downstream colour selection.
+ * `meta.brickSize` is the brick height at the time of emission (especially
+ * meaningful in ATR mode).
+ */
+
+import type { ChartTypeTransform, OHLCV, TransformedBar } from './types'
+
+/**
+ * Renko configuration.
+ *
+ * Exactly one of `brickSize` or `useATR` must be supplied. If both are present
+ * `useATR` wins (so callers can store both and toggle a flag).
+ */
+export interface RenkoConfig {
+    /** Fixed brick height in price units. Must be > 0. */
+    brickSize?: number
+    /** ATR-adaptive mode. `period` is the ATR lookback. */
+    useATR?: { period: number }
+}
+
+interface RenkoState {
+    /** Close of the most recently emitted brick. `null` until the first brick. */
+    lastBrickClose: number | null
+    /** Direction of the most recently emitted brick. `null` for the first brick. */
+    lastDirection: 'up' | 'down' | null
+    /** Count of input bars consumed so far (= next source index). */
+    nextIndex: number
+    /** For ATR mode — the rolling TR window (last `period` true ranges). */
+    trWindow: number[]
+    /** For ATR mode — previous close, needed to compute TR. */
+    prevClose: number | null
+    /** Effective brick size at the most recent emission (for inspection / tests). */
+    lastBrickSize: number | null
+}
+
+/** Compute true range for a bar against the prior close. */
+const trueRange = (bar: OHLCV, prevClose: number | null): number => {
+    const hl = bar.high - bar.low
+    if (prevClose === null) return hl
+    const hc = Math.abs(bar.high - prevClose)
+    const lc = Math.abs(bar.low - prevClose)
+    return Math.max(hl, hc, lc)
+}
+
+/**
+ * Build a Renko transform.
+ *
+ * The transform supports both `transform(input, config)` and `appendBar(bar)`.
+ * The config passed to `transform` is also captured for subsequent
+ * `appendBar` calls — so the typical flow is:
+ *
+ *     const r = createRenko()
+ *     const history = r.transform(historicalBars, { brickSize: 10 })
+ *     // ...later, as ticks arrive:
+ *     const newBricks = r.appendBar(liveBar)
+ */
+export function createRenko(): ChartTypeTransform<RenkoConfig> {
+    let state: RenkoState = {
+        lastBrickClose: null,
+        lastDirection: null,
+        nextIndex: 0,
+        trWindow: [],
+        prevClose: null,
+        lastBrickSize: null,
+    }
+    let activeConfig: RenkoConfig = { brickSize: 1 }
+
+    /**
+     * Return the current effective brick size given the active config and the
+     * current ATR window. Returns `null` when ATR mode is enabled but the
+     * window hasn't filled yet (no bricks can form until we have a brick
+     * size).
+     */
+    const currentBrickSize = (): number | null => {
+        if (activeConfig.useATR) {
+            const period = activeConfig.useATR.period
+            if (state.trWindow.length < period) return null
+            let sum = 0
+            // Use only the most recent `period` entries — older history is
+            // not part of the rolling ATR (Wilder's smoothing is a separate
+            // discussion; we use the simple rolling mean which is the
+            // baseline TradingView ATR-Renko shows).
+            for (let i = state.trWindow.length - period; i < state.trWindow.length; i++) {
+                sum += state.trWindow[i] ?? 0
+            }
+            return sum / period
+        }
+        return activeConfig.brickSize ?? null
+    }
+
+    /**
+     * Try to emit bricks from a single input bar. The bar's `close` is the
+     * trigger; we ignore intra-bar high/low for brick formation because Renko
+     * is canonically a *close-only* construction. (Using high/low works on
+     * tick data but creates phantom bricks on OHLC bars.)
+     */
+    const emitBricksFromBar = (bar: OHLCV, sourceIndex: number): TransformedBar[] => {
+        const out: TransformedBar[] = []
+        const brickSize = currentBrickSize()
+        if (brickSize === null || brickSize <= 0) return out
+
+        // Initialise the "last brick close" lazily on the first bar — we
+        // anchor it to the bar's close so the first non-trivial move starts
+        // brick formation. (Anchoring to `open` would mean the very first bar
+        // could itself form a brick, which differs from the convention.)
+        if (state.lastBrickClose === null) {
+            state.lastBrickClose = bar.close
+            return out
+        }
+
+        const close = bar.close
+        let firstBrickInThisBar = true
+
+        // Keep stepping bricks until the close no longer satisfies the
+        // threshold. Each iteration emits one brick and advances state.
+        // Loop bound: at most ceil(|close - lastBrickClose| / brickSize) — a
+        // hard upper bound prevents pathological infinite loops if brickSize
+        // becomes zero mid-iteration.
+        let safety = 0
+        while (safety++ < 1_000_000) {
+            const last: number | null = state.lastBrickClose
+            if (last === null) break
+            const diff: number = close - last
+
+            // Continuation needs 1×, reversal needs 2×. First-ever brick uses 1×.
+            let upThreshold: number
+            let downThreshold: number
+            if (state.lastDirection === 'up') {
+                upThreshold = brickSize
+                downThreshold = -2 * brickSize
+            } else if (state.lastDirection === 'down') {
+                upThreshold = 2 * brickSize
+                downThreshold = -brickSize
+            } else {
+                upThreshold = brickSize
+                downThreshold = -brickSize
+            }
+
+            if (diff >= upThreshold) {
+                const newClose: number = last + brickSize
+                out.push({
+                    timestamp: bar.timestamp,
+                    open: last,
+                    close: newClose,
+                    high: newClose,
+                    low: last,
+                    volume: firstBrickInThisBar ? bar.volume : 0,
+                    sourceBarIndexStart: sourceIndex,
+                    sourceBarIndexEnd: sourceIndex,
+                    meta: { direction: 'up', brickSize },
+                })
+                state.lastBrickClose = newClose
+                state.lastDirection = 'up'
+                state.lastBrickSize = brickSize
+                firstBrickInThisBar = false
+                continue
+            }
+
+            if (diff <= downThreshold) {
+                const newClose: number = last - brickSize
+                out.push({
+                    timestamp: bar.timestamp,
+                    open: last,
+                    close: newClose,
+                    high: last,
+                    low: newClose,
+                    volume: firstBrickInThisBar ? bar.volume : 0,
+                    sourceBarIndexStart: sourceIndex,
+                    sourceBarIndexEnd: sourceIndex,
+                    meta: { direction: 'down', brickSize },
+                })
+                state.lastBrickClose = newClose
+                state.lastDirection = 'down'
+                state.lastBrickSize = brickSize
+                firstBrickInThisBar = false
+                continue
+            }
+
+            break
+        }
+        return out
+    }
+
+    const consumeBar = (bar: OHLCV): TransformedBar[] => {
+        const sourceIndex = state.nextIndex
+        // Update TR window BEFORE checking brick formation so the first ATR
+        // window's worth of bars participate in brick sizing as soon as
+        // possible.
+        const tr = trueRange(bar, state.prevClose)
+        state.trWindow.push(tr)
+        // Cap the window growth to twice the period for memory bound;
+        // anything older is never read.
+        if (activeConfig.useATR) {
+            const period = activeConfig.useATR.period
+            if (state.trWindow.length > period * 2) {
+                state.trWindow = state.trWindow.slice(state.trWindow.length - period)
+            }
+        } else if (state.trWindow.length > 2048) {
+            // For non-ATR mode we don't need the window at all — clear it.
+            state.trWindow = []
+        }
+        state.prevClose = bar.close
+
+        const emitted = emitBricksFromBar(bar, sourceIndex)
+        state.nextIndex = sourceIndex + 1
+        return emitted
+    }
+
+    const resetState = (): void => {
+        state = {
+            lastBrickClose: null,
+            lastDirection: null,
+            nextIndex: 0,
+            trWindow: [],
+            prevClose: null,
+            lastBrickSize: null,
+        }
+    }
+
+    return {
+        typeId: 'renko',
+
+        transform(input: ReadonlyArray<OHLCV>, config: RenkoConfig): ReadonlyArray<TransformedBar> {
+            // Validate: at least one mode must be set with sane values.
+            if (!config.useATR && (config.brickSize === undefined || config.brickSize <= 0)) {
+                throw new KLineChartError('CHART_TYPE_CONFIG_INVALID', 'createRenko: config requires brickSize > 0 or useATR { period }')
+            }
+            if (config.useATR && config.useATR.period < 1) {
+                throw new KLineChartError('CHART_TYPE_CONFIG_INVALID', 'createRenko: useATR.period must be >= 1')
+            }
+            activeConfig = config
+            resetState()
+            const out: TransformedBar[] = []
+            for (const bar of input) {
+                const fresh = consumeBar(bar)
+                for (const b of fresh) out.push(b)
+            }
+            return out
+        },
+
+        appendBar(bar: OHLCV): ReadonlyArray<TransformedBar> {
+            return consumeBar(bar)
+        },
+
+        reset(): void {
+            resetState()
+        },
+    }
+}

package/src/chartTypes/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Chart-type transformers — public type contract.
+ *
+ * A "chart type" in TradingView (Heikin Ashi, Renko, P&F, Range Bars, etc.) is
+ * a **data transform**, not a different renderer. Every output is still
+ * OHLCV-shaped, so the same candle renderer paints all of them. This package
+ * is therefore deliberately headless: rendering belongs to the
+ * Renderer/Scene layer (see `docs/ROADMAP.md` §0).
+ *
+ * Why this matters for the WebGPU path: because the output is OHLCV, the
+ * existing instanced-quad K-line vertex pipeline (see `docs/ROADMAP.md` §2.3)
+ * draws Heikin Ashi / Renko / P&F / Range Bars at the same throughput as raw
+ * candles — no new render path, no new shader.
+ *
+ * ## Two transforms in one interface — batch vs incremental
+ *
+ * Every transform here supports two modes:
+ *
+ *  - **Batch** (`transform`): pure function over an OHLCV slice. Re-derives the
+ *    output from scratch. Use this for chart loads / history scrolls.
+ *  - **Incremental** (`appendBar`): consume one live bar at a time, emit zero
+ *    or more output bars, and update internal state. Use this for streaming
+ *    quotes.
+ *
+ * Calling `appendBar` repeatedly over the same sequence must produce **bit-for-
+ * bit identical** output to a single `transform` over that sequence. The test
+ * suite enforces this with a randomised property test on a ≥30-bar input.
+ *
+ * ## A note on time semantics
+ *
+ * Renko, P&F and Range Bars all break the "one input bar = one output bar"
+ * assumption. We preserve provenance with `sourceBarIndexStart` /
+ * `sourceBarIndexEnd` so callers can map back to the source series for
+ * tooltips, x-axis labels, and event correlation. The `timestamp` on a
+ * derived bar is the timestamp of the source bar that **closed** it (i.e. the
+ * trigger).
+ */
+
+/** Standard OHLCV row. Timestamps are epoch milliseconds. */
+export interface OHLCV {
+    timestamp: number
+    open: number
+    high: number
+    low: number
+    close: number
+    volume: number
+}
+
+/**
+ * One output bar from a chart-type transform. Extends `OHLCV` so it can flow
+ * through the same scale / renderer pipeline as raw candles.
+ *
+ * `sourceBarIndexStart` / `sourceBarIndexEnd` mark which input rows were
+ * aggregated into this output row (inclusive). For 1:1 transforms (Heikin
+ * Ashi) they are equal. For aggregating transforms (Renko, P&F, Range Bars)
+ * they describe a range of source rows. For "fanning" transforms — one input
+ * bar that produces multiple output bars (large-gap Renko, oversized Range
+ * bar) — every fanned-out output row shares the same start/end index.
+ */
+export interface TransformedBar extends OHLCV {
+    /** Lowest source index folded into this output bar (inclusive). */
+    sourceBarIndexStart: number
+    /** Highest source index folded into this output bar (inclusive). */
+    sourceBarIndexEnd: number
+    /**
+     * Transform-specific metadata. Marked `Readonly` so consumers can rely on
+     * structural sharing — a transform must never mutate metadata after
+     * emitting it.
+     */
+    meta?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Common shape for all chart-type transformers.
+ *
+ * `transform` is pure — it does NOT mutate `input` and (for stateful
+ * transforms) calling it resets internal state first so the result depends
+ * only on `input` + `config`.
+ *
+ * `appendBar` is incremental — it does mutate internal state. Calling
+ * `reset()` returns the transform to its initial state.
+ *
+ * `typeId` is a stable, human-readable identifier used by the scene/registry.
+ */
+export interface ChartTypeTransform<TConfig = unknown> {
+    readonly typeId: string
+    transform(input: ReadonlyArray<OHLCV>, config: TConfig): ReadonlyArray<TransformedBar>
+    /**
+     * Append one input bar and emit zero, one, or many output bars.
+     *
+     * Implementations that do not support incremental mode omit this method.
+     * For Heikin Ashi the output is always exactly one bar per call. For
+     * Renko / Range Bars / P&F the count can be 0..N depending on whether the
+     * new bar triggers brick/box formation.
+     */
+    appendBar?(input: OHLCV): ReadonlyArray<TransformedBar>
+    /** Drop internal state. Idempotent. Safe to call on stateless transforms. */
+    reset?(): void
+}