Move localization context to AsyncLocalStorage

This makes a lot of things easier, including async contexts,[^1] `c.render()` calls,[^2] etc.

With this, the `asFC` helper function is no longer necessary.

Closes #5

[^1]: Cf. honojs/hono#3812 for details on why async contexts were hard with `useRequestContext()`
[^2]: Cf. https://jsr.io/@wuespace/honolate@0.1.0/doc/~/asFC for why this was more difficult, before.

Author: pklaschka

example/main.tsx

@@ -1,7 +1,7 @@
 import { Hono } from "@hono/hono";
-import { jsxRenderer, useRequestContext } from "@hono/hono/jsx-renderer";
+import { jsxRenderer } from "@hono/hono/jsx-renderer";
 // import { languageDetector } from '@hono/hono/language';
-import { asFC, t } from "@wuespace/honolate";
+import { t } from "@wuespace/honolate";
 import { withI18n } from "./i18n.ts";
 
 const app = new Hono();
@@ -18,14 +18,12 @@ app.use(
 
 app.get("/", (c) => {
   return c.render(
-    asFC(() => (
-      <div>
-        {t`Welcome to the {{}}}}{{ {0} {1} {{0}} {{1}} homepage ${useRequestContext().req.url}!`}
-        {t`Hello world!`}
-        {t`Test: ${<code>{t`Hello!`}</code>}`}
-        <LocalePrinter />
-      </div>
-    )),
+    <div>
+      {t`Welcome to the {{}}}}{{ {0} {1} {{0}} {{1}} homepage ${3}!`}
+      {t`Hello world!`}
+      {t`Test: ${<code>{t`Hello!`}</code>}`}
+      <LocalePrinter />
+    </div>,
   );
 });
 

lib/hono/LazyLocalizedString.ts

@@ -9,7 +9,7 @@ import type { LocalizedStringValue } from "./LocalizedStringValue.ts";
  */
 export type LazyLocalizedString = {
   /**
-   * The localization key used to look up the localized string.
+   * The escaped localization key used to look up the localized string.
    */
   localizationKey: string;
   /**

lib/hono/asFC.tsx

@@ -1,6 +1,11 @@
 import type { FC } from "@hono/hono/jsx";
 
 /**
+ * @deprecated This is no longer necessary as of Honolate v0.2.0, since `t` can now be used directly in route handlers.
+ * Previously, `t` used the request context, which was only available inside functional components.
+ * Now, `t` uses AsyncLocalStorage to access the localization context, making it usable directly in route handlers.
+ *
+ * @remarks
  * Converts a JSX element into a functional component.
  *
  * This is necessary to add support for hooks like `useRequestContext` within the element,

lib/hono/ensureLazyLocalizedString.ts

@@ -1,3 +1,4 @@
+import { escapeKey } from "../common/escapeKey.ts";
 import type { LazyLocalizedString } from "./LazyLocalizedString.ts";
 import type { LocalizedStringValue } from "./LocalizedStringValue.ts";
 import { lt } from "./lt.ts";
@@ -10,11 +11,13 @@ import { lt } from "./lt.ts";
  * @returns the input as a LazyLocalizedString
  */
 export function ensureLazyLocalizedString(
-  input: TemplateStringsArray | LazyLocalizedString,
-  values: LocalizedStringValue[],
+  input: TemplateStringsArray | LazyLocalizedString | string,
+  values?: LocalizedStringValue[],
 ): LazyLocalizedString {
-  if (Array.isArray(input)) {
-    return lt(input as TemplateStringsArray, ...values);
+  if (typeof input === "string") {
+    return { localizationKey: escapeKey(input), values: [] };
+  } else if (Array.isArray(input)) {
+    return lt(input as TemplateStringsArray, ...(values ?? []));
   } else {
     return input as LazyLocalizedString;
   }

lib/hono/getLocalizationMap.ts

@@ -1,35 +1,18 @@
-import { useRequestContext } from "@hono/hono/jsx-renderer";
-import { neverThrow } from "../common/neverThrow.ts";
+import { currentLocalizedValuesStorage } from "./initHonolate.ts";
 
 /**
  * @returns the current locale's localization map, mapping localization keys to their respective translations
  */
 export function getLocalizationMap(): Record<string, string> {
-  const ctx = neverThrow(() => useRequestContext());
-  if (ctx instanceof Error) {
+  const localizationMap = currentLocalizedValuesStorage.getStore();
+  if (!localizationMap) {
     console.warn(
       new Error(
-        "t was called outside of a request context. Using default locale 'default'." +
-          "\nMake sure to wrap t calls within a Hono JSX Renderer context." +
-          "\nIf you're not in a functional component, use asFC() to wrap the parameter of c.render():" +
-          "\nc.render(asFC(() => <>{t`...`}</>))" +
-          "\ninstead of c.render(<>{t`...`}</>)",
-        { cause: ctx },
+        "t was called outside of a request context." +
+          "\nMake sure to only call t within routes that use the middleware returned by initHonolate.",
       ),
     );
     return {};
   }
-
-  const map = ctx.get("localizedValues");
-  if (!map || typeof map !== "object") {
-    console.warn(
-      new Error(
-        "Localized values not found in request context. Using empty localization map." +
-          "\nMake sure to update the localization files and initialize Honolate middleware correctly.",
-        { cause: ctx },
-      ),
-    );
-    return {};
-  }
-  return map as Record<string, string>;
+  return localizationMap;
 }

lib/hono/initHonolate.ts

@@ -5,6 +5,15 @@ import type { HonolateContext } from "./HonolateContext.ts";
 import type { InitHonolateOptions } from "./InitHonolateOptions.ts";
 import type { LocalizedValue } from "./LocalizedValue.ts";
 import { ensureRequestLanguage } from "./ensureRequestLanguage.ts";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export const currentLocaleStorage = new AsyncLocalStorage<string>();
+export const currentLocalizedValuesStorage = new AsyncLocalStorage<
+  Record<
+    string,
+    LocalizedValue
+  >
+>();
 
 /**
  * Initializes Honolate with the given options.
@@ -54,7 +63,14 @@ export const initHonolate: <T extends string>(
 
     c.set("localizedValues", languages.get(language) || {});
 
-    return next();
+    return currentLocaleStorage.run(
+      language,
+      () =>
+        currentLocalizedValuesStorage.run(
+          c.get("localizedValues") || {},
+          next,
+        ),
+    );
   });
 };
 

lib/hono/t.ts

@@ -56,13 +56,6 @@ export function t(
   string: TemplateStringsArray | LazyLocalizedString | string,
   ...values: LocalizedStringValue[]
 ): string | HtmlEscapedString {
-  if (typeof string === "string") {
-    // simple string, return as is
-    string = {
-      localizationKey: string,
-      values: [],
-    };
-  }
   const lls = ensureLazyLocalizedString(string, values);
   const localizationValues = getLocalizationMap();
 

lib/hono/useLocale.ts

@@ -1,27 +1,15 @@
-import { useRequestContext } from "@hono/hono/jsx-renderer";
-import { neverThrow } from "../common/neverThrow.ts";
-
-export class LocaleNotFoundError extends Error {}
-export class NoRequestContextError extends Error {}
+import { currentLocaleStorage } from "./initHonolate.ts";
 
 /**
  * Returns the current locale code. Must be used within a Hono JSX Renderer context.
  * @returns the current locale code
  */
 export function useLocale(): string {
-  const ctx = neverThrow(() => useRequestContext());
-  if (ctx instanceof Error) {
-    throw new NoRequestContextError(
-      "useLocale must be used within a Hono JSX Renderer context.",
-      { cause: ctx },
+  const locale = currentLocaleStorage.getStore();
+  if (!locale) {
+    throw new Error(
+      "No locale found in AsyncLocalStorage. Make sure to use the initHonolate middleware.",
     );
   }
-  const locale = ctx.get("language");
-  if (typeof locale === "string") {
-    return locale;
-  }
-  throw new LocaleNotFoundError(
-    'Language ("language") not found in request context. Make sure to set it before using useLocale.' +
-      "\nOne option to do so is to use the languageDetector middleware provided by hono.",
-  );
+  return locale;
 }