vibe-gx 4.2.0 → 4.2.1

package/README.md

@@ -1,770 +1,24 @@
-<div align="center">
-  <img src="https://github.com/thesixers/vibe/blob/808b45722a0b3ca0d266215bbe4cc074f62283e5/assets/vlogo.png?raw=true" alt="Vibe Logo" width="180" />
-  <h1>Vibe</h1>
-  <p>
-    <b>The fastest Node.js web framework with the simplest syntax.</b>
-  </p>
-  <p>
-    <img src="https://img.shields.io/badge/performance-11,472_RPS-brightgreen" alt="Performance" />
-    <img src="https://img.shields.io/badge/vs_Express-4.7x_faster-blue" alt="vs Express" />
-    <img src="https://img.shields.io/badge/vs_Fastify-faster-orange" alt="vs Fastify" />
-    <img src="https://img.shields.io/badge/license-MIT-green" alt="License" />
-  </p>
-</div>
+# Vibe
 
----
-
-## 📦 Installation
-
-```bash
-npm install vibe-gx
-```
-
-> Pure JavaScript — no native dependencies, no build steps, just install and go.
-
----
-
-## 🏆 Why Vibe?
-
-| Metric                     |      Vibe      |  Express  |  Fastify   |
-| :------------------------- | :------------: | :-------: | :--------: |
-| **JSON Performance**       | **11,472 RPS** | 2,421 RPS | 11,334 RPS |
-| **Install Size**           |  **~280 KB**   |   ~5 MB   |   ~4 MB    |
-| **Lines for Hello World**  |       3        |     5     |     6      |
-| **Dependencies**           |       1        |    30+    |    15+     |
-| **Built-in Clustering**    |       ✅       |    ❌     |     ❌     |
-| **Built-in Caching**       |       ✅       |    ❌     |     ❌     |
-| **Code-Gen Serialization** |       ✅       |    ❌     |     ✅     |
-
-> **Vibe is faster than Fastify, simpler than Express, and 14-18x smaller than both.**
-
----
-
-## ⚡ Features
-
-| Feature                       | Description                                                |
-| :---------------------------- | :--------------------------------------------------------- |
-| 🚀 **Code-Gen Serialization** | Schema-compiled JSON serializers via `new Function()`      |
-| 🎯 **Hybrid Router**          | O(1) static + O(log n) Trie routing                        |
-| 🔌 **Plugin System**          | Encapsulated `register()` with optional route prefixes     |
-| 🎨 **Decorators**             | Extend app, request, and response                          |
-| ⚡ **Cluster Mode**           | Built-in multi-process scaling                             |
-| 💾 **LRU Cache**              | Built-in response caching with ETag                        |
-| 🛡️ **Rate Limiting**          | Built-in sliding window rate limiter — no dependencies     |
-| 🌐 **CORS**                   | Built-in CORS with preflight handling — no dependencies    |
-| 🔗 **Connection Pool**        | Generic pool for databases                                 |
-| 📂 **File Uploads**           | Multipart uploads with size/type validation                |
-| 🌊 **Streaming**              | Large file uploads without buffering                       |
-| 🔒 **Security**               | Path traversal protection, body limits, error sanitization |
-| 🔄 **Express Adapter**        | Use any Express middleware with `adapt()`                  |
-
----
-
-## 🚀 Quick Start
-
-```javascript
-import vibe from "vibe-gx";
-
-const app = vibe();
-
-// Direct value - no callback needed!
-app.get("/", "Hello Vibe!");
-
-// Auto JSON response - just return an object
-app.get("/users/:id", (req) => ({ userId: req.params.id }));
-
-app.listen(3000);
-```
-
-**That's it.** No `res.send()`, no `res.json()` - just return data.
-
----
-
-## 📖 Core API
-
-### Routes
-
-Vibe supports all standard HTTP methods with a clean, flexible syntax:
-
-```javascript
-// String response
-app.get("/", "Hello World");
-
-// JSON response (just return an object)
-app.get("/json", { message: "Hello" });
-
-// Handler function with request access
-app.get("/users/:id", (req) => ({ id: req.params.id }));
-
-// Multiple route parameters
-app.get("/posts/:postId/comments/:commentId", (req) => ({
-  postId: req.params.postId,
-  commentId: req.params.commentId,
-}));
-
-// With options (interceptors, file uploads)
-app.post("/protected", { intercept: authCheck }, handler);
-
-// All HTTP methods
-app.get("/");
-app.post("/");
-app.put("/");
-app.del("/"); // DELETE
-app.patch("/");
-app.head("/");
-```
-
-### Query Parameters
-
-```javascript
-// GET /search?q=hello&page=2
-app.get("/search", (req) => ({
-  query: req.query.q, // "hello"
-  page: req.query.page, // "2"
-}));
-```
-
-### Request Body
-
-```javascript
-app.post("/users", (req) => {
-  const { name, email } = req.body;
-  return { created: { name, email } };
-});
-```
-
----
-
-## 📝 Logging & Error Handling
-
-Vibe ships with a structured JSON logger (Pino-compatible) and a powerful error interception system. Errors thrown, returned, or sent from any route are automatically caught and routed through a central error handler.
-
-### JSON Structured Logging
-
-Initialize the app with `logger: { lifecycle: true }` or add `prettyPrint: true` for development to get beautiful, human-readable terminal output.
-
-```javascript
-const app = vibe({
-  logger: {
-    lifecycle: true,
-    prettyPrint: process.env.NODE_ENV !== "production",
-  },
-});
-
-// JSON native bindings
-app.log.info({ database: "online" }, "System booting...");
-```
-
-### Contextual Sub-Loggers
-
-Every incoming request dynamically extracts a fast UUID exposed securely on `req.id` natively piping through to `req.log`.
-
-```javascript
-app.get("/users/:id", (req) => {
-  req.log.warn("Database lookup constraint fired");
-  // Production Output -> {"level":40,"time":123,"reqId":"abcd-123", "msg":"..."}
-
-  return { success: true };
-});
-```
-
-### Central Error Abstraction
-
-To route an error into the central handler without halting execution via `throw`, simply return an `Error` object from your handler — Vibe intercepts it automatically:
-
-```javascript
-app.get("/test", (req, res) => {
-  return new Error("Something went wrong");
-});
-```
-
----
-
-## 🔌 Plugin System
-
-Plugins provide encapsulated route groups with optional prefixes:
-
-```javascript
-// Register a plugin with prefix
-await app.register(
-  async (api) => {
-    api.get("/status", { status: "ok" }); // GET /api/status
-    api.get("/health", { healthy: true }); // GET /api/health
-
-    // Plugins can have their own interceptors
-    api.plugin((req, res) => {
-      console.log(`[API] ${req.method} ${req.url}`);
-    });
-  },
-  { prefix: "/api" },
-);
-
-// Nested plugins
-await app.register(
-  async (v1) => {
-    v1.get("/users", { version: 1 }); // GET /api/v1/users
-  },
-  { prefix: "/api/v1" },
-);
-```
-
----
-
-## 🛡️ Interceptors (Middleware)
-
-Interceptors run before your handler. Return `false` to stop execution.
-
-### Single Interceptor
-
-```javascript
-const authCheck = (req, res) => {
-  if (!req.headers.authorization) {
-    res.unauthorized("Token required");
-    return false; // Stop execution
-  }
-  req.user = { id: 1 };
-  return true; // Continue to handler
-};
-
-app.get("/protected", { intercept: authCheck }, (req) => {
-  return { user: req.user };
-});
-```
-
-### Multiple Interceptors
-
-```javascript
-app.get(
-  "/admin",
-  {
-    intercept: [authCheck, adminCheck, rateLimiter],
-  },
-  handler,
-);
-```
-
-### Global Interceptors
-
-```javascript
-// Applies to ALL routes
-app.plugin((req, res) => {
-  console.log(`${req.method} ${req.url}`);
-});
-```
-
----
-
-## 🎨 Decorators
-
-Extend app, request, or response with custom properties:
-
-```javascript
-// App decorator - shared config
-app.decorate("config", { env: "production", version: "1.0.0" });
-
-// Access directly on the app
-app.get("/version", () => ({ version: app.config.version }));
-
-// Same in plugins — decorators are spread directly
-app.register(
-  async (api) => {
-    api.get("/env", () => ({ env: api.config.env }));
-  },
-  { prefix: "/api" },
-);
-
-// Request decorator - add to all requests
-app.decorateRequest("timestamp", () => Date.now());
-
-app.get("/time", (req) => ({ timestamp: req.timestamp }));
-
-// Reply decorator - add methods to response
-app.decorateReply("sendSuccess", function (data) {
-  this.success(data);
-});
-```
-
----
-
-## 📂 File Uploads
-
-Vibe supports multipart file uploads with built-in validation and security.
-
-> **🔒 Security**: File uploads are **disabled by default**. You must explicitly configure `media` options to accept uploads.
-
-### Basic Upload
-
-```javascript
-app.post("/upload", { media: { dest: "uploads" } }, (req) => {
-  return { files: req.files, body: req.body };
-});
-```
-
-### Media Options
-
-```javascript
-app.post(
-  "/upload",
-  {
-    media: {
-      dest: "uploads", // Subfolder destination
-      public: true, // Save in public folder (default: true)
-      maxSize: 5 * 1024 * 1024, // Max file size: 5MB
-      allowedTypes: ["image/jpeg", "image/png", "image/*"], // Wildcards supported
-    },
-  },
-  handler,
-);
-```
-
-### Public vs Private Uploads
-
-**Public uploads** (web-accessible):
-
-```javascript
-app.post(
-  "/upload/avatar",
-  {
-    media: {
-      public: true, // ✅ Files accessible via HTTP
-      dest: "avatars", // Saved to: public/avatars/
-    },
-  },
-  handler,
-);
-
-// Files accessible at: http://yourapp.com/avatars/filename.jpg
-```
-
-**Private uploads** (server-only access):
-
-```javascript
-app.post(
-  "/upload/documents",
-  {
-    media: {
-      public: false, // 🔒 Files NOT web-accessible
-      dest: "documents", // Saved to: private/documents/
-    },
-  },
-  handler,
-);
-
-// Files only accessible via your backend code (e.g., sendAbsoluteFile)
-```
-
-### Uploaded File Object
+**The fastest Node.js web framework with the simplest syntax.**
 
-```javascript
-// req.files contains:
-[
-  {
-    filename: "image-a7x92b.png", // Saved filename (safe)
-    originalName: "photo.png", // Original filename
-    type: "image/png", // MIME type
-    filePath: "/uploads/image-a7x92b.png", // Full path
-    size: 102400, // Size in bytes
-  },
-];
-```
-
-### Streaming Uploads (Large Files)
-
-For large files, use streaming mode to avoid buffering in memory:
-
-```javascript
-import fs from "fs";
-
-app.post("/upload-large", { media: { streaming: true } }, (req) => {
-  req.on("file", (name, stream, info) => {
-    stream.pipe(fs.createWriteStream(`/uploads/${info.filename}`));
-  });
-  return { status: "uploading" };
-});
-```
-
-### Error Handling
-
-- **413 Payload Too Large** - File exceeds `maxSize`
-- **415 Unsupported Media Type** - File type not in `allowedTypes`
+![Performance](https://img.shields.io/badge/performance-11,472_RPS-brightgreen)
+![vs Express](https://img.shields.io/badge/vs_Express-4.7x_faster-blue)
+![vs Fastify](https://img.shields.io/badge/vs_Fastify-faster-orange)
+![License](https://img.shields.io/badge/license-MIT-green)
 
 ---
 
-## 🔥 Scalability
-
-### Cluster Mode
-
-Scale across all CPU cores automatically:
-
-```javascript
-import vibe, { clusterize, isPrimary, getWorkerId } from "vibe-gx";
-
-clusterize(
-  () => {
-    const app = vibe();
-    app.get("/", `Hello from worker ${getWorkerId()}!`);
-    app.listen(3000);
-  },
-  {
-    workers: 4, // Number of workers (default: CPU count)
-    restart: true, // Auto-restart crashed workers
-    restartDelay: 1000, // Delay before restart (ms)
-  },
-);
-```
-
-### LRU Cache
-
-Built-in response caching with ETag support:
-
-```javascript
-import vibe, { LRUCache, cacheMiddleware } from "vibe-gx";
-
-const cache = new LRUCache({
-  max: 1000, // Maximum entries
-  ttl: 60000, // TTL in milliseconds (60 seconds)
-});
-
-app.get("/expensive", { intercept: cacheMiddleware(cache) }, async () => {
-  // This only runs on cache MISS
-  return await expensiveOperation();
-});
-
-// Manual cache operations
-cache.set("key", { data: "value" });
-cache.get("key"); // { value, expires, etag }
-cache.delete("key");
-cache.clear();
-```
-
-### Connection Pool
-
-Generic connection pool for databases:
-
-```javascript
-import vibe, { createPool } from "vibe-gx";
-
-const dbPool = createPool({
-  create: async () => await connectToDatabase(),
-  destroy: async (conn) => await conn.close(),
-  validate: (conn) => conn.isAlive(),
-  min: 2, // Minimum connections
-  max: 10, // Maximum connections
-  acquireTimeout: 30000, // Timeout to acquire (ms)
-  idleTimeout: 60000, // Idle timeout (ms)
-});
-
-app.get("/users", async () => {
-  return await dbPool.use(async (conn) => {
-    return await conn.query("SELECT * FROM users");
-  });
-});
-
-// Pool statistics
-console.log(dbPool.stats);
-// { available: 5, inUse: 2, waiting: 0, max: 10 }
-
-// Cleanup on shutdown
-process.on("SIGTERM", () => dbPool.close());
-```
-
----
-
-## 🔄 Express Middleware Adapter
-
-Use any Express middleware with the adapter:
-
-```javascript
-import vibe, { adapt } from "vibe-gx";
-import helmet from "helmet";
-import compression from "compression";
-
-app.plugin(adapt(helmet()));
-app.plugin(adapt(compression()));
-```
-
-> **Note:** Vibe ships with a native `cors()` helper. No need to adapt the `cors` npm package.
-
----
-
-## 🛡️ Rate Limiting
-
-Built-in sliding window rate limiter — no external dependencies:
-
-```javascript
-import vibe, { rateLimit } from "vibe-gx";
-
-const app = vibe();
-
-// Global limit: 100 requests per minute per IP
-app.plugin(rateLimit({ max: 100, window: 60_000 }));
-
-// Per-route: tight limit on login (brute force protection)
-app.post(
-  "/auth/login",
-  { intercept: rateLimit({ max: 5, window: 60_000 }) },
-  handler,
-);
-```
-
-Sets `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `Retry-After` headers automatically.
-
----
-
-## 🌐 CORS
-
-Built-in CORS with automatic preflight handling — no external dependencies:
-
-```javascript
-import vibe, { cors } from "vibe-gx";
-
-const app = vibe();
-
-app.plugin(
-  cors({
-    origin: "https://myapp.com",
-    credentials: true,
-    maxAge: 86_400, // cache preflight for 24 hours
-  }),
-);
-```
-
-Supports wildcard, single origin, array of origins, and dynamic origin functions.
-
----
-
-## 🔒 Security
-
-Built-in protections:
-
-| Feature                                  | Status |
-| :--------------------------------------- | :----: |
-| **File upload protection** (opt-in only) |   ✅   |
-| Path traversal protection                |   ✅   |
-| File type validation                     |   ✅   |
-| Body size limits (1MB JSON, 10MB files)  |   ✅   |
-| Error sanitization (production mode)     |   ✅   |
-| Safe filename generation                 |   ✅   |
-| Port validation                          |   ✅   |
-
-### File Upload Security
-
-Routes **reject multipart uploads by default** unless `media` is explicitly configured:
-
-```javascript
-// ❌ This will reject file uploads with 400 Bad Request
-app.post("/api/data", (req) => ({ data: req.body }));
-
-// ✅ This accepts file uploads (explicit opt-in)
-app.post(
-  "/upload",
-  {
-    media: {
-      dest: "uploads",
-      maxSize: 5 * 1024 * 1024,
-      allowedTypes: ["image/*", "application/pdf"],
-    },
-  },
-  handler,
-);
-```
-
-This prevents attackers from uploading malicious files to unintended routes.
-
-Set `NODE_ENV=production` for secure error handling (stack traces hidden).
-
----
-
-## ⚡ Schema-Based Serialization
-
-**Optional** performance boost: Pre-compile JSON serializers for 2-3x faster responses.
-
-```javascript
-app.get(
-  "/users/:id",
-  {
-    schema: {
-      response: {
-        type: "object",
-        properties: {
-          id: { type: "number" },
-          name: { type: "string" },
-          email: { type: "string" },
-          active: { type: "boolean" },
-        },
-      },
-    },
-  },
-  async (req) => {
-    const user = await db.getUser(req.params.id);
-    return user; // Uses pre-compiled serializer (2-3x faster than JSON.stringify)
-  },
-);
-```
-
-**Benefits:**
-
-- ✅ 2-3x faster JSON serialization
-- ✅ Zero-loop code generation via `new Function()`
-- ✅ No `Object.keys()` enumeration
-- ✅ Zero runtime type checking
-- ✅ Completely optional (routes work without schemas)
-
----
-
-### Route Options
-
-```javascript
-app.post(
-  "/path",
-  {
-    intercept: authMiddleware, // Middleware function(s)
-    media: {
-      // File upload config
-      dest: "uploads",
-      maxSize: 10 * 1024 * 1024,
-      allowedTypes: ["image/*"],
-    },
-  },
-  handler,
-);
-```
-
-## 🛠️ API Reference
-
-### Application
-
-| Method                                           | Description            |
-| :----------------------------------------------- | :--------------------- |
-| `vibe({ logger?: LoggerConfig })`                | Initialize app         |
-| `app.setErrorHandler(fn)`                        | Override error handler |
-| `app.get/post/put/del/patch/head(path, handler)` | Register route         |
-| `app.listen(port, host?, callback?)`             | Start server           |
-| `app.register(fn, { prefix })`                   | Register plugin        |
-| `app.plugin(fn)`                                 | Global interceptor     |
-| `app.decorate(name, value)`                      | Add app property       |
-| `app.decorateRequest(name, value)`               | Add to all requests    |
-| `app.decorateReply(name, value)`                 | Add to all responses   |
-| `app.setPublicFolder(path)`                      | Set static folder      |
-| `app.logRoutes()`                                | Log all routes         |
-
-### Request (`req`)
-
-| Property      | Description                                              |
-| :------------ | :------------------------------------------------------- |
-| `req.id`      | Lazy UUID — generated only on first access               |
-| `req.log`     | Lazy context-bound logger — created only on first access |
-| `req.params`  | Route parameters (`:id`)                                 |
-| `req.query`   | Query string (`?page=1`)                                 |
-| `req.body`    | Parsed JSON/form body                                    |
-| `req.files`   | Uploaded files (multipart)                               |
-| `req.ip`      | Real client IP — proxy-aware (`x-forwarded-for` first)   |
-| `req.method`  | HTTP method                                              |
-| `req.url`     | Request URL (pathname only, query stripped)              |
-| `req.headers` | Request headers                                          |
-
-### Response (`res`)
-
-| Method                              | Description                  |
-| :---------------------------------- | :--------------------------- |
-| `res.json(data)`                    | Send JSON                    |
-| `res.send(data)`                    | Send any response            |
-| `res.status(code)`                  | Set status (chainable)       |
-| `res.redirect(url, code?)`          | Redirect (302)               |
-| `res.sendFile(path)`                | Send file from public folder |
-| `res.sendAbsoluteFile(path, opts?)` | Send file from any path      |
-| `res.sendHtml(filename)`            | Send HTML file               |
-| `res.success(data?, msg?)`          | 200 OK                       |
-| `res.created(data?, msg?)`          | 201 Created                  |
-| `res.badRequest(msg?, errors?)`     | 400 Bad Request              |
-| `res.unauthorized(msg?)`            | 401 Unauthorized             |
-| `res.forbidden(msg?)`               | 403 Forbidden                |
-| `res.notFound(msg?)`                | 404 Not Found                |
-| `res.conflict(msg?)`                | 409 Conflict                 |
-| `res.serverError(err?)`             | 500 Server Error             |
-
-### Cluster Utilities
-
-| Function               | Description                   |
-| :--------------------- | :---------------------------- |
-| `clusterize(fn, opts)` | Start in cluster mode         |
-| `isPrimary()`          | Check if primary process      |
-| `isWorker()`           | Check if worker process       |
-| `getWorkerId()`        | Get worker ID (0 for primary) |
-| `getWorkerCount()`     | Get number of active workers  |
-
-### Cache Utilities
-
-| Class/Function              | Description               |
-| :-------------------------- | :------------------------ |
-| `new LRUCache(opts)`        | Create LRU cache instance |
-| `cacheMiddleware(cache)`    | Create cache interceptor  |
-| `LRUCache.key(method, url)` | Generate cache key        |
-| `LRUCache.etag(value)`      | Generate ETag             |
-
-### Pool Utilities
-
-| Class/Function     | Description            |
-| :----------------- | :--------------------- |
-| `createPool(opts)` | Create connection pool |
-| `pool.acquire()`   | Acquire resource       |
-| `pool.release(r)`  | Release resource       |
-| `pool.use(fn)`     | Use with auto-release  |
-| `pool.close()`     | Close pool             |
-| `pool.stats`       | Get pool statistics    |
-
-### Rate Limit Utilities
-
-| Function          | Description                          |
-| :---------------- | :----------------------------------- |
-| `rateLimit(opts)` | Create a sliding window rate limiter |
-
-### CORS Utilities
-
-| Function      | Description               |
-| :------------ | :------------------------ |
-| `cors(opts?)` | Create a CORS interceptor |
-
----
-
-## 📊 Benchmarks
-
-Run benchmarks yourself:
-
-```bash
-npm run benchmark
-```
-
-Tested under overload (20,000 requests × 200 concurrent):
-
-```
-Framework    | JSON RPS    | vs Express | vs Fastify
--------------|-------------|------------|------------
-Vibe         | 11,472      | 4.7x ✅    | 1.01x ✅
-Fastify      | 11,334      | 4.7x       | baseline
-Hono         | 7,351       | 3.0x       | 0.6x
-Express      | 2,421       | baseline   | 0.2x
-```
-
----
-
-## 🧪 Testing
-
-```bash
-# Run all tests
-npm test
+## 📖 Complete Documentation
 
-# Run comprehensive tests
-npm run test:all
+Vibe-GX features, API references, tutorials, and guidelines are available on the official documentation website:
 
-# Run benchmarks
-npm run benchmark
-```
+👉 **[genesix.hkai.site/vibegx](https://genesix.hkai.site/vibegx)**
 
 ---
 
 ## 📝 License
 
-Part of the **GeNeSix** brand. Created by **Nnamdi "Joe" Amaga**.
+Part of the **GeNeSix** brand. Created by **NA**.
 
 MIT License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-gx",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "description": "A lightweight, high-performance Node.js web framework.",
   "type": "module",
   "main": "vibe.js",

package/utils/core/response.js

@@ -253,6 +253,48 @@ const vibeResponseMethods = {
     this.end(RESPONSES.serverError);
   },
 
+  /**
+   * Sets a cookie on the response.
+   * Chainable — supports multiple cookies: res.setCookie("a","1").setCookie("b","2")
+   * @param {string} name - Cookie name
+   * @param {string} value - Cookie value (will be URI-encoded)
+   * @param {Object} [options]
+   * @param {number} [options.maxAge] - Max age in seconds
+   * @param {Date} [options.expires] - Expiry date
+   * @param {string} [options.path="/"] - Cookie path
+   * @param {string} [options.domain] - Cookie domain
+   * @param {boolean} [options.secure] - HTTPS only
+   * @param {boolean} [options.httpOnly] - Inaccessible to JS
+   * @param {"Strict"|"Lax"|"None"} [options.sameSite] - SameSite policy
+   * @returns {this}
+   */
+  setCookie(name, value, options = {}) {
+    let cookie = `${name}=${encodeURIComponent(value)}`;
+    if (options.maxAge != null)          cookie += `; Max-Age=${options.maxAge}`;
+    if (options.expires instanceof Date) cookie += `; Expires=${options.expires.toUTCString()}`;
+    cookie += `; Path=${options.path ?? "/"}`;
+    if (options.domain)   cookie += `; Domain=${options.domain}`;
+    if (options.secure)   cookie += "; Secure";
+    if (options.httpOnly) cookie += "; HttpOnly";
+    if (options.sameSite) cookie += `; SameSite=${options.sameSite}`;
+
+    const existing = this.getHeader("Set-Cookie");
+    if (Array.isArray(existing))  this.setHeader("Set-Cookie", [...existing, cookie]);
+    else if (existing)             this.setHeader("Set-Cookie", [existing, cookie]);
+    else                           this.setHeader("Set-Cookie", cookie);
+    return this;
+  },
+
+  /**
+   * Clears a cookie by immediately expiring it.
+   * @param {string} name - Cookie name
+   * @param {Object} [options] - Same options as setCookie (except maxAge/expires)
+   * @returns {this}
+   */
+  clearCookie(name, options = {}) {
+    return this.setCookie(name, "", { ...options, maxAge: 0, expires: new Date(0) });
+  },
+
   /**
    * Redirects the client to another URL.
    * @param {string} url

package/utils/core/server.js

@@ -110,6 +110,25 @@ async function server(options, port, host, callback) {
       configurable: true,
     });
 
+    // Lazy req.cookies — parsed once on first access, zero cost if unused
+    Object.defineProperty(req, "cookies", {
+      get() {
+        if (this._parsedCookies !== undefined) return this._parsedCookies;
+        const header = this.headers["cookie"];
+        if (!header) return (this._parsedCookies = {});
+        const cookies = {};
+        for (const pair of header.split(";")) {
+          const idx = pair.indexOf("=");
+          if (idx < 0) continue;
+          const key = pair.slice(0, idx).trim();
+          const val = pair.slice(idx + 1).trim();
+          if (key) cookies[key] = decodeURIComponent(val);
+        }
+        return (this._parsedCookies = cookies);
+      },
+      configurable: true,
+    });
+
     if (options.loggerConfig && options.loggerConfig.lifecycle) {
       req.startTime = Date.now();
 

package/vibe.d.ts

@@ -162,6 +162,26 @@ export interface RouteOptions {
   schema?: SchemaOptions;
 }
 
+/**
+ * Options for cookie serialization.
+ */
+export interface CookieOptions {
+  /** Max age in seconds. Takes priority over expires. */
+  maxAge?: number;
+  /** Expiry date */
+  expires?: Date;
+  /** Cookie path. Default: "/" */
+  path?: string;
+  /** Cookie domain */
+  domain?: string;
+  /** Send only over HTTPS */
+  secure?: boolean;
+  /** Inaccessible to client-side JavaScript */
+  httpOnly?: boolean;
+  /** SameSite policy */
+  sameSite?: "Strict" | "Lax" | "None";
+}
+
 /**
  * Options for registering a plugin.
  */
@@ -239,6 +259,8 @@ export interface VibeRequest extends IncomingMessage {
   files?: UploadedFile[];
   /** Real client IP — first entry from x-forwarded-for, x-real-ip, or socket address */
   ip?: string;
+  /** Parsed cookies from the Cookie header (lazily evaluated on first access) */
+  cookies: Record<string, string>;
   /** Automatically generated UUID for the request lifecycle */
   id: string;
   /** Context-bound logger automatically stamped with the req.id constraint */
@@ -264,6 +286,21 @@ export interface VibeResponse extends ServerResponse {
   sendHtml: (filename: string) => void;
   redirect: (url: string, code?: number) => void;
 
+  /**
+   * Sets a cookie on the response. Chainable.
+   * @example
+   * res.setCookie("token", "abc", { httpOnly: true, secure: true, maxAge: 3600 });
+   * res.setCookie("a", "1").setCookie("b", "2"); // multiple cookies
+   */
+  setCookie(name: string, value: string, options?: CookieOptions): VibeResponse;
+
+  /**
+   * Clears a cookie by expiring it immediately.
+   * @example
+   * res.clearCookie("token");
+   */
+  clearCookie(name: string, options?: Omit<CookieOptions, "maxAge" | "expires">): VibeResponse;
+
   /** Sends a 200 OK response with a success message */
   success: (data?: any, message?: string) => void;
   /** Sends a 201 Created response */