Merge pull request #6 from wuespace/pklaschka/issue5

Use AsyncLocalStorage for better flexibility

Author: pklaschka

README.md

@@ -21,18 +21,18 @@ Create an `i18n.ts` file to configure your localization settings:
 
 ```typescript
 #!/usr/bin/env -S deno run --allow-read --allow-write=./locales/ --allow-env
-import { HonolateConfig, initHonolate, runCLI } from "@wuespace/honolate";
+import { initHonolate, InitHonolateOptions, runCLI } from "@wuespace/honolate";
 
-const config: HonolateConfig = {
-  defaultLocale: "en",
-  supportedLocales: {
+const config = {
+  defaultLanguage: "en",
+  languages: {
     en: import.meta.resolve("./locales/en.json"),
     de: import.meta.resolve("./locales/de.json"),
   },
-};
+} satisfies InitHonolateOptions<string>;
 
 // CLI
-import.meta.main && await runCLI(config, import.meta.dirname);
+import.meta.main && await runCLI(config, import.meta.dirname ?? Deno.cwd());
 
 // Middleware for Hono
 export const i18n = await initHonolate(config);
@@ -73,31 +73,16 @@ Deno.serve(app);
 You can use eager strings for immediate translation:
 
 ```typescript
-import { asFC, t } from "@wuespace/honolate";
+import { t } from "@wuespace/honolate";
 
-c.render(asFC(() => (
+c.render(
   <div>
     <h1>{t`Hello world!`}</h1>
     <p>{t`We can also use variables like ${new Date()}.`}</p>
-  </div>
-)));
+  </div>,
+);
 ```
 
-Note that the `t` function internally uses `useRequestContext` to access the
-current request context. For this to work, it can only be called inside a
-component rendered with the `jsxRenderer` middleware. Here, we use `asFC` to
-create a functional component out of an inline JSX expression.
-
-Internally, all `asFC` does is to create a functional component:
-
-```typescript
-function asFC<T>(Component: () => JSX.Element) {
-  return <Component />;
-}
-```
-
-With that, everything inside the function now has access to the request context.
-
 ### Lazy strings
 
 Sometimes, you need to define strings outside of a component context. In this
@@ -116,11 +101,11 @@ function:
 import { t } from "@wuespace/honolate";
 import { greeting } from "./greeting.ts";
 
-c.render(asFC(() => (
+c.render(
   <div>
     <h1>{t(greeting)}</h1>
-  </div>
-)));
+  </div>,
+);
 ```
 
 ### Updating localization files

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 ${c.req.url}!`}
+      {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

@@ -13,11 +13,10 @@ import type { LocalizedStringValue } from "./LocalizedStringValue.ts";
  *
  * Can be used as a template string tag or as a function with a LazyLocalizedString.
  *
- * Can only be called inside a functional component. To use this directly in route handlers,
- * use {@link asFC} to wrap the handler as a functional component.
- *
  * This cannot be used outside of Hono request context (e.g., in plain Deno scripts),
- * since it relies on the request context to provide the current language's localization map.
+ * since it relies on the request's localization context,
+ * set by {@link import("./initHonolate.ts").initHonolate},
+ * to provide the current language's localization map.
  *
  * @example Example as template string tag:
  * ```ts
@@ -33,15 +32,14 @@ import type { LocalizedStringValue } from "./LocalizedStringValue.ts";
  * const greeting = t(lls);
  * ```
  *
- * @example Using with asFC in route handler:
+ * @example Using in route handler:
  * ```ts
- * import { asFC, t } from '@wuespace/honolate';
+ * import { t } from '@wuespace/honolate';
  *
  * app.get('/greet', c => {
- *   return c.render(asFC(() => {
- *     const greeting = t`Hello ${c.req.param('name')}!`;
- *     return greeting;
- *   }));
+ *   return c.render(
+ *     <p>{t`Hello ${c.req.param('name')}!`}</p>
+ *   );
  * });
  * ```
  */
@@ -56,13 +54,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. Must be used within the scope of the `initHonolate` middleware.
  * @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;
 }