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

package/src/chartTypes/renko.ts

@@ -74,34 +74,34 @@ import type { ChartTypeTransform, OHLCV, TransformedBar } from './types'
  * `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 }
+  /** 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
+  /** 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)
+  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)
 }
 
 /**
@@ -117,195 +117,201 @@ const trueRange = (bar: OHLCV, prevClose: number | null): number => {
  *     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 }
+  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
+  /**
+   * 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
+  /**
+   * 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
-        }
+    // 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
+    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
+    // 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
-            }
+      // 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 >= 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
-            }
+      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
+      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 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 resetState = (): void => {
-        state = {
-            lastBrickClose: null,
-            lastDirection: null,
-            nextIndex: 0,
-            trWindow: [],
-            prevClose: null,
-            lastBrickSize: null,
-        }
+    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',
+  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
-        },
+    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)
-        },
+    appendBar(bar: OHLCV): ReadonlyArray<TransformedBar> {
+      return consumeBar(bar)
+    },
 
-        reset(): void {
-            resetState()
-        },
-    }
+    reset(): void {
+      resetState()
+    },
+  }
 }

package/src/chartTypes/types.ts

@@ -38,12 +38,12 @@
 
 /** Standard OHLCV row. Timestamps are epoch milliseconds. */
 export interface OHLCV {
-    timestamp: number
-    open: number
-    high: number
-    low: number
-    close: number
-    volume: number
+  timestamp: number
+  open: number
+  high: number
+  low: number
+  close: number
+  volume: number
 }
 
 /**
@@ -58,16 +58,16 @@ export interface OHLCV {
  * 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>>
+  /** 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>>
 }
 
 /**
@@ -83,17 +83,17 @@ export interface TransformedBar extends OHLCV {
  * `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
+  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
 }