BREAKING CHANGE: rename getLocale (#6)

* BREAKING CHANGE: rename `getLocale`

* fix

README.md

@@ -133,7 +133,7 @@ You can do `import { ... } from '@intlify/utils'` the above utilities
 
 - `getAcceptLanguages`
 - `getAcceptLanguage`
-- `getLocale`
+- `getAcceptLocale`
 - `getCookieLocale`
 - `setCookieLocale`
 

playground/browser/src/main.ts

@@ -1,6 +1,7 @@
 import './style.css'
 import intlifyLogo from '/intlify.svg'
 import { setupCounter } from './counter.ts'
+// @ts-expect-error: The URL format of import identifier is not allowd in TS as default.
 import { isLocale } from 'https://esm.sh/@intlify/utils'
 
 document.querySelector<HTMLDivElement>('#app')!.innerHTML = `

src/h3.test.ts

@@ -4,8 +4,8 @@ import supertest from 'supertest'
 import {
   getAcceptLanguage,
   getAcceptLanguages,
+  getAcceptLocale,
   getCookieLocale,
-  getLocale,
   setCookieLocale,
 } from './h3.ts'
 import { DEFAULT_COOKIE_NAME, DEFAULT_LANG_TAG } from './constants.ts'
@@ -97,7 +97,7 @@ describe('getAcceptLanguage', () => {
   })
 })
 
-describe('getLocale', () => {
+describe('getAcceptLocale', () => {
   test('basic', () => {
     const mockEvent = {
       node: {
@@ -109,7 +109,7 @@ describe('getLocale', () => {
         },
       },
     } as H3Event
-    const locale = getLocale(mockEvent)
+    const locale = getAcceptLocale(mockEvent)
 
     expect(locale.baseName).toEqual('en-US')
     expect(locale.language).toEqual('en')
@@ -127,7 +127,7 @@ describe('getLocale', () => {
         },
       },
     } as H3Event
-    const locale = getLocale(mockEvent)
+    const locale = getAcceptLocale(mockEvent)
 
     expect(locale.baseName).toEqual(DEFAULT_LANG_TAG)
   })
@@ -143,7 +143,7 @@ describe('getLocale', () => {
         },
       },
     } as H3Event
-    const locale = getLocale(mockEvent, 'ja-JP')
+    const locale = getAcceptLocale(mockEvent, 'ja-JP')
 
     expect(locale.baseName).toEqual('ja-JP')
   })
@@ -160,7 +160,7 @@ describe('getLocale', () => {
       },
     } as H3Event
 
-    expect(() => getLocale(mockEvent, 'ja-JP')).toThrowError(RangeError)
+    expect(() => getAcceptLocale(mockEvent, 'ja-JP')).toThrowError(RangeError)
   })
 })
 

src/h3.ts

@@ -70,7 +70,9 @@ export function getAcceptLanguage(event: H3Event): string {
 }
 
 /**
- * get locale
+ * get {@link Intl.Locale | locale} from `accept-language` header
+ *
+ * @description wrap with {@link Intl.Locale | locale}
  *
  * @example
  * example for h3:
@@ -93,7 +95,7 @@ export function getAcceptLanguage(event: H3Event): string {
  *
  * @returns {Intl.Locale} The first locale that resolved from `accept-language` header string, first language tag is used. if `*` (any language) or empty string is detected, return `en-US`.
  */
-export function getLocale(
+export function getAcceptLocale(
   event: H3Event,
   lang = DEFAULT_LANG_TAG,
 ): Intl.Locale {

src/node.test.ts

@@ -3,8 +3,8 @@ import supertest from 'supertest'
 import {
   getAcceptLanguage,
   getAcceptLanguages,
+  getAcceptLocale,
   getCookieLocale,
-  getLocale,
   setCookieLocale,
 } from './node.ts'
 import { createServer, IncomingMessage, OutgoingMessage } from 'node:http'
@@ -64,14 +64,14 @@ describe('getAcceptLanguage', () => {
   })
 })
 
-describe('getLocale', () => {
+describe('getAcceptLocale', () => {
   test('basic', () => {
     const mockRequest = {
       headers: {
         'accept-language': 'en-US,en;q=0.9,ja;q=0.8',
       },
     } as IncomingMessage
-    const locale = getLocale(mockRequest)
+    const locale = getAcceptLocale(mockRequest)
 
     expect(locale.baseName).toEqual('en-US')
     expect(locale.language).toEqual('en')
@@ -84,7 +84,7 @@ describe('getLocale', () => {
         'accept-language': '*',
       },
     } as IncomingMessage
-    const locale = getLocale(mockRequest)
+    const locale = getAcceptLocale(mockRequest)
 
     expect(locale.baseName).toEqual(DEFAULT_LANG_TAG)
   })
@@ -95,7 +95,7 @@ describe('getLocale', () => {
         'accept-language': '*',
       },
     } as IncomingMessage
-    const locale = getLocale(mockRequest, 'ja-JP')
+    const locale = getAcceptLocale(mockRequest, 'ja-JP')
 
     expect(locale.baseName).toEqual('ja-JP')
   })
@@ -106,7 +106,7 @@ describe('getLocale', () => {
         'accept-language': 's',
       },
     } as IncomingMessage
-    expect(() => getLocale(mockRequest, 'ja-JP')).toThrowError(RangeError)
+    expect(() => getAcceptLocale(mockRequest, 'ja-JP')).toThrowError(RangeError)
   })
 })
 

src/node.ts

@@ -68,7 +68,9 @@ export function getAcceptLanguage(request: IncomingMessage): string {
 }
 
 /**
- * get locale
+ * get {@link Intl.Locale | locale} from `accept-language` header
+ *
+ * @description wrap with {@link Intl.Locale | locale}
  *
  * @example
  * example for Node.js request:
@@ -91,7 +93,7 @@ export function getAcceptLanguage(request: IncomingMessage): string {
  *
  * @returns {Intl.Locale} The first locale that resolved from `accept-language` header string, first language tag is used. if `*` (any language) or empty string is detected, return `en-US`.
  */
-export function getLocale(
+export function getAcceptLocale(
   request: IncomingMessage,
   lang = DEFAULT_LANG_TAG,
 ): Intl.Locale {

src/web.test.ts

@@ -2,8 +2,8 @@ import { describe, expect, test } from 'vitest'
 import {
   getAcceptLanguage,
   getAcceptLanguages,
+  getAcceptLocale,
   getCookieLocale,
-  getLocale,
   setCookieLocale,
 } from './web.ts'
 import { DEFAULT_COOKIE_NAME, DEFAULT_LANG_TAG } from './constants.ts'
@@ -46,11 +46,11 @@ describe('getAcceptLanguage', () => {
   })
 })
 
-describe('getLocale', () => {
+describe('getAcceptLocale', () => {
   test('basic', () => {
     const mockRequest = new Request('https://example.com')
     mockRequest.headers.set('accept-language', 'en-US,en;q=0.9,ja;q=0.8')
-    const locale = getLocale(mockRequest)
+    const locale = getAcceptLocale(mockRequest)
 
     expect(locale.baseName).toEqual('en-US')
     expect(locale.language).toEqual('en')
@@ -60,23 +60,23 @@ describe('getLocale', () => {
   test('accept-language is any language', () => {
     const mockRequest = new Request('https://example.com')
     mockRequest.headers.set('accept-language', '*')
-    const locale = getLocale(mockRequest)
+    const locale = getAcceptLocale(mockRequest)
 
     expect(locale.baseName).toEqual(DEFAULT_LANG_TAG)
   })
 
   test('specify default language', () => {
     const mockRequest = new Request('https://example.com')
     mockRequest.headers.set('accept-language', '*')
-    const locale = getLocale(mockRequest, 'ja-JP')
+    const locale = getAcceptLocale(mockRequest, 'ja-JP')
 
     expect(locale.baseName).toEqual('ja-JP')
   })
 
   test('RangeError', () => {
     const mockRequest = new Request('https://example.com')
     mockRequest.headers.set('accept-language', 's')
-    expect(() => getLocale(mockRequest, 'ja-JP')).toThrowError(RangeError)
+    expect(() => getAcceptLocale(mockRequest, 'ja-JP')).toThrowError(RangeError)
   })
 })
 

src/web.ts

@@ -67,7 +67,9 @@ export function getAcceptLanguage(request: Request): string {
 }
 
 /**
- * get locale
+ * get {@link Intl.Locale | locale} from `accept-language` header
+ *
+ * @description wrap with {@link Intl.Locale | locale}
  *
  * @example
  * example for Web API request on Bun:
@@ -90,7 +92,7 @@ export function getAcceptLanguage(request: Request): string {
  *
  * @returns {Intl.Locale} The first locale that resolved from `accept-language` header string, first language tag is used. if `*` (any language) or empty string is detected, return `en-US`.
  */
-export function getLocale(
+export function getAcceptLocale(
   request: Request,
   lang = DEFAULT_LANG_TAG,
 ): Intl.Locale {