@haste-health/client 0.15.3

package/src/types/index.ts

@@ -0,0 +1,373 @@
+import { code, id } from "@haste-health/fhir-types/r4/types";
+import {
+  AllResourceTypes,
+  FHIR_VERSION,
+  Resource,
+  ResourceType,
+} from "@haste-health/fhir-types/versions";
+
+import type { Parameters } from "../url.js";
+import {
+  Interaction,
+  Request,
+  RequestLevel,
+  RequestType,
+  ResponseType,
+} from "./utilities.js";
+
+export * from "./utilities.js";
+
+export interface InstanceInteraction<Version extends FHIR_VERSION>
+  extends Request<Version, "instance"> {
+  resource: ResourceType<Version>;
+  id: id;
+}
+
+export interface TypeInteraction<Version extends FHIR_VERSION>
+  extends Request<Version, "type"> {
+  resource: ResourceType<Version>;
+}
+
+export interface SystemInteraction<Version extends FHIR_VERSION>
+  extends Request<Version, "system"> {}
+
+export interface ReadRequest<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: RequestType["read"];
+}
+
+export interface VersionReadRequest<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: RequestType["vread"];
+  versionId: string;
+}
+
+export interface InstanceUpdateRequest<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: RequestType["update"];
+  body: Resource<Version, ResourceType<Version>>;
+}
+
+// TODO - implement patch type
+export interface PatchRequest<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: RequestType["patch"];
+  body: unknown;
+}
+
+export interface InstanceDeleteRequest<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: RequestType["delete"];
+}
+
+export interface TypeDeleteRequest<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  parameters: Parameters<Version>;
+  type: RequestType["delete"];
+}
+
+export interface SystemDeleteRequest<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  parameters: Parameters<Version>;
+  type: RequestType["delete"];
+}
+
+export interface HistoryInstanceRequest<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: RequestType["history"];
+  parameters?: Parameters<Version>;
+}
+
+export interface CreateRequest<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  type: RequestType["create"];
+  body: Resource<Version, ResourceType<Version>>;
+}
+
+export interface ConditionalUpdateRequest<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  type: RequestType["update"];
+  parameters: Parameters<Version>;
+  body: Resource<Version, ResourceType<Version>>;
+}
+
+export interface TypeSearchRequest<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  parameters: Parameters<Version>;
+  type: RequestType["search"];
+}
+
+export interface TypeHistoryRequest<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  type: RequestType["history"];
+  parameters?: Parameters<Version>;
+}
+
+export interface CapabilitiesRequest<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  type: RequestType["capabilities"];
+}
+
+export interface BatchRequest<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  type: RequestType["batch"];
+  body: Resource<Version, "Bundle">;
+}
+
+export interface TransactionRequest<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  type: RequestType["transaction"];
+  body: Resource<Version, "Bundle">;
+}
+
+export interface SystemHistoryRequest<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  type: RequestType["history"];
+  parameters?: Parameters<Version>;
+}
+
+export interface SystemSearchRequest<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  parameters: Parameters<Version>;
+  type: RequestType["search"];
+}
+
+export interface InvokeInstanceRequest<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: RequestType["invoke"];
+  operation: code;
+  body: Resource<Version, "Parameters">;
+}
+
+export interface InvokeTypeRequest<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  type: RequestType["invoke"];
+  operation: code;
+  body: Resource<Version, "Parameters">;
+}
+
+export interface InvokeSystemRequest<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  type: RequestType["invoke"];
+  operation: code;
+  body: Resource<Version, "Parameters">;
+}
+
+export interface ReadResponse<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: ResponseType["read"];
+  body: Resource<Version, ResourceType<Version>>;
+}
+
+export interface VersionReadResponse<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: ResponseType["vread"];
+  versionId: string;
+  body: Resource<Version, ResourceType<Version>>;
+}
+
+export interface UpdateResponse<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: ResponseType["update"];
+  created?: boolean;
+  body: Resource<Version, ResourceType<Version>>;
+}
+
+// TODO - implement patch type
+export interface PatchResponse<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: ResponseType["patch"];
+  body: Resource<Version, ResourceType<Version>>;
+}
+
+export interface InstanceDeleteResponse<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: ResponseType["delete"];
+  deletion?: Resource<Version, AllResourceTypes>;
+}
+
+export interface TypeDeleteResponse<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  parameters: Parameters<Version>;
+  type: ResponseType["delete"];
+  // For conditional deletes include the resources that were deleted.
+  deletion?: Resource<Version, AllResourceTypes>[];
+}
+
+export interface SystemDeleteResponse<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  parameters: Parameters<Version>;
+  type: ResponseType["delete"];
+  // For conditional deletes include the resources that were deleted.
+  deletion?: Resource<Version, AllResourceTypes>[];
+}
+
+export interface InstanceHistoryResponse<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: ResponseType["history"];
+  body: Resource<Version, "Bundle">;
+}
+
+export interface CreateResponse<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  type: ResponseType["create"];
+  body: Resource<Version, ResourceType<Version>>;
+}
+
+export interface TypeSearchResponse<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  parameters: Parameters<Version>;
+  type: ResponseType["search"];
+  body: Resource<Version, "Bundle">;
+}
+
+export interface TypeHistoryResponse<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  type: ResponseType["history"];
+  body: Resource<Version, "Bundle">;
+}
+
+export interface CapabilitiesResponse<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  type: ResponseType["capabilities"];
+  body: Resource<Version, "CapabilityStatement">;
+}
+
+export interface BatchResponse<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  type: ResponseType["batch"];
+  body: Resource<Version, "Bundle">;
+}
+
+export interface TransactionResponse<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  type: ResponseType["transaction"];
+  body: Resource<Version, "Bundle">;
+}
+
+export interface SystemHistoryResponse<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  type: ResponseType["history"];
+  body: Resource<Version, "Bundle">;
+}
+
+export interface SystemSearchResponse<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  parameters: Parameters<Version>;
+  type: ResponseType["search"];
+  body: Resource<Version, "Bundle">;
+}
+
+export interface InvokeInstanceResponse<Version extends FHIR_VERSION>
+  extends InstanceInteraction<Version> {
+  type: ResponseType["invoke"];
+  operation: code;
+  body: Resource<Version, "Parameters">;
+}
+
+export interface InvokeTypeResponse<Version extends FHIR_VERSION>
+  extends TypeInteraction<Version> {
+  type: ResponseType["invoke"];
+  operation: code;
+  body: Resource<Version, "Parameters">;
+}
+
+export interface InvokeSystemResponse<Version extends FHIR_VERSION>
+  extends SystemInteraction<Version> {
+  type: ResponseType["invoke"];
+  operation: code;
+  body: Resource<Version, "Parameters">;
+}
+
+export type InvokeResponse<Version extends FHIR_VERSION> =
+  | InvokeInstanceResponse<Version>
+  | InvokeTypeResponse<Version>
+  | InvokeSystemResponse<Version>;
+
+export type InvokeRequest<Version extends FHIR_VERSION> =
+  | InvokeInstanceRequest<Version>
+  | InvokeTypeRequest<Version>
+  | InvokeSystemRequest<Version>;
+
+export type DeleteRequest<Version extends FHIR_VERSION> =
+  | InstanceDeleteRequest<Version>
+  | TypeDeleteRequest<Version>
+  | SystemDeleteRequest<Version>;
+export type DeleteResponse<Version extends FHIR_VERSION> =
+  | InstanceDeleteResponse<Version>
+  | TypeDeleteResponse<Version>
+  | SystemDeleteResponse<Version>;
+
+export type HistoryRequest<Version extends FHIR_VERSION> =
+  | HistoryInstanceRequest<Version>
+  | TypeHistoryRequest<Version>
+  | SystemHistoryRequest<Version>;
+export type HistoryResponse<Version extends FHIR_VERSION> =
+  | InstanceHistoryResponse<Version>
+  | TypeHistoryResponse<Version>
+  | SystemHistoryResponse<Version>;
+
+export type SearchRequest<Version extends FHIR_VERSION> =
+  | TypeSearchRequest<Version>
+  | SystemSearchRequest<Version>;
+export type SearchResponse<Version extends FHIR_VERSION> =
+  | TypeSearchResponse<Version>
+  | SystemSearchResponse<Version>;
+
+export type UpdateRequest<Version extends FHIR_VERSION> =
+  | InstanceUpdateRequest<Version>
+  | ConditionalUpdateRequest<Version>;
+
+interface ErrorResponse<
+  Version extends FHIR_VERSION,
+  Level extends keyof RequestLevel
+> extends Request<Version, Level> {
+  type: ResponseType["error"];
+  body: Resource<Version, "OperationOutcome">;
+}
+
+export type FHIRErrorResponse<Version extends FHIR_VERSION> =
+  | ErrorResponse<Version, "system">
+  | ErrorResponse<Version, "type">
+  | ErrorResponse<Version, "instance">;
+
+type InteractionToRequest<Version extends FHIR_VERSION> = {
+  invoke: InvokeRequest<Version>;
+  read: ReadRequest<Version>;
+  vread: VersionReadRequest<Version>;
+  update: UpdateRequest<Version>;
+  patch: PatchRequest<Version>;
+  delete: DeleteRequest<Version>;
+  history: HistoryRequest<Version>;
+  create: CreateRequest<Version>;
+  search: SearchRequest<Version>;
+  capabilities: CapabilitiesRequest<Version>;
+  batch: BatchRequest<Version>;
+  transaction: TransactionRequest<Version>;
+};
+
+export type FHIRRequest<
+  Version extends FHIR_VERSION,
+  I extends Interaction[keyof Interaction]
+> = InteractionToRequest<Version>[I];
+
+type InteractionToResponse<Version extends FHIR_VERSION> = {
+  error: FHIRErrorResponse<Version>;
+  invoke: InvokeResponse<Version>;
+  read: ReadResponse<Version>;
+  vread: VersionReadResponse<Version>;
+  update: UpdateResponse<Version>;
+  patch: PatchResponse<Version>;
+  history: HistoryResponse<Version>;
+  delete: DeleteResponse<Version>;
+  create: CreateResponse<Version>;
+  capabilities: CapabilitiesResponse<Version>;
+  batch: BatchResponse<Version>;
+  transaction: TransactionResponse<Version>;
+  search: SearchResponse<Version>;
+};
+
+export type FHIRResponse<
+  Version extends FHIR_VERSION,
+  I extends Interaction[keyof Interaction] | "error"
+> = InteractionToResponse<Version>[I];

package/src/types/utilities.ts

@@ -0,0 +1,62 @@
+import { FHIR_VERSIONS_SUPPORTED } from "@haste-health/fhir-types/versions";
+
+export type RequestLevel = {
+  instance: "instance";
+  system: "system";
+  type: "type";
+};
+
+export type Interaction = {
+  read: "read";
+  vread: "vread";
+  update: "update";
+  patch: "patch";
+  delete: "delete";
+  history: "history";
+  create: "create";
+  search: "search";
+  capabilities: "capabilities";
+  batch: "batch";
+  transaction: "transaction";
+  invoke: "invoke";
+};
+
+export function toInteraction<I extends AllInteractions>(
+  r: RequestType[I] | ResponseType[I]
+): I {
+  return r.split("-")[0] as I;
+}
+
+export type AllInteractions = Interaction[keyof Interaction];
+
+export type RequestType = {
+  [I in Interaction[keyof Interaction]]: `${I}-request`;
+};
+
+export type ResponseType = {
+  [I in Interaction[keyof Interaction]]: `${I}-response`;
+} & { error: "error-response" };
+
+export function RequestType<I extends Interaction[keyof Interaction]>(
+  interaction: I
+): RequestType[I] {
+  return `${interaction}-request` as RequestType[I];
+}
+
+export function ResponseType<
+  I extends Interaction[keyof Interaction] | "error"
+>(interaction: I): ResponseType[I] {
+  return `${interaction}-response` as ResponseType[I];
+}
+
+export type Request<
+  Version extends (typeof FHIR_VERSIONS_SUPPORTED)[number],
+  level extends keyof RequestLevel
+> = {
+  fhirVersion: Version;
+  level: RequestLevel[level];
+  http?: {
+    status: number;
+    headers: Record<string, string>;
+  };
+};

package/src/url.test.ts

@@ -0,0 +1,52 @@
+import { expect, test } from "@jest/globals";
+
+import parseFHIRSearch, {
+  escapeParameter,
+  splitParameter,
+  unescapeParameter,
+} from "./url.js";
+
+test("Test resource level", () => {
+  expect(parseFHIRSearch("Patient?name:text=bob")).toEqual([
+    { name: "name", modifier: "text", value: ["bob"] },
+  ]);
+});
+
+test("Test System level", () => {
+  expect(
+    parseFHIRSearch("Patient?name:text=bob&lastUpdated:not-in=1980-01-01"),
+  ).toEqual([
+    { name: "name", modifier: "text", value: ["bob"] },
+    {
+      name: "lastUpdated",
+      modifier: "not-in",
+      value: ["1980-01-01"],
+    },
+  ]);
+});
+
+test("TEST ESCAPING", () => {
+  expect(escapeParameter("test|123")).toEqual("test\\|123");
+  expect(unescapeParameter(escapeParameter("test|123"))).toEqual("test|123");
+  expect(escapeParameter("test\\123")).toEqual("test\\\\123");
+  expect(unescapeParameter(escapeParameter("test\\123"))).toEqual("test\\123");
+  expect(escapeParameter("test$123")).toEqual("test\\$123");
+  expect(escapeParameter("test,123")).toEqual("test\\,123");
+});
+
+test("TEST Parameter Split", () => {
+  expect(splitParameter("test\\|123|456", "|")).toEqual(["test|123", "456"]);
+  expect(splitParameter("|test\\|123|456|", "|")).toEqual([
+    "",
+    "test|123",
+    "456",
+    "",
+  ]);
+
+  expect(splitParameter("|123|test\\|123|456", "|")).toEqual([
+    "",
+    "123",
+    "test|123",
+    "456",
+  ]);
+});

package/src/url.ts

@@ -0,0 +1,141 @@
+import { FHIR_VERSION, Resource } from "@haste-health/fhir-types/versions";
+import { OperationError, outcomeError } from "@haste-health/operation-outcomes";
+
+type SPECIAL_CHARACTER = "\\" | "|" | "$" | ",";
+const SPECIAL_CHARACTERS: SPECIAL_CHARACTER[] = ["\\", "|", "$", ","];
+
+/**
+ * Returns string with split pieces and unescapes special characters from the split piece.
+ * @param parameter Parameter to be split
+ * @param specialCharacter One of special characters that get escaped on parameter.
+ */
+export function splitParameter(
+  parameter: string,
+  specialCharacter: SPECIAL_CHARACTER
+): string[] {
+  const specialCharEg = new RegExp(`\\${specialCharacter}`, "g");
+  let prevIndex = -1;
+  const pieces = [];
+  let match;
+
+  while ((match = specialCharEg.exec(parameter))) {
+    if (match.index === 0 || parameter[match.index - 1] !== "\\") {
+      pieces.push(parameter.substring(prevIndex + 1, match.index));
+      prevIndex = match.index;
+    }
+  }
+  pieces.push(parameter.substring(prevIndex + 1));
+
+  return pieces.map(unescapeParameter);
+}
+
+/**
+ * Escapes a parameter values special characters
+ * Reference: https://hl7.org/fhir/R4/search.html#escaping
+ * @param parameter Parameter value to escape
+ * @returns Escaped Parameter
+ */
+export function escapeParameter(parameter: string): string {
+  return SPECIAL_CHARACTERS.reduce(
+    (parameter: string, character: string): string => {
+      return parameter.replaceAll(character, `\\${character}`);
+    },
+    parameter
+  );
+}
+
+/**
+ * Unescapes a parameter values special characters.
+ * Reference: https://hl7.org/fhir/R4/search.html#escaping
+ * @param parameter Escaped Parameter
+ * @returns Unescaped Parameter
+ */
+export function unescapeParameter(parameter: string): string {
+  return SPECIAL_CHARACTERS.reduce(
+    (parameter: string, character: string): string => {
+      return parameter.replaceAll(`\\${character}`, character);
+    },
+    parameter
+  );
+}
+
+export interface ParsedParameter<T> {
+  name: string;
+  value: T[];
+  modifier?: string;
+  chains?: string[];
+}
+
+export interface SearchParameterResource<Version extends FHIR_VERSION>
+  extends ParsedParameter<string | number> {
+  type: "resource";
+  searchParameter: Resource<Version, "SearchParameter">;
+  chainedParameters?: Resource<Version, "SearchParameter">[][];
+}
+
+export interface SearchParameterResult
+  extends ParsedParameter<string | number> {
+  type: "result";
+}
+
+export type MetaParameter<Version extends FHIR_VERSION> =
+  | SearchParameterResource<Version>
+  | SearchParameterResult;
+
+export type Parameters<Version extends FHIR_VERSION> =
+  | ParsedParameter<string | number>[]
+  | MetaParameter<Version>[];
+
+/**
+ * Given a query string create complex FHIR Query object.
+ * @param queryParams Raw query parameters pulled off url
+ * @returns Record of parsed parameters with name modifier and value.
+ */
+export function parseQuery(
+  queryParams: string | undefined
+): ParsedParameter<string>[] {
+  const parameters = !queryParams
+    ? []
+    : queryParams
+        .split("&")
+        .map((param) => param.split("="))
+        .reduce(
+          (
+            parameters,
+            [key, value]
+          ): Record<string, ParsedParameter<string>> => {
+            const chains = key.split(".");
+
+            const [name, modifier] = chains[0].split(":");
+
+            const searchParam: ParsedParameter<string> = {
+              name,
+              modifier,
+              value: value.split(",").map((v) => decodeURIComponent(v)),
+            };
+
+            if (chains.length > 1) searchParam.chains = chains.slice(1);
+            if (modifier) searchParam.modifier = modifier;
+
+            return { ...parameters, [searchParam.name]: searchParam };
+          },
+          {}
+        );
+
+  return Object.values(parameters);
+}
+
+/**
+ * Given a url string parsequery parameters.
+ * @param url Any url to parse out query parameters.
+ * @returns Record of parsed parameters with name modifier and value.
+ */
+export default function parseUrl(
+  url: string
+): ParsedParameter<string | number>[] {
+  const chunks = url.split("?");
+  if (chunks.length > 2)
+    throw new OperationError(outcomeError("invalid", "Invalid query string"));
+  const [_, queryParams] = chunks;
+  return parseQuery(queryParams);
+}