@vizij/wasm-loader

Shared loader helpers for Vizij WebAssembly packages.

@vizij/wasm-loader encapsulates the boilerplate required to initialise Vizij’s wasm-bindgen artefacts across browsers, Node, and Electron/Tauri hosts. The loader caches bindings, resolves file URLs, enforces ABI checks, and delegates to package-specific initialisers.

Table of Contents

1. Overview
2. API
3. Usage
4. Development & Testing
5. Related Packages

Overview

• Provides a single loadBindings helper that wraps wasm-bindgen initialisation (init(module, initArg)).
• Normalises file URL handling by reading file:// URIs via Node’s fs/promises when running outside the browser.
• Caches the returned bindings so repeated init() calls reuse the same module.
• Enforces ABI compatibility when the caller supplies an expectedAbi and getAbiVersion function.

API

import { loadBindings, type LoadBindingsOptions, type InitInput } from "@vizij/wasm-loader";

interface LoadBindingsOptions<TBindings> {
  cache: { current: TBindings | null };
  importModule: () => Promise<any>;
  defaultWasmUrl: () => URL | string;
  init: (module: any, initArg: unknown) => Promise<void>;
  getBindings?: (module: any) => TBindings;
  expectedAbi?: number;
  getAbiVersion?: (bindings: TBindings) => number;
}

• cache – Mutable holder for the currently loaded bindings (passed by reference from the consuming package).
• importModule – Dynamic import that resolves to the wasm-bindgen JS shim.
• defaultWasmUrl – Function returning the default .wasm location (new URL("./pkg/package_bg.wasm", import.meta.url).toString() in many packages).
• init – Async function that initialises the wasm module (module.default(initArg) for wasm-bindgen).
• getBindings – Optional extractor (defaults to returning the module itself).
• expectedAbi / getAbiVersion – Optional ABI guard to ensure wasm packages are rebuilt together.
• InitInput – Union covering strings, URLs, ArrayBuffers, WebAssembly.Module, and Response.

Usage

Each wasm npm package wraps loadBindings with package-specific defaults:

// Inside a Vizij wasm wrapper (simplified)
const cache = { current: null };

export async function init(input?: InitInput): Promise<void> {
  await loadBindings({
    cache,
    importModule: () => import("../../pkg/package.js"),
    defaultWasmUrl: () =>
      new URL("../../pkg/package_bg.wasm", import.meta.url).toString(),
    init: (module, initArg) => module.default(initArg),
    getBindings: (module) => module,
    expectedAbi: 2,
    getAbiVersion: (bindings) => bindings.abi_version?.(),
  }, input);
}

Consumers can override the init argument when hosting assets elsewhere:

import { init } from "@vizij/animation-wasm";
import { readFile } from "node:fs/promises";

const bytes = await readFile("dist/animation_wasm_bg.wasm");
await init(bytes); // load from a buffer instead of fetch()

The loader automatically converts file:// URLs into buffers when running under Node.

Extending for multi-module packages

If you expose separate debug/release builds, call loadBindings with different caches and default URLs for each variant. This keeps cached bindings isolated while sharing the same loader logic.

Error translation

Wrap initialisation in try/catch to present actionable messages (e.g. Failed to load animation engine: ABI mismatch). The loader surfaces meaningful strings—forward them to your UI or logs.

Bundler Notes

• Tree-shakeable ESM build with explicit browser and node exports.
• Browser bundles never include Node-specific code paths because the fs/promises import is behind a dynamic import().
• The browser entry (@vizij/wasm-loader/browser) skips the file:// handling path entirely.

Development & Testing

pnpm --filter @vizij/wasm-loader run build

@vizij/wasm-loader does not currently define a standalone test script; validate changes through the wrapper packages that consume it.

Related Packages

• @vizij/animation-wasm, @vizij/node-graph-wasm, @vizij/orchestrator-wasm – primary consumers of this loader.
• vizij-animation-wasm et al. – Rust crates that produce the wasm artefacts loaded through this helper.