princejs 1.9.7 → 2.1.0

package/README.md

@@ -1,7 +1,5 @@
 <div align="center">
 
-<img src="./src/images/og.png" alt="PrinceJS"/>
-
 # 👑 PrinceJS
 
 **Ultra-clean, modern & minimal Bun web framework.**  
@@ -65,6 +63,7 @@ app.listen(3000);
 | Routing | `princejs` |
 | Middleware (CORS, Logger, Rate Limit, Auth, JWT) | `princejs/middleware` |
 | Zod Validation | `princejs/middleware` |
+| **Cookies & IP Detection** | `princejs` |
 | File Uploads | `princejs/helpers` |
 | WebSockets | `princejs` |
 | Server-Sent Events | `princejs/helpers` |
@@ -77,7 +76,93 @@ app.listen(3000);
 | SQLite Database | `princejs/db` |
 | Plugin System | `princejs` |
 | End-to-End Type Safety | `princejs/client` |
-| Deploy Adapters | `princejs/vercel` · `princejs/cloudflare` · `princejs/deno` |
+| Deploy Adapters | `princejs/vercel` · `princejs/cloudflare` · `princejs/deno` · `princejs/node` |
+| Lifecycle Hooks | `princejs` | 
+
+---
+
+## 🍪 Cookies & 🌐 IP Detection
+
+### Reading Cookies
+
+Cookies are automatically parsed from the request:
+
+```ts
+app.get("/profile", (req) => ({
+  sessionId: req.cookies?.sessionId,
+  theme: req.cookies?.theme,
+  allCookies: req.cookies // Record<string, string>
+}));
+```
+
+### Setting Cookies
+
+Use the response builder to set cookies with full control:
+
+```ts
+app.get("/login", (req) => 
+  app.response()
+    .status(200)
+    .json({ ok: true })
+    .cookie("sessionId", "abc123", {
+      maxAge: 3600,        // 1 hour
+      path: "/",
+      httpOnly: true,      // not accessible from JS
+      secure: true,        // HTTPS only
+      sameSite: "Strict"   // CSRF protection
+    })
+);
+
+// Chain multiple cookies
+app.response()
+  .json({ ok: true })
+  .cookie("session", "xyz")
+  .cookie("theme", "dark")
+  .cookie("lang", "en");
+```
+
+### Client IP Detection
+
+Automatically detect client IP from request headers:
+
+```ts
+app.get("/api/data", (req) => ({
+  clientIp: req.ip,
+  data: [...]
+}));
+```
+
+**Supported headers** (in priority order):
+- `X-Forwarded-For` — Load balancers, proxies (first IP in list)
+- `X-Real-IP` — Nginx, Apache reverse proxy
+- `CF-Connecting-IP` — Cloudflare
+- `X-Client-IP` — Other proxy services
+- Fallback — `127.0.0.1` (localhost)
+
+**Use cases:**
+- 🔒 Rate limiting per IP
+- 📊 Geolocation analytics
+- 🚨 IP-based access control
+- 👥 User tracking & fraud detection
+
+```ts
+// Rate limit by IP
+app.use((req, next) => {
+  const ip = req.ip;
+  const count = ipTracker.getCount(ip) || 0;
+  if (count > 100) return new Response("Too many requests", { status: 429 });
+  ipTracker.increment(ip);
+  return next();
+});
+
+// IP-based security
+app.post("/admin", (req) => {
+  if (!ALLOWED_IPS.includes(req.ip!)) {
+    return new Response("Forbidden", { status: 403 });
+  }
+  return { authorized: true };
+});
+```
 
 ---
 
@@ -160,6 +245,57 @@ app.plugin(usersPlugin, { prefix: "/api" });
 
 ---
 
+## 🎣 Lifecycle Hooks
+
+React to key moments in request processing with lifecycle hooks:
+
+```ts
+import { prince } from "princejs";
+
+const app = prince();
+
+// Called for every incoming request
+app.onRequest((req) => {
+  console.log(`📥 Request received: ${req.method} ${req.url}`);
+});
+
+// Called before handler execution
+app.onBeforeHandle((req, path, method) => {
+  console.log(`🔍 About to handle: ${method} ${path}`);
+  (req as any).startTime = Date.now();
+});
+
+// Called after successful handler execution
+app.onAfterHandle((req, res, path, method) => {
+  const duration = Date.now() - (req as any).startTime;
+  console.log(`✅ Response: ${method} ${path} ${res.status} (${duration}ms)`);
+});
+
+// Called when handler throws an error
+app.onError((err, req, path, method) => {
+  console.error(`❌ Error in ${method} ${path}:`, err.message);
+  // Send alert, log to monitoring service, etc.
+});
+
+app.get("/users", () => ({ users: [] }));
+```
+
+**Hook execution order:**
+1. `onRequest` — early for request-wide setup
+2. `onBeforeHandle` — just before route handler runs
+3. Handler executes
+4. `onAfterHandle` — after success (on error, skipped)
+5. `onError` — only if handler throws (skips onAfterHandle)
+
+**Use cases:**
+- 📊 Metrics & observability
+- 🔍 Request inspection & debugging
+- ⏱️ Timing & performance monitoring
+- 🚨 Error tracking & alerting  
+- 🔐 Security audits & compliance logging
+
+---
+
 ## 🔒 End-to-End Type Safety
 
 Define a contract once — your client gets full TypeScript autocompletion automatically:
@@ -206,6 +342,25 @@ import { toDeno } from "princejs/deno";
 Deno.serve(toDeno(app));
 ```
 
+**Node Adapter** - `server.ts`
+```ts
+import { createServer } from "http";
+import { toNode, toExpress } from "princejs/node";
+
+const app = prince();
+app.get("/", () => ({ message: "Hello from Node!" }));
+
+// Native Node.js http
+const server = createServer(toNode(app));
+server.listen(3000);
+
+// Or with Express
+import express from "express";
+const expressApp = express();
+expressApp.all("*", toExpress(app));
+expressApp.listen(3000);
+```
+
 ---
 
 ## 🎯 Full Example
@@ -222,7 +377,29 @@ import { z } from "zod";
 
 const app = prince(true);
 
-// Global middleware
+// ==========================================
+// LIFECYCLE HOOKS - Timing & Observability
+// ==========================================
+app.onRequest((req) => {
+  (req as any).startTime = Date.now();
+});
+
+app.onBeforeHandle((req, path, method) => {
+  console.log(`🔍 Handling: ${method} ${path}`);
+});
+
+app.onAfterHandle((req, res, path, method) => {
+  const duration = Date.now() - (req as any).startTime;
+  console.log(`✅ ${method} ${path} → ${res.status} (${duration}ms)`);
+});
+
+app.onError((err, req, path, method) => {
+  console.error(`❌ ${method} ${path} failed:`, err.message);
+});
+
+// ==========================================
+// GLOBAL MIDDLEWARE
+// ==========================================
 app.use(cors());
 app.use(logger());
 app.use(rateLimit({ max: 100, window: 60 }));
@@ -231,10 +408,31 @@ app.use(jwt(key));
 app.use(session({ secret: "key" }));
 app.use(compress());
 
+// ==========================================
+// ROUTES
+// ==========================================
+
 // JSX
 const Page = () => Html(Head("Test Page"), Body(H1("Hello World"), P("This is a test")));
 app.get("/jsx", () => render(Page()));
 
+// Cookies & IP Detection
+app.post("/login", (req) => 
+  app.response()
+    .json({ ok: true, ip: req.ip })
+    .cookie("sessionId", "user_123", { 
+      httpOnly: true, 
+      secure: true,
+      sameSite: "Strict",
+      maxAge: 86400 // 24 hours
+    })
+);
+
+app.get("/profile", (req) => ({
+  sessionId: req.cookies?.sessionId,
+  clientIp: req.ip,
+}));
+
 // Database
 const users = db.sqlite("./db.sqlite", "CREATE TABLE users...");
 app.get("/users", () => users.query("SELECT * FROM users"));
@@ -247,7 +445,7 @@ app.ws("/chat", {
 
 // Auth
 app.get("/protected", auth(), (req) => ({ user: req.user }));
-app.get("/api", apiKey({ keys: ["key_123"] }), handler);
+app.get("/api", apiKey({ keys: ["key_123"] }), (req) => ({ ok: true }));
 
 // Helpers
 app.get("/data", cache(60)(() => ({ time: Date.now() })));
@@ -256,10 +454,14 @@ app.get("/events", sse(), (req) => {
   setInterval(() => req.sseSend({ time: Date.now() }), 1000);
 });
 
-// Cron
+// ==========================================
+// CRON JOBS
+// ==========================================
 cron("*/1 * * * *", () => console.log("PrinceJS heartbeat"));
 
-// OpenAPI + Scalar docs
+// ==========================================
+// OPENAPI + SCALAR DOCS
+// ==========================================
 const api = app.openapi({ title: "PrinceJS App", version: "1.0.0" }, "/docs");
 api.route("GET", "/items", {
   summary: "List items",

package/dist/adapters/node.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Official Node.js deploy adapter for PrinceJS
+ *
+ * @example
+ * // server.ts
+ * import { createServer } from "http";
+ * import { prince } from "princejs";
+ * import { toNode } from "princejs/node";
+ *
+ * const app = prince();
+ * app.get("/", () => ({ message: "Hello from Node.js!" }));
+ *
+ * const server = createServer(toNode(app));
+ * server.listen(3000, () => {
+ *   console.log("Listening on http://localhost:3000");
+ * });
+ *
+ * @example
+ * // With Express.js
+ * import express from "express";
+ * import { prince } from "princejs";
+ * import { toExpress } from "princejs/node";
+ *
+ * const app = express();
+ * const princeApp = prince();
+ * princeApp.get("/", () => ({ message: "Hello!" }));
+ *
+ * app.all("*", toExpress(princeApp));
+ * app.listen(3000);
+ */
+export type PrinceApp = {
+    fetch(request: Request): Promise<Response>;
+};
+/**
+ * Converts a Prince app to a Node.js http.createServer() handler
+ * @example
+ * const server = createServer(toNode(app));
+ * server.listen(3000);
+ */
+export declare function toNode(app: PrinceApp): (req: any, res: any) => Promise<void>;
+/**
+ * Converts a Prince app to an Express.js middleware handler
+ * @example
+ * app.all("*", toExpress(princeApp));
+ */
+export declare function toExpress(app: PrinceApp): (req: any, res: any, next?: any) => Promise<void>;
+//# sourceMappingURL=node.d.ts.map

package/dist/adapters/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/adapters/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAAE,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,GAAG,EAAE,SAAS,GACb,CACD,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,GAAG,KACL,OAAO,CAAC,IAAI,CAAC,CAuCjB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,SAAS,GACb,CACD,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,GAAG,EACR,IAAI,CAAC,EAAE,GAAG,KACP,OAAO,CAAC,IAAI,CAAC,CAoCjB"}