feat: HEAD method handling

example/factories.ts

@@ -9,6 +9,7 @@ import {
 } from "express-zod-api";
 import { authMiddleware } from "./middlewares";
 import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
 import { z } from "zod/v4";
 
 /** @desc This factory extends the default one by enforcing the authentication using the specified middleware */
@@ -34,12 +35,15 @@ export const fileStreamingEndpointsFactory = new EndpointsFactory(
   new ResultHandler({
     positive: { schema: ez.buffer(), mimeType: "image/*" },
     negative: { schema: z.string(), mimeType: "text/plain" },
-    handler: ({ response, error, output }) => {
+    handler: async ({ response, error, output, request: { method } }) => {
       if (error) return void response.status(400).send(error.message);
       if ("filename" in output && typeof output.filename === "string") {
-        createReadStream(output.filename).pipe(
-          response.attachment(output.filename),
-        );
+        const target = response.attachment(output.filename);
+        if (method === "HEAD") {
+          const { size } = await stat(output.filename);
+          return void target.set("Content-Length", `${size}`).end();
+        }
+        createReadStream(output.filename).pipe(target);
       } else {
         response.status(400).send("Filename is missing");
       }

example/index.spec.ts

@@ -170,6 +170,20 @@ describe("Example", async () => {
       expect(hash).toMatchSnapshot();
     });
 
+    test("Should inform on content length for sendable image", async () => {
+      const response = await fetch(
+        `http://localhost:${port}/v1/avatar/send?userId=123`,
+        { method: "HEAD" },
+      );
+      expect(response.status).toBe(200);
+      expect(response.headers.has("Content-type")).toBeTruthy();
+      expect(response.headers.get("Content-type")).toBe(
+        "image/svg+xml; charset=utf-8",
+      );
+      expect(response.headers.has("Content-Length")).toBeTruthy();
+      expect(response.headers.get("Content-Length")).toBe("48687");
+    });
+
     test("Should stream an image with a correct header", async () => {
       const response = await fetch(
         `http://localhost:${port}/v1/avatar/stream?userId=123`,
@@ -194,6 +208,21 @@ describe("Example", async () => {
       expect(hash).toMatchSnapshot();
     });
 
+    test("Should inform on content length for streaming image", async () => {
+      const response = await fetch(
+        `http://localhost:${port}/v1/avatar/stream?userId=123`,
+        { method: "HEAD" },
+      );
+      expect(response.status).toBe(200);
+      expect(response.headers.has("Content-type")).toBeTruthy();
+      expect(response.headers.get("Content-type")).toBe("image/svg+xml");
+      expect(response.headers.get("Content-Disposition")).toBe(
+        `attachment; filename="logo.svg"`,
+      );
+      expect(response.headers.has("Content-Length")).toBeTruthy();
+      expect(response.headers.get("Content-Length")).toBe("48687");
+    });
+
     test("Should serve static files", async () => {
       const response = await fetch(`http://localhost:${port}/public/logo.svg`);
       expect(response.status).toBe(200);

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

@@ -51,8 +51,9 @@ export const getInput = (
   req: Request,
   userDefined: CommonConfig["inputSources"] = {},
 ): FlatObject => {
-  const method = getActualMethod(req);
-  if (method === "options") return {};
+  const actualMethod = getActualMethod(req);
+  if (actualMethod === "options") return {};
+  const method = actualMethod === "head" ? "get" : actualMethod;
   return (
     userDefined[method] ||
     defaultInputSources[method] ||

express-zod-api/src/method.ts

@@ -10,7 +10,7 @@ export const methods = [
 
 export type Method = (typeof methods)[number];
 
-export type AuxMethod = Extract<keyof IRouter, "options">;
+export type AuxMethod = Extract<keyof IRouter, "options" | "head">;
 
 export const isMethod = (subject: string): subject is Method =>
   (methods as string[]).includes(subject);

express-zod-api/src/routing.ts

@@ -6,7 +6,7 @@ import { ContentType } from "./content-type";
 import { DependsOnMethod } from "./depends-on-method";
 import { Diagnostics } from "./diagnostics";
 import { AbstractEndpoint } from "./endpoint";
-import { AuxMethod, Method } from "./method";
+import { AuxMethod, isMethod, Method } from "./method";
 import { OnEndpoint, walkRouting } from "./routing-walker";
 import { ServeStatic } from "./serve-static";
 import { GetLogger } from "./server-helpers";
@@ -25,8 +25,8 @@ export interface Routing {
 export type Parsers = Partial<Record<ContentType, RequestHandler[]>>;
 
 const lineUp = (methods: Array<Method | AuxMethod>) =>
-  methods // options is last, fine to sort in-place
-    .sort((a, b) => +(a === "options") - +(b === "options"))
+  methods // auxiliary methods go last
+    .sort((a, b) => +isMethod(b) - +isMethod(a) || a.localeCompare(b))
     .join(", ")
     .toUpperCase();
 
@@ -81,6 +81,8 @@ export const initRouting = ({
   const deprioritized = new Map<string, RequestHandler>();
   for (const [path, methods] of familiar) {
     const accessMethods = Array.from(methods.keys());
+    /** @link https://github.com/RobinTail/express-zod-api/discussions/2791#discussioncomment-13745912 */
+    if (accessMethods.includes("get")) accessMethods.push("head");
     for (const [method, [matchingParsers, endpoint]] of methods) {
       const handlers = matchingParsers
         .slice() // must be immutable

express-zod-api/tests/common-helpers.spec.ts

@@ -69,6 +69,13 @@ describe("Common Helpers", () => {
         param: 123,
       });
     });
+    test("should return query for HEAD requests by default", () => {
+      expect(
+        getInput(makeRequestMock({ method: "HEAD", query: { param: 123 } })),
+      ).toEqual({
+        param: 123,
+      });
+    });
     test("should return only query for DELETE requests by default", () => {
       expect(
         getInput(

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

@@ -20,8 +20,10 @@ describe("Method", () => {
   });
 
   describe("AuxMethod", () => {
-    test("should be options", () => {
-      expectTypeOf<AuxMethod>().toEqualTypeOf("options" as const);
+    test("should be options or head", () => {
+      expectTypeOf<"options">().toExtend<AuxMethod>();
+      expectTypeOf<"head">().toExtend<AuxMethod>();
+      expectTypeOf<"other">().not.toExtend<AuxMethod>();
     });
   });
 

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

@@ -232,7 +232,7 @@ describe("Routing", () => {
       expect(responseMock._getStatusCode()).toBe(200);
       expect(responseMock._getHeaders()).toEqual({
         "access-control-allow-origin": "*",
-        "access-control-allow-methods": "GET, POST, PUT, PATCH, OPTIONS",
+        "access-control-allow-methods": "GET, PATCH, POST, PUT, HEAD, OPTIONS",
         "access-control-allow-headers": "content-type",
         "x-custom-header": "Testing",
       });
@@ -362,7 +362,7 @@ describe("Routing", () => {
       expect(responseMock._getStatusCode()).toBe(200);
       expect(responseMock._getHeaders()).toEqual({
         "access-control-allow-origin": "*",
-        "access-control-allow-methods": "GET, POST, OPTIONS",
+        "access-control-allow-methods": "GET, POST, HEAD, OPTIONS",
         "access-control-allow-headers": "content-type",
       });
     });

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

@@ -437,7 +437,7 @@ describe("App in production mode", async () => {
         }),
       });
       expect(response.status).toBe(405);
-      expect(response.headers.get("Allow")).toBe("GET, POST");
+      expect(response.headers.get("Allow")).toBe("GET, POST, HEAD");
       const json = await response.json();
       expect(json).toMatchSnapshot();
     });