@alxia/language 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+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

@@ -0,0 +1,96 @@
+# @alxia/language
+
+The request's language for [alxia](https://www.npmjs.com/package/@alxia/core),
+typed as the languages you support — never a string a client made up. No
+dependency.
+
+```sh
+bun add @alxia/language @alxia/core
+bun add -d typescript
+```
+
+## Usage
+
+```ts
+import { alxia } from '@alxia/core';
+import { language } from '@alxia/language';
+
+const supported = ['en', 'fr', 'pt-BR'] as const;
+const greetings: Record<(typeof supported)[number], string> = { en: 'Hello', fr: 'Bonjour', 'pt-BR': 'Olá' };
+
+const app = alxia()
+	.use(language({ supported, fallback: 'en' }))
+	.get('/', ({ language, reply }) => reply(200, greetings[language])); // 'en' | 'fr' | 'pt-BR'
+
+app.listen(3000);
+```
+
+It reads, in `order`:
+
+| source | |
+| --- | --- |
+| `query` | `?lang=fr` |
+| `cookie` | `language=fr` |
+| `path` | `/fr/products`, at `pathIndex` |
+| `header` | `Accept-Language`, by weight: `de, fr-CA;q=0.8` is `fr` |
+
+then `resolve(ctx)` — a user's saved preference — then `fallback`. A tag
+matches whatever its case, by its base language (`fr-CA` for `fr`), or by a
+region of it (`pt` for `pt-BR`). `languageSource` says which source decided.
+
+Every response says `Content-Language`, and `Vary` by the headers it read.
+With `persist`, a language the query named is kept in the cookie.
+
+## Reading the app's context
+
+Annotate `resolve`'s parameter to decide by what an earlier plugin added —
+the language a signed-in user saved. The plugin then requires it: an app
+that does not give `user` before it cannot use it.
+
+```ts
+import { alxia, type BaseContext } from '@alxia/core';
+import { language } from '@alxia/language';
+
+const byUser = language({
+	supported: ['en', 'fr'],
+	fallback: 'en',
+	order: ['query', 'cookie'],
+	resolve: ({ user }: BaseContext & { user: { language: string } | null }) => user?.language,
+});
+
+alxia().use(auth).use(byUser); // auth derives user
+alxia().use(byUser); // a compile error: this app gives no `user`
+```
+
+A `resolve` annotated `any` would require nothing, so the plugin is refused
+on every app: annotate what it reads, or leave it unannotated.
+
+## Options
+
+| option | default | |
+| --- | --- | --- |
+| `supported` | required | the languages: `language`'s type |
+| `fallback` | required | one of them; the types refuse another |
+| `order` | `['query', 'cookie', 'header']` | |
+| `query`, `cookie` | `lang`, `language` | their names |
+| `pathIndex` | 0 | |
+| `persist` | `false` | `true`, or `{ maxAge, secure }` |
+| `contentLanguage` | `true` | |
+| `resolve` | none | `(ctx) => string \| undefined`; annotate `ctx` to read what an earlier plugin adds |
+| `vary` | none | the headers `resolve` reads, added to `Vary` |
+
+## API
+
+| export | |
+| --- | --- |
+| `language(options)` | the plugin: `language`, `languageSource` |
+| `LanguageOptions` | its options: `supported`, `fallback`, `order`, `query`, `cookie`, `pathIndex`, `persist`, `contentLanguage`, `resolve`, `vary` |
+| `negotiate(header, supported)` | the supported language `Accept-Language` prefers |
+| `parseAcceptLanguage(header)`, `match(tag, supported)` | its parts |
+| `LanguageContext`, `LanguageSource`, `Accepted` | its types |
+
+## Documentation
+
+- [Guide](https://github.com/softistx/alxia/tree/develop/packages/language/docs): every option with its default and an example, how the language is found and `Accept-Language` negotiated, reading what an earlier plugin added, the typed context, and the headers the plugin adds.
+- [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/language/docs/troubleshooting.md): an error, or a response in the wrong language, and what to do about it.
+- [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/language/docs/roadmap.md): what is coming, and what is not planned.

package/dist/decide.d.ts

@@ -0,0 +1,23 @@
+import { type BaseContext } from '@alxia/core';
+import type { LanguageContext, LanguageSource } from './types';
+/** `language()`'s options, their defaults applied. */
+export interface Settings<L extends string> {
+    readonly supported: readonly L[];
+    readonly fallback: L;
+    readonly order: readonly LanguageSource[];
+    readonly query: string;
+    readonly cookie: string;
+    readonly pathIndex: number;
+    readonly persist: {
+        readonly maxAge?: number;
+        readonly secure?: boolean;
+    } | undefined;
+    readonly contentLanguage: boolean;
+    readonly resolve: ((ctx: BaseContext) => string | undefined) | undefined;
+    readonly vary: readonly string[];
+}
+/** The request's language: each source in `order`, then `resolve`, then `fallback`. */
+export declare function decide<L extends string>(settings: Settings<L>, ctx: BaseContext): LanguageContext<L>;
+/** What the response says of it: `Vary`, `Content-Language`, the kept cookie. */
+export declare function respond<L extends string>(settings: Settings<L>, ctx: BaseContext, found: LanguageContext<L>): void;
+//# sourceMappingURL=decide.d.ts.map

package/dist/decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../src/decide.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAQ,MAAM,aAAa,CAAC;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/D,sDAAsD;AACtD,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EACb;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACvD,SAAS,CAAC;IACb,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IACzE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AA+BD,uFAAuF;AACvF,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EACtC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,GAAG,EAAE,WAAW,GACd,eAAe,CAAC,CAAC,CAAC,CAWpB;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EACvC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GACvB,IAAI,CAgBN"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { type LanguageOptions, language } from './language';
+export { type Accepted, match, negotiate, parseAcceptLanguage, } from './negotiate';
+export type { LanguageContext, LanguageSource } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EACN,KAAK,QAAQ,EACb,KAAK,EACL,SAAS,EACT,mBAAmB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,124 @@
+// src/language.ts
+import { definePlugin } from "@alxia/core";
+
+// src/decide.ts
+import { vary } from "@alxia/core";
+
+// src/negotiate.ts
+function parseAcceptLanguage(header) {
+  if (!header)
+    return [];
+  return header.split(",").map((part, index) => {
+    const [tag = "", ...params] = part.trim().split(";");
+    const q = params.map((param) => param.trim()).find((param) => param.startsWith("q="));
+    const weight = q === undefined ? 1 : Number(q.slice(2));
+    return {
+      tag: tag.trim(),
+      q: Number.isFinite(weight) ? weight : 0,
+      index
+    };
+  }).filter((entry) => entry.tag !== "" && entry.q > 0).sort((a, b) => b.q - a.q || a.index - b.index).map(({ tag, q }) => ({ tag, q }));
+}
+function match(tag, supported) {
+  const wanted = tag.toLowerCase();
+  if (wanted === "*")
+    return supported[0];
+  const exact = supported.find((language) => language.toLowerCase() === wanted);
+  if (exact !== undefined)
+    return exact;
+  const base = wanted.split("-")[0] ?? wanted;
+  return supported.find((language) => language.toLowerCase() === base) ?? supported.find((language) => language.toLowerCase().split("-")[0] === base);
+}
+function negotiate(header, supported) {
+  for (const { tag } of parseAcceptLanguage(header)) {
+    const found = match(tag, supported);
+    if (found !== undefined)
+      return found;
+  }
+  return;
+}
+
+// src/decide.ts
+function read(settings, ctx, source) {
+  const { supported } = settings;
+  switch (source) {
+    case "query": {
+      const value = ctx.url.searchParams.get(settings.query);
+      return value === null ? undefined : match(value, supported);
+    }
+    case "cookie": {
+      const value = new Bun.CookieMap(ctx.request.headers.get("cookie") ?? "").get(settings.cookie);
+      return value === null ? undefined : match(value, supported);
+    }
+    case "path": {
+      const segment = ctx.url.pathname.split("/").filter(Boolean)[settings.pathIndex];
+      return segment === undefined ? undefined : match(segment, supported);
+    }
+    case "header":
+      return negotiate(ctx.request.headers.get("accept-language"), supported);
+  }
+}
+function decide(settings, ctx) {
+  for (const source of settings.order) {
+    const value = read(settings, ctx, source);
+    if (value !== undefined)
+      return { language: value, languageSource: source };
+  }
+  const resolved = settings.resolve?.(ctx);
+  const value = resolved === undefined ? undefined : match(resolved, settings.supported);
+  return value === undefined ? { language: settings.fallback, languageSource: "fallback" } : { language: value, languageSource: "resolve" };
+}
+function respond(settings, ctx, found) {
+  const { headers, cookies } = ctx.set;
+  if (settings.order.includes("header"))
+    vary(headers, "Accept-Language");
+  if (settings.order.includes("cookie"))
+    vary(headers, "Cookie");
+  for (const name of settings.vary)
+    vary(headers, name);
+  if (settings.contentLanguage)
+    headers.set("content-language", found.language);
+  const { persist } = settings;
+  if (persist !== undefined && found.languageSource === "query") {
+    cookies.set(settings.cookie, found.language, {
+      path: "/",
+      sameSite: "lax",
+      httpOnly: false,
+      secure: persist.secure ?? true,
+      maxAge: persist.maxAge ?? 365 * 24 * 60 * 60
+    });
+  }
+}
+
+// src/language.ts
+function language(options) {
+  const settings = {
+    supported: options.supported,
+    fallback: options.fallback,
+    order: options.order ?? ["query", "cookie", "header"],
+    query: options.query ?? "lang",
+    cookie: options.cookie ?? "language",
+    pathIndex: options.pathIndex ?? 0,
+    persist: options.persist === true ? {} : options.persist === false ? undefined : options.persist,
+    contentLanguage: options.contentLanguage !== false,
+    resolve: options.resolve,
+    vary: options.vary ?? []
+  };
+  if (!settings.supported.includes(settings.fallback)) {
+    throw new TypeError(`language(): the fallback "${settings.fallback}" is not supported`);
+  }
+  return definePlugin()((app) => app.derive((ctx) => {
+    const found = decide(settings, ctx);
+    respond(settings, ctx, found);
+    return found;
+  }));
+}
+export {
+  language,
+  match,
+  negotiate,
+  parseAcceptLanguage
+};
+
+//# debugId=0E86121386DC727A64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/language.ts", "../src/decide.ts", "../src/negotiate.ts"],
+  "sourcesContent": [
+    "import { type BaseContext, definePlugin, type RequiresOf } from '@alxia/core';\nimport { decide, respond, type Settings } from './decide';\nimport type { LanguageContext, LanguageSource } from './types';\n\n/**\n * `Ctx` is the type `resolve`'s parameter is annotated with —\n * `BaseContext & { user: User }`, or `{ user: User }` alone — and\n * `BaseContext` when it is not.\n */\nexport interface LanguageOptions<\n\tL extends string,\n\tCtx extends object = BaseContext,\n> {\n\t/** The languages the app speaks: the context's `language` is one of them. */\n\treadonly supported: readonly L[];\n\t/** The one it speaks when the request names none it does. */\n\treadonly fallback: NoInfer<L>;\n\t/** Where it looks, in order. `query`, `cookie`, then `header` by default. */\n\treadonly order?: readonly LanguageSource[];\n\t/** The query parameter: `?lang=fr`. `lang` by default. */\n\treadonly query?: string;\n\t/** The cookie. `language` by default. */\n\treadonly cookie?: string;\n\t/** The index of the path segment: `/fr/products` is 0. 0 by default. */\n\treadonly pathIndex?: number;\n\t/**\n\t * Whether a language named by the query is kept in the cookie, so the\n\t * next request speaks it too. Off by default.\n\t */\n\treadonly persist?:\n\t\t| boolean\n\t\t| { readonly maxAge?: number; readonly secure?: boolean };\n\t/** Says `Content-Language` on every response. On by default. */\n\treadonly contentLanguage?: boolean;\n\t/**\n\t * Decides itself, after every source: a user's saved preference. Annotate\n\t * its parameter to read what an earlier plugin adds —\n\t * `(ctx: BaseContext & { user: User })` — and the app that uses the\n\t * plugin must then give it.\n\t */\n\treadonly resolve?: (ctx: BaseContext & Ctx) => string | undefined;\n\t/**\n\t * The request headers `resolve` reads, added to `Vary` so a cache keeps\n\t * one response per value: `['authorization']`. None by default.\n\t */\n\treadonly vary?: readonly string[];\n}\n\n/**\n * The request's language, as a plugin: the routes declared after it read\n * `language`, typed as one of `supported` — never a string a client made\n * up. It is read from the query, a cookie, a path segment and\n * `Accept-Language` — weights, `fr-CA` for `fr`, `fr` for `fr-FR` — in the\n * order given, then `fallback`.\n *\n * ```ts\n * app.use(language({ supported: ['en', 'fr'], fallback: 'en' }))\n *    .get('/', ({ language, reply }) => reply(200, language)); // 'en' | 'fr'\n * ```\n */\nexport function language<\n\tconst L extends string,\n\tCtx extends object = BaseContext,\n>(options: LanguageOptions<L, Ctx>) {\n\tconst settings: Settings<L> = {\n\t\tsupported: options.supported,\n\t\tfallback: options.fallback,\n\t\torder: options.order ?? ['query', 'cookie', 'header'],\n\t\tquery: options.query ?? 'lang',\n\t\tcookie: options.cookie ?? 'language',\n\t\tpathIndex: options.pathIndex ?? 0,\n\t\tpersist:\n\t\t\toptions.persist === true\n\t\t\t\t? {}\n\t\t\t\t: options.persist === false\n\t\t\t\t\t? undefined\n\t\t\t\t\t: options.persist,\n\t\tcontentLanguage: options.contentLanguage !== false,\n\t\t// `use` has checked that the app gives what `resolve` reads.\n\t\tresolve: options.resolve as Settings<L>['resolve'],\n\t\tvary: options.vary ?? [],\n\t};\n\tif (!settings.supported.includes(settings.fallback)) {\n\t\tthrow new TypeError(\n\t\t\t`language(): the fallback \"${settings.fallback}\" is not supported`,\n\t\t);\n\t}\n\treturn definePlugin<RequiresOf<Ctx, 'resolve'>>()((app) =>\n\t\tapp.derive((ctx): LanguageContext<L> => {\n\t\t\tconst found = decide(settings, ctx);\n\t\t\trespond(settings, ctx, found);\n\t\t\treturn found;\n\t\t}),\n\t);\n}\n",
+    "import { type BaseContext, vary } from '@alxia/core';\nimport { match, negotiate } from './negotiate';\nimport type { LanguageContext, LanguageSource } from './types';\n\n/** `language()`'s options, their defaults applied. */\nexport interface Settings<L extends string> {\n\treadonly supported: readonly L[];\n\treadonly fallback: L;\n\treadonly order: readonly LanguageSource[];\n\treadonly query: string;\n\treadonly cookie: string;\n\treadonly pathIndex: number;\n\treadonly persist:\n\t\t| { readonly maxAge?: number; readonly secure?: boolean }\n\t\t| undefined;\n\treadonly contentLanguage: boolean;\n\treadonly resolve: ((ctx: BaseContext) => string | undefined) | undefined;\n\treadonly vary: readonly string[];\n}\n\n/** The language of one source, if it names one `supported` has. */\nfunction read<L extends string>(\n\tsettings: Settings<L>,\n\tctx: BaseContext,\n\tsource: LanguageSource,\n): L | undefined {\n\tconst { supported } = settings;\n\tswitch (source) {\n\t\tcase 'query': {\n\t\t\tconst value = ctx.url.searchParams.get(settings.query);\n\t\t\treturn value === null ? undefined : match(value, supported);\n\t\t}\n\t\tcase 'cookie': {\n\t\t\tconst value = new Bun.CookieMap(\n\t\t\t\tctx.request.headers.get('cookie') ?? '',\n\t\t\t).get(settings.cookie);\n\t\t\treturn value === null ? undefined : match(value, supported);\n\t\t}\n\t\tcase 'path': {\n\t\t\tconst segment = ctx.url.pathname.split('/').filter(Boolean)[\n\t\t\t\tsettings.pathIndex\n\t\t\t];\n\t\t\treturn segment === undefined ? undefined : match(segment, supported);\n\t\t}\n\t\tcase 'header':\n\t\t\treturn negotiate(ctx.request.headers.get('accept-language'), supported);\n\t}\n}\n\n/** The request's language: each source in `order`, then `resolve`, then `fallback`. */\nexport function decide<L extends string>(\n\tsettings: Settings<L>,\n\tctx: BaseContext,\n): LanguageContext<L> {\n\tfor (const source of settings.order) {\n\t\tconst value = read(settings, ctx, source);\n\t\tif (value !== undefined) return { language: value, languageSource: source };\n\t}\n\tconst resolved = settings.resolve?.(ctx);\n\tconst value =\n\t\tresolved === undefined ? undefined : match(resolved, settings.supported);\n\treturn value === undefined\n\t\t? { language: settings.fallback, languageSource: 'fallback' }\n\t\t: { language: value, languageSource: 'resolve' };\n}\n\n/** What the response says of it: `Vary`, `Content-Language`, the kept cookie. */\nexport function respond<L extends string>(\n\tsettings: Settings<L>,\n\tctx: BaseContext,\n\tfound: LanguageContext<L>,\n): void {\n\tconst { headers, cookies } = ctx.set;\n\tif (settings.order.includes('header')) vary(headers, 'Accept-Language');\n\tif (settings.order.includes('cookie')) vary(headers, 'Cookie');\n\tfor (const name of settings.vary) vary(headers, name);\n\tif (settings.contentLanguage) headers.set('content-language', found.language);\n\tconst { persist } = settings;\n\tif (persist !== undefined && found.languageSource === 'query') {\n\t\tcookies.set(settings.cookie, found.language, {\n\t\t\tpath: '/',\n\t\t\tsameSite: 'lax',\n\t\t\thttpOnly: false,\n\t\t\tsecure: persist.secure ?? true,\n\t\t\tmaxAge: persist.maxAge ?? 365 * 24 * 60 * 60,\n\t\t});\n\t}\n}\n",
+    "/** One language a client accepts, with its weight. */\nexport interface Accepted {\n\treadonly tag: string;\n\treadonly q: number;\n}\n\n/** `Accept-Language` as its languages, the most wanted first; a weight of 0 refused. */\nexport function parseAcceptLanguage(\n\theader: string | null | undefined,\n): Accepted[] {\n\tif (!header) return [];\n\treturn header\n\t\t.split(',')\n\t\t.map((part, index) => {\n\t\t\tconst [tag = '', ...params] = part.trim().split(';');\n\t\t\tconst q = params\n\t\t\t\t.map((param) => param.trim())\n\t\t\t\t.find((param) => param.startsWith('q='));\n\t\t\tconst weight = q === undefined ? 1 : Number(q.slice(2));\n\t\t\treturn {\n\t\t\t\ttag: tag.trim(),\n\t\t\t\tq: Number.isFinite(weight) ? weight : 0,\n\t\t\t\tindex,\n\t\t\t};\n\t\t})\n\t\t.filter((entry) => entry.tag !== '' && entry.q > 0)\n\t\t.sort((a, b) => b.q - a.q || a.index - b.index)\n\t\t.map(({ tag, q }) => ({ tag, q }));\n}\n\n/**\n * The supported language a tag names: itself, whatever its case; its base\n * language — `fr-CA` to `fr`; or a region of it — `fr` to `fr-FR`.\n * `undefined` when none.\n */\nexport function match<const L extends string>(\n\ttag: string,\n\tsupported: readonly L[],\n): L | undefined {\n\tconst wanted = tag.toLowerCase();\n\tif (wanted === '*') return supported[0];\n\tconst exact = supported.find((language) => language.toLowerCase() === wanted);\n\tif (exact !== undefined) return exact;\n\tconst base = wanted.split('-')[0] ?? wanted;\n\treturn (\n\t\tsupported.find((language) => language.toLowerCase() === base) ??\n\t\tsupported.find((language) => language.toLowerCase().split('-')[0] === base)\n\t);\n}\n\n/** The supported language `Accept-Language` prefers, or `undefined`. */\nexport function negotiate<const L extends string>(\n\theader: string | null | undefined,\n\tsupported: readonly L[],\n): L | undefined {\n\tfor (const { tag } of parseAcceptLanguage(header)) {\n\t\tconst found = match(tag, supported);\n\t\tif (found !== undefined) return found;\n\t}\n\treturn undefined;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "0E86121386DC727A64756E2164756E21",
+  "names": []
+}

package/dist/language.d.ts

@@ -0,0 +1,57 @@
+import { type BaseContext, type RequiresOf } from '@alxia/core';
+import type { LanguageContext, LanguageSource } from './types';
+/**
+ * `Ctx` is the type `resolve`'s parameter is annotated with —
+ * `BaseContext & { user: User }`, or `{ user: User }` alone — and
+ * `BaseContext` when it is not.
+ */
+export interface LanguageOptions<L extends string, Ctx extends object = BaseContext> {
+    /** The languages the app speaks: the context's `language` is one of them. */
+    readonly supported: readonly L[];
+    /** The one it speaks when the request names none it does. */
+    readonly fallback: NoInfer<L>;
+    /** Where it looks, in order. `query`, `cookie`, then `header` by default. */
+    readonly order?: readonly LanguageSource[];
+    /** The query parameter: `?lang=fr`. `lang` by default. */
+    readonly query?: string;
+    /** The cookie. `language` by default. */
+    readonly cookie?: string;
+    /** The index of the path segment: `/fr/products` is 0. 0 by default. */
+    readonly pathIndex?: number;
+    /**
+     * Whether a language named by the query is kept in the cookie, so the
+     * next request speaks it too. Off by default.
+     */
+    readonly persist?: boolean | {
+        readonly maxAge?: number;
+        readonly secure?: boolean;
+    };
+    /** Says `Content-Language` on every response. On by default. */
+    readonly contentLanguage?: boolean;
+    /**
+     * Decides itself, after every source: a user's saved preference. Annotate
+     * its parameter to read what an earlier plugin adds —
+     * `(ctx: BaseContext & { user: User })` — and the app that uses the
+     * plugin must then give it.
+     */
+    readonly resolve?: (ctx: BaseContext & Ctx) => string | undefined;
+    /**
+     * The request headers `resolve` reads, added to `Vary` so a cache keeps
+     * one response per value: `['authorization']`. None by default.
+     */
+    readonly vary?: readonly string[];
+}
+/**
+ * The request's language, as a plugin: the routes declared after it read
+ * `language`, typed as one of `supported` — never a string a client made
+ * up. It is read from the query, a cookie, a path segment and
+ * `Accept-Language` — weights, `fr-CA` for `fr`, `fr` for `fr-FR` — in the
+ * order given, then `fallback`.
+ *
+ * ```ts
+ * app.use(language({ supported: ['en', 'fr'], fallback: 'en' }))
+ *    .get('/', ({ language, reply }) => reply(200, language)); // 'en' | 'fr'
+ * ```
+ */
+export declare function language<const L extends string, Ctx extends object = BaseContext>(options: LanguageOptions<L, Ctx>): import("@alxia/core").Alxia<RequiresOf<Ctx, "resolve"> & LanguageContext<L>, import("@alxia/core").Empty, "", never> & import("@alxia/core").Requiring<RequiresOf<Ctx, "resolve">>;
+//# sourceMappingURL=language.d.ts.map

package/dist/language.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language.d.ts","sourceRoot":"","sources":["../src/language.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAC/B,CAAC,SAAS,MAAM,EAChB,GAAG,SAAS,MAAM,GAAG,WAAW;IAEhC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EACd,OAAO,GACP;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3D,gEAAgE;IAChE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;IAClE;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACvB,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,GAAG,SAAS,MAAM,GAAG,WAAW,EAC/B,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,GAAG,CAAC,sLA+BjC"}

package/dist/negotiate.d.ts

@@ -0,0 +1,16 @@
+/** One language a client accepts, with its weight. */
+export interface Accepted {
+    readonly tag: string;
+    readonly q: number;
+}
+/** `Accept-Language` as its languages, the most wanted first; a weight of 0 refused. */
+export declare function parseAcceptLanguage(header: string | null | undefined): Accepted[];
+/**
+ * The supported language a tag names: itself, whatever its case; its base
+ * language — `fr-CA` to `fr`; or a region of it — `fr` to `fr-FR`.
+ * `undefined` when none.
+ */
+export declare function match<const L extends string>(tag: string, supported: readonly L[]): L | undefined;
+/** The supported language `Accept-Language` prefers, or `undefined`. */
+export declare function negotiate<const L extends string>(header: string | null | undefined, supported: readonly L[]): L | undefined;
+//# sourceMappingURL=negotiate.d.ts.map

package/dist/negotiate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiate.d.ts","sourceRoot":"","sources":["../src/negotiate.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,QAAQ,EAAE,CAmBZ;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAC3C,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,SAAS,CAAC,EAAE,GACrB,CAAC,GAAG,SAAS,CAUf;AAED,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAC/C,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,SAAS,EAAE,SAAS,CAAC,EAAE,GACrB,CAAC,GAAG,SAAS,CAMf"}

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+/** Where a language is read from. */
+export type LanguageSource = 'query' | 'cookie' | 'path' | 'header';
+/** What the routes behind the plugin read. */
+export interface LanguageContext<L extends string> {
+    readonly language: L;
+    /** Where it came from: `fallback` when nothing named one. */
+    readonly languageSource: LanguageSource | 'resolve' | 'fallback';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpE,8CAA8C;AAC9C,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM;IAChD,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,EAAE,cAAc,GAAG,SAAS,GAAG,UAAU,CAAC;CACjE"}

package/docs/README.md

@@ -0,0 +1,13 @@
+# @alxia/language documentation
+
+The [package README](../README.md) is the short version. This folder is
+the long one: every option with its default and an example, how a
+request's language is found and how `Accept-Language` is negotiated, what
+the routes behind the plugin read, and what to do when a response is not in
+the language you expected.
+
+| Page | Read it when |
+| --- | --- |
+| [Guide](guide.md) | choosing the sources and their order, reading the language from the path, keeping a choice in a cookie, deciding by what an earlier plugin added, typing what the routes read, caching the responses, or testing them |
+| [Troubleshooting](troubleshooting.md) | the plugin threw at start-up, `tsc` refused an option or a route, or a response is in the wrong language |
+| [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |