Wave Binder

TypeScript library for state management with a focus in orchestrating interdependent parameters (nodes), with native support for data retriving from REST API

What It’s For

Wave Binder solves scenarios where one field depends on another:

• region -> province -> municipality
• dynamic lists of repeated elements
• complex objects with nested fields
• value calculation via custom function or backend call

The model is reactive: when a node changes, dependent nodes update automatically.

Requirements

• Node.js 18+ recommended
• npm

Installation & Build (library)

From the repo root:

cd wvb
npm install
npm run build

Compiled output in wvb/lib/.

Key Concepts

1) Node (ProtoNode)

Each node has:

• name: logical name
• path: data path
• type: SINGLE | MULTI | LIST | COMPLEX
• dep: dependencies on other nodes
• la: loading action (how to compute/load the value)
• optional defaultValue

2) Loading Action (la)

• USER_SELECTION: value chosen by the user
• GET | POST | PUT | DELETE | PATCH: loading via HTTP
• CUSTOM_FUNCTION: calculation via registered custom function

3) Node Types

• SINGLE: single value
• MULTI: value selected from a list of choices
• LIST: dynamic list of child nodes
• COMPLEX: object with child fields

Usage Flow (important)

Initialization

Initialization starts asynchronous validations in the background.

import { WaveBinder } from "wave-binder";

const wb = new WaveBinder(license, protoNodes, services, customFunctions);
wb.tangleNodes();

Main APIs (WaveBinder)

• isReady(): boolean: ready/not-ready state
• tangleNodes(): connects dependencies
• getNodes(): returns internal nodes
• getNodeByName(name): find node by name
• getNodeByNameAndType(name, type): find node by name + type
• getNodeChoicesByName(name): choices of a MULTI node
• getDataPool(): synthetic snapshot of values
• getNodesInfo(logDepth?): values + event logs
• addCustomFunction(fn, name): register runtime custom function
• nukeNodes(): full teardown of nodes + stop periodic license checks

HTTP Services Configuration

Pass a Map<string, HttpServiceSetting>:

const services = new Map();
services.set("RETRIEVE_DATA", {
  target: "http://localhost:3000/retrieve",
  secure: false,
  authorization: "Bearer token"
});

Notes:

• if authorization is set and no Authorization header is already present in the node, it is added automatically
• HTTP config logs redact sensitive headers (Authorization, token, cookie, api-key)

Custom Functions (security)

Only trusted functions via reference are allowed:

const customFunctions = [
  { name: "sum", implementation: (a: number, b: number) => a + b }
];

Optional: you can receive a read-only snapshot of the node as the last argument:

{ name: "sumWithCtx", implementation: (a, b, snapshot) => {
  // snapshot frozen at invocation time
  // snapshot.node: { name, type, path, value, iteration }
  // snapshot.depValuesByParameter: dependency values by parameterName
  return a + b;
}}

Recent Breaking Changes

1. Asynchronous bootstrap available in background
2. String-based custom functions disabled
3. Stricter backend/custom function error handling (fallback to null)
4. More aggressive node teardown on license invalidation

Troubleshooting

Error: "WaveBinder is not ready..."

The runtime state has been invalidated. Check license/connectivity and reinitialize the binder.

Empty nodes after startup

License is invalid or heartbeat failed. Check:

• signature payload
• expiration date
• license server reachability

CORS blocked on license server

Configure ALLOWED_ORIGINS with the calling origin.

HTTPS required on license server

Configure a TLS reverse proxy or set REQUIRE_HTTPS=false only for local development.