tradelab 1.0.1 → 1.1.0

package/docs/superpowers/plans/2026-02-indicator-library.md

@@ -0,0 +1,677 @@
+# Indicator Library (`tradelab/ta`) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a real technical-analysis namespace (`tradelab/ta`) with RSI, MACD, Bollinger Bands, VWAP, Supertrend, Donchian, Keltner, and Stochastics, plus re-exports of the existing `ema`/`atr`/swing helpers.
+
+**Architecture:** One module per indicator family under `src/ta/`, aggregated by `src/ta/index.js`. Every indicator returns a **full-length array aligned to the input** (warmup region filled with `undefined` or the seed value, matching the existing `atr` convention) so values index 1:1 with candles inside `signal()`. Indicators consume either a `number[]` of closes (oscillators) or the candle array (range-based). A new subpath export `tradelab/ta` is added.
+
+**Tech Stack:** Node ESM, `node:test`. No new dependencies.
+
+---
+
+### Task 1: Scaffold the `ta` subpath
+
+**Files:**
+
+- Create: `src/ta/index.js`
+- Modify: `package.json` (exports map + files)
+- Modify: `scripts/build-cjs.mjs` (add `ta` bundle)
+- Test: `test/ta/scaffold.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// test/ta/scaffold.test.js
+import test from "node:test";
+import assert from "node:assert/strict";
+import * as ta from "../../src/ta/index.js";
+
+test("ta namespace re-exports existing ema and atr", () => {
+  assert.equal(typeof ta.ema, "function");
+  assert.equal(typeof ta.atr, "function");
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/ta/scaffold.test.js`
+Expected: FAIL — cannot find module `../../src/ta/index.js`.
+
+- [ ] **Step 3: Create src/ta/index.js**
+
+```js
+// src/ta/index.js
+export {
+  ema,
+  atr,
+  swingHigh,
+  swingLow,
+  detectFVG,
+  lastSwing,
+  structureState,
+} from "../utils/indicators.js";
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `node --test test/ta/scaffold.test.js`
+Expected: PASS.
+
+- [ ] **Step 5: Add the subpath to package.json**
+
+In the `exports` object, after the `"./live"` block, add:
+
+```json
+    "./ta": {
+      "types": "./types/ta.d.ts",
+      "import": "./src/ta/index.js",
+      "require": "./dist/cjs/ta.cjs"
+    },
+```
+
+- [ ] **Step 6: Add the ta bundle to scripts/build-cjs.mjs**
+
+Open `scripts/build-cjs.mjs`, find the array/list of entry points it bundles
+(the existing `index`, `data`, `live` entries), and add a `ta` entry mirroring
+the `live` one. For example, if entries look like:
+
+```js
+const entries = [
+  { in: "src/index.js", out: "dist/cjs/index.cjs" },
+  { in: "src/data/index.js", out: "dist/cjs/data.cjs" },
+  { in: "src/live/index.js", out: "dist/cjs/live.cjs" },
+];
+```
+
+add:
+
+```js
+  { in: "src/ta/index.js", out: "dist/cjs/ta.cjs" },
+```
+
+(If the file uses a different shape, follow that shape — the requirement is one
+esbuild output `dist/cjs/ta.cjs` from `src/ta/index.js`.)
+
+- [ ] **Step 7: Verify the build produces the bundle**
+
+Run: `npm run build`
+Expected: exit 0; `dist/cjs/ta.cjs` now exists. Confirm with `ls dist/cjs/ta.cjs`.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/ta/index.js test/ta/scaffold.test.js package.json scripts/build-cjs.mjs
+git commit -m "feat: scaffold tradelab/ta subpath
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: Oscillators — RSI, Stochastics, MACD
+
+**Files:**
+
+- Create: `src/ta/oscillators.js`
+- Modify: `src/ta/index.js`
+- Test: `test/ta/oscillators.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// test/ta/oscillators.test.js
+import test from "node:test";
+import assert from "node:assert/strict";
+import { rsi, stochastic, macd } from "../../src/ta/oscillators.js";
+
+test("rsi of a strictly rising series approaches 100", () => {
+  const closes = Array.from({ length: 30 }, (_, i) => 100 + i);
+  const out = rsi(closes, 14);
+  assert.equal(out.length, closes.length);
+  assert.equal(out[5], undefined); // warmup
+  assert.ok(out[29] > 99);
+});
+
+test("rsi of a strictly falling series approaches 0", () => {
+  const closes = Array.from({ length: 30 }, (_, i) => 100 - i);
+  const out = rsi(closes, 14);
+  assert.ok(out[29] < 1);
+});
+
+test("macd returns aligned macd/signal/histogram arrays", () => {
+  const closes = Array.from({ length: 60 }, (_, i) => 100 + Math.sin(i / 3) * 5);
+  const out = macd(closes, 12, 26, 9);
+  assert.equal(out.macd.length, closes.length);
+  assert.equal(out.signal.length, closes.length);
+  assert.equal(out.histogram.length, closes.length);
+  assert.ok(Number.isFinite(out.macd[59]));
+});
+
+test("stochastic %K stays within [0,100]", () => {
+  const bars = Array.from({ length: 40 }, (_, i) => ({
+    high: 101 + Math.sin(i),
+    low: 99 + Math.sin(i),
+    close: 100 + Math.sin(i) * 0.5,
+  }));
+  const out = stochastic(bars, 14, 3);
+  const k = out.k[39];
+  assert.ok(k >= 0 && k <= 100);
+  assert.equal(out.d.length, bars.length);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/ta/oscillators.test.js`
+Expected: FAIL — cannot find module.
+
+- [ ] **Step 3: Implement src/ta/oscillators.js**
+
+```js
+// src/ta/oscillators.js
+import { ema } from "../utils/indicators.js";
+
+/**
+ * Wilder's RSI. Returns a full-length array; warmup positions are `undefined`.
+ */
+export function rsi(closes, period = 14) {
+  const out = new Array(closes.length).fill(undefined);
+  if (closes.length <= period) return out;
+
+  let gainSum = 0;
+  let lossSum = 0;
+  for (let i = 1; i <= period; i += 1) {
+    const change = closes[i] - closes[i - 1];
+    if (change >= 0) gainSum += change;
+    else lossSum -= change;
+  }
+  let avgGain = gainSum / period;
+  let avgLoss = lossSum / period;
+  out[period] = avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss);
+
+  for (let i = period + 1; i < closes.length; i += 1) {
+    const change = closes[i] - closes[i - 1];
+    const gain = change > 0 ? change : 0;
+    const loss = change < 0 ? -change : 0;
+    avgGain = (avgGain * (period - 1) + gain) / period;
+    avgLoss = (avgLoss * (period - 1) + loss) / period;
+    out[i] = avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss);
+  }
+  return out;
+}
+
+/**
+ * MACD line, signal line, histogram. All full-length, aligned to input.
+ */
+export function macd(closes, fast = 12, slow = 26, signalPeriod = 9) {
+  const emaFast = ema(closes, fast);
+  const emaSlow = ema(closes, slow);
+  const macdLine = closes.map((_, i) => emaFast[i] - emaSlow[i]);
+  const signalLine = ema(macdLine, signalPeriod);
+  const histogram = macdLine.map((v, i) => v - signalLine[i]);
+  return { macd: macdLine, signal: signalLine, histogram };
+}
+
+/**
+ * Stochastic oscillator %K (smoothed close position in the high-low range) and
+ * %D (SMA of %K). `bars` need { high, low, close }.
+ */
+export function stochastic(bars, kPeriod = 14, dPeriod = 3) {
+  const k = new Array(bars.length).fill(undefined);
+  for (let i = kPeriod - 1; i < bars.length; i += 1) {
+    let hh = -Infinity;
+    let ll = Infinity;
+    for (let j = i - kPeriod + 1; j <= i; j += 1) {
+      if (bars[j].high > hh) hh = bars[j].high;
+      if (bars[j].low < ll) ll = bars[j].low;
+    }
+    const range = hh - ll;
+    k[i] = range === 0 ? 0 : ((bars[i].close - ll) / range) * 100;
+  }
+
+  const d = new Array(bars.length).fill(undefined);
+  for (let i = 0; i < bars.length; i += 1) {
+    if (i < kPeriod - 1 + dPeriod - 1) continue;
+    let sum = 0;
+    for (let j = i - dPeriod + 1; j <= i; j += 1) sum += k[j];
+    d[i] = sum / dPeriod;
+  }
+  return { k, d };
+}
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `node --test test/ta/oscillators.test.js`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Re-export from src/ta/index.js**
+
+Append to `src/ta/index.js`:
+
+```js
+export { rsi, macd, stochastic } from "./oscillators.js";
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/ta/oscillators.js src/ta/index.js test/ta/oscillators.test.js
+git commit -m "feat: add rsi, macd, stochastic to ta
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: Bands & channels — Bollinger, Donchian, Keltner
+
+**Files:**
+
+- Create: `src/ta/channels.js`
+- Modify: `src/ta/index.js`
+- Test: `test/ta/channels.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// test/ta/channels.test.js
+import test from "node:test";
+import assert from "node:assert/strict";
+import { bollinger, donchian, keltner } from "../../src/ta/channels.js";
+
+test("bollinger middle equals SMA and band width scales with stddev mult", () => {
+  const closes = Array.from({ length: 30 }, (_, i) => 100 + (i % 2 === 0 ? 1 : -1));
+  const out = bollinger(closes, 20, 2);
+  assert.equal(out.middle.length, closes.length);
+  const i = 25;
+  assert.ok(out.upper[i] > out.middle[i]);
+  assert.ok(out.lower[i] < out.middle[i]);
+  assert.ok(Math.abs(out.upper[i] - out.middle[i] - (out.middle[i] - out.lower[i])) < 1e-9);
+});
+
+test("donchian upper is the rolling high and lower is the rolling low", () => {
+  const bars = Array.from({ length: 25 }, (_, i) => ({
+    high: 100 + i,
+    low: 90 + i,
+    close: 95 + i,
+  }));
+  const out = donchian(bars, 20);
+  const i = 24;
+  assert.equal(out.upper[i], 100 + 24);
+  assert.equal(out.lower[i], 90 + 5);
+});
+
+test("keltner band is centered on EMA with ATR-scaled width", () => {
+  const bars = Array.from({ length: 40 }, (_, i) => ({
+    high: 101 + i * 0.1,
+    low: 99 + i * 0.1,
+    close: 100 + i * 0.1,
+  }));
+  const out = keltner(bars, 20, 14, 2);
+  const i = 39;
+  assert.ok(out.upper[i] > out.middle[i]);
+  assert.ok(out.lower[i] < out.middle[i]);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/ta/channels.test.js`
+Expected: FAIL — cannot find module.
+
+- [ ] **Step 3: Implement src/ta/channels.js**
+
+```js
+// src/ta/channels.js
+import { ema, atr } from "../utils/indicators.js";
+
+function rollingMean(values, period, i) {
+  let sum = 0;
+  for (let j = i - period + 1; j <= i; j += 1) sum += values[j];
+  return sum / period;
+}
+
+/**
+ * Bollinger Bands. `mult` standard deviations around the SMA middle band.
+ */
+export function bollinger(closes, period = 20, mult = 2) {
+  const middle = new Array(closes.length).fill(undefined);
+  const upper = new Array(closes.length).fill(undefined);
+  const lower = new Array(closes.length).fill(undefined);
+  for (let i = period - 1; i < closes.length; i += 1) {
+    const avg = rollingMean(closes, period, i);
+    let variance = 0;
+    for (let j = i - period + 1; j <= i; j += 1) variance += (closes[j] - avg) ** 2;
+    const sd = Math.sqrt(variance / period);
+    middle[i] = avg;
+    upper[i] = avg + mult * sd;
+    lower[i] = avg - mult * sd;
+  }
+  return { middle, upper, lower };
+}
+
+/**
+ * Donchian channel: rolling highest-high / lowest-low over `period` bars.
+ */
+export function donchian(bars, period = 20) {
+  const upper = new Array(bars.length).fill(undefined);
+  const lower = new Array(bars.length).fill(undefined);
+  const middle = new Array(bars.length).fill(undefined);
+  for (let i = period - 1; i < bars.length; i += 1) {
+    let hh = -Infinity;
+    let ll = Infinity;
+    for (let j = i - period + 1; j <= i; j += 1) {
+      if (bars[j].high > hh) hh = bars[j].high;
+      if (bars[j].low < ll) ll = bars[j].low;
+    }
+    upper[i] = hh;
+    lower[i] = ll;
+    middle[i] = (hh + ll) / 2;
+  }
+  return { upper, lower, middle };
+}
+
+/**
+ * Keltner channel: EMA middle, +/- mult * ATR width.
+ */
+export function keltner(bars, emaPeriod = 20, atrPeriod = 14, mult = 2) {
+  const closes = bars.map((b) => b.close);
+  const mid = ema(closes, emaPeriod);
+  const range = atr(bars, atrPeriod);
+  const upper = new Array(bars.length).fill(undefined);
+  const lower = new Array(bars.length).fill(undefined);
+  const middle = new Array(bars.length).fill(undefined);
+  for (let i = 0; i < bars.length; i += 1) {
+    if (range[i] === undefined) continue;
+    middle[i] = mid[i];
+    upper[i] = mid[i] + mult * range[i];
+    lower[i] = mid[i] - mult * range[i];
+  }
+  return { upper, lower, middle };
+}
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `node --test test/ta/channels.test.js`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Re-export**
+
+Append to `src/ta/index.js`:
+
+```js
+export { bollinger, donchian, keltner } from "./channels.js";
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/ta/channels.js src/ta/index.js test/ta/channels.test.js
+git commit -m "feat: add bollinger, donchian, keltner to ta
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: Trend & volume — Supertrend, VWAP
+
+**Files:**
+
+- Create: `src/ta/trend.js`
+- Modify: `src/ta/index.js`
+- Test: `test/ta/trend.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// test/ta/trend.test.js
+import test from "node:test";
+import assert from "node:assert/strict";
+import { supertrend, vwap } from "../../src/ta/trend.js";
+
+test("supertrend marks an uptrend (dir=1) on a rising series", () => {
+  const bars = Array.from({ length: 40 }, (_, i) => ({
+    high: 101 + i,
+    low: 99 + i,
+    close: 100 + i,
+  }));
+  const out = supertrend(bars, 10, 3);
+  assert.equal(out.direction.length, bars.length);
+  assert.equal(out.direction[39], 1);
+  assert.ok(out.line[39] < bars[39].close); // support trails below price
+});
+
+test("vwap resets each UTC day and lies within the day's range", () => {
+  const day1 = Date.UTC(2025, 0, 2, 14, 30);
+  const day2 = Date.UTC(2025, 0, 3, 14, 30);
+  const bars = [
+    { time: day1, high: 102, low: 98, close: 100, volume: 10 },
+    { time: day1 + 60000, high: 104, low: 100, close: 103, volume: 30 },
+    { time: day2, high: 50, low: 48, close: 49, volume: 5 },
+  ];
+  const out = vwap(bars);
+  assert.equal(out.length, 3);
+  assert.ok(out[1] >= 98 && out[1] <= 104);
+  // day2 resets: vwap equals the typical price of the single day-2 bar
+  assert.ok(Math.abs(out[2] - (50 + 48 + 49) / 3) < 1e-9);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/ta/trend.test.js`
+Expected: FAIL — cannot find module.
+
+- [ ] **Step 3: Implement src/ta/trend.js**
+
+```js
+// src/ta/trend.js
+import { atr } from "../utils/indicators.js";
+
+/**
+ * Supertrend. Returns { line, direction } full-length.
+ * direction: 1 = uptrend (line is support below price), -1 = downtrend.
+ */
+export function supertrend(bars, period = 10, mult = 3) {
+  const range = atr(bars, period);
+  const line = new Array(bars.length).fill(undefined);
+  const direction = new Array(bars.length).fill(undefined);
+
+  let prevUpper = Infinity;
+  let prevLower = -Infinity;
+  let prevDir = 1;
+
+  for (let i = 0; i < bars.length; i += 1) {
+    if (range[i] === undefined) continue;
+    const mid = (bars[i].high + bars[i].low) / 2;
+    const basicUpper = mid + mult * range[i];
+    const basicLower = mid - mult * range[i];
+    const close = bars[i].close;
+    const prevClose = i > 0 ? bars[i - 1].close : close;
+
+    const upper = basicUpper < prevUpper || prevClose > prevUpper ? basicUpper : prevUpper;
+    const lower = basicLower > prevLower || prevClose < prevLower ? basicLower : prevLower;
+
+    let dir = prevDir;
+    if (prevDir === 1 && close < lower) dir = -1;
+    else if (prevDir === -1 && close > upper) dir = 1;
+
+    line[i] = dir === 1 ? lower : upper;
+    direction[i] = dir;
+
+    prevUpper = upper;
+    prevLower = lower;
+    prevDir = dir;
+  }
+  return { line, direction };
+}
+
+function dayKeyUTC(timeMs) {
+  const d = new Date(timeMs);
+  return d.getUTCFullYear() * 10000 + (d.getUTCMonth() + 1) * 100 + d.getUTCDate();
+}
+
+/**
+ * Session VWAP, reset on each UTC calendar day. `bars` need
+ * { time, high, low, close, volume }. When volume is missing/zero, falls back
+ * to an unweighted cumulative typical-price average for that day.
+ */
+export function vwap(bars) {
+  const out = new Array(bars.length).fill(undefined);
+  let currentDay = null;
+  let cumPV = 0;
+  let cumV = 0;
+  let cumTP = 0;
+  let count = 0;
+
+  for (let i = 0; i < bars.length; i += 1) {
+    const day = dayKeyUTC(bars[i].time);
+    if (day !== currentDay) {
+      currentDay = day;
+      cumPV = 0;
+      cumV = 0;
+      cumTP = 0;
+      count = 0;
+    }
+    const tp = (bars[i].high + bars[i].low + bars[i].close) / 3;
+    const vol = Number.isFinite(bars[i].volume) ? bars[i].volume : 0;
+    cumPV += tp * vol;
+    cumV += vol;
+    cumTP += tp;
+    count += 1;
+    out[i] = cumV > 0 ? cumPV / cumV : cumTP / count;
+  }
+  return out;
+}
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `node --test test/ta/trend.test.js`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Re-export**
+
+Append to `src/ta/index.js`:
+
+```js
+export { supertrend, vwap } from "./trend.js";
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/ta/trend.js src/ta/index.js test/ta/trend.test.js
+git commit -m "feat: add supertrend and session vwap to ta
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Types + docs + README mention
+
+**Files:**
+
+- Create: `types/ta.d.ts`
+- Modify: `docs/api-reference.md`
+- Modify: `README.md` (mention the `ta` subpath under importing)
+
+- [ ] **Step 1: Write the type declaration file**
+
+```ts
+// types/ta.d.ts
+export type Candle = {
+  time: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+};
+
+export function ema(values: number[], period?: number): number[];
+export function atr(bars: Candle[], period?: number): (number | undefined)[];
+export function rsi(closes: number[], period?: number): (number | undefined)[];
+export function macd(
+  closes: number[],
+  fast?: number,
+  slow?: number,
+  signalPeriod?: number
+): { macd: number[]; signal: number[]; histogram: number[] };
+export function stochastic(
+  bars: Candle[],
+  kPeriod?: number,
+  dPeriod?: number
+): { k: (number | undefined)[]; d: (number | undefined)[] };
+export function bollinger(
+  closes: number[],
+  period?: number,
+  mult?: number
+): { middle: (number | undefined)[]; upper: (number | undefined)[]; lower: (number | undefined)[] };
+export function donchian(
+  bars: Candle[],
+  period?: number
+): { upper: (number | undefined)[]; lower: (number | undefined)[]; middle: (number | undefined)[] };
+export function keltner(
+  bars: Candle[],
+  emaPeriod?: number,
+  atrPeriod?: number,
+  mult?: number
+): { upper: (number | undefined)[]; lower: (number | undefined)[]; middle: (number | undefined)[] };
+export function supertrend(
+  bars: Candle[],
+  period?: number,
+  mult?: number
+): { line: (number | undefined)[]; direction: (number | undefined)[] };
+export function vwap(bars: Candle[]): (number | undefined)[];
+```
+
+- [ ] **Step 2: Typecheck**
+
+Run: `npm run typecheck`
+Expected: exit 0 (no errors introduced).
+
+- [ ] **Step 3: Document in docs/api-reference.md**
+
+Add a `### tradelab/ta` section listing each indicator, its input shape (closes
+array vs candle array), and its return shape — copy the signatures from
+`types/ta.d.ts` and add one line per indicator describing what it computes.
+
+- [ ] **Step 4: Mention in README importing section**
+
+Under `## Importing` → `### ESM`, add:
+
+```js
+import { rsi, macd, bollinger, vwap, supertrend } from "tradelab/ta";
+```
+
+and the CJS equivalent under `### CommonJS`.
+
+- [ ] **Step 5: Full build + test + lint, then commit**
+
+```bash
+npm run build && npm run lint && npm run format:check && npm test
+```
+
+Expected: all green.
+
+```bash
+git add types/ta.d.ts docs/api-reference.md README.md
+git commit -m "docs: document tradelab/ta indicator namespace
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Self-review checklist
+
+- [ ] Every indicator returns a full-length array/object aligned to the input (warmup = `undefined`), matching the existing `atr` convention so `signal()` can index by candle position. ✔
+- [ ] `tradelab/ta` resolves in ESM (`exports` map), CJS (`dist/cjs/ta.cjs` from build), and types (`types/ta.d.ts`). ✔ (Tasks 1, 5)
+- [ ] No existing export in `src/utils/indicators.js` changed — `ta` re-exports them. ✔
+- [ ] Signatures in `types/ta.d.ts` match the implementations (e.g. `macd` returns `{ macd, signal, histogram }`, `stochastic` returns `{ k, d }`). ✔