fix: throw clear error for invalid route return values

src/create-with-winter-spec.ts

@@ -126,6 +126,7 @@ function serializeResponse(
 ): Middleware {
   return async (req, ctx, next) => {
     const rawResponse = await next(req, ctx)
+    assertValidResponseValue(rawResponse)
 
     const statusCode =
       rawResponse instanceof WinterSpecResponse
@@ -150,6 +151,32 @@ function serializeResponse(
   }
 }
 
+function assertValidResponseValue(rawResponse: unknown): asserts rawResponse is SerializableToResponse | Response {
+  if (rawResponse == null) {
+    throw new Error(
+      "Route handlers must return a Response. If you are returning JSON, use ctx.json({...})."
+    )
+  }
+
+  if (typeof rawResponse === "object") {
+    if (
+      rawResponse instanceof Response ||
+      rawResponse instanceof WinterSpecResponse ||
+      "serializeToResponse" in rawResponse
+    ) {
+      return
+    }
+
+    throw new Error(
+      "Use ctx.json({...}) instead of returning an object directly."
+    )
+  }
+
+  throw new Error(
+    "Route handlers must return a Response. If you are returning JSON, use ctx.json({...})."
+  )
+}
+
 export async function wrapMiddlewares(
   middlewares: MiddlewareChain,
   routeFn: WinterSpecRouteFn<any, any, any>,

tests/errors/do-not-allow-raw-json.test.ts

@@ -37,3 +37,37 @@ test("should throw an error when responding with raw JSON", async (t) => {
     )
   )
 })
+
+test("should throw a clear error when route returns undefined", async (t) => {
+  const { axios } = await getTestRoute(t, {
+    globalSpec: {
+      authMiddleware: {},
+      beforeAuthMiddleware: [
+        async (req, ctx, next) => {
+          try {
+            return await next(req, ctx)
+          } catch (e: any) {
+            return Response.json({ error: e.message }, { status: 500 })
+          }
+        },
+      ],
+    },
+    routeSpec: {
+      methods: ["GET"],
+      jsonBody: z.any(),
+      jsonResponse: z.any(),
+    },
+    routePath: "/",
+    routeFn: () => undefined as any,
+  })
+
+  const { data } = await axios.get("/", {
+    validateStatus: () => true,
+  })
+
+  t.true(
+    data.error.includes(
+      "Route handlers must return a Response. If you are returning JSON, use ctx.json({...})."
+    )
+  )
+})