fhir-data-utils-ts 0.6.16 → 0.6.18

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.6.18 - 2026-10-08
+
+- Add the canonical Immunization series-dose claim, its FHIR R4 round trip,
+  reusable dose-order validation and a standalone claims-first
+  ImmunizationRecommendation builder for progressive clinical authoring.
+
+## 0.6.17 - 2026-10-08
+
+- Add the preferred HL7 Observation category catalogue for shared clinical
+  editors. English and Spanish labels retain a compact `HL7|code` suffix while
+  the stored option remains the complete canonical `system|code` token.
+
 ## 0.6.16 - 2026-10-07
 
 - Export the required FHIR R4 code bindings used by reusable IPS authoring

package/dist/builders/immunization-graph.d.ts

@@ -32,5 +32,17 @@ export type ImmunizationFlatInput = Readonly<{
     }>;
     attachments?: readonly FlatClaimResourceEntry[];
 }>;
+export type ImmunizationRecommendationFlatInput = Readonly<{
+    entryId: string;
+    immunizationEntryId: string;
+    subjectReference: string;
+    recommendationDate: string;
+    nextDoseDate: string;
+    vaccineCode: ImmunizationCoding;
+}>;
+/** Validates the optional positive dose number and its optional series total. */
+export declare function validateImmunizationDoseSeries(doseSequence?: string, seriesDoses?: string): void;
+/** Builds the recommendation related to one staged Immunization without reminder transport. */
+export declare function buildImmunizationRecommendationFlatEntry(input: ImmunizationRecommendationFlatInput): FlatClaimResourceEntry;
 /** Builds the shared claims-first human/animal immunization resource graph. */
 export declare function buildImmunizationFlatGraph(input: ImmunizationFlatInput): readonly FlatClaimResourceEntry[];

package/dist/builders/immunization-graph.js

@@ -5,6 +5,30 @@ import { ImmunizationClaim } from '../claims/immunization-claims.js';
 import { ImmunizationRecommendationClaim, ImmunizationRecommendationCodes, } from '../claims/immunization-recommendation-claims.js';
 import { MedicationClaim } from '../claims/medication-claims.js';
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+/** Validates the optional positive dose number and its optional series total. */
+export function validateImmunizationDoseSeries(doseSequence, seriesDoses) {
+    const dose = positiveInteger(doseSequence, 'immunization_dose_sequence_invalid');
+    const total = positiveInteger(seriesDoses, 'immunization_series_doses_invalid');
+    if (dose !== undefined && total !== undefined && total < dose) {
+        throw new TypeError('immunization_series_doses_invalid');
+    }
+}
+/** Builds the recommendation related to one staged Immunization without reminder transport. */
+export function buildImmunizationRecommendationFlatEntry(input) {
+    return buildFlatClaimResourceEntry({
+        entryId: required(input.entryId, 'immunization_recommendation_id_required'),
+        resourceType: ResourceTypesFhirR4.ImmunizationRecommendation,
+        claims: {
+            [ImmunizationRecommendationClaim.Patient]: required(input.subjectReference, 'immunization_subject_required'),
+            [ImmunizationRecommendationClaim.Date]: isoDate(input.recommendationDate, 'immunization_recommendation_date_invalid'),
+            [ImmunizationRecommendationClaim.VaccineCode]: codingToken(input.vaccineCode),
+            [ImmunizationRecommendationClaim.ForecastStatus]: ImmunizationRecommendationCodes.ForecastDue,
+            [ImmunizationRecommendationClaim.DateCriterionCode]: ImmunizationRecommendationCodes.RecommendedDate,
+            [ImmunizationRecommendationClaim.DateCriterionValue]: isoDate(input.nextDoseDate, 'immunization_next_dose_date_invalid'),
+            [ImmunizationRecommendationClaim.SupportingImmunization]: `${ResourceTypesFhirR4.Immunization}/${required(input.immunizationEntryId, 'immunization_id_required')}`,
+        },
+    });
+}
 /** Builds the shared claims-first human/animal immunization resource graph. */
 export function buildImmunizationFlatGraph(input) {
     const vaccineCode = codingToken(input.vaccineCode);
@@ -33,18 +57,13 @@ export function buildImmunizationFlatGraph(input) {
         children.push(buildMedicationEntry(input.medication));
     if (input.nextDoseDate) {
         const recommendationId = `${input.entryId}-recommendation`;
-        const recommendation = buildFlatClaimResourceEntry({
+        const recommendation = buildImmunizationRecommendationFlatEntry({
             entryId: recommendationId,
-            resourceType: ResourceTypesFhirR4.ImmunizationRecommendation,
-            claims: {
-                [ImmunizationRecommendationClaim.Patient]: input.subjectReference,
-                [ImmunizationRecommendationClaim.Date]: isoDate(required(input.recommendationDate, 'immunization_recommendation_date_required'), 'immunization_recommendation_date_invalid'),
-                [ImmunizationRecommendationClaim.VaccineCode]: vaccineCode,
-                [ImmunizationRecommendationClaim.ForecastStatus]: ImmunizationRecommendationCodes.ForecastDue,
-                [ImmunizationRecommendationClaim.DateCriterionCode]: ImmunizationRecommendationCodes.RecommendedDate,
-                [ImmunizationRecommendationClaim.DateCriterionValue]: isoDate(input.nextDoseDate, 'immunization_next_dose_date_invalid'),
-                [ImmunizationRecommendationClaim.SupportingImmunization]: `${ResourceTypesFhirR4.Immunization}/${input.entryId}`,
-            },
+            immunizationEntryId: input.entryId,
+            subjectReference: input.subjectReference,
+            recommendationDate: required(input.recommendationDate, 'immunization_recommendation_date_required'),
+            nextDoseDate: input.nextDoseDate,
+            vaccineCode: input.vaccineCode,
         });
         const tasks = buildImmunizationReminderTasks({
             entryIdPrefix: recommendationId,
@@ -113,3 +132,10 @@ function required(value, error) {
         throw new TypeError(error);
     return value.trim();
 }
+function positiveInteger(value, error) {
+    if (value === undefined || value === '')
+        return undefined;
+    if (!/^\d+$/.test(value) || Number(value) <= 0)
+        throw new TypeError(error);
+    return Number(value);
+}

package/dist/claims/immunization-claims.d.ts

@@ -20,6 +20,7 @@ export declare const ImmunizationClaim: {
     readonly VaccineCodeText: "Immunization.vaccine-code-text";
     readonly VaccineCodeDisplay: "Immunization.vaccine-code-display";
     readonly DoseSequence: "Immunization.dose-sequence";
+    readonly SeriesDoses: "Immunization.series-doses";
     readonly Subject: "Immunization.subject";
     readonly Note: "Immunization.note";
     readonly Route: "Immunization.route";

package/dist/claims/immunization-claims.js

@@ -21,6 +21,7 @@ export const ImmunizationClaim = {
     VaccineCodeText: 'Immunization.vaccine-code-text',
     VaccineCodeDisplay: 'Immunization.vaccine-code-display',
     DoseSequence: 'Immunization.dose-sequence',
+    SeriesDoses: 'Immunization.series-doses',
     Subject: 'Immunization.subject',
     Note: 'Immunization.note',
     Route: 'Immunization.route',
@@ -49,6 +50,7 @@ export const ImmunizationClaimSpecs = [
     { key: ImmunizationClaim.VaccineCodeText, meaning: 'Local-language vaccine label used by forms/UI.', example: 'Vacuna COVID-19' },
     { key: ImmunizationClaim.VaccineCodeDisplay, meaning: 'Canonical/international vaccine display label.', example: 'COVID-19 vaccine' },
     { key: ImmunizationClaim.DoseSequence, meaning: 'Dose sequence string.', example: '2' },
+    { key: ImmunizationClaim.SeriesDoses, meaning: 'Total number of doses in the vaccination series.', example: '3' },
     { key: ImmunizationClaim.Subject, meaning: 'Canonical subject reference.', example: 'did:web:patient.example.org' },
     { key: ImmunizationClaim.Note, meaning: 'Clinical note text.', example: 'No adverse reaction recorded.' },
 ];

package/dist/clinical-artifact-coded-options.d.ts

@@ -7,7 +7,7 @@ export type FhirClinicalCodedOption = Readonly<{
 }>;
 export type FhirClinicalCodedOptionSet = Readonly<{
     fhirVersion: 'R4';
-    binding: 'required';
+    binding: 'required' | 'preferred';
     system: string;
     options: readonly FhirClinicalCodedOption[];
 }>;

package/dist/clinical-artifact-coded-options.js

@@ -4,9 +4,10 @@ import { ConditionClaim } from './claims/condition-claims.js';
 import { ImmunizationClaim } from './claims/immunization-claims.js';
 import { MedicationStatementClaim } from './claims/medication-statement-claims.js';
 import { ProcedureClaim } from './claims/procedure-claims.js';
-import { ObservationClaim } from './observation-claims.js';
+import { ObservationCategoryCodes, ObservationClaim } from './observation-claims.js';
 const option = (code, en, es) => Object.freeze({ code, labels: Object.freeze({ en, es }) });
 const requiredSet = (system, options) => Object.freeze({ fhirVersion: 'R4', binding: 'required', system, options: Object.freeze(options) });
+const preferredSet = (system, options) => Object.freeze({ fhirVersion: 'R4', binding: 'preferred', system, options: Object.freeze(options) });
 const enteredInError = option('entered-in-error', 'Entered in error', 'Introducido por error');
 const unknown = option('unknown', 'Unknown', 'Desconocido');
 /**
@@ -27,6 +28,17 @@ export const FHIR_IPS_CLINICAL_CODED_OPTION_SETS = Object.freeze({
     [ConditionClaim.VerificationStatus]: requiredSet('http://terminology.hl7.org/CodeSystem/condition-ver-status', [option('unconfirmed', 'Unconfirmed', 'No confirmado'), option('provisional', 'Provisional', 'Provisional'), option('differential', 'Differential', 'Diferencial'), option('confirmed', 'Confirmed', 'Confirmado'), option('refuted', 'Refuted', 'Refutado'), enteredInError]),
     [ProcedureClaim.Status]: requiredSet('http://hl7.org/fhir/event-status', [option('preparation', 'Preparation', 'Preparación'), option('in-progress', 'In progress', 'En curso'), option('not-done', 'Not done', 'No realizado'), option('on-hold', 'On hold', 'En espera'), option('stopped', 'Stopped', 'Detenido'), option('completed', 'Completed', 'Completado'), enteredInError, unknown]),
     [ObservationClaim.Status]: requiredSet('http://hl7.org/fhir/observation-status', [option('registered', 'Registered', 'Registrado'), option('preliminary', 'Preliminary', 'Preliminar'), option('final', 'Final', 'Final'), option('amended', 'Amended', 'Modificado'), option('corrected', 'Corrected', 'Corregido'), option('cancelled', 'Cancelled', 'Cancelado'), enteredInError, unknown]),
+    [ObservationClaim.Category]: preferredSet(ObservationCategoryCodes.VitalSigns.system, [
+        option(ObservationCategoryCodes.SocialHistory.claim, 'Social history (HL7|social-history)', 'Historia social (HL7|social-history)'),
+        option(ObservationCategoryCodes.VitalSigns.claim, 'Vital signs (HL7|vital-signs)', 'Signos vitales (HL7|vital-signs)'),
+        option(ObservationCategoryCodes.Imaging.claim, 'Imaging (HL7|imaging)', 'Diagnóstico por imagen (HL7|imaging)'),
+        option(ObservationCategoryCodes.Laboratory.claim, 'Laboratory (HL7|laboratory)', 'Laboratorio (HL7|laboratory)'),
+        option(ObservationCategoryCodes.Procedure.claim, 'Procedure (HL7|procedure)', 'Procedimiento (HL7|procedure)'),
+        option(ObservationCategoryCodes.Survey.claim, 'Survey (HL7|survey)', 'Cuestionario (HL7|survey)'),
+        option(ObservationCategoryCodes.Exam.claim, 'Exam (HL7|exam)', 'Exploración (HL7|exam)'),
+        option(ObservationCategoryCodes.Therapy.claim, 'Therapy (HL7|therapy)', 'Terapia (HL7|therapy)'),
+        option(ObservationCategoryCodes.Activity.claim, 'Activity (HL7|activity)', 'Actividad (HL7|activity)'),
+    ]),
 });
 /** Returns localized labels while preserving the exact canonical code value. */
 export function clinicalArtifactCodedOptionsForClaim(claim, locale) {

package/dist/converters/convert-immunization.js

@@ -33,12 +33,15 @@ export function immunizationFlatToFhirR4(claims) {
         reasonReference: claims[ImmunizationClaim.ReasonReference] ? [{ reference: claims[ImmunizationClaim.ReasonReference] }] : undefined,
         statusReason: claims[ImmunizationClaim.StatusReason] ? { coding: codingFromValue(claims[ImmunizationClaim.StatusReason]) } : undefined,
         note: claims[ImmunizationClaim.Note] ? [{ text: claims[ImmunizationClaim.Note] }] : undefined,
-        protocolApplied: (claims[ImmunizationClaim.Series] || claims[ImmunizationClaim.TargetDisease] || claims[ImmunizationClaim.DoseSequence]) ? [{
+        protocolApplied: (claims[ImmunizationClaim.Series] || claims[ImmunizationClaim.TargetDisease] || claims[ImmunizationClaim.DoseSequence] || claims[ImmunizationClaim.SeriesDoses]) ? [{
                 series: claims[ImmunizationClaim.Series],
                 targetDisease: claims[ImmunizationClaim.TargetDisease] ? [{ coding: codingFromValue(claims[ImmunizationClaim.TargetDisease]) }] : undefined,
                 ...(claims[ImmunizationClaim.DoseSequence] && /^\d+$/.test(claims[ImmunizationClaim.DoseSequence])
                     ? { doseNumberPositiveInt: Number(claims[ImmunizationClaim.DoseSequence]) }
                     : { doseNumberString: claims[ImmunizationClaim.DoseSequence] }),
+                ...(claims[ImmunizationClaim.SeriesDoses] && /^\d+$/.test(claims[ImmunizationClaim.SeriesDoses])
+                    ? { seriesDosesPositiveInt: Number(claims[ImmunizationClaim.SeriesDoses]) }
+                    : {}),
             }] : undefined,
         reaction: claims[ImmunizationClaim.ReactionDate] ? [{ date: claims[ImmunizationClaim.ReactionDate] }] : undefined,
     };
@@ -70,6 +73,9 @@ export function immunizationFhirR4ToFlat(resource) {
         [ImmunizationClaim.DoseSequence]: protocolApplied?.doseNumberPositiveInt === undefined
             ? protocolApplied?.doseNumberString
             : String(protocolApplied.doseNumberPositiveInt),
+        [ImmunizationClaim.SeriesDoses]: protocolApplied?.seriesDosesPositiveInt === undefined
+            ? protocolApplied?.seriesDosesString
+            : String(protocolApplied.seriesDosesPositiveInt),
         [ImmunizationClaim.Subject]: referenceToValue(resource.patient),
         [ImmunizationClaim.Note]: resource.note?.[0]?.text,
         [ImmunizationClaim.Route]: codingToValue(resource.route?.coding?.[0]),

package/package.json

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