fix(errors): surface ctx.json guidance when route returns raw object

src/middleware/http-exceptions.ts

@@ -70,3 +70,9 @@ export class ResponseValidationError extends WinterSpecMiddlewareError {
     super(formatZodError(error), 500)
   }
 }
+
+export class InvalidRouteReturnError extends WinterSpecMiddlewareError {
+  constructor(message: string) {
+    super(message, 500)
+  }
+}

src/middleware/with-response-object-check.ts

@@ -1,4 +1,4 @@
-import { ResponseValidationError } from "./http-exceptions.js"
+import { InvalidRouteReturnError } from "./http-exceptions.js"
 import { Middleware } from "./types.js"
 import { RouteSpec } from "src/types/route-spec.js"
 
@@ -9,7 +9,7 @@ export const withResponseObjectCheck: Middleware<
   const rawResponse = await next(req, ctx)
 
   if (typeof rawResponse === "object" && !(rawResponse instanceof Response)) {
-    throw new Error(
+    throw new InvalidRouteReturnError(
       "Use ctx.json({...}) instead of returning an object directly."
     )
   }

src/middleware/with-unhandled-exception-handling.ts

@@ -13,6 +13,9 @@ export const withUnhandledExceptionHandling: Middleware<{
       logger.warn(
         "Caught unhandled HTTP exception thrown by WinterSpec provided middleware. Consider adding createWithDefaultExceptionHandling middleware to your global or route spec."
       )
+      return new Response(e?.message ?? null, {
+        status: e?.status ?? 500,
+      })
     } else {
       logger.warn(
         "Caught unknown unhandled exception; consider adding a exception handling middleware to your global or route spec."

tests/errors/raw-object-default-error-message.test.ts

@@ -0,0 +1,32 @@
+import test from "ava"
+import { z } from "zod"
+import { getTestRoute } from "tests/fixtures/get-test-route.js"
+
+test("returning a raw object surfaces ctx.json guidance by default", async (t) => {
+  const { axios } = await getTestRoute(t, {
+    globalSpec: {
+      authMiddleware: {},
+    },
+    routeSpec: {
+      methods: ["GET"],
+      jsonBody: z.any(),
+      jsonResponse: z.any(),
+    },
+    routePath: "/",
+    routeFn: () => {
+      return { foo: "bar" } as any
+    },
+  })
+
+  const response = await axios.get("/", {
+    validateStatus: () => true,
+    responseType: "text",
+  })
+
+  t.is(response.status, 500)
+  t.true(
+    String(response.data).includes(
+      "Use ctx.json({...}) instead of returning an object directly"
+    )
+  )
+})