WIP [api] adapt configs for ESM, run tests with --experimental-vm-mod…

…ules enabled, bump ts-jest

api.planx.uk/README.md

@@ -27,6 +27,7 @@ Development notes:
 
 - if you need to test or pull new changes from @opensystemslab/planx-document-templates or @opensystemslab/planx-core, make sure to update the commit hash in package.json first
 - you can also use `pnpm link {{local relative path to @opensystemslab/planx-document-templates or @opensystemslab/planx-core}}` to manage local development changes these packages without having to reinstall. If you do this, remember to also run `pnpm unlink` to unlink the local directory and then also update the commit hash to point to the most recent version of the package.
+- If you want to test particular files directly (e.g. `pnpm jest server.test.js`), note that since we now treat all files as ES modules, you'll need to export `NODE_OPTIONS="--experimental-vm-modules"` the following environment variable (or include it in every such command).
 
 ## Prior art
 

api.planx.uk/jest.config.ts

@@ -1,16 +1,30 @@
-export default {
+import type { JestConfigWithTsJest } from "ts-jest";
+
+const config: JestConfigWithTsJest = {
+  // we don't use a preset, preferring to give an explicit manual config
   testEnvironment: "node",
-  preset: "ts-jest",
   transform: {
-    "^.+\\.js$": [
-      "esbuild-jest",
+    // esbuild-jest is unmaintained and can't handle TypeScript with ESM, so we stick to ts-jest
+    // TODO: if tests are slow, consider swapping out for @swc/jest
+    "^.+\\.[jt]s$": [
+      "ts-jest",
       {
-        sourcemap: true,
+        useESM: true,
+        target: "esnext",
+        // we need a separate moduleResolutuion for tests (jest v30 may fix this)
+        tsconfig: "tsconfig.test.json",
       },
     ],
   },
   testPathIgnorePatterns: ["dist/*"],
   setupFilesAfterEnv: ["./jest.setup.js"],
+  // handle .ts files first, as ESM modules, and remove .js from imports for jest
+  moduleFileExtensions: ["ts", "js", "json"],
+  extensionsToTreatAsEsm: [".ts"],
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  // set up coverage collection
   collectCoverage: true,
   coverageThreshold: {
     global: {
@@ -20,3 +34,5 @@ export default {
   coverageReporters: ["lcov", "text-summary"],
   coverageDirectory: "./coverage",
 };
+
+export default config;

api.planx.uk/package.json

@@ -56,9 +56,9 @@
     "lint": "eslint '**/*.{js,ts}' && prettier -c .",
     "lint:fix": "eslint --fix '**/*.{js,ts}' && prettier -w .",
     "check": "tsc --noEmit && pnpm lint",
-    "test": "TZ=Europe/London jest --silent",
-    "test:coverage": "TZ=Europe/London jest; open ./coverage/lcov-report/index.html",
-    "test:watch": "TZ=Europe/London jest --coverage=false --watch",
+    "test": "TZ=Europe/London NODE_OPTIONS='$NODE_OPTIONS --experimental-vm-modules' jest --silent",
+    "test:coverage": "TZ=Europe/London NODE_OPTIONS='$NODE_OPTIONS --experimental-vm-modules' jest; open ./coverage/lcov-report/index.html",
+    "test:watch": "TZ=Europe/London NODE_OPTIONS='$NODE_OPTIONS --experimental-vm-modules' jest --coverage=false --watch",
     "build": "rimraf ./dist && npx tsc && pnpm copy-swagger-files",
     "prepare": "cd .. && husky install api.planx.uk/.husky",
     "copy-swagger-files": "copyfiles '**/docs.yaml' dist"
@@ -111,7 +111,7 @@
     "prettier": "^3.2.4",
     "rimraf": "^5.0.5",
     "supertest": "^7.0.0",
-    "ts-jest": "^29.1.1",
+    "ts-jest": "^29.2.3",
     "ts-node-dev": "^2.0.0",
     "typescript": "^5.5.2",
     "uuid": "^10.0.0"

api.planx.uk/tsconfig.json

@@ -1,4 +1,5 @@
 {
+  // as of July 24, esnext == es2022 and nodenext == node16
   "compilerOptions": {
     "allowJs": true,
     "esModuleInterop": true,

api.planx.uk/tsconfig.test.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler"
+  }
+}