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

package/src/features/indicators/schaffTrendCycle.ts

@@ -0,0 +1,94 @@
+import { KLineChartError } from '../../errors'
+/**
+ * STC — Schaff Trend Cycle (Doug Schaff, 2008).
+ *
+ * Doubly-stochastic MACD-cycle hybrid:
+ *
+ *   macd      = EMA(close, fast) - EMA(close, slow)
+ *   k1        = stoch(macd, cycle)         (raw, 0..100)
+ *   d1        = EMA(k1, factor)            (smoothing)
+ *   k2        = stoch(d1, cycle)
+ *   STC       = EMA(k2, factor)
+ *
+ * Defaults: fast=23, slow=50, cycle=10, factor=0.5 (smoothing constant,
+ * applied as `d = factor*new + (1-factor)*d_prev`).
+ *
+ * Output: `Float64Array` length === input. NaN until index >= slow + 2*cycle.
+ */
+
+export interface SchaffTrendCycleOptions {
+  fast?: number
+  slow?: number
+  cycle?: number
+  factor?: number
+}
+
+export function computeSchaffTrendCycle(
+  prices: ReadonlyArray<number>,
+  opts: SchaffTrendCycleOptions = {},
+): Float64Array {
+  const fast = opts.fast ?? 23
+  const slow = opts.slow ?? 50
+  const cycle = opts.cycle ?? 10
+  const factor = opts.factor ?? 0.5
+  if (fast < 2 || slow <= fast)
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'STC: require 2 <= fast < slow')
+  if (cycle < 2) throw new KLineChartError('INDICATOR_INVALID_PARAM', 'STC: cycle must be >= 2')
+  if (!(factor > 0 && factor <= 1))
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'STC: factor must be in (0, 1]')
+
+  const n = prices.length
+  const macd = new Float64Array(n)
+  const kFast = 2 / (fast + 1)
+  const kSlow = 2 / (slow + 1)
+  let emaF = Number.NaN
+  let emaS = Number.NaN
+  for (let i = 0; i < n; i++) {
+    const p = prices[i] as number
+    emaF = Number.isNaN(emaF) ? p : kFast * p + (1 - kFast) * emaF
+    emaS = Number.isNaN(emaS) ? p : kSlow * p + (1 - kSlow) * emaS
+    macd[i] = emaF - emaS
+  }
+
+  const k1 = stochOver(macd, cycle)
+  const d1 = smoothFactor(k1, factor)
+  const k2 = stochOver(d1, cycle)
+  const stc = smoothFactor(k2, factor)
+  return stc
+}
+
+function stochOver(input: Float64Array, period: number): Float64Array {
+  const n = input.length
+  const out = new Float64Array(n)
+  out.fill(Number.NaN)
+  for (let i = period - 1; i < n; i++) {
+    let lo = Infinity
+    let hi = -Infinity
+    let any = false
+    for (let j = i - period + 1; j <= i; j++) {
+      const v = input[j] as number
+      if (Number.isNaN(v)) continue
+      any = true
+      if (v < lo) lo = v
+      if (v > hi) hi = v
+    }
+    if (!any) continue
+    const denom = hi - lo
+    out[i] = denom === 0 ? 50 : (100 * ((input[i] as number) - lo)) / denom
+  }
+  return out
+}
+
+function smoothFactor(input: Float64Array, factor: number): Float64Array {
+  const n = input.length
+  const out = new Float64Array(n)
+  out.fill(Number.NaN)
+  let prev = Number.NaN
+  for (let i = 0; i < n; i++) {
+    const v = input[i] as number
+    if (Number.isNaN(v)) continue
+    prev = Number.isNaN(prev) ? v : factor * v + (1 - factor) * prev
+    out[i] = prev
+  }
+  return out
+}

package/src/features/indicators/stochRSI.ts

@@ -0,0 +1,108 @@
+import { KLineChartError } from '../../errors'
+/**
+ * Stochastic RSI (Chande & Kroll, 1994).
+ *
+ * Two-step composition:
+ *   1. RSI(period) over close-only.
+ *   2. Stochastic over the RSI series:
+ *        k[i] = 100 * (RSI[i] - min(RSI, stochPeriod))
+ *                   / (max(RSI, stochPeriod) - min(RSI, stochPeriod))
+ *   3. Smooth k by SMA(smoothK) → %K; smooth %K by SMA(smoothD) → %D.
+ *
+ * Output: parallel `Float64Array` pair { k, d }, both length === input.
+ * NaN leading. Returns 0..100.
+ */
+
+export interface StochRsiOptions {
+  rsiPeriod: number
+  stochPeriod: number
+  smoothK?: number
+  smoothD?: number
+}
+
+export function computeStochRSI(
+  prices: ReadonlyArray<number>,
+  opts: StochRsiOptions,
+): { k: Float64Array; d: Float64Array } {
+  const { rsiPeriod, stochPeriod } = opts
+  const smoothK = opts.smoothK ?? 3
+  const smoothD = opts.smoothD ?? 3
+  if (rsiPeriod < 2 || stochPeriod < 2 || smoothK < 1 || smoothD < 1) {
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'computeStochRSI: invalid period args')
+  }
+
+  const n = prices.length
+  const rsi = computeRsiSeries(prices, rsiPeriod)
+
+  const rawK = new Float64Array(n)
+  rawK.fill(Number.NaN)
+  for (let i = rsiPeriod + stochPeriod - 1; i < n; i++) {
+    let lo = Infinity
+    let hi = -Infinity
+    for (let j = i - stochPeriod + 1; j <= i; j++) {
+      const v = rsi[j] as number
+      if (Number.isNaN(v)) continue
+      if (v < lo) lo = v
+      if (v > hi) hi = v
+    }
+    const denom = hi - lo
+    rawK[i] = denom === 0 ? 50 : (100 * ((rsi[i] as number) - lo)) / denom
+  }
+
+  const k = smaSeries(rawK, smoothK)
+  const d = smaSeries(k, smoothD)
+  return { k, d }
+}
+
+function computeRsiSeries(prices: ReadonlyArray<number>, period: number): Float64Array {
+  const n = prices.length
+  const out = new Float64Array(n)
+  out.fill(Number.NaN)
+  if (n < period + 1) return out
+
+  let gainSum = 0
+  let lossSum = 0
+  for (let i = 1; i <= period; i++) {
+    const diff = (prices[i] as number) - (prices[i - 1] as number)
+    if (diff > 0) gainSum += diff
+    else lossSum += -diff
+  }
+  let avgGain = gainSum / period
+  let avgLoss = lossSum / period
+  out[period] = avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss)
+
+  for (let i = period + 1; i < n; i++) {
+    const diff = (prices[i] as number) - (prices[i - 1] as number)
+    const g = diff > 0 ? diff : 0
+    const l = diff < 0 ? -diff : 0
+    avgGain = (avgGain * (period - 1) + g) / period
+    avgLoss = (avgLoss * (period - 1) + l) / period
+    out[i] = avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss)
+  }
+  return out
+}
+
+function smaSeries(input: Float64Array, period: number): Float64Array {
+  const n = input.length
+  const out = new Float64Array(n)
+  out.fill(Number.NaN)
+  let acc = 0
+  let count = 0
+  let start = 0
+  for (let i = 0; i < n; i++) {
+    const v = input[i] as number
+    if (!Number.isNaN(v)) {
+      acc += v
+      count++
+    }
+    if (count >= period) {
+      out[i] = acc / period
+      // Slide window: subtract the value leaving the window (period back).
+      const left = input[start + count - period] as number
+      if (!Number.isNaN(left)) acc -= left
+      else count-- // adjust if a NaN was at the left edge
+      start = i - period + 2
+    }
+  }
+  return out
+}

package/src/features/indicators/t3.ts

@@ -0,0 +1,95 @@
+import { KLineChartError } from '../../errors'
+/**
+ * T3 — Tim Tillson's smoothed-EMA cascade (1998).
+ *
+ * Public reference: T. Tillson, "Better Moving Averages",
+ * Technical Analysis of Stocks & Commodities, January 1998.
+ *
+ * Algorithm:
+ *   1. EMA1 = EMA(price, period)
+ *   2. EMA2 = EMA(EMA1,  period)
+ *   3. EMA3 = EMA(EMA2,  period)
+ *   4. EMA4 = EMA(EMA3,  period)
+ *   5. EMA5 = EMA(EMA4,  period)
+ *   6. EMA6 = EMA(EMA5,  period)
+ *   T3 = c1*EMA6 + c2*EMA5 + c3*EMA4 + c4*EMA3
+ *   where
+ *     a  = volume factor in [0, 1], default 0.7
+ *     c1 = -a^3
+ *     c2 =  3*a^2 + 3*a^3
+ *     c3 = -6*a^2 - 3*a - 3*a^3
+ *     c4 =  1 + 3*a + a^3 + 3*a^2
+ *
+ * Output length === input length. The first non-NaN value emerges once the
+ * EMA cascade has primed (we seed each EMA on its first input).
+ */
+
+export interface T3Options {
+  period: number
+  /** Volume factor in [0, 1]. Default 0.7. Lower = smoother. */
+  volumeFactor?: number
+}
+
+function emaSeries(input: Float64Array, period: number): Float64Array {
+  const out = new Float64Array(input.length)
+  const k = 2 / (period + 1)
+  let prev = Number.NaN
+  for (let i = 0; i < input.length; i++) {
+    const v = input[i] as number
+    if (Number.isNaN(v)) {
+      out[i] = Number.NaN
+      continue
+    }
+    if (Number.isNaN(prev)) {
+      prev = v
+    } else {
+      prev = k * v + (1 - k) * prev
+    }
+    out[i] = prev
+  }
+  return out
+}
+
+export function computeT3(prices: ReadonlyArray<number>, opts: T3Options): Float64Array {
+  const { period } = opts
+  const a = opts.volumeFactor ?? 0.7
+  if (period < 2 || !Number.isFinite(period))
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'computeT3: period must be >= 2')
+  if (a < 0 || a > 1 || !Number.isFinite(a)) {
+    throw new KLineChartError(
+      'INDICATOR_INVALID_PARAM',
+      'computeT3: volumeFactor must be in [0, 1]',
+    )
+  }
+
+  const src = new Float64Array(prices.length)
+  for (let i = 0; i < prices.length; i++) src[i] = prices[i] as number
+
+  const e1 = emaSeries(src, period)
+  const e2 = emaSeries(e1, period)
+  const e3 = emaSeries(e2, period)
+  const e4 = emaSeries(e3, period)
+  const e5 = emaSeries(e4, period)
+  const e6 = emaSeries(e5, period)
+
+  const a2 = a * a
+  const a3 = a2 * a
+  const c1 = -a3
+  const c2 = 3 * a2 + 3 * a3
+  const c3 = -6 * a2 - 3 * a - 3 * a3
+  const c4 = 1 + 3 * a + a3 + 3 * a2
+
+  const out = new Float64Array(prices.length)
+  for (let i = 0; i < prices.length; i++) {
+    const v6 = e6[i] as number
+    const v5 = e5[i] as number
+    const v4 = e4[i] as number
+    const v3 = e3[i] as number
+    if (Number.isNaN(v6) || Number.isNaN(v5) || Number.isNaN(v4) || Number.isNaN(v3)) {
+      out[i] = Number.NaN
+    } else {
+      out[i] = c1 * v6 + c2 * v5 + c3 * v4 + c4 * v3
+    }
+  }
+  return out
+}

package/src/features/indicators/ultimateOscillator.ts

@@ -0,0 +1,86 @@
+import { KLineChartError } from '../../errors'
+/**
+ * Ultimate Oscillator — Larry Williams (1976).
+ *
+ * Weighted multi-period buying-pressure / true-range oscillator.
+ *
+ *   prevClose[i] = close[i-1]
+ *   BP[i]        = close[i] - min(low[i], prevClose[i])
+ *   TR[i]        = max(high[i], prevClose[i]) - min(low[i], prevClose[i])
+ *   avg(N)       = sum(BP, N) / sum(TR, N)
+ *   UO[i]        = 100 * (4*avg(p1) + 2*avg(p2) + avg(p3)) / 7
+ *
+ * Defaults: p1=7, p2=14, p3=28.
+ *
+ * Output: `Float64Array` length === input. NaN until index >= max(p1,p2,p3).
+ */
+
+export interface UltimateOscillatorOptions {
+  p1?: number
+  p2?: number
+  p3?: number
+}
+
+export function computeUltimateOscillator(
+  bars: ReadonlyArray<{ high: number; low: number; close: number }>,
+  opts: UltimateOscillatorOptions = {},
+): Float64Array {
+  const p1 = opts.p1 ?? 7
+  const p2 = opts.p2 ?? 14
+  const p3 = opts.p3 ?? 28
+  if (p1 < 1 || p2 < 1 || p3 < 1) {
+    throw new KLineChartError(
+      'INDICATOR_INVALID_PARAM',
+      'computeUltimateOscillator: all periods must be >= 1',
+    )
+  }
+  const n = bars.length
+  const bp = new Float64Array(n)
+  const tr = new Float64Array(n)
+  for (let i = 0; i < n; i++) {
+    const b = bars[i] as { high: number; low: number; close: number }
+    if (i === 0) {
+      bp[i] = 0
+      tr[i] = b.high - b.low
+      continue
+    }
+    const pc = (bars[i - 1] as { close: number }).close
+    const minLow = Math.min(b.low, pc)
+    bp[i] = b.close - minLow
+    tr[i] = Math.max(b.high, pc) - minLow
+  }
+  const r1 = rollingRatio(bp, tr, p1)
+  const r2 = rollingRatio(bp, tr, p2)
+  const r3 = rollingRatio(bp, tr, p3)
+  const out = new Float64Array(n)
+  const maxP = Math.max(p1, p2, p3)
+  for (let i = 0; i < n; i++) {
+    if (i < maxP) {
+      out[i] = Number.NaN
+      continue
+    }
+    out[i] = (100 * (4 * (r1[i] as number) + 2 * (r2[i] as number) + (r3[i] as number))) / 7
+  }
+  return out
+}
+
+function rollingRatio(num: Float64Array, den: Float64Array, period: number): Float64Array {
+  const n = num.length
+  const out = new Float64Array(n)
+  let sNum = 0
+  let sDen = 0
+  for (let i = 0; i < n; i++) {
+    sNum += num[i] as number
+    sDen += den[i] as number
+    if (i >= period) {
+      sNum -= num[i - period] as number
+      sDen -= den[i - period] as number
+    }
+    if (i < period - 1 || sDen === 0) {
+      out[i] = Number.NaN
+    } else {
+      out[i] = sNum / sDen
+    }
+  }
+  return out
+}

package/src/features/indicators/vidya.ts

@@ -0,0 +1,81 @@
+import { KLineChartError } from '../../errors'
+/**
+ * VIDYA — Variable Index Dynamic Average (Tushar Chande).
+ *
+ * CMO-adapted EMA: the smoothing constant is scaled by the absolute value
+ * of the Chande Momentum Oscillator, so VIDYA accelerates in trending
+ * markets and slows in chop.
+ *
+ *   gain[i] = max(price[i] - price[i-1], 0)
+ *   loss[i] = max(price[i-1] - price[i], 0)
+ *   CMO(t)  = 100 * (sum(gain, t-cmoPeriod+1..t) - sum(loss, ...))
+ *                  / (sum(gain) + sum(loss))           (NaN-guarded)
+ *   alpha   = (2 / (period + 1)) * |CMO(t) / 100|
+ *   VIDYA[i] = alpha * price[i] + (1 - alpha) * VIDYA[i-1]
+ *
+ * Output length === input length. Indices < cmoPeriod are NaN. VIDYA seeds
+ * on the first valid CMO sample.
+ */
+
+export interface VidyaOptions {
+  period: number
+  /** Window for the CMO numerator/denominator. Default 9. */
+  cmoPeriod?: number
+}
+
+export function computeVIDYA(prices: ReadonlyArray<number>, opts: VidyaOptions): Float64Array {
+  const { period } = opts
+  const cmoPeriod = opts.cmoPeriod ?? 9
+  if (period < 2 || !Number.isFinite(period))
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'computeVIDYA: period must be >= 2')
+  if (cmoPeriod < 1 || !Number.isFinite(cmoPeriod)) {
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'computeVIDYA: cmoPeriod must be >= 1')
+  }
+
+  const n = prices.length
+  const out = new Float64Array(n)
+  const baseAlpha = 2 / (period + 1)
+
+  // Rolling sums of gain / loss across the cmoPeriod window of diffs.
+  let gainSum = 0
+  let lossSum = 0
+  let prev = Number.NaN
+
+  for (let i = 0; i < n; i++) {
+    if (i === 0) {
+      out[i] = Number.NaN
+      continue
+    }
+    const cur = prices[i] as number
+    const previous = prices[i - 1] as number
+    const diff = cur - previous
+    const gain = diff > 0 ? diff : 0
+    const loss = diff < 0 ? -diff : 0
+    gainSum += gain
+    lossSum += loss
+
+    // Drop the diff that just slid out of the window.
+    if (i > cmoPeriod) {
+      const drop = (prices[i - cmoPeriod] as number) - (prices[i - cmoPeriod - 1] as number)
+      if (drop > 0) gainSum -= drop
+      else if (drop < 0) lossSum += drop // (-drop is the abs)
+    }
+
+    if (i < cmoPeriod) {
+      out[i] = Number.NaN
+      continue
+    }
+
+    const denom = gainSum + lossSum
+    const cmoAbs = denom === 0 ? 0 : Math.abs((gainSum - lossSum) / denom)
+    const alpha = baseAlpha * cmoAbs
+
+    if (Number.isNaN(prev)) {
+      prev = cur
+    } else {
+      prev = alpha * cur + (1 - alpha) * prev
+    }
+    out[i] = prev
+  }
+  return out
+}

package/src/features/indicators/zlema.ts

@@ -0,0 +1,42 @@
+import { KLineChartError } from '../../errors'
+/**
+ * ZLEMA — Zero-Lag Exponential Moving Average (Ehlers).
+ *
+ * Removes EMA lag by feeding the EMA a "momentum-adjusted" series:
+ *   lag = floor((period - 1) / 2)
+ *   adj[i] = price[i] + (price[i] - price[i - lag])
+ *   zlema  = EMA(adj, period)
+ *
+ * Output length === input length. Indices < lag are NaN (no adjustment
+ * available); the EMA seeds on the first valid sample.
+ */
+
+export interface ZlemaOptions {
+  period: number
+}
+
+export function computeZLEMA(prices: ReadonlyArray<number>, opts: ZlemaOptions): Float64Array {
+  const { period } = opts
+  if (period < 2 || !Number.isFinite(period))
+    throw new KLineChartError('INDICATOR_INVALID_PARAM', 'computeZLEMA: period must be >= 2')
+
+  const out = new Float64Array(prices.length)
+  const lag = Math.floor((period - 1) / 2)
+  const k = 2 / (period + 1)
+
+  let ema = Number.NaN
+  for (let i = 0; i < prices.length; i++) {
+    if (i < lag) {
+      out[i] = Number.NaN
+      continue
+    }
+    const adj = 2 * (prices[i] as number) - (prices[i - lag] as number)
+    if (Number.isNaN(ema)) {
+      ema = adj
+    } else {
+      ema = k * adj + (1 - k) * ema
+    }
+    out[i] = ema
+  }
+  return out
+}