@xndrjs/i18n-react 0.8.0-alpha.0

package/src/create-load-coordinator.test.ts

@@ -0,0 +1,357 @@
+import { describe, expect, it, vi } from "vitest";
+import { createI18nHandle } from "@xndrjs/i18n";
+import { IcuTranslationProviderMulti } from "@xndrjs/i18n";
+import { createLoadCoordinator } from "./create-load-coordinator.js";
+
+type MultiSchema = {
+  default: {
+    greeting: { en: string; it: string };
+  };
+  billing: {
+    invoice: { en: string; it: string };
+  };
+};
+
+type TestMultiParams = {
+  default: {
+    greeting: never;
+  };
+  billing: {
+    invoice: never;
+  };
+};
+
+const defaultEn = {
+  greeting: { en: "Hello" },
+};
+
+const defaultIt = {
+  greeting: { it: "Ciao" },
+};
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+describe("createLoadCoordinator", () => {
+  it("dedupes in-flight loads for the same key", async () => {
+    const coordinator = createLoadCoordinator<string>();
+    const load = vi.fn(() => Promise.resolve("loaded"));
+    const engine = {};
+    const key = { engineRef: engine, partition: "en", namespaces: ["default"] as const };
+
+    coordinator.request({ ...key, load });
+    coordinator.request({ ...key, load });
+
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(coordinator.getEntry(key)).toEqual({ status: "pending" });
+    await expect(coordinator.getPromise()).resolves.toBe("loaded");
+    expect(coordinator.revision).toBe(1);
+    expect(coordinator.getResolvedScope()).toBe("loaded");
+    expect(coordinator.getEntry(key)).toEqual({ status: "resolved", scope: "loaded" });
+  });
+
+  it("skips reload when the same key is already resolved", async () => {
+    const coordinator = createLoadCoordinator<number>();
+    const load = vi.fn(() => Promise.resolve(42));
+    const engine = {};
+    const key = {
+      engineRef: engine,
+      partition: undefined,
+      namespaces: ["default"] as const,
+    };
+
+    coordinator.request({ ...key, load });
+    await coordinator.getPromise();
+
+    coordinator.request({ ...key, load });
+
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(coordinator.revision).toBe(1);
+    await expect(coordinator.getPromise()).resolves.toBe(42);
+    expect(coordinator.getEntry(key)).toEqual({ status: "resolved", scope: 42 });
+  });
+
+  it("resolves synchronously when tryResolveSync returns a scope", () => {
+    const coordinator = createLoadCoordinator<string>();
+    const load = vi.fn(() => Promise.resolve("async"));
+    const tryResolveSync = vi.fn(() => "sync");
+    const engine = {};
+    const key = {
+      engineRef: engine,
+      partition: "en",
+      namespaces: ["default"] as const,
+    };
+
+    coordinator.request({ ...key, load, tryResolveSync });
+
+    expect(load).not.toHaveBeenCalled();
+    expect(tryResolveSync).toHaveBeenCalledTimes(1);
+    expect(coordinator.getEntry(key)).toEqual({ status: "resolved", scope: "sync" });
+    expect(coordinator.getResolvedScope()).toBe("sync");
+  });
+
+  it("falls back to async load when tryResolveSync returns null", async () => {
+    const coordinator = createLoadCoordinator<string>();
+    const load = vi.fn(() => Promise.resolve("async"));
+    const tryResolveSync = vi.fn(() => null);
+    const engine = {};
+    const key = {
+      engineRef: engine,
+      partition: "en",
+      namespaces: ["default"] as const,
+    };
+
+    coordinator.request({ ...key, load, tryResolveSync });
+
+    expect(coordinator.getEntry(key)).toEqual({ status: "pending" });
+    await expect(coordinator.getPromise()).resolves.toBe("async");
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(coordinator.getEntry(key)).toEqual({ status: "resolved", scope: "async" });
+  });
+
+  it("keeps concurrent namespace loads independent", async () => {
+    const coordinator = createLoadCoordinator<string>();
+    const billing = deferred<string>();
+    const user = deferred<string>();
+    const engine = {};
+    const billingKey = {
+      engineRef: engine,
+      partition: "en",
+      namespaces: ["billing"] as const,
+    };
+    const userKey = {
+      engineRef: engine,
+      partition: "en",
+      namespaces: ["user"] as const,
+    };
+
+    coordinator.request({ ...billingKey, load: () => billing.promise });
+    const billingPromise = coordinator.getPromise();
+
+    coordinator.request({ ...userKey, load: () => user.promise });
+    const userPromise = coordinator.getPromise();
+
+    expect(coordinator.getEntry(billingKey)).toEqual({ status: "pending" });
+    expect(coordinator.getEntry(userKey)).toEqual({ status: "pending" });
+
+    billing.resolve("billing-scope");
+    user.resolve("user-scope");
+
+    await expect(billingPromise).resolves.toBe("billing-scope");
+    await expect(userPromise).resolves.toBe("user-scope");
+    expect(coordinator.revision).toBe(2);
+    expect(coordinator.getEntry(billingKey)).toEqual({
+      status: "resolved",
+      scope: "billing-scope",
+    });
+    expect(coordinator.getEntry(userKey)).toEqual({
+      status: "resolved",
+      scope: "user-scope",
+    });
+  });
+
+  it("caches distinct partitions without cancelling the earlier one", async () => {
+    const coordinator = createLoadCoordinator<string>();
+    const first = deferred<string>();
+    const second = deferred<string>();
+    const engine = {};
+
+    coordinator.request({
+      engineRef: engine,
+      partition: "en",
+      namespaces: ["default"],
+      load: () => first.promise,
+    });
+    const enPromise = coordinator.getPromise();
+
+    coordinator.request({
+      engineRef: engine,
+      partition: "it",
+      namespaces: ["default"],
+      load: () => second.promise,
+    });
+    const itPromise = coordinator.getPromise();
+
+    first.resolve("en-scope");
+    second.resolve("it-scope");
+
+    await expect(enPromise).resolves.toBe("en-scope");
+    await expect(itPromise).resolves.toBe("it-scope");
+    expect(coordinator.revision).toBe(2);
+  });
+
+  it("notifies subscribers when a load resolves", async () => {
+    const coordinator = createLoadCoordinator<string>();
+    const pending = deferred<string>();
+    const engine = {};
+    const key = {
+      engineRef: engine,
+      partition: "en",
+      namespaces: ["default"] as const,
+    };
+    const listener = vi.fn();
+
+    const unsubscribe = coordinator.subscribe(listener);
+    coordinator.request({ ...key, load: () => pending.promise });
+
+    expect(listener).not.toHaveBeenCalled();
+    expect(coordinator.getEntry(key)).toEqual({ status: "pending" });
+
+    pending.resolve("ready");
+    await expect(coordinator.getPromise()).resolves.toBe("ready");
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(coordinator.revision).toBe(1);
+    expect(coordinator.getEntry(key)).toEqual({ status: "resolved", scope: "ready" });
+
+    unsubscribe();
+    const other = deferred<string>();
+    coordinator.request({
+      engineRef: engine,
+      partition: "it",
+      namespaces: ["default"],
+      load: () => other.promise,
+    });
+    other.resolve("other");
+    await vi.waitFor(() => expect(coordinator.revision).toBe(2));
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps an error entry and notifies subscribers on reject", async () => {
+    const coordinator = createLoadCoordinator<string>();
+    const pending = deferred<string>();
+    const engine = {};
+    const key = {
+      engineRef: engine,
+      partition: "en",
+      namespaces: ["default"] as const,
+    };
+    const load = vi.fn(() => pending.promise);
+    const listener = vi.fn();
+    const failure = new Error("load failed");
+
+    coordinator.subscribe(listener);
+    coordinator.request({ ...key, load });
+
+    expect(coordinator.getEntry(key)).toEqual({ status: "pending" });
+
+    pending.reject(failure);
+    await expect(coordinator.getPromise()).rejects.toThrow("load failed");
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(coordinator.revision).toBe(1);
+    expect(coordinator.getEntry(key)).toEqual({ status: "error", error: failure });
+    expect(coordinator.getResolvedScope()).toBeNull();
+
+    // Deduped: settled error entry is not retried until retry().
+    coordinator.request({ ...key, load });
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(coordinator.getEntry(key)).toEqual({ status: "error", error: failure });
+  });
+
+  it("retry() evicts an error entry so the next ensure reloads", async () => {
+    const coordinator = createLoadCoordinator<string>();
+    const engine = {};
+    const key = {
+      engineRef: engine,
+      partition: "en",
+      namespaces: ["default"] as const,
+    };
+    const load = vi
+      .fn()
+      .mockImplementationOnce(() => Promise.reject(new Error("fail")))
+      .mockImplementationOnce(() => Promise.resolve("ok"));
+
+    coordinator.request({ ...key, load });
+    await expect(coordinator.getPromise()).rejects.toThrow("fail");
+    expect(coordinator.getEntry(key).status).toBe("error");
+
+    coordinator.retry(key);
+    expect(coordinator.getEntry(key)).toEqual({ status: "pending" });
+
+    coordinator.request({ ...key, load });
+    await expect(coordinator.getPromise()).resolves.toBe("ok");
+    expect(load).toHaveBeenCalledTimes(2);
+    expect(coordinator.getEntry(key)).toEqual({ status: "resolved", scope: "ok" });
+  });
+
+  it("distinguishes different engineRef objects via WeakMap ids", async () => {
+    const coordinator = createLoadCoordinator<string>();
+    const engineA = {};
+    const engineB = {};
+    const loadA = vi.fn(() => Promise.resolve("a"));
+    const loadB = vi.fn(() => Promise.resolve("b"));
+
+    coordinator.request({
+      engineRef: engineA,
+      partition: "en",
+      namespaces: ["default"],
+      load: loadA,
+    });
+    const promiseA = coordinator.getPromise();
+    coordinator.request({
+      engineRef: engineB,
+      partition: "en",
+      namespaces: ["default"],
+      load: loadB,
+    });
+    const promiseB = coordinator.getPromise();
+
+    expect(loadA).toHaveBeenCalledTimes(1);
+    expect(loadB).toHaveBeenCalledTimes(1);
+    await expect(promiseA).resolves.toBe("a");
+    await expect(promiseB).resolves.toBe("b");
+    expect(
+      coordinator.getEntry({ engineRef: engineA, partition: "en", namespaces: ["default"] })
+    ).toEqual({ status: "resolved", scope: "a" });
+    expect(
+      coordinator.getEntry({ engineRef: engineB, partition: "en", namespaces: ["default"] })
+    ).toEqual({ status: "resolved", scope: "b" });
+  });
+
+  it("returns pending for unknown keys without using React use()", () => {
+    const coordinator = createLoadCoordinator<string>();
+    expect(
+      coordinator.getEntry({
+        engineRef: {},
+        partition: "en",
+        namespaces: ["missing"],
+      })
+    ).toEqual({ status: "pending" });
+    expect(coordinator.revision).toBe(0);
+  });
+
+  it("integrates with handle split-by-locale loads", async () => {
+    const defaultLoader = vi.fn(async (locale: string) =>
+      locale === "it" ? defaultIt : defaultEn
+    );
+    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
+    const handle = createI18nHandle(engine, {
+      namespaceLoaders: {
+        default: defaultLoader,
+      },
+    });
+    const load = () => handle.load({ namespaces: ["default"], locale: "it" });
+    const coordinator = createLoadCoordinator<Awaited<ReturnType<typeof load>>>();
+    const key = {
+      engineRef: engine,
+      partition: "it",
+      namespaces: ["default"] as const,
+    };
+
+    coordinator.request({ ...key, load });
+
+    const scope = await coordinator.getPromise();
+    expect(defaultLoader).toHaveBeenCalledWith("it", { locale: "it" });
+    expect(scope.t("default", "greeting")).toBe("Ciao");
+    expect(coordinator.revision).toBe(1);
+    expect(coordinator.getEntry(key).status).toBe("resolved");
+  });
+});

package/src/create-load-coordinator.ts

@@ -0,0 +1,312 @@
+/**
+ * Load deduplication for lazy i18n namespace gates / HOCs.
+ *
+ * Supports multiple concurrent keys so parallel per-namespace gates can share
+ * one coordinator. Each `(engine, partition, namespaces)` entry keeps its own
+ * promise and status. Display state (keep-previous / pendingLocale / stable `t`)
+ * lives here so gate components stay pure observers of `useSyncExternalStore`.
+ */
+import { createScopedT } from "./create-scoped-t.js";
+import type {
+  GetDisplayEntryOptions,
+  LoadCoordinator,
+  LoadCoordinatorEntry,
+  LoadCoordinatorKey,
+  LoadCoordinatorRequest,
+  LoadDisplayEntry,
+  ScopedScopeLike,
+  ScopedTranslateFn,
+} from "./types.js";
+
+const engineIds = new WeakMap<object, number>();
+let nextEngineId = 1;
+
+function engineId(ref: unknown): number {
+  if (ref === null || (typeof ref !== "object" && typeof ref !== "function")) {
+    return 0;
+  }
+  const obj = ref as object;
+  let id = engineIds.get(obj);
+  if (id === undefined) {
+    id = nextEngineId++;
+    engineIds.set(obj, id);
+  }
+  return id;
+}
+
+function cacheKey(
+  engineRef: unknown,
+  partition: string | undefined,
+  namespaces: readonly string[]
+): string {
+  return `${engineId(engineRef)}\0${partition ?? ""}\0${namespaces.join("\0")}`;
+}
+
+/** Gate identity for keep-previous (namespaces only — partition/locale can change). */
+function gateId(engineRef: unknown, namespaces: readonly string[]): string {
+  return `${engineId(engineRef)}\0${namespaces.join("\0")}`;
+}
+
+interface CacheEntry<Scope> {
+  status: "pending" | "resolved" | "error";
+  promise: Promise<Scope>;
+  resolvedScope: Scope | null;
+  error: unknown;
+  requestId: number;
+  /** Stable LoadCoordinatorEntry snapshot for getEntry(). */
+  entrySnapshot: LoadCoordinatorEntry<Scope>;
+}
+
+interface DisplayCache {
+  lastReady: { scope: ScopedScopeLike; locale: string } | null;
+  /** Stable display entry object until inputs change. */
+  displaySnapshot: LoadDisplayEntry<ScopedScopeLike> | null;
+  /** Identity key for the last displaySnapshot. */
+  displayKey: string | null;
+  boundT: ScopedTranslateFn | null;
+  boundTKey: string | null;
+}
+
+/**
+ * Dedupes in-flight loads by `(engineRef, partition, namespaces)` and exposes
+ * display snapshots + retry for manual pending/resolved/error rendering.
+ */
+export function createLoadCoordinator<Scope = ScopedScopeLike>(): LoadCoordinator<Scope> {
+  let revision = 0;
+  let nextRequestId = 0;
+  const entries = new Map<string, CacheEntry<Scope>>();
+  const displayByGate = new Map<string, DisplayCache>();
+  const listeners = new Set<() => void>();
+  let lastKey: string | null = null;
+
+  function notify(): void {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  function bumpAndNotify(): void {
+    revision += 1;
+    // Invalidate display snapshots that depend on entry status.
+    for (const display of displayByGate.values()) {
+      display.displaySnapshot = null;
+      display.displayKey = null;
+    }
+    notify();
+  }
+
+  function ensure(input: LoadCoordinatorRequest<Scope>): void {
+    const key = cacheKey(input.engineRef, input.partition, input.namespaces);
+    lastKey = key;
+
+    const existing = entries.get(key);
+    if (existing !== undefined) {
+      return;
+    }
+
+    if (input.tryResolveSync !== undefined) {
+      const syncScope = input.tryResolveSync();
+      if (syncScope !== null) {
+        const entrySnapshot: LoadCoordinatorEntry<Scope> = {
+          status: "resolved",
+          scope: syncScope,
+        };
+        entries.set(key, {
+          status: "resolved",
+          promise: Promise.resolve(syncScope),
+          resolvedScope: syncScope,
+          error: null,
+          requestId: ++nextRequestId,
+          entrySnapshot,
+        });
+        return;
+      }
+    }
+
+    const requestId = ++nextRequestId;
+    const promise = input.load().then(
+      (scope) => {
+        const entry = entries.get(key);
+        if (entry === undefined || entry.requestId !== requestId) {
+          return scope;
+        }
+        entry.status = "resolved";
+        entry.resolvedScope = scope;
+        entry.error = null;
+        entry.entrySnapshot = { status: "resolved", scope };
+        bumpAndNotify();
+        return scope;
+      },
+      (error: unknown) => {
+        const entry = entries.get(key);
+        if (entry !== undefined && entry.requestId === requestId) {
+          entry.status = "error";
+          entry.error = error;
+          entry.resolvedScope = null;
+          entry.entrySnapshot = { status: "error", error };
+          bumpAndNotify();
+        }
+        throw error;
+      }
+    );
+    // Mark rejection handled when only getEntry consumers attach (no getPromise).
+    void promise.catch(() => void null);
+
+    entries.set(key, {
+      status: "pending",
+      promise,
+      resolvedScope: null,
+      error: null,
+      requestId,
+      entrySnapshot: { status: "pending" },
+    });
+  }
+
+  function getEntry(keyInput: LoadCoordinatorKey): LoadCoordinatorEntry<Scope> {
+    const key = cacheKey(keyInput.engineRef, keyInput.partition, keyInput.namespaces);
+    const entry = entries.get(key);
+    if (entry === undefined) {
+      return { status: "pending" };
+    }
+    return entry.entrySnapshot;
+  }
+
+  function getOrCreateDisplay(engineRef: unknown, namespaces: readonly string[]): DisplayCache {
+    const id = gateId(engineRef, namespaces);
+    let display = displayByGate.get(id);
+    if (display === undefined) {
+      display = {
+        lastReady: null,
+        displaySnapshot: null,
+        displayKey: null,
+        boundT: null,
+        boundTKey: null,
+      };
+      displayByGate.set(id, display);
+    }
+    return display;
+  }
+
+  function bindT(
+    display: DisplayCache,
+    scope: ScopedScopeLike,
+    locale: string,
+    namespaces: readonly string[],
+    scopeToken: string
+  ): ScopedTranslateFn {
+    const tKey = `${scopeToken}\0${locale}\0${namespaces.join("\0")}`;
+    if (display.boundT !== null && display.boundTKey === tKey) {
+      return display.boundT;
+    }
+    const t = createScopedT(scope, { namespaces, locale });
+    display.boundT = t;
+    display.boundTKey = tKey;
+    return t;
+  }
+
+  function getDisplayEntry(
+    keyInput: LoadCoordinatorKey,
+    options: GetDisplayEntryOptions
+  ): LoadDisplayEntry<Scope> {
+    const key = cacheKey(keyInput.engineRef, keyInput.partition, keyInput.namespaces);
+    const entry = entries.get(key);
+    const display = getOrCreateDisplay(keyInput.engineRef, options.namespaces);
+    const keepPrevious = options.keepPrevious !== false;
+
+    const retry = () => {
+      retryKey(keyInput);
+    };
+
+    let result: LoadDisplayEntry<Scope>;
+
+    if (entry === undefined || entry.status === "pending") {
+      const kept = keepPrevious ? display.lastReady : null;
+      result = {
+        status: "pending",
+        display: kept as { scope: Scope & ScopedScopeLike; locale: string } | null,
+        pendingLocale: kept ? options.locale : undefined,
+        t: kept
+          ? bindT(display, kept.scope, kept.locale, options.namespaces, `kept:${kept.locale}`)
+          : null,
+      } as LoadDisplayEntry<Scope>;
+    } else if (entry.status === "resolved") {
+      const scope = entry.resolvedScope as Scope & ScopedScopeLike;
+      display.lastReady = { scope, locale: options.locale };
+      result = {
+        status: "ready",
+        scope,
+        locale: options.locale,
+        t: bindT(display, scope, options.locale, options.namespaces, `ready:${key}`),
+      } as LoadDisplayEntry<Scope>;
+    } else {
+      const kept = keepPrevious ? display.lastReady : null;
+      result = {
+        status: "error",
+        error: entry.error,
+        display: kept as { scope: Scope & ScopedScopeLike; locale: string } | null,
+        pendingLocale: kept ? options.locale : undefined,
+        t: kept
+          ? bindT(display, kept.scope, kept.locale, options.namespaces, `kept:${kept.locale}`)
+          : null,
+        retry,
+      } as LoadDisplayEntry<Scope>;
+    }
+
+    const displayKey = `${key}\0${result.status}\0${options.locale}\0${String(!!result.t)}`;
+    if (display.displaySnapshot !== null && display.displayKey === displayKey) {
+      return display.displaySnapshot as LoadDisplayEntry<Scope>;
+    }
+    display.displaySnapshot = result as LoadDisplayEntry<ScopedScopeLike>;
+    display.displayKey = displayKey;
+    return result;
+  }
+
+  function retryKey(keyInput: LoadCoordinatorKey): void {
+    const key = cacheKey(keyInput.engineRef, keyInput.partition, keyInput.namespaces);
+    if (!entries.has(key)) {
+      return;
+    }
+    entries.delete(key);
+    bumpAndNotify();
+  }
+
+  function subscribe(listener: () => void): () => void {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+
+  function getPromise(): Promise<Scope> {
+    if (lastKey === null) {
+      throw new Error("createLoadCoordinator: call ensure()/request() before getPromise()");
+    }
+    const entry = entries.get(lastKey);
+    if (entry === undefined) {
+      throw new Error("createLoadCoordinator: call ensure()/request() before getPromise()");
+    }
+    return entry.promise;
+  }
+
+  function getResolvedScope(): Scope | null {
+    if (lastKey === null) {
+      return null;
+    }
+    const entry = entries.get(lastKey);
+    return entry?.status === "resolved" ? entry.resolvedScope : null;
+  }
+
+  return {
+    get revision() {
+      return revision;
+    },
+    request: ensure,
+    ensure,
+    getEntry,
+    getDisplayEntry,
+    retry: retryKey,
+    subscribe,
+    getPromise,
+    getResolvedScope,
+  };
+}