ta-crypto 0.1.4 → 0.2.3

package/README.md

@@ -1,15 +1,9 @@
-# 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. 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
+Technical analysis indicators for crypto markets in Node.js.
 
 ## Install
 
@@ -20,56 +14,105 @@ 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);
+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 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);
+const vs = vwapSession(high, low, close, volume, [1, 1]);
 ```
 
-## API Conventions
+## Stateful API (streaming)
+
+```ts
+import { createRSI, createVWAPSession } from "ta-crypto";
+
+const rsi14 = createRSI(14);
+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"
+});
+```
+
+## 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:
+
+| Indicator set | Reference libs | Tolerance |
+| --- | --- | --- |
+| SMA/EMA/RSI/MACD/BBANDS/ATR/ADX | TA-Lib, pandas-ta, technicalindicators | 1e-8 |
+
+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`
 
-- Input arrays must be the same length.
-- Outputs are aligned to input length.
-- `null` marks periods with insufficient data.
+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
 
@@ -94,64 +137,80 @@ Trend:
 Crypto:
 - `vwapSession`, `fundingRateCumulative`, `fundingRateAPR`, `volatilityRegime`, `signedVolume`, `volumeDelta`, `orderflowImbalance`
 
-## Crypto-Specific Notes
+## Hero Features (crypto edge)
 
-Session VWAP:
-- Provide a `session` array with an id per candle. VWAP resets on each new session id.
+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
 
-Funding rate:
-- `fundingRateCumulative` sums periodic rates over time.
-- `fundingRateAPR` annualizes a periodic rate using `periodsPerYear`.
+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.
 
-Volatility regimes:
-- `volatilityRegime` computes realized volatility and returns -1, 0, or 1 based on z-score thresholds.
+## Candle Contracts
 
-Orderflow proxies:
-- `signedVolume`, `volumeDelta`, and `orderflowImbalance` infer buy/sell pressure from candle direction.
+Use typed candles plus helpers:
 
-## Release
+```ts
+import { pluckClose, toOHLCV } from "ta-crypto";
+
+const close = pluckClose(candles);
+const { open, high, low, close: c, volume } = toOHLCV(candles, 0);
+```
 
-Automated npm publish runs on tag push. Steps:
+Validation:
+- Multi-series indicators enforce equal lengths (`assertSameLength`).
+- Candle helpers validate finite numeric fields with index-specific error messages.
 
-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):
+## Module Imports
 
-```bash
-npm run changelog
+```ts
+import { sma } from "ta-crypto/indicators";
+import { vwapSession } from "ta-crypto/crypto";
+import { toOHLCV } from "ta-crypto/candles";
+import { createRSI } from "ta-crypto/stateful";
 ```
 
-3. Bump version (optional):
+## Bench (internal baseline, 10k candles)
 
-```bash
-npm run version:patch
+```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
 ```
 
-4. Run:
+Run locally:
 
 ```bash
-npm run release
+npm run bench
 ```
 
-Or do everything in one step:
+## 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
-npm run release:patch
+gh auth login
+gh workflow run ci.yml
+gh run list --workflow ci.yml --limit 1
 ```
 
-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.
+```bash
+npm run changelog
+npm run version:patch
+npm run release
+```
 
 ## License
 
 MIT
-
-## GitHub Packages
-
-Install from GitHub Packages:
-
-```bash
-npm i @TDamiao/ta-crypto
-```

package/dist/candles.d.ts

@@ -0,0 +1,15 @@
+import type { Candle } from "./types.js";
+export type OHLCV = {
+    open: number[];
+    high: number[];
+    low: number[];
+    close: number[];
+    volume: number[];
+    time: Array<number | string | Date | undefined>;
+};
+export declare function pluckOpen(candles: Candle[]): number[];
+export declare function pluckHigh(candles: Candle[]): number[];
+export declare function pluckLow(candles: Candle[]): number[];
+export declare function pluckClose(candles: Candle[]): number[];
+export declare function pluckVolume(candles: Candle[], fallback?: number): number[];
+export declare function toOHLCV(candles: Candle[], volumeFallback?: number): OHLCV;

package/dist/candles.js

@@ -0,0 +1,36 @@
+import { assertFiniteSeries } from "./core/math.js";
+export function pluckOpen(candles) {
+    const out = candles.map(c => c.open);
+    assertFiniteSeries("open", out);
+    return out;
+}
+export function pluckHigh(candles) {
+    const out = candles.map(c => c.high);
+    assertFiniteSeries("high", out);
+    return out;
+}
+export function pluckLow(candles) {
+    const out = candles.map(c => c.low);
+    assertFiniteSeries("low", out);
+    return out;
+}
+export function pluckClose(candles) {
+    const out = candles.map(c => c.close);
+    assertFiniteSeries("close", out);
+    return out;
+}
+export function pluckVolume(candles, fallback = 0) {
+    const out = candles.map(c => (c.volume === undefined ? fallback : c.volume));
+    assertFiniteSeries("volume", out);
+    return out;
+}
+export function toOHLCV(candles, volumeFallback = 0) {
+    return {
+        open: pluckOpen(candles),
+        high: pluckHigh(candles),
+        low: pluckLow(candles),
+        close: pluckClose(candles),
+        volume: pluckVolume(candles, volumeFallback),
+        time: candles.map(c => c.time)
+    };
+}

package/dist/core/math.d.ts

@@ -1,4 +1,5 @@
 export declare function isNum(value: unknown): value is number;
+export declare function assertFiniteSeries(name: string, values: number[]): void;
 export declare function assertSameLength(...series: number[][]): void;
 export declare function makeSeries(length: number): Array<number | null>;
 export declare function sum(values: number[], start: number, end: number): number;

package/dist/core/math.js

@@ -1,13 +1,20 @@
 export function isNum(value) {
     return typeof value === "number" && Number.isFinite(value);
 }
+export function assertFiniteSeries(name, values) {
+    for (let i = 0; i < values.length; i++) {
+        if (!isNum(values[i])) {
+            throw new Error(`${name}[${i}] must be a finite number`);
+        }
+    }
+}
 export function assertSameLength(...series) {
     if (series.length === 0)
         return;
     const len = series[0].length;
     for (const s of series) {
         if (s.length !== len) {
-            throw new Error("All series must have the same length");
+            throw new Error(`All series must have the same length (expected ${len}, got ${s.length})`);
         }
     }
 }

package/dist/core/momentum.js

@@ -1,4 +1,4 @@
-import { makeSeries } from "./math.js";
+import { assertSameLength, makeSeries } from "./math.js";
 import { ema } from "./overlap.js";
 export function macd(values, fast = 12, slow = 26, signal = 9) {
     const fastEma = ema(values, fast);
@@ -47,10 +47,8 @@ export function rsi(values, length = 14) {
     return out;
 }
 export function stoch(high, low, close, kLength = 14, dLength = 3) {
+    assertSameLength(high, low, close);
     const len = close.length;
-    if (high.length !== len || low.length !== len) {
-        throw new Error("All series must have the same length");
-    }
     const k = makeSeries(len);
     const d = makeSeries(len);
     for (let i = kLength - 1; i < len; i++) {

package/dist/core/trend.js

@@ -1,11 +1,9 @@
-import { makeSeries } from "./math.js";
+import { assertSameLength, makeSeries } from "./math.js";
 import { rma } from "./overlap.js";
 import { trueRange } from "./volatility.js";
 export function adx(high, low, close, length = 14) {
+    assertSameLength(high, low, close);
     const len = close.length;
-    if (high.length !== len || low.length !== len) {
-        throw new Error("All series must have the same length");
-    }
     const plusDM = new Array(len).fill(0);
     const minusDM = new Array(len).fill(0);
     for (let i = 1; i < len; i++) {

package/dist/core/volume.js

@@ -1,8 +1,6 @@
-import { makeSeries } from "./math.js";
+import { assertSameLength, makeSeries } from "./math.js";
 export function obv(close, volume) {
-    if (close.length !== volume.length) {
-        throw new Error("All series must have the same length");
-    }
+    assertSameLength(close, volume);
     const out = makeSeries(close.length);
     let acc = 0;
     for (let i = 0; i < close.length; i++) {
@@ -19,10 +17,8 @@ export function obv(close, volume) {
     return out;
 }
 export function mfi(high, low, close, volume, length = 14) {
+    assertSameLength(high, low, close, volume);
     const len = close.length;
-    if (high.length !== len || low.length !== len || volume.length !== len) {
-        throw new Error("All series must have the same length");
-    }
     const out = makeSeries(len);
     if (length <= 0)
         return out;

package/dist/crypto.d.ts

@@ -0,0 +1,2 @@
+export { vwapSession, fundingRateCumulative, fundingRateAPR, volatilityRegime, signedVolume, volumeDelta, orderflowImbalance } from "./core/crypto.js";
+export { createVWAPSession } from "./stateful.js";

package/dist/crypto.js

@@ -0,0 +1,2 @@
+export { vwapSession, fundingRateCumulative, fundingRateAPR, volatilityRegime, signedVolume, volumeDelta, orderflowImbalance } from "./core/crypto.js";
+export { createVWAPSession } from "./stateful.js";

package/dist/index.d.ts

@@ -5,8 +5,20 @@ export { logReturn, percentReturn, realizedVolatility } from "./core/performance
 export { obv, mfi } from "./core/volume.js";
 export { adx } from "./core/trend.js";
 export { vwapSession, fundingRateCumulative, fundingRateAPR, volatilityRegime, signedVolume, volumeDelta, orderflowImbalance } from "./core/crypto.js";
+export { pluckOpen, pluckHigh, pluckLow, pluckClose, pluckVolume, toOHLCV } from "./candles.js";
+export { createRSI, createVWAPSession } from "./stateful.js";
 export * from "./types.js";
+import * as candles from "./candles.js";
+import * as stateful from "./stateful.js";
 export declare const ta: {
+    createRSI(period?: number): stateful.StatefulIndicator<number, number | null>;
+    createVWAPSession(): stateful.StatefulIndicator<stateful.VWAPSessionInput, number | null>;
+    pluckOpen(candles: import("./types.js").Candle[]): number[];
+    pluckHigh(candles: import("./types.js").Candle[]): number[];
+    pluckLow(candles: import("./types.js").Candle[]): number[];
+    pluckClose(candles: import("./types.js").Candle[]): number[];
+    pluckVolume(candles: import("./types.js").Candle[], fallback?: number): number[];
+    toOHLCV(candles: import("./types.js").Candle[], volumeFallback?: number): candles.OHLCV;
     vwapSession(high: number[], low: number[], close: number[], volume: number[], session: Array<string | number>): Array<number | null>;
     fundingRateCumulative(values: number[]): Array<number | null>;
     fundingRateAPR(values: number[], periodsPerYear?: number): Array<number | null>;

package/dist/index.js

@@ -5,6 +5,8 @@ export { logReturn, percentReturn, realizedVolatility } from "./core/performance
 export { obv, mfi } from "./core/volume.js";
 export { adx } from "./core/trend.js";
 export { vwapSession, fundingRateCumulative, fundingRateAPR, volatilityRegime, signedVolume, volumeDelta, orderflowImbalance } from "./core/crypto.js";
+export { pluckOpen, pluckHigh, pluckLow, pluckClose, pluckVolume, toOHLCV } from "./candles.js";
+export { createRSI, createVWAPSession } from "./stateful.js";
 export * from "./types.js";
 import * as overlap from "./core/overlap.js";
 import * as momentum from "./core/momentum.js";
@@ -13,6 +15,8 @@ import * as performance from "./core/performance.js";
 import * as volume from "./core/volume.js";
 import * as trend from "./core/trend.js";
 import * as crypto from "./core/crypto.js";
+import * as candles from "./candles.js";
+import * as stateful from "./stateful.js";
 export const ta = {
     ...overlap,
     ...momentum,
@@ -20,5 +24,7 @@ export const ta = {
     ...performance,
     ...volume,
     ...trend,
-    ...crypto
+    ...crypto,
+    ...candles,
+    ...stateful
 };

package/dist/indicators.d.ts

@@ -0,0 +1,6 @@
+export { sma, ema, rma, hl2, hlc3, ohlc4, vwap, bbands } from "./core/overlap.js";
+export { rsi, macd, stoch } from "./core/momentum.js";
+export { trueRange, atr, natr } from "./core/volatility.js";
+export { logReturn, percentReturn, realizedVolatility } from "./core/performance.js";
+export { obv, mfi } from "./core/volume.js";
+export { adx } from "./core/trend.js";

package/dist/indicators.js

@@ -0,0 +1,6 @@
+export { sma, ema, rma, hl2, hlc3, ohlc4, vwap, bbands } from "./core/overlap.js";
+export { rsi, macd, stoch } from "./core/momentum.js";
+export { trueRange, atr, natr } from "./core/volatility.js";
+export { logReturn, percentReturn, realizedVolatility } from "./core/performance.js";
+export { obv, mfi } from "./core/volume.js";
+export { adx } from "./core/trend.js";

package/dist/stateful.d.ts

@@ -0,0 +1,13 @@
+export type StatefulIndicator<TIn, TOut> = {
+    next(value: TIn): TOut;
+    reset(): void;
+};
+export declare function createRSI(period?: number): StatefulIndicator<number, number | null>;
+export type VWAPSessionInput = {
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+    sessionId: string | number;
+};
+export declare function createVWAPSession(): StatefulIndicator<VWAPSessionInput, number | null>;

package/dist/stateful.js

@@ -0,0 +1,83 @@
+export function createRSI(period = 14) {
+    if (period <= 0) {
+        throw new Error("period must be > 0");
+    }
+    let prevPrice = null;
+    let avgGain = 0;
+    let avgLoss = 0;
+    let seedGain = 0;
+    let seedLoss = 0;
+    let seedCount = 0;
+    let count = 0;
+    return {
+        next(price) {
+            if (!Number.isFinite(price)) {
+                throw new Error("price must be a finite number");
+            }
+            count += 1;
+            if (prevPrice === null) {
+                prevPrice = price;
+                return null;
+            }
+            const diff = price - prevPrice;
+            prevPrice = price;
+            const gain = diff > 0 ? diff : 0;
+            const loss = diff < 0 ? -diff : 0;
+            if (seedCount < period) {
+                seedGain += gain;
+                seedLoss += loss;
+                seedCount += 1;
+                if (seedCount < period)
+                    return null;
+                avgGain = seedGain / period;
+                avgLoss = seedLoss / period;
+            }
+            else {
+                avgGain = (avgGain * (period - 1) + gain) / period;
+                avgLoss = (avgLoss * (period - 1) + loss) / period;
+            }
+            if (count < period + 1)
+                return null;
+            if (avgLoss === 0)
+                return 100;
+            const rs = avgGain / avgLoss;
+            return 100 - 100 / (1 + rs);
+        },
+        reset() {
+            prevPrice = null;
+            avgGain = 0;
+            avgLoss = 0;
+            seedGain = 0;
+            seedLoss = 0;
+            seedCount = 0;
+            count = 0;
+        }
+    };
+}
+export function createVWAPSession() {
+    let cumPV = 0;
+    let cumV = 0;
+    let lastSession;
+    return {
+        next(candle) {
+            const { high, low, close, volume, sessionId } = candle;
+            if (!Number.isFinite(high) || !Number.isFinite(low) || !Number.isFinite(close) || !Number.isFinite(volume)) {
+                throw new Error("high, low, close and volume must be finite numbers");
+            }
+            if (lastSession !== sessionId) {
+                cumPV = 0;
+                cumV = 0;
+                lastSession = sessionId;
+            }
+            const typical = (high + low + close) / 3;
+            cumPV += typical * volume;
+            cumV += volume;
+            return cumV === 0 ? null : cumPV / cumV;
+        },
+        reset() {
+            cumPV = 0;
+            cumV = 0;
+            lastSession = undefined;
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ta-crypto",
-  "version": "0.1.4",
+  "version": "0.2.3",
   "description": "Technical analysis for crypto markets in Node.js",
   "type": "module",
   "license": "MIT",
@@ -9,8 +9,25 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./indicators": {
+      "types": "./dist/indicators.d.ts",
+      "import": "./dist/indicators.js"
+    },
+    "./crypto": {
+      "types": "./dist/crypto.d.ts",
+      "import": "./dist/crypto.js"
+    },
+    "./candles": {
+      "types": "./dist/candles.d.ts",
+      "import": "./dist/candles.js"
+    },
+    "./stateful": {
+      "types": "./dist/stateful.d.ts",
+      "import": "./dist/stateful.js"
     }
   },
+  "sideEffects": false,
   "types": "dist/index.d.ts",
   "main": "dist/index.js",
   "files": [
@@ -30,10 +47,18 @@
     "version:minor": "npm version minor",
     "version:major": "npm version major",
     "changelog": "node ./scripts/changelog.js",
-    "test": "node -e \"console.log('no tests yet')\""
+    "generate:golden": "npm run build && node ./scripts/generate-golden.js",
+    "generate:compat": "npm run build && node ./scripts/export-compat-vectors.js",
+    "bench": "npm run build && node ./scripts/bench.js",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:golden": "npm run build && node --test test/golden.test.mjs",
+    "test:compat:technicalindicators": "npm run generate:compat && node ./scripts/compare-technicalindicators.js",
+    "test:compat:python": "npm run generate:compat && python ./scripts/compare-python-refs.py",
+    "test:compat": "npm run test:compat:technicalindicators && npm run test:compat:python"
   },
   "devDependencies": {
     "rimraf": "^5.0.5",
+    "technicalindicators": "^3.1.0",
     "typescript": "^5.4.5"
   },
   "keywords": [