lambder 4.9.1 → 5.1.2

package/README.md

@@ -0,0 +1,159 @@
+# Lambder
+
+A highly opinionated serverless web framework for TypeScript on AWS Lambda.
+Lambder handles HTTP requests, routes, type-safe APIs, sessions and the
+declarative policy layer around them (rate limits, authorization guards,
+idempotency), so an application is a set of declarations rather than a pile of
+per-handler boilerplate.
+
+```typescript
+import { initLambder, LambderLocalFileSource } from "lambder";
+import { z } from "zod";
+
+const lambder = initLambder<SessionData>().create({
+    apiPath: "/api",
+    files: new LambderLocalFileSource({ root: "./public" }),
+    session: { tableName: "app-session", tableRegion: "us-east-1", sessionSalt: process.env.SESSION_SALT! },
+});
+
+lambder.addApi("getCompany", {
+    input: z.object({ slug: z.string() }),
+    output: z.object({ id: z.string(), name: z.string() }),
+}, async ({ apiPayload }, res) => res.api(await loadCompany(apiPayload.slug)));
+
+export type ApiContractType = typeof lambder.ApiContract;
+export const handler = lambder.getHandler();
+```
+
+The frontend imports that contract type and gets autocomplete, typed payloads
+and typed results with no hand-written client:
+
+```typescript
+import { LambderCaller } from "lambder/client";
+import type { ApiContractType } from "./backend/handler";
+
+const caller = new LambderCaller<ApiContractType>({ apiPath: "/api", isCorsEnabled: false });
+const company = await caller.api("getCompany", { slug: "acme" });
+```
+
+## Features
+
+- **Type-safe APIs with Zod.** Define inputs and outputs with Zod schemas; get
+  runtime validation and compile-time inference on both sides of the wire.
+- **One inferred contract.** The API contract is derived from the backend code
+  and consumed by the frontend as a type-only import.
+- **Simple route and API declaration.** Paths, regexes, predicates and
+  structured matchers, chained fluently.
+- **Sessions.** DynamoDB-backed, with secrets hashed at rest, sliding
+  expiration, data refresh and cross-subdomain cookies.
+- **Declarative policies.** Named rate-limit policies, authorization guards and
+  idempotency, referenced by name from an API declaration and checked at
+  compile time.
+- **A real response pipeline.** Automatic Brotli/gzip, ETag and 304 handling,
+  cookies, and a guard against Lambda's response size cap.
+- **Hooks and actions.** Lifecycle hooks, plus `addAction()` for the non-HTTP
+  invocations (EventBridge, SQS, custom events) the same function receives.
+- **Frontend hosting.** Serve a build from a folder, S3, R2 or any HTTP
+  origin, with an app shell rendered through a build-pipeline-safe template
+  engine.
+- **Runs anywhere Lambda does.** API Gateway REST APIs (payload v1), HTTP APIs
+  (payload v2) and Lambda Function URLs; the payload format is detected per
+  event.
+
+## Installation
+
+```bash
+npm install lambder zod
+```
+
+`zod` and the AWS SDK clients are optional peer dependencies, so installing
+lambder never drags them into your tree. Add whatever the code you actually
+import needs:
+
+| What you import | What to install alongside |
+| --- | --- |
+| `lambder/client` (browser, shared isomorphic code) | `zod` |
+| `lambder` on AWS Lambda (`nodejs18.x` and later) | `zod`. The runtime already provides the AWS SDK v3, so mark the SDK packages as dev dependencies and keep them out of the deployment package |
+| `lambder` anywhere else (a long-running server, a container, local tests) | `zod`, `@aws-sdk/client-dynamodb`, `@aws-sdk/lib-dynamodb` |
+| `LambderS3FileSource` | `@aws-sdk/client-s3`, loaded on first read |
+| `lambder/testing` | `msw` |
+
+The SDK and its `@smithy` tree are roughly 21MB installed, which is why they are
+peers rather than dependencies: a frontend importing only `lambder/client` has
+no use for any of it, and a Lambda deployment package should not ship a second
+copy of what the runtime already loads. The runtime pins its own SDK version,
+so if you need a specific one, install it and bundle it yourself.
+
+## Package entry points
+
+The package ships three entry points; pick by where the code runs:
+
+| Entry | Runs in | Carries |
+| --- | --- | --- |
+| `lambder` | Server (Lambda) | The full framework: pipeline, sessions, DDB stores, policies, plus everything from `lambder/client` |
+| `lambder/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiError`/`refuse`, the API contract and envelope types, `html`/`xml` tagged templates, `createLambderI18n` |
+| `lambder/testing` | Dev and test tooling | `LambderMSW`, the MSW adapter that serves your typed contract from mock handlers |
+
+Frontends and shared isomorphic packages should import from `lambder/client`
+only; the entry's module graph contains no AWS SDK, Node built-ins, or server
+pipeline, so the browser boundary is structural rather than left to
+tree-shaking.
+
+Source layout mirrors this: `src/core/` (request pipeline), `src/policies/`
+(declarative rate limits, guards, idempotency), `src/session/`, `src/stores/`
+(DynamoDB primitives), `src/client/`, and `src/shared/` (isomorphic modules
+both entries re-export).
+
+## Documentation
+
+Start with [Getting started](./docs/getting-started.md), then reach for the
+guide that matches what you are building. The full index lives in
+[docs/](./docs/README.md).
+
+| Guide | Covers |
+| --- | --- |
+| [Getting started](./docs/getting-started.md) | The three-step path from a first API to a typed frontend call |
+| [Configuration](./docs/configuration.md) | Every `initLambder().create({...})` option, in one reference |
+| [Routing and actions](./docs/routing.md) | Routes, matchers, hooks, fallbacks, and non-HTTP invocations |
+| [APIs and refusals](./docs/apis.md) | `addApi`/`addSessionApi`, the inferred contract, `refuse()` and `LambderApiError` |
+| [Responses](./docs/responses.md) | The render context, resolver methods, cookies, compression, ETag and the size cap |
+| [Sessions](./docs/sessions.md) | DynamoDB sessions, cookie scope, secrets at rest, `dataRefresh`, the controller API |
+| [API policies](./docs/api-policies.md) | Declarative rate limits, guards and idempotency, and mandatory authorization declarations |
+| [Frontend client](./docs/client.md) | `LambderCaller`: typed calls, failure outcomes, timeouts, guard inputs, request compression |
+| [Frontend hosting](./docs/frontend-hosting.md) | File sources, `servePublicFiles`, `serveIndexHtml`, `res.templateFile` |
+| [Templating](./docs/templating.md) | `html`/`xml` tagged templates and `LambderTemplatingEngine` |
+| [Translations](./docs/i18n.md) | `createLambderI18n`: typed keys, extension, detection, runtime dictionaries |
+| [Testing](./docs/testing.md) | `LambderMSW`: typed MSW mocking of the API contract |
+| [DynamoDB tables](./docs/dynamodb-tables.md) | Table shapes, TTL and IAM for sessions, cache, rate limits and idempotency |
+| [Exports reference](./docs/exports.md) | Every name the three entry points export, grouped by purpose |
+
+## Standalone modules
+
+Self-contained tools that ship with the package and work with or without the
+framework:
+
+| Module | Guide | Description |
+| --- | --- | --- |
+| `html` / `xml` tags + `LambderTemplatingEngine` | [Templating](./docs/templating.md) | Type-safe tagged templates and a comment-only HTML template engine (build-pipeline-safe) |
+| `createLambderI18n` | [Translations](./docs/i18n.md) | Typed translations with enforced/optional languages, component-level extension and auto language detection (isomorphic) |
+| `LambderDdbCache` | [DynamoDB cache](./docs/ddb-cache.md) | DynamoDB-backed compressed JSON cache with lease-based single-fill and grouped keys (server-only) |
+| `LambderDdbRateLimiter` | [Rate limiter](./docs/ddb-rate-limiter.md) | DynamoDB fixed-window rate limiter, atomic per window (server-only) |
+| `LambderDdbIdempotency` | [Idempotency store](./docs/ddb-idempotency.md) | DynamoDB idempotency records with owner-checked claims and compressed replays (server-only) |
+| `LambderMSW` | [Testing](./docs/testing.md) | Typed MSW mocking of the API contract for frontend development |
+
+## Versioning and changes
+
+Released versions and what each one changed are in
+[CHANGELOG.md](./CHANGELOG.md). The current major is v5, which is v4's API
+plus this documentation set: upgrading from 4.x needs no code changes.
+Upgrading from 3.x is covered by the breaking-changes section of the 4.0.1
+entry.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to
+run the tests and what a good change looks like.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/core/LambderFiles.d.ts

@@ -9,9 +9,10 @@ export type LambderFile = {
  * servePublicFiles, serveIndexHtml, res.file and res.templateFile alike,
  * through the instance's one reader (LambderFiles). Implement `read` over
  * any backing store: LambderLocalFileSource (a folder), LambderS3FileSource
- * (S3, or R2 and other S3-compatible stores), or your own. The reader does
- * the rest for every source: traversal check, memory cache, mime fallback
- * from the extension.
+ * (S3, or R2 and other S3-compatible stores), LambderHttpFileSource (any
+ * origin serving files by path), or your own. The reader does the rest for
+ * every source: traversal check, memory cache, mime fallback from the
+ * extension.
  */
 export interface LambderFileSource {
     /**
@@ -48,6 +49,12 @@ export declare class LambderLocalFileSource implements LambderFileSource {
     });
     read(relativePath: string): Promise<LambderFile | null>;
 }
+/**
+ * A file a remote store returned: the store's Content-Type unless it is a
+ * generic octet-stream, in which case the extension decides, as for local
+ * files.
+ */
+export declare const remoteStoreFile: (body: Buffer, contentType: string | null | undefined) => LambderFile;
 /**
  * The path a source is asked for: leading slash stripped, traversal
  * rejected; null for a path that names no file (empty, or a directory).

package/dist/core/LambderFiles.js

@@ -27,6 +27,12 @@ export class LambderLocalFileSource {
         return { body: await fs.promises.readFile(absolute) };
     }
 }
+/**
+ * A file a remote store returned: the store's Content-Type unless it is a
+ * generic octet-stream, in which case the extension decides, as for local
+ * files.
+ */
+export const remoteStoreFile = (body, contentType) => contentType && !contentType.endsWith("octet-stream") ? { body, mimeType: contentType } : { body };
 /**
  * The path a source is asked for: leading slash stripped, traversal
  * rejected; null for a path that names no file (empty, or a directory).

package/dist/index.d.ts

@@ -21,6 +21,8 @@ export { LambderFiles, LambderLocalFileSource } from "./core/LambderFiles.js";
 export type { LambderFileSource, LambderFile, LambderFilesOption, LambderFileMemoryCacheOption, LambderReadFile } from "./core/LambderFiles.js";
 export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
 export type { LambderS3FileSourceOptions } from "./stores/LambderS3FileSource.js";
+export { LambderHttpFileSource } from "./stores/LambderHttpFileSource.js";
+export type { LambderHttpFileSourceOptions } from "./stores/LambderHttpFileSource.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
 export type { LambderSessionContext, LambderCreatedSession, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
 export { resolveCompressionOption, LAMBDER_ENCODINGS } from "./shared/LambderCompressionOption.js";

package/dist/index.js

@@ -18,6 +18,7 @@ export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
 export { LambderFiles, LambderLocalFileSource } from "./core/LambderFiles.js";
 export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
+export { LambderHttpFileSource } from "./stores/LambderHttpFileSource.js";
 // Compression: the option every site shares, and the one codec behind them all.
 export { resolveCompressionOption, LAMBDER_ENCODINGS } from "./shared/LambderCompressionOption.js";
 // Brotli/gzip plus the bounded, length-verified restore every compressed

package/dist/shared/LambderI18n.d.ts

@@ -4,7 +4,7 @@
  * 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.
+ * See docs/i18n.md for the full guide.
  */
 export interface LambderLanguageMeta {
     /** Native language name (shown in language switchers). */

package/dist/shared/LambderI18n.js

@@ -4,7 +4,7 @@
  * 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.
+ * See docs/i18n.md for the full guide.
  */
 // ---------------------------------------------------------------------------
 // Implementation

package/dist/stores/LambderHttpFileSource.d.ts

@@ -0,0 +1,31 @@
+import { type LambderFile, type LambderFileSource } from "../core/LambderFiles.js";
+export type LambderHttpFileSourceOptions = {
+    /**
+     * The folder URL relative paths resolve under: "https://assets.example.com/v42/".
+     * It names a folder, so a missing trailing slash is added.
+     */
+    baseUrl: string;
+    /** Sent with every read, e.g. an Authorization header for a private origin or a User-Agent a firewall allows. */
+    headers?: Record<string, string>;
+    /** How long one read may take before it fails. Default: 10000. */
+    timeoutMs?: number;
+};
+/**
+ * Files over HTTP(S) from any origin that serves them by path: a CDN, a
+ * public bucket's own domain (a Cloudflare R2 custom domain, an S3 website
+ * endpoint) or another server. Reads with the runtime's fetch, so it needs
+ * no SDK, and no credentials for a public origin; reads come out of the
+ * origin's edge cache. Each path segment is percent-encoded, so a relative
+ * path names the same object it would as an S3 key. A 404 or 410 reads as
+ * null and the request falls through; any other failed status, a network
+ * error or a timeout propagates as an error. The response's Content-Type is
+ * used unless it is a generic octet-stream, in which case the extension
+ * decides, as for local files.
+ */
+export declare class LambderHttpFileSource implements LambderFileSource {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly timeoutMs;
+    constructor({ baseUrl, headers, timeoutMs }: LambderHttpFileSourceOptions);
+    read(relativePath: string): Promise<LambderFile | null>;
+}

package/dist/stores/LambderHttpFileSource.js

@@ -0,0 +1,46 @@
+import { remoteStoreFile } from "../core/LambderFiles.js";
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * Files over HTTP(S) from any origin that serves them by path: a CDN, a
+ * public bucket's own domain (a Cloudflare R2 custom domain, an S3 website
+ * endpoint) or another server. Reads with the runtime's fetch, so it needs
+ * no SDK, and no credentials for a public origin; reads come out of the
+ * origin's edge cache. Each path segment is percent-encoded, so a relative
+ * path names the same object it would as an S3 key. A 404 or 410 reads as
+ * null and the request falls through; any other failed status, a network
+ * error or a timeout propagates as an error. The response's Content-Type is
+ * used unless it is a generic octet-stream, in which case the extension
+ * decides, as for local files.
+ */
+export class LambderHttpFileSource {
+    baseUrl;
+    headers;
+    timeoutMs;
+    constructor({ baseUrl, headers = {}, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+        let url;
+        try {
+            url = new URL(baseUrl);
+        }
+        catch {
+            throw new Error(`baseUrl must be an absolute http(s) URL: ${baseUrl}`);
+        }
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            throw new Error(`baseUrl must be an absolute http(s) URL: ${baseUrl}`);
+        if (!url.pathname.endsWith("/"))
+            url.pathname += "/";
+        this.baseUrl = url;
+        this.headers = headers;
+        this.timeoutMs = timeoutMs;
+    }
+    async read(relativePath) {
+        const url = new URL(relativePath.split("/").map(encodeURIComponent).join("/"), this.baseUrl);
+        const response = await fetch(url, { headers: this.headers, signal: AbortSignal.timeout(this.timeoutMs) });
+        if (!response.ok) {
+            await response.body?.cancel();
+            if (response.status === 404 || response.status === 410)
+                return null;
+            throw new Error(`LambderHttpFileSource: ${response.status} ${response.statusText} reading ${url}`);
+        }
+        return remoteStoreFile(Buffer.from(await response.arrayBuffer()), response.headers.get("content-type"));
+    }
+}

package/dist/stores/LambderS3FileSource.d.ts

@@ -1,5 +1,5 @@
 import type { S3Client, S3ClientConfig } from "@aws-sdk/client-s3";
-import type { LambderFile, LambderFileSource } from "../core/LambderFiles.js";
+import { type LambderFile, type LambderFileSource } from "../core/LambderFiles.js";
 export type LambderS3FileSourceOptions = {
     bucket: string;
     /** Literal key prefix the relative path is appended to, so include the trailing slash: "web/v42/". Default: none. */

package/dist/stores/LambderS3FileSource.js

@@ -1,3 +1,4 @@
+import { remoteStoreFile } from "../core/LambderFiles.js";
 /**
  * Files from an S3 bucket, or any S3-compatible store such as Cloudflare
  * R2 (pass its endpoint in clientConfig). Needs @aws-sdk/client-s3, an
@@ -46,8 +47,6 @@ export class LambderS3FileSource {
         }
         if (!output.Body)
             return null;
-        const body = Buffer.from(await output.Body.transformToByteArray());
-        const contentType = output.ContentType;
-        return contentType && !contentType.endsWith("octet-stream") ? { body, mimeType: contentType } : { body };
+        return remoteStoreFile(Buffer.from(await output.Body.transformToByteArray()), output.ContentType);
     }
 }

package/package.json

@@ -1,10 +1,40 @@
 {
   "name": "lambder",
-  "version": "4.9.1",
-  "description": "",
+  "version": "5.1.2",
+  "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
+  "keywords": [
+    "lambda",
+    "aws-lambda",
+    "serverless",
+    "framework",
+    "typescript",
+    "api",
+    "zod",
+    "type-safe",
+    "rest",
+    "api-gateway",
+    "dynamodb",
+    "session",
+    "rate-limit",
+    "idempotency",
+    "guards",
+    "msw",
+    "i18n",
+    "templating"
+  ],
+  "homepage": "https://github.com/nesovera/lambder#readme",
+  "bugs": {
+    "url": "https://github.com/nesovera/lambder/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nesovera/lambder.git"
+  },
+  "license": "MIT",
+  "author": "NesoVera",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -38,6 +68,9 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "typecheck": "tsc -p tsconfig.tests.json",
     "test": "npm run typecheck && vitest run",
@@ -45,12 +78,6 @@
     "build": "tsc",
     "lint": "eslint . --ext .ts,.tsx --fix"
   },
-  "author": "",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/nesovera/lambder.git"
-  },
   "dependencies": {
     "cookie": "^1.0.2",
     "js-cookie": "^3.0.5",