@alphacharts/indicators 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alphabench
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @alphacharts/indicators
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Technical studies for alphacharts: a typed study model, an incremental engine over the core's
+columnar data, a Web Worker runner, chart integration through the core plugin API, and
+211 studies (TA-Lib's catalogue plus TradingView's built-ins).
+
+## Use
+
+```ts
+import { addStudy } from "@alphacharts/indicators";
+import { rsi, macd, bbands } from "@alphacharts/indicators/studies"; // import only what you use
+
+const bb = addStudy(chart, candles, bbands, { length: 20 });               // overlay on the candles' pane
+const r = addStudy(chart, candles, rsi, { length: 14 });                   // own pane
+addStudy(chart, candles, "obv", {}, { volume: volumeSeries });            // by id: needs registerAllStudies()
+r.setInputs({ length: 21 }); r.setVisible(false); r.remove();              // re-parameterise, hide, remove
+chart.saveState(); chart.restoreState(saved);                               // studies are in the layout (installStudies(chart) first on a fresh chart)
+```
+
+`addStudy` throws on an unknown input, a value outside min/max/step type, or a source that lacks what the
+study needs (volume, OHLC). `await study.ready()` resolves when the last computation is on the chart.
+Subpaths: `.` (engine, runner, plugin), `./studies` (every study as a named export), `./all`
+(`ALL_STUDIES`, `registerAllStudies`), `./worker` (worker entry). Studies are plain objects in group modules
+(`src/studies/*.ts`), so a bundler keeps only those imported (one module per family rather than per study).
+
+## How it works
+
+- **Model** (`src/types.ts`): `StudyDef { id, name, family, inputs (int/float/bool/source/select with default, min, max,
+  step, options), needs, pane: overlay|new, columns, plots (line, histogram, area, band, fill, hline, markers, zigzag),
+  build }`. `build(graph, params)` declares nodes and returns the output columns.
+- **Engine** (`src/engine/graph.ts`): every value lives in a Float64Array column; a node writes only bar `i` and reads
+  `<= i` of its inputs and `<= i-1` of its own columns. So one code path is the batch (`run(0, n)`), an appended bar
+  (`run(n, n+1)`) and a tick revision (re-`run(n-1, n)`): per-bar cost does not depend on the series length
+  (O(1) for recursive and running-sum nodes, O(period) for window scans), and a revision recomputes from committed
+  state. Warm-up is NaN; absent values never become 0 (except where TA-Lib defines 0, noted in the study's reference).
+  setData/prepend on the source recompute fully.
+- **Runner** (`src/runner.ts`): `createRunner(ids, factory)` gives a `WorkerRunner` on the worker `factory` makes (the host's bundler spells the worker URL out; the package never guesses it) (arrays transferred, chunks of 65,536
+  bars so a `cancel` is serviced within a chunk; protocol documented in the file header) or the `InlineRunner`
+  when no factory is given or the worker would not start. The worker returns every graph column; the main thread adopts them and keeps
+  streaming ticks. Studies not built in (defined at runtime) run inline (`canRun`).
+- **Chart integration** (`src/chart/studies.ts`): one core series per drawn plot (pane = the source's for overlays,
+  the lowest free pane otherwise), the rest drawn on the overlay (fills, markers, ZigZag, lines shifted back in time
+  or joined across gaps; these do not take part in autoscale). Layout JSON is keyed by study instance id.
+- **Outside series** (`src/engine/feed.ts`, `Study.setFeed` / `pushFeedBar`): a study can read bars the host gives it (another
+  instrument, another timeframe). Each is a graph of its own on its own bars; the study's graph reads it through a join by time
+  (`Graph.joined` / `external`): `"same"` is the bar with exactly the study bar's time, else NaN, `"closed"` the latest bar whose
+  open + length is not after the study bar's start (no value contains data from after its bar, and the live bar sees the last finished one).
+  Lookups walk forward from the last answer, so a run and a tick are O(1) amortised; `StudyEngine.pushFeed` re-evaluates the last bar only
+  when it sees a different row. Runners: `RunRequest.feeds`, `StudyRunner.feedBar`.
+- **Bar colours, background shading, per-point line colour, left axis** (`src/chart/studies.ts`): `barcolor` plots colour the source's candles
+  (core `Series.setBarColors`; several studies compose on one source, the latest wins, removal restores exactly), `bgcolor` plots draw through core's
+  `BarShading` primitive (no part in autoscale), a line plot's `colorBy: { col, color }` colours its segments per bar, `StudyDef.scale: "left"`
+  puts the series on the left axis.
+- **WASM** (`src/engine/kernels.ts`, `enableWasm()` from `src/wasm.ts`): optional batch kernels from `@alphacharts/wasm`
+  for running sum, variance/stddev, rolling highest/lowest (+ bars) and linear regression, the kernels that won at 1M
+  and 10M bars in its benchmark. They are bit-identical to the JS loops (test/wasm.test.ts runs every study both
+  ways). Not used: EMA/RMA/WMA (no win), chunked runs (worker), series under 4,096 bars.
+
+## Verification
+
+Run `pnpm -C packages/indicators test`.
+- **TA-Lib** (`test/talib.test.ts`; `atr` and `natr` are not here, see below): fixtures generated offline by `scripts/gen_fixtures.py` (TA-Lib 0.8.2 in a
+  Python venv, see below) from `fixtures/cases/*.json` on a seeded 400-bar OHLCV set (`fixtures/dataset.json`;
+  3,000 bars of mixed candle shapes for the patterns). Compared at 1e-9 relative (+1e-12 absolute floor), NaN positions
+  must be identical; patterns are integers compared exactly. Case flags: `lead` (our study has valid values earlier
+  than TA-Lib's first output, e.g. MACD's line before its signal), `abs` (a value that is numerical noise around 0).
+- **TradingView-only** studies: hand-computed fixtures with the arithmetic in the test comments, plus invariants
+  (`test/tv-*.test.ts`).
+- **Incremental == batch** (`test/incremental.test.ts`): every study, seeded random appends with random last-bar
+  revisions, exact equality.
+- Runner protocol, worker/inline parity and cancellation: `test/runner.test.ts`. Browser: `bench/tests/indicators.spec.ts`.
+
+Where a study is not TA-Lib's arithmetic it says so in its `reference` field. Known differences:
+`atr`/`natr` (and every ATR band: keltner, supertrend, chande-kroll-stop, median) are Wilder's: bar 0's true range is high - low and the first value is at bar `length - 1`, TA-Lib's skips bar 0 and starts one bar later (hand case and an independent loop in `test/atr.test.ts`; `trange` stays TA-Lib's); `rsi` (and `stochrsi`) report 100 where RS is 0/0, the first `length` changes all zero (TA-Lib: 0; charting packages: 100, `test/rsi-flat.test.ts`);
+MACD/APO/PPO seed like TA-Lib (fast EMA at the slow EMA's first bar), TradingView seeds at bar 0 (gap < 1e-9 after
+~150 bars); `cmo` defaults to TradingView's window-sum form (`method: "wilder"` is TA-Lib's); the linear regression
+studies are TA-Lib's (checked against numpy polyfit); `ht-trendmode` reports TA-Lib's 0 inside its warm-up;
+`mavp` (TA-Lib's moving average with a per-bar period series) is not implemented: it needs a second input series.
+Not checked against TradingView itself (no access): the TradingView-only studies follow the definitions cited in their
+`reference` field; pivot formulas, Klinger, Schaff, the Relative Volatility form and Fractals tie rules were written
+from memory of TradingView's scripts and are verified only by the hand-computed tests.
+
+## Studies (211)
+
+- **Overlap (TA-Lib + MAs, bands, SAR)** (17): `sma`, `ema`, `wma`, `dema`, `tema`, `trima`, `kama`, `t3`, `ma`, `bbands`, `bbpb`, `bbw`, `midpoint`, `midprice`, `mama`, `sar`, `sarext`
+- **Momentum (TA-Lib)** (30): `rsi`, `cmo`, `mom`, `roc`, `rocp`, `rocr`, `rocr100`, `trix`, `apo`, `ppo`, `macd`, `macdfix`, `macdext`, `stoch`, `stochf`, `stochrsi`, `willr`, `cci`, `bop`, `mfi`, `ultosc`, `aroon`, `aroonosc`, `adx`, `adxr`, `dx`, `plus-di`, `minus-di`, `plus-dm`, `minus-dm`
+- **Volume (TA-Lib)** (3): `ad`, `adosc`, `obv`
+- **Volatility** (3): `trange` (TA-Lib's), `atr`, `natr` (Wilder's, not TA-Lib's)
+- **Price transforms (TA-Lib)** (4): `avgprice`, `medprice`, `typprice`, `wclprice`
+- **Statistics (TA-Lib)** (9): `linearreg`, `linearreg-slope`, `linearreg-intercept`, `linearreg-angle`, `tsf`, `stddev`, `var`, `correl`, `beta`
+- **Math transforms and operators (TA-Lib)** (26): `acos`, `asin`, `atan`, `ceil`, `cos`, `cosh`, `exp`, `floor`, `ln`, `log10`, `sin`, `sinh`, `sqrt`, `tan`, `tanh`, `add`, `sub`, `mult`, `div`, `max`, `min`, `sum`, `maxindex`, `minindex`, `minmax`, `minmaxindex`
+- **Cycle / Hilbert (TA-Lib)** (6): `ht-dcperiod`, `ht-dcphase`, `ht-phasor`, `ht-sine`, `ht-trendline`, `ht-trendmode`
+- **TradingView-only** (52): `smma`, `vwma`, `hma`, `alma`, `lsma`, `mcginley`, `ma-ribbon`, `ma-cross`, `envelopes`, `keltner`, `donchian`, `price-channel`, `chande-kroll-stop`, `linreg-channel`, `median`, `ichimoku`, `supertrend`, `alligator`, `fractals`, `zigzag`, `fisher`, `kst`, `tsi`, `vortex`, `coppock`, `connors-rsi`, `choppiness`, `rvi-vigor`, `rvi-volatility`, `smi-ergodic`, `rank-corr`, `bull-bear-power`, `awesome`, `accelerator`, `mass-index`, `dpo`, `schaff-tc`, `stoch-tv`, `volume`, `volume-osc`, `pvt`, `net-volume`, `elder-force`, `eom`, `chaikin-mf`, `klinger`, `vwap` (Session VWAP), `anchored-vwap`, `pivot-points`, `hist-vol`, `adr`, `bars-per-year`
+- **Candlestick patterns (TA-Lib CDL*)** (61): `cdl-<name>` for every TA-Lib pattern, e.g. `cdl-2crows`, `cdl-3blackcrows`, `cdl-3inside`, `cdl-3linestrike`, `cdl-3outside`, ...
+
+## Regenerating the TA-Lib fixtures
+
+Only needed when a case changes. From `packages/indicators`:
+
+```
+python -m venv .venv && . .venv/bin/activate
+pip install TA-Lib numpy        # TA-Lib needs the C library (brew install ta-lib)
+pnpm fixtures                   # python scripts/gen_fixtures.py [group ...]
+python scripts/gen_cdl_dataset.py   # only to rebuild fixtures/dataset-cdl.json
+```
+
+The fixtures are TA-Lib's output (BSD licence), see `NOTICE` at the repository root.

package/dist/all-_xzUPrL7.js

@@ -0,0 +1,21 @@
+import { $ as e, N as t, Nn as n, Nr as r, dn as i, er as a, f as o, fr as s, gr as c, ln as l, or as u, pn as d, ri as f } from "./tv-volume-BYSbfrVk.js";
+//#region src/studies/all.ts
+var p = (e) => typeof e == "object" && !!e && "build" in e && "columns" in e && "plots" in e, m = [
+	f,
+	r,
+	c,
+	s,
+	u,
+	a,
+	n,
+	d,
+	i,
+	l,
+	e,
+	t,
+	o
+].flatMap((e) => Object.values(e).filter(p));
+//#endregion
+export { m as t };
+
+//# sourceMappingURL=all-_xzUPrL7.js.map

package/dist/all-_xzUPrL7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"all-_xzUPrL7.js","names":["overlap","momentum","volume","volatility","price","statistic","math","cycle","sar","patterns","tvTrend","tvOsc","tvVolume","tv_trend_exports","tv_osc_exports","math_exports","momentum_exports","sar_exports","statistic_exports","tv_volume_exports","volatility_exports","volume_exports","patterns_exports","price_exports","cycle_exports","overlap_exports","isStudy","x","ALL_STUDIES","m"],"sources":["../src/studies/all.ts"],"sourcesContent":["// Every built-in study, collected from the group modules. Importing this pulls\n// them all in; import single studies from their group module to stay small.\n\nimport type { StudyDef } from \"../types.js\";\nimport * as overlap from \"./overlap.js\";\nimport * as momentum from \"./momentum.js\";\nimport * as volume from \"./volume.js\";\nimport * as volatility from \"./volatility.js\";\nimport * as price from \"./price.js\";\nimport * as statistic from \"./statistic.js\";\nimport * as math from \"./math.js\";\nimport * as cycle from \"./cycle.js\";\nimport * as sar from \"./sar.js\";\nimport * as patterns from \"./patterns.js\";\nimport * as tvTrend from \"./tv-trend.js\";\nimport * as tvOsc from \"./tv-osc.js\";\nimport * as tvVolume from \"./tv-volume.js\";\n\nconst isStudy = (x: unknown): x is StudyDef => typeof x === \"object\" && x !== null && \"build\" in x && \"columns\" in x && \"plots\" in x;\n\nexport const ALL_STUDIES: readonly StudyDef[] = [overlap, momentum, volume, volatility, price, statistic, math, cycle, sar, patterns, tvTrend, tvOsc, tvVolume].flatMap((m) =>\n  Object.values(m).filter(isStudy),\n);\n"],"mappings":";;AAkBA,IAAM0B,KAAW,MAA8B,OAAOC,KAAM,cAAYA,KAAc,WAAWA,KAAK,aAAaA,KAAK,WAAWA,GAEtHC,IAAmC;CAAC5B;CAASC;CAAUC;CAAQC;CAAYC;CAAOC;CAAWC;CAAMC;CAAOC;CAAKC;CAAUC;CAASC;CAAOC;AAAQ,CAAC,CAAC,SAAS,MACvK,OAAO,OAAOiB,CAAC,CAAC,CAAC,OAAOH,CAAO,CACjC"}

package/dist/all.js

@@ -0,0 +1,10 @@
+import { r as e } from "./registry-DdYYyZN_.js";
+import { t } from "./all-_xzUPrL7.js";
+//#region src/all.ts
+function n() {
+	e(t);
+}
+//#endregion
+export { t as ALL_STUDIES, n as registerAllStudies };
+
+//# sourceMappingURL=all.js.map

package/dist/all.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"all.js","names":["registerStudies","registerAllStudies","ALL_STUDIES"],"sources":["../src/all.ts"],"sourcesContent":["// Everything: the study list and a registrar. Importing this module pulls every\n// study in; import single studies from \"@alphacharts/indicators/studies\" to stay small.\nimport { registerStudies } from \"./registry.js\";\nimport { ALL_STUDIES } from \"./studies/all.js\";\n\nexport { ALL_STUDIES };\nexport function registerAllStudies(): void {\n  registerStudies(ALL_STUDIES);\n}\n"],"mappings":";;;AAMA,SAAgBC,IAA2B;CACzC,EAAgBC,CAAW;AAC7B"}