ta-crypto 0.1.5 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026
-
-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.
+MIT License
+
+Copyright (c) 2026
+
+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,157 +1,300 @@
-# ta-crypto
-
-[![npm version](https://img.shields.io/npm/v/ta-crypto.svg)](https://www.npmjs.com/package/ta-crypto)
-[![CI](https://github.com/TDamiao/ta-crypto/actions/workflows/ci.yml/badge.svg)](https://github.com/TDamiao/ta-crypto/actions/workflows/ci.yml)
-
-Technical analysis indicators for crypto markets in Node.js. Inspired by pandas-ta, but focused on crypto use-cases and Node-friendly APIs.
-
-## Features
-
-- Typed, lightweight indicators for OHLCV arrays
-- Crypto-specific extras like session VWAP, funding rate helpers, volatility regimes, and orderflow proxies
-- Functions return arrays aligned to input length with `null` for insufficient data
-
-## Install
-
-```bash
-npm i ta-crypto
-```
-
-## Quick Start
-
-```ts
-import {
-  ta,
-  sma,
-  rsi,
-  macd,
-  bbands,
-  atr,
-  vwap,
-  vwapSession,
-  realizedVolatility,
-  fundingRateCumulative,
-  volatilityRegime,
-  orderflowImbalance,
-  obv,
-  mfi,
-  stoch,
-  adx
-} from "ta-crypto";
-
-const close = [101, 102, 99, 105, 110, 108, 111];
-const open =  [100, 101, 100, 103, 108, 109, 110];
-const high =  [102, 103, 101, 106, 112, 110, 112];
-const low =   [ 99, 100,  98, 102, 107, 106, 109];
-const volume =[ 10,  12,  11,  15,  17,  14,  18];
-const session=[  1,   1,   1,   2,   2,   2,   3];
-
-const s = sma(close, 3);
-const r = rsi(close, 14);
-const m = macd(close);
-const b = bbands(close, 20, 2);
-const a = atr(high, low, close, 14);
-const v = vwap(high, low, close, volume);
-const vs = vwapSession(high, low, close, volume, session);
-const rv = realizedVolatility(close, 30, 365);
-const fr = fundingRateCumulative([0.0001, -0.0002, 0.00005]);
-const vr = volatilityRegime(close, 30, 365);
-const ofi = orderflowImbalance(open, close, volume, 20);
-const o = obv(close, volume);
-const moneyFlow = mfi(high, low, close, volume, 14);
-const st = stoch(high, low, close, 14, 3);
-const dx = adx(high, low, close, 14);
-
-const s2 = ta.sma(close, 3);
-```
-
-## API Conventions
-
-- Input arrays must be the same length.
-- Outputs are aligned to input length.
-- `null` marks periods with insufficient data.
-
-## Indicators
-
-Overlap:
-- `sma`, `ema`, `rma`, `hl2`, `hlc3`, `ohlc4`, `vwap`, `bbands`
-
-Momentum:
-- `rsi`, `macd`, `stoch`
-
-Volatility:
-- `trueRange`, `atr`, `natr`, `realizedVolatility`
-
-Performance:
-- `logReturn`, `percentReturn`
-
-Volume:
-- `obv`, `mfi`
-
-Trend:
-- `adx`
-
-Crypto:
-- `vwapSession`, `fundingRateCumulative`, `fundingRateAPR`, `volatilityRegime`, `signedVolume`, `volumeDelta`, `orderflowImbalance`
-
-## Crypto-Specific Notes
-
-Session VWAP:
-- Provide a `session` array with an id per candle. VWAP resets on each new session id.
-
-Funding rate:
-- `fundingRateCumulative` sums periodic rates over time.
-- `fundingRateAPR` annualizes a periodic rate using `periodsPerYear`.
-
-Volatility regimes:
-- `volatilityRegime` computes realized volatility and returns -1, 0, or 1 based on z-score thresholds.
-
-Orderflow proxies:
-- `signedVolume`, `volumeDelta`, and `orderflowImbalance` infer buy/sell pressure from candle direction.
-
-## Release
-
-Automated npm publish runs on tag push. Steps:
-
-1. Ensure `NPM_TOKEN` is set in GitHub Actions secrets.
-   - For GitHub Packages, set `GITHUB_TOKEN` (already provided) or a PAT if needed.
-2. Update changelog (recommended):
-
-```bash
-npm run changelog
-```
-
-3. Bump version (optional):
-
-```bash
-npm run version:patch
-```
-
-4. Run:
-
-```bash
-npm run release
-```
-
-Or do everything in one step:
-
-```bash
-npm run release:patch
-```
-
-GitHub Packages:
-- A separate workflow publishes `@TDamiao/ta-crypto` to GitHub Packages on the same tag.
-
-This creates and pushes a tag like `v0.1.1`, triggering the release workflow.
-
-## License
-
-MIT
-
-## GitHub Packages
-
-Install from GitHub Packages:
-
-```bash
-npm i @TDamiao/ta-crypto
-```
+# ta-crypto
+
+[![npm version](https://img.shields.io/npm/v/ta-crypto.svg)](https://www.npmjs.com/package/ta-crypto)
+[![CI](https://github.com/TDamiao/ta-crypto/actions/workflows/ci.yml/badge.svg)](https://github.com/TDamiao/ta-crypto/actions/workflows/ci.yml)
+
+Technical analysis indicators for crypto markets in Node.js.
+
+## Install
+
+```bash
+npm i ta-crypto
+```
+
+## Quick Start
+
+```ts
+import { sma, rsi, macd, bbands, atr, vwapSession, toOHLCV } from "ta-crypto";
+
+const candles = [
+  { open: 100, high: 102, low: 99, close: 101, volume: 10, time: 1 },
+  { open: 101, high: 103, low: 100, close: 102, volume: 12, time: 2 }
+];
+
+const { high, low, close, volume } = toOHLCV(candles, 0);
+const s = sma(close, 14);
+const r = rsi(close, 14);
+const m = macd(close);
+const b = bbands(close, 20, 2);
+const a = atr(high, low, close, 14);
+const vs = vwapSession(high, low, close, volume, [1, 1]);
+```
+
+## Stateful API (streaming)
+
+```ts
+import { createSMA, createEMA, createRSI, createVWAPSession } from "ta-crypto";
+
+const sma14 = createSMA(14);
+const ema14 = createEMA(14);
+const rsi14 = createRSI(14);
+const nextSma = sma14.next(101.25);
+const nextEma = ema14.next(101.25);
+const nextRsi = rsi14.next(101.25);
+
+const vwap = createVWAPSession();
+const nextVwap = vwap.next({
+  high: 102,
+  low: 99,
+  close: 101,
+  volume: 10,
+  sessionId: "2026-02-10-asia"
+});
+```
+
+Websocket-like streaming loop:
+
+```ts
+import { createEMA, createRSI } from "ta-crypto";
+
+const ema21 = createEMA(21);
+const rsi14 = createRSI(14);
+
+ws.on("message", (tick) => {
+  const price = Number(tick.last);
+  const e = ema21.next(price);
+  const r = rsi14.next(price);
+  if (e !== null && r !== null) {
+    // strategy signal path
+  }
+});
+```
+
+## Examples
+
+Real-world entry points live in `examples/`:
+- `examples/rsi-strategy.ts`
+- `examples/vwap-session.ts`
+- `examples/funding-arbitrage.ts`
+
+If you're using ta-crypto in production or experiments, feel free to add your example here.
+
+## Compatibility
+
+`ta-crypto` now ships golden tests (`test/fixtures/golden.json`) to lock behavior across releases.
+
+Classic indicators:
+
+| Indicator | Reference | Tolerance |
+| --- | --- | --- |
+| SMA, EMA, RSI | Golden baseline | 1e-10 |
+| MACD, BBANDS | Golden baseline | 1e-10 |
+| ATR, ADX | Golden baseline | 1e-10 |
+
+Crypto indicators:
+
+| Indicator | Reference | Tolerance |
+| --- | --- | --- |
+| VWAP Session | Golden baseline | 1e-10 |
+| Stateful VWAP Session parity | Batch VWAP Session | 1e-10 |
+
+Streaming parity:
+
+| Indicator | Reference | Tolerance |
+| --- | --- | --- |
+| Stateful RSI(14) | Batch RSI(14) | 1e-10 |
+
+External parity:
+
+Policy source: `scripts/compat-policy.json`
+
+| Indicator | Burn-in | Tolerance | Blocking refs | Non-blocking refs |
+| --- | --- | --- | --- | --- |
+| SMA(14) | 14 | 1e-10 | TA-Lib, technicalindicators | pandas-ta |
+| EMA(14) | 14 | 1e-10 | TA-Lib, technicalindicators | pandas-ta |
+| RSI(14) | 28 | 5e-2 | TA-Lib, technicalindicators | pandas-ta |
+| MACD(12,26,9) | 80 | 2e-2 | TA-Lib, technicalindicators | pandas-ta |
+| BBANDS(20,2) | 20 | 1e-10 | TA-Lib, technicalindicators | pandas-ta |
+| ATR(14) | 56 | 1.5e-1 | TA-Lib, technicalindicators | pandas-ta |
+| ADX/+DI/-DI(14) | 90 | 1.5 | TA-Lib, technicalindicators | pandas-ta |
+
+Warmup and alignment rules:
+- References are left-padded to full series length before comparison.
+- Comparison starts at indicator-specific burn-in and uses only overlapping non-null points.
+- `TA-Lib` and `technicalindicators` are release-blocking checks in CI.
+- `pandas-ta` is telemetry-only (warns when divergent or unavailable by environment).
+
+Generate/review vectors:
+
+```bash
+npm run generate:golden
+npm run test:golden
+npm run generate:compat
+npm run test:compat:technicalindicators
+# python deps: pip install -r scripts/requirements-compat.txt
+npm run test:compat:python
+```
+
+Note:
+- CI uses Linux + Python 3.12 for full TA-Lib/pandas-ta coverage.
+- On Windows, `pandas-ta` may be unavailable depending on upstream wheels; the script reports explicit skip in that case.
+- `TA-Lib` and `technicalindicators` are strict release gates; `pandas-ta` runs as compatibility telemetry and reports warnings when it diverges by environment.
+
+## Crypto Playbooks
+
+Session VWAP reset:
+- Provide one `sessionId` per candle.
+- VWAP resets exactly when `sessionId` changes.
+- Use exchange session boundaries (UTC day, funding window, or custom market session).
+
+Funding APR:
+- `fundingRateAPR(values, periodsPerYear)` annualizes periodic funding.
+- `periodsPerYear` presets:
+- `3/day` funding: `1095`
+- `1/hour` funding: `8760`
+- `1/8h` funding: `1095`
+
+Volatility regime:
+- `volatilityRegime(values, length, periodsPerYear, lowZ, highZ)` returns `-1`, `0`, `1`.
+- Default thresholds: `lowZ = -0.5`, `highZ = 0.5`.
+- Calibration approach: increase absolute thresholds for noisier low-timeframe pairs, reduce for smoother higher timeframes.
+
+## Indicators
+
+Overlap:
+- `sma`, `ema`, `rma`, `hl2`, `hlc3`, `ohlc4`, `vwap`, `bbands`
+
+Momentum:
+- `rsi`, `macd`, `stoch`
+
+Volatility:
+- `trueRange`, `atr`, `natr`, `realizedVolatility`
+
+Performance:
+- `logReturn`, `percentReturn`
+
+Volume:
+- `obv`, `mfi`
+
+Trend:
+- `adx`
+
+Crypto:
+- `vwapSession`, `fundingRateCumulative`, `fundingRateAPR`, `volatilityRegime`, `signedVolume`, `volumeDelta`, `orderflowImbalance`
+
+## Hero Features (crypto edge)
+
+1. Session-aware VWAP (`vwapSession`, `createVWAPSession`)
+2. Funding analytics (`fundingRateCumulative`, `fundingRateAPR`)
+3. Volatility regime labeling (`volatilityRegime`)
+4. Orderflow proxies (`signedVolume`, `volumeDelta`, `orderflowImbalance`)
+5. Streaming/stateful indicators for low-allocation pipelines
+
+Limitations:
+- Orderflow proxies infer pressure from candle direction and volume; they are not a replacement for L2/L3 order book data.
+- Different libraries use different warmup conventions; comparisons use overlapping non-null windows.
+
+## Typing and Inputs
+
+`ta-crypto` public APIs accept two input styles:
+- Primitive arrays (`number[]`) for low-level control.
+- Candle objects with long keys (`open/high/low/close/volume/time`) or aliases (`o/h/l/c/v/t`).
+
+Single-series APIs (for example `sma`, `ema`, `rsi`, `macd`, `bbands`) accept:
+
+```ts
+import { rsi } from "ta-crypto";
+
+const close = [101, 102, 103, 104];
+const candles = [{ o: 100, h: 102, l: 99, c: 101, v: 10, t: 1 }];
+
+rsi(close, 14);
+rsi(candles, 14); // uses candle close/c
+```
+
+OHLC/OHLCV APIs (for example `vwap`, `stoch`, `atr`, `natr`, `mfi`, `adx`) accept:
+
+```ts
+import { atr, vwap } from "ta-crypto";
+
+atr([102, 103], [99, 100], [101, 102], 14);
+atr([{ open: 100, high: 102, low: 99, close: 101, volume: 10 }], 14);
+
+vwap([102, 103], [99, 100], [101, 102], [10, 12]);
+vwap([{ o: 100, h: 102, l: 99, c: 101, v: 10 }]);
+```
+
+Helpers:
+
+```ts
+import { pluckClose, toOHLCV } from "ta-crypto";
+
+const close = pluckClose(candles);
+const ohlcv = toOHLCV(candles, 0);
+const ohlcvFromArrays = toOHLCV({ o: [1, 2], h: [3, 4], l: [0, 1], c: [2, 3], v: [5, 6] });
+```
+
+Validation:
+- Multi-series APIs enforce equal lengths.
+- Numeric inputs are validated as finite numbers with index-aware messages when possible.
+
+## Module Imports
+
+```ts
+import { sma } from "ta-crypto/indicators";
+import { vwapSession } from "ta-crypto/crypto";
+import { toOHLCV } from "ta-crypto/candles";
+import { createSMA, createEMA, createRSI } from "ta-crypto/stateful";
+```
+
+## Bench (internal baseline, 10k candles)
+
+```text
+sma(14): 0.619 ms/run
+ema(14): 0.549 ms/run
+rsi(14): 0.647 ms/run
+macd:    2.887 ms/run
+bbands:  2.159 ms/run
+atr(14): 1.356 ms/run
+adx(14): 5.371 ms/run
+```
+
+Run locally:
+
+```bash
+npm run bench
+```
+
+## Contributing
+
+ta-crypto is open to contributors.
+If you use it, improve it.
+If you miss something, build it.
+If you're learning, this is a great codebase to practice financial math.
+
+Start with `CONTRIBUTING.md` and `ROADMAP.md`.
+If you want to contribute but don't know where to start, pick an indicator from the roadmap and add tests comparing with TA-Lib.
+
+## Release
+
+Publications are gated by GitHub Actions:
+- `CI` runs build/tests + compatibility checks.
+- `Release` workflows run tests/compat again before publish.
+
+Recommended with GitHub CLI:
+
+```bash
+gh auth login
+gh workflow run ci.yml
+gh run list --workflow ci.yml --limit 1
+```
+
+```bash
+npm run changelog
+npm run version:patch
+npm run release
+```
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,67 @@
+import type { Candle, OHLCVInput, PriceInput } from "./types.js";
+type OHLCInput = Candle[] | OHLCVInput;
+export declare function sma(input: PriceInput, length?: number): Array<number | null>;
+export declare function ema(input: PriceInput, length?: number): Array<number | null>;
+export declare function rma(input: PriceInput, length?: number): Array<number | null>;
+export declare function bbands(input: PriceInput, length?: number, std?: number): {
+    basis: (number | null)[];
+    upper: (number | null)[];
+    lower: (number | null)[];
+};
+export declare function macd(input: PriceInput, fast?: number, slow?: number, signal?: number): {
+    macd: (number | null)[];
+    signal: (number | null)[];
+    histogram: (number | null)[];
+};
+export declare function rsi(input: PriceInput, length?: number): Array<number | null>;
+export declare function logReturn(input: PriceInput, cumulative?: boolean): Array<number | null>;
+export declare function percentReturn(input: PriceInput, cumulative?: boolean): Array<number | null>;
+export declare function realizedVolatility(input: PriceInput, length?: number, periodsPerYear?: number): Array<number | null>;
+export declare function hl2(high: number[], low: number[]): Array<number | null>;
+export declare function hl2(input: OHLCInput): Array<number | null>;
+export declare function hlc3(high: number[], low: number[], close: number[]): Array<number | null>;
+export declare function hlc3(input: OHLCInput): Array<number | null>;
+export declare function ohlc4(open: number[], high: number[], low: number[], close: number[]): Array<number | null>;
+export declare function ohlc4(input: OHLCInput): Array<number | null>;
+export declare function vwap(high: number[], low: number[], close: number[], volume: number[], length?: number): Array<number | null>;
+export declare function vwap(input: OHLCInput, length?: number): Array<number | null>;
+export declare function stoch(high: number[], low: number[], close: number[], kLength?: number, dLength?: number): {
+    k: Array<number | null>;
+    d: Array<number | null>;
+};
+export declare function stoch(input: OHLCInput, kLength?: number, dLength?: number): {
+    k: Array<number | null>;
+    d: Array<number | null>;
+};
+export declare function trueRange(high: number[], low: number[], close: number[]): Array<number | null>;
+export declare function trueRange(input: OHLCInput): Array<number | null>;
+export declare function atr(high: number[], low: number[], close: number[], length?: number): Array<number | null>;
+export declare function atr(input: OHLCInput, length?: number): Array<number | null>;
+export declare function natr(high: number[], low: number[], close: number[], length?: number): Array<number | null>;
+export declare function natr(input: OHLCInput, length?: number): Array<number | null>;
+export declare function obv(close: number[], volume: number[]): Array<number | null>;
+export declare function obv(input: OHLCInput): Array<number | null>;
+export declare function mfi(high: number[], low: number[], close: number[], volume: number[], length?: number): Array<number | null>;
+export declare function mfi(input: OHLCInput, length?: number): Array<number | null>;
+export declare function adx(high: number[], low: number[], close: number[], length?: number): {
+    adx: Array<number | null>;
+    plusDI: Array<number | null>;
+    minusDI: Array<number | null>;
+};
+export declare function adx(input: OHLCInput, length?: number): {
+    adx: Array<number | null>;
+    plusDI: Array<number | null>;
+    minusDI: Array<number | null>;
+};
+export declare function vwapSession(high: number[], low: number[], close: number[], volume: number[], session: Array<string | number>): Array<number | null>;
+export declare function vwapSession(input: OHLCInput, session: Array<string | number>): Array<number | null>;
+export declare function signedVolume(open: number[], close: number[], volume: number[]): Array<number | null>;
+export declare function signedVolume(input: OHLCInput): Array<number | null>;
+export declare function volumeDelta(open: number[], close: number[], volume: number[], length?: number): Array<number | null>;
+export declare function volumeDelta(input: OHLCInput, length?: number): Array<number | null>;
+export declare function orderflowImbalance(open: number[], close: number[], volume: number[], length?: number): Array<number | null>;
+export declare function orderflowImbalance(input: OHLCInput, length?: number): Array<number | null>;
+export declare function fundingRateCumulative(values: number[]): Array<number | null>;
+export declare function fundingRateAPR(values: number[], periodsPerYear?: number): Array<number | null>;
+export declare function volatilityRegime(input: PriceInput, length?: number, periodsPerYear?: number, lowZ?: number, highZ?: number): Array<number | null>;
+export {};