gdc-common-utils-ts 2.1.0 → 2.2.2

package/dist/utils/bundle-document-builder.js

@@ -1,4 +1,10 @@
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { AllergyIntoleranceClaim } from '../models/interoperable-claims/allergy-intolerance-claims.js';
+import { CompositionClaim } from '../models/interoperable-claims/composition-claims.js';
+import { ConditionClaim } from '../models/interoperable-claims/condition-claims.js';
+import { DiagnosticReportClaim } from '../models/interoperable-claims/diagnostic-report-claims.js';
+import { MedicationStatementClaim } from '../models/interoperable-claims/medication-statement-claims.js';
+import { ClaimConsent } from '../models/consent-rule.js';
 import { allergyIntoleranceFlatToFhirR4, appointmentFlatToFhirR4, carePlanFlatToFhirR4, clinicalImpressionFlatToFhirR4, compositionFlatToFhirR4, conditionFlatToFhirR4, convertFhirResourceToClaims, coverageFlatToFhirR4, deviceFlatToFhirR4, documentReferenceFlatToFhirR4, diagnosticReportFlatToFhirR4, encounterFlatToFhirR4, flagFlatToFhirR4, flatClaimsToFhirResource, immunizationFlatToFhirR4, locationFlatToFhirR4, medicationStatementFlatToFhirR4, observationFromFlatToFhirR4, organizationFlatToFhirR4, procedureFlatToFhirR4, relatedPersonFlatToFhirR4, } from './clinical-resource-converters.js';
 function asTrimmedString(value) {
     if (value === undefined || value === null)
@@ -93,6 +99,43 @@ function normalizeSectionCode(value) {
         return { code: system };
     return { system, code };
 }
+function resolveContainedReferenceListClaimKey(resourceType) {
+    switch (resourceType) {
+        case ResourceTypesFhirR4.MedicationStatement:
+            return MedicationStatementClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.AllergyIntolerance:
+            return AllergyIntoleranceClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.Condition:
+            return ConditionClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.DiagnosticReport:
+            return DiagnosticReportClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.Consent:
+            return ClaimConsent.containedReferenceList;
+        default:
+            return undefined;
+    }
+}
+function resolveContainedFlagClaimKey(resourceType) {
+    const normalized = asTrimmedString(resourceType);
+    return normalized ? `${normalized}.is-contained` : undefined;
+}
+function resolveContainedParentReferenceClaimKey(resourceType) {
+    const normalized = asTrimmedString(resourceType);
+    return normalized ? `${normalized}.contained-parent-reference` : undefined;
+}
+function mergeContainedResourceReferenceList(claims, references) {
+    const resourceType = detectClaimsResourceType(claims);
+    const claimKey = resourceType ? resolveContainedReferenceListClaimKey(resourceType) : undefined;
+    if (!claimKey || references.length === 0) {
+        return claims;
+    }
+    const current = splitCsv(claims[claimKey]);
+    const next = Array.from(new Set([...current, ...references].map((item) => asTrimmedString(item)).filter(Boolean)));
+    return {
+        ...claims,
+        [claimKey]: next.join(','),
+    };
+}
 export function detectClaimsResourceType(claims) {
     const keys = Object.keys(claims || {});
     if (keys.some((key) => key.startsWith('MedicationStatement.')))
@@ -181,12 +224,47 @@ export function extractBundleDocumentClaimsList(bundle, context = 'org.hl7.fhir.
         .map((entry) => entry?.resource)
         .filter((resource) => resource && typeof resource === 'object')
         .filter((resource) => !ignoredResourceTypes.has(String(resource.resourceType || '')))
-        .map((resource) => {
-        const metaClaims = resource?.meta?.claims;
-        if (metaClaims && typeof metaClaims === 'object' && !Array.isArray(metaClaims)) {
-            return ensureClaimsIdentifier({ ...metaClaims }, resource);
-        }
-        return ensureClaimsIdentifier(convertFhirResourceToClaims(resource, context), resource);
+        .flatMap((resource) => {
+        const resourceRecord = resource;
+        const resourceReference = `${asTrimmedString(resourceRecord.resourceType)}/${asTrimmedString(resourceRecord.id)}`;
+        const metaClaims = resourceRecord?.meta?.claims;
+        const baseClaims = metaClaims && typeof metaClaims === 'object' && !Array.isArray(metaClaims)
+            ? ensureClaimsIdentifier({ ...metaClaims }, resourceRecord)
+            : ensureClaimsIdentifier(convertFhirResourceToClaims(resourceRecord, context), resourceRecord);
+        const containedResources = Array.isArray(resourceRecord.contained)
+            ? resourceRecord.contained
+            : [];
+        const containedClaimsList = containedResources.map((containedResource, index) => {
+            const containedMetaClaims = (containedResource?.meta?.claims);
+            const containedClaims = containedMetaClaims && typeof containedMetaClaims === 'object' && !Array.isArray(containedMetaClaims)
+                ? ensureClaimsIdentifier({ ...containedMetaClaims }, containedResource)
+                : ensureClaimsIdentifier(convertFhirResourceToClaims(containedResource, context), containedResource);
+            const containedResourceType = asTrimmedString(containedResource.resourceType);
+            const containedFlagClaimKey = resolveContainedFlagClaimKey(containedResourceType);
+            const containedParentReferenceClaimKey = resolveContainedParentReferenceClaimKey(containedResourceType);
+            return {
+                ...containedClaims,
+                ...(containedFlagClaimKey ? { [containedFlagClaimKey]: true } : {}),
+                ...(containedParentReferenceClaimKey ? { [containedParentReferenceClaimKey]: resourceReference } : {}),
+                ...(asTrimmedString(containedResource.id) ? {} : {
+                    [`${containedResource.resourceType}.identifier`]: `${resourceReference}#contained-${index + 1}`,
+                }),
+            };
+        });
+        const containedReferences = containedResources
+            .map((containedResource, index) => {
+            const containedType = asTrimmedString(containedResource.resourceType);
+            const containedId = asTrimmedString(containedResource.id) || `${resourceReference}#contained-${index + 1}`;
+            if (!containedType || !containedId) {
+                return '';
+            }
+            return `${containedType}/${containedId}`;
+        })
+            .filter(Boolean);
+        return [
+            mergeContainedResourceReferenceList(baseClaims, containedReferences),
+            ...containedClaimsList,
+        ];
     });
 }
 export function resolveClaimsSectionList(claims) {
@@ -202,9 +280,17 @@ export function resolveClaimsSectionList(claims) {
     return Array.from(new Set(values));
 }
 export function buildBundleDocumentFromClaims(input) {
-    const compositionType = asTrimmedString(input.compositionType) || 'http://loinc.org|60591-5';
+    const compositionClaims = { ...(input.compositionClaims || {}) };
+    const compositionType = asTrimmedString(input.compositionType || compositionClaims[CompositionClaim.Type]) || 'http://loinc.org|60591-5';
+    const compositionSubject = asTrimmedString(input.subjectDid || compositionClaims[CompositionClaim.Subject]);
+    const compositionIdentifier = asTrimmedString(compositionClaims[CompositionClaim.Identifier]);
+    const compositionTitle = asTrimmedString(compositionClaims[CompositionClaim.Title]);
+    const compositionDate = asTrimmedString(compositionClaims[CompositionClaim.Date]);
+    const compositionAuthorList = splitCsv(compositionClaims[CompositionClaim.Author]);
     const compositionSections = new Map();
-    const entries = [];
+    const visibleEntries = [];
+    const resourceByReference = new Map();
+    const containedChildrenByParentReference = new Map();
     input.claimsList.forEach((claims, index) => {
         const resource = convertClaimsToFhirResource(claims);
         resource.meta = {
@@ -212,8 +298,23 @@ export function buildBundleDocumentFromClaims(input) {
             claims: { ...claims },
         };
         ensureResourceIdentifier(resource, claims, index);
-        entries.push({ resource });
-        const resourceRef = `${resource.resourceType}/${resource.id}`;
+        const resourceReference = `${resource.resourceType}/${asTrimmedString(resource.id)}`;
+        const containedFlagClaimKey = resolveContainedFlagClaimKey(resource.resourceType);
+        const containedParentReferenceClaimKey = resolveContainedParentReferenceClaimKey(resource.resourceType);
+        const isContained = containedFlagClaimKey
+            ? (claims[containedFlagClaimKey] === true || claims[containedFlagClaimKey] === 'true')
+            : false;
+        const containedParentReference = containedParentReferenceClaimKey
+            ? asTrimmedString(claims[containedParentReferenceClaimKey])
+            : '';
+        if (isContained && containedParentReference) {
+            const currentChildren = containedChildrenByParentReference.get(containedParentReference) || [];
+            containedChildrenByParentReference.set(containedParentReference, [...currentChildren, resource]);
+            return;
+        }
+        visibleEntries.push({ resource });
+        resourceByReference.set(resourceReference, resource);
+        const resourceRef = resourceReference;
         resolveClaimsSectionList(claims).forEach((sectionValue) => {
             const normalizedSection = asTrimmedString(sectionValue);
             if (!normalizedSection)
@@ -230,6 +331,13 @@ export function buildBundleDocumentFromClaims(input) {
             compositionSections.set(normalizedSection, section);
         });
     });
+    containedChildrenByParentReference.forEach((children, parentReference) => {
+        const parent = resourceByReference.get(parentReference);
+        if (!parent) {
+            return;
+        }
+        parent.contained = [...(Array.isArray(parent.contained) ? parent.contained : []), ...children];
+    });
     const [compositionSystem, compositionCode] = compositionType.split('|');
     return {
         resourceType: ResourceTypesFhirR4.Bundle,
@@ -238,8 +346,14 @@ export function buildBundleDocumentFromClaims(input) {
             {
                 resource: {
                     resourceType: ResourceTypesFhirR4.Composition,
+                    ...(compositionIdentifier ? { id: compositionIdentifier } : {}),
                     status: 'final',
-                    subject: input.subjectDid ? { reference: input.subjectDid } : undefined,
+                    ...(compositionIdentifier ? {
+                        identifier: [{ value: compositionIdentifier }],
+                    } : {}),
+                    ...(compositionSubject ? {
+                        subject: { reference: compositionSubject },
+                    } : {}),
                     type: {
                         coding: [
                             compositionCode
@@ -247,18 +361,24 @@ export function buildBundleDocumentFromClaims(input) {
                                 : { code: compositionSystem },
                         ],
                     },
+                    ...(compositionTitle ? { title: compositionTitle } : {}),
+                    ...(compositionDate ? { date: compositionDate } : {}),
+                    ...(compositionAuthorList.length > 0 ? {
+                        author: compositionAuthorList.map((reference) => ({ reference })),
+                    } : {}),
+                    meta: { claims: compositionClaims },
                     section: Array.from(compositionSections.values()),
                 },
             },
-            ...(input.subjectDid
+            ...(compositionSubject
                 ? [{
                         resource: {
                             resourceType: 'Patient',
-                            id: input.subjectDid,
+                            id: compositionSubject,
                         },
                     }]
                 : []),
-            ...entries,
+            ...visibleEntries,
         ],
     };
 }

package/dist/utils/bundle-editor-core.d.ts

@@ -0,0 +1,181 @@
+import type { BundleEntry, BundleJsonApi } from '../models/bundle';
+import { AllowedResourceType, BundleType, type BuiltBundleEntry, type BundleOperation, type ResourceTypeEntryEditor } from '../models/bundle-editor-types';
+import { type ValidateBundleDocumentResult } from './bundle-document-builder';
+import { buildEmployeePurgeBundle, buildEmployeeSearchBundle } from './employee';
+import { BundleEntryEditor } from './bundle-entry-editor';
+export declare class BundleEditor {
+    private bundleOperation;
+    private allowedResourceType;
+    private bundleType;
+    private compositionClaims;
+    private readonly entries;
+    /**
+     * Declares which business action this in-memory bundle is staging.
+     *
+     * Important distinction:
+     * - this is **not** the same concept as FHIR `Bundle.entry.request.method`
+     * - this is the higher-level action the editor is helping to assemble, for
+     *   example `create`, `search`, `disable`, or `purge`
+     * - the lower-level transport/request method may later be derived from that
+     *   action, and may differ by backend contract
+     *
+     * Example:
+     * - bundle operation `disable`
+     * - current employee GW contract -> inner `entry.request.method = DELETE`
+     * - current individual organization GW contract -> explicit `/_disable`
+     *   route with inner `entry.request.method = POST`
+     */
+    setBundleOperation(operation: BundleOperation): this;
+    /**
+     * Returns the current high-level business action assigned to the bundle.
+     *
+     * Read this as:
+     * - "what am I trying to do?"
+     *
+     * not as:
+     * - "which HTTP/FHIR request method will the final entry use?"
+     */
+    getBundleOperation(): BundleOperation | null;
+    /**
+     * Restricts the bundle to one resource type.
+     *
+     * For employee batch bundles this should be fixed to
+     * `EmployeeResourceTypes.employee` so the editor cannot mix unrelated
+     * resource kinds.
+     */
+    setAllowedResourceType(resourceType: AllowedResourceType): this;
+    /** Returns the bundle resource type restriction when already declared. */
+    getAllowedResourceType(): AllowedResourceType | null;
+    /** Declares which FHIR bundle shape the editor should materialize. */
+    setBundleType(type: BundleType): this;
+    /** Returns the declared target bundle shape. */
+    getBundleType(): BundleType;
+    setCompositionIdentifier(identifier?: string | null): this;
+    /** Returns the normalized `Composition.identifier` staged for the future document root. */
+    getCompositionIdentifier(): string | undefined;
+    setCompositionSubject(subject?: string | null): this;
+    /** Returns the normalized `Composition.subject` staged for the future document root. */
+    getCompositionSubject(): string | undefined;
+    setCompositionType(type?: string | null): this;
+    /** Returns the normalized `Composition.type` staged for the future document root. */
+    getCompositionType(): string | undefined;
+    setCompositionTitle(title?: string | null): this;
+    /** Returns the normalized `Composition.title` staged for the future document root. */
+    getCompositionTitle(): string | undefined;
+    setCompositionDate(date?: string | null): this;
+    /** Returns the normalized `Composition.date` staged for the future document root. */
+    getCompositionDate(): string | undefined;
+    setCompositionAuthorList(references: readonly string[]): this;
+    /** Returns the normalized `Composition.author` reference list staged for the future document root. */
+    getCompositionAuthorList(): string[];
+    /**
+     * Opens one new entry and returns a generic entry editor for that slot.
+     *
+     * The entry editor can later expose resource-specific semantics through
+     * methods such as `asEmployee()`.
+     */
+    newEntry(resourceId?: string, resourceTypeOverride?: AllowedResourceType): BundleEntryEditor;
+    /** Opens one new entry with an explicit resource type, mainly for document bundles. */
+    newEntryAs<T extends AllowedResourceType>(resourceType: T, resourceId?: string): ResourceTypeEntryEditor<T>;
+    /** Reopens one existing entry by `resource.id` or `fullUrl`. */
+    openEntry(resourceIdOrFullUrl: string): BundleEntryEditor;
+    /** Returns cloned staged entries for inspection or debugging. */
+    getEntries(): readonly BuiltBundleEntry[];
+    /** Returns the current Composition-level claims used when building a document bundle. */
+    getCompositionClaims(): Readonly<Record<string, unknown>>;
+    /**
+     * Validates whether the current editor state is sufficient to build one
+     * clinical `Bundle.type=document`.
+     */
+    validateDocumentAuthoring(): ValidateBundleDocumentResult;
+    /** Builds one Composition-first document bundle from the staged resource entries. */
+    buildDocument(): Record<string, unknown>;
+    /**
+     * Materializes the final bundle payload from the editor state.
+     *
+     * `build()` does not send, sign, or wrap the payload. It only returns the
+     * final bundle object for the declared operation and staged entries.
+     */
+    build(): ReturnType<typeof buildEmployeePurgeBundle> | ReturnType<typeof buildEmployeeSearchBundle> | {
+        resourceType: 'Bundle';
+        type: BundleType;
+        entry: BuiltBundleEntry[];
+    };
+    /**
+     * Materializes the staged entries as the `BundleJsonApi` shape used by
+     * `CommunicationAttachedBundleSession` and `ConsentAccessEditor`.
+     *
+     * Use this when the next layer edits bundle entries in-memory before another
+     * runtime wraps or sends the bundle.
+     */
+    buildJsonApi(): BundleJsonApi<BundleEntry>;
+    /** @internal */
+    getMutableEntry(entryIndex: number): BuiltBundleEntry;
+    /** @internal */
+    removeMutableEntry(entryIndex: number): void;
+    /** @internal */
+    findEntryIndexByIdentifierOrFullUrl(resourceIdOrFullUrl: string): number;
+    /**
+     * Creates the mutable entry state that will later be wrapped by one entry editor.
+     *
+     * The draft seeds bundle-owned defaults such as:
+     * - canonical internal identifier (`resource.id` / `fullUrl`)
+     * - request method derived from the high-level bundle operation
+     * - generic entry type string
+     *
+     * It does not yet imply that the public `<ResourceType>.identifier` claim was
+     * written; the entry editor decides when that claim must be synchronized.
+     */
+    private createEntryDraft;
+    /**
+     * Resolves which resource type one new entry should use.
+     *
+     * Non-document bundles stay homogeneous once an allowed resource type was
+     * declared. Document bundles may stage multiple resource types and therefore
+     * can use the override path repeatedly.
+     */
+    private resolveEntryResourceType;
+    /**
+     * Normalizes one single-entry search bundle into a plain claims object.
+     *
+     * Keep this internal because it is specific to the current search serialization
+     * contract and should not become the public reader/editor story.
+     */
+    private getSingleSearchClaims;
+    /** Returns the declared bundle operation or throws one onboarding-grade error. */
+    private requireBundleOperation;
+    /** Returns the allowed resource type or throws when the editor was not initialized correctly. */
+    private requireAllowedResourceType;
+    /**
+     * Stores one Composition scalar claim in the staged document metadata.
+     *
+     * Callers should use semantic wrappers such as `setCompositionTitle(...)`
+     * instead of touching claim keys directly.
+     */
+    private setCompositionScalarClaim;
+    /**
+     * Reads one normalized Composition scalar claim.
+     *
+     * This internal helper explains the otherwise opaque `getComposition...()`
+     * implementations: they all delegate to the same normalized metadata store.
+     */
+    private getCompositionScalarClaim;
+    /**
+     * Stores one CSV-backed Composition claim list such as `Composition.author`.
+     *
+     * The editor keeps the flattened storage representation internal while the
+     * public API exposes simple `string[]` setters/getters.
+     */
+    private setCompositionCsvClaimList;
+    /** Reads one CSV-backed Composition claim list as a normalized string array. */
+    private getCompositionCsvClaimList;
+}
+/**
+ * Generic editor for one staged bundle entry.
+ *
+ * This class only knows generic entry concerns such as:
+ * - resource id
+ * - fullUrl
+ * - meta claims
+ * - conversion to one resource-specific entry editor
+ */