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

package/src/chartTypes/pointAndFigure.ts

@@ -1,284 +0,0 @@
-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/chartTypes/rangeBars.ts

@@ -1,303 +0,0 @@
-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()
-    },
-  }
-}