equipped 5.3.0 → 5.3.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [5.3.1](https://github.com/kevinand11/equipped/compare/v5.3.0...v5.3.1) (2026-06-19)
+
+
+### Features
+
+* **server:** add before listen hook ([f72134c](https://github.com/kevinand11/equipped/commit/f72134c67273023a3e98351dd079fa6600b6a43d))
+
 ## [5.3.0](https://github.com/kevinand11/equipped/compare/v5.3.0-alpha.0...v5.3.0) (2026-06-19)
 
 

package/dist/cjs/server/adapters/express/index.cjs

@@ -873,6 +873,7 @@ var Server = class {
   #queue = [];
   #routesByKey = /* @__PURE__ */ new Set();
   #started = false;
+  #beforeListenHandlers = [];
   #notFoundHandler = null;
   setup(httpServer, config) {
     this.#httpServer = httpServer;
@@ -928,6 +929,11 @@ var Server = class {
     this.#notFoundHandler = handler;
     return this;
   }
+  onBeforeListen(handler) {
+    if (this.#started) throw new EquippedError("Cannot add before-listen handler after server has started", {});
+    this.#beforeListenHandlers.push(handler);
+    return this;
+  }
   test() {
     return (0, import_supertest.default)(this.#httpServer);
   }
@@ -961,6 +967,7 @@ var Server = class {
       });
       return await this.handleResponse(res, response);
     });
+    for (const handler of this.#beforeListenHandlers) await handler({ httpServer: this.#httpServer, port: config.port });
     const started = await this.startServer(config.port);
     if (started) Instance.get().log.info(`${instance.id}(${app.name}) service listening on port ${config.port}`);
     return started;
@@ -1112,6 +1119,7 @@ if (void 0) {
   const testInstanceState = globalThis;
   class TestServer extends Server {
     handledResponse = null;
+    startedPorts = [];
     notFoundHandler = null;
     constructor() {
       super();
@@ -1156,7 +1164,8 @@ if (void 0) {
     registerNotFoundHandler(cb) {
       this.notFoundHandler = cb;
     }
-    async startServer() {
+    async startServer(port) {
+      this.startedPorts.push(port);
       return true;
     }
     async dispatchNotFound(path) {
@@ -1167,6 +1176,43 @@ if (void 0) {
       return { handledResponse: this.handledResponse, rawResponse };
     }
   }
+  describe("Server before-listen handlers", () => {
+    test("runs before-listen handlers before adapter listen in registration order", async () => {
+      ensureTestInstance();
+      const server = new TestServer();
+      const calls = [];
+      let receivedServer = null;
+      server.onBeforeListen(({ httpServer, port }) => {
+        calls.push(`first:${port}`);
+        receivedServer = httpServer;
+        expect(server.startedPorts).toEqual([]);
+      }).onBeforeListen(({ httpServer, port }) => {
+        calls.push(`second:${port}`);
+        expect(httpServer).toBe(receivedServer);
+        expect(server.startedPorts).toEqual([]);
+      });
+      await server.start();
+      expect(calls).toEqual(["first:0", "second:0"]);
+      expect(receivedServer).toBeInstanceOf(http.Server);
+      expect(server.startedPorts).toEqual([0]);
+    });
+    test("rejects startup when a before-listen handler fails before adapter listen", async () => {
+      ensureTestInstance();
+      const server = new TestServer();
+      server.onBeforeListen(async () => {
+        throw new Error("before-listen failed");
+      });
+      await expect(server.start()).rejects.toThrow("before-listen failed");
+      expect(server.startedPorts).toEqual([]);
+    });
+    test("rejects adding before-listen handlers after server startup", async () => {
+      ensureTestInstance();
+      const server = new TestServer();
+      await server.start();
+      expect(() => server.onBeforeListen(() => {
+      })).toThrow("Cannot add before-listen handler after server has started");
+    });
+  });
   describe("Server not-found handler", () => {
     test("throws the default Equipped not-found error when no custom handler is set", async () => {
       ensureTestInstance();