@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.9 → 3.9.3-ultramodern.1

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@bleedingdev/modern-js-runtime-extensions",
   "description": "Fork-owned UltraModern.js runtime transaction, streaming, and safe failure primitives.",
-  "homepage": "https://github.com/BleedingDev/ultramodern.js#readme",
+  "homepage": "https://github.com/ultramodernjs/ultramodern.js#readme",
   "bugs": {
-    "url": "https://github.com/BleedingDev/ultramodern.js/issues"
+    "url": "https://github.com/ultramodernjs/ultramodern.js/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/BleedingDev/ultramodern.js.git",
+    "url": "git+https://github.com/ultramodernjs/ultramodern.js.git",
     "directory": "packages/runtime/runtime-extensions"
   },
   "license": "MIT",
-  "version": "3.9.0-ultramodern.9",
+  "version": "3.9.3-ultramodern.1",
   "engines": {
-    "node": ">=26.7.0"
+    "node": ">=26.10.0"
   },
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.js",
@@ -42,14 +42,6 @@
       },
       "default": "./dist/esm/safeFailure.mjs"
     },
-    "./build-identity": {
-      "types": "./dist/types/buildIdentity.d.ts",
-      "node": {
-        "import": "./dist/esm-node/buildIdentity.mjs",
-        "require": "./dist/cjs/buildIdentity.js"
-      },
-      "default": "./dist/esm/buildIdentity.mjs"
-    },
     "./workspace-events": {
       "types": "./dist/types/workspaceEvents.d.ts",
       "node": {
@@ -70,14 +62,6 @@
       },
       "default": "./dist/esm/localisedLoaderIdentity.mjs"
     },
-    "./react-context": {
-      "types": "./dist/types/reactContext.d.ts",
-      "node": {
-        "import": "./dist/esm-node/reactContext.mjs",
-        "require": "./dist/cjs/reactContext.js"
-      },
-      "default": "./dist/esm/reactContext.mjs"
-    },
     "./context-extensions": {
       "types": "./dist/types/contextExtensions.d.ts",
       "node": {
@@ -186,6 +170,14 @@
         "require": "./dist/cjs/routerPrefetchPolicy.js"
       },
       "default": "./dist/esm/routerPrefetchPolicy.mjs"
+    },
+    "./localised-urls": {
+      "types": "./dist/types/localisedUrls/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/localisedUrls/index.mjs",
+        "require": "./dist/cjs/localisedUrls/index.js"
+      },
+      "default": "./dist/esm/localisedUrls/index.mjs"
     }
   },
   "typesVersions": {
@@ -202,10 +194,6 @@
         "./dist/types/safeFailure.d.ts",
         "./src/safeFailure.ts"
       ],
-      "build-identity": [
-        "./dist/types/buildIdentity.d.ts",
-        "./src/buildIdentity.ts"
-      ],
       "workspace-events": [
         "./dist/types/workspaceEvents.d.ts",
         "./src/workspaceEvents.ts"
@@ -214,10 +202,6 @@
         "./dist/types/localisedLoaderIdentity.d.ts",
         "./src/localisedLoaderIdentity.ts"
       ],
-      "react-context": [
-        "./dist/types/reactContext.d.ts",
-        "./src/reactContext.ts"
-      ],
       "context-extensions": [
         "./dist/types/contextExtensions.d.ts",
         "./src/contextExtensions.ts"
@@ -269,47 +253,61 @@
       "router-prefetch-policy": [
         "./dist/types/routerPrefetchPolicy.d.ts",
         "./src/routerPrefetchPolicy.ts"
+      ],
+      "localised-urls": [
+        "./dist/types/localisedUrls/index.d.ts",
+        "./src/localisedUrls/index.ts"
       ]
     }
   },
   "devDependencies": {
     "@loadable/component": "5.16.7",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.0-ultramodern.9",
-    "@rsbuild/core": "2.2.3",
-    "@rslib/core": "1.0.0",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.3-ultramodern.1",
+    "@rsbuild/core": "2.2.11",
+    "@rslib/core": "1.0.3",
     "@scripts/rstest-config": "2.66.0",
-    "@testing-library/dom": "^10.4.1",
+    "@testing-library/dom": "^10.4.2",
     "@testing-library/react": "^16.3.3",
-    "@types/node": "^26.4.1",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.7",
-    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@types/node": "^26.6.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "esbuild": "^0.28.2",
     "nock": "^14.0.17",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "typescript": "^7.0.2"
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-helmet-async": "3.0.0",
+    "typescript": "7.0.2"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
-    "react": "^19.2.8"
+    "react": "^19.2.8",
+    "react-helmet-async": "3.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "react-helmet-async": {
+      "optional": true
     }
   },
   "dependencies": {
-    "@modern-js/create-request": "npm:@bleedingdev/modern-js-create-request@3.9.0-ultramodern.9",
-    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.0-ultramodern.9",
-    "react-helmet-async": "3.0.0"
+    "@modern-js/create-request": "npm:@bleedingdev/modern-js-create-request@3.9.3-ultramodern.1",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.3-ultramodern.1"
   },
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
     "dev": "rslib build --watch",
     "build": "rslib build",
     "test": "rstest"
+  },
+  "ultramodern": {
+    "sourceName": "@modern-js/runtime-extensions"
   }
 }

package/src/helmetCompat.ts

@@ -149,7 +149,7 @@ const createElementFactory = <Element>(react: ElementFactory<Element>) =>
 
 export const renderHeadMarker = <Element>(
   react: ElementFactory<Element>,
-  marker: MarkerProps | null | undefined,
+  marker: MarkerProps | undefined,
 ): Element | null =>
   marker ? createElementFactory(react)('template', marker) : null;
 

package/src/localisedUrls/config.ts

@@ -0,0 +1,18 @@
+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 const resolveLocalisedUrlsConfig = (
+  option: LocalisedUrlsOption | undefined,
+): ResolvedLocalisedUrlsConfig => {
+  if (option && typeof option === 'object' && Object.keys(option).length > 0) {
+    return { enabled: true, map: option };
+  }
+
+  return { enabled: false, map: {} };
+};

package/src/localisedUrls/index.ts

@@ -0,0 +1,25 @@
+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 { createLocalisedRouteRewrite } from './routeIdentity';
+export { applyLocalisedUrlsToRoutes, validateLocalisedUrls } from './routes';
+export type {
+  LocalisedRoute,
+  LocalisedUrlPathMap,
+  LocalisedUrlsMap,
+  LocalisedUrlsOption,
+  ResolvedLocalisedUrlsConfig,
+} from './types';

package/src/localisedUrls/normalise.ts

@@ -0,0 +1,62 @@
+const LOCALE_PARAM_NAMES = new Set(['lang', 'locale', 'language']);
+
+const normaliseSlashes = (path: string): string => {
+  const withoutDuplicateSlashes = path.replace(/\/+/g, '/');
+  const withLeadingSlash = withoutDuplicateSlashes.startsWith('/')
+    ? withoutDuplicateSlashes
+    : `/${withoutDuplicateSlashes}`;
+
+  return withLeadingSlash.length > 1
+    ? withLeadingSlash.replace(/\/+$/, '')
+    : withLeadingSlash;
+};
+
+export const normalisePathPattern = (path: string): string =>
+  normaliseSlashes(path).replace(/\[(.+?)\]/g, ':$1');
+
+/**
+ * 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 const normalisePathname = (pathname: string): string =>
+  normaliseSlashes(pathname);
+
+export const normaliseRoutePath = (path: string): string => {
+  const normalized = normalisePathPattern(path);
+  return normalized === '/' ? '' : normalized.slice(1);
+};
+
+const getLocaleParamSegment = (segment: string): string | null => {
+  if (!segment.startsWith(':')) {
+    return null;
+  }
+
+  const paramName = segment.slice(1).replace(/\?$/, '');
+  return LOCALE_PARAM_NAMES.has(paramName) ? segment : null;
+};
+
+const splitPathSegments = (path?: string): string[] => {
+  if (!path) {
+    return [];
+  }
+
+  return normalisePathPattern(path).split('/').filter(Boolean);
+};
+
+export const stripLeadingLocaleParam = (path?: string): string | undefined => {
+  const segments = splitPathSegments(path);
+  const leadingLocaleParam = getLocaleParamSegment(segments[0] || '');
+
+  if (!leadingLocaleParam) {
+    return path;
+  }
+
+  const remainingPath = segments.slice(1).join('/');
+  return remainingPath ? `/${remainingPath}` : undefined;
+};
+
+export const getLeadingLocaleParam = (path?: string): string | null => {
+  const segments = splitPathSegments(path);
+  return getLocaleParamSegment(segments[0] || '');
+};

package/src/localisedUrls/pathname.ts

@@ -0,0 +1,60 @@
+import { resolveLocalisedUrlsConfig } from './config';
+
+import { resolveCanonicalLocalisedPath, resolveLocalisedPath } from './resolve';
+
+import type { LocalisedUrlsOption } from './types';
+
+export const stripLanguagePrefix = (
+  pathname: string,
+  languages: string[],
+): string => {
+  const segments = pathname.split('/').filter(Boolean);
+  const firstSegment = segments[0]?.toLowerCase();
+
+  if (
+    firstSegment &&
+    languages.some(language => language.toLowerCase() === firstSegment)
+  ) {
+    return `/${segments.slice(1).join('/')}`;
+  }
+
+  return pathname || '/';
+};
+
+export const localiseTargetPathname = (
+  pathname: string,
+  language: string,
+  languages: string[],
+  localisedUrls?: LocalisedUrlsOption,
+): string => {
+  const pathWithoutLanguage = stripLanguagePrefix(pathname, languages);
+  const localisedUrlsConfig = resolveLocalisedUrlsConfig(localisedUrls);
+  const resolvedPath = localisedUrlsConfig.enabled
+    ? resolveLocalisedPath(
+        pathWithoutLanguage,
+        language,
+        languages,
+        localisedUrlsConfig.map,
+      )
+    : pathWithoutLanguage;
+  const resolvedSegments = resolvedPath.split('/').filter(Boolean);
+
+  return `/${[language, ...resolvedSegments].join('/')}`;
+};
+
+export const canonicalTargetPathname = (
+  pathname: string,
+  languages: string[],
+  localisedUrls?: LocalisedUrlsOption,
+): string => {
+  const pathWithoutLanguage = stripLanguagePrefix(pathname, languages);
+  const localisedUrlsConfig = resolveLocalisedUrlsConfig(localisedUrls);
+
+  return localisedUrlsConfig.enabled
+    ? resolveCanonicalLocalisedPath(
+        pathWithoutLanguage,
+        languages,
+        localisedUrlsConfig.map,
+      )
+    : pathWithoutLanguage;
+};

package/src/localisedUrls/patterns.ts

@@ -0,0 +1,283 @@
+import { normalisePathname, normalisePathPattern } from './normalise';
+
+const escapeRegExp = (value: string): string =>
+  value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const getParamName = (segment: string): string =>
+  segment.slice(1).replace(/\?$/, '');
+
+export const getOrderedPathParamSignature = (pattern: string): string[] =>
+  normalisePathPattern(pattern)
+    .split('/')
+    .filter(Boolean)
+    .flatMap(segment => {
+      if (segment === '*') {
+        return ['*'];
+      }
+      if (!segment.startsWith(':')) {
+        return [];
+      }
+
+      return [`:${getParamName(segment)}${segment.endsWith('?') ? '?' : ''}`];
+    });
+
+export const getPathParamSignature = (pattern: string): string[] =>
+  getOrderedPathParamSignature(pattern).sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0,
+  );
+
+export const getPathPatternValidationIssue = (
+  pattern: string,
+): string | undefined => {
+  const segments = normalisePathPattern(pattern).split('/').filter(Boolean);
+  const seenParams = new Set<string>();
+
+  for (const [index, segment] of segments.entries()) {
+    if (segment === '*') {
+      if (index !== segments.length - 1) {
+        return 'splat parameter "*" must be the final segment';
+      }
+      if (seenParams.has('*')) {
+        return 'duplicate splat parameter "*"';
+      }
+      seenParams.add('*');
+      continue;
+    }
+    if (!segment.startsWith(':')) {
+      continue;
+    }
+
+    const paramName = getParamName(segment);
+    if (seenParams.has(paramName)) {
+      return `duplicate path parameter ":${paramName}"`;
+    }
+    seenParams.add(paramName);
+  }
+
+  return undefined;
+};
+
+export const getPhysicalPathPattern = (pattern: string): string => {
+  const segments = normalisePathPattern(pattern).split('/').filter(Boolean);
+  const physicalSegments = segments.map(segment => {
+    if (segment === '*') {
+      return '*';
+    }
+    if (segment.startsWith(':')) {
+      return segment.endsWith('?') ? ':param?' : ':param';
+    }
+    return segment;
+  });
+
+  return `/${physicalSegments.join('/')}`;
+};
+
+interface CompiledPathPattern {
+  names: string[];
+  regexp: RegExp;
+}
+
+const compiledPathPatternCache = new Map<string, CompiledPathPattern>();
+
+const compilePathPattern = (pattern: string): CompiledPathPattern => {
+  const normalizedPattern = normalisePathPattern(pattern);
+  const cached = compiledPathPatternCache.get(normalizedPattern);
+  if (cached) {
+    return cached;
+  }
+
+  const names: string[] = [];
+  const segments = normalizedPattern.split('/').filter(Boolean);
+  const source = segments
+    .map(segment => {
+      if (segment.startsWith(':')) {
+        names.push(getParamName(segment));
+        const paramPattern = '([^/]+)';
+        return segment.endsWith('?')
+          ? `(?:/${paramPattern})?`
+          : `/${paramPattern}`;
+      }
+      if (segment === '*') {
+        names.push('*');
+        return '(?:/(.*))?';
+      }
+      return `/${escapeRegExp(segment)}`;
+    })
+    .join('');
+
+  const compiled = {
+    names,
+    regexp: new RegExp(`^${source || '/'}$`),
+  };
+  compiledPathPatternCache.set(normalizedPattern, compiled);
+
+  return compiled;
+};
+
+const getPatternSpecificity = (pattern: string) => {
+  const segments = normalisePathPattern(pattern).split('/').filter(Boolean);
+  let staticSegments = 0;
+  let dynamicSegments = 0;
+  let optionalSegments = 0;
+  let splatSegments = 0;
+
+  for (const segment of segments) {
+    if (segment === '*') {
+      splatSegments++;
+    } else if (segment.startsWith(':')) {
+      dynamicSegments++;
+      if (segment.endsWith('?')) {
+        optionalSegments++;
+      }
+    } else {
+      staticSegments++;
+    }
+  }
+
+  return {
+    staticSegments,
+    dynamicSegments,
+    optionalSegments,
+    splatSegments,
+    totalSegments: segments.length,
+  };
+};
+
+const comparePatternSpecificity = (left: string, right: string): number => {
+  const a = getPatternSpecificity(left);
+  const b = getPatternSpecificity(right);
+
+  return (
+    b.staticSegments - a.staticSegments ||
+    a.splatSegments - b.splatSegments ||
+    a.optionalSegments - b.optionalSegments ||
+    b.totalSegments - a.totalSegments ||
+    a.dynamicSegments - b.dynamicSegments
+  );
+};
+
+export const haveEqualPatternSpecificity = (
+  left: string,
+  right: string,
+): boolean => comparePatternSpecificity(left, right) === 0;
+
+export const doPathPatternsOverlap = (left: string, right: string): boolean => {
+  const leftSegments = normalisePathPattern(left).split('/').filter(Boolean);
+  const rightSegments = normalisePathPattern(right).split('/').filter(Boolean);
+  if (leftSegments.length !== rightSegments.length) {
+    return false;
+  }
+
+  return leftSegments.every((leftSegment, index) => {
+    const rightSegment = rightSegments[index];
+    const leftIsDynamic = leftSegment === '*' || leftSegment.startsWith(':');
+    const rightIsDynamic = rightSegment === '*' || rightSegment.startsWith(':');
+    return leftIsDynamic || rightIsDynamic || leftSegment === rightSegment;
+  });
+};
+
+const comparePatternNames = (left: string, right: string): number => {
+  const normalizedLeft = normalisePathPattern(left);
+  const normalizedRight = normalisePathPattern(right);
+
+  return normalizedLeft < normalizedRight
+    ? -1
+    : normalizedLeft > normalizedRight
+      ? 1
+      : 0;
+};
+
+export const sortPatternsBySpecificity = <T extends { pattern: string }>(
+  patterns: T[],
+): T[] =>
+  patterns
+    .map((pattern, index) => ({ pattern, index }))
+    .sort(
+      (left, right) =>
+        comparePatternSpecificity(
+          left.pattern.pattern,
+          right.pattern.pattern,
+        ) ||
+        comparePatternNames(left.pattern.pattern, right.pattern.pattern) ||
+        left.index - right.index,
+    )
+    .map(({ pattern }) => pattern);
+
+/**
+ * `decodeURIComponent` throws `URIError` on malformed percent-encoding
+ * (e.g. `%E0%A4%A`), which attacker-controlled request URLs can carry.
+ * Treat such segments as undecodable instead of throwing.
+ */
+const decodePathParam = (value: string): string | null => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+};
+
+const encodeSplatParam = (value: string): string =>
+  value.split('/').map(encodeURIComponent).join('/');
+
+export const matchPathPattern = (
+  pathname: string,
+  pattern: string,
+): Record<string, string> | null => {
+  const { names, regexp } = compilePathPattern(pattern);
+  const match = regexp.exec(normalisePathname(pathname));
+  if (!match) {
+    return null;
+  }
+
+  const params: Record<string, string> = {};
+  for (let index = 0; index < names.length; index++) {
+    const decoded = decodePathParam(match[index + 1] || '');
+    if (decoded === null) {
+      // Malformed encoding cannot identify a localised route: no match.
+      return null;
+    }
+    Object.defineProperty(params, names[index], {
+      configurable: true,
+      enumerable: true,
+      value: decoded,
+      writable: true,
+    });
+  }
+
+  return params;
+};
+
+export const buildPathFromPattern = (
+  pattern: string,
+  params: Record<string, string>,
+): string => {
+  const segments = normalisePathPattern(pattern).split('/').filter(Boolean);
+  const path = segments
+    .map(segment => {
+      if (segment.startsWith(':')) {
+        const paramName = getParamName(segment);
+        const param = Object.hasOwn(params, paramName)
+          ? params[paramName]
+          : undefined;
+        if (param === undefined || param === '') {
+          if (segment.endsWith('?')) {
+            return '';
+          }
+          throw new Error(
+            `Missing required path parameter "${paramName}" for pattern "${normalisePathPattern(
+              pattern,
+            )}".`,
+          );
+        }
+        return encodeURIComponent(param);
+      }
+      if (segment === '*') {
+        return encodeSplatParam(params['*'] || '');
+      }
+      return segment;
+    })
+    .filter(Boolean)
+    .join('/');
+
+  return `/${path}`;
+};