@rethinkhealth/hl7v2-ast 0.2.3 → 0.2.5

package/README.md

@@ -2,23 +2,20 @@
 
 **H**ealth **L**evel **7** Version 2 **A**bstract **S**yntax **T**ree.
 
-***
-
-**hl7v2-ast** is a specification for representing HL7v2 messages as an [abstract syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree). It implements **[unist](https://github.com/syntax-tree/unist)** and provides a structured representation of HL7v2 segments, fields, components, and subcomponents.
+**hl7v2-ast** is a specification for representing HL7v2 messages as an [abstract syntax tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree). It implements **[unist](https://github.com/syntax-tree/unist)** and provides a structured, lossless representation of HL7v2 segments, fields, field repetitions, components, and subcomponents.
 
 ## Introduction
 
-This document defines a format for representing HL7v2 messages as an abstract syntax tree. 
+This document defines a format for representing HL7v2 messages as an abstract syntax tree.
 
-**hl7v2-ast** was created to support parsing, validation, and transformation of HL7v2 messages in a structured way.
+**hl7v2-ast** was created to support parsing, validation, transformation, and linting of HL7v2 messages in a structured way.
 
 The specification follows the [Unist](https://github.com/syntax-tree/unist) model to benefit from the ecosystem of utilities and the [Unified](https://unifiedjs.com) processing pipeline.
 
 ### Where this specification fits
 
-- **hl7v2-ast** extends [unist](https://github.com/syntax-tree/unist) with HL7-specific node types.
-- Integrates with editor tooling, validators, and transformers.
-
+* **hl7v2-ast** extends [unist](https://github.com/syntax-tree/unist) with HL7-specific node types.
+* Integrates with editor tooling, validators, and transformers.
 
 ## Types
 
@@ -28,6 +25,25 @@ TypeScript types are published with the package:
 npm install @rethinkhealth/hl7v2-ast
 ```
 
+---
+
+## Node Hierarchy
+
+The AST reflects the full HL7v2 delimiter hierarchy:
+
+```
+root
+└── segment
+    └── field (|)
+        └── field-repetition (~)
+            └── component (^)
+                └── subcomponent (&)
+```
+
+* Every **field** always contains one or more `field-repetition` nodes, even if there is no `~`.
+* Every **component** always contains one or more `subcomponent` nodes, even if there is no `&`.
+* Only `subcomponent` nodes carry `value`.
+
 ## Nodes (abstract)
 
 ### `Literal`
@@ -38,8 +54,7 @@ interface Literal <: UnistLiteral {
 }
 ```
 
-**Literal** represents a leaf HL7v2 node containing a `value`, such as a field,
-component, or subcomponent.
+Represents a leaf HL7v2 node containing a value. In this AST, the leaf is always a `subcomponent`.
 
 ### `Parent`
 
@@ -49,38 +64,45 @@ interface Parent <: UnistParent {
 }
 ```
 
-**Parent** represents a container node in HL7v2, such as `message` or `segment`.
+Represents a container node such as a `segment`, `field`, or `component`.
 
-## Nodes
+## Nodes (concrete)
 
-### `Message`
+### `Root`
 
 ```idl
-interface Message <: Parent {
-  type: 'message'
-  children: [Segment]
+interface Root <: Parent {
+  type: 'root'
+  children: [Segment | Group]
 }
 ```
 
-**Message** is the root of an HL7v2 document. It contains one or more `Segment` nodes.
+Root of an HL7v2 AST. Can represent a full message or a fragment.
+
+---
 
 ### `Segment`
 
 ```idl
 interface Segment <: Parent {
   type: 'segment'
-  name: string
-  index: number
-  delimiter: string
   children: [Field]
 }
 ```
 
-**Segment** represents an HL7v2 segment such as `MSH`, `PID`, or `OBX`.
+Represents an HL7v2 segment such as `MSH`, `PID`, or `OBX`.
 
-* `name` is the 3-letter segment code.
-* `index` is the segment's position in the message.
-* `delimiter` is the field separator used.
+### `Group`
+
+```idl
+interface Group <: Parent {
+  type: 'group'
+  name: string
+  children: [Segment]
+}
+```
+
+Represents a repeating or optional group of related segments (e.g., ORC+OBR+OBX).
 
 ### `Field`
 
@@ -88,16 +110,23 @@ interface Segment <: Parent {
 interface Field <: Parent {
   type: 'field'
   index: number
-  value?: string
-  delimiter?: string
-  children?: [Component]
+  children: [FieldRepetition]
 }
 ```
 
-**Field** represents a field within a segment.
+Represents a field inside a segment. **Always** contains one or more `field-repetition` nodes.
+
+### `FieldRepetition`
 
-* If the field contains components, it is a `Parent`.
-* If not, it is a `Literal` with a `value`.
+```idl
+interface FieldRepetition <: Parent {
+  type: 'field-repetition'
+  index?: number
+  children: [Component]
+}
+```
+
+Represents one `~`-separated instance of a field. **Always** contains one or more `component` nodes.
 
 ### `Component`
 
@@ -105,15 +134,11 @@ interface Field <: Parent {
 interface Component <: Parent {
   type: 'component'
   index: number
-  value?: string
-  delimiter?: string
-  children?: [Subcomponent]
+  children: [Subcomponent]
 }
 ```
 
-**Component** represents a component within a field.
-
-* Contains `Subcomponent` nodes if further split.
+Represents a `^`-separated component. **Always** contains one or more `subcomponent` nodes.
 
 ### `Subcomponent`
 
@@ -125,11 +150,11 @@ interface Subcomponent <: Literal {
 }
 ```
 
-**Subcomponent** represents the smallest value unit in an HL7v2 message.
+Represents an `&`-separated subcomponent and holds the actual text value.
 
 ## Position
 
-All nodes may include a `position` property following [unist]((https://github.com/syntax-tree/unist)):
+All nodes may include a `position` property following [unist](https://github.com/syntax-tree/unist):
 
 ```idl
 interface Position {
@@ -138,50 +163,17 @@ interface Position {
 }
 
 interface Point {
-  line: number    // 1-based segment line
-  column: number  // 1-based character column within the segment
-  offset: number  // 0-based character index in the entire message
-}
-```
-
-Example:
-
-```json
-{
-  "type": "field",
-  "index": 1,
-  "value": "DOE^JOHN",
-  "position": {
-    "start": { "line": 2, "column": 5, "offset": 48 },
-    "end": { "line": 2, "column": 14, "offset": 57 }
-  }
+  line: number
+  column: number
+  offset: number
 }
 ```
 
-## Delimiters
-
-HL7v2 messages use configurable delimiters. **hl7v2-ast** tracks delimiters per node for round-tripping.
-
-Default:
-
-```json
-{
-  "field": "|",
-  "component": "^",
-  "subcomponent": "&",
-  "repetition": "~",
-  "escape": "\\",
-  "segment": "\r"
-}
-```
-
-MSH-1 and MSH-2 are auto-detected unless overridden.
-
 ## Content model
 
 ```idl
 type HL7v2Content =
-  Message | Segment | Field | Component | Subcomponent
+  Root | Segment | Group | Field | FieldRepetition | Component | Subcomponent
 ```
 
 ## Extensions
@@ -192,7 +184,6 @@ The AST is designed for:
 * **Annotation plugins** (map to FHIR, metadata)
 * **Transformers** (to JSON, FHIR, XML)
 
-
 ## Contributing
 
 We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.

package/index.d.ts

@@ -1,59 +1,297 @@
-import type { Node, Position } from 'unist';
+import type {
+  Data as UnistData,
+  Literal as UnistLiteral,
+  Node as UnistNode,
+  Parent as UnistParent,
+} from 'unist';
+
+// ## Abstract nodes
+
+/**
+ * Union of registered HL7v2 literals.
+ *
+ * To register custom HL7v2 nodes, add them to {@link RootContentMap} and other
+ * places where relevant.
+ * They will be automatically added here.
+ */
+export type Literals = Extract<Nodes, UnistLiteral>;
+
+/**
+ * Union of registered HL7v2 parents.
+ *
+ * To register custom HL7v2 nodes, add them to {@link RootContentMap} and other
+ * places where relevant.
+ * They will be automatically added here.
+ */
+export type Parents = Extract<Nodes, UnistParent>;
+
+/**
+ * Union of registered HL7v2 nodes.
+ *
+ * To register custom HL7v2 nodes, add them to {@link RootContentMap} and other
+ * places where relevant.
+ * They will be automatically added here.
+ */
+export type Nodes = Root | RootContent;
 
 /**
- * HL7v2 Node specification following the Unist spec
+ * Info associated with HL7v2Node nodes by the ecosystem.
+ *
+ * This space is guaranteed to never be specified by unist or HL7v2Node.
+ * But you can use it in utilities and plugins to store data.
  *
- * @see https://github.com/syntax-tree/unist#node
+ * This type can be augmented to register custom data.
+ * For example:
+ *
+ * ```ts
+ * declare module '@rethinkhealth/hl7v2-ast' {
+ *   interface Data {
+ *     // `someNode.data.myId` is typed as `number | undefined`
+ *     myId?: number | undefined
+ *   }
+ * }
+ * ```
  */
-export interface HL7v2Node extends Node {
+export interface Data extends UnistData {}
+
+/**
+ * Abstract HL7v2 node.
+ *
+ * This interface is supposed to be extended.
+ * If you can use {@link Literal} or {@link Parent}, you should.
+ *
+ * For a union of all registered HL7v2 nodes, see {@link Nodes}.
+ */
+export interface Node extends UnistNode {
   /**
-   * The type of the node.
-   *
-   * There are 6 types of nodes:
-   * - **root**: The root node of the AST. This is the top-level node of the AST.
-   * - **segment**: A segment node (e.g. PID, MSH, etc.)
-   * - **header**: A header node (e.g. MSH, EVN, etc.)
-   * - **field**: A field node (e.g. PID.1, MSH.1, etc.)
-   * - **component**: A component node (e.g. PID.1.1, MSH.1.1, etc.)
-   * - **subcomponent**: A subcomponent node (e.g. PID.1.1.1, MSH.1.1.1, etc.)
+   * Info from the ecosystem.
    */
-  type: 'root' | 'segment' | 'header' | 'field' | 'component' | 'subcomponent';
+  data?: Data | undefined;
+}
 
+/**
+ * Abstract HL7v2 node that contains the smallest possible value.
+ *
+ * This interface is supposed to be extended if you make custom HL7v2 nodes.
+ *
+ * For a union of all registered mdast literals, see {@link Literals}.
+ */
+export interface Literal extends Node {
   /**
-   * The name of the node (e.g. "PID", "MSH", "EVN", etc.)
+   * Plain-text value.
    */
-  name?: string;
+  value: string;
+}
 
+/**
+ * Abstract HL7v2 node that contains other HL7v2 nodes (*children*).
+ *
+ * This interface is supposed to be extended if you make custom HL7v2 nodes.
+ *
+ * For a union of all registered mdast parents, see {@link Parents}.
+ */
+export interface Parent extends Node {
   /**
-   * The index of the node in the parent.
-   *
-   * This is valuable in HL7v2 where fields and components' order is
-   * relevant.
+   * List of children.
    */
-  index?: number;
+  children: RootContent[];
+}
 
+// ## Content Maps
+
+/**
+ * Union of registered mdast nodes that can occur in {@link Root}.
+ *
+ * To register custom mdast nodes, add them to {@link RootContentMap}.
+ * They will be automatically added here.
+ */
+export type RootContent = RootContentMap[keyof RootContentMap];
+
+/**
+ * Registry of all mdast nodes that can occur as children of {@link Root}.
+ *
+ * > **Note**: {@link Root} does not need to be an entire document.
+ * > it can also be a fragment.
+ *
+ * This interface can be augmented to register custom node types:
+ *
+ * ```ts
+ * declare module 'mdast' {
+ *   interface RootContentMap {
+ *     // Allow using toml nodes defined by `remark-frontmatter`.
+ *     toml: TOML;
+ *   }
+ * }
+ * ```
+ *
+ * For a union of all {@link Root} children, see {@link RootContent}.
+ */
+export interface RootContentMap {
+  segment: Segment;
+  group: Group;
+  field: Field;
+  fieldRepetition: FieldRepetition;
+  component: Component;
+  subcomponent: Subcomponent;
+}
+
+// ## Concrete nodes
+
+/**
+ * Document fragment or a whole document.
+ *
+ * Should be used as the root of a tree and must not be used as a child.
+ */
+export interface Root extends Parent {
+  /**
+   * Node type of HL7v2 root.
+   */
+  type: 'root';
   /**
-   * The value of the node. This is the raw value of the node.
-   *
-   * TODO: We might consider removing this property and use the children
-   * property instead.
+   * Data associated with the mdast root.
    */
-  value?: string;
+  data?: RootData | undefined;
+}
+
+/**
+ * Info associated with HL7v2 root nodes by the ecosystem.
+ */
+export interface RootData extends Data {}
 
+/**
+ * HL7v2 segment.
+ */
+export interface Segment extends Parent {
+  /**
+   * Node type of HL7v2 segment.
+   */
+  type: 'segment';
   /**
-   * The delimiter of the node.
+   * Children of block quote.
    */
-  delimiter?: string;
+  children: Field[];
+  /**
+   * Data associated with the mdast block quote.
+   */
+  data?: SegmentData | undefined;
+}
 
+/**
+ * Info associated with HL7v2 segment nodes by the ecosystem.
+ */
+export interface SegmentData extends Data {}
+
+/**
+ * HL7v2 group.
+ *
+ * A group is a set of segments that appear together in a defined order within a message.
+ * They are often used when a message needs to repeat a set of related segments together
+ * rather than just a single segment.
+ *
+ * Groups can be required/optional and repeating/non-repeating, just like segments.
+ */
+export interface Group extends Parent {
+  /**
+   * Node type of HL7v2 segment.
+   */
+  type: 'group';
+  /**
+   * Children of block quote.
+   */
+  children: Segment[];
+  /**
+   * Data associated with the mdast block quote.
+   */
+  data?: GroupData | undefined;
+}
+
+/**
+ * Info associated with HL7v2 segment nodes by the ecosystem.
+ */
+export interface GroupData extends Data {}
+
+/**
+ * HL7v2 field.
+ */
+export interface Field extends Parent {
+  /**
+   * Node type of HL7v2 field.
+   */
+  type: 'field';
+  /**
+   * Children of field.
+   */
+  children: FieldRepetition[];
+  /**
+   * Data associated with the mdast block quote.
+   */
+  data?: FieldData | undefined;
+}
+
+/**
+ * Info associated with HL7v2 segment nodes by the ecosystem.
+ */
+export interface FieldData extends Data {}
+
+/**
+ * HL7v2 field repetition.
+ */
+export interface FieldRepetition extends Parent {
+  /**
+   * Node type of HL7v2 field repetition.
+   */
+  type: 'field-repetition';
+  /**
+   * Children of field repetition.
+   */
+  children: Component[];
+  /**
+   * Data associated with the mdast block quote.
+   */
+  data?: FieldRepetitionData | undefined;
+}
+
+/**
+ * Info associated with HL7v2 field repetition nodes by the ecosystem.
+ */
+export interface FieldRepetitionData extends Data {}
+
+/**
+ * HL7v2 component.
+ */
+export interface Component extends Parent {
+  /**
+   * Node type of HL7v2 component.
+   */
+  type: 'component';
+  /**
+   * Children of component.
+   */
+  children: Subcomponent[];
   /**
-   * The children of the node.
+   * Data associated with the mdast block quote.
    */
-  children?: HL7v2Node[];
+  data?: ComponentData | undefined;
+}
 
+/**
+ * Info associated with HL7v2 segment nodes by the ecosystem.
+ */
+export interface ComponentData extends Data {}
+
+/**
+ * HL7v2 subcomponent.
+ */
+export interface Subcomponent extends Literal {
   /**
-   * The position of the node in the source text.
-   *
-   * This is used for round-tripping the AST back to the original text.
+   * Node type of HL7v2 subcomponent.
    */
-  position?: Position;
+  type: 'subcomponent';
+
+  /**
+   * Data associated with the mdast block quote.
+   */
+  data?: SubcomponentData | undefined;
 }
+
+export interface SubcomponentData extends Data {}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rethinkhealth/hl7v2-ast",
   "description": "HL7v2 is a specification for representing HL7v2 messages as an abstract syntax tree. It implements the unist spec.",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "license": "MIT",
   "author": {
     "name": "Melek Somai",
@@ -33,6 +33,6 @@
     "access": "public"
   },
   "scripts": {
-    "check-types": "tsc --noEmit"
+    "check-types": "tsc ./index.d.ts --noEmit"
   }
 }