feat: add runtime agnostic error handler

Adds a new option `onError` at the root level configuration.

Author: danielpza

docs/1.guide/5.options.md

@@ -94,6 +94,29 @@ serve({
 > - Use environment variables or secure secret management for production deployments
 > - Consider using automatic certificate management (e.g., Let's Encrypt) for production
 
+### `onError`
+
+Runtime agnostic error handler.
+
+> [!NOTE]
+>
+> This handler will take precedence over runtime specific error handlers.
+
+**Example:**
+
+```js
+import { serve } from "srvx";
+
+serve({
+  onError(error) {
+    return new Response(`<pre>${error}\n${error.stack}</pre>`, {
+      headers: { "Content-Type": "text/html" },
+    });
+  },
+  fetch: () => new Response("👋 Hello there!"),
+});
+```
+
 ## Runtime specific options
 
 ### Node.js

src/_plugin.ts

@@ -66,6 +66,10 @@ export function wrapFetch(server: Server, fetchHandler: ServerHandler) {
       }
     }
 
+    if (resPromise && server.options.onError) {
+      resPromise = resPromise.catch(server.options.onError);
+    }
+
     // Response hooks
     if (hasResponseHooks) {
       for (const resHook of responseHooks) {

src/types.ts

@@ -95,6 +95,13 @@ export interface ServerOptions {
     passphrase?: string;
   };
 
+  /**
+   * Runtime agnostic error handler (optional).
+   *
+   * @note This handler will take precedence over runtime specific error handlers.
+   */
+  onError?: (error: Error) => MaybePromise<Response>;
+
   /**
    * Node.js server options.
    */

test/_fixture.ts

@@ -29,6 +29,9 @@ export const server = serve({
         },
       })) satisfies ServerPlugin,
   ),
+  async onError(err) {
+    return new Response(`onError: ${err.message}`, { status: 500 });
+  },
   async fetch(req) {
     const Response =
       (globalThis as any).TEST_RESPONSE_CTOR || globalThis.Response;
@@ -70,6 +73,9 @@ export const server = serve({
       case "/req-headers-instanceof": {
         return new Response(req.headers instanceof Headers ? "yes" : "no");
       }
+      case "/error": {
+        throw new Error("test error");
+      }
     }
     return new Response("404", { status: 404 });
   },

test/_tests.ts

@@ -63,6 +63,12 @@ export function addTests(
     expect(await response.text()).toMatch(/ip: ::1|ip: 127.0.0.1/);
   });
 
+  test("runtime agnostic error handler (onError)", async () => {
+    const response = await fetch(url("/error"));
+    expect(response.status).toBe(500);
+    expect(await response.text()).toBe("onError: test error");
+  });
+
   describe("plugin", () => {
     for (const hook of ["req", "res"]) {
       for (const type of ["async", "sync"]) {