equipped 5.3.0-alpha.0 → 5.3.0

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.0](https://github.com/kevinand11/equipped/compare/v5.3.0-alpha.0...v5.3.0) (2026-06-19)
+
+
+### Features
+
+* **server:** add custom not found fallback ([6173b4f](https://github.com/kevinand11/equipped/commit/6173b4ffb7f14dd7f965507c972f9fb1434dc5d1))
+
 ## [5.3.0-alpha.0](https://github.com/kevinand11/equipped/compare/v5.2.9...v5.3.0-alpha.0) (2026-06-16)
 
 

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

@@ -68,6 +68,7 @@ var RequestError = class extends EquippedError {
 };
 
 // src/server/adapters/base.ts
+var import_node_http = require("http");
 var import_cors = require("@fastify/cors");
 var import_cors2 = require("cors");
 var import_socket = require("socket.io");
@@ -839,6 +840,22 @@ var serverConfigPipe = () => import_valleyed6.v.object({
   ),
   socketsAuthMethods: import_valleyed6.v.defaults(import_valleyed6.v.array(import_valleyed6.v.instanceOf(BaseRequestAuthMethod)), [])
 });
+var rawResponseHandledSymbol = /* @__PURE__ */ Symbol("rawResponseHandled");
+var rawResponseHandled = Object.freeze({ [rawResponseHandledSymbol]: true });
+var rawResponseNotStartedMessage = "Raw not-found handler did not start or complete a response";
+function isRawResponseHandled(input) {
+  return Boolean(input && typeof input === "object" && rawResponseHandledSymbol in input);
+}
+function hasRawResponseStarted(response) {
+  return response.headersSent || response.writableEnded;
+}
+function writeRawHandlerError(response, error) {
+  if (hasRawResponseStarted(response)) return;
+  response.statusCode = StatusCodes.BadRequest;
+  response.setHeader("Content-Type", "application/json");
+  const message = error instanceof Error ? error.message : `${error}`;
+  response.end(JSON.stringify([{ message }]));
+}
 var errorsSchemas = Object.entries(StatusCodes).filter(([, value]) => value > 399).map(([key, value]) => ({
   status: value,
   contentType: "application/json",
@@ -855,6 +872,8 @@ var Server = class {
   #serverConfig;
   #queue = [];
   #routesByKey = /* @__PURE__ */ new Set();
+  #started = false;
+  #notFoundHandler = null;
   setup(httpServer, config) {
     this.#httpServer = httpServer;
     this.#serverConfig = config;
@@ -904,10 +923,16 @@ var Server = class {
       });
     });
   }
+  setNotFoundHandler(handler) {
+    if (this.#started) throw new EquippedError("Cannot set not-found handler after server has started", {});
+    this.#notFoundHandler = handler;
+    return this;
+  }
   test() {
     return (0, import_supertest.default)(this.#httpServer);
   }
   async start() {
+    this.#started = true;
     const config = this.#serverConfig;
     const instance = Instance.get();
     const { app } = instance.settings;
@@ -921,10 +946,7 @@ var Server = class {
         })
       });
     await Promise.all(this.#queue.map((cb) => cb()));
-    this.registerNotFoundHandler(async (req) => {
-      const request = await this.parseRequest(req);
-      throw new NotFoundError(`Route ${request.path} not found`);
-    });
+    this.registerNotFoundHandler(async (req, res) => await this.#handleNotFound(req, res));
     this.registerErrorHandler(async (error, _, res) => {
       if (!(error instanceof EquippedError)) Instance.get().log.error({ error }, "Uncaught error in route handler");
       const response = error instanceof RequestError ? new Response({
@@ -943,6 +965,31 @@ var Server = class {
     if (started) Instance.get().log.info(`${instance.id}(${app.name}) service listening on port ${config.port}`);
     return started;
   }
+  createNodeRawResponder(input) {
+    return async (handler) => {
+      input.beforeHandle?.();
+      try {
+        await handler(input.request, input.response);
+      } catch (error) {
+        if (!hasRawResponseStarted(input.response)) {
+          writeRawHandlerError(input.response, error);
+          return rawResponseHandled;
+        }
+        throw error;
+      }
+      if (!hasRawResponseStarted(input.response))
+        writeRawHandlerError(input.response, new EquippedError(rawResponseNotStartedMessage, {}));
+      return rawResponseHandled;
+    };
+  }
+  async #handleNotFound(req, res) {
+    const request = await this.parseRequest(req);
+    if (!this.#notFoundHandler) throw new NotFoundError(`Route ${request.path} not found`);
+    const result = await this.#notFoundHandler({ request, respondWithRaw: this.createRawResponder(req, res) });
+    if (isRawResponseHandled(result)) return;
+    if (result instanceof Response) return await this.handleResponse(res, result);
+    throw new EquippedError("Not-found handler must return a Response or respondWithRaw(...)", {});
+  }
   #resolveSchema(method, schema) {
     const defaultStatusCode = schema?.defaultStatusCode ?? StatusCodes.Ok;
     const defaultContentType = schema?.defaultContentType ?? "application/json";
@@ -1033,6 +1080,170 @@ var Server = class {
     };
   }
 };
+if (void 0) {
+  let ensureTestInstance = function() {
+    const instance = Instance.maybeGet() ?? Instance.create({ app: { name: "equipped-test" }, log: { level: "silent" } });
+    if (!testInstanceState.__equippedTestInstanceAliased) {
+      instance.alias("equipped-test");
+      testInstanceState.__equippedTestInstanceAliased = true;
+    }
+  }, createRawResponse = function() {
+    const chunks = [];
+    return {
+      statusCode: 200,
+      headersSent: false,
+      writableEnded: false,
+      headers: {},
+      setHeader(key, value) {
+        this.headers[key] = value;
+      },
+      end(chunk) {
+        if (chunk !== void 0) chunks.push(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk));
+        this.headersSent = true;
+        this.writableEnded = true;
+      },
+      body() {
+        return chunks.join("");
+      }
+    };
+  };
+  ensureTestInstance2 = ensureTestInstance, createRawResponse2 = createRawResponse;
+  const { describe, expect, test } = void 0;
+  const testInstanceState = globalThis;
+  class TestServer extends Server {
+    handledResponse = null;
+    notFoundHandler = null;
+    constructor() {
+      super();
+      this.setup(http.createServer(), {
+        port: 0,
+        cors: void 0,
+        eventBus: void 0,
+        publicPath: void 0,
+        healthPath: void 0,
+        openapi: { docsVersion: "1.0.0", docsBaseUrl: ["/"], docsPath: "/__docs" },
+        requests: {
+          log: false,
+          rateLimit: { enabled: false, periodInMs: 1, limit: 1 },
+          slowdown: { enabled: false, periodInMs: 1, delayAfter: 1, delayInMs: 1 }
+        },
+        socketsAuthMethods: []
+      });
+    }
+    async parseRequest(req) {
+      return new Request2({
+        ip: "127.0.0.1",
+        body: {},
+        cookies: {},
+        params: {},
+        query: {},
+        method: Methods.get,
+        path: req.path,
+        headers: {},
+        files: {}
+      });
+    }
+    async handleResponse(_, response) {
+      this.handledResponse = response;
+    }
+    createRawResponder(req, res) {
+      return this.createNodeRawResponder({ request: req.rawRequest, response: res.rawResponse });
+    }
+    registerRoute() {
+    }
+    registerErrorHandler() {
+    }
+    registerNotFoundHandler(cb) {
+      this.notFoundHandler = cb;
+    }
+    async startServer() {
+      return true;
+    }
+    async dispatchNotFound(path) {
+      if (!this.notFoundHandler) throw new Error("not-found handler was not registered");
+      this.handledResponse = null;
+      const rawResponse = createRawResponse();
+      await this.notFoundHandler({ path, rawRequest: {} }, { rawResponse });
+      return { handledResponse: this.handledResponse, rawResponse };
+    }
+  }
+  describe("Server not-found handler", () => {
+    test("throws the default Equipped not-found error when no custom handler is set", async () => {
+      ensureTestInstance();
+      const server = new TestServer();
+      await server.start();
+      await expect(server.dispatchNotFound("/missing")).rejects.toBeInstanceOf(NotFoundError);
+    });
+    test("allows a custom not-found handler to return an Equipped response", async () => {
+      ensureTestInstance();
+      const server = new TestServer();
+      server.setNotFoundHandler(
+        ({ request }) => new Response({
+          body: [{ message: `No route for ${request.path}` }],
+          status: StatusCodes.NotFound,
+          headers: {},
+          cookies: {},
+          contentType: "application/json"
+        })
+      );
+      await server.start();
+      const result = await server.dispatchNotFound("/custom");
+      expect(result.handledResponse?.status).toBe(StatusCodes.NotFound);
+      expect(result.handledResponse?.body).toEqual([{ message: "No route for /custom" }]);
+    });
+    test("allows a custom not-found handler to complete the response through a raw Node listener", async () => {
+      ensureTestInstance();
+      const server = new TestServer();
+      server.setNotFoundHandler(
+        ({ respondWithRaw }) => respondWithRaw((_, response) => {
+          response.statusCode = 203;
+          response.end("raw fallback");
+        })
+      );
+      await server.start();
+      const result = await server.dispatchNotFound("/page");
+      expect(result.handledResponse).toBeNull();
+      expect(result.rawResponse.statusCode).toBe(203);
+      expect(result.rawResponse.body()).toBe("raw fallback");
+    });
+    test("writes a clear raw error when a raw not-found handler does not start a response", async () => {
+      ensureTestInstance();
+      const server = new TestServer();
+      server.setNotFoundHandler(({ respondWithRaw }) => respondWithRaw(() => {
+      }));
+      await server.start();
+      const result = await server.dispatchNotFound("/page");
+      expect(result.handledResponse).toBeNull();
+      expect(result.rawResponse.statusCode).toBe(StatusCodes.BadRequest);
+      expect(result.rawResponse.body()).toContain(rawResponseNotStartedMessage);
+    });
+    test("rejects a custom not-found handler result that is neither an Equipped response nor raw completion", async () => {
+      ensureTestInstance();
+      const server = new TestServer();
+      server.setNotFoundHandler((() => void 0));
+      await server.start();
+      await expect(server.dispatchNotFound("/bad")).rejects.toThrow("Not-found handler must return a Response or respondWithRaw(...)");
+    });
+    test("rejects setting the custom not-found handler after server startup", async () => {
+      ensureTestInstance();
+      const server = new TestServer();
+      await server.start();
+      expect(
+        () => server.setNotFoundHandler(
+          () => new Response({
+            body: null,
+            status: StatusCodes.NotFound,
+            headers: {},
+            cookies: {},
+            contentType: "application/json"
+          })
+        )
+      ).toThrow("Cannot set not-found handler after server has started");
+    });
+  });
+}
+var ensureTestInstance2;
+var createRawResponse2;
 
 // src/errors/types/badRequestError.ts
 var BadRequestError = class extends RequestError {
@@ -1678,6 +1889,9 @@ var ExpressServer = class extends configurable(serverConfigPipe, Server) {
       response.body.pipe(res);
     }
   }
+  createRawResponder(req, res) {
+    return this.createNodeRawResponder({ request: req, response: res });
+  }
   registerRoute(method, path, cb) {
     this.#app[method]?.(path, async (req, res) => cb(req, res));
   }
@@ -1698,6 +1912,54 @@ var ExpressServer = class extends configurable(serverConfigPipe, Server) {
     });
   }
 };
+if (void 0) {
+  let ensureTestInstance = function() {
+    const instance = Instance.maybeGet() ?? Instance.create({ app: { name: "equipped-test" }, log: { level: "silent" } });
+    if (!testInstanceState.__equippedTestInstanceAliased) {
+      instance.alias("equipped-test");
+      testInstanceState.__equippedTestInstanceAliased = true;
+    }
+  }, createExpressResponse = function() {
+    return {
+      statusCode: 200,
+      headersSent: false,
+      writableEnded: false,
+      setHeader: vi.fn(),
+      end(chunk) {
+        void chunk;
+        this.headersSent = true;
+        this.writableEnded = true;
+      }
+    };
+  };
+  ensureTestInstance2 = ensureTestInstance, createExpressResponse2 = createExpressResponse;
+  const { describe, expect, test, vi } = void 0;
+  const testInstanceState = globalThis;
+  class TestExpressServer extends ExpressServer {
+    exposeRawResponder(req, res) {
+      return this.createRawResponder(req, res);
+    }
+  }
+  describe("ExpressServer raw responder", () => {
+    test("passes the Express request and response to the raw Node handler", async () => {
+      ensureTestInstance();
+      const server = TestExpressServer.create({ port: 0, requests: { log: false } });
+      const req = { marker: "request" };
+      const res = createExpressResponse();
+      let received = null;
+      await server.exposeRawResponder(
+        req,
+        res
+      )(async (request, response) => {
+        received = { request, response };
+        response.end("ok");
+      });
+      expect(received).toEqual({ request: req, response: res });
+    });
+  });
+}
+var ensureTestInstance2;
+var createExpressResponse2;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ExpressServer