@medplum/fhir-router 5.1.8 → 5.1.9

package/dist/cjs/index.d.ts

@@ -143,6 +143,16 @@ export declare abstract class FhirRepository<TClient = unknown> {
      * @returns The search results.
      */
     abstract search<T extends Resource>(searchRequest: SearchRequest<T>): Promise<Bundle<WithId<T>>>;
+    /**
+     * Searches for FHIR resources by reference.
+     *
+     * This is an advanced operation that is primarily used to optimize GraphQL resolvers that need to search for resources by reference.
+     *
+     * @param searchRequest - The FHIR search request.
+     * @param referenceField - The name of the reference field to search by (e.g. "patient" or "subject").
+     * @param references - The reference values to search for (e.g. ["Patient/123", "Patient/456"]).
+     * @returns A record mapping reference values to the resources that reference them (e.g. { "Patient/123": [Observation1, Observation2], "Patient/456": [Observation3] }).
+     */
     abstract searchByReference<T extends Resource>(searchRequest: SearchRequest<T>, referenceField: string, references: string[]): Promise<Record<string, WithId<T>[]>>;
     /**
      * Runs a callback function within a transaction.
@@ -176,14 +186,61 @@ export declare abstract class FhirRepository<TClient = unknown> {
      * @returns Promise to the array of search results.
      */
     searchResources<T extends Resource>(searchRequest: SearchRequest<T>): Promise<WithId<T>[]>;
+    /**
+     * Conditionally creates a FHIR resource.
+     *
+     * The action it takes depends on how many matches are found:
+     *
+     *   1. No matches: The server processes the create as above
+     *   2. One Match: The server ignores the post and returns 200 OK
+     *   3. Multiple matches: The server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough
+     *
+     * See: https://hl7.org/fhir/R4/http.html#ccreate
+     *
+     * @param resource - The FHIR resource to create.
+     * @param search - The "If-None-Exist" search criteria to determine if the resource already exists.
+     * @param options - Additional options for resource creation.
+     * @returns A promise resolving to the created resource and the operation outcome.
+     */
     conditionalCreate<T extends Resource>(resource: T, search: SearchRequest<T>, options?: CreateResourceOptions): Promise<{
         resource: WithId<T>;
         outcome: OperationOutcome;
     }>;
+    /**
+     * Conditionally updates a FHIR resource.
+     *
+     * The action it takes depends on how many matches are found:
+     *
+     *   1. No matches, no id provided: The server creates the resource.
+     *   2. No matches, id provided: The server treats the interaction as an Update as Create interaction (or rejects it, if it does not support Update as Create)
+     *   3. One Match, no resource id provided OR (resource id provided and it matches the found resource): The server performs the update against the matching resource
+     *   4. One Match, resource id provided but does not match resource found: The server returns a 400 Bad Request error indicating the client id specification was a problem preferably with an OperationOutcome
+     *   5. Multiple matches: The server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough preferably with an OperationOutcome
+     *
+     * See: https://hl7.org/fhir/R4/http.html#cond-update
+     *
+     * @param resource - The FHIR resource to update.
+     * @param search - The "If-Exist" search criteria to determine if the resource already exists.
+     * @param options - Additional options for resource update.
+     * @returns A promise resolving to the updated resource and the operation outcome.
+     */
     conditionalUpdate<T extends Resource>(resource: T, search: SearchRequest, options?: CreateResourceOptions & UpdateResourceOptions): Promise<{
         resource: WithId<T>;
         outcome: OperationOutcome;
     }>;
+    /**
+     * Conditionally deletes a FHIR resource.
+     *
+     * The action it takes depends on how many matches are found:
+     *
+     *   1. No matches or One Match: The server performs an ordinary delete on the matching resource
+     *   2. Multiple matches: A server may choose to delete all the matching resources, or it may choose to return a 412 Precondition Failed error indicating the client's criteria were not selective enough.
+     *
+     * See: https://hl7.org/fhir/R4/http.html#3.1.0.7.1
+     *
+     * @param search - The "If-Exist" search criteria to determine which resource(s) to delete.
+     * @returns A promise that resolves when the operation is complete.
+     */
     conditionalDelete(search: SearchRequest): Promise<void>;
     conditionalPatch(search: SearchRequest, patch: Operation[]): Promise<WithId<Resource>>;
 }

package/dist/esm/index.d.ts

@@ -143,6 +143,16 @@ export declare abstract class FhirRepository<TClient = unknown> {
      * @returns The search results.
      */
     abstract search<T extends Resource>(searchRequest: SearchRequest<T>): Promise<Bundle<WithId<T>>>;
+    /**
+     * Searches for FHIR resources by reference.
+     *
+     * This is an advanced operation that is primarily used to optimize GraphQL resolvers that need to search for resources by reference.
+     *
+     * @param searchRequest - The FHIR search request.
+     * @param referenceField - The name of the reference field to search by (e.g. "patient" or "subject").
+     * @param references - The reference values to search for (e.g. ["Patient/123", "Patient/456"]).
+     * @returns A record mapping reference values to the resources that reference them (e.g. { "Patient/123": [Observation1, Observation2], "Patient/456": [Observation3] }).
+     */
     abstract searchByReference<T extends Resource>(searchRequest: SearchRequest<T>, referenceField: string, references: string[]): Promise<Record<string, WithId<T>[]>>;
     /**
      * Runs a callback function within a transaction.
@@ -176,14 +186,61 @@ export declare abstract class FhirRepository<TClient = unknown> {
      * @returns Promise to the array of search results.
      */
     searchResources<T extends Resource>(searchRequest: SearchRequest<T>): Promise<WithId<T>[]>;
+    /**
+     * Conditionally creates a FHIR resource.
+     *
+     * The action it takes depends on how many matches are found:
+     *
+     *   1. No matches: The server processes the create as above
+     *   2. One Match: The server ignores the post and returns 200 OK
+     *   3. Multiple matches: The server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough
+     *
+     * See: https://hl7.org/fhir/R4/http.html#ccreate
+     *
+     * @param resource - The FHIR resource to create.
+     * @param search - The "If-None-Exist" search criteria to determine if the resource already exists.
+     * @param options - Additional options for resource creation.
+     * @returns A promise resolving to the created resource and the operation outcome.
+     */
     conditionalCreate<T extends Resource>(resource: T, search: SearchRequest<T>, options?: CreateResourceOptions): Promise<{
         resource: WithId<T>;
         outcome: OperationOutcome;
     }>;
+    /**
+     * Conditionally updates a FHIR resource.
+     *
+     * The action it takes depends on how many matches are found:
+     *
+     *   1. No matches, no id provided: The server creates the resource.
+     *   2. No matches, id provided: The server treats the interaction as an Update as Create interaction (or rejects it, if it does not support Update as Create)
+     *   3. One Match, no resource id provided OR (resource id provided and it matches the found resource): The server performs the update against the matching resource
+     *   4. One Match, resource id provided but does not match resource found: The server returns a 400 Bad Request error indicating the client id specification was a problem preferably with an OperationOutcome
+     *   5. Multiple matches: The server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough preferably with an OperationOutcome
+     *
+     * See: https://hl7.org/fhir/R4/http.html#cond-update
+     *
+     * @param resource - The FHIR resource to update.
+     * @param search - The "If-Exist" search criteria to determine if the resource already exists.
+     * @param options - Additional options for resource update.
+     * @returns A promise resolving to the updated resource and the operation outcome.
+     */
     conditionalUpdate<T extends Resource>(resource: T, search: SearchRequest, options?: CreateResourceOptions & UpdateResourceOptions): Promise<{
         resource: WithId<T>;
         outcome: OperationOutcome;
     }>;
+    /**
+     * Conditionally deletes a FHIR resource.
+     *
+     * The action it takes depends on how many matches are found:
+     *
+     *   1. No matches or One Match: The server performs an ordinary delete on the matching resource
+     *   2. Multiple matches: A server may choose to delete all the matching resources, or it may choose to return a 412 Precondition Failed error indicating the client's criteria were not selective enough.
+     *
+     * See: https://hl7.org/fhir/R4/http.html#3.1.0.7.1
+     *
+     * @param search - The "If-Exist" search criteria to determine which resource(s) to delete.
+     * @returns A promise that resolves when the operation is complete.
+     */
     conditionalDelete(search: SearchRequest): Promise<void>;
     conditionalPatch(search: SearchRequest, patch: Operation[]): Promise<WithId<Resource>>;
 }