gdc-common-utils-ts 2.1.0 → 2.2.2

package/dist/utils/bundle-editor-core.js

@@ -0,0 +1,467 @@
+/**
+ * File discipline note:
+ * - Read `ARCHITECTURE.md` and `CONTRIBUTING.md` before changing this module.
+ * - This file owns only bundle-level orchestration for `BundleEditor`.
+ * - Shared helper logic belongs in `bundle-editor-helpers.ts`.
+ * - Entry/resource-specific behavior belongs in dedicated `*-entry-editor.ts`
+ *   modules, one exported class per file.
+ */
+import { ClaimsPersonSchemaorg } from '../constants/schemaorg.js';
+import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { BundleEditorValidationIssues, BundleTypes, } from '../models/bundle-editor-types.js';
+import { CompositionClaim } from '../models/interoperable-claims/composition-claims.js';
+import { getClaimValues, setClaimValues } from '../claims/claim-list-helpers.js';
+import { buildBundleDocumentFromClaims } from './bundle-document-builder.js';
+import { buildEmployeeBatchEntry, buildEmployeePurgeBundle, buildEmployeeSearchBundle, EmployeeBundleOperations, EmployeeResourceTypes, } from './employee.js';
+import { BundleEntryEditor } from './bundle-entry-editor.js';
+import { cloneEntry, createCanonicalIdentifierUrn, inferGenericEntryType, normalizeOptionalIdentifier, resolveEntryTypeForOperation, resolveRequestMethodForOperation, } from './bundle-editor-helpers.js';
+export class BundleEditor {
+    bundleOperation = null;
+    allowedResourceType = null;
+    bundleType = BundleTypes.batch;
+    compositionClaims = {};
+    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) {
+        this.bundleOperation = operation;
+        return 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() {
+        return this.bundleOperation;
+    }
+    /**
+     * 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) {
+        this.allowedResourceType = resourceType;
+        return this;
+    }
+    /** Returns the bundle resource type restriction when already declared. */
+    getAllowedResourceType() {
+        return this.allowedResourceType;
+    }
+    /** Declares which FHIR bundle shape the editor should materialize. */
+    setBundleType(type) {
+        this.bundleType = type;
+        return this;
+    }
+    /** Returns the declared target bundle shape. */
+    getBundleType() {
+        return this.bundleType;
+    }
+    setCompositionIdentifier(identifier) {
+        return this.setCompositionScalarClaim(CompositionClaim.Identifier, identifier);
+    }
+    /** Returns the normalized `Composition.identifier` staged for the future document root. */
+    getCompositionIdentifier() {
+        return this.getCompositionScalarClaim(CompositionClaim.Identifier);
+    }
+    setCompositionSubject(subject) {
+        return this.setCompositionScalarClaim(CompositionClaim.Subject, subject);
+    }
+    /** Returns the normalized `Composition.subject` staged for the future document root. */
+    getCompositionSubject() {
+        return this.getCompositionScalarClaim(CompositionClaim.Subject);
+    }
+    setCompositionType(type) {
+        return this.setCompositionScalarClaim(CompositionClaim.Type, type);
+    }
+    /** Returns the normalized `Composition.type` staged for the future document root. */
+    getCompositionType() {
+        return this.getCompositionScalarClaim(CompositionClaim.Type);
+    }
+    setCompositionTitle(title) {
+        return this.setCompositionScalarClaim(CompositionClaim.Title, title);
+    }
+    /** Returns the normalized `Composition.title` staged for the future document root. */
+    getCompositionTitle() {
+        return this.getCompositionScalarClaim(CompositionClaim.Title);
+    }
+    setCompositionDate(date) {
+        return this.setCompositionScalarClaim(CompositionClaim.Date, date);
+    }
+    /** Returns the normalized `Composition.date` staged for the future document root. */
+    getCompositionDate() {
+        return this.getCompositionScalarClaim(CompositionClaim.Date);
+    }
+    setCompositionAuthorList(references) {
+        return this.setCompositionCsvClaimList(CompositionClaim.Author, references);
+    }
+    /** Returns the normalized `Composition.author` reference list staged for the future document root. */
+    getCompositionAuthorList() {
+        return this.getCompositionCsvClaimList(CompositionClaim.Author);
+    }
+    /**
+     * 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, resourceTypeOverride) {
+        const operation = this.requireBundleOperation();
+        const resourceType = this.resolveEntryResourceType(resourceTypeOverride);
+        const entry = this.createEntryDraft(operation, resourceType, resourceId);
+        this.entries.push(entry);
+        return new BundleEntryEditor(this, this.entries.length - 1);
+    }
+    /** Opens one new entry with an explicit resource type, mainly for document bundles. */
+    newEntryAs(resourceType, resourceId) {
+        return this.newEntry(resourceId, resourceType).asResourceType(resourceType);
+    }
+    /** Reopens one existing entry by `resource.id` or `fullUrl`. */
+    openEntry(resourceIdOrFullUrl) {
+        const normalizedIdentifier = normalizeOptionalIdentifier(resourceIdOrFullUrl);
+        if (!normalizedIdentifier) {
+            throw new Error('openEntry requires a non-empty resource identifier or fullUrl.');
+        }
+        const entryIndex = this.entries.findIndex((entry) => {
+            return normalizeOptionalIdentifier(entry.resource?.id) === normalizedIdentifier
+                || normalizeOptionalIdentifier(entry.fullUrl) === normalizedIdentifier;
+        });
+        if (entryIndex < 0) {
+            throw new Error(`openEntry could not find resource identifier or fullUrl: ${normalizedIdentifier}`);
+        }
+        return new BundleEntryEditor(this, entryIndex);
+    }
+    /** Returns cloned staged entries for inspection or debugging. */
+    getEntries() {
+        return this.entries.map((entry) => cloneEntry(entry));
+    }
+    /** Returns the current Composition-level claims used when building a document bundle. */
+    getCompositionClaims() {
+        return { ...this.compositionClaims };
+    }
+    /**
+     * Validates whether the current editor state is sufficient to build one
+     * clinical `Bundle.type=document`.
+     */
+    validateDocumentAuthoring() {
+        const issues = [];
+        if (this.bundleType !== BundleTypes.document) {
+            issues.push(BundleEditorValidationIssues.DocumentModeRequired);
+        }
+        if (!this.getCompositionSubject()) {
+            issues.push(BundleEditorValidationIssues.CompositionSubjectRequired);
+        }
+        if (!this.getCompositionType()) {
+            issues.push(BundleEditorValidationIssues.CompositionTypeRequired);
+        }
+        if (!this.getCompositionTitle()) {
+            issues.push(BundleEditorValidationIssues.CompositionTitleRequired);
+        }
+        if (!this.getCompositionDate()) {
+            issues.push(BundleEditorValidationIssues.CompositionDateRequired);
+        }
+        if (this.getCompositionAuthorList().length === 0) {
+            issues.push(BundleEditorValidationIssues.CompositionAuthorRequired);
+        }
+        if (this.entries.length === 0) {
+            issues.push(BundleEditorValidationIssues.DocumentEntryRequired);
+        }
+        return {
+            ok: issues.length === 0,
+            issues,
+        };
+    }
+    /** Builds one Composition-first document bundle from the staged resource entries. */
+    buildDocument() {
+        const validation = this.validateDocumentAuthoring();
+        if (!validation.ok) {
+            throw new Error(`BundleEditor cannot build document: ${validation.issues.join(' ')}`);
+        }
+        return buildBundleDocumentFromClaims({
+            claimsList: this.entries.map((entry) => ({ ...(entry.resource?.meta?.claims || {}) })),
+            subjectDid: this.getCompositionSubject(),
+            compositionType: this.getCompositionType(),
+            compositionClaims: this.getCompositionClaims(),
+        });
+    }
+    /**
+     * 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() {
+        if (this.bundleType === BundleTypes.document) {
+            return this.buildDocument();
+        }
+        const operation = this.requireBundleOperation();
+        const resourceType = this.requireAllowedResourceType();
+        if (operation === EmployeeBundleOperations.search) {
+            if (resourceType !== EmployeeResourceTypes.employee) {
+                throw new Error(`BundleEditor search currently supports only resource type: ${EmployeeResourceTypes.employee}`);
+            }
+            return buildEmployeeSearchBundle({
+                claims: this.getSingleSearchClaims(),
+                resourceType,
+            });
+        }
+        if (operation === EmployeeBundleOperations.purge) {
+            if (resourceType !== EmployeeResourceTypes.employee) {
+                throw new Error(`BundleEditor purge currently supports only resource type: ${EmployeeResourceTypes.employee}`);
+            }
+            return {
+                resourceType: EmployeeResourceTypes.bundle,
+                type: EmployeeResourceTypes.batch,
+                entry: this.entries.map((entry) => {
+                    const identifier = normalizeOptionalIdentifier(entry.resource?.meta?.claims?.[ClaimsPersonSchemaorg.identifier]
+                        || entry.resource?.id
+                        || entry.fullUrl);
+                    if (!identifier) {
+                        throw new Error('Every purge entry requires one canonical employee identifier.');
+                    }
+                    return buildEmployeePurgeBundle({
+                        identifier,
+                        resourceType,
+                    }).entry[0];
+                }),
+            };
+        }
+        return {
+            resourceType: ResourceTypesFhirR4.Bundle,
+            type: this.bundleType,
+            entry: this.entries.map((entry) => cloneEntry(entry)),
+        };
+    }
+    /**
+     * 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() {
+        return {
+            resourceType: ResourceTypesFhirR4.Bundle,
+            type: this.bundleType,
+            data: this.entries.map((entry) => {
+                const clonedEntry = cloneEntry(entry);
+                const { request: _requestIgnored, ...clonedEntryWithoutRequest } = clonedEntry;
+                const normalizedRequest = clonedEntry.request
+                    ? {
+                        method: clonedEntry.request.method,
+                        url: clonedEntry.request.url || '',
+                    }
+                    : undefined;
+                return normalizedRequest
+                    ? {
+                        ...clonedEntryWithoutRequest,
+                        request: normalizedRequest,
+                    }
+                    : clonedEntryWithoutRequest;
+            }),
+        };
+    }
+    /** @internal */
+    getMutableEntry(entryIndex) {
+        if (!Number.isInteger(entryIndex) || entryIndex < 0 || entryIndex >= this.entries.length) {
+            throw new Error(`BundleEditor could not open entry index: ${entryIndex}`);
+        }
+        return this.entries[entryIndex];
+    }
+    /** @internal */
+    removeMutableEntry(entryIndex) {
+        if (!Number.isInteger(entryIndex) || entryIndex < 0 || entryIndex >= this.entries.length) {
+            throw new Error(`BundleEditor could not remove entry index: ${entryIndex}`);
+        }
+        this.entries.splice(entryIndex, 1);
+    }
+    /** @internal */
+    findEntryIndexByIdentifierOrFullUrl(resourceIdOrFullUrl) {
+        const normalizedIdentifier = normalizeOptionalIdentifier(resourceIdOrFullUrl);
+        if (!normalizedIdentifier) {
+            return -1;
+        }
+        return this.entries.findIndex((entry) => {
+            return normalizeOptionalIdentifier(entry.resource?.id) === normalizedIdentifier
+                || normalizeOptionalIdentifier(entry.fullUrl) === normalizedIdentifier;
+        });
+    }
+    /**
+     * 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.
+     */
+    createEntryDraft(operation, resourceType, resourceId) {
+        const normalizedIdentifier = operation === EmployeeBundleOperations.search
+            ? normalizeOptionalIdentifier(resourceId)
+            : (normalizeOptionalIdentifier(resourceId) || createCanonicalIdentifierUrn());
+        const claims = {
+            '@context': 'org.schema',
+            ...(normalizedIdentifier ? { [ClaimsPersonSchemaorg.identifier]: normalizedIdentifier } : {}),
+        };
+        if (resourceType !== EmployeeResourceTypes.employee) {
+            return {
+                type: inferGenericEntryType(resourceType, operation),
+                request: { method: resolveRequestMethodForOperation(operation) },
+                fullUrl: normalizedIdentifier,
+                resource: {
+                    resourceType,
+                    ...(normalizedIdentifier ? { id: normalizedIdentifier } : {}),
+                    meta: { claims: {} },
+                },
+            };
+        }
+        const entry = buildEmployeeBatchEntry({
+            type: resolveEntryTypeForOperation(operation),
+            method: resolveRequestMethodForOperation(operation),
+            resourceId: normalizedIdentifier,
+            resourceType,
+            claims,
+        });
+        if (normalizedIdentifier) {
+            entry.fullUrl = normalizedIdentifier;
+        }
+        return entry;
+    }
+    /**
+     * 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.
+     */
+    resolveEntryResourceType(resourceTypeOverride) {
+        const explicitResourceType = normalizeOptionalIdentifier(resourceTypeOverride);
+        if (explicitResourceType) {
+            if (this.bundleType !== BundleTypes.document
+                && this.allowedResourceType
+                && explicitResourceType !== this.allowedResourceType) {
+                throw new Error(`BundleEditor cannot mix resource types in ${this.bundleType} mode: ${this.allowedResourceType} vs ${explicitResourceType}`);
+            }
+            return explicitResourceType;
+        }
+        if (!this.allowedResourceType) {
+            throw new Error('BundleEditor requires setAllowedResourceType(...) before newEntry() or build().');
+        }
+        return this.allowedResourceType;
+    }
+    /**
+     * 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.
+     */
+    getSingleSearchClaims() {
+        if (this.entries.length === 0) {
+            return {};
+        }
+        if (this.entries.length > 1) {
+            throw new Error('Search bundles currently support one entry per bundle.');
+        }
+        const claims = this.entries[0].resource?.meta?.claims || {};
+        const searchClaims = {};
+        for (const [key, value] of Object.entries(claims)) {
+            if (value === undefined
+                || value === null
+                || typeof value === 'string'
+                || typeof value === 'number'
+                || typeof value === 'boolean') {
+                searchClaims[key] = value;
+            }
+        }
+        return searchClaims;
+    }
+    /** Returns the declared bundle operation or throws one onboarding-grade error. */
+    requireBundleOperation() {
+        if (!this.bundleOperation) {
+            throw new Error('BundleEditor requires setBundleOperation(...) before newEntry() or build().');
+        }
+        return this.bundleOperation;
+    }
+    /** Returns the allowed resource type or throws when the editor was not initialized correctly. */
+    requireAllowedResourceType() {
+        if (!this.allowedResourceType) {
+            throw new Error('BundleEditor requires setAllowedResourceType(...) before newEntry() or build().');
+        }
+        return this.allowedResourceType;
+    }
+    /**
+     * Stores one Composition scalar claim in the staged document metadata.
+     *
+     * Callers should use semantic wrappers such as `setCompositionTitle(...)`
+     * instead of touching claim keys directly.
+     */
+    setCompositionScalarClaim(claimKey, value) {
+        const normalized = normalizeOptionalIdentifier(value);
+        if (!normalized) {
+            delete this.compositionClaims[claimKey];
+            return this;
+        }
+        this.compositionClaims[claimKey] = normalized;
+        return this;
+    }
+    /**
+     * Reads one normalized Composition scalar claim.
+     *
+     * This internal helper explains the otherwise opaque `getComposition...()`
+     * implementations: they all delegate to the same normalized metadata store.
+     */
+    getCompositionScalarClaim(claimKey) {
+        return normalizeOptionalIdentifier(this.compositionClaims[claimKey]);
+    }
+    /**
+     * 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.
+     */
+    setCompositionCsvClaimList(claimKey, values) {
+        const next = setClaimValues({}, claimKey, values);
+        const normalized = normalizeOptionalIdentifier(next[claimKey]);
+        if (!normalized) {
+            delete this.compositionClaims[claimKey];
+            return this;
+        }
+        this.compositionClaims[claimKey] = normalized;
+        return this;
+    }
+    /** Reads one CSV-backed Composition claim list as a normalized string array. */
+    getCompositionCsvClaimList(claimKey) {
+        return getClaimValues(this.compositionClaims, claimKey);
+    }
+}
+/**
+ * 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
+ */

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

@@ -0,0 +1,53 @@
+import { type BundleRequest } from '../models/bundle';
+import { type BundleOperation } from '../models/bundle-editor-types';
+export declare function cloneEntry<T>(value: T): T;
+/** Clones one claim value while preserving simple arrays used by flat claims. */
+export declare function cloneClaimValue<T>(value: T): T;
+/**
+ * Trims one candidate identifier-like value and returns `undefined` when it is
+ * empty or absent.
+ *
+ * Use this before writing ids, references, `fullUrl`, or flat-claim scalars so
+ * every editor follows the same blank-value rule.
+ */
+export declare function normalizeOptionalIdentifier(value: unknown): string | undefined;
+/** Returns one canonical `urn:uuid:*` identifier for new entry/resource drafts. */
+export declare function createCanonicalIdentifierUrn(): string;
+/**
+ * Maps the editor's high-level business operation to the low-level request
+ * method stored in staged bundle entries.
+ */
+export declare function resolveRequestMethodForOperation(operation: BundleOperation): BundleRequest['method'];
+/**
+ * Resolves the legacy entry `type` string used by employee-oriented batch flows.
+ *
+ * This is not the same concept as `resource.resourceType`.
+ */
+export declare function resolveEntryTypeForOperation(operation: BundleOperation): string;
+/**
+ * Builds the generic entry `type` string for non-employee resource drafts.
+ *
+ * This is one bundle-internal classification token, not a FHIR field.
+ */
+export declare function inferGenericEntryType(resourceType: string, operation: BundleOperation): string;
+/**
+ * Resolves which flat-claims key stores the CSV of linked/contained resource
+ * references for one parent resource type.
+ */
+export declare function resolveContainedReferenceListClaimKey(resourceType: string): string;
+/** Returns the internal visibility-control claim that marks one resource as contained. */
+export declare function resolveContainedFlagClaimKey(resourceType: string): string;
+/** Returns the internal parent-reference claim for one contained child resource. */
+export declare function resolveContainedParentReferenceClaimKey(resourceType: string): string;
+/**
+ * Normalizes one linked-resource reference into both:
+ * - `identifier`: the entry-local id part
+ * - `reference`: the canonical `ResourceType/<id>` string
+ *
+ * This lets the editors accept either a bare id or a full FHIR-style reference
+ * while keeping one normalized shape internally.
+ */
+export declare function normalizeContainedReference(resourceType: string, referenceOrIdentifier: string): {
+    identifier: string;
+    reference: string;
+};

package/dist/utils/bundle-editor-helpers.js

@@ -0,0 +1,146 @@
+/**
+ * File discipline note:
+ * - Read `ARCHITECTURE.md` and `CONTRIBUTING.md` before changing this module.
+ * - Keep only reusable pure helper logic here.
+ * - Do not move entry-specific orchestration back into this file; that belongs
+ *   in the editor classes.
+ */
+import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { AllergyIntoleranceClaim, } from '../models/interoperable-claims/allergy-intolerance-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 { BundleEditableResourceTypes, } from '../models/bundle-editor-types.js';
+import { EmployeeBatchEntryTypes, EmployeeBundleMethods, EmployeeBundleOperations, } from './employee.js';
+export function cloneEntry(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/** Clones one claim value while preserving simple arrays used by flat claims. */
+export function cloneClaimValue(value) {
+    if (Array.isArray(value)) {
+        return [...value];
+    }
+    return value;
+}
+/**
+ * Trims one candidate identifier-like value and returns `undefined` when it is
+ * empty or absent.
+ *
+ * Use this before writing ids, references, `fullUrl`, or flat-claim scalars so
+ * every editor follows the same blank-value rule.
+ */
+export function normalizeOptionalIdentifier(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const normalized = String(value).trim();
+    return normalized ? normalized : undefined;
+}
+/** Returns one canonical `urn:uuid:*` identifier for new entry/resource drafts. */
+export function createCanonicalIdentifierUrn() {
+    const cryptoLike = globalThis;
+    const uuid = typeof cryptoLike.crypto?.randomUUID === 'function'
+        ? cryptoLike.crypto.randomUUID()
+        : `resource-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    return `urn:uuid:${uuid}`;
+}
+/**
+ * Maps the editor's high-level business operation to the low-level request
+ * method stored in staged bundle entries.
+ */
+export function resolveRequestMethodForOperation(operation) {
+    switch (operation) {
+        case EmployeeBundleOperations.disable:
+            return EmployeeBundleMethods.disable;
+        case EmployeeBundleOperations.search:
+        case EmployeeBundleOperations.create:
+        case EmployeeBundleOperations.purge:
+        default:
+            return EmployeeBundleMethods.create;
+    }
+}
+/**
+ * Resolves the legacy entry `type` string used by employee-oriented batch flows.
+ *
+ * This is not the same concept as `resource.resourceType`.
+ */
+export function resolveEntryTypeForOperation(operation) {
+    switch (operation) {
+        case EmployeeBundleOperations.search:
+            return EmployeeBatchEntryTypes.search;
+        case EmployeeBundleOperations.disable:
+            return EmployeeBatchEntryTypes.disable;
+        case EmployeeBundleOperations.purge:
+            return EmployeeBatchEntryTypes.purge;
+        case EmployeeBundleOperations.create:
+        default:
+            return EmployeeBatchEntryTypes.create;
+    }
+}
+/**
+ * Builds the generic entry `type` string for non-employee resource drafts.
+ *
+ * This is one bundle-internal classification token, not a FHIR field.
+ */
+export function inferGenericEntryType(resourceType, operation) {
+    const normalizedResourceType = String(resourceType || '').trim();
+    if (normalizedResourceType === BundleEditableResourceTypes.employee) {
+        return resolveEntryTypeForOperation(operation);
+    }
+    return `${normalizedResourceType}-${operation}-request-v1.0`;
+}
+/**
+ * Resolves which flat-claims key stores the CSV of linked/contained resource
+ * references for one parent resource type.
+ */
+export function resolveContainedReferenceListClaimKey(resourceType) {
+    switch (resourceType) {
+        case ResourceTypesFhirR4.AllergyIntolerance:
+            return AllergyIntoleranceClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.Condition:
+            return ConditionClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.MedicationStatement:
+            return MedicationStatementClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.DiagnosticReport:
+            return DiagnosticReportClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.Consent:
+            return ClaimConsent.containedReferenceList;
+        default:
+            return '';
+    }
+}
+/** Returns the internal visibility-control claim that marks one resource as contained. */
+export function resolveContainedFlagClaimKey(resourceType) {
+    return `${resourceType}.is-contained`;
+}
+/** Returns the internal parent-reference claim for one contained child resource. */
+export function resolveContainedParentReferenceClaimKey(resourceType) {
+    return `${resourceType}.contained-parent-reference`;
+}
+/**
+ * Normalizes one linked-resource reference into both:
+ * - `identifier`: the entry-local id part
+ * - `reference`: the canonical `ResourceType/<id>` string
+ *
+ * This lets the editors accept either a bare id or a full FHIR-style reference
+ * while keeping one normalized shape internally.
+ */
+export function normalizeContainedReference(resourceType, referenceOrIdentifier) {
+    const normalizedValue = normalizeOptionalIdentifier(referenceOrIdentifier);
+    if (!normalizedValue) {
+        return { identifier: '', reference: '' };
+    }
+    const slashIndex = normalizedValue.indexOf('/');
+    if (slashIndex > 0) {
+        const identifier = normalizedValue.slice(slashIndex + 1).trim();
+        return {
+            identifier,
+            reference: `${String(resourceType || '').trim() || normalizedValue.slice(0, slashIndex).trim()}/${identifier}`,
+        };
+    }
+    return {
+        identifier: normalizedValue,
+        reference: `${String(resourceType || '').trim()}/${normalizedValue}`,
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { BundleEditor } from './bundle-editor-core';
+import type { BundleEntryEditor } from './bundle-entry-editor';
+export type BundleEntryEditorConstructor<T extends BundleEntryEditor = BundleEntryEditor> = new (bundleEditor: BundleEditor, entryIndex: number) => T;
+export declare function registerBundleEntryEditor(resourceType: string, ctor: BundleEntryEditorConstructor): void;
+export declare function getBundleEntryEditorConstructor(resourceType: string): BundleEntryEditorConstructor | undefined;
+export declare function createRegisteredBundleEntryEditor<T extends BundleEntryEditor>(resourceType: string, bundleEditor: BundleEditor, entryIndex: number): T;

package/dist/utils/bundle-editor-registry.js

@@ -0,0 +1,14 @@
+const bundleEntryEditorConstructors = new Map();
+export function registerBundleEntryEditor(resourceType, ctor) {
+    bundleEntryEditorConstructors.set(String(resourceType || '').trim(), ctor);
+}
+export function getBundleEntryEditorConstructor(resourceType) {
+    return bundleEntryEditorConstructors.get(String(resourceType || '').trim());
+}
+export function createRegisteredBundleEntryEditor(resourceType, bundleEditor, entryIndex) {
+    const ctor = getBundleEntryEditorConstructor(resourceType);
+    if (!ctor) {
+        throw new Error('BundleEntryEditor has not registered a constructor for resource type: ' + String(resourceType || '').trim());
+    }
+    return new ctor(bundleEditor, entryIndex);
+}