wickra/docs/wiki/Quickstart-Node.md

Quickstart: Node

A five-minute tour of the Wickra Node.js binding. The binding is generated by napi-rs, so it's a native addon — no WebAssembly, no slow JS reimplementation.

Install

npm install wickra

Windows install caveat (current, 0.1.4). The platform-specific sub-package wickra-win32-x64-msvc@0.1.4 is presently held back by npm's automated spam filter. On a Windows x64 machine npm install wickra succeeds, but require('wickra') then throws Error: Cannot find module 'wickra-win32-x64-msvc' because the loader falls through to require('wickra-win32-x64-msvc') when no local .node binary is found. Linux x64 and macOS (x64 + arm64) wheels are unaffected. If you are on Windows today, build the binding from source (see "Building from source" below) until the npm side is resolved.

A first run

const wickra = require('wickra');

console.log('wickra', wickra.version());

// Simple moving average over a fixed window.
const sma = new wickra.SMA(3);
console.log(sma.batch([2, 4, 6, 8, 10]));
// -> [ NaN, NaN, 4, 6, 8 ]

Two things to notice:

1. The batch return type is a regular JavaScript Array<number>. Warmup slots are NaN, not null or undefined, so the array is Number.isFinite-checkable in one pass.
2. new wickra.SMA(0) does not throw. Constructors in the Node binding currently cannot raise errors from JS (a napi-rs 2.16 limitation), so pathological values like period = 0 are clamped to the smallest valid window. This is exactly the behaviour pinned by bindings/node/__tests__/smoke.test.js ("zero period is clamped to a valid window").

Streaming

const wickra = require('wickra');

const sma = new wickra.SMA(3);
for (const price of [2, 4, 6, 8, 10]) {
  const value = sma.update(price);
  console.log('update', price, '->', value);
}

Output:

update 2 -> null
update 4 -> null
update 6 -> 4
update 8 -> 6
update 10 -> 8

update returns either a JavaScript number or null while the indicator is still warming up. (Compare with batch, where warmup slots are NaN. The asymmetry exists because the streaming API surfaces "no value yet" through the JS type system, whereas the batch result is shaped as a numeric array for downstream numeric code.)

MACD: streaming and batch

MACD is the canonical multi-output indicator. The Node API surfaces this in two shapes:

• update(price) returns either null (during warmup) or { macd, signal, histogram }.
• batch(prices) returns a flat Array<number> of length prices.length * 3, laid out as [macd_0, signal_0, hist_0, macd_1, signal_1, hist_1, ...], with each warmup row written as three NaNs.

Streaming form:

const wickra = require('wickra');

const macd = new wickra.MACD(12, 26, 9);
let last = null;
for (let i = 0; i < 40; i++) {
  last = macd.update(100 + i * 0.5);
}
console.log(last);
// -> { macd: 3.5, signal: 3.500000000000001, histogram: -8.881784197001252e-16 }

Batch form (note the flat layout):

const wickra = require('wickra');

const prices = Array.from({ length: 40 }, (_, i) => 100 + i * 0.5);
const macd = new wickra.MACD(12, 26, 9);
const flat = macd.batch(prices);

console.log('total values:', flat.length);          // -> 120 (= 40 * 3)
console.log('row 33 :', flat.slice(99, 102));       // -> [ 3.5, 3.5, 0 ]
console.log('row 39 :', flat.slice(117, 120));      // -> [ 3.5, 3.5000000..., -8.88e-16 ]

// Reshape into 3-tuples if you want:
const rows = [];
for (let i = 0; i < flat.length; i += 3) {
  rows.push({ macd: flat[i], signal: flat[i + 1], histogram: flat[i + 2] });
}

MACD(12, 26, 9) emits its first non-NaN row at index 33 because the underlying Rust warmup_period() is slow + signal − 1 = 34 (the first ready row is warmup_period - 1 in 0-indexed terms).

API surface

The complete TypeScript definitions live at bindings/node/index.d.ts. Every indicator class exposes some subset of:

Member	Notes
constructor(...)	Pathological values are clamped, not thrown.
update(...)	Returns the indicator output or null during warmup.
batch(...)	Single-output: flat Array<number> with NaN warmup. Multi-output: flat interleaved Array<number>.
reset()	Returns to a freshly-constructed state.
isReady()	true once the first value has been emitted.
warmupPeriod()	Present on single-output indicators (SMA, EMA, WMA, RSI, ...). Not exposed on every multi-output class — check index.d.ts.

A complete reference run lives in bindings/node/__tests__/smoke.test.js:

cd bindings/node
npm install
npm run build       # only needed if you cloned the repo (Windows: see above)
npm test

Building from source (Windows workaround)

If you are on Windows x64 and want to use Wickra today, build the binding locally from the repository:

git clone https://github.com/kingchenc/wickra
cd wickra/bindings/node
npm install
npm run build       # requires a Rust toolchain (rustup) on PATH
npm test

npm run build produces wickra.win32-x64-msvc.node in the binding directory; the platform loader in index.js then picks it up before falling through to the npm sub-package and the install just works.

See also

• Quickstart: Python — sibling binding with NumPy shapes.
• Streaming vs Batch — why update is the primary entry point, not batch.
• Warmup Periods — exact warmup_period() for every indicator.
• Source: https://github.com/kingchenc/wickra