princejs 2.1.6 → 2.2.0

package/Readme.md

@@ -28,7 +28,7 @@ Benchmarked with `oha -c 100 -z 30s` on Windows 10:
 | Fastify | 15,519 | 16,434 |
 | Express | 13,138 | 13,458 |
 
-> PrinceJS is **2.3× faster than Express**, matches Hono head-to-head, and sits at just **5.1kB gzipped** — loads in ~101ms on a slow 3G connection.
+> PrinceJS is **2.3× faster than Express**, matches Hono head-to-head, and sits at just **6.3kB gzipped** — loads in ~122ms on a slow 3G connection.
 
 ---
 
@@ -62,8 +62,10 @@ app.listen(3000);
 | Feature | Import |
 |---------|--------|
 | Routing, WebSockets, OpenAPI, Plugins, Lifecycle Hooks, Cookies, IP | `princejs` |
+| **Route Grouping** | `princejs` |
 | CORS, Logger, JWT, Auth, Rate Limit, Validate, Compress, Session, API Key | `princejs/middleware` |
-| File Uploads, SSE, In-memory Cache | `princejs/helpers` |
+| **Secure Headers, Timeout, Request ID, IP Restriction, Static Files, JWKS** | `princejs/middleware` |
+| File Uploads, SSE, In-memory Cache, **Streaming** | `princejs/helpers` |
 | Cron Scheduler | `princejs/scheduler` |
 | JSX / SSR | `princejs/jsx` |
 | SQLite Database | `princejs/db` |
@@ -155,6 +157,167 @@ app.post("/admin", (req) => {
 
 ---
 
+---
+
+## 📁 Route Grouping
+
+Namespace routes under a shared prefix with optional shared middleware. Zero overhead at request time — just registers prefixed routes in the trie.
+
+```ts
+// Basic grouping
+app.group("/api", (r) => {
+  r.get("/users",     () => ({ users: [] }));          // → GET /api/users
+  r.post("/users",    (req) => req.parsedBody);         // → POST /api/users
+  r.get("/users/:id", (req) => ({ id: req.params?.id })); // → GET /api/users/:id
+});
+
+// With shared middleware — applies to every route in the group
+import { auth } from "princejs/middleware";
+
+app.group("/admin", auth(), (r) => {
+  r.get("/stats",   () => ({ ok: true }));              // → GET /admin/stats
+  r.delete("/user", () => ({ deleted: true }));         // → DELETE /admin/user
+});
+
+// Chainable
+app
+  .group("/v1", (r) => { r.get("/ping", () => ({ v: 1 })); })
+  .group("/v2", (r) => { r.get("/ping", () => ({ v: 2 })); });
+```
+
+---
+
+## 🔐 Security Middleware
+
+### Secure Headers
+
+One call sets X-Frame-Options, HSTS, X-Content-Type-Options, X-XSS-Protection, and Referrer-Policy:
+
+```ts
+import { secureHeaders } from "princejs/middleware";
+
+app.use(secureHeaders());
+
+// Custom overrides
+app.use(secureHeaders({
+  xFrameOptions: "DENY",
+  contentSecurityPolicy: "default-src 'self'",
+  permissionsPolicy: "camera=(), microphone=()",
+  strictTransportSecurity: "max-age=63072000; includeSubDomains; preload",
+}));
+```
+
+### Request Timeout
+
+Kill hanging requests before they pile up:
+
+```ts
+import { timeout } from "princejs/middleware";
+
+app.use(timeout(5000));                        // 408 after 5s
+app.use(timeout(3000, "Gateway Timeout"));     // custom message
+```
+
+### Request ID
+
+Attach a unique ID to every request for distributed tracing and log correlation:
+
+```ts
+import { requestId } from "princejs/middleware";
+
+app.use(requestId());
+// → sets req.id and X-Request-ID response header
+
+// Custom header or generator
+app.use(requestId({
+  header:    "X-Trace-ID",
+  generator: () => `req-${Date.now()}`,
+}));
+
+app.get("/", (req) => ({ requestId: req.id }));
+```
+
+### IP Restriction
+
+Allow or deny specific IPs:
+
+```ts
+import { ipRestriction } from "princejs/middleware";
+
+// Only allow these IPs
+app.use(ipRestriction({ allowList: ["192.168.1.1", "10.0.0.1"] }));
+
+// Block specific IPs
+app.use(ipRestriction({ denyList: ["1.2.3.4"] }));
+```
+
+### JWKS — Auth0, Clerk, Supabase
+
+Verify JWTs against a remote JWKS endpoint — no symmetric key needed:
+
+```ts
+import { jwks } from "princejs/middleware";
+
+// Auth0
+app.use(jwks("https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json"));
+
+// Clerk
+app.use(jwks("https://YOUR_CLERK_DOMAIN/.well-known/jwks.json"));
+
+// Keys are cached automatically — only fetched on rotation
+app.get("/protected", auth(), (req) => ({ user: req.user }));
+```
+
+---
+
+## 📂 Static Files
+
+Serve a directory of static files. Falls through to your routes if the file doesn't exist:
+
+```ts
+import { serveStatic } from "princejs/middleware";
+
+app.use(serveStatic("./public"));
+
+// Your API routes still work normally
+app.get("/api/users", () => ({ users: [] }));
+```
+
+---
+
+## 🌊 Streaming
+
+Stream responses chunk by chunk — perfect for AI/LLM token output:
+
+```ts
+import { stream } from "princejs/helpers";
+
+// Async generator (cleanest for AI output)
+app.get("/ai", stream(async function*(req) {
+  yield "Hello ";
+  yield "from ";
+  yield "PrinceJS!";
+}));
+
+// Callback style
+app.get("/stream", stream((req) => {
+  req.streamSend("chunk 1");
+  req.streamSend("chunk 2");
+}));
+
+// Async callback
+app.get("/slow-stream", stream(async (req) => {
+  req.streamSend("Starting...");
+  await fetch("https://api.openai.com/v1/chat/completions", { /* ... */ })
+    .then(res => res.body?.pipeTo(new WritableStream({
+      write(chunk) { req.streamSend(chunk); }
+    })));
+}));
+
+// Custom content type
+app.get("/binary", stream(() => { /* ... */ }, { contentType: "application/octet-stream" }));
+```
+
 ## 📖 OpenAPI + Scalar Docs ✨
 
 Auto-generate an OpenAPI 3.0 spec and serve a beautiful [Scalar](https://scalar.com) UI — all from a single `app.openapi()` call.
@@ -352,8 +515,11 @@ import {
   session,
   compress,
   validate,
+  secureHeaders,
+  timeout,
+  requestId,
 } from "princejs/middleware";
-import { cache, upload, sse } from "princejs/helpers";
+import { cache, upload, sse, stream } from "princejs/helpers";
 import { cron } from "princejs/scheduler";
 import { Html, Head, Body, H1, P, render } from "princejs/jsx";
 import { db } from "princejs/db";
@@ -372,6 +538,9 @@ app.onError((err, req, path, method) => {
 });
 
 // ── Global middleware ─────────────────────────────────────
+app.use(secureHeaders());
+app.use(requestId());
+app.use(timeout(10000));
 app.use(cors());
 app.use(logger());
 app.use(rateLimit(100, 60));
@@ -431,6 +600,17 @@ app.post(
   (req) => ({ created: req.parsedBody })
 );
 
+// ── Route groups ─────────────────────────────────────────
+app.group("/v1", (r) => {
+  r.get("/status", () => ({ version: 1, ok: true }));
+});
+
+// ── Streaming ─────────────────────────────────────────────
+app.get("/ai", stream(async function*() {
+  yield "Hello ";
+  yield "World!";
+}));
+
 // ── Cron ──────────────────────────────────────────────────
 cron("* * * * *", () => console.log("💓 heartbeat"));
 
@@ -492,7 +672,7 @@ bun test
 
 <div align="center">
 
-**PrinceJS: 5.1kB. Hono-speed. Everything included. 👑**
+**PrinceJS: 6.3kB. Hono-speed. Everything included. 👑**
 
 *Built with ❤️ in Nigeria*
 

package/dist/helpers.d.ts

@@ -3,4 +3,7 @@ export declare const cache: (ttl: number) => (handler: any) => (req: PrinceReque
 export declare const email: (to: string, subject: string, html: string) => Promise<void>;
 export declare const upload: () => (req: PrinceRequest) => Promise<Response>;
 export declare const sse: () => (req: PrinceRequest) => Response;
+export declare const stream: (handler: (req: PrinceRequest) => AsyncGenerator<string | Uint8Array, void, unknown> | void | Promise<void>, options?: {
+    contentType?: string;
+}) => (req: PrinceRequest) => Response;
 //# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG9C,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,MAEvB,SAAS,GAAG,MAAY,KAAK,aAAa,iBASnD,CAAC;AAGF,eAAO,MAAM,KAAK,GAAU,IAAI,MAAM,EAAE,SAAS,MAAM,EAAE,MAAM,MAAM,kBAMpE,CAAC;AAGF,eAAO,MAAM,MAAM,SACH,KAAK,aAAa,sBA4CjC,CAAC;AAGF,eAAO,MAAM,GAAG,SACN,KAAK,aAAa,aA0B3B,CAAC"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG9C,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,MAEvB,SAAS,GAAG,MAAY,KAAK,aAAa,iBASnD,CAAC;AAGF,eAAO,MAAM,KAAK,GAAU,IAAI,MAAM,EAAE,SAAS,MAAM,EAAE,MAAM,MAAM,kBAMpE,CAAC;AAGF,eAAO,MAAM,MAAM,SACH,KAAK,aAAa,sBA4CjC,CAAC;AAGF,eAAO,MAAM,GAAG,SACN,KAAK,aAAa,aA0B3B,CAAC;AAgBF,eAAO,MAAM,MAAM,GACjB,SAAS,CAAC,GAAG,EAAE,aAAa,KAAK,cAAc,CAAC,MAAM,GAAG,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC1G,UAAU;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,MAK1B,KAAK,aAAa,aAmD3B,CAAC"}

package/dist/helpers.js

@@ -81,8 +81,64 @@ var sse = () => {
     });
   };
 };
+var stream = (handler, options) => {
+  const contentType = options?.contentType ?? "text/plain; charset=utf-8";
+  const enc = new TextEncoder;
+  return (req) => {
+    let resolveController;
+    const controllerReady = new Promise((res) => {
+      resolveController = res;
+    });
+    const readable = new ReadableStream({
+      start(c) {
+        resolveController(c);
+      }
+    });
+    controllerReady.then((controller) => {
+      const enqueue = (chunk) => controller.enqueue(typeof chunk === "string" ? enc.encode(chunk) : chunk);
+      req.streamSend = enqueue;
+      req.streamClose = () => controller.close();
+      req.streamError = (e) => controller.error(e);
+      const result = handler(req);
+      if (result && typeof result[Symbol.asyncIterator] === "function") {
+        (async () => {
+          try {
+            for await (const chunk of result) {
+              enqueue(chunk);
+            }
+            controller.close();
+          } catch (e) {
+            controller.error(e);
+          }
+        })();
+      } else if (result instanceof Promise) {
+        result.then(() => {
+          try {
+            controller.close();
+          } catch {}
+        }).catch((e) => {
+          try {
+            controller.error(e);
+          } catch {}
+        });
+      } else {
+        try {
+          controller.close();
+        } catch {}
+      }
+    });
+    return new Response(readable, {
+      headers: {
+        "Content-Type": contentType,
+        "Transfer-Encoding": "chunked",
+        "X-Content-Type-Options": "nosniff"
+      }
+    });
+  };
+};
 export {
   upload,
+  stream,
   sse,
   email,
   cache

package/dist/middleware.d.ts

@@ -35,5 +35,27 @@ export declare const session: (options: {
     maxAge?: number;
     name?: string;
 }) => (req: PrinceRequest, next: Next) => Promise<Response | undefined>;
+export declare const secureHeaders: (options?: {
+    xFrameOptions?: string;
+    xContentTypeOptions?: boolean;
+    xXssProtection?: string;
+    strictTransportSecurity?: string;
+    referrerPolicy?: string;
+    permissionsPolicy?: string;
+    contentSecurityPolicy?: string;
+}) => (req: PrinceRequest, next: Next) => Promise<Response | undefined>;
+export declare const timeout: (ms: number, message?: string) => (req: PrinceRequest, next: Next) => Promise<Response | undefined>;
+export declare const requestId: (options?: {
+    header?: string;
+    generator?: () => string;
+}) => (req: PrinceRequest, next: Next) => Promise<Response | undefined>;
+export declare const ipRestriction: (options: {
+    allowList?: string[];
+    denyList?: string[];
+}) => (req: PrinceRequest, next: Next) => Promise<Response | undefined>;
+export declare const serveStatic: (root: string) => (req: PrinceRequest, next: Next) => Promise<Response | undefined>;
+export declare const jwks: (jwksUrl: string, options?: {
+    algorithms?: string[];
+}) => (req: PrinceRequest, next: Next) => Promise<Response | undefined>;
 export {};
 //# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,KAAK,IAAI,GAAG,MAAM,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;AAGhD,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QACjB,GAAG,EAAE,aAAa,CAAC;QACnB,GAAG,CAAC,EAAE,QAAQ,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,GAAG,CAAC;KACb,KAAK,IAAI,CAAC;CACZ;AAED,eAAO,MAAM,MAAM,GAAI,UAAS,aAAkB,MASlC,KAAK,aAAa,EAAE,MAAM,IAAI,kCAqD7C,CAAC;AAGF,eAAO,MAAM,IAAI,GAAI,SAAQ,MAAY,MACzB,KAAK,GAAG,EAAE,MAAM,QAAQ,iBA+BvC,CAAC;AAGF,eAAO,MAAM,OAAO,GAAU,SAAS,GAAG,EAAE,QAAQ,UAAU,EAAE,WAAW,MAAM,oBAQhF,CAAC;AAEF,eAAO,MAAM,GAAG,GAAI,KAAK,UAAU,MACnB,KAAK,aAAa,EAAE,MAAM,IAAI,kCAuB7C,CAAC;AAGF,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,eAAW,MAGlC,KAAK,aAAa,EAAE,MAAM,IAAI,kCAqC7C,CAAC;AAGF,eAAO,MAAM,QAAQ,GAAI,QAAQ,CAAC,CAAC,SAAS,MAC5B,KAAK,GAAG,EAAE,MAAM,QAAQ,iBAyEvC,CAAC;AAGF,eAAO,MAAM,IAAI,GAAI,UAAU;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,MACnC,KAAK,aAAa,EAAE,MAAM,IAAI,kCAwB7C,CAAC;AAGF,eAAO,MAAM,MAAM,GAAI,SAAS;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,MAInD,KAAK,aAAa,EAAE,MAAM,IAAI,kCAa7C,CAAC;AAGF,eAAO,MAAM,QAAQ,GAAI,UAAU;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC;CAC1C,MAIe,KAAK,aAAa,EAAE,MAAM,IAAI,kCAqC7C,CAAC;AAGF,eAAO,MAAM,OAAO,GAAI,SAAS;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,MAce,KAAK,aAAa,EAAE,MAAM,IAAI,kCA+C7C,CAAC"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,KAAK,IAAI,GAAG,MAAM,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;AAGhD,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QACjB,GAAG,EAAE,aAAa,CAAC;QACnB,GAAG,CAAC,EAAE,QAAQ,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,GAAG,CAAC;KACb,KAAK,IAAI,CAAC;CACZ;AAED,eAAO,MAAM,MAAM,GAAI,UAAS,aAAkB,MASlC,KAAK,aAAa,EAAE,MAAM,IAAI,kCAqD7C,CAAC;AAGF,eAAO,MAAM,IAAI,GAAI,SAAQ,MAAY,MACzB,KAAK,GAAG,EAAE,MAAM,QAAQ,iBA+BvC,CAAC;AAGF,eAAO,MAAM,OAAO,GAAU,SAAS,GAAG,EAAE,QAAQ,UAAU,EAAE,WAAW,MAAM,oBAQhF,CAAC;AAEF,eAAO,MAAM,GAAG,GAAI,KAAK,UAAU,MACnB,KAAK,aAAa,EAAE,MAAM,IAAI,kCAuB7C,CAAC;AAGF,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,eAAW,MAGlC,KAAK,aAAa,EAAE,MAAM,IAAI,kCAqC7C,CAAC;AAGF,eAAO,MAAM,QAAQ,GAAI,QAAQ,CAAC,CAAC,SAAS,MAC5B,KAAK,GAAG,EAAE,MAAM,QAAQ,iBAyEvC,CAAC;AAGF,eAAO,MAAM,IAAI,GAAI,UAAU;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,MACnC,KAAK,aAAa,EAAE,MAAM,IAAI,kCAwB7C,CAAC;AAGF,eAAO,MAAM,MAAM,GAAI,SAAS;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,MAInD,KAAK,aAAa,EAAE,MAAM,IAAI,kCAa7C,CAAC;AAGF,eAAO,MAAM,QAAQ,GAAI,UAAU;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC;CAC1C,MAIe,KAAK,aAAa,EAAE,MAAM,IAAI,kCAqC7C,CAAC;AAGF,eAAO,MAAM,OAAO,GAAI,SAAS;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,MAce,KAAK,aAAa,EAAE,MAAM,IAAI,kCA+C7C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,UAAU;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,MAEe,KAAK,aAAa,EAAE,MAAM,IAAI,kCAiB7C,CAAC;AAGF,eAAO,MAAM,OAAO,GAAI,IAAI,MAAM,EAAE,gBAA2B,MAC/C,KAAK,aAAa,EAAE,MAAM,IAAI,kCAiB7C,CAAC;AAGF,eAAO,MAAM,SAAS,GAAI,UAAU;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,MAGjE,KAAK,aAAa,EAAE,MAAM,IAAI,kCAS7C,CAAC;AAGF,eAAO,MAAM,aAAa,GAAI,SAAS;IAAE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,MAGpE,KAAK,aAAa,EAAE,MAAM,IAAI,kCAM7C,CAAC;AAGF,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,MAExB,KAAK,aAAa,EAAE,MAAM,IAAI,kCAe7C,CAAC;AAMF,eAAO,MAAM,IAAI,GAAI,SAAS,MAAM,EAAE,UAAU;IAAE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,MAEzD,KAAK,aAAa,EAAE,MAAM,IAAI,kCAe7C,CAAC"}