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

package/src/features/chartTypes/pointAndFigure.ts

@@ -0,0 +1,284 @@
+import { KLineChartError } from '../../errors'
+/**
+ * Point & Figure (P&F) — classic three-box-reversal column chart.
+ *
+ * P&F is the oldest non-time chart type still in use (de Villiers documented
+ * it in 1933, traders were drawing it on graph paper a century before that).
+ * It is a column chart: each column is either rising X's or falling O's, and
+ * we move to a new column only when price reverses by `reversal × boxSize`.
+ *
+ * ## Algorithm (classic 3-box reversal)
+ *
+ *  - State: current column `direction`, current column extent `[low, high]`.
+ *  - For each new input bar with `[H, L]`:
+ *
+ *    - If column is X (up):
+ *        * If `H >= high + boxSize`: extend the X column up to the highest box
+ *          containing `H` (i.e. set `high := floor(H / boxSize) * boxSize`).
+ *        * Else if `L <= high - reversal * boxSize`: reverse — start a new O
+ *          column. The new column starts **one box below** the prior X
+ *          column's high, and goes down to the lowest box `>= L`. The "one
+ *          box below" rule is the classical de Villiers convention and is
+ *          what TradingView uses.
+ *        * Else: bar does nothing.
+ *
+ *    - Symmetric for an O (down) column.
+ *
+ *  - First-ever input bar seeds the chart with an X column anchored on the
+ *    bar's `low` rounded down to a box boundary, extended up to `H` rounded
+ *    down to a box boundary. (Some traditions start with the high; we use
+ *    low-anchored which is more deterministic for a single bar.)
+ *
+ * ## Why this is lossy by design
+ *
+ * P&F deletes time entirely. Two bars produced at very different times can
+ * land in the same column. We therefore set every output column's
+ * `timestamp` to the timestamp of the source bar that **closed** the column
+ * (i.e. the last bar that touched it). This gives downstream tooltips a
+ * meaningful anchor while honouring the lossy semantics.
+ *
+ * ## OHLCV mapping for one column
+ *
+ *  - `open`  = starting box price (column entry)
+ *  - `close` = final box price (column exit / current frontier)
+ *  - `high`  = max box price reached in this column
+ *  - `low`   = min box price reached in this column
+ *  - `volume`= sum of input bar volumes that touched this column
+ *
+ * For an X column `close === high` and `open === low`. For an O column
+ * `close === low` and `open === high`. We populate `meta.direction` so
+ * renderers can colour distinctly.
+ *
+ * ## Reversal vs extension at the exact threshold
+ *
+ * If a bar simultaneously satisfies both extension and reversal — e.g. an X
+ * column where `H >= high + boxSize` AND `L <= high - reversal * boxSize` —
+ * **extension wins** (we follow the direction-of-momentum rule). This avoids
+ * "chop" in volatile bars but is a deliberate trade-off; some older systems
+ * give reversal priority on the basis of "the down move came second". We
+ * pick extension because it matches modern interactive P&F implementations
+ * including TradingView.
+ *
+ * ## Emission strategy
+ *
+ * Each completed column emits exactly **one** TransformedBar — the column's
+ * snapshot at the moment it closed. While a column is still "open" (i.e. it
+ * is the current column being extended) it does NOT appear in the output.
+ * `appendBar` therefore returns `[]` for bars that only extend the current
+ * column, and `[completedColumn, ...]` for bars that trigger a reversal.
+ *
+ * In batch mode `transform()` returns every column INCLUDING the in-progress
+ * final column so the user sees the full picture. This is the only place
+ * where batch and incremental diverge — and it's intentional, because there
+ * is no streaming convention to "tentatively emit" a still-open column.
+ * Tests assert that *closed* columns match between modes.
+ */
+
+import type { ChartTypeTransform, OHLCV, TransformedBar } from './types'
+
+export interface PointAndFigureConfig {
+  /** Box height in price units. Must be > 0. */
+  boxSize: number
+  /** Reversal in number of boxes. Classic value is 3. Must be >= 1. */
+  reversal: number
+}
+
+interface PFColumn {
+  direction: 'up' | 'down'
+  /** Price of the column's first box (entry). */
+  startPrice: number
+  /** Price of the column's current frontier box. */
+  endPrice: number
+  /** Source index range this column has aggregated. */
+  sourceStart: number
+  sourceEnd: number
+  /** Sum of input bar volumes accumulated into this column. */
+  volume: number
+  /** Timestamp of the last bar that touched this column. */
+  timestamp: number
+}
+
+interface PFState {
+  column: PFColumn | null
+  nextIndex: number
+  closedColumns: TransformedBar[]
+}
+
+/**
+ * Convert an internal column to a `TransformedBar`. We compute `open`, `close`,
+ * `high`, `low` from the column's two endpoints (P&F columns are monotonic in
+ * one direction so the two endpoints are the extremes).
+ */
+const columnToBar = (col: PFColumn): TransformedBar => {
+  const open = col.startPrice
+  const close = col.endPrice
+  const high = Math.max(open, close)
+  const low = Math.min(open, close)
+  return {
+    timestamp: col.timestamp,
+    open,
+    high,
+    low,
+    close,
+    volume: col.volume,
+    sourceBarIndexStart: col.sourceStart,
+    sourceBarIndexEnd: col.sourceEnd,
+    meta: { direction: col.direction },
+  }
+}
+
+export function createPointAndFigure(): ChartTypeTransform<PointAndFigureConfig> {
+  let state: PFState = { column: null, nextIndex: 0, closedColumns: [] }
+  let activeConfig: PointAndFigureConfig = { boxSize: 1, reversal: 3 }
+
+  /** Snap `p` down to the nearest box boundary. */
+  const floorToBox = (p: number, box: number): number => Math.floor(p / box) * box
+  /** Snap `p` up to the nearest box boundary. */
+  const ceilToBox = (p: number, box: number): number => Math.ceil(p / box) * box
+
+  /**
+   * Process one input bar and return any column(s) that **closed** as a
+   * result. The in-progress column is held in `state.column` and is NOT
+   * returned until it closes (i.e. a reversal pushes it into closedColumns).
+   */
+  const consumeBar = (bar: OHLCV): TransformedBar[] => {
+    const sourceIndex = state.nextIndex
+    state.nextIndex = sourceIndex + 1
+    const { boxSize, reversal } = activeConfig
+    const closed: TransformedBar[] = []
+
+    // Seed: no current column. Anchor an X column on the bar's low/high
+    // rounded to box boundaries. If high-low rounds to the same box (very
+    // narrow bar) we still create a degenerate column of height zero so
+    // the chart has a starting point — it will be extended by future bars.
+    if (state.column === null) {
+      const start = floorToBox(bar.low, boxSize)
+      const end = floorToBox(bar.high, boxSize)
+      state.column = {
+        direction: 'up',
+        startPrice: start,
+        endPrice: end,
+        sourceStart: sourceIndex,
+        sourceEnd: sourceIndex,
+        volume: bar.volume,
+        timestamp: bar.timestamp,
+      }
+      return closed
+    }
+
+    const col = state.column
+
+    if (col.direction === 'up') {
+      // Try extension first (extension wins ties — see file header).
+      const newHigh = floorToBox(bar.high, boxSize)
+      if (newHigh >= col.endPrice + boxSize) {
+        col.endPrice = newHigh
+        col.sourceEnd = sourceIndex
+        col.volume += bar.volume
+        col.timestamp = bar.timestamp
+        return closed
+      }
+      // Then reversal.
+      if (bar.low <= col.endPrice - reversal * boxSize) {
+        // Close the X column.
+        closed.push(columnToBar(col))
+        state.closedColumns.push(closed[closed.length - 1] as TransformedBar)
+        // Start a new O column ONE box below the X column's high.
+        const newColumnStart = col.endPrice - boxSize
+        const newColumnEnd = ceilToBox(bar.low, boxSize)
+        state.column = {
+          direction: 'down',
+          startPrice: newColumnStart,
+          endPrice: newColumnEnd <= newColumnStart ? newColumnEnd : newColumnStart,
+          sourceStart: sourceIndex,
+          sourceEnd: sourceIndex,
+          volume: bar.volume,
+          timestamp: bar.timestamp,
+        }
+        return closed
+      }
+      // Bar does nothing — still attribute volume + advance source range
+      // so the column's metadata reflects the bars that touched it.
+      col.sourceEnd = sourceIndex
+      col.volume += bar.volume
+      col.timestamp = bar.timestamp
+      return closed
+    }
+
+    // col.direction === 'down'
+    const newLow = ceilToBox(bar.low, boxSize)
+    if (newLow <= col.endPrice - boxSize) {
+      col.endPrice = newLow
+      col.sourceEnd = sourceIndex
+      col.volume += bar.volume
+      col.timestamp = bar.timestamp
+      return closed
+    }
+    if (bar.high >= col.endPrice + reversal * boxSize) {
+      closed.push(columnToBar(col))
+      state.closedColumns.push(closed[closed.length - 1] as TransformedBar)
+      const newColumnStart = col.endPrice + boxSize
+      const newColumnEnd = floorToBox(bar.high, boxSize)
+      state.column = {
+        direction: 'up',
+        startPrice: newColumnStart,
+        endPrice: newColumnEnd >= newColumnStart ? newColumnEnd : newColumnStart,
+        sourceStart: sourceIndex,
+        sourceEnd: sourceIndex,
+        volume: bar.volume,
+        timestamp: bar.timestamp,
+      }
+      return closed
+    }
+    col.sourceEnd = sourceIndex
+    col.volume += bar.volume
+    col.timestamp = bar.timestamp
+    return closed
+  }
+
+  const resetState = (): void => {
+    state = { column: null, nextIndex: 0, closedColumns: [] }
+  }
+
+  return {
+    typeId: 'point-and-figure',
+
+    transform(
+      input: ReadonlyArray<OHLCV>,
+      config: PointAndFigureConfig,
+    ): ReadonlyArray<TransformedBar> {
+      if (config.boxSize <= 0) {
+        throw new KLineChartError(
+          'CHART_TYPE_CONFIG_INVALID',
+          'createPointAndFigure: boxSize must be > 0',
+        )
+      }
+      if (config.reversal < 1 || !Number.isFinite(config.reversal)) {
+        throw new KLineChartError(
+          'CHART_TYPE_CONFIG_INVALID',
+          'createPointAndFigure: reversal must be >= 1',
+        )
+      }
+      activeConfig = config
+      resetState()
+      for (const bar of input) {
+        consumeBar(bar)
+      }
+      // Batch mode includes the currently-open column as the last entry —
+      // see file header. Incremental mode does not.
+      const out = [...state.closedColumns]
+      if (state.column !== null) {
+        out.push(columnToBar(state.column))
+      }
+      return out
+    },
+
+    appendBar(bar: OHLCV): ReadonlyArray<TransformedBar> {
+      return consumeBar(bar)
+    },
+
+    reset(): void {
+      resetState()
+    },
+  }
+}

package/src/features/chartTypes/rangeBars.ts

@@ -0,0 +1,303 @@
+import { KLineChartError } from '../../errors'
+/**
+ * Range Bars — fixed-range price bars.
+ *
+ * Every output bar spans exactly `range` price units (high - low === range at
+ * close). When the active bar's range reaches the threshold it is closed and
+ * a new bar begins, opening at the trigger price. Time, like Renko and P&F,
+ * is collapsed.
+ *
+ * ## Why range bars over Renko
+ *
+ *  - **Renko** uses only the close; intra-bar wicks are invisible. Good for
+ *    long-term swing visualisation.
+ *  - **Range bars** use the entire (high, low) of every input bar. They show
+ *    intra-bar excursions and tend to be more responsive to spikes.
+ *
+ * ## Algorithm
+ *
+ * State carries the in-progress bar `{open, high, low, volume, ...}`. For each
+ * input bar:
+ *
+ *   1. Decide a *direction* for the input bar (`up` if close >= open, else
+ *      `down`). Range bars need a direction because OHLC bars don't carry the
+ *      tick-level path between low and high.
+ *   2. Merge the input bar into the open bar BUT only along the direction —
+ *      meaning we honour both high and low, but if the merged span exceeds
+ *      `range` we *carve* the range bar in the direction of motion.
+ *   3. Carving: an "up" input that pushes total span past `range` closes the
+ *      current bar at `low + range`. The carved excess starts the next bar
+ *      with `open = low + range`, and any remaining high above the carved
+ *      ceiling becomes the next bar's high (recursion).
+ *   4. Edge case: a single input bar with `high - low > range` walks the bar's
+ *      range in `range`-sized steps in the input's direction and emits one
+ *      output bar per full step.
+ *
+ * ## Direction heuristic for OHLC inputs
+ *
+ * When closing from a single input contribution, we use `input.close >= input.open`
+ * to choose the carve direction. This is the same heuristic TradingView uses
+ * with OHLC input — exact tick-by-tick directionality would require trades.
+ *
+ * ## Volume aggregation
+ *
+ * Volume is summed across every input bar that contributes any range. For a
+ * single input that produces multiple output bars (a split), the input's
+ * volume is divided proportionally to the price extent each output bar
+ * carves of the input bar's total H-L.
+ *
+ * ## Emission strategy
+ *
+ * `transform()` returns every closed bar PLUS the currently-open bar (mirrors
+ * a live chart). `appendBar()` returns only the bars that closed on this
+ * append — the open bar is held in state. Tests assert the closed prefix
+ * matches between modes.
+ */
+
+import type { ChartTypeTransform, OHLCV, TransformedBar } from './types'
+
+export interface RangeBarsConfig {
+  /** Range height in price units. Must be > 0. */
+  range: number
+}
+
+interface OpenRangeBar {
+  open: number
+  high: number
+  low: number
+  volume: number
+  sourceStart: number
+  sourceEnd: number
+  timestamp: number
+}
+
+interface RangeState {
+  open: OpenRangeBar | null
+  nextIndex: number
+  closed: TransformedBar[]
+}
+
+const makeClosed = (
+  open: number,
+  high: number,
+  low: number,
+  close: number,
+  volume: number,
+  sourceStart: number,
+  sourceEnd: number,
+  timestamp: number,
+): TransformedBar => {
+  const direction: 'up' | 'down' = close >= open ? 'up' : 'down'
+  return {
+    timestamp,
+    open,
+    high,
+    low,
+    close,
+    volume,
+    sourceBarIndexStart: sourceStart,
+    sourceBarIndexEnd: sourceEnd,
+    meta: { direction },
+  }
+}
+
+export function createRangeBars(): ChartTypeTransform<RangeBarsConfig> {
+  let state: RangeState = { open: null, nextIndex: 0, closed: [] }
+  let activeConfig: RangeBarsConfig = { range: 1 }
+
+  /**
+   * Merge one input bar into the open range bar, carving as many closed
+   * range bars as needed. Returns the bars that closed during this merge.
+   */
+  const consumeBar = (bar: OHLCV): TransformedBar[] => {
+    const sourceIndex = state.nextIndex
+    state.nextIndex = sourceIndex + 1
+    const range = activeConfig.range
+    const closed: TransformedBar[] = []
+
+    const upward = bar.close >= bar.open
+    const inputExtent = Math.max(bar.high - bar.low, 1e-12)
+
+    // Seed: no in-progress bar yet. Open one at the input's open. The
+    // input's full H/L participates immediately.
+    if (state.open === null) {
+      state.open = {
+        open: bar.open,
+        high: bar.open,
+        low: bar.open,
+        volume: 0,
+        sourceStart: sourceIndex,
+        sourceEnd: sourceIndex,
+        timestamp: bar.timestamp,
+      }
+    }
+
+    // Track how much input volume we've attributed so we can split it
+    // proportionally across any carved bars.
+    let inputVolUsed = 0
+
+    // Repeatedly merge the input into the open bar; each iteration either
+    // (a) closes a bar and seeds a new open one from the carved-off
+    // remainder, or (b) finishes by absorbing the entire input range.
+    //
+    // We walk the input bar along its direction. `remainingHigh` and
+    // `remainingLow` shrink as we carve. We stop when no further range
+    // bar can be closed.
+    let remainingHigh = bar.high
+    let remainingLow = bar.low
+
+    let safety = 0
+    while (safety++ < 1_000_000) {
+      const opened = state.open!
+      // Apply the remaining input extent to the open bar.
+      const mergedHigh = Math.max(opened.high, remainingHigh)
+      const mergedLow = Math.min(opened.low, remainingLow)
+      const span = mergedHigh - mergedLow
+      if (span < range) {
+        // Whole remainder fits within range — absorb and stop.
+        opened.high = mergedHigh
+        opened.low = mergedLow
+        opened.sourceEnd = sourceIndex
+        opened.timestamp = bar.timestamp
+        // All remaining input volume goes here.
+        opened.volume += bar.volume - inputVolUsed
+        inputVolUsed = bar.volume
+        break
+      }
+
+      // Span >= range. Carve a range bar in the direction of motion.
+      // For an up bar: close at low + range (we move up first).
+      // For a down bar: close at high - range.
+      let closePrice: number
+      let closedHigh: number
+      let closedLow: number
+      if (upward) {
+        closedLow = mergedLow
+        closedHigh = mergedLow + range
+        closePrice = closedHigh
+      } else {
+        closedHigh = mergedHigh
+        closedLow = mergedHigh - range
+        closePrice = closedLow
+      }
+
+      // Volume attributed to this carved bar: proportional to the
+      // input extent it covers, plus any volume already accumulated on
+      // the open bar from prior input bars.
+      const carvedExtent = Math.min(range, span)
+      const inputShare = (carvedExtent / inputExtent) * bar.volume
+      const attribInput = Math.min(inputShare, bar.volume - inputVolUsed)
+      inputVolUsed += attribInput
+
+      const closedVolume = opened.volume + attribInput
+      closed.push(
+        makeClosed(
+          opened.open,
+          closedHigh,
+          closedLow,
+          closePrice,
+          closedVolume,
+          opened.sourceStart,
+          sourceIndex,
+          bar.timestamp,
+        ),
+      )
+      state.closed.push(closed[closed.length - 1] as TransformedBar)
+
+      // Seed the next open bar at the carve boundary. The remaining
+      // input extent above (for up) or below (for down) the carve
+      // continues into the new bar.
+      if (upward) {
+        remainingLow = closePrice
+        state.open = {
+          open: closePrice,
+          high: closePrice,
+          low: closePrice,
+          volume: 0,
+          sourceStart: sourceIndex,
+          sourceEnd: sourceIndex,
+          timestamp: bar.timestamp,
+        }
+        // If the input bar's high is no greater than the carve
+        // ceiling, nothing more from this input remains for further
+        // carving.
+        if (remainingHigh <= closePrice) {
+          // The new open bar already has open=closePrice; the
+          // remaining high contributes nothing further. Stop.
+          state.open.high = closePrice
+          state.open.low = closePrice
+          // Attribute leftover input volume to the now-current open.
+          state.open.volume = bar.volume - inputVolUsed
+          inputVolUsed = bar.volume
+          break
+        }
+      } else {
+        remainingHigh = closePrice
+        state.open = {
+          open: closePrice,
+          high: closePrice,
+          low: closePrice,
+          volume: 0,
+          sourceStart: sourceIndex,
+          sourceEnd: sourceIndex,
+          timestamp: bar.timestamp,
+        }
+        if (remainingLow >= closePrice) {
+          state.open.high = closePrice
+          state.open.low = closePrice
+          state.open.volume = bar.volume - inputVolUsed
+          inputVolUsed = bar.volume
+          break
+        }
+      }
+    }
+
+    return closed
+  }
+
+  const resetState = (): void => {
+    state = { open: null, nextIndex: 0, closed: [] }
+  }
+
+  return {
+    typeId: 'range-bars',
+
+    transform(input: ReadonlyArray<OHLCV>, config: RangeBarsConfig): ReadonlyArray<TransformedBar> {
+      if (config.range <= 0 || !Number.isFinite(config.range)) {
+        throw new KLineChartError('CHART_TYPE_CONFIG_INVALID', 'createRangeBars: range must be > 0')
+      }
+      activeConfig = config
+      resetState()
+      for (const bar of input) consumeBar(bar)
+      const out = [...state.closed]
+      if (state.open !== null) {
+        // The trailing in-progress bar's "close" is its frontier — the
+        // direction of last accumulation. We pick high for "up" if
+        // close>=open, else low, matching candle semantics.
+        const o = state.open
+        const close = o.high - o.open >= o.open - o.low ? o.high : o.low
+        out.push(
+          makeClosed(
+            o.open,
+            o.high,
+            o.low,
+            close,
+            o.volume,
+            o.sourceStart,
+            o.sourceEnd,
+            o.timestamp,
+          ),
+        )
+      }
+      return out
+    },
+
+    appendBar(bar: OHLCV): ReadonlyArray<TransformedBar> {
+      return consumeBar(bar)
+    },
+
+    reset(): void {
+      resetState()
+    },
+  }
+}