Skip to main content
Version: v0.0.3

Class: CcdaDocument

The immutable parsed C-CDA document. Carries the recognized identity, the header, the top-level sections (empty for an unstructured document, see nonXmlBody), and the frozen lenient-parse warnings.

Example​

import { parseCcda } from "@cosyte/ccda";
const doc = parseCcda(xml);
console.log(doc.documentType, doc.getPatient()?.name?.text, doc.getMrn());

Constructors​

Constructor​

new CcdaDocument(init): CcdaDocument

Internal

Construct a CcdaDocument. Freezes the warnings array (after a slice) so callers cannot mutate parser output after handoff.

Parameters​

init​

CcdaDocumentInit

Returns​

CcdaDocument

Properties​

allergies​

readonly allergies: readonly AllergyConcern[]

Extracted Allergy Concern Acts (across all sections). Empty when none.

documentType​

readonly documentType: DocumentType | undefined

The recognized document type, or undefined when the root templateId is unrecognized/absent.

encounters​

readonly encounters: readonly Encounter[]

Extracted Encounter Activities, visits/admissions (across all sections). Empty when none.

familyHistory​

readonly familyHistory: readonly FamilyHistory[]

Extracted Family History Organizers, one per relative (across all sections). Empty when none.

functionalStatus​

readonly functionalStatus: readonly StatusObservation[]

Extracted Functional Status findings (across all sections). Empty when none.

readonly header: CcdaHeader

The parsed US Realm Header.

immunizations​

readonly immunizations: readonly Immunization[]

Extracted Immunization Activities (across all sections). Empty when none.

medications​

readonly medications: readonly Medication[]

Extracted Medication Activities (across all sections). Empty when none.

mentalStatus​

readonly mentalStatus: readonly StatusObservation[]

Extracted Mental Status findings (across all sections). Empty when none.

nonXmlBody​

readonly nonXmlBody: ED | undefined

The quarantined nonXMLBody content for an unstructured document (base64 never decoded).

pastMedicalHistory​

readonly pastMedicalHistory: readonly Problem[]

Extracted Past Medical History problems, bare historical Problem Observations. Empty when none.

plannedItems​

readonly plannedItems: readonly PlannedItem[]

Extracted planned items from the Plan of Treatment, all future/ordered (across all sections). Empty when none.

problems​

readonly problems: readonly ProblemConcern[]

Extracted Problem Concern Acts (across all sections). Empty when none.

procedures​

readonly procedures: readonly Procedure[]

Extracted procedures, performed or planned (across all sections). Empty when none.

profile​

readonly profile: ProfileAttribution | undefined

The profile applied at parse time (name + lineage), or undefined when none was active.

results​

readonly results: readonly ResultOrganizer[]

Extracted Result Organizers, lab/diagnostic panels (across all sections). Empty when none.

sections​

readonly sections: readonly CcdaSection[]

Top-level framed sections from the structuredBody. Empty for an unstructured document.

smokingStatus​

readonly smokingStatus: readonly SmokingStatus[]

Extracted Smoking Status observations from Social History. Empty when none.

templateIds​

readonly templateIds: readonly II[]

The root templateIds, in document order (raw recognition signal).

vitals​

readonly vitals: readonly VitalSignsOrganizer[]

Extracted Vital Signs Organizers, vital-reading clusters (across all sections). Empty when none.

warnings​

readonly warnings: readonly CcdaWarning[]

Lenient-parse warnings, frozen at the model boundary.

Methods​

allSections()​

allSections(): readonly CcdaSection[]

Every section in the document, flattened depth-first (top-level sections followed by their nested subsections). Order is document order.

Returns​

readonly CcdaSection[]

Example​

for (const s of doc.allSections()) console.log(s.key ?? "(unrecognized)");

findSection()​

findSection(key): CcdaSection | undefined

Find the first recognized section with the given catalog key, searching top-level sections then their subsections (depth-first). Returns undefined when no recognized section matches.

Parameters​

key​

string

Returns​

CcdaSection | undefined

Example​

const allergies = doc.findSection("allergies");
console.log(allergies?.narrativeText);

getAllergies()​

getAllergies(): readonly AllergyConcern[]

The patient's Allergy Concern Acts, each wrapping one or more allergy/intolerance observations (including the "No Known Allergies" negated form). Empty when the document carries no Allergies entries.

Returns​

readonly AllergyConcern[]

Example​

const nka = doc.getAllergies().some((c) => c.allergies.some((a) => a.noKnownAllergy));

getEncounters()​

getEncounters(): readonly Encounter[]

The patient's Encounter Activities, each carrying the encounter type code, status, and visit period. Empty when the document carries no Encounters entries.

Returns​

readonly Encounter[]

Example​

for (const e of doc.getEncounters()) console.log(e.code?.code, e.effectiveTime);

getFamilyHistory()​

getFamilyHistory(): readonly FamilyHistory[]

The patient's Family History, one FamilyHistory per relative, each carrying the relative's structured identity and their recorded conditions. Empty when the document carries no Family History entries.

Returns​

readonly FamilyHistory[]

Example​

for (const h of doc.getFamilyHistory())
  console.log(h.relative.relationship?.code, h.observations.length);

getFunctionalStatus()​

getFunctionalStatus(): readonly StatusObservation[]

The patient's Functional Status findings, ADLs, mobility, and self-care observations (plus any scored assessment scales). Empty when the document carries no Functional Status entries.

Returns​

readonly StatusObservation[]

Example​

const scales = doc.getFunctionalStatus().filter((o) => o.assessmentScale);
console.log(scales[0]?.code?.code);

getImmunizations()​

getImmunizations(): readonly Immunization[]

The patient's Immunization Activities, each carrying the CVX vaccine, dose, route, and date (including the refused not-administered form). Empty when the document carries no Immunizations entries.

Returns​

readonly Immunization[]

Example​

const given = doc.getImmunizations().filter((i) => i.refused !== true);
console.log(given[0]?.vaccine?.code);

getMedications()​

getMedications(): readonly Medication[]

The patient's Medication Activities, each carrying the RxNorm drug, dose, route, and timing. Empty when the document carries no Medications entries.

Returns​

readonly Medication[]

Example​

for (const m of doc.getMedications()) console.log(m.drug?.code, m.dose?.value);

getMentalStatus()​

getMentalStatus(): readonly StatusObservation[]

The patient's Mental Status findings, cognition and mood observations (plus any scored assessment scales such as a PHQ-9). Empty when the document carries no Mental Status entries.

Returns​

readonly StatusObservation[]

Example​

for (const o of doc.getMentalStatus()) console.log(o.code?.code, o.value?.kind);

getMrn()​

getMrn(): string | undefined

The patient's MRN string, the first patientRole/id extension (see pickMrn). undefined when there is no patient, when that id has no extension, or when it carries a nullFlavor: the document disowned that identifier, and a bare string return has nowhere to carry the marking that qualified it. It withholds rather than falling through to the next <id>, since nothing in a C-CDA ranks patientRole/id entries and the next one is as likely to be an account or member number. The verbatim value is still reachable at getPatient()?.identifiers, where the nullFlavor travels with it.

Returns​

string | undefined

Example​

console.log(doc.getMrn() ?? "no MRN");

getPastMedicalHistory()​

getPastMedicalHistory(): readonly Problem[]

The patient's Past Medical History, historical problems carried as bare Problem Observations (distinct from the active-concern Problems section). Empty when the document carries no Past Medical History entries.

Returns​

readonly Problem[]

Example​

console.log(doc.getPastMedicalHistory()[0]?.value?.code);

getPatient()​

getPatient(): CcdaPatient | undefined

The first recordTarget patient, or undefined when the document carries none. A document with multiple record targets emits MULTIPLE_RECORD_TARGETS at parse time; this returns the first.

Returns​

CcdaPatient | undefined

Example​

const p = doc.getPatient();
console.log(p?.name?.text ?? "unknown patient");

getPlannedItems()​

getPlannedItems(): readonly PlannedItem[]

The patient's planned items from the Plan of Treatment, each future/ordered (never performed), carrying its planned code, kind, and a disposition of "planned" derived from moodCode (never read as performed). Empty when the document carries no Plan of Treatment entries.

Two bounds, because a quiet result here is not a complete one. This returns seven entry templates and the Plan of Treatment Section admits eleven: Instruction (…22.4.20), Handoff Communication Participants (…22.4.141), Nutrition Recommendation (…22.4.130) and Goal Observation (…22.4.121) are not acts planned for the patient and are not returned, and nothing is raised about them. A Goal Observation is the clearest of the four: it is moodCode="GOL", which this parser calls neither performed nor planned. And a planned entry is reached as a direct <entry> act or nested inside a Planned Intervention Act (…22.4.146), the one container R2.1 lets hold all seven inline. Nesting is not solved in general: R2.1 also puts planned acts inside a Nutrition Recommendation (…22.4.130, six of the seven) and a Planned Intervention Act inside an Intervention Act (…22.4.131), and a planned entry in either is still not reached. All of it re-serializes faithfully, so toString() is the fallback.

Returns​

readonly PlannedItem[]

Example​

const orders = doc.getPlannedItems().filter((p) => p.kind === "medicationActivity");
console.log(orders[0]?.code?.code);

getProblems()​

getProblems(): readonly ProblemConcern[]

The patient's Problem Concern Acts, each wrapping one or more coded problems with an active/resolved status. Empty when the document carries no Problems entries.

Returns​

readonly ProblemConcern[]

Example​

const active = doc.getProblems().filter((c) => c.status === "active");
console.log(active[0]?.problems[0]?.value?.code);

getProcedures()​

getProcedures(): readonly Procedure[]

The patient's procedures, each carrying its procedure code, status, and a disposition of "performed" vs "planned" derived from moodCode (never conflated). Empty when the document carries no Procedures entries.

Returns​

readonly Procedure[]

Example​

const performed = doc.getProcedures().filter((p) => p.disposition === "performed");
console.log(performed[0]?.code?.code);

getResults()​

getResults(): readonly ResultOrganizer[]

The patient's Result Organizers, lab/diagnostic panels, each carrying its member Result Observations with UCUM-checked values and reference ranges. Empty when the document carries no Results entries.

Returns​

readonly ResultOrganizer[]

Example​

for (const panel of doc.getResults())
  for (const r of panel.results) console.log(r.code?.code, r.interpretation?.code);

getSmokingStatus()​

getSmokingStatus(): readonly SmokingStatus[]

The patient's Smoking Status observations (from Social History), each carrying the SNOMED smoking-status value and an unknown flag for the explicitly-unknown form. Empty when the document records no smoking status.

Returns​

readonly SmokingStatus[]

Example​

const known = doc.getSmokingStatus().filter((s) => !s.unknown);
console.log(known[0]?.value?.code);

getVitals()​

getVitals(): readonly VitalSignsOrganizer[]

The patient's Vital Signs Organizers, reading clusters, each carrying its member Vital Sign Observations with UCUM-checked PQ values. Empty when the document carries no Vital Signs entries.

Returns​

readonly VitalSignsOrganizer[]

Example​

for (const cluster of doc.getVitals())
  for (const v of cluster.vitals) console.log(v.code?.code, v.value);

toString()​

toString(): string

Serialize this document back to spec-clean C-CDA XML, the conservative emit half of the Postel's-Law contract. Returns the faithful re-emission of the source the parser read (no silent loss of unmodeled content), with a guaranteed XML declaration. Serialization is a fixed point: parseCcda(doc.toString()).toString() === doc.toString().

Returns​

string

The spec-clean XML text.

Throws​

If this document was hand-constructed (not produced by parseCcda) and so retains no source document to emit.

Example​

const doc = parseCcda(xml);
const xmlOut = doc.toString();

withWarnings()​

withWarnings(additional): CcdaDocument

Return a new CcdaDocument with additional warnings appended, structurally sharing every parsed field (header, sections, entries, and the serialized snapshot) with this instance by reference. The original is never mutated. A downstream pass (e.g. profile-aware validation) uses this to annotate a document without re-parsing.

Parameters​

additional​

readonly CcdaWarning[]

Warnings to append after the existing ones.

Returns​

CcdaDocument

A new document; this instance is unchanged.

Example​

const annotated = doc.withWarnings([
  { code: "SECTION_PLACEMENT_SUSPECT", message: "...", position: {} },
]);
// doc.warnings is unchanged; annotated.warnings has the extra entry.