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

package/src/features/chartTypes/renko.ts

@@ -0,0 +1,317 @@
+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/features/indicators/alma.ts

@@ -0,0 +1,64 @@
+import { KLineChartError } from '../../errors'
+/**
+ * ALMA — Arnaud Legoux Moving Average.
+ *
+ * Public reference: Legoux & Beneduce, "ALMA Indicator Description" (2009).
+ *
+ * Weighted MA where weights are a Gaussian centred at `offset * (period-1)`
+ * (default 0.85 = near the right edge), spread parameter `sigma` (default 6).
+ *
+ *   m       = offset * (period - 1)
+ *   s       = period / sigma
+ *   w[k]    = exp(-(k - m)^2 / (2 * s^2))   for k in 0..period-1
+ *   alma[i] = sum(w[k] * price[i - k]) / sum(w[k])
+ *
+ * `offset` near 1 follows price tightly (short lag); near 0 smooths heavily.
+ * `sigma` controls the bell width — lower = sharper centre.
+ *
+ * Output length === input length. Indices < period - 1 are NaN.
+ */
+
+export interface AlmaOptions {
+  period: number
+  /** Default 0.85 — fractional position of the Gaussian centre, in [0, 1]. */
+  offset?: number
+  /** Default 6 — bell width parameter. Must be > 0. */
+  sigma?: number
+}
+
+export function computeALMA(prices: ReadonlyArray<number>, opts: AlmaOptions): Float64Array {
+  const { period } = opts
+  const offset = opts.offset ?? 0.85
+  const sigma = opts.sigma ?? 6
+  if (period < 1 || !Number.isFinite(period))
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'computeALMA: period must be >= 1')
+  if (sigma <= 0 || !Number.isFinite(sigma))
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'computeALMA: sigma must be > 0')
+  if (offset < 0 || offset > 1)
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'computeALMA: offset must be in [0, 1]')
+
+  const out = new Float64Array(prices.length)
+  const m = offset * (period - 1)
+  const s = period / sigma
+  const denom = 2 * s * s
+  const weights = new Float64Array(period)
+  let wsum = 0
+  for (let k = 0; k < period; k++) {
+    const w = Math.exp(-((k - m) * (k - m)) / denom)
+    weights[k] = w
+    wsum += w
+  }
+
+  for (let i = 0; i < prices.length; i++) {
+    if (i < period - 1) {
+      out[i] = Number.NaN
+      continue
+    }
+    let acc = 0
+    for (let k = 0; k < period; k++) {
+      acc += (weights[k] as number) * (prices[i - k] as number)
+    }
+    out[i] = acc / wsum
+  }
+  return out
+}

package/src/features/indicators/awesomeOscillator.ts

@@ -0,0 +1,57 @@
+import { KLineChartError } from '../../errors'
+/**
+ * Awesome Oscillator — Bill Williams.
+ *
+ *   median[i] = (high[i] + low[i]) / 2
+ *   AO[i]     = SMA(median, fast) - SMA(median, slow)
+ *
+ * Defaults: fast=5, slow=34.
+ *
+ * Output: `Float64Array` of length === input. NaN leading.
+ */
+
+export interface AwesomeOscillatorOptions {
+  fast?: number
+  slow?: number
+}
+
+export function computeAwesomeOscillator(
+  bars: ReadonlyArray<{ high: number; low: number }>,
+  opts: AwesomeOscillatorOptions = {},
+): Float64Array {
+  const fast = opts.fast ?? 5
+  const slow = opts.slow ?? 34
+  if (fast < 1 || slow < 1 || fast >= slow) {
+    throw new KLineChartError(
+      'INDICATOR_INVALID_PARAM',
+      'computeAwesomeOscillator: require 1 <= fast < slow',
+    )
+  }
+  const n = bars.length
+  const med = new Float64Array(n)
+  for (let i = 0; i < n; i++) {
+    const b = bars[i] as { high: number; low: number }
+    med[i] = (b.high + b.low) / 2
+  }
+  const sf = simpleSMA(med, fast)
+  const ss = simpleSMA(med, slow)
+  const out = new Float64Array(n)
+  for (let i = 0; i < n; i++) {
+    const a = sf[i] as number
+    const b = ss[i] as number
+    out[i] = Number.isNaN(a) || Number.isNaN(b) ? Number.NaN : a - b
+  }
+  return out
+}
+
+function simpleSMA(input: Float64Array, period: number): Float64Array {
+  const n = input.length
+  const out = new Float64Array(n)
+  let acc = 0
+  for (let i = 0; i < n; i++) {
+    acc += input[i] as number
+    if (i >= period) acc -= input[i - period] as number
+    out[i] = i < period - 1 ? Number.NaN : acc / period
+  }
+  return out
+}

package/src/features/indicators/dpo.ts

@@ -0,0 +1,38 @@
+import { KLineChartError } from '../../errors'
+/**
+ * DPO — Detrended Price Oscillator.
+ *
+ *   shift = floor(period / 2) + 1
+ *   sma   = SMA(close, period)
+ *   DPO[i] = close[i - shift] - sma[i]
+ *
+ * The shift makes DPO a centred oscillator: the trend (SMA) is removed
+ * at a centred lag so the result is a cleaner cycle indicator.
+ *
+ * Output: `Float64Array` length === input. NaN until index >= period + shift.
+ */
+
+export interface DpoOptions {
+  period: number
+}
+
+export function computeDPO(prices: ReadonlyArray<number>, opts: DpoOptions): Float64Array {
+  const { period } = opts
+  if (period < 2 || !Number.isFinite(period))
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'computeDPO: period must be >= 2')
+  const n = prices.length
+  const out = new Float64Array(n)
+  out.fill(Number.NaN)
+  const shift = Math.floor(period / 2) + 1
+
+  let acc = 0
+  for (let i = 0; i < n; i++) {
+    acc += prices[i] as number
+    if (i >= period) acc -= prices[i - period] as number
+    if (i < period - 1) continue
+    const sma = acc / period
+    const back = i - shift
+    if (back >= 0) out[i] = (prices[back] as number) - sma
+  }
+  return out
+}

package/src/features/indicators/fisherTransform.ts

@@ -0,0 +1,66 @@
+import { KLineChartError } from '../../errors'
+/**
+ * Fisher Transform — John Ehlers (2002).
+ *
+ * Maps price into a near-Gaussian distribution to make turning points sharper:
+ *
+ *   med[i]   = (high[i] + low[i]) / 2
+ *   hi[i]    = max(med, period)
+ *   lo[i]    = min(med, period)
+ *   raw[i]   = 0.5 * 2 * ((med - lo) / (hi - lo) - 0.5)            (in [-1, 1))
+ *   v[i]     = clip(0.33 * raw + 0.67 * v[i-1], -0.999, 0.999)
+ *   fish[i]  = 0.5 * ln((1 + v) / (1 - v)) + 0.5 * fish[i-1]
+ *
+ * Output: `{ fisher, trigger }` parallel arrays. `trigger` is `fisher`
+ * shifted one bar (a common companion plot).
+ */
+
+export interface FisherTransformOptions {
+  period: number
+}
+
+export function computeFisherTransform(
+  bars: ReadonlyArray<{ high: number; low: number }>,
+  opts: FisherTransformOptions,
+): { fisher: Float64Array; trigger: Float64Array } {
+  const { period } = opts
+  if (period < 2 || !Number.isFinite(period)) {
+    throw new KLineChartError(
+      'INDICATOR_INVALID_PARAM',
+      'computeFisherTransform: period must be >= 2',
+    )
+  }
+  const n = bars.length
+  const fisher = new Float64Array(n)
+  const trigger = new Float64Array(n)
+  fisher.fill(Number.NaN)
+  trigger.fill(Number.NaN)
+
+  let v = 0
+  let f = 0
+
+  for (let i = 0; i < n; i++) {
+    if (i < period - 1) continue
+    let hi = -Infinity
+    let lo = Infinity
+    for (let j = i - period + 1; j <= i; j++) {
+      const b = bars[j] as { high: number; low: number }
+      const med = (b.high + b.low) / 2
+      if (med > hi) hi = med
+      if (med < lo) lo = med
+    }
+    const b = bars[i] as { high: number; low: number }
+    const medCur = (b.high + b.low) / 2
+    const denom = hi - lo
+    const norm = denom === 0 ? 0 : (medCur - lo) / denom // [0, 1]
+    const raw = 2 * (norm - 0.5) // [-1, 1]
+    v = 0.33 * raw + 0.67 * v
+    if (v > 0.999) v = 0.999
+    if (v < -0.999) v = -0.999
+    const fNew = 0.5 * Math.log((1 + v) / (1 - v)) + 0.5 * f
+    trigger[i] = f // previous fisher serves as trigger
+    f = fNew
+    fisher[i] = f
+  }
+  return { fisher, trigger }
+}

package/src/features/indicators/frama.ts

@@ -0,0 +1,94 @@
+import { KLineChartError } from '../../errors'
+/**
+ * FRAMA — Fractal Adaptive Moving Average (John Ehlers, 2005).
+ *
+ * Estimates the fractal dimension D of price over the last `period` bars
+ * (split into two halves) and uses it to adapt an EMA smoothing constant:
+ *
+ *   N1 = (max(H_first_half) - min(H_first_half)) / (period/2)
+ *   N2 = (max(H_second_half) - min(H_second_half)) / (period/2)
+ *   N3 = (max(H_full) - min(H_full)) / period
+ *   D  = (log(N1 + N2) - log(N3)) / log(2)
+ *   alpha = exp(-4.6 * (D - 1))
+ *   FRAMA = alpha * price + (1 - alpha) * FRAMA_prev
+ *
+ * Output length === input length. Indices < period are NaN.
+ *
+ * Note: Ehlers's original uses H (high) and L (low) separately for each
+ * range. With close-only input we use price extrema as a faithful
+ * close-input approximation — documented divergence vs the H/L variant.
+ */
+
+export interface FramaOptions {
+  /** Must be EVEN and >= 4. Default 16. */
+  period: number
+}
+
+function rangeMaxMin(
+  arr: ReadonlyArray<number>,
+  start: number,
+  end: number,
+): {
+  max: number
+  min: number
+} {
+  let max = -Infinity
+  let min = Infinity
+  for (let i = start; i < end; i++) {
+    const v = arr[i] as number
+    if (v > max) max = v
+    if (v < min) min = v
+  }
+  return { max, min }
+}
+
+export function computeFRAMA(prices: ReadonlyArray<number>, opts: FramaOptions): Float64Array {
+  const { period } = opts
+  if (period < 4 || period % 2 !== 0 || !Number.isFinite(period)) {
+    throw new KLineChartError(
+      'INDICATOR_INVALID_PARAM',
+      'computeFRAMA: period must be even and >= 4',
+    )
+  }
+
+  const n = prices.length
+  const out = new Float64Array(n)
+  const half = period >> 1
+  let prev = Number.NaN
+
+  for (let i = 0; i < n; i++) {
+    if (i < period - 1) {
+      out[i] = Number.NaN
+      continue
+    }
+    const fullStart = i - period + 1
+    const midStart = i - half + 1
+    const r1 = rangeMaxMin(prices, fullStart, fullStart + half)
+    const r2 = rangeMaxMin(prices, midStart, midStart + half)
+    const rF = rangeMaxMin(prices, fullStart, fullStart + period)
+    const N1 = (r1.max - r1.min) / half
+    const N2 = (r2.max - r2.min) / half
+    const N3 = (rF.max - rF.min) / period
+
+    let alpha: number
+    if (N1 <= 0 || N2 <= 0 || N3 <= 0) {
+      // Degenerate flat window — fall back to a simple EMA constant.
+      alpha = 2 / (period + 1)
+    } else {
+      const D = (Math.log(N1 + N2) - Math.log(N3)) / Math.LN2
+      alpha = Math.exp(-4.6 * (D - 1))
+      // Numerical safety: clamp to [0.01, 1].
+      if (!(alpha > 0)) alpha = 0.01
+      if (alpha > 1) alpha = 1
+    }
+
+    const cur = prices[i] as number
+    if (Number.isNaN(prev)) {
+      prev = cur
+    } else {
+      prev = alpha * cur + (1 - alpha) * prev
+    }
+    out[i] = prev
+  }
+  return out
+}

package/src/features/indicators/lsma.ts

@@ -0,0 +1,59 @@
+import { KLineChartError } from '../../errors'
+/**
+ * LSMA — Least-Squares (Linear Regression) Moving Average.
+ *
+ * At each index i (with at least `period` samples available), fit a
+ * line `y = a + b * x` over the last `period` prices via least squares,
+ * and emit the value of that line at the right endpoint (`y[period-1]`).
+ *
+ * Closed-form (mean-centred):
+ *   x̄ = (period - 1) / 2          (since x = 0..period-1)
+ *   ȳ = mean(prices over window)
+ *   b = sum((x - x̄) * (y - ȳ)) / sum((x - x̄)^2)
+ *   a = ȳ - b * x̄
+ *   lsma[i] = a + b * (period - 1)
+ *
+ * Output length === input length. Indices < period - 1 are NaN.
+ */
+
+export interface LsmaOptions {
+  period: number
+}
+
+export function computeLSMA(prices: ReadonlyArray<number>, opts: LsmaOptions): Float64Array {
+  const { period } = opts
+  if (period < 2 || !Number.isFinite(period))
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'computeLSMA: period must be >= 2')
+
+  const out = new Float64Array(prices.length)
+  const xbar = (period - 1) / 2
+  // sum((x - x̄)^2) for x = 0..period-1 is a constant; precompute.
+  let xxSum = 0
+  for (let k = 0; k < period; k++) {
+    const d = k - xbar
+    xxSum += d * d
+  }
+
+  for (let i = 0; i < prices.length; i++) {
+    if (i < period - 1) {
+      out[i] = Number.NaN
+      continue
+    }
+    // Window covers indices i - period + 1 .. i, mapped to x = 0..period-1.
+    let ysum = 0
+    for (let k = 0; k < period; k++) {
+      ysum += prices[i - period + 1 + k] as number
+    }
+    const ybar = ysum / period
+    let xy = 0
+    for (let k = 0; k < period; k++) {
+      const xd = k - xbar
+      const yd = (prices[i - period + 1 + k] as number) - ybar
+      xy += xd * yd
+    }
+    const b = xy / xxSum
+    const a = ybar - b * xbar
+    out[i] = a + b * (period - 1)
+  }
+  return out
+}