Skip to content

Commit f609126

Browse files
dnlboxdnlbox
authored
feat: add bundle recipes (#9)
Add a public recipe API and CLI --recipe support so users can generate deterministic, pipeline-oriented Bundle fixtures from YAML or JSON recipes.
1 parent 20e7596 commit f609126

12 files changed

Lines changed: 1086 additions & 4 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [Unreleased]
9+
10+
### Added
11+
12+
- Bundle recipes: `generate bundle --recipe <file>` now accepts user-defined YAML or JSON recipes for deterministic, pipeline-oriented Bundle generation. Recipes define ordered resources, aliases, field overrides, and reference wiring while keeping clinical meaning user-owned.
13+
- Public recipe API: `createBundleFromRecipe(recipe, options)` plus exported recipe types.
14+
- Starter recipe examples under `examples/recipes/` for lab result, condition plus medication, and diagnostic workup bundle shapes.
15+
816
## [0.2.0] - 2026-06-01
917

1018
### Added

‎README.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,81 @@ const [bundle] = createBundleBuilder()
172172

173173
Each bundle includes: Patient, Organization, Practitioner, PractitionerRole, and N clinical resources (Observations, Conditions, AllergyIntolerance, MedicationStatement). All internal references are consistent: `Observation.subject` points to the Patient, `Observation.performer[0]` to the Practitioner, and `Patient.managingOrganization` to the Organization.
174174

175+
## Bundle recipes
176+
177+
For pipeline tests that need a specific bundle shape, define a user-owned YAML or JSON recipe:
178+
179+
```bash
180+
fhir-test-data generate bundle --recipe ./lab-result-basic.yaml --seed 42
181+
```
182+
183+
Recipes are composition rules, not clinical scenario models. The user chooses the resource mix, codes, values, and reference graph; `fhir-test-data` handles deterministic generation, FHIR resource builders, deep-merged field overrides, and reference wiring.
184+
185+
```yaml
186+
name: lab-result-basic
187+
locale: uk
188+
fhirVersion: R4
189+
bundle:
190+
type: transaction
191+
resources:
192+
- type: Patient
193+
id: patient
194+
- type: Encounter
195+
id: encounter
196+
fields:
197+
subject: patient
198+
- type: Observation
199+
id: hba1c
200+
fields:
201+
subject: patient
202+
encounter: encounter
203+
category:
204+
- coding:
205+
- system: http://terminology.hl7.org/CodeSystem/observation-category
206+
code: laboratory
207+
display: Laboratory
208+
code:
209+
coding:
210+
- system: http://loinc.org
211+
code: "4548-4"
212+
display: HbA1c
213+
valueQuantity:
214+
value: 7.2
215+
unit: "%"
216+
system: http://unitsofmeasure.org
217+
code: "%"
218+
- type: DiagnosticReport
219+
id: report
220+
fields:
221+
subject: patient
222+
encounter: encounter
223+
category:
224+
- coding:
225+
- system: http://terminology.hl7.org/CodeSystem/v2-0074
226+
code: LAB
227+
display: Laboratory
228+
code:
229+
coding:
230+
- system: http://loinc.org
231+
code: "55454-3"
232+
display: Hemoglobin A1c in Blood
233+
result:
234+
- hba1c
235+
```
236+
237+
Recipe fields are deep-merged into generated resources. Reference fields such as `subject`, `encounter`, `performer`, `result`, `organization`, and `practitioner` can use recipe aliases. CLI flags override recipe defaults:
238+
239+
```bash
240+
fhir-test-data generate bundle --recipe ./lab-result-basic.yaml \
241+
--locale us --fhir-version R5 --count 2 --seed 42
242+
```
243+
244+
Starter recipes are published under `examples/recipes/`:
245+
246+
- `lab-result-basic.yaml`
247+
- `condition-medication-basic.yaml`
248+
- `diagnostic-workup-basic.yaml`
249+
175250
---
176251

177252
## Fault injection

‎examples/recipes/condition-medication-basic.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: condition-medication-basic
2+
locale: us
3+
fhirVersion: R4
4+
bundle:
5+
type: transaction
6+
resources:
7+
- type: Patient
8+
id: patient
9+
- type: Condition
10+
id: condition
11+
fields:
12+
subject: patient
13+
code:
14+
coding:
15+
- system: http://snomed.info/sct
16+
code: "38341003"
17+
display: Hypertension
18+
text: Hypertension
19+
- type: MedicationStatement
20+
id: medication
21+
fields:
22+
subject: patient
23+
medicationCodeableConcept:
24+
coding:
25+
- system: http://www.nlm.nih.gov/research/umls/rxnorm
26+
code: "197361"
27+
display: Amlodipine 5 MG Oral Tablet
28+
text: Amlodipine 5 MG Oral Tablet
29+
dosage:
30+
- text: 5 mg daily

‎examples/recipes/diagnostic-workup-basic.yaml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: diagnostic-workup-basic
2+
locale: us
3+
fhirVersion: R4
4+
bundle:
5+
type: transaction
6+
resources:
7+
- type: Patient
8+
id: patient
9+
- type: Practitioner
10+
id: practitioner
11+
- type: Organization
12+
id: organization
13+
- type: Encounter
14+
id: encounter
15+
fields:
16+
subject: patient
17+
- type: Observation
18+
id: vital-sign
19+
fields:
20+
subject: patient
21+
encounter: encounter
22+
performer:
23+
- practitioner
24+
category:
25+
- coding:
26+
- system: http://terminology.hl7.org/CodeSystem/observation-category
27+
code: vital-signs
28+
display: Vital Signs
29+
code:
30+
coding:
31+
- system: http://loinc.org
32+
code: "8480-6"
33+
display: Systolic blood pressure
34+
text: Systolic blood pressure
35+
valueQuantity:
36+
value: 142
37+
unit: mmHg
38+
system: http://unitsofmeasure.org
39+
code: mm[Hg]
40+
- type: DiagnosticReport
41+
id: report
42+
fields:
43+
subject: patient
44+
encounter: encounter
45+
performer:
46+
- practitioner
47+
category:
48+
- coding:
49+
- system: http://terminology.hl7.org/CodeSystem/v2-0074
50+
code: LAB
51+
display: Laboratory
52+
code:
53+
coding:
54+
- system: http://loinc.org
55+
code: "85354-9"
56+
display: Blood pressure panel with all children optional
57+
text: Blood pressure panel
58+
result:
59+
- vital-sign

‎examples/recipes/lab-result-basic.yaml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: lab-result-basic
2+
locale: us
3+
fhirVersion: R4
4+
bundle:
5+
type: transaction
6+
resources:
7+
- type: Patient
8+
id: patient
9+
- type: Encounter
10+
id: encounter
11+
fields:
12+
subject: patient
13+
- type: Observation
14+
id: lab-result
15+
fields:
16+
subject: patient
17+
encounter: encounter
18+
category:
19+
- coding:
20+
- system: http://terminology.hl7.org/CodeSystem/observation-category
21+
code: laboratory
22+
display: Laboratory
23+
code:
24+
coding:
25+
- system: http://loinc.org
26+
code: "4548-4"
27+
display: HbA1c
28+
text: HbA1c
29+
valueQuantity:
30+
value: 7.2
31+
unit: "%"
32+
system: http://unitsofmeasure.org
33+
code: "%"
34+
- type: DiagnosticReport
35+
id: report
36+
fields:
37+
subject: patient
38+
encounter: encounter
39+
category:
40+
- coding:
41+
- system: http://terminology.hl7.org/CodeSystem/v2-0074
42+
code: LAB
43+
display: Laboratory
44+
code:
45+
coding:
46+
- system: http://loinc.org
47+
code: "55454-3"
48+
display: Hemoglobin A1c in Blood
49+
text: Hemoglobin A1c in Blood
50+
result:
51+
- lab-result

‎package.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
},
3535
"files": [
3636
"dist/",
37+
"examples/",
3738
"README.md",
3839
"LICENSE"
3940
],
@@ -71,9 +72,11 @@
7172
"prepublishOnly": "pnpm build && pnpm typecheck && pnpm test"
7273
},
7374
"dependencies": {
74-
"commander": "^15.0.0"
75+
"commander": "^15.0.0",
76+
"js-yaml": "^4.1.1"
7577
},
7678
"devDependencies": {
79+
"@types/js-yaml": "^4.0.9",
7780
"@types/node": "^24.12.4",
7881
"@typescript-eslint/eslint-plugin": "^8.59.4",
7982
"@typescript-eslint/parser": "^8.59.4",

‎pnpm-lock.yaml‎

Lines changed: 6 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)