resolve-accept-language 3.0.0 → 3.1.1

package/README.md

@@ -47,6 +47,8 @@ fr-CA
 
 ## Advanced use cases
 
+### Match types
+
 You may want to control exactly the behavior depending on the type of match. For example, you might 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 `{ returnMatchType: true }` option. It offers more visibility into the selection process while matching a locale:
 
 ```ts
@@ -69,30 +71,54 @@ if (matchType === MATCH_TYPES.locale) {
   console.log('The match is language-based')
 } else if (matchType === MATCH_TYPES.relatedLocale) {
   console.log('The match is related-locale-based')
+} else if (matchType === MATCH_TYPES.languageCountry) {
+  console.log('The match is language country-based')
 } else if (matchType === MATCH_TYPES.defaultLocale) {
   console.log('The match is the default locale')
 }
 ```
 
+### Country match
+
+There may be cases where it is preferred to perform a "country match" before falling back to the default locale match. For example:
+
+```ts
+console.log(
+  resolveAcceptLanguage('af-ZA', ['en-US', 'zu-ZA'] as const, 'en-US', {
+    returnMatchType: true,
+    matchCountry: true,
+  })
+)
+```
+
+Output:
+
+```json
+{ "match": "zu-ZA", "matchType": "country" }
+```
+
+In this case, the header prefers `af-ZA`, which shares the same country as `zu-ZA`. Instead of falling back to the default `en-US`, `zu-ZA` is matched.
+
+This behavior is not set by default because, in most cases, the quality of the default locale is better than the translations. Performing a country match could potentially lower the quality of the selection. However, there may be cases where this is not true, which is why the `matchCountry` option exists.
+
 ## 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 will always be placed 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.
-2. All locales and languages are extracted from the HTTP header and sorted by quality factor and position in the header.
-3. The following matching logic will be performed:
-   1. Perform a first loop on the directives
-      1. If the directive is a locale, then try to find an exact locale match (**locale match**)
-      2. If the directive is a language, then
-         1. Create a new list of directives that have locales matching the language
-         2. Loop through this new list, and try to find an exact locale match (**language-specific locale match**)
-         3. If no match is found, then try to find a locale that matches the language (**language match**)
-   2. Perform a second loop on the directives
-      1. Create a new list of languages from the locales
-      2. Loop through this new list, then try to find a locale that matches the language (**related-locale match**)
-   3. If everything fails, then the fallback is the default locale (**default locale match**)
+The matching strategy follows these steps, in order:
+
+1. Start with the default locale, as it's considered the highest quality content available.
+2. Extract all locales and languages from the HTTP header, sorted by quality factor and position in the header. Each of these elements is referred to as a "directive".
+3. Perform matching in several stages:
+   1. **Locale Match**: Look for an exact locale match in the directives.
+   2. **Language-Specific Locale Match**: If no locale match is found, look for a locale that matches the language of the directive.
+   3. **Language Match**: If no language-specific locale match is found, look for a locale that matches the language.
+   4. **Related-Locale Match**: If no language match is found, look for a locale that matches the language in the next round of directives.
+   5. **Language Country Match**: If no related-locale match is found, look for a locale that matches the default locale's language but in a country from a locale specified in a directive.
+   6. **Country Match**: If the option is enabled and no language country match is found, look for a locale that matches the country in the next round of directives.
+   7. **Default Locale Match**: If all else fails, fall back to the default locale.
+
+Each stage only happens if the previous stage didn't find a match. This ensures the best possible match is found according to the given criteria.
 
 ## Why another `Accept-Language` package?
 

package/lib/cjs/directives.d.ts

@@ -2,6 +2,8 @@
 type Directive = {
     /** The ISO 639-1 alpha-2 language code. */
     languageCode: string;
+    /** The ISO 3166-1 alpha-2 country code. */
+    countryCode?: string;
     /** The locale identifier using the BCP 47 `language`-`country` in case-normalized format. */
     locale?: string;
     /** The quality factor (default is 1; values can range from 0 to 1 with up to 3 decimals). */

package/lib/cjs/directives.js

@@ -1 +1 @@
-"use strict";var __assign=this&&this.__assign||function(){return __assign=Object.assign||function(e){for(var r,t=1,a=arguments.length;t<a;t++)for(var i in r=arguments[t])Object.prototype.hasOwnProperty.call(r,i)&&(e[i]=r[i]);return e},__assign.apply(this,arguments)},__read=this&&this.__read||function(e,r){var t="function"==typeof Symbol&&e[Symbol.iterator];if(!t)return e;var a,i,o=t.call(e),n=[];try{for(;(void 0===r||r-- >0)&&!(a=o.next()).done;)n.push(a.value)}catch(e){i={error:e}}finally{try{a&&!a.done&&(t=o.return)&&t.call(o)}finally{if(i)throw i.error}}return n},__spreadArray=this&&this.__spreadArray||function(e,r,t){if(t||2===arguments.length)for(var a,i=0,o=r.length;i<o;i++)!a&&i in r||(a||(a=Array.prototype.slice.call(r,0,i)),a[i]=r[i]);return e.concat(a||Array.prototype.slice.call(r))};Object.defineProperty(exports,"__esModule",{value:!0}),exports.getDirectives=void 0;var getDirective=function(e){var r=e.match(/^((?<matchedLanguageCode>([a-z]{2}))(-(?<matchedCountryCode>[a-z]{2}|419))?)(;q=(?<matchedQuality>(1(\.0{0,3})?)|(0(\.\d{0,3})?)))?$/i);if(null==r?void 0:r.groups){var t=r.groups,a=t.matchedLanguageCode,i=t.matchedCountryCode,o=t.matchedQuality,n=a.toLowerCase(),s=i?i.toUpperCase():void 0;if("419"!==s||"es"===n){var c=void 0===o?1:Number.parseFloat(o);return{languageCode:n,locale:s?"".concat(n,"-").concat(s):void 0,quality:c}}}},getDirectives=function(e){var r=[],t=0;e.split(",").forEach((function(e){var a=getDirective(e.trim());a&&(r.some((function(e){return e.languageCode===a.languageCode&&e.locale===a.locale}))||(r.push(__assign(__assign({},a),{headerPosition:t})),t++))}));var a=r.findIndex((function(e){return"es-419"===e.locale}));if(a>=0){var i=r[a],o=["es-AR","es-CL","es-CO","es-CR","es-HN","es-MX","es-PE","es-US","es-UY","es-VE"].map((function(e){return __assign(__assign({},i),{locale:e})}));r.splice.apply(r,__spreadArray([a,1],__read(o),!1))}return r.sort((function(e,r){var t=r.quality-e.quality;return t||e.headerPosition-r.headerPosition}))};exports.getDirectives=getDirectives;
+"use strict";var __assign=this&&this.__assign||function(){return __assign=Object.assign||function(e){for(var r,t=1,a=arguments.length;t<a;t++)for(var i in r=arguments[t])Object.prototype.hasOwnProperty.call(r,i)&&(e[i]=r[i]);return e},__assign.apply(this,arguments)},__read=this&&this.__read||function(e,r){var t="function"==typeof Symbol&&e[Symbol.iterator];if(!t)return e;var a,i,o=t.call(e),n=[];try{for(;(void 0===r||r-- >0)&&!(a=o.next()).done;)n.push(a.value)}catch(e){i={error:e}}finally{try{a&&!a.done&&(t=o.return)&&t.call(o)}finally{if(i)throw i.error}}return n},__spreadArray=this&&this.__spreadArray||function(e,r,t){if(t||2===arguments.length)for(var a,i=0,o=r.length;i<o;i++)!a&&i in r||(a||(a=Array.prototype.slice.call(r,0,i)),a[i]=r[i]);return e.concat(a||Array.prototype.slice.call(r))};Object.defineProperty(exports,"__esModule",{value:!0}),exports.getDirectives=void 0;var getDirective=function(e){var r=e.match(/^((?<matchedLanguageCode>([a-z]{2}))(-(?<matchedCountryCode>[a-z]{2}|419))?)(;q=(?<matchedQuality>(1(\.0{0,3})?)|(0(\.\d{0,3})?)))?$/i);if(null==r?void 0:r.groups){var t=r.groups,a=t.matchedLanguageCode,i=t.matchedCountryCode,o=t.matchedQuality,n=a.toLowerCase(),s=i?i.toUpperCase():void 0;if("419"!==s||"es"===n){var c=void 0===o?1:Number.parseFloat(o);return{languageCode:n,countryCode:s,locale:s?"".concat(n,"-").concat(s):void 0,quality:c}}}},getDirectives=function(e){var r=[],t=0;e.split(",").forEach((function(e){var a=getDirective(e.trim());a&&(r.some((function(e){return e.languageCode===a.languageCode&&e.locale===a.locale}))||(r.push(__assign(__assign({},a),{headerPosition:t})),t++))}));var a=r.findIndex((function(e){return"es-419"===e.locale}));if(a>=0){var i=r[a],o=["es-AR","es-CL","es-CO","es-CR","es-HN","es-MX","es-PE","es-US","es-UY","es-VE"].map((function(e){return __assign(__assign({},i),{locale:e})}));r.splice.apply(r,__spreadArray([a,1],__read(o),!1))}return r.sort((function(e,r){var t=r.quality-e.quality;return t||e.headerPosition-r.headerPosition}))};exports.getDirectives=getDirectives;

package/lib/cjs/index.d.ts

@@ -1,5 +1,5 @@
 /** The type of matches. */
-export type MatchType = 'locale' | 'languageSpecificLocale' | 'language' | 'relatedLocale' | 'defaultLocale';
+export type MatchType = 'locale' | 'languageSpecificLocale' | 'language' | 'relatedLocale' | 'languageCountry' | 'country' | 'defaultLocale';
 /** The type of matches enumeration. */
 export declare const MATCH_TYPES: {
     readonly [K in MatchType]: K;
@@ -10,6 +10,8 @@ export type NormalizeLocale<Remainder extends string> = Remainder extends `${inf
 type Options<WithMatchType extends boolean | undefined> = {
     /** Should the match type be returned? */
     returnMatchType?: WithMatchType;
+    /** Should the country of the locale be used for matching? */
+    matchCountry?: boolean;
 };
 type Result<Locales extends string[], WithMatchType extends boolean | undefined> = WithMatchType extends true ? {
     /** The best locale match. */
@@ -38,5 +40,5 @@ type Result<Locales extends string[], WithMatchType extends boolean | undefined>
  *   'en-US'
  * )
  */
-export declare const resolveAcceptLanguage: <Locales extends string[], WithMatchType extends boolean | undefined = undefined>(acceptLanguageHeader: string, locales: Locales, defaultLocale: Locales[number], options?: Options<WithMatchType> | undefined) => Result<Locales, WithMatchType>;
+export declare const resolveAcceptLanguage: <Locales extends string[], WithMatchType extends boolean | undefined = undefined>(acceptLanguageHeader: string, locales: Locales, defaultLocale: Locales[number], options?: Options<WithMatchType>) => Result<Locales, WithMatchType>;
 export {};

package/lib/cjs/index.js

@@ -1 +1 @@
-"use strict";var __read=this&&this.__read||function(e,a){var r="function"==typeof Symbol&&e[Symbol.iterator];if(!r)return e;var t,o,l=r.call(e),n=[];try{for(;(void 0===a||a-- >0)&&!(t=l.next()).done;)n.push(t.value)}catch(e){o={error:e}}finally{try{t&&!t.done&&(r=l.return)&&r.call(l)}finally{if(o)throw o.error}}return n},__spreadArray=this&&this.__spreadArray||function(e,a,r){if(r||2===arguments.length)for(var t,o=0,l=a.length;o<l;o++)!t&&o in a||(t||(t=Array.prototype.slice.call(a,0,o)),t[o]=a[o]);return e.concat(t||Array.prototype.slice.call(a))},__values=this&&this.__values||function(e){var a="function"==typeof Symbol&&Symbol.iterator,r=a&&e[a],t=0;if(r)return r.call(e);if(e&&"number"==typeof e.length)return{next:function(){return e&&t>=e.length&&(e=void 0),{value:e&&e[t++],done:!e}}};throw new TypeError(a?"Object is not iterable.":"Symbol.iterator is not defined.")};Object.defineProperty(exports,"__esModule",{value:!0}),exports.resolveAcceptLanguage=exports.MATCH_TYPES=void 0;var directives_1=require("./directives"),locales_1=require("./locales");exports.MATCH_TYPES={locale:"locale",languageSpecificLocale:"languageSpecificLocale",language:"language",relatedLocale:"relatedLocale",defaultLocale:"defaultLocale"};var resolveAcceptLanguage=function(e,a,r,t){if(a.forEach((function(e){if(!(0,locales_1.isLocale)(e,!1))throw new Error("Invalid locale identifier '".concat(e,"'. A valid locale should follow the BCP 47 'language-country' format."))})),!(0,locales_1.isLocale)(r,!1))throw new Error("Invalid default locale identifier '".concat(r,"'. A valid locale should follow the BCP 47 'language-country' format."));if(!a.some((function(e){return e.toLowerCase()===r.toLowerCase()})))throw new Error("The default locale '".concat(r,"' must be included in the locales array because it is used as a fallback when no match is found."));var o=new locales_1.Locale(r).identifier,l=new Set(__spreadArray([o],__read(a.map((function(e){return new locales_1.Locale(e).identifier}))),!1)),n=function(){var a,r,t,n,c=new locales_1.LocaleList(l),i=(0,directives_1.getDirectives)(e),u=function(e){var a=e.locale,r=e.languageCode;if(!c.languages.has(r))return"continue";if(void 0!==a)return c.locales.has(a)?{value:{match:a,matchType:exports.MATCH_TYPES.locale}}:"continue";var t=i.find((function(e){return e.languageCode===r&&void 0!==e.locale&&c.locales.has(e.locale)}));if(t)return{value:{match:t.locale,matchType:exports.MATCH_TYPES.languageSpecificLocale}};var o=c.objects.find((function(e){return e.languageCode===r}));return o?{value:{match:o.identifier,matchType:exports.MATCH_TYPES.language}}:void 0};try{for(var f=__values(i),s=f.next();!s.done;s=f.next()){var d=u(s.value);if("object"==typeof d)return d.value}}catch(e){a={error:e}}finally{try{s&&!s.done&&(r=f.return)&&r.call(f)}finally{if(a)throw a.error}}var v=function(e){if(!c.languages.has(e.languageCode))return"continue";var a=c.objects.find((function(a){return a.languageCode===e.languageCode}));return a?{value:{match:a.identifier,matchType:exports.MATCH_TYPES.relatedLocale}}:void 0};try{for(var h=__values(i),g=h.next();!g.done;g=h.next()){var y=v(g.value);if("object"==typeof y)return y.value}}catch(e){t={error:e}}finally{try{g&&!g.done&&(n=h.return)&&n.call(h)}finally{if(t)throw t.error}}return{match:o,matchType:exports.MATCH_TYPES.defaultLocale}}();return(null==t?void 0:t.returnMatchType)?n:n.match};exports.resolveAcceptLanguage=resolveAcceptLanguage;
+"use strict";var __read=this&&this.__read||function(e,r){var a="function"==typeof Symbol&&e[Symbol.iterator];if(!a)return e;var t,o,n=a.call(e),l=[];try{for(;(void 0===r||r-- >0)&&!(t=n.next()).done;)l.push(t.value)}catch(e){o={error:e}}finally{try{t&&!t.done&&(a=n.return)&&a.call(n)}finally{if(o)throw o.error}}return l},__spreadArray=this&&this.__spreadArray||function(e,r,a){if(a||2===arguments.length)for(var t,o=0,n=r.length;o<n;o++)!t&&o in r||(t||(t=Array.prototype.slice.call(r,0,o)),t[o]=r[o]);return e.concat(t||Array.prototype.slice.call(r))},__values=this&&this.__values||function(e){var r="function"==typeof Symbol&&Symbol.iterator,a=r&&e[r],t=0;if(a)return a.call(e);if(e&&"number"==typeof e.length)return{next:function(){return e&&t>=e.length&&(e=void 0),{value:e&&e[t++],done:!e}}};throw new TypeError(r?"Object is not iterable.":"Symbol.iterator is not defined.")};Object.defineProperty(exports,"__esModule",{value:!0}),exports.resolveAcceptLanguage=exports.MATCH_TYPES=void 0;var directives_1=require("./directives"),locales_1=require("./locales");exports.MATCH_TYPES={locale:"locale",languageSpecificLocale:"languageSpecificLocale",language:"language",relatedLocale:"relatedLocale",languageCountry:"languageCountry",country:"country",defaultLocale:"defaultLocale"};var resolveAcceptLanguage=function(e,r,a,t){if(r.forEach((function(e){if(!(0,locales_1.isLocale)(e,!1))throw new Error("Invalid locale identifier '".concat(e,"'. A valid locale should follow the BCP 47 'language-country' format."))})),!(0,locales_1.isLocale)(a,!1))throw new Error("Invalid default locale identifier '".concat(a,"'. A valid locale should follow the BCP 47 'language-country' format."));if(!r.some((function(e){return e.toLowerCase()===a.toLowerCase()})))throw new Error("The default locale '".concat(a,"' must be included in the locales array because it is used as a fallback when no match is found."));var o=new locales_1.Locale(a),n=new Set(__spreadArray([o.identifier],__read(r.map((function(e){return new locales_1.Locale(e).identifier}))),!1)),l=function(){var r,a,l,c,i,u,f,d,s=new locales_1.LocaleList(n),v=(0,directives_1.getDirectives)(e),y=v.filter((function(e){return s.languages.has(e.languageCode)})),g=function(e){var r=e.locale,a=e.languageCode;if(void 0!==r)return s.locales.has(r)?{value:{match:r,matchType:exports.MATCH_TYPES.locale}}:"continue";var t=v.find((function(e){return e.languageCode===a&&void 0!==e.locale&&s.locales.has(e.locale)}));if(t)return{value:{match:t.locale,matchType:exports.MATCH_TYPES.languageSpecificLocale}};var o=s.objects.find((function(e){return e.languageCode===a}));return o?{value:{match:o.identifier,matchType:exports.MATCH_TYPES.language}}:void 0};try{for(var h=__values(y),p=h.next();!p.done;p=h.next()){var _=g(P=p.value);if("object"==typeof _)return _.value}}catch(e){r={error:e}}finally{try{p&&!p.done&&(a=h.return)&&a.call(h)}finally{if(r)throw r.error}}var C=function(e){var r=s.objects.find((function(r){return r.languageCode===e.languageCode}));if(r)return{value:{match:r.identifier,matchType:exports.MATCH_TYPES.relatedLocale}}};try{for(var m=__values(y),T=m.next();!T.done;T=m.next()){var w=C(P=T.value);if("object"==typeof w)return w.value}}catch(e){l={error:e}}finally{try{T&&!T.done&&(c=m.return)&&c.call(m)}finally{if(l)throw l.error}}var x=s.objects.filter((function(e){return e.languageCode===o.languageCode&&e.identifier!==o.identifier})).map((function(e){return e.countryCode}));if(x.length>0)try{for(var L=__values(v),A=L.next();!A.done;A=L.next()){if(void 0!==(P=A.value).locale&&void 0!==P.countryCode&&x.includes(P.countryCode))return{match:"".concat(o.languageCode,"-").concat(P.countryCode),matchType:exports.MATCH_TYPES.languageCountry}}}catch(e){i={error:e}}finally{try{A&&!A.done&&(u=L.return)&&u.call(L)}finally{if(i)throw i.error}}if(null==t?void 0:t.matchCountry){var b=function(e){var r=s.objects.find((function(r){return r.countryCode===e.countryCode}));if(r)return{value:{match:r.identifier,matchType:exports.MATCH_TYPES.country}}};try{for(var S=__values(v),E=S.next();!E.done;E=S.next()){var P,M=b(P=E.value);if("object"==typeof M)return M.value}}catch(e){f={error:e}}finally{try{E&&!E.done&&(d=S.return)&&d.call(S)}finally{if(f)throw f.error}}}return{match:o.identifier,matchType:exports.MATCH_TYPES.defaultLocale}}();return(null==t?void 0:t.returnMatchType)?l:l.match};exports.resolveAcceptLanguage=resolveAcceptLanguage;

package/lib/cjs/locales.d.ts

@@ -1,11 +1,11 @@
 /** Class to manage a locale identifier using the BCP 47 `language`-`country` format. */
 export declare class Locale {
+    /** The ISO 639-1 alpha-2 language code. */
+    readonly languageCode: 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: string;
-    /** The ISO 639-1 alpha-2 language code. */
-    readonly languageCode: string;
     /**
      * Create a new `Locale` object.
      *
@@ -16,10 +16,10 @@ export declare class Locale {
     constructor(identifier: string);
 }
 export declare class LocaleList {
-    /** 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 ISO 3166-1 alpha-2 country codes. */
+    readonly countries: 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. */

package/lib/cjs/locales.js

@@ -1 +1 @@
-"use strict";var __read=this&&this.__read||function(e,o){var t="function"==typeof Symbol&&e[Symbol.iterator];if(!t)return e;var a,r,i=t.call(e),s=[];try{for(;(void 0===o||o-- >0)&&!(a=i.next()).done;)s.push(a.value)}catch(e){r={error:e}}finally{try{a&&!a.done&&(t=i.return)&&t.call(i)}finally{if(r)throw r.error}}return s};Object.defineProperty(exports,"__esModule",{value:!0}),exports.isLocale=exports.LocaleList=exports.Locale=void 0;var Locale=function(e){if(!(0,exports.isLocale)(e,!1))throw new Error("invalid locale identifier '".concat(e,"'"));var o=__read(e.split("-"),2),t=o[0],a=o[1];this.languageCode=t.toLowerCase(),this.countryCode=a.toUpperCase(),this.identifier="".concat(this.languageCode,"-").concat(this.countryCode)};exports.Locale=Locale;var LocaleList=function(e){var o=this;this.countries=new Set,this.languages=new Set,this.locales=new Set,this.objects=[],e.forEach((function(e){var t=new Locale(e);o.objects.push(t),o.locales.add(t.identifier),o.languages.add(t.languageCode),o.countries.add(t.countryCode)}))};exports.LocaleList=LocaleList;var isLocale=function(e,o){return void 0===o&&(o=!0),new RegExp(/^[a-z]{2}-[A-Z]{2}$/,o?void 0:"i").test(e)};exports.isLocale=isLocale;
+"use strict";var __read=this&&this.__read||function(e,o){var t="function"==typeof Symbol&&e[Symbol.iterator];if(!t)return e;var a,r,i=t.call(e),s=[];try{for(;(void 0===o||o-- >0)&&!(a=i.next()).done;)s.push(a.value)}catch(e){r={error:e}}finally{try{a&&!a.done&&(t=i.return)&&t.call(i)}finally{if(r)throw r.error}}return s};Object.defineProperty(exports,"__esModule",{value:!0}),exports.isLocale=exports.LocaleList=exports.Locale=void 0;var Locale=function(e){if(!(0,exports.isLocale)(e,!1))throw new Error("invalid locale identifier '".concat(e,"'"));var o=__read(e.split("-"),2),t=o[0],a=o[1];this.languageCode=t.toLowerCase(),this.countryCode=a.toUpperCase(),this.identifier="".concat(this.languageCode,"-").concat(this.countryCode)};exports.Locale=Locale;var LocaleList=function(e){var o=this;this.languages=new Set,this.countries=new Set,this.locales=new Set,this.objects=[],e.forEach((function(e){var t=new Locale(e);o.objects.push(t),o.locales.add(t.identifier),o.languages.add(t.languageCode),o.countries.add(t.countryCode)}))};exports.LocaleList=LocaleList;var isLocale=function(e,o){return void 0===o&&(o=!0),new RegExp(/^[a-z]{2}-[A-Z]{2}$/,o?void 0:"i").test(e)};exports.isLocale=isLocale;

package/lib/esm/directives.d.ts

@@ -2,6 +2,8 @@
 type Directive = {
     /** The ISO 639-1 alpha-2 language code. */
     languageCode: string;
+    /** The ISO 3166-1 alpha-2 country code. */
+    countryCode?: string;
     /** The locale identifier using the BCP 47 `language`-`country` in case-normalized format. */
     locale?: string;
     /** The quality factor (default is 1; values can range from 0 to 1 with up to 3 decimals). */

package/lib/esm/directives.js

@@ -1 +1 @@
-var __assign=this&&this.__assign||function(){return __assign=Object.assign||function(e){for(var r,a=1,t=arguments.length;a<t;a++)for(var n in r=arguments[a])Object.prototype.hasOwnProperty.call(r,n)&&(e[n]=r[n]);return e},__assign.apply(this,arguments)},__read=this&&this.__read||function(e,r){var a="function"==typeof Symbol&&e[Symbol.iterator];if(!a)return e;var t,n,o=a.call(e),i=[];try{for(;(void 0===r||r-- >0)&&!(t=o.next()).done;)i.push(t.value)}catch(e){n={error:e}}finally{try{t&&!t.done&&(a=o.return)&&a.call(o)}finally{if(n)throw n.error}}return i},__spreadArray=this&&this.__spreadArray||function(e,r,a){if(a||2===arguments.length)for(var t,n=0,o=r.length;n<o;n++)!t&&n in r||(t||(t=Array.prototype.slice.call(r,0,n)),t[n]=r[n]);return e.concat(t||Array.prototype.slice.call(r))},getDirective=function(e){var r=e.match(/^((?<matchedLanguageCode>([a-z]{2}))(-(?<matchedCountryCode>[a-z]{2}|419))?)(;q=(?<matchedQuality>(1(\.0{0,3})?)|(0(\.\d{0,3})?)))?$/i);if(null==r?void 0:r.groups){var a=r.groups,t=a.matchedLanguageCode,n=a.matchedCountryCode,o=a.matchedQuality,i=t.toLowerCase(),s=n?n.toUpperCase():void 0;if("419"!==s||"es"===i){var l=void 0===o?1:Number.parseFloat(o);return{languageCode:i,locale:s?"".concat(i,"-").concat(s):void 0,quality:l}}}};export var getDirectives=function(e){var r=[],a=0;e.split(",").forEach((function(e){var t=getDirective(e.trim());t&&(r.some((function(e){return e.languageCode===t.languageCode&&e.locale===t.locale}))||(r.push(__assign(__assign({},t),{headerPosition:a})),a++))}));var t=r.findIndex((function(e){return"es-419"===e.locale}));if(t>=0){var n=r[t],o=["es-AR","es-CL","es-CO","es-CR","es-HN","es-MX","es-PE","es-US","es-UY","es-VE"].map((function(e){return __assign(__assign({},n),{locale:e})}));r.splice.apply(r,__spreadArray([t,1],__read(o),!1))}return r.sort((function(e,r){var a=r.quality-e.quality;return a||e.headerPosition-r.headerPosition}))};
+var __assign=this&&this.__assign||function(){return __assign=Object.assign||function(e){for(var r,a=1,t=arguments.length;a<t;a++)for(var n in r=arguments[a])Object.prototype.hasOwnProperty.call(r,n)&&(e[n]=r[n]);return e},__assign.apply(this,arguments)},__read=this&&this.__read||function(e,r){var a="function"==typeof Symbol&&e[Symbol.iterator];if(!a)return e;var t,n,o=a.call(e),i=[];try{for(;(void 0===r||r-- >0)&&!(t=o.next()).done;)i.push(t.value)}catch(e){n={error:e}}finally{try{t&&!t.done&&(a=o.return)&&a.call(o)}finally{if(n)throw n.error}}return i},__spreadArray=this&&this.__spreadArray||function(e,r,a){if(a||2===arguments.length)for(var t,n=0,o=r.length;n<o;n++)!t&&n in r||(t||(t=Array.prototype.slice.call(r,0,n)),t[n]=r[n]);return e.concat(t||Array.prototype.slice.call(r))},getDirective=function(e){var r=e.match(/^((?<matchedLanguageCode>([a-z]{2}))(-(?<matchedCountryCode>[a-z]{2}|419))?)(;q=(?<matchedQuality>(1(\.0{0,3})?)|(0(\.\d{0,3})?)))?$/i);if(null==r?void 0:r.groups){var a=r.groups,t=a.matchedLanguageCode,n=a.matchedCountryCode,o=a.matchedQuality,i=t.toLowerCase(),s=n?n.toUpperCase():void 0;if("419"!==s||"es"===i){var c=void 0===o?1:Number.parseFloat(o);return{languageCode:i,countryCode:s,locale:s?"".concat(i,"-").concat(s):void 0,quality:c}}}};export var getDirectives=function(e){var r=[],a=0;e.split(",").forEach((function(e){var t=getDirective(e.trim());t&&(r.some((function(e){return e.languageCode===t.languageCode&&e.locale===t.locale}))||(r.push(__assign(__assign({},t),{headerPosition:a})),a++))}));var t=r.findIndex((function(e){return"es-419"===e.locale}));if(t>=0){var n=r[t],o=["es-AR","es-CL","es-CO","es-CR","es-HN","es-MX","es-PE","es-US","es-UY","es-VE"].map((function(e){return __assign(__assign({},n),{locale:e})}));r.splice.apply(r,__spreadArray([t,1],__read(o),!1))}return r.sort((function(e,r){var a=r.quality-e.quality;return a||e.headerPosition-r.headerPosition}))};

package/lib/esm/index.d.ts

@@ -1,5 +1,5 @@
 /** The type of matches. */
-export type MatchType = 'locale' | 'languageSpecificLocale' | 'language' | 'relatedLocale' | 'defaultLocale';
+export type MatchType = 'locale' | 'languageSpecificLocale' | 'language' | 'relatedLocale' | 'languageCountry' | 'country' | 'defaultLocale';
 /** The type of matches enumeration. */
 export declare const MATCH_TYPES: {
     readonly [K in MatchType]: K;
@@ -10,6 +10,8 @@ export type NormalizeLocale<Remainder extends string> = Remainder extends `${inf
 type Options<WithMatchType extends boolean | undefined> = {
     /** Should the match type be returned? */
     returnMatchType?: WithMatchType;
+    /** Should the country of the locale be used for matching? */
+    matchCountry?: boolean;
 };
 type Result<Locales extends string[], WithMatchType extends boolean | undefined> = WithMatchType extends true ? {
     /** The best locale match. */
@@ -38,5 +40,5 @@ type Result<Locales extends string[], WithMatchType extends boolean | undefined>
  *   'en-US'
  * )
  */
-export declare const resolveAcceptLanguage: <Locales extends string[], WithMatchType extends boolean | undefined = undefined>(acceptLanguageHeader: string, locales: Locales, defaultLocale: Locales[number], options?: Options<WithMatchType> | undefined) => Result<Locales, WithMatchType>;
+export declare const resolveAcceptLanguage: <Locales extends string[], WithMatchType extends boolean | undefined = undefined>(acceptLanguageHeader: string, locales: Locales, defaultLocale: Locales[number], options?: Options<WithMatchType>) => Result<Locales, WithMatchType>;
 export {};

package/lib/esm/index.js

@@ -1 +1 @@
-var __read=this&&this.__read||function(e,a){var r="function"==typeof Symbol&&e[Symbol.iterator];if(!r)return e;var t,o,l=r.call(e),n=[];try{for(;(void 0===a||a-- >0)&&!(t=l.next()).done;)n.push(t.value)}catch(e){o={error:e}}finally{try{t&&!t.done&&(r=l.return)&&r.call(l)}finally{if(o)throw o.error}}return n},__spreadArray=this&&this.__spreadArray||function(e,a,r){if(r||2===arguments.length)for(var t,o=0,l=a.length;o<l;o++)!t&&o in a||(t||(t=Array.prototype.slice.call(a,0,o)),t[o]=a[o]);return e.concat(t||Array.prototype.slice.call(a))},__values=this&&this.__values||function(e){var a="function"==typeof Symbol&&Symbol.iterator,r=a&&e[a],t=0;if(r)return r.call(e);if(e&&"number"==typeof e.length)return{next:function(){return e&&t>=e.length&&(e=void 0),{value:e&&e[t++],done:!e}}};throw new TypeError(a?"Object is not iterable.":"Symbol.iterator is not defined.")};import{getDirectives}from"./directives.js";import{Locale,LocaleList,isLocale}from"./locales.js";export var MATCH_TYPES={locale:"locale",languageSpecificLocale:"languageSpecificLocale",language:"language",relatedLocale:"relatedLocale",defaultLocale:"defaultLocale"};export var resolveAcceptLanguage=function(e,a,r,t){if(a.forEach((function(e){if(!isLocale(e,!1))throw new Error("Invalid locale identifier '".concat(e,"'. A valid locale should follow the BCP 47 'language-country' format."))})),!isLocale(r,!1))throw new Error("Invalid default locale identifier '".concat(r,"'. A valid locale should follow the BCP 47 'language-country' format."));if(!a.some((function(e){return e.toLowerCase()===r.toLowerCase()})))throw new Error("The default locale '".concat(r,"' must be included in the locales array because it is used as a fallback when no match is found."));var o=new Locale(r).identifier,l=new Set(__spreadArray([o],__read(a.map((function(e){return new Locale(e).identifier}))),!1)),n=function(){var a,r,t,n,i=new LocaleList(l),c=getDirectives(e),u=function(e){var a=e.locale,r=e.languageCode;if(!i.languages.has(r))return"continue";if(void 0!==a)return i.locales.has(a)?{value:{match:a,matchType:MATCH_TYPES.locale}}:"continue";var t=c.find((function(e){return e.languageCode===r&&void 0!==e.locale&&i.locales.has(e.locale)}));if(t)return{value:{match:t.locale,matchType:MATCH_TYPES.languageSpecificLocale}};var o=i.objects.find((function(e){return e.languageCode===r}));return o?{value:{match:o.identifier,matchType:MATCH_TYPES.language}}:void 0};try{for(var f=__values(c),d=f.next();!d.done;d=f.next()){var s=u(d.value);if("object"==typeof s)return s.value}}catch(e){a={error:e}}finally{try{d&&!d.done&&(r=f.return)&&r.call(f)}finally{if(a)throw a.error}}var v=function(e){if(!i.languages.has(e.languageCode))return"continue";var a=i.objects.find((function(a){return a.languageCode===e.languageCode}));return a?{value:{match:a.identifier,matchType:MATCH_TYPES.relatedLocale}}:void 0};try{for(var h=__values(c),g=h.next();!g.done;g=h.next()){var y=v(g.value);if("object"==typeof y)return y.value}}catch(e){t={error:e}}finally{try{g&&!g.done&&(n=h.return)&&n.call(h)}finally{if(t)throw t.error}}return{match:o,matchType:MATCH_TYPES.defaultLocale}}();return(null==t?void 0:t.returnMatchType)?n:n.match};
+var __read=this&&this.__read||function(e,r){var a="function"==typeof Symbol&&e[Symbol.iterator];if(!a)return e;var t,n,o=a.call(e),l=[];try{for(;(void 0===r||r-- >0)&&!(t=o.next()).done;)l.push(t.value)}catch(e){n={error:e}}finally{try{t&&!t.done&&(a=o.return)&&a.call(o)}finally{if(n)throw n.error}}return l},__spreadArray=this&&this.__spreadArray||function(e,r,a){if(a||2===arguments.length)for(var t,n=0,o=r.length;n<o;n++)!t&&n in r||(t||(t=Array.prototype.slice.call(r,0,n)),t[n]=r[n]);return e.concat(t||Array.prototype.slice.call(r))},__values=this&&this.__values||function(e){var r="function"==typeof Symbol&&Symbol.iterator,a=r&&e[r],t=0;if(a)return a.call(e);if(e&&"number"==typeof e.length)return{next:function(){return e&&t>=e.length&&(e=void 0),{value:e&&e[t++],done:!e}}};throw new TypeError(r?"Object is not iterable.":"Symbol.iterator is not defined.")};import{getDirectives}from"./directives.js";import{Locale,LocaleList,isLocale}from"./locales.js";export var MATCH_TYPES={locale:"locale",languageSpecificLocale:"languageSpecificLocale",language:"language",relatedLocale:"relatedLocale",languageCountry:"languageCountry",country:"country",defaultLocale:"defaultLocale"};export var resolveAcceptLanguage=function(e,r,a,t){if(r.forEach((function(e){if(!isLocale(e,!1))throw new Error("Invalid locale identifier '".concat(e,"'. A valid locale should follow the BCP 47 'language-country' format."))})),!isLocale(a,!1))throw new Error("Invalid default locale identifier '".concat(a,"'. A valid locale should follow the BCP 47 'language-country' format."));if(!r.some((function(e){return e.toLowerCase()===a.toLowerCase()})))throw new Error("The default locale '".concat(a,"' must be included in the locales array because it is used as a fallback when no match is found."));var n=new Locale(a),o=new Set(__spreadArray([n.identifier],__read(r.map((function(e){return new Locale(e).identifier}))),!1)),l=function(){var r,a,l,i,c,u,f,d,y=new LocaleList(o),v=getDirectives(e),h=v.filter((function(e){return y.languages.has(e.languageCode)})),s=function(e){var r=e.locale,a=e.languageCode;if(void 0!==r)return y.locales.has(r)?{value:{match:r,matchType:MATCH_TYPES.locale}}:"continue";var t=v.find((function(e){return e.languageCode===a&&void 0!==e.locale&&y.locales.has(e.locale)}));if(t)return{value:{match:t.locale,matchType:MATCH_TYPES.languageSpecificLocale}};var n=y.objects.find((function(e){return e.languageCode===a}));return n?{value:{match:n.identifier,matchType:MATCH_TYPES.language}}:void 0};try{for(var g=__values(h),m=g.next();!m.done;m=g.next()){var p=s(j=m.value);if("object"==typeof p)return p.value}}catch(e){r={error:e}}finally{try{m&&!m.done&&(a=g.return)&&a.call(g)}finally{if(r)throw r.error}}var _=function(e){var r=y.objects.find((function(r){return r.languageCode===e.languageCode}));if(r)return{value:{match:r.identifier,matchType:MATCH_TYPES.relatedLocale}}};try{for(var C=__values(h),T=C.next();!T.done;T=C.next()){var w=_(j=T.value);if("object"==typeof w)return w.value}}catch(e){l={error:e}}finally{try{T&&!T.done&&(i=C.return)&&i.call(C)}finally{if(l)throw l.error}}var L=y.objects.filter((function(e){return e.languageCode===n.languageCode&&e.identifier!==n.identifier})).map((function(e){return e.countryCode}));if(L.length>0)try{for(var b=__values(v),S=b.next();!S.done;S=b.next()){if(void 0!==(j=S.value).locale&&void 0!==j.countryCode&&L.includes(j.countryCode))return{match:"".concat(n.languageCode,"-").concat(j.countryCode),matchType:MATCH_TYPES.languageCountry}}}catch(e){c={error:e}}finally{try{S&&!S.done&&(u=b.return)&&u.call(b)}finally{if(c)throw c.error}}if(null==t?void 0:t.matchCountry){var A=function(e){var r=y.objects.find((function(r){return r.countryCode===e.countryCode}));if(r)return{value:{match:r.identifier,matchType:MATCH_TYPES.country}}};try{for(var E=__values(v),x=E.next();!x.done;x=E.next()){var j,P=A(j=x.value);if("object"==typeof P)return P.value}}catch(e){f={error:e}}finally{try{x&&!x.done&&(d=E.return)&&d.call(E)}finally{if(f)throw f.error}}}return{match:n.identifier,matchType:MATCH_TYPES.defaultLocale}}();return(null==t?void 0:t.returnMatchType)?l:l.match};

package/lib/esm/locales.d.ts

@@ -1,11 +1,11 @@
 /** Class to manage a locale identifier using the BCP 47 `language`-`country` format. */
 export declare class Locale {
+    /** The ISO 639-1 alpha-2 language code. */
+    readonly languageCode: 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: string;
-    /** The ISO 639-1 alpha-2 language code. */
-    readonly languageCode: string;
     /**
      * Create a new `Locale` object.
      *
@@ -16,10 +16,10 @@ export declare class Locale {
     constructor(identifier: string);
 }
 export declare class LocaleList {
-    /** 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 ISO 3166-1 alpha-2 country codes. */
+    readonly countries: 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. */

package/lib/esm/locales.js

@@ -1 +1 @@
-var __read=this&&this.__read||function(e,t){var o="function"==typeof Symbol&&e[Symbol.iterator];if(!o)return e;var a,r,i=o.call(e),n=[];try{for(;(void 0===t||t-- >0)&&!(a=i.next()).done;)n.push(a.value)}catch(e){r={error:e}}finally{try{a&&!a.done&&(o=i.return)&&o.call(i)}finally{if(r)throw r.error}}return n},Locale=function(e){if(!isLocale(e,!1))throw new Error("invalid locale identifier '".concat(e,"'"));var t=__read(e.split("-"),2),o=t[0],a=t[1];this.languageCode=o.toLowerCase(),this.countryCode=a.toUpperCase(),this.identifier="".concat(this.languageCode,"-").concat(this.countryCode)};export{Locale};var LocaleList=function(e){var t=this;this.countries=new Set,this.languages=new Set,this.locales=new Set,this.objects=[],e.forEach((function(e){var o=new Locale(e);t.objects.push(o),t.locales.add(o.identifier),t.languages.add(o.languageCode),t.countries.add(o.countryCode)}))};export{LocaleList};export var isLocale=function(e,t){return void 0===t&&(t=!0),new RegExp(/^[a-z]{2}-[A-Z]{2}$/,t?void 0:"i").test(e)};
+var __read=this&&this.__read||function(e,t){var o="function"==typeof Symbol&&e[Symbol.iterator];if(!o)return e;var a,r,i=o.call(e),n=[];try{for(;(void 0===t||t-- >0)&&!(a=i.next()).done;)n.push(a.value)}catch(e){r={error:e}}finally{try{a&&!a.done&&(o=i.return)&&o.call(i)}finally{if(r)throw r.error}}return n},Locale=function(e){if(!isLocale(e,!1))throw new Error("invalid locale identifier '".concat(e,"'"));var t=__read(e.split("-"),2),o=t[0],a=t[1];this.languageCode=o.toLowerCase(),this.countryCode=a.toUpperCase(),this.identifier="".concat(this.languageCode,"-").concat(this.countryCode)};export{Locale};var LocaleList=function(e){var t=this;this.languages=new Set,this.countries=new Set,this.locales=new Set,this.objects=[],e.forEach((function(e){var o=new Locale(e);t.objects.push(o),t.locales.add(o.identifier),t.languages.add(o.languageCode),t.countries.add(o.countryCode)}))};export{LocaleList};export var isLocale=function(e,t){return void 0===t&&(t=!0),new RegExp(/^[a-z]{2}-[A-Z]{2}$/,t?void 0:"i").test(e)};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resolve-accept-language",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Resolve the preferred locale based on the value of an `Accept-Language` HTTP header.",
   "keywords": [
     "accept-language",
@@ -53,18 +53,18 @@
     "@eslint/js": "^8.57.0",
     "@release-it/conventional-changelog": "8.0.1",
     "@types/jest": "29.5.12",
-    "@types/node": "^20.11.24",
+    "@types/node": "^20.11.25",
     "@typescript-eslint/eslint-plugin": "7.1.1",
     "@typescript-eslint/parser": "7.1.1",
     "depcheck": "^1.4.7",
-    "dotenv-cli": "7.3.0",
+    "dotenv-cli": "7.4.1",
     "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-jsdoc": "48.2.1",
     "eslint-plugin-json-files": "4.1.0",
     "eslint-plugin-prefer-arrow-functions": "3.3.2",
     "eslint-plugin-prettier": "5.1.3",
@@ -77,9 +77,9 @@
     "prettier-plugin-organize-imports": "3.2.4",
     "prettier-plugin-sh": "0.14.0",
     "release-it": "17.1.1",
-    "terser": "^5.28.1",
+    "terser": "^5.29.1",
     "ts-jest": "29.1.2",
-    "typescript": "5.3.3"
+    "typescript": "5.4.2"
   },
   "engines": {
     "node": "^14.18.1 || >=16.0.0"