@alxia/language 0.1.2 → 0.3.0

package/README.md

@@ -39,12 +39,13 @@ 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.
+With `persist`, a language the query named is kept in the cookie. Given to
+`use` on the app, it runs on every request: a 404 says `Content-Language` too.
 
 ## 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
+Annotate `resolve`'s parameter to decide by what an earlier middleware added —
+the language a signed-in user saved. The middleware then requires it: an app
 that does not give `user` before it cannot use it.
 
 ```ts
@@ -58,11 +59,11 @@ const byUser = language({
 	resolve: ({ user }: BaseContext & { user: { language: string } | null }) => user?.language,
 });
 
-alxia().use(auth).use(byUser); // auth derives user
+alxia().plugin(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
+A `resolve` annotated `any` would require nothing, so the middleware is refused
 on every app: annotate what it reads, or leave it unannotated.
 
 ## Options
@@ -76,21 +77,22 @@ on every app: annotate what it reads, or leave it unannotated.
 | `pathIndex` | 0 | |
 | `persist` | `false` | `true`, or `{ maxAge, secure }` |
 | `contentLanguage` | `true` | |
-| `resolve` | none | `(ctx) => string \| undefined`; annotate `ctx` to read what an earlier plugin adds |
+| `resolve` | none | `(ctx) => string \| undefined`; annotate `ctx` to read what an earlier middleware adds |
 | `vary` | none | the headers `resolve` reads, added to `Vary` |
 
 ## API
 
 | export | |
 | --- | --- |
-| `language(options)` | the plugin: `language`, `languageSource` |
+| `language(options)` | the middleware, given to `app.use`: it adds `language` and `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 |
+| `LanguageMiddleware<L, Requires>` | what `language()` returns: a middleware adding `LanguageContext<L>`, requiring of the app what `resolve` reads |
 
 ## 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.
+- [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 middleware added, the typed context, and the headers the middleware 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/index.d.ts

@@ -1,4 +1,4 @@
-export { type LanguageOptions, language } from './language';
+export { type LanguageMiddleware, 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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,QAAQ,GACR,MAAM,YAAY,CAAC;AACpB,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

@@ -1,5 +1,8 @@
 // src/language.ts
-import { definePlugin } from "@alxia/core";
+import {
+  defineMiddleware,
+  markFactory
+} from "@alxia/core";
 
 // src/decide.ts
 import { vary } from "@alxia/core";
@@ -107,12 +110,13 @@ function language(options) {
   if (!settings.supported.includes(settings.fallback)) {
     throw new TypeError(`language(): the fallback "${settings.fallback}" is not supported`);
   }
-  return definePlugin()((app) => app.derive((ctx) => {
+  return defineMiddleware()(function language(ctx, next) {
     const found = decide(settings, ctx);
     respond(settings, ctx, found);
-    return found;
-  }));
+    return next(found);
+  });
 }
+markFactory(language);
 export {
   language,
   match,
@@ -120,5 +124,5 @@ export {
   parseAcceptLanguage
 };
 
-//# debugId=0E86121386DC727A64756E2164756E21
+//# debugId=5CF534D30FB9E72064756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -2,11 +2,11 @@
   "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 {\n\ttype BaseContext,\n\tdefineMiddleware,\n\ttype Empty,\n\ttype Middleware,\n\tmarkFactory,\n\ttype Next,\n\ttype RequiresOf,\n} 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 * What `language()` makes: a middleware that gives `language`, one of `L`,\n * and requires `Requires` of the app — what `resolve` reads.\n */\nexport type LanguageMiddleware<\n\tL extends string,\n\tRequires extends object = Empty,\n> = Middleware<Requires, Promise<Next<LanguageContext<L>>>>;\n\n/**\n * The request's language, as a middleware: 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>(\n\toptions: LanguageOptions<L, Ctx>,\n): LanguageMiddleware<L, RequiresOf<Ctx, 'resolve'>> {\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// `app.plugin` 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 defineMiddleware<RequiresOf<Ctx, 'resolve'>>()(\n\t\tfunction language(ctx, next) {\n\t\t\tconst found: LanguageContext<L> = decide(settings, ctx);\n\t\t\trespond(settings, ctx, found);\n\t\t\treturn next(found);\n\t\t},\n\t);\n}\n\nmarkFactory(language);\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",
+  "mappings": "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",
+  "debugId": "5CF534D30FB9E72064756E2164756E21",
   "names": []
 }

package/dist/language.d.ts

@@ -1,4 +1,4 @@
-import { type BaseContext, type RequiresOf } from '@alxia/core';
+import { type BaseContext, type Empty, type Middleware, type Next, type RequiresOf } from '@alxia/core';
 import type { LanguageContext, LanguageSource } from './types';
 /**
  * `Ctx` is the type `resolve`'s parameter is annotated with —
@@ -42,7 +42,12 @@ export interface LanguageOptions<L extends string, Ctx extends object = BaseCont
     readonly vary?: readonly string[];
 }
 /**
- * The request's language, as a plugin: the routes declared after it read
+ * What `language()` makes: a middleware that gives `language`, one of `L`,
+ * and requires `Requires` of the app — what `resolve` reads.
+ */
+export type LanguageMiddleware<L extends string, Requires extends object = Empty> = Middleware<Requires, Promise<Next<LanguageContext<L>>>>;
+/**
+ * The request's language, as a middleware: 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
@@ -53,5 +58,5 @@ export interface LanguageOptions<L extends string, Ctx extends object = BaseCont
  *    .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">>;
+export declare function language<const L extends string, Ctx extends object = BaseContext>(options: LanguageOptions<L, Ctx>): LanguageMiddleware<L, RequiresOf<Ctx, 'resolve'>>;
 //# sourceMappingURL=language.d.ts.map

package/dist/language.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"language.d.ts","sourceRoot":"","sources":["../src/language.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,WAAW,EAEhB,KAAK,KAAK,EACV,KAAK,UAAU,EAEf,KAAK,IAAI,EACT,KAAK,UAAU,EACf,MAAM,aAAa,CAAC;AAErB,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;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAC7B,CAAC,SAAS,MAAM,EAChB,QAAQ,SAAS,MAAM,GAAG,KAAK,IAC5B,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACvB,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,GAAG,SAAS,MAAM,GAAG,WAAW,EAEhC,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,GAAG,CAAC,GAC9B,kBAAkB,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CA+BnD"}

package/docs/README.md

@@ -3,11 +3,11 @@
 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 routes behind the middleware 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 |
+| [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 middleware added, typing what the routes read, caching the responses, or testing them |
+| [Troubleshooting](troubleshooting.md) | `language()` 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 |

package/docs/guide.md

@@ -28,8 +28,11 @@ client that names no language it supports gets `Hello`. `current` is typed
 ```ts
 function language<const L extends string, Ctx extends object = BaseContext>(
 	options: LanguageOptions<L, Ctx>,
-): Alxia<RequiresOf<Ctx> & LanguageContext<L>, Empty, '', never> &
-	Requiring<RequiresOf<Ctx>>;
+): LanguageMiddleware<L, RequiresOf<Ctx, 'resolve'>>;
+
+// A middleware: it gives `language`, and requires of the app what `resolve` reads.
+type LanguageMiddleware<L extends string, Requires extends object = Empty> =
+	Middleware<Requires, Promise<Next<LanguageContext<L>>>>;
 
 interface LanguageOptions<L extends string, Ctx extends object = BaseContext> {
 	readonly supported: readonly L[];
@@ -54,11 +57,13 @@ type `resolve`'s parameter is annotated with. `RequiresOf<Ctx>`,
 see
 [Reading the app's context](#reading-the-apps-context).
 
-`language()` returns an app plugin: pass it to `use`, called. It is a
-`derive`, so it applies to the routes declared **after** it — in the same
-app, or inside the [group](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/groups-and-plugins.md)
-it is used in — and adds `language` and `languageSource` to their context.
-A route declared before it neither runs it nor reads them.
+`language()` returns a middleware: pass it to `app.use`, called. A `use()` on
+the app runs on every request, in declaration order, a request no route
+matches included, and adds `language` and `languageSource` to what is
+declared **after** it: the middlewares and the routes. Inside a
+[group](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/groups-and-plugins.md)
+it applies to the group's routes only. A route declared before it neither
+runs it nor reads them.
 
 It throws once, when it is created, if `fallback` is not one of
 `supported`:
@@ -82,7 +87,7 @@ for when they cannot.
 | `cookie` | `string` | `'language'` | the cookie read, and written by `persist` |
 | `pathIndex` | `number` | `0` | the path segment read by the `path` source: `/fr/products` is 0 |
 | `persist` | `boolean \| { maxAge?, secure? }` | `false` | a language the query named is written to the cookie |
-| `contentLanguage` | `boolean` | `true` | `Content-Language` on every response the plugin runs for |
+| `contentLanguage` | `boolean` | `true` | `Content-Language` on every response the middleware runs for |
 | `resolve` | `(ctx: BaseContext & Ctx) => string \| undefined` | none | decides after every source, before `fallback`; its annotated parameter types what it reads |
 | `vary` | `readonly string[]` | none | the request headers `resolve` reads, added to `Vary` |
 
@@ -105,7 +110,7 @@ language({ supported, fallback: 'en' });
 ```
 
 `fallback` must be one of them; the types refuse another (`fallback: 'de'`
-is a compile error), and so does the plugin, at start-up.
+is a compile error), and so does `language()`, at start-up.
 
 ### `order`
 
@@ -141,7 +146,7 @@ language({ supported: ['en', 'fr'], fallback: 'en', order: ['path'], pathIndex:
 // /shop/fr/products → 'fr'
 ```
 
-The plugin reads the segment; it does not route on it or remove it. The
+The middleware reads the segment; it does not route on it or remove it. The
 routes still declare it, as a parameter:
 
 ```ts
@@ -150,7 +155,7 @@ const app = alxia()
 	.get('/:lang/products', ({ language: current, reply }) => reply(200, current));
 
 await app.request('/fr/products'); // 'fr'
-await app.request('/products');    // 404: no route matches; the plugin never runs
+await app.request('/products');    // 404: no route matches (it still says Content-Language)
 ```
 
 A segment is matched like any other tag, so `/fr-ca/products` is `fr` too.
@@ -184,8 +189,8 @@ the cookie or the header sets nothing. For the cookie to be read back,
 
 ### `contentLanguage`
 
-On by default: every response of a route behind the plugin says
-`Content-Language: <language>`. A route that sets its own wins over it:
+On by default: every response of a request the middleware runs on says
+`Content-Language: <language>`, a 404 included when it is used on the app. A route that sets its own wins over it:
 
 ```ts
 .get('/legal', ({ reply }) => reply(200, legalText, { headers: { 'content-language': 'fr' } }));
@@ -214,27 +219,27 @@ language({
 ```
 
 `vary` names the request headers `resolve` reads, so a shared cache keeps
-one response per value; the plugin cannot see what a function reads.
+one response per value; the middleware cannot see what a function reads.
 
 It receives the request's `BaseContext` — `request`, `url`, `ip`,
 `pathParams`, `set` — and, when its parameter is annotated, what an earlier
-plugin added: see [Reading the app's context](#reading-the-apps-context). It
+middleware added: see [Reading the app's context](#reading-the-apps-context). It
 returns a tag, or `undefined` for none. The tag is matched against
 `supported` like any other: a tag it does not support is ignored, and
 `fallback` decides. It is synchronous: a preference kept in a database is
 either written to the cookie when the user saves it — see
 [the realistic setup](#a-realistic-setup) — or loaded by an async `derive`
-or plugin before `language()`, which `resolve` then reads — see
+or middleware before `language()`, which `resolve` then reads — see
 [Reading the app's context](#reading-the-apps-context).
 
 ### Reading the app's context
 
-To decide by what an earlier plugin added, such as a signed-in `user` and
+To decide by what an earlier middleware added, such as a signed-in `user` and
 the language they saved, annotate `resolve`'s parameter. `language()` infers
 what it reads from that annotation — `supported` still types `language` —
-and the plugin is a
+and the middleware requires it, as a
 [`definePlugin`](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/writing-a-plugin.md#a-plugin-that-needs-an-earlier-one)
-plugin: an app that does not give `user` before it cannot use it.
+plugin does: an app that does not give `user` before it cannot use it.
 
 ```ts
 import { alxia, type BaseContext } from '@alxia/core';
@@ -254,26 +259,26 @@ const byUser = language({
 });
 
 const app = alxia()
-	.use(auth) // derives user: User | null
+	.plugin(auth) // an app: derives user: User | null
 	.use(byUser)
 	.get('/', ({ language: current, reply }) => reply(200, current)); // 'en' | 'fr'
 
 alxia().use(byUser);
-// error: the plugin reads "user", which this app's context does not give: use the plugin that adds it first
+// error: Property 'user' is missing in type 'BaseContext & Empty' but required in type '{ user: User | null; }'
 ```
 
 The annotation may be `BaseContext & { user: User }` or `{ user: User }`
-alone; either way the plugin requires `{ user: User }`. An app whose `user`
+alone; either way the middleware requires `{ user: User }`. An app whose `user`
 has a type that does not fit it is refused too —
-`the plugin reads "user", which this app's context gives with another type` —
-while a narrower one passes: an app deriving `user: User` may use a plugin
+`Types of property 'user' are incompatible` —
+while a narrower one passes: an app deriving `user: User` may use a middleware
 that reads `User | null`. Annotating a key `BaseContext` already has with
 a type it does not give — `({ url }: { url: string })` — is refused the
 same way.
-A `resolve` left unannotated reads `BaseContext` only, and the plugin
+A `resolve` left unannotated reads `BaseContext` only, and the middleware
 requires nothing.
 Annotated `unknown` or `object`, it requires nothing either. Annotated
-`any`, it would read anything and require nothing, so the plugin is
+`any`, it would read anything and require nothing, so the middleware is
 refused on every app instead:
 [`the plugin's resolve reads its context as any: annotate what it reads, or leave it unannotated`](troubleshooting.md#the-plugins-resolve-reads-its-context-as-any-annotate-what-it-reads-or-leave-it-unannotated).
 
@@ -387,11 +392,11 @@ function negotiate<const L extends string>(header: string | null | undefined, su
 
 The three are exported for code outside a request — a background job
 choosing an email's language from a saved header, a WebSocket upgrade —
-and return the same answers the plugin would.
+and return the same answers the middleware would.
 
 ## The typed context
 
-The routes behind the plugin read:
+What the routes and middlewares after it read:
 
 ```ts
 interface LanguageContext<L extends string> {
@@ -448,7 +453,7 @@ so a shared cache keeps one copy per language rather than serving the first
 one to everyone. The query and the path are part of the URL, and need no
 `Vary`. What `resolve` reads is added only when the `vary` option names it.
 
-The plugin adds to `ctx.set.headers`, and a reply's own `Vary` adds to it
+The middleware adds to `ctx.set.headers`, and a reply's own `Vary` adds to it
 rather than replacing it:
 
 ```ts
@@ -462,8 +467,11 @@ the cache the same headers, so it keys by them:
 `cache({ ttl: 60, vary: ['accept-language', 'cookie'] })`. A response that
 sets a cookie — a `persist` from the query — is not cached.
 
-A request that matches no route — a `404`, a `405` — never reaches the
-plugin, so it carries none of these headers.
+A request that matches no route — a `404`, a `405` — runs the app's
+`use()` middlewares, so with `language()` on the app it carries these
+headers too. Inside a `group`, the middleware runs for the group's routes
+only: an unmatched request, even one under the group's prefix, carries
+none of them.
 
 ## A realistic setup
 
@@ -489,7 +497,7 @@ export const app = alxia()
 		language({
 			supported,
 			fallback: 'en',
-			persist: { secure: process.env['NODE_ENV'] === 'production' },
+			persist: { secure: Bun.env.NODE_ENV !== 'development' }, // read at runtime: bun build inlines process.env
 		}),
 	)
 	.get('/', ({ language: current, reply }) => reply(200, messages[current].welcome))
@@ -499,11 +507,9 @@ export const app = alxia()
 		set.cookies.set('language', chosen, { path: '/', sameSite: 'lax', maxAge: 365 * 24 * 60 * 60 });
 		return reply(200, { language: chosen });
 	});
-
-export type App = typeof app;
 ```
 
-The saved choice is the `language` cookie, which the plugin reads on every
+The saved choice is the `language` cookie, which the middleware reads on every
 request after, before the browser's languages. `secure` is off outside
 production, so the cookie survives a plain-`http` development server.
 
@@ -548,6 +554,6 @@ describe('language', () => {
 ```
 
 [`@alxia/i18n`](https://www.npmjs.com/package/@alxia/i18n) builds on this
-plugin — its options pass through — and adds `t()` bound to the request's
+middleware — its options pass through — and adds `t()` bound to the request's
 language. When something does not behave as described here,
 [Troubleshooting](troubleshooting.md) starts from the symptom.

package/docs/roadmap.md

@@ -7,7 +7,7 @@ number on it. Every release, with each change it made, is in
 
 ## Now
 
-Nothing scheduled yet.
+- **A middleware, not a plugin (0.4).** `app.use(language({ ... }))` runs on every request, a 404 included, which then says `Content-Language` and `Vary` too. `app.plugin(language(...))`, the deprecated plugin form, was removed with alxia 0.5: give it to `use`.
 
 ## Next
 

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting
 
-Each entry is headed by the text you see: the error the plugin throws at
+Each entry is headed by the text you see: the error `language()` throws at
 start-up, an error from `tsc`, or — for a trap that prints nothing — what
 the response does that you did not expect.
 
@@ -12,13 +12,13 @@ the response does that you did not expect.
 
 - [`Type '"de"' is not assignable to type '"en" | "fr"'`](#type-de-is-not-assignable-to-type-en--fr)
 - [`Property 'language' does not exist on type 'Context<Empty, "/", Empty>'`](#property-language-does-not-exist-on-type-contextempty--empty)
-- [`Type 'Alxia<Empty, Empty, "", never>' is missing the following properties from type 'LanguageOptions<string, BaseContext>': supported, fallback`](#type-alxiaempty-empty--never-is-missing-the-following-properties-from-type-languageoptionsstring-basecontext-supported-fallback)
+- [`Type 'LanguageMiddleware<string, Empty>' is not assignable to type '"this looks like a factory given uncalled: call it, as use(cors()) and not use(cors)"'`](#type-languagemiddlewarestring-empty-is-not-assignable-to-type-this-looks-like-a-factory-given-uncalled-call-it-as-usecors-and-not-usecors)
 - [`Element implicitly has an 'any' type because expression of type 'string' can't be used to index type '{ en: string; fr: string; }'`](#element-implicitly-has-an-any-type-because-expression-of-type-string-cant-be-used-to-index-type--en-string-fr-string-)
 - [`Type 'string | null' is not assignable to type 'string | undefined'`](#type-string--null-is-not-assignable-to-type-string--undefined)
 - [`Type 'Promise<string>' is not assignable to type 'string'`](#type-promisestring-is-not-assignable-to-type-string)
 - [`Property 'user' does not exist on type 'BaseContext'`](#property-user-does-not-exist-on-type-basecontext)
-- [`the plugin reads "user", which this app's context does not give: use the plugin that adds it first`](#the-plugin-reads-user-which-this-apps-context-does-not-give-use-the-plugin-that-adds-it-first)
-- [`the plugin reads "user", which this app's context gives with another type`](#the-plugin-reads-user-which-this-apps-context-gives-with-another-type)
+- [`Property 'user' is missing in type 'BaseContext & Empty' but required in type '{ user: User | null; }'`](#property-user-is-missing-in-type-basecontext--empty-but-required-in-type--user-user--null-)
+- [`Types of property 'user' are incompatible`](#types-of-property-user-are-incompatible)
 - [`the plugin's resolve reads its context as any: annotate what it reads, or leave it unannotated`](#the-plugins-resolve-reads-its-context-as-any-annotate-what-it-reads-or-leave-it-unannotated)
 
 **Responses**
@@ -79,13 +79,12 @@ error TS2339: Property 'language' does not exist on type 'Context<Empty, "/", Em
 ```
 
 **When:** a route reads `language` but is declared before
-`.use(language(…))`, or in another app or group than the one that uses it.
+`.use(language(…))`, or in another app or group than the one that mounts it.
 
-**Why:** the plugin is a route hook: it applies to the routes declared
-after it, at runtime and in the types alike. A route before it never runs
-it.
+**Why:** the middleware applies to what is declared after it, at runtime
+and in the types alike. A route before it never runs it.
 
-**Fix:** use the plugin first:
+**Fix:** `use` it first:
 
 ```ts
 const app = alxia()
@@ -93,21 +92,27 @@ const app = alxia()
 	.get('/', ({ language: current, reply }) => reply(200, current));
 ```
 
-### `Type 'Alxia<Empty, Empty, "", never>' is missing the following properties from type 'LanguageOptions<string, BaseContext>': supported, fallback`
+### `Type 'LanguageMiddleware<string, Empty>' is not assignable to type '"this looks like a factory given uncalled: call it, as use(cors()) and not use(cors)"'`
 
 ```text
-error TS2769: No overload matches this call.
-  Overload 1 of 2, '(plugin: (app: Alxia<Empty, Empty, "", never>) => …): Alxia<…>', gave the following error.
-    Argument of type '<const L extends string, Ctx extends object = BaseContext>(options: LanguageOptions<L, Ctx>) => Alxia<RequiresOf<Ctx, "resolve"> & LanguageContext<L>, Empty, "", never> & Requiring<...>' is not assignable to parameter of type '(app: Alxia<Empty, Empty, "", never>) => …'.
-      Types of parameters 'options' and 'app' are incompatible.
-        Type 'Alxia<Empty, Empty, "", never>' is missing the following properties from type 'LanguageOptions<string, BaseContext>': supported, fallback
+error TS2345: Argument of type '<const L extends string, Ctx extends object = BaseContext>(options: LanguageOptions<L, Ctx>) => LanguageMiddleware<L, RequiresOf<Ctx, "resolve">>' is not assignable to parameter of type '…'.
+  …
+      Type 'LanguageMiddleware<string, Empty>' is not assignable to type '"this looks like a factory given uncalled: call it, as use(cors()) and not use(cors)"'.
 ```
 
-**When:** `app.use(language)`, without calling it.
+**When:** `app.use(language)`, the factory given uncalled. The message names
+`cors` as its example, whichever factory it is. It also throws where it is
+declared, since alxia 0.5, rather than answering each request with a 500:
 
-**Why:** `language` makes the plugin from its options; it is not the plugin.
+```text
+TypeError: use(): argument 1 looks like a factory (language): call it, use(language())
+```
 
-**Fix:**
+**Why:** `language` makes the middleware; it is not the middleware. A
+function that returns a function is no middleware, and `language` is marked
+as a factory, so `use`, a route and `plugin` refuse it.
+
+**Fix:** call it with its options:
 
 ```ts
 alxia().use(language({ supported: ['en', 'fr'], fallback: 'en' }));
@@ -183,7 +188,7 @@ database or a session store.
 **Why:** `resolve` is synchronous: it runs on every request, after the
 sources, and returns a tag or `undefined`.
 
-**Fix:** keep the preference where the plugin already reads it. When the
+**Fix:** keep the preference where the middleware already reads it. When the
 user saves it, write it to the cookie; every request after reads it from
 there, before `Accept-Language`:
 
@@ -202,7 +207,7 @@ const app = alxia()
 
 Do the same at sign-in, from the stored preference.
 
-Or load it before the plugin, in an async `derive` or the plugin that
+Or load it before the middleware, in an async `derive` or the middleware that
 signs the user in, and annotate `resolve` to read it — see
 [Reading the app's context](guide.md#reading-the-apps-context):
 
@@ -224,18 +229,18 @@ const app = alxia()
 error TS2339: Property 'user' does not exist on type 'BaseContext'.
 ```
 
-**When:** `resolve` reads something a `derive` or a plugin before
+**When:** `resolve` reads something a `derive` or a middleware before
 `language()` added — a user, a session — and its parameter is not
 annotated: `resolve: (ctx) => ctx.user.language`.
 
 **Why:** an unannotated `resolve` is typed with the request's `BaseContext`
-— `request`, `url`, `ip`, `pathParams`, `set` — not with what other hooks
+— `request`, `url`, `ip`, `pathParams`, `set` — not with what other middlewares
 added. `language()` is built before it is used, so it cannot see the app it
 will be used on.
 
 **Fix:** annotate the parameter with what it reads. `language()` infers it
-from the annotation, and the app that uses the plugin must then give it,
-before the plugin:
+from the annotation, and the app that uses the middleware must then give it,
+before it:
 
 ```ts
 import type { BaseContext } from '@alxia/core';
@@ -246,55 +251,59 @@ const byUser = language({
 	resolve: ({ user }: BaseContext & { user: User }) => user.language ?? undefined,
 });
 
-alxia().use(auth).use(byUser); // auth derives user
+alxia().plugin(auth).use(byUser); // auth derives user
 ```
 
 See [Reading the app's context](guide.md#reading-the-apps-context).
 
-### `the plugin reads "user", which this app's context does not give: use the plugin that adds it first`
+### `Property 'user' is missing in type 'BaseContext & Empty' but required in type '{ user: User | null; }'`
 
 ```text
 error TS2769: No overload matches this call.
   …
-        Types of property ''~requires'' are incompatible.
-          Type '{ user: User; }' is not assignable to type '"the plugin reads \"user\", which this app's context does not give: use the plugin that adds it first"'.
+          Type 'BaseContext & Empty' is not assignable to type 'MiddlewareContext<{ user: User | null; }>'.
+            Property 'user' is missing in type 'BaseContext & Empty' but required in type '{ user: User | null; }'.
 ```
 
-**When:** the plugin's `resolve` is annotated to read `user`, and it is
+**When:** the middleware's `resolve` is annotated to read `user`, and it is
 used on an app — or in a group — whose context has no `user` at that point:
-`alxia().use(byUser)`, or `use(byUser)` before `use(auth)`.
+`alxia().use(byUser)`, or `use(byUser)` before `plugin(auth)`.
 
-**Why:** an annotated `resolve` makes the plugin require what it reads, and
-`use` checks the app's context against it, so `resolve` never runs without
+**Why:** an annotated `resolve` makes the middleware require what it reads, and
+`app.use` checks the app's context against it, so `resolve` never runs without
 it.
 
-**Fix:** use the plugin that adds `user` first, with the type `resolve`
+**Fix:** mount what adds `user` first, with the type `resolve`
 reads:
 
 ```ts
-alxia().use(auth).use(byUser);
+alxia().plugin(auth).use(byUser);
 ```
 
 More on this message in
-[`@alxia/core`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/core/docs/troubleshooting.md#the-plugin-reads--which-this-apps-context-does-not-give-use-the-plugin-that-adds-it-first).
+[`@alxia/core`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/core/docs/troubleshooting.md#the-plugin-reads--which-this-apps-context-does-not-give-add-the-plugin-or-middleware-that-gives-it-first).
 
-### `the plugin reads "user", which this app's context gives with another type`
+### `Types of property 'user' are incompatible`
 
 ```text
 error TS2769: No overload matches this call.
   …
-          Type '{ user: User; }' is not assignable to type '"the plugin reads \"user\", which this app's context gives with another type"'.
+          Type 'BaseContext & Empty & { user: User | null; }' is not assignable to type 'MiddlewareContext<{ user: User; }>'.
+            Type 'BaseContext & Empty & { user: User | null; }' is not assignable to type '{ user: User; }'.
+              Types of property 'user' are incompatible.
+                Type 'User | null' is not assignable to type 'User'.
+                  Type 'null' is not assignable to type 'User'.
 ```
 
 **When:** the app gives a `user`, but of a type that does not fit the one
 `resolve`'s parameter is annotated with: a `User | null` where `resolve`
 reads `User`, or a user of another shape.
 
-**Why:** `use` checks each key the plugin reads against the app's context;
+**Why:** `app.use` checks each key the middleware reads against the app's context;
 a narrower type passes, a wider or different one does not.
 
 **Fix:** annotate `resolve` with the type the app gives — `User | null`,
-handled inside — or narrow it in the plugin before:
+handled inside — or narrow it in the middleware before:
 
 ```ts
 language({
@@ -312,20 +321,20 @@ More on this message in
 ```text
 error TS2769: No overload matches this call.
   …
-        Types of property ''~requires'' are incompatible.
-          Type '{ readonly '~any': "the plugin's resolve reads its context as any: annotate what it reads, or leave it unannotated"; }' is not assignable to type '"the plugin's resolve reads its context as any: annotate what it reads, or leave it unannotated"'.
+          Type 'BaseContext & Empty' is not assignable to type 'MiddlewareContext<{ readonly '~any': "the plugin's resolve reads its context as any: annotate what it reads, or leave it unannotated"; }>'.
+            Property ''~any'' is missing in type 'BaseContext & Empty' but required in type '{ readonly '~any': "the plugin's resolve reads its context as any: annotate what it reads, or leave it unannotated"; }'.
 ```
 
 **When:** `resolve`'s parameter is annotated `any` —
-`resolve: (ctx: any) => ctx.user.language` — and the plugin is used, on
+`resolve: (ctx: any) => ctx.user.language` — and the middleware is used, on
 any app, whatever its context gives.
 
 **Why:** an `any` parameter reads any key and says nothing of what it
-reads, so the plugin would require nothing, and an app without a `user`
-would be accepted, and throw on every request. The plugin is refused
+reads, so the middleware would require nothing, and an app without a `user`
+would be accepted, and throw on every request. It is refused
 instead.
 
-**Fix:** annotate what `resolve` reads, and use the plugin that adds it
+**Fix:** annotate what `resolve` reads, and mount what adds it
 first:
 
 ```ts
@@ -335,7 +344,7 @@ const byUser = language({
 	resolve: ({ user }: BaseContext & { user: User }) => user.language ?? undefined,
 });
 
-alxia().use(auth).use(byUser);
+alxia().plugin(auth).use(byUser);
 ```
 
 Or leave it unannotated when it reads only the request:
@@ -373,7 +382,7 @@ await app.request('/', { headers: { 'accept-language': 'fr-FR,fr;q=0.9,en;q=0.8'
 **When:** a language switcher links to `?lang=fr`; that page is in French,
 the next one, without the query, is not.
 
-**Why:** the query only decides the request that carries it. The plugin
+**Why:** the query only decides the request that carries it. The middleware
 keeps it for the next ones only when all of these hold:
 
 - `persist` is set — it is off by default;
@@ -391,7 +400,7 @@ language({
 	supported: ['en', 'fr'],
 	fallback: 'en',
 	order: ['query', 'cookie', 'header'],
-	persist: { secure: process.env['NODE_ENV'] === 'production' },
+	persist: { secure: Bun.env.NODE_ENV !== 'development' }, // read at runtime: bun build inlines process.env
 });
 ```
 
@@ -400,22 +409,28 @@ language({
 **When:** behind a CDN, a reverse proxy, or `@alxia/cache`, the first
 visitor's language is served to everyone after.
 
-**Why:** the response depends on what the plugin read, and a cache keyed
-on the URL alone ignores it. The plugin says `Vary: Accept-Language,
+**Why:** the response depends on what the middleware read, and a cache keyed
+on the URL alone ignores it. It says `Vary: Accept-Language,
 Cookie` with the default `order`, and a reply's own `Vary` adds to it. Two
 things still leave a header out:
 
 - what `resolve` reads, unless the `vary` option names it;
-- an `onResponse` hook that sets `Vary` with `headers.set` instead of
-  `@alxia/core`'s `vary`, which replaces every name before it.
+- a middleware that sets `Vary` with
+  `headers.set` instead of `@alxia/core`'s `vary`, which replaces every
+  name before it.
 
 **Fix:** name what `resolve` reads, add to `Vary` rather than setting it,
 and give a cache the same headers:
 
 ```ts
-import { alxia, vary, withHeaders } from '@alxia/core';
+import { alxia, defineMiddleware, settle, vary, withHeaders } from '@alxia/core';
 
 alxia()
+	.use(
+		defineMiddleware(async (ctx, next) =>
+			withHeaders(await settle(ctx, next()), (headers) => vary(headers, 'Accept-Encoding')),
+		),
+	)
 	.use(
 		language({
 			supported: ['en', 'fr'],
@@ -423,8 +438,7 @@ alxia()
 			resolve: (ctx) => ctx.request.headers.get('x-preferred-language') ?? undefined,
 			vary: ['X-Preferred-Language'],
 		}),
-	)
-	.onResponse((response) => withHeaders(response, (headers) => vary(headers, 'Accept-Encoding')));
+	);
 // Vary: Accept-Language, Cookie, X-Preferred-Language, Accept-Encoding
 ```
 
@@ -437,9 +451,9 @@ cache({ ttl: 60, vary: ['accept-language', 'cookie', 'x-preferred-language'] });
 **When:** `order` lists `'path'`, and the routes are declared without the
 language segment: `.get('/products', …)`.
 
-**Why:** the plugin reads the segment at `pathIndex`; it does not remove
+**Why:** the middleware reads the segment at `pathIndex`; it does not remove
 it from the path or route on it. `/fr/products` matches no route, so the
-`404` is answered before the plugin runs.
+`404` is answered: the language was read, but no route answers in it.
 
 **Fix:** declare the segment in the routes:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/language",
-	"version": "0.1.2",
+	"version": "0.3.0",
 	"description": "The request's language for alxia, typed as the languages you support: from the query, a cookie, the path or Accept-Language, weights and regions included",
 	"license": "MIT",
 	"type": "module",
@@ -41,11 +41,11 @@
 		]
 	},
 	"devDependencies": {
-		"@alxia/core": "^0.3.0",
+		"@alxia/core": "^0.5.0",
 		"@types/bun": "^1.4.2"
 	},
 	"peerDependencies": {
-		"@alxia/core": "^0.3.0",
+		"@alxia/core": "^0.5.0",
 		"typescript": "^6.0.3 || ^7.0.0"
 	}
 }