Przejdź do treści
Biblioteka skilli
Medycyna i zdrowie · Konwersja i formaty

cosyte-transform

/cosyte-transform

Konwertuje sparsowane wiadomości HL7 v2 do FHIR R4, mapując na przykład PID na Patient, PV1 na Encounter i wyniki OBX na Observation.

Repozytorium
agent-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
5
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Konwertuje sparsowane wiadomości HL7 v2 do FHIR R4, mapując na przykład PID na Patient, PV1 na Encounter i wyniki OBX na Observation.

Oryginalny opis (EN)

Convert parsed HL7 v2 messages to FHIR R4 with @cosyte/transform, grounded on the HL7 Version 2 to FHIR implementation guide. Use when a developer says convert this HL7 message to FHIR, map PID to Patient or PV1 to Encounter, turn an ORU^R01 OBX into Observation and DiagnosticReport, map ORM_O01 or OML_O21 orders to ServiceRequest and MedicationRequest, or convert VXU_V04, SIU_S12 or MDM_T02 to Immunization, Appointment or DocumentReference. toFhir returns a FHIR message Bundle plus value-free diagnostics. Also covers the six datatype converters (DTM, CX, CWE, XPN, XAD, NM to FHIR) and the nar

Jak działa

  1. When to use it
  2. Install
  3. Minimal example
  4. Key API
  5. Limits and known defects
  6. PHI handling
  7. Docs
Sekcje z nagłówków SKILL.md, w oryginale · 158 linii, 1 192 słów
Podgląd SKILL.md
---
name: cosyte-transform
description: "Convert parsed HL7 v2 messages to FHIR R4 with @cosyte/transform, grounded on the HL7 Version 2 to FHIR implementation guide. Use when a developer says convert this HL7 message to FHIR, map PID to Patient or PV1 to Encounter, turn an ORU^R01 OBX into Observation and DiagnosticReport, map ORM_O01 or OML_O21 orders to ServiceRequest and MedicationRequest, or convert VXU_V04, SIU_S12 or MDM_T02 to Immunization, Appointment or DocumentReference. toFhir returns a FHIR message Bundle plus value-free diagnostics. Also covers the six datatype converters (DTM, CX, CWE, XPN, XAD, NM to FHIR) and the narrow reverse path from a FHIR Patient or Observation to an HL7 v2 message with a PID or OBX. For parsing HL7 use cosyte-hl7; for FHIR resources on their own use cosyte-fhir; for code systems and ConceptMaps use cosyte-terminology."
license: MIT
metadata:
  package: "@cosyte/transform"
  version: "0.2.1"
  docs: "https://docs.cosyte.com/transform/intro"
---

# @cosyte/transform

HL7 v2 to FHIR R4 transformation for Node.js and TypeScript. It takes messages already parsed by
`@cosyte/hl7`, produces `@cosyte/fhir` model nodes grounded on the official HL7 Version 2 to FHIR
implementation guide (`hl7.fhir.uv.v2mappings`), and reports every ambiguity as a typed,
value-free `TransformIssue` instead of guessing.

## When to use it

- "Convert this HL7 v2 message to FHIR", "map an ADT^A01 to Patient and Encounter".
- ADT with NK1, AL1, DG1, PR1 and IN1 to RelatedPerson, AllergyIntolerance, Condition,
  Procedure and Coverage.
- ORU^R01 to DiagnosticReport, Observation and Specimen.
- ORM_O01 or OML_O21 to ServiceRequest, RXO to MedicationRequest, TQ1 to a FHIR Timing.
- VXU_V04 to Immunization, SIU_S12 to Appointment, MDM_T02 to DocumentReference.
- Converting a single v2 datatype: DTM/TS, CX, CWE/CE, XPN, XAD, NM with units.
- Rendering the diagnostics as a FHIR OperationOutcome.
- Emitting a v2 message carrying a PID or OBX from a FHIR Patient or Observation (narrow, lossy).

Use another skill when:

- parsing or reading the HL7 message itself: `cosyte-hl7`;
- reading, validating or serializing FHIR resources on their own: `cosyte-fhir`;
- code systems, ConceptMaps, UCUM or RxNorm: `cosyte-terminology`;
- receiving HL7 over a socket: `cosyte-mllp`; synthetic fixtures: `cosyte-synth`.

## Install

```bash
npm install @cosyte/transform @cosyte/hl7 @cosyte/fhir
```

`@cosyte/hl7` and `@cosyte/fhir` are peer dependencies at `^0.1.8` (since 0.2.1): install them
beside it and parse with `@cosyte/hl7` before you transform. No third-party runtime dependencies.
Node `>=22.0.0`. Dual ESM and CommonJS builds with type declarations for both.

## Minimal example

Transform a synthetic ADT^A01, log the issues, then read the PID fields the Patient does not carry
(see the first limit below) straight from the parsed message.

```ts
import { serializeResource } from "@cosyte/fhir";
import { parseHL7 } from "@cosyte/hl7";
import { createNamingSystem, toFhir } from "@cosyte/transform";

// A synthetic ADT^A01. Every name, identifier and date is invented.
const raw =
  "MSH|^~\\&|ADTAPP|MAIN|FHIRGW|REF|20260419101500||ADT^A01^ADT_A01|MSG00001|P|2.5\r" +
  "EVN|A01|20260419101500\r" +
  "PID|1||MRN12345^^^HOSP^MR||Doe^John^Q||19800115|M||2106-3^White^CDCREC|" +
  "123 Main St^^Boston^MA^02101||||en^English^ISO639|||||||" +
  "2186-5^Not Hispanic or Latino^CDCREC|||||||20260418|Y\r" +
  "PV1|1|I|ICU^101^A^HOSP||||||||||||||||VISIT001\r";

const msg = parseHL7(raw);

const { bundle, issues } = toFhir(msg, {
  // Seed every assigning authority you trust. A bare HD.1 never becomes a system on its own.
  namingSystem: createNamingSystem({ authorities: { HOSP: "https://example.org/fhir/sid/mrn" } }),
});

console.log(serializeResource(bundle).length, "bytes of FHIR JSON");
for (const i of issues) {
  // Value-free: a stable code, the v2 location and the FHIR path. Safe to log.
  console.log(i.severity, i.code, i.v2Location, i.fhirPath ?? "");
}

// toFhir reports these six PID fields as dropped but does not map them. Read them here.
const p = msg.patient;
const race = p?.race?.identifier; // PID-10
const language = p?.language?.identifier; // PID-15
const hasSsn = (msg.get("PID.19") ?? "") !== ""; // PID-19: check presence, do not copy it around
const ethnicity = p?.ethnicity?.identifier; // PID-22
const deathDateTime = msg.segments("PID")[0]?.field(29).asTs(); // PID-29, fidelity TS
const deathIndicator = msg.get("PID.30"); // PID-30, "Y" means deceased
const recordedDeceased = deathIndicator === "Y" || deathDateTime?.valid === true;
console.log({ race, language, hasSsn, ethnicity, recordedDeceased });
```

This MSH-7 has no timezone, so the transform reduces it to date precision and raises
`TRANSFORM_TIMESTAMP_NO_TIMEZONE` rather than assuming UTC. Pass
`assumeTimezoneOffsetMinutes` only when you know the sender's offset.

## Key API

- `toFhir(msg, opts?)`: parsed `Hl7Message` in, `{ bundle, issues }` out; `bundle` is a FHIR R4
  message Bundle (MessageHeader first, references resolve to `urn:uuid:` fullUrls). Options:
  `namingSystem`, `assumeTimezoneOffsetMinutes`, `generateId` (deterministic fullUrls for tests).
- `createNamingSystem({ authorities, codeSystems })`: assigning authority (HD) to
  `Identifier.system`, v2 coding-system mnemonic to canonical URI. `DEFAULT_V2_CODE_SYSTEMS` is
  the built-in seed.
- Datatype converters returning `{ value, issues }`: `toFhirDateTime`, `toFhirIdentifier`,
  `toFhirCodeableConcept`, `toFhirHumanName`, `toFhirAddress`, `toFhirQuantity`.
- `toFhirCodeableConceptVia(cwe, map)` with IG value maps such as `ROUTE_VALUE_MAP`,
  `SITE_VALUE_MAP`, `APPOINTMENT_TYPE_VALUE_MAP`, `SUBSTITUTION_VALUE_MAP`,
  `ALLERGY_CATEGORY_VALUE_MAP`, `ALLERGY_TYPE_VALUE_MAP`, `ALLERGY_CRITICALITY_VALUE_MAP`.
- `toOperationOutcome(issues)`: the issues as a FHIR OperationOutcome node.
- `ISSUE_CODES`, `ISSUE_REGISTRY`, and the `TransformIssue` type (`code`, `severity`,
  `v2Location`, `fhirPath`, `message`).
- `toV2Patient(resource, trigger, options?)`, `toV2Observation(resource, trigger, options?)`:
  FHIR to a v2 `ADT^<trigger>` with a PID or `ORU^<trigger>` with an OBX.
- `IG_MAPPED_ADT_TRIGGERS`, `IG_MAPPED_ORU_TRIGGERS`, `IG_MAPPED_ORDER_TRIGGERS` and siblings:
  triggers with an IG message map; others are segment-assembled and flagged.

## Limits and known defects

- The PID to Patient map carries only PID-3, 5, 7, 8 and 11, and only the first repetition of
  PID-5 and PID-11. Since 0.2.0 each valued PID-10 race, PID-15 language, PID-19 SSN, PID-22
  ethnicity, PID-29 death date and PID-30 death indicator raises `TRANSFORM_ELEMENT_DROPPED`
  (information severity) at its own location, and PID-13 and PID-14 telecom raise one each at
  `PID.13` and `PID.14`; none of them is mapped. Never treat a Patient with no `deceased[x]` as
  alive: check the issues for `PID.29` and `PID.30`, or read those six fields from the parsed message
  with `@cosyte/hl7`, as the example does, and carry them yourself.
- A valued PID-7, PV1-44, PV1-45 or MSH-7 that `@cosyte/hl7` cannot read as a date is left out of
  the Bundle and raises `TRANSFORM_TIMESTAMP_DROPPED_BY_PARSER` (since 0.2.0). A timestamp part out
  of range, such as hour 25 or 31 February, or an offset outside -14:00 to +14:00, is dropped with
  `TRANSFORM_ELEMENT_DROPPED` and the value keeps the parts it can place.
- "Validated" means a small internal required-element check, not FHIR conformance. None of the
  IG's seven test messages yields a Bundle clean against FHIR R4 plus US Core 9.0.0; six of seven
  are clean against base R4 (SIU_S12 breaks `app-3`). Validate against your own profiles. A clean
  Bundle does not prove the right v2 field reached the right FHIR element.
- No profiles and no terminology content ship. Fields whose IG target is SNOMED CT stay
  structural unless you supply a ConceptMap; TXA-2 and RXA-5 are carried as-is.
- No Practitioner, Location or Organization is built; those references are deferred with an
  issue. `Coverage.status` is never asserted (read it as unknown, not active), `Coverage.payor` is
  a display only, and `Procedure.status` is `unknown` unless the message determines it.
- An unseeded assigning authority gives an identifier with no system plus
  `TRANSFORM_IDENTIFIER_SYSTEM_UNRESOLVED`. A naked timestamp loses its time of day.
- RXE has no IG map: flagged, never assembled. A TQ1 schedule is fully grounded or withheld.
- Resources that fail the emit gate are withheld (`TRANSFORM_RESOURCE_INVALID`); with no
  Patient, AL1, DG1, PR1 and IN1 resources are withheld too. Segments that reached nothing raise
  `TRANSFORM_SEGMENT_NOT_EMITTED` or `TRANSFORM_SEGMENT_NO_IG_MAP`.
- The FHIR to v2 path is narrow, lossy and not a round trip. The trigger is always yours
  (`TRANSFORM_MISSING_TRIGGER` otherwise); many-to-one codes are refused
  (`TRANSFORM_CODE_NOT_INVERTIBLE`). Any wider FHIR to v2 conversion is not implemented.
- Check `issues` on every call and act on the codes; do not ship a Bundle unread.

## PHI handling

- Every `TransformIssue` is value-free: a stable code, a v2 location, a FHIR path and a static
  message, never a field value. Issue messages are safe to log verbatim, and
  `toOperationOutcome` reads only issue metadata.
- An unclassifiable segment name is located as `[#4]` with no part of the name reproduced.
- The Bundle and any v2 message from the reverse path are the converted patient data: protect
  them like the source message.
- Use synthetic data in tests and examples. Never paste real patient data into prompts, fixtures
  or logs.

## Docs

- https://docs.cosyte.com/transform/intro
- https://www.npmjs.com/package/@cosyte/transform
- https://github.com/cosyte/transform
- [references/REFERENCE.md](references/REFERENCE.md): the segment to resource map, per-family
  notes and refusals, the reverse path, and the issue code list.
Pliki w paczce (2)
  • SKILL.md 10 KB
  • references/REFERENCE.md 13 KB

Wersje

W bazie nie ma innych skilli o nazwie cosyte-transform.

Migawka bazy z 13.11.2026 · wersja paczki bcb118a7f1fe (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100ehr-data-parsing
    Parsuje i wyciąga dane kliniczne z wiadomości HL7v2 i zasobów FHIR R4 w Pythonie: segmenty PID, OBX i MSH, zasoby Patient i Observation, wiadomości ADT i ORU oraz konwersja HL7 do FHIR.
  • 100cosyte-fhir
    Czyta, waliduje i zapisuje zasoby FHIR R4 w TypeScript, zachowuje precyzję liczb dziesiętnych i sprawdza profile, na przykład US Core.
  • 100cosyte
    Kieruje zadania danych medycznych w Node.js i TypeScript do właściwego pakietu @cosyte i jego skilla, na przykład dla HL7 v2, X12, FHIR, C-CDA czy DICOM.
  • 100curatr
    Ocenia jakość danych FHIR w dokumentacji medycznej pacjenta, wskazuje błędne kody i brakujące pola prostym językiem, stosuje zatwierdzone poprawki z Provenance i przygotowuje prośbę do placówki.
  • 100fhir-info
    Podaje pola, typy, liczności, cele referencji i wartości słownikowe zasobów FHIR R4, pomagając pisać konwertery i sprawdzać zgodność ze standardem.
  • 100fhir-api
    Wspiera implementację serwerów i klientów FHIR REST zgodnie ze specyfikacją HL7: operacje, wyszukiwanie, historia, bundle, transakcje i negocjacja treści.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.