@bleedingdev/modern-js-i18n-runtime-extensions 3.8.3-ultramodern.2

package/dist/types/language-sync/react.d.ts

@@ -0,0 +1,38 @@
+import type React from 'react';
+import { type LanguageSyncFailure, type LanguageSyncPolicy } from './controller';
+export interface LatestLanguageSyncOptions<TTarget extends object> {
+    changeLanguage: (target: TTarget, language: string) => PromiseLike<unknown> | unknown;
+    commitLanguage: (target: TTarget, language: string) => void;
+    desiredLanguage?: string;
+    enabled?: boolean;
+    policy?: LanguageSyncPolicy;
+    readLanguage?: (target: TTarget) => string | undefined;
+    reportFailure?: (failure: LanguageSyncFailure) => void;
+    target?: TTarget;
+}
+export declare const useLatestLanguageSync: <TTarget extends object>({ changeLanguage, commitLanguage, desiredLanguage, enabled, policy, readLanguage, reportFailure, target, }: LatestLanguageSyncOptions<TTarget>) => (language: string) => void;
+interface LanguageDetectorLike {
+    cacheUserLanguage?: (language: string) => void;
+}
+export interface I18nLanguageSyncInstance {
+    changeLanguage?: (language?: string) => PromiseLike<unknown> | unknown;
+    i18nInstance?: {
+        instance?: I18nLanguageSyncInstance;
+    };
+    isInitialized?: boolean;
+    language: string;
+    options?: {
+        detection?: unknown;
+    };
+    services?: {
+        languageDetector?: LanguageDetectorLike;
+    };
+    setLang?: (language: string) => PromiseLike<unknown> | unknown;
+}
+/**
+ * Compatibility-shaped adapter for the Modern.js i18n provider. The shared
+ * coordinator is fork-owned; the upstream hook remains available to direct
+ * internal consumers until the equivalent shrink can be upstreamed.
+ */
+export declare function useLanguageSync<TInstance extends I18nLanguageSyncInstance>(i18nInstance: TInstance | undefined, localePathRedirect: boolean, languages: string[], pathname: string | undefined, prevLangRef: React.MutableRefObject<string>, setLang: (language: string) => void): (language: string) => void;
+export {};

package/dist/types/localisedUrls/config.d.ts

@@ -0,0 +1,9 @@
+import type { LocalisedUrlsOption, ResolvedLocalisedUrlsConfig } from './types';
+/**
+ * Localised URLs are strictly opt-in: only an explicit, non-empty map enables
+ * route expansion and validation. `true`, `false`, an empty map and absence
+ * all resolve to disabled, so upstream-style configs (`localePathRedirect` +
+ * `languages` without a map) keep plain locale-prefix behavior instead of
+ * failing the build for every route missing from a map they never wrote.
+ */
+export declare const resolveLocalisedUrlsConfig: (option: LocalisedUrlsOption | undefined) => ResolvedLocalisedUrlsConfig;

package/dist/types/localisedUrls/index.d.ts

@@ -0,0 +1,9 @@
+export { resolveLocalisedUrlsConfig } from './config';
+export { normalisePathname, normalisePathPattern } from './normalise';
+export { canonicalTargetPathname, localiseTargetPathname, stripLanguagePrefix, } from './pathname';
+export { buildPathFromPattern, matchPathPattern } from './patterns';
+export type { LocaleRedirectSkipRule } from './redirect';
+export { DEFAULT_LOCALE_REDIRECT_SKIP_RULES, isDefaultLocaleRedirectSkipPath, matchesPathPrefix, shouldSkipLocaleRedirect, } from './redirect';
+export { resolveCanonicalLocalisedPath, resolveLocalisedPath } from './resolve';
+export { applyLocalisedUrlsToRoutes, validateLocalisedUrls } from './routes';
+export type { LocalisedRoute, LocalisedUrlPathMap, LocalisedUrlsMap, LocalisedUrlsOption, ResolvedLocalisedUrlsConfig, } from './types';

package/dist/types/localisedUrls/normalise.d.ts

@@ -0,0 +1,10 @@
+export declare const normalisePathPattern: (path: string) => string;
+/**
+ * Normalise a concrete request pathname: slash cleanup only. Unlike
+ * {@link normalisePathPattern} it must not rewrite literal `[x]` segments to
+ * `:x` params — pathnames are values, not patterns.
+ */
+export declare const normalisePathname: (pathname: string) => string;
+export declare const normaliseRoutePath: (path: string) => string;
+export declare const stripLeadingLocaleParam: (path?: string) => string | undefined;
+export declare const getLeadingLocaleParam: (path?: string) => string | null;

package/dist/types/localisedUrls/pathname.d.ts

@@ -0,0 +1,4 @@
+import type { LocalisedUrlsOption } from './types';
+export declare const stripLanguagePrefix: (pathname: string, languages: string[]) => string;
+export declare const localiseTargetPathname: (pathname: string, language: string, languages: string[], localisedUrls?: LocalisedUrlsOption) => string;
+export declare const canonicalTargetPathname: (pathname: string, languages: string[], localisedUrls?: LocalisedUrlsOption) => string;

package/dist/types/localisedUrls/patterns.d.ts

@@ -0,0 +1,11 @@
+export declare const getOrderedPathParamSignature: (pattern: string) => string[];
+export declare const getPathParamSignature: (pattern: string) => string[];
+export declare const getPathPatternValidationIssue: (pattern: string) => string | undefined;
+export declare const getPhysicalPathPattern: (pattern: string) => string;
+export declare const haveEqualPatternSpecificity: (left: string, right: string) => boolean;
+export declare const doPathPatternsOverlap: (left: string, right: string) => boolean;
+export declare const sortPatternsBySpecificity: <T extends {
+    pattern: string;
+}>(patterns: T[]) => T[];
+export declare const matchPathPattern: (pathname: string, pattern: string) => Record<string, string> | null;
+export declare const buildPathFromPattern: (pattern: string, params: Record<string, string>) => string;

package/dist/types/localisedUrls/redirect.d.ts

@@ -0,0 +1,11 @@
+export type LocaleRedirectSkipRule = {
+    type: 'exact';
+    path: string;
+} | {
+    type: 'prefix';
+    path: string;
+};
+export declare const DEFAULT_LOCALE_REDIRECT_SKIP_RULES: readonly LocaleRedirectSkipRule[];
+export declare const matchesPathPrefix: (pathname: string, prefix: string) => boolean;
+export declare const isDefaultLocaleRedirectSkipPath: (pathname: string, languages?: string[]) => boolean;
+export declare const shouldSkipLocaleRedirect: (pathname: string, languages?: string[], ignoreRedirectRoutes?: string[] | ((pathname: string) => boolean)) => boolean;

package/dist/types/localisedUrls/resolve.d.ts

@@ -0,0 +1,7 @@
+import type { LocalisedUrlsMap } from './types';
+export declare const resolveLocalisedPath: (pathname: string, targetLanguage: string, languages: string[], localisedUrls: LocalisedUrlsMap) => string;
+/**
+ * Reverse-map language-specific pathnames back to language-agnostic
+ * LocalisedUrlsMap keys.
+ */
+export declare const resolveCanonicalLocalisedPath: (pathname: string, languages: string[], localisedUrls: LocalisedUrlsMap) => string;

package/dist/types/localisedUrls/routes.d.ts

@@ -0,0 +1,3 @@
+import type { LocalisedRoute, LocalisedUrlsMap } from './types';
+export declare const validateLocalisedUrls: (routes: LocalisedRoute[], languages: string[], localisedUrls: LocalisedUrlsMap) => void;
+export declare const applyLocalisedUrlsToRoutes: (routes: LocalisedRoute[], languages: string[], localisedUrls: LocalisedUrlsMap) => LocalisedRoute[];

package/dist/types/localisedUrls/types.d.ts

@@ -0,0 +1,14 @@
+export type LocalisedRoute = {
+    type: 'nested' | 'page';
+    path?: string;
+    id?: string;
+    children?: LocalisedRoute[];
+    [key: string]: any;
+};
+export type LocalisedUrlPathMap = Record<string, string>;
+export type LocalisedUrlsMap = Record<string, LocalisedUrlPathMap>;
+export type LocalisedUrlsOption = boolean | LocalisedUrlsMap;
+export interface ResolvedLocalisedUrlsConfig {
+    enabled: boolean;
+    map: LocalisedUrlsMap;
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@bleedingdev/modern-js-i18n-runtime-extensions",
+  "description": "Fork-owned UltraModern.js i18n runtime coordination and localized-route extensions.",
+  "homepage": "https://github.com/BleedingDev/ultramodern.js#readme",
+  "bugs": {
+    "url": "https://github.com/BleedingDev/ultramodern.js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BleedingDev/ultramodern.js.git",
+    "directory": "packages/runtime/i18n-extensions"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "framework",
+    "modern.js",
+    "i18n"
+  ],
+  "version": "3.8.3-ultramodern.2",
+  "types": "./dist/types/index.d.ts",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/index.mjs",
+        "require": "./dist/cjs/index.js"
+      },
+      "default": "./dist/esm/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types/index.d.ts",
+        "./src/index.ts"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=26.7.0"
+  },
+  "dependencies": {
+    "i18next-browser-languagedetector": "^8.2.1"
+  },
+  "peerDependencies": {
+    "@modern-js/runtime": "3.8.3-ultramodern.2",
+    "react": "^19.2.8"
+  },
+  "devDependencies": {
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.8.3-ultramodern.2",
+    "@rslib/core": "0.23.2",
+    "@scripts/rstest-config": "2.66.0",
+    "@types/node": "^26.2.0",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "rslib build --watch",
+    "build": "rslib build",
+    "test": "rstest --passWithNoTests"
+  }
+}

package/rslib.config.mts

@@ -0,0 +1,4 @@
+import { rslibConfig } from '@modern-js/rslib';
+import { defineConfig } from '@rslib/core';
+
+export default defineConfig(rslibConfig);

package/rstest.config.mts

@@ -0,0 +1,36 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { ProjectConfig } from '@rstest/core';
+import { withTestPreset } from '@scripts/rstest-config';
+
+const packageDirectory = dirname(fileURLToPath(import.meta.url));
+const commonConfig: ProjectConfig = {
+  setupFiles: [
+    resolve(packageDirectory, '../../../scripts/rstest-config/setup.ts'),
+  ],
+  globals: true,
+};
+
+export default {
+  projects: [
+    withTestPreset({
+      name: 'i18n-extensions-node',
+      testEnvironment: 'node',
+      include: ['tests/**/*.test.ts'],
+      extends: commonConfig,
+    }),
+    withTestPreset({
+      name: 'i18n-extensions-client',
+      testEnvironment: 'happy-dom',
+      include: ['tests/**/*.test.tsx'],
+      extends: {
+        ...commonConfig,
+        tools: {
+          swc: {
+            jsc: { transform: { react: { runtime: 'automatic' } } },
+          },
+        },
+      },
+    }),
+  ],
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './language-sync/controller';
+export * from './language-sync/react';
+export * from './localisedUrls/index';

package/src/language-sync/controller.ts

@@ -0,0 +1,386 @@
+export type LanguageSyncFailureReason = 'rejected' | 'timeout';
+
+export interface LanguageSyncFailure {
+  attempts: number;
+  error: unknown;
+  language: string;
+  reason: LanguageSyncFailureReason;
+}
+
+export interface LanguageSyncPolicy {
+  attemptTimeoutMs?: number;
+  maxAttempts?: number;
+  retryDelayMs?: (failedAttempts: number) => number;
+}
+
+export interface LanguageSyncCallbacks<TTarget extends object> {
+  changeLanguage: (
+    target: TTarget,
+    language: string,
+  ) => PromiseLike<unknown> | unknown;
+  commitLanguage: (target: TTarget, language: string) => void;
+  readLanguage?: (target: TTarget) => string | undefined;
+  reportFailure?: (failure: LanguageSyncFailure) => void;
+}
+
+export interface LatestLanguageSyncBinding<TTarget extends object> {
+  activate(target: TTarget): void;
+  clearRequest(): void;
+  deactivate(): void;
+  request(language: string): void;
+  updateCallbacks(callbacks: LanguageSyncCallbacks<TTarget>): void;
+}
+
+const DEFAULT_ATTEMPT_TIMEOUT_MS = 1_000;
+const DEFAULT_MAX_ATTEMPTS = 4;
+
+const defaultRetryDelay = (failedAttempts: number) =>
+  Math.min(50 * 2 ** Math.max(failedAttempts - 1, 0), 1_000);
+
+const normalizePolicy = (policy: LanguageSyncPolicy) => ({
+  attemptTimeoutMs: Math.max(
+    1,
+    policy.attemptTimeoutMs ?? DEFAULT_ATTEMPT_TIMEOUT_MS,
+  ),
+  maxAttempts: Math.max(1, policy.maxAttempts ?? DEFAULT_MAX_ATTEMPTS),
+  retryDelayMs: policy.retryDelayMs ?? defaultRetryDelay,
+});
+
+class LanguageSyncTimeoutError extends Error {
+  constructor(language: string, timeoutMs: number) {
+    super(
+      `Language synchronization for "${language}" did not settle within ${timeoutMs}ms.`,
+    );
+    this.name = 'LanguageSyncTimeoutError';
+  }
+}
+
+interface ActiveIntent {
+  attempts: number;
+  generation: number;
+  language: string;
+  status: 'attempting' | 'failed' | 'retry-wait' | 'satisfied';
+}
+
+interface Attempt {
+  generation: number;
+  language: string;
+  settled: boolean;
+  timedOut: boolean;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+let requestOrder = 0;
+
+class Binding<TTarget extends object> {
+  callbacks: LanguageSyncCallbacks<TTarget> | undefined;
+  coordinator: Coordinator<TTarget> | undefined;
+  desiredLanguage: string | undefined;
+  order = 0;
+  target: TTarget | undefined;
+
+  constructor(readonly policy: ReturnType<typeof normalizePolicy>) {}
+
+  activate(target: TTarget) {
+    if (this.target === target && this.coordinator) {
+      return;
+    }
+    const desiredLanguage = this.desiredLanguage;
+    const order = this.order;
+    this.deactivate();
+    this.desiredLanguage = desiredLanguage;
+    this.order = order;
+    this.target = target;
+    this.coordinator = getCoordinator(target, this.policy);
+    this.coordinator.add(this);
+    this.coordinator.refresh();
+  }
+
+  clearRequest() {
+    if (!this.desiredLanguage) {
+      return;
+    }
+    this.desiredLanguage = undefined;
+    this.order = ++requestOrder;
+    this.coordinator?.refresh();
+  }
+
+  deactivate() {
+    const coordinator = this.coordinator;
+    this.coordinator = undefined;
+    this.target = undefined;
+    this.desiredLanguage = undefined;
+    coordinator?.remove(this);
+  }
+
+  request(language: string) {
+    const normalizedLanguage = language.trim();
+    if (!normalizedLanguage) {
+      return;
+    }
+    const repeatedFailedRequest =
+      this.desiredLanguage === normalizedLanguage &&
+      this.coordinator?.isFailed(normalizedLanguage);
+    this.desiredLanguage = normalizedLanguage;
+    this.order = ++requestOrder;
+    this.coordinator?.refresh(repeatedFailedRequest);
+  }
+
+  updateCallbacks(callbacks: LanguageSyncCallbacks<TTarget>) {
+    this.callbacks = callbacks;
+  }
+}
+
+class Coordinator<TTarget extends object> {
+  private readonly bindings = new Set<Binding<TTarget>>();
+  private generation = 0;
+  private intent: ActiveIntent | undefined;
+  private retryTimer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(
+    private readonly target: TTarget,
+    private readonly policy: ReturnType<typeof normalizePolicy>,
+  ) {}
+
+  add(binding: Binding<TTarget>) {
+    this.bindings.add(binding);
+  }
+
+  isFailed(language: string) {
+    return (
+      this.intent?.language === language && this.intent.status === 'failed'
+    );
+  }
+
+  refresh(forceRetry = false) {
+    const selected = this.selectBinding();
+    if (!selected?.desiredLanguage) {
+      this.invalidateIntent();
+      return;
+    }
+
+    const language = selected.desiredLanguage;
+    if (this.intent?.language === language && !forceRetry) {
+      if (this.intent.status === 'satisfied') {
+        this.commit(language);
+      }
+      return;
+    }
+
+    this.beginIntent(language, false);
+  }
+
+  remove(binding: Binding<TTarget>) {
+    this.bindings.delete(binding);
+    this.refresh();
+  }
+
+  private beginIntent(language: string, forceChange: boolean) {
+    this.clearRetry();
+    const intent: ActiveIntent = {
+      attempts: 0,
+      generation: ++this.generation,
+      language,
+      status: 'attempting',
+    };
+    this.intent = intent;
+
+    const activeBinding = this.selectBinding();
+    if (
+      !forceChange &&
+      activeBinding?.callbacks?.readLanguage?.(this.target) === language
+    ) {
+      intent.status = 'satisfied';
+      this.commit(language);
+      return;
+    }
+
+    this.startAttempt(intent);
+  }
+
+  private clearRetry() {
+    if (this.retryTimer !== undefined) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = undefined;
+    }
+  }
+
+  private commit(language: string) {
+    for (const binding of this.bindings) {
+      if (binding.callbacks) {
+        binding.callbacks.commitLanguage(this.target, language);
+      }
+    }
+  }
+
+  private failAttempt(
+    intent: ActiveIntent,
+    reason: LanguageSyncFailureReason,
+    error: unknown,
+  ) {
+    if (this.intent !== intent || intent.status === 'satisfied') {
+      return;
+    }
+
+    if (intent.attempts >= this.policy.maxAttempts) {
+      intent.status = 'failed';
+      for (const binding of this.bindings) {
+        if (binding.desiredLanguage === intent.language) {
+          binding.callbacks?.reportFailure?.({
+            attempts: intent.attempts,
+            error,
+            language: intent.language,
+            reason,
+          });
+        }
+      }
+      return;
+    }
+
+    intent.status = 'retry-wait';
+    const retryDelay = Math.max(0, this.policy.retryDelayMs(intent.attempts));
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = undefined;
+      if (this.intent === intent && this.selectBinding()?.desiredLanguage) {
+        intent.status = 'attempting';
+        this.startAttempt(intent);
+      }
+    }, retryDelay);
+  }
+
+  private invalidateIntent() {
+    this.clearRetry();
+    this.generation += 1;
+    this.intent = undefined;
+  }
+
+  private onFulfilled(attempt: Attempt) {
+    if (attempt.settled) {
+      return;
+    }
+    attempt.settled = true;
+    clearTimeout(attempt.timer);
+
+    const intent = this.intent;
+    if (!intent) {
+      return;
+    }
+
+    if (attempt.language === intent.language) {
+      this.clearRetry();
+      if (intent.status !== 'satisfied') {
+        intent.status = 'satisfied';
+        this.commit(intent.language);
+      }
+      return;
+    }
+
+    // A superseded operation may mutate a shared i18n singleton when it
+    // eventually settles. Reassert the committed intent through the newest
+    // mounted binding, even when the binding that started the stale work left.
+    this.beginIntent(intent.language, true);
+  }
+
+  private onRejected(attempt: Attempt, error: unknown) {
+    if (attempt.settled) {
+      return;
+    }
+    attempt.settled = true;
+    clearTimeout(attempt.timer);
+    if (attempt.timedOut) {
+      return;
+    }
+
+    const intent = this.intent;
+    if (
+      intent?.generation === attempt.generation &&
+      intent.language === attempt.language
+    ) {
+      this.failAttempt(intent, 'rejected', error);
+    }
+  }
+
+  private selectBinding() {
+    let selected: Binding<TTarget> | undefined;
+    for (const binding of this.bindings) {
+      if (
+        binding.desiredLanguage &&
+        binding.callbacks &&
+        (!selected || binding.order > selected.order)
+      ) {
+        selected = binding;
+      }
+    }
+    return selected;
+  }
+
+  private startAttempt(intent: ActiveIntent) {
+    const binding = this.selectBinding();
+    const callbacks = binding?.callbacks;
+    if (!callbacks || binding?.desiredLanguage !== intent.language) {
+      this.refresh();
+      return;
+    }
+
+    intent.attempts += 1;
+    const attempt: Attempt = {
+      generation: intent.generation,
+      language: intent.language,
+      settled: false,
+      timedOut: false,
+      timer: undefined as unknown as ReturnType<typeof setTimeout>,
+    };
+    attempt.timer = setTimeout(() => {
+      if (attempt.settled || attempt.timedOut) {
+        return;
+      }
+      attempt.timedOut = true;
+      if (
+        this.intent === intent &&
+        intent.generation === attempt.generation &&
+        intent.language === attempt.language
+      ) {
+        this.failAttempt(
+          intent,
+          'timeout',
+          new LanguageSyncTimeoutError(
+            attempt.language,
+            this.policy.attemptTimeoutMs,
+          ),
+        );
+      }
+    }, this.policy.attemptTimeoutMs);
+
+    let result: PromiseLike<unknown> | unknown;
+    try {
+      result = callbacks.changeLanguage(this.target, intent.language);
+    } catch (error) {
+      this.onRejected(attempt, error);
+      return;
+    }
+
+    Promise.resolve(result).then(
+      () => this.onFulfilled(attempt),
+      error => this.onRejected(attempt, error),
+    );
+  }
+}
+
+const coordinators = new WeakMap<object, Coordinator<any>>();
+
+const getCoordinator = <TTarget extends object>(
+  target: TTarget,
+  policy: ReturnType<typeof normalizePolicy>,
+): Coordinator<TTarget> => {
+  const existing = coordinators.get(target);
+  if (existing) {
+    return existing;
+  }
+  const coordinator = new Coordinator(target, policy);
+  coordinators.set(target, coordinator);
+  return coordinator;
+};
+
+export const createLatestLanguageSyncBinding = <TTarget extends object>(
+  policy: LanguageSyncPolicy = {},
+): LatestLanguageSyncBinding<TTarget> => new Binding(normalizePolicy(policy));