@metriport/fhir-sdk 1.2.5

package/dist/index.js

@@ -0,0 +1,681 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FhirBundleSdk = void 0;
+const smart_resources_1 = require("./types/smart-resources");
+function getResourceIdentifier(entry) {
+    if (entry.resource?.id) {
+        return entry.resource.id;
+    }
+    if (entry.fullUrl) {
+        return entry.fullUrl;
+    }
+    return undefined;
+}
+/**
+ * FHIR Bundle SDK for parsing, querying, and manipulating FHIR bundles with reference resolution
+ */
+class FhirBundleSdk {
+    constructor(bundle) {
+        this.resourcesById = new Map();
+        this.resourcesByFullUrl = new Map();
+        this.resourcesByType = new Map();
+        // Smart resource caching to maintain object identity
+        this.smartResourceCache = new WeakMap();
+        // Array caching for type-specific getters to maintain reference identity
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.smartResourceArrayCache = new Map();
+        // Circular reference protection
+        this.resolutionStack = new Set();
+        // FR-1.1, FR-1.4: Initialize bundle and create indexes
+        this.bundle = bundle;
+        this.bundle.total = bundle.entry?.length ?? 0;
+        this.buildResourceIndexes();
+    }
+    get total() {
+        if (!this.bundle.entry) {
+            throw new Error("No valid total - bundle property `entry` is undefined");
+        }
+        return this.bundle.entry.length;
+    }
+    get entry() {
+        if (!this.bundle.entry) {
+            console.error("Bundle property `entry` is undefined");
+            return [];
+        }
+        return this.bundle.entry;
+    }
+    toObject() {
+        return this.bundle;
+    }
+    /**
+     * Create a new FhirBundleSdk instance (async for backwards compatibility)
+     * FR-1.2: Validate bundle resourceType
+     */
+    static async create(bundle) {
+        return FhirBundleSdk.createSync(bundle);
+    }
+    /**
+     * Create a new FhirBundleSdk instance synchronously
+     * FR-1.2: Validate bundle resourceType
+     */
+    static createSync(bundle) {
+        // FR-1.2: Validate bundle resourceType
+        if (bundle.resourceType !== "Bundle") {
+            throw new Error("Invalid bundle: resourceType must be 'Bundle'");
+        }
+        return new FhirBundleSdk(bundle);
+    }
+    /**
+     * Build O(1) indexes for resource lookup
+     */
+    buildResourceIndexes() {
+        if (!this.bundle.entry) {
+            return;
+        }
+        for (const entry of this.bundle.entry) {
+            if (!entry.resource) {
+                continue;
+            }
+            const resource = entry.resource;
+            // Index by resource.id if it exists
+            if (resource.id) {
+                this.resourcesById.set(resource.id, resource);
+            }
+            // Index by fullUrl if it exists
+            if (entry.fullUrl) {
+                this.resourcesByFullUrl.set(entry.fullUrl, resource);
+            }
+            // Index by resource type for type-specific getters
+            const resourceType = resource.resourceType;
+            if (!this.resourcesByType.has(resourceType)) {
+                this.resourcesByType.set(resourceType, []);
+            }
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            this.resourcesByType.get(resourceType).push(resource);
+        }
+    }
+    /**
+     * Create a smart resource with reference resolution methods
+     * FR-5.1: Resources returned by SDK have additional getter methods for each Reference field
+     * FR-5.7: Reference resolution operates in O(1) time complexity per reference
+     * FR-5.8: Original reference fields remain unchanged
+     */
+    createSmartResource(resource) {
+        // Check cache first to maintain object identity
+        const cached = this.smartResourceCache.get(resource);
+        if (cached) {
+            return cached;
+        }
+        const smartResource = new Proxy(resource, {
+            get: (target, prop, receiver) => {
+                // Handle the smart resource marker
+                if (prop === "__isSmartResource") {
+                    return true;
+                }
+                // Check if this is a reference method call
+                if (typeof prop === "string" && (0, smart_resources_1.isReferenceMethod)(prop, target.resourceType)) {
+                    return () => this.resolveReference(prop, target);
+                }
+                // Return original property
+                return Reflect.get(target, prop, receiver);
+            },
+            // Ensure JSON serialization works correctly (FR-5.8)
+            ownKeys: target => {
+                return Reflect.ownKeys(target).filter(key => key !== "__isSmartResource");
+            },
+            getOwnPropertyDescriptor: (target, prop) => {
+                if (prop === "__isSmartResource") {
+                    return undefined;
+                }
+                return Reflect.getOwnPropertyDescriptor(target, prop);
+            },
+        });
+        // Cache the smart resource
+        this.smartResourceCache.set(resource, smartResource);
+        return smartResource;
+    }
+    /**
+     * Resolve a reference method call to actual resources
+     * FR-5.2-5.6: Handle different reference types and patterns
+     */
+    resolveReference(methodName, resource) {
+        const referenceField = (0, smart_resources_1.getReferenceField)(methodName, resource.resourceType);
+        if (!referenceField) {
+            return undefined;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const referenceValue = resource[referenceField];
+        if (!referenceValue) {
+            // FR-5.6: Return appropriate empty value for missing references
+            return this.isArrayReferenceField(referenceField, resource.resourceType) ? [] : undefined;
+        }
+        // Handle array references
+        if (Array.isArray(referenceValue)) {
+            const resolvedResources = [];
+            for (const ref of referenceValue) {
+                const resolved = this.resolveReferenceObject(ref);
+                if (resolved) {
+                    resolvedResources.push(this.createSmartResource(resolved));
+                }
+            }
+            return resolvedResources;
+        }
+        // Handle single reference - we know it's not an array at this point
+        const resolved = this.resolveReferenceObject(referenceValue);
+        if (resolved) {
+            // Type assertion is safe here because we've established this is the single reference path
+            return this.createSmartResource(resolved);
+        }
+        return undefined;
+    }
+    /**
+     * Resolve a single reference object to a resource
+     * FR-5.5: Reference resolution methods handle both resource.id and fullUrl matching
+     */
+    resolveReferenceObject(referenceObj) {
+        if (!referenceObj || typeof referenceObj !== "object" || !("reference" in referenceObj)) {
+            return undefined;
+        }
+        const reference = referenceObj.reference;
+        // Circular reference protection
+        if (this.resolutionStack.has(reference)) {
+            return undefined;
+        }
+        this.resolutionStack.add(reference);
+        try {
+            // Try to resolve by resource ID (e.g., "Patient/123")
+            if (reference.includes("/")) {
+                const [, resourceId] = reference.split("/");
+                if (resourceId && this.resourcesById.has(resourceId)) {
+                    return this.resourcesById.get(resourceId);
+                }
+            }
+            // Try to resolve by fullUrl (e.g., "urn:uuid:123")
+            if (this.resourcesByFullUrl.has(reference)) {
+                return this.resourcesByFullUrl.get(reference);
+            }
+            return undefined;
+        }
+        finally {
+            this.resolutionStack.delete(reference);
+        }
+    }
+    /**
+     * Check if a reference field expects an array of references
+     */
+    isArrayReferenceField(fieldName, resourceType) {
+        // Known array reference fields
+        const arrayFields = new Set(["performer", "participant", "result", "generalPractitioner"]);
+        return arrayFields.has(fieldName);
+    }
+    /**
+     * Find all Reference fields in a resource recursively
+     */
+    findAllReferences(resource) {
+        const references = [];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        function searchObject(obj, path = "") {
+            if (!obj || typeof obj !== "object") {
+                return;
+            }
+            // Check if this object is a Reference
+            if (obj.reference && typeof obj.reference === "string") {
+                references.push({
+                    field: path || "reference",
+                    reference: obj.reference,
+                });
+                return;
+            }
+            // Recursively search object properties
+            for (const [key, value] of Object.entries(obj)) {
+                const currentPath = path ? `${path}.${key}` : key;
+                if (Array.isArray(value)) {
+                    value.forEach((item, index) => {
+                        searchObject(item, `${currentPath}[${index}]`);
+                    });
+                }
+                else if (value && typeof value === "object") {
+                    searchObject(value, currentPath);
+                }
+            }
+        }
+        searchObject(resource);
+        return references;
+    }
+    /**
+     * Check if a reference can be resolved within the bundle
+     */
+    canResolveReference(reference) {
+        // Try to resolve by resource ID (e.g., "Patient/123")
+        if (reference.includes("/")) {
+            const [, resourceId] = reference.split("/");
+            if (resourceId && this.resourcesById.has(resourceId)) {
+                return true;
+            }
+        }
+        // Try to resolve by fullUrl (e.g., "urn:uuid:123")
+        if (this.resourcesByFullUrl.has(reference)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * FR-2.1: Validate all references in the bundle
+     * FR-2.2: Identifies references by Resource/id pattern and fullUrl references
+     * FR-2.3: Handles both relative and absolute references
+     * FR-2.4: Returns validation result with broken reference details
+     */
+    lookForBrokenReferences() {
+        const brokenReferences = [];
+        if (!this.bundle.entry) {
+            return { hasBrokenReferences: false, brokenReferences: [] };
+        }
+        for (const entry of this.bundle.entry) {
+            if (!entry.resource) {
+                continue;
+            }
+            const resource = entry.resource;
+            const resourceReferences = this.findAllReferences(resource);
+            for (const { field, reference } of resourceReferences) {
+                if (!this.canResolveReference(reference)) {
+                    brokenReferences.push({
+                        sourceResourceId: resource.id || entry.fullUrl || "unknown",
+                        sourceResourceType: resource.resourceType,
+                        referenceField: field,
+                        reference: reference,
+                    });
+                }
+            }
+        }
+        return {
+            hasBrokenReferences: brokenReferences.length > 0,
+            brokenReferences: brokenReferences,
+        };
+    }
+    /**
+     * FR-3.1: Get resource by ID with type parameter support
+     * FR-3.2: Method searches both resource.id and entry.fullUrl for matches
+     * FR-3.4: Method returns undefined if resource not found
+     * FR-3.5: Lookup operates in O(1) time complexity
+     * FR-5.1: Returns smart resource with reference resolution methods
+     */
+    getResourceById(id) {
+        // First try to find by resource.id
+        const resourceById = this.resourcesById.get(id);
+        if (resourceById) {
+            return this.createSmartResource(resourceById);
+        }
+        // Then try to find by fullUrl
+        const resourceByFullUrl = this.resourcesByFullUrl.get(id);
+        if (resourceByFullUrl) {
+            return this.createSmartResource(resourceByFullUrl);
+        }
+        // Return undefined if not found (FR-3.4)
+        return undefined;
+    }
+    /**
+     * Generic helper method to get a resource by ID with type validation
+     */
+    getResourceByIdAndType(id, resourceType) {
+        const resource = this.getResourceById(id);
+        if (resource && resource.resourceType === resourceType) {
+            return resource;
+        }
+        return undefined;
+    }
+    /**
+     * Generic helper method to get all resources of a specific type
+     * FR-10.1: Returns references to cached objects, not copies
+     */
+    getResourcesByType(resourceType) {
+        // Check cache first to maintain array reference identity
+        const cached = this.smartResourceArrayCache.get(resourceType);
+        if (cached) {
+            return cached;
+        }
+        const resources = (this.resourcesByType.get(resourceType) || []);
+        const smartResources = resources.map(resource => this.createSmartResource(resource));
+        // Cache the array to maintain reference identity
+        this.smartResourceArrayCache.set(resourceType, smartResources);
+        return smartResources;
+    }
+    /**
+     * Create a new bundle entry from an existing entry, preserving fullUrl
+     */
+    createBundleEntry(originalEntry, resource) {
+        if (originalEntry.fullUrl) {
+            return {
+                fullUrl: originalEntry.fullUrl,
+                resource: resource,
+            };
+        }
+        return {
+            resource: resource,
+        };
+    }
+    /**
+     * Create a new bundle with specified entries, maintaining original metadata
+     */
+    createExportBundle(entries) {
+        const exportBundle = {
+            resourceType: "Bundle",
+            type: this.bundle.type || "collection",
+            total: entries.length,
+            entry: entries,
+        };
+        // Preserve original bundle metadata (FR-6.4)
+        if (this.bundle.id) {
+            exportBundle.id = this.bundle.id;
+        }
+        if (this.bundle.meta) {
+            exportBundle.meta = { ...this.bundle.meta };
+        }
+        if (this.bundle.identifier) {
+            exportBundle.identifier = this.bundle.identifier;
+        }
+        if (this.bundle.timestamp) {
+            exportBundle.timestamp = this.bundle.timestamp;
+        }
+        return exportBundle;
+    }
+    /**
+     * Find original bundle entry for a given resource
+     */
+    findOriginalEntry(resource) {
+        if (!this.bundle.entry) {
+            return undefined;
+        }
+        return this.bundle.entry.find(entry => entry.resource === resource || (entry.resource?.id && entry.resource.id === resource.id));
+    }
+    /**
+     * FR-6.1: Export subset of resources by their IDs
+     * FR-6.4: Exported bundles maintain original bundle metadata but update total count
+     * FR-6.5: Exported bundles include only resources that exist in the original bundle
+     * FR-6.6: Exported bundles preserve original entry.fullUrl values
+     */
+    exportSubset(resourceIds) {
+        const exportEntries = [];
+        for (const resourceId of resourceIds) {
+            const resource = this.getResourceById(resourceId);
+            if (resource) {
+                const originalEntry = this.findOriginalEntry(resource);
+                if (originalEntry) {
+                    exportEntries.push(this.createBundleEntry(originalEntry, resource));
+                }
+            }
+            // FR-6.5: Silently skip resources that don't exist
+        }
+        return this.createExportBundle(exportEntries);
+    }
+    /**
+     * FR-6.2: Export all resources of a specific type
+     * FR-6.4: Exported bundles maintain original bundle metadata but update total count
+     * FR-6.6: Exported bundles preserve original entry.fullUrl values
+     */
+    exportByType(resourceType) {
+        const resources = this.resourcesByType.get(resourceType) || [];
+        const exportEntries = [];
+        for (const resource of resources) {
+            const originalEntry = this.findOriginalEntry(resource);
+            if (originalEntry) {
+                exportEntries.push(this.createBundleEntry(originalEntry, resource));
+            }
+        }
+        return this.createExportBundle(exportEntries);
+    }
+    /**
+     * FR-6.3: Export all resources of specified types
+     * FR-6.4: Exported bundles maintain original bundle metadata but update total count
+     * FR-6.6: Exported bundles preserve original entry.fullUrl values
+     */
+    exportByTypes(resourceTypes) {
+        const exportEntries = [];
+        for (const resourceType of resourceTypes) {
+            const resources = this.resourcesByType.get(resourceType) || [];
+            for (const resource of resources) {
+                const originalEntry = this.findOriginalEntry(resource);
+                if (originalEntry) {
+                    exportEntries.push(this.createBundleEntry(originalEntry, resource));
+                }
+            }
+        }
+        return this.createExportBundle(exportEntries);
+    }
+    /**
+     * Concatenate entries from another FhirBundleSdk with this bundle
+     * Returns a new bundle with combined entries while preserving original metadata
+     */
+    async concatEntries(otherSdk) {
+        const currentEntries = this.bundle.entry || [];
+        const otherEntries = otherSdk.bundle.entry || [];
+        const combinedEntries = [...currentEntries, ...otherEntries];
+        const resultBundle = this.createExportBundle(combinedEntries);
+        return await FhirBundleSdk.create(resultBundle);
+    }
+    /**
+     * Diff this bundle with another bundle or FhirBundleSdk by comparing resource ids.
+     * Returns three FhirBundleSdk instances: common, baseOnly, parameterOnly.
+     */
+    async diff(other) {
+        const baseBundle = this.bundle;
+        const parameterBundle = other instanceof FhirBundleSdk ? other.bundle : other;
+        const commonEntries = [];
+        const baseOnlyEntries = [];
+        const parameterOnlyEntries = [];
+        // Create maps with resource identifiers (prefer resource.id, fallback to fullUrl)
+        const baseResourceIdentifiers = new Map();
+        const parameterResourceIdentifiers = new Map();
+        // Populate base bundle identifiers
+        for (const entry of baseBundle?.entry ?? []) {
+            const identifier = getResourceIdentifier(entry);
+            if (identifier) {
+                baseResourceIdentifiers.set(identifier, entry);
+            }
+        }
+        // Populate parameter bundle identifiers
+        for (const entry of parameterBundle?.entry ?? []) {
+            const identifier = getResourceIdentifier(entry);
+            if (identifier) {
+                parameterResourceIdentifiers.set(identifier, entry);
+            }
+        }
+        // Find common and base-only resources
+        for (const [identifier, entry] of baseResourceIdentifiers.entries()) {
+            if (parameterResourceIdentifiers.has(identifier)) {
+                commonEntries.push(entry);
+            }
+            else {
+                baseOnlyEntries.push(entry);
+            }
+        }
+        // Find parameter-only resources
+        for (const [identifier, entry] of parameterResourceIdentifiers.entries()) {
+            if (!baseResourceIdentifiers.has(identifier)) {
+                parameterOnlyEntries.push(entry);
+            }
+        }
+        return {
+            common: await FhirBundleSdk.create(this.createExportBundle(commonEntries)),
+            baseOnly: await FhirBundleSdk.create(this.createExportBundle(baseOnlyEntries)),
+            parameterOnly: await FhirBundleSdk.create(this.createExportBundle(parameterOnlyEntries)),
+        };
+    }
+}
+exports.FhirBundleSdk = FhirBundleSdk;
+/**
+ * Configuration for dynamically generated resource getter methods.
+ *
+ * Each entry in this array automatically generates both single and collection getter methods.
+ *
+ * **Example:**
+ * ```typescript
+ * {
+ *   resourceType: 'Patient',
+ *   singleGetterMethodName: 'getPatientById',
+ *   collectionGetterMethodName: 'getPatients'
+ * }
+ * ```
+ *
+ * **Generates the equivalent of:**
+ * ```typescript
+ * // Single resource getter
+ * getPatientById(id: string): Smart<Patient> | undefined {
+ *   return this.getResourceByIdAndType<Patient>(id, 'Patient');
+ * }
+ *
+ * // Collection getter
+ * getPatients(): Smart<Patient>[] {
+ *   return this.getResourcesByType<Patient>('Patient');
+ * }
+ * ```
+ *
+ * **Usage:**
+ * ```typescript
+ * const sdk = await FhirBundleSdk.create(bundle);
+ * const patient = sdk.getPatientById('patient-123'); // Smart<Patient> | undefined
+ * const allPatients = sdk.getPatients(); // Smart<Patient>[]
+ * ```
+ *
+ * To add a new resource type, simply add a new entry to this array and declare
+ * the corresponding method signatures in the class body.
+ */
+FhirBundleSdk.RESOURCE_METHODS = [
+    {
+        resourceType: "Patient",
+        singleGetterMethodName: "getPatientById",
+        collectionGetterMethodName: "getPatients",
+    },
+    {
+        resourceType: "Observation",
+        singleGetterMethodName: "getObservationById",
+        collectionGetterMethodName: "getObservations",
+    },
+    {
+        resourceType: "Encounter",
+        singleGetterMethodName: "getEncounterById",
+        collectionGetterMethodName: "getEncounters",
+    },
+    {
+        resourceType: "AllergyIntolerance",
+        singleGetterMethodName: "getAllergyIntoleranceById",
+        collectionGetterMethodName: "getAllergyIntolerances",
+    },
+    {
+        resourceType: "Condition",
+        singleGetterMethodName: "getConditionById",
+        collectionGetterMethodName: "getConditions",
+    },
+    {
+        resourceType: "Organization",
+        singleGetterMethodName: "getOrganizationById",
+        collectionGetterMethodName: "getOrganizations",
+    },
+    {
+        resourceType: "Location",
+        singleGetterMethodName: "getLocationById",
+        collectionGetterMethodName: "getLocations",
+    },
+    {
+        resourceType: "Practitioner",
+        singleGetterMethodName: "getPractitionerById",
+        collectionGetterMethodName: "getPractitioners",
+    },
+    {
+        resourceType: "DiagnosticReport",
+        singleGetterMethodName: "getDiagnosticReportById",
+        collectionGetterMethodName: "getDiagnosticReports",
+    },
+    {
+        resourceType: "Composition",
+        singleGetterMethodName: "getCompositionById",
+        collectionGetterMethodName: "getCompositions",
+    },
+    {
+        resourceType: "Coverage",
+        singleGetterMethodName: "getCoverageById",
+        collectionGetterMethodName: "getCoverages",
+    },
+    {
+        resourceType: "DocumentReference",
+        singleGetterMethodName: "getDocumentReferenceById",
+        collectionGetterMethodName: "getDocumentReferences",
+    },
+    {
+        resourceType: "Immunization",
+        singleGetterMethodName: "getImmunizationById",
+        collectionGetterMethodName: "getImmunizations",
+    },
+    {
+        resourceType: "Medication",
+        singleGetterMethodName: "getMedicationById",
+        collectionGetterMethodName: "getMedications",
+    },
+    {
+        resourceType: "MedicationRequest",
+        singleGetterMethodName: "getMedicationRequestById",
+        collectionGetterMethodName: "getMedicationRequests",
+    },
+    {
+        resourceType: "Procedure",
+        singleGetterMethodName: "getProcedureById",
+        collectionGetterMethodName: "getProcedures",
+    },
+    {
+        resourceType: "FamilyMemberHistory",
+        singleGetterMethodName: "getFamilyMemberHistoryById",
+        collectionGetterMethodName: "getFamilyMemberHistories",
+    },
+    {
+        resourceType: "MedicationAdministration",
+        singleGetterMethodName: "getMedicationAdministrationById",
+        collectionGetterMethodName: "getMedicationAdministrations",
+    },
+    {
+        resourceType: "MedicationDispense",
+        singleGetterMethodName: "getMedicationDispenseById",
+        collectionGetterMethodName: "getMedicationDispenses",
+    },
+    {
+        resourceType: "MedicationStatement",
+        singleGetterMethodName: "getMedicationStatementById",
+        collectionGetterMethodName: "getMedicationStatements",
+    },
+    {
+        resourceType: "RelatedPerson",
+        singleGetterMethodName: "getRelatedPersonById",
+        collectionGetterMethodName: "getRelatedPersons",
+    },
+    {
+        resourceType: "RiskAssessment",
+        singleGetterMethodName: "getRiskAssessmentById",
+        collectionGetterMethodName: "getRiskAssessments",
+    },
+    {
+        resourceType: "ServiceRequest",
+        singleGetterMethodName: "getServiceRequestById",
+        collectionGetterMethodName: "getServiceRequests",
+    },
+];
+// Static initialization block to generate methods
+(() => {
+    // Generate both single and collection getter methods from unified configuration
+    for (const { resourceType, singleGetterMethodName, collectionGetterMethodName, } of FhirBundleSdk.RESOURCE_METHODS) {
+        // Generate single resource getter (e.g., getPatientById)
+        Object.defineProperty(FhirBundleSdk.prototype, singleGetterMethodName, {
+            value: function (id) {
+                return this.getResourceByIdAndType(id, resourceType);
+            },
+            writable: false,
+            configurable: false,
+        });
+        // Generate collection getter (e.g., getPatients)
+        Object.defineProperty(FhirBundleSdk.prototype, collectionGetterMethodName, {
+            value: function () {
+                return this.getResourcesByType(resourceType);
+            },
+            writable: false,
+            configurable: false,
+        });
+    }
+})();
+//# sourceMappingURL=index.js.map