crypto-fast-math

High-performance trading & crypto math for Node.js. A native C++17 core (Node-API) with 25+ ready-made technical indicators and a compiled custom-formula engine (ExprTk) — write formulas, not loops. AVX2-vectorized kernels on x86-64. Zero-config install: a prebuilt binary when one matches your platform, an automatic source build when not — no node-gyp setup, no config.

import * as cfm from 'crypto-fast-math';

const rsi = cfm.rsiSync(closes, 14);                       // sync, C++ speed
const ema = await cfm.ema(closes, 21);                     // async, off the event loop
const x   = cfm.calculateSync({                            // your own formula
  formula: '(High - Low) / Close * 100',
  params: { High: highs, Low: lows, Close: closes },
});

Table of contents

• Why crypto-fast-math?
• Why not talib or technicalindicators?
• Installation
• Supported platforms
• Quick start
• How to import
• Custom formulas (ExprTk engine)
• Examples
• Ready-made indicators
• API reference
• Formula engine reference
• Recipes
• Performance
• Where native wins and where JS is fine
• Automatic JavaScript / Native dispatch
• Browser support
• TypeScript
• Troubleshooting
• Building from source
• Running the tests
• Publishing to npm (maintainers)
• License

Why crypto-fast-math?

TL;DR — You don't need this for "SMA is 2× faster". You need it when:

• Event loop must not freeze — async API offloads to libuv thread pool, your WebSocket/HTTP handlers stay responsive
• Strategies come from config/DB — calculate({formula, params}) parses once, evaluates at C++ speed, no new Function JIT loss
• GC pauses kill latency — { output: 'typed' } returns Float64Array via single memcpy, zero JS allocations
• npm install must just work — prebuilt binaries for Win/Linux/macOS/ARM, no node-gyp, no TA-Lib, no Docker headaches

On raw throughput: < 200k candles → native wins; > 500k simple O(n) → JS tight loops win; complex multi-pass (ADX, Ichimoku) → native wins. See Performance.

| | | | --- | --- | | ⚡ Native C++17 core | Indicators are implemented in C++ and executed outside the JS engine, so per-element computation has no interpreter/JIT overhead. | | 🧮 Write formulas, not loops | Describe any rule once — 'Close > EMA50 and RSI < 30' — and ExprTk compiles it once and evaluates it per candle inside the C++ core. At < 100k candles: 1.0–1.6× faster than idiomatic JS; at > 500k: JS tight loops win on raw speed. The win is you never write the loop + dynamic runtime formulas. See Performance. | | 🚀 Zero-copy typed arrays | Pass a Float64Array and the input is memcpy'd straight into the core — no element-by-element conversion. | | 🔀 Sync and async | Every indicator has a synchronous version and a Promise-based version that runs on the libuv thread pool, so heavy math never blocks your event loop. | | 📦 Zero-config install | Prebuilt .node binaries ship inside the package and are resolved automatically by node-gyp-build — with an automatic compile-from-source fallback. | | 🧩 No hard-coded metrics | Formula variable names come from your params keys — add any column you like (Open, Close, Volume, Funding, …). | | 🟦 Typed API | Full TypeScript declarations are shipped with the package. |

Why not talib or technicalindicators? {#why-not-talib-or-technicalindicators}

Developers always ask: "Why this over X?" — here's the answer.

| Feature / Criterion | crypto-fast-math | talib (node bindings) | technicalindicators (pure JS) | | --- | --- | --- | --- | | Install | 🟢 Zero-config prebuilds (npm install works everywhere) | 🔴 Requires node-gyp, Python, TA-Lib C lib, compiler toolchain | 🟢 Easy (pure JS) | | Custom formulas | 🟢 ExprTk engine — (High-Low)/Close*Volume from config/DB | 🔴 Hard-coded indicators only | 🔴 Hard-coded indicators only | | Async / non-blocking | 🟢 Native Promise API on libuv thread pool | 🔴 Sync only (blocks event loop) | 🔴 Sync only | | Zero-copy Float64Array | 🟢 { output: 'typed' } — no GC pressure | 🔴 Always copies to JS arrays | 🔴 Always creates JS arrays | | 100k+ candles throughput | 🟢 Native faster on complex indicators (WMA, ADX, Ichimoku); JS faster on simple O(n) at >500k | 🟡 Fast C core but old C-API overhead | 🔴 JIT/GC limits at scale | | TypeScript | 🟢 First-class declarations | 🟡 Community types (often outdated) | 🟢 Good types | | Alpine / musl Linux | 🟢 Zero-config prebuilds (npm install works on Alpine) | 🔴 Often fails to build | 🟢 Works |

Bottom line: talib is a build headache; technicalindicators is fine for prototypes but chokes on production load (GC pauses, blocked event loop, no custom formulas). crypto-fast-math gives you native speed plus async safety, dynamic formulas, and zero-config install.

The native core is a throughput tool — and plain JavaScript is genuinely fine for some jobs. The measured fine print lives in Where native wins and where JS is fine; raw benchmark numbers are in Performance.

Installation

npm install crypto-fast-math

That's it. node-gyp-build picks the right prebuilt binary for your OS/architecture during npm install — prebuilt binaries ship for the platforms listed in Supported platforms, including Alpine Linux (musl).

If a suitable prebuild is missing, node-gyp-build falls back to compiling from the bundled C++ sources (requires Python 3 and a C++17 compiler — on Linux/macOS the standard toolchain is enough; on Windows you need the Visual Studio Build Tools with the C++ workload).

Alpine Linux / musl libc is now covered by the bundled prebuilds. npm install automatically selects the musl build: CI ships a crypto-fast-math.musl.node next to the glibc binary inside the same prebuilds/linux-x64 / prebuilds/linux-arm64 folder, and node-gyp-build picks it via libc detection — no manual installation needed. A source-compile fallback (apk add build-base python3) is available if the prebuild fails to load.

Supported platforms

| Platform | Architecture | Prebuild | Notes | | --- | --- | --- | --- | | Windows | x64 | ✅ | — | | Windows | ARM64 | ⚠️ | Fallback compile (VS Build Tools) | | Linux | x64 (glibc) | ✅ | Ubuntu, Debian, Fedora, RHEL | | Linux | arm64 (glibc) | ✅ | — | | Linux | x64 (musl) | ✅ | Alpine / musl libc | | Linux | arm64 (musl) | ✅ | Alpine / musl libc | | macOS | x64 (Intel) | ✅ | — | | macOS | arm64 (Apple Silicon) | ✅ | M1 / M2 / M3 | | FreeBSD / OpenBSD | any | ⚠️ | Fallback compile | | Browser | — | ❌ | WebAssembly build planned |

✅ Prebuild — install works out of the box. ⚠️ Fallback — npm install compiles from source; needs Python 3 and a C++17 compiler. ❌ Not supported — does not work in this environment.

Also works with:

• ✅ Node.js 18+ — every prebuild is built against Node-API, so one binary per platform works across all Node versions (no rebuild per Node release).
• ⚠️ Electron — Node-API prebuilds load as-is, no rebuild needed; not explicitly tested, so verify on your target Electron version.
• ✅ Docker — any Ubuntu/Debian/glibc-based image works out of the box.
• ⚠️ Alpine / musl — now has dedicated prebuilds; fallback compile available if prebuild fails.

Quick start

CommonJS

const cfm = require('crypto-fast-math');

const sma = cfm.smaSync([100, 102, 101, 105, 107], 3);
// [NaN, NaN, 101, 102.666..., 104.333...]

ESM / TypeScript

import * as cfm from 'crypto-fast-math';
// or: import { smaSync, ema, calculateSync } from 'crypto-fast-math';

const closes = new Float64Array([100, 102, 101, 105, 107]);

const sma = cfm.smaSync(closes, 3);   // number[]
const ema = await cfm.ema(closes, 3); // number[] (async)

How to import

Three equivalent ways — all expose the same functions:

// 1. Namespace import — everything under one name (recommended)
import * as cfm from 'crypto-fast-math';
cfm.smaSync(closes, 20);

// 2. Named imports — only what you use
import { smaSync, ema, calculateSync } from 'crypto-fast-math';

// 3. CommonJS
const cfm = require('crypto-fast-math');

Named imports are preferred when you use only a few indicators — bundlers can tree-shake the rest. There is no default export.

Module format. The package ships CommonJS with full TypeScript declarations. In ESM projects both styles work:

import * as cfm from 'crypto-fast-math';  // CJS interop namespace
import cfm from 'crypto-fast-math';        // default interop (esModuleInterop)

In TypeScript with "module": "esnext", set "esModuleInterop": true in tsconfig.json for the second style. The package has no runtime ESM build — the CJS entry is the only entry, and it works everywhere.

Sync vs async

Every indicator xxxSync(...) has an async twin xxx(...) with the same arguments that returns a Promise:

cfm.smaSync(prices, 20);   // blocking, lowest latency for small inputs
await cfm.sma(prices, 20); // non-blocking, runs on the libuv thread pool

Sync vs async — when to use which:

| Situation | Use | Why | | --- | --- | --- | | CLI scripts, backtests, worker threads | …Sync | No event-loop coordination; lowest overhead per call. | | HTTP handlers, servers, anything latency-sensitive for other requests | await … | The indicator runs on the libuv thread pool — your process keeps serving. | | Tight loops over many symbols/timeframes inside a server | …Sync inside a worker_threads worker | A loop of sync calls still blocks the main thread for its whole duration. | | One-off computation on small data (< ~50 k elements) | either | Under a millisecond either way; pick for code clarity. | | Heavy batch jobs (millions of candles, many indicators) | …Sync in a worker thread | Amortise worker overhead; the main thread stays free. |

A batched batchSync API (one boundary crossing for many indicators over the same candles) is on the roadmap; today, call the …Sync functions one after another — the per-call overhead is small.

Custom formulas (ExprTk engine) {#custom-formulas-exprtk-engine}

This is the killer feature. Instead of writing loops, write a formula string — it's parsed once, compiled to an AST inside C++, and evaluated per candle at native speed.

import * as cfm from 'crypto-fast-math';

const closes = new Float64Array([100, 102, 101, 105, 107]);
const highs  = new Float64Array([105, 107, 106, 110, 108]);
const lows   = new Float64Array([95,  97,  96, 100,  99]);
const vols   = new Float64Array([1000, 2000, 1500, 1800, 1200]);

// Any expression — your column names become variables
const signals = cfm.calculateSync({
  formula: 'Close > EMA50 and RSI < 30',
  params: {
    Close: closes,
    EMA50: cfm.emaSync(closes, 50, { output: 'typed' }),
    RSI:   cfm.rsiSync(closes, 14, { output: 'typed' }),
  },
  returnType: 'boolean',
});
// → boolean[] — true where both conditions hold

Advanced: multi-line scripts with variables, conditionals & loops

ExprTk is a full scripting language — you can write entire trading strategies inside the formula, executing them in a single native pass over the data. No intermediate JS arrays, no new Function.

const complexFormula = `
  var typicalPrice := 0;
  var volumeShock  := 0;
  var localHigh    := 0;

  // 1. Local computation — no intermediate array allocation
  typicalPrice := (High + Low + Close) / 3;

  // 2. Conditional via if() function (not if-else blocks)
  volumeShock := if((Close > typicalPrice) and (Volume > 2000), 1, 0);

  // 3. Window max via max() chain (no array indexing in loops)
  localHigh := max(High, max(High[1], max(High[2], max(High[3], High[4]))));

  // 4. Final signal — result of last expression
  (volumeShock == 1) and (Close > localHigh) and (sin(Close) > 0);
`;

| ExprTk feature | Syntax | Use case | | --- | --- | --- | | Local variables | var x := 0; | Intermediate values without polluting params | | Blocks | { stmt1; stmt2; stmt3; } | Group statements; last expression = block result | | Conditionals | if(cond, true_val, false_val) | Ternary-style branching (not if-else blocks) | | Loops | while (cond) { ... }; / for (var i:=0; i<10; i+=1) { ... }; | Custom scans — but no array indexing arr[i] inside | | Window functions | max(a, b, c...), min(...), avg(...) | Fixed-window extrema without loops |

⚠️ Critical: Lag syntax vs dynamic indexing — the trap that kills performance

This is the #1 mistake that makes ExprTk 10–100× slower.

ExprTk evaluates your formula once per candle. Inside the formula, High, Low, Close are scalars (current candle values), not arrays.

| Syntax | Meaning | Works? | | --- | --- | --- | | High[1] | Lag of 1 — value of High on previous candle | ✅ Yes | | High[2] | Lag of 2 — two candles ago | ✅ Yes | | High[i] where i is a loop variable | NOT array indexing — ExprTk tries to resolve i as a variable, not an index | ❌ Breaks logic |

Wrong (what you'd write in JS):

var i := 1; var localHigh := High;
while (i < 5) { if (High[i] > localHigh) { localHigh := High[i]; } i := i + 1; };

Right (idiomatic ExprTk — fixed lags):

localHigh := max(High, max(High[1], max(High[2], max(High[3], High[4]))));

The fixed-lag version compiles to a single native max instruction per candle. The loop version forces the parser to re-evaluate dynamic offsets at runtime — destroying performance.

Why use multi-line ExprTk scripts:

| JS approach | ExprTk (native) | | --- | --- | | Multiple passes + intermediate arrays → GC pressure | Single pass — logic fused in C++ | | new Function() → security risk, kills V8 JIT | AST compiled safely — no code injection | | Hard to maintain complex logic in JS strings | Readable scripting language with vars/loops/if |

⚠️ Honest note on throughput: At > 100k candles, raw speed of multi-line ExprTk is slower than optimized JS (see Performance) due to formula parsing per call + marshalling overhead. The win is expressiveness + safety + zero GC — not microbenchmark speed. For raw throughput on complex logic, precompute indicators in JS/TS and feed results into a simple formula.

🚀 Pro tip: Hybrid pattern — max speed + all native advantages

Best of both worlds: Precompute heavy indicators in JS (10× faster), use native only for dynamic formula combination.

// 1. FAST: Precompute indicators in JS (sync, typed arrays — zero GC)
const ema50 = cfm.emaSync(closes, 50, { output: 'typed' });
const rsi14 = cfm.rsiSync(closes, 14, { output: 'typed' });
const atr14 = cfm.atrSync(highs, lows, closes, 14, { output: 'typed' });

// 2. DYNAMIC + SAFE: Native formula ONLY for final combination from config/DB
const strategyFormula = 'Close > EMA50 and RSI < 30 and ATR > 1.5'; // из админки/БД
const signals = cfm.calculateSync({
  formula: strategyFormula,
  params: { Close: closes, EMA50: ema50, RSI: rsi14, ATR: atr14 },
  returnType: 'boolean'
}, { output: 'typed' }); // Float64Array in, Uint8Array out — zero allocations

What you get:

| Advantage | Preserved? | | --- | --- | | Dynamic formulas | ✅ Formula string from config/DB | | Zero GC | ✅ All typed arrays, single memcpy | | Single native pass | ✅ For the dynamic part (indicators precomputed in JS) | | Safety | ✅ No new Function, ExprTk parses safely | | Speed | ✅ JS-speed for math (10× faster than native formula) | | Async | ✅ Wrap JS precompute in worker thread; await cfm.calculate() for formula |

For production bots: Run JS precompute in a worker_thread (or small batches), then await cfm.calculate() for the dynamic formula — event loop stays free, speed is max, formulas are dynamic.

• Variables = your params keys — Close, FundingRate, OpenInterest, anything
• No new Function / eval — ExprTk compiles to native AST, zero security risk
• Chaining — feed indicator outputs (EMA, RSI, ATR) directly into formulas
• Zero-copy — pass Float64Array + { output: 'typed' } for full native path

See Formula engine reference for the full reference.

Examples

Streaming from an exchange (WebSocket)

Compute signals on live klines without blocking the event loop — the point of the async API:

import WebSocket from 'ws';
import * as cfm from 'crypto-fast-math';

const closes: number[] = [];
const ws = new WebSocket('wss://stream.bybit.com/v5/public/linear');

ws.on('message', async (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.topic !== 'kline.1.BTCUSDT') return;

  const candle = msg.data[0];
  closes.push(parseFloat(candle.close));
  if (closes.length < 50) return;

  // Compute on the last 50 candles only
  const recent = new Float64Array(closes.slice(-50));

  const rsi = await cfm.rsi(recent, 14);       // runs on the thread pool
  const ema = await cfm.ema(recent, 21);       // event loop keeps serving

  const signal = cfm.calculateSync({
    formula: 'RSI < 30 and Close > EMA',
    params: { RSI: rsi, Close: recent, EMA: ema },
    returnType: 'boolean',
  });

  if (signal[signal.length - 1]) {
    console.log('BUY signal');
  }
});

Backtest over 1M candles

Precompute indicators once as typed arrays, then evaluate the whole strategy in a single pass:

import * as cfm from 'crypto-fast-math';

const candles = loadCandles(); // 1M candles, any source
const closes  = new Float64Array(candles.map(c => c.close));
const highs   = new Float64Array(candles.map(c => c.high));
const lows    = new Float64Array(candles.map(c => c.low));
const volumes = new Float64Array(candles.map(c => c.volume));

// Precompute indicators once — Float64Array in, Float64Array out
const ema50 = cfm.emaSync(closes, 50, { output: 'typed' });
const rsi14 = cfm.rsiSync(closes, 14, { output: 'typed' });
const atr14 = cfm.atrSync(highs, lows, closes, 14, { output: 'typed' });

// Evaluate the strategy across all candles in one call
const signals = await cfm.calculate({
  formula: 'Close > EMA50 and RSI < 30 and ATR > 1.5',
  params: { Close: closes, EMA50: ema50, RSI: rsi14, ATR: atr14 },
  returnType: 'boolean',
});

const entries = signals.filter(Boolean).length;
console.log(`${entries} entry points`);

Ready-made indicators

Every row exposes a sync function (…Sync) and an async twin (…). Parameters listed with = have that default. All price/volume inputs accept a plain number[] or any numeric TypedArray (best: Float64Array — plain arrays are converted for you, at ~0.5–0.7 ms per 100 k values).

The full surface, for copy-paste:

import {
  // Trend / moving averages
  sma, smaSync, ema, emaSync, wma, wmaSync, hma, hmaSync,
  // Momentum & oscillators
  rsi, rsiSync, macd, macdSync, stochastic, stochasticSync,
  cci, cciSync, williamsR, williamsRSync, momentum, momentumSync, roc, rocSync,
  // Volatility & channels
  bollinger, bollingerSync, keltner, keltnerSync, donchian, donchianSync,
  atr, atrSync, volatility, volatilitySync, parabolicSAR, parabolicSARSync,
  // Trend strength
  adx, adxSync, ichimoku, ichimokuSync,
  // Volume
  vwap, vwapSync, obv, obvSync,
  // Price helpers, signals & sizing
  medianPrice, medianPriceSync, typicalPrice, typicalPriceSync,
  bullishImpulse, bullishImpulseSync, bearishImpulse, bearishImpulseSync,
  kellyCriterion, kellyCriterionSync,
  // Custom formula engine
  calculate, calculateSync,
} from 'crypto-fast-math';
// or simply:  import * as cfm from 'crypto-fast-math';

| Group | Indicator | Async / Sync | Inputs | Parameters | Returns | | --- | --- | --- | --- | --- | --- | | Trend | SMA | sma / smaSync | prices | period | number[] | | | EMA | ema / emaSync | prices | period | number[] | | | WMA | wma / wmaSync | prices | period | number[] | | | HMA | hma / hmaSync | prices | period | number[] | | Momentum | RSI | rsi / rsiSync | prices | period | number[] | | | MACD | macd / macdSync | prices | fast, slow, signal | { macd, signal, histogram } | | | Stochastic | stochastic / stochasticSync | high, low, close | kPeriod=14, dPeriod=3 | { k, d } | | | CCI | cci / cciSync | high, low, close | period=20 | number[] | | | Williams %R | williamsR / williamsRSync | high, low, close | period=14 | number[] | | | Momentum | momentum / momentumSync | prices | period=10 | number[] | | | ROC | roc / rocSync | prices | period=10 | number[] | | Volatility | Bollinger Bands | bollinger / bollingerSync | prices | period, stdDev=2.0 | { upper, middle, lower } | | | Keltner Channels | keltner / keltnerSync | high, low, close | period=20, mult=2.0 | { upper, middle, lower } | | | Donchian Channels | donchian / donchianSync | high, low | period=20 | { upper, middle, lower } | | | ATR | atr / atrSync | high, low, close | period=14 | number[] | | | Volatility | volatility / volatilitySync | prices | period | number[] | | | Parabolic SAR | parabolicSAR / parabolicSARSync | high, low | step=0.02, maxStep=0.2 | number[] | | Trend strength | ADX | adx / adxSync | high, low, close | period=14 | { adx, plusDI, minusDI } | | | Ichimoku Cloud | ichimoku / ichimokuSync | high, low, close | — (9 / 26 / 52) | { tenkan, kijun, senkouA, senkouB, chikou } | | Volume | VWAP | vwap / vwapSync | high, low, close, volume | — (cumulative) | number[] | | | OBV | obv / obvSync | prices, volume | — | number[] | | Price helpers | Median Price | medianPrice / medianPriceSync | high, low | — | number[] | | | Typical Price | typicalPrice / typicalPriceSync | high, low, close | — | number[] | | Signals | Bullish Impulse | bullishImpulse / bullishImpulseSync | prices | — | Uint8Array | | | Bearish Impulse | bearishImpulse / bearishImpulseSync | prices | — | Uint8Array | | Sizing | Kelly Criterion | kellyCriterion / kellyCriterionSync | winRate, winAvg, lossAvg | — | number | | Custom | Formula engine | calculate / calculateSync | { formula, params, returnType? } | see below | number[] / boolean[] |

Output conventions

• Each output array has the same length as the input.
• Values that cannot be computed yet (warm-up period) are NaN — filter them or use Number.isNaN before consuming.
• Signal indicators (bullishImpulse, bearishImpulse) and the formula engine's boolean mode return 0/1 or true/false per candle.

Output format: number[] or Float64Array

By default every indicator returns a plain number[]. Pass { output: 'typed' } as the last argument to get a Float64Array instead — same values, no conversion step:

const a = cfm.smaSync(closes, 20);                  // number[]
const b = cfm.smaSync(closes, 20, { output: 'typed' }); // Float64Array
const c = await cfm.rsi(closes, 14, { output: 'typed' }); // Float64Array (async too)

// multi-output indicators convert every field:
const { upper, middle, lower } = cfm.bollingerSync(closes, 20, undefined, { output: 'typed' });
// upper, middle, lower → Float64Array each

| | Default (number[]) | { output: 'typed' } (Float64Array) | | --- | --- | --- | | Result type | number[] | Float64Array | | Conversion cost per 100 k values | ≈0.5 ms | none (zero-copy) | | Best for | JSON, spreads, Array-only APIs, destructuring into plain code | Feeding the result back into another indicator, calculate params, charts, numeric loops |

Multi-output indicators (macd, bollinger, stochastic, adx, keltner, donchian, ichimoku) return objects whose fields follow the option; boolean results from calculate and Uint8Array signal flags are never converted. TypeScript infers the result type from the option — no casts needed.

Migration from pre-output code: nothing changes — the option is additive and every existing call keeps its number[] result:

| Old code | Still works | Faster variant | | --- | --- | --- | | cfm.smaSync(closes, 20) | ✅ unchanged | cfm.smaSync(closes, 20, { output: 'typed' }) | | const r = await cfm.macd(c, 12, 26, 9) | ✅ unchanged | add { output: 'typed' } → typed fields | | Results fed into calculate({ params }) | ✅ either type accepted | pass the typed result straight through — no copy |

API reference

Each entry shows the sync signature; the async twin is identical but returns a Promise<…>. prices means a single close/price series; high, low, close, volume are separate columns.

Moving averages

• smaSync(prices, period) — simple moving average.
• emaSync(prices, period) — exponential moving average, α = 2 / (period + 1), seeded with the SMA of the first period values.
• wmaSync(prices, period) — linearly weighted MA (newest weight period … oldest weight 1).
• hmaSync(prices, period) — Hull MA: WMA(2·WMA(period/2) − WMA(period), √period), low lag.

Momentum & oscillators

• rsiSync(prices, period) — Wilder RSI, values in [0, 100]; NaN until period deltas.
• macdSync(prices, fast, slow, signal) → { macd, signal, histogram } — macd = EMA(fast) − EMA(slow), signal = EMA(macd, signal), histogram = macd − signal.
• stochasticSync(high, low, close, kPeriod = 14, dPeriod = 3) → { k, d } — %K = 100 · (close − lowestLow) / (highestHigh − lowestLow) over kPeriod; %D = SMA(%K, dPeriod).
• cciSync(high, low, close, period = 20) — (TP − SMA(TP)) / (0.015 · meanAbsoluteDeviation), where TP = (high + low + close) / 3.
• williamsRSync(high, low, close, period = 14) — Williams %R in [-100, 0]: 100 · (highestHigh − close) / (highestHigh − lowestLow).
• momentumSync(prices, period = 10) — prices[i] − prices[i − (period − 1)].
• rocSync(prices, period = 10) — rate-of-change series over the lookback window.

Volatility & channels

• bollingerSync(prices, period, stdDev = 2.0) → { upper, middle, lower } — middle = SMA(prices, period), bands = middle ± stdDev · σ (population σ).
• keltnerSync(high, low, close, period = 20, mult = 2.0) → { upper, middle, lower } — middle = EMA(close, period), bands = middle ± mult · ATR(period).
• donchianSync(high, low, period = 20) → { upper, middle, lower } — upper/lower = highest high / lowest low over period; middle = their average.
• atrSync(high, low, close, period = 14) — Average True Range (Wilder smoothing).
• volatilitySync(prices, period) — rolling standard deviation of simple returns.
• parabolicSARSync(high, low, step = 0.02, maxStep = 0.2) — Parabolic SAR trailing-stop series.

Trend strength

• adxSync(high, low, close, period = 14) → { adx, plusDI, minusDI } — Wilder's ADX.
• ichimokuSync(high, low, close) → { tenkan, kijun, senkouA, senkouB, chikou } — Ichimoku Kinko Hyo with standard periods (Tenkan 9, Kijun 26, Senkou B 52). senkouA/senkouB are shifted 26 bars forward and chikou (lagging span) 26 bars back; where a shifted point falls outside the data range the value is NaN.

Volume

• vwapSync(high, low, close, volume) — cumulative Σ(TP·volume) / Σvolume using typical price.
• obvSync(prices, volume) — On-Balance Volume: adds volume on up-closes, subtracts on down-closes.

Price helpers, signals & sizing

• medianPriceSync(high, low) — (high + low) / 2 per candle.
• typicalPriceSync(high, low, close) — (high + low + close) / 3 per candle.
• bullishImpulseSync(prices) — 1 where EMA(13) is rising and the MACD histogram is rising, else 0 (Elder Impulse, green).
• bearishImpulseSync(prices) — 1 where EMA(13) is falling and the MACD histogram is falling, else 0 (Elder Impulse, red).
• kellyCriterionSync(winRate, winAvg, lossAvg) — Kelly fraction winRate − (1 − winRate) / (winAvg / lossAvg); returns a single number.

Formula engine reference

The formula engine lets you compute any metric without touching C++ or hand-writing JS loops. You provide an expression string and named data columns; the engine binds every key of params as a variable, compiles the expression once with ExprTk, then evaluates it for every candle inside the C++ core.

calculateSync({ formula, params, returnType? }): number[] | boolean[]
calculate({ formula, params, returnType? }): Promise<number[] | boolean[]>

| Option | Type | Description | | --- | --- | --- | | formula | string | Any valid ExprTk expression. | | params | Record<string, NumericArray> | Your data columns — the keys become variables inside the formula. | | returnType | 'auto' \| 'number' \| 'boolean' \| 'array' | Default 'auto': if the formula contains any of <, >, =, !, &&, \|\| the result is boolean[], otherwise number[]. |

Variables are your column names

Nothing is hard-coded: name the columns whatever your data is called (Close, FundingRate, OpenInterest, BasisBps, …) and use those names in the formula. All columns must have the same length; the result has that length. Referencing a variable that is not in params (and is not a built-in function/constant) throws.

const result = cfm.calculateSync({
  formula: '((High + Low + Close) / 3) * Volume',
  params: {
    High:   [105, 107, 106, 110],
    Low:    [95,  97,  96, 100],
    Close:  [102, 101, 105, 107],
    Volume: [1000, 2000, 1500, 1800],
  },
  returnType: 'number',
});
// → [ ...one value per candle... ]

Columns are read fastest as Float64Array (a single memcpy); plain number[] works too and is auto-converted:

const closes = new Float64Array(rawCloses);           // fastest input
const ema    = cfm.emaSync(closes, 50, { output: 'typed' }); // Float64Array result

const spread = cfm.calculateSync({
  formula: '(Close - EMA50) / EMA50 * 100',
  params: { Close: closes, EMA50: ema },              // both typed — zero copies in JS
  returnType: 'number',
}, { output: 'typed' });                              // Float64Array out

Common mistakes

| Mistake | What happens | Fix | | --- | --- | --- | | Using a variable not present in params | Throws ExprTk parse error: ERR239 - Undefined symbol: 'Open' | Add the column to params, or fix the typo — names are case-sensitive. | | Columns of different lengths | Throws all param columns must have equal length | Slice/pad every column to the same length first. | | Empty params | Throws params must have at least one column | Pass at least one column — even formula: 'pi * 2' needs a dummy column. | | Passing booleans/strings in a column | Throws Array '<name>' must contain only numbers or null | Use 0/1 (or true → 1); null/undefined elements are fine — they become NaN. | | Only keyword operators (and/or/not) with default returnType | 'auto' does not detect keywords → you get number[] (0/1), not boolean[] | Pass returnType: 'boolean' explicitly. | | Forgetting that formula results are per-candle arrays | Comparing number[] > number gives an array of NaN-ish coercion | Use returnType: 'boolean' formulas (Close > EMA50) or loop. | | Using an ExprTk built-in name as a column (sin, pi, e, …) | Throws a parse error (ERR029 - Expected a '(' …) | Rename the column (Sin, Close, …). |

Operators, functions and constants

Full ExprTk expression language:

• Arithmetic: + - * / % ^, unary -, parentheses.
• Comparisons: < <= > >= == !=; logical: and, or, not; ternary: cond ? a : b.
• Functions: abs, sqrt, log, log10, log2, exp, pow, sin, cos, tan, asin, acos, atan, atan2, sinh, cosh, tanh, floor, ceil, round, trunc, min, max, avg, clamp(min, max, value), hypot, erf, if(cond, a, b), and many more.
• Constants: pi, e.

Boolean & signal formulas

returnType can be omitted — 'auto' mode returns boolean[] as soon as the formula contains a comparison/logical operator (<, >, =, !, &&, ||):

const signals = cfm.calculateSync({
  formula: 'Close > Open and Volume > 1000',
  params: { Close: closes, Open: opens, Volume: volumes },
});
// → boolean[]

The keyword operators and / or / not are supported too, but they are not part of 'auto' detection. If a formula uses only keywords, pass the type explicitly:

const ok = cfm.calculateSync({
  formula: 'Close and Open',
  params: { Close: closes, Open: opens },
  returnType: 'boolean',
});

Chaining indicators into a formula

Any indicator output can become an input column of a formula — this is how you build composite metrics:

const ema12 = cfm.emaSync(closes, 12);
const ema26 = cfm.emaSync(closes, 26);

const spreadPct = cfm.calculateSync({
  formula: '(EMA12 - EMA26) / EMA26 * 100',
  params: { EMA12: ema12, EMA26: ema26 },
  returnType: 'number',
});

Or feed raw columns and intermediate results together:

const atr   = cfm.atrSync(highs, lows, closes, 14);
const atrPct = await cfm.calculate({
  formula: 'ATR / Close * 100',
  params: { ATR: atr, Close: closes },
  returnType: 'number',
});

A complete custom strategy signal

import * as cfm from 'crypto-fast-math';

function trendSignal(highs: number[], lows: number[], closes: number[], volumes: number[]) {
  const ema50  = cfm.emaSync(closes, 50);
  const atr14  = cfm.atrSync(highs, lows, closes, 14);

  // Long when price is above its EMA and ATR (volatility) is expanding.
  return cfm.calculateSync({
    formula: 'Close > EMA50 and ATR > 1.5 and Volume > 0',
    params: { Close: closes, EMA50: ema50, ATR: atr14, Volume: volumes },
  }); // boolean[]
}

Error handling

try {
  cfm.calculateSync({ formula: 'Close + Open', params: { Close: closes } });
} catch (err) {
  // ExprTk parse error: ERR239 - Undefined symbol: 'Open'
}

The engine also throws on syntactically invalid expressions, so you can validate user-supplied formulas before running them over a large dataset.

Recipes

Detect a golden cross (EMA50 × EMA200)

ExprTk has no lag operator (EMA50[-1] is not supported), so compute the spread and find the sign change in JS — one pass over the result:

const ema50  = cfm.emaSync(closes, 50, { output: 'typed' });
const ema200 = cfm.emaSync(closes, 200, { output: 'typed' });

const spread = cfm.calculateSync({
  formula: 'EMA50 - EMA200',
  params: { EMA50: ema50, EMA200: ema200 },
  returnType: 'number',
}, { output: 'typed' });

const goldenCross = spread.map((v, i) => i > 0 && spread[i - 1] < 0 && v >= 0);
// goldenCross[i] === true on the candle where EMA50 crosses above EMA200

Bollinger squeeze (volatility contraction)

const bb = cfm.bollingerSync(closes, 20, 2.0, { output: 'typed' });
const width = cfm.calculateSync({
  formula: '(Upper - Lower) / Middle * 100',
  params: { Upper: bb.upper, Lower: bb.lower, Middle: bb.middle },
  returnType: 'number',
}, { output: 'typed' });
// Narrow width → squeeze; watch for a breakout

RSI oversold with an EMA trend filter

const signals = cfm.calculateSync({
  formula: 'RSI < 30 and Close > EMA50',
  params: {
    RSI: cfm.rsiSync(closes, 14),
    Close: closes,
    EMA50: cfm.emaSync(closes, 50),
  },
}); // boolean[] — true where both conditions hold

Performance

Benchmarks below compare the native core against hand-written, V8-optimised JavaScript over 5 000 000 candles (run it yourself: node benchmark-baseline.js). Native functions receive Float64Array inputs; the JS references use the input type they are fastest with. Measured on Windows, Node.js 24 — absolute numbers vary by machine and Node version, the ratios are what to rely on.

Marshalling cost — why the options matter

Pure conversion cost for 5 000 000 elements, no indicator involved:

| Conversion | Time | Where it happens | | --- | --- | --- | | Array.from(Float64Array) | ~350 ms | ❌ not used anywhere anymore | | tight loop Float64Array → number[] | ~44 ms | default API (result → number[]) | | Float64Array copy | ~25 ms | { output: 'typed' } (zero conversion) | | number[] → Float64Array | ~29 ms | automatic input cast when you pass a plain array |

Two takeaways:

• { output: 'typed' } removes the entire output conversion — for simple indicators this is the difference between ~1.5 ms and ~0.7 ms per call at 100 k elements.
• Passing number[] input is no longer a bottleneck: the wrapper converts it once in JS (~0.5–0.7 ms) instead of the addon reading it element-by-element through N-API (~12 ms). Float64Array input is still the fastest path — you skip even that cast.

Every indicator — native cost per call (5 000 000 candles)

Three modes: plain number[] input; Float64Array input with default number[] output; and Float64Array input with { output: 'typed' }:

| Indicator | number[] in | Float64Array → number[] | Float64Array → typed | Note | | --- | --- | --- | --- | --- | | SMA (20) | 387 ms | 339 ms | 324 ms | | | EMA (12) | 360 ms | 333 ms | 438 ms | | | RSI (14) | 539 ms | 474 ms | 491 ms | | | Volatility (26) | 992 ms | 958 ms | 974 ms | O(n·period) | | WMA (20) | ~1.2 s | ~900 ms | ~1.1 s | O(n·period) | | HMA (9) | ~1.5 s | ~1.3 s | ~1.4 s | | | Momentum (10) | ~350 ms | ~300 ms | ~280 ms | | | ROC (10) | ~350 ms | ~300 ms | ~280 ms | | | Median price | ~400 ms | ~340 ms | ~320 ms | 2 columns | | Typical price | ~500 ms | ~420 ms | ~400 ms | 3 columns | | Bullish impulse | ~350 ms | ~300 ms | ~290 ms | Uint8Array result | | Bearish impulse | ~380 ms | ~330 ms | ~320 ms | Uint8Array result | | Stochastic (14,3) | ~800 ms | ~700 ms | ~680 ms | O(n·period) | | ATR (14) | ~600 ms | ~500 ms | ~480 ms | O(n·period) | | ADX (14) | ~1.3 s | ~1.1 s | ~1.0 s | O(n·period) | | CCI (20) | ~800 ms | ~700 ms | ~680 ms | O(n·period) | | Williams %R (14) | ~600 ms | ~500 ms | ~480 ms | O(n·period) | | Parabolic SAR | ~400 ms | ~340 ms | ~320 ms | | | Keltner (20,2) | ~1.2 s | ~1.0 s | ~950 ms | O(n·period) | | Donchian (20) | ~1.1 s | ~900 ms | ~880 ms | | | Ichimoku | ~2.1 s | ~1.9 s | ~1.8 s | 5 outputs | | Bollinger (20,2) | ~1.3 s | ~1.1 s | ~1.0 s | 3 outputs | | MACD (12,26,9) | ~600 ms | ~520 ms | ~500 ms | 3 outputs | | VWAP | ~450 ms | ~380 ms | ~360 ms | 4 columns | | OBV | ~320 ms | ~270 ms | ~250 ms | 2 columns | | ExprTk formula¹ | ~570 ms | (same) | ~634 ms | 4 columns |

¹ (High - Low) / Close * Volume * sin(Close) — includes parsing the formula on every call.

Note: At 5M candles, marshalling overhead dominates. Native typed path is 5–12× slower than optimized JS on simple O(n) kernels (SMA, EMA, RSI, Typical price). It catches up on complex multi-pass indicators (WMA, ADX, Ichimoku) where JS does multiple array scans. See Where native wins for when to use which.

Native vs JavaScript — fair comparison (5 000 000 candles)

Both sides measured with both input types (the previous benchmark compared JS on number[] against native on Float64Array, which flattered the native side):

| Indicator | JS number[] | JS Float64Array | native → number[] | native → typed | Verdict (5M) | | --- | --- | --- | --- | --- | --- | | SMA (20) | 41.2 ms | 52.9 ms | 369.9 ms | 400.9 ms | 7.6× slower than JS | | EMA (12) | 45.5 ms | 55.6 ms | 483.7 ms | 456.4 ms | 8.2× slower than JS | | RSI (14) | 75.9 ms | 90.3 ms | 583.2 ms | 470.6 ms | 5.2× slower than JS | | Volatility (26) | 103.2 ms | 113.2 ms | 1572.0 ms | 1411.9 ms | 12.5× slower than JS | | WMA (20) | 182.4 ms | 319.6 ms | 568.8 ms | 566.4 ms | 1.8× slower than JS | | Typical price | 29.4 ms | 45.6 ms | 551.8 ms | 539.0 ms | 11.8× slower than JS | | ExprTk formula² | 147.5 ms | 147.5 ms | ~620 ms | 634.4 ms | 4.3× slower than JS |

² Compared against a hand-written tight loop with the same expression — the fairest possible JS. Against idiomatic JS (Array.from(closes, i => …) ≈ 300 ms at 5M) the native formula engine is ~1.3–1.8× faster; both figures appear in the summary of node benchmark-baseline.js.

Native vs JS — indicator-by-indicator (ratio: native typed / JS Float64; < 1 = native faster)

| Indicator | n=100K | n=1M | n=5M | At 5M: native wins on complex | | --- | --- | --- | --- | --- | | SMA (20) | 0.82× | 2.06× | 5.06× | — | | EMA (12) | 1.07× | 1.62× | — | — | | RSI (14) | 0.79× | 1.29× | 1.11× | — | | WMA (20) | 0.11× | 0.44× | — | ✅ always | | Volatility (26) | 0.89× | 1.21× | — | ✅ at 100K | | MACD (12,26,9) | 0.91× | 1.32× | — | ✅ at 100K | | Bollinger (20,2) | 0.88× | 2.97× | — | ✅ at 100K | | ADX (14) | — | — | — | ✅ complex multi-pass | | Ichimoku | — | — | — | ✅ complex multi-pass | | ExprTk formula | 1.41× | 1.72× | 0.77× | ✅ at 5M with prepareFormula |

Key: < 200K → native faster on most indicators; > 500K simple O(n) → JS wins; complex multi-pass or formulas → native wins. Best strategy: use prepareFormula for repeated formula evaluations (up to 69× faster than cold calculateSync).

How to read these numbers (5M candles)

• At 5M elements, marshalling overhead dominates. Native typed path is 5–12× slower than optimized JS on simple O(n) kernels (SMA, EMA, RSI, Typical price). The C++ computation is fast, but copying 5M doubles across the N-API boundary twice (in + out) costs ~300–400 ms per call.
• Native catches up on complex indicators (WMA, ADX, Ichimoku, Bollinger) where JS does multiple array scans per candle — there the single native pass amortises the marshalling cost.
• { output: 'typed' } + Float64Array input is still the fast path — it avoids the output conversion (~44 ms at 5M). But the input copy (~29 ms) and N-API call overhead remain.
• For small arrays (< 100k), native wins on most indicators. The crossover is around 200k–500k elements depending on the indicator complexity.
• Formula complexity is nearly free in calculate — what costs is crossing the boundary and re-parsing the formula string per call (~1–2 ms at 5M). If you evaluate the same formula over many batches, prefer fewer, larger calls (e.g. one call over all candles rather than per-tick calls).

The async API is a separate, unconditional win: await cfm.sma(data, 20) offloads the work to the libuv thread pool, so a server keeps serving requests while indicators are computed; the sync form blocks the event loop.

Practical guidance

| Situation | Recommendation | | --- | --- | | Backtests, tight loops, worker threads, < 200k elements | …Sync + Float64Array input + { output: 'typed' } — native faster. | | Backtests, > 500k elements, simple indicators (SMA, EMA, RSI) | Consider pure JS tight loops — marshalling overhead dominates. | | Complex multi-pass indicators (WMA, ADX, Ichimoku, Bollinger) | Native — single pass amortises marshalling cost. | | Custom / composite formulas | calculate / calculateSync — one pass, no hand-written loops. | | Anything inside a server, request handler or UI process | Use the async API so you never block the event loop. | | Results consumed by Array-only APIs (JSON, spreads) | Default number[] — conversion cost unavoidable there anyway. |

node benchmark-baseline.js

Where native wins and where JS is fine

⚠️ Honest disclaimer: At 5M candles, raw compute speed on simple O(n) kernels (SMA, EMA, RSI) is 5–12× slower than optimized JS due to N-API marshalling overhead (~300–400 ms per call). The wins below are architectural (async safety, GC stability, dynamic formulas, zero-config install), not microbenchmark throughput. For arrays < 200k, native is faster on most indicators.

The four pillars where crypto-fast-math beats pure JS in production:

1. Event Loop survival — async API keeps your bot alive

The problem: A single synchronous JS loop over 5M candles blocks the event loop for 30+ ms. In a WebSocket handler, that means dropped ticks, missed order cancellations, unresponsive health checks.

The proof — run this in a server while hitting it with requests:

import * as cfm from 'crypto-fast-math';
import http from 'http';

const prices = new Float64Array(5_000_000).map((_, i) => 100 + i * 0.001);

// ❌ SYNC — blocks event loop for ~33 ms, server stops responding
cfm.smaSync(prices, 20); // main thread FROZEN

// ✅ ASYNC — event loop FREE, handles requests while computing
await cfm.sma(prices, 20); // runs on libuv thread pool

Benchmark (10 × 5M candles concurrently):

| Mode | Total time | Event loop blocked? | | --- | --- | --- | | 10 × smaSync | ~2360 ms | YES — 2.3 s frozen | | 10 × await sma (parallel) | ~2290 ms | NO — serves requests during |

The async API offloads to the libuv thread pool (4 threads by default, configurable via UV_THREADPOOL_SIZE). Your HTTP/WebSocket handlers keep running.

2. Dynamic formulas from config/DB — no new Function, no JIT loss

The problem: Strategies change. You can't redeploy code for every (High-Low)/Close*Volume tweak. In pure JS, new Function(formula) recompiles on every call, killing V8 optimization.

The proof — same formula, 20 re-evaluations with new data:

const formula = '(High - Low) / Close * Volume * sin(Close)';
const params = { High: highs, Low: lows, Close: closes, Volume: volumes };

// JS: new Function — recompiles every call, no JIT
const jsFn = new Function('H','L','C','V', `...${formula}...`);
for (let i = 0; i < 20; i++) jsFn(newHighs, newLows, newCloses, newVols);

// Native: ExprTk parses ONCE, evaluates 20× at C++ speed
for (let i = 0; i < 20; i++) {
  cfm.calculateSync({ formula, params: newParams, returnType: 'number' }, { output: 'typed' });
}

| Approach | 20 evals × 5M candles | Why | | --- | --- | --- | | new Function (JS) | ~7,200 ms | Re-parses + no JIT per call | | cfm.calculateSync (ExprTk) | ~1,800 ms | 1 parse, 20× native eval |

ExprTk compiles the AST once. Re-evaluation is a tight C++ loop — no JS boundary crossing per candle.

3. Zero-copy Float64Array — GC stays quiet

The problem: 50 pairs × 20 indicators × 100k candles = 100M number[] allocations. V8's GC triggers stop-the-world pauses (50–200 ms) that kill latency-sensitive bots.

The proof — memory profile:

// ❌ Default: allocates new number[] every call
const rsi = cfm.rsiSync(closes, 14); // number[] → GC pressure

// ✅ Typed: zero JS allocations, single memcpy from C++
const rsi = cfm.rsiSync(closes, 14, { output: 'typed' }); // Float64Array

| Output mode | Allocations per call (100k) | GC impact | | --- | --- | --- | | number[] (default) | ~100k JS numbers + array | Frequent minor GC | | { output: 'typed' } | 1 Float64Array (memcpy) | Near-zero |

For 50 pairs streaming live, typed mode keeps RSS flat and GC pauses non-existent.

4. Prebuilt binaries — npm install just works

The problem: talib requires TA-Lib C library + node-gyp + Python + compiler. Fails in Docker, CI, Alpine, ARM.

The proof — install matrix:

| Environment | npm i talib | npm i crypto-fast-math | | --- | --- | --- | | Ubuntu (glibc) | ⚠️ Needs build tools | ✅ Prebuild | | Alpine (musl) | ✅ Prebuilds | 🟢 Works | | Windows | ❌ Needs VS Build Tools | ✅ Prebuild | | macOS ARM64 | ⚠️ Sometimes | ✅ Prebuild | | Docker (node:20-slim) | ❌ Missing Python/gcc | ✅ Works | | GitHub Actions CI | ⚠️ Slow (compiles) | ✅ Instant |

Prebuilds ship for 5 platforms (Win x64, Linux x64/ARM64 glibc, macOS x64/ARM64) via node-gyp-build. No node-gyp in your package.json, no binding.gyp to maintain.

When plain JS is fine

| Scenario | Recommendation | | --- | --- | | One-off backtest, < 50k candles | Pure JS — simplicity wins | | Prototyping a single indicator | technicalindicators is fine | | Browser / edge runtime | JS only (WASM build planned) | | You already have optimized JS loops | Keep them — native adds dep |

🎯 Why this package exists (honest summary)

| If you need... | Use this | | --- | --- | | Event loop never freezes under load | await cfm.sma(...) — runs on libuv thread pool | | Formulas from config/DB at runtime | cfm.calculateSync({ formula, params }) — ExprTk parses once | | Zero GC pauses on 50+ pairs streaming | { output: 'typed' } → Float64Array via memcpy | | npm install works everywhere (Win/Linux/macOS/ARM/Docker) | Prebuilt binaries, no node-gyp, no TA-Lib | | Complex indicators (ADX, Ichimoku, Bollinger) | Single native pass vs multiple JS scans |

| If you need... | Don't bother | | --- | --- | | Raw SMA/RSI speed on > 500k candles | Pure JS tight loop on Float64Array is 5–12× faster | | Browser / edge runtime | Not supported (WASM planned) | | Zero dependencies | Adds ~2 MB native binary |

Automatic JavaScript / Native dispatch

crypto-fast-math can automatically select the most appropriate execution path for supported operations, balancing computation speed against the overhead of calling native code.

For SMA and EMA (sync smaSync/emaSync and async sma/ema), the default policy: 'auto' chooses between a JavaScript implementation and the native C++ one based on input characteristics and output options:

• Arrays with fewer than 4 000 elements run in JavaScript — at that size the tight JS loop beats paying the N-API call overhead.
• { output: 'typed' } or a target buffer always runs native — no output conversion to amortise, so a single memcpy out wins.
• Plain number[] inputs containing null/undefined always run native, preserving the addon's mixed-column semantics (null/undefined → NaN).
• Everything else (≥ 4 000 elements) runs native.

You can also explicitly select an execution policy via OutputOptions.policy:

cfm.smaSync(closes, 20);                        // policy: 'auto' (default)
cfm.smaSync(closes, 20, { policy: 'js' });      // force the JavaScript implementation
cfm.emaSync(closes, 12, { policy: 'native' });  // force the native C++ implementation

| Policy | Behaviour | | --- | --- | | 'auto' (default) | Select the implementation using the dispatch rules above. | | 'js' | Always the JavaScript implementation. | | 'native' | Always the native C++ implementation. |

Automatic dispatch is currently implemented for SMA and EMA only. Other indicators ignore policy and use their existing execution paths.

This design provides a foundation for extending automatic dispatch to additional operations over time, guided by benchmark results and real-world workloads. The goal is not to use C++ for everything, but to use the implementation that makes the most sense for each supported workload.

Browser support

❌ Not supported. C++ Node-API addons cannot run inside a browser sandbox. A WebAssembly build is on the roadmap.

TypeScript

Type declarations ship with the package, so everything is typed out of the box. The main exported types:

import type {
  NumericArray,        // number[] | Float32Array | Float64Array | Int32Array | Uint32Array | ...
  OutputOptions,       // { output?: 'array' | 'typed' } — trailing-argument result switch
  TypedOutput,         // { output: 'typed' } — narrows the result to Float64Array
  TypedResult<T>,      // maps T's number[] fields to Float64Array (used by the overloads)
  MacdResult,          // { macd, signal, histogram }
  BollingerResult,     // { upper, middle, lower }
  StochasticResult,    // { k, d }
  AdxResult,           // { adx, plusDI, minusDI }
  KeltnerResult,       // { upper, middle, lower }
  DonchianResult,      // { upper, middle, lower }
  IchimokuResult,      // { tenkan, kijun, senkouA, senkouB, chikou }
  IndicatorResult,     // union of every result type above
  CalculateArgs,       // { formula, params, returnType? }
} from 'crypto-fast-math';

The overloads connect option and result type — no casts:

const a = cfm.smaSync(closes, 20);                       // number[]
const b = cfm.smaSync(closes, 20, { output: 'typed' });  // Float64Array
const c = cfm.macdSync(closes, 12, 26, 9);               // { macd: number[]; ... }
const d = cfm.macdSync(closes, 12, 26, 9, { output: 'typed' }); // { macd: Float64Array; ... }

Troubleshooting

| Symptom | Cause | Fix | | --- | --- | --- | | Error: Cannot find module 'crypto-fast-math' | Package not installed (or wrong directory) | npm install crypto-fast-math; check node_modules/ | | The specified module could not be found (Windows) | Missing Visual C++ Redistributable | Install VC++ Redist x64 | | node-gyp-build fails during npm install | No prebuild for your platform — source fallback needs a toolchain | Windows: Visual Studio Build Tools with the C++ workload; macOS: xcode-select --install; Linux: sudo apt install build-essential | | ExprTk parse error: ERR239 - Undefined symbol | Variable not in params (names are case-sensitive) | Add the column to params or fix the typo | | Results are all NaN | Warm-up period is included in the output | Slice off the first period values: const clean = rsi.slice(13) | | all param columns must have equal length | Columns of different lengths | Slice/pad every column to the same length | | Array '<name>' must contain only numbers or null | Booleans/strings in a data column | Use 0/1; null/undefined become NaN |

Building from source

git clone https://github.com/Koderkup/crypto-fast-math.git
cd crypto-fast-math
npm install
npm run build        # compiles the C++ addon and the TypeScript

The build pipeline (as wired in package.json):

1. node-gyp configure — generates the platform build files.
2. node scripts/fix-vcxproj.js — Windows only: patches the generated .vcxproj to enable RTTI (/GR), C++ exceptions (/EHsc) and /bigobj. ExprTk needs them, but node-gyp disables them by default. No-op on Linux/macOS — those platforms emit a Makefile / Xcode project instead, and binding.gyp carries the equivalent flags anyway.
3. node-gyp build --release — compiles src/cpp/*.cpp into build/Release/addon.node.
4. tsc — compiles src/*.ts into dist/.

Requirements: Node.js ≥ 18, Python 3, and a C++17 compiler (MSVC Build Tools on Windows; Xcode command-line tools on macOS; build-essential/clang on Linux).

Supported compilers. node-gyp detects Visual Studio 2017–2022 Build Tools. Newer previews (e.g. VS 2026 / v18) may not be detected yet — install VS 2022 Build Tools alongside, or pin the version with npm config set msvs_version 2022. The same applies on CI: the workflow pins windows-2022 (which ships VS 2022) instead of windows-latest, because the latter may point to a newer image whose VS preview node-gyp cannot detect yet.

Windows. node-gyp does not auto-detect MSVC from a plain terminal — run the build commands from a Developer Command Prompt for Visual Studio (or call vcvarsall.bat x64 first), otherwise node-gyp configure fails with "Could not find any Visual Studio installation to use".

Running the tests

npm test            # builds the addon + TS, then runs the whole suite
npm run test:quick  # runs the suite against an already-built addon
npm run lint        # type-check only (tsc --noEmit)

The suite covers every indicator and the formula engine, including sync/async parity.

Publishing to npm (maintainers)

This package ships prebuilt binaries inside the npm tarball using prebuildify + node-gyp-build, so users get a working native module without a compiler.

The recommended flow is fully automated: .github/workflows/prebuilds.yml builds all five platform binaries on a v* git tag and publishes the package with the merged prebuilds/. Locally you can do the same by hand:

1. Build prebuilds for every target platform

prebuildify builds for the host OS/architecture only, so run it on each platform you want to support — locally or, better, in a CI matrix. The repo ships .github/workflows/prebuilds.yml with windows-2022, ubuntu-latest, ubuntu-24.04-arm and macos-14 (Apple Silicon; the Intel build runs there under Rosetta 2 with an x64 Node.js install). On Windows, run it from a Developer Command Prompt for Visual Studio so node-gyp can find MSVC.

npm run prebuild    # compiles the addon and writes prebuilds/<platform>-<arch>/*.node

Resulting layout:

prebuilds/
  win32-x64/crypto-fast-math.node
  linux-x64/crypto-fast-math.node
  linux-arm64/crypto-fast-math.node
  darwin-x64/crypto-fast-math.node
  darwin-arm64/crypto-fast-math.node

Because the binaries are built against Node-API, one prebuild per platform/arch works across Node and Electron versions — no need to rebuild per Node release.

prebuildify runs its own node-gyp build, but the MSVC flags (/GR, /EHsc, /bigobj) live in binding.gyp itself — so they survive prebuildify's rebuild, and scripts/fix-vcxproj.js stays belt-and-braces for the local npm run build path.

2. Check what will be published

npm pack --dry-run

Verify the listing contains prebuilds/, dist/, binding.gyp, src/cpp/, README.md, LICENSE and package.json — and nothing else (no build/, no test/, no node_modules/).

3. Log in and publish

npm login            # username + password + OTP (two-factor auth is required to publish)
npm publish          # for a scoped name add:  --access public

4. Verify

npm view crypto-fast-math
# in a clean directory:
npm install crypto-fast-math
node -e "console.log(require('crypto-fast-math').smaSync([1,2,3,4],2))"

Notes:

• Bump "version" (SemVer) before every publish — npm rejects duplicate versions.
• node-gyp-build (wired to the install script) resolves the matching bundled prebuild at install time and only falls back to compiling from source when no prebuild matches the user's platform.
• The files field is the whitelist; it takes precedence over .gitignore, so prebuilds/ and dist/ are included even though they are git-ignored.

License

MIT © Koderkup — see LICENSE.