@glion/builder

Tiny, typed helpers for assembling HL7v2 ASTs by hand.

What it does

@glion/builder provides five short functions (m, s, f, r, c) that wrap unist-builder and return nodes typed from @glion/ast. You build trees with a few function calls instead of nesting u('node-type', ...) boilerplate by hand, and the output is the same shape a parser would produce — so any Glion consumer (serializers, linters, annotators) can read it back. The builder is intentionally small: no hidden serialization, no format guessing, no HL7v2 semantics. You decide what the tree looks like; the helpers just reduce the typing.

Install

npm install @glion/builder

Use

import { c, f, m, s } from "@glion/builder";

const tree = m(
  s(
    f("MSH"), // include the segment header explicitly
    f("^~\\&")
  ),
  s(
    f("PID"),
    f(), // empty field
    f([
      c(["123456", "DOE", "JOHN"]), // arrays and individual args are interchangeable
    ])
  )
);

tree is a Root node containing two segments (MSH, PID). Pass it to @glion/to-hl7v2 to serialize, to @glion/jsonify to jsonify, or to any unist visitor to inspect it.

API

m(...children: RootContent[]): Root

Build a Root (message) node.

• No arguments → empty root.
• Pass any number of RootContent nodes (segments, fragments); they are appended in order.
• Arguments are used as-is. Pass concrete AST nodes rather than nested arrays.

s(...fields: Field[]): Segment

Build a Segment node.

• No arguments → empty segment.
• Include the header field yourself, typically f('PID'), as the first argument.
• Fields are appended in the order provided; the helper does not auto-flatten.

f(...values: Array<string | Component | FieldRepetition | Array<string | Component | FieldRepetition>>): Field

Build a Field node.

• No arguments → empty field with a single empty repetition.
• Strings become components with a single subcomponent containing the value.
• Component instances are added directly.
• FieldRepetition instances are preserved so you can control repetitions explicitly.
• Arrays are flattened one level, letting you mix individual values and grouped lists.
• Sequences of strings/components are grouped into a single repetition unless a FieldRepetition is introduced explicitly.

r(...components: Array<string | Component | Array<string | Component>>): FieldRepetition

Build a FieldRepetition node.

• No arguments → repetition with an empty component.
• Strings become components with a single subcomponent containing the value.
• Components are inserted as-is.
• Arrays are flattened one level for convenience.

c(...values: Array<string | string[]>): Component

Build a Component node.

• No arguments → component with an empty subcomponent.
• Strings become subcomponents.
• Arrays are flattened one level, so c('DOE', ['JOHN', 'Q']) works.

For advanced scenarios — multiple repetitions per field, custom metadata, node reuse — drop down to unist-builder (u) directly and mix those nodes with the helpers above.

Design

• Explicit. You build the same AST shape you would by hand. There is no hidden serialization logic or format guessing.
• Composable. Each helper is a thin wrapper over unist-builder, so raw nodes from u() and other utilities can be mixed freely.
• Minimal. A small surface means fewer abstractions to learn and less room for divergent interpretations of the HL7v2 model.

Experimental: empty mode

The builder respects the emptyMode experimental setting from @glion/config. When emptyMode: "empty" is configured in your .hl7v2rc.json, empty fields, repetitions, and components use empty children arrays instead of the legacy full structure:

// Legacy mode (default):
f(); // → Field → Rep → Comp → Sub("")

// Empty mode (via .hl7v2rc.json: { settings: { experimental: { emptyMode: "empty" } } }):
f(); // → Field with children: []

See @glion/config for configuration details.

Part of Glion

@glion/builder is part of Glion, the application framework for HL7v2. See the Glion README for the full package catalog and architecture.