ta-crypto 0.2.3 → 0.3.0

package/README.md

@@ -33,9 +33,13 @@ const vs = vwapSession(high, low, close, volume, [1, 1]);
 ## Stateful API (streaming)
 
 ```ts
-import { createRSI, createVWAPSession } from "ta-crypto";
+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();
@@ -48,6 +52,33 @@ const nextVwap = vwap.next({
 });
 ```
 
+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.
@@ -75,9 +106,23 @@ Streaming parity:
 
 External parity:
 
-| Indicator set | Reference libs | Tolerance |
-| --- | --- | --- |
-| SMA/EMA/RSI/MACD/BBANDS/ATR/ADX | TA-Lib, pandas-ta, technicalindicators | 1e-8 |
+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:
 
@@ -149,20 +194,49 @@ 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.
 
-## Candle Contracts
+## 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`).
 
-Use typed candles plus helpers:
+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 { open, high, low, close: c, volume } = toOHLCV(candles, 0);
+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 indicators enforce equal lengths (`assertSameLength`).
-- Candle helpers validate finite numeric fields with index-specific error messages.
+- Multi-series APIs enforce equal lengths.
+- Numeric inputs are validated as finite numbers with index-aware messages when possible.
 
 ## Module Imports
 
@@ -170,7 +244,7 @@ Validation:
 import { sma } from "ta-crypto/indicators";
 import { vwapSession } from "ta-crypto/crypto";
 import { toOHLCV } from "ta-crypto/candles";
-import { createRSI } from "ta-crypto/stateful";
+import { createSMA, createEMA, createRSI } from "ta-crypto/stateful";
 ```
 
 ## Bench (internal baseline, 10k candles)
@@ -191,6 +265,16 @@ Run locally:
 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:

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 {};

package/dist/api.js

@@ -0,0 +1,241 @@
+import { assertFiniteSeries } from "./core/math.js";
+import { normalizePrice, toOHLCV } from "./candles.js";
+import { sma as coreSma, ema as coreEma, rma as coreRma, hl2 as coreHl2, hlc3 as coreHlc3, ohlc4 as coreOhlc4, vwap as coreVwap, bbands as coreBbands } from "./core/overlap.js";
+import { rsi as coreRsi, macd as coreMacd, stoch as coreStoch } from "./core/momentum.js";
+import { trueRange as coreTrueRange, atr as coreAtr, natr as coreNatr } from "./core/volatility.js";
+import { logReturn as coreLogReturn, percentReturn as corePercentReturn, realizedVolatility as coreRealizedVolatility } from "./core/performance.js";
+import { obv as coreObv, mfi as coreMfi } from "./core/volume.js";
+import { adx as coreAdx } from "./core/trend.js";
+import { vwapSession as coreVwapSession, fundingRateCumulative as coreFundingRateCumulative, fundingRateAPR as coreFundingRateAPR, volatilityRegime as coreVolatilityRegime, signedVolume as coreSignedVolume, volumeDelta as coreVolumeDelta, orderflowImbalance as coreOrderflowImbalance } from "./core/crypto.js";
+function isNumericArray(input) {
+    return Array.isArray(input) && (input.length === 0 || typeof input[0] === "number");
+}
+function parseHLC(input, low, close) {
+    if (isNumericArray(input)) {
+        if (!low || !close) {
+            throw new Error("Expected high, low, close arrays or candles/OHLCV object input");
+        }
+        assertFiniteSeries("high", input);
+        assertFiniteSeries("low", low);
+        assertFiniteSeries("close", close);
+        return { high: input, low, close };
+    }
+    return toOHLCV(input);
+}
+function parseOHLC(input, high, low, close) {
+    if (isNumericArray(input)) {
+        if (!high || !low || !close) {
+            throw new Error("Expected open, high, low, close arrays or candles/OHLCV object input");
+        }
+        assertFiniteSeries("open", input);
+        assertFiniteSeries("high", high);
+        assertFiniteSeries("low", low);
+        assertFiniteSeries("close", close);
+        return { open: input, high, low, close };
+    }
+    return toOHLCV(input);
+}
+function parseHLCV(input, low, close, volume) {
+    if (isNumericArray(input)) {
+        if (!low || !close || !volume) {
+            throw new Error("Expected high, low, close, volume arrays or candles/OHLCV object input");
+        }
+        assertFiniteSeries("high", input);
+        assertFiniteSeries("low", low);
+        assertFiniteSeries("close", close);
+        assertFiniteSeries("volume", volume);
+        return { high: input, low, close, volume };
+    }
+    return toOHLCV(input);
+}
+function parseOCV(input, close, volume) {
+    if (isNumericArray(input)) {
+        if (!close || !volume) {
+            throw new Error("Expected open, close, volume arrays or candles/OHLCV object input");
+        }
+        assertFiniteSeries("open", input);
+        assertFiniteSeries("close", close);
+        assertFiniteSeries("volume", volume);
+        return { open: input, close, volume };
+    }
+    return toOHLCV(input);
+}
+export function sma(input, length = 14) {
+    return coreSma(normalizePrice(input), length);
+}
+export function ema(input, length = 14) {
+    return coreEma(normalizePrice(input), length);
+}
+export function rma(input, length = 14) {
+    return coreRma(normalizePrice(input), length);
+}
+export function bbands(input, length = 20, std = 2) {
+    return coreBbands(normalizePrice(input), length, std);
+}
+export function macd(input, fast = 12, slow = 26, signal = 9) {
+    return coreMacd(normalizePrice(input), fast, slow, signal);
+}
+export function rsi(input, length = 14) {
+    return coreRsi(normalizePrice(input), length);
+}
+export function logReturn(input, cumulative = false) {
+    return coreLogReturn(normalizePrice(input), cumulative);
+}
+export function percentReturn(input, cumulative = false) {
+    return corePercentReturn(normalizePrice(input), cumulative);
+}
+export function realizedVolatility(input, length = 30, periodsPerYear = 365) {
+    return coreRealizedVolatility(normalizePrice(input), length, periodsPerYear);
+}
+export function hl2(input, low) {
+    if (isNumericArray(input)) {
+        if (!low)
+            throw new Error("Expected high + low arrays or candles/OHLCV object input");
+        return coreHl2(input, low);
+    }
+    const ohlcv = toOHLCV(input);
+    return coreHl2(ohlcv.high, ohlcv.low);
+}
+export function hlc3(input, low, close) {
+    const ohlcv = parseHLC(input, low, close);
+    return coreHlc3(ohlcv.high, ohlcv.low, ohlcv.close);
+}
+export function ohlc4(input, high, low, close) {
+    const ohlcv = parseOHLC(input, high, low, close);
+    return coreOhlc4(ohlcv.open, ohlcv.high, ohlcv.low, ohlcv.close);
+}
+export function vwap(input, lowOrLength, close, volume, length) {
+    if (isNumericArray(input)) {
+        const low = Array.isArray(lowOrLength) ? lowOrLength : undefined;
+        const resolvedLength = typeof lowOrLength === "number" ? lowOrLength : length;
+        const ohlcv = parseHLCV(input, low, close, volume);
+        return coreVwap(ohlcv.high, ohlcv.low, ohlcv.close, ohlcv.volume, resolvedLength);
+    }
+    const ohlcv = toOHLCV(input);
+    const resolvedLength = typeof lowOrLength === "number" ? lowOrLength : length;
+    return coreVwap(ohlcv.high, ohlcv.low, ohlcv.close, ohlcv.volume, resolvedLength);
+}
+export function stoch(input, lowOrKLength, closeOrDLength, kLength = 14, dLength = 3) {
+    if (isNumericArray(input)) {
+        const low = Array.isArray(lowOrKLength) ? lowOrKLength : undefined;
+        const close = Array.isArray(closeOrDLength) ? closeOrDLength : undefined;
+        const resolvedK = typeof lowOrKLength === "number" ? lowOrKLength : kLength;
+        const resolvedD = typeof closeOrDLength === "number" ? closeOrDLength : dLength;
+        const ohlcv = parseHLC(input, low, close);
+        return coreStoch(ohlcv.high, ohlcv.low, ohlcv.close, resolvedK, resolvedD);
+    }
+    const resolvedK = typeof lowOrKLength === "number" ? lowOrKLength : kLength;
+    const resolvedD = typeof closeOrDLength === "number" ? closeOrDLength : dLength;
+    const ohlcv = toOHLCV(input);
+    return coreStoch(ohlcv.high, ohlcv.low, ohlcv.close, resolvedK, resolvedD);
+}
+export function trueRange(input, low, close) {
+    const ohlcv = parseHLC(input, low, close);
+    return coreTrueRange(ohlcv.high, ohlcv.low, ohlcv.close);
+}
+export function atr(input, lowOrLength, close, length = 14) {
+    if (isNumericArray(input)) {
+        const low = Array.isArray(lowOrLength) ? lowOrLength : undefined;
+        const resolvedLength = typeof lowOrLength === "number" ? lowOrLength : length;
+        const ohlcv = parseHLC(input, low, close);
+        return coreAtr(ohlcv.high, ohlcv.low, ohlcv.close, resolvedLength);
+    }
+    const ohlcv = toOHLCV(input);
+    const resolvedLength = typeof lowOrLength === "number" ? lowOrLength : length;
+    return coreAtr(ohlcv.high, ohlcv.low, ohlcv.close, resolvedLength);
+}
+export function natr(input, lowOrLength, close, length = 14) {
+    if (isNumericArray(input)) {
+        const low = Array.isArray(lowOrLength) ? lowOrLength : undefined;
+        const resolvedLength = typeof lowOrLength === "number" ? lowOrLength : length;
+        const ohlcv = parseHLC(input, low, close);
+        return coreNatr(ohlcv.high, ohlcv.low, ohlcv.close, resolvedLength);
+    }
+    const ohlcv = toOHLCV(input);
+    const resolvedLength = typeof lowOrLength === "number" ? lowOrLength : length;
+    return coreNatr(ohlcv.high, ohlcv.low, ohlcv.close, resolvedLength);
+}
+export function obv(input, volume) {
+    if (isNumericArray(input)) {
+        if (!volume)
+            throw new Error("Expected close + volume arrays or candles/OHLCV object input");
+        return coreObv(input, volume);
+    }
+    const ohlcv = toOHLCV(input);
+    return coreObv(ohlcv.close, ohlcv.volume);
+}
+export function mfi(input, lowOrLength, close, volume, length = 14) {
+    if (isNumericArray(input)) {
+        const low = Array.isArray(lowOrLength) ? lowOrLength : undefined;
+        const resolvedLength = typeof lowOrLength === "number" ? lowOrLength : length;
+        const ohlcv = parseHLCV(input, low, close, volume);
+        return coreMfi(ohlcv.high, ohlcv.low, ohlcv.close, ohlcv.volume, resolvedLength);
+    }
+    const ohlcv = toOHLCV(input);
+    const resolvedLength = typeof lowOrLength === "number" ? lowOrLength : length;
+    return coreMfi(ohlcv.high, ohlcv.low, ohlcv.close, ohlcv.volume, resolvedLength);
+}
+export function adx(input, lowOrLength, close, length = 14) {
+    if (isNumericArray(input)) {
+        const low = Array.isArray(lowOrLength) ? lowOrLength : undefined;
+        const resolvedLength = typeof lowOrLength === "number" ? lowOrLength : length;
+        const ohlcv = parseHLC(input, low, close);
+        return coreAdx(ohlcv.high, ohlcv.low, ohlcv.close, resolvedLength);
+    }
+    const ohlcv = toOHLCV(input);
+    const resolvedLength = typeof lowOrLength === "number" ? lowOrLength : length;
+    return coreAdx(ohlcv.high, ohlcv.low, ohlcv.close, resolvedLength);
+}
+export function vwapSession(input, lowOrSession, close, volume, session) {
+    if (isNumericArray(input)) {
+        if (!isNumericArray(lowOrSession)) {
+            throw new Error("Expected high, low, close, volume, session arrays");
+        }
+        if (!session || !close || !volume) {
+            throw new Error("Expected high, low, close, volume, session arrays");
+        }
+        return coreVwapSession(input, lowOrSession, close, volume, session);
+    }
+    if (!Array.isArray(lowOrSession)) {
+        throw new Error("session must be an array");
+    }
+    const ohlcv = toOHLCV(input);
+    return coreVwapSession(ohlcv.high, ohlcv.low, ohlcv.close, ohlcv.volume, lowOrSession);
+}
+export function signedVolume(input, close, volume) {
+    const ohlcv = parseOCV(input, close, volume);
+    return coreSignedVolume(ohlcv.open, ohlcv.close, ohlcv.volume);
+}
+export function volumeDelta(input, closeOrLength, volume, length = 14) {
+    if (isNumericArray(input)) {
+        const close = Array.isArray(closeOrLength) ? closeOrLength : undefined;
+        const resolvedLength = typeof closeOrLength === "number" ? closeOrLength : length;
+        const ohlcv = parseOCV(input, close, volume);
+        return coreVolumeDelta(ohlcv.open, ohlcv.close, ohlcv.volume, resolvedLength);
+    }
+    const ohlcv = toOHLCV(input);
+    const resolvedLength = typeof closeOrLength === "number" ? closeOrLength : length;
+    return coreVolumeDelta(ohlcv.open, ohlcv.close, ohlcv.volume, resolvedLength);
+}
+export function orderflowImbalance(input, closeOrLength, volume, length = 14) {
+    if (isNumericArray(input)) {
+        const close = Array.isArray(closeOrLength) ? closeOrLength : undefined;
+        const resolvedLength = typeof closeOrLength === "number" ? closeOrLength : length;
+        const ohlcv = parseOCV(input, close, volume);
+        return coreOrderflowImbalance(ohlcv.open, ohlcv.close, ohlcv.volume, resolvedLength);
+    }
+    const ohlcv = toOHLCV(input);
+    const resolvedLength = typeof closeOrLength === "number" ? closeOrLength : length;
+    return coreOrderflowImbalance(ohlcv.open, ohlcv.close, ohlcv.volume, resolvedLength);
+}
+export function fundingRateCumulative(values) {
+    assertFiniteSeries("values", values);
+    return coreFundingRateCumulative(values);
+}
+export function fundingRateAPR(values, periodsPerYear = 365 * 3) {
+    assertFiniteSeries("values", values);
+    return coreFundingRateAPR(values, periodsPerYear);
+}
+export function volatilityRegime(input, length = 30, periodsPerYear = 365, lowZ = -0.5, highZ = 0.5) {
+    return coreVolatilityRegime(normalizePrice(input), length, periodsPerYear, lowZ, highZ);
+}

package/dist/candles.d.ts

@@ -1,15 +1,9 @@
-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>;
-};
+import type { Candle, OHLCV, OHLCVInput, PriceInput } from "./types.js";
+export declare function isCandleArray(input: PriceInput | OHLCVInput): input is Candle[];
+export declare function normalizePrice(input: PriceInput, name?: string): number[];
 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;
+export declare function toOHLCV(input: Candle[] | OHLCVInput, volumeFallback?: number): OHLCV;

package/dist/candles.js

@@ -1,36 +1,98 @@
-import { assertFiniteSeries } from "./core/math.js";
+import { assertFiniteSeries, assertSameLength, isNum } from "./core/math.js";
+function readField(candle, index, name, alias) {
+    const value = candle[name] ?? candle[alias];
+    if (!isNum(value)) {
+        throw new Error(`candles[${index}].${name} (or .${alias}) must be a finite number`);
+    }
+    return value;
+}
+function readTime(candle) {
+    const value = candle.time ?? candle.t;
+    return value;
+}
+function hasOHLCVArrays(input) {
+    return "open" in input && "high" in input && "low" in input && "close" in input;
+}
+export function isCandleArray(input) {
+    return Array.isArray(input) && input.length > 0 && typeof input[0] !== "number";
+}
+export function normalizePrice(input, name = "values") {
+    if (Array.isArray(input) && (input.length === 0 || typeof input[0] === "number")) {
+        assertFiniteSeries(name, input);
+        return input;
+    }
+    return pluckClose(input);
+}
 export function pluckOpen(candles) {
-    const out = candles.map(c => c.open);
+    const out = candles.map((candle, index) => readField(candle, index, "open", "o"));
     assertFiniteSeries("open", out);
     return out;
 }
 export function pluckHigh(candles) {
-    const out = candles.map(c => c.high);
+    const out = candles.map((candle, index) => readField(candle, index, "high", "h"));
     assertFiniteSeries("high", out);
     return out;
 }
 export function pluckLow(candles) {
-    const out = candles.map(c => c.low);
+    const out = candles.map((candle, index) => readField(candle, index, "low", "l"));
     assertFiniteSeries("low", out);
     return out;
 }
 export function pluckClose(candles) {
-    const out = candles.map(c => c.close);
+    const out = candles.map((candle, index) => readField(candle, index, "close", "c"));
     assertFiniteSeries("close", out);
     return out;
 }
 export function pluckVolume(candles, fallback = 0) {
-    const out = candles.map(c => (c.volume === undefined ? fallback : c.volume));
+    if (!isNum(fallback)) {
+        throw new Error("volumeFallback must be a finite number");
+    }
+    const out = candles.map((candle, index) => {
+        const value = candle.volume ?? candle.v;
+        const normalized = value === undefined ? fallback : value;
+        if (!isNum(normalized)) {
+            throw new Error(`candles[${index}].volume (or .v) must be a finite number`);
+        }
+        return normalized;
+    });
     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)
-    };
+export function toOHLCV(input, volumeFallback = 0) {
+    if (Array.isArray(input)) {
+        return {
+            open: pluckOpen(input),
+            high: pluckHigh(input),
+            low: pluckLow(input),
+            close: pluckClose(input),
+            volume: pluckVolume(input, volumeFallback),
+            time: input.map(c => readTime(c))
+        };
+    }
+    if (hasOHLCVArrays(input)) {
+        assertFiniteSeries("open", input.open);
+        assertFiniteSeries("high", input.high);
+        assertFiniteSeries("low", input.low);
+        assertFiniteSeries("close", input.close);
+        const volume = input.volume ?? new Array(input.close.length).fill(volumeFallback);
+        assertFiniteSeries("volume", volume);
+        assertSameLength(input.open, input.high, input.low, input.close, volume);
+        const time = input.time ?? new Array(input.close.length).fill(undefined);
+        if (time.length !== input.close.length) {
+            throw new Error(`All series must have the same length (expected ${input.close.length}, got ${time.length})`);
+        }
+        return { open: input.open, high: input.high, low: input.low, close: input.close, volume, time };
+    }
+    assertFiniteSeries("open", input.o);
+    assertFiniteSeries("high", input.h);
+    assertFiniteSeries("low", input.l);
+    assertFiniteSeries("close", input.c);
+    const volume = input.v ?? new Array(input.c.length).fill(volumeFallback);
+    assertFiniteSeries("volume", volume);
+    assertSameLength(input.o, input.h, input.l, input.c, volume);
+    const time = input.t ?? new Array(input.c.length).fill(undefined);
+    if (time.length !== input.c.length) {
+        throw new Error(`All series must have the same length (expected ${input.c.length}, got ${time.length})`);
+    }
+    return { open: input.o, high: input.h, low: input.l, close: input.c, volume, time };
 }

package/dist/crypto.d.ts

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

package/dist/crypto.js

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

package/dist/index.d.ts

@@ -1,64 +1,83 @@
-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";
-export { vwapSession, fundingRateCumulative, fundingRateAPR, volatilityRegime, signedVolume, volumeDelta, orderflowImbalance } from "./core/crypto.js";
+export { sma, ema, rma, hl2, hlc3, ohlc4, vwap, bbands, rsi, macd, stoch, trueRange, atr, natr, logReturn, percentReturn, realizedVolatility, obv, mfi, adx, vwapSession, fundingRateCumulative, fundingRateAPR, volatilityRegime, signedVolume, volumeDelta, orderflowImbalance } from "./api.js";
 export { pluckOpen, pluckHigh, pluckLow, pluckClose, pluckVolume, toOHLCV } from "./candles.js";
-export { createRSI, createVWAPSession } from "./stateful.js";
+export { createSMA, createEMA, 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: {
+    createSMA(period?: number): stateful.StatefulIndicator<number, number | null>;
+    createEMA(period?: number): stateful.StatefulIndicator<number, number | null>;
     createRSI(period?: number): stateful.StatefulIndicator<number, number | null>;
     createVWAPSession(): stateful.StatefulIndicator<stateful.VWAPSessionInput, number | null>;
+    isCandleArray(input: import("./types.js").PriceInput | import("./types.js").OHLCVInput): input is import("./types.js").Candle[];
+    normalizePrice(input: import("./types.js").PriceInput, name?: string): number[];
     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>;
-    volatilityRegime(values: number[], length?: number, periodsPerYear?: number, lowZ?: number, highZ?: number): Array<number | null>;
-    signedVolume(open: number[], close: number[], volume: number[]): Array<number | null>;
-    volumeDelta(open: number[], close: number[], volume: number[], length?: number): Array<number | null>;
-    orderflowImbalance(open: number[], close: number[], volume: number[], length?: number): Array<number | null>;
-    adx(high: number[], low: number[], close: number[], length?: number): {
-        adx: (number | null)[];
-        plusDI: (number | null)[];
-        minusDI: (number | null)[];
+    toOHLCV(input: import("./types.js").Candle[] | import("./types.js").OHLCVInput, volumeFallback?: number): import("./types.js").OHLCV;
+    sma(input: import("./types.js").PriceInput, length?: number): Array<number | null>;
+    ema(input: import("./types.js").PriceInput, length?: number): Array<number | null>;
+    rma(input: import("./types.js").PriceInput, length?: number): Array<number | null>;
+    bbands(input: import("./types.js").PriceInput, length?: number, std?: number): {
+        basis: (number | null)[];
+        upper: (number | null)[];
+        lower: (number | null)[];
     };
-    obv(close: number[], volume: number[]): Array<number | null>;
-    mfi(high: number[], low: number[], close: number[], volume: number[], length?: number): Array<number | null>;
-    logReturn(values: number[], cumulative?: boolean): Array<number | null>;
-    percentReturn(values: number[], cumulative?: boolean): Array<number | null>;
-    realizedVolatility(values: number[], length?: number, periodsPerYear?: number): Array<number | null>;
-    trueRange(high: number[], low: number[], close: number[]): Array<number | null>;
-    atr(high: number[], low: number[], close: number[], length?: number): Array<number | null>;
-    natr(high: number[], low: number[], close: number[], length?: number): Array<number | null>;
-    macd(values: number[], fast?: number, slow?: number, signal?: number): {
+    macd(input: import("./types.js").PriceInput, fast?: number, slow?: number, signal?: number): {
         macd: (number | null)[];
         signal: (number | null)[];
         histogram: (number | null)[];
     };
-    rsi(values: number[], length?: number): Array<number | null>;
-    stoch(high: number[], low: number[], close: number[], kLength?: number, dLength?: number): {
-        k: (number | null)[];
-        d: (number | null)[];
-    };
-    sma(values: number[], length?: number): Array<number | null>;
-    ema(values: number[], length?: number): Array<number | null>;
-    rma(values: number[], length?: number): Array<number | null>;
+    rsi(input: import("./types.js").PriceInput, length?: number): Array<number | null>;
+    logReturn(input: import("./types.js").PriceInput, cumulative?: boolean): Array<number | null>;
+    percentReturn(input: import("./types.js").PriceInput, cumulative?: boolean): Array<number | null>;
+    realizedVolatility(input: import("./types.js").PriceInput, length?: number, periodsPerYear?: number): Array<number | null>;
     hl2(high: number[], low: number[]): Array<number | null>;
+    hl2(input: import("./types.js").OHLCVInput | import("./types.js").Candle[]): Array<number | null>;
     hlc3(high: number[], low: number[], close: number[]): Array<number | null>;
+    hlc3(input: import("./types.js").OHLCVInput | import("./types.js").Candle[]): Array<number | null>;
     ohlc4(open: number[], high: number[], low: number[], close: number[]): Array<number | null>;
+    ohlc4(input: import("./types.js").OHLCVInput | import("./types.js").Candle[]): Array<number | null>;
     vwap(high: number[], low: number[], close: number[], volume: number[], length?: number): Array<number | null>;
-    bbands(values: number[], length?: number, std?: number): {
-        basis: (number | null)[];
-        upper: (number | null)[];
-        lower: (number | null)[];
+    vwap(input: import("./types.js").OHLCVInput | import("./types.js").Candle[], length?: number): Array<number | null>;
+    stoch(high: number[], low: number[], close: number[], kLength?: number, dLength?: number): {
+        k: Array<number | null>;
+        d: Array<number | null>;
+    };
+    stoch(input: import("./types.js").OHLCVInput | import("./types.js").Candle[], kLength?: number, dLength?: number): {
+        k: Array<number | null>;
+        d: Array<number | null>;
+    };
+    trueRange(high: number[], low: number[], close: number[]): Array<number | null>;
+    trueRange(input: import("./types.js").OHLCVInput | import("./types.js").Candle[]): Array<number | null>;
+    atr(high: number[], low: number[], close: number[], length?: number): Array<number | null>;
+    atr(input: import("./types.js").OHLCVInput | import("./types.js").Candle[], length?: number): Array<number | null>;
+    natr(high: number[], low: number[], close: number[], length?: number): Array<number | null>;
+    natr(input: import("./types.js").OHLCVInput | import("./types.js").Candle[], length?: number): Array<number | null>;
+    obv(close: number[], volume: number[]): Array<number | null>;
+    obv(input: import("./types.js").OHLCVInput | import("./types.js").Candle[]): Array<number | null>;
+    mfi(high: number[], low: number[], close: number[], volume: number[], length?: number): Array<number | null>;
+    mfi(input: import("./types.js").OHLCVInput | import("./types.js").Candle[], length?: number): Array<number | null>;
+    adx(high: number[], low: number[], close: number[], length?: number): {
+        adx: Array<number | null>;
+        plusDI: Array<number | null>;
+        minusDI: Array<number | null>;
+    };
+    adx(input: import("./types.js").OHLCVInput | import("./types.js").Candle[], length?: number): {
+        adx: Array<number | null>;
+        plusDI: Array<number | null>;
+        minusDI: Array<number | null>;
     };
+    vwapSession(high: number[], low: number[], close: number[], volume: number[], session: Array<string | number>): Array<number | null>;
+    vwapSession(input: import("./types.js").OHLCVInput | import("./types.js").Candle[], session: Array<string | number>): Array<number | null>;
+    signedVolume(open: number[], close: number[], volume: number[]): Array<number | null>;
+    signedVolume(input: import("./types.js").OHLCVInput | import("./types.js").Candle[]): Array<number | null>;
+    volumeDelta(open: number[], close: number[], volume: number[], length?: number): Array<number | null>;
+    volumeDelta(input: import("./types.js").OHLCVInput | import("./types.js").Candle[], length?: number): Array<number | null>;
+    orderflowImbalance(open: number[], close: number[], volume: number[], length?: number): Array<number | null>;
+    orderflowImbalance(input: import("./types.js").OHLCVInput | import("./types.js").Candle[], length?: number): Array<number | null>;
+    fundingRateCumulative(values: number[]): Array<number | null>;
+    fundingRateAPR(values: number[], periodsPerYear?: number): Array<number | null>;
+    volatilityRegime(input: import("./types.js").PriceInput, length?: number, periodsPerYear?: number, lowZ?: number, highZ?: number): Array<number | null>;
 };

package/dist/index.js

@@ -1,30 +1,12 @@
-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";
-export { vwapSession, fundingRateCumulative, fundingRateAPR, volatilityRegime, signedVolume, volumeDelta, orderflowImbalance } from "./core/crypto.js";
+export { sma, ema, rma, hl2, hlc3, ohlc4, vwap, bbands, rsi, macd, stoch, trueRange, atr, natr, logReturn, percentReturn, realizedVolatility, obv, mfi, adx, vwapSession, fundingRateCumulative, fundingRateAPR, volatilityRegime, signedVolume, volumeDelta, orderflowImbalance } from "./api.js";
 export { pluckOpen, pluckHigh, pluckLow, pluckClose, pluckVolume, toOHLCV } from "./candles.js";
-export { createRSI, createVWAPSession } from "./stateful.js";
+export { createSMA, createEMA, createRSI, createVWAPSession } from "./stateful.js";
 export * from "./types.js";
-import * as overlap from "./core/overlap.js";
-import * as momentum from "./core/momentum.js";
-import * as volatility from "./core/volatility.js";
-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 api from "./api.js";
 import * as candles from "./candles.js";
 import * as stateful from "./stateful.js";
 export const ta = {
-    ...overlap,
-    ...momentum,
-    ...volatility,
-    ...performance,
-    ...volume,
-    ...trend,
-    ...crypto,
+    ...api,
     ...candles,
     ...stateful
 };

package/dist/indicators.d.ts

@@ -1,6 +1 @@
-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";
+export { sma, ema, rma, hl2, hlc3, ohlc4, vwap, bbands, rsi, macd, stoch, trueRange, atr, natr, logReturn, percentReturn, realizedVolatility, obv, mfi, adx } from "./api.js";

package/dist/indicators.js

@@ -1,6 +1 @@
-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";
+export { sma, ema, rma, hl2, hlc3, ohlc4, vwap, bbands, rsi, macd, stoch, trueRange, atr, natr, logReturn, percentReturn, realizedVolatility, obv, mfi, adx } from "./api.js";

package/dist/stateful.d.ts

@@ -2,6 +2,8 @@ export type StatefulIndicator<TIn, TOut> = {
     next(value: TIn): TOut;
     reset(): void;
 };
+export declare function createSMA(period?: number): StatefulIndicator<number, number | null>;
+export declare function createEMA(period?: number): StatefulIndicator<number, number | null>;
 export declare function createRSI(period?: number): StatefulIndicator<number, number | null>;
 export type VWAPSessionInput = {
     high: number;

package/dist/stateful.js

@@ -1,3 +1,62 @@
+export function createSMA(period = 14) {
+    if (period <= 0) {
+        throw new Error("period must be > 0");
+    }
+    const window = [];
+    let sum = 0;
+    return {
+        next(value) {
+            if (!Number.isFinite(value)) {
+                throw new Error("value must be a finite number");
+            }
+            window.push(value);
+            sum += value;
+            if (window.length < period) {
+                return null;
+            }
+            if (window.length > period) {
+                sum -= window.shift();
+            }
+            return sum / period;
+        },
+        reset() {
+            window.length = 0;
+            sum = 0;
+        }
+    };
+}
+export function createEMA(period = 14) {
+    if (period <= 0) {
+        throw new Error("period must be > 0");
+    }
+    const k = 2 / (period + 1);
+    let seedSum = 0;
+    let seedCount = 0;
+    let prev = null;
+    return {
+        next(value) {
+            if (!Number.isFinite(value)) {
+                throw new Error("value must be a finite number");
+            }
+            if (prev === null) {
+                seedSum += value;
+                seedCount += 1;
+                if (seedCount < period) {
+                    return null;
+                }
+                prev = seedSum / period;
+                return prev;
+            }
+            prev = (value - prev) * k + prev;
+            return prev;
+        },
+        reset() {
+            seedSum = 0;
+            seedCount = 0;
+            prev = null;
+        }
+    };
+}
 export function createRSI(period = 14) {
     if (period <= 0) {
         throw new Error("period must be > 0");

package/dist/types.d.ts

@@ -1,10 +1,38 @@
 export type NumericSeries = number[];
 export type Series = Array<number | null>;
-export type Candle = {
-    time?: number | string | Date;
+export type TimeValue = number | string | Date;
+export type CandleObject = {
     open: number;
     high: number;
     low: number;
     close: number;
     volume?: number;
+    time?: TimeValue;
 };
+export type CandleAlias = {
+    o: number;
+    h: number;
+    l: number;
+    c: number;
+    v?: number;
+    t?: TimeValue;
+};
+export type Candle = CandleObject | CandleAlias;
+export type OHLCV = {
+    open: number[];
+    high: number[];
+    low: number[];
+    close: number[];
+    volume: number[];
+    time: Array<TimeValue | undefined>;
+};
+export type OHLCVAlias = {
+    o: number[];
+    h: number[];
+    l: number[];
+    c: number[];
+    v?: number[];
+    t?: Array<TimeValue | undefined>;
+};
+export type OHLCVInput = OHLCV | OHLCVAlias;
+export type PriceInput = NumericSeries | Candle[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ta-crypto",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Technical analysis for crypto markets in Node.js",
   "type": "module",
   "license": "MIT",