@metriport/fhir-sdk 0.30.0-alpha.1

package/dist/fhir-bundle-sdk.d.ts

@@ -0,0 +1,233 @@
+import { Bundle, BundleEntry, Resource } from "@medplum/fhirtypes";
+import { SmartAllergyIntolerance, SmartCarePlan, SmartComposition, SmartCondition, SmartCoverage, SmartDiagnosticReport, SmartDocumentReference, SmartEncounter, SmartFamilyMemberHistory, SmartImmunization, SmartLocation, SmartMedication, SmartMedicationAdministration, SmartMedicationDispense, SmartMedicationRequest, SmartMedicationStatement, SmartObservation, SmartOrganization, SmartPatient, SmartPractitioner, SmartProcedure, SmartRelatedPerson, SmartRiskAssessment, SmartServiceRequest, ToSmart } from "./types/coding-fields";
+import { Smart } from "./types/smart-resources";
+import { ValidationResult, BundleDiffResult, WalkOptions, LLMContextOptions, WalkResult, ReverseReferenceOptions, DateRangeSearchOptions } from "./types/sdk-types";
+/**
+ * FHIR Bundle SDK for parsing, querying, and manipulating FHIR bundles with reference resolution
+ */
+export declare class FhirBundleSdk {
+    private bundle;
+    private resourcesById;
+    private resourcesByFullUrl;
+    private resourcesByType;
+    private reverseReferencesById;
+    private dateRangeIndex;
+    private smartResourceCache;
+    private smartResourceArrayCache;
+    private resolutionStack;
+    /**
+     * 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.
+     */
+    private static readonly RESOURCE_METHODS;
+    private constructor();
+    get total(): number;
+    get entry(): BundleEntry[];
+    toObject(): Bundle;
+    /**
+     * Strip non-clinical metadata from a FHIR resource to reduce noise for LLM consumption.
+     * Removes: meta, extension, modifierExtension, text, id, identifier, and all reference fields
+     * Returns an immutable copy without mutating the original.
+     */
+    static stripNonClinicalData<T extends Resource>(resource: T): T;
+    /**
+     * Create a new FhirBundleSdk instance (async for backwards compatibility)
+     * FR-1.2: Validate bundle resourceType
+     */
+    static create(bundle: Bundle): Promise<FhirBundleSdk>;
+    /**
+     * Create a new FhirBundleSdk instance synchronously
+     * FR-1.2: Validate bundle resourceType
+     */
+    static createSync(bundle: Bundle): FhirBundleSdk;
+    /**
+     * 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
+     */
+    private createSmartResource;
+    /**
+     * 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(): ValidationResult;
+    /**
+     * 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<T extends Resource>(id: string): ToSmart<T> | undefined;
+    /**
+     * Generic helper method to get a resource by ID with type validation
+     */
+    private getResourceByIdAndType;
+    getPatientById: (id: string) => SmartPatient | undefined;
+    getObservationById: (id: string) => SmartObservation | undefined;
+    getEncounterById: (id: string) => SmartEncounter | undefined;
+    getAllergyIntoleranceById: (id: string) => SmartAllergyIntolerance | undefined;
+    getConditionById: (id: string) => SmartCondition | undefined;
+    getOrganizationById: (id: string) => SmartOrganization | undefined;
+    getLocationById: (id: string) => SmartLocation | undefined;
+    getPractitionerById: (id: string) => SmartPractitioner | undefined;
+    getDiagnosticReportById: (id: string) => SmartDiagnosticReport | undefined;
+    getCompositionById: (id: string) => SmartComposition | undefined;
+    getCoverageById: (id: string) => SmartCoverage | undefined;
+    getDocumentReferenceById: (id: string) => SmartDocumentReference | undefined;
+    getImmunizationById: (id: string) => SmartImmunization | undefined;
+    getMedicationById: (id: string) => SmartMedication | undefined;
+    getMedicationRequestById: (id: string) => SmartMedicationRequest | undefined;
+    getProcedureById: (id: string) => SmartProcedure | undefined;
+    getFamilyMemberHistoryById: (id: string) => SmartFamilyMemberHistory | undefined;
+    getMedicationAdministrationById: (id: string) => SmartMedicationAdministration | undefined;
+    getMedicationDispenseById: (id: string) => SmartMedicationDispense | undefined;
+    getMedicationStatementById: (id: string) => SmartMedicationStatement | undefined;
+    getRelatedPersonById: (id: string) => SmartRelatedPerson | undefined;
+    getRiskAssessmentById: (id: string) => SmartRiskAssessment | undefined;
+    getServiceRequestById: (id: string) => SmartServiceRequest | undefined;
+    getCarePlanById: (id: string) => SmartCarePlan | undefined;
+    /**
+     * Generic helper method to get all resources of a specific type
+     * FR-10.1: Returns references to cached objects, not copies
+     */
+    private getResourcesByType;
+    getPatients: () => SmartPatient[];
+    getObservations: () => SmartObservation[];
+    getEncounters: () => SmartEncounter[];
+    getPractitioners: () => SmartPractitioner[];
+    getDiagnosticReports: () => SmartDiagnosticReport[];
+    getAllergyIntolerances: () => SmartAllergyIntolerance[];
+    getConditions: () => SmartCondition[];
+    getOrganizations: () => SmartOrganization[];
+    getLocations: () => SmartLocation[];
+    getCompositions: () => SmartComposition[];
+    getCoverages: () => SmartCoverage[];
+    getDocumentReferences: () => SmartDocumentReference[];
+    getImmunizations: () => SmartImmunization[];
+    getMedications: () => SmartMedication[];
+    getMedicationRequests: () => SmartMedicationRequest[];
+    getProcedures: () => SmartProcedure[];
+    getFamilyMemberHistories: () => SmartFamilyMemberHistory[];
+    getMedicationAdministrations: () => SmartMedicationAdministration[];
+    getMedicationDispenses: () => SmartMedicationDispense[];
+    getMedicationStatements: () => SmartMedicationStatement[];
+    getRelatedPersons: () => SmartRelatedPerson[];
+    getRiskAssessments: () => SmartRiskAssessment[];
+    getServiceRequests: () => SmartServiceRequest[];
+    getCarePlans: () => SmartCarePlan[];
+    /**
+     * 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: string[]): Bundle;
+    /**
+     * 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: string): Bundle;
+    /**
+     * 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: string[]): Bundle;
+    /**
+     * Concatenate entries from another FhirBundleSdk with this bundle
+     * Returns a new bundle with combined entries while preserving original metadata
+     */
+    concatEntries(otherSdk: FhirBundleSdk): Promise<FhirBundleSdk>;
+    /**
+     * Diff this bundle with another FHIR Bundle by comparing resource ids.
+     * Returns three FhirBundleSdk instances: common, baseOnly, parameterOnly.
+     */
+    diff(other: Bundle): Promise<BundleDiffResult>;
+    /**
+     * Diff this bundle with another FhirBundleSdk by comparing resource ids.
+     * Returns three FhirBundleSdk instances: common, baseOnly, parameterOnly.
+     */
+    diff(other: FhirBundleSdk): Promise<BundleDiffResult>;
+    /**
+     * 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
+     */
+    walkReferences<T extends Resource>(startResource: Smart<T>, options?: WalkOptions): WalkResult<T>;
+    /**
+     * 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
+     * @returns Formatted string suitable for LLM context
+     */
+    generateLLMContext<T extends Resource>(startResource: Smart<T>, options?: LLMContextOptions): string;
+    /**
+     * Get all resources that reference a given resource ID (reverse reference lookup).
+     * Operates in O(1) time complexity.
+     *
+     * @param targetId - The ID of the resource to find references to
+     * @param options - Optional filters for resourceType and referenceField
+     * @returns Array of smart resources that reference the target resource
+     */
+    getResourcesReferencingId<T extends Resource = Resource>(targetId: string, options?: ReverseReferenceOptions): ToSmart<T>[];
+    /**
+     * Get all resources referenced by a given resource (forward reference lookup).
+     * Returns all resources that the given resource points to based on REFERENCE_METHOD_MAPPING.
+     *
+     * @param resource - The smart resource to get references from
+     * @returns Array of smart resources referenced by the given resource
+     */
+    getResourcesReferencedBy<T extends Resource = Resource>(resource: Smart<Resource>): ToSmart<T>[];
+    /**
+     * Search for resources by date range using interval tree.
+     * Operates in O(log n + k) time complexity, where k is the number of matching intervals.
+     *
+     * @param options - Search options including date range and optional filters
+     * @returns Array of smart resources that match the date range criteria
+     */
+    searchByDateRange<T extends Resource = Resource>(options: DateRangeSearchOptions): ToSmart<T>[];
+}
+//# sourceMappingURL=fhir-bundle-sdk.d.ts.map

package/dist/fhir-bundle-sdk.d.ts.map

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