@formatjs/intl-localematcher 0.7.2 → 0.7.4

package/README.md

@@ -1,3 +1,41 @@
 # Intl LocaleMatcher
 
 We've migrated the docs to https://formatjs.github.io/docs/polyfills/intl-localematcher.
+
+## Performance
+
+This package implements a highly optimized three-tier locale matching algorithm that provides excellent performance even with large locale sets (700+ locales).
+
+### Benchmark Results
+
+Benchmarked with 725 CLDR locales on Node.js:
+
+| Scenario                                                | Latency | Throughput | Relative Performance |
+| ------------------------------------------------------- | ------- | ---------- | -------------------- |
+| **Tier 1: Exact Match** (`en`)                          | 1.38ms  | 730 ops/s  | Baseline             |
+| **Tier 2: 1-level Fallback** (`en-US` → `en`)           | 1.39ms  | 725 ops/s  | 1.01x slower         |
+| **Tier 2: Maximized Match** (`zh-TW` → `zh-Hant`)       | 1.40ms  | 720 ops/s  | 1.02x slower         |
+| **Tier 3: CLDR Distance** (`sr-Latn-BA` → `sr-Latn-BA`) | 1.38ms  | 730 ops/s  | 1.00x slower         |
+| **Tier 3: Fuzzy Match** (`en-XZ` → `en`)                | 1.50ms  | 670 ops/s  | 1.09x slower         |
+
+### Real-world Impact
+
+The optimization in this package resolved [issue #4936](https://github.com/formatjs/formatjs/issues/4936), where `DurationFormat` instantiation was taking **610ms** on React Native/Hermes due to slow locale matching against 700+ auto-loaded locales.
+
+**After optimization:**
+
+- Common case (`en-US`): **1.39ms** per instantiation
+- Chinese locales (`zh-TW`): **1.40ms** per instantiation
+- Serbo-Croatian locales: **1.38ms** per instantiation
+
+**Performance improvement: 439x faster** 🚀
+
+### Three-Tier Optimization
+
+The algorithm uses three tiers for maximum performance:
+
+1. **Tier 1 (Exact Match)**: O(1) Set lookup for exact locale matches
+2. **Tier 2 (Maximization + Fallback)**: Progressive subtag removal with locale maximization
+3. **Tier 3 (CLDR Distance)**: Full UTS #35 Enhanced Language Matching with memoization
+
+This design ensures that common cases (exact matches and simple fallbacks) are extremely fast, while complex scenarios (script/region matching, language distances) still perform well.

package/abstract/BestAvailableLocale.js

@@ -1,12 +1,20 @@
+// Cache for Set conversions to avoid repeated array->Set conversions
+var availableLocalesSetCache = new WeakMap();
 /**
  * https://tc39.es/ecma402/#sec-bestavailablelocale
  * @param availableLocales
  * @param locale
  */
 export function BestAvailableLocale(availableLocales, locale) {
+    // Fast path: use Set for O(1) lookups instead of O(n) indexOf
+    var availableSet = availableLocalesSetCache.get(availableLocales);
+    if (!availableSet) {
+        availableSet = new Set(availableLocales);
+        availableLocalesSetCache.set(availableLocales, availableSet);
+    }
     var candidate = locale;
     while (true) {
-        if (availableLocales.indexOf(candidate) > -1) {
+        if (availableSet.has(candidate)) {
             return candidate;
         }
         var pos = candidate.lastIndexOf('-');