FhirClient

FhirClient is the base class responsible for handling HTTP requests to a FHIR server. It does not include any SMART-related logic or any authentication methods, but it is ideal if you want to connect to an open server, especially in NodeJS where it can be used without having to provide a server request/response environment.

Usage

// BROWSER (via script tag; FHIR is global variable)
const client = new FHIR.FhirClient("https://open-fhir-server.org");

// BROWSER (ES module or TypeScript)
import { FhirClient } from "fhirclient/browser";
const client = new FhirClient("https://open-fhir-server.org");

// BROWSER (bundler in CommonJS project)
const { FhirClient } = require("fhirclient/browser");
const client = new FhirClient("https://open-fhir-server.org");

// SERVER (CommonJS syntax
const { FhirClient } = require("fhirclient/node");
const client = new FhirClient("https://open-fhir-server.org");

// SERVER (ESM syntax)
import { FhirClient } from "fhirclient/node";
const client = new FhirClient("https://open-fhir-server.org");

Constructor

Creating an instance is simple. The constructor only accepts a single required argument - the base URL of the FHIR server:

// Create a client for the public FHIR server
const client = new FhirClient("https://r4.smarthealthit.org");

// Now we can use the client to make requests
const patient = await client.fhirRequest("Patient/123");
const observation = await client.fhirRequest("Observation/123");
// ....

Methods

create

create(resource: FhirResource, options: RequestOptions = {}): Promise<FhirResource>

Wrapper for fhirRequest implementing the FHIR resource create operation.

---

update

update(resource: FhirResource, options: RequestOptions = {}): Promise<FhirResource>

Wrapper for fhirRequest implementing the FHIR resource update operation.

---

patch

patch(uri: string, patch: Object, options: RequestOptions = {}): Promise<FhirResource>

Wrapper for fhirRequest implementing the FHIR resource update operation.

---

delete

delete(uri: string, options: RequestOptions = {}): Promise<FhirResource>

Wrapper for fhirRequest implementing the FHIR resource delete operation. Example:

client.delete("Patient/id");

---

getReferences

getReferences(resource: FhirResource, references: string[], options: RequestOptions = {}): Record<string, FhirResource>

Fetch all references found within the given resource, build a object where keys are the references as found in the source resource, and values are the resources that those references point to. Returns a promise that resolves with that map-like object.

---

resolveReferences

resolveReferences(resource: FhirResource, references: string[], options: RequestOptions = {}): Promise<FhirResource>

Similar to getReferences, but modifies the resources by replacing the references with whatever they resolve to.

---

pages

*pages(bundleOrUrl: string | URL | Bundle, options: RequestOptions = {}): AsyncGenerator<Bundle>

An sync iterator to make it easier to consume multiple pages in streaming fashion. Example:

// Iterate over the first 10 pages of patients
for await(const page of client.pages("/Patient", { limit: 10 })) {
                
    console.log(page)

    // We have full control here! We can wait a while before fetching the next
    // page, or throw an error, or just `break;` if we want to exit early
    await sleep(100) // just an example
}

---

resources

*resources(bundleOrUrl: string | URL | Bundle, options: RequestOptions = {}): AsyncGenerator<FhirResource>

Returns an sync iterator to make it easier to consume multiple resources in streaming fashion:

// Iterate over the first 200 patients, even if they come from multiple pages
for await(const patient of client.resources("/Patient", { limit: 200 })) {
    console.log(patient)
}

---

getFhirVersion

getFhirVersion(): Promise<string>

Returns a promise that will be resolved with the FHIR version as defined in the conformance statement of the server.

---

getFhirRelease

getFhirRelease(): Promise<number>

Returns a promise that will be resolved with the numeric FHIR version:

• 2 for DSTU2
• 3 for STU3
• 4 for R4
• 0 if the version is not known

Types

RequestOptions

For the purpose of documentation we define a type called RequestOptions. This includes any option that fetch supports plus two custom ones. This can be written like so in TypeScript:

interface RequestOptions extends RequestInit {
    /**
     * If the `includeResponse` option is `true` we can expect a
     * `CombinedFetchResult` where the `response` property is the `Response`
     * object and the `body` property is the parsed body.
     */
    includeResponse?: boolean;

    /**
     * Sets a limit if applicable. For example, we can control how many pages to
     * or resources to fetch
     */
    limit?: number
}

Extending the Class

You can extend this class to provide additional functionality. Here is a simple example that would add an access token to every request:

import { FhirClient } from "fhirclient";

class AuthenticatedFhirClient extends FhirClient {
    async fhirRequest<T>(uri, options = {}) {
        options.headers = {
            ...options.headers,
            authorization: `Bearer ${process.env.ACCESS_TOKEN}`
        }
        return super.fhirRequest<T>(uri, options)
    }
}