br(v9): Making createServer() sync again (#3472)

Thanks to #3465 
This should simplify daily routines for beginners.

## Tradeoffs 

- Removed `Promise` from `ServerHook` type => `beforeRouting` and
`afterRouting` become sync
- No further async features to `createServer`

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

## Summary by CodeRabbit

* **Documentation**
* Updated code examples to show synchronous server initialization
without `await`

* **Refactor**
* Server creation function is now fully synchronous; remove `await` when
invoking it
  * Server lifecycle hooks execute synchronously during initialization

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: RobinTail

README.md

@@ -683,9 +683,7 @@ const config = createConfig({
   }, // ... cors, logger, etc
 });
 
-// 'await' is only needed if you're going to use the returned entities.
-// For top level CJS you can wrap you code with (async () => { ... })()
-const { app, servers, logger } = await createServer(config, routing);
+const { app, servers, logger } = createServer(config, routing);
 ```
 
 Ensure having `@types/node` package installed. At least you need to specify the port (usually it is 443) or UNIX socket,

example/index.ts

@@ -2,9 +2,4 @@ import { createServer } from "express-zod-api";
 import { config } from "./config.ts";
 import { routing } from "./routing.ts";
 
-/**
- * "await" is only needed for using entities returned from this method.
- * If you can not use await (on the top level of CJS), use IIFE wrapper:
- * @example (async () => { await ... })()
- * */
-await createServer(config, routing);
+createServer(config, routing);

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

@@ -156,12 +156,11 @@ 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 */
   getLogger: GetLogger;
-}) => void | Promise<void>;
+}) => void;
 
 export interface HttpConfig {
   /** @desc Port, UNIX socket or custom options. */

express-zod-api/src/server.ts

@@ -63,7 +63,7 @@ export const attachRouting = (config: AppConfig, routing: Routing) => {
   return { notFoundHandler, logger };
 };
 
-export const createServer = async (config: ServerConfig, routing: Routing) => {
+export const createServer = (config: ServerConfig, routing: Routing) => {
   const { logger, getLogger, notFoundHandler, catcher, loggingMiddleware } =
     makeCommonEntities(config);
   const app = express()
@@ -80,7 +80,7 @@ export const createServer = async (config: ServerConfig, routing: Routing) => {
     );
   }
   if (config.cookies) app.use(createCookieParser({ config }));
-  await config.beforeRouting?.({ app, getLogger });
+  config.beforeRouting?.({ app, getLogger });
 
   const parsers: Parsers = {
     json: [config.jsonParser || express.json()],
@@ -90,7 +90,7 @@ export const createServer = async (config: ServerConfig, routing: Routing) => {
   };
   initRouting({ app, routing, getLogger, config, parsers });
 
-  await config.afterRouting?.({ app, getLogger });
+  config.afterRouting?.({ app, getLogger });
   app.use(catcher, notFoundHandler);
 
   const created: Array<http.Server | https.Server> = [];

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

@@ -40,7 +40,7 @@ describe("Server", () => {
   });
 
   describe("createServer()", () => {
-    test("Should create server with minimal config", async () => {
+    test("Should create server with minimal config", () => {
       const port = givePort();
       const configMock = {
         http: { listen: port },
@@ -58,7 +58,7 @@ describe("Server", () => {
           }),
         },
       };
-      const { servers } = await createServer(configMock, routingMock);
+      const { servers } = createServer(configMock, routingMock);
       expect(servers).toHaveLength(1);
       expect(servers[0]).toBeTruthy();
       expect(appMock).toBeTruthy();
@@ -90,7 +90,7 @@ describe("Server", () => {
       expect(httpListenSpy).toHaveBeenCalledWith(port, expect.any(Function));
     });
 
-    test("Should create server with custom parsers, logger, error handler and hooks", async () => {
+    test("Should create server with custom parsers, logger, error handler and hooks", () => {
       const customLogger = new BuiltinLogger({ level: "silent" });
       const infoMethod = vi.spyOn(customLogger, "info");
       const port = givePort();
@@ -135,7 +135,7 @@ describe("Server", () => {
           }),
         },
       };
-      const { logger, app } = await createServer(
+      const { logger, app } = createServer(
         configMock as unknown as ServerConfig,
         routingMock,
       );
@@ -211,7 +211,7 @@ describe("Server", () => {
       );
     });
 
-    test("should create a HTTPS server on request", async () => {
+    test("should create a HTTPS server on request", () => {
       const configMock = {
         https: {
           listen: givePort(),
@@ -230,7 +230,7 @@ describe("Server", () => {
         },
       };
 
-      const { servers } = await createServer(configMock, routingMock);
+      const { servers } = createServer(configMock, routingMock);
       expect(servers).toHaveLength(1);
       expect(servers[0]).toBeTruthy();
       expect(createHttpsServerSpy).toHaveBeenCalledWith(
@@ -244,7 +244,7 @@ describe("Server", () => {
       );
     });
 
-    test("should create both HTTP and HTTPS servers", async () => {
+    test("should create both HTTP and HTTPS servers", () => {
       const configMock = {
         http: { listen: givePort() },
         https: {
@@ -255,47 +255,47 @@ describe("Server", () => {
         startupLogo: false,
         logger: { level: "warn" as const },
       };
-      const { servers } = await createServer(configMock, {});
+      const { servers } = createServer(configMock, {});
       expect(servers).toHaveLength(2);
       expect(servers[0]).toBeTruthy();
       expect(servers[1]).toBeTruthy();
     });
 
-    test("should warn when neigher configured", async () => {
+    test("should warn when neigher configured", () => {
       const customLogger = new BuiltinLogger({ level: "silent" });
       const warnMethod = vi.spyOn(customLogger, "warn");
-      await createServer(
+      createServer(
         { cors: false, startupLogo: false, logger: customLogger },
         {},
       );
       expect(warnMethod).toHaveBeenCalledWith("No servers configured.");
     });
 
-    test("should enable compression on request", async () => {
+    test("should enable compression on request", () => {
       const configMock = {
         http: { listen: givePort() },
         compression: true,
         cors: true,
         startupLogo: false,
         logger: { level: "warn" },
       } satisfies ServerConfig;
-      await createServer(configMock, {});
+      createServer(configMock, {});
       expect(appMock.use).toHaveBeenCalledTimes(3);
       expect(compressionMock).toHaveBeenCalledTimes(1);
       expect(compressionMock).toHaveBeenCalledWith(undefined);
     });
 
     test.each([true, { secret: "my-secret" }])(
       "should enable cookie parser on demand %#",
-      async (cookies) => {
+      (cookies) => {
         const configMock = {
           http: { listen: givePort() },
           cookies,
           cors: true,
           startupLogo: false,
           logger: { level: "warn" },
         } satisfies ServerConfig;
-        await createServer(configMock, {});
+        createServer(configMock, {});
         expect(appMock.use).toHaveBeenCalledTimes(3);
         expect(cookieParserMock).toHaveBeenCalledTimes(1);
         expect(cookieParserMock).toHaveBeenCalledWith(
@@ -305,7 +305,7 @@ describe("Server", () => {
       },
     );
 
-    test("should enable uploads on request", async () => {
+    test("should enable uploads on request", () => {
       const configMock = {
         http: { listen: givePort() },
         upload: {
@@ -328,7 +328,7 @@ describe("Server", () => {
           }),
         },
       };
-      await createServer(configMock, routingMock);
+      createServer(configMock, routingMock);
       expect(appMock.use).toHaveBeenCalledTimes(2);
       expect(appMock.get).toHaveBeenCalledTimes(1);
       expect(appMock.get).toHaveBeenCalledWith(
@@ -340,7 +340,7 @@ describe("Server", () => {
       );
     });
 
-    test("should enable raw on request", async () => {
+    test("should enable raw on request", () => {
       const configMock = {
         http: { listen: givePort() },
         cors: true,
@@ -356,7 +356,7 @@ describe("Server", () => {
           }),
         },
       };
-      await createServer(configMock, routingMock);
+      createServer(configMock, routingMock);
       expect(appMock.use).toHaveBeenCalledTimes(2);
       expect(appMock.get).toHaveBeenCalledTimes(1);
       expect(appMock.get).toHaveBeenCalledWith(
@@ -368,7 +368,7 @@ describe("Server", () => {
       );
     });
 
-    test("should enable urlencoded on request", async () => {
+    test("should enable urlencoded on request", () => {
       const configMock = {
         http: { listen: givePort() },
         cors: false,
@@ -383,7 +383,7 @@ describe("Server", () => {
           }),
         },
       };
-      await createServer(configMock, routingMock);
+      createServer(configMock, routingMock);
       expect(appMock.use).toHaveBeenCalledTimes(2);
       expect(appMock.get).toHaveBeenCalledTimes(1);
       expect(appMock.get).toHaveBeenCalledWith(

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

@@ -17,7 +17,7 @@ import {
 import { givePort } from "../../tools/ports";
 import { setTimeout } from "node:timers/promises";
 
-describe("App in production mode", async () => {
+describe("App in production mode", () => {
   vi.stubEnv("TSDOWN_STATIC", "production");
   vi.stubEnv("NODE_ENV", "production");
   const port = givePort();
@@ -176,13 +176,16 @@ describe("App in production mode", async () => {
   });
   const {
     servers: [server],
-  } = await createServer(config, routing);
+  } = createServer(config, routing);
   expect(server).toBeTruthy();
-  await vi.waitFor(() => assert(server!.listening), { timeout: 1e4 });
-  expect(warnMethod).toHaveBeenCalledWith(
-    "DeprecationError (express): Sample deprecation message",
-    expect.any(Array), // stack
-  );
+
+  beforeAll(async () => {
+    await vi.waitFor(() => assert(server!.listening), { timeout: 1e4 });
+    expect(warnMethod).toHaveBeenCalledWith(
+      "DeprecationError (express): Sample deprecation message",
+      expect.any(Array), // stack
+    );
+  });
 
   afterAll(async () => {
     server!.close();