feat: add toLocale util (#18)

* feat: add `toLocale` util

* refactor

README.md

@@ -121,6 +121,7 @@ You can play the below examples:
 ### Common
 
 - `isLocale`
+- `toLocale`
 - `parseAcceptLanguage`
 - `validateLanguageTag`
 - `normalizeLanguageName`

src/http.ts

@@ -4,6 +4,7 @@ import {
   isURLSearchParams,
   parseAcceptLanguage,
   pathLanguageParser,
+  toLocale,
   validateLanguageTag,
 } from './shared.ts'
 import { ACCEPT_LANGUAGE_HEADER } from './constants.ts'
@@ -136,7 +137,7 @@ export function getHeaderLanguagesWithGetter(
 }
 
 export function getLocaleWithGetter(getter: () => string): Intl.Locale {
-  return new Intl.Locale(getter())
+  return toLocale(getter())
 }
 
 export function validateLocale(locale: string | Intl.Locale): void {

src/shared.test.ts

@@ -5,6 +5,7 @@ import {
   normalizeLanguageName,
   parseAcceptLanguage,
   pathLanguageParser,
+  toLocale,
   validateLanguageTag,
 } from './shared.ts'
 
@@ -18,6 +19,21 @@ describe('isLocale', () => {
   })
 })
 
+describe('toLocale', () => {
+  test('language tag', () => {
+    expect(toLocale('en-US').toString()).toBe('en-US')
+  })
+
+  test('Intl.Locale instance', () => {
+    const locale = new Intl.Locale('en-US')
+    expect(toLocale(locale).toString()).toBe('en-US')
+  })
+
+  test('invalid language tag', () => {
+    expect(() => toLocale('')).toThrowError(RangeError)
+  })
+})
+
 describe('parseAcceptLanguage', () => {
   test('basic: ja,en-US;q=0.7,en;q=0.3', () => {
     expect(parseAcceptLanguage('ja,en-US;q=0.7,en;q=0.3')).toEqual([

src/shared.ts

@@ -20,6 +20,19 @@ export function isLocale(val: unknown): val is Intl.Locale {
   return toTypeString(val) === '[object Intl.Locale]'
 }
 
+/**
+ * returns the {@link Intl.Locale | locale}
+ *
+ * @param {string | Intl.Locale} val The value for which the 'locale' is requested.
+ *
+ * @throws {RangeError} Throws the {@link RangeError} if `val` is not a well-formed BCP 47 language tag.
+ *
+ * @returns {Intl.Locale} The locale
+ */
+export function toLocale(val: string | Intl.Locale): Intl.Locale {
+  return isLocale(val) ? val : new Intl.Locale(val)
+}
+
 /**
  * parse `accept-language` header string
  *