Updates to Dependencies, Build Chain, and Examples

.github/pull_request_template.md

@@ -9,10 +9,8 @@ For items that are not-applicable, mark "N/A" and ✔.
 - [ ] Tests are included and test edge cases
 - [ ] Tests have been run locally and pass
 - [ ] Code coverage has not gone down and all code touched or added is covered.
-- [ ] Code passes lint and prettier (hint: use `npm run test:plus` to run tests, lint, and prettier)
+- [ ] Code passes lint and prettier (hint: use `npm run check` to run tests, lint, and prettier)
 - [ ] All dependent libraries are appropriately updated or have a corresponding PR related to this change
-- [ ] `cql4browsers.js` built with `npm run build:browserify` if source changed.
-
 **Reviewer:**
 
 Name:

.github/workflows/ci-workflow.yml

@@ -12,15 +12,6 @@ jobs:
         with:
           node-version: 24.x
       - run: npm audit --omit=dev
-  cql4browsers:
-    name: Check cql4browsers
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 24.x
-      - run: ./bin/validate_cql4browsers.sh
   lint:
     name: Check lint and prettier
     runs-on: ubuntu-latest
@@ -38,7 +29,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: [18.x, 22.x, 24.x]
+        node: [20.x, 22.x, 24.x]
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
@@ -73,3 +64,24 @@ jobs:
         working-directory: test-server
       - run: npm run check
         working-directory: test-server
+  examples:
+    name: Check examples
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24.x
+      - run: npm ci
+      - run: npm ci
+        working-directory: examples/browser
+      - run: npm test
+        working-directory: examples/browser
+      - run: npm ci
+        working-directory: examples/node
+      - run: npm test
+        working-directory: examples/node
+      - run: npm ci
+        working-directory: examples/typescript
+      - run: npm test
+        working-directory: examples/typescript

.gitignore

@@ -1,9 +1,12 @@
 lib
 lib-test
+dist
 node_modules
 .DS_Store
 .nyc_output
-.vscode
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.sample.json
 coverage
 *.original.coffee
 yarn-error.log

.mocharc.json

@@ -1,5 +1,5 @@
 {
   "ignore": ["test/spec-tests/*.js"],
   "extension": ["ts"],
-  "require": ["ts-node/register", "./test/should-extensions.ts"]
+  "require": ["tsx/cjs", "./test/should-extensions.ts"]
 }

.npmignore

@@ -6,3 +6,4 @@
 /test
 /test-server
 /CQL_Execution_Features.xlsx
+/examples

.oxlintrc.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "env": {
+    "builtin": true,
+    "es6": true,
+    "mocha": true,
+    "node": true
+  },
+  "ignorePatterns": [
+    "**/lib",
+    "**/lib-test",
+    "**/dist",
+    "test-server/**"
+  ],
+  "rules": {
+    "no-loss-of-precision": "off",
+    "no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_"
+      }
+    ],
+    "no-var": "error",
+    "prefer-const": "error",
+    "prefer-rest-params": "error",
+    "prefer-spread": "error",
+    "curly": "error",
+    "no-console": [
+      "warn",
+      {
+        "allow": [
+          "warn",
+          "error"
+        ]
+      }
+    ]
+  },
+  "overrides": [
+    {
+      "files": [
+        "test/elm/**/*.js"
+      ],
+      "rules": {
+        "unicorn/no-empty-file": "off"
+      }
+    }
+  ]
+}

.prettierignore

@@ -1,10 +1,10 @@
 lib
 lib-test
+dist
 node_modules
 .nyc_output
 .vscode
 coverage
-cql4browsers.js
 # the following uses its own prettier config
 test-server
 # the following are generated by the test generator

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    // recommended for lint and code formatting
+    "oxc.oxc-vscode",
+    "esbenp.prettier-vscode"
+  ]
+}

.vscode/settings.sample.json

@@ -0,0 +1,10 @@
+{
+  "[javascript][typescript][typescriptreact]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[json]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "vscode.json-language-features"
+  }
+}

DEPENDENCY_NOTES.md

@@ -3,5 +3,4 @@ The following notes about the app's dependencies should be revisited and resolve
 As of 2026-07-27:
 
 - `@types/node`: Consider updating to `26.x` in the future, but for now `24.x` still has plent of time in LTS.
-- `typescript`: `7.x` uses a new native compiler without a native API. Libraries like `ts-node` and `typescript-eslint` do not yet support it.
 - `tslog` (test-server only): `5.x` is ESM-only and replaces v4's flat logger settings such as `hideLogPositionForProduction` and `prettyLogTemplate`. Updating will require some migration.

README.md

@@ -63,13 +63,13 @@ To use this project, you should perform the following steps:
 1. Install [Node.js](http://nodejs.org/) LTS<sup>*</sup>
 2. Execute the following from the root directory: `npm install`
 
-<sup>*</sup> This project is primarily developed and tested using Node 24.x, but all versions >= 18.x are expected to work. Since Node 18.x has reached end-of-life, developers should consider this project's support for Node 18.x to be _deprecated_.
+<sup>*</sup> This project is primarily developed and tested using Node 24.x, but all versions >= 20.x are expected to work. Since Node 18.x reached end-of-life over a year ago, this project no longer supports it.
 
 # To Execute Your CQL
 
 Please note that while the CQL Execution library supports many aspects of CQL, it does not support
 everything in the CQL specification.  You should check to see what is implemented (by referencing
-the unit tests) before expecting it to work! For a working example, see `examples`.
+the unit tests) before expecting it to work! For working examples, see the `examples` directory.
 
 There are several steps involved to execute CQL.  First, you must create a JSON representation of
 the ELM. For the easiest integration, we will generate a JSON file using cql-to-elm:
@@ -82,10 +82,9 @@ the ELM. For the easiest integration, we will generate a JSON file using cql-to-
 4. `./gradlew :cql-to-elm-cli:installDist`
 5. `./cql-to-elm-cli/build/install/cql-to-elm-cli/bin/cql-to-elm-cli --format=JSON --input ${path_to_cql} --output ${path_to_cql-execution}/customCQL`
 
-The above example puts the example CQL into a subfolder of the `cql-execution` project to make the
-relative paths to `cql-execution` libraries easier, but it doesn't _have_ to go there.  If you put
-it elsewhere, you'll need to modify the examples below so that the `require` statements point to
-the correct location of the `cql` export.
+This repository contains self-contained Node.js and TypeScript mini-projects under `examples`.
+They depend on the repository's local `cql-execution` package; projects outside this repository
+should install `cql-execution` from npm instead.
 
 In the rest of the examples, we'll assume an `age.cql` file with the following contents. This
 follows the example already in the "examples" folder (but of course you can use your own CQL):
@@ -110,12 +109,11 @@ define InDemographic:
 Next, we can create a TypeScript file to execute the above CQL. This file will need to contain (or
 `import`) JSON patient representations for testing as well. Our example CQL uses a "Simple"
 data model developed only for demonstration and testing purposes.  In this model, each patient is
-represented using a simple JSON object.  For ease of use, let's put the file in the `customCQL`
-directory:
+represented using a simple JSON object.
 
 ``` typescript
-import cql from '../../src/cql';
-import * as measure from './age.json'; // Requires the "resolveJsonModule" compiler option to be "true"
+import cql from 'cql-execution';
+import measure from './age.json'; // Requires the "resolveJsonModule" compiler option to be "true"
 
 const lib = new cql.Library(measure);
 const executor = new cql.Executor(lib);
@@ -125,14 +123,14 @@ const psource = new cql.PatientSource([
     recordType: 'Patient',
     name: 'John Smith',
     gender: 'M',
-    birthDate: '1980-02-17T06:15'
+    birthDate: '1980-02-17'
   },
   {
     id: '2',
     recordType: 'Patient',
     name: 'Sally Smith',
     gender: 'F',
-    birthDate: '2007-08-02T11:47'
+    birthDate: '2007-08-02'
   }
 ]);
 
@@ -151,30 +149,27 @@ In the above file, we've assumed the JSON ELM JSON file for the measure is calle
 also assumed a couple of very simple patients.  Let's call the file we just created
 `exec-age.ts`.
 
-Now we can execute the measure using [ts-node](https://www.npmjs.com/package/ts-node):
+The complete TypeScript example has its own dependencies, scripts, and tests. Run it with:
 
-``` bash
-npx ts-node -O '{ "resolveJsonModule": true }' --files ${path_to_cql-execution}/customCQL/exec-age.ts
+```bash
+cd examples/typescript
+npm install
+npm start
 ```
 
 If all is well, it should print the result object to standard out.
 
 ## JavaScript Example
 
-For usage in regular JavaScript, we can refer to the compiled JavaScript in the `lib` directory.
-Ensure that this JavaScript is present by running `npm run build` before continuing on to the example.
-We will follow the same steps as the above TypeScript example, but our JavaScript code must use `require`
-instead of `import`, and will load the `cql-execution` library from the `lib` directory. As before,
-let's put the file in the `customCQL` directory:
+For regular JavaScript, we use `require` to load the installed `cql-execution` package:
 
 Next, create a JavaScript file to execute the CQL above.  This file will need to contain (or
 `require`) JSON patient representations for testing as well.  Our example CQL uses a "Simple"
 data model developed only for demonstration and testing purposes.  In this model, each patient is
-represented using a simple JSON object.  For ease of use, let's put the file in the `customCQL`
-directory:
+represented using a simple JSON object.
 
 ```js
-const cql = require('../lib/cql');
+const cql = require('cql-execution');
 const measure = require('./age.json');
 
 const lib = new cql.Library(measure);
@@ -184,13 +179,13 @@ const psource = new cql.PatientSource([ {
   'recordType' : 'Patient',
   'name': 'John Smith',
   'gender': 'M',
-  'birthDate' : '1980-02-17T06:15'
+  'birthDate' : '1980-02-17'
 }, {
   'id' : '2',
   'recordType' : 'Patient',
   'name': 'Sally Smith',
   'gender': 'F',
-  'birthDate' : '2007-08-02T11:47'
+  'birthDate' : '2007-08-02'
 } ]);
 
 executor
@@ -207,10 +202,12 @@ executor
 The above file has the same assumptions as the TypeScript example above. Let's call the file we just created
 `exec-age.js`.
 
-Now we can execute the measure using Node.js:
+The complete Node.js example has its own dependencies, scripts, and tests. Run it with:
 
 ```shell
-node ${path_to_cql-execution}/customCQL/exec-age.js
+cd examples/node
+npm install
+npm start
 ```
 
 If all is well, it should print the result object to standard out, and the output should be identical to that of the TypeScript example.
@@ -351,12 +348,3 @@ execute `npm run watch:test-data`.
 # Using the Test Server and CQL Tests Runner
 
 See [test-server/README.md](test-server/README.md).
-
-# Pull Requests
-
-If TypeScript source code is modified, `cql4browsers.js` needs to be included in the pull request,
-otherwise GitHub Actions CI will fail. To generate this file, run:
-
-```
-npm run build:browserify
-```