@openmrs/esm-utils 9.0.3-pre.4715 → 9.0.3-pre.4735

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 13 files with swc (205.79ms)
+[0] Successfully compiled: 14 files with swc (265.01ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/get-locale.js

@@ -3,7 +3,7 @@
  * @returns string
  */ export function getLocale() {
     let language = window.i18next.language;
-    language = language.replace('_', '-'); // just in case
+    language = language.replaceAll('_', '-'); // just in case
     // Hack for `ht` until all browsers update their unicode support with ht to fr mapping.
     // See https://unicode-org.atlassian.net/browse/CLDR-14956
     if (language === 'ht') {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './age-helpers';
 export * from './dates';
 export * from './get-locale';
 export * from './is-online';
+export * from './match-locale';
 export * from './patient-helpers';
 export * from './shallowEqual';
 export * from './storage';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -3,6 +3,7 @@ export * from "./age-helpers.js";
 export * from "./dates/index.js";
 export * from "./get-locale.js";
 export * from "./is-online.js";
+export * from "./match-locale.js";
 export * from "./patient-helpers.js";
 export * from "./shallowEqual.js";
 export * from "./storage.js";

package/dist/match-locale.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolves a requested locale against a list of available locales using the
+ * BCP 47 lookup algorithm (RFC 4647, §3.4).
+ *
+ * Tags are compared in canonical form via {@link Intl.Locale}, so casing and
+ * underscore-vs-hyphen differences in the inputs do not affect matching. The
+ * value returned is taken verbatim from `available`, preserving the caller's
+ * original casing.
+ *
+ * In addition to the truncation steps prescribed by RFC 4647, this function
+ * also performs prefix expansion at each level: when the requested tag is
+ * truncated to a more general range (e.g. `en` after stripping `en-CA`), any
+ * available locale whose canonical form begins with that range plus a hyphen
+ * (e.g. `en-US`, `en-GB`) is treated as a match. This is a relaxation of the
+ * strict lookup algorithm but typically reflects user intent — a user who
+ * asked for `en-CA` will usually accept `en-US` over a non-English fallback.
+ *
+ * Tags that fail to parse are skipped with a console warning; they never match
+ * and never throw.
+ *
+ * @param requested - The locale the caller would like to use, or `null`/`undefined`
+ *   if no preference is known.
+ * @param available - The list of locales the application supports.
+ * @param fallback - The value to return when no match is found. Defaults to
+ *   `undefined`.
+ * @returns The matched locale from `available`, or `fallback` if nothing matches.
+ *
+ * @example
+ * matchLocale('en-CA', ['en-US', 'en-GB', 'fr-FR'], 'en-US'); // => 'en-US'
+ * matchLocale('fr-BE', ['en-US', 'fr-FR', 'de-DE'], 'en-US'); // => 'fr-FR'
+ * matchLocale('zh-Hant-TW', ['zh-Hant', 'zh-Hans', 'en'], 'en'); // => 'zh-Hant'
+ */
+export declare function matchLocale(requested: string | null | undefined, available: ReadonlyArray<string>, fallback?: string): string | undefined;
+//# sourceMappingURL=match-locale.d.ts.map

package/dist/match-locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match-locale.d.ts","sourceRoot":"","sources":["../src/match-locale.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CA6DpB"}

package/dist/match-locale.js

@@ -0,0 +1,104 @@
+/**
+ * Returns a canonical BCP 47 representation of `tag`, or `undefined` if it is not a
+ * structurally valid tag. Underscores are accepted as a separator and normalized to
+ * hyphens before canonicalization to accommodate locale strings that originate from
+ * Java-style identifiers (e.g. `en_GB`).
+ */ function canonicalize(tag) {
+    if (typeof tag !== 'string' || tag.trim().length === 0) {
+        return undefined;
+    }
+    const normalized = tag.replaceAll('_', '-');
+    try {
+        return new Intl.Locale(normalized).toString();
+    } catch  {
+        return undefined;
+    }
+}
+/**
+ * Resolves a requested locale against a list of available locales using the
+ * BCP 47 lookup algorithm (RFC 4647, §3.4).
+ *
+ * Tags are compared in canonical form via {@link Intl.Locale}, so casing and
+ * underscore-vs-hyphen differences in the inputs do not affect matching. The
+ * value returned is taken verbatim from `available`, preserving the caller's
+ * original casing.
+ *
+ * In addition to the truncation steps prescribed by RFC 4647, this function
+ * also performs prefix expansion at each level: when the requested tag is
+ * truncated to a more general range (e.g. `en` after stripping `en-CA`), any
+ * available locale whose canonical form begins with that range plus a hyphen
+ * (e.g. `en-US`, `en-GB`) is treated as a match. This is a relaxation of the
+ * strict lookup algorithm but typically reflects user intent — a user who
+ * asked for `en-CA` will usually accept `en-US` over a non-English fallback.
+ *
+ * Tags that fail to parse are skipped with a console warning; they never match
+ * and never throw.
+ *
+ * @param requested - The locale the caller would like to use, or `null`/`undefined`
+ *   if no preference is known.
+ * @param available - The list of locales the application supports.
+ * @param fallback - The value to return when no match is found. Defaults to
+ *   `undefined`.
+ * @returns The matched locale from `available`, or `fallback` if nothing matches.
+ *
+ * @example
+ * matchLocale('en-CA', ['en-US', 'en-GB', 'fr-FR'], 'en-US'); // => 'en-US'
+ * matchLocale('fr-BE', ['en-US', 'fr-FR', 'de-DE'], 'en-US'); // => 'fr-FR'
+ * matchLocale('zh-Hant-TW', ['zh-Hant', 'zh-Hans', 'en'], 'en'); // => 'zh-Hant'
+ */ export function matchLocale(requested, available, fallback) {
+    if (requested == null) {
+        return fallback;
+    }
+    const requestedCanonical = canonicalize(requested);
+    if (!requestedCanonical) {
+        console.warn(`matchLocale: invalid requested locale tag: ${JSON.stringify(requested)}`);
+        return fallback;
+    }
+    const pool = [];
+    for (const entry of available){
+        const canonical = canonicalize(entry);
+        if (!canonical) {
+            console.warn(`matchLocale: skipping invalid available locale tag: ${JSON.stringify(entry)}`);
+            continue;
+        }
+        pool.push({
+            canonical,
+            original: entry
+        });
+    }
+    let candidate = requestedCanonical;
+    while(candidate){
+        const exact = pool.find((p)=>p.canonical === candidate);
+        if (exact) {
+            return exact.original;
+        }
+        const prefix = candidate + '-';
+        const prefixed = pool.find((p)=>p.canonical.startsWith(prefix));
+        if (prefixed) {
+            return prefixed.original;
+        }
+        // Once the truncation chain has exhausted every `ht` option, retry the
+        // lookup with `fr-HT`. This mirrors the `ht` → `fr-HT` workaround in
+        // `get-locale.ts`: Haitian Creole content is typically registered under
+        // `fr-HT` because of incomplete browser Intl support for `ht`, so a caller
+        // asking for `ht` needs to find it there.
+        if (candidate === 'ht') {
+            candidate = 'fr-HT';
+            continue;
+        }
+        // RFC 4647 §3.4 step 4: strip the trailing subtag.
+        const lastDash = candidate.lastIndexOf('-');
+        if (lastDash === -1) {
+            break;
+        }
+        candidate = candidate.slice(0, lastDash);
+        // RFC 4647 §3.4 step 5: a trailing single-letter subtag is an extension
+        // singleton (e.g. `-x-` for private use, `-u-` for Unicode extensions) and
+        // is not meaningful on its own, so strip it together with its separator.
+        const tailDash = candidate.lastIndexOf('-');
+        if (tailDash !== -1 && candidate.length - tailDash === 2) {
+            candidate = candidate.slice(0, tailDash);
+        }
+    }
+    return fallback;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-utils",
-  "version": "9.0.3-pre.4715",
+  "version": "9.0.3-pre.4735",
   "license": "MPL-2.0",
   "description": "Helper utilities for OpenMRS",
   "type": "module",
@@ -63,7 +63,7 @@
     "rxjs": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-globals": "9.0.3-pre.4715",
+    "@openmrs/esm-globals": "9.0.3-pre.4735",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@types/lodash-es": "^4.17.12",

package/src/get-locale.ts

@@ -4,7 +4,7 @@
  */
 export function getLocale() {
   let language = window.i18next.language;
-  language = language.replace('_', '-'); // just in case
+  language = language.replaceAll('_', '-'); // just in case
   // Hack for `ht` until all browsers update their unicode support with ht to fr mapping.
   // See https://unicode-org.atlassian.net/browse/CLDR-14956
   if (language === 'ht') {

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './age-helpers';
 export * from './dates';
 export * from './get-locale';
 export * from './is-online';
+export * from './match-locale';
 export * from './patient-helpers';
 export * from './shallowEqual';
 export * from './storage';

package/src/match-locale.test.ts

@@ -0,0 +1,180 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { matchLocale } from './match-locale';
+
+describe('matchLocale', () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  describe('examples from the spec', () => {
+    it('falls back to en-US when en-CA is requested but only other English variants exist', () => {
+      expect(matchLocale('en-CA', ['en-US', 'en-GB', 'fr-FR'], 'en-US')).toBe('en-US');
+    });
+
+    it('matches the language family when the region differs', () => {
+      expect(matchLocale('fr-BE', ['en-US', 'fr-FR', 'de-DE'], 'en-US')).toBe('fr-FR');
+    });
+
+    it('truncates a script subtag to find a script-only match', () => {
+      expect(matchLocale('zh-Hant-TW', ['zh-Hant', 'zh-Hans', 'en'], 'en')).toBe('zh-Hant');
+    });
+  });
+
+  describe('exact matching', () => {
+    it('returns the exact match when one is present', () => {
+      expect(matchLocale('en-US', ['fr-FR', 'en-US', 'de-DE'], 'fr-FR')).toBe('en-US');
+    });
+
+    it('returns the original casing from `available`, not the canonical form', () => {
+      expect(matchLocale('en-us', ['en-US'])).toBe('en-US');
+      expect(matchLocale('EN-US', ['en-us'])).toBe('en-us');
+    });
+
+    it('matches the first occurrence when an available locale appears multiple times', () => {
+      expect(matchLocale('en', ['en', 'en-US', 'en'])).toBe('en');
+    });
+  });
+
+  describe('canonicalization', () => {
+    it('treats underscore-separated tags as equivalent to hyphen-separated tags', () => {
+      expect(matchLocale('en_GB', ['en-GB'])).toBe('en-GB');
+      expect(matchLocale('en-GB', ['en_GB'])).toBe('en_GB');
+    });
+
+    it('is case-insensitive across language, script, and region subtags', () => {
+      expect(matchLocale('ZH-hant-tw', ['zh-Hant'])).toBe('zh-Hant');
+    });
+
+    it('canonicalizes script casing for matching (Latn vs latn)', () => {
+      expect(matchLocale('sr-latn-rs', ['sr-Latn'])).toBe('sr-Latn');
+    });
+  });
+
+  describe('truncation', () => {
+    it('strips a region subtag to match a language-only available locale', () => {
+      expect(matchLocale('en-CA', ['en'])).toBe('en');
+    });
+
+    it('strips a region from a script+region tag, leaving the script', () => {
+      expect(matchLocale('zh-Hant-TW', ['zh-Hant'])).toBe('zh-Hant');
+    });
+
+    it('strips a single-letter extension singleton along with its trailing subtag', () => {
+      // `en-US-x-private` → `en-US-x` → strip singleton → `en-US` → `en`.
+      expect(matchLocale('en-US-x-private', ['en'])).toBe('en');
+    });
+  });
+
+  describe('prefix expansion', () => {
+    it('expands a language-only request to a regional variant', () => {
+      expect(matchLocale('en', ['en-US', 'en-GB'])).toBe('en-US');
+    });
+
+    it('falls through truncation steps before expanding', () => {
+      // `fr-BE` → no exact, no `fr-BE-…` prefix → truncate to `fr` →
+      // no exact `fr` → expand to `fr-FR`.
+      expect(matchLocale('fr-BE', ['fr-FR'])).toBe('fr-FR');
+    });
+
+    it('does not match across language families', () => {
+      expect(matchLocale('fr-BE', ['en-US', 'de-DE'], 'en-US')).toBe('en-US');
+    });
+  });
+
+  describe('fallback handling', () => {
+    it('returns the fallback when no match is found', () => {
+      expect(matchLocale('ja', ['en-US', 'fr-FR'], 'en-US')).toBe('en-US');
+    });
+
+    it('returns undefined when no fallback is provided and no match is found', () => {
+      expect(matchLocale('ja', ['en-US', 'fr-FR'], undefined)).toBeUndefined();
+    });
+
+    it('returns the fallback when `available` is empty', () => {
+      expect(matchLocale('en-US', [], 'fallback-tag')).toBe('fallback-tag');
+    });
+
+    it('returns the fallback when `requested` is null', () => {
+      expect(matchLocale(null, ['en-US'], 'en-US')).toBe('en-US');
+    });
+
+    it('returns the fallback when `requested` is undefined', () => {
+      expect(matchLocale(undefined, ['en-US'], 'en-US')).toBe('en-US');
+    });
+  });
+
+  describe('ht → fr-HT fallback', () => {
+    it('falls back to fr-HT when `ht` is requested and no Haitian Creole locale is available', () => {
+      expect(matchLocale('ht', ['fr-HT', 'en-US'])).toBe('fr-HT');
+    });
+
+    it('falls back from `ht-HT` to `fr-HT`', () => {
+      expect(matchLocale('ht-HT', ['fr-HT', 'en-US'])).toBe('fr-HT');
+    });
+
+    it('falls back from `ht-Latn-HT` to `fr-HT`', () => {
+      expect(matchLocale('ht-Latn-HT', ['fr-HT', 'en-US'])).toBe('fr-HT');
+    });
+
+    it('continues truncating to plain `fr` when `fr-HT` is not available', () => {
+      expect(matchLocale('ht', ['fr', 'en-US'])).toBe('fr');
+    });
+
+    it('expands the post-remap `fr-HT` candidate to any available `fr-*` variant', () => {
+      // Truncate `ht` → remap to `fr-HT` → no exact `fr-HT` and no `fr-HT-…` →
+      // truncate to `fr` → no exact `fr`, but prefix `fr-` matches `fr-FR`.
+      expect(matchLocale('ht', ['fr-FR'])).toBe('fr-FR');
+    });
+
+    it('prefers an available `ht` locale over the French fallback', () => {
+      expect(matchLocale('ht', ['ht', 'fr-HT'])).toBe('ht');
+    });
+
+    it('prefers an available `ht-HT` locale over the French fallback', () => {
+      expect(matchLocale('ht-HT', ['ht-HT', 'fr-HT'])).toBe('ht-HT');
+    });
+
+    it('uses the `ht` prefix expansion before falling back to French', () => {
+      // Requested `ht-Latn-HT` truncates to `ht`; prefix expansion finds `ht-HT`
+      // before the loop ever sees the `ht` → `fr-HT` remap.
+      expect(matchLocale('ht-Latn-HT', ['ht-HT', 'fr-HT'])).toBe('ht-HT');
+    });
+
+    it('returns the fallback when neither Haitian Creole nor French is available', () => {
+      expect(matchLocale('ht-HT', ['en-US', 'de-DE'], 'en-US')).toBe('en-US');
+    });
+  });
+
+  describe('invalid input', () => {
+    it('returns the fallback and warns when `requested` is not a valid tag', () => {
+      expect(matchLocale('not a locale', ['en-US'], 'en-US')).toBe('en-US');
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('invalid requested locale tag'));
+    });
+
+    it('returns the fallback and warns when `requested` is an empty string', () => {
+      expect(matchLocale('', ['en-US'], 'en-US')).toBe('en-US');
+      expect(warnSpy).toHaveBeenCalled();
+    });
+
+    it('skips invalid entries in `available` and warns about each', () => {
+      expect(matchLocale('en-US', ['not-a-locale!', 'en-US'])).toBe('en-US');
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('invalid available locale tag'));
+    });
+
+    it('still returns the fallback when every available entry is invalid', () => {
+      expect(matchLocale('en-US', ['!!!', '@@@'], 'fallback')).toBe('fallback');
+      expect(warnSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not warn when all inputs are valid', () => {
+      matchLocale('en-US', ['en-US']);
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/match-locale.ts

@@ -0,0 +1,118 @@
+/**
+ * Returns a canonical BCP 47 representation of `tag`, or `undefined` if it is not a
+ * structurally valid tag. Underscores are accepted as a separator and normalized to
+ * hyphens before canonicalization to accommodate locale strings that originate from
+ * Java-style identifiers (e.g. `en_GB`).
+ */
+function canonicalize(tag: string): string | undefined {
+  if (typeof tag !== 'string' || tag.trim().length === 0) {
+    return undefined;
+  }
+
+  const normalized = tag.replaceAll('_', '-');
+
+  try {
+    return new Intl.Locale(normalized).toString();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolves a requested locale against a list of available locales using the
+ * BCP 47 lookup algorithm (RFC 4647, §3.4).
+ *
+ * Tags are compared in canonical form via {@link Intl.Locale}, so casing and
+ * underscore-vs-hyphen differences in the inputs do not affect matching. The
+ * value returned is taken verbatim from `available`, preserving the caller's
+ * original casing.
+ *
+ * In addition to the truncation steps prescribed by RFC 4647, this function
+ * also performs prefix expansion at each level: when the requested tag is
+ * truncated to a more general range (e.g. `en` after stripping `en-CA`), any
+ * available locale whose canonical form begins with that range plus a hyphen
+ * (e.g. `en-US`, `en-GB`) is treated as a match. This is a relaxation of the
+ * strict lookup algorithm but typically reflects user intent — a user who
+ * asked for `en-CA` will usually accept `en-US` over a non-English fallback.
+ *
+ * Tags that fail to parse are skipped with a console warning; they never match
+ * and never throw.
+ *
+ * @param requested - The locale the caller would like to use, or `null`/`undefined`
+ *   if no preference is known.
+ * @param available - The list of locales the application supports.
+ * @param fallback - The value to return when no match is found. Defaults to
+ *   `undefined`.
+ * @returns The matched locale from `available`, or `fallback` if nothing matches.
+ *
+ * @example
+ * matchLocale('en-CA', ['en-US', 'en-GB', 'fr-FR'], 'en-US'); // => 'en-US'
+ * matchLocale('fr-BE', ['en-US', 'fr-FR', 'de-DE'], 'en-US'); // => 'fr-FR'
+ * matchLocale('zh-Hant-TW', ['zh-Hant', 'zh-Hans', 'en'], 'en'); // => 'zh-Hant'
+ */
+export function matchLocale(
+  requested: string | null | undefined,
+  available: ReadonlyArray<string>,
+  fallback?: string,
+): string | undefined {
+  if (requested == null) {
+    return fallback;
+  }
+
+  const requestedCanonical = canonicalize(requested);
+  if (!requestedCanonical) {
+    console.warn(`matchLocale: invalid requested locale tag: ${JSON.stringify(requested)}`);
+    return fallback;
+  }
+
+  const pool: Array<{ canonical: string; original: string }> = [];
+  for (const entry of available) {
+    const canonical = canonicalize(entry);
+    if (!canonical) {
+      console.warn(`matchLocale: skipping invalid available locale tag: ${JSON.stringify(entry)}`);
+      continue;
+    }
+    pool.push({ canonical, original: entry });
+  }
+
+  let candidate = requestedCanonical;
+  while (candidate) {
+    const exact = pool.find((p) => p.canonical === candidate);
+    if (exact) {
+      return exact.original;
+    }
+
+    const prefix = candidate + '-';
+    const prefixed = pool.find((p) => p.canonical.startsWith(prefix));
+    if (prefixed) {
+      return prefixed.original;
+    }
+
+    // Once the truncation chain has exhausted every `ht` option, retry the
+    // lookup with `fr-HT`. This mirrors the `ht` → `fr-HT` workaround in
+    // `get-locale.ts`: Haitian Creole content is typically registered under
+    // `fr-HT` because of incomplete browser Intl support for `ht`, so a caller
+    // asking for `ht` needs to find it there.
+    if (candidate === 'ht') {
+      candidate = 'fr-HT';
+      continue;
+    }
+
+    // RFC 4647 §3.4 step 4: strip the trailing subtag.
+    const lastDash = candidate.lastIndexOf('-');
+    if (lastDash === -1) {
+      break;
+    }
+    candidate = candidate.slice(0, lastDash);
+
+    // RFC 4647 §3.4 step 5: a trailing single-letter subtag is an extension
+    // singleton (e.g. `-x-` for private use, `-u-` for Unicode extensions) and
+    // is not meaningful on its own, so strip it together with its separator.
+    const tailDash = candidate.lastIndexOf('-');
+    if (tailDash !== -1 && candidate.length - tailDash === 2) {
+      candidate = candidate.slice(0, tailDash);
+    }
+  }
+
+  return fallback;
+}