docs: add API docs

Author: kazupon

README.md

@@ -74,59 +74,9 @@ You can play the below examples:
 - 🌍 [Browser](https://github.com/intlify/utils/tree/main/examples/browser):
   `npm run play:browser`
 
-## 🔨 Utilities
+## 🤝 API
 
-### Common
-
-- `isLocale`
-- `toLocale`
-- `parseAcceptLanguage`
-- `validateLangTag`
-- `normalizeLanguageName`
-
-You can do `import { ... } from '@intlify/utils'` the above utilities
-
-### Navigator
-
-- `getNavigatorLocales`
-- `getNavigatorLocale`
-
-You can do `import { ... } from '@intlify/utils'` the above utilities
-
-<!-- eslint-disable markdown/no-missing-label-refs -->
-
-> [!NOTE]
-> for Node.js You need to do `import { ... } from '@intlify/utils/node'`
-
-<!-- eslint-enable markdown/no-missing-label-refs -->
-
-### HTTP
-
-- `getHeaderLanguages`
-- `getHeaderLanguage`
-- `getHeaderLocales`
-- `getHeaderLocale`
-- `getCookieLocale`
-- `setCookieLocale`
-- `getPathLocale`
-- `getQueryLocale`
-- `tryHeaderLocales`
-- `tryHeaderLocale`
-- `tryCookieLocale`
-- `tryPathLocale`
-- `tryQueryLocale`
-
-The about utilities functions accept Web APIs such as [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) that is supported by JS environments (such as Deno, Bun, and Browser)
-
-#### Specialized environments
-
-If you will use Node.js and H3, You can do `import { ... } from '@intlify/utils/{ENV}'` the above utilities.
-
-The namespace `{ENV}` is one of the following:
-
-- `node`: accept `IncomingMessage` and `Outgoing` by Node.js [http](https://nodejs.org/api/http.html) module
-- `h3`: accept `H3Event` by HTTP framework [h3](https://github.com/unjs/h3)
-- `hono`: accept `Context` by edge-side web framework [hono](https://github.com/honojs/hono)
+See the [API docs](./docs/index.md)
 
 ## 🙌 Contributing guidelines
 

docs/default/functions/createPathIndexLanguageParser.md

@@ -0,0 +1,25 @@
+[**@intlify/utils**](../../index.md)
+
+***
+
+[@intlify/utils](../../index.md) / [default](../index.md) / createPathIndexLanguageParser
+
+# Function: createPathIndexLanguageParser()
+
+```ts
+function createPathIndexLanguageParser(index): PathLanguageParser;
+```
+
+create a parser, which can split with slash `/`
+
+## Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `index` | `number` | `0` | An index of locale, which is included in path |
+
+## Returns
+
+`PathLanguageParser`
+
+A return a parser, which has `PathLanguageParser` interface

docs/default/functions/getCookieLocale.md

@@ -0,0 +1,46 @@
+[**@intlify/utils**](../../index.md)
+
+***
+
+[@intlify/utils](../../index.md) / [default](../index.md) / getCookieLocale
+
+# Function: getCookieLocale()
+
+```ts
+function getCookieLocale(request, options): Locale;
+```
+
+get locale from cookie
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | `Request` | The Request \| request |
+| `options` | `CookieLocaleOptions` | The CookieLocaleOptions \| cookie locale options, `lang` option is `en-US` as default, you must specify the language tag with the [BCP 47 syntax](https://datatracker.ietf.org/doc/html/rfc4646#section-2.1). `name` option is `i18n_locale` as default. |
+
+## Returns
+
+`Locale`
+
+The locale that resolved from cookie
+
+## Example
+
+example for Web API request on Deno:
+
+```ts
+import { getCookieLocale } from 'https://esm.sh/@intlify/utils/web'
+
+Deno.serve({
+  port: 8080,
+}, (req) => {
+  const locale = getCookieLocale(req)
+  console.log(locale) // output `Intl.Locale` instance
+  // ...
+})
+```
+
+## Throws
+
+Throws a `RangeError` if `lang` option or cookie name value are not a well-formed BCP 47 language tag.

docs/default/functions/getHeaderLanguage.md

@@ -0,0 +1,46 @@
+[**@intlify/utils**](../../index.md)
+
+***
+
+[@intlify/utils](../../index.md) / [default](../index.md) / getHeaderLanguage
+
+# Function: getHeaderLanguage()
+
+```ts
+function getHeaderLanguage(request, options): string;
+```
+
+get language from header
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | `Request` | The Request \| request |
+| `options` | `HeaderOptions` | The HeaderOptions \| header options object |
+
+## Returns
+
+`string`
+
+The **first language tag** of header, if header is not exists, or `*` (any language), return empty string.
+
+## Description
+
+parse header string, default `accept-language`. if you use `accept-language`, this function returns the **first language tag** of `accept-language` header.
+
+## Example
+
+example for Web API request on Deno:
+
+```ts
+import { getAcceptLanguage } from 'https://esm.sh/@intlify/utils/web'
+
+Deno.serve({
+  port: 8080,
+}, (req) => {
+  const langTag = getHeaderLanguage(req)
+  // ...
+  return new Response(`accepted language: ${langTag}`
+})
+```

docs/default/functions/getHeaderLanguages.md

@@ -0,0 +1,46 @@
+[**@intlify/utils**](../../index.md)
+
+***
+
+[@intlify/utils](../../index.md) / [default](../index.md) / getHeaderLanguages
+
+# Function: getHeaderLanguages()
+
+```ts
+function getHeaderLanguages(request, options): string[];
+```
+
+get languages from header
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | `Request` | The Request \| request |
+| `options` | `HeaderOptions` | The HeaderOptions \| header options object. `name` option is `accept-language` as default. |
+
+## Returns
+
+`string`[]
+
+The array of language tags, if you use `accept-language` header and `*` (any language) or empty string is detected, return an empty array.
+
+## Description
+
+parse header string, default `accept-language` header
+
+## Example
+
+example for Web API request on Deno:
+
+```ts
+import { getHeaderLanguages } from 'https://esm.sh/@intlify/utils/web'
+
+Deno.serve({
+  port: 8080,
+}, (req) => {
+  const langTags = getHeaderLanguages(req)
+  // ...
+  return new Response(`accepted languages: ${langTags.join(', ')}`
+})
+```

docs/default/functions/getHeaderLocale.md

@@ -0,0 +1,51 @@
+[**@intlify/utils**](../../index.md)
+
+***
+
+[@intlify/utils](../../index.md) / [default](../index.md) / getHeaderLocale
+
+# Function: getHeaderLocale()
+
+```ts
+function getHeaderLocale(request, options): Locale;
+```
+
+get locale from header
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | `Request` | The Request \| request |
+| `options` | `HeaderOptions` & `object` | The HeaderOptions \| header options object. `lang` option is `en-US` as default, you must specify the language tag with the [BCP 47 syntax](https://datatracker.ietf.org/doc/html/rfc4646#section-2.1). `name` option is `accept-language` as default, and `parser` option is `parseDefaultHeader` as default. |
+
+## Returns
+
+`Locale`
+
+The first locale that resolved from header string. if you use `accept-language` header and `*` (any language) or empty string is detected, return `en-US`.
+
+## Description
+
+wrap language tag with Intl.Locale \| locale, languages tags will be parsed from `accept-language` header as default.
+
+## Example
+
+```ts
+example for Web API request on Bun:
+
+import { getHeaderLocale } from '@intlify/utils/web'
+
+Bun.serve({
+  port: 8080,
+  fetch(req) {
+    const locale = getHeaderLocale(req)
+    // ...
+    return new Response(`accpected locale: ${locale.toString()}`)
+  },
+})
+```
+
+## Throws
+
+Throws the `RangeError` if `lang` option or header are not a well-formed BCP 47 language tag.

docs/default/functions/getHeaderLocales.md

@@ -0,0 +1,51 @@
+[**@intlify/utils**](../../index.md)
+
+***
+
+[@intlify/utils](../../index.md) / [default](../index.md) / getHeaderLocales
+
+# Function: getHeaderLocales()
+
+```ts
+function getHeaderLocales(request, options): Locale[];
+```
+
+get locales from header
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `request` | `Request` | The Request \| request |
+| `options` | `HeaderOptions` | The HeaderOptions \| header options object |
+
+## Returns
+
+`Locale`[]
+
+The locales that wrapped from header, if you use `accept-language` header and `*` (any language) or empty string is detected, return an empty array.
+
+## Description
+
+wrap language tags with Intl.Locale \| locale, languages tags will be parsed from `accept-language` header as default.
+
+## Example
+
+example for Web API request on Bun:
+
+```ts
+import { getHeaderLocales } from '@intlify/utils/web'
+
+Bun.serve({
+  port: 8080,
+  fetch(req) {
+    const locales = getHeaderLocales(req)
+    // ...
+    return new Response(`accpected locales: ${locales.map(locale => locale.toString()).join(', ')}`)
+  },
+})
+```
+
+## Throws
+
+Throws the `RangeError` if header are not a well-formed BCP 47 language tag.

docs/default/functions/getNavigatorLocale.md

@@ -0,0 +1,24 @@
+[**@intlify/utils**](../../index.md)
+
+***
+
+[@intlify/utils](../../index.md) / [default](../index.md) / getNavigatorLocale
+
+# Function: getNavigatorLocale()
+
+```ts
+function getNavigatorLocale(): Locale;
+```
+
+get navigator locale
+
+## Returns
+
+`Locale`
+
+The Intl.Locale \| locale
+
+## Description
+
+This function is the `Intl.Locale` wrapper of `navigator.language`.
+The value depends on the environments. if you use this function on the browser, you can get the languages, that are set in the browser, else if you use this function on the server side (Deno only), that value is the language set in the server.

docs/default/functions/getNavigatorLocales.md

@@ -0,0 +1,24 @@
+[**@intlify/utils**](../../index.md)
+
+***
+
+[@intlify/utils](../../index.md) / [default](../index.md) / getNavigatorLocales
+
+# Function: getNavigatorLocales()
+
+```ts
+function getNavigatorLocales(): readonly Locale[];
+```
+
+get navigator locales
+
+## Returns
+
+readonly `Locale`[]
+
+The array of Intl.Locale \| locales
+
+## Description
+
+This function is a wrapper that maps in `Intl.Locale` in `navigator.languages`.
+This function return values depends on the environments. if you use this function on the browser, you can get the languages, that are set in the browser, else if you use this function on the server side (Deno only), that value is the languages set in the server.