@bonsae/node-red-type-check-plugin

Editor wire type-checking for @bonsae/nrg nodes — a Node-RED plugin that compiles a deployed flow into a TypeScript program and type-checks every connection under nrg's accumulating-record message model.

Because nrg nodes declare their ports as TypeScript types, a wire is only valid when the source's output is assignable to what the target reads off the shared, accumulating record. This plugin proves that with the real TypeScript compiler — no shipped .d.ts, no guessing.

Three sources fan into one invoice. It reads { order, customer }, and each incoming wire is checked against that on its own — the colour of each wire is decided entirely by the port types (a valid wire is left Node-RED's default grey; only problems are painted):

interface Order {
  id: string;
  total: number;
}
interface Customer {
  id: string;
  name: string;
}

// invoice READS both fields — both required
class Invoice extends IONode<
  never,
  never,
  Input<Port<{ order: Order; customer: Customer }>>,
  never
> {}

// full ADDS both        → valid: wire left grey
class Full extends IONode<
  never,
  never,
  never,
  Outputs<{ out: Port<{ order: Order; customer: Customer }> }>
> {}

// source ADDS only order → RED: customer is missing (its order is fine)
class Source extends IONode<
  never,
  never,
  never,
  Outputs<{ out: Port<{ order: Order }> }>
> {}

// untyped ADDS Port<any> → YELLOW: nothing to check the wire against
class Untyped extends IONode<
  never,
  never,
  never,
  Outputs<{ out: Port<any> }>
> {}

The source wire is red only because customer is missing — its order is the exact Order shape invoice reads. (Make Order.id a number on one side and that wire goes red for a type mismatch instead — same colour, different reason, which is why the port code is what to read.)

What it does

On every deploy (flows:started) it:

1. builds a registry of your node types (reads/adds) from the consumer's src/server,
2. compiles the whole flow into one TypeScript program (accumulating-record model — one call per node, wires as arguments),
3. type-checks each wire, and
4. reports per-wire verdicts to the Node-RED log and to the editor, which paints failing wires red.

It fails open — a checker problem never blocks authoring. Junction nodes are transparent (types flow straight through them); change/function and other core/non-nrg nodes are an unchecked (any) boundary, loudly reported.

The check is deploy-only — a wire's validity depends on the whole upstream accumulation, not just its two endpoints, so there is no per-wire probe. The whole-flow report is pushed over RED.comms on every deploy and the editor paints from it.

Admin routes (on Node-RED's admin API, default http://127.0.0.1:1880):

• GET nrg/type-check/status → { available: true } — the editor's feature gate
• GET nrg/type-check/flow → the latest full deploy report (curl-able)

A port's Data Schema narrows its type

Some ports have no static shape. A node that parses a body can only declare the widest honest type — a parsed JSON body is whatever the sender sent — so every downstream reader that wants a real field off it is unwireable, and correctly so.

The flow author knows the shape the node author can't, and already states it in that port's Data Schema, which nrg enforces at runtime. So when a port's Validate Data toggle is on, the checker renders that schema as a type and intersects it onto the port — turning a correctly-wired-but-unsatisfiable connection green, with no change to any node's code.

It is gated on the toggle because the check believes exactly what the runtime enforces: a schema sitting there with validation off is documentation, and documentation must not make a wire green. The two directions differ on purpose — an output schema is intersected onto what the port adds, so it can only ever turn a wire red → green; an input schema is an extra reader constraint per incoming wire, so it can turn one green → red, which is the point (the runtime would have thrown on that message anyway).

Data Schemas are written rooted at the whole message record, not at the port's own fragment, because that is what nrg hands the validator. See Narrowing a port with its Data Schema for the worked example.

Install

npm install @bonsae/node-red-type-check-plugin

Node-RED discovers it as a plugin automatically. Inside an nrg package, install it as a dev dependency and nrg dev auto-loads it from your node_modules — the dev wire check turns on with no further setup.

How types resolve

The checker reads the consumer's TypeScript source and resolves @bonsae/nrg from the consumer's own install — so this package depends only on typescript, never on @bonsae/nrg.

Development

pnpm install
pnpm build      # esbuild → dist/plugin.js (a single CommonJS file Node-RED requires)
pnpm validate   # tsc --noEmit + prettier
pnpm test       # vitest

The plugin is authored in TypeScript and bundled to CommonJS so Node-RED can require() it; the build normalises the default export onto module.exports, which is what Node-RED's plugin loader calls.

License

MIT