fix(client): stop BundleParser handing back types it never checked

FhirResourceReader.search() already returns Bundle<WithId<T>>, and every
BundleParser method threw that away, so callers cast back to what they
started with. Three defects, one template, so r4/r4b/r5 are fixed together.

- getAllResources is generic in the bundle's element type, so a searchset
  comes back as what the reader knew instead of widening to Resource[].
- The resourceType argument is checked against the FHIR resourceType union:
  a typo, or a type argument that disagrees with it, is now a compile error
  instead of an empty array typed as the resource that was asked for.
- Nothing promises WithId any more. id is optional in FHIR (contained
  resources and POST bundle entries have none) and was never verified, so
  the promise moved into the hasId guard, which callers chain where the
  guarantee is needed.
- resolveReference takes its return type from the bundle rather than
  asserting one; resolveReferenceOfType narrows a mixed bundle by a checked
  resourceType and returns undefined when the reference resolves elsewhere.

reader.ts loses the two casts that repeated the same pattern on values the
bundle type already described.

Breaking for consumers of the 0.2 line, so the three packages go to 0.3.0
and each README carries the migration.

CI now builds and tests every package under packages/. They were compiled
only at release time, so a type error in the template reached npm before
anything ran tsc over it.

Closes #149

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 }}

packages/client-r4/README.md

@@ -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/package-lock.json

@@ -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.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();
+    });
   });
 });