@medplum/fhir-router 5.1.23 → 5.1.26

package/dist/cjs/index.d.ts

@@ -1,4 +1,5 @@
 import type { Bundle } from '@medplum/fhirtypes';
+import type { BundleEntry } from '@medplum/fhirtypes';
 import type { CapabilityStatementRestInteraction } from '@medplum/fhirtypes';
 import type { CapabilityStatementRestResourceInteraction } from '@medplum/fhirtypes';
 import type { Event as Event_2 } from '@medplum/core';
@@ -20,6 +21,223 @@ export declare interface BatchEvent extends Event_2 {
     size?: number;
 }
 
+/**
+ * The durable, JSON-serializable state produced by preprocessing a batch bundle. This is
+ * everything required to (re)hydrate a {@link BatchProcessor} and resume processing after a
+ * server restart or worker crash, EXCEPT the progress marker (the index into `bundleInfo.ordering`
+ * of the next entry to process) and the per-entry results produced so far, both of which the
+ * caller (e.g. the async batch worker) is responsible for persisting separately.
+ *
+ * @see BatchProcessor.preprocess
+ * @see BatchProcessor.fromState
+ */
+export declare interface BatchInitialState {
+    /**
+     * The preprocessed bundle. During preprocessing the bundle is mutated in place: `create`
+     * entries are assigned resource IDs and conditional `update`/`delete` URLs are rewritten to
+     * absolute references. This mutated form MUST be persisted and reloaded verbatim — re-running
+     * preprocessing on the original bundle would assign fresh random IDs and break references to
+     * resources that were already created.
+     */
+    bundle: Bundle;
+    bundleInfo: BundlePreprocessInfo;
+    resolvedIdentities: Record<string, string>;
+    /**
+     * Result entries produced during preprocessing itself (i.e. error responses for malformed
+     * entries in a non-transaction bundle), keyed by their index in the original bundle. These
+     * entries are never re-processed, so they are captured here rather than in per-entry progress.
+     */
+    preprocessResults: Record<number, BundleEntry>;
+}
+
+/**
+ * The BatchProcessor class contains the state for processing a batch/transaction bundle.
+ * In particular, it tracks rewritten IDs as necessary.
+ *
+ * The processor supports two modes of operation:
+ *
+ * 1. One-shot via {@link BatchProcessor.run}, used for synchronous batch/transaction requests.
+ *    This preprocesses and then processes every entry within a single call.
+ *
+ * 2. Re-entrant, used by the async batch worker. The caller drives processing one entry at a
+ *    time via {@link BatchProcessor.preprocess}, {@link BatchProcessor.hasMoreEntries}, and
+ *    {@link BatchProcessor.processNextEntry}, persisting durable state ({@link BatchInitialState},
+ *    progress marker, and per-entry results) as it goes. After a restart the processor is
+ *    rehydrated via {@link BatchProcessor.fromState} and processing resumes from the persisted
+ *    marker. Only `batch` bundles are re-entrant; `transaction` bundles must use {@link BatchProcessor.run}.
+ */
+export declare class BatchProcessor {
+    private readonly router;
+    private repo;
+    private readonly bundle;
+    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;
+    /**
+     * Creates a batch processor.
+     * @param router - The FHIR router.
+     * @param repo - The FHIR repository.
+     * @param bundle - The input bundle.
+     * @param req - The request for the batch.
+     */
+    constructor(router: FhirRouter, repo: FhirRepository, bundle: Bundle, req: FhirRequest);
+    /**
+     * Rehydrates a batch processor from previously-persisted durable state so that processing can
+     * resume after a server restart or worker crash. Intended for the re-entrant (async batch)
+     * flow; the caller is responsible for loading the {@link BatchInitialState} and progress marker
+     * from durable storage, and for assembling the final response bundle from the durably-persisted
+     * result entries (this instance only tracks results produced in the current run).
+     * @param router - The FHIR router.
+     * @param repo - The FHIR repository.
+     * @param req - The request for the batch.
+     * @param initialState - The durable state produced by {@link BatchProcessor.preprocess}.
+     * @param position - The index into `bundleInfo.ordering` of the next entry to process.
+     * @returns A batch processor positioned to resume at `position`.
+     */
+    static fromState(router: FhirRouter, repo: FhirRepository, req: FhirRequest, initialState: BatchInitialState, position: number): BatchProcessor;
+    /**
+     * Processes a FHIR batch or transaction request in a single call.
+     * @returns The bundle response.
+     */
+    run(): Promise<Bundle>;
+    /**
+     * Validates and preprocesses the bundle, scanning entries to resolve identities, rewrite
+     * conditional references, and compute processing order.
+     *
+     * For the re-entrant flow, the returned {@link BatchInitialState} should be persisted to
+     * durable storage before processing entries so that the processor can be rehydrated via
+     * {@link BatchProcessor.fromState} after a restart.
+     * @returns The durable initial state for the batch.
+     */
+    preprocess(): Promise<BatchInitialState>;
+    /**
+     * @returns True if there are more entries to process, i.e. {@link BatchProcessor.processNextEntry} should be
+     * called again.
+     */
+    hasMoreEntries(): boolean;
+    /**
+     * @returns The index into `bundleInfo.ordering` of the next entry to process. This is the
+     * progress marker that should be persisted (together with the result entries produced so far)
+     * to allow resuming via {@link BatchProcessor.fromState}.
+     */
+    getPosition(): number;
+    /**
+     * Returns the result entries produced since the last call (keyed by their index in the
+     * original bundle) and clears the pending buffer. The caller persists these to durable
+     * storage as a checkpoint before advancing the durable progress marker.
+     * @returns Newly-produced result entries, keyed by original bundle index or `undefined`
+     * if no new entries were produced.
+     */
+    takePendingResults(): Record<number, BundleEntry> | undefined;
+    private processEntriesAndBuild;
+    private dispatchPreEvent;
+    private dispatchPostEvent;
+    /**
+     * Assembles the response bundle from the result entries recorded on this instance. Used by the
+     * one-shot {@link BatchProcessor.run} flow. The re-entrant flow instead assembles the final bundle from durably
+     * persisted results via {@link buildBatchResponseBundle}.
+     * @returns The bundle response.
+     */
+    private buildResultBundle;
+    /**
+     * Executes a callback with the provided repository intended for use with transaction-scoped operations.
+     * @param repo - The repository to use.
+     * @param callback - The callback to execute.
+     * @returns The result of the callback.
+     */
+    private withRepo;
+    /**
+     * 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;
+    /**
+     * Resolves the resource identity associated with an entry, and tracks it for later reference rewriting.
+     * @see https://www.hl7.org/fhir/R4/http.html#trules
+     *
+     * @param entry - The entry to resolve.
+     * @param index - The index of the Bundle entry.
+     * @param seenIdentities - The set of resolved identities that have already been seen in preprocessing.
+     * @returns - The (error) result for the entry, if it could not be preprocessed.
+     */
+    private preprocessEntry;
+    private resolveIdentity;
+    private getRouteForEntry;
+    private resolveCreateIdentity;
+    private resolveModificationIdentity;
+    /**
+     * Processes the next entry in the bundle ordering (the entry at the current progress marker),
+     * recording its result and advancing the marker.
+     *
+     * For `batch` bundles, per-entry errors are captured as error result entries and processing
+     * continues; a 429 (rate limit) terminates the batch, filling all remaining entries with the
+     * rate-limit outcome.
+     *
+     * Must be called only after {@link BatchProcessor.preprocess} or {@link BatchProcessor.fromState}.
+     * Callers should guard with {@link BatchProcessor.hasMoreEntries}. The re-entrant flow only supports
+     * `batch` semantics. For `transaction` bundles, use {@link BatchProcessor.run}.
+     */
+    processNextEntry(): Promise<void>;
+    /**
+     * Processes the next entry in the bundle ordering (the entry at the current progress marker),
+     * recording its result and advancing the marker.
+     *
+     * For `batch` bundles, per-entry errors are captured as error result entries and processing
+     * continues; a 429 (rate limit) terminates the batch, filling all remaining entries with the
+     * rate-limit outcome. For `transaction` bundles, any entry error is thrown so the enclosing
+     * transaction rolls back.
+     */
+    private processNextEntryImpl;
+    private setResult;
+    /**
+     * Processes a single entry from a FHIR batch request.
+     * @param entry - The bundle entry.
+     * @returns The bundle entry response.
+     */
+    private processBatchEntry;
+    /**
+     * Constructs the equivalent HTTP request for a Bundle entry, based on its `request` field.
+     * @param entry - The Bundle entry to parse.
+     * @param route - The route associated with the request.
+     * @returns The HTTP request to perform the operation specified by the given batch entry.
+     */
+    private parseBatchRequest;
+    private parsePatchBody;
+    private parsePatchParameter;
+    private rewriteIds;
+    private rewriteIdsInArray;
+    private rewriteIdsInObject;
+    private rewriteIdsInString;
+    private isTransaction;
+}
+
+/**
+ * Assembles a batch/transaction response bundle from result entries that were collected across
+ * multiple re-entrant processing runs and persisted to durable storage. Used by the async batch
+ * worker to build the final (or a partial) response bundle from checkpointed results.
+ * @param bundleType - The type of the request bundle (`batch` or `transaction`).
+ * @param entryCount - The number of entries in the original request bundle.
+ * @param results - The result entries, keyed by their index in the original request bundle.
+ * @returns The response bundle, with one entry per original request entry.
+ */
+export declare function buildBatchResponseBundle(bundleType: Bundle['type'], entryCount: number, results: Record<number, BundleEntry>): Bundle;
+
+export declare type BundlePreprocessInfo = {
+    ordering: number[];
+    requiresStrongTransaction: boolean;
+    updates: number;
+};
+
 export declare function createResourceImpl<T extends Resource>(resourceType: T['resourceType'], resource: T, repo: FhirRepository, options?: CreateResourceOptions): Promise<FhirResponse>;
 
 export declare type CreateResourceOptions = {

package/dist/esm/index.d.ts

@@ -1,4 +1,5 @@
 import type { Bundle } from '@medplum/fhirtypes';
+import type { BundleEntry } from '@medplum/fhirtypes';
 import type { CapabilityStatementRestInteraction } from '@medplum/fhirtypes';
 import type { CapabilityStatementRestResourceInteraction } from '@medplum/fhirtypes';
 import type { Event as Event_2 } from '@medplum/core';
@@ -20,6 +21,223 @@ export declare interface BatchEvent extends Event_2 {
     size?: number;
 }
 
+/**
+ * The durable, JSON-serializable state produced by preprocessing a batch bundle. This is
+ * everything required to (re)hydrate a {@link BatchProcessor} and resume processing after a
+ * server restart or worker crash, EXCEPT the progress marker (the index into `bundleInfo.ordering`
+ * of the next entry to process) and the per-entry results produced so far, both of which the
+ * caller (e.g. the async batch worker) is responsible for persisting separately.
+ *
+ * @see BatchProcessor.preprocess
+ * @see BatchProcessor.fromState
+ */
+export declare interface BatchInitialState {
+    /**
+     * The preprocessed bundle. During preprocessing the bundle is mutated in place: `create`
+     * entries are assigned resource IDs and conditional `update`/`delete` URLs are rewritten to
+     * absolute references. This mutated form MUST be persisted and reloaded verbatim — re-running
+     * preprocessing on the original bundle would assign fresh random IDs and break references to
+     * resources that were already created.
+     */
+    bundle: Bundle;
+    bundleInfo: BundlePreprocessInfo;
+    resolvedIdentities: Record<string, string>;
+    /**
+     * Result entries produced during preprocessing itself (i.e. error responses for malformed
+     * entries in a non-transaction bundle), keyed by their index in the original bundle. These
+     * entries are never re-processed, so they are captured here rather than in per-entry progress.
+     */
+    preprocessResults: Record<number, BundleEntry>;
+}
+
+/**
+ * The BatchProcessor class contains the state for processing a batch/transaction bundle.
+ * In particular, it tracks rewritten IDs as necessary.
+ *
+ * The processor supports two modes of operation:
+ *
+ * 1. One-shot via {@link BatchProcessor.run}, used for synchronous batch/transaction requests.
+ *    This preprocesses and then processes every entry within a single call.
+ *
+ * 2. Re-entrant, used by the async batch worker. The caller drives processing one entry at a
+ *    time via {@link BatchProcessor.preprocess}, {@link BatchProcessor.hasMoreEntries}, and
+ *    {@link BatchProcessor.processNextEntry}, persisting durable state ({@link BatchInitialState},
+ *    progress marker, and per-entry results) as it goes. After a restart the processor is
+ *    rehydrated via {@link BatchProcessor.fromState} and processing resumes from the persisted
+ *    marker. Only `batch` bundles are re-entrant; `transaction` bundles must use {@link BatchProcessor.run}.
+ */
+export declare class BatchProcessor {
+    private readonly router;
+    private repo;
+    private readonly bundle;
+    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;
+    /**
+     * Creates a batch processor.
+     * @param router - The FHIR router.
+     * @param repo - The FHIR repository.
+     * @param bundle - The input bundle.
+     * @param req - The request for the batch.
+     */
+    constructor(router: FhirRouter, repo: FhirRepository, bundle: Bundle, req: FhirRequest);
+    /**
+     * Rehydrates a batch processor from previously-persisted durable state so that processing can
+     * resume after a server restart or worker crash. Intended for the re-entrant (async batch)
+     * flow; the caller is responsible for loading the {@link BatchInitialState} and progress marker
+     * from durable storage, and for assembling the final response bundle from the durably-persisted
+     * result entries (this instance only tracks results produced in the current run).
+     * @param router - The FHIR router.
+     * @param repo - The FHIR repository.
+     * @param req - The request for the batch.
+     * @param initialState - The durable state produced by {@link BatchProcessor.preprocess}.
+     * @param position - The index into `bundleInfo.ordering` of the next entry to process.
+     * @returns A batch processor positioned to resume at `position`.
+     */
+    static fromState(router: FhirRouter, repo: FhirRepository, req: FhirRequest, initialState: BatchInitialState, position: number): BatchProcessor;
+    /**
+     * Processes a FHIR batch or transaction request in a single call.
+     * @returns The bundle response.
+     */
+    run(): Promise<Bundle>;
+    /**
+     * Validates and preprocesses the bundle, scanning entries to resolve identities, rewrite
+     * conditional references, and compute processing order.
+     *
+     * For the re-entrant flow, the returned {@link BatchInitialState} should be persisted to
+     * durable storage before processing entries so that the processor can be rehydrated via
+     * {@link BatchProcessor.fromState} after a restart.
+     * @returns The durable initial state for the batch.
+     */
+    preprocess(): Promise<BatchInitialState>;
+    /**
+     * @returns True if there are more entries to process, i.e. {@link BatchProcessor.processNextEntry} should be
+     * called again.
+     */
+    hasMoreEntries(): boolean;
+    /**
+     * @returns The index into `bundleInfo.ordering` of the next entry to process. This is the
+     * progress marker that should be persisted (together with the result entries produced so far)
+     * to allow resuming via {@link BatchProcessor.fromState}.
+     */
+    getPosition(): number;
+    /**
+     * Returns the result entries produced since the last call (keyed by their index in the
+     * original bundle) and clears the pending buffer. The caller persists these to durable
+     * storage as a checkpoint before advancing the durable progress marker.
+     * @returns Newly-produced result entries, keyed by original bundle index or `undefined`
+     * if no new entries were produced.
+     */
+    takePendingResults(): Record<number, BundleEntry> | undefined;
+    private processEntriesAndBuild;
+    private dispatchPreEvent;
+    private dispatchPostEvent;
+    /**
+     * Assembles the response bundle from the result entries recorded on this instance. Used by the
+     * one-shot {@link BatchProcessor.run} flow. The re-entrant flow instead assembles the final bundle from durably
+     * persisted results via {@link buildBatchResponseBundle}.
+     * @returns The bundle response.
+     */
+    private buildResultBundle;
+    /**
+     * Executes a callback with the provided repository intended for use with transaction-scoped operations.
+     * @param repo - The repository to use.
+     * @param callback - The callback to execute.
+     * @returns The result of the callback.
+     */
+    private withRepo;
+    /**
+     * 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;
+    /**
+     * Resolves the resource identity associated with an entry, and tracks it for later reference rewriting.
+     * @see https://www.hl7.org/fhir/R4/http.html#trules
+     *
+     * @param entry - The entry to resolve.
+     * @param index - The index of the Bundle entry.
+     * @param seenIdentities - The set of resolved identities that have already been seen in preprocessing.
+     * @returns - The (error) result for the entry, if it could not be preprocessed.
+     */
+    private preprocessEntry;
+    private resolveIdentity;
+    private getRouteForEntry;
+    private resolveCreateIdentity;
+    private resolveModificationIdentity;
+    /**
+     * Processes the next entry in the bundle ordering (the entry at the current progress marker),
+     * recording its result and advancing the marker.
+     *
+     * For `batch` bundles, per-entry errors are captured as error result entries and processing
+     * continues; a 429 (rate limit) terminates the batch, filling all remaining entries with the
+     * rate-limit outcome.
+     *
+     * Must be called only after {@link BatchProcessor.preprocess} or {@link BatchProcessor.fromState}.
+     * Callers should guard with {@link BatchProcessor.hasMoreEntries}. The re-entrant flow only supports
+     * `batch` semantics. For `transaction` bundles, use {@link BatchProcessor.run}.
+     */
+    processNextEntry(): Promise<void>;
+    /**
+     * Processes the next entry in the bundle ordering (the entry at the current progress marker),
+     * recording its result and advancing the marker.
+     *
+     * For `batch` bundles, per-entry errors are captured as error result entries and processing
+     * continues; a 429 (rate limit) terminates the batch, filling all remaining entries with the
+     * rate-limit outcome. For `transaction` bundles, any entry error is thrown so the enclosing
+     * transaction rolls back.
+     */
+    private processNextEntryImpl;
+    private setResult;
+    /**
+     * Processes a single entry from a FHIR batch request.
+     * @param entry - The bundle entry.
+     * @returns The bundle entry response.
+     */
+    private processBatchEntry;
+    /**
+     * Constructs the equivalent HTTP request for a Bundle entry, based on its `request` field.
+     * @param entry - The Bundle entry to parse.
+     * @param route - The route associated with the request.
+     * @returns The HTTP request to perform the operation specified by the given batch entry.
+     */
+    private parseBatchRequest;
+    private parsePatchBody;
+    private parsePatchParameter;
+    private rewriteIds;
+    private rewriteIdsInArray;
+    private rewriteIdsInObject;
+    private rewriteIdsInString;
+    private isTransaction;
+}
+
+/**
+ * Assembles a batch/transaction response bundle from result entries that were collected across
+ * multiple re-entrant processing runs and persisted to durable storage. Used by the async batch
+ * worker to build the final (or a partial) response bundle from checkpointed results.
+ * @param bundleType - The type of the request bundle (`batch` or `transaction`).
+ * @param entryCount - The number of entries in the original request bundle.
+ * @param results - The result entries, keyed by their index in the original request bundle.
+ * @returns The response bundle, with one entry per original request entry.
+ */
+export declare function buildBatchResponseBundle(bundleType: Bundle['type'], entryCount: number, results: Record<number, BundleEntry>): Bundle;
+
+export declare type BundlePreprocessInfo = {
+    ordering: number[];
+    requiresStrongTransaction: boolean;
+    updates: number;
+};
+
 export declare function createResourceImpl<T extends Resource>(resourceType: T['resourceType'], resource: T, repo: FhirRepository, options?: CreateResourceOptions): Promise<FhirResponse>;
 
 export declare type CreateResourceOptions = {