@svgrid/grid 3.0.2 → 3.0.4

package/src/chart-stats.ts

@@ -0,0 +1,409 @@
+/**
+ * Statistics the chart engine computes from raw values: five-number summaries,
+ * regression and moving-average overlays. DOM-free, spec-free.
+ */
+import type { BoxStats, ChartReducer } from './chart-types'
+
+// The two trend primitives live in their own leaf (see chart-trend.ts for
+// why) and are re-exported here so every importer of chart-stats keeps working.
+export { linearTrend, pearson } from './chart-trend'
+
+/**
+ * Five-number summary of a raw sample, with the 1.5 IQR whisker rule.
+ *
+ * Whiskers stop at the last observation INSIDE the fence rather than at the
+ * fence itself, which is what makes them read as real data; anything past them
+ * comes back in `outliers`. Quartiles use linear interpolation between the two
+ * neighbouring order statistics.
+ *
+ * Returns `null` for an empty sample, so a category with no observations is a
+ * gap rather than a box drawn at zero.
+ */
+export function boxStats(sample: ReadonlyArray<number>, whisker = 1.5): BoxStats | null {
+  const v = sample.filter((n) => Number.isFinite(n)).slice().sort((a, b) => a - b)
+  if (!v.length) return null
+  const q = (p: number) => {
+    const pos = (v.length - 1) * p
+    const lo = Math.floor(pos)
+    const hi = Math.ceil(pos)
+    return lo === hi ? v[lo]! : v[lo]! + (v[hi]! - v[lo]!) * (pos - lo)
+  }
+  const q1 = q(0.25)
+  const median = q(0.5)
+  const q3 = q(0.75)
+  const fenceLo = q1 - whisker * (q3 - q1)
+  const fenceHi = q3 + whisker * (q3 - q1)
+  const inside = v.filter((n) => n >= fenceLo && n <= fenceHi)
+  const outliers = v.filter((n) => n < fenceLo || n > fenceHi)
+  return {
+    // `inside` can only be empty if every point is an outlier, which the fence
+    // rule makes impossible (q1 and q3 are always within it) - but a degenerate
+    // sample should still produce a box rather than `undefined` coordinates.
+    min: inside.length ? inside[0]! : v[0]!,
+    q1,
+    median,
+    q3,
+    max: inside.length ? inside[inside.length - 1]! : v[v.length - 1]!,
+    ...(outliers.length ? { outliers } : {}),
+  }
+}
+
+/**
+ * A regression's result: the fitted value at every index (NaN where the
+ * source was non-finite or the model cannot take the value), R-squared
+ * against the finite source values, the equation, and `predict`, the model
+ * at any x. With no `xs` the x of a value is its index, which is what a
+ * category chart's overlay wants; a scatter passes its points' x values, so
+ * the fit is y on x and `predict` draws the curve across the plot.
+ */
+export type RegressionFit = { fitted: number[]; r2: number; equation: string; predict: (x: number) => number }
+
+const NO_FIT = (values: ReadonlyArray<number>): RegressionFit => ({ fitted: values.map(() => NaN), r2: 0, equation: '', predict: () => NaN })
+/** The x of each value: the caller's, else the index. */
+const xsOf = (values: ReadonlyArray<number>, xs?: ReadonlyArray<number>): number[] => (xs ? values.map((_, i) => xs[i] ?? NaN) : values.map((_, i) => i))
+
+/** R-squared of a fit: 1 minus residual over total variance across the
+ *  indices where both the value and the fit are finite. 0 when there is no
+ *  variance to explain. */
+export function rSquared(values: ReadonlyArray<number>, fitted: ReadonlyArray<number>): number {
+  let n = 0
+  let mean = 0
+  for (let i = 0; i < values.length; i += 1) {
+    if (Number.isFinite(values[i]) && Number.isFinite(fitted[i])) { n += 1; mean += values[i]! }
+  }
+  if (n < 2) return 0
+  mean /= n
+  let ssRes = 0
+  let ssTot = 0
+  for (let i = 0; i < values.length; i += 1) {
+    if (!Number.isFinite(values[i]) || !Number.isFinite(fitted[i])) continue
+    ssRes += (values[i]! - fitted[i]!) ** 2
+    ssTot += (values[i]! - mean) ** 2
+  }
+  if (ssTot === 0) return ssRes === 0 ? 1 : 0
+  return Math.max(0, Math.min(1, 1 - ssRes / ssTot))
+}
+
+const fmtCoef = (c: number) => (Math.abs(c) >= 1000 || (Math.abs(c) < 0.001 && c !== 0) ? c.toExponential(2) : String(Math.round(c * 1000) / 1000))
+
+/** Solve a small linear system by Gaussian elimination with partial pivoting;
+ *  null when singular. */
+function solve(a: number[][], b: number[]): number[] | null {
+  const n = b.length
+  const m = a.map((row, i) => [...row, b[i]!])
+  for (let c = 0; c < n; c += 1) {
+    let p = c
+    for (let r = c + 1; r < n; r += 1) if (Math.abs(m[r]![c]!) > Math.abs(m[p]![c]!)) p = r
+    if (Math.abs(m[p]![c]!) < 1e-12) return null
+    ;[m[c], m[p]] = [m[p]!, m[c]!]
+    for (let r = 0; r < n; r += 1) {
+      if (r === c) continue
+      const f = m[r]![c]! / m[c]![c]!
+      for (let k = c; k <= n; k += 1) m[r]![k]! -= f * m[c]![k]!
+    }
+  }
+  return m.map((row, i) => row[n]! / row[i]!)
+}
+
+/**
+ * Least-squares polynomial of `degree` (clamped to 1..6) through
+ * (x, values[i]), x the index or the caller's `xs`. The x values are
+ * normalised to [-1, 1] before the normal equations are solved, so a
+ * degree-6 fit over a thousand points does not lose the low coefficients to
+ * rounding. Non-finite values are skipped and fitted as NaN.
+ */
+export function polynomialFit(values: ReadonlyArray<number>, degree: number, xs?: ReadonlyArray<number>): RegressionFit {
+  const d = Math.max(1, Math.min(6, Math.round(degree)))
+  const n = values.length
+  const nan = NO_FIT(values)
+  const X = xsOf(values, xs)
+  const idx: number[] = []
+  for (let i = 0; i < n; i += 1) if (Number.isFinite(values[i]) && Number.isFinite(X[i])) idx.push(i)
+  if (idx.length <= d) return nan
+  let lo = Infinity
+  let hi = -Infinity
+  for (const i of idx) { lo = Math.min(lo, X[i]!); hi = Math.max(hi, X[i]!) }
+  if (!xs) { lo = 0; hi = Math.max(1, n - 1) }
+  const scale = Math.max(hi - lo, 1e-12)
+  const nx = (x: number) => (2 * (x - lo)) / scale - 1
+  // Normal equations: sum x^(j+k) c_k = sum x^j y.
+  const a: number[][] = Array.from({ length: d + 1 }, () => new Array(d + 1).fill(0))
+  const b: number[] = new Array(d + 1).fill(0)
+  for (const i of idx) {
+    const x = nx(X[i]!)
+    const y = values[i]!
+    const pow: number[] = [1]
+    for (let k = 1; k <= 2 * d; k += 1) pow.push(pow[k - 1]! * x)
+    for (let j = 0; j <= d; j += 1) {
+      b[j]! += pow[j]! * y
+      for (let k = 0; k <= d; k += 1) a[j]![k]! += pow[j + k]!
+    }
+  }
+  const c = solve(a, b)
+  if (!c) return nan
+  const predict = (x: number) => {
+    const u = nx(x)
+    let y = 0
+    let p = 1
+    for (let k = 0; k <= d; k += 1) { y += c[k]! * p; p *= u }
+    return y
+  }
+  const fitted = values.map((v, i) => (Number.isFinite(v) && Number.isFinite(X[i]) ? predict(X[i]!) : NaN))
+  const terms = c.map((ck, k) => (k === 0 ? fmtCoef(ck) : `${fmtCoef(ck)} u^${k}`)).reverse()
+  const u = xs ? `u = 2(x - ${fmtCoef(lo)})/${fmtCoef(scale)} - 1` : `u = 2x/${scale} - 1`
+  return { fitted, r2: rSquared(values, fitted), equation: `y = ${terms.join(' + ')} (${u})`, predict }
+}
+
+/** Ordinary least squares of values on their index, or on `xs`, as a {@link RegressionFit}. */
+export function linearFit(values: ReadonlyArray<number>, xs?: ReadonlyArray<number>): RegressionFit {
+  const X = xsOf(values, xs)
+  const { slope, intercept, ok } = lineThrough(X, values)
+  if (!ok) return NO_FIT(values)
+  const predict = (x: number) => slope * x + intercept
+  const fitted = values.map((v, i) => (Number.isFinite(v) && Number.isFinite(X[i]) ? predict(X[i]!) : NaN))
+  return { fitted, r2: rSquared(values, fitted), equation: `y = ${fmtCoef(slope)} x + ${fmtCoef(intercept)}`, predict }
+}
+
+/** Fit y = a * e^(b x) by least squares on ln y, x the index or `xs`;
+ *  values at or below zero cannot be logged and are skipped (fitted as NaN). */
+export function exponentialFit(values: ReadonlyArray<number>, xs?: ReadonlyArray<number>): RegressionFit {
+  const X = xsOf(values, xs)
+  const logs = values.map((v) => (Number.isFinite(v) && v > 0 ? Math.log(v) : NaN))
+  const { slope: b, intercept, ok } = lineThrough(X, logs)
+  if (!ok) return NO_FIT(values)
+  const a = Math.exp(intercept)
+  const predict = (x: number) => a * Math.exp(b * x)
+  const fitted = values.map((v, i) => (Number.isFinite(v) && v > 0 && Number.isFinite(X[i]) ? predict(X[i]!) : NaN))
+  return { fitted, r2: rSquared(values, fitted), equation: `y = ${fmtCoef(a)} e^(${fmtCoef(b)} x)`, predict }
+}
+
+/** Fit y = a + b ln(x + 1) by least squares (x the index, shifted by one so
+ *  the first point has a logarithm), or y = a + b ln(x) on `xs`, where
+ *  points with x at or below zero are skipped. */
+export function logarithmicFit(values: ReadonlyArray<number>, xs?: ReadonlyArray<number>): RegressionFit {
+  const shift = xs ? 0 : 1
+  const lx = xsOf(values, xs).map((x) => (x + shift > 0 ? Math.log(x + shift) : NaN))
+  const { slope, intercept, ok } = lineThrough(lx, values)
+  if (!ok) return NO_FIT(values)
+  const predict = (x: number) => (x + shift > 0 ? intercept + slope * Math.log(x + shift) : NaN)
+  const fitted = values.map((v, i) => (Number.isFinite(v) && Number.isFinite(lx[i]) ? intercept + slope * lx[i]! : NaN))
+  const arg = xs ? 'x' : 'x + 1'
+  return { fitted, r2: rSquared(values, fitted), equation: `y = ${fmtCoef(intercept)} + ${fmtCoef(slope)} ln(${arg})`, predict }
+}
+
+/** Fit y = a (x + 1)^b by least squares on ln y against ln(x + 1), or
+ *  y = a x^b on `xs`; values (and x on `xs`) at or below zero are skipped
+ *  (fitted as NaN). */
+export function powerFit(values: ReadonlyArray<number>, xs?: ReadonlyArray<number>): RegressionFit {
+  const shift = xs ? 0 : 1
+  const lx = xsOf(values, xs).map((x) => (x + shift > 0 ? Math.log(x + shift) : NaN))
+  const logs = values.map((v) => (Number.isFinite(v) && v > 0 ? Math.log(v) : NaN))
+  const { slope, intercept, ok } = lineThrough(lx, logs)
+  if (!ok) return NO_FIT(values)
+  const a = Math.exp(intercept)
+  const predict = (x: number) => (x + shift > 0 ? a * Math.pow(x + shift, slope) : NaN)
+  const fitted = values.map((v, i) => (Number.isFinite(v) && v > 0 && Number.isFinite(lx[i]) ? a * Math.exp(slope * lx[i]!) : NaN))
+  const arg = xs ? 'x' : '(x + 1)'
+  return { fitted, r2: rSquared(values, fitted), equation: `y = ${fmtCoef(a)} ${arg}^${fmtCoef(slope)}`, predict }
+}
+
+/** Least squares of y on arbitrary x, skipping non-finite pairs. */
+function lineThrough(xs: ReadonlyArray<number>, ys: ReadonlyArray<number>): { slope: number; intercept: number; ok: boolean } {
+  let n = 0, sx = 0, sy = 0, sxx = 0, sxy = 0
+  for (let i = 0; i < ys.length; i += 1) {
+    const x = xs[i]!
+    const y = ys[i]!
+    if (!Number.isFinite(x) || !Number.isFinite(y)) continue
+    n += 1; sx += x; sy += y; sxx += x * x; sxy += x * y
+  }
+  if (n < 2) return { slope: 0, intercept: 0, ok: false }
+  const denom = n * sxx - sx * sx
+  const slope = denom === 0 ? 0 : (n * sxy - sx * sy) / denom
+  return { slope, intercept: (sy - slope * sx) / n, ok: true }
+}
+
+/** Simple moving average over a window of `period` values. Window centres
+ *  trail to the right (typical for time-series). NaN for points before the
+ *  window is full. */
+export function simpleMovingAverage(values: number[], period: number): number[] {
+  if (period < 1) return values.slice()
+  const out: number[] = new Array(values.length).fill(NaN)
+  let sum = 0, count = 0
+  for (let i = 0; i < values.length; i += 1) {
+    const v = values[i]!
+    if (Number.isFinite(v)) { sum += v; count += 1 }
+    if (i >= period) {
+      const drop = values[i - period]!
+      if (Number.isFinite(drop)) { sum -= drop; count -= 1 }
+    }
+    if (i >= period - 1 && count > 0) out[i] = sum / count
+  }
+  return out
+}
+
+/** Exponential moving average. Smoothing factor alpha = 2 / (period + 1). */
+export function exponentialMovingAverage(values: number[], period: number): number[] {
+  const alpha = 2 / (Math.max(1, period) + 1)
+  const out: number[] = new Array(values.length).fill(NaN)
+  let prev: number | null = null
+  for (let i = 0; i < values.length; i += 1) {
+    const v = values[i]!
+    if (!Number.isFinite(v)) { out[i] = prev ?? NaN; continue }
+    prev = prev == null ? v : alpha * v + (1 - alpha) * prev
+    out[i] = prev
+  }
+  return out
+}
+
+
+/** The reducers that need every observation, not a running sum and count. */
+export function reducerNeedsSamples(reducer: ChartReducer): boolean {
+  return !(reducer === 'sum' || reducer === 'avg' || reducer === 'count')
+}
+
+/**
+ * Collapse a group's observations to one number. `sum` / `avg` / `count` are
+ * what `rowsToChartSpec` always did; the rest are the ones a pivot table
+ * offers and a chart panel was missing: `min`, `max`, `median`, `first`,
+ * `last`, `countDistinct`, and `pN` for the Nth percentile (`'p90'`). An
+ * empty group reduces to 0 for `sum` / `count` and to NaN otherwise, so a
+ * missing bucket draws as a gap rather than as a fake zero.
+ */
+export function reduceValues(samples: ReadonlyArray<number>, reducer: ChartReducer): number {
+  const n = samples.length
+  switch (reducer) {
+    case 'count':
+      return n
+    case 'sum': {
+      let s = 0
+      for (const v of samples) s += v
+      return s
+    }
+    case 'avg': {
+      if (!n) return 0
+      let s = 0
+      for (const v of samples) s += v
+      return s / n
+    }
+    case 'min':
+      return n ? Math.min(...samples) : Number.NaN
+    case 'max':
+      return n ? Math.max(...samples) : Number.NaN
+    case 'first':
+      return n ? samples[0]! : Number.NaN
+    case 'last':
+      return n ? samples[n - 1]! : Number.NaN
+    case 'countDistinct':
+      return new Set(samples).size
+    case 'median':
+      return percentile(samples, 50)
+    default: {
+      const m = /^p(\d+(?:\.\d+)?)$/.exec(reducer)
+      return m ? percentile(samples, Number(m[1])) : Number.NaN
+    }
+  }
+}
+
+/** The p-th percentile (0..100) by linear interpolation between order statistics. */
+export function percentile(samples: ReadonlyArray<number>, p: number): number {
+  const v = samples.filter((n) => Number.isFinite(n)).slice().sort((a, b) => a - b)
+  if (!v.length) return Number.NaN
+  const pos = (v.length - 1) * Math.max(0, Math.min(100, p)) / 100
+  const lo = Math.floor(pos)
+  const hi = Math.ceil(pos)
+  return lo === hi ? v[lo]! : v[lo]! + (v[hi]! - v[lo]!) * (pos - lo)
+}
+
+/** How `rowsToChartSpec` groups dates when `bucket` is set. */
+export type ChartTimeBucket = 'day' | 'week' | 'month' | 'quarter' | 'year'
+
+/**
+ * The ISO date (`YYYY-MM-DD`, UTC) that starts the bucket containing `date`:
+ * the day itself, the Monday of its week, the first of its month, quarter or
+ * year. Returns `''` for a value that is not a date, so the caller can drop
+ * the row rather than file it under 1970.
+ */
+export function bucketStart(date: string | number | Date, bucket: ChartTimeBucket): string {
+  const t = date instanceof Date ? date.getTime() : typeof date === 'number' ? date : Date.parse(date)
+  if (!Number.isFinite(t)) return ''
+  const d = new Date(t)
+  const y = d.getUTCFullYear()
+  const m = d.getUTCMonth()
+  let out: Date
+  switch (bucket) {
+    case 'day':
+      out = new Date(Date.UTC(y, m, d.getUTCDate()))
+      break
+    case 'week': {
+      // Monday-based, which is what a business calendar reads.
+      const day = (d.getUTCDay() + 6) % 7
+      out = new Date(Date.UTC(y, m, d.getUTCDate() - day))
+      break
+    }
+    case 'month':
+      out = new Date(Date.UTC(y, m, 1))
+      break
+    case 'quarter':
+      out = new Date(Date.UTC(y, m - (m % 3), 1))
+      break
+    default:
+      out = new Date(Date.UTC(y, 0, 1))
+  }
+  return out.toISOString().slice(0, 10)
+}
+
+/** What {@link binValues} returns: one category per bin plus the edges. */
+export type ChartBins = {
+  /** Bin midpoints as strings, ready to be the categories of a numeric axis. */
+  categories: string[]
+  /** Observations per bin. */
+  counts: number[]
+  /** Bin edges, one more than there are bins. */
+  edges: number[]
+  /** Width of every bin. */
+  width: number
+}
+
+/**
+ * Bin a raw sample for a histogram. The bin count comes from `bins`, from a
+ * `binWidth`, or from a rule: `'sturges'` (default, log2 n + 1), `'fd'`
+ * (Freedman-Diaconis, 2 IQR / cbrt n) or `'sqrt'`. The range is the data's
+ * extent unless `min` / `max` pin it; the top edge is inclusive. Edges are
+ * rounded to a sensible precision for the width, so labels read as `10, 20,
+ * 30` rather than `10.000000001`.
+ */
+export function binValues(
+  values: ReadonlyArray<number>,
+  opts: { bins?: number; binWidth?: number; method?: 'sturges' | 'fd' | 'sqrt'; min?: number; max?: number } = {},
+): ChartBins {
+  const v = values.filter((n) => Number.isFinite(n))
+  if (!v.length) return { categories: [], counts: [], edges: [], width: 0 }
+  const lo = opts.min ?? Math.min(...v)
+  let hi = opts.max ?? Math.max(...v)
+  if (hi <= lo) hi = lo + 1
+  let count: number
+  if (opts.bins && opts.bins > 0) count = Math.round(opts.bins)
+  else if (opts.binWidth && opts.binWidth > 0) count = Math.max(1, Math.ceil((hi - lo) / opts.binWidth))
+  else if (opts.method === 'sqrt') count = Math.ceil(Math.sqrt(v.length))
+  else if (opts.method === 'fd') {
+    const iqr = percentile(v, 75) - percentile(v, 25)
+    const w = iqr > 0 ? (2 * iqr) / Math.cbrt(v.length) : 0
+    count = w > 0 ? Math.ceil((hi - lo) / w) : Math.ceil(Math.log2(v.length) + 1)
+  } else count = Math.ceil(Math.log2(v.length) + 1)
+  count = Math.max(1, Math.min(1000, count))
+  const width = opts.binWidth && opts.binWidth > 0 ? opts.binWidth : (hi - lo) / count
+  // Precision from the width: a 0.25 width keeps two decimals, a 10 width none.
+  const decimals = width >= 1 ? 0 : Math.min(6, Math.ceil(-Math.log10(width)) + 1)
+  const fix = (n: number) => Number(n.toFixed(decimals))
+  const edges: number[] = []
+  for (let i = 0; i <= count; i += 1) edges.push(fix(lo + i * width))
+  const counts = new Array<number>(count).fill(0)
+  for (const n of v) {
+    let i = Math.floor((n - lo) / width)
+    if (i >= count) i = count - 1
+    if (i < 0) i = 0
+    counts[i] = (counts[i] ?? 0) + 1
+  }
+  const categories = counts.map((_, i) => String(fix(lo + (i + 0.5) * width)))
+  return { categories, counts, edges, width }
+}

package/src/chart-stream.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest'
+import { appendPoints } from './chart-stream'
+import { PER_CATEGORY_SERIES_KEYS } from './chart-decimate'
+import type { ChartSpec } from './chart-types'
+
+const base = (): ChartSpec => ({
+  type: 'line',
+  categories: ['t1', 't2'],
+  series: [
+    { label: 'a', values: [1, 2] },
+    { label: 'b', values: [10, 20] },
+  ],
+})
+
+describe('appendPoints', () => {
+  it('appends one category and one value per series, by index or by label', () => {
+    const next = appendPoints(base(), { category: 't3', values: [3, 30] })
+    expect(next.categories).toEqual(['t1', 't2', 't3'])
+    expect(next.series.map((s) => s.values)).toEqual([[1, 2, 3], [10, 20, 30]])
+    const byLabel = appendPoints(base(), { category: 't3', values: { b: 33 } })
+    expect(byLabel.series[0]!.values[2]).toBeNaN()
+    expect(byLabel.series[1]!.values[2]).toBe(33)
+    const many = appendPoints(base(), [{ category: 't3', values: [3, 30] }, { category: 't4', values: [4, 40] }])
+    expect(many.categories).toHaveLength(4)
+    expect(many.series[1]!.values).toEqual([10, 20, 30, 40])
+  })
+
+  it('keeps every per-category array parallel: bands, row ids, candles, volumes, errors, colours', () => {
+    const spec: ChartSpec = {
+      type: 'candlestick',
+      categories: ['d1'],
+      series: [
+        { label: 'px', values: [10], ohlc: [{ o: 9, h: 11, l: 8, c: 10 }], volumes: [100], rowIds: [[1]], colors: ['#f00'], errors: [1], upperValues: [11], lowerValues: [9] },
+        { label: 'sig', values: [5] },
+      ],
+      waterfallTotals: [false],
+    }
+    const next = appendPoints(spec, { category: 'd2', values: [12, 6], ohlc: { o: 10, h: 13, l: 10, c: 12 }, volume: 120, rowIds: [[2], [9]], upper: [13], lower: [11] })
+    const px = next.series[0]!
+    for (const key of PER_CATEGORY_SERIES_KEYS) {
+      const arr = px[key] as unknown[] | undefined
+      if (arr) expect(arr.length, key).toBe(2)
+    }
+    expect(px.ohlc![1]).toEqual({ o: 10, h: 13, l: 10, c: 12 })
+    expect(px.volumes).toEqual([100, 120])
+    expect(px.rowIds).toEqual([[1], [2]])
+    expect(px.upperValues).toEqual([11, 13])
+    expect(px.lowerValues).toEqual([9, 11])
+    // Not given for this point: a gap, not a shorter array.
+    expect(px.colors).toEqual(['#f00', null])
+    expect(px.errors![1]).toBeNull()
+    // A series without row ids grows them only because the point brings one.
+    expect(next.series[1]!.rowIds).toEqual([[], [9]])
+    expect(next.series[1]!.ohlc).toBeUndefined()
+    expect(next.waterfallTotals).toEqual([false, false])
+  })
+
+  it('trims to the window from the right and leaves a short spec alone', () => {
+    const s = appendPoints(base(), [{ category: 't3', values: [3, 30] }, { category: 't4', values: [4, 40] }], { window: 3 })
+    expect(s.categories).toEqual(['t2', 't3', 't4'])
+    expect(s.series[0]!.values).toEqual([2, 3, 4])
+    const short = appendPoints(base(), { category: 't3', values: [3, 30] }, { window: 10 })
+    expect(short.categories).toHaveLength(3)
+    expect(appendPoints(base(), [], { window: 1 }).categories).toEqual(['t2'])
+  })
+
+  it('does not mutate the input spec or its arrays', () => {
+    const spec = base()
+    const before = JSON.stringify(spec)
+    const next = appendPoints(spec, { category: 't3', values: [3, 30] }, { window: 2 })
+    expect(JSON.stringify(spec)).toBe(before)
+    expect(next.series[0]!.values).not.toBe(spec.series[0]!.values)
+    expect(next.categories).not.toBe(spec.categories)
+  })
+})

package/src/chart-stream.ts

@@ -0,0 +1,114 @@
+/**
+ * Live data. A feed hands a chart one new point every few hundred
+ * milliseconds; the spec is immutable state, so each tick wants a new spec
+ * with the point appended and the oldest dropped, with every per-category
+ * array kept in step. Demo 159 rebuilt the whole spec from a rows array on
+ * every tick; `appendPoints` does the append in one call and keeps the
+ * confidence bands, row ids, candles and volumes parallel by construction,
+ * because it walks the same key list the zoom window and decimation use.
+ */
+import type { ChartSpec, ChartSeries, OhlcBar } from './chart-types'
+import { PER_CATEGORY_SERIES_KEYS, PER_CATEGORY_SPEC_KEYS, pickCategories } from './chart-decimate'
+
+/** One new category with its values, for {@link appendPoints}. */
+export type ChartPoint = {
+  /** The category label (a date string on a time axis). */
+  category: string
+  /** One value per series in spec order, or values keyed by series label;
+   *  a series not named gets a gap (NaN). */
+  values: ReadonlyArray<number> | Record<string, number>
+  /** The bar for a candlestick series (the first series with `ohlc`). */
+  ohlc?: OhlcBar | null
+  /** The volume for that series. */
+  volume?: number
+  /** Row ids behind the point, one array per series in spec order. */
+  rowIds?: ReadonlyArray<ReadonlyArray<string | number>>
+  /** Confidence band ends, one per series in spec order. */
+  upper?: ReadonlyArray<number>
+  lower?: ReadonlyArray<number>
+  /** Range low / bullet target, one per series in spec order. */
+  low?: ReadonlyArray<number>
+  target?: ReadonlyArray<number>
+}
+
+/** What {@link appendPoints} takes besides the points. */
+export type AppendPointsOptions = {
+  /** Keep only the last `window` categories after appending. */
+  window?: number
+}
+
+/** The gap value each per-category array takes when a point does not set it. */
+function gapFor(key: (typeof PER_CATEGORY_SERIES_KEYS)[number]): unknown {
+  switch (key) {
+    case 'rowIds': return []
+    case 'ohlc': case 'boxes': case 'markers': case 'colors': case 'errors': return null
+    default: return Number.NaN
+  }
+}
+
+/**
+ * Append one or more points to a spec and return the new spec, trimmed to
+ * the trailing `window` categories when one is given. Every array a series
+ * carries per category (values, row ids, bands, candles, volumes, colours,
+ * markers, errors, lows, targets) grows by the same count, with a gap where
+ * the point says nothing; so do the spec-level ones (waterfall totals). The
+ * input is never mutated: only the arrays that grow are copied, which keeps
+ * Svelte's state diffing cheap at 4 Hz.
+ */
+export function appendPoints(spec: ChartSpec, points: ChartPoint | ReadonlyArray<ChartPoint>, opts: AppendPointsOptions = {}): ChartSpec {
+  const list = Array.isArray(points) ? (points as ReadonlyArray<ChartPoint>) : [points as ChartPoint]
+  if (!list.length) return opts.window ? trim(spec, opts.window) : spec
+  const categories = [...spec.categories, ...list.map((p) => p.category)]
+  const ohlcOwner = spec.series.findIndex((s) => s.ohlc)
+  const series = spec.series.map((s, si) => {
+    const next: ChartSeries = { ...s, values: [...s.values] }
+    for (const p of list) {
+      const v = Array.isArray(p.values) ? (p.values as ReadonlyArray<number>)[si] : (p.values as Record<string, number>)[s.label]
+      next.values.push(typeof v === 'number' ? v : Number.NaN)
+    }
+    for (const key of PER_CATEGORY_SERIES_KEYS) {
+      if (key === 'values') continue
+      const has = s[key] !== undefined
+      // A key the series does not carry is only created when a point brings
+      // it (a candle, a volume), so a plain line stays a plain line.
+      const brings = list.some((p) =>
+        (key === 'ohlc' && p.ohlc !== undefined && si === (ohlcOwner < 0 ? 0 : ohlcOwner)) ||
+        (key === 'volumes' && p.volume !== undefined && si === (ohlcOwner < 0 ? 0 : ohlcOwner)) ||
+        (key === 'rowIds' && p.rowIds?.[si] !== undefined) ||
+        (key === 'upperValues' && p.upper?.[si] !== undefined) ||
+        (key === 'lowerValues' && p.lower?.[si] !== undefined) ||
+        (key === 'lowValues' && p.low?.[si] !== undefined) ||
+        (key === 'targets' && p.target?.[si] !== undefined))
+      if (!has && !brings) continue
+      const base: unknown[] = has ? [...(s[key] as unknown[])] : new Array(s.values.length).fill(gapFor(key))
+      for (const p of list) {
+        let v: unknown = undefined
+        if (key === 'ohlc' && si === (ohlcOwner < 0 ? 0 : ohlcOwner)) v = p.ohlc
+        else if (key === 'volumes' && si === (ohlcOwner < 0 ? 0 : ohlcOwner)) v = p.volume
+        else if (key === 'rowIds') v = p.rowIds?.[si]
+        else if (key === 'upperValues') v = p.upper?.[si]
+        else if (key === 'lowerValues') v = p.lower?.[si]
+        else if (key === 'lowValues') v = p.low?.[si]
+        else if (key === 'targets') v = p.target?.[si]
+        base.push(v === undefined ? gapFor(key) : v)
+      }
+      ;(next as unknown as Record<string, unknown>)[key] = base
+    }
+    return next
+  })
+  let out: ChartSpec = { ...spec, categories, series }
+  for (const key of PER_CATEGORY_SPEC_KEYS) {
+    const arr = spec[key] as unknown[] | undefined
+    if (arr) (out as unknown as Record<string, unknown>)[key] = [...arr, ...list.map(() => false)]
+  }
+  if (opts.window) out = trim(out, opts.window)
+  return out
+}
+
+/** The last `window` categories of a spec (the spec itself when it fits). */
+function trim(spec: ChartSpec, window: number): ChartSpec {
+  const n = spec.categories.length
+  if (window <= 0 || n <= window) return spec
+  const indices = Array.from({ length: window }, (_, k) => n - window + k)
+  return pickCategories(spec, indices)
+}