Merge pull request #9 from wuespace/localized-http-exception

Add `LocalizedHttpException` for nice, localized error handling

Author: pklaschka

example/main.tsx

@@ -1,6 +1,6 @@
 import { Hono } from "@hono/hono";
 import { jsxRenderer } from "@hono/hono/jsx-renderer";
-import { lt, t, useLocale } from "@wuespace/honolate";
+import { LocalizedHttpException, lt, t, useLocale } from "@wuespace/honolate";
 import { withI18n } from "./i18n.ts";
 
 const lazyTerm = lt`Lazy term`;
@@ -10,6 +10,21 @@ export const app = new Hono()
     withI18n,
     jsxRenderer(),
   )
+  .onError((err, c) => {
+    const localizedError = LocalizedHttpException.fromCause(err);
+    console.error("[app]", localizedError);
+    return c.json({
+      errorId: localizedError.errorId,
+      title: t(localizedError.options.localizedTitle ?? lt`Unknown Error`),
+      message: t(
+        localizedError.options.localizedMessage ??
+          lt`An unexpected error occurred while processing your request.`,
+      ),
+      technicalMessage: localizedError.options.technicalMessage,
+    }, {
+      status: localizedError.status,
+    });
+  })
   .get("/text", (c) => c.text(t`Hello world!`))
   .get("/locale", (c) => c.text(useLocale()))
   .get("/render", (c) => c.render(<h1>{t`Hello world!`}</h1>))
@@ -27,6 +42,14 @@ export const app = new Hono()
     "/escape-test",
     (c) => c.text(t`This text contains ${1} {} curly braces and \\{{}}{0}.`),
   )
+  .get("/trigger-500", () => {
+    throw new LocalizedHttpException({
+      status: 500,
+      localizedTitle: lt`Hello world!`,
+      localizedMessage: lt`Untranslated text`,
+      technicalMessage: "Technical message",
+    });
+  })
   .notFound((c) => c.text("Not Found", 404));
 
 import.meta.main && Deno.serve(app.fetch);

lib/hono/LocalizedHttpException.ts

@@ -0,0 +1,130 @@
+import { HTTPException } from "@hono/hono/http-exception";
+import type { LazyLocalizedString } from "./LazyLocalizedString.ts";
+
+/**
+ * Options for creating a LocalizedHttpException.
+ */
+export interface LocalizedHttpExceptionOptions {
+  /**
+   * Technical message for this error. Logged for debugging purposes.
+   * This is the only message guaranteed to be logged.
+   */
+  readonly technicalMessage?: string;
+  /**
+   * HTTP status code to be used for this error.
+   * Defaults to 500 (Internal Server Error).
+   */
+  readonly status?: HTTPException["status"];
+  /**
+   * Optional cause of this error. Logged for debugging purposes.
+   */
+  readonly cause?: unknown;
+  /**
+   * Localized title for this error. Shown to the user.
+   */
+  readonly localizedTitle?: LazyLocalizedString;
+  /**
+   * Localized message for this error. Shown to the user.
+   */
+  readonly localizedMessage?: LazyLocalizedString;
+}
+
+/**
+ * An HTTP exception that supports localization.
+ *
+ * Contains both technical details for logging and user-friendly localized messages.
+ *
+ * Use {@link fromCause} to convert arbitrary errors / exceptions into LocalizedHttpExceptions.
+ *
+ * By logging the LocalizedHttpException, the technical message and cause are preserved for debugging purposes.
+ * Logs and user messages can be correlated using the {@link errorId}.
+ *
+ * See {@link LocalizedHttpExceptionOptions} for details on the available options.
+ *
+ * @example
+ *
+ * ```ts
+ * throw new LocalizedHttpException({
+ *   technicalMessage: "Database connection failed",
+ *   status: 503,
+ *   localizedTitle: lt`Service Unavailable`,
+ *   localizedMessage: lt`The service is currently unavailable. Please try again later.`,
+ * });
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * router.onError((err, c) => {
+ *   const localizedError = LocalizedHttpException.fromCause(err);
+ *   console.error("[router]", localizedError);
+ *   c.status(localizedError.status || 500);
+ *   return c.render(
+ *     <>
+ *       <h1>{ t(localizedError.options.localizedTitle ?? lt`Unknown Error`)}</h1>
+ *       <p>{ t(localizedError.options.localizedMessage ?? lt`An unexpected error occurred while processing your request.`) }</p>
+ *       <p>{ t(`Please specify the following error ID when contacting support:`) }</p>
+ *       <pre><code>{ localizedError.errorId }</code></pre>
+ *     </>
+ *   );
+ * });
+ * ```
+ */
+export class LocalizedHttpException extends HTTPException {
+  /**
+   * Unique error ID for this exception instance.
+   * Used for correlating logs with user reports.
+   *
+   * Format: ISO timestamp + "-" + first 8 characters of a UUIDv4
+   */
+  public readonly errorId: string = new Date().toISOString() + "-" +
+    crypto.randomUUID().substring(0, 8);
+
+  /**
+   * Creates a new LocalizedHttpException.
+   * Use {@link fromCause} to convert arbitrary errors / exceptions into LocalizedHttpExceptions.
+   * @param options the options for the error. See {@link LocalizedHttpExceptionOptions} for details
+   */
+  constructor(
+    public readonly options: LocalizedHttpExceptionOptions = {},
+  ) {
+    super(options.status ?? 500, {
+      cause: options.cause,
+    });
+    this.message = options.technicalMessage
+      ? `<${this.errorId}> ${options.technicalMessage}`
+      : `<${this.errorId}>`;
+  }
+
+  /**
+   * Converts an arbitrary error into a LocalizedHttpException.
+   *
+   * Useful for error handlers that can receive any kind of error.
+   * After conversion, the returned LocalizedHttpException can be used to
+   * retrieve localized messages for the user.
+   *
+   * By logging the returned LocalizedHttpException, the technical message
+   * and cause are preserved for debugging purposes.
+   * Logs and user messages can be correlated using the {@link errorId}.
+   * @param error the original error
+   * @returns a corresponding {@link LocalizedHttpException}
+   */
+  static fromCause(
+    error: unknown,
+  ): LocalizedHttpException {
+    if (error instanceof LocalizedHttpException) {
+      return error;
+    }
+    if (error instanceof HTTPException) {
+      return new LocalizedHttpException({
+        technicalMessage: error.message,
+        status: error.status,
+        cause: error,
+      });
+    }
+    return new LocalizedHttpException({
+      technicalMessage: "Unknown error (see cause for details)",
+      cause: error,
+    });
+  }
+}

lib/mod.ts

@@ -7,3 +7,7 @@ export { runCLI } from "./extract/runCLI.ts";
 export { useLocale } from "./hono/useLocale.ts";
 export type { LocalizedStringValue } from "./hono/LocalizedStringValue.ts";
 export type { LazyLocalizedString } from "./hono/LazyLocalizedString.ts";
+export {
+  LocalizedHttpException,
+  type LocalizedHttpExceptionOptions,
+} from "./hono/LocalizedHttpException.ts";

tests/hono-e2e.test.ts

@@ -72,6 +72,43 @@ describe("Hono + Honolate E2E", () => {
       );
     });
   });
+  describe("Error handling and LocalizedHttpException", () => {
+    const origConsoleLog = console.error;
+    const logs = new Set();
+    function before() {
+      console.error = (...args) => {
+        logs.add(args.join("\n"));
+      };
+    }
+    function after() {
+      logs.clear();
+      console.error = origConsoleLog;
+    }
+
+    it("GET /trigger-500 should return localized error response", async () => {
+      before();
+      // @ts-expect-error testing purposes
+      const resDefault = await (await testApp["trigger-500"].$get({})).json();
+      // @ts-expect-error testing purposes
+      const resEn = await (await testApp["trigger-500"].$get({
+        query: { lang: "en" },
+      })).json();
+      // @ts-expect-error testing purposes
+      const resDe = await (await testApp["trigger-500"].$get({
+        query: { lang: "de" },
+      })).json();
+
+      expect(resDefault.title).toBe("Hello world!");
+      expect(resDefault.message).toBe("Untranslated text");
+      expect(resEn.title).toBe("Hello world!");
+      expect(resEn.message).toBe("Untranslated text");
+      expect(resDe.title).toBe("Hallo Welt!");
+      expect(resDe.message).toBe("Untranslated text");
+
+      expect(logs.size).toBe(3);
+      after();
+    });
+  });
   describe("Locale", () => {
     it("GET /locale should return correct locale", async () => {
       const resDefault = await (await testApp.locale.$get({})).text();