@@W-20607771@@ Add fuzzyPathMatching option to optimize route configuration - #3530

PR: Add fuzzyPathMatching option to optimize route configuration

🎯 Summary

This PR introduces an optional fuzzyPathMatching flag to configureRoutes() that dramatically reduces the number of generated routes by using parameterized paths with regex constraints instead of explicit route enumeration.

🚨 The Problem

When configuring routes with multiple sites and locales, the current implementation generates explicit routes for every possible combination. This leads to exponential route growth:

This impacts:

• Memory usage — Large route arrays consume heap space
• Route matching performance — React Router must iterate through all routes
• Build/startup time — Route generation overhead scales with combinations

✅ The Solution

Instead of generating explicit routes like:

/us/en/products
/us/es/products
/global/en/products
/global/fr/products
...

We now support parameterized routes with regex constraints:

/:site(us|global)/:locale(en|es|fr)/products

This reduces route count from O(sites × locales × routes) to O(routes × 4) maximum.

🔧 Changes Made

1. New fuzzyPathMatching option — Opt-in flag in the options object
2. Refactored configureRoutes() — Split into two internal functions:
   • configureRoutesWithExplicitMatching() — Original behavior
   • configureRoutesWithFuzzyMatching() — New optimized approach
3. Helper function buildRoutePatterns() — Builds regex patterns from site/locale refs
4. Comprehensive test coverage — 12 new test cases for fuzzy matching

📖 Usage

// Default behavior (unchanged, backwards compatible)
const routes = configureRoutes(routes, config, { 
  ignoredRoutes: [] 
})

// New optimized behavior (opt-in)
const routes = configureRoutes(routes, config, { 
  ignoredRoutes: [],
  fuzzyPathMatching: true 
})

⚠️ Trade-offs with Fuzzy Matching

Important: With fuzzy matching enabled, invalid site/locale combinations (e.g., a locale not supported by a specific site) may match. Runtime validation should be performed after route matching:

const { site, locale } = useParams()
if (site && locale) {
  const siteConfig = getSites().find(s => s.id === site || s.alias === site)
  const validLocales = siteConfig?.l10n.supportedLocales
    .flatMap(l => [l.id, l.alias])
  
  if (!validLocales?.includes(locale)) {
    // Handle invalid combination
  }
}

🛡️ Not a Breaking Change

• Default behavior unchanged — fuzzyPathMatching defaults to false
• Existing tests pass — All 9 original test cases remain and pass
• API signature compatible — The options object is extended, not replaced
• Opt-in only — Teams must explicitly enable the new behavior

📊 Performance Comparison

For a real-world config with 2 sites, 4 locales each, and 20 base routes:

✅ Testing

• All existing tests pass
• 12 new tests added for fuzzyPathMatching
• Tests cover all URL config combinations
• Property preservation verified

npm test -- --testPathPattern=routes-utils.test.js

📝 Checklist

• Code follows project conventions
• Tests added for new functionality
• Existing tests still pass
• No breaking changes to public API
• JSDoc comments updated