@fhir-dsl/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdelhadi Sabani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,160 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FhirError: () => FhirError,
+  FhirExecutor: () => FhirExecutor,
+  fetchAllPages: () => fetchAllPages,
+  paginate: () => paginate,
+  unwrapBundle: () => unwrapBundle
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var FhirError = class extends Error {
+  constructor(status, statusText, operationOutcome) {
+    const message = operationOutcome?.issue?.[0]?.diagnostics ?? operationOutcome?.issue?.[0]?.details?.text ?? `${status} ${statusText}`;
+    super(`FHIR Error: ${message}`);
+    this.status = status;
+    this.statusText = statusText;
+    this.operationOutcome = operationOutcome;
+    this.name = "FhirError";
+  }
+  status;
+  statusText;
+  operationOutcome;
+  get issues() {
+    return this.operationOutcome?.issue ?? [];
+  }
+};
+
+// src/executor.ts
+var FhirExecutor = class {
+  #config;
+  #fetch;
+  constructor(config) {
+    this.#config = config;
+    this.#fetch = config.fetch ?? globalThis.fetch;
+  }
+  async execute(query) {
+    const url = new URL(
+      query.path,
+      this.#config.baseUrl.endsWith("/") ? this.#config.baseUrl : `${this.#config.baseUrl}/`
+    );
+    for (const param of query.params) {
+      const value = param.prefix ? `${param.prefix}${param.value}` : String(param.value);
+      url.searchParams.append(param.name, value);
+    }
+    const headers = {
+      Accept: "application/fhir+json",
+      "Content-Type": "application/fhir+json",
+      ...this.#config.headers,
+      ...query.headers
+    };
+    if (this.#config.auth) {
+      const { type, credentials } = this.#config.auth;
+      headers.Authorization = type === "bearer" ? `Bearer ${credentials}` : `Basic ${credentials}`;
+    }
+    const response = await this.#fetch(url.toString(), {
+      method: query.method,
+      headers,
+      ...query.body ? { body: JSON.stringify(query.body) } : {}
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => null);
+      throw new FhirError(response.status, response.statusText, errorBody);
+    }
+    return response.json();
+  }
+  async executeUrl(url) {
+    const headers = {
+      Accept: "application/fhir+json",
+      ...this.#config.headers
+    };
+    if (this.#config.auth) {
+      const { type, credentials } = this.#config.auth;
+      headers.Authorization = type === "bearer" ? `Bearer ${credentials}` : `Basic ${credentials}`;
+    }
+    const response = await this.#fetch(url, { method: "GET", headers });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => null);
+      throw new FhirError(response.status, response.statusText, errorBody);
+    }
+    return response.json();
+  }
+};
+
+// src/pagination.ts
+async function* paginate(executor, firstBundle) {
+  let bundle = firstBundle;
+  while (bundle) {
+    const entries = bundle.entry ?? [];
+    const resources = entries.filter((e) => e.resource !== void 0).map((e) => e.resource);
+    if (resources.length > 0) {
+      yield resources;
+    }
+    const nextLink = bundle.link?.find((l) => l.relation === "next");
+    if (nextLink?.url) {
+      bundle = await executor.executeUrl(nextLink.url);
+    } else {
+      bundle = void 0;
+    }
+  }
+}
+async function fetchAllPages(executor, firstBundle) {
+  const all = [];
+  for await (const page of paginate(executor, firstBundle)) {
+    all.push(...page);
+  }
+  return all;
+}
+
+// src/result.ts
+function unwrapBundle(bundle) {
+  const entries = bundle.entry ?? [];
+  const data = [];
+  const included = [];
+  for (const entry of entries) {
+    if (!entry.resource) continue;
+    if (entry.search?.mode === "include") {
+      included.push(entry.resource);
+    } else {
+      data.push(entry.resource);
+    }
+  }
+  const nextLink = bundle.link?.find((l) => l.relation === "next");
+  return {
+    data,
+    included,
+    total: bundle.total,
+    hasNext: !!nextLink,
+    nextUrl: nextLink?.url,
+    raw: bundle
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FhirError,
+  FhirExecutor,
+  fetchAllPages,
+  paginate,
+  unwrapBundle
+});

package/dist/index.d.cts

@@ -0,0 +1,56 @@
+import { CompiledQuery } from '@fhir-dsl/core';
+import { Resource, Bundle } from '@fhir-dsl/types';
+
+interface FhirClientConfig {
+    baseUrl: string;
+    auth?: {
+        type: "bearer" | "basic";
+        credentials: string;
+    } | undefined;
+    headers?: Record<string, string> | undefined;
+    fetch?: typeof globalThis.fetch | undefined;
+}
+
+interface OperationOutcome {
+    resourceType: "OperationOutcome";
+    issue: OperationOutcomeIssue[];
+}
+interface OperationOutcomeIssue {
+    severity: "fatal" | "error" | "warning" | "information";
+    code: string;
+    details?: {
+        text?: string;
+    };
+    diagnostics?: string;
+    location?: string[];
+    expression?: string[];
+}
+declare class FhirError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly operationOutcome?: (OperationOutcome | null) | undefined;
+    constructor(status: number, statusText: string, operationOutcome?: (OperationOutcome | null) | undefined);
+    get issues(): OperationOutcomeIssue[];
+}
+
+declare class FhirExecutor {
+    #private;
+    constructor(config: FhirClientConfig);
+    execute<T = unknown>(query: CompiledQuery): Promise<T>;
+    executeUrl<T = unknown>(url: string): Promise<T>;
+}
+
+declare function paginate<T extends Resource>(executor: FhirExecutor, firstBundle: Bundle): AsyncGenerator<T[], void, undefined>;
+declare function fetchAllPages<T extends Resource>(executor: FhirExecutor, firstBundle: Bundle): Promise<T[]>;
+
+interface SearchResult<Primary extends Resource, Included extends Resource = never> {
+    data: Primary[];
+    included: [Included] extends [never] ? [] : Included[];
+    total?: number | undefined;
+    hasNext: boolean;
+    nextUrl?: string | undefined;
+    raw: Bundle;
+}
+declare function unwrapBundle<Primary extends Resource, Included extends Resource = never>(bundle: Bundle): SearchResult<Primary, Included>;
+
+export { type FhirClientConfig, FhirError, FhirExecutor, type OperationOutcome, type OperationOutcomeIssue, type SearchResult, fetchAllPages, paginate, unwrapBundle };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { CompiledQuery } from '@fhir-dsl/core';
+import { Resource, Bundle } from '@fhir-dsl/types';
+
+interface FhirClientConfig {
+    baseUrl: string;
+    auth?: {
+        type: "bearer" | "basic";
+        credentials: string;
+    } | undefined;
+    headers?: Record<string, string> | undefined;
+    fetch?: typeof globalThis.fetch | undefined;
+}
+
+interface OperationOutcome {
+    resourceType: "OperationOutcome";
+    issue: OperationOutcomeIssue[];
+}
+interface OperationOutcomeIssue {
+    severity: "fatal" | "error" | "warning" | "information";
+    code: string;
+    details?: {
+        text?: string;
+    };
+    diagnostics?: string;
+    location?: string[];
+    expression?: string[];
+}
+declare class FhirError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly operationOutcome?: (OperationOutcome | null) | undefined;
+    constructor(status: number, statusText: string, operationOutcome?: (OperationOutcome | null) | undefined);
+    get issues(): OperationOutcomeIssue[];
+}
+
+declare class FhirExecutor {
+    #private;
+    constructor(config: FhirClientConfig);
+    execute<T = unknown>(query: CompiledQuery): Promise<T>;
+    executeUrl<T = unknown>(url: string): Promise<T>;
+}
+
+declare function paginate<T extends Resource>(executor: FhirExecutor, firstBundle: Bundle): AsyncGenerator<T[], void, undefined>;
+declare function fetchAllPages<T extends Resource>(executor: FhirExecutor, firstBundle: Bundle): Promise<T[]>;
+
+interface SearchResult<Primary extends Resource, Included extends Resource = never> {
+    data: Primary[];
+    included: [Included] extends [never] ? [] : Included[];
+    total?: number | undefined;
+    hasNext: boolean;
+    nextUrl?: string | undefined;
+    raw: Bundle;
+}
+declare function unwrapBundle<Primary extends Resource, Included extends Resource = never>(bundle: Bundle): SearchResult<Primary, Included>;
+
+export { type FhirClientConfig, FhirError, FhirExecutor, type OperationOutcome, type OperationOutcomeIssue, type SearchResult, fetchAllPages, paginate, unwrapBundle };

package/dist/index.js

@@ -0,0 +1,129 @@
+// src/errors.ts
+var FhirError = class extends Error {
+  constructor(status, statusText, operationOutcome) {
+    const message = operationOutcome?.issue?.[0]?.diagnostics ?? operationOutcome?.issue?.[0]?.details?.text ?? `${status} ${statusText}`;
+    super(`FHIR Error: ${message}`);
+    this.status = status;
+    this.statusText = statusText;
+    this.operationOutcome = operationOutcome;
+    this.name = "FhirError";
+  }
+  status;
+  statusText;
+  operationOutcome;
+  get issues() {
+    return this.operationOutcome?.issue ?? [];
+  }
+};
+
+// src/executor.ts
+var FhirExecutor = class {
+  #config;
+  #fetch;
+  constructor(config) {
+    this.#config = config;
+    this.#fetch = config.fetch ?? globalThis.fetch;
+  }
+  async execute(query) {
+    const url = new URL(
+      query.path,
+      this.#config.baseUrl.endsWith("/") ? this.#config.baseUrl : `${this.#config.baseUrl}/`
+    );
+    for (const param of query.params) {
+      const value = param.prefix ? `${param.prefix}${param.value}` : String(param.value);
+      url.searchParams.append(param.name, value);
+    }
+    const headers = {
+      Accept: "application/fhir+json",
+      "Content-Type": "application/fhir+json",
+      ...this.#config.headers,
+      ...query.headers
+    };
+    if (this.#config.auth) {
+      const { type, credentials } = this.#config.auth;
+      headers.Authorization = type === "bearer" ? `Bearer ${credentials}` : `Basic ${credentials}`;
+    }
+    const response = await this.#fetch(url.toString(), {
+      method: query.method,
+      headers,
+      ...query.body ? { body: JSON.stringify(query.body) } : {}
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => null);
+      throw new FhirError(response.status, response.statusText, errorBody);
+    }
+    return response.json();
+  }
+  async executeUrl(url) {
+    const headers = {
+      Accept: "application/fhir+json",
+      ...this.#config.headers
+    };
+    if (this.#config.auth) {
+      const { type, credentials } = this.#config.auth;
+      headers.Authorization = type === "bearer" ? `Bearer ${credentials}` : `Basic ${credentials}`;
+    }
+    const response = await this.#fetch(url, { method: "GET", headers });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => null);
+      throw new FhirError(response.status, response.statusText, errorBody);
+    }
+    return response.json();
+  }
+};
+
+// src/pagination.ts
+async function* paginate(executor, firstBundle) {
+  let bundle = firstBundle;
+  while (bundle) {
+    const entries = bundle.entry ?? [];
+    const resources = entries.filter((e) => e.resource !== void 0).map((e) => e.resource);
+    if (resources.length > 0) {
+      yield resources;
+    }
+    const nextLink = bundle.link?.find((l) => l.relation === "next");
+    if (nextLink?.url) {
+      bundle = await executor.executeUrl(nextLink.url);
+    } else {
+      bundle = void 0;
+    }
+  }
+}
+async function fetchAllPages(executor, firstBundle) {
+  const all = [];
+  for await (const page of paginate(executor, firstBundle)) {
+    all.push(...page);
+  }
+  return all;
+}
+
+// src/result.ts
+function unwrapBundle(bundle) {
+  const entries = bundle.entry ?? [];
+  const data = [];
+  const included = [];
+  for (const entry of entries) {
+    if (!entry.resource) continue;
+    if (entry.search?.mode === "include") {
+      included.push(entry.resource);
+    } else {
+      data.push(entry.resource);
+    }
+  }
+  const nextLink = bundle.link?.find((l) => l.relation === "next");
+  return {
+    data,
+    included,
+    total: bundle.total,
+    hasNext: !!nextLink,
+    nextUrl: nextLink?.url,
+    raw: bundle
+  };
+}
+export {
+  FhirError,
+  FhirExecutor,
+  fetchAllPages,
+  paginate,
+  unwrapBundle
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@fhir-dsl/runtime",
+  "version": "0.1.0",
+  "description": "Runtime execution layer for FHIR DSL queries with pagination and error handling",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@fhir-dsl/core": "0.1.0",
+    "@fhir-dsl/types": "0.1.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "Abdelhadi Sabani",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abellaismail7/fhir-dsl.git",
+    "directory": "packages/runtime"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "fhir",
+    "runtime",
+    "typescript",
+    "healthcare"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsup --watch"
+  }
+}