@jarenjs/core 0.9.2 → 0.34.0

package/src/errors.js

@@ -0,0 +1,102 @@
+//@ts-check
+/**
+ * @file The suite's one coded-error contract. Every engine error that
+ * carries a stable diagnosis code derives from {@link CodedError}; the
+ * canonical form is the structured triple `{ code, reason, docPath |
+ * dataPath }`, and `message` is COMPOSED from it for the channels that
+ * have no structured reader (an uncaught throw, a console, a CI
+ * transcript, a model reading `{ error: err.message }`).
+ *
+ * The rendering decision, fixed here so every package agrees:
+ *
+ *   `${code}: ${reason}`                      — no location
+ *   `${code}: ${reason} at ${docPath}`        — a document location
+ *   `${code}: ${reason} in data ${dataPath}`  — a data location
+ *   `${code}: ${reason} at ${d} in data ${p}` — both
+ *
+ * `docPath` points into the offending *document* (a query, a stylesheet,
+ * an app document); `dataPath` points into the offending *data* the
+ * document was applied to. They are different facts and stay separately
+ * readable and separately identifiable — `at` always means document,
+ * `in data` always means data. A root pointer (`''`) is a real location
+ * and renders as `at ''`; absence is `undefined` and renders nothing.
+ * Absence must never be normalized to `''` — the AI repair loop's
+ * `docPath ?? instancePath ?? ''` fallback chain relies on `undefined`
+ * to fall through, and `''` is a legitimate root pointer.
+ *
+ * Cause presence uses the `hasOwn` form: the constructor takes an
+ * options bag, and `Object.hasOwn(options, 'cause')` decides whether an
+ * own `cause` is installed — so a host that threw `undefined` (passed as
+ * `{ cause: undefined }`) stays distinguishable from "no cause" (no
+ * options, or an options bag without the key). Positional-adapter
+ * subclasses that translate an optional trailing `cause` parameter MUST
+ * map an `undefined` argument to "no cause", never to
+ * `{ cause: undefined }`.
+ *
+ * Deliberately OUTSIDE this contract: `ValidationError`
+ * (keyword-keyed, locale-rendered, has its own `toJSON`), the
+ * `LabeledSyntaxError` family (`source`/`position` over a source
+ * string), and josl's line/column family (`line`/`column`/`hint`).
+ * Different shapes for different consumers — do not "finish the job" by
+ * folding them in.
+ *
+ * Localization: `@jarenjs/locales` keys its catalogs by JSON Schema
+ * KEYWORD (`form/minLength`, …), not by error code — coded errors are
+ * localizable by nothing today. Stated so nobody assumes otherwise; a
+ * code-keyed catalog would be a new locales feature, not a property of
+ * this base.
+ */
+
+/**
+ * Compose the canonical coded message from the structured fields.
+ * @param {string} code - Stable diagnosis code
+ * @param {string} reason - The bare human-readable reason
+ * @param {string} [docPath] - JSON Pointer into the offending document
+ * @param {string} [dataPath] - Pointer/path into the offending data
+ * @returns {string}
+ */
+function composeCodedMessage(code, reason, docPath, dataPath) {
+  let message = `${code}: ${reason}`;
+  if (docPath !== undefined) message += ` at ${docPath === '' ? "''" : docPath}`;
+  if (dataPath !== undefined) message += ` in data ${dataPath === '' ? "''" : dataPath}`;
+  return message;
+}
+
+/**
+ * Base class for every coded error in the suite. Subclasses are thin
+ * per-package adapters that fix the public `name` (passed as a string
+ * literal because bundles are minified and a mangled class name must
+ * not leak into `error.name`) and translate their historical positional
+ * signatures into the location/options form.
+ */
+export class CodedError extends Error {
+  /**
+   * @param {string} name - The public class name for `error.name`
+   * @param {string} code - Stable diagnosis code
+   * @param {string} reason - The bare reason; `message` is composed from
+   *   `code`, `reason` and the location and must not be pre-composed
+   * @param {string | { docPath?: string, dataPath?: string }} [location]
+   *   - A string is a `docPath`; the object form carries either or both
+   * @param {{ cause?: unknown }} [options] - `cause` is installed as an
+   *   own property exactly when the key is present (`hasOwn` form),
+   *   preserving "host threw `undefined`" as distinct from "no cause"
+   */
+  constructor(name, code, reason, location = undefined, options = undefined) {
+    const docPath = typeof location === 'string' ? location : location?.docPath;
+    const dataPath = typeof location === 'string' ? undefined : location?.dataPath;
+    super(composeCodedMessage(code, reason, docPath, dataPath));
+    this.name = name;
+    this.code = code;
+    this.reason = reason;
+    this.docPath = docPath;
+    if (dataPath !== undefined) this.dataPath = dataPath;
+    if (options !== undefined && Object.hasOwn(options, 'cause')) {
+      // The native `new Error(msg, { cause })` shape: non-enumerable,
+      // writable, configurable — installed by hand so an explicitly
+      // `undefined` cause is representable.
+      Object.defineProperty(this, 'cause', {
+        value: options.cause, writable: true, enumerable: false, configurable: true,
+      });
+    }
+  }
+}

package/src/finance/amortization.js

@@ -0,0 +1,50 @@
+//@ts-check
+/**
+ * @file Loan amortization. Given a principal, a periodic
+ * rate and a term, produce the period-by-period split of each payment
+ * into interest and principal with the running balance.
+ */
+
+import { pmt as tvmPmt } from './tvm.js';
+
+/**
+ * @typedef {object} AmortRow
+ * @property {number} period 1-based period index
+ * @property {number} payment total payment this period
+ * @property {number} interest interest portion
+ * @property {number} principal principal portion
+ * @property {number} balance remaining balance after this payment
+ */
+
+/**
+ * Build a full amortization schedule. The payment is derived from the
+ * standard annuity formula unless an explicit `payment` is supplied
+ * (e.g. a rounded real-world instalment); the final period absorbs any
+ * rounding residue so the balance lands exactly on zero.
+ *
+ * @param {number} principal loan amount (positive)
+ * @param {number} rate periodic interest rate
+ * @param {number} nper number of periods
+ * @param {{ payment?: number, type?: number }} [opts]
+ * @returns {AmortRow[]}
+ */
+export function amortizationSchedule(principal, rate, nper, opts = {}) {
+  const type = opts.type ?? 0;
+  const payment = opts.payment ?? -tvmPmt(rate, nper, principal, 0, type);
+  const rows = [];
+  let balance = principal;
+  for (let period = 1; period <= nper; period++) {
+    const interest = balance * rate;
+    let principalPart = payment - interest;
+    let pay = payment;
+    if (period === nper) {
+      // clear any residual balance on the last row
+      principalPart = balance;
+      pay = balance + interest;
+    }
+    balance -= principalPart;
+    if (Math.abs(balance) < 1e-9) balance = 0;
+    rows.push({ period, payment: pay, interest, principal: principalPart, balance });
+  }
+  return rows;
+}

package/src/finance/bond.js

@@ -0,0 +1,100 @@
+//@ts-check
+/**
+ * @file Bond math: price, yield-to-maturity, Macaulay and
+ * modified duration, and convexity. Basic day-count only (level coupons,
+ * whole periods to maturity); exotic conventions are out of scope.
+ *
+ * Rates and the coupon rate are annual; `freq` coupons are paid per year.
+ */
+
+import { newtonRaphson, bisect } from '../math/solve.js';
+
+/**
+ * Clean price of a coupon bond.
+ * @param {number} face par/redemption value
+ * @param {number} couponRate annual coupon rate
+ * @param {number} ytm annual yield to maturity
+ * @param {number} years years to maturity
+ * @param {number} [freq] coupons per year
+ * @returns {number}
+ */
+export function bondPrice(face, couponRate, ytm, years, freq = 2) {
+  const n = Math.round(years * freq);
+  const c = face * couponRate / freq;
+  const y = ytm / freq;
+  let price = 0;
+  for (let t = 1; t <= n; t++) price += c / Math.pow(1 + y, t);
+  price += face / Math.pow(1 + y, n);
+  return price;
+}
+
+/**
+ * Yield to maturity from a market price (iterative).
+ * @param {number} price @param {number} face @param {number} couponRate
+ * @param {number} years @param {number} [freq]
+ * @returns {number}
+ */
+export function bondYTM(price, face, couponRate, years, freq = 2) {
+  const f = (y) => bondPrice(face, couponRate, y, years, freq) - price;
+  const df = (y) => {
+    const h = 1e-6;
+    return (f(y + h) - f(y - h)) / (2 * h);
+  };
+  const n = newtonRaphson(f, df, couponRate || 0.05, { tol: 1e-9, maxIter: 100 });
+  if (n.converged && isFinite(n.root) && n.root > -1) return n.root;
+  const b = bisect(f, -0.9999, 5, { tol: 1e-9, maxIter: 300 });
+  return b.converged ? b.root : NaN;
+}
+
+/**
+ * Macaulay duration (in years).
+ * @param {number} face @param {number} couponRate @param {number} ytm
+ * @param {number} years @param {number} [freq]
+ * @returns {number}
+ */
+export function macaulayDuration(face, couponRate, ytm, years, freq = 2) {
+  const n = Math.round(years * freq);
+  const c = face * couponRate / freq;
+  const y = ytm / freq;
+  let weighted = 0;
+  let price = 0;
+  for (let t = 1; t <= n; t++) {
+    const cf = t === n ? c + face : c;
+    const dpv = cf / Math.pow(1 + y, t);
+    price += dpv;
+    weighted += t * dpv;
+  }
+  return (weighted / price) / freq;
+}
+
+/**
+ * Modified duration.
+ * @param {number} face @param {number} couponRate @param {number} ytm
+ * @param {number} years @param {number} [freq]
+ * @returns {number}
+ */
+export function modifiedDuration(face, couponRate, ytm, years, freq = 2) {
+  const mac = macaulayDuration(face, couponRate, ytm, years, freq);
+  return mac / (1 + ytm / freq);
+}
+
+/**
+ * Convexity (in years²).
+ * @param {number} face @param {number} couponRate @param {number} ytm
+ * @param {number} years @param {number} [freq]
+ * @returns {number}
+ */
+export function convexity(face, couponRate, ytm, years, freq = 2) {
+  const n = Math.round(years * freq);
+  const c = face * couponRate / freq;
+  const y = ytm / freq;
+  let price = 0;
+  let cx = 0;
+  for (let t = 1; t <= n; t++) {
+    const cf = t === n ? c + face : c;
+    const dpv = cf / Math.pow(1 + y, t);
+    price += dpv;
+    cx += dpv * t * (t + 1);
+  }
+  return (cx / (price * Math.pow(1 + y, 2))) / (freq * freq);
+}

package/src/finance/cashflow.js

@@ -0,0 +1,122 @@
+//@ts-check
+/**
+ * @file Cash-flow analysis: NPV, IRR, MIRR and their
+ * date-indexed variants XNPV/XIRR. Built on `math/solve`. Cash flows are
+ * arrays with element `t` occurring at period `t` (index 0 = now).
+ */
+
+import { newtonRaphson, bisect } from '../math/solve.js';
+
+const MS_PER_DAY = 86400000;
+const DAYS_PER_YEAR = 365;
+
+/**
+ * Net present value of a period-indexed cash-flow series.
+ * @param {number} rate discount rate per period
+ * @param {number[]} cashflows cashflows[t] at period t (index 0 = t0)
+ * @returns {number}
+ */
+export function npv(rate, cashflows) {
+  let acc = 0;
+  for (let t = 0; t < cashflows.length; t++) {
+    acc += cashflows[t] / Math.pow(1 + rate, t);
+  }
+  return acc;
+}
+
+/**
+ * Internal rate of return: the rate for which `npv` is zero. Newton with
+ * a bisection fallback; returns `NaN` if no rate is found.
+ * @param {number[]} cashflows
+ * @param {number} [guess]
+ * @returns {number}
+ */
+export function irr(cashflows, guess = 0.1) {
+  const f = (r) => npv(r, cashflows);
+  const df = (r) => {
+    let acc = 0;
+    for (let t = 1; t < cashflows.length; t++) {
+      acc += -t * cashflows[t] / Math.pow(1 + r, t + 1);
+    }
+    return acc;
+  };
+  const n = newtonRaphson(f, df, guess, { tol: 1e-9, maxIter: 100 });
+  if (n.converged && isFinite(n.root) && n.root > -1) return n.root;
+  const b = bisect(f, -0.999999, 1e6, { tol: 1e-9, maxIter: 300 });
+  return b.converged ? b.root : NaN;
+}
+
+/**
+ * Modified internal rate of return.
+ * @param {number[]} cashflows
+ * @param {number} financeRate rate paid on negative flows
+ * @param {number} reinvestRate rate earned on positive flows
+ * @returns {number}
+ */
+export function mirr(cashflows, financeRate, reinvestRate) {
+  const n = cashflows.length - 1;
+  let pvNeg = 0;
+  let fvPos = 0;
+  for (let t = 0; t < cashflows.length; t++) {
+    const cf = cashflows[t];
+    if (cf < 0) pvNeg += cf / Math.pow(1 + financeRate, t);
+    else fvPos += cf * Math.pow(1 + reinvestRate, n - t);
+  }
+  if (pvNeg === 0 || fvPos === 0) return NaN;
+  return Math.pow(-fvPos / pvNeg, 1 / n) - 1;
+}
+
+/**
+ * Convert an array of dates (Date, ms timestamp, or day number) to year
+ * fractions from the first date.
+ * @param {Array<Date|number>} dates
+ * @returns {number[]}
+ */
+function yearFractions(dates) {
+  const toMs = (d) => (d instanceof Date ? d.getTime() : d * (typeof d === 'number' && d < 1e6 ? MS_PER_DAY : 1));
+  const t0 = toMs(dates[0]);
+  return dates.map((d) => (toMs(d) - t0) / MS_PER_DAY / DAYS_PER_YEAR);
+}
+
+/**
+ * Date-indexed NPV. `dates` may be `Date`s or ms timestamps.
+ * @param {number} rate annual discount rate
+ * @param {number[]} cashflows
+ * @param {Array<Date|number>} dates
+ * @returns {number}
+ */
+export function xnpv(rate, cashflows, dates) {
+  const yf = yearFractions(dates);
+  let acc = 0;
+  for (let i = 0; i < cashflows.length; i++) {
+    acc += cashflows[i] / Math.pow(1 + rate, yf[i]);
+  }
+  return acc;
+}
+
+/**
+ * Date-indexed IRR.
+ * @param {number[]} cashflows
+ * @param {Array<Date|number>} dates
+ * @param {number} [guess]
+ * @returns {number}
+ */
+export function xirr(cashflows, dates, guess = 0.1) {
+  const yf = yearFractions(dates);
+  const f = (r) => {
+    let acc = 0;
+    for (let i = 0; i < cashflows.length; i++) acc += cashflows[i] / Math.pow(1 + r, yf[i]);
+    return acc;
+  };
+  const df = (r) => {
+    let acc = 0;
+    for (let i = 0; i < cashflows.length; i++) {
+      acc += -yf[i] * cashflows[i] / Math.pow(1 + r, yf[i] + 1);
+    }
+    return acc;
+  };
+  const n = newtonRaphson(f, df, guess, { tol: 1e-9, maxIter: 100 });
+  if (n.converged && isFinite(n.root) && n.root > -1) return n.root;
+  const b = bisect(f, -0.999999, 1e6, { tol: 1e-9, maxIter: 300 });
+  return b.converged ? b.root : NaN;
+}

package/src/finance/depreciation.js

@@ -0,0 +1,54 @@
+//@ts-check
+/**
+ * @file Depreciation schedules: straight-line,
+ * declining-balance (double-declining when factor = 2) and
+ * sum-of-years-digits. Each returns an array of per-period depreciation
+ * amounts of length `life`.
+ */
+
+/**
+ * Straight-line depreciation: equal charge each period.
+ * @param {number} cost @param {number} salvage @param {number} life periods
+ * @returns {number[]}
+ */
+export function straightLine(cost, salvage, life) {
+  const per = (cost - salvage) / life;
+  return Array.from({ length: life }, () => per);
+}
+
+/**
+ * Declining-balance depreciation. `factor` = 2 is double-declining. Never
+ * depreciates below salvage; the final periods absorb the remainder.
+ * @param {number} cost @param {number} salvage @param {number} life
+ * @param {number} [factor]
+ * @returns {number[]}
+ */
+export function decliningBalance(cost, salvage, life, factor = 2) {
+  const rate = factor / life;
+  const out = [];
+  let book = cost;
+  for (let i = 0; i < life; i++) {
+    let dep = book * rate;
+    if (book - dep < salvage) dep = book - salvage;
+    if (dep < 0) dep = 0;
+    out.push(dep);
+    book -= dep;
+  }
+  return out;
+}
+
+/**
+ * Sum-of-years-digits depreciation.
+ * @param {number} cost @param {number} salvage @param {number} life
+ * @returns {number[]}
+ */
+export function sumOfYearsDigits(cost, salvage, life) {
+  const syd = (life * (life + 1)) / 2;
+  const base = cost - salvage;
+  const out = [];
+  for (let i = 0; i < life; i++) {
+    const remaining = life - i;
+    out.push(base * remaining / syd);
+  }
+  return out;
+}

package/src/finance/index.js

@@ -0,0 +1,27 @@
+//@ts-check
+/**
+ * @file `@jarenjs/core/finance` — the finance & trading formula library.
+ * Pure, zero runtime dependencies (imports only `@jarenjs/core/math`).
+ * Every export is a plain function over numbers/number-arrays, reusable
+ * by any package: a calculator, a trading dashboard or a backtester. The
+ * math lives here; orchestration (which variable to solve, forms, display)
+ * lives in the consumer.
+ */
+
+export { pmt, pv, fv, nper, rate } from './tvm.js';
+export { npv, irr, mirr, xnpv, xirr } from './cashflow.js';
+export { amortizationSchedule } from './amortization.js';
+export {
+  simpleInterest, compoundAmount, compoundInterest,
+  nominalToEffective, effectiveToNominal, continuousCompound,
+} from './interest.js';
+export { straightLine, decliningBalance, sumOfYearsDigits } from './depreciation.js';
+export {
+  bondPrice, bondYTM, macaulayDuration, modifiedDuration, convexity,
+} from './bond.js';
+export {
+  sma, ema, wma, macd, rsi, bollinger, stochastic, atr, roc,
+} from './indicators.js';
+export {
+  cagr, holdingPeriodReturn, returnsOf, volatility, sharpe, maxDrawdown,
+} from './returns.js';

package/src/finance/indicators.js

@@ -0,0 +1,207 @@
+//@ts-check
+/**
+ * @file Technical / trading indicators over a price or OHLC
+ * series. Every function returns an array **aligned** to the input (same
+ * length), with `null` in warm-up positions where the indicator is not
+ * yet defined. Single-pass where the math allows; `Float64Array` inputs
+ * are accepted (array-like reads only).
+ */
+
+/**
+ * Simple moving average.
+ * @param {ArrayLike<number>} values @param {number} period
+ * @returns {Array<number|null>}
+ */
+export function sma(values, period) {
+  const n = values.length;
+  const out = new Array(n).fill(null);
+  let sum = 0;
+  for (let i = 0; i < n; i++) {
+    sum += values[i];
+    if (i >= period) sum -= values[i - period];
+    if (i >= period - 1) out[i] = sum / period;
+  }
+  return out;
+}
+
+/**
+ * Exponential moving average (SMA-seeded).
+ * @param {ArrayLike<number>} values @param {number} period
+ * @returns {Array<number|null>}
+ */
+export function ema(values, period) {
+  const n = values.length;
+  const out = new Array(n).fill(null);
+  if (n < period) return out;
+  const k = 2 / (period + 1);
+  let seed = 0;
+  for (let i = 0; i < period; i++) seed += values[i];
+  let prev = seed / period;
+  out[period - 1] = prev;
+  for (let i = period; i < n; i++) {
+    prev = values[i] * k + prev * (1 - k);
+    out[i] = prev;
+  }
+  return out;
+}
+
+/**
+ * Weighted moving average (linear weights 1..period).
+ * @param {ArrayLike<number>} values @param {number} period
+ * @returns {Array<number|null>}
+ */
+export function wma(values, period) {
+  const n = values.length;
+  const out = new Array(n).fill(null);
+  const denom = (period * (period + 1)) / 2;
+  for (let i = period - 1; i < n; i++) {
+    let acc = 0;
+    for (let j = 0; j < period; j++) acc += values[i - period + 1 + j] * (j + 1);
+    out[i] = acc / denom;
+  }
+  return out;
+}
+
+/**
+ * MACD: line = EMA(fast) − EMA(slow), signal = EMA(line, signalPeriod),
+ * histogram = line − signal. Each is an aligned array.
+ * @param {ArrayLike<number>} values
+ * @param {number} [fast] @param {number} [slow] @param {number} [signalPeriod]
+ * @returns {{ macd: Array<number|null>, signal: Array<number|null>, histogram: Array<number|null> }}
+ */
+export function macd(values, fast = 12, slow = 26, signalPeriod = 9) {
+  const ef = ema(values, fast);
+  const es = ema(values, slow);
+  const line = ef.map((v, i) => (v !== null && es[i] !== null ? v - es[i] : null));
+  // signal EMA runs over the defined tail of the MACD line
+  const defined = line.filter((v) => v !== null);
+  const startIdx = line.findIndex((v) => v !== null);
+  const sig = ema(defined, signalPeriod);
+  const signal = new Array(values.length).fill(null);
+  for (let i = 0; i < sig.length; i++) {
+    if (sig[i] !== null) signal[startIdx + i] = sig[i];
+  }
+  const histogram = line.map((v, i) => (v !== null && signal[i] !== null ? v - signal[i] : null));
+  return { macd: line, signal, histogram };
+}
+
+/**
+ * Relative Strength Index (Wilder's smoothing).
+ * @param {ArrayLike<number>} values @param {number} [period]
+ * @returns {Array<number|null>}
+ */
+export function rsi(values, period = 14) {
+  const n = values.length;
+  const out = new Array(n).fill(null);
+  if (n <= period) return out;
+  let gain = 0;
+  let loss = 0;
+  for (let i = 1; i <= period; i++) {
+    const ch = values[i] - values[i - 1];
+    if (ch >= 0) gain += ch; else loss -= ch;
+  }
+  let avgGain = gain / period;
+  let avgLoss = loss / period;
+  out[period] = avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss);
+  for (let i = period + 1; i < n; i++) {
+    const ch = values[i] - values[i - 1];
+    const g = ch >= 0 ? ch : 0;
+    const l = ch < 0 ? -ch : 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;
+}
+
+/**
+ * Bollinger Bands (population standard deviation).
+ * @param {ArrayLike<number>} values @param {number} [period] @param {number} [k]
+ * @returns {{ middle: Array<number|null>, upper: Array<number|null>, lower: Array<number|null> }}
+ */
+export function bollinger(values, period = 20, k = 2) {
+  const n = values.length;
+  const middle = sma(values, period);
+  const upper = new Array(n).fill(null);
+  const lower = new Array(n).fill(null);
+  for (let i = period - 1; i < n; i++) {
+    const mean = middle[i];
+    let variance = 0;
+    for (let j = i - period + 1; j <= i; j++) variance += (values[j] - mean) ** 2;
+    const sd = Math.sqrt(variance / period);
+    upper[i] = mean + k * sd;
+    lower[i] = mean - k * sd;
+  }
+  return { middle, upper, lower };
+}
+
+/**
+ * Stochastic oscillator (%K and its %D moving average).
+ * @param {ArrayLike<number>} high @param {ArrayLike<number>} low @param {ArrayLike<number>} close
+ * @param {number} [kPeriod] @param {number} [dPeriod]
+ * @returns {{ k: Array<number|null>, d: Array<number|null> }}
+ */
+export function stochastic(high, low, close, kPeriod = 14, dPeriod = 3) {
+  const n = close.length;
+  const k = new Array(n).fill(null);
+  for (let i = kPeriod - 1; i < n; i++) {
+    let hh = -Infinity;
+    let ll = Infinity;
+    for (let j = i - kPeriod + 1; j <= i; j++) {
+      if (high[j] > hh) hh = high[j];
+      if (low[j] < ll) ll = low[j];
+    }
+    k[i] = hh === ll ? 100 : (100 * (close[i] - ll)) / (hh - ll);
+  }
+  const kDefined = k.filter((v) => v !== null);
+  const start = k.findIndex((v) => v !== null);
+  const dTail = sma(kDefined, dPeriod);
+  const d = new Array(n).fill(null);
+  for (let i = 0; i < dTail.length; i++) if (dTail[i] !== null) d[start + i] = dTail[i];
+  return { k, d };
+}
+
+/**
+ * Average True Range (Wilder's smoothing).
+ * @param {ArrayLike<number>} high @param {ArrayLike<number>} low @param {ArrayLike<number>} close
+ * @param {number} [period]
+ * @returns {Array<number|null>}
+ */
+export function atr(high, low, close, period = 14) {
+  const n = close.length;
+  const out = new Array(n).fill(null);
+  if (n <= period) return out;
+  const tr = new Array(n);
+  tr[0] = high[0] - low[0];
+  for (let i = 1; i < n; i++) {
+    tr[i] = Math.max(
+      high[i] - low[i],
+      Math.abs(high[i] - close[i - 1]),
+      Math.abs(low[i] - close[i - 1]),
+    );
+  }
+  let acc = 0;
+  for (let i = 1; i <= period; i++) acc += tr[i];
+  let prev = acc / period;
+  out[period] = prev;
+  for (let i = period + 1; i < n; i++) {
+    prev = (prev * (period - 1) + tr[i]) / period;
+    out[i] = prev;
+  }
+  return out;
+}
+
+/**
+ * Rate of change (percent) over `period`.
+ * @param {ArrayLike<number>} values @param {number} [period]
+ * @returns {Array<number|null>}
+ */
+export function roc(values, period = 12) {
+  const n = values.length;
+  const out = new Array(n).fill(null);
+  for (let i = period; i < n; i++) {
+    const base = values[i - period];
+    out[i] = base === 0 ? null : (100 * (values[i] - base)) / base;
+  }
+  return out;
+}