@alxia/context-storage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @alxia/context-storage
+
+The request's context, anywhere it runs — a service, a repository, a logger
+three calls down — without passing it: [alxia](https://www.npmjs.com/package/@alxia/core)'s
+`hono/context-storage`, on `AsyncLocalStorage`, **typed by the app**. No
+dependency.
+
+```sh
+bun add @alxia/context-storage @alxia/core
+bun add -d typescript
+```
+
+## Usage
+
+```ts
+import { alxia } from '@alxia/core';
+import { contextStorage } from '@alxia/context-storage';
+import { session } from '@alxia/janus';
+
+const base = alxia().decorate({ db }).use(session(auth, { required: true }));
+
+export const requestContext = contextStorage<typeof base>();
+
+const app = base
+	.use(requestContext)
+	.get('/orders', async ({ reply }) => reply(200, await listOrders()));
+```
+
+```ts
+// orders.ts — no context passed down
+import { requestContext } from './app';
+
+export async function listOrders() {
+	const { db, user, set } = requestContext.context();   // typed: user, db
+	set.headers.set('cache-control', 'private');
+	return db.orders.forUser(user.id);
+}
+```
+
+The context holds through every `await`, timer and promise of the
+request, and never leaks into another's: twenty concurrent requests read
+twenty contexts.
+
+## 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.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 |
+| `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.
+
+Pass the plugin to `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)).
+
+## API
+
+| export | |
+| --- | --- |
+| `contextStorage<App>()` | the plugin, with `context()` and `tryContext()` typed by `App` |
+| `ContextStoragePlugin<App>` | its type |
+| `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`.
+- [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

@@ -0,0 +1,2 @@
+export { ContextStorageError, type ContextStorageErrorCode, type ContextStoragePlugin, contextStorage, getContext, getRequestContext, runWithContext, tryGetContext, tryGetRequestContext, } from './storage';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,mBAAmB,EACnB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,oBAAoB,GACpB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,70 @@
+// src/storage.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  alxia
+} from "@alxia/core";
+
+class ContextStorageError extends Error {
+  name = "ContextStorageError";
+  code;
+  constructor(code) {
+    super(code === "OUTSIDE_REQUEST" ? "getContext(): called outside a request — use tryGetContext(), or runWithContext() in a job or a test" : "getContext(): this request reached no route declared after contextStorage() — use it earlier, or getRequestContext()");
+    this.code = code;
+  }
+}
+var storage = new AsyncLocalStorage;
+function getContext() {
+  const holder = storage.getStore();
+  if (holder === undefined)
+    throw new ContextStorageError("OUTSIDE_REQUEST");
+  if (holder.ctx === undefined)
+    throw new ContextStorageError("NOT_ROUTED");
+  return holder.ctx;
+}
+function tryGetContext() {
+  return storage.getStore()?.ctx;
+}
+function getRequestContext() {
+  const holder = storage.getStore();
+  if (holder === undefined)
+    throw new ContextStorageError("OUTSIDE_REQUEST");
+  return holder.request;
+}
+function tryGetRequestContext() {
+  return storage.getStore()?.request;
+}
+function runWithContext(ctx, work) {
+  return storage.run({ request: ctx, ctx }, work);
+}
+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 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();
+  });
+  return Object.assign(plugin, {
+    context: () => getContext(),
+    tryContext: () => tryGetContext()
+  });
+}
+export {
+  ContextStorageError,
+  contextStorage,
+  getContext,
+  getRequestContext,
+  runWithContext,
+  tryGetContext,
+  tryGetRequestContext
+};
+
+//# debugId=F3B664A2ABF678EE64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "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"
+  ],
+  "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",
+  "names": []
+}

package/dist/storage.d.ts

@@ -0,0 +1,67 @@
+import { type Alxia, type BaseContext, type ContextOf, type Empty, type RequestContext } 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. */
+ | 'NOT_ROUTED';
+export declare class ContextStorageError extends Error {
+    readonly name = "ContextStorageError";
+    readonly code: ContextStorageErrorCode;
+    constructor(code: ContextStorageErrorCode);
+}
+/**
+ * The context of the route the current request reached: what its handler
+ * reads — the request, `set`, `reply`, and what every hook before it added.
+ * Throws a `ContextStorageError` outside a route declared after
+ * `contextStorage()`.
+ *
+ * `Ctx` types what the hooks added; prefer the typed `context()` of the plugin
+ * 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.
+ */
+export declare function getRequestContext(): RequestContext;
+/** `getRequestContext()`, or `undefined` outside a request. */
+export declare function tryGetRequestContext(): RequestContext | undefined;
+/**
+ * Runs `work` with `ctx` as the current context: a job, a queue consumer,
+ * 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> & {
+    /** `getContext()`, typed by `App`. */
+    context(): ContextOf<App> extends never ? BaseContext : ContextOf<App>;
+    /** `tryGetContext()`, typed by `App`. */
+    tryContext(): (ContextOf<App> extends never ? BaseContext : ContextOf<App>) | undefined;
+};
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * ```ts
+ * const base = alxia().decorate({ db }).use(session(auth, { required: true }));
+ * export const requestContext = contextStorage<typeof base>();
+ * const app = base.use(requestContext).get('/orders', ({ reply }) => reply(200, listOrders()));
+ *
+ * // orders.ts — no context passed
+ * export const listOrders = () => {
+ *   const { db, user } = requestContext.context();
+ *   return db.orders.forUser(user.id);
+ * };
+ * ```
+ */
+export declare function contextStorage<App = undefined>(...uncalled: readonly never[]): ContextStoragePlugin<App>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +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"}

package/docs/README.md

@@ -0,0 +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
+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.
+
+| 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 |
+| [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |

package/docs/guide.md

@@ -0,0 +1,418 @@
+# 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.
+
+```ts
+import { alxia } from '@alxia/core';
+import { contextStorage } from '@alxia/context-storage';
+
+const base = alxia()
+	.decorate({ greeting: 'Hello' })
+	.derive(({ request }) => ({ user: request.headers.get('x-user') ?? 'anonymous' }));
+
+const requestContext = contextStorage<typeof base>();
+
+// three calls down, no context passed
+function greet(): string {
+	const { greeting, user } = requestContext.context(); // typed: greeting, user
+	return `${greeting}, ${user}`;
+}
+
+const app = base.use(requestContext).get('/hello', ({ reply }) => reply(200, greet()));
+
+app.listen(3000);
+```
+
+`curl -H 'x-user: Ada' localhost:3000/hello` answers `Hello, Ada`. `greet`
+could live in another module, behind any number of `await`s: it reads the
+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;
+};
+
+function getContext<Ctx extends object = Empty>(): BaseContext & Ctx;
+function tryGetContext<Ctx extends object = Empty>(): (BaseContext & Ctx) | undefined;
+function getRequestContext(): RequestContext;
+function tryGetRequestContext(): RequestContext | undefined;
+function runWithContext<T>(ctx: BaseContext, work: () => T): T;
+
+class ContextStorageError extends Error {
+	readonly name: 'ContextStorageError';
+	readonly code: ContextStorageErrorCode;
+}
+
+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`.
+
+| Export | Returns | Where it would have nothing |
+| --- | --- | --- |
+| `requestContext.context()` | the route's context, typed by `App` | throws a `ContextStorageError` |
+| `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` |
+| `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
+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:
+
+| 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 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` |
+
+The two errors carry these messages:
+
+| `code` | `message` |
+| --- | --- |
+| `OUTSIDE_REQUEST` | `getContext(): called outside a request — use tryGetContext(), or runWithContext() in a job or a test` |
+| `NOT_ROUTED` | `getContext(): this request reached no route declared after contextStorage() — use it earlier, or getRequestContext()` |
+
+Thrown inside a route, either one answers a `500 {"error":"internal"}` and
+is logged, like any other error. `code` tells them apart:
+
+```ts
+import { ContextStorageError, getContext } from '@alxia/context-storage';
+
+try {
+	getContext();
+} catch (error) {
+	if (error instanceof ContextStorageError) console.log(error.code); // 'OUTSIDE_REQUEST'
+}
+```
+
+Code that runs both in and out of requests uses `tryContext()`,
+`tryGetContext()` or `tryGetRequestContext()` instead of catching.
+
+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,
+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
+then call those without passing anything down.
+
+```ts
+// context.ts
+import { alxia } from '@alxia/core';
+import { contextStorage } from '@alxia/context-storage';
+
+export interface Order {
+	readonly id: number;
+	readonly userId: number;
+	readonly total: number;
+}
+
+const db = { orders: [{ id: 1, userId: 1, total: 42 }] as Order[] };
+const users = new Map([['Bearer ada', { id: 1, name: 'Ada' }]]);
+
+export const base = alxia()
+	.decorate({ db })
+	.derive(({ request, reply }) => {
+		const user = users.get(request.headers.get('authorization') ?? '');
+		return user ? { user } : reply(401, { error: 'unauthenticated' as const });
+	});
+
+export const requestContext = contextStorage<typeof base>();
+```
+
+```ts
+// orders.ts
+import { requestContext } from './context';
+
+export async function listOrders() {
+	const { db, user, set } = requestContext.context();
+	set.headers.set('cache-control', 'private');
+	return db.orders.filter((order) => order.userId === user.id);
+}
+```
+
+```ts
+// app.ts
+import { base, requestContext } from './context';
+import { listOrders } from './orders';
+
+export const app = base
+	.use(requestContext)
+	.get('/orders', async ({ reply }) => reply(200, await listOrders()));
+```
+
+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:
+
+```ts
+// log.ts
+import { tryGetRequestContext } from '@alxia/context-storage';
+import { requestContext } from './context';
+
+export function log(message: string): void {
+	const request = tryGetRequestContext(); // undefined outside a request
+	console.log(
+		JSON.stringify({
+			message,
+			method: request?.request.method,
+			route: request?.route,
+			user: requestContext.tryContext()?.user.id,
+		}),
+	);
+}
+```
+
+`log('listing orders')` from `listOrders` prints the method, `/orders` and
+the user's id; from startup, the message alone.
+
+## Typing it
+
+`contextStorage<App>()` takes the type of an app, and `context()` and `tryContext()`
+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 |
+
+```ts
+import { alxia } from '@alxia/core';
+import { contextStorage } from '@alxia/context-storage';
+
+const base = alxia()
+	.decorate({ greeting: 'Hello' })
+	.derive(({ request }) => ({ user: request.headers.get('x-user') ?? 'anonymous' }));
+
+const typed = contextStorage<typeof base>();
+const untyped = contextStorage();
+
+export function whoIsAsking(): string {
+	untyped.context().route;     // string: BaseContext only
+	// untyped.context().user — error TS2339: Property 'user' does not exist on type 'BaseContext'.
+	return typed.context().user; // string
+}
+```
+
+Three rules follow from typing by an app:
+
+- **Type it by the app before the plugin, never by the app that uses 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
+  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>()`.
+- **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:
+
+```ts
+import { getContext } from '@alxia/context-storage';
+
+// in code that only ever runs under GET /orders/:id, with a params schema
+const { params } = getContext<{ params: { id: number } }>();
+```
+
+`getContext<Ctx>()` and `tryGetContext<Ctx>()` believe what `Ctx` says,
+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:
+
+```ts
+import { alxia } from '@alxia/core';
+import { contextStorage, getContext } from '@alxia/context-storage';
+
+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
+	.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.
+
+| 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 |
+| 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` |
+| 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
+[refused](troubleshooting.md#typeerror-contextstorage-is-a-factory-usecontextstorage-not-usecontextstorage).
+
+## What `AsyncLocalStorage` carries
+
+The store follows the request's asynchronous work: every `await`, promise,
+`setTimeout` and microtask started while the request runs reads the
+context of that request, and concurrent requests never see each other's.
+
+```ts
+async function greet(): Promise<string> {
+	await Bun.sleep(10);
+	await new Promise((resolve) => setTimeout(resolve, 1));
+	const { greeting, user } = requestContext.context(); // still this request's
+	return `${greeting} ${user}`;
+}
+```
+
+A server-sent event stream's generator runs while the response streams, and
+reads the context too.
+
+What it carries is decided where a callback is **scheduled**, not where it
+runs:
+
+| The callback | Sees |
+| --- | --- |
+| a `setTimeout` or promise started in the request, firing after the response is sent | that request's context, stale: `context()` does not throw, but `set` no longer reaches any response |
+| 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` |
+
+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
+the context when it runs:
+
+```ts
+import { requestContext } from './context';
+
+const pending: (() => Promise<void>)[] = [];
+
+export function auditLater(action: string): void {
+	const { user, route } = requestContext.context(); // read now, in the request
+	pending.push(async () => {
+		console.log(JSON.stringify({ action, user: user.id, route }));
+	});
+}
+
+setInterval(() => {
+	for (const job of pending.splice(0)) void job(); // runs outside any request
+}, 1000);
+```
+
+For a socket, read what a message needs from `socket.data`, which holds the
+upgrade's context.
+
+## Jobs and tests: `runWithContext`
+
+`runWithContext(ctx, work)` runs `work` with `ctx` as the current context,
+for code that reads it outside any request: a queue consumer, a scheduled
+job, a unit test of a service. `getContext()` and `getRequestContext()` both
+return `ctx` while it runs, and `work`'s return value — a promise included
+— comes back as it is.
+
+`ctx` is a `BaseContext`. A job has no request to build one from, so give it
+what the code reads, and say that is all it is:
+
+```ts
+import type { ContextOf } from '@alxia/core';
+import { runWithContext } from '@alxia/context-storage';
+import { type base } from './context';
+import { listOrders } from './orders';
+
+type Ctx = ContextOf<typeof base>;
+
+const job = {
+	db: { orders: [{ id: 7, userId: 0, total: 1 }] },
+	user: { id: 0, name: 'nightly' },
+	set: { headers: new Headers(), cookies: new Bun.CookieMap() },
+} satisfies Partial<Ctx>;
+
+const orders = await runWithContext(job as unknown as Ctx, () => listOrders());
+```
+
+`satisfies` checks the fields you give against the app's context; the cast
+admits the ones you left out, which the code must not read.
+
+A test covers both sides — the service through a real request, and alone:
+
+```ts
+import { describe, expect, test } from 'bun:test';
+import type { ContextOf } from '@alxia/core';
+import { runWithContext } from '@alxia/context-storage';
+import { app } from './app';
+import { type base } from './context';
+import { listOrders } from './orders';
+
+describe('listOrders', () => {
+	test('reads the user of the request it runs in', async () => {
+		const response = await app.request('/orders', {
+			headers: { authorization: 'Bearer ada' },
+		});
+		expect(response.status).toBe(200);
+		expect(response.headers.get('cache-control')).toBe('private');
+		expect(await response.json()).toEqual([{ id: 1, userId: 1, total: 42 }]);
+	});
+
+	test('concurrent requests never see each other', async () => {
+		const answers = await Promise.all(
+			['Bearer ada', 'Bearer nobody', 'Bearer ada'].map(
+				async (authorization) =>
+					(await app.request('/orders', { headers: { authorization } })).status,
+			),
+		);
+		expect(answers).toEqual([200, 401, 200]);
+	});
+
+	test('runs alone, with a context of its own', async () => {
+		const ctx = {
+			db: { orders: [{ id: 2, userId: 9, total: 5 }] },
+			user: { id: 9, name: 'test' },
+			set: { headers: new Headers(), cookies: new Bun.CookieMap() },
+		} satisfies Partial<ContextOf<typeof base>>;
+
+		const orders = await runWithContext(ctx as unknown as ContextOf<typeof base>, listOrders);
+
+		expect(orders).toEqual([{ id: 2, userId: 9, total: 5 }]);
+		expect(ctx.set.headers.get('cache-control')).toBe('private');
+	});
+});
+```
+
+When `getContext()` throws, or a service reads the wrong context,
+[Troubleshooting](troubleshooting.md) starts from the message.

package/docs/roadmap.md

@@ -0,0 +1,50 @@
+# Roadmap
+
+What `@alxia/context-storage` gives an app, and what is coming. This page
+is a direction, not a commitment: the version something shipped in is the
+only number on it. Every release, with each change it made, is in
+[`CHANGELOG.md`](https://github.com/softistx/alxia/blob/develop/packages/context-storage/CHANGELOG.md).
+
+## Now
+
+Nothing scheduled yet.
+
+## Next
+
+Nothing scheduled yet.
+
+## Later
+
+Nothing scheduled yet.
+
+## Not planned
+
+- **A runtime dependency.** `@alxia/context-storage` declares no
+  dependency, only peers: `@alxia/core` and `typescript`. It is built on
+  `@alxia/core`'s public API and the runtime's own `AsyncLocalStorage`.
+
+## Shipped
+
+### 0.1.0
+
+- **The request's context anywhere it runs.** `alxia().use(contextStorage())`
+  lets a service, a repository or a logger read the context of the route
+  that called it with `getContext()`, without it being passed down, through
+  every `await`, timer and promise, and never another request's.
+- **Typed by the app.** `contextStorage<typeof base>()` gives `context()` and
+  `tryContext()` what a route declared next on `base` reads: the values its
+  `decorate` and `derive` hooks added.
+- **The request in global hooks.** `getRequestContext()` reads the request
+  before routing, in a 404 and in an `onResponse`, with the route it
+  reached and the error it failed with; `tryGetRequestContext()` returns
+  `undefined` outside a request instead of throwing.
+- **Jobs and tests.** `runWithContext(ctx, work)` runs code that reads the
+  context outside a request.
+- **A refusal that says why.** Where there is no context, `getContext()`
+  throws a `ContextStorageError` coded `OUTSIDE_REQUEST` or `NOT_ROUTED`,
+  and `tryGetContext()` returns `undefined`.
+  `use(contextStorage)`, the factory uncalled, fails `tsc` and throws a
+  `TypeError` at startup, rather than leaving the routes after it unserved.
+- **Ported from `hono/context-storage`.** One store, and `getContext()`
+  read wherever it is called, as Hono's is: code written against one ports
+  to the other.

package/docs/troubleshooting.md

@@ -0,0 +1,276 @@
+# Troubleshooting
+
+Each entry is headed by the text you see: an error in the server log, a
+behaviour that prints nothing, or an error from `tsc`. A
+`ContextStorageError` thrown inside a route also answers the request with
+`500 {"error":"internal"}`; the message is in the server log.
+
+**Runtime**
+
+- [`TypeError: contextStorage is a factory: use(contextStorage()), not use(contextStorage)`](#typeerror-contextstorage-is-a-factory-usecontextstorage-not-usecontextstorage)
+- [`ContextStorageError: getContext(): called outside a request — use tryGetContext(), or runWithContext() in a job or a test`](#contextstorageerror-getcontext-called-outside-a-request--use-trygetcontext-or-runwithcontext-in-a-job-or-a-test)
+- [`ContextStorageError: getContext(): this request reached no route declared after contextStorage() — use it earlier, or getRequestContext()`](#contextstorageerror-getcontext-this-request-reached-no-route-declared-after-contextstorage--use-it-earlier-or-getrequestcontext)
+- [A header set from a timer never reaches the response](#a-header-set-from-a-timer-never-reaches-the-response)
+
+**Types**
+
+- [`'requestContext' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.`](#requestcontext-implicitly-has-type-any-because-it-does-not-have-a-type-annotation-and-is-referenced-directly-or-indirectly-in-its-own-initializer)
+- [`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)
+
+## Runtime
+
+### `TypeError: contextStorage is a factory: use(contextStorage()), not use(contextStorage)`
+
+`tsc` reports the same mistake first:
+
+```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>'.
+```
+
+**When:** at startup, on `.use(contextStorage)`: the factory given to `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.
+
+**Fix:** call it, once, and keep the result:
+
+```ts
+export const requestContext = contextStorage<typeof base>();
+
+const app = base.use(requestContext);
+```
+
+### `ContextStorageError: getContext(): called outside a request — use tryGetContext(), or runWithContext() in a job or a test`
+
+`error.code` is `'OUTSIDE_REQUEST'`. `getContext()`, `requestContext.context()`
+and `getRequestContext()` all throw it.
+
+**When:** the code that reads the context runs where no request is:
+
+- at the top level of a module, or in code run at startup;
+- 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;
+- 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.
+
+**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
+**scheduled**; anything started outside a request has none.
+
+**Fix:** in code that runs in and out of requests, use `tryContext()` —
+or `tryGetRequestContext()` for the request alone:
+
+```ts
+const user = requestContext.tryContext()?.user; // undefined outside a request
+const method = tryGetRequestContext()?.request.method; // the same
+```
+
+In a job, a consumer or a test, give the code a context to read:
+
+```ts
+import type { ContextOf } from '@alxia/core';
+import { runWithContext } from '@alxia/context-storage';
+
+type Ctx = ContextOf<typeof base>;
+
+const job = {
+	db,
+	user: { id: 0, name: 'nightly' },
+	set: { headers: new Headers(), cookies: new Bun.CookieMap() },
+} satisfies Partial<Ctx>;
+
+await runWithContext(job as unknown as Ctx, () => listOrders());
+```
+
+For work that outlives the request, read the context in the request and
+hand the values over:
+
+```ts
+export function auditLater(action: string): void {
+	const { user } = requestContext.context(); // in the request
+	pending.push(() => audit(action, user.id)); // runs later, needs nothing
+}
+```
+
+In a socket handler, read what the upgrade's hooks 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.
+
+### `ContextStorageError: getContext(): this request reached no route declared after contextStorage() — use it earlier, or getRequestContext()`
+
+`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.
+
+**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()));
+```
+
+In a global hook, or in code that also runs for a 404, read the request
+instead, which holds wherever there is one:
+
+```ts
+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);
+});
+```
+
+### A header set from a timer never reaches the response
+
+**When:** a `setTimeout`, a promise that is not awaited, or a callback
+started in a request calls `requestContext.context().set.headers.set(…)` — or
+sets a cookie — after the handler has returned.
+
+**Why:** the callback still reads the request's context — `context()` does not
+throw — but the response was already sent. The context is stale, not gone.
+
+**Fix:** await the work that shapes the response before replying, and
+detach only what does not:
+
+```ts
+const app = base.use(requestContext).get('/orders', async ({ reply }) => {
+	const orders = await listOrders(); // sets cache-control while the response is open
+	void sendReceipt();                // detached: must not touch `set`
+	return reply(200, orders);
+});
+```
+
+
+## Types
+
+### `'requestContext' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.`
+
+```text
+error TS7022: 'app' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.
+error TS7022: 'requestContext' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.
+```
+
+Often with `TS2448: Block-scoped variable 'requestContext' used before its declaration.`
+
+**When:** the plugin is typed by the app that uses 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`.
+
+**Fix:** type it by the app as it stands **before** the plugin:
+
+```ts
+export const base = alxia().decorate({ db });
+export const requestContext = contextStorage<typeof base>();
+export const app = base.use(requestContext).get('/orders', ({ reply }) => reply(200, 'ok'));
+```
+
+### `Property 'user' does not exist on type 'BaseContext'.`
+
+```text
+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
+
+- the plugin was made without an app type, `contextStorage()`; or
+- it is typed by `base`, and the hook 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
+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:
+
+```ts
+const base = alxia()
+	.decorate({ db })
+	.derive(({ request }) => ({ user: request.headers.get('x-user') ?? 'anonymous' }));
+
+export const requestContext = contextStorage<typeof base>();
+// requestContext.context().user: string
+```
+
+### `Property 'params' does not exist on type 'BaseContext & …'.`
+
+```text
+error TS2339: Property 'params' does not exist on type 'BaseContext & Empty & { readonly db: … }'.
+```
+
+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.
+
+**Fix:** pass them from the handler, or, in code that only runs under one
+route, state them:
+
+```ts
+import { getContext } from '@alxia/context-storage';
+
+const { params } = getContext<{ params: { id: number } }>(); // nothing checks this
+```
+
+### `Object literal may only specify known properties, and 'db' does not exist in type 'BaseContext'.`
+
+```text
+error TS2353: Object literal may only specify known properties, and 'db' does not exist in type 'BaseContext'.
+```
+
+**When:** `runWithContext({ db, user }, work)`, with a context written by
+hand for a job or a test.
+
+**Why:** `runWithContext` takes a `BaseContext`: a whole request context.
+A job has no request, so a literal has neither the fields it requires nor
+room for the ones the app adds.
+
+**Fix:** check the fields against the app's context with `satisfies`, and
+cast — `work` must then read only what you gave:
+
+```ts
+import type { ContextOf } from '@alxia/core';
+
+type Ctx = ContextOf<typeof base>;
+
+const ctx = {
+	db,
+	user: { id: 0, name: 'job' },
+	set: { headers: new Headers(), cookies: new Bun.CookieMap() }, // listOrders sets a header
+} satisfies Partial<Ctx>;
+
+runWithContext(ctx as unknown as Ctx, () => listOrders());
+```

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@alxia/context-storage",
+	"version": "0.1.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",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"docs",
+		"README.md",
+		"package.json",
+		"LICENSE"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/alxia.git",
+		"directory": "packages/context-storage"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun run ../../build.ts",
+		"test": "bun test src",
+		"typecheck": "tsc --noEmit"
+	},
+	"alxia": {
+		"entrypoints": [
+			"src/index.ts"
+		]
+	},
+	"devDependencies": {
+		"@alxia/core": "^0.1.0",
+		"@types/bun": "^1.4.2",
+		"zod": "^4.6.5"
+	},
+	"peerDependencies": {
+		"@alxia/core": "^0.1.0",
+		"typescript": "^6.0.3 || ^7.0.0"
+	}
+}