@metriport/fhir-sdk 1.2.7 → 1.3.1

package/dist/internal/graph-traversal.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.walkReferences = void 0;
+const smart_resources_1 = require("../types/smart-resources");
+/**
+ * Walk references from a starting resource using BFS traversal.
+ * Discovers all reachable resources up to maxDepth levels.
+ *
+ * @param startResource - The smart resource to start traversal from
+ * @param options - Walk options including maxDepth and includeStartResource
+ * @returns WalkResult containing all discovered resources organized by depth
+ */
+function walkReferences(startResource, options) {
+    const maxDepth = options?.maxDepth ?? Infinity;
+    const includeStartResource = options?.includeStartResource ?? true;
+    const resourcesByDepth = new Map();
+    const visited = new Set();
+    const queue = [];
+    // Initialize with start resource at depth 0
+    queue.push({ resource: startResource, depth: 0 });
+    if (startResource.id) {
+        visited.add(startResource.id);
+    }
+    let maxDepthReached = 0;
+    while (queue.length > 0) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const { resource, depth } = queue.shift();
+        // Track max depth reached
+        if (depth > maxDepthReached) {
+            maxDepthReached = depth;
+        }
+        // Add resource to current depth level
+        if (!resourcesByDepth.has(depth)) {
+            resourcesByDepth.set(depth, []);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        resourcesByDepth.get(depth).push(resource);
+        // Stop if we've reached max depth
+        if (depth >= maxDepth) {
+            continue;
+        }
+        // Get all reference methods for this resource type
+        const referenceMethods = smart_resources_1.REFERENCE_METHOD_MAPPING[resource.resourceType];
+        if (!referenceMethods) {
+            continue;
+        }
+        // Iterate through all reference methods
+        for (const methodName of Object.keys(referenceMethods)) {
+            // Call the reference method
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const referencedResources = resource[methodName]();
+            if (!referencedResources) {
+                continue;
+            }
+            // Handle both single and array references
+            const resourceArray = Array.isArray(referencedResources)
+                ? referencedResources
+                : [referencedResources];
+            for (const referencedResource of resourceArray) {
+                if (!referencedResource?.id) {
+                    continue;
+                }
+                // Skip if already visited
+                if (visited.has(referencedResource.id)) {
+                    continue;
+                }
+                visited.add(referencedResource.id);
+                queue.push({ resource: referencedResource, depth: depth + 1 });
+            }
+        }
+    }
+    // Build flat array of all resources
+    const allResources = [];
+    for (const [depth, resources] of resourcesByDepth.entries()) {
+        // Skip depth 0 (start resource) if includeStartResource is false
+        if (depth === 0 && !includeStartResource) {
+            continue;
+        }
+        allResources.push(...resources);
+    }
+    return {
+        resourcesByDepth,
+        allResources,
+        startResource,
+        depthReached: maxDepthReached,
+    };
+}
+exports.walkReferences = walkReferences;
+//# sourceMappingURL=graph-traversal.js.map

package/dist/internal/graph-traversal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-traversal.js","sourceRoot":"","sources":["../../src/internal/graph-traversal.ts"],"names":[],"mappings":"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"}

package/dist/internal/indexing.d.ts

@@ -0,0 +1,17 @@
+import { Bundle, Resource } from "@medplum/fhirtypes";
+import { ReverseReference } from "../types/sdk-types";
+import { IntervalTree } from "../utils/interval-tree";
+import { DateIndexRecord } from "../types/sdk-types";
+/**
+ * Build O(1) indexes for resource lookup
+ */
+export declare function buildResourceIndexes(bundle: Bundle, resourcesById: Map<string, Resource>, resourcesByFullUrl: Map<string, Resource>, resourcesByType: Map<string, Resource[]>, reverseReferencesById: Map<string, ReverseReference[]>, dateRangeIndex: IntervalTree<DateIndexRecord, number>, resolutionStack: Set<string>): void;
+/**
+ * Build reverse reference index for O(1) reverse lookup
+ */
+export declare function buildReverseReferenceIndex(bundle: Bundle, reverseReferencesById: Map<string, ReverseReference[]>, resourcesByFullUrl: Map<string, Resource>): void;
+/**
+ * Build date range index for O(log n + k) date range searches
+ */
+export declare function buildDateRangeIndex(bundle: Bundle, dateRangeIndex: IntervalTree<DateIndexRecord, number>): void;
+//# sourceMappingURL=indexing.d.ts.map

package/dist/internal/indexing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexing.d.ts","sourceRoot":"","sources":["../../src/internal/indexing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQrD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EACpC,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,EACxC,qBAAqB,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,EACtD,cAAc,EAAE,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,EACrD,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAC3B,IAAI,CAuCN;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,qBAAqB,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,EACtD,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,GACxC,IAAI,CA6DN;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,GACpD,IAAI,CAiBN"}

package/dist/internal/indexing.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDateRangeIndex = exports.buildReverseReferenceIndex = exports.buildResourceIndexes = void 0;
+const reference_utils_1 = require("./reference-utils");
+const date_extraction_1 = require("./date-extraction");
+/**
+ * Build O(1) indexes for resource lookup
+ */
+function buildResourceIndexes(bundle, resourcesById, resourcesByFullUrl, resourcesByType, reverseReferencesById, dateRangeIndex, resolutionStack) {
+    if (!bundle.entry) {
+        return;
+    }
+    for (const entry of bundle.entry) {
+        if (!entry.resource) {
+            continue;
+        }
+        const resource = entry.resource;
+        // Index by resource.id if it exists
+        if (resource.id) {
+            resourcesById.set(resource.id, resource);
+        }
+        // Index by fullUrl if it exists
+        if (entry.fullUrl) {
+            resourcesByFullUrl.set(entry.fullUrl, resource);
+        }
+        // Index by resource type for type-specific getters
+        const resourceType = resource.resourceType;
+        if (!resourcesByType.has(resourceType)) {
+            resourcesByType.set(resourceType, []);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        resourcesByType.get(resourceType).push(resource);
+    }
+    // Build reverse reference index
+    buildReverseReferenceIndex(bundle, reverseReferencesById, resourcesByFullUrl);
+    // Build date range index
+    buildDateRangeIndex(bundle, dateRangeIndex);
+    // Clear resolution stack after index building
+    resolutionStack.clear();
+}
+exports.buildResourceIndexes = buildResourceIndexes;
+/**
+ * Build reverse reference index for O(1) reverse lookup
+ */
+function buildReverseReferenceIndex(bundle, reverseReferencesById, resourcesByFullUrl) {
+    if (!bundle.entry) {
+        return;
+    }
+    for (const entry of bundle.entry) {
+        if (!entry.resource) {
+            continue;
+        }
+        const resource = entry.resource;
+        const sourceResourceId = resource.id ?? entry.fullUrl ?? "unknown";
+        const references = (0, reference_utils_1.findAllReferences)(resource);
+        for (const { field, reference } of references) {
+            // Extract target ID from reference
+            const targetId = (0, reference_utils_1.extractTargetIdFromReference)(reference);
+            if (!targetId) {
+                continue;
+            }
+            // Add to reverse index for both the extracted ID and the full reference
+            const reverseRef = {
+                sourceResourceId,
+                sourceResourceType: resource.resourceType,
+                referenceField: (0, reference_utils_1.normalizeReferenceField)(field),
+            };
+            // Index by extracted resource ID (e.g., "patient-123" from "Patient/patient-123")
+            if (!reverseReferencesById.has(targetId)) {
+                reverseReferencesById.set(targetId, []);
+            }
+            reverseReferencesById.get(targetId)?.push(reverseRef);
+            // Also index by full reference if it's different (e.g., "urn:uuid:patient-123")
+            if (targetId !== reference) {
+                if (!reverseReferencesById.has(reference)) {
+                    reverseReferencesById.set(reference, []);
+                }
+                reverseReferencesById.get(reference)?.push(reverseRef);
+            }
+            // Also try to index by the actual resource ID if we can find it efficiently
+            // Check if this reference can be resolved to a resource with a different ID
+            if (!reference.includes("/")) {
+                // This is likely a fullUrl reference (e.g., "urn:uuid:xxx")
+                // Check if we have a resource with this fullUrl
+                const targetResource = resourcesByFullUrl.get(reference);
+                if (targetResource?.id &&
+                    targetResource.id !== targetId &&
+                    targetResource.id !== reference) {
+                    if (!reverseReferencesById.has(targetResource.id)) {
+                        reverseReferencesById.set(targetResource.id, []);
+                    }
+                    reverseReferencesById.get(targetResource.id)?.push(reverseRef);
+                }
+            }
+        }
+    }
+}
+exports.buildReverseReferenceIndex = buildReverseReferenceIndex;
+/**
+ * Build date range index for O(log n + k) date range searches
+ */
+function buildDateRangeIndex(bundle, dateRangeIndex) {
+    if (!bundle.entry) {
+        return;
+    }
+    for (const entry of bundle.entry) {
+        if (!entry.resource || !entry.resource.id) {
+            continue;
+        }
+        const resource = entry.resource;
+        const dateIntervals = (0, date_extraction_1.extractDateIntervalsFromResource)(resource);
+        for (const interval of dateIntervals) {
+            dateRangeIndex.insert(interval);
+        }
+    }
+}
+exports.buildDateRangeIndex = buildDateRangeIndex;
+//# sourceMappingURL=indexing.js.map

package/dist/internal/indexing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexing.js","sourceRoot":"","sources":["../../src/internal/indexing.ts"],"names":[],"mappings":"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"}

package/dist/internal/llm-context.d.ts

@@ -0,0 +1,39 @@
+import { Resource } from "@medplum/fhirtypes";
+import { Smart } from "../types/smart-resources";
+import { LLMContextOptions, WalkResult } from "../types/sdk-types";
+/**
+ * Strip non-clinical metadata from a FHIR resource to reduce noise for LLM consumption.
+ * Removes: meta, extension, modifierExtension, text
+ * Returns an immutable copy without mutating the original.
+ */
+export declare function stripNonClinicalData<T extends Resource>(resource: T): T;
+/**
+ * Group resources by their resource type
+ */
+export declare function groupResourcesByType(resources: Resource[]): Record<string, Resource[]>;
+/**
+ * Format a single resource as readable text
+ */
+export declare function formatResourceAsText(resource: Resource): string;
+/**
+ * Format resources as structured text for better LLM readability
+ */
+export declare function formatAsStructuredText(resourcesByDepth: Map<number, Resource[]>): string;
+/**
+ * Format resources as JSON with depth annotations
+ */
+export declare function formatAsJSON(resourcesByDepth: Map<number, Resource[]>): string;
+/**
+ * Generate LLM-friendly context from a starting resource and its related resources.
+ * Uses BFS to discover related resources, strips non-clinical data, and formats output.
+ *
+ * @param startResource - The smart resource to start traversal from
+ * @param options - Options for depth, inclusion, and format
+ * @param walkReferencesFn - Function to walk references (passed in to avoid circular dependency)
+ * @returns Formatted string suitable for LLM context
+ */
+export declare function generateLLMContext<T extends Resource>(startResource: Smart<T>, options: LLMContextOptions | undefined, walkReferencesFn: (startResource: Smart<T>, options: {
+    maxDepth: number;
+    includeStartResource: boolean;
+}) => WalkResult<T>): string;
+//# sourceMappingURL=llm-context.d.ts.map

package/dist/internal/llm-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-context.d.ts","sourceRoot":"","sources":["../../src/internal/llm-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,QAAQ,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CA+BvE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAetF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA0C/D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAqCxF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAc9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,QAAQ,EACnD,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,gBAAgB,EAAE,CAChB,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,OAAO,CAAA;CAAE,KACzD,UAAU,CAAC,CAAC,CAAC,GACjB,MAAM,CAoCR"}

package/dist/internal/llm-context.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLLMContext = exports.formatAsJSON = exports.formatAsStructuredText = exports.formatResourceAsText = exports.groupResourcesByType = exports.stripNonClinicalData = void 0;
+/**
+ * Strip non-clinical metadata from a FHIR resource to reduce noise for LLM consumption.
+ * Removes: meta, extension, modifierExtension, text
+ * Returns an immutable copy without mutating the original.
+ */
+function stripNonClinicalData(resource) {
+    function deepCloneAndStrip(obj) {
+        if (obj === null || obj === undefined) {
+            return obj;
+        }
+        if (Array.isArray(obj)) {
+            return obj.map(item => deepCloneAndStrip(item));
+        }
+        if (typeof obj === "object") {
+            const result = {};
+            for (const [key, value] of Object.entries(obj)) {
+                // Skip non-clinical fields
+                if (key === "meta" ||
+                    key === "extension" ||
+                    key === "modifierExtension" ||
+                    key === "text") {
+                    continue;
+                }
+                result[key] = deepCloneAndStrip(value);
+            }
+            return result;
+        }
+        return obj;
+    }
+    return deepCloneAndStrip(resource);
+}
+exports.stripNonClinicalData = stripNonClinicalData;
+/**
+ * Group resources by their resource type
+ */
+function groupResourcesByType(resources) {
+    const grouped = {};
+    for (const resource of resources) {
+        const type = resource.resourceType;
+        if (!grouped[type]) {
+            grouped[type] = [];
+        }
+        const resourceArray = grouped[type];
+        if (resourceArray) {
+            resourceArray.push(resource);
+        }
+    }
+    return grouped;
+}
+exports.groupResourcesByType = groupResourcesByType;
+/**
+ * Format a single resource as readable text
+ */
+function formatResourceAsText(resource) {
+    const lines = [];
+    lines.push(`[Type: ${resource.resourceType}, ID: ${resource.id ?? "unknown"}]`);
+    function formatValue(value, indent = 2) {
+        const prefix = " ".repeat(indent);
+        const result = [];
+        if (value === null || value === undefined) {
+            return [`${prefix}(none)`];
+        }
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                return [`${prefix}[]`];
+            }
+            for (const [index, item] of value.entries()) {
+                result.push(`${prefix}[${index}]:`);
+                result.push(...formatValue(item, indent + 2));
+            }
+            return result;
+        }
+        if (typeof value === "object") {
+            for (const [key, val] of Object.entries(value)) {
+                result.push(`${prefix}${key}:`);
+                result.push(...formatValue(val, indent + 2));
+            }
+            return result;
+        }
+        return [`${prefix}${String(value)}`];
+    }
+    // Format key fields
+    for (const [key, value] of Object.entries(resource)) {
+        if (key === "resourceType" || key === "id")
+            continue; // Already shown in header
+        lines.push(`  ${key}:`);
+        lines.push(...formatValue(value, 4));
+    }
+    return lines.join("\n");
+}
+exports.formatResourceAsText = formatResourceAsText;
+/**
+ * Format resources as structured text for better LLM readability
+ */
+function formatAsStructuredText(resourcesByDepth) {
+    const lines = [];
+    // Primary resource section
+    const primaryResources = resourcesByDepth.get(0) ?? [];
+    if (primaryResources.length > 0) {
+        lines.push("PRIMARY RESOURCE:");
+        lines.push("=".repeat(80));
+        for (const resource of primaryResources) {
+            lines.push(formatResourceAsText(resource));
+            lines.push("");
+        }
+    }
+    // Related resources by depth
+    for (const [depth, resources] of resourcesByDepth.entries()) {
+        if (depth === 0)
+            continue; // Already handled above
+        const depthLabel = depth === 1 ? "DIRECTLY REFERENCED" : `INDIRECTLY REFERENCED (Depth ${depth})`;
+        lines.push(`${depthLabel} RESOURCES:`);
+        lines.push("=".repeat(80));
+        // Group by resource type for better organization
+        const groupedByType = groupResourcesByType(resources);
+        for (const [resourceType, typeResources] of Object.entries(groupedByType)) {
+            lines.push(`\n--- ${resourceType} (${typeResources.length}) ---\n`);
+            for (const resource of typeResources) {
+                lines.push(formatResourceAsText(resource));
+                lines.push("");
+            }
+        }
+    }
+    return lines.join("\n");
+}
+exports.formatAsStructuredText = formatAsStructuredText;
+/**
+ * Format resources as JSON with depth annotations
+ */
+function formatAsJSON(resourcesByDepth) {
+    const relatedResourcesByDepth = {};
+    for (const [depth, resources] of resourcesByDepth.entries()) {
+        if (depth === 0)
+            continue; // Skip primary resource (already at top)
+        relatedResourcesByDepth[`depth_${depth}`] = resources;
+    }
+    const output = {
+        primaryResource: resourcesByDepth.get(0)?.[0],
+        relatedResourcesByDepth,
+    };
+    return JSON.stringify(output, null, 2);
+}
+exports.formatAsJSON = formatAsJSON;
+/**
+ * Generate LLM-friendly context from a starting resource and its related resources.
+ * Uses BFS to discover related resources, strips non-clinical data, and formats output.
+ *
+ * @param startResource - The smart resource to start traversal from
+ * @param options - Options for depth, inclusion, and format
+ * @param walkReferencesFn - Function to walk references (passed in to avoid circular dependency)
+ * @returns Formatted string suitable for LLM context
+ */
+function generateLLMContext(startResource, options, walkReferencesFn) {
+    const maxDepth = options?.maxDepth ?? 2;
+    const includeStartResource = options?.includeStartResource ?? true;
+    const format = options?.format ?? "structured-text";
+    // Walk the reference graph
+    const walkResult = walkReferencesFn(startResource, {
+        maxDepth,
+        includeStartResource,
+    });
+    // Log resource counts for debugging
+    console.log(`[LLM Context] Total resources discovered: ${walkResult.allResources.length}`);
+    for (const [depth, resources] of walkResult.resourcesByDepth.entries()) {
+        console.log(`[LLM Context] Depth ${depth}: ${resources.length} resources`);
+    }
+    // Strip non-clinical data from all resources
+    const cleanedResourcesByDepth = new Map();
+    for (const [depth, resources] of walkResult.resourcesByDepth.entries()) {
+        // Skip depth 0 if includeStartResource is false
+        if (depth === 0 && !includeStartResource) {
+            continue;
+        }
+        cleanedResourcesByDepth.set(depth, resources.map(r => stripNonClinicalData(r)));
+    }
+    // Format based on selected format
+    if (format === "json") {
+        return formatAsJSON(cleanedResourcesByDepth);
+    }
+    else {
+        return formatAsStructuredText(cleanedResourcesByDepth);
+    }
+}
+exports.generateLLMContext = generateLLMContext;
+//# sourceMappingURL=llm-context.js.map

package/dist/internal/llm-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-context.js","sourceRoot":"","sources":["../../src/internal/llm-context.ts"],"names":[],"mappings":"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"}

package/dist/internal/reference-resolution.d.ts

@@ -0,0 +1,25 @@
+import { Resource } from "@medplum/fhirtypes";
+import { Smart } from "../types/smart-resources";
+import { ReverseReferenceOptions } from "../types/sdk-types";
+/**
+ * Check if a reference field expects an array of references
+ */
+export declare function isArrayReferenceField(fieldName: string): boolean;
+/**
+ * Resolve a single reference object to a resource
+ * FR-5.5: Reference resolution methods handle both resource.id and fullUrl matching
+ */
+export declare function resolveReferenceObject(referenceObj: unknown, resourcesById: Map<string, Resource>, resourcesByFullUrl: Map<string, Resource>, resolutionStack: Set<string>): Resource | undefined;
+/**
+ * Resolve a reference method call to actual resources
+ * FR-5.2-5.6: Handle different reference types and patterns
+ */
+export declare function resolveReference(methodName: string, resource: Resource, resourcesById: Map<string, Resource>, resourcesByFullUrl: Map<string, Resource>, resolutionStack: Set<string>, createSmartResourceFn: <T extends Resource>(resource: T) => Smart<T>): Smart<Resource> | Smart<Resource>[] | undefined;
+/**
+ * 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
+ */
+export declare function createSmartResource<T extends Resource>(resource: T, smartResourceCache: WeakMap<Resource, Smart<Resource>>, resourcesById: Map<string, Resource>, resourcesByFullUrl: Map<string, Resource>, resolutionStack: Set<string>, getResourcesReferencingIdFn: (targetId: string, options?: ReverseReferenceOptions) => Smart<Resource>[]): Smart<T>;
+//# sourceMappingURL=reference-resolution.d.ts.map

package/dist/internal/reference-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-resolution.d.ts","sourceRoot":"","sources":["../../src/internal/reference-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAwC,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAIhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,OAAO,EACrB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EACpC,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAC3B,QAAQ,GAAG,SAAS,CAgCtB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EACpC,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,qBAAqB,EAAE,CAAC,CAAC,SAAS,QAAQ,EAAE,QAAQ,EAAE,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,GACnE,KAAK,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,GAAG,SAAS,CA0CjD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,QAAQ,EACpD,QAAQ,EAAE,CAAC,EACX,kBAAkB,EAAE,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,EACtD,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EACpC,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EACzC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,2BAA2B,EAAE,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,uBAAuB,KAC9B,KAAK,CAAC,QAAQ,CAAC,EAAE,GACrB,KAAK,CAAC,CAAC,CAAC,CA+DV"}

package/dist/internal/reference-resolution.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSmartResource = exports.resolveReference = exports.resolveReferenceObject = exports.isArrayReferenceField = void 0;
+const smart_resources_1 = require("../types/smart-resources");
+/**
+ * Check if a reference field expects an array of references
+ */
+function isArrayReferenceField(fieldName) {
+    // Known array reference fields
+    const arrayFields = new Set(["performer", "participant", "result", "generalPractitioner"]);
+    return arrayFields.has(fieldName);
+}
+exports.isArrayReferenceField = isArrayReferenceField;
+/**
+ * Resolve a single reference object to a resource
+ * FR-5.5: Reference resolution methods handle both resource.id and fullUrl matching
+ */
+function resolveReferenceObject(referenceObj, resourcesById, resourcesByFullUrl, resolutionStack) {
+    if (!referenceObj || typeof referenceObj !== "object" || !("reference" in referenceObj)) {
+        return undefined;
+    }
+    const reference = referenceObj.reference;
+    // Circular reference protection
+    if (resolutionStack.has(reference)) {
+        return undefined;
+    }
+    resolutionStack.add(reference);
+    try {
+        // Try to resolve by resource ID (e.g., "Patient/123")
+        if (reference.includes("/")) {
+            const [, resourceId] = reference.split("/");
+            if (resourceId && resourcesById.has(resourceId)) {
+                return resourcesById.get(resourceId);
+            }
+        }
+        // Try to resolve by fullUrl (e.g., "urn:uuid:123")
+        if (resourcesByFullUrl.has(reference)) {
+            return resourcesByFullUrl.get(reference);
+        }
+        return undefined;
+    }
+    finally {
+        resolutionStack.delete(reference);
+    }
+}
+exports.resolveReferenceObject = resolveReferenceObject;
+/**
+ * Resolve a reference method call to actual resources
+ * FR-5.2-5.6: Handle different reference types and patterns
+ */
+function resolveReference(methodName, resource, resourcesById, resourcesByFullUrl, resolutionStack, createSmartResourceFn) {
+    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 isArrayReferenceField(referenceField) ? [] : undefined;
+    }
+    // Handle array references
+    if (Array.isArray(referenceValue)) {
+        const resolvedResources = [];
+        for (const ref of referenceValue) {
+            const resolved = resolveReferenceObject(ref, resourcesById, resourcesByFullUrl, resolutionStack);
+            if (resolved) {
+                resolvedResources.push(createSmartResourceFn(resolved));
+            }
+        }
+        return resolvedResources;
+    }
+    // Handle single reference - we know it's not an array at this point
+    const resolved = resolveReferenceObject(referenceValue, resourcesById, resourcesByFullUrl, resolutionStack);
+    if (resolved) {
+        // Type assertion is safe here because we've established this is the single reference path
+        return createSmartResourceFn(resolved);
+    }
+    return undefined;
+}
+exports.resolveReference = resolveReference;
+/**
+ * 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
+ */
+function createSmartResource(resource, smartResourceCache, resourcesById, resourcesByFullUrl, resolutionStack, getResourcesReferencingIdFn) {
+    // Check cache first to maintain object identity
+    const cached = 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;
+            }
+            // Handle reverse reference method
+            if (prop === "getReferencingResources") {
+                return (options) => {
+                    const resourceId = target.id;
+                    if (!resourceId) {
+                        return [];
+                    }
+                    return getResourcesReferencingIdFn(resourceId, options);
+                };
+            }
+            // Check if this is a reference method call
+            if (typeof prop === "string" && (0, smart_resources_1.isReferenceMethod)(prop, target.resourceType)) {
+                return () => resolveReference(prop, target, resourcesById, resourcesByFullUrl, resolutionStack, res => createSmartResource(res, smartResourceCache, resourcesById, resourcesByFullUrl, resolutionStack, getResourcesReferencingIdFn));
+            }
+            // 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" && key !== "getReferencingResources");
+        },
+        getOwnPropertyDescriptor: (target, prop) => {
+            if (prop === "__isSmartResource" || prop === "getReferencingResources") {
+                return undefined;
+            }
+            return Reflect.getOwnPropertyDescriptor(target, prop);
+        },
+    });
+    // Cache the smart resource
+    smartResourceCache.set(resource, smartResource);
+    return smartResource;
+}
+exports.createSmartResource = createSmartResource;
+//# sourceMappingURL=reference-resolution.js.map