@medplum/fhir-router 5.1.27 → 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';
@@ -349,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.
      *
@@ -457,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 = {
@@ -508,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>;
@@ -529,7 +597,7 @@ export declare class MemoryRepository extends FhirRepository {
     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)[]>;

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';
@@ -349,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.
      *
@@ -457,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 = {
@@ -508,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>;
@@ -529,7 +597,7 @@ export declare class MemoryRepository extends FhirRepository {
     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)[]>;