fhir-data-utils-ts 0.2.4 → 0.3.1

package/dist/converters/convert-observation.js

@@ -0,0 +1,246 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+// File: src/utils/convert-observation.ts
+import { ObservationClaim } from '../observation-claims.js';
+import { buildFlatClaimResourceEntry, } from '../flat-claim-resource-graph.js';
+import { codingFromValue, codingListToCsv, codingToValue, referenceListToCsv, referenceToValue } from './convert-shared.js';
+/**
+ * Converts flat editable Observation claims into a FHIR R4 Observation.
+ *
+ * Naming convention:
+ * - place the concrete FHIR version suffix at the end of the helper name
+ * - prefer `observationFromFlatToFhirR4` / `observationToFlatFhirR4`
+ * - avoid `observationFhirR4ToFlat`
+ */
+export function observationFromFlatToFhirR4(claims) {
+    const subject = claims[ObservationClaim.Subject] ?? claims[ObservationClaim.Patient];
+    const codeToken = claims[ObservationClaim.Code]
+        ?? codingToValue({
+            system: claims[ObservationClaim.CodeSystem],
+            code: claims[ObservationClaim.CodeValue],
+        });
+    const valueConceptToken = claims[ObservationClaim.ValueConcept]
+        ?? codingToValue({
+            system: claims[ObservationClaim.ValueConceptSystem],
+            code: claims[ObservationClaim.ValueConceptValue],
+        });
+    const valueQuantityCoding = codingFromValue(claims[ObservationClaim.ValueQuantityUnit])?.[0];
+    const codeCoding = codingFromValue(codeToken)?.map((coding) => ({
+        ...coding,
+        ...(claims[ObservationClaim.CodeDisplay] ? { display: claims[ObservationClaim.CodeDisplay] } : {}),
+    }));
+    const valueConceptCoding = codingFromValue(valueConceptToken)?.map((coding) => ({
+        ...coding,
+        ...(claims[ObservationClaim.ValueConceptDisplay]
+            ? { display: claims[ObservationClaim.ValueConceptDisplay] }
+            : {}),
+    }));
+    const componentCodes = splitClaimList(claims[ObservationClaim.ComponentCode]);
+    const componentDisplays = splitClaimList(claims[ObservationClaim.ComponentCodeDisplay]);
+    const componentNumbers = splitClaimList(claims[ObservationClaim.ComponentValueQuantityNumber]);
+    const componentUnits = splitClaimList(claims[ObservationClaim.ComponentValueQuantityUnit]);
+    const referenceUnit = claims[ObservationClaim.ReferenceRangeUnit];
+    return {
+        resourceType: 'Observation',
+        identifier: claims[ObservationClaim.Identifier] ? [{ value: claims[ObservationClaim.Identifier] }] : undefined,
+        status: claims[ObservationClaim.Status],
+        category: claims[ObservationClaim.Category] ? claims[ObservationClaim.Category].split(',').map((value) => ({ coding: codingFromValue(value.trim()) })) : undefined,
+        code: codeToken
+            ? {
+                coding: codeCoding,
+                ...(claims[ObservationClaim.CodeText] ? { text: claims[ObservationClaim.CodeText] } : {}),
+            }
+            : undefined,
+        subject: subject ? { reference: subject } : undefined,
+        effectiveDateTime: claims[ObservationClaim.EffectiveDateTime]
+            ?? claims[ObservationClaim.EffectiveDateTimeLegacy]
+            ?? claims[ObservationClaim.Date],
+        issued: claims[ObservationClaim.EffectiveDateTime] || claims[ObservationClaim.EffectiveDateTimeLegacy]
+            ? undefined
+            : claims[ObservationClaim.Date],
+        performer: claims[ObservationClaim.Performer] ? claims[ObservationClaim.Performer].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
+        valueCodeableConcept: valueConceptToken
+            ? {
+                coding: valueConceptCoding,
+                ...(claims[ObservationClaim.ValueConceptText]
+                    ? { text: claims[ObservationClaim.ValueConceptText] }
+                    : {}),
+            }
+            : undefined,
+        valueDateTime: claims[ObservationClaim.ValueDate],
+        valueQuantity: claims[ObservationClaim.ValueQuantityNumber]
+            ? {
+                value: Number(claims[ObservationClaim.ValueQuantityNumber]),
+                ...(claims[ObservationClaim.ValueQuantityComparator]
+                    ? { comparator: claims[ObservationClaim.ValueQuantityComparator] }
+                    : {}),
+                ...(claims[ObservationClaim.ValueQuantityUnit]
+                    ? {
+                        unit: claims[ObservationClaim.ValueQuantityUnit],
+                        ...(valueQuantityCoding?.system ? { system: valueQuantityCoding.system } : {}),
+                        ...(valueQuantityCoding?.code ? { code: valueQuantityCoding.code } : {}),
+                    }
+                    : {}),
+            }
+            : undefined,
+        valueString: claims[ObservationClaim.ValueString],
+        note: claims[ObservationClaim.Note] ? [{ text: claims[ObservationClaim.Note] }] : undefined,
+        basedOn: claims[ObservationClaim.BasedOn] ? claims[ObservationClaim.BasedOn].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
+        device: claims[ObservationClaim.Device] ? { reference: claims[ObservationClaim.Device] } : undefined,
+        encounter: claims[ObservationClaim.Encounter] ? { reference: claims[ObservationClaim.Encounter] } : undefined,
+        focus: claims[ObservationClaim.Focus] ? claims[ObservationClaim.Focus].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
+        hasMember: claims[ObservationClaim.HasMember] ? claims[ObservationClaim.HasMember].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
+        method: claims[ObservationClaim.Method] ? { coding: codingFromValue(claims[ObservationClaim.Method]) } : undefined,
+        specimen: claims[ObservationClaim.Specimen] ? { reference: claims[ObservationClaim.Specimen] } : undefined,
+        referenceRange: claims[ObservationClaim.ReferenceRangeLowNumber] || claims[ObservationClaim.ReferenceRangeHighNumber] || claims[ObservationClaim.ReferenceRangeText]
+            ? [{
+                    low: claims[ObservationClaim.ReferenceRangeLowNumber] ? quantityFromClaims(claims[ObservationClaim.ReferenceRangeLowNumber], referenceUnit) : undefined,
+                    high: claims[ObservationClaim.ReferenceRangeHighNumber] ? quantityFromClaims(claims[ObservationClaim.ReferenceRangeHighNumber], referenceUnit) : undefined,
+                    text: claims[ObservationClaim.ReferenceRangeText],
+                }]
+            : undefined,
+        component: componentCodes.map((code, index) => ({
+            code: { coding: codingFromValue(code)?.map((coding) => ({ ...coding, ...(componentDisplays[index] ? { display: componentDisplays[index] } : {}) })) },
+            valueQuantity: componentNumbers[index] ? quantityFromClaims(componentNumbers[index], componentUnits[index]) : undefined,
+        })),
+    };
+}
+/**
+ * Converts a FHIR R4 Observation into the flat editable claims contract.
+ *
+ * `Observation.category` stays in `Observation.category`.
+ * Coded result values belong in `Observation.value-concept-*`.
+ */
+export function observationToFlatFhirR4(resource) {
+    if (resource.component?.length) {
+        throw new TypeError('observation_component_graph_required');
+    }
+    const valueCodeableConcept = resource.valueCodeableConcept;
+    const codeCoding = resource.code?.coding?.[0];
+    const valueConceptCoding = valueCodeableConcept?.coding?.[0];
+    const valueQuantity = resource.valueQuantity;
+    const referenceRange = resource.referenceRange?.[0];
+    const referenceLow = referenceRange?.low;
+    const referenceHigh = referenceRange?.high;
+    return {
+        [ObservationClaim.BasedOn]: referenceListToCsv(resource.basedOn),
+        [ObservationClaim.Category]: codingListToCsv(resource.category?.flatMap((item) => item.coding || [])),
+        [ObservationClaim.Code]: codingToValue(codeCoding),
+        [ObservationClaim.CodeSystem]: codeCoding?.system,
+        [ObservationClaim.CodeValue]: codeCoding?.code,
+        [ObservationClaim.CodeText]: resource.code?.text,
+        [ObservationClaim.CodeDisplay]: codeCoding?.display,
+        [ObservationClaim.Date]: resource.effectiveDateTime || resource.issued,
+        [ObservationClaim.Device]: referenceToValue(resource.device),
+        [ObservationClaim.Encounter]: referenceToValue(resource.encounter),
+        [ObservationClaim.Focus]: referenceListToCsv(resource.focus),
+        [ObservationClaim.HasMember]: referenceListToCsv(resource.hasMember),
+        [ObservationClaim.Identifier]: resource.identifier?.[0]?.value,
+        [ObservationClaim.Method]: codingToValue(resource.method?.coding?.[0]),
+        [ObservationClaim.Patient]: referenceToValue(resource.subject),
+        [ObservationClaim.Performer]: referenceListToCsv(resource.performer),
+        [ObservationClaim.Specimen]: referenceToValue(resource.specimen),
+        [ObservationClaim.Status]: resource.status,
+        [ObservationClaim.Subject]: referenceToValue(resource.subject),
+        [ObservationClaim.ValueConcept]: codingToValue(valueConceptCoding),
+        [ObservationClaim.ValueConceptSystem]: valueConceptCoding?.system,
+        [ObservationClaim.ValueConceptValue]: valueConceptCoding?.code,
+        [ObservationClaim.ValueConceptText]: valueCodeableConcept?.text,
+        [ObservationClaim.ValueConceptDisplay]: valueConceptCoding?.display,
+        [ObservationClaim.ValueDate]: resource.valueDateTime,
+        [ObservationClaim.ValueQuantityComparator]: valueQuantity?.comparator,
+        [ObservationClaim.ValueQuantityNumber]: valueQuantity?.value !== undefined ? String(valueQuantity.value) : undefined,
+        [ObservationClaim.ValueQuantityUnit]: codingToValue(valueQuantity?.system || valueQuantity?.code
+            ? { system: valueQuantity?.system, code: valueQuantity?.code }
+            : undefined) || valueQuantity?.unit,
+        [ObservationClaim.ValueString]: resource.valueString,
+        [ObservationClaim.Note]: resource.note?.[0]?.text,
+        [ObservationClaim.EffectiveDateTime]: resource.effectiveDateTime,
+        [ObservationClaim.ReferenceRangeLowNumber]: scalarString(referenceLow?.value),
+        [ObservationClaim.ReferenceRangeHighNumber]: scalarString(referenceHigh?.value),
+        [ObservationClaim.ReferenceRangeUnit]: codingToValue(referenceLow?.system || referenceLow?.code ? { system: referenceLow?.system, code: referenceLow?.code } : referenceHigh?.system || referenceHigh?.code ? { system: referenceHigh?.system, code: referenceHigh?.code } : undefined) || referenceLow?.unit || referenceHigh?.unit,
+        [ObservationClaim.ReferenceRangeText]: referenceRange?.text,
+    };
+}
+/**
+ * Flattens a native component Observation into a parent plus independently
+ * indexable reduced Observation entries. Membership belongs to the parent
+ * through `Observation.has-member`; child containment flags are never written.
+ */
+export function observationFhirR4ToFlatGraph(resource, options) {
+    const components = resource.component ?? [];
+    if (options.componentEntryIds && options.componentEntryIds.length !== components.length) {
+        throw new TypeError('observation_component_entry_count_mismatch');
+    }
+    const componentEntryIds = components.map((_, index) => options.componentEntryIds?.[index] ?? `${options.parentEntryId}-component-${index + 1}`);
+    const shared = {
+        subject: resource.subject,
+        effectiveDateTime: resource.effectiveDateTime,
+        issued: resource.issued,
+        category: resource.category,
+    };
+    const parentClaims = definedClaims(observationToFlatFhirR4({ ...resource, component: undefined }));
+    if (componentEntryIds.length) {
+        parentClaims[ObservationClaim.HasMember] = componentEntryIds
+            .map(entryId => `Observation/${entryId}`)
+            .join(',');
+    }
+    const parent = buildFlatClaimResourceEntry({
+        entryId: options.parentEntryId,
+        resourceType: 'Observation',
+        claims: parentClaims,
+    });
+    const children = components.map((component, index) => {
+        const entryId = componentEntryIds[index];
+        const claims = definedClaims(observationToFlatFhirR4({
+            resourceType: 'Observation',
+            identifier: [{ value: entryId }],
+            ...shared,
+            ...component,
+            status: undefined,
+            component: undefined,
+        }));
+        return buildFlatClaimResourceEntry({ entryId, resourceType: 'Observation', claims });
+    });
+    return Object.freeze([parent, ...children]);
+}
+/** Reconstructs a native FHIR R4 `Observation.component[]` from its flat graph. */
+export function observationFlatGraphToFhirR4(graph, parentEntryId) {
+    const parent = graph.find(entry => entry.entryId === parentEntryId && entry.resourceType === 'Observation');
+    if (!parent)
+        throw new TypeError('observation_parent_entry_not_found');
+    const byReference = new Map(graph.map(entry => [entry.reference, entry]));
+    const references = parent.claims[ObservationClaim.HasMember]?.split(',').map(value => value.trim()).filter(Boolean) ?? [];
+    const projected = { ...observationFromFlatToFhirR4(parent.claims) };
+    delete projected.hasMember;
+    projected.component = references.map(reference => {
+        const child = byReference.get(reference);
+        if (!child || child.resourceType !== 'Observation')
+            throw new TypeError('observation_component_entry_not_found');
+        const componentObservation = observationFromFlatToFhirR4(child.claims);
+        return definedObject({
+            code: componentObservation.code,
+            valueCodeableConcept: componentObservation.valueCodeableConcept,
+            valueDateTime: componentObservation.valueDateTime,
+            valueQuantity: componentObservation.valueQuantity,
+            valueString: componentObservation.valueString,
+            referenceRange: componentObservation.referenceRange,
+        });
+    });
+    return projected;
+}
+function splitClaimList(value) { return value ? JSON.parse(value) : []; }
+function scalarString(value) { return value === undefined || value === null ? undefined : String(value); }
+function quantityFromClaims(number, unit) {
+    const coding = codingFromValue(unit)?.[0];
+    return { value: Number(number), ...(unit ? { unit, ...(coding?.system ? { system: coding.system } : {}), ...(coding?.code ? { code: coding.code } : {}) } : {}) };
+}
+function definedClaims(claims) {
+    return Object.fromEntries(Object.entries(claims).filter((entry) => typeof entry[1] === 'string'));
+}
+function definedObject(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
+}
+/** @deprecated Prefer `observationFromFlatToFhirR4`. */
+export const observationFlatToFhirR4 = observationFromFlatToFhirR4;
+/** @deprecated Prefer `observationToFlatFhirR4`. */
+export const observationFhirR4ToFlat = observationToFlatFhirR4;

package/dist/converters/convert-organization.d.ts

@@ -0,0 +1,3 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+export declare function organizationFlatToFhirR4(claims: FlatClaims): FhirResource;
+export declare function organizationFhirR4ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-organization.js

@@ -0,0 +1,39 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+// File: src/convert/convert-organization.ts
+import { OrganizationClaim } from '../claims/organization-claims.js';
+import { codingFromValue, codingToValue, referenceToValue } from './convert-shared.js';
+function splitCsv(value) {
+    return String(value || '')
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+export function organizationFlatToFhirR4(claims) {
+    return {
+        resourceType: 'Organization',
+        identifier: claims[OrganizationClaim.Identifier] ? [{ value: claims[OrganizationClaim.Identifier] }] : undefined,
+        active: claims[OrganizationClaim.Active] === undefined ? undefined : claims[OrganizationClaim.Active] === 'true',
+        type: claims[OrganizationClaim.Type] ? [{ coding: codingFromValue(claims[OrganizationClaim.Type]) }] : undefined,
+        name: claims[OrganizationClaim.Name],
+        alias: splitCsv(claims[OrganizationClaim.Alias]),
+        partOf: claims[OrganizationClaim.PartOf] ? { reference: claims[OrganizationClaim.PartOf] } : undefined,
+        telecom: splitCsv(claims[OrganizationClaim.Telecom]).map((value) => ({ value })),
+        address: claims[OrganizationClaim.Address] ? [{ text: claims[OrganizationClaim.Address] }] : undefined,
+    };
+}
+export function organizationFhirR4ToFlat(resource) {
+    const alias = resource.alias?.filter(Boolean);
+    const telecom = resource.telecom
+        ?.map((item) => item?.value)
+        .filter((item) => Boolean(item));
+    return {
+        [OrganizationClaim.Identifier]: resource.identifier?.[0]?.value,
+        [OrganizationClaim.Active]: resource.active === undefined ? undefined : String(resource.active),
+        [OrganizationClaim.Type]: codingToValue(resource.type?.[0]?.coding?.[0]),
+        [OrganizationClaim.Name]: resource.name,
+        [OrganizationClaim.Alias]: alias?.length ? alias.join(',') : undefined,
+        [OrganizationClaim.PartOf]: referenceToValue(resource.partOf),
+        [OrganizationClaim.Telecom]: telecom?.length ? telecom.join(',') : undefined,
+        [OrganizationClaim.Address]: resource.address?.[0]?.text,
+    };
+}

package/dist/converters/convert-practitioner-role.d.ts

@@ -0,0 +1,3 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+export declare function practitionerRoleFhirR4ToFlat(resource: FhirResource, _context?: string): FlatClaims;
+export declare function practitionerRoleFlatToFhirR4(claims: FlatClaims): FhirResource;

package/dist/converters/convert-practitioner-role.js

@@ -0,0 +1,62 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { PractitionerRoleClaim } from '../claims/practitioner-role-claims.js';
+import { codingFromValue, codingToValue, referenceListToCsv, referenceToValue, } from './convert-shared.js';
+export function practitionerRoleFhirR4ToFlat(resource, _context = 'org.hl7.fhir.api') {
+    const concept = resource.code?.[0];
+    return {
+        [PractitionerRoleClaim.Identifier]: resource.identifier?.[0]?.value,
+        [PractitionerRoleClaim.Active]: resource.active === undefined ? undefined : String(resource.active),
+        [PractitionerRoleClaim.Practitioner]: referenceToValue(resource.practitioner),
+        [PractitionerRoleClaim.Organization]: referenceToValue(resource.organization),
+        [PractitionerRoleClaim.Location]: referenceListToCsv(resource.location),
+        [PractitionerRoleClaim.Service]: referenceListToCsv(resource.healthcareService),
+        [PractitionerRoleClaim.Specialty]: codingToValue(resource.specialty?.[0]?.coding?.[0]),
+        [PractitionerRoleClaim.PeriodStart]: resource.period?.start,
+        [PractitionerRoleClaim.PeriodEnd]: resource.period?.end,
+        [PractitionerRoleClaim.Code]: codingToValue(concept?.coding?.[0]),
+        [PractitionerRoleClaim.CodeText]: concept?.text,
+        [PractitionerRoleClaim.CodeDisplay]: concept?.coding?.[0]?.display,
+    };
+}
+export function practitionerRoleFlatToFhirR4(claims) {
+    const location = claims[PractitionerRoleClaim.Location]?.split(',').map((reference) => ({ reference: reference.trim() }));
+    const healthcareService = claims[PractitionerRoleClaim.Service]?.split(',').map((reference) => ({ reference: reference.trim() }));
+    const coding = codingFromValue(claims[PractitionerRoleClaim.Code])?.map((item) => ({
+        ...item,
+        ...(claims[PractitionerRoleClaim.CodeDisplay]
+            ? { display: claims[PractitionerRoleClaim.CodeDisplay] }
+            : {}),
+    }));
+    return {
+        resourceType: 'PractitionerRole',
+        identifier: claims[PractitionerRoleClaim.Identifier]
+            ? [{ value: claims[PractitionerRoleClaim.Identifier] }]
+            : undefined,
+        active: claims[PractitionerRoleClaim.Active] === undefined
+            ? undefined
+            : claims[PractitionerRoleClaim.Active] === 'true',
+        practitioner: claims[PractitionerRoleClaim.Practitioner]
+            ? { reference: claims[PractitionerRoleClaim.Practitioner] }
+            : undefined,
+        organization: claims[PractitionerRoleClaim.Organization]
+            ? { reference: claims[PractitionerRoleClaim.Organization] }
+            : undefined,
+        location,
+        healthcareService,
+        specialty: claims[PractitionerRoleClaim.Specialty]
+            ? [{ coding: codingFromValue(claims[PractitionerRoleClaim.Specialty]) }]
+            : undefined,
+        period: claims[PractitionerRoleClaim.PeriodStart] || claims[PractitionerRoleClaim.PeriodEnd]
+            ? {
+                start: claims[PractitionerRoleClaim.PeriodStart],
+                end: claims[PractitionerRoleClaim.PeriodEnd],
+            }
+            : undefined,
+        code: coding || claims[PractitionerRoleClaim.CodeText] ? [{
+                ...(coding ? { coding } : {}),
+                ...(claims[PractitionerRoleClaim.CodeText]
+                    ? { text: claims[PractitionerRoleClaim.CodeText] }
+                    : {}),
+            }] : undefined,
+    };
+}

package/dist/converters/convert-procedure.d.ts

@@ -0,0 +1,3 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+export declare function procedureFlatToFhirR4(claims: FlatClaims): FhirResource;
+export declare function procedureFhirR4ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-procedure.js

@@ -0,0 +1,64 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+// File: src/utils/convert-procedure.ts
+import { ProcedureClaim } from '../claims/procedure-claims.js';
+import { codingFromValue, codingToValue, referenceListToCsv, referenceToValue } from './convert-shared.js';
+export function procedureFlatToFhirR4(claims) {
+    const subject = claims[ProcedureClaim.Subject] ?? claims[ProcedureClaim.Patient];
+    return {
+        resourceType: 'Procedure',
+        identifier: claims[ProcedureClaim.Identifier] ? [{ value: claims[ProcedureClaim.Identifier] }] : undefined,
+        status: claims[ProcedureClaim.Status],
+        subject: subject ? { reference: subject } : undefined,
+        code: claims[ProcedureClaim.Code]
+            ? {
+                coding: codingFromValue(claims[ProcedureClaim.Code])?.map((coding) => ({
+                    ...coding,
+                    ...(claims[ProcedureClaim.CodeDisplay]
+                        ? { display: claims[ProcedureClaim.CodeDisplay] }
+                        : {}),
+                })),
+                ...(claims[ProcedureClaim.CodeText]
+                    ? { text: claims[ProcedureClaim.CodeText] }
+                    : {}),
+            }
+            : undefined,
+        performedDateTime: claims[ProcedureClaim.Date],
+        note: claims[ProcedureClaim.Note] ? [{ text: claims[ProcedureClaim.Note] }] : undefined,
+        basedOn: claims[ProcedureClaim.BasedOn] ? claims[ProcedureClaim.BasedOn].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
+        bodySite: claims[ProcedureClaim.BodySite] ? [{ coding: codingFromValue(claims[ProcedureClaim.BodySite]) }] : undefined,
+        encounter: claims[ProcedureClaim.Encounter] ? { reference: claims[ProcedureClaim.Encounter] } : undefined,
+        instantiatesCanonical: claims[ProcedureClaim.InstantiatesCanonical] ? [claims[ProcedureClaim.InstantiatesCanonical]] : undefined,
+        instantiatesUri: claims[ProcedureClaim.InstantiatesUri] ? [claims[ProcedureClaim.InstantiatesUri]] : undefined,
+        location: claims[ProcedureClaim.Location] ? { reference: claims[ProcedureClaim.Location] } : undefined,
+        partOf: claims[ProcedureClaim.PartOf] ? claims[ProcedureClaim.PartOf].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
+        performer: claims[ProcedureClaim.Performer] ? claims[ProcedureClaim.Performer].split(',').map((reference) => ({ actor: { reference: reference.trim() } })) : undefined,
+        reasonCode: claims[ProcedureClaim.ReasonCode] ? [{ coding: codingFromValue(claims[ProcedureClaim.ReasonCode]) }] : undefined,
+        reasonReference: claims[ProcedureClaim.ReasonReference] ? claims[ProcedureClaim.ReasonReference].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
+    };
+}
+export function procedureFhirR4ToFlat(resource) {
+    const performer = Array.isArray(resource.performer)
+        ? resource.performer.map((item) => referenceToValue(item?.actor)).filter((item) => Boolean(item))
+        : [];
+    return {
+        [ProcedureClaim.BasedOn]: referenceListToCsv(resource.basedOn),
+        [ProcedureClaim.BodySite]: codingToValue(resource.bodySite?.[0]?.coding?.[0]),
+        [ProcedureClaim.Code]: codingToValue(resource.code?.coding?.[0]),
+        [ProcedureClaim.CodeText]: resource.code?.text,
+        [ProcedureClaim.CodeDisplay]: resource.code?.coding?.[0]?.display,
+        [ProcedureClaim.Date]: resource.performedDateTime || resource.performedPeriod?.start,
+        [ProcedureClaim.Encounter]: referenceToValue(resource.encounter),
+        [ProcedureClaim.Identifier]: resource.identifier?.[0]?.value,
+        [ProcedureClaim.InstantiatesCanonical]: Array.isArray(resource.instantiatesCanonical) ? resource.instantiatesCanonical[0] : undefined,
+        [ProcedureClaim.InstantiatesUri]: Array.isArray(resource.instantiatesUri) ? resource.instantiatesUri[0] : undefined,
+        [ProcedureClaim.Location]: referenceToValue(resource.location),
+        [ProcedureClaim.PartOf]: referenceListToCsv(resource.partOf),
+        [ProcedureClaim.Patient]: referenceToValue(resource.subject),
+        [ProcedureClaim.Performer]: performer.length ? performer.join(',') : undefined,
+        [ProcedureClaim.ReasonCode]: codingToValue(resource.reasonCode?.[0]?.coding?.[0]),
+        [ProcedureClaim.ReasonReference]: referenceListToCsv(resource.reasonReference),
+        [ProcedureClaim.Status]: resource.status,
+        [ProcedureClaim.Subject]: referenceToValue(resource.subject),
+        [ProcedureClaim.Note]: resource.note?.[0]?.text,
+    };
+}

package/dist/converters/convert-related-person.d.ts

@@ -0,0 +1,3 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+export declare function relatedPersonFlatToFhirR4(claims: FlatClaims): FhirResource;
+export declare function relatedPersonFhirR4ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-related-person.js

@@ -0,0 +1,31 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+// File: src/utils/convert-related-person.ts
+import { RelatedPersonClaim } from '../claims/related-person-claims.js';
+import { codingFromValue, codingToValue, referenceToValue } from './convert-shared.js';
+export function relatedPersonFlatToFhirR4(claims) {
+    return {
+        resourceType: 'RelatedPerson',
+        identifier: claims[RelatedPersonClaim.Identifier] ? [{ value: claims[RelatedPersonClaim.Identifier] }] : undefined,
+        active: claims[RelatedPersonClaim.Active] === undefined ? undefined : claims[RelatedPersonClaim.Active] === 'true',
+        patient: claims[RelatedPersonClaim.Patient] ? { reference: claims[RelatedPersonClaim.Patient] } : undefined,
+        relationship: claims[RelatedPersonClaim.Relationship] ? [{ coding: codingFromValue(claims[RelatedPersonClaim.Relationship]) }] : undefined,
+        name: claims[RelatedPersonClaim.Name] ? [{ text: claims[RelatedPersonClaim.Name] }] : undefined,
+        telecom: claims[RelatedPersonClaim.Telecom] ? [{ value: claims[RelatedPersonClaim.Telecom] }] : undefined,
+        gender: claims[RelatedPersonClaim.Gender],
+        birthDate: claims[RelatedPersonClaim.BirthDate],
+        address: claims[RelatedPersonClaim.Address] ? [{ text: claims[RelatedPersonClaim.Address] }] : undefined,
+    };
+}
+export function relatedPersonFhirR4ToFlat(resource) {
+    return {
+        [RelatedPersonClaim.Identifier]: resource.identifier?.[0]?.value,
+        [RelatedPersonClaim.Active]: resource.active === undefined ? undefined : String(resource.active),
+        [RelatedPersonClaim.Patient]: referenceToValue(resource.patient),
+        [RelatedPersonClaim.Relationship]: codingToValue(resource.relationship?.[0]?.coding?.[0]),
+        [RelatedPersonClaim.Name]: resource.name?.[0]?.text,
+        [RelatedPersonClaim.Telecom]: resource.telecom?.[0]?.value,
+        [RelatedPersonClaim.Gender]: resource.gender,
+        [RelatedPersonClaim.BirthDate]: resource.birthDate,
+        [RelatedPersonClaim.Address]: resource.address?.[0]?.text,
+    };
+}

package/dist/converters/convert-shared.d.ts

@@ -0,0 +1,33 @@
+import type { FhirResource } from '../fhir-types.js';
+export type FlatClaims = Record<string, string | undefined>;
+export type { FhirResource } from '../fhir-types.js';
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function codingFromValue(value?: string): Array<{
+    system?: string;
+    code: string;
+}> | undefined;
+export declare function codingToValue(coding?: {
+    system?: string;
+    code?: string;
+}): string | undefined;
+export declare function referenceToValue(reference?: {
+    reference?: string;
+}): string | undefined;
+export declare function referenceListToCsv(references?: Array<{
+    reference?: string;
+}>): string | undefined;
+export declare function codingListToCsv(codings?: Array<{
+    system?: string;
+    code?: string;
+}>): string | undefined;
+export declare function requireClaim(claims: FlatClaims, key: string): string;
+export declare function requireSubjectIdentifier(value: string, key: string): void;
+export declare function requireDidWeb(value: string, key: string): void;
+/**
+ * Generic structural fallback for unsupported resources.
+ */
+export declare function fhirResourceToFlatClaims(resource: FhirResource, context?: string): FlatClaims;
+/**
+ * Generic structural regeneration for unsupported resources.
+ */
+export declare function flatClaimsToFhirResource(claims: FlatClaims): FhirResource;