Merge branch 'feature/LF-2295/option-to-export-as-ES-modules' into 'master'

Add ES module support alongside CommonJS

See merge request lfor/fhirpath.js!66

Author: yuriy-sedinkin

.gitignore

@@ -3,6 +3,7 @@ node_modules
 downloads
 src/scratch.js
 build
+/esm/
 .DS_Store
 .editorconfig
 .codex

CHANGELOG.md

@@ -3,7 +3,7 @@
 This log documents significant changes for each release.  This project follows
 [Semantic Versioning](http://semver.org/).
 
-## [5.0.0] - 2026-06-18
+## [5.0.0] - 2026-07-13
 ### Added
 - Added support for FHIRPath Instance Selector/Object Creation syntax for
   constructing FHIR instances, including nested objects, primitive values,
@@ -13,6 +13,31 @@ This log documents significant changes for each release.  This project follows
   `ResourceNode` and `FP_Type` results.
 - Added `path2Repeating` to FHIR model contexts for repeatability-aware object
   construction.
+- ES module entry points so `fhirpath` and its `fhir-context/*` models load
+  with `import` (default and named exports) as well as `require`; a
+  `package.json` `exports` map, `module` field, and `.d.mts` declarations
+  route ES module and CommonJS consumers to the matching code and types.
+  - Documented entry points (`fhirpath`, `fhirpath/fhir-context/<version>`,
+    and `fhirpath/package.json`) are unchanged, and a wildcard fallback keeps
+    other deep file-path imports working. Because the package now declares
+    `exports`, those deep imports must include the file extension (e.g.
+    `fhirpath/fhir-context/r4/index.js`); extensionless deep paths that
+    previously resolved via Node's directory/extension lookup no longer do.
+  - The `import` build is a pre-bundled, self-contained ES module
+    (`esm/fhirpath.mjs`) that inlines the CommonJS dependencies (`antlr4`,
+    `date-fns`, `decimal.js`, `@lhncbc/ucum-lhc`, and `@loxjs/url-join`), so
+    esbuild-based bundlers (e.g. the Angular CLI) no longer emit
+    "optimization bailout" warnings; the `require` entry point is unchanged.
+  - `import` and `require` load separate copies of the library, so an
+    application should not mix them for the same package — values from one
+    are not `instanceof`-compatible with the other.
+- Type declarations for the exported `util` helpers and the `ucumUtils`
+  instance, so their named (and default-export) usages are typed for both ES
+  module and CommonJS consumers.
+- Explicit type exports for `Model`, `ResourceNode`, `Options`,
+  `OptionVariants`, `Path`, and `UserInvocationTable`, so consumers can import
+  and reference these types by name (e.g.
+  `import type { OptionVariants } from 'fhirpath'`).
 
 ### Changed
 - Raw internal `ResourceNode` output now represents absent `_data` as `null` and

README.md

@@ -30,12 +30,42 @@ Try it out on the [demo page](https://hl7.github.io/fhirpath.js/).
 npm install --save fhirpath
 ```
 
+The library ships both CommonJS and ES module entry points.
+
+For CommonJS:
 ```js
 const fhirpath = require('fhirpath');
 // For FHIR model data (choice type support) pull in the model file:
 const fhirpath_r4_model = require('fhirpath/fhir-context/r4');
 ```
 
+For ESM:
+```js
+import fhirpath from 'fhirpath';
+// Named exports are also available, e.g. `import { evaluate } from 'fhirpath'`.
+// For FHIR model data (choice type support) pull in the model file:
+import fhirpath_r4_model from 'fhirpath/fhir-context/r4';
+```
+
+The `import` entry point resolves to a pre-bundled, self-contained ES module
+that inlines fhirpath's CommonJS dependencies. This means bundlers such as
+esbuild (used by the Angular CLI) will not emit "CommonJS or AMD dependencies
+can cause optimization bailouts" warnings for fhirpath.
+
+Do not mix `require('fhirpath')` and `import 'fhirpath'` for the same package
+within a single application. The `import` entry point is a self-contained
+bundle with its own copy of the library and its dependencies, so values created
+via one entry point (e.g. `FP_Decimal` or other internal type instances) are
+not `instanceof`-compatible with the other, and helpers such as `ucumUtils`
+would be duplicated. Pick one module system per application.
+
+The `esm/fhirpath.mjs` bundle is generated by the package's `prepare` lifecycle
+script (`npm run build:esm`) and is included in the published npm package, so
+installing fhirpath from the npm registry needs no extra step. If you instead
+install it from a git reference with lifecycle scripts disabled (e.g.
+`npm install --ignore-scripts`), run `npm run build:esm` afterward so the
+`import` entry point (`esm/fhirpath.mjs`) exists.
+
 ### Web-browser:
 
 Download the zip file from the [releases
@@ -715,14 +745,22 @@ open browser on localhost:8080
   ```
 * Compare the output files in the new folder to those of the last release
   (looking for issues that might be due to changes in the StructureDefinition format)
-* Copy the `index.js` file from the last release into the new folder
+* Copy the CommonJS and ES module entry files from the last release into the
+  new folder
   ```
-  > cp ../r5/index.js r6
+  > cp ../r5/index.js ../r5/index.mjs ../r5/index.d.ts ../r5/index.d.mts r6
   ```
-* Update the `/index.d.ts` file to include the new module as an export (can copy from previous version)
-  ``` js
-  declare module "fhirpath/fhir-context/r6" {
-    export const {
+* Update the header comment (version name) in `r6/index.mjs` and
+  `r6/index.d.mts`. If the new version has no `score` property, also remove
+  `score` from the named-export lists in `r6/index.mjs` and `r6/index.d.ts`.
+* `r6/index.d.ts` declares the model's named exports for CommonJS consumers
+  (copy from the previous version, shown below); `r6/index.d.mts` re-exports
+  them for ES module consumers via `export * from "./index.js"` and needs no
+  per-version changes.
+  ``` ts
+  import {Model} from "../../src/fhirpath";
+
+  export const {
       version,
       score,
       choiceTypePaths,
@@ -733,8 +771,22 @@ open browser on localhost:8080
       resourcesWithUrlParam,
       path2TypeWithoutElements,
       path2RefType
-    }: Model;
-  }
+  }: Model;
+  ```
+* Register the new version in the `exports` map in `package.json` so it can be
+  imported by name through both `import` and `require` (copy an existing
+  `./fhir-context/<version>` entry and change the version)
+  ``` json
+  "./fhir-context/r6": {
+    "import": {
+      "types": "./fhir-context/r6/index.d.mts",
+      "default": "./fhir-context/r6/index.mjs"
+    },
+    "require": {
+      "types": "./fhir-context/r6/index.d.ts",
+      "default": "./fhir-context/r6/index.js"
+    }
+  },
   ```
 
 ## Credits

demo/package-lock.json

@@ -271,8 +271,12 @@ getVariableLabels().forEach((item, index) => {
 function addVariable(name = null, val = null) {
   const newItem = document.createElement("label");
   newItem.innerHTML =
-    `<li>%<input type="text" value="${name || ''}"></li><button type="button">` +
+    `<li>%<input type="text"></li><button type="button">` +
     "Remove variable</button>";
+  // Assign the variable name via the value property instead of interpolating
+  // it into innerHTML. The name can come from the untrusted "p" URL parameter,
+  // so interpolating it would allow DOM-based XSS.
+  newItem.querySelector('input').value = name || '';
   if (val) {
     newItem.setAttribute("data-json", fhirpath.util.toJSON(val, 2));
   }

demo/public/app.js

@@ -12,7 +12,10 @@ module.exports = [
 
   {
     // Apply this configuration to source files and the converter module
-    files: ['src/**/*.js', 'src/parser/index.js', 'converter/**/*.js'],
+    files: [
+      'src/**/*.js', 'src/**/*.mjs', 'src/parser/index.js',
+      'converter/**/*.js', 'fhir-context/**/*.mjs'
+    ],
     languageOptions: {
       ecmaVersion: 2020,
       sourceType: 'module',

eslint.config.js

@@ -0,0 +1,10 @@
+// Type declarations for the ES module wrapper (index.mjs) of the DSTU2 model.
+
+import type { Model } from "../../src/fhirpath.js";
+
+export * from "./index.js";
+
+
+declare const model: Model;
+
+export default model;

fhir-context/dstu2/index.d.mts

@@ -0,0 +1,23 @@
+// ES module wrapper around the CommonJS FHIR DSTU2 model (index.js).
+//
+// Re-exposes the model object as the default export and its fields as named
+// exports so ES module consumers can use either
+// `import model from 'fhirpath/fhir-context/dstu2'` or named imports.
+
+
+import model from './index.js';
+
+
+export default model;
+
+export const {
+  version,
+  choiceTypePaths,
+  pathsDefinedElsewhere,
+  type2Parent,
+  path2Type,
+  path2Repeating,
+  resourcesWithUrlParam,
+  path2TypeWithoutElements,
+  path2RefType
+} = model;

fhir-context/dstu2/index.mjs

@@ -0,0 +1,10 @@
+// Type declarations for the ES module wrapper (index.mjs) of the R4 model.
+
+import type { Model } from "../../src/fhirpath.js";
+
+export * from "./index.js";
+
+
+declare const model: Model;
+
+export default model;

fhir-context/r4/index.d.mts

@@ -0,0 +1,24 @@
+// ES module wrapper around the CommonJS FHIR R4 model (index.js).
+//
+// Re-exposes the model object as the default export and its fields as named
+// exports so ES module consumers can use either
+// `import model from 'fhirpath/fhir-context/r4'` or named imports.
+
+
+import model from './index.js';
+
+
+export default model;
+
+export const {
+  version,
+  score,
+  choiceTypePaths,
+  pathsDefinedElsewhere,
+  type2Parent,
+  path2Type,
+  path2Repeating,
+  resourcesWithUrlParam,
+  path2TypeWithoutElements,
+  path2RefType
+} = model;