resolve-accept-language 2.1.17 → 2.1.19

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2021 Avansai
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2021 Avansai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,105 +1,105 @@
-# resolve-accept-language
-
-[![License](https://img.shields.io/npm/l/make-coverage-badge.svg?color=brightgreen)](https://opensource.org/licenses/MIT)
-[![npm download](https://img.shields.io/npm/dw/resolve-accept-language.svg?color=brightgreen)](https://www.npmjs.com/package/resolve-accept-language)
-![Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)
-![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)
-
-Resolve the best locale based on the value of an `Accept-Language` HTTP header.
-
-## Usage
-
-Add the package as a dependency:
-
-```
-npm install resolve-accept-language
-```
-
-Code example:
-
-```ts
-import resolveAcceptLanguage from 'resolve-accept-language'
-
-/**
- * The API is well documented from within your IDE using TSDoc. The arguments are as follows:
- *
- * 1) The HTTP accept-language header.
- * 2) The available locales (they must contain the default locale).
- * 3) The default locale.
- */
-console.log(
-  resolveAcceptLanguage(
-    'fr-CA;q=0.01,en-CA;q=0.1,en-US;q=0.001',
-    // The `as const` is optional for TypeScript but gives better typing.
-    ['en-US', 'fr-CA'] as const,
-    'en-US'
-  )
-)
-```
-
-Output:
-
-```
-fr-CA
-```
-
-## Advanced use cases
-
-You may want to control exactly the behavior depending on the type of match. For example, you could want to display a language picker on your home page if the match is not satisfactory. In those cases, you will need to use the `ResolveAcceptLanguage` class instead. It offers more visibility into the selection process while matching a locale:
-
-```ts
-import { MATCH_TYPES, ResolveAcceptLanguage } from 'resolve-accept-language'
-
-const resolveAcceptLanguage = new ResolveAcceptLanguage(
-  'fr-CA;q=0.01,en-CA;q=0.1,en-US;q=0.001' as const,
-  ['en-US', 'fr-CA'],
-  'fr-CA'
-)
-
-console.log(`A locale was matched: ${resolveAcceptLanguage.getMatch()}`)
-
-if (resolveAcceptLanguage.getMatchType() === MATCH_TYPES.localeBased) {
-  console.log('The match is locale-based')
-} else if (resolveAcceptLanguage.getMatchType() === MATCH_TYPES.languageBased) {
-  console.log('The match is language-based')
-} else if (resolveAcceptLanguage.getMatchType() === MATCH_TYPES.relatedLocaleBased) {
-  console.log('The match is related-locale-based')
-} else if (resolveAcceptLanguage.getMatchType() === MATCH_TYPES.defaultLocale) {
-  console.log('The match is the default locale')
-}
-```
-
-## How does the resolver work?
-
-As per RFC 4647, this package uses the "lookup" matching scheme. This means that it will always produce exactly one match for a given request.
-
-The matching strategy will use the following logic:
-
-1. The default locale (when provided) will always be put as the first locale being evaluated since it is considered the highest quality content available. Otherwise, the locales will be evaluated in the order provided, where the first is the highest quality and the last the lowest.
-2. All locales and languages are extracted from the HTTP header and sorted by quality factor. Locales and languages that are in the HTTP header but not in scope are discarded.
-3. Three different matching patterns (based on the HTTP header's quality factor and order of the provided locales):
-   1. If there were any matches, get the highest-ranked (quality factor) locale or language code:
-      1. **Locale-based match**: Is the highest-ranked a locale? If yes, this is the best match.
-      2. **Language-based match**: Otherwise, find the first locale that matches the highest-ranked language.
-   2. **Related-locale-based match**: If there is no match, find the first locale with a language that matches the highest-ranked language of locales that were not in scope. This is a bit of a "fuzzy match", but the presumption is that it's better to show content in a language that can be understood even if the country is wrong.
-4. When using `resolveAcceptLanguage` return the default locale as a last resort option.
-
-## Why another `Accept-Language` package?
-
-The `Accept-Language` header has been around since 1999. Like many other standards that deal with languages, the header is based
-on BCP 47 language tags. Language tags can be as simple as `fr` (non-country specific French) or more complex, for example,
-`sr-Latn-RS` would represent Latin script Serbian.
-
-One of the main challenges is that BCP 47 language tags can be either overly simple or too complex. This is one of the problems this
-library will try to address by focusing on locales identifiers using the `language`-`country` format instead of trying to provide
-full BCP 47 language tags support. The main reasons for this:
-
-- Using 2 letter language codes is rarely sufficient. Without being explicit about the targeted country for a given language, it is impossible to provide the right format for some content such as dates and numbers. Also, while languages are similar across countries, there are different ways to say the same thing. Our hypothesis is that by better targeting the audience, the user experience will improve.
-- About 99% of all cases can be covered using the `language`-`country` format. We could possibly extend script support in the future given a valid use case, but in the meantime, our goal is to keep this library as simple as possible, while providing the best matches.
-
-## Additional references
-
-- Matching of Language Tags ([RFC 4647](https://tools.ietf.org/html/rfc4647))
-- Tags for Identifying Languages ([RFC 4646](https://tools.ietf.org/html/rfc4646))
-- The Accept-Language request-header field ([RFC 2616 section 14.4](https://tools.ietf.org/html/rfc2616#section-14.4))
-- Quality values ([RFC 2616 section 3.9](https://tools.ietf.org/html/rfc2616#section-3.9))
+# resolve-accept-language
+
+[![License](https://img.shields.io/npm/l/make-coverage-badge.svg?color=brightgreen)](https://opensource.org/licenses/MIT)
+[![npm download](https://img.shields.io/npm/dw/resolve-accept-language.svg?color=brightgreen)](https://www.npmjs.com/package/resolve-accept-language)
+![Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)
+
+Resolve the best locale based on the value of an `Accept-Language` HTTP header.
+
+## Usage
+
+Add the package as a dependency:
+
+```
+npm install resolve-accept-language
+```
+
+Code example:
+
+```ts
+import resolveAcceptLanguage from 'resolve-accept-language'
+
+/**
+ * The API is well documented from within your IDE using TSDoc. The arguments are as follows:
+ *
+ * 1) The HTTP accept-language header.
+ * 2) The available locales (they must contain the default locale).
+ * 3) The default locale.
+ */
+console.log(
+  resolveAcceptLanguage(
+    'fr-CA;q=0.01,en-CA;q=0.1,en-US;q=0.001',
+    // The `as const` is optional for TypeScript but gives better typing.
+    ['en-US', 'fr-CA'] as const,
+    'en-US'
+  )
+)
+```
+
+Output:
+
+```
+fr-CA
+```
+
+## Advanced use cases
+
+You may want to control exactly the behavior depending on the type of match. For example, you could want to display a language picker on your home page if the match is not satisfactory. In those cases, you will need to use the `ResolveAcceptLanguage` class instead. It offers more visibility into the selection process while matching a locale:
+
+```ts
+import { MATCH_TYPES, ResolveAcceptLanguage } from 'resolve-accept-language'
+
+const resolveAcceptLanguage = new ResolveAcceptLanguage(
+  'fr-CA;q=0.01,en-CA;q=0.1,en-US;q=0.001' as const,
+  ['en-US', 'fr-CA'],
+  'fr-CA'
+)
+
+console.log(`A locale was matched: ${resolveAcceptLanguage.getMatch()}`)
+
+if (resolveAcceptLanguage.getMatchType() === MATCH_TYPES.localeBased) {
+  console.log('The match is locale-based')
+} else if (resolveAcceptLanguage.getMatchType() === MATCH_TYPES.languageBased) {
+  console.log('The match is language-based')
+} else if (resolveAcceptLanguage.getMatchType() === MATCH_TYPES.relatedLocaleBased) {
+  console.log('The match is related-locale-based')
+} else if (resolveAcceptLanguage.getMatchType() === MATCH_TYPES.defaultLocale) {
+  console.log('The match is the default locale')
+}
+```
+
+## How does the resolver work?
+
+As per RFC 4647, this package uses the "lookup" matching scheme. This means that it will always produce exactly one match for a given request.
+
+The matching strategy will use the following logic:
+
+1. The default locale (when provided) will always be put as the first locale being evaluated since it is considered the highest quality content available. Otherwise, the locales will be evaluated in the order provided, where the first is the highest quality and the last the lowest.
+2. All locales and languages are extracted from the HTTP header and sorted by quality factor. Locales and languages that are in the HTTP header but not in scope are discarded.
+3. Three different matching patterns (based on the HTTP header's quality factor and order of the provided locales):
+   1. If there were any matches, get the highest-ranked (quality factor) locale or language code:
+      1. **Locale-based match**: Is the highest-ranked a locale? If yes, this is the best match.
+      2. **Language-based match**: Otherwise, find the first locale that matches the highest-ranked language.
+   2. **Related-locale-based match**: If there is no match, find the first locale with a language that matches the highest-ranked language of locales that were not in scope. This is a bit of a "fuzzy match", but the presumption is that it's better to show content in a language that can be understood even if the country is wrong.
+4. When using `resolveAcceptLanguage` return the default locale as a last resort option.
+
+## Why another `Accept-Language` package?
+
+The `Accept-Language` header has been around since 1999. Like many other standards that deal with languages, the header is based
+on BCP 47 language tags. Language tags can be as simple as `fr` (non-country specific French) or more complex, for example,
+`sr-Latn-RS` would represent Latin script Serbian.
+
+One of the main challenges is that BCP 47 language tags can be either overly simple or too complex. This is one of the problems this
+library will try to address by focusing on locales identifiers using the `language`-`country` format instead of trying to provide
+full BCP 47 language tags support. The main reasons for this:
+
+- Using 2 letter language codes is rarely sufficient. Without being explicit about the targeted country for a given language, it is impossible to provide the right format for some content such as dates and numbers. Also, while languages are similar across countries, there are different ways to say the same thing. Our hypothesis is that by better targeting the audience, the user experience will improve.
+- About 99% of all cases can be covered using the `language`-`country` format. We could possibly extend script support in the future given a valid use case, but in the meantime, our goal is to keep this library as simple as possible, while providing the best matches.
+
+## Additional references
+
+- Matching of Language Tags ([RFC 4647](https://tools.ietf.org/html/rfc4647))
+- Tags for Identifying Languages ([RFC 4646](https://tools.ietf.org/html/rfc4646))
+- The Accept-Language request-header field ([RFC 2616 section 14.4](https://tools.ietf.org/html/rfc2616#section-14.4))
+- Quality values ([RFC 2616 section 3.9](https://tools.ietf.org/html/rfc2616#section-3.9))

package/lib/esm/locale-list.d.ts

@@ -0,0 +1,19 @@
+import Locale from './locale';
+export default class LocaleList<TLocales extends readonly string[]> {
+    /** A set of ISO 3166-1 alpha-2 country codes. */
+    readonly countries: Set<string>;
+    /** A set of ISO 639-1 alpha-2 language codes. */
+    readonly languages: Set<string>;
+    /** A set of locale identifiers using the BCP 47 `language`-`country` case-normalized format. */
+    readonly locales: Set<string>;
+    /** A list of locale objects. */
+    readonly objects: Locale[];
+    /**
+     * Create a list of locale identifiers.
+     *
+     * @param locales - An array of locale identifiers using the BCP 47 `language`-`country` format.
+     *
+     * @throws Will throw an error if one of the locale's format is invalid.
+     */
+    constructor(locales: TLocales extends string[] ? TLocales[number][] : TLocales);
+}

package/lib/esm/locale-list.js

@@ -0,0 +1,32 @@
+import Locale from './locale';
+var LocaleList = /** @class */ (function () {
+    /**
+     * Create a list of locale identifiers.
+     *
+     * @param locales - An array of locale identifiers using the BCP 47 `language`-`country` format.
+     *
+     * @throws Will throw an error if one of the locale's format is invalid.
+     */
+    function LocaleList(locales) {
+        var _this = this;
+        /** A set of ISO 3166-1 alpha-2 country codes. */
+        this.countries = new Set();
+        /** A set of ISO 639-1 alpha-2 language codes. */
+        this.languages = new Set();
+        /** A set of locale identifiers using the BCP 47 `language`-`country` case-normalized format. */
+        this.locales = new Set();
+        /** A list of locale objects. */
+        this.objects = [];
+        locales.forEach(function (locale) {
+            var localeObject = new Locale(locale);
+            if (!_this.locales.has(localeObject.identifier)) {
+                _this.objects.push(localeObject);
+                _this.locales.add(localeObject.identifier);
+                _this.languages.add(localeObject.languageCode);
+                _this.countries.add(localeObject.countryCode);
+            }
+        });
+    }
+    return LocaleList;
+}());
+export default LocaleList;

package/lib/esm/locale.d.ts

@@ -0,0 +1,39 @@
+import { NormalizeLocale } from './resolve-accept-language';
+/** Class to manage a locale identifier using the BCP 47 `language`-`country` format. */
+export default class Locale<TLocale extends string = string> {
+    /** The ISO 3166-1 alpha-2 country code. */
+    readonly countryCode: string;
+    /** The locale identifier using the BCP 47 `language`-`country` case-normalized format. */
+    readonly identifier: NormalizeLocale<TLocale>;
+    /** The ISO 639-1 alpha-2 language code. */
+    readonly languageCode: string;
+    /**
+     * Create a new `Locale` object.
+     *
+     * @param identifier - A locale identifier using the BCP 47 `language`-`country` format (case insensitive).
+     *
+     * @throws An error if the `identifier` format is invalid.
+     */
+    constructor(identifier: string);
+    /**
+     * Is a given string an ISO 3166-1 alpha-2 country code.
+     *
+     * @param countryCode - An ISO 3166-1 alpha-2 country code.
+     * @param caseNormalized - Should we verify if the identifier is using the case-normalized format?
+     */
+    static isCountryCode(countryCode: string, caseNormalized?: boolean): boolean;
+    /**
+     * Is a given string an ISO 639-1 alpha-2 language code.
+     *
+     * @param languageCode - An ISO 639-1 alpha-2 language code.
+     * @param caseNormalized - Should we verify if the identifier is using the case-normalized format?
+     */
+    static isLanguageCode(languageCode: string, caseNormalized?: boolean): boolean;
+    /**
+     * Is a given string a locale identifier following the BCP 47 `language`-`country` format.
+     *
+     * @param identifier - A potential locale identify to verify.
+     * @param caseNormalized - Should we verify if the identifier is using the case-normalized format?
+     */
+    static isLocale(identifier: string, caseNormalized?: boolean): boolean;
+}

package/lib/esm/locale.js

@@ -0,0 +1,54 @@
+/** Class to manage a locale identifier using the BCP 47 `language`-`country` format. */
+var Locale = /** @class */ (function () {
+    /**
+     * Create a new `Locale` object.
+     *
+     * @param identifier - A locale identifier using the BCP 47 `language`-`country` format (case insensitive).
+     *
+     * @throws An error if the `identifier` format is invalid.
+     */
+    function Locale(identifier) {
+        if (!Locale.isLocale(identifier, false)) {
+            throw new Error("invalid locale identifier '".concat(identifier, "'"));
+        }
+        var _a = identifier.split('-'), languageCode = _a[0], countryCode = _a[1];
+        this.languageCode = languageCode.toLowerCase();
+        this.countryCode = countryCode.toUpperCase();
+        this.identifier = "".concat(this.languageCode, "-").concat(this.countryCode);
+    }
+    /**
+     * Is a given string an ISO 3166-1 alpha-2 country code.
+     *
+     * @param countryCode - An ISO 3166-1 alpha-2 country code.
+     * @param caseNormalized - Should we verify if the identifier is using the case-normalized format?
+     */
+    Locale.isCountryCode = function (countryCode, caseNormalized) {
+        if (caseNormalized === void 0) { caseNormalized = true; }
+        var regExp = new RegExp(/^[A-Z]{2}$/, caseNormalized ? undefined : 'i');
+        return regExp.test(countryCode);
+    };
+    /**
+     * Is a given string an ISO 639-1 alpha-2 language code.
+     *
+     * @param languageCode - An ISO 639-1 alpha-2 language code.
+     * @param caseNormalized - Should we verify if the identifier is using the case-normalized format?
+     */
+    Locale.isLanguageCode = function (languageCode, caseNormalized) {
+        if (caseNormalized === void 0) { caseNormalized = true; }
+        var regExp = new RegExp(/^[a-z]{2}$/, caseNormalized ? undefined : 'i');
+        return regExp.test(languageCode);
+    };
+    /**
+     * Is a given string a locale identifier following the BCP 47 `language`-`country` format.
+     *
+     * @param identifier - A potential locale identify to verify.
+     * @param caseNormalized - Should we verify if the identifier is using the case-normalized format?
+     */
+    Locale.isLocale = function (identifier, caseNormalized) {
+        if (caseNormalized === void 0) { caseNormalized = true; }
+        var regExp = new RegExp(/^[a-z]{2}-[A-Z]{2}$/, caseNormalized ? undefined : 'i');
+        return regExp.test(identifier);
+    };
+    return Locale;
+}());
+export default Locale;

package/lib/esm/lookup-list.d.ts

@@ -0,0 +1,79 @@
+import { NormalizeLocale } from './resolve-accept-language';
+/** Lookup list used to match the preferred locale based on the value of an `Accept-Language` HTTP header. */
+export default class LookupList<TLocales extends readonly string[]> {
+    /** The list of locales used to get the match during the lookup. */
+    private localeList;
+    /**
+     * Data object where the properties are quality (in string format) and their values a set containing locale
+     * identifiers using the `language`-`country` format and ISO 639-1 alpha-2 language code.
+     */
+    private localesAndLanguagesByQuality;
+    /**
+     * Data object where the properties are quality (in string format) and their value a set of ISO 639-1 alpha-2
+     * language code.
+     */
+    private relatedLocaleLanguagesByQuality;
+    /**
+     * Create a new `LookupList` object.
+     *
+     * @param acceptLanguageHeader - The value of an HTTP request `Accept-Language` header (also known as a "language priority list").
+     * @param locales - An array of locale identifiers. The order will be used for matching where the first identifier will be more
+     * likely to be matched than the last identifier.
+     */
+    constructor(acceptLanguageHeader: string, locales: TLocales extends string[] ? TLocales[number][] : TLocales, defaultLocale: TLocales[number]);
+    /**
+     * Get the top locale-based match if available.
+     *
+     * @returns The top locale-based match or undefined when there is no match.
+     */
+    getLocaleBasedMatch(): NormalizeLocale<TLocales[number]> | undefined;
+    /**
+     * Get the language-based match if available.
+     *
+     * @returns The language-based match or undefined when there is no match.
+     */
+    getLanguageBasedMatch(): NormalizeLocale<TLocales[number]> | undefined;
+    /**
+     * Get the related-locale-based match if available.
+     *
+     * @returns The related-locale-based match or undefined when there is no match.
+     */
+    getRelatedLocaleBasedMatch(): NormalizeLocale<TLocales[number]> | undefined;
+    /**
+     * Add a language in the data object matching its quality.
+     *
+     * @param quality - The HTTP header's quality factor associated with a language.
+     * @param languageCode - An ISO 639-1 alpha-2 language code.
+     */
+    private addLanguage;
+    /**
+     * Add a locale in the data object matching its quality.
+     *
+     * @param quality - The HTTP header's quality factor associated with a locale.
+     * @param identifier - A locale identifier using the BCP 47 `language`-`country` case-normalized format.
+     */
+    private addLocale;
+    /**
+     * Add a related locale's language in the data object matching its quality.
+     *
+     * @param quality - The HTTP header's quality factor associated with a related locale's language.
+     * @param languageCode - An ISO 639-1 alpha-2 language code.
+     */
+    private addRelatedLocaleLanguage;
+    /**
+     * Get a directive object from a directive string.
+     *
+     * @param directiveString - The string representing a directive, extracted from the HTTP header.
+     *
+     * @returns A `Directive` object or `undefined` if the string's format is invalid.
+     */
+    private getDirective;
+    /**
+     * Get a match from a data object.
+     *
+     * @param dataObject - A data object.
+     *
+     * @returns A match or undefined when there is no match.
+     */
+    private getMatch;
+}

package/lib/esm/lookup-list.js

@@ -0,0 +1,207 @@
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+import Locale from './locale';
+import LocaleList from './locale-list';
+/** Lookup list used to match the preferred locale based on the value of an `Accept-Language` HTTP header. */
+var LookupList = /** @class */ (function () {
+    /**
+     * Create a new `LookupList` object.
+     *
+     * @param acceptLanguageHeader - The value of an HTTP request `Accept-Language` header (also known as a "language priority list").
+     * @param locales - An array of locale identifiers. The order will be used for matching where the first identifier will be more
+     * likely to be matched than the last identifier.
+     */
+    function LookupList(acceptLanguageHeader, locales, defaultLocale) {
+        var _this = this;
+        /**
+         * Data object where the properties are quality (in string format) and their values a set containing locale
+         * identifiers using the `language`-`country` format and ISO 639-1 alpha-2 language code.
+         */
+        this.localesAndLanguagesByQuality = {};
+        /**
+         * Data object where the properties are quality (in string format) and their value a set of ISO 639-1 alpha-2
+         * language code.
+         */
+        this.relatedLocaleLanguagesByQuality = {};
+        // Put the default locale first so that it will be more likely to be matched.
+        this.localeList = new LocaleList(__spreadArray([
+            defaultLocale
+        ], locales.filter(function (locale) { return locale !== defaultLocale; }), true));
+        var directives = acceptLanguageHeader
+            .split(',')
+            .map(function (directiveString) { return _this.getDirective(directiveString.trim()); })
+            .filter(function (directive) { return directive !== undefined; });
+        // Check if 'es-419' exists in the directives
+        var es419DirectiveIndex = directives.findIndex(function (directive) { return directive.locale === 'es-419'; });
+        if (es419DirectiveIndex >= 0) {
+            // Remove 'es-419' from the directive.
+            var es419Directive_1 = directives[es419DirectiveIndex];
+            directives.splice(es419DirectiveIndex, 1);
+            // Replace `es-419` by the common Latin American spanish variants supported by browsers.
+            var latinAmericanLocales = [
+                'es-AR', // Spanish Argentina
+                'es-CL', // Spanish Chile
+                'es-CO', // Spanish Colombia
+                'es-CR', // Spanish Costa Rica
+                'es-HN', // Spanish Honduras
+                'es-MX', // Spanish Mexico
+                'es-PE', // Spanish Peru
+                'es-US', // Spanish United States
+                'es-UY', // Spanish Uruguay
+                'es-VE', // Spanish Venezuela
+            ];
+            latinAmericanLocales.forEach(function (locale) {
+                directives.push({
+                    languageCode: 'es',
+                    locale: locale,
+                    quality: es419Directive_1.quality,
+                });
+            });
+        }
+        for (var _i = 0, directives_1 = directives; _i < directives_1.length; _i++) {
+            var directive = directives_1[_i];
+            var locale = directive.locale, languageCode = directive.languageCode, quality = directive.quality;
+            // If the language is not supported, skip to the next match.
+            if (!this.localeList.languages.has(languageCode)) {
+                continue;
+            }
+            // If there is no country code (while the language is supported), add the language preference.
+            if (!locale) {
+                this.addLanguage(quality, languageCode);
+                continue;
+            }
+            // If the locale is not supported, but the locale's language is, add to locale language preference.
+            if (!this.localeList.locales.has(locale) && this.localeList.languages.has(languageCode)) {
+                this.addRelatedLocaleLanguage(quality, languageCode);
+                continue;
+            }
+            // If the locale is supported, add the locale preference.
+            this.addLocale(quality, locale);
+        }
+    }
+    /**
+     * Get the top locale-based match if available.
+     *
+     * @returns The top locale-based match or undefined when there is no match.
+     */
+    LookupList.prototype.getLocaleBasedMatch = function () {
+        var match = this.getMatch(this.localesAndLanguagesByQuality);
+        return match && Locale.isLocale(match)
+            ? match
+            : undefined;
+    };
+    /**
+     * Get the language-based match if available.
+     *
+     * @returns The language-based match or undefined when there is no match.
+     */
+    LookupList.prototype.getLanguageBasedMatch = function () {
+        var match = this.getMatch(this.localesAndLanguagesByQuality);
+        return match && !Locale.isLocale(match)
+            ? this.localeList.objects.find(function (locale) { return locale.languageCode === match; })
+                .identifier
+            : undefined;
+    };
+    /**
+     * Get the related-locale-based match if available.
+     *
+     * @returns The related-locale-based match or undefined when there is no match.
+     */
+    LookupList.prototype.getRelatedLocaleBasedMatch = function () {
+        var match = this.getMatch(this.relatedLocaleLanguagesByQuality);
+        return match
+            ? this.localeList.objects.find(function (locale) { return locale.languageCode === match; })
+                .identifier
+            : undefined;
+    };
+    /**
+     * Add a language in the data object matching its quality.
+     *
+     * @param quality - The HTTP header's quality factor associated with a language.
+     * @param languageCode - An ISO 639-1 alpha-2 language code.
+     */
+    LookupList.prototype.addLanguage = function (quality, languageCode) {
+        if (!this.localesAndLanguagesByQuality[quality]) {
+            this.localesAndLanguagesByQuality[quality] = new Set();
+        }
+        this.localesAndLanguagesByQuality[quality].add(languageCode);
+    };
+    /**
+     * Add a locale in the data object matching its quality.
+     *
+     * @param quality - The HTTP header's quality factor associated with a locale.
+     * @param identifier - A locale identifier using the BCP 47 `language`-`country` case-normalized format.
+     */
+    LookupList.prototype.addLocale = function (quality, identifier) {
+        if (!this.localesAndLanguagesByQuality[quality]) {
+            this.localesAndLanguagesByQuality[quality] = new Set();
+        }
+        this.localesAndLanguagesByQuality[quality].add(identifier);
+    };
+    /**
+     * Add a related locale's language in the data object matching its quality.
+     *
+     * @param quality - The HTTP header's quality factor associated with a related locale's language.
+     * @param languageCode - An ISO 639-1 alpha-2 language code.
+     */
+    LookupList.prototype.addRelatedLocaleLanguage = function (quality, languageCode) {
+        if (!this.relatedLocaleLanguagesByQuality[quality]) {
+            this.relatedLocaleLanguagesByQuality[quality] = new Set();
+        }
+        this.relatedLocaleLanguagesByQuality[quality].add(languageCode);
+    };
+    /**
+     * Get a directive object from a directive string.
+     *
+     * @param directiveString - The string representing a directive, extracted from the HTTP header.
+     *
+     * @returns A `Directive` object or `undefined` if the string's format is invalid.
+     */
+    LookupList.prototype.getDirective = function (directiveString) {
+        /**
+         * The regular expression is excluding certain directives due to the inability to configure those options in modern
+         * browsers today (also those options seem unpractical):
+         *
+         * - The wildcard character "*", as per RFC 2616 (section 14.4), should match any unmatched language tag.
+         * - Language tags that starts with a wildcard (e.g., "*-CA") should match the first supported locale of a country.
+         * - A quality value equivalent to "0", as per RFC 2616 (section 3.9), should be considered as "not acceptable".
+         * - We hardcode the support for the `419` UN M49 code (as country code) representing Latin America to support `es-419`.
+         */
+        var directiveMatch = directiveString.match(/^((?<matchedLanguageCode>([a-z]{2}))(-(?<matchedCountryCode>[a-z]{2}|419))?)(;q=(?<matchedQuality>(1(\.0{0,3})?)|(0(\.\d{0,3})?)))?$/i);
+        if (!(directiveMatch === null || directiveMatch === void 0 ? void 0 : directiveMatch.groups)) {
+            return undefined; // No regular expression match.
+        }
+        var _a = directiveMatch.groups, matchedLanguageCode = _a.matchedLanguageCode, matchedCountryCode = _a.matchedCountryCode, matchedQuality = _a.matchedQuality;
+        var languageCode = matchedLanguageCode.toLowerCase();
+        var countryCode = matchedCountryCode ? matchedCountryCode.toUpperCase() : undefined;
+        // Only `es-419` is supported in browsers - if any other languages are using `419` we filter them out.
+        if (countryCode === '419' && languageCode !== 'es') {
+            return undefined;
+        }
+        var quality = matchedQuality === undefined ? '1' : Number.parseFloat(matchedQuality).toString(); // Remove trailing zeros.
+        var locale = countryCode ? "".concat(languageCode, "-").concat(countryCode) : undefined;
+        return { languageCode: languageCode, locale: locale, quality: quality };
+    };
+    /**
+     * Get a match from a data object.
+     *
+     * @param dataObject - A data object.
+     *
+     * @returns A match or undefined when there is no match.
+     */
+    LookupList.prototype.getMatch = function (dataObject) {
+        var dataObjectEntries = Object.entries(dataObject);
+        return dataObjectEntries.length === 0
+            ? undefined
+            : dataObjectEntries.sort().reverse()[0][1].values().next().value;
+    };
+    return LookupList;
+}());
+export default LookupList;

package/lib/esm/resolve-accept-language.d.ts

@@ -0,0 +1,63 @@
+/** The type matches. */
+export type MatchType = 'localeBased' | 'languageBased' | 'relatedLocaleBased' | 'defaultLocale';
+/** Match type enumeration. */
+export declare const MATCH_TYPES: {
+    readonly [K in MatchType]: K;
+};
+/** Type to normalize the locale format. */
+export type NormalizeLocale<Remainder extends string> = Remainder extends `${infer LanguageCode}-${infer CountryCode}` ? `${Lowercase<LanguageCode>}-${Uppercase<CountryCode>}` : Remainder;
+/** Resolve the preferred locale from an HTTP `Accept-Language` header. */
+export declare class ResolveAcceptLanguage<TLocales extends readonly string[] = string[]> {
+    /** The default locale. */
+    private defaultLocale;
+    /** The locale-based match, if applicable. */
+    private localeBasedMatch;
+    /** The language-based match, if applicable. */
+    private languageBasedMatch;
+    /** The related-locale-based match, if applicable. */
+    private relatedLocaleBasedMatch;
+    /**
+     * Create a new `ResolveAcceptLanguage` object.
+     *
+     * All locale identifiers provided as parameters must following the BCP 47 `language`-`country` (case insensitive).
+     *
+     * @param acceptLanguageHeader - The value of an HTTP request `Accept-Language` header (also known as a "language priority list").
+     * @param locales - An array of locale identifiers. The order will be used for matching where the first identifier will be more
+     * likely to be matched than the last identifier.
+     */
+    constructor(acceptLanguageHeader: string, locales: TLocales extends string[] ? TLocales[number][] : TLocales, defaultLocale: TLocales[number]);
+    /**
+     * Get the type of match.
+     *
+     * @returns The type of match.
+     */
+    getMatchType(): MatchType;
+    /**
+     * Get the matching locale.
+     *
+     * @returns The matching locale.
+     */
+    getMatch(): NormalizeLocale<TLocales[number]>;
+}
+/**
+ * Resolve the preferred locale from an HTTP `Accept-Language` header.
+ *
+ * All locale identifiers provided as parameters must following the BCP 47 `language`-`country` (case insensitive).
+ *
+ * @param acceptLanguageHeader - The value of an HTTP request `Accept-Language` header (also known as a "language priority list").
+ * @param locales - An array of locale identifiers that must include the default locale. The order will be used for matching where
+ * the first identifier will be more likely to be matched than the last identifier.
+ * @param defaultLocale - The default locale identifier when no match is found.
+ *
+ * @returns The locale identifier which was the best match, in case-normalized format.
+ *
+ * @example
+ * // returns 'fr-CA'
+ * resolveAcceptLanguage(
+ *   'fr-CA;q=0.01,en-CA;q=0.1,en-US;q=0.001',
+ *   ['en-US', 'fr-CA'],
+ *   'en-US'
+ * )
+ */
+declare const resolveAcceptLanguage: <TLocales extends readonly string[]>(acceptLanguageHeader: string, locales: TLocales extends string[] ? TLocales[number][] : TLocales, defaultLocale: TLocales[number]) => NormalizeLocale<TLocales[number]>;
+export default resolveAcceptLanguage;

package/lib/esm/resolve-accept-language.js

@@ -0,0 +1,103 @@
+import Locale from './locale';
+import LookupList from './lookup-list';
+/** Match type enumeration. */
+export var MATCH_TYPES = {
+    localeBased: 'localeBased',
+    languageBased: 'languageBased',
+    relatedLocaleBased: 'relatedLocaleBased',
+    defaultLocale: 'defaultLocale',
+};
+/** Resolve the preferred locale from an HTTP `Accept-Language` header. */
+var ResolveAcceptLanguage = /** @class */ (function () {
+    /**
+     * Create a new `ResolveAcceptLanguage` object.
+     *
+     * All locale identifiers provided as parameters must following the BCP 47 `language`-`country` (case insensitive).
+     *
+     * @param acceptLanguageHeader - The value of an HTTP request `Accept-Language` header (also known as a "language priority list").
+     * @param locales - An array of locale identifiers. The order will be used for matching where the first identifier will be more
+     * likely to be matched than the last identifier.
+     */
+    function ResolveAcceptLanguage(acceptLanguageHeader, locales, defaultLocale) {
+        // Check if the locales are valid.
+        locales.forEach(function (locale) {
+            if (!Locale.isLocale(locale, false)) {
+                throw new Error("invalid locale identifier '".concat(locale, "'"));
+            }
+        });
+        // Check if the default locale is valid.
+        if (!Locale.isLocale(defaultLocale, false)) {
+            throw new Error("invalid default locale identifier '".concat(defaultLocale, "'"));
+        }
+        // Check if the default locale is included in the locales.
+        if (!locales.some(function (locale) { return locale.toLowerCase() === defaultLocale.toLowerCase(); })) {
+            throw new Error('the default locale must be included in the locales');
+        }
+        this.defaultLocale = new Locale(defaultLocale).identifier;
+        var lookupList = new LookupList(acceptLanguageHeader, locales, defaultLocale);
+        // Check if the match if locale based.
+        this.localeBasedMatch = lookupList.getLocaleBasedMatch();
+        if (this.localeBasedMatch) {
+            return;
+        }
+        // Check if the match is language based.
+        this.languageBasedMatch = lookupList.getLanguageBasedMatch();
+        if (this.languageBasedMatch) {
+            return;
+        }
+        // Check if the match is related-locale based.
+        this.relatedLocaleBasedMatch = lookupList.getRelatedLocaleBasedMatch();
+        if (this.relatedLocaleBasedMatch) {
+            return;
+        }
+    }
+    /**
+     * Get the type of match.
+     *
+     * @returns The type of match.
+     */
+    ResolveAcceptLanguage.prototype.getMatchType = function () {
+        return this.localeBasedMatch
+            ? MATCH_TYPES.localeBased
+            : this.languageBasedMatch
+                ? MATCH_TYPES.languageBased
+                : this.relatedLocaleBasedMatch
+                    ? MATCH_TYPES.relatedLocaleBased
+                    : MATCH_TYPES.defaultLocale;
+    };
+    /**
+     * Get the matching locale.
+     *
+     * @returns The matching locale.
+     */
+    ResolveAcceptLanguage.prototype.getMatch = function () {
+        var _a, _b, _c;
+        return ((_c = (_b = (_a = this.localeBasedMatch) !== null && _a !== void 0 ? _a : this.languageBasedMatch) !== null && _b !== void 0 ? _b : this.relatedLocaleBasedMatch) !== null && _c !== void 0 ? _c : this.defaultLocale);
+    };
+    return ResolveAcceptLanguage;
+}());
+export { ResolveAcceptLanguage };
+/**
+ * Resolve the preferred locale from an HTTP `Accept-Language` header.
+ *
+ * All locale identifiers provided as parameters must following the BCP 47 `language`-`country` (case insensitive).
+ *
+ * @param acceptLanguageHeader - The value of an HTTP request `Accept-Language` header (also known as a "language priority list").
+ * @param locales - An array of locale identifiers that must include the default locale. The order will be used for matching where
+ * the first identifier will be more likely to be matched than the last identifier.
+ * @param defaultLocale - The default locale identifier when no match is found.
+ *
+ * @returns The locale identifier which was the best match, in case-normalized format.
+ *
+ * @example
+ * // returns 'fr-CA'
+ * resolveAcceptLanguage(
+ *   'fr-CA;q=0.01,en-CA;q=0.1,en-US;q=0.001',
+ *   ['en-US', 'fr-CA'],
+ *   'en-US'
+ * )
+ */
+var resolveAcceptLanguage = function (acceptLanguageHeader, locales, defaultLocale) {
+    return new ResolveAcceptLanguage(acceptLanguageHeader, locales, defaultLocale).getMatch();
+};
+export default resolveAcceptLanguage;

package/package.json

@@ -1,68 +1,73 @@
-{
-  "name": "resolve-accept-language",
-  "version": "2.1.17",
-  "description": "Resolve the preferred locale based on the value of an `Accept-Language` HTTP header.",
-  "keywords": [
-    "accept-language",
-    "RFC 4647",
-    "locale",
-    "language tags",
-    "RFC 4646",
-    "BCP 47",
-    "RFC 2616",
-    "resolve",
-    "detect",
-    "intl",
-    "i18n",
-    "internationalization"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Avansai/resolve-accept-language.git"
-  },
-  "license": "MIT",
-  "author": "Avansai (https://avansai.com)",
-  "main": "lib/resolve-accept-language.js",
-  "types": "lib/resolve-accept-language.d.ts",
-  "files": [
-    "lib"
-  ],
-  "scripts": {
-    "build": "npm run prettier && npm run lint-fix && rm -Rf ./lib && tsc && npm run test",
-    "lint-check": "eslint --ext .js --ext .jsx --ext .ts --ext .tsx --ext .json .",
-    "lint-fix": "eslint --ext .js --ext .jsx --ext .ts --ext .tsx --ext .json --fix .",
-    "lint-print-config": "eslint --print-config ./eslintrc.yaml",
-    "prettier": "prettier --write .",
-    "release": "dotenv -- release-it --only-version",
-    "test": "jest --coverage"
-  },
-  "devDependencies": {
-    "@release-it/conventional-changelog": "8.0.1",
-    "@types/jest": "29.5.12",
-    "@typescript-eslint/eslint-plugin": "6.21.0",
-    "@typescript-eslint/parser": "6.21.0",
-    "dotenv-cli": "7.3.0",
-    "eslint": "8.56.0",
-    "eslint-config-prettier": "9.1.0",
-    "eslint-import-resolver-node": "0.3.9",
-    "eslint-import-resolver-typescript": "3.6.1",
-    "eslint-plugin-import": "2.29.1",
-    "eslint-plugin-jest": "27.6.3",
-    "eslint-plugin-json-files": "4.1.0",
-    "eslint-plugin-prefer-arrow-functions": "3.2.4",
-    "eslint-plugin-prettier": "5.1.3",
-    "eslint-plugin-tsdoc": "0.2.17",
-    "eslint-plugin-unicorn": "51.0.1",
-    "jest": "29.7.0",
-    "prettier": "3.2.5",
-    "prettier-plugin-organize-imports": "3.2.4",
-    "prettier-plugin-sh": "0.14.0",
-    "release-it": "17.0.3",
-    "ts-jest": "29.1.2",
-    "ts-node": "10.9.2",
-    "typescript": "5.3.3"
-  },
-  "engines": {
-    "node": "^14.18.1 || >=16.0.0"
-  }
-}
+{
+  "name": "resolve-accept-language",
+  "version": "2.1.19",
+  "description": "Resolve the preferred locale based on the value of an `Accept-Language` HTTP header.",
+  "keywords": [
+    "accept-language",
+    "RFC 4647",
+    "locale",
+    "language tags",
+    "RFC 4646",
+    "BCP 47",
+    "RFC 2616",
+    "resolve",
+    "detect",
+    "intl",
+    "i18n",
+    "internationalization"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Avansai/resolve-accept-language.git"
+  },
+  "license": "MIT",
+  "author": "Avansai (https://avansai.com)",
+  "type": "module",
+  "main": "lib/cjs/index.js",
+  "module": "lib/esm/index.js",
+  "types": "lib/esm/resolve-accept-language.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "npm run prettier && npm run lint-fix && rm -Rf ./lib && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && npm run test",
+    "lint-check": "eslint --ext .js --ext .jsx --ext .ts --ext .tsx --ext .json .",
+    "lint-fix": "eslint --fix .",
+    "lint-print-config": "eslint --print-config ./eslintrc.yaml",
+    "prettier": "prettier --write .",
+    "release": "dotenv -- release-it --only-version",
+    "test": "jest --coverage"
+  },
+  "devDependencies": {
+    "@release-it/conventional-changelog": "8.0.1",
+    "@types/jest": "29.5.12",
+    "@typescript-eslint/eslint-plugin": "7.0.2",
+    "@typescript-eslint/parser": "7.0.2",
+    "dotenv-cli": "7.3.0",
+    "eslint": "8.57.0",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-import-resolver-node": "0.3.9",
+    "eslint-import-resolver-typescript": "3.6.1",
+    "eslint-plugin-import": "2.29.1",
+    "eslint-plugin-jest": "27.9.0",
+    "eslint-plugin-jsdoc": "48.2.0",
+    "eslint-plugin-json-files": "4.1.0",
+    "eslint-plugin-prefer-arrow-functions": "3.2.4",
+    "eslint-plugin-prettier": "5.1.3",
+    "eslint-plugin-tsdoc": "0.2.17",
+    "eslint-plugin-unicorn": "51.0.1",
+    "globals": "14.0.0",
+    "jest": "29.7.0",
+    "jsonc-eslint-parser": "2.4.0",
+    "prettier": "3.2.5",
+    "prettier-plugin-organize-imports": "3.2.4",
+    "prettier-plugin-sh": "0.14.0",
+    "release-it": "17.1.1",
+    "ts-jest": "29.1.2",
+    "ts-node": "10.9.2",
+    "typescript": "5.3.3"
+  },
+  "engines": {
+    "node": "^14.18.1 || >=16.0.0"
+  }
+}