@alxia/context-storage 0.1.1 → 0.2.0

package/README.md

@@ -41,21 +41,45 @@ The context holds through every `await`, timer and promise of the
 request, and never leaks into another's: twenty concurrent requests read
 twenty contexts.
 
+With `@alxia/core`'s `Register` naming `base`, `contextStorage()` needs no
+type argument: it reads the registered context, `AppContext`. Either way
+the app that mounts it must give that context, a compile error otherwise:
+
+```ts
+declare module '@alxia/core' {
+	interface Register {
+		context: typeof base;
+	}
+}
+
+export const requestContext = contextStorage(); // context(): AppContext
+base.use(requestContext);                       // ok
+alxia().use(requestContext);                    // compile error: Property 'db' is missing in type 'BaseContext & Empty'
+```
+
+Requiring that context of the app is new in 0.4.0: a middleware used on an app
+that does not give it, which read `undefined` at runtime, is now a compile
+error ([Upgrading](https://github.com/softistx/alxia/blob/develop/packages/core/docs/upgrading.md#the-context-registered-once-register-and-defineroutes)).
+
 ## Reading it
 
 | | |
 | --- | --- |
-| `requestContext.context()` | the route's context, typed by the app the plugin was given: the request, `set`, `reply`, and what every hook before it added. Throws outside |
+| `requestContext.context()` | the route's context, typed by the app the middleware was given: the request, `set`, `reply`, and what every middleware before it added. Throws outside |
 | `requestContext.tryContext()` | the same, or `undefined`: code that runs in and out of requests |
 | `getContext<Ctx>()`, `tryGetContext<Ctx>()` | untyped, as `hono/context-storage`'s: `Ctx` is yours to state |
-| `getRequestContext()`, `tryGetRequestContext()` | the request as global hooks see it — in a 404, an `onResponse` — with the `route` it reached and its `error`; the `try` form returns `undefined` outside a request |
+| `getRequestContext()`, `tryGetRequestContext()` | the request as a middleware after it sees it — in a 404 too — with the `route` it reached (`undefined` when none) and its `error`; the `try` form returns `undefined` outside a request |
 | `runWithContext(ctx, work)` | runs `work` with a context: a job, a queue consumer, a test of a service |
 
-Outside a request, `getContext()` throws a `ContextStorageError` coded
-`OUTSIDE_REQUEST`; in a request that reached no route declared after the
-plugin, `NOT_ROUTED`. Declare it before the routes whose code reads it.
+Give it to `use` before the routes whose code reads it, and before the
+middlewares that read the context: it runs on every request the app takes,
+a 404 included. `getRequestContext()` works in every middleware after it;
+`getContext()` only in a request that reached a route. Outside a request,
+or where the middleware did not run (a route declared before it),
+`getContext()` throws a `ContextStorageError` coded `OUTSIDE_REQUEST`; in
+a request that reached no route, `NOT_ROUTED`.
 
-Pass the plugin to `use` called: `use(contextStorage)`, uncalled, is refused by
+Pass it to `app.use` called: `use(contextStorage)`, uncalled, is refused by
 `tsc` (`TS2769`) and throws a `TypeError` at startup
 ([troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/context-storage/docs/troubleshooting.md#typeerror-contextstorage-is-a-factory-usecontextstorage-not-usecontextstorage)).
 
@@ -63,13 +87,15 @@ Pass the plugin to `use` called: `use(contextStorage)`, uncalled, is refused by
 
 | export | |
 | --- | --- |
-| `contextStorage<App>()` | the plugin, with `context()` and `tryContext()` typed by `App` |
-| `ContextStoragePlugin<App>` | its type |
+| `contextStorage<App>()` | the middleware, given to `app.use`, with `context()` and `tryContext()` typed by `App` — by default the app `@alxia/core`'s `Register` names, `BaseContext` when none — and required of the app that mounts it |
+| `StoredContext<App>` | what `context()` returns: `ContextOf<App>`, or `BaseContext` when `App` is no app |
+| `ContextStorageMiddleware<App>` | its type: a middleware with `context()` and `tryContext()` |
+| `ContextStoragePlugin<App>` | deprecated: the former name of `ContextStorageMiddleware` |
 | `getContext`, `tryGetContext`, `getRequestContext`, `tryGetRequestContext`, `runWithContext` | the store, untyped |
 | `ContextStorageError`, `ContextStorageErrorCode` | why there is no context |
 
 ## Documentation
 
-- [Guide](https://github.com/softistx/alxia/tree/develop/packages/context-storage/docs): what the plugin stores and when, reading it from a service or a logger, its typing, where it sits among hooks, what a timer or a detached callback sees, and jobs and tests with `runWithContext`.
+- [Guide](https://github.com/softistx/alxia/tree/develop/packages/context-storage/docs): what the middleware stores and when, reading it from a service or a logger, its typing, where it sits among the other middlewares, what a timer or a detached callback sees, and jobs and tests with `runWithContext`.
 - [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/context-storage/docs/troubleshooting.md): a `ContextStorageError`, the `TypeError` of `use(contextStorage)`, or a `tsc` error, and what to do about it.
 - [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/context-storage/docs/roadmap.md): what is coming, and what is not planned.

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { ContextStorageError, type ContextStorageErrorCode, type ContextStoragePlugin, contextStorage, getContext, getRequestContext, runWithContext, tryGetContext, tryGetRequestContext, } from './storage';
+export { ContextStorageError, type ContextStorageErrorCode, type ContextStorageMiddleware, type ContextStoragePlugin, contextStorage, getContext, getRequestContext, runWithContext, type StoredContext, tryGetContext, tryGetRequestContext, } from './storage';
 //# 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,EACN,mBAAmB,EACnB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,oBAAoB,GACpB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,mBAAmB,EACnB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,KAAK,aAAa,EAClB,aAAa,EACb,oBAAoB,GACpB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,7 +1,8 @@
 // src/storage.ts
 import { AsyncLocalStorage } from "node:async_hooks";
 import {
-  alxia
+  defineMiddleware,
+  settle
 } from "@alxia/core";
 
 class ContextStorageError extends Error {
@@ -40,18 +41,16 @@ function contextStorage(...uncalled) {
   if (uncalled.length > 0) {
     throw new TypeError("contextStorage is a factory: use(contextStorage()), not use(contextStorage)");
   }
-  const plugin = alxia().around((request, next) => {
+  const middleware = defineMiddleware((ctx, next) => {
+    const routed = ctx.route === undefined ? undefined : ctx;
     const current = storage.getStore();
-    if (current?.request.request === request.request)
-      return next();
-    return storage.run({ request, ctx: undefined }, next);
-  }).wrap((ctx, next) => {
-    const holder = storage.getStore();
-    if (holder !== undefined)
-      holder.ctx = ctx;
-    return next();
+    if (current !== undefined && current.request.url === ctx.url) {
+      current.ctx = routed ?? current.ctx;
+      return settle(ctx, next());
+    }
+    return storage.run({ request: ctx, ctx: routed }, () => settle(ctx, next()));
   });
-  return Object.assign(plugin, {
+  return Object.assign(middleware, {
     context: () => getContext(),
     tryContext: () => tryGetContext()
   });
@@ -66,5 +65,5 @@ export {
   tryGetRequestContext
 };
 
-//# debugId=F3B664A2ABF678EE64756E2164756E21
+//# debugId=6963925A93E2187F64756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/storage.ts"],
   "sourcesContent": [
-    "import { AsyncLocalStorage } from 'node:async_hooks';\nimport {\n\ttype Alxia,\n\talxia,\n\ttype BaseContext,\n\ttype ContextOf,\n\ttype Empty,\n\ttype RequestContext,\n} from '@alxia/core';\n\n/** Why there is no context to read. */\nexport type ContextStorageErrorCode =\n\t/** Called outside any request: at startup, in a job, after the response. */\n\t| 'OUTSIDE_REQUEST'\n\t/** In a request, but not in a route declared after `contextStorage()`: a 404, a hook, a route before it. */\n\t| 'NOT_ROUTED';\n\nexport class ContextStorageError extends Error {\n\toverride readonly name = 'ContextStorageError';\n\treadonly code: ContextStorageErrorCode;\n\n\tconstructor(code: ContextStorageErrorCode) {\n\t\tsuper(\n\t\t\tcode === 'OUTSIDE_REQUEST'\n\t\t\t\t? 'getContext(): called outside a request — use tryGetContext(), or runWithContext() in a job or a test'\n\t\t\t\t: 'getContext(): this request reached no route declared after contextStorage() — use it earlier, or getRequestContext()',\n\t\t);\n\t\tthis.code = code;\n\t}\n}\n\ninterface Holder {\n\treadonly request: RequestContext;\n\tctx: BaseContext | undefined;\n}\n\n/**\n * One store for the process: every `contextStorage()` writes to it, and\n * `getContext()` reads it wherever it is called — the way `hono/context-storage`\n * works, so code written against one ports to the other.\n */\nconst storage = new AsyncLocalStorage<Holder>();\n\n/**\n * The context of the route the current request reached: what its handler\n * reads — the request, `set`, `reply`, and what every hook before it added.\n * Throws a `ContextStorageError` outside a route declared after\n * `contextStorage()`.\n *\n * `Ctx` types what the hooks added; prefer the typed `context()` of the plugin\n * itself, typed by the app.\n */\nexport function getContext<Ctx extends object = Empty>(): BaseContext & Ctx {\n\tconst holder = storage.getStore();\n\tif (holder === undefined) throw new ContextStorageError('OUTSIDE_REQUEST');\n\tif (holder.ctx === undefined) throw new ContextStorageError('NOT_ROUTED');\n\treturn holder.ctx as BaseContext & Ctx;\n}\n\n/** `getContext()`, or `undefined` where it would throw: code that runs in and out of requests. */\nexport function tryGetContext<Ctx extends object = Empty>():\n\t| (BaseContext & Ctx)\n\t| undefined {\n\treturn storage.getStore()?.ctx as (BaseContext & Ctx) | undefined;\n}\n\n/**\n * The request as every global hook sees it — before routing, in a 404, in\n * an `onResponse` — with the route it reached and the error it failed with.\n */\nexport function getRequestContext(): RequestContext {\n\tconst holder = storage.getStore();\n\tif (holder === undefined) throw new ContextStorageError('OUTSIDE_REQUEST');\n\treturn holder.request;\n}\n\n/** `getRequestContext()`, or `undefined` outside a request. */\nexport function tryGetRequestContext(): RequestContext | undefined {\n\treturn storage.getStore()?.request;\n}\n\n/**\n * Runs `work` with `ctx` as the current context: a job, a queue consumer,\n * a test calling a service that reads `getContext()`.\n */\nexport function runWithContext<T>(ctx: BaseContext, work: () => T): T {\n\treturn storage.run({ request: ctx, ctx }, work);\n}\n\n/** The plugin, and its context typed by the app it follows. */\nexport type ContextStoragePlugin<App> = Alxia<Empty, Empty, '', never> & {\n\t/** `getContext()`, typed by `App`. */\n\tcontext(): ContextOf<App> extends never ? BaseContext : ContextOf<App>;\n\t/** `tryGetContext()`, typed by `App`. */\n\ttryContext():\n\t\t| (ContextOf<App> extends never ? BaseContext : ContextOf<App>)\n\t\t| undefined;\n};\n\n/**\n * The request's context, anywhere it runs, as a plugin: from the routes\n * declared after it, every function their handlers call — however deep,\n * through every `await` and timer — reads it with `getContext()`, without\n * it being passed down.\n *\n * Typed by the app it is used on: give the plugin that app's type, and its\n * `context()` returns what its routes read — the `user` a session derived, the\n * `db` decorated.\n *\n * ```ts\n * const base = alxia().decorate({ db }).use(session(auth, { required: true }));\n * export const requestContext = contextStorage<typeof base>();\n * const app = base.use(requestContext).get('/orders', ({ reply }) => reply(200, listOrders()));\n *\n * // orders.ts — no context passed\n * export const listOrders = () => {\n *   const { db, user } = requestContext.context();\n *   return db.orders.forUser(user.id);\n * };\n * ```\n */\nexport function contextStorage<App = undefined>(\n\t...uncalled: readonly never[]\n): ContextStoragePlugin<App> {\n\tif (uncalled.length > 0) {\n\t\t// `use(contextStorage)`: the app is handed to the factory, and what\n\t\t// follows would be declared on a plugin nobody serves.\n\t\tthrow new TypeError(\n\t\t\t'contextStorage is a factory: use(contextStorage()), not use(contextStorage)',\n\t\t);\n\t}\n\tconst plugin = alxia()\n\t\t.around((request, next) => {\n\t\t\tconst current = storage.getStore();\n\t\t\tif (current?.request.request === request.request) return next();\n\t\t\treturn storage.run({ request, ctx: undefined }, next);\n\t\t})\n\t\t.wrap((ctx, next) => {\n\t\t\tconst holder = storage.getStore();\n\t\t\tif (holder !== undefined) holder.ctx = ctx;\n\t\t\treturn next();\n\t\t});\n\treturn Object.assign(plugin, {\n\t\tcontext: () => getContext(),\n\t\ttryContext: () => tryGetContext(),\n\t}) as unknown as ContextStoragePlugin<App>;\n}\n"
+    "import { AsyncLocalStorage } from 'node:async_hooks';\nimport {\n\ttype BaseContext,\n\ttype ContextOf,\n\tdefineMiddleware,\n\ttype Empty,\n\ttype Middleware,\n\ttype MiddlewareMark,\n\ttype Mounted,\n\ttype RegisteredBase,\n\ttype RequestContext,\n\ttype RequiresOf,\n\tsettle,\n} from '@alxia/core';\n\n/** Why there is no context to read. */\nexport type ContextStorageErrorCode =\n\t/** Called outside any request: at startup, in a job, after the response. */\n\t| 'OUTSIDE_REQUEST'\n\t/** In a request `contextStorage()` ran on, but that reached no route: a 404, a 405. A route it did not run on is `OUTSIDE_REQUEST`. */\n\t| 'NOT_ROUTED';\n\nexport class ContextStorageError extends Error {\n\toverride readonly name = 'ContextStorageError';\n\treadonly code: ContextStorageErrorCode;\n\n\tconstructor(code: ContextStorageErrorCode) {\n\t\tsuper(\n\t\t\tcode === 'OUTSIDE_REQUEST'\n\t\t\t\t? 'getContext(): called outside a request — use tryGetContext(), or runWithContext() in a job or a test'\n\t\t\t\t: 'getContext(): this request reached no route declared after contextStorage() — use it earlier, or getRequestContext()',\n\t\t);\n\t\tthis.code = code;\n\t}\n}\n\ninterface Holder {\n\treadonly request: RequestContext;\n\tctx: BaseContext | undefined;\n}\n\n/**\n * One store for the process: every `contextStorage()` writes to it, and\n * `getContext()` reads it wherever it is called — the way `hono/context-storage`\n * works, so code written against one ports to the other.\n */\nconst storage = new AsyncLocalStorage<Holder>();\n\n/**\n * The context of the route the current request reached: what its handler\n * reads — the request, `set`, `reply`, and what every hook before it added.\n * Throws a `ContextStorageError` outside a route declared after\n * `contextStorage()`.\n *\n * `Ctx` types what the hooks added; prefer the typed `context()` of the middleware\n * itself, typed by the app.\n */\nexport function getContext<Ctx extends object = Empty>(): BaseContext & Ctx {\n\tconst holder = storage.getStore();\n\tif (holder === undefined) throw new ContextStorageError('OUTSIDE_REQUEST');\n\tif (holder.ctx === undefined) throw new ContextStorageError('NOT_ROUTED');\n\treturn holder.ctx as BaseContext & Ctx;\n}\n\n/** `getContext()`, or `undefined` where it would throw: code that runs in and out of requests. */\nexport function tryGetContext<Ctx extends object = Empty>():\n\t| (BaseContext & Ctx)\n\t| undefined {\n\treturn storage.getStore()?.ctx as (BaseContext & Ctx) | undefined;\n}\n\n/**\n * The request as a middleware sees it — in a 404 too — with the route it\n * reached and the error it failed with.\n */\nexport function getRequestContext(): RequestContext {\n\tconst holder = storage.getStore();\n\tif (holder === undefined) throw new ContextStorageError('OUTSIDE_REQUEST');\n\treturn holder.request;\n}\n\n/** `getRequestContext()`, or `undefined` outside a request. */\nexport function tryGetRequestContext(): RequestContext | undefined {\n\treturn storage.getStore()?.request;\n}\n\n/**\n * Runs `work` with `ctx` as the current context: a job, a queue consumer,\n * a test calling a service that reads `getContext()`.\n */\nexport function runWithContext<T>(ctx: BaseContext, work: () => T): T {\n\treturn storage.run({ request: ctx, ctx }, work);\n}\n\n/**\n * The middleware, and its context typed by the app it follows. It\n * requires that context of the app that uses it, beyond the base context:\n * `app.use` on an app that does not give it is a compile error.\n */\nexport type ContextStorageMiddleware<App> = Middleware<\n\tRequiresOf<StoredContext<App>, 'context'>,\n\tPromise<Response>\n> &\n\tMiddlewareMark & {\n\t\t/** `getContext()`, typed by `App`. */\n\t\tcontext(): StoredContext<App>;\n\t\t/** `tryGetContext()`, typed by `App`. */\n\t\ttryContext(): StoredContext<App> | undefined;\n\t};\n\n/** @deprecated Renamed `ContextStorageMiddleware`: it is a middleware. */\nexport type ContextStoragePlugin<App> = ContextStorageMiddleware<App>;\n\n/** What `context()` reads: the context of `App`, or the base context when `App` is no app. */\nexport type StoredContext<App> = [ContextOf<App>] extends [never]\n\t? BaseContext\n\t: Mounted<ContextOf<App>>;\n\n/**\n * The request's context, anywhere it runs, as a middleware: from the\n * routes declared after it, every function their handlers call — however\n * deep, through every `await` and timer — reads it with `getContext()`,\n * without it being passed down; the answer to an error too, an `onError`\n * hook's included. Give it to `use` before the middlewares whose errors\n * your own middleware answers: what the rest throws is answered inside\n * it, as the route would.\n *\n * Typed by the app it is used on: give the plugin that app's type, and its\n * `context()` returns what its routes read — the `user` a session derived, the\n * `db` decorated. Given none, the app `Register` names in `@alxia/core`\n * (`BaseContext` when nothing is registered). Either way the app that uses\n * it must give that context: using it before is a compile error.\n *\n * ```ts\n * const base = alxia().decorate({ db }).use(session(auth, { required: true }));\n * export const requestContext = contextStorage<typeof base>();\n * const app = base.use(requestContext).get('/orders', ({ reply }) => reply(200, listOrders()));\n *\n * // orders.ts — no context passed\n * export const listOrders = () => {\n *   const { db, user } = requestContext.context();\n *   return db.orders.forUser(user.id);\n * };\n * ```\n */\nexport function contextStorage<App = RegisteredBase>(\n\t...uncalled: readonly never[]\n): ContextStorageMiddleware<App> {\n\tif (uncalled.length > 0) {\n\t\t// `use(contextStorage)`: the app is handed to the factory, and what\n\t\t// follows would be declared on a plugin nobody serves.\n\t\tthrow new TypeError(\n\t\t\t'contextStorage is a factory: use(contextStorage()), not use(contextStorage)',\n\t\t);\n\t}\n\tconst middleware = defineMiddleware((ctx, next) => {\n\t\t// A route's context; none for a request no route matches.\n\t\tconst routed = ctx.route === undefined ? undefined : ctx;\n\t\tconst current = storage.getStore();\n\t\t// A second one, on the same request: the context it reaches is the route's.\n\t\tif (current !== undefined && current.request.url === ctx.url) {\n\t\t\tcurrent.ctx = routed ?? current.ctx;\n\t\t\treturn settle(ctx, next());\n\t\t}\n\t\treturn storage.run({ request: ctx, ctx: routed }, () =>\n\t\t\tsettle(ctx, next()),\n\t\t);\n\t});\n\treturn Object.assign(middleware, {\n\t\tcontext: () => getContext(),\n\t\ttryContext: () => tryGetContext(),\n\t}) as unknown as ContextStorageMiddleware<App>;\n}\n"
   ],
-  "mappings": ";AAAA;AACA;AAAA;AAAA;AAAA;AAgBO,MAAM,4BAA4B,MAAM;AAAA,EAC5B,OAAO;AAAA,EAChB;AAAA,EAET,WAAW,CAAC,MAA+B;AAAA,IAC1C,MACC,SAAS,oBACN,yGACA,sHACJ;AAAA,IACA,KAAK,OAAO;AAAA;AAEd;AAYA,IAAM,UAAU,IAAI;AAWb,SAAS,UAAsC,GAAsB;AAAA,EAC3E,MAAM,SAAS,QAAQ,SAAS;AAAA,EAChC,IAAI,WAAW;AAAA,IAAW,MAAM,IAAI,oBAAoB,iBAAiB;AAAA,EACzE,IAAI,OAAO,QAAQ;AAAA,IAAW,MAAM,IAAI,oBAAoB,YAAY;AAAA,EACxE,OAAO,OAAO;AAAA;AAIR,SAAS,aAAyC,GAE5C;AAAA,EACZ,OAAO,QAAQ,SAAS,GAAG;AAAA;AAOrB,SAAS,iBAAiB,GAAmB;AAAA,EACnD,MAAM,SAAS,QAAQ,SAAS;AAAA,EAChC,IAAI,WAAW;AAAA,IAAW,MAAM,IAAI,oBAAoB,iBAAiB;AAAA,EACzE,OAAO,OAAO;AAAA;AAIR,SAAS,oBAAoB,GAA+B;AAAA,EAClE,OAAO,QAAQ,SAAS,GAAG;AAAA;AAOrB,SAAS,cAAiB,CAAC,KAAkB,MAAkB;AAAA,EACrE,OAAO,QAAQ,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI;AAAA;AAmCxC,SAAS,cAA+B,IAC3C,UACyB;AAAA,EAC5B,IAAI,SAAS,SAAS,GAAG;AAAA,IAGxB,MAAM,IAAI,UACT,6EACD;AAAA,EACD;AAAA,EACA,MAAM,SAAS,MAAM,EACnB,OAAO,CAAC,SAAS,SAAS;AAAA,IAC1B,MAAM,UAAU,QAAQ,SAAS;AAAA,IACjC,IAAI,SAAS,QAAQ,YAAY,QAAQ;AAAA,MAAS,OAAO,KAAK;AAAA,IAC9D,OAAO,QAAQ,IAAI,EAAE,SAAS,KAAK,UAAU,GAAG,IAAI;AAAA,GACpD,EACA,KAAK,CAAC,KAAK,SAAS;AAAA,IACpB,MAAM,SAAS,QAAQ,SAAS;AAAA,IAChC,IAAI,WAAW;AAAA,MAAW,OAAO,MAAM;AAAA,IACvC,OAAO,KAAK;AAAA,GACZ;AAAA,EACF,OAAO,OAAO,OAAO,QAAQ;AAAA,IAC5B,SAAS,MAAM,WAAW;AAAA,IAC1B,YAAY,MAAM,cAAc;AAAA,EACjC,CAAC;AAAA;",
-  "debugId": "F3B664A2ABF678EE64756E2164756E21",
+  "mappings": ";AAAA;AACA;AAAA;AAAA;AAAA;AAAA;AAqBO,MAAM,4BAA4B,MAAM;AAAA,EAC5B,OAAO;AAAA,EAChB;AAAA,EAET,WAAW,CAAC,MAA+B;AAAA,IAC1C,MACC,SAAS,oBACN,yGACA,sHACJ;AAAA,IACA,KAAK,OAAO;AAAA;AAEd;AAYA,IAAM,UAAU,IAAI;AAWb,SAAS,UAAsC,GAAsB;AAAA,EAC3E,MAAM,SAAS,QAAQ,SAAS;AAAA,EAChC,IAAI,WAAW;AAAA,IAAW,MAAM,IAAI,oBAAoB,iBAAiB;AAAA,EACzE,IAAI,OAAO,QAAQ;AAAA,IAAW,MAAM,IAAI,oBAAoB,YAAY;AAAA,EACxE,OAAO,OAAO;AAAA;AAIR,SAAS,aAAyC,GAE5C;AAAA,EACZ,OAAO,QAAQ,SAAS,GAAG;AAAA;AAOrB,SAAS,iBAAiB,GAAmB;AAAA,EACnD,MAAM,SAAS,QAAQ,SAAS;AAAA,EAChC,IAAI,WAAW;AAAA,IAAW,MAAM,IAAI,oBAAoB,iBAAiB;AAAA,EACzE,OAAO,OAAO;AAAA;AAIR,SAAS,oBAAoB,GAA+B;AAAA,EAClE,OAAO,QAAQ,SAAS,GAAG;AAAA;AAOrB,SAAS,cAAiB,CAAC,KAAkB,MAAkB;AAAA,EACrE,OAAO,QAAQ,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI;AAAA;AAsDxC,SAAS,cAAoC,IAChD,UAC6B;AAAA,EAChC,IAAI,SAAS,SAAS,GAAG;AAAA,IAGxB,MAAM,IAAI,UACT,6EACD;AAAA,EACD;AAAA,EACA,MAAM,aAAa,iBAAiB,CAAC,KAAK,SAAS;AAAA,IAElD,MAAM,SAAS,IAAI,UAAU,YAAY,YAAY;AAAA,IACrD,MAAM,UAAU,QAAQ,SAAS;AAAA,IAEjC,IAAI,YAAY,aAAa,QAAQ,QAAQ,QAAQ,IAAI,KAAK;AAAA,MAC7D,QAAQ,MAAM,UAAU,QAAQ;AAAA,MAChC,OAAO,OAAO,KAAK,KAAK,CAAC;AAAA,IAC1B;AAAA,IACA,OAAO,QAAQ,IAAI,EAAE,SAAS,KAAK,KAAK,OAAO,GAAG,MACjD,OAAO,KAAK,KAAK,CAAC,CACnB;AAAA,GACA;AAAA,EACD,OAAO,OAAO,OAAO,YAAY;AAAA,IAChC,SAAS,MAAM,WAAW;AAAA,IAC1B,YAAY,MAAM,cAAc;AAAA,EACjC,CAAC;AAAA;",
+  "debugId": "6963925A93E2187F64756E2164756E21",
   "names": []
 }

package/dist/storage.d.ts

@@ -1,9 +1,9 @@
-import { type Alxia, type BaseContext, type ContextOf, type Empty, type RequestContext } from '@alxia/core';
+import { type BaseContext, type ContextOf, type Empty, type Middleware, type MiddlewareMark, type Mounted, type RegisteredBase, type RequestContext, type RequiresOf } from '@alxia/core';
 /** Why there is no context to read. */
 export type ContextStorageErrorCode = 
 /** Called outside any request: at startup, in a job, after the response. */
 'OUTSIDE_REQUEST'
-/** In a request, but not in a route declared after `contextStorage()`: a 404, a hook, a route before it. */
+/** In a request `contextStorage()` ran on, but that reached no route: a 404, a 405. A route it did not run on is `OUTSIDE_REQUEST`. */
  | 'NOT_ROUTED';
 export declare class ContextStorageError extends Error {
     readonly name = "ContextStorageError";
@@ -16,15 +16,15 @@ export declare class ContextStorageError extends Error {
  * Throws a `ContextStorageError` outside a route declared after
  * `contextStorage()`.
  *
- * `Ctx` types what the hooks added; prefer the typed `context()` of the plugin
+ * `Ctx` types what the hooks added; prefer the typed `context()` of the middleware
  * itself, typed by the app.
  */
 export declare function getContext<Ctx extends object = Empty>(): BaseContext & Ctx;
 /** `getContext()`, or `undefined` where it would throw: code that runs in and out of requests. */
 export declare function tryGetContext<Ctx extends object = Empty>(): (BaseContext & Ctx) | undefined;
 /**
- * The request as every global hook sees it — before routing, in a 404, in
- * an `onResponse` — with the route it reached and the error it failed with.
+ * The request as a middleware sees it — in a 404 too — with the route it
+ * reached and the error it failed with.
  */
 export declare function getRequestContext(): RequestContext;
 /** `getRequestContext()`, or `undefined` outside a request. */
@@ -34,22 +34,35 @@ export declare function tryGetRequestContext(): RequestContext | undefined;
  * a test calling a service that reads `getContext()`.
  */
 export declare function runWithContext<T>(ctx: BaseContext, work: () => T): T;
-/** The plugin, and its context typed by the app it follows. */
-export type ContextStoragePlugin<App> = Alxia<Empty, Empty, '', never> & {
+/**
+ * The middleware, and its context typed by the app it follows. It
+ * requires that context of the app that uses it, beyond the base context:
+ * `app.use` on an app that does not give it is a compile error.
+ */
+export type ContextStorageMiddleware<App> = Middleware<RequiresOf<StoredContext<App>, 'context'>, Promise<Response>> & MiddlewareMark & {
     /** `getContext()`, typed by `App`. */
-    context(): ContextOf<App> extends never ? BaseContext : ContextOf<App>;
+    context(): StoredContext<App>;
     /** `tryGetContext()`, typed by `App`. */
-    tryContext(): (ContextOf<App> extends never ? BaseContext : ContextOf<App>) | undefined;
+    tryContext(): StoredContext<App> | undefined;
 };
+/** @deprecated Renamed `ContextStorageMiddleware`: it is a middleware. */
+export type ContextStoragePlugin<App> = ContextStorageMiddleware<App>;
+/** What `context()` reads: the context of `App`, or the base context when `App` is no app. */
+export type StoredContext<App> = [ContextOf<App>] extends [never] ? BaseContext : Mounted<ContextOf<App>>;
 /**
- * The request's context, anywhere it runs, as a plugin: from the routes
- * declared after it, every function their handlers call — however deep,
- * through every `await` and timer — reads it with `getContext()`, without
- * it being passed down.
+ * The request's context, anywhere it runs, as a middleware: from the
+ * routes declared after it, every function their handlers call — however
+ * deep, through every `await` and timer — reads it with `getContext()`,
+ * without it being passed down; the answer to an error too, an `onError`
+ * hook's included. Give it to `use` before the middlewares whose errors
+ * your own middleware answers: what the rest throws is answered inside
+ * it, as the route would.
  *
  * Typed by the app it is used on: give the plugin that app's type, and its
  * `context()` returns what its routes read — the `user` a session derived, the
- * `db` decorated.
+ * `db` decorated. Given none, the app `Register` names in `@alxia/core`
+ * (`BaseContext` when nothing is registered). Either way the app that uses
+ * it must give that context: using it before is a compile error.
  *
  * ```ts
  * const base = alxia().decorate({ db }).use(session(auth, { required: true }));
@@ -63,5 +76,5 @@ export type ContextStoragePlugin<App> = Alxia<Empty, Empty, '', never> & {
  * };
  * ```
  */
-export declare function contextStorage<App = undefined>(...uncalled: readonly never[]): ContextStoragePlugin<App>;
+export declare function contextStorage<App = RegisteredBase>(...uncalled: readonly never[]): ContextStorageMiddleware<App>;
 //# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,KAAK,EAEV,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,cAAc,EACnB,MAAM,aAAa,CAAC;AAErB,uCAAuC;AACvC,MAAM,MAAM,uBAAuB;AAClC,4EAA4E;AAC1E,iBAAiB;AACnB,4GAA4G;GAC1G,YAAY,CAAC;AAEhB,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,yBAAyB;IAC/C,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;gBAE3B,IAAI,EAAE,uBAAuB;CAQzC;AAcD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,SAAS,MAAM,GAAG,KAAK,KAAK,WAAW,GAAG,GAAG,CAK1E;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,GAAG,SAAS,MAAM,GAAG,KAAK,KACrD,CAAC,WAAW,GAAG,GAAG,CAAC,GACnB,SAAS,CAEX;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAIlD;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,IAAI,cAAc,GAAG,SAAS,CAEjE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAEpE;AAED,+DAA+D;AAC/D,MAAM,MAAM,oBAAoB,CAAC,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,GAAG;IACxE,sCAAsC;IACtC,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,SAAS,KAAK,GAAG,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IACvE,yCAAyC;IACzC,UAAU,IACP,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,KAAK,GAAG,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,GAC7D,SAAS,CAAC;CACb,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAG,SAAS,EAC7C,GAAG,QAAQ,EAAE,SAAS,KAAK,EAAE,GAC3B,oBAAoB,CAAC,GAAG,CAAC,CAuB3B"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,SAAS,EAEd,KAAK,KAAK,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,EAEf,MAAM,aAAa,CAAC;AAErB,uCAAuC;AACvC,MAAM,MAAM,uBAAuB;AAClC,4EAA4E;AAC1E,iBAAiB;AACnB,uIAAuI;GACrI,YAAY,CAAC;AAEhB,qBAAa,mBAAoB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,yBAAyB;IAC/C,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;gBAE3B,IAAI,EAAE,uBAAuB;CAQzC;AAcD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,SAAS,MAAM,GAAG,KAAK,KAAK,WAAW,GAAG,GAAG,CAK1E;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,GAAG,SAAS,MAAM,GAAG,KAAK,KACrD,CAAC,WAAW,GAAG,GAAG,CAAC,GACnB,SAAS,CAEX;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAIlD;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,IAAI,cAAc,GAAG,SAAS,CAEjE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAEpE;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,CAAC,GAAG,IAAI,UAAU,CACrD,UAAU,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,EACzC,OAAO,CAAC,QAAQ,CAAC,CACjB,GACA,cAAc,GAAG;IAChB,sCAAsC;IACtC,OAAO,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC;IAC9B,yCAAyC;IACzC,UAAU,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C,CAAC;AAEH,0EAA0E;AAC1E,MAAM,MAAM,oBAAoB,CAAC,GAAG,IAAI,wBAAwB,CAAC,GAAG,CAAC,CAAC;AAEtE,8FAA8F;AAC9F,MAAM,MAAM,aAAa,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC9D,WAAW,GACX,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAG,cAAc,EAClD,GAAG,QAAQ,EAAE,SAAS,KAAK,EAAE,GAC3B,wBAAwB,CAAC,GAAG,CAAC,CAyB/B"}

package/docs/README.md

@@ -1,12 +1,12 @@
 # @alxia/context-storage documentation
 
 The [package README](../README.md) is the short version. This folder is
-the long one: what the plugin stores and when, how to read it from a
+the long one: what the middleware stores and when, how to read it from a
 service, a repository or a logger, how its type follows the app, where it
-sits among an app's hooks, and what a timer or a detached callback sees.
+sits among an app's middlewares, and what a timer or a detached callback sees.
 
 | Page | Read it when |
 | --- | --- |
-| [Guide](guide.md) | reading the request's context from code the handler calls, typing it, placing the plugin among other hooks, running a job or a test with a context, or wondering what a timer sees |
-| [Troubleshooting](troubleshooting.md) | `getContext()` threw a `ContextStorageError`, a service read the wrong context or none, `use(contextStorage)` threw a `TypeError`, or `tsc` refused the plugin or its type |
+| [Guide](guide.md) | reading the request's context from code the handler calls, typing it, placing the middleware among the others, running a job or a test with a context, or wondering what a timer sees |
+| [Troubleshooting](troubleshooting.md) | `getContext()` threw a `ContextStorageError`, a service read the wrong context or none, `use(contextStorage)` threw a `TypeError`, or `tsc` refused the middleware or its type |
 | [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |

package/docs/guide.md

@@ -1,8 +1,8 @@
 # Guide
 
 This page covers what `contextStorage()` stores and when, how code outside
-a handler reads it, how its type follows the app, where the plugin sits
-among an app's hooks, and what `AsyncLocalStorage` does and does not carry.
+a handler reads it, how its type follows the app, where the middleware sits
+among an app's middlewares, and what `AsyncLocalStorage` does and does not carry.
 
 ```ts
 import { alxia } from '@alxia/core';
@@ -32,13 +32,23 @@ context of the request that called it, and never another's.
 ## The signature
 
 ```ts
-// `uncalled` takes nothing: it makes `use(contextStorage)` a compile error
-function contextStorage<App = undefined>(...uncalled: readonly never[]): ContextStoragePlugin<App>;
-
-type ContextStoragePlugin<App> = Alxia<Empty, Empty, '', never> & {
-	context(): ContextOf<App> extends never ? BaseContext : ContextOf<App>;
-	tryContext(): (ContextOf<App> extends never ? BaseContext : ContextOf<App>) | undefined;
-};
+// `uncalled` takes nothing: it makes `use(contextStorage)` a compile error.
+// `App` defaults to the app `Register` names in `@alxia/core` (`RegisteredBase`)
+function contextStorage<App = RegisteredBase>(...uncalled: readonly never[]): ContextStorageMiddleware<App>;
+
+// A middleware: it requires `App`'s context of the app that mounts it.
+// `ContextStoragePlugin<App>`, its name in 0.3, is a deprecated alias.
+type ContextStorageMiddleware<App> = Middleware<
+	RequiresOf<StoredContext<App>, 'context'>,
+	Promise<Response>
+> &
+	MiddlewareMark & {
+		context(): StoredContext<App>;
+		tryContext(): StoredContext<App> | undefined;
+	};
+
+// What `context()` returns: `App`'s context, or `BaseContext` when `App` is no app
+type StoredContext<App> = [ContextOf<App>] extends [never] ? BaseContext : Mounted<ContextOf<App>>;
 
 function getContext<Ctx extends object = Empty>(): BaseContext & Ctx;
 function tryGetContext<Ctx extends object = Empty>(): (BaseContext & Ctx) | undefined;
@@ -54,9 +64,11 @@ class ContextStorageError extends Error {
 type ContextStorageErrorCode = 'OUTSIDE_REQUEST' | 'NOT_ROUTED';
 ```
 
-`contextStorage()` returns an app plugin: pass it to `use`, called — `use(contextStorage)` fails `tsc` with `TS2769` and throws a `TypeError` at startup ([troubleshooting](troubleshooting.md#typeerror-contextstorage-is-a-factory-usecontextstorage-not-usecontextstorage)). It adds
-nothing to the app's type. `BaseContext`, `RequestContext` and `ContextOf`
-come from `@alxia/core`.
+`contextStorage()` returns a middleware: pass it to `app.use`, called — `use(contextStorage)` fails `tsc` with `TS2769` and throws a `TypeError` at startup ([troubleshooting](troubleshooting.md#typeerror-contextstorage-is-a-factory-usecontextstorage-not-usecontextstorage)). It adds
+nothing to the app's type, but it requires `StoredContext<App>` of the app
+that mounts it: `app.use` on an app that does not give that context is a compile
+error. `BaseContext`, `RequestContext`, `ContextOf`, `RegisteredBase`,
+`Middleware`, `MiddlewareMark`, `RequiresOf` and `Mounted` come from `@alxia/core`.
 
 | Export | Returns | Where it would have nothing |
 | --- | --- | --- |
@@ -64,33 +76,40 @@ come from `@alxia/core`.
 | `requestContext.tryContext()` | the same | `undefined` |
 | `getContext<Ctx>()` | the route's context, as `BaseContext & Ctx`: `Ctx` is yours to state | throws a `ContextStorageError` |
 | `tryGetContext<Ctx>()` | the same | `undefined` |
-| `getRequestContext()` | the request as global hooks see it: `request`, `url`, `ip`, `server`, and once routing has run, `route` and `error` | throws a `ContextStorageError` coded `OUTSIDE_REQUEST` |
+| `getRequestContext()` | the request as a middleware sees it: `request`, `url`, `ip`, `server`, `route` (`undefined` when no route matched) and, once a route has failed, `error` | throws a `ContextStorageError` coded `OUTSIDE_REQUEST` |
 | `tryGetRequestContext()` | the same | `undefined` |
 | `runWithContext(ctx, work)` | what `work` returns, with `ctx` as the current context while it runs | — |
 
 There is one store per copy of the package: every `contextStorage()` writes
-to it, and `getContext()` reads it wherever it is called. Two plugins on one
+to it, and `getContext()` reads it wherever it is called. Two of them on one
 app read the same context.
 
 ## What it stores, and when
 
-The plugin adds two hooks. A global `around` hook opens a store for every
-request the app receives, wherever the plugin is used, holding the
-request's `RequestContext`. A route hook records the route's context in
-that store, for the routes declared after the plugin only. So what each
-function reads depends on where the code runs:
+`contextStorage()` is a middleware: it opens a store around the rest of the
+chain, holding the request's context, and records the route's context in
+it when the request reached a route. A `use()` on the app runs on every
+request, in declaration order, so what each function reads depends on
+whether the middleware ran on the request, and where the code runs
+relative to it:
 
 | Code running in | `getRequestContext()` | `tryGetRequestContext()` | `getContext()` | `tryGetContext()` |
 | --- | --- | --- | --- | --- |
-| an `onRequest` hook | the request, `route` still `undefined` | the same | throws `NOT_ROUTED` | `undefined` |
-| a route declared **before** the plugin, and its `onResponse` | the request | the same | throws `NOT_ROUTED` | `undefined` |
-| a `derive` or `wrap` declared after the plugin | the request | the same | the route's context, **before validation**: no `params`, `query` or `body` yet | the same |
-| the handler of a route declared after the plugin, and everything it calls | the request | the same | the context the handler receives — the same object | the same |
-| that route's `onError` and `onResponse` hooks | the request, with `route` and `error` | the same | the same context | the same |
-| an `onResponse` for a 404 | the request, `route` `undefined` | the same | throws `NOT_ROUTED` | `undefined` |
+| a middleware declared **before** it | throws `OUTSIDE_REQUEST` | `undefined` | throws `OUTSIDE_REQUEST` | `undefined` |
+| a middleware after it, on a request a route matched | the request, with its `route` | the same | the route's context, **before validation**: no `params`, `query` or `body` yet, and without what later middlewares add | the same |
+| a middleware after it, on a request no route matched (a 404, a 405) | the request, `route` `undefined` | the same | throws `NOT_ROUTED` | `undefined` |
+| the handler of a route the middleware ran on, and everything it calls | the request | the same | the context the handler receives, with what the middlewares added | the same |
+| a middleware that catches an error, after it | the request, with `route` and `error` | the same | the same context | the same |
+| a route declared **before** it, or outside the `group` it is used in | throws `OUTSIDE_REQUEST` | `undefined` | throws `OUTSIDE_REQUEST` | `undefined` |
+| the deprecated `onRequest` and `onResponse` hooks, which run outside the chain | throws `OUTSIDE_REQUEST` | `undefined` | throws `OUTSIDE_REQUEST` | `undefined` |
+| the deprecated `onError` and `onRefusal` hooks, which answer at the route boundary | the request, with `route` and `error` | the same | the same context | the same |
 | a socket's handlers (`open`, `message`, `close`) | throws `OUTSIDE_REQUEST` | `undefined` | throws `OUTSIDE_REQUEST` | `undefined` |
 | startup, a job, a timer started at startup | throws `OUTSIDE_REQUEST` | `undefined` | throws `OUTSIDE_REQUEST` | `undefined` |
 
+`contextStorage()` settles `next()`: an error the rest of the chain throws
+is answered inside the store, as the route would answer it, so a hook or
+a middleware that reads the context while answering an error still finds it.
+
 The two errors carry these messages:
 
 | `code` | `message` |
@@ -116,13 +135,13 @@ Code that runs both in and out of requests uses `tryContext()`,
 
 The context is the whole of what the handler reads: the request, `set` to
 add a header or a cookie to the response, `reply` and `redirect`, and what
-every hook added — so a service three calls down can set a response header,
+every middleware added — so a service three calls down can set a response header,
 as `listOrders` does below.
 
 ## Reading it from outside the handler
 
-Keep the app's base and the plugin in a module of their own, and import the
-plugin from every service, repository or logger that reads it. The handlers
+Keep the app's base and the middleware in a module of their own, and import it
+from every service, repository or logger that reads it. The handlers
 then call those without passing anything down.
 
 ```ts
@@ -171,8 +190,8 @@ export const app = base
 ```
 
 A logger is the code that runs in and out of requests: at startup, in a 404,
-in a route. `tryGetRequestContext()` gives it the request wherever there is
-one, and `tryContext()` the user where a route was reached:
+in a route. `tryGetRequestContext()` gives it the request wherever the
+middleware ran, and `tryContext()` the user where a route was reached:
 
 ```ts
 // log.ts
@@ -202,8 +221,8 @@ return what a route declared next on that app would read: `ContextOf<App>`.
 
 | `App` | `context()` returns |
 | --- | --- |
-| none: `contextStorage()` | `BaseContext`: the request, `set`, `reply`, `redirect`, `route`, `pathParams` |
-| `typeof base` | `ContextOf<typeof base>`: `BaseContext` plus everything `base`'s `decorate`, `derive` and plugins added |
+| none: `contextStorage()` | the context `@alxia/core`'s `Register` names, `AppContext`; with nothing registered, `BaseContext`: the request, `set`, `reply`, `redirect`, `route`, `pathParams` |
+| `typeof base` | `ContextOf<typeof base>`: `BaseContext` plus everything `base`'s `decorate`, `derive` and middlewares added |
 
 ```ts
 import { alxia } from '@alxia/core';
@@ -223,24 +242,46 @@ export function whoIsAsking(): string {
 }
 ```
 
-Three rules follow from typing by an app:
+With `Register` augmented beside `base`
+([`@alxia/core`'s `Register`](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/types.md#register-and-appcontext)),
+`contextStorage()` is `contextStorage<typeof base>()` with no import of
+`base`:
+
+```ts
+declare module '@alxia/core' {
+	interface Register {
+		context: typeof base;
+	}
+}
+
+export const requestContext = contextStorage(); // context().user: string
+```
+
+Four rules follow from typing by an app:
+
+- **The app that mounts it must give that context.** The middleware requires
+  what `context()` reads beyond `BaseContext`, as a `definePlugin` does:
+  `alxia().use(contextStorage<typeof base>())` is a compile error, since
+  `context()` would claim a `user` that no middleware of that app adds.
 
-- **Type it by the app before the plugin, never by the app that uses it.**
+- **Type it by the app before the middleware, never by the app that mounts it.**
   `const app = alxia().use(requestContext)…` with
   `requestContext = contextStorage<typeof app>()` is a circular type, which
-  `tsc` refuses with `TS7022`. Declare `base` first, as above.
-- **What a hook after the plugin adds is there at runtime, not in the
+  `tsc` refuses with `TS7022`. Declare `base` first, as above. Registered,
+  the same holds: give `contextStorage()` to the app after `base`, never
+  to the registered `base` itself.
+- **What a middleware after it adds is there at runtime, not in the
   type.** `context()` knows `base`, so a `derive` added after
-  `base.use(requestContext)` is missing from its type. Put the hooks whose
-  values services read in `base`, or state the type with `getContext<Ctx>()`.
+  `base.use(requestContext)` is missing from its type. Put the middlewares
+  whose values services read in `base`, or state the type with `getContext<Ctx>()`.
 - **A route's own `params`, `query`, `body` and `headers` are not in it**:
-  they belong to one route's schema, not to the app. Read them in the
-  handler and pass them down, or state them:
+  they belong to one route's `validate(…)`, not to the app. Read them in
+  the handler and pass them down, or state them:
 
 ```ts
 import { getContext } from '@alxia/context-storage';
 
-// in code that only ever runs under GET /orders/:id, with a params schema
+// in code that only ever runs under GET /orders/:id, after its validate({ params })
 const { params } = getContext<{ params: { id: number } }>();
 ```
 
@@ -249,10 +290,10 @@ as `hono/context-storage`'s do: nothing checks it against the route.
 
 ## Where it sits
 
-The plugin's `around` hook is global: it applies to every request, wherever
-`use` is called. Its route hook applies to the routes declared after it, in
-the same app or group. So **use it before the routes whose code reads the
-context**, and after the hooks whose values services read:
+`app.use(contextStorage())` runs on every request, a 404 included, and
+wraps what is declared after it, in the same app or group. So **use it
+before the routes whose code reads the context**, and after the middlewares
+whose values services read:
 
 ```ts
 import { alxia } from '@alxia/core';
@@ -263,26 +304,25 @@ const requestContext = contextStorage();
 const app = alxia()
 	.get('/health', ({ reply }) => reply(200, 'ok'))      // getContext() throws NOT_ROUTED here
 	.use(requestContext)
-	.derive(() => ({ startedAt: Date.now() }))            // after the plugin: may call code that reads it
+	.derive(() => ({ startedAt: Date.now() }))            // after it: may call code that reads it
 	.get('/me', ({ reply }) => reply(200, getContext().route)); // '/me'
 ```
 
-A hook declared before the plugin that ends the request — a `derive`
-answering `401` — ends it before the plugin's route hook runs: in that
-request's `onResponse`, `getContext()` throws `NOT_ROUTED`, and
-`getRequestContext()` still answers.
+A middleware declared before `contextStorage()` that ends the request, a
+`401` from a guard, ends it before the middleware runs: nothing it calls
+finds a store. Put the guards after `contextStorage()` when the code that
+answers needs the context; put it after the observers (`logger`,
+`telemetry`) and before an error-handling `try`/`catch` that reads it.
 
 | Placement | Effect |
 | --- | --- |
-| at the top of the chain | every route can read it; `context()` is typed `BaseContext` unless typed by an app declared before it |
+| first on the app | every route after it, and every middleware after it, can read it; a request no route matches gets `getRequestContext()` too; `context()` is typed `BaseContext` unless typed by an app declared before it |
 | after `decorate` and `derive` | the usual place: typed by them, and every route after reads it |
-| inside a `group` | the group's routes read it; a route outside the group throws `NOT_ROUTED` |
+| inside a `group` | the group's routes read it; a route outside the group, or a request no route matches, throws `OUTSIDE_REQUEST`: the middleware never ran |
 | twice | harmless: one store, one context per request |
 
-The plugin is an app like any other: `requestContext.get('/x', handler)` is the
-route method, and the context is read with `context()` and `tryContext()`.
-Declare routes on the app rather than on the plugin, and pass
-`contextStorage()` to `use` called — the uncalled form is
+`contextStorage()` is a middleware, not an app: declare routes on the app,
+and pass `contextStorage()` to `app.use` called — the uncalled form is
 [refused](troubleshooting.md#typeerror-contextstorage-is-a-factory-usecontextstorage-not-usecontextstorage).
 
 ## What `AsyncLocalStorage` carries
@@ -312,7 +352,7 @@ runs:
 | a `setInterval`, queue consumer or pool started at startup | nothing: `context()` throws `OUTSIDE_REQUEST`, `tryContext()` is `undefined` |
 | a function pushed into a queue in the request, and run by something started at startup | nothing, as above |
 | an `EventEmitter` listener | the context of the code that called `emit`, since listeners run synchronously |
-| a WebSocket's `open`, `message` and `close` | nothing: a socket's upgrade runs outside `around` |
+| a WebSocket's `open`, `message` and `close` | nothing: a socket's handlers run outside the chain |
 
 So work that outlives the request — a write-behind, an e-mail, an audit
 event — takes what it needs **before** it is detached, instead of reading

package/docs/roadmap.md

@@ -7,7 +7,11 @@ only 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(contextStorage())` opens the store on every request, a 404 included: `getRequestContext()` works in every middleware after it, and an error is answered inside it, so an `onError` hook or a catching middleware still reads the context. `app.plugin(contextStorage())` still works, deprecated.
+- **Typed by `Register`.** With `@alxia/core`'s `Register` naming the
+  base, `contextStorage()` needs no type argument: `context()` reads the
+  registered context. Typed either way, the middleware requires that context
+  of the app that mounts it, a compile error otherwise.
 
 ## Next
 

package/docs/troubleshooting.md

@@ -18,6 +18,7 @@ behaviour that prints nothing, or an error from `tsc`. A
 - [`Property 'user' does not exist on type 'BaseContext'.`](#property-user-does-not-exist-on-type-basecontext)
 - [`Property 'params' does not exist on type 'BaseContext & …'.`](#property-params-does-not-exist-on-type-basecontext--)
 - [`Object literal may only specify known properties, and 'db' does not exist in type 'BaseContext'.`](#object-literal-may-only-specify-known-properties-and-db-does-not-exist-in-type-basecontext)
+- [`Property 'user' is missing in type 'BaseContext & Empty' but required in type '{ user: string; }'`](#property-user-is-missing-in-type-basecontext--empty-but-required-in-type--user-string-)
 
 ## Runtime
 
@@ -28,16 +29,18 @@ behaviour that prints nothing, or an error from `tsc`. A
 ```text
 error TS2769: No overload matches this call.
   …
-    Argument of type '<App = undefined>(...uncalled: readonly never[]) => ContextStoragePlugin<App>' is not assignable to parameter of type '(app: Alxia<Empty, Empty, "", never>) => ContextStoragePlugin<undefined>'.
+    Argument of type '<App = Alxia<Empty, "", never>>(...uncalled: readonly never[]) => ContextStorageMiddleware<App>' is not assignable to parameter of type 'ScopeMiddleware<Empty, [], MiddlewareReturn>'.
+      …
+          Type 'BaseContext & Empty' is not assignable to type 'never'.
 ```
 
-**When:** at startup, on `.use(contextStorage)`: the factory given to `use`
-without being called.
+**When:** at startup, on `.use(contextStorage)`: the factory given to
+`app.use` without being called.
 
-**Why:** `use` takes a function as a plugin and calls it with the app.
-Called that way, `contextStorage` would return a new, empty plugin app,
-and every route declared after it would land on an app nobody serves; it
-refuses the argument instead.
+**Why:** `app.use` calls a function it is given with the app, as a plugin.
+Called that way, `contextStorage` would be handed the app, and what
+follows would be declared on a plugin nobody serves; it refuses the
+argument instead.
 
 **Fix:** call it, once, and keep the result:
 
@@ -58,13 +61,17 @@ and `getRequestContext()` all throw it.
 - in a job, a queue consumer, or a callback run by a `setInterval` started
   at startup — including a function pushed onto a queue during a request
   and run later by such a timer;
-- in a WebSocket's `open`, `message` or `close`, since a socket's upgrade
-  runs outside the plugin's hook;
+- in a route declared **before** `use(requestContext)`, or outside the
+  `group` it is used in: the middleware never ran on that request;
+- in a middleware declared before it, or in the deprecated `onRequest` and
+  `onResponse` hooks, which run outside the chain;
+- in a WebSocket's `open`, `message` or `close`, since a socket's handlers
+  run outside the chain;
 - with two copies of `@alxia/context-storage` installed: each has its own
-  store, so a plugin from one is invisible to `getContext()` from the other.
+  store, so the middleware from one is invisible to `getContext()` from the other.
 
-**Why:** the context lives in an `AsyncLocalStorage` that the plugin opens
-for each request. A callback reads the store that was current where it was
+**Why:** the context lives in an `AsyncLocalStorage` that the middleware opens
+for each request it runs on. A callback reads the store that was current where it was
 **scheduled**; anything started outside a request has none.
 
 **Fix:** in code that runs in and out of requests, use `tryContext()` —
@@ -102,7 +109,7 @@ export function auditLater(action: string): void {
 }
 ```
 
-In a socket handler, read what the upgrade's hooks added from
+In a socket handler, read what the upgrade's middlewares added from
 `socket.data`. For two copies, `bun pm ls --all | grep context-storage`
 shows them; align the versions the app and its dependencies ask for.
 
@@ -110,39 +117,35 @@ shows them; align the versions the app and its dependencies ask for.
 
 `error.code` is `'NOT_ROUTED'`.
 
-**When:** in a request, but not inside a route declared after the plugin:
-
-- in a route declared **before** `use(requestContext)`, or outside the
-  `group` it is used in;
-- in an `onRequest` hook, which runs before routing;
-- in an `onResponse` hook, for a `404`, or for a request a hook declared
-  before the plugin refused — a `derive` answering `401`;
-- in code those call.
-
-**Why:** the plugin opens the store for every request, but records the
-route's context only for the routes declared after it: until then there is
-a request and no route.
+**When:** in a request the middleware ran on, but that reached no route:
+a 404 or a 405, in a middleware after `use(requestContext)`, or in code
+that middleware calls.
 
-**Fix:** use the plugin before the routes whose code reads it:
-
-```ts
-const app = base
-	.use(requestContext) // before every route that reads it
-	.get('/orders', async ({ reply }) => reply(200, await listOrders()));
-```
+**Why:** `use(requestContext)` on the app runs on every request, and records
+the route's context only when a route matched: for an unmatched request
+there is a request and no route.
 
-In a global hook, or in code that also runs for a 404, read the request
-instead, which holds wherever there is one:
+**Fix:** in a middleware, or in code that also runs for a 404, read the
+request instead, which holds wherever the middleware ran:
 
 ```ts
+import { defineMiddleware } from '@alxia/core';
 import { getRequestContext } from '@alxia/context-storage';
 
-app.onResponse((response) => {
-	const { request, route } = getRequestContext(); // route is undefined for a 404
-	console.log(request.method, route ?? 'unmatched', response.status);
-});
+app.use(requestContext).use(
+	defineMiddleware(async (_ctx, next) => {
+		const response = await next();
+		const { request, route } = getRequestContext(); // route is undefined for a 404
+		console.log(request.method, route ?? 'unmatched', response.status);
+		return response;
+	}),
+);
 ```
 
+A route declared before the middleware, or outside its `group`, throws
+`OUTSIDE_REQUEST` instead (see above): mount it before the routes whose
+code reads it.
+
 ### A header set from a timer never reaches the response
 
 **When:** a `setTimeout`, a promise that is not awaited, or a callback
@@ -175,16 +178,16 @@ error TS7022: 'requestContext' implicitly has type 'any' because it does not hav
 
 Often with `TS2448: Block-scoped variable 'requestContext' used before its declaration.`
 
-**When:** the plugin is typed by the app that uses it:
+**When:** the middleware is typed by the app that mounts it:
 
 ```ts
 export const app = alxia().decorate({ db }).use(requestContext).get(/* … */);
 export const requestContext = contextStorage<typeof app>(); // circular
 ```
 
-**Why:** `app`'s type depends on the plugin, and the plugin's on `app`.
+**Why:** `app`'s type depends on the middleware, and the middleware's on `app`.
 
-**Fix:** type it by the app as it stands **before** the plugin:
+**Fix:** type it by the app as it stands **before** the middleware:
 
 ```ts
 export const base = alxia().decorate({ db });
@@ -200,18 +203,22 @@ error TS2339: Property 'user' does not exist on type 'BaseContext'.
 
 Also as `Property 'user' does not exist on type 'BaseContext & Empty & { readonly db: … }'.`
 
-**When:** reading from `context()` a value a hook adds, and either
+**When:** reading from `context()` a value a middleware adds, and either
 
-- the plugin was made without an app type, `contextStorage()`; or
-- it is typed by `base`, and the hook adding `user` comes after it:
+- the middleware was made without an app type, `contextStorage()`, and
+  `@alxia/core`'s `Register` names no base; or
+- it is `contextStorage()` given to the registered `base` itself, which
+  cannot read `Register` while `base` is being typed; or
+- it is typed by `base`, and the middleware adding `user` comes after it:
   `base.use(requestContext).derive(() => ({ user }))`.
 
 **Why:** `context()` returns `ContextOf<App>`: what a route declared next on
-`App` reads. With no `App`, that is `BaseContext`; a hook after `App` is
+`App` reads. With no `App`, that is `BaseContext`; a middleware after `App` is
 not in it. At runtime the value is there.
 
-**Fix:** declare every hook whose values services read in `base`, then type
-the plugin by it:
+**Fix:** declare every middleware whose values services read in `base`, then type
+it by `base` — or register `base` with `@alxia/core`'s `Register` and
+give `contextStorage()` to the app after `base`, never to `base` itself:
 
 ```ts
 const base = alxia()
@@ -232,9 +239,10 @@ The same for `query`, `body` and `headers`.
 
 **When:** reading a route's validated input from `requestContext.context()`.
 
-**Why:** those belong to one route's schema, not to the app, so the app's
-context does not have them. Hooks run before validation: a `derive` reads
-them as `undefined` even at runtime.
+**Why:** those belong to one route's `validate(…)`, not to the app, so the
+app's context does not have them. The app's middlewares run before a
+route's own, `validate` among them: a `derive` reads the request as it
+arrived, the body `undefined`, even at runtime.
 
 **Fix:** pass them from the handler, or, in code that only runs under one
 route, state them:
@@ -274,3 +282,33 @@ const ctx = {
 
 runWithContext(ctx as unknown as Ctx, () => listOrders());
 ```
+
+### `Property 'user' is missing in type 'BaseContext & Empty' but required in type '{ user: string; }'`
+
+```text
+error TS2769: No overload matches this call.
+  …
+          Type 'BaseContext & Empty' is not assignable to type 'MiddlewareContext<{ user: string; }>'.
+            Property 'user' is missing in type 'BaseContext & Empty' but required in type '{ user: string; }'.
+```
+
+**When:** an app uses the middleware typed by another app, `contextStorage<typeof
+base>()`, or by the registered one, `contextStorage()`, and does not give
+what that app's middlewares add:
+
+```ts
+const base = alxia().derive(({ request }) => ({ user: request.headers.get('x-user') ?? 'anonymous' }));
+const requestContext = contextStorage<typeof base>();
+
+alxia().use(requestContext);
+```
+
+**Why:** `context()` would return a `user` that no middleware of this app adds:
+at runtime it would be `undefined`.
+
+**Fix:** mount it on the app it is typed by, after `base`:
+
+```ts
+base.use(requestContext);
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/context-storage",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"description": "The request's context anywhere it runs — a service, a repository, a logger — through AsyncLocalStorage: alxia's hono/context-storage, typed by the app",
 	"license": "MIT",
 	"type": "module",
@@ -41,12 +41,12 @@
 		]
 	},
 	"devDependencies": {
-		"@alxia/core": "^0.2.0",
+		"@alxia/core": "^0.4.0",
 		"@types/bun": "^1.4.2",
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
-		"@alxia/core": "^0.2.0",
+		"@alxia/core": "^0.4.0",
 		"typescript": "^6.0.3 || ^7.0.0"
 	}
 }