Merge pull request #150 from Max-Health-Inc/develop

🚀 Promote develop → main

Author: quotentiroler

.github/workflows/ci.yml

@@ -46,3 +46,34 @@ jobs:
       - name: Report newer IG releases
         run: npm run check:ig-versions
         continue-on-error: true
+
+  # The published packages under packages/ were only compiled at release time, so a
+  # type error in scripts/client-codegen/template reached npm before anything ran
+  # tsc over it. The drift check above proves the copies match the template; this
+  # proves the template itself compiles and its tests pass.
+  packages:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        package: [client-r4, client-r4b, client-r5, dicomweb, oauth-crypto, smart-auth, zod]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      # The packages resolve @max-health-inc/config (their vitest preset) from the
+      # repo root, so the root install has to happen before the package's own tests.
+      - run: npm ci
+
+      - run: npm ci
+        working-directory: packages/${{ matrix.package }}
+
+      - run: npm run build
+        working-directory: packages/${{ matrix.package }}
+
+      - run: npm run test --if-present
+        working-directory: packages/${{ matrix.package }}

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "babelfhir-ts",
-  "version": "1.6.1",
+  "version": "1.6.2-dev.20260808230507.48274f8c",
   "description": "BabelFHIR-TS: generate TypeScript interfaces, validators, and helper classes from FHIR R4/R4B/R5 StructureDefinitions (profiles) directly inside package archives.",
   "type": "module",
   "main": "out/src/main.js",

package.json

@@ -72,12 +72,45 @@ const patient = await client.patient().read('example');
 ### Bundle Parsing
 
 ```ts
-import { BundleParser } from '@babelfhir-ts/client-r4';
+import { BundleParser, hasId } from '@babelfhir-ts/client-r4';
 
-const patients = BundleParser.getResourcesByType<fhir4.Patient>(bundle, 'Patient');
-const first = BundleParser.getFirstResourceByType<fhir4.Patient>(bundle, 'Patient');
+// A searchset keeps the type the reader already knew.
+const searchset = await client.read().patient().search({ name: 'Smith' }); // Bundle<WithId<fhir4.Patient>>
+const all = BundleParser.getAllResources(searchset); // WithId<fhir4.Patient>[]
+
+// On a mixed bundle the return type follows the resourceType argument — no type argument, no cast.
+const patients = BundleParser.getResourcesByType(bundle, 'Patient'); // fhir4.Patient[]
+const first = BundleParser.getFirstResourceByType(bundle, 'Observation'); // fhir4.Observation | undefined
+
+// `id` is optional in FHIR, so narrow to it explicitly where it is required.
+const identified = patients.filter(hasId); // WithId<fhir4.Patient>[]
+
+// References resolve to the bundle's element type, or to a checked resourceType.
+const subject = BundleParser.resolveReferenceOfType(obs.subject, bundle, 'Patient');
+```
+
+Pass an explicit type argument for profile types from other generated packages —
+`resourceType` is then constrained to that type's own discriminant:
+
+```ts
+BundleParser.getResourcesByType<USCorePatientProfile>(bundle, 'Patient');
 ```
 
+### Migrating to 0.3
+
+`BundleParser` no longer returns types it has not checked, so code written against
+0.2 can see new compile errors:
+
+- `getResourcesByType` and `getFirstResourceByType` return `T` instead of
+  `WithId<T>`. `id` is optional in FHIR and was never verified, so add
+  `.filter(hasId)` where the guarantee is needed.
+- `resourceType` is checked against the FHIR resource type union, which turns a
+  typo into a compile error. A value chosen at runtime should be typed
+  `FhirResourceType` rather than `string`.
+- `resolveReference` takes its return type from the bundle. To narrow a mixed
+  bundle, call `resolveReferenceOfType(ref, bundle, 'Patient')`, which returns
+  `undefined` when the reference resolves to another resource type.
+
 ## API
 
 | Export | Description |
@@ -87,6 +120,8 @@ const first = BundleParser.getFirstResourceByType<fhir4.Patient>(bundle, 'Patien
 | `FhirClient` | Combined read + write client |
 | `SmartFhirClient` | SMART-authenticated FHIR client |
 | `BundleParser` | Static bundle extraction helpers |
+| `hasId` | Type guard narrowing a resource to `WithId<T>` |
+| `FhirResourceType` / `ResourceOfType` | The `resourceType` union, and the resource behind one of its members |
 | `SmartAuth` | SMART on FHIR v2 authorization (re-exported from `@babelfhir-ts/smart-auth`) |
 | `discoverEndpoints` | SMART endpoint discovery |
 

packages/client-r4/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@babelfhir-ts/client-r4",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Typed FHIR R4 client with read/write/search methods for all 145 base resource types, SMART on FHIR auth, and bundle parsing",
   "type": "module",
   "main": "dist/index.js",

packages/client-r4/package-lock.json

@@ -3,7 +3,8 @@
 
 import { describe, it, expect } from "vitest";
 import { BundleParser } from "./bundle-parser.js";
-import type { Bundle } from "./types.js";
+import { hasId } from "./types.js";
+import type { Bundle, WithId } from "./types.js";
 
 describe("BundleParser", () => {
   const patient1 = { resourceType: "Patient" as const, id: "1", name: [{ family: "Smith" }] };
@@ -22,14 +23,14 @@ describe("BundleParser", () => {
 
   describe("getResourcesByType", () => {
     it("filters resources by resourceType", () => {
-      const patients = BundleParser.getResourcesByType<fhir4.Patient>(bundle, "Patient");
+      const patients = BundleParser.getResourcesByType(bundle, "Patient");
       expect(patients).toHaveLength(2);
-      expect(patients[0].id).toBe("1");
-      expect(patients[1].id).toBe("2");
+      expect(patients[0]?.id).toBe("1");
+      expect(patients[1]?.id).toBe("2");
     });
 
     it("returns empty array for non-matching type", () => {
-      const conditions = BundleParser.getResourcesByType<fhir4.Condition>(bundle, "Condition");
+      const conditions = BundleParser.getResourcesByType(bundle, "Condition");
       expect(conditions).toEqual([]);
     });
 
@@ -46,11 +47,27 @@ describe("BundleParser", () => {
       };
       expect(BundleParser.getResourcesByType(noRes, "Patient")).toEqual([]);
     });
+
+    it("keeps resources that have no id, and hasId drops them", () => {
+      const posting: Bundle<fhir4.Resource> = {
+        resourceType: "Bundle",
+        type: "transaction",
+        entry: [
+          { resource: { resourceType: "Patient" } as fhir4.Resource, request: { method: "POST", url: "Patient" } },
+          { resource: patient1 as fhir4.Resource },
+        ],
+      };
+      expect(BundleParser.getResourcesByType(posting, "Patient")).toHaveLength(2);
+
+      const withIds: WithId<fhir4.Patient>[] = BundleParser.getResourcesByType(posting, "Patient").filter(hasId);
+      expect(withIds).toHaveLength(1);
+      expect(withIds[0]?.id).toBe("1");
+    });
   });
 
   describe("getFirstResourceByType", () => {
     it("returns first matching resource", () => {
-      const first = BundleParser.getFirstResourceByType<fhir4.Patient>(bundle, "Patient");
+      const first = BundleParser.getFirstResourceByType(bundle, "Patient");
       expect(first?.id).toBe("1");
     });
 
@@ -65,6 +82,17 @@ describe("BundleParser", () => {
       expect(all).toHaveLength(3);
     });
 
+    it("preserves the bundle's element type", () => {
+      const searchset: Bundle<WithId<fhir4.Patient>> = {
+        resourceType: "Bundle",
+        type: "searchset",
+        entry: [{ resource: patient1 }, { resource: patient2 }],
+      };
+      // No cast: what the reader knew is what comes back.
+      const patients: WithId<fhir4.Patient>[] = BundleParser.getAllResources(searchset);
+      expect(patients.map(p => p.id)).toEqual(["1", "2"]);
+    });
+
     it("returns empty array for empty bundle", () => {
       const empty: Bundle<fhir4.Resource> = { resourceType: "Bundle", type: "searchset" };
       expect(BundleParser.getAllResources(empty)).toEqual([]);
@@ -96,26 +124,23 @@ describe("BundleParser", () => {
     };
 
     it("resolves by exact fullUrl match", () => {
-      const result = BundleParser.resolveReference<fhir4.Patient>(
+      const result = BundleParser.resolveReference(
         { reference: "https://fhir.example.com/Patient/1" },
         bundleWithFullUrls,
       );
       expect(result?.id).toBe("1");
     });
 
     it("resolves by urn:uuid fullUrl match", () => {
-      const result = BundleParser.resolveReference<fhir4.Patient>(
+      const result = BundleParser.resolveReference(
         { reference: "urn:uuid:abc-123" },
         bundleWithFullUrls,
       );
       expect(result?.id).toBe("2");
     });
 
     it("resolves by ResourceType/id relative reference", () => {
-      const result = BundleParser.resolveReference<fhir4.Patient>(
-        { reference: "Patient/1" },
-        bundleWithFullUrls,
-      );
+      const result = BundleParser.resolveReference({ reference: "Patient/1" }, bundleWithFullUrls);
       expect(result?.id).toBe("1");
     });
 
@@ -127,10 +152,7 @@ describe("BundleParser", () => {
           { fullUrl: "https://fhir.example.com/Patient/99", resource: { resourceType: "Patient" } as fhir4.Resource },
         ],
       };
-      const result = BundleParser.resolveReference<fhir4.Patient>(
-        { reference: "Patient/99" },
-        bundleNoId,
-      );
+      const result = BundleParser.resolveReference({ reference: "Patient/99" }, bundleNoId);
       expect(result?.resourceType).toBe("Patient");
     });
 
@@ -151,5 +173,47 @@ describe("BundleParser", () => {
         bundleWithFullUrls,
       )).toBeUndefined();
     });
+
+    it("preserves the bundle's element type", () => {
+      const searchset: Bundle<WithId<fhir4.Patient>> = {
+        resourceType: "Bundle",
+        type: "searchset",
+        entry: [{ fullUrl: "https://fhir.example.com/Patient/1", resource: patient1 }],
+      };
+      const resolved: WithId<fhir4.Patient> | undefined = BundleParser.resolveReference(
+        { reference: "Patient/1" },
+        searchset,
+      );
+      expect(resolved?.id).toBe("1");
+    });
+  });
+
+  describe("resolveReferenceOfType", () => {
+    const bundleWithFullUrls: Bundle<fhir4.Resource> = {
+      resourceType: "Bundle",
+      type: "searchset",
+      entry: [
+        { fullUrl: "https://fhir.example.com/Patient/1", resource: patient1 as fhir4.Resource },
+        { fullUrl: "https://fhir.example.com/Observation/obs-1", resource: observation as fhir4.Resource },
+      ],
+    };
+
+    it("resolves a reference of the requested type", () => {
+      const result = BundleParser.resolveReferenceOfType(
+        { reference: "Patient/1" },
+        bundleWithFullUrls,
+        "Patient",
+      );
+      expect(result?.id).toBe("1");
+    });
+
+    it("returns undefined when the reference resolves to another type", () => {
+      const result = BundleParser.resolveReferenceOfType(
+        { reference: "https://fhir.example.com/Observation/obs-1" },
+        bundleWithFullUrls,
+        "Patient",
+      );
+      expect(result).toBeUndefined();
+    });
   });
 });