vibe-gx 1.0.2 → 1.0.4

package/README.md

@@ -120,9 +120,40 @@ app.get("/users", async (req, res) => {
 });
 ```
 
-### Streaming Uploads
+### File Uploads
+
+Vibe supports multipart file uploads with built-in validation.
+
+#### Basic File Upload
+
+```javascript
+app.post("/upload", { media: { dest: "uploads" } }, (req, res) => {
+  return { files: req.files, body: req.body };
+});
+```
+
+#### Media Options
 
 ```javascript
+app.post(
+  "/upload",
+  {
+    media: {
+      dest: "uploads", // Folder to save files
+      public: true, // Save inside public folder (default: true)
+      maxSize: 5 * 1024 * 1024, // Max file size: 5MB
+      allowedTypes: ["image/jpeg", "image/png", "application/pdf"],
+    },
+  },
+  handler,
+);
+```
+
+#### Streaming Uploads (Large Files)
+
+```javascript
+import fs from "fs";
+
 app.post("/upload", { media: { streaming: true } }, (req, res) => {
   req.on("file", (name, stream, info) => {
     stream.pipe(fs.createWriteStream(`/uploads/${info.filename}`));
@@ -131,8 +162,85 @@ app.post("/upload", { media: { streaming: true } }, (req, res) => {
 });
 ```
 
+#### Uploaded File Object
+
+```javascript
+// req.files contains:
+[
+  {
+    filename: "image-a7x92b.png", // Saved filename
+    originalName: "photo.png", // Original filename
+    type: "image/png", // MIME type
+    filePath: "/uploads/image.png", // Full path
+    size: 102400, // Size in bytes
+  },
+];
+```
+
 ---
 
+### 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;
+  }
+  req.user = { id: 1 };
+  return true;
+};
+
+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}`);
+});
+```
+
+---
+
+### 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-gx",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A lightweight, regex-based Node.js web framework built for speed and simplicity.",
   "type": "module",
   "main": "vibe.js",

package/vibe.d.ts

@@ -26,25 +26,67 @@ export interface UploadedFile {
 
 /**
  * Configuration for file uploads on a specific route.
+ *
+ * @example
+ * {
+ *   dest: "uploads",
+ *   maxSize: 5 * 1024 * 1024,  // 5MB
+ *   allowedTypes: ["image/jpeg", "image/png"],
+ *   public: true
+ * }
  */
 export interface MediaOptions {
   /** Save file inside the configured public folder. Default: true */
   public?: boolean;
   /** Subfolder destination for uploads (e.g., "uploads/avatars") */
   dest?: string;
-  /** Maximum allowed file size in bytes. Default: 10 MB */
+  /** Maximum allowed file size in bytes. Default: 10 MB (10485760) */
   maxSize?: number;
-  /** Allowed MIME types (e.g., ["image/png", "image/jpeg"]) */
+  /**
+   * Allowed MIME types. Supports wildcards like "image/*"
+   * @example ["image/jpeg", "image/png", "application/pdf"]
+   */
   allowedTypes?: string[];
+  /** Enable streaming mode for large files. Use req.on('file', ...) */
+  streaming?: boolean;
 }
 
 /**
  * Options for registering a route.
+ *
+ * @example
+ * // With interceptor only
+ * { intercept: authMiddleware }
+ *
+ * @example
+ * // With file upload
+ * {
+ *   intercept: authMiddleware,
+ *   media: {
+ *     dest: "uploads",
+ *     maxSize: 10 * 1024 * 1024,
+ *     allowedTypes: ["image/*"]
+ *   }
+ * }
  */
 export interface RouteOptions {
-  /** Middleware(s) to run before the main handler */
+  /**
+   * Middleware function(s) to run before the handler.
+   * Return false to stop execution.
+   * @example
+   * intercept: (req, res) => {
+   *   if (!req.headers.authorization) {
+   *     res.unauthorized();
+   *     return false;
+   *   }
+   *   return true;
+   * }
+   */
   intercept?: Interceptor | Interceptor[];
-  /** Configuration for file uploads */
+  /**
+   * Configuration for file uploads (multipart/form-data).
+   * Files will be available in req.files array.
+   */
   media?: MediaOptions;
 }
 
@@ -89,7 +131,13 @@ export interface VibeResponse extends ServerResponse {
   json: (data: any) => void;
   send: (data: string | number | boolean | object) => void;
   status: (code: number) => VibeResponse;
+  /** Send a file from the public folder */
   sendFile: (filePath: string) => void;
+  /** Send any file by absolute path */
+  sendAbsoluteFile: (
+    absolutePath: string,
+    opts?: { download?: boolean; filename?: string },
+  ) => void;
   sendHtml: (filename: string) => void;
   redirect: (url: string, code?: number) => void;
 
@@ -167,13 +215,45 @@ export const color: Record<ColorName, (text: string) => string>;
 
 /**
  * Route registration function.
- * Supports two signatures:
- * 1. (path, handler)
- * 2. (path, options, handler)
+ *
+ * @example
+ * // Simple handler
+ * app.get("/path", (req, res) => { ... });
+ *
+ * @example
+ * // Static response
+ * app.get("/", "Hello World");
+ *
+ * @example
+ * // With options (interceptor + file upload)
+ * app.post("/upload", {
+ *   intercept: authMiddleware,
+ *   media: {
+ *     dest: "uploads",
+ *     maxSize: 10 * 1024 * 1024,
+ *     allowedTypes: ["image/*"]
+ *   }
+ * }, handler);
  */
 export interface RouteRegistrar {
+  /**
+   * Register a route with a handler or static response.
+   * @param path - Route path (e.g., "/users/:id")
+   * @param handler - Handler function, string, number, or object
+   */
   (path: string, handler: Handler | string | number | object): void;
-  (path: string, options: RouteOptions, handler: Handler): void;
+
+  /**
+   * Register a route with options and handler.
+   * @param path - Route path (e.g., "/upload")
+   * @param options - Route options (intercept, media)
+   * @param handler - Handler function
+   */
+  (
+    path: string,
+    options: RouteOptions,
+    handler: Handler | string | number | object,
+  ): void;
 }
 
 /** Sub-router or prefixed router instance */