← Blog

Cosyte 0.1: fourteen libraries for healthcare data

The first post on this blog promised practical notes rather than launch posts. This is the one exception, and most of it is a list.

Every @cosyte library is now on npm at 0.1. There are fourteen of them: parsers for the eight standards healthcare data moves in (HL7 v2, FHIR, C-CDA, X12, NCPDP, ASTM, DICOM and MLLP), and six libraries that build on those parsers. All of them are MIT-licensed TypeScript for Node.js.

npm install @cosyte/hl7
import { parseHL7 } from "@cosyte/hl7";

// A synthetic admit, cut short: no PV1 segment, which an ADT^A01 should carry.
const msg = parseHL7(
  "MSH|^~\\&|ADT|HOSP|LIS|HOSP|20260925120000||ADT^A01^ADT_A01|MSG00001|P|2.5\r" +
    "EVN|A01|20260925120000\r" +
    "PID|1||MRN12345^^^HOSP^MR||ROE^SAM\r",
);

console.log(msg.patient?.mrn); // MRN12345
console.log(msg.warnings.map((w) => w.code)); // [ 'MISSING_EXPECTED_GROUP' ]

That is the whole idea in two lines of output. The message is incomplete, so the parser still reads what is there and tells you, with a stable code, what is missing. It does not throw, and it does not quietly fill the gap.

What 0.1 means

Each package’s public surface (the functions it exports, the shapes they return and its warning codes) is now the surface we keep stable. Below 1.0, a breaking change moves the minor version, and the changelog says how to migrate. Each README states what its release covers and what is still moving. We would rather you read that section than trust this paragraph.

What is in it

One parser per standard:

  • @cosyte/hl7 reads HL7 v2 by field name, with 20 stable warning codes for what real feeds get wrong.
  • @cosyte/mllp is the MLLP client and server: framing, acknowledgements correlated to their messages, and reconnects.
  • @cosyte/fhir reads and writes FHIR R4 JSON and XML without losing a decimal, then validates against the profiles you supply.
  • @cosyte/ccda turns C-CDA documents into typed models across fourteen entry families, and builds three document types.
  • @cosyte/x12 reads the HIPAA X12 5010 transaction sets, with every amount in exact decimal arithmetic.
  • @cosyte/ncpdp handles NCPDP Telecom pharmacy claims and SCRIPT ePrescribing in one package.
  • @cosyte/astm reads analyzer records and frames, verifies checksums, and takes its delimiters from the stream rather than from an assumption.
  • @cosyte/dicom reads the metadata of a DICOM Part 10 file without decoding a pixel.

And the libraries that build on them:

  • @cosyte/terminology resolves code systems, translates through ConceptMaps and validates UCUM units, over the releases you supply.
  • @cosyte/deid applies a HIPAA Safe Harbor policy to the fields you locate in a document, and writes a manifest that never holds a value.
  • @cosyte/transform maps HL7 v2 messages to FHIR R4 resources, grounded on HL7’s v2-to-FHIR implementation guide.
  • @cosyte/synth generates deterministic synthetic fixtures for six formats, each built through its parser’s own serializer.
  • @cosyte/dates converts and validates the dates the parsers return, without inventing a timezone.
  • @cosyte/cli puts the parsers in a terminal, and exposes the same commands to an agent over MCP.

The rules every package follows

  • Lenient on the way in. A parser accepts what real systems send and records what it tolerated.
  • Warnings you can log. A warning carries a stable code and a position rather than the value that caused it. Where a package makes an exception, its README says so.
  • Synthetic data only. Every example and fixture is invented. The thirteen repositories that handle messages run a PHI scan in CI; @cosyte/dates handles only date parts and has none.
  • Small dependency trees. The parsers have no runtime dependencies, except that C-CDA and the SCRIPT side of NCPDP each use one XML parser.

What it does not do

Every standards page lists the limits its package’s README states, and they are worth reading before you depend on anything. A few to know now: @cosyte/dicom never decodes pixels, @cosyte/deid never certifies anything and blocks free text until you bring a redactor, and @cosyte/mllp does not build batch acknowledgements. Pathways, the integration engine we are building, is not part of this release.

Where to start

The standards pages say what each standard is and where it shows up, with sources, and show each library’s example, limits and alternatives. The documentation has a quickstart per package.

If you would rather have the integration built for you, we build and run integrations on these same libraries, and the libraries stay free. The integration services page has the packages.

If one of these saves you a day, a star on its GitHub repository helps other engineers find it. If one of them reads a message wrong, open an issue with the smallest synthetic message that shows it.