@matchstick-trading/primitives 0.0.10

package/dist/core/series.js

@@ -0,0 +1,331 @@
+// A series with a clock. A point says when it is (an ISO-8601 UTC instant) and what it is: a finite number, or one of five
+// reasons there is no number. Zero is a value; NaN and infinity are refused, never drawn as gaps. The rules here are plain
+// functions: no calendar (a calendar is the host's), no repair (a disagreement is reported, never fixed), no network.
+// The shape follows the series data contract draft; `report` and `alignSeries` are the two pure readers of it.
+export const POINT_KINDS = ['value', 'missing', 'market-closed', 'not-applicable', 'halted', 'unknown'];
+const ISO_UTC = /^(\d{4})-(\d{2})-(\d{2})T([01]\d|2[0-3]):([0-5]\d):([0-5]\d)(\.\d+)?Z$/;
+/** An ISO-8601 UTC instant whose calendar date is real: `Date.parse` alone would turn 2026-02-30 into March 2. */
+const isIso = (s) => {
+    if (typeof s !== 'string')
+        return false;
+    const m = ISO_UTC.exec(s);
+    if (!m || !Number.isFinite(Date.parse(s)))
+        return false;
+    const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
+    return d.getUTCFullYear() === Number(m[1]) && d.getUTCMonth() === Number(m[2]) - 1 && d.getUTCDate() === Number(m[3]);
+};
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function unknownKeys(obj, allowed, path, issues) {
+    for (const k of Object.keys(obj))
+        if (!allowed.includes(k))
+            issues.push({ path: [...path, k], message: `unknown key "${k}"` });
+}
+/**
+ * Check a value at the boundary (a recorded session, an adapter's output, a hand-built set). Every problem is returned
+ * in one pass, not only the first. The input is not changed.
+ */
+export function validateSeriesSet(input) {
+    const issues = [];
+    if (!isRecord(input))
+        return { ok: false, issues: [{ path: [], message: 'expected an object' }] };
+    unknownKeys(input, ['schemaVersion', 'alignment', 'window', 'series'], [], issues);
+    if (input.schemaVersion !== '0')
+        issues.push({ path: ['schemaVersion'], message: 'must be "0"' });
+    const al = input.alignment;
+    if (!isRecord(al))
+        issues.push({ path: ['alignment'], message: 'expected an object' });
+    else {
+        unknownKeys(al, ['mode', 'toleranceMs', 'primary'], ['alignment'], issues);
+        if (al.mode !== 'exact' && al.mode !== 'asof' && al.mode !== 'none')
+            issues.push({ path: ['alignment', 'mode'], message: 'must be "exact", "asof" or "none"' });
+        if (al.toleranceMs !== undefined && !(typeof al.toleranceMs === 'number' && Number.isInteger(al.toleranceMs) && al.toleranceMs >= 0))
+            issues.push({ path: ['alignment', 'toleranceMs'], message: 'must be a whole number of milliseconds, 0 or more' });
+        if (al.mode === 'asof' && al.toleranceMs === undefined)
+            issues.push({ path: ['alignment', 'toleranceMs'], message: 'required when mode is asof' });
+        if (typeof al.primary !== 'string' || al.primary === '')
+            issues.push({ path: ['alignment', 'primary'], message: 'must name a series' });
+    }
+    const w = input.window;
+    if (w !== undefined) {
+        if (!isRecord(w))
+            issues.push({ path: ['window'], message: 'expected an object' });
+        else {
+            unknownKeys(w, ['start', 'end'], ['window'], issues);
+            if (!isIso(w.start))
+                issues.push({ path: ['window', 'start'], message: 'must be an ISO-8601 UTC time like 2026-01-05T14:30:00Z' });
+            if (!isIso(w.end))
+                issues.push({ path: ['window', 'end'], message: 'must be an ISO-8601 UTC time like 2026-01-05T14:30:00Z' });
+            if (isIso(w.start) && isIso(w.end) && Date.parse(w.end) <= Date.parse(w.start))
+                issues.push({ path: ['window', 'end'], message: 'end must be after start (the range is [start, end))' });
+        }
+    }
+    const list = input.series;
+    if (!Array.isArray(list) || list.length === 0)
+        issues.push({ path: ['series'], message: 'expected at least one series' });
+    else {
+        const ids = [];
+        for (let i = 0; i < list.length; i++) {
+            const s = list[i]; // by index: an empty slot in a sparse array is read as undefined, not skipped
+            const at = ['series', i];
+            if (!isRecord(s)) {
+                issues.push({ path: at, message: 'expected an object' });
+                continue;
+            }
+            unknownKeys(s, ['id', 'label', 'unit', 'calendar', 'points'], at, issues);
+            if (typeof s.id !== 'string' || s.id === '')
+                issues.push({ path: [...at, 'id'], message: 'must be a non-empty string' });
+            else
+                ids.push(s.id);
+            if (typeof s.label !== 'string' || s.label === '')
+                issues.push({ path: [...at, 'label'], message: 'must be a non-empty string' });
+            if (s.unit !== undefined && typeof s.unit !== 'string')
+                issues.push({ path: [...at, 'unit'], message: 'must be a string' });
+            if (s.calendar !== undefined) {
+                const c = s.calendar;
+                if (!isRecord(c))
+                    issues.push({ path: [...at, 'calendar'], message: 'expected an object' });
+                else {
+                    unknownKeys(c, ['id', 'version', 'tz'], [...at, 'calendar'], issues);
+                    if (typeof c.id !== 'string' || c.id === '')
+                        issues.push({ path: [...at, 'calendar', 'id'], message: 'must be a non-empty string' });
+                    if (typeof c.tz !== 'string' || c.tz === '')
+                        issues.push({ path: [...at, 'calendar', 'tz'], message: 'must be a non-empty string' });
+                    if (c.version !== undefined && typeof c.version !== 'string')
+                        issues.push({ path: [...at, 'calendar', 'version'], message: 'must be a string' });
+                }
+            }
+            if (!Array.isArray(s.points)) {
+                issues.push({ path: [...at, 'points'], message: 'expected a list' });
+                continue;
+            }
+            let last = Number.NEGATIVE_INFINITY;
+            for (let j = 0; j < s.points.length; j++) {
+                const p = s.points[j];
+                const pat = [...at, 'points', j];
+                if (!isRecord(p)) {
+                    issues.push({ path: pat, message: 'expected an object' });
+                    continue;
+                }
+                const kind = p.kind;
+                if (typeof kind !== 'string' || !POINT_KINDS.includes(kind)) {
+                    issues.push({ path: [...pat, 'kind'], message: `must be one of ${POINT_KINDS.join(', ')}` });
+                    continue;
+                }
+                unknownKeys(p, kind === 'value' ? ['t', 'kind', 'v'] : ['t', 'kind'], pat, issues);
+                if (!isIso(p.t))
+                    issues.push({ path: [...pat, 't'], message: 'must be an ISO-8601 UTC time like 2026-01-05T14:30:00Z' });
+                else {
+                    const ms = Date.parse(p.t);
+                    if (ms <= last)
+                        issues.push({ path: [...pat, 't'], message: 'timestamps must strictly increase' });
+                    last = ms;
+                }
+                if (kind === 'value' && !(typeof p.v === 'number' && Number.isFinite(p.v)))
+                    issues.push({ path: [...pat, 'v'], message: 'a value must be a finite number (NaN and infinity are refused)' });
+            }
+        }
+        if (new Set(ids).size !== ids.length)
+            issues.push({ path: ['series'], message: 'series ids must be unique' });
+        if (isRecord(al) && typeof al.primary === 'string' && al.primary !== '' && !ids.includes(al.primary))
+            issues.push({ path: ['alignment', 'primary'], message: 'primary must name a series' });
+    }
+    return issues.length === 0 ? { ok: true, value: input } : { ok: false, issues };
+}
+/**
+ * `validateSeriesSet` as a Standard Schema (v1), so any validator-aware tool can run it at a boundary, for example
+ * `check(seriesSetSchema, data)` from `@fieldtest/core`. Imports nothing.
+ */
+export const seriesSetSchema = {
+    '~standard': {
+        version: 1,
+        vendor: 'matchstick-primitives',
+        validate(value) {
+            const r = validateSeriesSet(value);
+            return r.ok ? { value: r.value } : { issues: r.issues.map((i) => ({ message: i.message, path: i.path })) };
+        },
+    },
+};
+const inWindow = (set, ms) => !set.window || (ms >= Date.parse(set.window.start) && ms < Date.parse(set.window.end));
+/** Index of the last time in `times` (ascending) that is at or before `t`, or -1. */
+function atOrBefore(times, t) {
+    let lo = 0;
+    let hi = times.length - 1;
+    let found = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (times[mid] <= t) {
+            found = mid;
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    return found;
+}
+/**
+ * Where the series in a set disagree, read on the primary's timestamps. In order: every `unknown` point in the window
+ * (`unclassified`), a series that stops before the window ends (`feed-stopped`), then for each primary point and
+ * each other series, no point within tolerance (`no-point`) or two different kinds (`gap-kind-differs`).
+ *
+ * `not-applicable` against anything is expected (a warm-up) and is not reported. `unknown` against another gap kind
+ * cannot disagree, but `unknown` against a value does. `halted` is an ordinary kind. With mode `none` there is no
+ * comparison across series. The set is not changed; run `validateSeriesSet` first for a set from outside.
+ */
+export function report(set) {
+    const out = [];
+    const primary = set.series.find((s) => s.id === set.alignment.primary);
+    for (const s of set.series)
+        for (const q of s.points)
+            if (q.kind === 'unknown' && inWindow(set, Date.parse(q.t)))
+                out.push({ t: q.t, kind: 'unclassified', series: [s.id], detail: `${s.id}: absent, source does not say why` });
+    if (set.window) {
+        const end = Date.parse(set.window.end);
+        for (const s of set.series) {
+            const inside = s.points.filter((q) => Date.parse(q.t) < end); // a point after the range cannot hide a feed that stopped inside it
+            const ts = inside.map((q) => Date.parse(q.t));
+            const gaps = ts.slice(1).map((x, i) => x - ts[i]).sort((x, y) => x - y);
+            const step = gaps[Math.floor(gaps.length / 2)] ?? 0; // the usual interval: the median
+            const last = ts.length ? ts[ts.length - 1] : undefined;
+            if (last === undefined || last < end - step) {
+                const lastText = last === undefined ? 'none' : inside[inside.length - 1].t;
+                out.push({ t: last === undefined ? set.window.start : lastText, kind: 'feed-stopped', series: [s.id], detail: `${s.id} last point ${lastText} is more than one interval (${step} ms) before the range end ${set.window.end} (exclusive)` });
+            }
+        }
+    }
+    if (!primary || set.alignment.mode === 'none')
+        return out;
+    const tolerance = set.alignment.mode === 'asof' ? set.alignment.toleranceMs ?? 0 : 0;
+    const isGap = (k) => k !== 'value';
+    for (const s of set.series) {
+        if (s === primary)
+            continue;
+        const times = s.points.map((q) => Date.parse(q.t));
+        for (const pt of primary.points) {
+            const t = Date.parse(pt.t);
+            if (!inWindow(set, t))
+                continue;
+            const at = atOrBefore(times, t);
+            if (at < 0 || t - times[at] > tolerance) {
+                out.push({ t: pt.t, kind: 'no-point', series: [primary.id, s.id], detail: `${s.id} has no point within ${tolerance} ms` });
+                continue;
+            }
+            const other = s.points[at];
+            const same = other.kind === pt.kind;
+            const warmup = other.kind === 'not-applicable' || pt.kind === 'not-applicable';
+            const dontKnow = (other.kind === 'unknown' || pt.kind === 'unknown') && isGap(other.kind) && isGap(pt.kind);
+            if (!same && !warmup && !dontKnow)
+                out.push({ t: pt.t, kind: 'gap-kind-differs', series: [primary.id, s.id], detail: `${primary.id}=${pt.kind}, ${s.id}=${other.kind}` });
+        }
+    }
+    return out;
+}
+/**
+ * Put a series on the bars' clock: for each bar time, the point at that instant (`exact`) or the latest point at or
+ * before it within the tolerance (`asof`). A bar with no point gets `null` and the state `no-point`. Nothing is carried
+ * across a gap kind and no zero is invented. `none` is read as `exact`.
+ */
+export function alignSeries(barTimes, series, options = {}) {
+    const tolerance = options.mode === 'asof' ? Math.max(0, options.toleranceMs ?? 0) : 0;
+    const times = series.points.map((q) => Date.parse(q.t));
+    const values = new Array(barTimes.length).fill(null);
+    const states = new Array(barTimes.length).fill('no-point');
+    for (let i = 0; i < barTimes.length; i++) {
+        const at = atOrBefore(times, barTimes[i]);
+        if (at < 0 || barTimes[i] - times[at] > tolerance)
+            continue;
+        const p = series.points[at];
+        states[i] = p.kind;
+        if (p.kind === 'value')
+            values[i] = p.v;
+    }
+    return { id: series.id, label: series.label, values, states };
+}
+/**
+ * Turn a value-per-bar array (a study, or anything made by position) into points on the bars' clock. A number is a
+ * value; `null`, NaN and infinity become `gapKind` (default `not-applicable`, which is what a warm-up is).
+ */
+export function pointsFromValues(barTimes, values, gapKind = 'not-applicable') {
+    const out = [];
+    for (let i = 0; i < barTimes.length; i++) {
+        const v = values[i];
+        const at = barTimes[i];
+        const t = new Date(typeof at === 'number' ? at : at.timestamp).toISOString();
+        out.push(typeof v === 'number' && Number.isFinite(v) ? { t, kind: 'value', v } : { t, kind: gapKind });
+    }
+    return out;
+}
+const NO_VALUES = [];
+/**
+ * The values to draw for one series on these bars. `points` are placed by time (see `alignSeries`); `values` are read by
+ * position. Problems are returned in words and the series is still drawn as far as it can be: a length that does not
+ * match the bars, a series with no value on any bar, points out of time order.
+ */
+export function resolveSeries(barTimes, input, options = {}) {
+    const problems = [];
+    const name = `"${input.label || input.id}"`;
+    let values;
+    let states;
+    if (input.points !== undefined) {
+        if (!Array.isArray(input.points)) {
+            problems.push(`${name} has points that are not a list, so it is not drawn.`);
+            values = NO_VALUES;
+        }
+        else {
+            // Only a usable point goes on: an object with a readable time, a known kind, and a finite number on a value.
+            const usable = [];
+            let bad = 0;
+            for (let i = 0; i < input.points.length; i++) {
+                const p = input.points[i];
+                const ok = typeof p === 'object' && p !== null && isIso(p.t)
+                    && POINT_KINDS.includes(p.kind) && (p.kind !== 'value' || (typeof p.v === 'number' && Number.isFinite(p.v)));
+                if (ok)
+                    usable.push(p);
+                else {
+                    bad++;
+                    // A rejected point with a readable time stays as an unknown, so an as-of alignment cannot carry the value before it across.
+                    if (typeof p === 'object' && p !== null && isIso(p.t))
+                        usable.push({ t: p.t, kind: 'unknown' });
+                }
+            }
+            if (bad > 0)
+                problems.push(`${name} has ${bad} point${bad === 1 ? '' : 's'} that cannot be used (a missing time, a time that is not ISO-8601 UTC ending in Z, an unknown kind, or a value that is not a finite number), so ${bad === 1 ? 'it was' : 'they were'} left out.`);
+            let prev = Number.NEGATIVE_INFINITY;
+            let ordered = true;
+            for (const p of usable) {
+                const t = Date.parse(p.t);
+                if (t <= prev) {
+                    ordered = false;
+                    break;
+                }
+                prev = t;
+            }
+            if (!ordered) {
+                problems.push(`${name} has points that are not in strictly increasing time order, so it is not drawn.`);
+                values = NO_VALUES;
+            }
+            else {
+                const aligned = alignSeries(barTimes, { id: input.id, label: input.label, points: usable }, options);
+                values = aligned.values;
+                states = aligned.states;
+                if (usable.length > 0 && aligned.states.every((s) => s === 'no-point'))
+                    problems.push(`${name} has no point on any bar. Point times are ISO-8601 UTC text, for example 2026-01-05T14:30:00Z, and must fall on the bars' times.`);
+            }
+        }
+    }
+    else {
+        values = input.values ?? NO_VALUES;
+        if (input.values !== undefined && input.values.length !== barTimes.length)
+            problems.push(`${name} has ${input.values.length} values for ${barTimes.length} bars. Values are read by position, so the extra or missing ones are ignored. Pass points with times instead.`);
+    }
+    if (!problems.some((p) => !p.includes('cannot be used')) && !values.some((v) => typeof v === 'number' && Number.isFinite(v)))
+        problems.push(`${name} has no value on any bar.`);
+    return { values, states, problems };
+}
+/** The ids used by more than one series, once each. */
+export function duplicateIds(items) {
+    const seen = new Set();
+    const dup = new Set();
+    for (const { id } of items)
+        (seen.has(id) ? dup : seen).add(id);
+    return [...dup];
+}

package/dist/core/studies.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Chart studies as plain functions: moving averages, Bollinger bands, VWAP, RSI and ATR. Each takes the bars and
+ * returns one value per bar, `null` while the study is still warming up (or where a bar's input is not a finite
+ * number). Standard textbook definitions only. Nothing here throws: a bad period is rounded to a whole number of at
+ * least 1, and empty input gives an empty array.
+ */
+import type { CandleBar, ChartViewport } from './chart-scale.js';
+/** One value per bar, `null` where the study has no value yet. */
+export type Series = Array<number | null>;
+/** Which price of a bar a study reads. hl2 is (high + low) / 2, hlc3 adds the close, ohlc4 averages all four. */
+export type StudySource = 'open' | 'high' | 'low' | 'close' | 'hl2' | 'hlc3' | 'ohlc4';
+/** A bar's price for `source`; NaN when a needed field is not finite. */
+export declare function sourcePrice(bar: CandleBar, source?: StudySource): number;
+/** Simple moving average: the mean of the last `period` prices. Null until a full window of finite prices exists. */
+export declare function sma(bars: readonly CandleBar[], period: number, source?: StudySource): Series;
+/**
+ * Exponential moving average with weight 2 / (period + 1). It starts from the simple average of the first `period`
+ * prices, so the first value sits at index period - 1. A bar with no finite price gets null and the average carries
+ * on from the next good bar.
+ */
+export declare function ema(bars: readonly CandleBar[], period: number, source?: StudySource): Series;
+/** Weighted moving average: the newest price in the window counts `period` times, the oldest once. */
+export declare function wma(bars: readonly CandleBar[], period: number, source?: StudySource): Series;
+export interface BollingerBands {
+    middle: Series;
+    upper: Series;
+    lower: Series;
+}
+/** Bollinger bands on the close: a simple average, and `mult` population standard deviations above and below it. */
+export declare function bollinger(bars: readonly CandleBar[], period?: number, mult?: number): BollingerBands;
+export interface VwapOptions {
+    /**
+     * Where the running total restarts: 'session' at each UTC day boundary (moved by `sessionStartUtcMinute`), 'all' never,
+     * or a timestamp: bars before it have no value and the total starts on the first bar at or after it.
+     */
+    anchor?: 'session' | 'all' | number;
+    /** Minutes after 00:00 UTC at which a session begins. Default 0. */
+    sessionStartUtcMinute?: number;
+    /** Band widths in volume-weighted standard deviations, for example [1, 2]. */
+    bands?: readonly number[];
+}
+export interface VwapBand {
+    mult: number;
+    upper: Series;
+    lower: Series;
+}
+export interface VwapResult {
+    vwap: Series;
+    bands: VwapBand[];
+}
+/**
+ * Volume-weighted average price on the typical price (high + low + close) / 3, restarting at the anchor. A bar with
+ * no volume yet in its run has no value. Bands sit `mult` volume-weighted standard deviations of the typical price
+ * around the line.
+ */
+export declare function vwap(bars: readonly CandleBar[], options?: VwapOptions): VwapResult;
+/**
+ * Relative strength index with Wilder smoothing, 0 to 100. The first value sits at index `period` (it needs
+ * `period` price changes). All gains and no losses is 100; no movement at all is 50.
+ */
+export declare function rsi(bars: readonly CandleBar[], period?: number): Series;
+/**
+ * Average true range with Wilder smoothing. A bar's true range is the largest of high - low, |high - previous close|
+ * and |low - previous close| (just high - low for the first bar). The first value sits at index period - 1.
+ */
+export declare function atr(bars: readonly CandleBar[], period?: number): Series;
+/** The whole-bar indexes a viewport shows, clamped to the series; last < first when nothing is visible. Same rule as the chart frame. */
+export declare function visibleIndexes(viewport: ChartViewport, total: number): {
+    first: number;
+    last: number;
+};
+/**
+ * The [low, high] of the study values over bars first..last, for `Chart.Root`'s `include` so a line outside the candle
+ * range stays in view. With no value to show it returns [Infinity, -Infinity], which the chart ignores.
+ */
+export declare function studyRange(visible: {
+    first: number;
+    last: number;
+}, ...series: ReadonlyArray<ReadonlyArray<number | null>>): [number, number];
+//# sourceMappingURL=studies.d.ts.map

package/dist/core/studies.js

@@ -0,0 +1,237 @@
+/** A bar's price for `source`; NaN when a needed field is not finite. */
+export function sourcePrice(bar, source = 'close') {
+    switch (source) {
+        case 'open': return bar.open;
+        case 'high': return bar.high;
+        case 'low': return bar.low;
+        case 'hl2': return (bar.high + bar.low) / 2;
+        case 'hlc3': return (bar.high + bar.low + bar.close) / 3;
+        case 'ohlc4': return (bar.open + bar.high + bar.low + bar.close) / 4;
+        default: return bar.close;
+    }
+}
+const whole = (period, fallback) => (Number.isFinite(period) ? Math.max(1, Math.floor(period)) : fallback);
+const blank = (length) => new Array(length).fill(null);
+/** Simple moving average: the mean of the last `period` prices. Null until a full window of finite prices exists. */
+export function sma(bars, period, source = 'close') {
+    const n = whole(period, 1);
+    const out = blank(bars.length);
+    const prices = bars.map((b) => sourcePrice(b, source));
+    for (let i = n - 1; i < prices.length; i++) {
+        let sum = 0;
+        let ok = true;
+        for (let k = i - n + 1; k <= i; k++) {
+            if (!Number.isFinite(prices[k])) {
+                ok = false;
+                break;
+            }
+            sum += prices[k];
+        }
+        if (ok)
+            out[i] = sum / n;
+    }
+    return out;
+}
+/**
+ * Exponential moving average with weight 2 / (period + 1). It starts from the simple average of the first `period`
+ * prices, so the first value sits at index period - 1. A bar with no finite price gets null and the average carries
+ * on from the next good bar.
+ */
+export function ema(bars, period, source = 'close') {
+    const n = whole(period, 1);
+    const out = blank(bars.length);
+    const alpha = 2 / (n + 1);
+    let previous = null;
+    let seed = 0;
+    let seen = 0;
+    for (let i = 0; i < bars.length; i++) {
+        const price = sourcePrice(bars[i], source);
+        if (!Number.isFinite(price))
+            continue;
+        if (previous === null) {
+            seed += price;
+            seen++;
+            if (seen === n) {
+                previous = seed / n;
+                out[i] = previous;
+            }
+        }
+        else {
+            previous = previous + alpha * (price - previous);
+            out[i] = previous;
+        }
+    }
+    return out;
+}
+/** Weighted moving average: the newest price in the window counts `period` times, the oldest once. */
+export function wma(bars, period, source = 'close') {
+    const n = whole(period, 1);
+    const out = blank(bars.length);
+    const prices = bars.map((b) => sourcePrice(b, source));
+    const weights = (n * (n + 1)) / 2;
+    for (let i = n - 1; i < prices.length; i++) {
+        let sum = 0;
+        let ok = true;
+        for (let k = 0; k < n; k++) {
+            const price = prices[i - n + 1 + k];
+            if (!Number.isFinite(price)) {
+                ok = false;
+                break;
+            }
+            sum += price * (k + 1);
+        }
+        if (ok)
+            out[i] = sum / weights;
+    }
+    return out;
+}
+/** Bollinger bands on the close: a simple average, and `mult` population standard deviations above and below it. */
+export function bollinger(bars, period = 20, mult = 2) {
+    const n = whole(period, 20);
+    const k = Number.isFinite(mult) ? mult : 2;
+    const middle = sma(bars, n, 'close');
+    const upper = blank(bars.length);
+    const lower = blank(bars.length);
+    for (let i = 0; i < bars.length; i++) {
+        const mean = middle[i];
+        if (mean === null)
+            continue;
+        let squares = 0;
+        for (let j = i - n + 1; j <= i; j++)
+            squares += (bars[j].close - mean) ** 2;
+        const deviation = Math.sqrt(squares / n);
+        upper[i] = mean + k * deviation;
+        lower[i] = mean - k * deviation;
+    }
+    return { middle, upper, lower };
+}
+const DAY_MS = 86400000;
+/**
+ * Volume-weighted average price on the typical price (high + low + close) / 3, restarting at the anchor. A bar with
+ * no volume yet in its run has no value. Bands sit `mult` volume-weighted standard deviations of the typical price
+ * around the line.
+ */
+export function vwap(bars, options = {}) {
+    const { anchor = 'session', bands = [] } = options;
+    const offset = (Number.isFinite(options.sessionStartUtcMinute) ? options.sessionStartUtcMinute : 0) * 60000;
+    const mults = bands.filter((m) => Number.isFinite(m));
+    const line = blank(bars.length);
+    const edges = mults.map((mult) => ({ mult, upper: blank(bars.length), lower: blank(bars.length) }));
+    let session = Number.NaN;
+    let volume = 0;
+    let money = 0;
+    let squares = 0;
+    for (let i = 0; i < bars.length; i++) {
+        const bar = bars[i];
+        if (typeof anchor === 'number' && bar.timestamp < anchor)
+            continue;
+        if (anchor === 'session') {
+            const day = Math.floor((bar.timestamp - offset) / DAY_MS);
+            if (day !== session) {
+                session = day;
+                volume = 0;
+                money = 0;
+                squares = 0;
+            }
+        }
+        const price = sourcePrice(bar, 'hlc3');
+        if (Number.isFinite(price) && Number.isFinite(bar.volume) && bar.volume > 0) {
+            volume += bar.volume;
+            money += bar.volume * price;
+            squares += bar.volume * price * price;
+        }
+        if (volume <= 0)
+            continue;
+        const mean = money / volume;
+        line[i] = mean;
+        const deviation = Math.sqrt(Math.max(0, squares / volume - mean * mean));
+        for (const edge of edges) {
+            edge.upper[i] = mean + edge.mult * deviation;
+            edge.lower[i] = mean - edge.mult * deviation;
+        }
+    }
+    return { vwap: line, bands: edges };
+}
+/**
+ * Relative strength index with Wilder smoothing, 0 to 100. The first value sits at index `period` (it needs
+ * `period` price changes). All gains and no losses is 100; no movement at all is 50.
+ */
+export function rsi(bars, period = 14) {
+    const n = whole(period, 14);
+    const out = blank(bars.length);
+    let gain = 0;
+    let loss = 0;
+    const score = () => (gain === 0 && loss === 0 ? 50 : loss === 0 ? 100 : 100 - 100 / (1 + gain / loss));
+    for (let i = 1; i < bars.length; i++) {
+        const change = bars[i].close - bars[i - 1].close;
+        if (!Number.isFinite(change))
+            return out; // a gap in the data ends the study rather than guessing
+        const up = Math.max(0, change);
+        const down = Math.max(0, -change);
+        if (i <= n) {
+            gain += up / n;
+            loss += down / n;
+            if (i === n)
+                out[i] = score();
+        }
+        else {
+            gain = (gain * (n - 1) + up) / n;
+            loss = (loss * (n - 1) + down) / n;
+            out[i] = score();
+        }
+    }
+    return out;
+}
+/**
+ * Average true range with Wilder smoothing. A bar's true range is the largest of high - low, |high - previous close|
+ * and |low - previous close| (just high - low for the first bar). The first value sits at index period - 1.
+ */
+export function atr(bars, period = 14) {
+    const n = whole(period, 14);
+    const out = blank(bars.length);
+    let average = 0;
+    for (let i = 0; i < bars.length; i++) {
+        const bar = bars[i];
+        const previous = i > 0 ? bars[i - 1].close : bar.close;
+        const range = Math.max(bar.high - bar.low, Math.abs(bar.high - previous), Math.abs(bar.low - previous));
+        if (!Number.isFinite(range))
+            return out;
+        if (i < n) {
+            average += range / n;
+            if (i === n - 1)
+                out[i] = average;
+        }
+        else {
+            average = (average * (n - 1) + range) / n;
+            out[i] = average;
+        }
+    }
+    return out;
+}
+/** The whole-bar indexes a viewport shows, clamped to the series; last < first when nothing is visible. Same rule as the chart frame. */
+export function visibleIndexes(viewport, total) {
+    const start = Number.isFinite(viewport.start) ? viewport.start : 0;
+    const end = Number.isFinite(viewport.end) ? viewport.end : start + 1;
+    return { first: Math.max(0, Math.floor(start)), last: Math.min(total - 1, Math.ceil(Math.max(end, start + 1)) - 1) };
+}
+/**
+ * The [low, high] of the study values over bars first..last, for `Chart.Root`'s `include` so a line outside the candle
+ * range stays in view. With no value to show it returns [Infinity, -Infinity], which the chart ignores.
+ */
+export function studyRange(visible, ...series) {
+    let low = Infinity;
+    let high = -Infinity;
+    for (const values of series) {
+        const end = Math.min(visible.last, values.length - 1);
+        for (let i = Math.max(0, visible.first); i <= end; i++) {
+            const value = values[i];
+            if (value === null || !Number.isFinite(value))
+                continue;
+            if (value < low)
+                low = value;
+            if (value > high)
+                high = value;
+        }
+    }
+    return [low, high];
+}