[api] adopt ESM throughout (#3464)

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"` (or include it in every such command).
 
 ## Prior art
 

api.planx.uk/airbrake.ts

@@ -1,5 +1,5 @@
 import { Notifier } from "@airbrake/node";
-import { isLiveEnv } from "./helpers";
+import { isLiveEnv } from "./helpers.js";
 
 const airbrake =
   isLiveEnv() &&

api.planx.uk/client/index.test.ts

@@ -1,7 +1,7 @@
 import { CoreDomainClient } from "@opensystemslab/planx-core";
-import { getClient } from ".";
-import { userContext } from "../modules/auth/middleware";
-import { getJWT } from "../tests/mockJWT";
+import { getClient } from "./index.js";
+import { userContext } from "../modules/auth/middleware.js";
+import { getJWT } from "../tests/mockJWT.js";
 
 test("getClient() throws an error if a store is not set", () => {
   expect(() => getClient()).toThrow();

api.planx.uk/client/index.ts

@@ -1,7 +1,7 @@
 import { CoreDomainClient } from "@opensystemslab/planx-core";
-import { userContext } from "../modules/auth/middleware";
-import { ServerError } from "../errors";
-import { buildJWTForAPIRole } from "../modules/auth/service";
+import { userContext } from "../modules/auth/middleware.js";
+import { ServerError } from "../errors/index.js";
+import { buildJWTForAPIRole } from "../modules/auth/service.js";
 
 /**
  * Connects to Hasura using the "api" role

api.planx.uk/errors/index.ts

@@ -1 +1 @@
-export { ServerError } from "./ServerError";
+export { ServerError } from "./serverError.js";

api.planx.uk/helpers.test.ts

@@ -4,13 +4,13 @@ import {
   getFlowData,
   getFormattedEnvironment,
   isLiveEnv,
-} from "./helpers";
-import { queryMock } from "./tests/graphqlQueryMock";
+} from "./helpers.js";
+import { queryMock } from "./tests/graphqlQueryMock.js";
 import {
   childFlow,
   draftParentFlow,
   flattenedParentFlow,
-} from "./tests/mocks/validateAndPublishMocks";
+} from "./tests/mocks/validateAndPublishMocks.js";
 
 describe("getFormattedEnvironment() function", () => {
   const OLD_ENV = process.env;

api.planx.uk/helpers.ts

@@ -1,8 +1,8 @@
 import { gql } from "graphql-request";
-import { capitalize } from "lodash";
-import { Flow, Node } from "./types";
+import capitalize from "lodash/capitalize.js";
+import { Flow, Node } from "./types.js";
 import { ComponentType, FlowGraph } from "@opensystemslab/planx-core/types";
-import { $public, getClient } from "./client";
+import { $public, getClient } from "./client/index.js";
 
 export interface FlowData {
   slug: string;

api.planx.uk/index.ts

@@ -1,4 +1,4 @@
-import server from "./server";
+import server from "./server.js";
 
 const PORT = process.env.PORT || 8001;
 

api.planx.uk/jest.config.ts

@@ -1,16 +1,31 @@
-export default {
+import type { JestConfigWithTsJest } from "ts-jest";
+
+const config: JestConfigWithTsJest = {
+  // ts-jest presets are deprecated, so we prefer to give an explicit manual config
   testEnvironment: "node",
-  preset: "ts-jest",
   transform: {
-    "^.+\\.js$": [
-      "esbuild-jest",
+    // esbuild-jest transformer is unmaintained and can't handle ts-with-esm, so we stick to ts-jest
+    // TODO: if tests are too slow, consider swapping out for @swc/jest
+    "^.+\\.[jt]s$": [
+      "ts-jest",
       {
-        sourcemap: true,
+        useESM: true,
+        // we need a separate module/moduleResolution config for tests (jest v30 may fix this)
+        tsconfig: "tsconfig.test.json",
       },
     ],
   },
+  // mime v4 (which moves to pure ESM) may still have commonJS traces, so we transform it
+  transformIgnorePatterns: ["node_modules\\/.pnpm\\/(?!(mime))"],
   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 +35,5 @@ export default {
   coverageReporters: ["lcov", "text-summary"],
   coverageDirectory: "./coverage",
 };
+
+export default config;

api.planx.uk/jest.setup.js

@@ -1,5 +1,5 @@
 import dotenv from "dotenv";
-import { queryMock } from "./tests/graphqlQueryMock";
+import { queryMock } from "./tests/graphqlQueryMock.js";
 
 dotenv.config({
   path: "./.env.test",

api.planx.uk/lib/hasura/metadata/index.test.ts

@@ -1,4 +1,4 @@
-import { createScheduledEvent, RequiredScheduledEventArgs } from ".";
+import { createScheduledEvent, RequiredScheduledEventArgs } from "./index.js";
 import Axios, { AxiosError } from "axios";
 
 jest.mock("axios", () => ({

api.planx.uk/lib/hasura/metadata/index.ts

@@ -90,4 +90,4 @@ const createScheduledEvent = async (args: RequiredScheduledEventArgs) => {
   }
 };
 
-export { createScheduledEvent, RequiredScheduledEventArgs };
+export { createScheduledEvent, type RequiredScheduledEventArgs };

api.planx.uk/lib/hasura/schema/index.test.ts

@@ -1,4 +1,4 @@
-import { runSQL } from ".";
+import { runSQL } from "./index.js";
 import Axios, { AxiosError } from "axios";
 
 jest.mock("axios", () => ({

api.planx.uk/lib/notify/index.test.ts

@@ -1,6 +1,6 @@
-import { sendEmail } from ".";
+import { sendEmail } from "./index.js";
 import { NotifyClient } from "notifications-node-client";
-import { NotifyConfig } from "../../types";
+import { NotifyConfig } from "../../types.js";
 
 jest.mock("notifications-node-client");
 

api.planx.uk/lib/notify/index.ts

@@ -1,7 +1,7 @@
 import { NotifyClient } from "notifications-node-client";
-import { softDeleteSession } from "../../modules/saveAndReturn/service/utils";
-import { NotifyConfig } from "../../types";
-import { $api, $public } from "../../client";
+import { softDeleteSession } from "../../modules/saveAndReturn/service/utils.js";
+import { NotifyConfig } from "../../types.js";
+import { $api, $public } from "../../client/index.js";
 
 const notifyClient = new NotifyClient(process.env.GOVUK_NOTIFY_API_KEY);
 

api.planx.uk/modules/admin/routes.ts

@@ -1,11 +1,11 @@
 import { Router } from "express";
-import { usePlatformAdminAuth } from "../auth/middleware";
-import { getOneAppXML } from "./session/oneAppXML";
-import { getCSVData, getRedactedCSVData } from "./session/csv";
-import { getHTMLExport, getRedactedHTMLExport } from "./session/html";
-import { generateZip } from "./session/zip";
-import { getSessionSummary } from "./session/summary";
-import { getDigitalPlanningApplicationPayload } from "./session/digitalPlanningData";
+import { usePlatformAdminAuth } from "../auth/middleware.js";
+import { getOneAppXML } from "./session/oneAppXML.js";
+import { getCSVData, getRedactedCSVData } from "./session/csv.js";
+import { getHTMLExport, getRedactedHTMLExport } from "./session/html.js";
+import { generateZip } from "./session/zip.js";
+import { getSessionSummary } from "./session/summary.js";
+import { getDigitalPlanningApplicationPayload } from "./session/digitalPlanningData.js";
 
 const router = Router();
 

api.planx.uk/modules/admin/session/csv.test.ts

@@ -1,6 +1,6 @@
 import supertest from "supertest";
-import app from "../../../server";
-import { authHeader } from "../../../tests/mockJWT";
+import app from "../../../server.js";
+import { authHeader } from "../../../tests/mockJWT.js";
 
 const endpoint = (strings: TemplateStringsArray) =>
   `/admin/session/${strings[0]}/csv`;

api.planx.uk/modules/admin/session/csv.ts

@@ -1,6 +1,6 @@
 import { stringify } from "csv-stringify";
 import { NextFunction, Request, Response } from "express";
-import { $api } from "../../../client";
+import { $api } from "../../../client/index.js";
 
 /**
  * @swagger

api.planx.uk/modules/admin/session/digitalPlanningData.test.ts

@@ -1,7 +1,7 @@
 import supertest from "supertest";
-import app from "../../../server";
-import { authHeader } from "../../../tests/mockJWT";
-import { expectedPlanningPermissionPayload } from "../../../tests/mocks/digitalPlanningDataMocks";
+import app from "../../../server.js";
+import { authHeader } from "../../../tests/mockJWT.js";
+import { expectedPlanningPermissionPayload } from "../../../tests/mocks/digitalPlanningDataMocks.js";
 
 const endpoint = (strings: TemplateStringsArray) =>
   `/admin/session/${strings[0]}/digital-planning-application`;

api.planx.uk/modules/admin/session/digitalPlanningData.ts

@@ -1,5 +1,5 @@
 import { NextFunction, Request, Response } from "express";
-import { $api } from "../../../client";
+import { $api } from "../../../client/index.js";
 
 /**
  * @swagger

api.planx.uk/modules/admin/session/html.test.ts

@@ -1,6 +1,6 @@
 import supertest from "supertest";
-import app from "../../../server";
-import { authHeader } from "../../../tests/mockJWT";
+import app from "../../../server.js";
+import { authHeader } from "../../../tests/mockJWT.js";
 
 const endpoint = (strings: TemplateStringsArray) =>
   `/admin/session/${strings[0]}/html`;

api.planx.uk/modules/admin/session/html.ts

@@ -3,8 +3,8 @@ import type {
   DrawBoundaryUserAction,
   PlanXExportData,
 } from "@opensystemslab/planx-core/types";
+import { $api } from "../../../client/index.js";
 import type { RequestHandler } from "express";
-import { $api } from "../../../client";
 
 type HTMLExportHandler = RequestHandler<{ sessionId: string }, string>;
 

api.planx.uk/modules/admin/session/oneAppXML.test.ts

@@ -1,6 +1,6 @@
 import supertest from "supertest";
-import app from "../../../server";
-import { authHeader } from "../../../tests/mockJWT";
+import app from "../../../server.js";
+import { authHeader } from "../../../tests/mockJWT.js";
 
 const endpoint = (strings: TemplateStringsArray) =>
   `/admin/session/${strings[0]}/xml`;

api.planx.uk/modules/admin/session/oneAppXML.ts

@@ -1,5 +1,5 @@
 import { Request, Response, NextFunction } from "express";
-import { $api } from "../../../client";
+import { $api } from "../../../client/index.js";
 
 /**
  * @swagger

api.planx.uk/modules/admin/session/summary.test.ts

@@ -1,7 +1,7 @@
 import supertest from "supertest";
-import app from "../../../server";
-import { queryMock } from "../../../tests/graphqlQueryMock";
-import { authHeader } from "../../../tests/mockJWT";
+import app from "../../../server.js";
+import { queryMock } from "../../../tests/graphqlQueryMock.js";
+import { authHeader } from "../../../tests/mockJWT.js";
 
 const endpoint = (strings: TemplateStringsArray) =>
   `/admin/session/${strings[0]}/summary`;

api.planx.uk/modules/admin/session/summary.ts

@@ -7,8 +7,8 @@ import {
 import { NextFunction, Request, Response } from "express";
 import { gql } from "graphql-request";
 
-import { Breadcrumb, Flow, LowCalSession, Passport } from "../../../types";
-import { $api } from "../../../client";
+import { Breadcrumb, Flow, LowCalSession, Passport } from "../../../types.js";
+import { $api } from "../../../client/index.js";
 
 /**
  * @swagger

api.planx.uk/modules/admin/session/zip.test.ts

@@ -1,6 +1,6 @@
 import supertest from "supertest";
-import app from "../../../server";
-import { authHeader } from "../../../tests/mockJWT";
+import app from "../../../server.js";
+import { authHeader } from "../../../tests/mockJWT.js";
 
 jest.mock("../../send/utils/exportZip", () => ({
   buildSubmissionExportZip: jest.fn().mockResolvedValue({

api.planx.uk/modules/admin/session/zip.ts

@@ -1,5 +1,5 @@
 import { NextFunction, Request, Response } from "express";
-import { buildSubmissionExportZip } from "../../send/utils/exportZip";
+import { buildSubmissionExportZip } from "../../send/utils/exportZip.js";
 
 /**
  * @swagger

api.planx.uk/modules/analytics/controller.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { trackAnalyticsLogExit } from "./service";
-import { ValidatedRequestHandler } from "../../shared/middleware/validate";
+import { trackAnalyticsLogExit } from "./service.js";
+import { ValidatedRequestHandler } from "../../shared/middleware/validate.js";
 
 export const logAnalyticsSchema = z.object({
   query: z.object({

api.planx.uk/modules/analytics/index.test.ts

@@ -1,6 +1,6 @@
 import supertest from "supertest";
-import app from "../../server";
-import { queryMock } from "../../tests/graphqlQueryMock";
+import app from "../../server.js";
+import { queryMock } from "../../tests/graphqlQueryMock.js";
 
 describe("Logging analytics", () => {
   beforeEach(() => {

api.planx.uk/modules/analytics/routes.ts

@@ -1,10 +1,10 @@
-import { validate } from "./../../shared/middleware/validate";
+import { validate } from "./../../shared/middleware/validate.js";
 import { Router } from "express";
 import {
   logAnalyticsSchema,
   logUserExitController,
   logUserResumeController,
-} from "./controller";
+} from "./controller.js";
 
 const router = Router();
 

api.planx.uk/modules/analytics/service.ts

@@ -1,5 +1,5 @@
 import { gql } from "graphql-request";
-import { $public } from "../../client";
+import { $public } from "../../client/index.js";
 
 interface UpdateAnalyticsLogUserExit {
   analyticsLog: {

api.planx.uk/modules/auth/middleware.test.ts

@@ -1,4 +1,4 @@
-import { isEqual } from "./middleware";
+import { isEqual } from "./middleware.js";
 
 describe("isEqual() helper function", () => {
   it("handles undefined secrets", () => {

api.planx.uk/modules/auth/middleware.ts

@@ -1,7 +1,7 @@
 import crypto from "crypto";
 import assert from "assert";
-import { ServerError } from "../../errors";
-import { Template } from "../../lib/notify";
+import { ServerError } from "../../errors/index.js";
+import { Template } from "../../lib/notify/index.js";
 import { expressjwt } from "express-jwt";
 
 import passport from "passport";

api.planx.uk/modules/auth/routes.ts

@@ -1,6 +1,6 @@
 import { Router } from "express";
-import * as Middleware from "./middleware";
-import * as Controller from "./controller";
+import * as Middleware from "./middleware.js";
+import * as Controller from "./controller.js";
 
 const router = Router();
 

api.planx.uk/modules/auth/service.test.ts

@@ -1,4 +1,4 @@
-import { checkUserCanAccessEnv } from "./service";
+import { checkUserCanAccessEnv } from "./service.js";
 
 const mockIsStagingOnly = jest.fn();
 

api.planx.uk/modules/auth/service.ts

@@ -1,5 +1,5 @@
-import { sign } from "jsonwebtoken";
-import { $api } from "../../client";
+import jwt from "jsonwebtoken";
+import { $api } from "../../client/index.js";
 import { User, Role } from "@opensystemslab/planx-core/types";
 
 export const buildJWT = async (email: string): Promise<string | undefined> => {
@@ -13,12 +13,11 @@ export const buildJWT = async (email: string): Promise<string | undefined> => {
     "https://hasura.io/jwt/claims": generateHasuraClaimsForUser(user),
   };
 
-  const jwt = sign(data, process.env.JWT_SECRET!);
-  return jwt;
+  return jwt.sign(data, process.env.JWT_SECRET!);
 };
 
 export const buildJWTForAPIRole = () =>
-  sign(
+  jwt.sign(
     {
       "https://hasura.io/jwt/claims": {
         "x-hasura-allowed-roles": ["api"],

api.planx.uk/modules/auth/strategy/google.ts

@@ -1,5 +1,5 @@
 import { Strategy as GoogleStrategy } from "passport-google-oauth20";
-import { buildJWT } from "../service";
+import { buildJWT } from "../service.js";
 
 export const googleStrategy = new GoogleStrategy(
   {