@coderbuzz/ken 0.1.4 → 0.2.0

package/README.md

@@ -25,8 +25,8 @@ built-in WebSocket support.
   the box.
 - **Schema Validation**: Validate request params, query, headers, cookies, and
   body with inline schemas.
-- **Built-in Middleware**: JWT, CORS, sessions, compression, rate limiting,
-  secure headers, and more.
+- **Built-in Middleware**: JWT, JWK/JWKS, CORS, sessions, compression, rate
+  limiting, secure headers, and more.
 - **WebSocket Support**: Real-time connections with pub/sub, ping/pong, and
   typed upgrade data.
 - **Performance-Driven**: Minimal overhead engineered for high throughput and
@@ -49,12 +49,11 @@ npm install @coderbuzz/ken
 import { AppServer } from "npm:@coderbuzz/ken";
 ```
 
-For Node.js, also install a peer for ESM compatibility:
-
-```sh
-npm install tsx
-node --import tsx/esm server.ts
-```
+> **Node.js**: The package ships as ESM. Your project must have
+> `"type": "module"` in `package.json`, or use the `.mjs` extension. Node.js 18+
+> required. If you write your app in TypeScript, use a runtime that supports it
+> natively (Bun, Deno) or a transpiler such as [tsx](https://tsx.is) / `tsc` for
+> Node.js.
 
 ---
 
@@ -73,14 +72,38 @@ console.log(`Listening on ${hostname}:${port}`);
 
 ---
 
+## App vs AppServer
+
+| Class       | Purpose                                                                       |
+| ----------- | ----------------------------------------------------------------------------- |
+| `App`       | Pure router — no server lifecycle. Used for sub-apps and modular composition. |
+| `AppServer` | `App` + `run()` / `stop()`. The entry point for a server process.             |
+
+```ts
+import { App, AppServer } from "@coderbuzz/ken";
+
+// Root server
+const app = new AppServer({ port: 3000, hostname: "0.0.0.0" });
+
+// Sub-app (pure router)
+const api = new App();
+api.get("/users", handler);
+app.use("/api/v1", api);
+
+const { hostname, port } = await app.run();
+await app.stop(); // graceful shutdown
+```
+
+---
+
 ## Routing
 
 ### Static Routes
 
 ```ts
-app.get("/", "Hello Ken!");
+app.get("/", "Hello Ken!"); // string → text/plain
 app.get("/health", "OK");
-app.get("/version", { version: "1.0.0" }); // plain objects are JSON-serialized
+app.get("/version", { version: "1.0.0" }); // object → JSON-serialized
 ```
 
 ### Dynamic Params
@@ -109,17 +132,37 @@ app.get("/files/*", (ctx) => new Response(`File: ${ctx.params["*"]}`));
 ### HTTP Methods
 
 ```ts
+app.get("/items", handler);
 app.post("/items", handler);
 app.put("/items/:id", handler);
 app.patch("/items/:id", handler);
 app.delete("/items/:id", handler);
+app.head("/items", handler);
+app.options("/items", handler);
+```
+
+### Route Introspection
+
+```ts
+// Returns RouteInfo[] — { method, path }[]
+const routes = app.getRoutes();
+
+// Print a colored table to console
+app.printRoutes();
+// ┌──────────┬────────────────────┐
+// │  Method  │ Path               │
+// ├──────────┼────────────────────┤
+// │  GET     │ /                  │
+// │  POST    │ /users             │
+// │  WS      │ /chat              │
+// └──────────┴────────────────────┘
 ```
 
 ---
 
 ## Schema Validation
 
-Ken validates request data inline via the schema object (first argument before
+Ken validates request data inline via the schema object (second argument before
 the handler). Use
 [`@coderbuzz/kyo`](https://www.npmjs.com/package/@coderbuzz/kyo) for schema
 builders.
@@ -128,6 +171,7 @@ builders.
 import {
   boolean,
   coerce,
+  date,
   number,
   object,
   optional,
@@ -218,6 +262,21 @@ app.post("/api/submit", {
 });
 ```
 
+### Date Validation
+
+```ts
+app.post("/api/register", {
+  json: object({
+    born: coerce(
+      date({ min: new Date("1900-01-01"), max: new Date("2025-12-31") }),
+    ),
+  }),
+}, async (ctx) => {
+  const { born } = await ctx.json;
+  return Response.json({ born: born.toISOString() });
+});
+```
+
 ---
 
 ## Middleware & State
@@ -268,11 +327,15 @@ app.post("/admin/action", {
       if ((ctx.state as any).auth.role !== "admin") {
         throw new Response("Forbidden", { status: 403 });
       }
+      // void return — not included in ctx.state type
     },
   },
 }, () => Response.json({ message: "Action performed" }));
 ```
 
+> **Note:** Middleware with `void` return types are excluded from `ctx.state`.
+> Only middleware that returns a value contributes to the state type.
+
 ### `onFinish` Callback
 
 ```ts
@@ -294,7 +357,8 @@ app.get("/with-logging", {
 
 ### `define()` — Scoped Middleware
 
-Apply middleware to a group of routes with full type inference:
+Apply middleware to a group of routes with full type inference. Routes inside
+the callback automatically inherit the state type:
 
 ```ts
 app.define(
@@ -316,16 +380,33 @@ app.define(
 );
 ```
 
+`define()` can be nested for layered composition:
+
+```ts
+app.define({ requestId: () => crypto.randomUUID() }, (app) => {
+  app.define({ timestamp: () => Date.now() }, (app) => {
+    app.get("/meta", (ctx) =>
+      Response.json({
+        id: ctx.state.requestId,
+        ts: ctx.state.timestamp,
+      }));
+  });
+});
+```
+
 ### `apply()` — Global Middleware
 
 ```ts
-// Side-effect middleware (logging, metrics)
+// Side-effect middleware (logging, metrics) — no state produced
 app.apply("/*", (ctx) => {
   console.log(ctx.method, ctx.url);
 });
 
-// State-producing middleware
+// State-producing middleware — added to ctx.state for all matching routes
 app.apply("/*", { auth: (ctx) => verifyAuth(ctx) });
+
+// Scoped to a prefix
+app.apply("/api/*", { apiVersion: () => "v1" });
 ```
 
 ### `use()` — Mount Sub-Apps
@@ -335,7 +416,10 @@ const api = new App();
 api.get("/users", handler);
 api.get("/posts", handler);
 
-app.use("/api/v1", api);
+app.use("/api/v1", api); // mounts at /api/v1/users and /api/v1/posts
+
+// Without prefix — routes merged at root
+app.use(api);
 ```
 
 ---
@@ -363,14 +447,24 @@ app.get("/login", (ctx) => {
   });
   return new Response("Logged in");
 });
+
+// Multiple cookies
+app.get("/setup", (ctx) => {
+  ctx.setCookie("theme", "dark");
+  ctx.setCookie("lang", "en", { path: "/", maxAge: 86400 });
+  return new Response("OK");
+});
 ```
 
+All cookie options: `path`, `domain`, `maxAge`, `expires`, `httpOnly`, `secure`,
+`sameSite` (`'Strict' | 'Lax' | 'None'`).
+
 ---
 
 ## Error Handling
 
 ```ts
-// Custom app-level error handler
+// App-level error handler — fallback for all routes
 app.onError((error, ctx) => {
   console.error(ctx.method, ctx.url, error);
   return Response.json(
@@ -386,37 +480,134 @@ app.notFound((ctx) => {
   return Response.json({ error: "Not Found", path: ctx.url }, { status: 404 });
 });
 
+// Route-level onError — takes priority over app-level
+app.get("/validate", {
+  onError: (error, ctx) => {
+    return Response.json({ custom: true, message: String(error) }, {
+      status: 422,
+    });
+  },
+}, () => {
+  throw new Error("validation failed");
+});
+
 // Throw a Response to short-circuit with a specific status
-app.get("/secret", (ctx) => {
+app.get("/secret", () => {
   throw new Response("Forbidden", { status: 403 });
 });
 ```
 
+### Error Propagation Rules
+
+1. **Route-level `onError`** takes priority over app-level.
+2. **Thrown `Response`** instances short-circuit the chain and are returned
+   as-is (the `onError` handler receives the `Response` as the error value).
+3. Sub-app `onError` is inherited by routes mounted via `app.use()`.
+4. Middleware errors are caught by the route's `onError` (or app-level fallback)
+   — they behave the same as handler errors.
+
+### Sub-App Error Scoping
+
+```ts
+const subApp = new App();
+subApp.onError((error) => Response.json({ appError: true }, { status: 400 }));
+subApp.get("/fail", () => {
+  throw new Error("fail");
+});
+// Route-level overrides sub-app error handler
+subApp.get("/custom", {
+  onError: () => Response.json({ routeError: true }, { status: 418 }),
+}, () => {
+  throw new Error("custom");
+});
+app.use("/sub", subApp);
+```
+
+### Custom Not Found Handlers
+
+```ts
+// Sub-app scoped 404 (only matches /nf-api/* paths)
+const apiApp = new App();
+apiApp.get("/items", () => Response.json([{ id: 1 }]));
+apiApp.notFound((ctx) =>
+  Response.json({ error: "API not found", path: ctx.url }, { status: 404 })
+);
+app.use("/nf-api", apiApp);
+
+// define()-scoped notFound (inherits middleware state)
+app.define({ reqUser: () => "user123" }, (app) => {
+  app.get("/dashboard", (ctx) => Response.json({ user: ctx.state.reqUser }));
+  app.notFound((ctx) =>
+    Response.json({ error: "Not Found", user: ctx.state.reqUser }, {
+      status: 404,
+    })
+  );
+});
+
+// Global fallback
+app.notFound((ctx) =>
+  Response.json({ error: "Global not found", method: ctx.method }, {
+    status: 404,
+  })
+);
+```
+
 ---
 
 ## Built-in Middleware
 
+All middleware are used via the `state` key in the schema object (per-route) or
+via `define()` / `apply()` (scoped). They return typed values into `ctx.state`.
+
 ### CORS
 
+`cors()` returns an `App` instance. Mount it with `app.use()`:
+
 ```ts
 import { cors } from "@coderbuzz/ken";
 
-const api = cors({ origin: "https://example.com", credentials: true });
-api.get("/", () => Response.json({ data: true }));
-app.use("/api", api);
+// CORS for specific routes — define routes inside the cors app
+const apiCors = cors({ origin: "https://example.com", credentials: true });
+apiCors.get("/data", () => Response.json({ data: 1 }));
+app.use("/api", apiCors);
+
+// CORS with wildcard (all origins)
+const publicCors = cors({ origin: "*" });
+publicCors.get("/", () => Response.json({ public: true }));
+app.use("/public", publicCors);
+
+// CORS with dynamic origin resolver
+const dynamicCors = cors({
+  origin: (requestOrigin, ctx) => {
+    const allowed = ["https://app.example.com", "https://admin.example.com"];
+    return allowed.includes(requestOrigin) ? requestOrigin : allowed[0];
+  },
+  allowMethods: ["GET", "POST"],
+  allowHeaders: ["Content-Type", "Authorization"],
+  exposeHeaders: ["X-Request-Id"],
+  maxAge: 86400,
+  credentials: true,
+});
 ```
 
 ### JWT
 
 ```ts
-import { jwt, signJwt } from "@coderbuzz/ken";
+import { decodeJwt, jwt, signJwt, verifyJwt } from "@coderbuzz/ken";
 
 // Sign a token
 app.get("/token", async () => {
-  const token = await signJwt({
-    sub: "user123",
-    exp: Math.floor(Date.now() / 1000) + 3600,
-  }, "secret");
+  const token = await signJwt(
+    {
+      sub: "user123",
+      iss: "my-app",
+      aud: "my-api",
+      exp: Math.floor(Date.now() / 1000) + 3600,
+      iat: Math.floor(Date.now() / 1000),
+    },
+    "secret",
+    "HS256", // default — also supports HS384, HS512
+  );
   return Response.json({ token });
 });
 
@@ -424,6 +615,46 @@ app.get("/token", async () => {
 app.get("/secure", {
   state: { auth: jwt({ secret: "secret" }) },
 }, (ctx) => Response.json({ payload: ctx.state.auth }));
+
+// With claims validation
+app.get("/strict", {
+  state: {
+    auth: jwt({
+      secret: "secret",
+      issuer: "my-app",
+      audience: "my-api",
+      clockTolerance: 5, // seconds
+    }),
+  },
+}, (ctx) => Response.json({ sub: ctx.state.auth.sub }));
+```
+
+### JWK / JWKS (RSA, ECDSA)
+
+```ts
+import { jwk } from "@coderbuzz/ken";
+
+// Verify tokens against a JWKS endpoint (e.g., Auth0, Cognito)
+app.get("/secure", {
+  state: {
+    auth: jwk({
+      jwksUrl: "https://your-auth-provider/.well-known/jwks.json",
+      issuer: "https://your-auth-provider/",
+      audience: "your-api-identifier",
+      cacheTtl: 600_000, // 10 minutes
+    }),
+  },
+}, (ctx) => Response.json({ payload: ctx.state.auth }));
+
+// With pre-loaded keys (no HTTP fetch)
+app.get("/secure2", {
+  state: {
+    auth: jwk({
+      keys: [myRsaJwk],
+      issuer: "https://issuer.example.com",
+    }),
+  },
+}, (ctx) => Response.json({ payload: ctx.state.auth }));
 ```
 
 ### Session
@@ -431,6 +662,7 @@ app.get("/secure", {
 ```ts
 import { session } from "@coderbuzz/ken";
 
+// Sync — in-memory lookup
 const userSession = session({
   cookieName: "_sid",
   validate: (cookieValue) => {
@@ -438,6 +670,23 @@ const userSession = session({
     if (!user?.active) throw new Response("Unauthorized", { status: 401 });
     return user;
   },
+  // Optional: custom unauthorized response
+  onUnauthorized: (ctx) => new Response("Please log in", { status: 401 }),
+});
+
+// Async — database lookup or encrypted cookie
+const encryptedSession = session({
+  cookieName: "_ak",
+  validate: async (cookieValue, ctx) => {
+    const apiKey = await decryptString(cookieValue, secretKey);
+    if (!MEDIA_OWNERS[apiKey]?.active) {
+      throw new Response(null, {
+        status: 302,
+        headers: { Location: "/auth?redirect=" + ctx.url },
+      });
+    }
+    return apiKey;
+  },
 });
 
 app.get("/dashboard", {
@@ -450,9 +699,23 @@ app.get("/dashboard", {
 ```ts
 import { basicAuth } from "@coderbuzz/ken";
 
+// Static credentials
 app.get("/admin", {
   state: { auth: basicAuth({ username: "admin", password: "secret" }) },
 }, (ctx) => Response.json({ user: ctx.state.auth.username }));
+
+// Custom verification function
+app.get("/custom-admin", {
+  state: {
+    auth: basicAuth({
+      verifyUser: async (username, password, ctx) => {
+        return username === "admin" &&
+          password === await getHashedPassword(username);
+      },
+      realm: "Admin Area",
+    }),
+  },
+}, (ctx) => Response.json({ user: ctx.state.auth.username }));
 ```
 
 ### Bearer Auth
@@ -460,17 +723,48 @@ app.get("/admin", {
 ```ts
 import { bearerAuth } from "@coderbuzz/ken";
 
+// Single token
 app.get("/api/resource", {
   state: { auth: bearerAuth({ token: "my-token" }) },
 }, (ctx) => Response.json({ token: ctx.state.auth.token }));
+
+// Multiple valid tokens
+app.get("/api/multi", {
+  state: { auth: bearerAuth({ token: ["token-a", "token-b"] }) },
+}, (ctx) => Response.json({ token: ctx.state.auth.token }));
+
+// Custom verification
+app.get("/api/dynamic", {
+  state: {
+    auth: bearerAuth({
+      verifyToken: async (token, ctx) => {
+        return await verifyInDatabase(token);
+      },
+    }),
+  },
+}, (ctx) => Response.json({ token: ctx.state.auth.token }));
 ```
 
 ### Logger
 
+`logger()` returns an `App` instance. Mount it with `app.use()`:
+
 ```ts
 import { logger } from "@coderbuzz/ken";
 
+// Global logger (all routes)
 app.use(logger());
+
+// Custom log function
+app.use(logger({ logFn: (msg) => myLogService.info(msg) }));
+
+// Custom format
+app.use(logger({
+  format: ({ method, url, status, duration }) =>
+    `[${
+      new Date().toISOString()
+    }] ${method} ${url} → ${status} (${duration}ms)`,
+}));
 ```
 
 ### Request ID
@@ -481,6 +775,18 @@ import { requestId } from "@coderbuzz/ken";
 app.get("/request", {
   state: { reqId: requestId() },
 }, (ctx) => Response.json({ id: ctx.state.reqId }));
+// Response header: X-Request-Id: <uuid>
+
+// Custom options
+app.get("/request", {
+  state: {
+    reqId: requestId({
+      requestHeaderName: "X-Correlation-Id", // reuse incoming ID if present
+      headerName: "X-Request-Id",
+      generator: () => `req-${Date.now()}`,
+    }),
+  },
+}, (ctx) => Response.json({ id: ctx.state.reqId }));
 ```
 
 ### Secure Headers
@@ -488,11 +794,29 @@ app.get("/request", {
 ```ts
 import { secureHeaders } from "@coderbuzz/ken";
 
+// Use sensible defaults (Helmet-inspired)
+app.define({ sec: secureHeaders() }, (app) => {
+  app.get("/", () => new Response("secure"));
+});
+
+// Customize individual headers
 app.get("/page", {
-  state: { sec: secureHeaders() },
+  state: {
+    sec: secureHeaders({
+      xFrameOptions: "DENY",
+      contentSecurityPolicy: "default-src 'self'",
+      crossOriginOpenerPolicy: false, // disable a header
+    }),
+  },
 }, () => new Response("secure"));
 ```
 
+Default headers set: `Cross-Origin-Opener-Policy`,
+`Cross-Origin-Resource-Policy`, `Origin-Agent-Cluster`, `Referrer-Policy`,
+`Strict-Transport-Security`, `X-Content-Type-Options`, `X-DNS-Prefetch-Control`,
+`X-Download-Options`, `X-Frame-Options`, `X-Permitted-Cross-Domain-Policies`,
+`X-XSS-Protection`. Also removes `X-Powered-By`.
+
 ### Compression
 
 ```ts
@@ -500,20 +824,44 @@ import { compress } from "@coderbuzz/ken";
 
 app.get("/data", {
   state: { encoding: compress() },
-}, (ctx) => Response.json({ encoding: ctx.state.encoding.encoding }));
+}, (ctx) => {
+  // ctx.state.encoding.encoding is 'gzip' | 'deflate' | 'br' | null
+  return Response.json({ data: largePayload });
+});
 ```
 
+Note: Ken negotiates the encoding preference; actual body compression is handled
+by the runtime (Bun, Deno) or a reverse proxy.
+
 ### Cache
 
 ```ts
 import { cache } from "@coderbuzz/ken";
 
+// Cache for 1 hour (CDN-friendly)
 app.get("/static", {
   state: { caching: cache({ maxAge: 3600, public: true }) },
 }, () => new Response("cached content"));
+
+// No caching
+app.get("/dynamic", {
+  state: { caching: cache({ noStore: true }) },
+}, () => Response.json({ time: Date.now() }));
+
+// Advanced CDN directives
+app.get("/cdn", {
+  state: {
+    caching: cache({
+      maxAge: 60,
+      sMaxAge: 3600,
+      staleWhileRevalidate: 300,
+      vary: "Accept-Language",
+    }),
+  },
+}, () => new Response("cdn content"));
 ```
 
-### Rate Limiting / Body Limit
+### Body Limit
 
 ```ts
 import { bodyLimit } from "@coderbuzz/ken";
@@ -533,7 +881,13 @@ import { timeout } from "@coderbuzz/ken";
 
 app.get("/slow", {
   state: { timeoutSig: timeout({ duration: 5000 }) },
-}, () => new Response("fast enough"));
+}, async (ctx) => {
+  // Pass the AbortSignal to downstream fetch calls
+  const data = await fetch("https://api.example.com/data", {
+    signal: ctx.state.timeoutSig.signal,
+  });
+  return Response.json(await data.json());
+});
 ```
 
 ### Timing
@@ -544,6 +898,15 @@ import { timing } from "@coderbuzz/ken";
 app.get("/timed", {
   state: { perf: timing() },
 }, () => new Response("timed"));
+// Response header: Server-Timing: total;dur=2.50
+
+// Custom metric name and description
+app.get("/timed-custom", {
+  state: {
+    perf: timing({ name: "app", description: "Application processing" }),
+  },
+}, () => new Response("timed"));
+// Response header: Server-Timing: app;desc="Application processing";dur=2.50
 ```
 
 ### IP Restriction
@@ -551,9 +914,15 @@ app.get("/timed", {
 ```ts
 import { ipRestriction } from "@coderbuzz/ken";
 
+// Allow list
 app.get("/internal", {
   state: { ipCheck: ipRestriction({ allowList: ["127.0.0.1", "::1"] }) },
 }, () => new Response("allowed"));
+
+// Deny list
+app.get("/public", {
+  state: { ipCheck: ipRestriction({ denyList: ["10.0.0.1"] }) },
+}, () => new Response("public content"));
 ```
 
 ### CSRF Protection
@@ -561,11 +930,22 @@ app.get("/internal", {
 ```ts
 import { csrf } from "@coderbuzz/ken";
 
+// Same-origin only (auto-detect)
+app.post("/form", {
+  state: { protection: csrf() },
+}, () => Response.json({ success: true }));
+
+// Specific origins
 app.post("/form", {
   state: { protection: csrf({ origin: ["https://example.com"] }) },
 }, () => Response.json({ success: true }));
 ```
 
+Note: CSRF only applies to unsafe methods (POST, PUT, PATCH, DELETE) with
+form-compatible content types. JSON API requests
+(`Content-Type:
+application/json`) are automatically skipped.
+
 ### ETag
 
 ```ts
@@ -619,6 +999,15 @@ app.ws("/chat", {
   close(peer, code, reason) {
     console.log("disconnected", code, reason);
   },
+  error(peer, error) {
+    console.error("ws error", error);
+  },
+  ping(peer, data) {
+    console.log("ping received");
+  },
+  pong(peer, data) {
+    console.log("pong received — peer alive");
+  },
 });
 ```
 
@@ -630,7 +1019,7 @@ app.ws<{ userId: string }>("/auth", {
     const url = new URL(req.url);
     const userId = url.searchParams.get("userId");
     if (!userId) return new Response("Unauthorized", { status: 401 });
-    return { userId };
+    return { userId }; // becomes peer.data
   },
   open(peer) {
     peer.send(`Hello ${peer.data.userId}`);
@@ -650,10 +1039,11 @@ app.ws("/chat", {
     peer.publish("chat", "someone joined");
   },
   message(peer, message) {
-    peer.publish("chat", message);
-    peer.send(`you: ${message}`);
+    peer.publish("chat", message); // broadcast to all except sender
+    peer.send(`you: ${message}`); // echo to sender
   },
   close(peer) {
+    peer.unsubscribe("chat");
     peer.publish("chat", "someone left");
   },
 });
@@ -661,6 +1051,9 @@ app.ws("/chat", {
 
 ### WsTopicHub (App-Level Pub/Sub)
 
+Use `WsTopicHub` for pub/sub across all runtimes, including cross-topic
+broadcasts from HTTP routes or background tasks:
+
 ```ts
 import { WsTopicHub } from "@coderbuzz/ken";
 
@@ -674,7 +1067,7 @@ app.ws("/notifications", {
     hub.unsubscribeAll(peer);
   },
   message(peer, _msg) {
-    hub.markAlive(peer);
+    hub.markAlive(peer); // heartbeat acknowledgment
   },
 });
 
@@ -689,14 +1082,114 @@ app.post("/broadcast", async (ctx) => {
 ### Ping/Pong (Heartbeat)
 
 ```ts
-app.ws("/live", {
-  pong(peer) {
-    console.log(`${peer.remoteAddress} is alive`);
-  },
-  message(peer, msg) {
-    peer.send(msg);
+app.ws(
+  "/live",
+  {
+    pong(peer) {
+      console.log(`${peer.remoteAddress} is alive`);
+    },
+    message(peer, msg) {
+      peer.send(msg);
+    },
   },
-}, { pingInterval: 30, pongTimeout: 10 });
+  { pingInterval: 30, pongTimeout: 10 }, // WsOptions
+);
+```
+
+### WsOptions
+
+| Option              | Type      | Default      | Description                                |
+| ------------------- | --------- | ------------ | ------------------------------------------ |
+| `maxPayloadLength`  | `number`  | `16_777_216` | Max message size in bytes (16 MB)          |
+| `backpressureLimit` | `number`  | `16_777_216` | Max send buffer size (16 MB)               |
+| `pingInterval`      | `number`  | `30`         | Seconds between server ping frames         |
+| `pongTimeout`       | `number`  | `10`         | Seconds to wait for pong before closing    |
+| `perMessageDeflate` | `boolean` | `false`      | Enable per-message compression             |
+| `idleTimeout`       | `number`  | `120`        | Seconds before idle connections are closed |
+
+---
+
+## WebSocket Client (WSClient)
+
+Ken includes a built-in fault-tolerant WebSocket client with the Ken Binary
+WebSocket Protocol (KBWP) — 80–93% bandwidth reduction over JSON for protocol
+messages.
+
+```ts
+import { WSClient } from "@coderbuzz/ken";
+
+const client = new WSClient("wss://api.example.com/ws", {
+  token: "my-jwt", // auth token
+  authMode: "message", // 'message' (binary, default) or 'query' (?token=)
+  heartbeatInterval: 30_000, // ms between pings
+  requestTimeout: 10_000, // sendWait() timeout
+  maxRetries: Infinity, // reconnect attempts
+  onConnect: () => console.log("Connected"),
+  onDisconnect: (code, reason) => console.log("Disconnected", code),
+  onReconnectAttempt: (attempt, delay) =>
+    console.log(`Retry #${attempt} in ${delay}ms`),
+});
+
+await client.connect();
+
+// Fire-and-forget
+client.send("hello");
+
+// Request-response (binary REQUEST frame + correlation ID)
+const result = await client.sendWait({ type: "getData", id: 42 });
+
+// Pub/sub
+client.subscribe("events", (data) => console.log("Event:", data));
+client.publish("events", { action: "click" });
+client.unsubscribe("events");
+
+await client.close();
+```
+
+### wsClientProtocol — Server-Side Counterpart
+
+```ts
+import { wsClientProtocol } from "@coderbuzz/ken";
+
+// Without auth
+app.use(
+  "/chat",
+  wsClientProtocol({
+    pingInterval: 20,
+    idleTimeout: 60,
+    upgrade(req) {
+      const name = new URL(req.url).searchParams.get("name") ?? "anon";
+      return { username: name };
+    },
+    open(peer) {
+      peer.subscribe("chat");
+    },
+    message(peer, msg) {
+      peer.send(`echo: ${msg}`);
+    },
+    close(peer) {
+      peer.unsubscribe("chat");
+    },
+  }),
+);
+
+// With post-connect binary auth (secure)
+app.use(
+  "/ws",
+  wsClientProtocol<{ userId: string }>({
+    authenticate: async (token) => {
+      const user = await verifyJwt(token, "secret");
+      return user ? { userId: String(user.sub) } : null;
+    },
+    tokenParam: "token", // also accept ?token= query param
+    open(peer) {
+      console.log("authed:", peer.data.userId);
+    },
+    message(peer, msg) {
+      peer.send(msg);
+    },
+  }),
+);
 ```
 
 ---
@@ -722,54 +1215,154 @@ app.get("/stream", () => {
 
 ```ts
 import {
+  getMimeType,
   listDirectory,
   receiveFiles,
   saveFile,
   sendFile,
 } from "@coderbuzz/ken";
+```
+
+### Serve a File
 
-// Serve a file
+```ts
+// Basic
 app.get("/download", (ctx) => sendFile(ctx, "./assets/file.pdf"));
 
-// List directory
+// With full options (enables ETag, Range, conditional requests)
+app.get(
+  "/download/:name",
+  (ctx) =>
+    sendFile(ctx, `./uploads/${ctx.params.name}`, {
+      download: true, // trigger browser download
+      // download: "custom-name.pdf",       // download with custom filename
+      cacheControl: "public, max-age=3600",
+      reqHeaders: ctx.headers, // enables ETag/Range/If-Modified-Since
+    }),
+);
+```
+
+`sendFile` supports ETag / If-None-Match (→ 304), Last-Modified /
+If-Modified-Since (→ 304), and Range requests (→ 206 Partial Content). On Bun,
+uses `Bun.file()` for zero-copy sendfile.
+
+### List Directory
+
+```ts
 app.get("/files", (ctx) => listDirectory(ctx, "./uploads"));
 
-// Receive uploaded files
+// With options
+app.get("/files", async (ctx) => {
+  return listDirectory(ctx, "./uploads", {
+    recursive: true,
+    maxDepth: 3,
+    stats: true, // include size and modifiedAt (default: true)
+    filter: (entry) => !entry.name.startsWith("."),
+  });
+});
+```
+
+Each entry: `{ name, path, isDirectory, size, modifiedAt }`.
+
+### Receive Uploaded Files
+
+```ts
 app.post("/upload", async (ctx) => {
-  const files = await receiveFiles(ctx);
+  const files = await receiveFiles(ctx, {
+    maxFileSize: 5_000_000,
+    maxFiles: 10,
+    allowedTypes: ["image/png", "image/jpeg"],
+    fields: ["avatar", "banner"],
+  });
   for (const file of files) {
+    // file: { fieldName, fileName, type, size, data: ArrayBuffer }
     await saveFile(file, "./uploads");
   }
   return Response.json({ count: files.length });
 });
 ```
 
+### MIME Type Detection
+
+```ts
+getMimeType("photo.jpg"); // 'image/jpeg'
+getMimeType(".css"); // 'text/css; charset=utf-8'
+getMimeType("data.bin"); // 'application/octet-stream'
+```
+
 ---
 
 ## Utilities
 
+### Encryption (AES-GCM)
+
 ```ts
 import {
-  compressString,
-  decompressString,
   decryptString,
   encryptString,
   generateSecretKey,
-  getPathname,
-  memoize,
 } from "@coderbuzz/ken";
 
-// Encryption
-const key = await generateSecretKey();
-const encrypted = await encryptString("hello", key);
-const decrypted = await decryptString(encrypted, key);
+// Generate a random 256-bit key (sync)
+const key = generateSecretKey(); // base64-encoded string
+
+// Encrypt / decrypt
+const encrypted = await encryptString("hello world", key);
+const original = await decryptString(encrypted, key);
+```
+
+Uses AES-256-GCM via Web Crypto API with LRU key caching. Output is
+base64-encoded `IV (12 bytes) + ciphertext`.
 
-// Compression
-const compressed = await compressString("large text...");
+### Compression
+
+```ts
+import { compressString, decompressString } from "@coderbuzz/ken";
+
+// Default: gzip (standard Web API, compatible with all runtimes)
+const compressed = await compressString("large text payload...");
 const original = await decompressString(compressed);
 
-// Memoization
-const cached = memoize(expensiveFn, { ttl: 60_000 });
+// Custom encoding and quality level
+const gz = await compressString("text", { encoding: "gzip", level: 9 });
+const plain = await decompressString(gz, { encoding: "gzip" });
+```
+
+Supported encodings: `'gzip'` (default), `'deflate'`, `'deflate-raw'`.
+gzip/deflate levels: 0–9.
+
+### Memoization
+
+```ts
+import { memoize } from "@coderbuzz/ken";
+
+// Sync — auto-detected
+const expensive = memoize((id: string) => computeResult(id));
+expensive("abc"); // computes
+expensive("abc"); // cached
+
+// Async — auto-detected, with thundering herd protection
+const fetchUser = memoize(
+  async (id: string) => db.users.findById(id),
+  { ttl: 30_000, maxSize: 500 },
+);
+
+// Multi-arg with custom key resolver
+const multi = memoize(
+  (a: number, b: number) => a + b,
+  { key: (a, b) => `${a}:${b}` },
+);
+```
+
+Options: `maxSize` (default: 256), `ttl` (ms, default: 0 = no expiry), `key`
+(custom key resolver).
+
+### URL Utilities
+
+```ts
+import { getPathname } from "@coderbuzz/ken";
+
+getPathname("https://example.com/api/v1?q=1"); // '/api/v1'
 ```
 
 ---
@@ -784,6 +1377,16 @@ if (isDeno) console.log("Running on Deno");
 if (isNode) console.log("Running on Node.js");
 ```
 
+### Node.js with uWebSockets.js
+
+For maximum performance on Node.js, install `uWebSockets.js` and set the `UWS`
+environment variable:
+
+```sh
+npm install uWebSockets.js
+UWS=1 node --import tsx/esm server.ts
+```
+
 ---
 
 ## Remote Info
@@ -795,6 +1398,30 @@ app.get("/ip", (ctx) => {
 });
 ```
 
+Ken checks proxy headers in order: `CF-Connecting-IP`, `X-Real-IP`,
+`X-Forwarded-For`, `True-Client-IP` — then falls back to the raw socket address.
+
+---
+
+## Context API Reference
+
+| Property                            | Type                                | Description                        |
+| ----------------------------------- | ----------------------------------- | ---------------------------------- |
+| `ctx.url`                           | `string`                            | Full request URL                   |
+| `ctx.method`                        | `string`                            | HTTP method (uppercase)            |
+| `ctx.params`                        | `Record<string, string>` (or typed) | Route path parameters              |
+| `ctx.query`                         | `Record<string, string>` (or typed) | URL query string parameters        |
+| `ctx.headers`                       | `Record<string, string>` (or typed) | Request headers (lowercase keys)   |
+| `ctx.cookies`                       | `Record<string, string>` (or typed) | Request cookies                    |
+| `ctx.json`                          | `Promise<any>` (or typed)           | Parsed JSON body                   |
+| `ctx.text`                          | `Promise<string>` (or typed)        | Raw text body                      |
+| `ctx.form`                          | `Promise<FormData>` (or typed)      | Parsed form data body              |
+| `ctx.body`                          | `any`                               | Raw body stream (runtime-specific) |
+| `ctx.state`                         | typed                               | State produced by middleware       |
+| `ctx.remoteInfo`                    | `{ address: string; port: number }` | Client IP and port                 |
+| `ctx.setCookie(name, value, opts?)` | `void`                              | Set a response cookie              |
+| `ctx.onFinish(cb)`                  | `void`                              | Register post-response callback    |
+
 ---
 
 ## License