@rhythmjs/http 0.0.1 → 0.0.3

package/README.md

@@ -77,6 +77,48 @@ new RhythmRouter().use(etag()).get("/report", (ctx) => {
 - `etag({ weak: true })` emits `W/"..."` tags.
 - Only successful (2xx) string bodies are tagged; a pre-set `ETag` is left alone.
 
+## `@rhythmjs/http/i18n`
+
+[i18next](https://www.i18next.com/) integration: detects the request language, exposes a
+request-scoped translator on the context, and sets the `Content-Language` response header. The
+middleware is typed and coupled structurally (`I18nInstanceLike`) rather than against i18next's own
+types — every instance capability (`cloneInstance`, `getFixedT`, `changeLanguage`, `init`) is
+feature-detected at runtime, so it works across i18next versions (optional peer dependency, any
+version) and with any compatible instance.
+
+```ts
+import i18next from "i18next";
+import { i18n, type I18nContext } from "@rhythmjs/http/i18n";
+
+await i18next.init({
+  supportedLngs: ["en", "de"],
+  fallbackLng: "en",
+  resources: {
+    en: { translation: { greeting: "Hello {{name}}" } },
+    de: { translation: { greeting: "Hallo {{name}}" } },
+  },
+});
+
+new RhythmRouter().use<I18nContext>(i18n({ i18next })).get("/greet", (ctx) => {
+  ctx.response.body = ctx.t("greeting", { name: "Ada" }); // "Hallo Ada" for ?lng=de
+});
+```
+
+- `ctx.t` — the instance's own `t` type bound to the detected language (a real i18next instance
+  keeps its full `TFunction` typing); `ctx.language` — the resolved language; `ctx.i18n` — a
+  request-scoped clone when the instance supports `cloneInstance` (safe for `changeLanguage` per
+  request), otherwise a `getFixedT`-based fallback.
+- Detection tries `?lng=` querystring, the `i18next` cookie, then `Accept-Language` (ordered by
+  quality, matched exactly or by base language against `supportedLngs`), falling back to
+  `fallbackLng`. Configure via `detection` — `order` (may include `"path"` for `/de/...`-style
+  prefixes with `lookupPath` as the segment index), `lookupQuerystring`, `lookupCookie`,
+  `supportedLanguages`, `fallbackLanguage`.
+- `cacheCookie: true` persists the resolved language in the detection cookie
+  (`cacheCookieMaxAge` seconds, default one year); `contentLanguage: false` disables the response
+  header. An uninitialized instance is initialized on first request.
+- The standalone `detectLanguage(request, options?)` and `parseAcceptLanguage(header)` helpers are
+  exported too.
+
 ## `@rhythmjs/http/timeout`
 
 Fails requests that exceed a deadline with `504 { "success": false, "status": 504, "message": "Gateway Timeout" }`.
@@ -105,6 +147,49 @@ new RhythmRouter().use(bodyLimit(1024 * 1024)).post("/upload", async (ctx) => {
 });
 ```
 
+## `@rhythmjs/http/request-scope`
+
+Opens a per-request scope (backed by
+[`AsyncLocalStorage`](https://nodejs.org/api/async_context.html)) holding the current
+`RhythmHttpContext` plus a request-local key-value store, readable anywhere in the call stack — loggers,
+database helpers, service functions — without threading `ctx` through every signature.
+
+```ts
+import { requestScope, RequestScope } from "@rhythmjs/http/request-scope";
+
+new RhythmRouter()
+  .use(requestScope())
+  .use(async (_ctx, next) => {
+    RequestScope.set("requestId", crypto.randomUUID());
+    await next();
+  })
+  .get("/greet", (ctx) => {
+    ctx.response.body = greeting();
+  });
+
+// Anywhere else, no ctx parameter needed:
+function greeting() {
+  const path = new URL(RequestScope.context().request.url).pathname;
+  return `Hello from ${path} (request ${RequestScope.get("requestId")})`;
+}
+```
+
+- `requestScope()` — register it before any middleware or handler that uses `RequestScope`. Each request
+  gets its own scope; concurrent requests never see each other's context or store.
+- `RequestScope.context<TContext>()` — the current context. Pass your extended context type (e.g.
+  `RequestScope.context<RhythmHttpContext & CookiesContext>()`) for typed access to properties added by
+  earlier middleware.
+- `RequestScope.get(key)` / `set(key, value)` / `has(key)` / `delete(key)` — the request-local store, for
+  values that belong to the request but not on the context (request ids, loggers, the authenticated
+  user). Augment the `RequestScopeStore` interface via declaration merging to type your keys.
+- `RequestScope.run(context, fn)` — open a scope manually, for tests and non-HTTP entry points that reuse
+  request-scoped helpers.
+- Naming convention: bare accessors (`context()`, `get()`, `set()`, …) throw `RequestScopeError` when no
+  scope is active; `contextOrNull()` and `isActive()` never throw, for code that runs both inside and
+  outside requests.
+- Requires an `AsyncLocalStorage`-capable runtime: Node.js, Bun, and Deno work out of the box; on
+  Cloudflare Workers enable the `nodejs_compat` (or `nodejs_als`) compatibility flag.
+
 ## Development
 
 ```sh

package/dist/body-limit/body-limit.d.ts

@@ -1,4 +1,4 @@
-import { Middleware } from "@rhythmjs/rhythm";
+import { Middleware } from "@rhythmjs/rhythm/types";
 import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
 //#region src/body-limit/body-limit.d.ts
 export declare function bodyLimit(maxBytes: number): Middleware<RhythmHttpContext>;

package/dist/cookies/cookies.d.ts

@@ -1,4 +1,4 @@
-import { Middleware } from "@rhythmjs/rhythm";
+import { DeriveMiddleware } from "@rhythmjs/rhythm/types";
 import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
 //#region src/cookies/cookies.d.ts
 export interface CookieOptions {
@@ -23,5 +23,5 @@ export declare class Cookies {
 export type CookiesContext = {
   cookies: Cookies;
 };
-export declare function cookies(): Middleware<RhythmHttpContext>;
+export declare function cookies(): DeriveMiddleware<RhythmHttpContext, CookiesContext>;
 //#endregion

package/dist/cookies/cookies.js

@@ -56,9 +56,11 @@ var Cookies = class {
 	}
 };
 function cookies() {
-	return async (ctx, next) => {
-		await next({ cookies: new Cookies(parseCookies(ctx.request.headers.get("cookie")), ctx.response.headers) });
+	const middleware = async (ctx, next) => {
+		ctx.cookies = new Cookies(parseCookies(ctx.request.headers.get("cookie")), ctx.response.headers);
+		await next();
 	};
+	return middleware;
 }
 //#endregion
 export { Cookies, cookies, parseCookies, serializeCookie };

package/dist/etag/etag.d.ts

@@ -1,4 +1,4 @@
-import { Middleware } from "@rhythmjs/rhythm";
+import { Middleware } from "@rhythmjs/rhythm/types";
 import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
 //#region src/etag/etag.d.ts
 export interface EtagOptions {

package/dist/i18n/i18n.d.ts

@@ -0,0 +1,46 @@
+import { DeriveMiddleware } from "@rhythmjs/rhythm/types";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/i18n/i18n.d.ts
+export type DetectionSource = "querystring" | "cookie" | "header" | "path";
+export interface LanguageDetectionOptions {
+  order?: DetectionSource[];
+  lookupQuerystring?: string;
+  lookupCookie?: string;
+  lookupPath?: number;
+  supportedLanguages?: string[];
+  fallbackLanguage?: string;
+}
+export interface I18nInstanceLike {
+  t: (...args: any[]) => any;
+  isInitialized?: boolean;
+  language?: string;
+  resolvedLanguage?: string;
+  options?: {
+    supportedLngs?: unknown;
+    fallbackLng?: unknown;
+  };
+  init?: (...args: any[]) => any;
+  cloneInstance?: (...args: any[]) => any;
+  changeLanguage?: (...args: any[]) => any;
+  getFixedT?: (...args: any[]) => (...args: any[]) => any;
+}
+export interface I18nContext<TInstance extends I18nInstanceLike = I18nInstanceLike> {
+  i18n: TInstance;
+  t: TInstance["t"];
+  language: string;
+}
+export interface I18nOptions<TInstance extends I18nInstanceLike = I18nInstanceLike> {
+  i18next: TInstance;
+  detection?: LanguageDetectionOptions;
+  cacheCookie?: boolean;
+  cacheCookieMaxAge?: number;
+  contentLanguage?: boolean;
+}
+export interface AcceptedLanguage {
+  language: string;
+  quality: number;
+}
+export declare function parseAcceptLanguage(header: string | null): AcceptedLanguage[];
+export declare function detectLanguage(request: Request, options?: LanguageDetectionOptions): string | undefined;
+export declare function i18n<TInstance extends I18nInstanceLike>(options: I18nOptions<TInstance>): DeriveMiddleware<RhythmHttpContext, I18nContext<TInstance>>;
+//#endregion

package/dist/i18n/i18n.js

@@ -0,0 +1,139 @@
+//#region src/i18n/i18n.ts
+function parseAcceptLanguage(header) {
+	if (!header) return [];
+	const accepted = [];
+	for (const part of header.split(",")) {
+		const [tag, ...params] = part.trim().split(";");
+		const language = tag?.trim();
+		if (!language) continue;
+		let quality = 1;
+		for (const param of params) {
+			const [key, value] = param.split("=");
+			if (key?.trim().toLowerCase() !== "q") continue;
+			const parsed = Number.parseFloat(value ?? "");
+			if (!Number.isNaN(parsed)) quality = Math.min(Math.max(parsed, 0), 1);
+		}
+		if (quality > 0) accepted.push({
+			language,
+			quality
+		});
+	}
+	return accepted.sort((a, b) => b.quality - a.quality);
+}
+function readCookie(header, name) {
+	if (!header) return void 0;
+	for (const part of header.split(/;\s*/)) {
+		const eq = part.indexOf("=");
+		if (eq === -1) continue;
+		if (part.slice(0, eq).trim() !== name) continue;
+		try {
+			return decodeURIComponent(part.slice(eq + 1).trim());
+		} catch {
+			return part.slice(eq + 1).trim();
+		}
+	}
+}
+function candidatesFrom(request, options) {
+	const order = options.order ?? [
+		"querystring",
+		"cookie",
+		"header"
+	];
+	const url = new URL(request.url);
+	for (const source of order) {
+		let candidates = [];
+		if (source === "querystring") {
+			const value = url.searchParams.get(options.lookupQuerystring ?? "lng");
+			if (value) candidates = [value];
+		} else if (source === "cookie") {
+			const value = readCookie(request.headers.get("cookie"), options.lookupCookie ?? "i18next");
+			if (value) candidates = [value];
+		} else if (source === "path") {
+			const value = url.pathname.split("/").filter((segment) => segment !== "")[options.lookupPath ?? 0];
+			if (value) candidates = [value];
+		} else candidates = parseAcceptLanguage(request.headers.get("accept-language")).map((entry) => entry.language).filter((language) => language !== "*");
+		if (candidates.length > 0) return candidates;
+	}
+	return [];
+}
+function matchLanguage(candidates, supported) {
+	if (supported === void 0 || supported.length === 0) return candidates[0];
+	const byLower = new Map(supported.map((language) => [language.toLowerCase(), language]));
+	for (const candidate of candidates) {
+		const lower = candidate.toLowerCase();
+		const exact = byLower.get(lower);
+		if (exact !== void 0) return exact;
+		const base = byLower.get(lower.split("-")[0]);
+		if (base !== void 0) return base;
+		const baseOfSupported = supported.find((language) => language.toLowerCase().split("-")[0] === lower);
+		if (baseOfSupported !== void 0) return baseOfSupported;
+	}
+}
+function detectLanguage(request, options = {}) {
+	return matchLanguage(candidatesFrom(request, options), options.supportedLanguages) ?? options.fallbackLanguage;
+}
+function supportedFromInstance(instance) {
+	const supported = instance.options?.supportedLngs;
+	if (!Array.isArray(supported)) return void 0;
+	const languages = supported.filter((language) => typeof language === "string" && language !== "cimode");
+	return languages.length > 0 ? languages : void 0;
+}
+function fallbackFromInstance(instance) {
+	const fallback = instance.options?.fallbackLng;
+	if (typeof fallback === "string") return fallback;
+	if (Array.isArray(fallback) && typeof fallback[0] === "string") return fallback[0];
+}
+function isInstanceLike(value) {
+	return typeof value === "object" && value !== null && typeof value.t === "function";
+}
+async function scopeInstance(instance, language) {
+	if (typeof instance.cloneInstance === "function") {
+		const clone = instance.cloneInstance();
+		if (isInstanceLike(clone)) {
+			const scoped = clone;
+			if (language !== void 0 && language !== scoped.language && typeof scoped.changeLanguage === "function") await scoped.changeLanguage(language);
+			return {
+				scoped,
+				translate: scoped.t.bind(scoped),
+				resolved: scoped.resolvedLanguage ?? scoped.language ?? language ?? ""
+			};
+		}
+	}
+	if (language !== void 0 && typeof instance.getFixedT === "function") return {
+		scoped: instance,
+		translate: instance.getFixedT(language),
+		resolved: language
+	};
+	if (language !== void 0 && language !== instance.language && typeof instance.changeLanguage === "function") await instance.changeLanguage(language);
+	return {
+		scoped: instance,
+		translate: instance.t.bind(instance),
+		resolved: instance.resolvedLanguage ?? instance.language ?? language ?? ""
+	};
+}
+function i18n(options) {
+	const instance = options.i18next;
+	const detection = options.detection ?? {};
+	const cookieName = detection.lookupCookie ?? "i18next";
+	const cacheCookieMaxAge = options.cacheCookieMaxAge ?? 31536e3;
+	let initializing;
+	const middleware = async (ctx, next) => {
+		if (instance.isInitialized !== true && typeof instance.init === "function") {
+			initializing ??= Promise.resolve(instance.init());
+			await initializing;
+		}
+		const supported = detection.supportedLanguages ?? supportedFromInstance(instance);
+		const fallback = detection.fallbackLanguage ?? fallbackFromInstance(instance);
+		const language = matchLanguage(candidatesFrom(ctx.request, detection), supported) ?? fallback;
+		const { scoped, translate, resolved } = await scopeInstance(instance, language);
+		ctx.i18n = scoped;
+		ctx.t = translate;
+		ctx.language = resolved;
+		await next();
+		if (options.cacheCookie === true && resolved !== "" && readCookie(ctx.request.headers.get("cookie"), cookieName) !== resolved) ctx.response.headers.append("set-cookie", `${cookieName}=${encodeURIComponent(resolved)}; Max-Age=${cacheCookieMaxAge}; Path=/; SameSite=Lax`);
+		if (options.contentLanguage !== false && resolved !== "" && ctx.response.headers.get("content-language") === null) ctx.response.headers.set("content-language", resolved);
+	};
+	return middleware;
+}
+//#endregion
+export { detectLanguage, i18n, parseAcceptLanguage };

package/dist/request-scope/request-scope.d.ts

@@ -0,0 +1,22 @@
+import { Middleware } from "@rhythmjs/rhythm/types";
+import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
+//#region src/request-scope/request-scope.d.ts
+export interface RequestScopeStore {}
+export declare class RequestScopeError extends Error {
+  constructor(message: string);
+}
+export declare function requestScope<TContext extends RhythmHttpContext = RhythmHttpContext>(): Middleware<TContext>;
+export declare class RequestScope {
+  private constructor();
+  static isActive(): boolean;
+  static context<TContext extends RhythmHttpContext = RhythmHttpContext>(): TContext;
+  static contextOrNull<TContext extends RhythmHttpContext = RhythmHttpContext>(): TContext | null;
+  static get<K extends keyof RequestScopeStore>(key: K): RequestScopeStore[K] | undefined;
+  static get<T = unknown>(key: string | symbol): T | undefined;
+  static set<K extends keyof RequestScopeStore>(key: K, value: RequestScopeStore[K]): void;
+  static set<T = unknown>(key: string | symbol, value: T): void;
+  static has(key: string | symbol): boolean;
+  static delete(key: string | symbol): boolean;
+  static run<TContext extends RhythmHttpContext, TResult>(context: TContext, fn: () => TResult): TResult;
+}
+//#endregion

package/dist/request-scope/request-scope.js

@@ -0,0 +1,54 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/request-scope/request-scope.ts
+var RequestScopeError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RequestScopeError";
+	}
+};
+const frames = new AsyncLocalStorage();
+function activeFrame(operation) {
+	const frame = frames.getStore();
+	if (frame === void 0) throw new RequestScopeError(`RequestScope.${operation}() was called outside an active request scope. Register the requestScope() middleware before anything that uses RequestScope, or open a scope manually with RequestScope.run().`);
+	return frame;
+}
+function requestScope() {
+	return async (ctx, next) => {
+		await frames.run({
+			context: ctx,
+			store: /* @__PURE__ */ new Map()
+		}, next);
+	};
+}
+var RequestScope = class {
+	constructor() {}
+	static isActive() {
+		return frames.getStore() !== void 0;
+	}
+	static context() {
+		return activeFrame("context").context;
+	}
+	static contextOrNull() {
+		return frames.getStore()?.context ?? null;
+	}
+	static get(key) {
+		return activeFrame("get").store.get(key);
+	}
+	static set(key, value) {
+		activeFrame("set").store.set(key, value);
+	}
+	static has(key) {
+		return activeFrame("has").store.has(key);
+	}
+	static delete(key) {
+		return activeFrame("delete").store.delete(key);
+	}
+	static run(context, fn) {
+		return frames.run({
+			context,
+			store: /* @__PURE__ */ new Map()
+		}, fn);
+	}
+};
+//#endregion
+export { RequestScope, RequestScopeError, requestScope };

package/dist/session/session.d.ts

@@ -1,4 +1,4 @@
-import { Middleware } from "@rhythmjs/rhythm";
+import { DeriveMiddleware } from "@rhythmjs/rhythm/types";
 import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
 //#region src/session/session.d.ts
 export type SessionData = Record<string, unknown>;
@@ -31,5 +31,5 @@ export interface SessionOptions {
   secure?: boolean;
   sameSite?: "strict" | "lax" | "none";
 }
-export declare function session(options?: SessionOptions): Middleware<RhythmHttpContext>;
+export declare function session(options?: SessionOptions): DeriveMiddleware<RhythmHttpContext, SessionContext>;
 //#endregion

package/dist/session/session.js

@@ -40,14 +40,14 @@ function session(options = {}) {
 	const path = options.path ?? "/";
 	const sameSite = options.sameSite ?? "lax";
 	const baseAttributes = `; Path=${path}; HttpOnly; SameSite=${`${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`}${options.secure ? "; Secure" : ""}`;
-	return async (ctx, next) => {
+	const middleware = async (ctx, next) => {
 		const incomingId = readCookie(ctx.request.headers.get("cookie"), cookieName);
 		const existing = incomingId === void 0 ? void 0 : await store.get(incomingId);
 		const id = existing === void 0 ? crypto.randomUUID() : incomingId;
 		const data = { ...existing };
 		let dirty = false;
 		let destroyed = false;
-		await next({ session: {
+		ctx.session = {
 			id,
 			get: (key) => data[key],
 			set: (key, value) => {
@@ -61,7 +61,8 @@ function session(options = {}) {
 			destroy: () => {
 				destroyed = true;
 			}
-		} });
+		};
+		await next();
 		if (destroyed) {
 			if (incomingId !== void 0) await store.delete(incomingId);
 			ctx.response.headers.append("set-cookie", `${cookieName}=; Max-Age=0${baseAttributes}`);
@@ -72,6 +73,7 @@ function session(options = {}) {
 			if (existing === void 0) ctx.response.headers.append("set-cookie", `${cookieName}=${id}; Max-Age=${maxAge}${baseAttributes}`);
 		}
 	};
+	return middleware;
 }
 //#endregion
 export { MemoryStore, session };

package/dist/timeout/timeout.d.ts

@@ -1,4 +1,4 @@
-import { Middleware } from "@rhythmjs/rhythm";
+import { Middleware } from "@rhythmjs/rhythm/types";
 import { RhythmHttpContext } from "@rhythmjs/router/adapters/context";
 //#region src/timeout/timeout.d.ts
 export declare function timeout(ms: number): Middleware<RhythmHttpContext>;

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@rhythmjs/http",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "HTTP utility middleware (cookies, sessions, etag, timeout, body limit) for Rhythm routers and handlers.",
   "keywords": [
+    "async-local-storage",
     "body-limit",
     "cookies",
     "etag",
     "http",
+    "i18n",
+    "i18next",
     "middleware",
+    "request-scope",
     "rhythm",
     "session",
     "timeout"
@@ -35,6 +39,14 @@
       "types": "./dist/etag/etag.d.ts",
       "default": "./dist/etag/etag.js"
     },
+    "./i18n": {
+      "types": "./dist/i18n/i18n.d.ts",
+      "default": "./dist/i18n/i18n.js"
+    },
+    "./request-scope": {
+      "types": "./dist/request-scope/request-scope.d.ts",
+      "default": "./dist/request-scope/request-scope.js"
+    },
     "./session": {
       "types": "./dist/session/session.d.ts",
       "default": "./dist/session/session.js"
@@ -48,27 +60,32 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vp pack",
-    "prepublishOnly": "vp check && vp test && vp pack",
-    "typecheck": "tsc --noEmit",
-    "test": "vp test",
-    "lint": "vp lint",
-    "fmt": "vp fmt",
-    "fmt:check": "vp fmt --check",
-    "check": "vp check"
-  },
   "devDependencies": {
     "@types/node": "^26.6.3",
+    "i18next": "^26.4.2",
     "typescript": "^7.0.2",
     "vite-plus": "^1.0.0"
   },
   "peerDependencies": {
-    "@rhythmjs/rhythm": "^0.0.1",
-    "@rhythmjs/router": "^0.0.1"
+    "@rhythmjs/rhythm": "^0.0.5",
+    "@rhythmjs/router": "^0.0.5",
+    "i18next": "*"
+  },
+  "peerDependenciesMeta": {
+    "i18next": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=20.19.0"
   },
-  "packageManager": "pnpm@10.33.2"
-}
+  "scripts": {
+    "build": "vp pack",
+    "typecheck": "tsc --noEmit",
+    "test": "vp test",
+    "lint": "vp lint",
+    "fmt": "vp fmt",
+    "fmt:check": "vp fmt --check",
+    "check": "vp check"
+  }
+}