princejs 2.1.6 → 2.2.1

package/Readme.md

@@ -61,9 +61,9 @@ app.listen(3000);
 
 | Feature | Import |
 |---------|--------|
-| Routing, WebSockets, OpenAPI, Plugins, Lifecycle Hooks, Cookies, IP | `princejs` |
-| CORS, Logger, JWT, Auth, Rate Limit, Validate, Compress, Session, API Key | `princejs/middleware` |
-| File Uploads, SSE, In-memory Cache | `princejs/helpers` |
+| Routing, Route Grouping, WebSockets, OpenAPI, Plugins, Lifecycle Hooks, Cookies, IP | `princejs` |
+| CORS, Logger, JWT, JWKS, Auth, Rate Limit, Validate, Compress, Session, API Key, Secure Headers, Timeout, Request ID, IP Restriction, Static Files | `princejs/middleware` |
+| File Uploads, SSE, Streaming, In-memory Cache | `princejs/helpers` |
 | Cron Scheduler | `princejs/scheduler` |
 | JSX / SSR | `princejs/jsx` |
 | SQLite Database | `princejs/db` |
@@ -155,6 +155,188 @@ app.post("/admin", (req) => {
 
 ---
 
+
+## 🗂️ Route Grouping
+
+Group routes under a shared prefix with optional shared middleware. Zero overhead at request time — purely a registration convenience.
+
+```ts
+import { prince } from "princejs";
+
+const app = prince();
+
+// Basic grouping
+app.group("/api", (r) => {
+  r.get("/users",     () => ({ users: [] }));
+  r.post("/users",    (req) => ({ created: req.parsedBody }));
+  r.get("/users/:id", (req) => ({ id: req.params?.id }));
+});
+// → GET  /api/users
+// → POST /api/users
+// → 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",   () => ({ stats: {} }));
+  r.delete("/users/:id", (req) => ({ deleted: req.params?.id }));
+});
+
+// Chainable
+app
+  .group("/v1", (r) => { r.get("/ping", () => ({ v: 1 })); })
+  .group("/v2", (r) => { r.get("/ping", () => ({ v: 2 })); });
+
+app.listen(3000);
+```
+
+---
+
+## 🛡️ Secure Headers
+
+One call sets all the security headers your production app needs:
+
+```ts
+import { secureHeaders } from "princejs/middleware";
+
+app.use(secureHeaders());
+// Sets: X-Frame-Options, X-Content-Type-Options, X-XSS-Protection,
+//       Strict-Transport-Security, Referrer-Policy
+
+// Custom options
+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));          // 5 second global timeout → 408
+app.use(timeout(3000, "Slow!")); // custom message
+
+// Per-route timeout
+app.get("/heavy", timeout(10000), (req) => heavyOperation());
+```
+
+---
+
+## 🏷️ 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 name
+app.use(requestId({ header: "X-Trace-ID" }));
+
+// Custom generator
+app.use(requestId({ generator: () => `req-${Date.now()}` }));
+
+app.get("/", (req) => ({ requestId: req.id }));
+```
+
+---
+
+## 🚫 IP Restriction
+
+Allow or block 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 these IPs
+app.use(ipRestriction({ denyList: ["1.2.3.4"] }));
+```
+
+---
+
+## 📁 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"));
+// → GET /logo.png        serves ./public/logo.png
+// → GET /               serves ./public/index.html
+// → GET /api/users      falls through to your route handler
+```
+
+---
+
+## 🌊 Streaming
+
+Stream chunked responses for AI/LLM output, large payloads, or anything that generates data over time:
+
+```ts
+import { stream } from "princejs/helpers";
+
+// Async generator — cleanest for AI token streaming
+app.get("/ai", stream(async function*(req) {
+  yield "Hello ";
+  await delay(100);
+  yield "from ";
+  yield "PrinceJS!";
+}));
+
+// Async callback
+app.get("/data", stream(async (req) => {
+  req.streamSend("chunk 1");
+  await fetchMoreData();
+  req.streamSend("chunk 2");
+}));
+
+// Custom content type for binary or JSON streams
+app.get("/events", stream(async function*(req) {
+  for (const item of items) {
+    yield JSON.stringify(item) + "\n";
+  }
+}, { contentType: "application/x-ndjson" }));
+```
+
+---
+
+## 🔑 JWKS / Third-Party Auth
+
+Verify JWTs from Auth0, Clerk, Supabase, or any 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.clerk.accounts.dev/.well-known/jwks.json"));
+
+// Supabase
+app.use(jwks("https://your-project.supabase.co/auth/v1/.well-known/jwks.json"));
+
+// req.user is set after verification, same as jwt()
+app.get("/protected", auth(), (req) => ({ user: req.user }));
+```
+
+---
+
 ## 📖 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 +534,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 +557,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));

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":"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"}