@medplum/fhir-router 5.1.26 → 5.1.28

package/dist/cjs/index.d.ts

@@ -4,6 +4,7 @@ import type { CapabilityStatementRestInteraction } from '@medplum/fhirtypes';
 import type { CapabilityStatementRestResourceInteraction } from '@medplum/fhirtypes';
 import type { Event as Event_2 } from '@medplum/core';
 import { EventTarget as EventTarget_2 } from '@medplum/core';
+import type { IncludeTarget } from '@medplum/core';
 import type { IncomingHttpHeaders } from 'node:http';
 import type { Operation } from '@medplum/core';
 import type { OperationOutcome } from '@medplum/fhirtypes';
@@ -11,6 +12,7 @@ import { OperationOutcomeError } from '@medplum/core';
 import type { Parameters as Parameters_2 } from '@medplum/fhirtypes';
 import type { Reference } from '@medplum/fhirtypes';
 import type { Resource } from '@medplum/fhirtypes';
+import type { ResourceType } from '@medplum/fhirtypes';
 import type { SearchRequest } from '@medplum/core';
 import type { WithId } from '@medplum/core';
 
@@ -73,13 +75,8 @@ export declare class BatchProcessor {
     private readonly req;
     private resolvedIdentities;
     private bundleInfo;
-    private resultEntries;
-    /** Index into `bundleInfo.ordering` of the next entry to process. */
-    private position;
-    /** Indices (into the original bundle) of results produced since the last {@link BatchProcessor.takePendingResults} call. */
-    private pendingIndices;
-    /** Error messages accumulated across processed entries, for the post-batch telemetry event. */
-    private readonly errors;
+    /** The state mutated through processing (and preprocessing) */
+    private state;
     /**
      * Creates a batch processor.
      * @param router - The FHIR router.
@@ -157,7 +154,6 @@ export declare class BatchProcessor {
      * Scans the Bundle in order to ensure entries are processed in the correct sequence,
      * as well as to identify any operations that might require specific handling.
      *
-     * @param results - The array of result entries, to track partial results.
      * @returns The information gathered from scanning the Bundle.
      */
     private preprocessBundle;
@@ -232,11 +228,12 @@ export declare class BatchProcessor {
  */
 export declare function buildBatchResponseBundle(bundleType: Bundle['type'], entryCount: number, results: Record<number, BundleEntry>): Bundle;
 
-export declare type BundlePreprocessInfo = {
+export declare interface BundlePreprocessInfo {
     ordering: number[];
     requiresStrongTransaction: boolean;
     updates: number;
-};
+    resourceTypes: Set<ResourceType>;
+}
 
 export declare function createResourceImpl<T extends Resource>(resourceType: T['resourceType'], resource: T, repo: FhirRepository, options?: CreateResourceOptions): Promise<FhirResponse>;
 
@@ -353,7 +350,7 @@ export declare abstract class FhirRepository {
      * @param patch - The JSONPatch operations.
      * @returns The patched resource.
      */
-    abstract patchResource<T extends Resource>(resourceType: T['resourceType'], id: string, patch: Operation[] | Parameters_2): Promise<WithId<T>>;
+    abstract patchResource<T extends Resource>(resourceType: T['resourceType'], id: string, patch: Operation[] | Parameters_2, options?: UpdateResourceOptions): Promise<WithId<T>>;
     /**
      * Searches for FHIR resources.
      *
@@ -377,10 +374,10 @@ export declare abstract class FhirRepository {
      * Runs a callback function within a transaction.
      *
      * @param callback - The callback function to be run within a transaction.
+     * @param options - The transaction options.
+     * @returns The result of the callback function.
      */
-    abstract withTransaction<TResult>(callback: (txRepo: this) => Promise<TResult>, options?: {
-        serializable?: boolean;
-    }): Promise<TResult>;
+    abstract withTransaction<TResult>(callback: (txRepo: this) => Promise<TResult>, options: TransactionOptions): Promise<TResult>;
     /**
      * Searches for a single FHIR resource.
      *
@@ -461,7 +458,7 @@ export declare abstract class FhirRepository {
      * @returns A promise that resolves when the operation is complete.
      */
     conditionalDelete(search: SearchRequest): Promise<void>;
-    conditionalPatch(search: SearchRequest, patch: Operation[]): Promise<WithId<Resource>>;
+    conditionalPatch(search: SearchRequest, patch: Operation[], options?: UpdateResourceOptions): Promise<WithId<Resource>>;
 }
 
 export declare type FhirRequest = {
@@ -483,7 +480,9 @@ export declare type FhirRequestConfig = {
     transactions?: boolean;
 };
 
-export declare type FhirResponse = [OperationOutcome] | [OperationOutcome, Resource] | [OperationOutcome, Resource, FhirResponseOptions];
+export declare type FhirResponse = [
+OperationOutcome
+] | [OperationOutcome, Resource] | [OperationOutcome, Resource, FhirResponseOptions];
 
 export declare type FhirResponseOptions = {
     contentType?: string;
@@ -510,8 +509,75 @@ export declare class FhirRouter extends EventTarget_2 {
     log(level: string, message: string, data?: Record<string, any>): void;
 }
 
+/**
+ * Gets the extra search entries for the _include and _revinclude parameters.
+ *
+ * The `entries` array is appended to in place.
+ *
+ * @param repo - The FHIR repository.
+ * @param searchRequest - The original search request.
+ * @param resources - The resources returned by the original search.
+ * @param entries - The output bundle entries.
+ * @param options - Optional repository-specific behavior.
+ */
+export declare function getExtraEntries<T extends Resource>(repo: FhirRepository, searchRequest: SearchRequest<T>, resources: T[], entries: BundleEntry[], options?: IncludeOptions): Promise<void>;
+
+/**
+ * Returns bundle entries for the resources that are included in the search result.
+ *
+ * See documentation on _include: https://hl7.org/fhir/R4/search.html#include
+ * @param repo - The repository.
+ * @param include - The include parameter.
+ * @param resources - The base search result resources.
+ * @param options - Optional repository-specific behavior.
+ * @returns The bundle entries for the included resources.
+ */
+export declare function getSearchIncludeEntries(repo: FhirRepository, include: IncludeTarget, resources: Resource[], options?: IncludeOptions): Promise<BundleEntry[]>;
+
+/**
+ * Returns bundle entries for the resources that are reverse included in the search result.
+ *
+ * See documentation on _revinclude: https://hl7.org/fhir/R4/search.html#revinclude
+ * @param repo - The repository.
+ * @param revInclude - The revInclude parameter.
+ * @param resources - The base search result resources.
+ * @param options - Optional repository-specific behavior.
+ * @returns The bundle entries for the reverse included resources.
+ */
+export declare function getSearchRevIncludeEntries(repo: FhirRepository, revInclude: IncludeTarget, resources: Resource[], options?: IncludeOptions): Promise<BundleEntry[]>;
+
 export declare type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 
+export declare interface IncludeOptions {
+    /**
+     * Builds the `Bundle.entry.fullUrl` for an included resource.
+     * When omitted, `fullUrl` is not set on the resulting entries.
+     */
+    readonly fullUrl?: (resourceType: string, id: string) => string;
+    /**
+     * The maximum number of `:iterate` rounds before the search is rejected. Defaults to 5.
+     */
+    readonly maxDepth?: number;
+    /**
+     * The maximum total number of bundle entries before the search is rejected.
+     * Defaults to `DEFAULT_MAX_SEARCH_COUNT`.
+     */
+    readonly maxResults?: number;
+    /**
+     * Executes the sub-searches needed for canonical `_include` and for all `_revinclude` targets.
+     * Defaults to `repo.searchResources()`.
+     */
+    readonly executeSearch?: IncludeSearchFn;
+}
+
+/**
+ * Executes a search on behalf of the include logic.
+ *
+ * The default implementation uses {@link FhirRepository.searchResources}. The server overrides this
+ * to reuse its already-built query pipeline rather than re-entering the public `search()` entry point.
+ */
+export declare type IncludeSearchFn = (searchRequest: SearchRequest) => Promise<WithId<Resource>[]>;
+
 export declare interface LogEvent extends Event_2 {
     message: string;
     data?: Record<string, any>;
@@ -527,16 +593,22 @@ export declare class MemoryRepository extends FhirRepository {
     withSeeding<T>(fn: () => T | Promise<T>): Promise<T>;
     clear(): void;
     setMode(_mode: RepositoryMode): void;
+    private createResourceSync;
     createResource<T extends Resource>(resource: T, options?: CreateResourceOptions, update?: boolean): Promise<WithId<T>>;
     generateId(): string;
     updateResource<T extends Resource>(resource: T, options?: UpdateResourceOptions): Promise<WithId<T>>;
-    patchResource<T extends Resource>(resourceType: T['resourceType'], id: string, patch: Operation[] | Parameters_2): Promise<WithId<T>>;
+    patchResource<T extends Resource>(resourceType: T['resourceType'], id: string, patch: Operation[] | Parameters_2, options?: UpdateResourceOptions): Promise<WithId<T>>;
     readResource<T extends Resource>(resourceType: string, id: string): Promise<T>;
     readReference<T extends Resource>(reference: Reference<T>): Promise<WithId<T>>;
     readReferences<T extends Resource>(references: readonly Reference<T>[]): Promise<(T | OperationOutcomeError)[]>;
     readHistory<T extends Resource>(resourceType: string, id: string): Promise<Bundle<T>>;
     readVersion<T extends Resource>(resourceType: string, id: string, versionId: string): Promise<T>;
+    private searchSync;
     search<T extends Resource>(searchRequest: SearchRequest<T>): Promise<Bundle<WithId<T>>>;
+    conditionalCreate<T extends Resource>(resource: T, search: SearchRequest<T>, options?: CreateResourceOptions): Promise<{
+        resource: WithId<T>;
+        outcome: OperationOutcome;
+    }>;
     searchByReference<T extends Resource>(searchRequest: SearchRequest<T>, referenceField: string, references: string[]): Promise<Record<string, WithId<T>[]>>;
     deleteResource(resourceType: string, id: string): Promise<void>;
     withTransaction<TResult>(callback: (repo: this) => Promise<TResult>): Promise<TResult>;
@@ -571,6 +643,8 @@ export declare const RepositoryMode: {
 
 export declare type RepositoryMode = (typeof RepositoryMode)[keyof typeof RepositoryMode];
 
+declare type ResourceTypeInput = ResourceType | readonly ResourceType[] | ReadonlySet<ResourceType>;
+
 /** @see http://hl7.org/fhir/R4/codesystem-restful-interaction.html */
 export declare type RestInteraction = CapabilityStatementRestInteraction['code'] | CapabilityStatementRestResourceInteraction['code'] | 'operation';
 
@@ -595,6 +669,11 @@ export declare type RouteResult<Handler, Metadata> = {
     data?: Metadata;
 };
 
+export declare interface TransactionOptions {
+    readonly resourceTypes: ResourceTypeInput;
+    readonly serializable?: boolean;
+}
+
 export declare function updateResourceImpl<T extends Resource>(resourceType: T['resourceType'], id: string, resource: T, repo: FhirRepository, options?: UpdateResourceOptions): Promise<FhirResponse>;
 
 export declare type UpdateResourceOptions = {

package/dist/esm/index.d.ts

@@ -4,6 +4,7 @@ import type { CapabilityStatementRestInteraction } from '@medplum/fhirtypes';
 import type { CapabilityStatementRestResourceInteraction } from '@medplum/fhirtypes';
 import type { Event as Event_2 } from '@medplum/core';
 import { EventTarget as EventTarget_2 } from '@medplum/core';
+import type { IncludeTarget } from '@medplum/core';
 import type { IncomingHttpHeaders } from 'node:http';
 import type { Operation } from '@medplum/core';
 import type { OperationOutcome } from '@medplum/fhirtypes';
@@ -11,6 +12,7 @@ import { OperationOutcomeError } from '@medplum/core';
 import type { Parameters as Parameters_2 } from '@medplum/fhirtypes';
 import type { Reference } from '@medplum/fhirtypes';
 import type { Resource } from '@medplum/fhirtypes';
+import type { ResourceType } from '@medplum/fhirtypes';
 import type { SearchRequest } from '@medplum/core';
 import type { WithId } from '@medplum/core';
 
@@ -73,13 +75,8 @@ export declare class BatchProcessor {
     private readonly req;
     private resolvedIdentities;
     private bundleInfo;
-    private resultEntries;
-    /** Index into `bundleInfo.ordering` of the next entry to process. */
-    private position;
-    /** Indices (into the original bundle) of results produced since the last {@link BatchProcessor.takePendingResults} call. */
-    private pendingIndices;
-    /** Error messages accumulated across processed entries, for the post-batch telemetry event. */
-    private readonly errors;
+    /** The state mutated through processing (and preprocessing) */
+    private state;
     /**
      * Creates a batch processor.
      * @param router - The FHIR router.
@@ -157,7 +154,6 @@ export declare class BatchProcessor {
      * Scans the Bundle in order to ensure entries are processed in the correct sequence,
      * as well as to identify any operations that might require specific handling.
      *
-     * @param results - The array of result entries, to track partial results.
      * @returns The information gathered from scanning the Bundle.
      */
     private preprocessBundle;
@@ -232,11 +228,12 @@ export declare class BatchProcessor {
  */
 export declare function buildBatchResponseBundle(bundleType: Bundle['type'], entryCount: number, results: Record<number, BundleEntry>): Bundle;
 
-export declare type BundlePreprocessInfo = {
+export declare interface BundlePreprocessInfo {
     ordering: number[];
     requiresStrongTransaction: boolean;
     updates: number;
-};
+    resourceTypes: Set<ResourceType>;
+}
 
 export declare function createResourceImpl<T extends Resource>(resourceType: T['resourceType'], resource: T, repo: FhirRepository, options?: CreateResourceOptions): Promise<FhirResponse>;
 
@@ -353,7 +350,7 @@ export declare abstract class FhirRepository {
      * @param patch - The JSONPatch operations.
      * @returns The patched resource.
      */
-    abstract patchResource<T extends Resource>(resourceType: T['resourceType'], id: string, patch: Operation[] | Parameters_2): Promise<WithId<T>>;
+    abstract patchResource<T extends Resource>(resourceType: T['resourceType'], id: string, patch: Operation[] | Parameters_2, options?: UpdateResourceOptions): Promise<WithId<T>>;
     /**
      * Searches for FHIR resources.
      *
@@ -377,10 +374,10 @@ export declare abstract class FhirRepository {
      * Runs a callback function within a transaction.
      *
      * @param callback - The callback function to be run within a transaction.
+     * @param options - The transaction options.
+     * @returns The result of the callback function.
      */
-    abstract withTransaction<TResult>(callback: (txRepo: this) => Promise<TResult>, options?: {
-        serializable?: boolean;
-    }): Promise<TResult>;
+    abstract withTransaction<TResult>(callback: (txRepo: this) => Promise<TResult>, options: TransactionOptions): Promise<TResult>;
     /**
      * Searches for a single FHIR resource.
      *
@@ -461,7 +458,7 @@ export declare abstract class FhirRepository {
      * @returns A promise that resolves when the operation is complete.
      */
     conditionalDelete(search: SearchRequest): Promise<void>;
-    conditionalPatch(search: SearchRequest, patch: Operation[]): Promise<WithId<Resource>>;
+    conditionalPatch(search: SearchRequest, patch: Operation[], options?: UpdateResourceOptions): Promise<WithId<Resource>>;
 }
 
 export declare type FhirRequest = {
@@ -483,7 +480,9 @@ export declare type FhirRequestConfig = {
     transactions?: boolean;
 };
 
-export declare type FhirResponse = [OperationOutcome] | [OperationOutcome, Resource] | [OperationOutcome, Resource, FhirResponseOptions];
+export declare type FhirResponse = [
+OperationOutcome
+] | [OperationOutcome, Resource] | [OperationOutcome, Resource, FhirResponseOptions];
 
 export declare type FhirResponseOptions = {
     contentType?: string;
@@ -510,8 +509,75 @@ export declare class FhirRouter extends EventTarget_2 {
     log(level: string, message: string, data?: Record<string, any>): void;
 }
 
+/**
+ * Gets the extra search entries for the _include and _revinclude parameters.
+ *
+ * The `entries` array is appended to in place.
+ *
+ * @param repo - The FHIR repository.
+ * @param searchRequest - The original search request.
+ * @param resources - The resources returned by the original search.
+ * @param entries - The output bundle entries.
+ * @param options - Optional repository-specific behavior.
+ */
+export declare function getExtraEntries<T extends Resource>(repo: FhirRepository, searchRequest: SearchRequest<T>, resources: T[], entries: BundleEntry[], options?: IncludeOptions): Promise<void>;
+
+/**
+ * Returns bundle entries for the resources that are included in the search result.
+ *
+ * See documentation on _include: https://hl7.org/fhir/R4/search.html#include
+ * @param repo - The repository.
+ * @param include - The include parameter.
+ * @param resources - The base search result resources.
+ * @param options - Optional repository-specific behavior.
+ * @returns The bundle entries for the included resources.
+ */
+export declare function getSearchIncludeEntries(repo: FhirRepository, include: IncludeTarget, resources: Resource[], options?: IncludeOptions): Promise<BundleEntry[]>;
+
+/**
+ * Returns bundle entries for the resources that are reverse included in the search result.
+ *
+ * See documentation on _revinclude: https://hl7.org/fhir/R4/search.html#revinclude
+ * @param repo - The repository.
+ * @param revInclude - The revInclude parameter.
+ * @param resources - The base search result resources.
+ * @param options - Optional repository-specific behavior.
+ * @returns The bundle entries for the reverse included resources.
+ */
+export declare function getSearchRevIncludeEntries(repo: FhirRepository, revInclude: IncludeTarget, resources: Resource[], options?: IncludeOptions): Promise<BundleEntry[]>;
+
 export declare type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 
+export declare interface IncludeOptions {
+    /**
+     * Builds the `Bundle.entry.fullUrl` for an included resource.
+     * When omitted, `fullUrl` is not set on the resulting entries.
+     */
+    readonly fullUrl?: (resourceType: string, id: string) => string;
+    /**
+     * The maximum number of `:iterate` rounds before the search is rejected. Defaults to 5.
+     */
+    readonly maxDepth?: number;
+    /**
+     * The maximum total number of bundle entries before the search is rejected.
+     * Defaults to `DEFAULT_MAX_SEARCH_COUNT`.
+     */
+    readonly maxResults?: number;
+    /**
+     * Executes the sub-searches needed for canonical `_include` and for all `_revinclude` targets.
+     * Defaults to `repo.searchResources()`.
+     */
+    readonly executeSearch?: IncludeSearchFn;
+}
+
+/**
+ * Executes a search on behalf of the include logic.
+ *
+ * The default implementation uses {@link FhirRepository.searchResources}. The server overrides this
+ * to reuse its already-built query pipeline rather than re-entering the public `search()` entry point.
+ */
+export declare type IncludeSearchFn = (searchRequest: SearchRequest) => Promise<WithId<Resource>[]>;
+
 export declare interface LogEvent extends Event_2 {
     message: string;
     data?: Record<string, any>;
@@ -527,16 +593,22 @@ export declare class MemoryRepository extends FhirRepository {
     withSeeding<T>(fn: () => T | Promise<T>): Promise<T>;
     clear(): void;
     setMode(_mode: RepositoryMode): void;
+    private createResourceSync;
     createResource<T extends Resource>(resource: T, options?: CreateResourceOptions, update?: boolean): Promise<WithId<T>>;
     generateId(): string;
     updateResource<T extends Resource>(resource: T, options?: UpdateResourceOptions): Promise<WithId<T>>;
-    patchResource<T extends Resource>(resourceType: T['resourceType'], id: string, patch: Operation[] | Parameters_2): Promise<WithId<T>>;
+    patchResource<T extends Resource>(resourceType: T['resourceType'], id: string, patch: Operation[] | Parameters_2, options?: UpdateResourceOptions): Promise<WithId<T>>;
     readResource<T extends Resource>(resourceType: string, id: string): Promise<T>;
     readReference<T extends Resource>(reference: Reference<T>): Promise<WithId<T>>;
     readReferences<T extends Resource>(references: readonly Reference<T>[]): Promise<(T | OperationOutcomeError)[]>;
     readHistory<T extends Resource>(resourceType: string, id: string): Promise<Bundle<T>>;
     readVersion<T extends Resource>(resourceType: string, id: string, versionId: string): Promise<T>;
+    private searchSync;
     search<T extends Resource>(searchRequest: SearchRequest<T>): Promise<Bundle<WithId<T>>>;
+    conditionalCreate<T extends Resource>(resource: T, search: SearchRequest<T>, options?: CreateResourceOptions): Promise<{
+        resource: WithId<T>;
+        outcome: OperationOutcome;
+    }>;
     searchByReference<T extends Resource>(searchRequest: SearchRequest<T>, referenceField: string, references: string[]): Promise<Record<string, WithId<T>[]>>;
     deleteResource(resourceType: string, id: string): Promise<void>;
     withTransaction<TResult>(callback: (repo: this) => Promise<TResult>): Promise<TResult>;
@@ -571,6 +643,8 @@ export declare const RepositoryMode: {
 
 export declare type RepositoryMode = (typeof RepositoryMode)[keyof typeof RepositoryMode];
 
+declare type ResourceTypeInput = ResourceType | readonly ResourceType[] | ReadonlySet<ResourceType>;
+
 /** @see http://hl7.org/fhir/R4/codesystem-restful-interaction.html */
 export declare type RestInteraction = CapabilityStatementRestInteraction['code'] | CapabilityStatementRestResourceInteraction['code'] | 'operation';
 
@@ -595,6 +669,11 @@ export declare type RouteResult<Handler, Metadata> = {
     data?: Metadata;
 };
 
+export declare interface TransactionOptions {
+    readonly resourceTypes: ResourceTypeInput;
+    readonly serializable?: boolean;
+}
+
 export declare function updateResourceImpl<T extends Resource>(resourceType: T['resourceType'], id: string, resource: T, repo: FhirRepository, options?: UpdateResourceOptions): Promise<FhirResponse>;
 
 export declare type UpdateResourceOptions = {