Package Exports

@vizij/node-graph-wasm

Readme

@vizij/node-graph-wasm

Vizij’s node graph engine for JavaScript.

This package ships the WebAssembly build of vizij-graph-core together with a TypeScript wrapper, schema helpers, and sample graphs. Load Vizij GraphSpecs, stage host inputs, evaluate outputs, and update node parameters from any modern JS runtime without compiling Rust.

Overview
Key Concepts
Installation
API
Usage
Samples & Fixtures
Development & Testing
Related Packages

Overview

Built from vizij-graph-core with wasm-bindgen; the npm package is the canonical JavaScript distribution maintained by the Vizij team.
Provides a high-level Graph class, low-level bindings, TypeScript definitions, and ready-to-use fixtures.
Supports both browser and Node environments—init() chooses the right loader and validates the ABI (abi_version() === 2).
Ships GraphSpec normalisers and schema inspection helpers so editors and tooling can speak the same language as Vizij runtimes.

Key Concepts

GraphSpec – Declarative JSON describing nodes, parameters, and the explicit links array that connects node outputs to inputs (selectors, output keys). The package normalises shorthand specs automatically.
Graph Runtime – The Graph class owns a GraphRuntime, handling loadGraph, stageInput, setParam, step, and evalAll.
Staged Inputs – Host-provided values keyed by TypedPath. They are latched until you replace or remove them.
Evaluation Result – evalAll() returns per-node port snapshots plus a WriteBatch of sink writes (each with Value + Shape metadata).
Node Schema Registry – getNodeSchemas() exposes the runtime-supported nodes, ideal for palettes/editors.
ABI Guard – abi_version() ensures the JS glue and .wasm binary are compatible. Rebuild when versions change.

Installation

npm install @vizij/node-graph-wasm
# or pnpm add @vizij/node-graph-wasm

For local development inside Vizij:

pnpm run build:wasm:graph
cd npm/@vizij/node-graph-wasm
pnpm install
pnpm run build

Link into vizij-web while iterating:

(cd npm/@vizij/node-graph-wasm && pnpm link --global)
(cd ../vizij-web && pnpm link @vizij/node-graph-wasm)

API

async function init(input?: InitInput): Promise<void>;
function abi_version(): number;
async function normalizeGraphSpec(spec: GraphSpec | string): Promise<GraphSpec>;
async function getNodeSchemas(): Promise<Registry>;
const graphSamples: Record<string, GraphSpec>;

class Graph {
  constructor();
  loadGraph(specOrJson: GraphSpec | string): void;
  unloadGraph(): void;
  stageInput(path: string, value: ValueInput, shape?: ShapeJSON, immediateEval?: boolean): void;
  clearStagedInputs(): void;
  applyStagedInputs(): void;
  evalAll(): EvalResult;
  setParam(nodeId: string, key: string, value: ValueInput): void;
  setTime(t: number): void;
  step(dt: number): void;
  getWrites(): WriteOpJSON[];
  clearWrites(): void;
  waitForGraphReady?(): Promise<void>; // only populated when used through React provider
}

Normalization & Schema Helpers

normalizeGraphSpec(spec) – round-trips any GraphSpec (object or JSON string) through the Rust normaliser so shorthand inputs/legacy inputs maps come back with explicit links, typed paths, and canonical casing.
getNodeSchemas() – returns the runtime node registry (including new controllers like case, default-blend, weighted blend helpers, etc.) for palette/editor usage.
graphSamples – curated ready-to-load specs that already reflect the canonical links form and typed path parameters.

Types (GraphSpec, EvalResult, ValueJSON, ShapeJSON, etc.) are exported from src/types.

Usage

import {
  init,
  Graph,
  normalizeGraphSpec,
  graphSamples,
  valueAsNumber,
} from "@vizij/node-graph-wasm";

await init();

const graph = new Graph();
const spec = await normalizeGraphSpec(graphSamples.vectorPlayground);
graph.loadGraph(spec);

graph.stageInput("demo/path", { float: 1 }, undefined, true);
const result = graph.evalAll();

const nodeValue =
  result.nodes["const"]?.out?.value ?? { type: "float", data: NaN };
console.log("Node value", valueAsNumber(nodeValue));

for (const write of result.writes) {
  console.log("Write", write.path, write.value);
}

Manual time control:

graph.setTime(0);
graph.step(1 / 60);
graph.evalAll();

Staging inputs lazily:

graph.stageInput("demo/path", { vec3: [0, 1, 0] });
graph.applyStagedInputs();
graph.evalAll();

Samples & Fixtures

The package exports several ready-to-run specs:

graphSamples map (e.g., vectorPlayground, oscillatorBasics, logicGate).
Named exports (oscillatorBasics, nestedTelemetry, etc.) for convenience.

Helpers:

import { loadNodeGraphBundle } from "@vizij/node-graph-wasm";

const { spec, stage } = await loadNodeGraphBundle("urdf-ik-position");
graph.loadGraph(spec);
if (stage) {
  for (const [path, payload] of Object.entries(stage)) {
    graph.stageInput(path, payload.value, payload.shape);
  }
}

Fixtures originate from @vizij/test-fixtures so tests and demos share the same assets.

Development & Testing

pnpm run build:wasm:graph          # regenerate pkg/
cd npm/@vizij/node-graph-wasm
pnpm test

The Vitest suite runs sample graphs through the wasm bridge, checking evaluation results and write batches. For Rust-side coverage, run cargo test -p vizij-graph-wasm.

vizij-graph-wasm – Rust crate producing the wasm build.
vizij-graph-core – underlying evaluator.
@vizij/node-graph-react – React integration built on this npm package.
@vizij/value-json – shared value helpers used during staging.

Need assistance or spot a bug? Open an issue—robust bindings keep Vizij graphs portable. 🧠

JSPM