v0.1.0

HL7 v2 for Node.js and TypeScript. @cosyte/hl7 parses the messages hospital systems actually send,
vendor quirks included, and hands fields back by name (msg.patient?.mrn) rather than by position
(PID-3.1). It also builds messages and writes them back spec-clean.

npm install @cosyte/hl7@0.1.0

Node.js 22 or newer. ESM and CommonJS, with type declarations. No runtime dependencies. MIT.

What 0.1 means

This is the first release whose public API we treat as settled: the exported functions, the message
and helper surfaces, and the warning and finding codes. Renaming a warning code is a breaking change.
While the package is below 1.0, a breaking change bumps the minor version (0.1 to 0.2) and is called
out in the changelog; a fix that changes no public value ships as a patch.

What you can build on

• One-line reads through named helpers (msg.patient, msg.meta, msg.observations()), dot-paths
  (msg.get("PID.5.1")) or structural traversal.
• A lenient parser that tolerates what real feeds send and reports each deviation as a warning with a
  stable code and a position, never the field's value. Four structural failures are fatal;
  { strict: true } turns every warning into an error for CI.
• Eight built-in vendor profiles and defineProfile() for your own senders.
• Parse, modify and toString() to emit spec-clean HL7, with escape sequences re-emitted byte for byte.
• parseStream for batch files too large to buffer.

What changed

• Five new typed builders: buildOrm, buildSiu, buildMdm, buildDft and buildVxu, plus
  prior-identity content on the ADT builder for merges.
• Typed message overlays. msg.is("ADT^A01") answers at run time and narrows at compile time, so
  the accessors after the check are scoped to that message type's published structure.
• Opt-in structure validation. validateMessageStructure(msg) checks segment order and counts
  against HL7's published message structures, which the library now derives from HL7's
  machine-readable definitions: 94 message and trigger-event pairs, up from 32.
• Clinical status on the helpers. Observations and orders carry resultStatus (OBX-11 and OBR-25,
  classified by HL7's published tables), immunizations carry administrationStatus, and medications
  carry orderControl from ORC-1.
• Allergies from IAM as well as AL1, so an ADT^A60 no longer returns an empty list that reads
  as "no allergies recorded".
• Profiles can name fields on standard segments (segmentOverrides: { PID: { fields: { siteMrn: 19 } } }), and a profile's field names are checked by the compiler.
• Conformance profiles gain condition predicates, value sets bound to a coding system, declared
  conformance levels, component rules, and the C(a/b) and B usages.
• Schemas for toJSON(). emitMessageSchema produces the JSON Schema and Zod description of the
  serialized message.
• Dates. One conversion surface shared with the other @cosyte parsers (toObject, toISO,
  toDate); vendor date formats gain month names, AM/PM and 12-hour clocks; declared formats now
  reach every datetime the library returns.
• Segment names are matched regardless of case, so a sender shipping pid no longer loses the segment.

Upgrading from 0.0.x

• buildAdt refuses a merge event with no prior identity. For the ten triggers whose published
  structure requires MRG (A40, A41, A42, A43, A44, A45, A47, A49, A50 and A51), it used to return a
  message carrying a MISSING_EXPECTED_GROUP warning; it now throws a TypeError naming the message
  type and the member that would supply the segment. Pass the prior identity.
• msg.identityEvents() recognizes five more triggers, A45, A47, A49, A50 and A51, which used to
  return an empty list.
• An order-ambiguous slash date is refused instead of being read in US order. If you relied on
  that default, declare it: parseHL7(raw, { dateFormats: ["MM/DD/YYYY"] }).
• dateFormats is validated strictly: a format that constructed and never matched now throws where
  you wrote it.
• Conformance profiles: a usage paired with a cardinality the methodology disallows is refused when
  the profile is defined; FindingCode gains PROFILE_UNDECLARED_CONTENT and UsageCode gains B
  and the conditional form, so exhaustive switch statements need new cases.
• msg.allergies() now also returns entries from IAM segments.
• Immunization gains the required administrationStatus key, so code that builds Immunization
  objects by hand must supply it.

Not covered

• Network transport: MLLP framing is stripped on read, and sending or receiving over a socket belongs
  to @cosyte/mllp.
• Conversion to FHIR. That is @cosyte/transform.
• HL7 v3 and CDA: the parser reads v2 only. C-CDA documents are @cosyte/ccda.
• Exhaustive coded-value validation: the library validates structure, not every coded value against
  every HL7 table.

Links

• Docs: https://docs.cosyte.com/hl7?utm_source=github&utm_medium=release&utm_campaign=cosyte-0-1-launch&utm_content=release-hl7
• Quickstart: https://docs.cosyte.com/hl7/quickstart?utm_source=github&utm_medium=release&utm_campaign=cosyte-0-1-launch&utm_content=release-hl7
• Source: https://github.com/cosyte/hl7
• npm: https://www.npmjs.com/package/@cosyte/hl7/v/0.1.0
• Full changelog: https://github.com/cosyte/hl7/blob/main/CHANGELOG.md

v0.0.10

What changed

• The README lockup now links to cosyte.com (ASSETS).

Full detail for each change is in CHANGELOG.md.

Install

npm install @cosyte/hl7@0.0.10

npm: https://www.npmjs.com/package/@cosyte/hl7/v/0.0.10

v0.0.9

What changed

• CHANGELOG.md, which ships inside the tarball, is now written by the release instead of by hand, so it stops describing already-published code as unreleased.

Full detail for each change is in CHANGELOG.md.

Install

npm install @cosyte/hl7@0.0.9

npm: https://www.npmjs.com/package/@cosyte/hl7/v/0.0.9

v0.0.8

What changed

Internal tooling and CI only. No change to the published package surface.

Install

npm install @cosyte/hl7@0.0.8

npm: https://www.npmjs.com/package/@cosyte/hl7/v/0.0.8

v0.0.7

What changed

• The attw publish gate no longer reports a pass on a tarball that carries no types.
• The PHI commit-gate no longer reads a symbolic link as clean.

Full detail for each change is in CHANGELOG.md.

Install

npm install @cosyte/hl7@0.0.7

npm: https://www.npmjs.com/package/@cosyte/hl7/v/0.0.7

v0.0.6

What changed

• The PHI scan no longer refuses an entire sweep when a build tool's transient file vanishes before it can be read; that one file is skipped and reported instead, and everything else still refuses.

Full detail for each change is in CHANGELOG.md.

Install

npm install @cosyte/hl7@0.0.6

npm: https://www.npmjs.com/package/@cosyte/hl7/v/0.0.6

v0.0.5

What changed

• The README now opens with the Cosyte mark, which follows the reader's color scheme, in place of the per-package banner.

Full detail for each change is in CHANGELOG.md.

Install

npm install @cosyte/hl7@0.0.5

npm: https://www.npmjs.com/package/@cosyte/hl7/v/0.0.5

v0.0.4

What changed

• Add the cosyte brand banner to the top of the README, so the npm package page and the repo page both open with the mark, the package name, and one line of what the parser does.
• Correct four wrong claims in the README feature list: the package needs Node 22 and targets ES2023, and it carries 20 stable warning codes rather than 18.
• Fix a defect where a warning or error message could carry clinical text into a log line: on default settings, an unescaped line break inside a narrative field put field content into the message.

Full detail for each change is in CHANGELOG.md.

Install

npm install @cosyte/hl7@0.0.4

npm: https://www.npmjs.com/package/@cosyte/hl7/v/0.0.4

v0.0.3

What changed

• Doc comments that ship in the type declarations are cleaned of internal project references and gated against their return.
• The documentation pages shipped with this package no longer carry internal project references, and a CI check keeps them out.

Full detail for each change is in CHANGELOG.md.

Install

npm install @cosyte/hl7@0.0.3

npm: https://www.npmjs.com/package/@cosyte/hl7/v/0.0.3

v0.0.2

What changed

• Add conformance-profile tooling: validateAgainstProfile.
• Add the FHIR-bridge IR-stability contract + coverage proof.
• Re-ground profiles.meditech to a publicly downloadable MEDITECH interface specification.
• Add a performance / throughput bar: reproducible benchmark suite + a ratio-based perf-regression guard.
• Add profiles.philips, the seventh built-in vendor profile: Philips Vue PACS ("IS Link") imaging.
• Add streaming / incremental parse: parseStream.
• Add formatted-text rendering + a first-class text codec.
• Add typed emit symmetry: composite setters + buildAdt / buildOru.
• Add profiles.va, the eighth built-in vendor profile: VA VistA Radiology/Nuclear Medicine imaging.
• Add profiles.visage, the sixth built-in vendor profile: Visage 7 imaging/PACS.

Full detail for each change is in CHANGELOG.md.

Install

npm install @cosyte/hl7@0.0.2

npm: https://www.npmjs.com/package/@cosyte/hl7/v/0.0.2