Writing TypeScript transformers

Stages are ordinary TypeScript modules. They run on a Node.js worker pool inside the engine, which means modern syntax, real types, and the standard library you already know — not a decade-old embedded JavaScript runtime.

The editor

Each stage opens in a Monaco editor — the same editor component that powers VS Code — with type checking, completion and inline diagnostics. A type error shows up while you are typing, not after a deploy.

Types for healthcare payloads

npm type packages are available, so a FHIR transformer can be written against real resource shapes rather than any:

import type { Patient } from '@types/fhir/r4';

export default function transform(message: Patient): Patient {
  // Autocomplete and type errors work here.
  return message;
}

For HL7 v2, the engine exposes segment and field access helpers rather than making you index into a string by offset.

Run it before you deploy

The designer executes a stage in the browser, in a Web Worker, against whatever sample message you point it at. You get the output and any thrown error immediately.

This is the tightest loop in the product, and it is worth building the habit:

1. Pick a sample from the project’s test data.
2. Run the stage.
3. Read the output.
4. Adjust.

No deploy, no environment consumed, no waiting.

Practical guidance

• Fail loudly in the validator, quietly in the filter. A filter returning false is a normal outcome; a validator throwing is an incident.
• Keep the source transformer destination-agnostic. Anything that depends on which system receives the message belongs in a destination transformer.
• Prefer pure functions. A stage that only depends on its input is one you can test against a fixture and reason about later.
• Do not log payloads. Secret references are never rendered into logs or traces, and message bodies should not be either — particularly on plans where PHI is permitted.

From the editor to the repository

The stage you edit is a file in the project. Publishing creates a revision you can inspect and roll back to, and exporting the project gives you the same files on disk, ready to run on the open-source engine. Engine-level API detail lives in the intu-dev docs.