This mono-repository (Paqrat76/ts-fhir-datamodels) includes a code generator for generating TypeScript FHIR data models from FHIR artifacts. These generated data models are intended to be used by FHIR developers in their Node.js FHIR applications.
The HAPI FHIR ecosystem (implemented in Java) includes data model classes representing FHIR resources and data types. These data model classes include a number of getters and setters for the basic properties of that data model along with many convenience methods. These HAPI FHIR data models provided the inspiration for the design of the data models generated by this project.
A proof-of-concept (POC) project was undertaken to arrive at a design for TypeScript that could easily be applied to generated data models. This POC project resulted in contents for a core library that contains the base data models, implementations of the FHIR primitive data types, and various utilities required by the data models. Additionally, a set of implementation patterns were identified to facilitate code generation of data models for resources and complex data types.
This project is a mono-repository containing two types of NPM workspaces.
The app workspaces contain the code generator project and a project used to perform functional testing of a specific
set of generated data models.
The packages workspaces contain a project for a FHIR Core library used by all generated data model projects.
It also contains projects for each of the FHIR release-specific (FHIR R4 and later versions) generated data models.
app WorkspacesThe generator project contains the code generator for generating TypeScript FHIR data models.
This generator is not published or used independently.
It is intended to be executed from NPM scripts in the root package.json to generate TypeScript classes representing
FHIR data models for FHIR resources, complex data types, and selected code systems.
These generated TypeScript classes along with the @paq-ts-fhir/fhir-core library will be published as public NPM
libraries for each supported FHIR release (i.e., R4, R4B, R5; R6 when released).
The generator-datamodel-ftest project provides the capability to functionally test a well-defined set of generated
data models.
It is intended to simulate the production projects for generated FHIR data models.
Code patterns were identified and applied to the Handlebars templates used in the generator project.
Testing these code patterns is necessary to ensure generated code works as expected.
To test all of these code patterns, two custom FHIR StructureDefinitions were created to define custom FHIR
resources that contain all the possible patterns.
These two custom FHIR StructureDefinitions are consumed by the generator to generate their associated
data models (TestModel and SimplePersonModel).
These custom-generated data models are only used to perform a comprehensive set of functional tests to verify the
patterns used to create the data models result is correct code.
These custom resource data models make use of standard FHIR data types and reference standard FHIR resources.
The primitive FHIR data types are defined in @paq-ts-fhir/fhir-core.
The related complex FHIR data types are generated along with the related FHIR resources.
A separate FHIR cache (.fhir) was created in test/ftest-cache/.fhir to contain the two custom FHIR
resources along with all dependent FHIR resources and complex types.
Additionally, ValueSets and CodeSystems required to generate the pseudo-enum classes for those used by
the code primitive data type having a "required" ValueSet binding are included in this FHIR cache.
packages WorkspacesThe @paq-ts-fhir/fhir-core package is a TypeScript library providing common base data models, primitive FHIR data
types, custom errors, and various utilities required by the FHIR release-specific generated data model packages.
This package is the sole dependency of the FHIR release-specific generated data model packages.
This package's only dependencies are the Luxon and
Zod libraries.
The FHIR Core library is not designed or intended for general use in any other context.
Separate projects under the packages directory contain the FHIR release-specific generated data models
(e.g., @paq-ts-fhir/r4-datamodels).
The projects contain the generated data models for all FHIR release-specific resources and complex types along with the
"pseudo-enum" classes for a related set of FHIR CodeSystems.
These packages are published to NPM as public libraries.
Because the FHIR data models are created from a code generator, the only time these projects will need to be re-generated
is to fix bugs or add new features.
These generated data models are dependent on the FHIR Core library (i.e., @paq-ts-fhir/fhir-core) and the generator
project (i.e., generator) used to generate them.
Bugs in the FHIR Core library can typically be resolved by making the fix and releasing a new version of the
@paq-ts-fhir/fhir-core package with an updated patch-level version number.
This does not require a new release of the generated data models because the generated data model packages depend on
the @paq-ts-fhir/fhir-core package using a patch-level dependency (e.g., ~1.2.3).
Bugs in the generated data model code will require a fix within the generator project resulting in changes to the
generated data model code.
To fix these bugs, the generator project will need to be updated to fix the bug in the generated code and then the
generated data models will need to be regenerated.
This will requires a new release of the generated data model projects.
As long as these changes are backwards compatible, the new release of the generated data models will update the data
models projects version number to a new minor-level version number.
The above process can also be used to add new non-breaking features to the generated data models.
While this should never happen, any bug fix or the addition of a new feature that causes a breaking change to the generated data models will require a new release of the generated data model projects. These new releases will require a new major-level version number change.
Any changes to data model packages requiring a new minor-level or major-level version number change will also require an update to the generated documentation site.
Release Notes are available for all published FHIR data model libraries.