okengine 0.5.1 → 0.6.1

package/src/i18n/format.ts

@@ -0,0 +1,67 @@
+/**
+ * ICU MessageFormat formatting via FormatJS (`intl-messageformat`).
+ *
+ * Supports interpolation, cardinal/ordinal plurals, `select` / `selectordinal`,
+ * and rich-text tags (`<tag>…</tag>` with function values).
+ */
+
+import IntlMessageFormat from "intl-messageformat";
+import type { MessageValues } from "./types.ts";
+
+const cache = new Map<string, IntlMessageFormat>();
+
+/**
+ * Clear the compiled-message cache (tests only).
+ */
+export function clearMessageFormatCache(): void {
+  cache.clear();
+}
+
+/**
+ * Format an ICU message for a locale.
+ *
+ * @param message - ICU MessageFormat source
+ * @param locale - BCP 47 locale tag
+ * @param values - Interpolation / plural / select / rich-text values
+ */
+export function formatMessage(message: string, locale: string, values?: MessageValues): string {
+  const cacheKey = `${locale}\0${message}`;
+  let formatter = cache.get(cacheKey);
+  if (!formatter) {
+    try {
+      formatter = new IntlMessageFormat(message, locale);
+    } catch {
+      // Malformed ICU — treat as a plain template.
+      return message;
+    }
+    cache.set(cacheKey, formatter);
+  }
+
+  try {
+    const result = formatter.format(values as Record<string, unknown> | undefined);
+    return partsToString(result);
+  } catch {
+    // Missing args — leave the source for callers that fall back.
+    return message;
+  }
+}
+
+/**
+ * Collapse FormatJS rich-text / string output to a single string.
+ *
+ * @param result - `format()` return value
+ */
+function partsToString(result: unknown): string {
+  if (typeof result === "string") return result;
+  if (typeof result === "number" || typeof result === "boolean") return String(result);
+  if (Array.isArray(result)) {
+    return result
+      .map((part) => {
+        if (typeof part === "string" || typeof part === "number") return String(part);
+        return "";
+      })
+      .join("");
+  }
+  if (result == null) return "";
+  return String(result);
+}

package/src/i18n/index.ts

@@ -0,0 +1,57 @@
+/**
+ * App i18n — ICU message catalogs for `fx.t`, typed keys, locale helpers.
+ *
+ * Channel locale resolution lives in `elements/channel/locale.ts`; this
+ * module owns Flow-facing string catalogs registered via {@link defineLocale}.
+ */
+
+export { clearMessageFormatCache, formatMessage } from "./format.ts";
+
+export {
+  catalogReasonKey,
+  failureMessageValues,
+  isCatalogReason,
+  resolveFailureMessage,
+} from "./failure-message.ts";
+
+export {
+  getActiveDefaultLocale,
+  getActiveLocale,
+  getLocaleContext,
+  runWithLocale,
+  type LocaleContext,
+} from "./locale-context.ts";
+
+export {
+  clearMessageCatalogs,
+  defineLocale,
+  defineMessages,
+  flattenMessages,
+  getMessageCatalogs,
+  interpolateMessage,
+  matchConfiguredLocale,
+  translate,
+  type MessageCatalog,
+  type MessageCatalogs,
+  type TranslateOptions,
+} from "./messages.ts";
+
+export type {
+  AppMessageKey,
+  FlattenKeys,
+  MessageTree,
+  MessageValue,
+  MessageValues,
+  MessagesFor,
+  Register,
+} from "./types.ts";
+
+export {
+  formatLocaleChain,
+  isRtlLocale,
+  parseAcceptLanguage,
+  resolveLocale,
+  type LocaleChainStep,
+  type LocaleResolution,
+  type ResolveLocaleOptions,
+} from "../elements/channel/locale.ts";

package/src/i18n/locale-context.ts

@@ -0,0 +1,48 @@
+/**
+ * Request-scoped locale for {@link fail} / {@link OkeError} localization.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** Active locale bag for the current async context. */
+export interface LocaleContext {
+  readonly locale: string;
+  readonly defaultLocale: string;
+}
+
+const storage = new AsyncLocalStorage<LocaleContext>();
+
+/**
+ * Run `fn` with an active locale context (request / invocation scope).
+ *
+ * @param ctx - Locale + default
+ * @param fn - Work to run
+ */
+export function runWithLocale<T>(ctx: LocaleContext, fn: () => T): T {
+  return storage.run(ctx, fn);
+}
+
+/**
+ * Active locale context, if any.
+ */
+export function getLocaleContext(): LocaleContext | undefined {
+  return storage.getStore();
+}
+
+/**
+ * Active locale, or `fallback` when none is set.
+ *
+ * @param fallback - Default when outside a request (default `"en"`)
+ */
+export function getActiveLocale(fallback = "en"): string {
+  return storage.getStore()?.locale ?? fallback;
+}
+
+/**
+ * Active default locale for catalog fallback.
+ *
+ * @param fallback - Default when outside a request (default `"en"`)
+ */
+export function getActiveDefaultLocale(fallback = "en"): string {
+  return storage.getStore()?.defaultLocale ?? fallback;
+}

package/src/i18n/messages.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from "bun:test";
+import { clearMessageFormatCache, formatMessage } from "./format.ts";
+import {
+  clearMessageCatalogs,
+  defineLocale,
+  defineMessages,
+  flattenMessages,
+  getMessageCatalogs,
+  matchConfiguredLocale,
+  translate,
+} from "./messages.ts";
+import type { FlattenKeys, MessagesFor } from "./types.ts";
+
+describe("flattenMessages", () => {
+  test("flattens nested trees with dot keys", () => {
+    expect(
+      flattenMessages({
+        errors: { notFound: "Missing" },
+        hello: "Hi",
+      }),
+    ).toEqual({
+      "errors.notFound": "Missing",
+      hello: "Hi",
+    });
+  });
+});
+
+describe("defineLocale / getMessageCatalogs", () => {
+  test("registers overlays that win over built-ins", () => {
+    clearMessageCatalogs();
+    defineLocale("en", { greeting: "Hello, {name}" });
+    defineLocale("ar", { greeting: "مرحباً، {name}" });
+    const catalogs = getMessageCatalogs();
+    expect(catalogs.en?.greeting).toBe("Hello, {name}");
+    expect(catalogs.ar?.greeting).toBe("مرحباً، {name}");
+    // Built-ins remain available under the same locale.
+    expect(catalogs.en?.["errors.Unauthorized"]).toBe("Authentication required.");
+    defineLocale("en", { greeting: "Hi, {name}" });
+    expect(getMessageCatalogs().en?.greeting).toBe("Hi, {name}");
+    clearMessageCatalogs();
+  });
+});
+
+describe("formatMessage — ICU", () => {
+  test("interpolates simple placeholders", () => {
+    clearMessageFormatCache();
+    expect(formatMessage("Hello, {name}", "en", { name: "Ada" })).toBe("Hello, Ada");
+  });
+
+  test("cardinal plurals", () => {
+    clearMessageFormatCache();
+    const msg = "{count, plural, =0 {no items} one {# item} other {# items}}";
+    expect(formatMessage(msg, "en", { count: 0 })).toBe("no items");
+    expect(formatMessage(msg, "en", { count: 1 })).toBe("1 item");
+    expect(formatMessage(msg, "en", { count: 5 })).toBe("5 items");
+  });
+
+  test("ordinal plurals via selectordinal", () => {
+    clearMessageFormatCache();
+    const msg = "You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!";
+    expect(formatMessage(msg, "en", { place: 1 })).toBe("You finished 1st!");
+    expect(formatMessage(msg, "en", { place: 2 })).toBe("You finished 2nd!");
+    expect(formatMessage(msg, "en", { place: 3 })).toBe("You finished 3rd!");
+    expect(formatMessage(msg, "en", { place: 11 })).toBe("You finished 11th!");
+  });
+
+  test("enum select", () => {
+    clearMessageFormatCache();
+    const msg = "{status, select, online {Online} offline {Offline} other {Unknown}}";
+    expect(formatMessage(msg, "en", { status: "online" })).toBe("Online");
+    expect(formatMessage(msg, "en", { status: "offline" })).toBe("Offline");
+    expect(formatMessage(msg, "en", { status: "away" })).toBe("Unknown");
+  });
+
+  test("rich text tags via function values", () => {
+    clearMessageFormatCache();
+    const msg = "Read <docs>the docs</docs>.";
+    expect(
+      formatMessage(msg, "en", {
+        docs: (chunks) => `[${chunks.join("")}]`,
+      }),
+    ).toBe("Read [the docs].");
+  });
+
+  test("Arabic plural sample", () => {
+    clearMessageFormatCache();
+    const msg =
+      "{count, plural, zero {لا عناصر} one {عنصر واحد} two {عنصران} few {# عناصر} many {# عنصراً} other {# عنصر}}";
+    expect(formatMessage(msg, "ar", { count: 0 })).toBe("لا عناصر");
+    expect(formatMessage(msg, "ar", { count: 1 })).toBe("عنصر واحد");
+    expect(formatMessage(msg, "ar", { count: 2 })).toBe("عنصران");
+  });
+});
+
+describe("translate", () => {
+  const catalogs = {
+    en: {
+      "errors.notFound": "Not found",
+      greeting: "Hello, {name}",
+      items: "{count, plural, one {# item} other {# items}}",
+    },
+    ar: {
+      greeting: "مرحباً، {name}",
+    },
+  };
+
+  test("uses locale, then default, then key", () => {
+    expect(
+      translate({
+        locale: "ar",
+        defaultLocale: "en",
+        catalogs,
+        key: "greeting",
+        values: { name: "Ada" },
+      }),
+    ).toBe("مرحباً، Ada");
+    expect(
+      translate({
+        locale: "ar",
+        defaultLocale: "en",
+        catalogs,
+        key: "errors.notFound",
+      }),
+    ).toBe("Not found");
+    expect(
+      translate({
+        locale: "en",
+        defaultLocale: "en",
+        catalogs,
+        key: "items",
+        values: { count: 3 },
+      }),
+    ).toBe("3 items");
+    expect(
+      translate({
+        locale: "ar",
+        defaultLocale: "en",
+        catalogs,
+        key: "missing",
+        values: { x: 1 },
+      }),
+    ).toBe('missing:{"x":1}');
+  });
+});
+
+describe("matchConfiguredLocale", () => {
+  test("matches exact, base tag, then default", () => {
+    const locales = ["en", "ar"] as const;
+    expect(matchConfiguredLocale("ar", locales, "en")).toBe("ar");
+    expect(matchConfiguredLocale("ar-SA", locales, "en")).toBe("ar");
+    expect(matchConfiguredLocale("fr", locales, "en")).toBe("en");
+    expect(matchConfiguredLocale(undefined, locales, "en")).toBe("en");
+  });
+});
+
+describe("type helpers (compile-time shapes)", () => {
+  test("defineMessages preserves tree; MessagesFor aligns locales", () => {
+    const en = defineMessages({
+      errors: { notFound: "Not found" },
+      greeting: "Hello, {name}",
+    });
+    const ar = {
+      errors: { notFound: "غير موجود" },
+      greeting: "مرحباً، {name}",
+    } satisfies MessagesFor<typeof en>;
+
+    type Keys = FlattenKeys<typeof en>;
+    const key: Keys = "errors.notFound";
+    expect(en.errors.notFound).toBe("Not found");
+    expect(ar.greeting).toContain("{name}");
+    expect(key).toBe("errors.notFound");
+  });
+});

package/src/i18n/messages.ts

@@ -0,0 +1,169 @@
+/**
+ * App message catalogs for {@link Fx.t}.
+ *
+ * Locales register via {@link defineLocale}; boot wires catalogs into `fx`
+ * with the active request locale and the `i18n.default` fallback from
+ * `oke.config.ts`. Messages use ICU MessageFormat syntax.
+ *
+ * Built-in EN/AR catalogs (framework OKE codes + typed failures) are always
+ * present; app keys override built-ins for the same locale/key.
+ */
+
+import { builtinAr } from "./catalogs/ar.ts";
+import { builtinEn } from "./catalogs/en.ts";
+import { formatMessage } from "./format.ts";
+import type { MessageTree, MessageValues } from "./types.ts";
+
+export type { MessageTree, MessageValues } from "./types.ts";
+
+/** Flat key → message map after {@link flattenMessages}. */
+export type MessageCatalog = Readonly<Record<string, string>>;
+
+/** All registered locale catalogs (locale → flat map). */
+export type MessageCatalogs = Readonly<Record<string, MessageCatalog>>;
+
+/**
+ * Flatten a nested message tree into dot-separated keys.
+ *
+ * @param tree - Nested or flat messages
+ * @param prefix - Key prefix for recursion
+ */
+export function flattenMessages(tree: MessageTree, prefix = ""): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(tree)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "string") {
+      out[path] = value;
+    } else {
+      Object.assign(out, flattenMessages(value, path));
+    }
+  }
+  return out;
+}
+
+/** App-registered overlays (win over built-ins per key). */
+const registry = new Map<string, Record<string, string>>();
+
+/** Built-in EN/AR catalogs (framework + typed failures). */
+const builtins: Readonly<Record<string, MessageCatalog>> = {
+  en: flattenMessages(builtinEn as unknown as MessageTree),
+  ar: flattenMessages(builtinAr as unknown as MessageTree),
+};
+
+/**
+ * Identity helper that preserves a `const` message tree for typing.
+ *
+ * @param messages - Canonical catalog (usually English)
+ */
+export function defineMessages<const T extends MessageTree>(messages: T): T {
+  return messages;
+}
+
+/**
+ * Register (or replace) messages for a locale.
+ *
+ * Side-effect import from `src/locales/<locale>.ts` before boot.
+ * Prefer `as const` / {@link defineMessages} on the default locale, then
+ * `satisfies MessagesFor<typeof en>` on translations so keys stay aligned.
+ *
+ * @param locale - BCP 47 locale tag (e.g. `"en"`, `"ar"`)
+ * @param messages - Nested or flat ICU message tree
+ */
+export function defineLocale<const T extends MessageTree>(locale: string, messages: T): T {
+  const tag = locale.trim();
+  if (!tag) throw new Error("defineLocale: locale must be non-empty");
+  registry.set(tag, flattenMessages(messages));
+  return messages;
+}
+
+/**
+ * Snapshot of every catalog — built-ins merged under app overlays.
+ */
+export function getMessageCatalogs(): MessageCatalogs {
+  const locales = new Set([...Object.keys(builtins), ...registry.keys()]);
+  const out: Record<string, MessageCatalog> = {};
+  for (const locale of locales) {
+    out[locale] = { ...(builtins[locale] ?? {}), ...(registry.get(locale) ?? {}) };
+  }
+  return out;
+}
+
+/**
+ * Clear app-registered catalogs (tests only). Built-ins remain.
+ */
+export function clearMessageCatalogs(): void {
+  registry.clear();
+}
+
+/**
+ * @deprecated Use ICU `{name}` via {@link formatMessage} / `fx.t`. Kept for
+ * channel-style `{{name}}` callers during migration; not used by `fx.t`.
+ *
+ * @param template - Message template
+ * @param params - Replacement values
+ */
+export function interpolateMessage(
+  template: string,
+  params?: Readonly<Record<string, unknown>>,
+): string {
+  if (!params) return template;
+  return template.replace(/\{\{(\w+)\}\}/g, (_, name: string) => {
+    const value = params[name];
+    return value === undefined || value === null ? `{{${name}}}` : String(value);
+  });
+}
+
+/** Options for {@link translate}. */
+export interface TranslateOptions {
+  readonly locale: string;
+  readonly defaultLocale: string;
+  readonly catalogs: MessageCatalogs;
+  readonly key: string;
+  readonly values?: MessageValues;
+  /** @deprecated Prefer {@link TranslateOptions.values}. */
+  readonly params?: MessageValues;
+}
+
+/**
+ * Resolve a message key through locale → default → key fallback, then format
+ * with ICU MessageFormat.
+ *
+ * @param options - Locale, catalogs, key, values
+ */
+export function translate(options: TranslateOptions): string {
+  const { locale, defaultLocale, catalogs, key } = options;
+  const values = options.values ?? options.params;
+  const primary = catalogs[locale]?.[key];
+  if (primary !== undefined) return formatMessage(primary, locale, values);
+  if (locale !== defaultLocale) {
+    const fallback = catalogs[defaultLocale]?.[key];
+    if (fallback !== undefined) return formatMessage(fallback, defaultLocale, values);
+  }
+  if (values === undefined) return key;
+  return `${key}:${JSON.stringify(values)}`;
+}
+
+/**
+ * Pick the best catalog locale from a candidate against configured locales.
+ *
+ * Exact match, then language subtag (`ar-SA` → `ar`), then default.
+ *
+ * @param candidate - Requested locale (may be undefined)
+ * @param locales - Configured locales
+ * @param defaultLocale - Fallback locale
+ */
+export function matchConfiguredLocale(
+  candidate: string | undefined,
+  locales: readonly string[],
+  defaultLocale: string,
+): string {
+  if (!candidate?.trim()) return defaultLocale;
+  const tag = candidate.trim();
+  if (locales.includes(tag)) return tag;
+  const base = tag.toLowerCase().split("-")[0] ?? tag;
+  const byBase = locales.find(
+    (l) => l.toLowerCase() === base || l.toLowerCase().startsWith(`${base}-`),
+  );
+  if (byBase) return byBase;
+  return defaultLocale;
+}

package/src/i18n/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Type-level helpers for message catalogs — keys, shapes, Register slot.
+ */
+
+/** Nested or flat message tree (leaf values are ICU message strings). */
+export type MessageTree = {
+  readonly [key: string]: string | MessageTree;
+};
+
+/**
+ * Flatten a message tree into dot-separated key unions.
+ *
+ * @typeParam T - Message tree
+ * @typeParam Prefix - Accumulated path prefix
+ */
+export type FlattenKeys<T, Prefix extends string = ""> = {
+  [K in keyof T & string]: T[K] extends string
+    ? Prefix extends ""
+      ? K
+      : `${Prefix}.${K}`
+    : T[K] extends MessageTree
+      ? FlattenKeys<T[K], Prefix extends "" ? K : `${Prefix}.${K}`>
+      : never;
+}[keyof T & string];
+
+/**
+ * Same key structure as {@link Base}; every leaf is an ICU message string.
+ * Use with `satisfies` so Arabic (etc.) cannot drift from English keys.
+ *
+ * @typeParam Base - Canonical (usually English) tree
+ */
+export type MessagesFor<Base extends MessageTree> = {
+  [K in keyof Base]: Base[K] extends string
+    ? string
+    : Base[K] extends MessageTree
+      ? MessagesFor<Base[K]>
+      : never;
+};
+
+/**
+ * Module-augmentation slot for typed `fx.t` keys.
+ *
+ * @example
+ * ```ts
+ * const en = { greeting: "Hello, {name}" } as const;
+ * defineLocale("en", en);
+ *
+ * declare module "okengine" {
+ *   interface Register {
+ *     messages: typeof en;
+ *   }
+ * }
+ * ```
+ */
+export interface Register {
+  // intentionally empty — augmented by the app
+}
+
+/** Messages from {@link Register}, when the app augments them. */
+type MessagesFromRegister = Register extends { readonly messages: infer M }
+  ? M extends MessageTree
+    ? M
+    : never
+  : never;
+
+/**
+ * Autocomplete / compile-time keys for {@link Fx.t}.
+ * Falls back to `string` until the app augments {@link Register}.
+ */
+export type AppMessageKey = [MessagesFromRegister] extends [never]
+  ? string
+  : FlattenKeys<MessagesFromRegister>;
+
+/**
+ * Values passed to ICU messages — primitives plus rich-text tag functions.
+ *
+ * Tag functions receive the formatted chunks inside `<tag>…</tag>` and return
+ * a string (or stringable) replacement.
+ */
+export type MessageValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | null
+  | undefined
+  | ((chunks: readonly string[]) => string);
+
+/** Named values for one `fx.t` / {@link formatMessage} call. */
+export type MessageValues = Readonly<Record<string, MessageValue>>;

package/src/index.ts

@@ -176,6 +176,32 @@ export {
   type ContextInference,
 } from "./compiler/index.ts";
 
+export {
+  defineLocale,
+  defineMessages,
+  flattenMessages,
+  formatMessage,
+  getMessageCatalogs,
+  interpolateMessage,
+  isRtlLocale,
+  matchConfiguredLocale,
+  parseAcceptLanguage,
+  resolveFailureMessage,
+  resolveLocale,
+  runWithLocale,
+  translate,
+  type AppMessageKey,
+  type FlattenKeys,
+  type LocaleContext,
+  type MessageCatalog,
+  type MessageCatalogs,
+  type MessageTree,
+  type MessageValue,
+  type MessageValues,
+  type MessagesFor,
+  type Register,
+} from "./i18n/index.ts";
+
 export {
   createBunRuntime,
   createWebStandardRuntime,