@carlos-tzin/tzin 0.1.9 → 0.1.11

package/README.md

@@ -6,6 +6,7 @@
 > A pact between client and server, declared once.
 
 [![CI](https://github.com/Charly921/tzin/actions/workflows/ci.yml/badge.svg)](https://github.com/Charly921/tzin/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@carlos-tzin/tzin)](https://www.npmjs.com/package/@carlos-tzin/tzin)
 
 **Status: experimental, pre-1.0.** The core works end-to-end and the scaling thesis is
 measured (see [Benchmarks](#benchmarks)), but this is not yet production software.
@@ -24,6 +25,7 @@ npx create-tzin my-app
 
 - **[API Reference](docs/api-reference.md)** — all exports, types, and options
 - **[Architecture Guide](docs/architecture.md)** — request pipeline, design decisions, internals
+- **[Roadmap](docs/roadmap.md)** — future features
 
 ## Why another framework?
 
@@ -41,7 +43,7 @@ tzin's answer: **declare a contract once**, get everything else for free.
 
 ```ts
 import { t } from '@carlos-tzin/tzin'
-import { contract, impl, createApp } from '@carlos-tzin/tzin'
+import { contract, impl, createApp, listen } from '@carlos-tzin/tzin'
 
 const getUser = contract({
   method: 'GET',
@@ -58,234 +60,191 @@ export const getUserRoute = impl(getUser, async ({ params }) => {
   if (!user) throw new HttpError(404, 'user not found')
   return { status: 200, body: user }
 })
+
+const app = createApp([getUserRoute])
+listen(app, 3000)
 ```
 
 From that single declaration:
 
 - **Handler input is extracted, not guessed**: `{ params }` exists because you declared
   it; add `query`, `body`, `headers` or `cookies` to the contract and they appear,
-  fully typed and validated per request (cookies are parsed from the header).
+  fully typed and validated per request.
 - **The compiler enforces your responses**: returning a shape that doesn't match the
   declared `200` body is a type error. Thrown `HttpError`s map to their status.
 - **OpenAPI 3.1 is free**: contracts are JSON Schema (TypeBox), so
   `generateOpenApi(routes)` needs no translation layer.
 
-### Server
-
-Web Standards all the way down — an app is just `fetch(req): Promise<Response>`,
-testable without a socket, deployable on Node, Bun, or edge workers:
-
-```ts
-const app = createApp([getUserRoute])
+## Features
 
-// Node
-listen(app, 3000)
-// Anywhere else
-export default { fetch: app.fetch }
-```
+### Core
 
-### Typed client
+| Feature | Import | Description |
+|---|---|---|
+| Contracts | `@carlos-tzin/tzin` | Type-safe API contracts |
+| Routes | `@carlos-tzin/tzin` | Bind contracts to handlers |
+| Middleware | `@carlos-tzin/tzin` | Onion-style middleware |
+| DI | `@carlos-tzin/tzin` | Typed dependency injection |
 
-One call, fully inferred — statuses are a discriminated union:
+### Runtime
 
-```ts
-const api = client({ getUser }, 'https://api.example.com')
-
-const res = await api.getUser({ params: { id: 'u1' } })
-if (res.status === 200) {
-  res.body.name // string
-} else {
-  res.body.error // string
-}
-```
+| Feature | Import | Description |
+|---|---|---|
+| Node server | `@carlos-tzin/tzin` | `listen(app, port)` |
+| Bun server | `@carlos-tzin/tzin` | `serveBun(app, port)` |
+| Workers | `@carlos-tzin/tzin` | `toWorker(app)` |
+| Dev server | CLI | `tzin dev` with hot reload |
 
-## Benchmarks
+### Realtime
 
-100 endpoints with distinct schemas, checked by `tsc --extendedDiagnostics`
-(generate with `node scripts/gen-fixtures.mjs <N>`):
+| Feature | Import | Description |
+|---|---|---|
+| Channels | `@carlos-tzin/tzin` | SSE + POST channels |
+| Presence | `@carlos-tzin/tzin` | Phoenix-style presence |
+| WebSocket | `@carlos-tzin/tzin/ws` | Native WS channels |
+| Browser client | `@carlos-tzin/tzin/client-browser` | Zero-dep browser client |
 
-| N routes | tzin: types | Hono: types | tzin: instantiations | Hono: instantiations | Check tzin / hono |
-|---|---|---|---|---|---|
-| 20 | 4,851 | 72,368 | 22,472 | 156,054 | 0.25s / 0.31s |
-| 100 | 15,779 | 111,952 | 93,128 | 240k | 0.53s / 0.55s |
-| 300 | 43,099 | 210,912 | 270k | 590k | 1.13s / 1.34s |
+### AI-Native
 
-tzin grows **strictly linearly** (~130 types/endpoint). Two structural findings about
-the chained-builder model this measures against:
+| Feature | Import | Description |
+|---|---|---|
+| MCP Server | `@carlos-tzin/tzin` | Streamable HTTP + stdio |
+| OpenAPI | `@carlos-tzin/tzin` | Auto-generated from contracts |
+| LLMs.txt | `@carlos-tzin/tzin` | AI-readable API index |
 
-1. Route chains must live in a **single expression** — write routes as separate
-   statements and `typeof app` silently loses every route (intermediate types only
-   flow through the chain).
-2. Registering the same path twice **silently degrades client typing**.
+### Database
 
-A flat registry of plain objects has neither failure mode by construction.
+| Feature | Import | Description |
+|---|---|---|
+| Models | `@carlos-tzin/tzin/db` | Type-safe ORM |
+| Query builder | `@carlos-tzin/tzin/db` | Chainable queries |
+| Store adapters | `@carlos-tzin/tzin/db` | Swappable backends |
 
-*Honest caveat: the Hono fixture returns constant JSON without validators; the
-documented blow-ups compound further when `zValidator` inference enters the chain.*
+### Auth
 
-### Runtime throughput
+| Feature | Import | Description |
+|---|---|---|
+| Bearer auth | `@carlos-tzin/tzin/auth` | JWT validation |
+| Optional auth | `@carlos-tzin/tzin/auth` | Non-strict JWT |
+| API key | `@carlos-tzin/tzin/auth` | Header-based auth |
+| JWT utils | `@carlos-tzin/tzin/auth` | sign/verify |
 
-100 routes · `GET /r50/item` · 64 connections · 5s (`npm run bench:http`, autocannon,
-each framework in its own process, 3 rotated rounds, median — order rotates so
-machine drift can't bias any variant; tzin runs from built `dist/`):
+### Jobs
 
-| Framework | req/s | p99 |
+| Feature | Import | Description |
 |---|---|---|
-| raw node:http (floor) | ~42k | 2–3ms |
-| hono | ~34–36k | 3ms |
-| tzin | ~30–31k | 6ms |
-| express | ~15k | 7ms |
+| Define jobs | `@carlos-tzin/tzin/jobs` | Background tasks |
+| Enqueue | `@carlos-tzin/tzin/jobs` | Job queue |
+| Retry | `@carlos-tzin/tzin/jobs` | Auto-retry on failure |
 
-The honest decomposition (`npm run bench:pipeline`, in-process `app.fetch` with
-identical request construction):
+### Logging
 
-| Metric | tzin | hono |
+| Feature | Import | Description |
 |---|---|---|
-| in-process dispatch | ~127k req/s | ~118k req/s |
+| Logger | `@carlos-tzin/tzin/log` | Structured logging |
+| Child loggers | `@carlos-tzin/tzin/log` | Scoped context |
+| Pretty/JSON | `@carlos-tzin/tzin/log` | Configurable output |
 
-Framework-side, tzin matches hono (routing is a radix trie at 9.1M lookups/s,
-full TypeBox validation costs ≈0.05µs/request). The Node adapter duck-types
-requests, memoizes route matches per `METHOD path`, keeps the abort signal lazy
-(wired only if something reads `ctx.signal`), and skips undici Response
-construction entirely on the JSON hot path via `app.dispatchRaw` — tzin lands
-at ~0.9x of hono over the network.
+### Testing
 
-## AI-native: every API is an MCP server
+| Feature | Import | Description |
+|---|---|---|
+| Test client | `@carlos-tzin/tzin/test` | API testing |
+| Schema validation | `@carlos-tzin/tzin/test` | Type assertions |
+| Mock data | `@carlos-tzin/tzin/test` | Generate mocks |
 
-tzin ships first-class [MCP](https://modelcontextprotocol.io) support — the same
-contracts that generate your OpenAPI document also expose your endpoints as tools
-for AI agents:
+## Quick Start
 
-```ts
-import { startStdioMcp } from '@carlos-tzin/tzin'
+### 1. Scaffold
 
-const app = createApp(routes)
-startStdioMcp(app) // newline-delimited JSON-RPC on stdio
+```bash
+npx create-tzin my-api
+cd my-api
 ```
 
-- `tools/list` returns each endpoint with a real JSON Schema `inputSchema` assembled
-  from its declared sections — **no conversion layer**, TypeBox already is JSON Schema.
-- `tools/call` dispatches **in-process** through the full app: validation, middleware
-  and DI all apply; HTTP errors surface as `isError` results.
-- Contract-level `name` and `description` become the tool's identity; OpenAPI reuses
-  them as `operationId`/`description`.
-
-Prefer HTTP? Enable the Streamable HTTP transport on the same app:
+### 2. Define a contract
 
 ```ts
-const app = createApp(routes, { mcp: true }) // POST /mcp speaks JSON-RPC
-```
+// src/routes/users.ts
+import { t, contract, impl } from '@carlos-tzin/tzin'
 
-And give LLMs a map of your API straight from the contracts:
+export const getUser = contract({
+  method: 'GET',
+  path: '/users/:id',
+  params: t.Object({ id: t.String() }),
+  responses: {
+    200: t.Object({ id: t.String(), name: t.String() }),
+    404: t.Object({ error: t.String() }),
+  },
+})
 
-```ts
-const app = createApp(routes, {
-  llms: true,
-  openapi: true,
-  meta: { title: 'My API' },
+export const getUserRoute = impl(getUser, async ({ params }) => {
+  return { status: 200, body: { id: params.id, name: 'Ada' } }
 })
-// GET /llms.txt       — index of endpoints (method, path, name, description)
-// GET /llms-full.txt  — same index plus every declared JSON Schema inline
-// GET /openapi.json   — OpenAPI 3.1 document (TypeBox == JSON Schema == OpenAPI)
 ```
 
-## Realtime channels with presence
-
-Phoenix-style channels, mounted as ordinary routes — SSE down, POST up, so it
-runs on every runtime including Workers:
+### 3. Create the app
 
 ```ts
-import { Hub, Presence, channelRoutes } from '@carlos-tzin/tzin'
-
-const hub = new Hub()
-const presence = new Presence(hub, 30_000)
+// src/app.ts
+import { createApp } from '@carlos-tzin/tzin'
+import { getUserRoute } from './routes/users.js'
 
-const app = createApp(channelRoutes(hub, { presence }))
-// GET  /channels/:topic?member=alice   → SSE stream; presence joins
-// POST /channels/:topic                → { event, data } broadcast
-// POST /channels/:topic/heartbeat      → keep member listed (TTL-refreshed)
-// POST /channels/:topic/leave          → presence_diff broadcast
+export const app = createApp([getUserRoute], {
+  openapi: true,
+  mcp: true,
+  meta: { title: 'My API', version: '1.0.0' },
+})
 ```
 
-Members that stop heartbeating are swept and announced via `presence_diff` —
-ghost clients disappear even after crashes. The in-memory `Hub` is one process;
-multi-node deployments wire hubs together over a message bus:
-
-```ts
-import { Hub } from '@carlos-tzin/tzin'
-import { LocalBus, type MessageBus } from 'tzin/bus'
-
-// Any PUBLISH/SUBSCRIBE transport maps onto this 2-method interface:
-const bus: MessageBus = redisPubSubAdapter // Redis, Postgres LISTEN/NOTIFY...
+### 4. Run
 
-const nodeA = new Hub({ bus })
-const nodeB = new Hub({ bus })
-// A publish on node A reaches subscribers of every node; own frames are
-// ignored, so there is no echo. Bus subscriptions are per-topic and lazy.
+```bash
+npx tzin dev    # dev server at http://localhost:3000
+npx tzin build  # production build
 ```
 
-Presence replicates Phoenix-style: every node merges remote join/leave/sweep
-frames into its local view, so `presence_state` snapshots are complete
-cluster-wide, subscribers get the full roster on connect, and ghosts left by a
-dead node are expired by any surviving node's TTL sweep.
+## CLI
 
-A zero-dependency client ships for browsers (and Node >= 22 with any
-EventSource polyfill) — auto-heartbeat, presence events and reconnection via
-the platform's EventSource:
-
-```ts
-import { joinChannel } from 'tzin/client-browser'
-
-const chat = joinChannel('https://api.example.com', 'lobby', { member: 'ada' })
-chat.on('message', (data) => render(data))
-chat.on('presence_diff', (d) => updateRoster(d))
-await chat.push('message', { text: 'hello' })
+```bash
+tzin dev [--port N]              # dev server with hot reload
+tzin build                       # build for production
+tzin deploy --target node|workers # deploy
+tzin generate route <name>       # scaffold a route
+tzin generate middleware <name>  # scaffold middleware
+tzin generate test <name>        # scaffold a test
 ```
 
-### Native WebSockets
-
-Prefer WebSockets over SSE+POST? The same Hub and Presence power a WS route —
-one protocol implementation, thin per-runtime adapters:
-
-```ts
-import { wsChannels } from 'tzin/ws'
-import { attachChannels } from 'tzin/ws-node' // Node adapter (ws package)
-// Bun: serve(app, port, { wsRoutes: [wsChannels(hub, { presence })] })
+## Benchmarks
 
-const server = await listen(createApp(routes), 3000)
-attachChannels(server, [wsChannels(hub, { presence })])
-// ws://host/channels/:topic?member=ada — frames: {type:'push'|'heartbeat'}, receive {event,data}
-```
+100 endpoints with distinct schemas, checked by `tsc --extendedDiagnostics`:
 
-On Cloudflare Workers, run the whole app inside a Durable Object so every
-connection shares one I/O context — cross-connection broadcast then behaves
-exactly like Node/Bun (workerd drops sends that come from another request's
-context, which is why plain fetch handlers can't relay between sockets):
+| N routes | tzin: types | Hono: types | tzin: instantiations | Hono: instantiations |
+|---|---|---|---|---|
+| 20 | 4,851 | 72,368 | 22,472 | 156,054 |
+| 100 | 15,779 | 111,952 | 93,128 | 240k |
+| 300 | 43,099 | 210,912 | 270k | 590k |
 
-```ts
-import { toDurableWorker, toWorker, TzinChannels } from '@carlos-tzin/tzin'
-import { Hub, Presence, channelRoutes, wsChannels, createApp } from '@carlos-tzin/tzin'
+tzin grows **strictly linearly** (~130 types/endpoint).
 
-export { TzinChannels } // workerd discovers DO classes among exports
+### Runtime throughput
 
-export default toDurableWorker(() => {
-  const hub = new Hub()
-  const presence = new Presence(hub)
-  const app = createApp([...routes, ...channelRoutes(hub, { presence })])
-  return toWorker(app, { wsRoutes: [wsChannels(hub, { presence })] })
-})
-```
+| Framework | req/s | p99 |
+|---|---|---|
+| raw node:http (floor) | ~42k | 2–3ms |
+| hono | ~34–36k | 3ms |
+| tzin | ~30–31k | 6ms |
+| express | ~15k | 7ms |
 
-```jsonc
-// wrangler config additions:
-"durable_objects": {
-  "bindings": [{ "name": "TZIN_APP", "class_name": "TzinChannels" }]
-},
-"migrations": [{ "tag": "v1", "new_sqlite_classes": ["TzinChannels"] }]
-```
+## Examples
 
-Verified against real workerd via miniflare (`npm run probe:workers`):
-HTTP ✓, WS upgrade ✓, roster ✓, broadcast across connections ✓, leave diff ✓.
+| Example | Runtime | What it shows |
+|---|---|---|
+| `examples/node-demo.ts` | Node | Minimal HTTP server with contracts |
+| `examples/bun-demo.ts` | Bun | Bun.serve with validation |
+| `examples/todo-api.ts` | Node | Full CRUD: auth middleware, DI, OpenAPI, MCP |
+| `examples/mcp-demo.ts` | Node | MCP server over stdio |
+| `examples/ws-demo.ts` | Bun | WebSocket channels with presence |
 
 ## Design principles
 
@@ -297,8 +256,6 @@ HTTP ✓, WS upgrade ✓, roster ✓, broadcast across connections ✓, leave di
 - **Errors are control flow.** Throw typed errors; the response union already knows.
 - **Light DI without ceremony.** `provide(key, value)` at app level seeds typed
   singletons into every request's context — handlers just `ctx.require(db)`.
-  Request-scoped middleware can override. No decorators, no reflection, no
-  container configuration files.
 
 ## Development
 
@@ -308,33 +265,6 @@ npm test          # vitest — runtime + end-to-end client + type assertions
 npm run typecheck # strict tsc across src/test/bench fixtures
 ```
 
-### Dev server
-
-```sh
-npx tsx src/cli.ts dev examples/node-demo.ts --port 3000
-```
-
-Hot-reloading server (tsx watch) that prints your route table straight from the
-contracts on every reload:
-
-```
-tzin dev · 2 routes
-
-  GET     /users/:id        get_user   Look up a user by id
-  POST    /users            create_user
-```
-
-### Examples
-
-| Example | Runtime | What it shows |
-|---|---|---|
-| `examples/node-demo.ts` | Node | Minimal HTTP server with contracts |
-| `examples/bun-demo.ts` | Bun | Bun.serve with validation |
-| `examples/todo-api.ts` | Node | Full CRUD: auth middleware, DI, OpenAPI, MCP |
-| `examples/mcp-demo.ts` | Node | MCP server over stdio |
-| `examples/ws-demo.ts` | Bun | WebSocket channels with presence |
-| `examples/worker-channels.ts` | Workers | Cloudflare DO-backed channels |
-
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/cache.d.ts

@@ -0,0 +1,92 @@
+import type { Middleware } from './middleware.js';
+export interface CacheConfig {
+    /** Cache duration in ms (default: 60000 = 1 minute) */
+    ttl?: number;
+    /** Key generator function (default: URL + method) */
+    keyGenerator?: (req: Request) => string;
+    /** Only cache certain methods (default: GET, HEAD) */
+    methods?: string[];
+    /** Only cache certain status codes (default: 200) */
+    statuses?: number[];
+    /** Skip caching for certain requests */
+    skip?: (req: Request) => boolean;
+    /** Custom cache store */
+    store?: CacheStore;
+    /** Include cache headers in response */
+    headers?: boolean;
+    /** Vary headers for cache key */
+    vary?: string[];
+}
+export interface CacheStore {
+    get(key: string): CacheEntry | null;
+    set(key: string, entry: CacheEntry): void;
+    delete(key: string): void;
+    clear(): void;
+}
+export interface CacheEntry {
+    response: CachedResponse;
+    timestamp: number;
+    ttl: number;
+}
+export interface CachedResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * HTTP caching middleware.
+ *
+ * Caches responses based on URL and method. Supports TTL, cache invalidation,
+ * and cache headers.
+ *
+ * @example
+ * ```ts
+ * import { cache } from '@carlos-tzin/tzin/cache'
+ *
+ * const app = createApp(routes, {
+ *   middleware: [cache({ ttl: 60000 })], // 1 minute cache
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Per-route caching
+ * const app = createApp([
+ *   impl(getUser, async (input) => {
+ *     return { status: 200 as const, body: { id: '1', name: 'Ada' } }
+ *   })
+ * ], {
+ *   middleware: [cache({ ttl: 300000 })], // 5 minutes
+ * })
+ * ```
+ */
+export declare function cache(config?: CacheConfig): Middleware;
+/**
+ * Stale-while-revalidate caching.
+ *
+ * Returns stale cache immediately while revalidating in background.
+ */
+export declare function staleWhileRevalidate(config?: CacheConfig & {
+    /** Stale duration in ms (how long to serve stale) */
+    staleTtl?: number;
+}): Middleware;
+/**
+ * Cache invalidation middleware.
+ *
+ * Invalidates cache entries based on patterns.
+ */
+export declare function invalidateCache(config: {
+    /** Pattern to match keys for invalidation */
+    pattern?: RegExp;
+    /** Specific keys to invalidate */
+    keys?: string[];
+    /** Custom invalidation function */
+    invalidator?: (req: Request) => string[];
+}): Middleware;
+/**
+ * Get cache info from response headers.
+ */
+export declare function getCacheInfo(response: Response): {
+    hit: boolean;
+    age?: number;
+} | null;

package/dist/cache.js

@@ -0,0 +1,219 @@
+// ── Memory Store ─────────────────────────────────────────────────────
+class MemoryCacheStore {
+    store = new Map();
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return null;
+        if (Date.now() > entry.timestamp + entry.ttl) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry;
+    }
+    set(key, entry) {
+        this.store.set(key, entry);
+    }
+    delete(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+// ── Default Key Generator ────────────────────────────────────────────
+function defaultKeyGenerator(req) {
+    const url = new URL(req.url);
+    return `${req.method}:${url.pathname}${url.search}`;
+}
+// ── Cache Middleware ─────────────────────────────────────────────────
+/**
+ * HTTP caching middleware.
+ *
+ * Caches responses based on URL and method. Supports TTL, cache invalidation,
+ * and cache headers.
+ *
+ * @example
+ * ```ts
+ * import { cache } from '@carlos-tzin/tzin/cache'
+ *
+ * const app = createApp(routes, {
+ *   middleware: [cache({ ttl: 60000 })], // 1 minute cache
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Per-route caching
+ * const app = createApp([
+ *   impl(getUser, async (input) => {
+ *     return { status: 200 as const, body: { id: '1', name: 'Ada' } }
+ *   })
+ * ], {
+ *   middleware: [cache({ ttl: 300000 })], // 5 minutes
+ * })
+ * ```
+ */
+export function cache(config = {}) {
+    const { ttl = 60000, keyGenerator = defaultKeyGenerator, methods = ['GET', 'HEAD'], statuses = [200], headers = true, vary = [], } = config;
+    const store = config.store ?? new MemoryCacheStore();
+    return async ({ req, next }) => {
+        // Only cache specified methods
+        if (!methods.includes(req.method)) {
+            return next();
+        }
+        // Skip if configured
+        if (config.skip?.(req)) {
+            return next();
+        }
+        const key = keyGenerator(req);
+        // Check cache
+        const cached = store.get(key);
+        if (cached) {
+            const response = new Response(cached.response.body, {
+                status: cached.response.status,
+                headers: cached.response.headers,
+            });
+            if (headers) {
+                response.headers.set('X-Cache', 'HIT');
+                response.headers.set('X-Cache-Age', Math.floor((Date.now() - cached.timestamp) / 1000).toString());
+            }
+            return response;
+        }
+        // Execute request
+        const response = await next();
+        // Only cache specified status codes
+        if (!statuses.includes(response.status)) {
+            return response;
+        }
+        // Clone response to read body
+        const clonedResponse = response.clone();
+        const body = await clonedResponse.text();
+        // Build headers object
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        // Store in cache
+        store.set(key, {
+            response: {
+                status: response.status,
+                headers: responseHeaders,
+                body: body,
+            },
+            timestamp: Date.now(),
+            ttl,
+        });
+        // Add cache headers
+        if (headers) {
+            const newResponse = new Response(body, {
+                status: response.status,
+                headers: responseHeaders,
+            });
+            newResponse.headers.set('X-Cache', 'MISS');
+            newResponse.headers.set('Cache-Control', `public, max-age=${Math.floor(ttl / 1000)}`);
+            newResponse.headers.set('ETag', `"${hashString(key + body)}"`);
+            return newResponse;
+        }
+        return response;
+    };
+}
+/**
+ * Stale-while-revalidate caching.
+ *
+ * Returns stale cache immediately while revalidating in background.
+ */
+export function staleWhileRevalidate(config = {}) {
+    const { staleTtl = 86400000, ...cacheConfig } = config;
+    const store = cacheConfig.store ?? new MemoryCacheStore();
+    return async ({ req, next }) => {
+        const key = (cacheConfig.keyGenerator ?? defaultKeyGenerator)(req);
+        const cached = store.get(key);
+        if (cached) {
+            const age = Date.now() - cached.timestamp;
+            const isStale = age > (cacheConfig.ttl ?? 60000);
+            if (isStale && age < staleTtl) {
+                // Serve stale immediately, revalidate in background
+                const response = new Response(cached.response.body, {
+                    status: cached.response.status,
+                    headers: cached.response.headers,
+                });
+                response.headers.set('X-Cache', 'STALE');
+                response.headers.set('Warning', '110 - "Response is stale"');
+                // Revalidate in background (fire and forget)
+                next().then((freshResponse) => {
+                    if (freshResponse.ok) {
+                        freshResponse.clone().text().then((freshBody) => {
+                            const headers = {};
+                            freshResponse.headers.forEach((v, k) => { headers[k] = v; });
+                            store.set(key, {
+                                response: { status: freshResponse.status, headers, body: freshBody },
+                                timestamp: Date.now(),
+                                ttl: cacheConfig.ttl ?? 60000,
+                            });
+                        });
+                    }
+                }).catch(() => { });
+                return response;
+            }
+        }
+        // Normal cache flow
+        return cache(cacheConfig)({ req, ctx: undefined, next });
+    };
+}
+/**
+ * Cache invalidation middleware.
+ *
+ * Invalidates cache entries based on patterns.
+ */
+export function invalidateCache(config) {
+    const store = config.pattern || config.keys ? new MemoryCacheStore() : null;
+    return async ({ req, next }) => {
+        // Check for cache invalidation headers
+        const invalidate = req.headers.get('X-Cache-Invalidate');
+        if (invalidate === 'true') {
+            store?.clear();
+        }
+        // Check for specific key invalidation
+        if (config.keys) {
+            for (const key of config.keys) {
+                store?.delete(key);
+            }
+        }
+        // Check for custom invalidation
+        if (config.invalidator) {
+            const keys = config.invalidator(req);
+            for (const key of keys) {
+                store?.delete(key);
+            }
+        }
+        return next();
+    };
+}
+// ── Utilities ────────────────────────────────────────────────────────
+/**
+ * Get cache info from response headers.
+ */
+export function getCacheInfo(response) {
+    const cacheHeader = response.headers.get('X-Cache');
+    if (!cacheHeader)
+        return null;
+    return {
+        hit: cacheHeader === 'HIT',
+        age: response.headers.get('X-Cache-Age')
+            ? parseInt(response.headers.get('X-Cache-Age'), 10)
+            : undefined,
+    };
+}
+/**
+ * Simple string hash function.
+ */
+function hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return Math.abs(hash).toString(36);
+}

package/dist/db.js

@@ -1,3 +1,4 @@
+import { Value } from '@sinclair/typebox/value';
 // ── Memory store (default) ──────────────────────────────────────────
 class MemoryStore {
     data = new Map();
@@ -99,11 +100,11 @@ export function defineModel(tableName, schema, config) {
         tableName,
         async findById(id) {
             const row = globalStore.findById(tableName, id, pk);
-            return row ? schema.Decode(row) : null;
+            return row ? Value.Decode(schema, row) : null;
         },
         async findFirst(where) {
             const rows = globalStore.findAll(tableName).filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
-            return rows[0] ? schema.Decode(rows[0]) : null;
+            return rows[0] ? Value.Decode(schema, rows[0]) : null;
         },
         findMany(where) {
             const filters = where
@@ -170,7 +171,7 @@ export function defineModel(tableName, schema, config) {
                 },
                 exec: async () => {
                     const rows = applyFilters([], filters);
-                    return rows.map((r) => schema.Decode(r));
+                    return rows.map((r) => Value.Decode(schema, r));
                 },
                 first: async () => {
                     const rows = await builder.exec();
@@ -184,14 +185,14 @@ export function defineModel(tableName, schema, config) {
         },
         async create(data) {
             const row = globalStore.insert(tableName, data);
-            return schema.Decode(row);
+            return Value.Decode(schema, row);
         },
         async createMany(data) {
             return Promise.all(data.map((d) => this.create(d)));
         },
         async update(id, data) {
             const row = globalStore.update(tableName, id, data, pk);
-            return row ? schema.Decode(row) : null;
+            return row ? Value.Decode(schema, row) : null;
         },
         async delete(id) {
             return globalStore.delete(tableName, id, pk);

package/dist/log.d.ts

@@ -0,0 +1,52 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    data?: Record<string, unknown>;
+    timestamp: Date;
+    context?: string;
+}
+export interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    fatal(message: string, data?: Record<string, unknown>): void;
+    /** Create a child logger with a prefix */
+    child(prefix: string): Logger;
+}
+export interface LoggerConfig {
+    /** Minimum log level (default: 'info') */
+    level?: LogLevel;
+    /** Custom transport function */
+    transport?: (entry: LogEntry) => void;
+    /** Include timestamp in output (default: true) */
+    timestamp?: boolean;
+    /** Pretty print with colors (default: true in dev) */
+    pretty?: boolean;
+}
+/**
+ * Configure the global logger.
+ *
+ * @example
+ * ```ts
+ * import { configure } from '@carlos-tzin/tzin/log'
+ *
+ * configure({ level: 'debug', pretty: true })
+ * ```
+ */
+export declare function configure(config: LoggerConfig): void;
+/**
+ * Get the global logger.
+ *
+ * @example
+ * ```ts
+ * import { getLogger } from '@carlos-tzin/tzin/log'
+ *
+ * const log = getLogger()
+ * log.info('Server started', { port: 3000 })
+ * ```
+ */
+export declare function getLogger(context?: string): Logger;
+/** Convenience export - reads config dynamically */
+export declare const log: Logger;

package/dist/log.js

@@ -0,0 +1,96 @@
+// ── Types ────────────────────────────────────────────────────────────
+// ── Log Level Order ──────────────────────────────────────────────────
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    fatal: 4,
+};
+// ── Colors ───────────────────────────────────────────────────────────
+const COLORS = {
+    debug: '\x1b[36m', // cyan
+    info: '\x1b[32m', // green
+    warn: '\x1b[33m', // yellow
+    error: '\x1b[31m', // red
+    fatal: '\x1b[35m', // magenta
+};
+const RESET = '\x1b[0m';
+// ── Default Transport ────────────────────────────────────────────────
+function defaultTransport(entry, config) {
+    const { level, message, data, timestamp, context } = entry;
+    const showTimestamp = config.timestamp !== false;
+    const pretty = config.pretty !== false;
+    if (pretty) {
+        const color = COLORS[level];
+        const prefix = context ? `[${context}]` : '';
+        const time = showTimestamp ? `${timestamp.toISOString()} ` : '';
+        const dataStr = data && Object.keys(data).length > 0 ? ` ${JSON.stringify(data)}` : '';
+        console.log(`${color}${time}${prefix} ${level.toUpperCase()}${RESET} ${message}${dataStr}`);
+    }
+    else {
+        const json = { level, message, timestamp: timestamp.toISOString() };
+        if (context)
+            json.context = context;
+        if (data && Object.keys(data).length > 0)
+            json.data = data;
+        console.log(JSON.stringify(json));
+    }
+}
+// ── Logger Factory ───────────────────────────────────────────────────
+function createLogger(context) {
+    function log(level, message, data) {
+        const config = globalConfig;
+        const minLevel = LOG_LEVELS[config.level ?? 'info'];
+        if (LOG_LEVELS[level] < minLevel)
+            return;
+        const transport = config.transport ?? ((entry) => defaultTransport(entry, config));
+        const entry = {
+            level,
+            message,
+            data,
+            timestamp: new Date(),
+            context,
+        };
+        transport(entry);
+    }
+    return {
+        debug: (msg, data) => log('debug', msg, data),
+        info: (msg, data) => log('info', msg, data),
+        warn: (msg, data) => log('warn', msg, data),
+        error: (msg, data) => log('error', msg, data),
+        fatal: (msg, data) => log('fatal', msg, data),
+        child: (prefix) => createLogger(context ? `${context}:${prefix}` : prefix),
+    };
+}
+// ── Global Logger ────────────────────────────────────────────────────
+let globalConfig = {};
+/**
+ * Configure the global logger.
+ *
+ * @example
+ * ```ts
+ * import { configure } from '@carlos-tzin/tzin/log'
+ *
+ * configure({ level: 'debug', pretty: true })
+ * ```
+ */
+export function configure(config) {
+    globalConfig = config;
+}
+/**
+ * Get the global logger.
+ *
+ * @example
+ * ```ts
+ * import { getLogger } from '@carlos-tzin/tzin/log'
+ *
+ * const log = getLogger()
+ * log.info('Server started', { port: 3000 })
+ * ```
+ */
+export function getLogger(context) {
+    return createLogger(context);
+}
+/** Convenience export - reads config dynamically */
+export const log = createLogger();

package/dist/rate-limit.d.ts

@@ -0,0 +1,79 @@
+import type { Middleware } from './middleware.js';
+export interface RateLimitConfig {
+    /** Maximum requests per window (default: 100) */
+    max?: number;
+    /** Window duration in ms (default: 60000 = 1 minute) */
+    windowMs?: number;
+    /** Key function to identify clients (default: IP) */
+    keyGenerator?: (req: Request) => string;
+    /** Custom error response */
+    onLimitReached?: (req: Request, retryAfter: number) => Response;
+    /** Skip certain requests */
+    skip?: (req: Request) => boolean;
+    /** Custom store for distributed rate limiting */
+    store?: RateLimitStore;
+    /** Headers to include in response */
+    headers?: boolean;
+}
+export interface RateLimitStore {
+    get(key: string): {
+        count: number;
+        resetTime: number;
+    } | null;
+    increment(key: string, windowMs: number): {
+        count: number;
+        resetTime: number;
+    };
+    decrement(key: string): void;
+    reset(key: string): void;
+}
+export interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    resetTime: number;
+    retryAfter: number;
+}
+/**
+ * Rate limiting middleware.
+ *
+ * Limits the number of requests from a client within a time window.
+ *
+ * @example
+ * ```ts
+ * import { rateLimit } from '@carlos-tzin/tzin/rate-limit'
+ *
+ * const app = createApp(routes, {
+ *   middleware: [rateLimit({ max: 100, windowMs: 60000 })],
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Per-route rate limiting
+ * const app = createApp([
+ *   impl(getUser, async (input) => {
+ *     // This handler has its own rate limit
+ *     return { status: 200 as const, body: { ok: true } }
+ *   })
+ * ], {
+ *   middleware: [rateLimit({ max: 10, windowMs: 60000 })],
+ * })
+ * ```
+ */
+export declare function rateLimit(config?: RateLimitConfig): Middleware;
+/**
+ * Strict rate limiting for sensitive endpoints (login, password reset).
+ * Uses sliding window for more accurate limiting.
+ */
+export declare function strictRateLimit(config?: RateLimitConfig): Middleware;
+/**
+ * Create a rate limiter with custom key generation.
+ */
+export declare function createRateLimiter(config: RateLimitConfig & {
+    /** Endpoint name for logging */
+    endpoint?: string;
+}): Middleware;
+/**
+ * Get rate limit info from response headers.
+ */
+export declare function getRateLimitInfo(response: Response): RateLimitInfo | null;

package/dist/rate-limit.js

@@ -0,0 +1,188 @@
+// ── Memory Store ─────────────────────────────────────────────────────
+class MemoryStore {
+    store = new Map();
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return null;
+        if (Date.now() > entry.resetTime) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry;
+    }
+    increment(key, windowMs) {
+        const existing = this.get(key);
+        if (existing) {
+            existing.count++;
+            return existing;
+        }
+        const entry = { count: 1, resetTime: Date.now() + windowMs };
+        this.store.set(key, entry);
+        return entry;
+    }
+    decrement(key) {
+        const entry = this.store.get(key);
+        if (entry && entry.count > 0) {
+            entry.count--;
+        }
+    }
+    reset(key) {
+        this.store.delete(key);
+    }
+}
+// ── Sliding Window Counter Store ─────────────────────────────────────
+class SlidingWindowStore {
+    store = new Map();
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return null;
+        if (Date.now() > entry.resetTime) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry;
+    }
+    increment(key, windowMs) {
+        const now = Date.now();
+        const existing = this.get(key);
+        if (existing) {
+            // Sliding window: keep the same reset time
+            existing.count++;
+            return existing;
+        }
+        const entry = { count: 1, resetTime: now + windowMs };
+        this.store.set(key, entry);
+        return entry;
+    }
+    decrement(key) {
+        const entry = this.store.get(key);
+        if (entry && entry.count > 0) {
+            entry.count--;
+        }
+    }
+    reset(key) {
+        this.store.delete(key);
+    }
+}
+// ── Default Key Generator ────────────────────────────────────────────
+function defaultKeyGenerator(req) {
+    // Try to get IP from various headers
+    const forwarded = req.headers.get('x-forwarded-for');
+    if (forwarded) {
+        return forwarded.split(',')[0].trim();
+    }
+    const realIp = req.headers.get('x-real-ip');
+    if (realIp) {
+        return realIp;
+    }
+    // Fallback to a default (in real apps, this would be the socket IP)
+    return 'unknown';
+}
+// ── Rate Limit Middleware ────────────────────────────────────────────
+/**
+ * Rate limiting middleware.
+ *
+ * Limits the number of requests from a client within a time window.
+ *
+ * @example
+ * ```ts
+ * import { rateLimit } from '@carlos-tzin/tzin/rate-limit'
+ *
+ * const app = createApp(routes, {
+ *   middleware: [rateLimit({ max: 100, windowMs: 60000 })],
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Per-route rate limiting
+ * const app = createApp([
+ *   impl(getUser, async (input) => {
+ *     // This handler has its own rate limit
+ *     return { status: 200 as const, body: { ok: true } }
+ *   })
+ * ], {
+ *   middleware: [rateLimit({ max: 10, windowMs: 60000 })],
+ * })
+ * ```
+ */
+export function rateLimit(config = {}) {
+    const { max = 100, windowMs = 60000, keyGenerator = defaultKeyGenerator, onLimitReached = defaultOnLimitReached, skip, headers = true, } = config;
+    const store = config.store ?? new MemoryStore();
+    return async ({ req, next }) => {
+        // Skip if configured
+        if (skip?.(req)) {
+            return next();
+        }
+        const key = keyGenerator(req);
+        const { count, resetTime } = store.increment(key, windowMs);
+        const remaining = Math.max(0, max - count);
+        const retryAfter = Math.ceil((resetTime - Date.now()) / 1000);
+        // Check if limit exceeded
+        if (count > max) {
+            store.decrement(key);
+            return onLimitReached(req, retryAfter);
+        }
+        const response = await next();
+        // Add rate limit headers
+        if (headers) {
+            const newResponse = new Response(response.body, response);
+            newResponse.headers.set('X-RateLimit-Limit', max.toString());
+            newResponse.headers.set('X-RateLimit-Remaining', remaining.toString());
+            newResponse.headers.set('X-RateLimit-Reset', Math.ceil(resetTime / 1000).toString());
+            return newResponse;
+        }
+        return response;
+    };
+}
+/**
+ * Strict rate limiting for sensitive endpoints (login, password reset).
+ * Uses sliding window for more accurate limiting.
+ */
+export function strictRateLimit(config = {}) {
+    const store = new SlidingWindowStore();
+    return rateLimit({
+        ...config,
+        store,
+        max: config.max ?? 5,
+        windowMs: config.windowMs ?? 900000, // 15 minutes
+    });
+}
+/**
+ * Create a rate limiter with custom key generation.
+ */
+export function createRateLimiter(config) {
+    return rateLimit(config);
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+function defaultOnLimitReached(_req, retryAfter) {
+    return new Response(JSON.stringify({
+        error: 'Too many requests',
+        retryAfter,
+    }), {
+        status: 429,
+        headers: {
+            'content-type': 'application/json',
+            'Retry-After': retryAfter.toString(),
+        },
+    });
+}
+// ── Utilities ────────────────────────────────────────────────────────
+/**
+ * Get rate limit info from response headers.
+ */
+export function getRateLimitInfo(response) {
+    const limit = response.headers.get('X-RateLimit-Limit');
+    const remaining = response.headers.get('X-RateLimit-Remaining');
+    const reset = response.headers.get('X-RateLimit-Reset');
+    if (!limit || !remaining || !reset)
+        return null;
+    return {
+        limit: parseInt(limit, 10),
+        remaining: parseInt(remaining, 10),
+        resetTime: parseInt(reset, 10) * 1000,
+        retryAfter: parseInt(response.headers.get('Retry-After') ?? '0', 10),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlos-tzin/tzin",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Contract-first TypeScript framework. Types that scale, realtime channels with presence, and an MCP server for every API.",
   "license": "MIT",
   "author": "The tzin authors",
@@ -58,6 +58,18 @@
     "./jobs": {
       "types": "./dist/jobs.d.ts",
       "default": "./dist/jobs.js"
+    },
+    "./log": {
+      "types": "./dist/log.d.ts",
+      "default": "./dist/log.js"
+    },
+    "./rate-limit": {
+      "types": "./dist/rate-limit.d.ts",
+      "default": "./dist/rate-limit.js"
+    },
+    "./cache": {
+      "types": "./dist/cache.d.ts",
+      "default": "./dist/cache.js"
     }
   },
   "files": [