@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.11 → 3.9.0-ultramodern.12

package/src/localisedUrls/resolve.ts

@@ -0,0 +1,106 @@
+import { normalisePathname } from './normalise';
+
+import {
+  buildPathFromPattern,
+  matchPathPattern,
+  sortPatternsBySpecificity,
+} from './patterns';
+
+import type { LocalisedUrlsMap } from './types';
+
+type CanonicalCandidate = {
+  pattern: string;
+  canonicalPattern: string;
+  localisedUrlEntry: LocalisedUrlsMap[string];
+};
+
+type ResolveLocalisedUrlPathOptions =
+  | {
+      mode: 'localised';
+      targetLanguage: string;
+    }
+  | {
+      mode: 'canonical';
+    };
+
+const getCanonicalCandidates = (
+  localisedUrls: LocalisedUrlsMap,
+): CanonicalCandidate[] =>
+  sortPatternsBySpecificity(
+    Object.entries(localisedUrls).map(
+      ([canonicalPattern, localisedUrlEntry]) => ({
+        pattern: canonicalPattern,
+        canonicalPattern,
+        localisedUrlEntry,
+      }),
+    ),
+  );
+
+const resolveLocalisedUrlPath = (
+  pathname: string,
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+  options: ResolveLocalisedUrlPathOptions,
+): string => {
+  const normalizedPathname = normalisePathname(pathname);
+  const canonicalCandidates = getCanonicalCandidates(localisedUrls);
+
+  const candidates = sortPatternsBySpecificity(
+    canonicalCandidates.flatMap(({ canonicalPattern, localisedUrlEntry }) => {
+      const targetPattern =
+        options.mode === 'localised'
+          ? localisedUrlEntry[options.targetLanguage]
+          : canonicalPattern;
+      if (!targetPattern) {
+        return [];
+      }
+
+      const sourcePatterns = new Set([
+        canonicalPattern,
+        ...languages
+          .map(language => localisedUrlEntry[language])
+          .filter((sourcePattern): sourcePattern is string =>
+            Boolean(sourcePattern),
+          ),
+      ]);
+      return Array.from(sourcePatterns, sourcePattern => ({
+        pattern: sourcePattern,
+        sourcePattern,
+        targetPattern,
+      }));
+    }),
+  );
+
+  for (const { sourcePattern, targetPattern } of candidates) {
+    const params = matchPathPattern(normalizedPathname, sourcePattern);
+    if (params) {
+      return buildPathFromPattern(targetPattern, params);
+    }
+  }
+
+  return normalizedPathname;
+};
+
+export const resolveLocalisedPath = (
+  pathname: string,
+  targetLanguage: string,
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+): string =>
+  resolveLocalisedUrlPath(pathname, languages, localisedUrls, {
+    mode: 'localised',
+    targetLanguage,
+  });
+
+/**
+ * Reverse-map language-specific pathnames back to language-agnostic
+ * LocalisedUrlsMap keys.
+ */
+export const resolveCanonicalLocalisedPath = (
+  pathname: string,
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+): string =>
+  resolveLocalisedUrlPath(pathname, languages, localisedUrls, {
+    mode: 'canonical',
+  });

package/src/localisedUrls/routeIdentity.ts

@@ -0,0 +1,83 @@
+import { normalisePathPattern } from './normalise';
+import { buildPathFromPattern, matchPathPattern } from './patterns';
+
+interface RouteIdentity {
+  id?: string;
+  path?: string;
+  canonicalPath: string;
+  paths?: Record<string, string>;
+}
+
+interface RouteNode {
+  id?: string;
+  path?: string;
+  children?: RouteNode[];
+  modernLocalisedRoute?: RouteIdentity;
+}
+
+type PathRewrite = { from: string; to: string };
+
+function rewritePath(url: URL, mappings: PathRewrite[]) {
+  for (const { from, to } of mappings) {
+    const params = matchPathPattern(url.pathname, from);
+    if (params) {
+      url.pathname = buildPathFromPattern(to, params);
+      break;
+    }
+  }
+  return url;
+}
+
+/** Use the router's URL rewrite seam; browser URLs retain their locale spelling. */
+export function createLocalisedRouteRewrite(routes: RouteNode[]) {
+  const input: PathRewrite[] = [];
+  const output: PathRewrite[] = [];
+  const visit = (nodes: RouteNode[], parent: string) => {
+    for (const route of nodes) {
+      const fullPath = normalisePathPattern(`${parent}/${route.path ?? ''}`);
+      const identity = route.modernLocalisedRoute;
+      if (identity?.paths && fullPath.endsWith(identity.canonicalPath)) {
+        const prefix = fullPath.slice(0, -identity.canonicalPath.length);
+        const hasLocale = prefix
+          .split('/')
+          .some(segment => /^:(?:lang|locale|language)\??$/.test(segment));
+        for (const [language, localisedPath] of Object.entries(
+          identity.paths,
+        )) {
+          const localePrefix = prefix
+            .split('/')
+            .map(segment =>
+              /^:(?:lang|locale|language)\??$/.test(segment)
+                ? language
+                : segment,
+            )
+            .join('/');
+          const canonical = normalisePathPattern(
+            `${localePrefix}/${identity.canonicalPath}`,
+          );
+          const localised = normalisePathPattern(
+            `${localePrefix}/${localisedPath}`,
+          );
+          if (canonical !== localised) {
+            input.push({ from: localised, to: canonical });
+            if (hasLocale) output.push({ from: canonical, to: localised });
+          }
+        }
+      }
+      if (route.children) visit(route.children, fullPath);
+    }
+  };
+  visit(routes, '');
+  if (input.length === 0) return undefined;
+  const specificity = (pattern: string) =>
+    pattern
+      .split('/')
+      .filter(segment => segment && !segment.startsWith(':') && segment !== '*')
+      .length;
+  for (const mappings of [input, output])
+    mappings.sort((a, b) => specificity(b.from) - specificity(a.from));
+  return {
+    input: ({ url }: { url: URL }) => rewritePath(url, input),
+    output: ({ url }: { url: URL }) => rewritePath(url, output),
+  };
+}

package/src/localisedUrls/routes.ts

@@ -0,0 +1,451 @@
+import {
+  getLeadingLocaleParam,
+  normalisePathPattern,
+  normaliseRoutePath,
+  stripLeadingLocaleParam,
+} from './normalise';
+import {
+  doPathPatternsOverlap,
+  getOrderedPathParamSignature,
+  getPathParamSignature,
+  getPathPatternValidationIssue,
+  getPhysicalPathPattern,
+  haveEqualPatternSpecificity,
+} from './patterns';
+import type {
+  LocalisedRoute,
+  LocalisedUrlPathMap,
+  LocalisedUrlsMap,
+} from './types';
+
+const isLocalisableRoutePath = (path?: string): path is string => {
+  const pathWithoutLocale = stripLeadingLocaleParam(path);
+
+  if (
+    !pathWithoutLocale ||
+    pathWithoutLocale === '/' ||
+    pathWithoutLocale === '*'
+  ) {
+    return false;
+  }
+
+  return true;
+};
+
+const joinPath = (parentPath: string, routePath?: string): string => {
+  if (!isLocalisableRoutePath(routePath)) {
+    return parentPath;
+  }
+
+  const segment = normaliseRoutePath(stripLeadingLocaleParam(routePath) || '');
+  return normalisePathPattern(`${parentPath}/${segment}`);
+};
+
+const isFrameworkInternalRoutePath = (canonicalPath: string) =>
+  canonicalPath === '/_mf' || canonicalPath.startsWith('/_mf/');
+
+const legalRouteIdPart = (value: string): string =>
+  value.replace(/[^a-zA-Z0-9_$-]+/g, '_').replace(/^_+|_+$/g, '') || 'index';
+
+const formatParamSignature = (signature: string[]): string =>
+  signature.length > 0 ? signature.join(', ') : '(none)';
+
+const validateLocalisedUrlPatterns = (
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+) => {
+  const physicalPatterns = new Map<
+    string,
+    { canonicalPath: string; source: string }
+  >();
+  const claimedPatterns: Array<{
+    canonicalPath: string;
+    pattern: string;
+    source: string;
+  }> = [];
+
+  const claimPhysicalPattern = (
+    sourcePattern: string,
+    canonicalPath: string,
+    source: string,
+  ) => {
+    const physicalPattern = getPhysicalPathPattern(sourcePattern);
+    const existing = physicalPatterns.get(physicalPattern);
+    if (existing && existing.canonicalPath !== canonicalPath) {
+      throw new Error(
+        `localisedUrls["${existing.canonicalPath}"] ${existing.source} and localisedUrls["${canonicalPath}"] ${source} generate the same physical route pattern "${physicalPattern}". Localised route patterns must identify exactly one canonical route.`,
+      );
+    }
+
+    const overlapping = claimedPatterns.find(
+      claimed =>
+        claimed.canonicalPath !== canonicalPath &&
+        haveEqualPatternSpecificity(claimed.pattern, sourcePattern) &&
+        doPathPatternsOverlap(claimed.pattern, sourcePattern),
+    );
+    if (overlapping) {
+      throw new Error(
+        `localisedUrls["${overlapping.canonicalPath}"] ${overlapping.source} pattern "${overlapping.pattern}" and localisedUrls["${canonicalPath}"] ${source} pattern "${sourcePattern}" are equal-specificity overlapping route patterns. Localised route patterns must identify exactly one canonical route.`,
+      );
+    }
+
+    physicalPatterns.set(physicalPattern, { canonicalPath, source });
+    claimedPatterns.push({ canonicalPath, pattern: sourcePattern, source });
+  };
+
+  for (const [canonicalPath, entry] of Object.entries(localisedUrls).sort(
+    ([left], [right]) => (left < right ? -1 : left > right ? 1 : 0),
+  )) {
+    const canonicalIssue = getPathPatternValidationIssue(canonicalPath);
+    if (canonicalIssue) {
+      throw new Error(
+        `localisedUrls["${canonicalPath}"] canonical pattern has ${canonicalIssue}.`,
+      );
+    }
+    const expectedSignature = getPathParamSignature(canonicalPath);
+    const expectedOrderedSignature =
+      getOrderedPathParamSignature(canonicalPath);
+    claimPhysicalPattern(canonicalPath, canonicalPath, 'canonical pattern');
+
+    for (const language of languages) {
+      const localisedPattern = entry[language];
+      if (!localisedPattern) {
+        continue;
+      }
+
+      const localisedIssue = getPathPatternValidationIssue(localisedPattern);
+      if (localisedIssue) {
+        throw new Error(
+          `localisedUrls["${canonicalPath}"].${language} has ${localisedIssue}.`,
+        );
+      }
+
+      const actualSignature = getPathParamSignature(localisedPattern);
+      if (
+        actualSignature.length !== expectedSignature.length ||
+        actualSignature.some(
+          (parameter, index) => parameter !== expectedSignature[index],
+        )
+      ) {
+        throw new Error(
+          `localisedUrls["${canonicalPath}"].${language} must use the same parameter signature as "${canonicalPath}": expected ${formatParamSignature(
+            expectedSignature,
+          )}; received ${formatParamSignature(actualSignature)}.`,
+        );
+      }
+
+      const actualOrderedSignature =
+        getOrderedPathParamSignature(localisedPattern);
+      if (
+        expectedOrderedSignature.some(
+          parameter => parameter === '*' || parameter.endsWith('?'),
+        ) &&
+        actualOrderedSignature.some(
+          (parameter, index) => parameter !== expectedOrderedSignature[index],
+        )
+      ) {
+        throw new Error(
+          `localisedUrls["${canonicalPath}"].${language} must keep optional and splat parameters in canonical order: expected ${formatParamSignature(
+            expectedOrderedSignature,
+          )}; received ${formatParamSignature(actualOrderedSignature)}.`,
+        );
+      }
+
+      claimPhysicalPattern(localisedPattern, canonicalPath, `.${language}`);
+    }
+  }
+};
+
+const ensureLocalisedUrlsForPath = (
+  canonicalPath: string,
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+): LocalisedUrlPathMap => {
+  const entry = localisedUrls[canonicalPath];
+  if (!entry) {
+    throw new Error(
+      `localisedUrls is enabled, but route "${canonicalPath}" does not define localised URLs for languages: ${languages.join(
+        ', ',
+      )}. Add localisedUrls["${canonicalPath}"] or set localeDetection.localisedUrls to false.`,
+    );
+  }
+
+  const missingLanguages = languages.filter(language => !entry[language]);
+  if (missingLanguages.length > 0) {
+    throw new Error(
+      `localisedUrls["${canonicalPath}"] is missing languages: ${missingLanguages.join(
+        ', ',
+      )}. Every configured language must have a localised URL.`,
+    );
+  }
+
+  return entry;
+};
+
+export const validateLocalisedUrls = (
+  routes: LocalisedRoute[],
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+) => {
+  validateLocalisedUrlPatterns(languages, localisedUrls);
+
+  const visit = (route: LocalisedRoute, parentPath: string) => {
+    const canonicalPath = joinPath(parentPath, route.path);
+    if (
+      isLocalisableRoutePath(route.path) &&
+      !isFrameworkInternalRoutePath(canonicalPath)
+    ) {
+      ensureLocalisedUrlsForPath(canonicalPath, languages, localisedUrls);
+    }
+
+    if ('children' in route && route.children) {
+      route.children.forEach(child => visit(child, canonicalPath));
+    }
+  };
+
+  routes.forEach(route => visit(route, ''));
+};
+
+const getLocalisedRouteIdSuffixes = (
+  paths: string[],
+): Array<string | undefined> => {
+  const usedSuffixes = new Set<string>();
+
+  return paths.map((path, index) => {
+    if (index === 0) {
+      return undefined;
+    }
+
+    const baseSuffix = legalRouteIdPart(path);
+    let suffix = baseSuffix;
+    let disambiguator = 2;
+    while (usedSuffixes.has(suffix)) {
+      suffix = `${baseSuffix}_${disambiguator++}`;
+    }
+    usedSuffixes.add(suffix);
+    return suffix;
+  });
+};
+
+const getLocalisedRoutePaths = (
+  canonicalPath: string,
+  parentLocalisedPaths: Record<string, string>,
+  languages: string[],
+  entry: LocalisedUrlPathMap,
+): string[] => {
+  const paths = languages.map(language => {
+    const fullPath = normalisePathPattern(entry[language]);
+    const parentPath = normalisePathPattern(
+      parentLocalisedPaths[language] || '/',
+    );
+    if (parentPath === '/') {
+      return normaliseRoutePath(fullPath) || undefined;
+    }
+
+    const parentPrefix = `${parentPath}/`;
+    if (!fullPath.startsWith(parentPrefix)) {
+      throw new Error(
+        `localisedUrls["${canonicalPath}"].${language} must be nested under "${parentPath}" because its parent route is localised there.`,
+      );
+    }
+
+    return normaliseRoutePath(fullPath.slice(parentPath.length));
+  });
+
+  const uniquePaths = Array.from(new Set(paths.filter(Boolean) as string[]));
+  return uniquePaths;
+};
+
+const transformLocalisedRoute = (
+  route: LocalisedRoute,
+  parentCanonicalPath: string,
+  parentLocalisedPaths: Record<string, string>,
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+  projection: 'physical' | 'canonical',
+): LocalisedRoute[] => {
+  const isSplat = stripLeadingLocaleParam(route.path) === '*';
+  const canonicalPath = isSplat
+    ? normalisePathPattern(`${parentCanonicalPath}/*`)
+    : joinPath(parentCanonicalPath, route.path);
+  const localisedUrlEntry =
+    isLocalisableRoutePath(route.path) &&
+    !isFrameworkInternalRoutePath(canonicalPath)
+      ? ensureLocalisedUrlsForPath(canonicalPath, languages, localisedUrls)
+      : undefined;
+  const routeLocalisedPaths = localisedUrlEntry
+    ? languages.reduce<Record<string, string>>((acc, language) => {
+        acc[language] = normalisePathPattern(localisedUrlEntry[language]);
+        return acc;
+      }, {})
+    : isSplat
+      ? Object.fromEntries(
+          Object.entries(parentLocalisedPaths).map(([language, path]) => [
+            language,
+            normalisePathPattern(`${path}/*`),
+          ]),
+        )
+      : parentLocalisedPaths;
+
+  const children =
+    'children' in route && route.children
+      ? route.children.flatMap(child =>
+          transformLocalisedRoute(
+            child,
+            canonicalPath,
+            routeLocalisedPaths,
+            languages,
+            localisedUrls,
+            projection,
+          ),
+        )
+      : undefined;
+
+  const baseRoute = {
+    ...route,
+    ...(!isFrameworkInternalRoutePath(canonicalPath)
+      ? {
+          modernLocalisedRoute: {
+            id: route.id,
+            path: route.path,
+            canonicalPath,
+            paths:
+              localisedUrlEntry ?? (isSplat ? routeLocalisedPaths : undefined),
+          },
+        }
+      : {}),
+    ...(children ? { children } : {}),
+  } as LocalisedRoute;
+
+  if (!localisedUrlEntry) {
+    return [baseRoute];
+  }
+
+  const localisedPaths = getLocalisedRoutePaths(
+    canonicalPath,
+    parentLocalisedPaths,
+    languages,
+    localisedUrlEntry,
+  );
+  // Validate nesting for both adapters, but only React Router needs physical
+  // variants. TanStack consumes the source identity and native URL rewrites.
+  if (projection === 'canonical') return [baseRoute];
+
+  const leadingLocaleParam = getLeadingLocaleParam(route.path);
+  const routeIdPaths = leadingLocaleParam
+    ? localisedPaths.map(path =>
+        normaliseRoutePath(`${leadingLocaleParam}/${path}`),
+      )
+    : localisedPaths;
+  const routeIdSuffixes = getLocalisedRouteIdSuffixes(routeIdPaths);
+
+  return localisedPaths.map((localisedPath, index) =>
+    cloneRouteWithLocalisedPath(
+      baseRoute,
+      localisedPath,
+      routeIdSuffixes[index],
+      canonicalPath,
+    ),
+  );
+};
+
+const suffixRouteIds = <T extends LocalisedRoute>(
+  route: T,
+  suffix: string,
+): T => {
+  const children =
+    'children' in route && route.children
+      ? route.children.map(child => suffixRouteIds(child, suffix))
+      : undefined;
+
+  return {
+    ...route,
+    ...(route.id ? { id: `${route.id}__localised_${suffix}` } : {}),
+    ...(children ? { children } : {}),
+  };
+};
+
+const collectRouteIdCounts = (
+  routes: LocalisedRoute[],
+  counts = new Map<string, number>(),
+): Map<string, number> => {
+  for (const route of routes) {
+    if (route.id) {
+      counts.set(route.id, (counts.get(route.id) ?? 0) + 1);
+    }
+    if ('children' in route && route.children) {
+      collectRouteIdCounts(route.children, counts);
+    }
+  }
+  return counts;
+};
+
+const validateNoNewRouteIdCollisions = (
+  sourceRoutes: LocalisedRoute[],
+  localisedRoutes: LocalisedRoute[],
+) => {
+  const sourceCounts = collectRouteIdCounts(sourceRoutes);
+  const localisedCounts = collectRouteIdCounts(localisedRoutes);
+
+  for (const [routeId, count] of localisedCounts) {
+    if (count > 1 && count > (sourceCounts.get(routeId) ?? 0)) {
+      throw new Error(
+        `Localised route expansion generated duplicate route ID "${routeId}". Change the source route ID or localised path so every generated route remains identifiable.`,
+      );
+    }
+  }
+};
+
+const cloneRouteWithLocalisedPath = (
+  route: LocalisedRoute,
+  path: string,
+  routeIdSuffix: string | undefined,
+  canonicalPath: string,
+): LocalisedRoute => {
+  const leadingLocaleParam = getLeadingLocaleParam(route.path);
+  const localisedPath = leadingLocaleParam
+    ? normaliseRoutePath(`${leadingLocaleParam}/${path}`)
+    : path;
+  const routeWithPath = {
+    ...route,
+    path: localisedPath,
+  } as LocalisedRoute;
+  // Language-agnostic source pattern; lets downstream codegen collapse the
+  // localized physical variants back to one canonical route.
+  (routeWithPath as { modernCanonicalPath?: string }).modernCanonicalPath =
+    canonicalPath;
+
+  return routeIdSuffix
+    ? suffixRouteIds(routeWithPath, routeIdSuffix)
+    : routeWithPath;
+};
+
+export const applyLocalisedUrlsToRoutes = (
+  routes: LocalisedRoute[],
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+  projection: 'physical' | 'canonical' = 'physical',
+): LocalisedRoute[] => {
+  const rootLocalisedPaths = languages.reduce<Record<string, string>>(
+    (acc, language) => {
+      acc[language] = '/';
+      return acc;
+    },
+    {},
+  );
+
+  validateLocalisedUrls(routes, languages, localisedUrls);
+
+  const localisedRoutes = routes.flatMap(route =>
+    transformLocalisedRoute(
+      route,
+      '',
+      rootLocalisedPaths,
+      languages,
+      localisedUrls,
+      projection,
+    ),
+  );
+  validateNoNewRouteIdCollisions(routes, localisedRoutes);
+  return localisedRoutes;
+};

package/src/localisedUrls/types.ts

@@ -0,0 +1,18 @@
+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/src/routeHydration.ts

@@ -71,7 +71,7 @@ const isAsyncEntryScriptChunk = (chunk: ScriptChunkLike, entryName: string) => {
 
 export function getMatchedRouteChunks<T>(
   routeManifest: RouteManifestLike | undefined,
-  matchedRouteIds: string[],
+  matchedRouteIds: readonly string[],
   routeAssetToChunk: (asset: string) => T,
 ): T[] {
   const routeAssets = routeManifest?.routeAssets;
@@ -167,7 +167,7 @@ export function replaceChunkJsPlaceholder(
 
 export function createRouteHydrationScriptTags(
   routeManifest: RouteManifestLike | undefined,
-  matchedRouteIds: string[],
+  matchedRouteIds: readonly string[],
   entryName: string,
   options: {
     nonce?: string;