lambder 3.1.1 → 3.2.1

package/Readme.md

@@ -2,7 +2,7 @@
 
 Lambder is a highly opinionated dynamic serverless framework designed to facilitate the management and implementation of routes and APIs within AWS Lambda functions, specifically tailored for TypeScript projects. It provides a streamlined approach to handling HTTP requests, managing sessions, and defining API routes, making serverless application development more intuitive and structured.
 
-**New in v3:** Public file serving with `servePublicFiles()` + `serveIndexHtml()`, unified `addAction()` for non-HTTP triggers, automatic gzip + ETag, thrown responses with a real `die`, the comment-based `LambderTemplatingEngine`, type-safe `html`/`xml` tagged templates, and API Gateway HTTP API (payload v2) / Lambda Function URL support.
+**New in v3:** Public file serving with `servePublicFiles()` + `serveIndexHtml()`, unified `addAction()` for non-HTTP triggers, automatic gzip + ETag, thrown responses with a real `die`, the comment-based `LambderTemplatingEngine`, type-safe `html`/`xml` tagged templates, API Gateway HTTP API (payload v2) / Lambda Function URL support, the `LambderDdbCache` DynamoDB cache (3.1) and typed translations with `createLambderI18n` (3.2).
 
 ## Features
 
@@ -14,6 +14,19 @@ Lambder is a highly opinionated dynamic serverless framework designed to facilit
 - **Error Handling**: Comprehensive error handling capabilities, including global error handlers and route-specific fallbacks.
 - **Seamless Integration**: Works with API Gateway REST APIs (payload v1), HTTP APIs (payload v2) and Lambda Function URLs; the payload format is detected per event.
 
+## Standalone Modules
+
+Self-contained tools that ship with the package and work with or without the framework. Each has its own guide:
+
+| Module | Guide | Description |
+|---|---|---|
+| `html` / `xml` tags + `LambderTemplatingEngine` | [docs/TEMPLATING.md](./docs/TEMPLATING.md) | Type-safe tagged templates and a comment-only HTML template engine (build-pipeline-safe) |
+| `LambderDdbCache` | [docs/DDB_CACHE.md](./docs/DDB_CACHE.md) | DynamoDB-backed compressed JSON cache with lease-based single-fill (server-only) |
+| `createLambderI18n` | [docs/I18N.md](./docs/I18N.md) | Typed translations with enforced/optional languages, component-level extension and auto language detection (isomorphic) |
+| `LambderMSW` | [docs/LAMBDER_MSW.md](./docs/LAMBDER_MSW.md) | Typed MSW mocking of the API contract for frontend development |
+
+Also see [docs/TYPE_SAFE_QUICK_START.md](./docs/TYPE_SAFE_QUICK_START.md) and [docs/DYNAMODB_SETUP.md](./docs/DYNAMODB_SETUP.md).
+
 ## Installation
 
 ```bash
@@ -278,23 +291,15 @@ Access the session controller with `lambder.getSessionController(ctx)`:
 
 ### Type-Safe Templating (html / xml)
 
-Lambder ships zero-dependency tagged template literals instead of a template engine. Interpolated values are HTML-escaped automatically, and everything is plain TypeScript, so templates are fully type-checked and refactorable.
+Lambder ships zero-dependency tagged template literals instead of a template engine. Interpolated values are HTML-escaped automatically, and everything is plain TypeScript, so templates are fully type-checked and refactorable. **Full guide: [docs/TEMPLATING.md](./docs/TEMPLATING.md).**
 
 ```typescript
 import { html, xml, raw } from "lambder";
 
-// Values are escaped by default (XSS-safe):
-const page = html`<h1>Hello ${user.name}</h1>`;
-
-// Arrays flatten; nested fragments are not double-escaped:
+// Values are escaped by default (XSS-safe); arrays flatten; nested fragments
+// are not double-escaped; null/undefined/false render as empty string:
 const list = html`<ul>${items.map((item) => html`<li>${item.label}</li>`)}</ul>`;
 
-// Conditionals: null/undefined/false render as empty string:
-const nav = html`${isLoggedIn && html`<a href="/logout">Log out</a>`}`;
-
-// raw() inserts trusted markup verbatim (never pass user input):
-const head = html`${raw('<meta charset="utf-8">')}`;
-
 // Works for XML too (xml is an alias of html):
 return res.xml(xml`<?xml version="1.0" encoding="UTF-8"?>
 <urlset>${urls.map((loc) => xml`<url><loc>${loc}</loc></url>`)}</urlset>`);
@@ -302,77 +307,41 @@ return res.xml(xml`<?xml version="1.0" encoding="UTF-8"?>
 
 ### Templating with LambderTemplatingEngine
 
-`LambderTemplatingEngine` is a standalone, comment-only HTML template engine. Every construct is an HTML comment, so templates survive HTML build pipelines (e.g. Vite) untouched, and during frontend development the browser simply renders the default content because the markers are invisible. It can template anything: SPA shells, emails, error pages.
-
-**Syntax** (everything is an HTML comment):
+`LambderTemplatingEngine` is a standalone, comment-only HTML template engine. Every construct is an HTML comment, so templates survive HTML build pipelines (e.g. Vite) untouched, and during frontend development the browser simply renders the default content because the markers are invisible. **Full guide: [docs/TEMPLATING.md](./docs/TEMPLATING.md).**
 
 ```html
 <title><!--slot:title-->Default Title<!--/slot:title--></title>   <!-- replaceable region -->
 <!--slot:head/-->                                                  <!-- insert-only point -->
 <!--if:isRtl--><body dir="rtl"><!--else--><body><!--/if:isRtl-->   <!-- conditional -->
-<!--if:!minimal--><nav>...</nav><!--/if:!minimal-->                <!-- negated conditional -->
 ```
 
-**Usage** (standalone, importable directly from `lambder`):
-
 ```typescript
-import { LambderTemplatingEngine, html, jsonScript } from "lambder";
+import { LambderTemplatingEngine, html } from "lambder";
 
-// Compile once (throws early on unclosed/mismatched blocks) ...
 const template = await LambderTemplatingEngine.fromFile("./templates/page.html");
-// ... render many times, per request:
 const output = template.render({
-    title: userInput,                                         // plain values are escaped (XSS-safe)
-    head: html`<link rel="canonical" href="${canonicalUrl}" />
-        ${jsonScript("app-data", preloadedState)}`,           // html`...`/raw()/jsonScript() inserted verbatim
-    isRtl: lang === "ar",                                     // condition names use truthiness
+    title: userInput,                                        // escaped (XSS-safe)
+    head: html`<link rel="canonical" href="${canonicalUrl}" />`,
+    isRtl: lang === "ar",
 });
-
-// Runtime introspection (dynamically typed by design):
-template.slotNames;       // e.g. ["title", "head"]
-template.conditionNames;  // e.g. ["isRtl", "minimal"]
-template.has("title");    // true
 ```
 
-Rules:
-- Slot values: strings/numbers escaped; `html`/`raw()`/`jsonScript()` verbatim; arrays flattened; `null`/`undefined`/`false` keep the slot's default content
-- Unknown data keys are ignored, so one data object can serve several templates with different slots
-- Blocks nest freely; there are intentionally no loops or inline expressions: build dynamic lists server-side with `html` and pass them into a slot
-- Attribute-position values (e.g. `<html lang="...">`) are handled with if/else around whole-tag variants
-
 ### Hosting a frontend build (servePublicFiles + templateFile)
 
-Lambder has no SPA-specific machinery; hosting a frontend build is a recipe built from three generic primitives:
-
-1. **`servePublicFiles(options?)`**: a terminal slot that serves real files under `publicPath`. It runs only when no route or API matched, so unlike a `"/(.*)"` catch-all route it can never shadow routes registered after it. Traversal-safe, mime-typed, memory-cached for warm invocations, immutable Cache-Control for content-hashed assets (`app-4f8a1b2c.js`), automatic ETag/gzip. When the file does not exist, the request **falls through**.
-2. **`serveIndexHtml(handler?, options?)`**: the next slot in the fallback chain, gated by a built-in filter: only `GET`/`HEAD` (option `methods`) and, by default, only paths that do not look like files (`skipFilePaths: true`, so a missing `/logo.png` is a 404, not a soft-404 HTML shell). Optional `redirectTrailingSlash` (default false) 301s `/about/` to `/about`. Gated-out requests fall through to `setRouteFallbackHandler`. Without a handler it serves `publicPath/index.html` (option `indexFile`) via `res.templateFile` with `no-cache`, so plain hosting is zero-config and templating is opt-in.
-3. **`res.templateFile(path, data?, options?)`**: render any HTML file under `publicPath` through `LambderTemplatingEngine` (compiled once, cached across warm invocations) and return it as an HTML response.
-
-```html
-<!-- frontend index.html (markers survive the Vite build; defaults show in vite dev) -->
-<title><!--slot:title-->My App<!--/slot:title--></title>
-<!--slot:head/-->
-```
+Lambder has no SPA-specific machinery; hosting a frontend build is a recipe built from three generic primitives: `servePublicFiles()` (terminal slot serving real files: memory-cached, immutable Cache-Control for hashed assets, ETag/gzip, falls through when missing), `serveIndexHtml()` (next fallback slot, GET/HEAD + non-file-path gated) and `res.templateFile()` (render an HTML file through the templating engine, compiled once and cached). **Full guide with the multi-tenant recipe: [docs/TEMPLATING.md](./docs/TEMPLATING.md).**
 
 ```typescript
-lambder
-    // Multi-tenant roots are just app logic in the path mapper:
-    .servePublicFiles({ path: (ctx) => `${getBrandFromHost(ctx.host)}${ctx.path}` })
-    // Only GET/HEAD page requests reach this handler:
-    .serveIndexHtml(async (ctx, res) => {
-        return res.templateFile(`${getBrandFromHost(ctx.host)}/index.html`, {
-            title: pageTitle(ctx),                        // escaped automatically
-            head: html`<link rel="canonical" href="${canonicalUrl(ctx)}" />
-                ${jsonScript("app-data", preloadedState(ctx))}`,
-            isRtl: activeLang(ctx) === "ar",
-        }, { cacheControl: "no-cache" });
-    });
-
-// Or, zero-config for a single-tenant app without templating:
+// Zero-config single-tenant hosting:
 lambder.servePublicFiles().serveIndexHtml();
-```
 
-Files without template markers can opt into virtual slots (`title` = the `<title>` element, `head` = before `</head>`) with `res.templateFile(path, data, { htmlVirtualSlots: true })`. File cache policies (`cacheControl`, `immutablePattern`, `memoryCache`) are configurable via `LambderPublicFilesOptions`, and both slots take an explicit compression policy: `servePublicFiles({ compress: (ctx) => /\.(css|js|svg)$/.test(ctx.path) })` and `serveIndexHtml(handler, { compress: true })` (default "auto").
+// Templated shell:
+lambder.servePublicFiles().serveIndexHtml(async (ctx, res) => {
+    return res.templateFile("index.html", {
+        title: pageTitle(ctx),
+        head: html`<link rel="canonical" href="${canonicalUrl(ctx)}" />`,
+    }, { cacheControl: "no-cache" });
+});
+```
 
 ### Render Context (ctx) Variables
 
@@ -430,7 +399,7 @@ Responses are finalized once at the end of the request: automatic gzip (when the
 
 ### DynamoDB Cache (LambderDdbCache)
 
-Standalone, persistent JSON cache backed by a DynamoDB table (`pk`/`sk` keys + `expiresAt` TTL attribute, same shape as the session table). Values are Brotli-compressed; small values are stored inline in a manifest item, large values are split into versioned binary chunks written before the manifest, so readers only ever see complete versions. Includes an in-memory LRU layer for warm invocations, single-flight deduplication, a DynamoDB lease so only one Lambda fills a missing key, and fail-open semantics (cache infrastructure errors fall back to the loader; loader errors propagate).
+Standalone, persistent JSON cache backed by a DynamoDB table (`pk`/`sk` keys + `expiresAt` TTL attribute, same shape as the session table). Brotli-compressed values, in-memory LRU layer, single-flight deduplication, a DynamoDB lease so only one Lambda fills a missing key, and fail-open semantics. Server-only. **Full guide with table setup: [docs/DDB_CACHE.md](./docs/DDB_CACHE.md).**
 
 ```typescript
 import { LambderDdbCache } from "lambder";
@@ -448,7 +417,30 @@ const city = await cache.getOrSet(`city:${slug}`, async () => fetchCityFromDb(sl
 // Also: cache.get(key), cache.set(key, value, { ttlSeconds }), cache.has(key), cache.delete(key)
 ```
 
-Required IAM actions on the table: `dynamodb:GetItem`, `PutItem`, `DeleteItem`, `Query`, `BatchWriteItem`. Server-only (uses AWS SDK + zlib).
+### Typed Translations (createLambderI18n)
+
+Standalone, framework-free i18n with a compile-time contract: keys and `{token}` params are inferred from the default-language dictionary, components extend the base keys with their own (strictly, or partially with fallback), and the active language resolves automatically (custom detector → browser languages → default). **Full guide: [docs/I18N.md](./docs/I18N.md).**
+
+```typescript
+import { createLambderI18n } from "lambder";
+
+export const i18n = createLambderI18n({
+    languages: { en: { name: "English" }, tr: { name: "Türkçe" }, de: { name: "Deutsch" } },
+    defaultLanguage: "en",
+    enforced: ["en"],                       // languages every dictionary must provide
+    base: {                                 // strict: all languages, all keys
+        en: { greet: "Hello {name}" },
+        tr: { greet: "Merhaba {name}" },
+        de: { greet: "Hallo {name}" },
+    },
+});
+
+// componentA.ts — only enforced languages required; de falls back to en:
+const cI18n = i18n.extendPartial({ en: { compute: "Compute" }, tr: { compute: "Hesapla" } });
+cI18n.t("compute");                 // auto-resolved language
+cI18n.t("greet", { name: "Ada" });  // base keys + params, compile-time enforced
+cI18n.forLanguage("tr")("compute"); // explicit (per-request backend use)
+```
 
 ## Frontend Usage with LambderCaller
 

package/dist/LambderDdbCache.js

@@ -1,6 +1,5 @@
 import { BatchWriteItemCommand, DeleteItemCommand, DynamoDBClient, GetItemCommand, PutItemCommand, QueryCommand, } from "@aws-sdk/client-dynamodb";
-import { createHash, randomUUID } from "crypto";
-import { brotliCompress, brotliDecompress, constants as zlibConstants, } from "zlib";
+import { getCrypto, getZlib } from "./node-polyfills.js";
 import { LRUCache } from "lru-cache";
 const DEFAULT_TTL_SECONDS = 365 * 24 * 60 * 60;
 const DEFAULT_CHUNK_BYTES = 350 * 1024;
@@ -11,29 +10,56 @@ const META_SORT_KEY = "meta";
 const LOCK_SORT_KEY = "lock";
 const BATCH_WRITE_LIMIT = 25;
 const MAX_BATCH_RETRIES = 8;
-const compress = (input, quality) => new Promise((resolve, reject) => {
-    const options = {
-        params: {
-            [zlibConstants.BROTLI_PARAM_QUALITY]: quality,
-            [zlibConstants.BROTLI_PARAM_MODE]: zlibConstants.BROTLI_MODE_TEXT,
-        },
-    };
-    brotliCompress(input, options, (error, output) => {
-        if (error)
-            reject(error);
-        else
-            resolve(output);
+// Node builtins are loaded lazily through node-polyfills so this module can
+// sit in a frontend bundle's import graph (via the package root) without
+// breaking; using the cache at runtime still requires Node.
+const requireZlib = async () => {
+    const zlib = await getZlib();
+    if (!zlib)
+        throw new Error("LambderDdbCache requires a Node.js environment.");
+    return zlib;
+};
+const requireCrypto = async () => {
+    const crypto = await getCrypto();
+    if (!crypto)
+        throw new Error("LambderDdbCache requires a Node.js environment.");
+    return crypto;
+};
+const compress = async (input, quality) => {
+    const zlib = await requireZlib();
+    return new Promise((resolve, reject) => {
+        zlib.brotliCompress(input, {
+            params: {
+                [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
+                [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
+            },
+        }, (error, output) => {
+            if (error)
+                reject(error);
+            else
+                resolve(output);
+        });
     });
-});
-const decompress = (input, maxOutputLength) => new Promise((resolve, reject) => {
-    brotliDecompress(input, { maxOutputLength }, (error, output) => {
-        if (error)
-            reject(error);
-        else
-            resolve(output);
+};
+const decompress = async (input, maxOutputLength) => {
+    const zlib = await requireZlib();
+    return new Promise((resolve, reject) => {
+        zlib.brotliDecompress(input, { maxOutputLength }, (error, output) => {
+            if (error)
+                reject(error);
+            else
+                resolve(output);
+        });
     });
-});
-const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+};
+const sha256 = async (value) => {
+    const crypto = await requireCrypto();
+    return crypto.createHash("sha256").update(value).digest("hex");
+};
+const randomUUID = async () => {
+    const crypto = await requireCrypto();
+    return crypto.randomUUID();
+};
 const positiveInteger = (value, name) => {
     if (!Number.isSafeInteger(value) || value <= 0) {
         throw new Error(`${name} must be a positive safe integer`);
@@ -105,7 +131,7 @@ export class LambderDdbCache {
         }
         if (cached)
             this.memory?.delete(normalizedKey);
-        const pk = this.partitionKey(normalizedKey);
+        const pk = await this.partitionKey(normalizedKey);
         const manifest = await this.readManifest(pk);
         if (!manifest || manifest.expiresAt <= nowSeconds)
             return undefined;
@@ -114,7 +140,7 @@ export class LambderDdbCache {
             if (compressed.length !== manifest.compressedBytes) {
                 throw new Error("compressed byte length does not match manifest");
             }
-            if (sha256(compressed) !== manifest.checksum) {
+            if (await sha256(compressed) !== manifest.checksum) {
                 throw new Error("compressed checksum does not match manifest");
             }
             const output = await decompress(compressed, this.maxValueBytes);
@@ -140,7 +166,7 @@ export class LambderDdbCache {
             return true;
         if (cached)
             this.memory?.delete(normalizedKey);
-        const manifest = await this.readManifest(this.partitionKey(normalizedKey));
+        const manifest = await this.readManifest(await this.partitionKey(normalizedKey));
         return !!manifest && manifest.expiresAt > nowSeconds;
     }
     async set(key, value, options = {}) {
@@ -157,8 +183,8 @@ export class LambderDdbCache {
         if (compressed.length > this.maxValueBytes) {
             throw new Error(`Compressed cache value exceeds maxValueBytes (${compressed.length} > ${this.maxValueBytes})`);
         }
-        const pk = this.partitionKey(normalizedKey);
-        const version = `${Date.now().toString(36)}-${randomUUID()}`;
+        const pk = await this.partitionKey(normalizedKey);
+        const version = `${Date.now().toString(36)}-${await randomUUID()}`;
         const expiresAt = this.nowSeconds() + ttlSeconds;
         const chunks = [];
         const inline = compressed.length <= this.chunkBytes;
@@ -187,7 +213,7 @@ export class LambderDdbCache {
                 chunkCount: { N: String(chunks.length) },
                 compressedBytes: { N: String(compressed.length) },
                 uncompressedBytes: { N: String(input.length) },
-                checksum: { S: sha256(compressed) },
+                checksum: { S: await sha256(compressed) },
                 encoding: { S: "br" },
                 createdAt: { N: String(this.nowSeconds()) },
                 expiresAt: { N: String(expiresAt) },
@@ -198,7 +224,7 @@ export class LambderDdbCache {
     }
     async delete(key) {
         const normalizedKey = this.normalizeKey(key);
-        const pk = this.partitionKey(normalizedKey);
+        const pk = await this.partitionKey(normalizedKey);
         this.memory?.delete(normalizedKey);
         const keys = [];
         let cursor;
@@ -264,8 +290,8 @@ export class LambderDdbCache {
     async fill(key, factory, options) {
         const leaseSeconds = positiveInteger(options.leaseSeconds ?? 15, "leaseSeconds");
         const waitForFillMs = positiveInteger(options.waitForFillMs ?? 5_000, "waitForFillMs");
-        const pk = this.partitionKey(key);
-        const owner = randomUUID();
+        const pk = await this.partitionKey(key);
+        const owner = await randomUUID();
         if (await this.acquireLease(pk, owner, leaseSeconds)) {
             try {
                 const value = await factory();
@@ -465,8 +491,8 @@ export class LambderDdbCache {
         }
         return key;
     }
-    partitionKey(key) {
-        return `${this.namespace}#${sha256(key)}`;
+    async partitionKey(key) {
+        return `${this.namespace}#${await sha256(key)}`;
     }
     chunkSortKey(version, index) {
         return `chunk#${version}#${String(index).padStart(6, "0")}`;

package/dist/LambderI18n.d.ts

@@ -0,0 +1,103 @@
+/**
+ * LambderI18n — standalone, framework-free, isomorphic typed translation module.
+ *
+ * Zero dependencies, no Node/DOM requirements (browser detection is feature-gated),
+ * safe to import in both lambda backends and frontend bundles.
+ *
+ * See docs/I18N.md for the full guide.
+ */
+export interface LambderLanguageMeta {
+    /** Native language name (shown in language switchers). */
+    name: string;
+    /** English language name, for accessibility / tooltips. */
+    englishName?: string;
+    /** BCP-47 locale for Intl APIs (e.g. "zh-CN"). Defaults to the code. */
+    intlLocale?: string;
+    /** Text direction. Defaults to "ltr". */
+    dir?: "ltr" | "rtl";
+    /** App-specific extras (e.g. flag emoji). */
+    [extra: string]: unknown;
+}
+/** Extracts `{param}` placeholder names from a string literal type. */
+export type LambderI18nExtractParams<S extends string> = S extends `${string}{${infer P}}${infer Rest}` ? P | LambderI18nExtractParams<Rest> : never;
+/**
+ * Typed translator: `t(key)` — and when the key's contract value contains
+ * `{tokens}`, a params object with exactly those tokens is required.
+ */
+export type LambderI18nTranslator<TContract extends Record<string, string>> = <K extends keyof TContract & string>(...args: LambderI18nExtractParams<TContract[K]> extends never ? [key: K] : [key: K, params: Record<LambderI18nExtractParams<TContract[K]>, string | number>]) => string;
+export interface LambderI18nConfig<TLanguages extends Record<string, LambderLanguageMeta>, TDefault extends keyof TLanguages & string, TEnforced extends readonly (keyof TLanguages & string)[], TContract extends Record<string, string>> {
+    /** Master registry of every supported language and its metadata. */
+    languages: TLanguages;
+    /** Final fallback language. Must be included in `enforced`. */
+    defaultLanguage: TDefault;
+    /**
+     * Languages every dictionary must always provide. `extendPartial` requires
+     * only these; all other languages become optional and fall back.
+     */
+    enforced: TEnforced;
+    /**
+     * App-wide base dictionary. Strict: every language in `languages` must
+     * provide every key (the `defaultLanguage` block is the typed contract).
+     */
+    base: {
+        [L in keyof TLanguages]: Record<keyof TContract, string>;
+    } & {
+        [D in TDefault]: TContract;
+    };
+    /**
+     * Optional language detector, tried before browser detection. Return a
+     * supported code to pick it, or null/undefined to continue the chain:
+     * setLanguage override → detectLanguage → browser languages → defaultLanguage.
+     */
+    detectLanguage?: (helpers: {
+        isLanguageCode: (value: string) => value is keyof TLanguages & string;
+        languages: TLanguages;
+        defaultLanguage: TDefault;
+    }) => string | null | undefined;
+}
+export interface LambderI18nInstance<TLanguages extends Record<string, LambderLanguageMeta>, TDefault extends keyof TLanguages & string, TEnforced extends readonly (keyof TLanguages & string)[], TContract extends Record<string, string>> {
+    /** Translate using the automatically resolved active language. */
+    t: LambderI18nTranslator<TContract>;
+    /** Translator bound to an explicit language (per-request backend use). */
+    forLanguage(code: keyof TLanguages & string): LambderI18nTranslator<TContract>;
+    /**
+     * Strict extension: every language must provide every new key.
+     * Returns a new instance whose key space = parent keys + new keys.
+     */
+    extend<const TExt extends {
+        [D in TDefault]: Record<string, string>;
+    }>(dict: {
+        [L in keyof TLanguages]: Record<keyof TExt[TDefault], string>;
+    } & TExt): LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract & TExt[TDefault]>;
+    /**
+     * Partial extension: only the `enforced` languages are required; all other
+     * languages are optional (and may provide a subset of keys) — missing
+     * translations fall back to the default language.
+     */
+    extendPartial<const TExt extends {
+        [D in TDefault]: Record<string, string>;
+    }>(dict: {
+        [E in TEnforced[number]]: Record<keyof TExt[TDefault], string>;
+    } & {
+        [L in Exclude<keyof TLanguages & string, TEnforced[number]>]?: Partial<Record<keyof TExt[TDefault], string>>;
+    } & TExt): LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract & TExt[TDefault]>;
+    /** Merge additional translations at runtime (e.g. fetched from an API). */
+    registerDictionary(code: keyof TLanguages & string, dict: Record<string, string>): void;
+    /** Override the active language (shared with all extended instances). */
+    setLanguage(code: keyof TLanguages & string): void;
+    /** Clear the override and re-run detection. */
+    resetLanguage(): void;
+    /** The currently active language code. */
+    readonly currentLanguage: keyof TLanguages & string;
+    /** Metadata of the currently active language. */
+    readonly currentLanguageMeta: TLanguages[keyof TLanguages];
+    /** Subscribe to language changes. Returns an unsubscribe function. */
+    onLanguageChange(listener: (code: keyof TLanguages & string) => void): () => void;
+    /** Type guard: is this string a supported language code? */
+    isLanguageCode(value: string): value is keyof TLanguages & string;
+    readonly languages: TLanguages;
+    readonly languageList: (keyof TLanguages & string)[];
+    readonly defaultLanguage: TDefault;
+    readonly enforced: TEnforced;
+}
+export declare const createLambderI18n: <const TLanguages extends Record<string, LambderLanguageMeta>, const TDefault extends keyof TLanguages & string, const TEnforced extends readonly (keyof TLanguages & string)[], const TContract extends Record<string, string>>(config: LambderI18nConfig<TLanguages, TDefault, TEnforced, TContract>) => LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract>;

package/dist/LambderI18n.js

@@ -0,0 +1,178 @@
+/**
+ * LambderI18n — standalone, framework-free, isomorphic typed translation module.
+ *
+ * Zero dependencies, no Node/DOM requirements (browser detection is feature-gated),
+ * safe to import in both lambda backends and frontend bundles.
+ *
+ * See docs/I18N.md for the full guide.
+ */
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/** Islamery-style browser detection: ordered prefs, full code then primary subtag. */
+const detectBrowserLanguage = (isCode) => {
+    if (typeof navigator === "undefined")
+        return null;
+    const prefs = navigator.languages?.length ? navigator.languages : [navigator.language];
+    for (const pref of prefs ?? []) {
+        const lower = (pref ?? "").toLowerCase();
+        if (isCode(lower))
+            return lower;
+        const primary = lower.split("-")[0] ?? "";
+        if (isCode(primary))
+            return primary;
+    }
+    return null;
+};
+/** Mutable active-language state, shared between an instance and all its extensions. */
+class LanguageState {
+    isCode;
+    defaultLanguage;
+    customDetect;
+    override = null;
+    detected = null;
+    listeners = new Set();
+    constructor(isCode, defaultLanguage, customDetect) {
+        this.isCode = isCode;
+        this.defaultLanguage = defaultLanguage;
+        this.customDetect = customDetect;
+    }
+    resolve() {
+        if (this.override)
+            return this.override;
+        if (this.detected)
+            return this.detected;
+        const custom = this.customDetect?.();
+        if (custom && this.isCode(custom)) {
+            this.detected = custom;
+            return custom;
+        }
+        const browser = detectBrowserLanguage(this.isCode);
+        this.detected = browser ?? this.defaultLanguage;
+        return this.detected;
+    }
+    set(code) {
+        if (!this.isCode(code))
+            throw new Error(`LambderI18n: unsupported language code "${code}".`);
+        if (this.override === code)
+            return;
+        this.override = code;
+        this.notify(code);
+    }
+    reset() {
+        this.override = null;
+        this.detected = null;
+        this.notify(this.resolve());
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    notify(code) {
+        for (const listener of this.listeners)
+            listener(code);
+    }
+}
+const interpolate = (text, params) => {
+    if (!params)
+        return text;
+    let out = text;
+    for (const [token, value] of Object.entries(params)) {
+        out = out.split(`{${token}}`).join(String(value));
+    }
+    return out;
+};
+const layerLookup = (layer, lang, key) => {
+    for (let node = layer; node; node = node.parent) {
+        const value = node.dicts[lang]?.[key];
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+};
+const buildInstance = (core, layer) => {
+    const translateIn = (lang, key, params) => {
+        const text = layerLookup(layer, lang, key)
+            ?? layerLookup(layer, core.defaultLanguage, key)
+            ?? key;
+        return interpolate(text, params);
+    };
+    const t = (key, params) => translateIn(core.state.resolve(), key, params);
+    const validateExtension = (dict, requiredLanguages, label) => {
+        for (const lang of Object.keys(dict)) {
+            if (!core.isCode(lang))
+                throw new Error(`LambderI18n: ${label} contains unsupported language "${lang}".`);
+        }
+        for (const lang of requiredLanguages) {
+            if (!dict[lang])
+                throw new Error(`LambderI18n: ${label} is missing required language "${lang}".`);
+        }
+    };
+    const instance = {
+        t: t,
+        forLanguage(code) {
+            if (!core.isCode(code))
+                throw new Error(`LambderI18n: unsupported language code "${code}".`);
+            return ((key, params) => translateIn(code, key, params));
+        },
+        extend(dict) {
+            validateExtension(dict, core.languageList, "extend() dictionary");
+            return buildInstance(core, { dicts: dict, parent: layer });
+        },
+        extendPartial(dict) {
+            validateExtension(dict, core.enforced, "extendPartial() dictionary");
+            return buildInstance(core, { dicts: dict, parent: layer });
+        },
+        registerDictionary(code, dict) {
+            if (!core.isCode(code))
+                throw new Error(`LambderI18n: unsupported language code "${code}".`);
+            layer.dicts[code] = { ...layer.dicts[code], ...dict };
+        },
+        setLanguage(code) { core.state.set(code); },
+        resetLanguage() { core.state.reset(); },
+        get currentLanguage() { return core.state.resolve(); },
+        get currentLanguageMeta() { return core.languages[core.state.resolve()]; },
+        onLanguageChange(listener) { return core.state.subscribe(listener); },
+        isLanguageCode: core.isCode,
+        languages: core.languages,
+        languageList: core.languageList,
+        defaultLanguage: core.defaultLanguage,
+        enforced: core.enforced,
+    };
+    return instance;
+};
+export const createLambderI18n = (config) => {
+    const languageList = Object.keys(config.languages);
+    const isCode = (value) => Object.prototype.hasOwnProperty.call(config.languages, value);
+    if (!isCode(config.defaultLanguage)) {
+        throw new Error(`LambderI18n: defaultLanguage "${config.defaultLanguage}" is not in languages.`);
+    }
+    for (const lang of config.enforced) {
+        if (!isCode(lang))
+            throw new Error(`LambderI18n: enforced language "${lang}" is not in languages.`);
+    }
+    if (!config.enforced.includes(config.defaultLanguage)) {
+        throw new Error(`LambderI18n: defaultLanguage "${config.defaultLanguage}" must be listed in enforced.`);
+    }
+    for (const lang of languageList) {
+        if (!config.base[lang]) {
+            throw new Error(`LambderI18n: base dictionary is missing language "${lang}".`);
+        }
+    }
+    const customDetect = config.detectLanguage
+        ? () => config.detectLanguage({
+            isLanguageCode: isCode,
+            languages: config.languages,
+            defaultLanguage: config.defaultLanguage,
+        })
+        : null;
+    const core = {
+        languages: config.languages,
+        languageList,
+        defaultLanguage: config.defaultLanguage,
+        enforced: config.enforced,
+        state: new LanguageState(isCode, config.defaultLanguage, customDetect),
+        isCode,
+    };
+    return buildInstance(core, { dicts: { ...config.base }, parent: null });
+};

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export type { LambderSessionCookieOptions } from "./LambderSessionController.js"
 export type { LambderSessionContext } from "./LambderSessionManager.js";
 export { LambderDdbCache } from "./LambderDdbCache.js";
 export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./LambderDdbCache.js";
+export { createLambderI18n } from "./LambderI18n.js";
+export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, } from "./LambderI18n.js";
 export { type ApiContractShape, } from "./LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent } from "./LambderContext.js";
 export { createContext, isV2HttpEvent } from "./LambderContext.js";

package/dist/index.js

@@ -16,4 +16,6 @@ export { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
 export { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
 // DynamoDB-backed compressed cache (standalone, server-only)
 export { LambderDdbCache } from "./LambderDdbCache.js";
+// Typed translations (standalone, isomorphic)
+export { createLambderI18n } from "./LambderI18n.js";
 export { createContext, isV2HttpEvent } from "./LambderContext.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "3.1.1",
+  "version": "3.2.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",