Skip to content
Nodus

The Nodus class

Nodus is the main entry point. One instance owns one graph and one rendering surface. It is exported as both a named and a default export.

import { Nodus } from '@kortexya/nodus';

Constructor

new Nodus<ND, ED>(params?)

The WebAssembly core auto-initializes on import via top-level await, so by the time the module resolves the engine is ready. There is no init function and no Nodus.create() — new Nodus({...}) is synchronous.

Parameters

params is an optional object. Known keys:

  • container — an HTMLElement or an element id string to render into. Omitting it runs Nodus headless (no rendering surface), which is useful for computing layouts or running algorithms server-side or in tests.
  • renderer — 'wasm' | 'canvas'. The wasm renderer uses the GPU (preferring WebGPU, with a WebGL2 build); canvas uses Canvas 2D. When WebGPU is absent Nodus falls back to Canvas 2D automatically. Passing an unknown renderer name throws and lists the valid names. See Rendering pipeline.

Any other options flow through setOptions(opts) / getOptions().

// Render into an element by reference.
const nodus = new Nodus({ container: document.getElementById('graph') });


// Or by id string, choosing the Canvas 2D renderer explicitly.
const canvasNodus = new Nodus({ container: 'graph', renderer: 'canvas' });


// Headless: no container, for compute-only work.
const headless = new Nodus();

Generics: ND and ED

ND is the type of each node’s data payload and ED the type of each edge’s data payload. They flow through to getData() / setData() on the element wrappers, giving you typed access to your own fields without affecting the visual attributes.

interface PersonData { label: string; age: number; }
interface KnowsData { since: number; }


const nodus = new Nodus<PersonData, KnowsData>({ container: 'graph' });
// node.getData() is typed as PersonData; edge.getData() as KnowsData.

Lifecycle

  • onReady(cb) — register a callback that runs once the instance is ready.
  • reset() — reset the instance to a clean state.
  • destroy() — tear down the instance and release its resources.
  • isDestroyed() — true after destroy().
  • isDebug() — whether debug mode is enabled.

nodus.build exposes build metadata as { version, commit, buildTime }.

nodus.onReady(() => console.log('ready', nodus.build.version));


// later, when you are done:
nodus.destroy();
console.log(nodus.isDestroyed()); // true

Settings

setOptions(opts: object): void
getOptions(): object

setOptions applies instance options; getOptions returns the current options. Constructor keys other than container and renderer are forwarded to setOptions. See Configuration for the options surface.

nodus.setOptions({ /* options */ });
const current = nodus.getOptions();

Graph and selection methods

The Graph API and selection methods are mixed directly onto the instance, so you call them on nodus, not on a sub-module:

await nodus.setGraph({ nodes: [{ id: 'a' }], edges: [] });
const a = nodus.getNode('a');
const selected = nodus.getSelectedNodes();

These are documented in full on Graph: nodes & edges (including the Node, Edge, NodeList and EdgeList wrappers and the selection helpers). Everything else is reached through the instance modules listed in the API overview.