fhir-data-utils-ts 0.3.5 → 0.3.6

package/.codex/skills/govern-fhir-data-utilities/SKILL.md

@@ -38,6 +38,11 @@ description: Complete or audit migrations, claim catalogs, converters, builders,
   storage remain in a separately versioned imaging/storage package.
 - Preserve `Encounter.appointment`; an Appointment lifecycle transition must
   not sever the encounter from the scheduling event that originated it.
+- Build laboratory panels with `buildDiagnosticReportFlatGraph(...)`.
+  `DiagnosticReport.code` is mandatory and names the report/panel; result
+  measurements are independent `Observation` entries and formatted PDF/image
+  evidence is an independent `DocumentReference`. Preliminary state does not
+  itself authorize ledger or research projection.
 
 ## Change with executable contracts
 

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.6 - 2026-09-26
+
+- Add a product-neutral claims-first DiagnosticReport graph builder for coded
+  laboratory panels, independent Observation results and PDF/image
+  DocumentReference evidence.
+- Correct the document builder to emit the canonical DocumentReference claim
+  catalog and complete list helpers for report results, performers, specimens
+  and graph references.
+
 ## 0.3.5 - 2026-09-26
 
 - Preserve the originating `Encounter.appointment` reference and expose the

package/README.md

@@ -29,6 +29,13 @@ through `<ResourceType>.contained-reference-list`; children do not carry
 as `<ResourceType>.language`, `.narrative-status` and `.xhtml`. Native FHIR is
 materialized only by an explicit R4/R5/R6 import or export adapter.
 
+Laboratory authoring uses `buildDiagnosticReportFlatGraph(...)`.
+`DiagnosticReport.code` is the coded report or panel type, atomic results are
+independent LOINC-coded `Observation` entries, and PDF/JPEG/PNG evidence is an
+independent `DocumentReference`. Preliminary reports can be reviewed and
+securely exchanged; ledger and research eligibility remain downstream policy
+and normally require the confirmed final lifecycle state.
+
 ## Public contract
 
 The root export and stable subpaths provide:

package/dist/builders/diagnostic-report-graph.d.ts

@@ -0,0 +1,31 @@
+import { type DiagnosticReportStatus } from '../constants/clinical-statuses.js';
+import { type FlatClaimResourceEntry } from '../flat-claim-resource-graph.js';
+export type DiagnosticReportCoding = Readonly<{
+    system: string;
+    code: string;
+    display?: string;
+    text?: string;
+}>;
+export type DiagnosticReportFlatInput = Readonly<{
+    entryId: string;
+    identifier: string;
+    status: DiagnosticReportStatus;
+    subjectReference: string;
+    issuedAt: string;
+    reportCode: DiagnosticReportCoding;
+    encounterReference?: string;
+    performerReferences?: readonly string[];
+    results?: readonly FlatClaimResourceEntry[];
+    attachments?: readonly FlatClaimResourceEntry[];
+}>;
+/**
+ * Builds a claims-first DiagnosticReport graph for human, animal, or One Health
+ * laboratory reports. `DiagnosticReport.code` identifies the report/panel;
+ * atomic measurements remain independent `Observation` entries and PDF/JPEG/
+ * PNG evidence remains independent `DocumentReference` entries.
+ *
+ * `preliminary` reports can be exchanged and reviewed, but downstream ledger
+ * and secondary-use policy decides whether only `final` is eligible for those
+ * projections. This builder does not confer authority or consent.
+ */
+export declare function buildDiagnosticReportFlatGraph(input: DiagnosticReportFlatInput): readonly FlatClaimResourceEntry[];

package/dist/builders/diagnostic-report-graph.js

@@ -0,0 +1,86 @@
+// Copyright 2026 ConnectHealth.info (Connecting Solution & Applications Ltd.) under the Apache License, Version 2.0.
+import { DiagnosticReportClaim } from '../claims/diagnostic-report-claims.js';
+import { DiagnosticReportStatuses } from '../constants/clinical-statuses.js';
+import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { buildFlatClaimResourceEntry, linkFlatClaimResourceEntries, } from '../flat-claim-resource-graph.js';
+const DIAGNOSTIC_REPORT_STATUSES = new Set(Object.values(DiagnosticReportStatuses));
+/**
+ * Builds a claims-first DiagnosticReport graph for human, animal, or One Health
+ * laboratory reports. `DiagnosticReport.code` identifies the report/panel;
+ * atomic measurements remain independent `Observation` entries and PDF/JPEG/
+ * PNG evidence remains independent `DocumentReference` entries.
+ *
+ * `preliminary` reports can be exchanged and reviewed, but downstream ledger
+ * and secondary-use policy decides whether only `final` is eligible for those
+ * projections. This builder does not confer authority or consent.
+ */
+export function buildDiagnosticReportFlatGraph(input) {
+    const status = required(input.status, 'diagnostic_report_status_required');
+    if (!DIAGNOSTIC_REPORT_STATUSES.has(status))
+        throw new TypeError('diagnostic_report_status_invalid');
+    const claims = {
+        [DiagnosticReportClaim.Identifier]: required(input.identifier, 'diagnostic_report_identifier_required'),
+        [DiagnosticReportClaim.Status]: status,
+        [DiagnosticReportClaim.Subject]: required(input.subjectReference, 'diagnostic_report_subject_required'),
+        [DiagnosticReportClaim.Date]: isoDateTime(input.issuedAt, 'diagnostic_report_date_invalid'),
+        [DiagnosticReportClaim.Code]: codingToken(input.reportCode),
+    };
+    if (input.reportCode.display?.trim())
+        claims[DiagnosticReportClaim.CodeDisplay] = input.reportCode.display.trim();
+    if (input.reportCode.text?.trim())
+        claims[DiagnosticReportClaim.CodeText] = input.reportCode.text.trim();
+    if (input.encounterReference?.trim()) {
+        claims[DiagnosticReportClaim.Encounter] = required(input.encounterReference, 'diagnostic_report_encounter_invalid');
+    }
+    if (input.performerReferences?.length) {
+        claims[DiagnosticReportClaim.Performer] = referenceList(input.performerReferences, 'diagnostic_report_performer_invalid');
+    }
+    const results = [...(input.results ?? [])];
+    if (results.some(entry => entry.resourceType !== ResourceTypesFhirR4.Observation)) {
+        throw new TypeError('diagnostic_report_result_invalid');
+    }
+    const attachments = [...(input.attachments ?? [])];
+    if (attachments.some(entry => entry.resourceType !== ResourceTypesFhirR4.DocumentReference)) {
+        throw new TypeError('diagnostic_report_attachment_invalid');
+    }
+    if (results.length)
+        claims[DiagnosticReportClaim.Result] = results.map(entry => entry.reference).join(',');
+    const report = buildFlatClaimResourceEntry({
+        entryId: input.entryId,
+        resourceType: ResourceTypesFhirR4.DiagnosticReport,
+        claims,
+    });
+    const children = [...results, ...attachments];
+    const graph = [report, ...children];
+    return children.length
+        ? linkFlatClaimResourceEntries(graph, {
+            parentEntryId: report.entryId,
+            childEntryIds: children.map(entry => entry.entryId),
+        })
+        : graph;
+}
+function codingToken(value) {
+    const system = required(value.system, 'diagnostic_report_code_system_required');
+    const code = required(value.code, 'diagnostic_report_code_required');
+    if (system.includes('|') || code.includes('|') || system.includes(',') || code.includes(',')) {
+        throw new TypeError('diagnostic_report_code_invalid');
+    }
+    return `${system}|${code}`;
+}
+function referenceList(values, error) {
+    const normalized = [...new Set(values.map(value => required(value, error)))];
+    if (normalized.some(value => value.includes(',')))
+        throw new TypeError(error);
+    return normalized.join(',');
+}
+function isoDateTime(value, error) {
+    const normalized = required(value, error);
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(normalized) || Number.isNaN(Date.parse(normalized)))
+        throw new TypeError(error);
+    return normalized;
+}
+function required(value, error) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(error);
+    return value.trim();
+}

package/dist/builders/index.d.ts

@@ -1,2 +1,3 @@
+export * from './diagnostic-report-graph.js';
 export * from './immunization-graph.js';
 export * from './immunization-reminders.js';

package/dist/builders/index.js

@@ -1,2 +1,3 @@
+export * from './diagnostic-report-graph.js';
 export * from './immunization-graph.js';
 export * from './immunization-reminders.js';

package/dist/claim-helpers/claims-helpers-diagnostic-report.d.ts

@@ -8,8 +8,20 @@ export declare function getDiagnosticReportIdentifier(claims: DiagnosticReportIn
 export declare function setDiagnosticReportIdentifier(claims: DiagnosticReportInteroperableClaims, value: string): DiagnosticReportInteroperableClaims;
 export declare function getDiagnosticReportResultList(claims: DiagnosticReportInteroperableClaims): string[];
 export declare function setDiagnosticReportResultList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function addDiagnosticReportResultList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function removeDiagnosticReportResultList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function getDiagnosticReportPerformerList(claims: DiagnosticReportInteroperableClaims): string[];
+export declare function setDiagnosticReportPerformerList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function addDiagnosticReportPerformerList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function removeDiagnosticReportPerformerList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function getDiagnosticReportSpecimenList(claims: DiagnosticReportInteroperableClaims): string[];
+export declare function setDiagnosticReportSpecimenList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function addDiagnosticReportSpecimenList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function removeDiagnosticReportSpecimenList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
 export declare function getDiagnosticReportContainedResourceReferenceList(claims: DiagnosticReportInteroperableClaims): string[];
 export declare function setDiagnosticReportContainedResourceReferenceList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function addDiagnosticReportContainedResourceReferenceList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function removeDiagnosticReportContainedResourceReferenceList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
 /** @deprecated Use `getDiagnosticReportContainedResourceReferenceList`. */
 export declare function getDiagnosticReportContainedDocumentIdentifierList(claims: DiagnosticReportInteroperableClaims): string[];
 /** @deprecated Use `setDiagnosticReportContainedResourceReferenceList`. */

package/dist/claim-helpers/claims-helpers-diagnostic-report.js

@@ -24,6 +24,36 @@ export function getDiagnosticReportResultList(claims) {
 export function setDiagnosticReportResultList(claims, values) {
     return setDiagnosticReportClaimList(claims, DiagnosticReportClaim.Result, values);
 }
+export function addDiagnosticReportResultList(claims, values) {
+    return addDiagnosticReportClaimList(claims, DiagnosticReportClaim.Result, values);
+}
+export function removeDiagnosticReportResultList(claims, values) {
+    return removeDiagnosticReportClaimList(claims, DiagnosticReportClaim.Result, values);
+}
+export function getDiagnosticReportPerformerList(claims) {
+    return getDiagnosticReportClaimList(claims, DiagnosticReportClaim.Performer);
+}
+export function setDiagnosticReportPerformerList(claims, values) {
+    return setDiagnosticReportClaimList(claims, DiagnosticReportClaim.Performer, values);
+}
+export function addDiagnosticReportPerformerList(claims, values) {
+    return addDiagnosticReportClaimList(claims, DiagnosticReportClaim.Performer, values);
+}
+export function removeDiagnosticReportPerformerList(claims, values) {
+    return removeDiagnosticReportClaimList(claims, DiagnosticReportClaim.Performer, values);
+}
+export function getDiagnosticReportSpecimenList(claims) {
+    return getDiagnosticReportClaimList(claims, DiagnosticReportClaim.Specimen);
+}
+export function setDiagnosticReportSpecimenList(claims, values) {
+    return setDiagnosticReportClaimList(claims, DiagnosticReportClaim.Specimen, values);
+}
+export function addDiagnosticReportSpecimenList(claims, values) {
+    return addDiagnosticReportClaimList(claims, DiagnosticReportClaim.Specimen, values);
+}
+export function removeDiagnosticReportSpecimenList(claims, values) {
+    return removeDiagnosticReportClaimList(claims, DiagnosticReportClaim.Specimen, values);
+}
 export function getDiagnosticReportContainedResourceReferenceList(claims) {
     const canonical = getDiagnosticReportClaimList(claims, DiagnosticReportClaim.ContainedReferenceList);
     const legacy = getDiagnosticReportClaimList(claims, DiagnosticReportClaim.ContainedDocuments);
@@ -37,6 +67,16 @@ export function setDiagnosticReportContainedResourceReferenceList(claims, values
     delete cleaned[DiagnosticReportClaim.ContainedDocuments];
     return cleaned;
 }
+export function addDiagnosticReportContainedResourceReferenceList(claims, values) {
+    return setDiagnosticReportContainedResourceReferenceList(claims, [
+        ...getDiagnosticReportContainedResourceReferenceList(claims),
+        ...(Array.isArray(values) ? values : [values]),
+    ]);
+}
+export function removeDiagnosticReportContainedResourceReferenceList(claims, values) {
+    const removals = new Set(Array.isArray(values) ? values : [values]);
+    return setDiagnosticReportContainedResourceReferenceList(claims, getDiagnosticReportContainedResourceReferenceList(claims).filter(value => !removals.has(value)));
+}
 /** @deprecated Use `getDiagnosticReportContainedResourceReferenceList`. */
 export function getDiagnosticReportContainedDocumentIdentifierList(claims) {
     return getDiagnosticReportContainedResourceReferenceList(claims);

package/dist/claims/diagnostic-report-claims.d.ts

@@ -33,31 +33,6 @@ export declare const DiagnosticReportClaim: {
      */
     readonly ContainedDocuments: "DiagnosticReport.contained-documents";
 };
-/**
- * TODO(ips-next):
- * Add resource-level claim helpers in `src/utils/claims-helpers-diagnostic-report.ts`
- * following the same contract already used by Consent/Medication/Condition/Allergy:
- * - `getDiagnosticReportClaimList(...)`
- * - `setDiagnosticReportClaimList(...)`
- * - `addDiagnosticReportClaimList(...)`
- * - `removeDiagnosticReportClaimList(...)`
- * - focused helpers for:
- *   - `get/set/add/removeDiagnosticReportResultList`
- *   - `get/set/add/removeDiagnosticReportPerformerList`
- *   - `get/set/add/removeDiagnosticReportSpecimenList`
- *   - `get/set/add/removeDiagnosticReportContainedResourceReferences`
- *   - `get/setDiagnosticReportPresentedFormContentType`
- *   - `get/setDiagnosticReportPresentedFormData`
- *   - `get/setDiagnosticReportPresentedFormUrl`
- *
- * Keep naming aligned with canonical FHIR search parameter names
- * (lowercase with `-`) and reuse the existing `SearchParamNames` + contextualized
- * claim-key mapping pattern.
- *
- * This file is intentionally type-first only for now so GW Core and
- * `common-utils` can already exercise the rest of the bundle workflow without
- * committing to the DiagnosticReport editing surface yet.
- */
 export type DiagnosticReportClaimKey = typeof DiagnosticReportClaim[keyof typeof DiagnosticReportClaim];
 export declare const DiagnosticReportClaimSpecs: ClaimSpec[];
 export declare const DiagnosticReportSearchParamNames: {
@@ -95,15 +70,7 @@ export declare enum DiagnosticReportClaimsFhirApi {
 }
 export declare const DiagnosticReportSearchParamToClaimKey: Record<DiagnosticReportSearchParamName, DiagnosticReportClaimsFhirApi>;
 /**
- * TODO(ips-next):
- * Add `DiagnosticReportClaimsFhirApiExtended` only if/when the bundle editor
- * needs operational flat fields beyond the official search parameter surface.
- *
- * Do not invent camelCase names. Prefer official FHIR search parameter names
- * or explicit attachment aliases such as `presented-form-*` and
- * `contained-reference-list`.
- *
- * Keep `DiagnosticReport` paused at the typing/mapping layer until:
- * 1. `claims-helpers-diagnostic-report.ts` exists
- * 2. GW Core readers/tests consume the same shared claim keys
+ * Operational attachment and graph claims remain separate from the official
+ * SearchParameter catalog above. They support claims-first authoring without
+ * pretending that those aliases are searchable FHIR parameters.
  */

package/dist/claims/diagnostic-report-claims.js

@@ -54,7 +54,7 @@ export const DiagnosticReportClaimSpecs = [
     { key: DiagnosticReportClaim.PresentedFormContentType, meaning: 'FHIR presentedForm attachment content type.', example: 'application/pdf' },
     { key: DiagnosticReportClaim.PresentedFormData, meaning: 'FHIR presentedForm inline base64 payload.', example: 'JVBERi0xLjc...' },
     { key: DiagnosticReportClaim.PresentedFormUrl, meaning: 'FHIR presentedForm external URL.', example: 'https://example.org/report.pdf' },
-    { key: DiagnosticReportClaim.ContainedDocuments, meaning: 'CSV of linked DocumentReference identifiers stored in the same bundle.', example: 'docref-example-001,docref-example-002' },
+    { key: DiagnosticReportClaim.ContainedReferenceList, meaning: 'Canonical CSV of independent result and evidence resource references linked by this report.', example: 'Observation/result-1,DocumentReference/report-1' },
 ];
 export const DiagnosticReportSearchParamNames = {
     BasedOn: 'based-on',
@@ -106,15 +106,7 @@ export const DiagnosticReportSearchParamToClaimKey = {
     [DiagnosticReportSearchParamNames.Subject]: DiagnosticReportClaimsFhirApi.Subject,
 };
 /**
- * TODO(ips-next):
- * Add `DiagnosticReportClaimsFhirApiExtended` only if/when the bundle editor
- * needs operational flat fields beyond the official search parameter surface.
- *
- * Do not invent camelCase names. Prefer official FHIR search parameter names
- * or explicit attachment aliases such as `presented-form-*` and
- * `contained-reference-list`.
- *
- * Keep `DiagnosticReport` paused at the typing/mapping layer until:
- * 1. `claims-helpers-diagnostic-report.ts` exists
- * 2. GW Core readers/tests consume the same shared claim keys
+ * Operational attachment and graph claims remain separate from the official
+ * SearchParameter catalog above. They support claims-first authoring without
+ * pretending that those aliases are searchable FHIR parameters.
  */

package/dist/flat-claim-resource-graph.js

@@ -70,16 +70,16 @@ export function normalizeLegacyContainedClaims(entry) {
  */
 export function buildDocumentReferenceFlatEntry(input) {
     const claims = {
-        'DocumentReference.identifier': requiredToken(input.identifier, 'document_reference_identifier_required'),
-        'DocumentReference.content-type': input.contentType,
-        'DocumentReference.contenthash': requiredToken(input.contentHash, 'document_reference_contenthash_required'),
+        [DocumentReferenceClaim.Identifier]: requiredToken(input.identifier, 'document_reference_identifier_required'),
+        [DocumentReferenceClaim.ContentType]: input.contentType,
+        [DocumentReferenceClaim.ContentHash]: requiredToken(input.contentHash, 'document_reference_contenthash_required'),
     };
     if (input.title?.trim())
-        claims['DocumentReference.title'] = input.title.trim();
+        claims[DocumentReferenceClaim.Description] = input.title.trim();
     if (input.url?.trim())
-        claims['DocumentReference.url'] = input.url.trim();
+        claims[DocumentReferenceClaim.Location] = input.url.trim();
     if (input.dataBase64?.trim())
-        claims['DocumentReference.data'] = input.dataBase64.trim();
+        claims[DocumentReferenceClaim.ContentData] = input.dataBase64.trim();
     return buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'DocumentReference', claims });
 }
 function splitCsv(value) {
@@ -106,3 +106,4 @@ function requiredResourceType(value) {
         throw new TypeError('flat_claim_resource_type_invalid');
     return normalized;
 }
+import { DocumentReferenceClaim } from './claims/document-reference-claims.js';

package/docs/UHC_FHIR_UTILS_MIGRATION.md

@@ -83,6 +83,13 @@ one native `Observation.component[]`; it does not export three independent
 native Observations. Component entries do not use `is-contained`,
 `contained-parent-reference` or `contained-reference-list`.
 
+Diagnostic laboratory authoring is owned here by
+`buildDiagnosticReportFlatGraph(...)`: `DiagnosticReport.code` identifies the
+report/panel, independent Observation entries carry atomic results, and
+independent DocumentReference entries carry PDF/image evidence. Sector roles,
+confirmation, ledger eligibility, consent and research policy remain outside
+this package.
+
 Aligned JSON arrays and the older comma-separated `Observation.component-*`
 claims are accepted only by the migration reader. No current writer emits
 either representation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",