feat(deps): Sync loadPeer() (#3465)

This is now possible because we dropped Node 20 in v28 ( #3242 ) and
`require(ESM)` is available since 22.12 without flags. So we can do
dynamic module import without async.

Could benefit in #3463 

A semi-breaking change to `Integration::create()` is postponed until
next major.

⌛ Mocking peers in tests requires a rework (in progress)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Refactor**
* Peer dependency loading is now synchronous, simplifying server startup
flow.
* Middleware setup for cookies and uploads now runs synchronously during
initialization.
* `Integration` TypeScript configuration is optional; prefer `new
Integration(...)` over the deprecated `Integration.create()`.

* **Tests**
* Updated integration and peer-helper tests to reflect synchronous
initialization/loader behavior.
  * Adjusted and streamlined mocks for peers used in tests.

* **Documentation**
* Updated the README “End-to-End Type Safety” example and added a
`v28.6.0` changelog entry.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: RobinTail

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Version 28
 
+### v28.6.0
+
+- Changes to the `Integration` generator:
+  - The `typescript` option is no longer required for constructor;
+  - `Integration.create()` is now deprecated — use `new Integration()` instead;
+  - This is possible thanks to the `require(ESM)` feature, available on all supported Node.js versions;
+
 ### v28.5.0
 
 - Changes to the proprietary `Date` handling schemas:

README.md

@@ -1190,11 +1190,9 @@ safety between your API and frontend. Make sure you have `typescript` installed.
 and using the async `printFormatted()` method.
 
 ```ts
-import typescript from "typescript";
 import { Integration } from "express-zod-api";
 
 const client = new Integration({
-  typescript, // or await Integration.create() to delegate importing
   routing,
   config,
   variant: "client", // <— optional, see also "types" for a DIY solution

compat-test/int.spec.ts

@@ -2,11 +2,9 @@ import { Integration } from "express-zod-api";
 import { describe, test, expect } from "vitest";
 
 describe("Integration", () => {
-  test("should work with minimum supported TypeScript", async () => {
+  test("should work with minimum supported TypeScript",  () => {
     expect(
-      (
-        await Integration.create({ config: { cors: false }, routing: {} })
-      ).print()
+      new Integration({ config: { cors: false }, routing: {} }).print()
     ).toContain("export class Client");
   });
 });

express-zod-api/src/config-type.ts

@@ -156,6 +156,7 @@ interface GracefulOptions {
   beforeExit?: () => void | Promise<void>;
 }
 
+/** @todo consider removing Promise to make createServer sync in next major */
 type ServerHook = (params: {
   app: IRouter;
   /** @desc Returns child logger for the given request (if configured) or the configured logger otherwise */

express-zod-api/src/integration.ts

@@ -15,7 +15,8 @@ import type { ClientMethod } from "./method";
 import type { CommonConfig } from "./config-type";
 
 interface IntegrationParams {
-  typescript: typeof ts;
+  /** @default loadPeer("typescript") */
+  typescript?: typeof ts;
   routing: Routing;
   config: CommonConfig;
   /**
@@ -81,7 +82,7 @@ export class Integration extends IntegrationBase {
   }
 
   public constructor({
-    typescript,
+    typescript = loadPeer<typeof ts>("typescript"),
     routing,
     config,
     brandHandling,
@@ -181,10 +182,14 @@ export class Integration extends IntegrationBase {
     );
   }
 
+  /**
+   * @deprecated use `new Integration()` without `typescript` option on its argument
+   * @todo remove in the next major — no longer needed
+   * */
   public static async create(params: Omit<IntegrationParams, "typescript">) {
     return new Integration({
       ...params,
-      typescript: await loadPeer<typeof ts>("typescript"),
+      typescript: loadPeer<typeof ts>("typescript"),
     });
   }
 
@@ -233,8 +238,7 @@ export class Integration extends IntegrationBase {
     let format = userDefined;
     if (!format) {
       try {
-        const prettierFormat = (await loadPeer<typeof Prettier>("prettier"))
-          .format;
+        const prettierFormat = loadPeer<typeof Prettier>("prettier").format;
         format = (text) => prettierFormat(text, { filepath: "client.ts" });
       } catch {}
     }

express-zod-api/src/peer-helpers.ts

@@ -1,11 +1,17 @@
+import { createRequire } from "node:module";
 import { MissingPeerError } from "./errors";
 
-export const loadPeer = async <T>(
+let require: NodeJS.Require;
+
+export const loadPeer = <T>(
   moduleName: string,
   moduleExport: string = "default",
-): Promise<T> => {
+): T => {
   try {
-    return (await import(moduleName))[moduleExport];
-  } catch {}
-  throw new MissingPeerError(moduleName);
+    const mod = (require ??= createRequire(import.meta.url))(moduleName);
+    if (moduleExport !== "default") return mod[moduleExport] as T;
+    return mod.default !== undefined ? mod.default : mod;
+  } catch {
+    throw new MissingPeerError(moduleName);
+  }
 };

express-zod-api/src/server-helpers.ts

@@ -82,12 +82,12 @@ export const createUploadFailureHandler =
     next();
   };
 
-export const createCookieParser = async ({
+export const createCookieParser = ({
   config,
 }: {
   config: ServerConfig;
-}): Promise<RequestHandler> => {
-  const parser = await loadPeer<typeof cookieParser>("cookie-parser");
+}): RequestHandler => {
+  const parser = loadPeer<typeof cookieParser>("cookie-parser");
   const { secret, ...rest } = {
     ...(typeof config.cookies === "object" && config.cookies),
   };
@@ -98,14 +98,14 @@ export const createUploadLogger = (
   logger: ActualLogger,
 ): Pick<Console, "log"> => ({ log: logger.debug.bind(logger) });
 
-export const createUploadParsers = async ({
+export const createUploadParsers = ({
   getLogger,
   config,
 }: {
   getLogger: GetLogger;
   config: ServerConfig;
-}): Promise<RequestHandler[]> => {
-  const uploader = await loadPeer<typeof fileUpload>("express-fileupload");
+}): RequestHandler[] => {
+  const uploader = loadPeer<typeof fileUpload>("express-fileupload");
   const { limitError, beforeUpload, ...options } = {
     ...(typeof config.upload === "object" && config.upload),
   };

express-zod-api/src/server.ts

@@ -72,23 +72,21 @@ export const createServer = async (config: ServerConfig, routing: Routing) => {
     .use(loggingMiddleware);
 
   if (config.compression) {
-    const compressor = await loadPeer<typeof compression>("compression");
+    const compressor = loadPeer<typeof compression>("compression");
     app.use(
       compressor(
         typeof config.compression === "object" ? config.compression : undefined,
       ),
     );
   }
-  if (config.cookies) app.use(await createCookieParser({ config }));
+  if (config.cookies) app.use(createCookieParser({ config }));
   await config.beforeRouting?.({ app, getLogger });
 
   const parsers: Parsers = {
     json: [config.jsonParser || express.json()],
     raw: [config.rawParser || express.raw(), moveRaw],
     form: [config.formParser || express.urlencoded()],
-    upload: config.upload
-      ? await createUploadParsers({ config, getLogger })
-      : [],
+    upload: config.upload ? createUploadParsers({ config, getLogger }) : [],
   };
   initRouting({ app, routing, getLogger, config, parsers });
 

express-zod-api/tests/express-mock.ts

@@ -1,13 +1,6 @@
 const expressJsonMock = vi.fn();
 const expressRawMock = vi.fn();
 const expressUrlencodedMock = vi.fn();
-const compressionMock = vi.fn();
-const fileUploadMock = vi.fn();
-const cookieParserMock = vi.fn();
-
-vi.mock("compression", () => ({ default: compressionMock }));
-vi.mock("express-fileupload", () => ({ default: fileUploadMock }));
-vi.mock("cookie-parser", () => ({ default: cookieParserMock }));
 
 const staticHandler = vi.fn();
 const staticMock = vi.fn(() => staticHandler);
@@ -35,9 +28,6 @@ expressMock.static = staticMock;
 vi.mock("express", () => ({ default: expressMock }));
 
 export {
-  compressionMock,
-  fileUploadMock,
-  cookieParserMock,
   expressMock,
   appMock,
   expressJsonMock,

express-zod-api/tests/integration.spec.ts

@@ -51,7 +51,7 @@ describe("Integration", () => {
   );
 
   test("Should treat optionals the same way as z.infer() by default", async () => {
-    const client = await Integration.create({
+    const client = new Integration({
       config: configMock,
       routing: {
         v1: {
@@ -74,7 +74,7 @@ describe("Integration", () => {
   test.each([undefined, false])(
     "Should support HEAD method by default %#",
     async (hasHeadMethod) => {
-      const client = await Integration.create({
+      const client = new Integration({
         config: configMock,
         hasHeadMethod,
         variant: "types",
@@ -111,7 +111,7 @@ describe("Integration", () => {
         handler: vi.fn(),
       }),
     );
-    const client = await Integration.create({
+    const client = new Integration({
       config: configMock,
       variant: "types",
       routing: {