fhir-data-utils-ts 0.2.4 → 0.3.2

package/dist/converters/convert-shared.js

@@ -0,0 +1,190 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+// File: src/utils/convert-shared.ts
+export function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export function codingFromValue(value) {
+    if (!value)
+        return undefined;
+    const [system, code] = value.split('|');
+    if (!code)
+        return [{ code: system }];
+    return system ? [{ system, code }] : [{ code }];
+}
+/** Convert one canonical comma-separated token list into FHIR Coding entries. */
+export function codingListFromCsv(value) {
+    const codings = String(value || '')
+        .split(',')
+        .map((token) => token.trim())
+        .filter(Boolean)
+        .flatMap((token) => codingFromValue(token) ?? []);
+    return codings.length ? codings : undefined;
+}
+export function codingToValue(coding) {
+    if (!coding?.code)
+        return undefined;
+    return coding.system ? `${coding.system}|${coding.code}` : coding.code;
+}
+export function referenceToValue(reference) {
+    return reference?.reference;
+}
+export function referenceListToCsv(references) {
+    const values = (references || [])
+        .map((item) => item?.reference)
+        .filter((item) => Boolean(item));
+    return values.length ? values.join(',') : undefined;
+}
+export function codingListToCsv(codings) {
+    const values = (codings || [])
+        .map((item) => codingToValue(item))
+        .filter((item) => Boolean(item));
+    return values.length ? values.join(',') : undefined;
+}
+export function requireClaim(claims, key) {
+    const value = claims[key];
+    if (!value)
+        throw new Error(`Missing required claim: ${key}`);
+    return value;
+}
+export function requireSubjectIdentifier(value, key) {
+    if (!value.startsWith('urn:') && !value.startsWith('did:web:')) {
+        throw new Error(`Invalid ${key}: expected urn:* or did:web:*`);
+    }
+}
+export function requireDidWeb(value, key) {
+    if (!value.startsWith('did:web:')) {
+        throw new Error(`Invalid ${key}: expected did:web:*`);
+    }
+}
+function stringifyClaimLeaf(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+function flattenClaimPath(prefix, value, out) {
+    const primitive = stringifyClaimLeaf(value);
+    if (primitive !== undefined) {
+        out[prefix] = primitive;
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            out[`${prefix}#type`] = typeof value;
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => {
+            flattenClaimPath(`${prefix}[${index}]`, entry, out);
+        });
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const [key, nestedValue] of Object.entries(value)) {
+            if (key === 'claims' && prefix.endsWith('.meta'))
+                continue;
+            if (key === 'meta' && isPlainObject(nestedValue) && 'claims' in nestedValue) {
+                const nestedMeta = { ...nestedValue };
+                delete nestedMeta.claims;
+                if (Object.keys(nestedMeta).length === 0)
+                    continue;
+                flattenClaimPath(`${prefix}.${key}`, nestedMeta, out);
+                continue;
+            }
+            flattenClaimPath(`${prefix}.${key}`, nestedValue, out);
+        }
+    }
+}
+function parseClaimPath(path) {
+    const segments = [];
+    const re = /([^[.\]]+)|\[(\d+)\]/g;
+    let match;
+    while ((match = re.exec(path)) !== null) {
+        if (match[1])
+            segments.push(match[1]);
+        else if (match[2])
+            segments.push(Number(match[2]));
+    }
+    return segments;
+}
+function coerceClaimLeaf(value, typeHint) {
+    if (typeHint === 'boolean')
+        return value === 'true';
+    if (typeHint === 'number')
+        return Number(value);
+    return value;
+}
+function assignInflatedPath(target, path, value, typeHint) {
+    const segments = parseClaimPath(path);
+    if (segments.length === 0)
+        return;
+    let cursor = target;
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        const nextSegment = segments[index + 1];
+        const isLast = index === segments.length - 1;
+        if (typeof segment === 'number') {
+            if (!Array.isArray(cursor))
+                return;
+            if (isLast) {
+                cursor[segment] = coerceClaimLeaf(value, typeHint);
+                return;
+            }
+            if (cursor[segment] === undefined)
+                cursor[segment] = typeof nextSegment === 'number' ? [] : {};
+            cursor = cursor[segment];
+            continue;
+        }
+        if (!isPlainObject(cursor))
+            return;
+        if (isLast) {
+            cursor[segment] = coerceClaimLeaf(value, typeHint);
+            return;
+        }
+        if (cursor[segment] === undefined)
+            cursor[segment] = typeof nextSegment === 'number' ? [] : {};
+        cursor = cursor[segment];
+    }
+}
+/**
+ * Generic structural fallback for unsupported resources.
+ */
+export function fhirResourceToFlatClaims(resource, context = 'org.hl7.fhir.api') {
+    if (!resource?.resourceType) {
+        throw new Error('FHIR resource must define resourceType.');
+    }
+    const out = { '@context': context };
+    for (const [key, value] of Object.entries(resource)) {
+        if (key === 'resourceType')
+            continue;
+        flattenClaimPath(`${resource.resourceType}.${key}`, value, out);
+    }
+    return out;
+}
+/**
+ * Generic structural regeneration for unsupported resources.
+ */
+export function flatClaimsToFhirResource(claims) {
+    const typeHints = new Map();
+    for (const [key, value] of Object.entries(claims || {})) {
+        if (key.endsWith('#type') && typeof value === 'string') {
+            typeHints.set(key.slice(0, -5), value);
+        }
+    }
+    const entries = Object.entries(claims || {}).filter(([key, value]) => key !== '@context' && !key.endsWith('#type') && value !== undefined);
+    const firstClaimKey = entries[0]?.[0];
+    if (!firstClaimKey || !firstClaimKey.includes('.')) {
+        throw new Error('Flat claims must contain at least one contextualized resource claim.');
+    }
+    const resourceType = firstClaimKey.split('.')[0];
+    const resource = { resourceType };
+    for (const [key, value] of entries) {
+        if (typeof value !== 'string')
+            continue;
+        if (!key.startsWith(`${resourceType}.`))
+            continue;
+        assignInflatedPath(resource, key.slice(resourceType.length + 1), value, typeHints.get(key));
+    }
+    return resource;
+}

package/dist/converters/index.d.ts

@@ -0,0 +1,24 @@
+export * from './convert-shared.js';
+export * from './convert-allergy-intolerance.js';
+export * from './convert-appointment-response.js';
+export * from './convert-appointment.js';
+export * from './convert-care-plan.js';
+export * from './convert-clinical-impression.js';
+export * from './convert-composition.js';
+export * from './convert-consent.js';
+export * from './convert-condition.js';
+export * from './convert-coverage.js';
+export * from './convert-device-use-statement.js';
+export * from './convert-device.js';
+export * from './convert-diagnostic-report.js';
+export * from './convert-document-reference.js';
+export * from './convert-encounter.js';
+export * from './convert-flag.js';
+export * from './convert-immunization.js';
+export * from './convert-location.js';
+export * from './convert-medication-statement.js';
+export * from './convert-observation.js';
+export * from './convert-organization.js';
+export * from './convert-practitioner-role.js';
+export * from './convert-procedure.js';
+export * from './convert-related-person.js';

package/dist/converters/index.js

@@ -0,0 +1,24 @@
+export * from './convert-shared.js';
+export * from './convert-allergy-intolerance.js';
+export * from './convert-appointment-response.js';
+export * from './convert-appointment.js';
+export * from './convert-care-plan.js';
+export * from './convert-clinical-impression.js';
+export * from './convert-composition.js';
+export * from './convert-consent.js';
+export * from './convert-condition.js';
+export * from './convert-coverage.js';
+export * from './convert-device-use-statement.js';
+export * from './convert-device.js';
+export * from './convert-diagnostic-report.js';
+export * from './convert-document-reference.js';
+export * from './convert-encounter.js';
+export * from './convert-flag.js';
+export * from './convert-immunization.js';
+export * from './convert-location.js';
+export * from './convert-medication-statement.js';
+export * from './convert-observation.js';
+export * from './convert-organization.js';
+export * from './convert-practitioner-role.js';
+export * from './convert-procedure.js';
+export * from './convert-related-person.js';

package/dist/fhir-bundle.d.ts

@@ -0,0 +1,9 @@
+import type { FhirBundle, FhirResource } from './fhir-types.js';
+export declare function readBundleResources<TResource extends FhirResource = FhirResource>(bundle: FhirBundle<TResource>): readonly TResource[];
+export declare function findBundleResources<TResource extends FhirResource = FhirResource>(bundle: FhirBundle, resourceType: string): readonly TResource[];
+/** Traverses top-level and native contained resources without changing ownership. */
+export declare function walkBundleResources(bundle: FhirBundle): readonly FhirResource[];
+/** Classifies top-level Bundle resources in encounter order without cloning or mutation. */
+export declare function classifyBundleResources(bundle: FhirBundle): ReadonlyMap<string, readonly FhirResource[]>;
+/** Resolves `ResourceType/id`, `urn:uuid:*`, an entry fullUrl, or a bare resource id. */
+export declare function findBundleResourceByReference(bundle: FhirBundle, reference: string): FhirResource | undefined;

package/dist/fhir-bundle.js

@@ -0,0 +1,43 @@
+export function readBundleResources(bundle) {
+    if (bundle.resourceType !== 'Bundle')
+        throw new TypeError('fhir_bundle_required');
+    return Object.freeze((bundle.entry ?? []).flatMap(entry => entry.resource ? [entry.resource] : []));
+}
+export function findBundleResources(bundle, resourceType) {
+    return Object.freeze(readBundleResources(bundle).filter(resource => resource.resourceType === resourceType));
+}
+/** Traverses top-level and native contained resources without changing ownership. */
+export function walkBundleResources(bundle) {
+    const output = [];
+    const visit = (resource) => {
+        output.push(resource);
+        for (const child of resource.contained ?? [])
+            visit(child);
+    };
+    for (const resource of readBundleResources(bundle))
+        visit(resource);
+    return Object.freeze(output);
+}
+/** Classifies top-level Bundle resources in encounter order without cloning or mutation. */
+export function classifyBundleResources(bundle) {
+    const classified = new Map();
+    for (const resource of readBundleResources(bundle)) {
+        const resources = classified.get(resource.resourceType) ?? [];
+        resources.push(resource);
+        classified.set(resource.resourceType, resources);
+    }
+    return classified;
+}
+/** Resolves `ResourceType/id`, `urn:uuid:*`, an entry fullUrl, or a bare resource id. */
+export function findBundleResourceByReference(bundle, reference) {
+    const target = reference.trim();
+    if (!target)
+        throw new TypeError('fhir_reference_required');
+    const directEntry = bundle.entry?.find(entry => entry.fullUrl === target);
+    if (directEntry?.resource)
+        return directEntry.resource;
+    const [resourceType, id] = target.includes('/')
+        ? target.split('/', 2)
+        : [undefined, target.startsWith('urn:uuid:') ? target.slice('urn:uuid:'.length) : target];
+    return readBundleResources(bundle).find(resource => resource.id === id && (!resourceType || resource.resourceType === resourceType));
+}

package/dist/fhir-search-parameters.d.ts

@@ -0,0 +1,18 @@
+export type FhirSearchParameterType = 'number' | 'date' | 'string' | 'token' | 'reference' | 'composite' | 'quantity' | 'uri';
+export type FhirSearchPrefix = 'eq' | 'ne' | 'gt' | 'lt' | 'ge' | 'le' | 'sa' | 'eb' | 'ap';
+export type FhirSearchParameter = Readonly<{
+    name: string;
+    type: FhirSearchParameterType;
+    value: string | number;
+    prefix?: FhirSearchPrefix;
+    system?: string;
+    unit?: string;
+}>;
+/** Parses one typed FHIR query value without the lossy integer coercion of the retired UHC helper. */
+export declare function parseFhirSearchParameter(input: Readonly<{
+    name: string;
+    type: FhirSearchParameterType;
+    value: string;
+}>): FhirSearchParameter;
+/** Repeats parameters for AND; callers may use comma-separated values for FHIR OR. */
+export declare function buildFhirSearchQuery(parameters: readonly FhirSearchParameter[]): string;

package/dist/fhir-search-parameters.js

@@ -0,0 +1,52 @@
+const PREFIX = /^(eq|ne|gt|lt|ge|le|sa|eb|ap)/;
+/** Parses one typed FHIR query value without the lossy integer coercion of the retired UHC helper. */
+export function parseFhirSearchParameter(input) {
+    const name = required(input.name, 'fhir_search_name_required');
+    const raw = required(input.value, 'fhir_search_value_required');
+    if (input.type === 'token') {
+        const separator = raw.lastIndexOf('|');
+        return Object.freeze({ name, type: input.type, value: separator < 0 ? raw : raw.slice(separator + 1), ...(separator < 0 ? {} : { system: raw.slice(0, separator) }) });
+    }
+    if (input.type === 'quantity') {
+        const match = raw.match(PREFIX);
+        const withoutPrefix = match ? raw.slice(2) : raw;
+        const [numberValue, system, unit] = withoutPrefix.split('|');
+        const value = Number(numberValue);
+        if (!Number.isFinite(value))
+            throw new TypeError('fhir_search_quantity_invalid');
+        return Object.freeze({ name, type: input.type, value, ...(match ? { prefix: match[1] } : {}), ...(system ? { system } : {}), ...(unit ? { unit } : {}) });
+    }
+    if (input.type === 'number') {
+        const match = raw.match(PREFIX);
+        const value = Number(match ? raw.slice(2) : raw);
+        if (!Number.isFinite(value))
+            throw new TypeError('fhir_search_number_invalid');
+        return Object.freeze({ name, type: input.type, value, ...(match ? { prefix: match[1] } : {}) });
+    }
+    if (input.type === 'date') {
+        const match = raw.match(PREFIX);
+        return Object.freeze({ name, type: input.type, value: match ? raw.slice(2) : raw, ...(match ? { prefix: match[1] } : {}) });
+    }
+    return Object.freeze({ name, type: input.type, value: raw });
+}
+/** Repeats parameters for AND; callers may use comma-separated values for FHIR OR. */
+export function buildFhirSearchQuery(parameters) {
+    const query = new URLSearchParams();
+    for (const parameter of parameters) {
+        const prefix = parameter.prefix ?? '';
+        const scalar = String(parameter.value);
+        const value = parameter.type === 'token' && parameter.system
+            ? `${parameter.system}|${scalar}`
+            : parameter.type === 'quantity' && (parameter.system || parameter.unit)
+                ? `${prefix}${scalar}|${parameter.system ?? ''}|${parameter.unit ?? ''}`
+                : `${prefix}${scalar}`;
+        query.append(required(parameter.name, 'fhir_search_name_required'), value);
+    }
+    return query.toString();
+}
+function required(value, error) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError(error);
+    return normalized;
+}

package/dist/fhir-tokens.d.ts

@@ -0,0 +1,11 @@
+import type { FhirContactPoint } from './fhir-types.js';
+/** Builds the FHIR token wire form after rejecting empty or ambiguous input. */
+export declare function makeFhirToken(system: string, code: string): string;
+/** Escapes FHIR search delimiters according to the search value grammar. */
+export declare function escapeFhirSearchValue(value: string): string;
+/** Builds one comma-separated FHIR OR value; repeated query keys remain AND. */
+export declare function joinFhirOrList(values?: readonly (string | number)[]): string | undefined;
+/** Converts valid ContactPoint values to token search values. */
+export declare function telecomToTokens(resource: Readonly<{
+    telecom?: readonly FhirContactPoint[];
+}>): readonly string[];

package/dist/fhir-tokens.js

@@ -0,0 +1,26 @@
+/** Builds the FHIR token wire form after rejecting empty or ambiguous input. */
+export function makeFhirToken(system, code) {
+    const normalizedSystem = required(system, 'fhir_token_system_required');
+    const normalizedCode = required(code, 'fhir_token_code_required');
+    if (normalizedSystem.includes('|') || normalizedCode.includes('|'))
+        throw new TypeError('fhir_token_invalid');
+    return `${normalizedSystem}|${normalizedCode}`;
+}
+/** Escapes FHIR search delimiters according to the search value grammar. */
+export function escapeFhirSearchValue(value) {
+    return String(value).replace(/[\\,|$]/g, '\\$&');
+}
+/** Builds one comma-separated FHIR OR value; repeated query keys remain AND. */
+export function joinFhirOrList(values) {
+    return values?.length ? values.map(value => escapeFhirSearchValue(String(value))).join(',') : undefined;
+}
+/** Converts valid ContactPoint values to token search values. */
+export function telecomToTokens(resource) {
+    return Object.freeze((resource.telecom ?? []).flatMap(point => point.system && point.value?.trim() ? [makeFhirToken(point.system, point.value.trim())] : []));
+}
+function required(value, error) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError(error);
+    return normalized;
+}

package/dist/fhir-types.d.ts

@@ -0,0 +1,77 @@
+/** Version-neutral FHIR primitives used by flat-claim adapters. */
+export type FhirPrimitive = string | number | boolean;
+export type FhirCoding = Readonly<{
+    system?: string;
+    version?: string;
+    code?: string;
+    display?: string;
+    userSelected?: boolean;
+}>;
+export type FhirCodeableConcept = Readonly<{
+    coding?: readonly FhirCoding[];
+    text?: string;
+}>;
+export type FhirIdentifier = Readonly<{
+    use?: string;
+    type?: FhirCodeableConcept;
+    system?: string;
+    value?: string;
+    period?: FhirPeriod;
+    assigner?: FhirReference;
+}>;
+export type FhirReference = Readonly<{
+    reference?: string;
+    type?: string;
+    identifier?: FhirIdentifier;
+    display?: string;
+}>;
+export type FhirQuantity = Readonly<{
+    value?: number;
+    comparator?: '<' | '<=' | '>=' | '>';
+    unit?: string;
+    system?: string;
+    code?: string;
+}>;
+export type FhirPeriod = Readonly<{
+    start?: string;
+    end?: string;
+}>;
+export type FhirAnnotation = Readonly<{
+    authorReference?: FhirReference;
+    authorString?: string;
+    time?: string;
+    text: string;
+}>;
+export type FhirContactPoint = Readonly<{
+    system?: 'phone' | 'fax' | 'email' | 'pager' | 'url' | 'sms' | 'other';
+    value?: string;
+    use?: 'home' | 'work' | 'temp' | 'old' | 'mobile';
+    rank?: number;
+    period?: FhirPeriod;
+}>;
+export type FhirResource = Readonly<{
+    resourceType: string;
+    id?: string;
+    language?: string;
+    meta?: Readonly<Record<string, unknown>>;
+    contained?: readonly FhirResource[];
+    [key: string]: unknown;
+}>;
+export type FhirBundleEntry<TResource extends FhirResource = FhirResource> = Readonly<{
+    fullUrl?: string;
+    resource?: TResource;
+    request?: Readonly<{
+        method?: string;
+        url?: string;
+    }>;
+    response?: Readonly<{
+        status?: string;
+        location?: string;
+    }>;
+}>;
+export type FhirBundle<TResource extends FhirResource = FhirResource> = FhirResource & Readonly<{
+    resourceType: 'Bundle';
+    type?: string;
+    total?: number;
+    entry?: readonly FhirBundleEntry<TResource>[];
+}>;

package/dist/fhir-types.js

@@ -0,0 +1 @@
+export {};

package/dist/fhir-values.d.ts

@@ -0,0 +1,13 @@
+import type { FhirCoding, FhirIdentifier, FhirQuantity, FhirReference } from './fhir-types.js';
+/** Serializes a Coding as the established `system|code` flat token. */
+export declare function codingToToken(coding: FhirCoding | undefined): string | undefined;
+/** Parses a flat coding token without treating URI colons or slashes as separators. */
+export declare function tokenToCoding(token: string | undefined): FhirCoding | undefined;
+/** Serializes an Identifier without discarding its assigning system. */
+export declare function identifierToToken(identifier: FhirIdentifier | undefined): string | undefined;
+export declare function tokenToIdentifier(token: string | undefined): FhirIdentifier | undefined;
+export declare function referenceToString(reference: FhirReference | undefined): string | undefined;
+export declare function stringToReference(reference: string | undefined): FhirReference | undefined;
+/** Serializes Quantity as `value|system|code`; unit remains display-only. */
+export declare function quantityToToken(quantity: FhirQuantity | undefined): string | undefined;
+export declare function tokenToQuantity(token: string | undefined): FhirQuantity | undefined;

package/dist/fhir-values.js

@@ -0,0 +1,53 @@
+/** Serializes a Coding as the established `system|code` flat token. */
+export function codingToToken(coding) {
+    const code = coding?.code?.trim();
+    if (!code)
+        return undefined;
+    const system = coding?.system?.trim();
+    return system ? `${system}|${code}` : code;
+}
+/** Parses a flat coding token without treating URI colons or slashes as separators. */
+export function tokenToCoding(token) {
+    const value = token?.trim();
+    if (!value)
+        return undefined;
+    const separator = value.lastIndexOf('|');
+    return separator < 0
+        ? Object.freeze({ code: value })
+        : Object.freeze({ system: value.slice(0, separator) || undefined, code: value.slice(separator + 1) });
+}
+/** Serializes an Identifier without discarding its assigning system. */
+export function identifierToToken(identifier) {
+    const value = identifier?.value?.trim();
+    if (!value)
+        return undefined;
+    const system = identifier?.system?.trim();
+    return system ? `${system}|${value}` : value;
+}
+export function tokenToIdentifier(token) {
+    const coding = tokenToCoding(token);
+    return coding?.code ? Object.freeze({ system: coding.system, value: coding.code }) : undefined;
+}
+export function referenceToString(reference) {
+    return reference?.reference?.trim() || undefined;
+}
+export function stringToReference(reference) {
+    const value = reference?.trim();
+    return value ? Object.freeze({ reference: value }) : undefined;
+}
+/** Serializes Quantity as `value|system|code`; unit remains display-only. */
+export function quantityToToken(quantity) {
+    if (quantity?.value === undefined || !Number.isFinite(quantity.value))
+        return undefined;
+    return [String(quantity.value), quantity.system?.trim() ?? '', quantity.code?.trim() ?? ''].join('|');
+}
+export function tokenToQuantity(token) {
+    const value = token?.trim();
+    if (!value)
+        return undefined;
+    const [numberValue, system, code] = value.split('|');
+    const numeric = Number(numberValue);
+    if (!Number.isFinite(numeric))
+        throw new TypeError('fhir_quantity_token_invalid');
+    return Object.freeze({ value: numeric, ...(system ? { system } : {}), ...(code ? { code, unit: code } : {}) });
+}