@reasonhealth/fhir-zod 1.0.0 → 1.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@reasonhealth/fhir-zod)](https://www.npmjs.com/package/@reasonhealth/fhir-zod)
 
-Zod schemas for FHIR R4, R4B, and R5. Generated from official FHIR StructureDefinition packages via [`@reasonhealth/fhir-ts-codegen`](../fhir-ts-codegen).
+Zod schemas for FHIR R4, R4B, and R5. Generated from official FHIR StructureDefinition packages via [`@reasonhealth/fhir-ts-codegen`](https://github.com/reason-healthcare/fhir-types-workspace/tree/main/packages/fhir-ts-codegen).
 
 ## Installation
 
@@ -38,8 +38,6 @@ import { PatientSchema } from '@reasonhealth/fhir-zod/r4'
 type Patient = z.infer<typeof PatientSchema>
 ```
 
-See [EXAMPLES.md](./EXAMPLES.md) for more usage patterns.
-
 ### Available entry points
 
 | Import | FHIR Version |
@@ -53,6 +51,82 @@ Every schema file exports:
 - A `*Schema` constant for each FHIR type (e.g. `PatientSchema`, `BundleSchema`)
 - An inferred TypeScript `type` for each schema (e.g. `type Patient = z.infer<typeof PatientSchema>`)
 
+## Examples
+
+### Safe parse with error handling
+
+```ts
+import { ObservationSchema } from '@reasonhealth/fhir-zod/r4'
+
+const result = ObservationSchema.safeParse(raw)
+if (!result.success) {
+  console.error('Invalid Observation:', result.error.flatten())
+} else {
+  console.log('Status:', result.data.status)
+}
+```
+
+### Infer types from schemas
+
+```ts
+import { z } from 'zod'
+import { PatientSchema, BundleSchema } from '@reasonhealth/fhir-zod/r4'
+
+type Patient = z.infer<typeof PatientSchema>
+type Bundle  = z.infer<typeof BundleSchema>
+```
+
+### Using with `@types/fhir`
+
+`@types/fhir` provides ambient namespace types (`fhir4.Patient`, etc.). Build a type-guard that bridges the two:
+
+```ts
+import { PatientSchema } from '@reasonhealth/fhir-zod/r4'
+
+function isPatient(resource: fhir4.Resource): resource is fhir4.Patient {
+  return PatientSchema.safeParse(resource).success
+}
+```
+
+### Bundle unpacking
+
+```ts
+import { BundleSchema, PatientSchema } from '@reasonhealth/fhir-zod/r4'
+
+const bundle = BundleSchema.parse(raw)
+const patients = (bundle.entry ?? [])
+  .map(e => e.resource)
+  .filter(r => r?.resourceType === 'Patient')
+  .map(r => PatientSchema.parse(r))
+```
+
+### Discriminated union
+
+```ts
+import { z } from 'zod'
+import { PatientSchema, PractitionerSchema, OrganizationSchema } from '@reasonhealth/fhir-zod/r4'
+
+const SubjectSchema = z.discriminatedUnion('resourceType', [
+  PatientSchema,
+  PractitionerSchema,
+  OrganizationSchema,
+])
+
+type Subject = z.infer<typeof SubjectSchema>
+```
+
+### Extend or restrict for profiles
+
+```ts
+import { PatientSchema } from '@reasonhealth/fhir-zod/r4'
+
+const PatientSummarySchema = PatientSchema.pick({ id: true, name: true, birthDate: true })
+
+const IdentifiedPatientSchema = PatientSchema.extend({
+  id: PatientSchema.shape.id.unwrap(), // make id required
+})
+```
+
 ## What's generated
 
 Notable schema features:

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "@reasonhealth/fhir-zod",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Zod schemas for FHIR R4, R4B, R5",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/reason-healthcare/fhir-types-workspace.git",
+    "directory": "packages/fhir-zod"
+  },
+  "homepage": "https://github.com/reason-healthcare/fhir-types-workspace/tree/main/packages/fhir-zod#readme",
+  "bugs": {
+    "url": "https://github.com/reason-healthcare/fhir-types-workspace/issues"
+  },
   "exports": {
     "./r4": "./src/r4.ts",
     "./r4b": "./src/r4b.ts",