@metriport/fhir-sdk 1.2.7 → 1.3.0

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

@@ -0,0 +1,222 @@
+import { AllergyIntolerance, Bundle, BundleEntry, Composition, Condition, Coverage, DiagnosticReport, DocumentReference, Encounter, FamilyMemberHistory, Immunization, Location, Medication, MedicationAdministration, MedicationDispense, MedicationRequest, MedicationStatement, Observation, Organization, Patient, Practitioner, Procedure, RelatedPerson, Resource, RiskAssessment, ServiceRequest } from "@medplum/fhirtypes";
+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
+     * 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): Smart<T> | undefined;
+    /**
+     * Generic helper method to get a resource by ID with type validation
+     */
+    private getResourceByIdAndType;
+    getPatientById: (id: string) => Smart<Patient> | undefined;
+    getObservationById: (id: string) => Smart<Observation> | undefined;
+    getEncounterById: (id: string) => Smart<Encounter> | undefined;
+    getAllergyIntoleranceById: (id: string) => Smart<AllergyIntolerance> | undefined;
+    getConditionById: (id: string) => Smart<Condition> | undefined;
+    getOrganizationById: (id: string) => Smart<Organization> | undefined;
+    getLocationById: (id: string) => Smart<Location> | undefined;
+    getPractitionerById: (id: string) => Smart<Practitioner> | undefined;
+    getDiagnosticReportById: (id: string) => Smart<DiagnosticReport> | undefined;
+    getCompositionById: (id: string) => Smart<Composition> | undefined;
+    getCoverageById: (id: string) => Smart<Coverage> | undefined;
+    getDocumentReferenceById: (id: string) => Smart<DocumentReference> | undefined;
+    getImmunizationById: (id: string) => Smart<Immunization> | undefined;
+    getMedicationById: (id: string) => Smart<Medication> | undefined;
+    getMedicationRequestById: (id: string) => Smart<MedicationRequest> | undefined;
+    getProcedureById: (id: string) => Smart<Procedure> | undefined;
+    getFamilyMemberHistoryById: (id: string) => Smart<FamilyMemberHistory> | undefined;
+    getMedicationAdministrationById: (id: string) => Smart<MedicationAdministration> | undefined;
+    getMedicationDispenseById: (id: string) => Smart<MedicationDispense> | undefined;
+    getMedicationStatementById: (id: string) => Smart<MedicationStatement> | undefined;
+    getRelatedPersonById: (id: string) => Smart<RelatedPerson> | undefined;
+    getRiskAssessmentById: (id: string) => Smart<RiskAssessment> | undefined;
+    getServiceRequestById: (id: string) => Smart<ServiceRequest> | 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: () => Smart<Patient>[];
+    getObservations: () => Smart<Observation>[];
+    getEncounters: () => Smart<Encounter>[];
+    getPractitioners: () => Smart<Practitioner>[];
+    getDiagnosticReports: () => Smart<DiagnosticReport>[];
+    getAllergyIntolerances: () => Smart<AllergyIntolerance>[];
+    getConditions: () => Smart<Condition>[];
+    getOrganizations: () => Smart<Organization>[];
+    getLocations: () => Smart<Location>[];
+    getCompositions: () => Smart<Composition>[];
+    getCoverages: () => Smart<Coverage>[];
+    getDocumentReferences: () => Smart<DocumentReference>[];
+    getImmunizations: () => Smart<Immunization>[];
+    getMedications: () => Smart<Medication>[];
+    getMedicationRequests: () => Smart<MedicationRequest>[];
+    getProcedures: () => Smart<Procedure>[];
+    getFamilyMemberHistories: () => Smart<FamilyMemberHistory>[];
+    getMedicationAdministrations: () => Smart<MedicationAdministration>[];
+    getMedicationDispenses: () => Smart<MedicationDispense>[];
+    getMedicationStatements: () => Smart<MedicationStatement>[];
+    getRelatedPersons: () => Smart<RelatedPerson>[];
+    getRiskAssessments: () => Smart<RiskAssessment>[];
+    getServiceRequests: () => Smart<ServiceRequest>[];
+    /**
+     * 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): Smart<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): Smart<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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"}