vibe-gx 1.0.1

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nnamdi "Joe" Amaga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+<div align="center">
+  <img src="./assets/vlogo.png" alt="Vibe Logo" width="180" />
+  <h1>Vibe</h1>
+  <p>
+    <b>A lightweight, high-performance Node.js web framework built for speed and scalability.</b>
+  </p>
+</div>
+
+---
+
+Vibe (part of the **GeNeSix** ecosystem) is a zero-dependency\* web framework with **Radix Trie routing**, **cluster mode**, **response caching**, and a **Fastify-style plugin system**.
+
+> **Dependency Note:** The only dependency is `busboy` for multipart file parsing.
+
+## ⚡ Features
+
+| Feature                  | Description                                   |
+| :----------------------- | :-------------------------------------------- |
+| 🚀 **Radix Trie Router** | O(log n) route matching with hybrid mode      |
+| 🔌 **Plugin System**     | Fastify-style `register()` with encapsulation |
+| 🎨 **Decorators**        | Extend app, request, and response             |
+| ⚡ **Cluster Mode**      | Multi-process scaling                         |
+| 💾 **Response Caching**  | LRU cache with ETag support                   |
+| 🔗 **Connection Pool**   | Generic pool for database connections         |
+| 📂 **Streaming**         | Stream large files without buffering          |
+
+## 🚀 Quick Start
+
+```javascript
+import vibe from "./vibe.js";
+
+const app = vibe();
+
+app.get("/", "Hello Vibe!");
+app.get("/users/:id", (req, res) => ({ userId: req.params.id }));
+
+app.listen(3000);
+```
+
+## 📖 Core API
+
+### Routes
+
+```javascript
+app.get("/path", handler);
+app.post("/path", { intercept: authMiddleware }, handler);
+app.del("/path", handler); // DELETE
+```
+
+### Plugins (Fastify-style)
+
+```javascript
+app.register(
+  async (app) => {
+    app.get("/status", { status: "ok" });
+  },
+  { prefix: "/api" },
+);
+```
+
+### Decorators
+
+```javascript
+app.decorate("config", { env: "prod" });
+app.decorateRequest("user", null);
+app.decorateReply("sendSuccess", function (d) {
+  this.success(d);
+});
+```
+
+---
+
+## 🔥 Scalability Features
+
+### Cluster Mode
+
+```javascript
+import vibe, { clusterize } from "./vibe.js";
+
+clusterize(
+  () => {
+    const app = vibe();
+    app.get("/", "Hello from worker!");
+    app.listen(3000);
+  },
+  { workers: 4, restart: true },
+);
+```
+
+### Response Caching
+
+```javascript
+import vibe, { LRUCache, cacheMiddleware } from "./vibe.js";
+
+const app = vibe();
+const cache = new LRUCache({ max: 1000, ttl: 60000 });
+
+app.get("/data", { intercept: cacheMiddleware(cache) }, () => {
+  return { expensive: "computation" };
+});
+```
+
+### Connection Pool
+
+```javascript
+import vibe, { createPool } from "./vibe.js";
+
+const dbPool = createPool({
+  create: async () => new DBConnection(),
+  destroy: async (conn) => conn.close(),
+  max: 10,
+});
+
+app.decorate("db", dbPool);
+
+app.get("/users", async (req, res) => {
+  return await app.decorators.db.use(async (conn) => {
+    return conn.query("SELECT * FROM users");
+  });
+});
+```
+
+### Streaming Uploads
+
+```javascript
+app.post("/upload", { media: { streaming: true } }, (req, res) => {
+  req.on("file", (name, stream, info) => {
+    stream.pipe(fs.createWriteStream(`/uploads/${info.filename}`));
+  });
+  return { status: "uploading" };
+});
+```
+
+---
+
+## 🛠️ API Reference
+
+### Application
+
+| Method                    | Description       |
+| :------------------------ | :---------------- |
+| `app.listen(port)`        | Start server      |
+| `app.register(fn, opts)`  | Register plugin   |
+| `app.decorate(name, val)` | Add app property  |
+| `app.plugin(fn)`          | Global middleware |
+
+### Request (`req`)
+
+| Property     | Description      |
+| :----------- | :--------------- |
+| `req.params` | Route parameters |
+| `req.query`  | Query strings    |
+| `req.body`   | Parsed body      |
+| `req.files`  | Uploaded files   |
+
+### Response (`res`)
+
+| Method              | Description   |
+| :------------------ | :------------ |
+| `res.json(data)`    | Send JSON     |
+| `res.send(data)`    | Send response |
+| `res.status(code)`  | Set status    |
+| `res.success(data)` | 200 OK        |
+| `res.notFound()`    | 404           |
+
+---
+
+## 📝 License
+
+Part of the **GeNeSix** brand. Created by **Nnamdi "Joe" Amaga**. MIT License.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "vibe-gx",
+  "version": "1.0.1",
+  "description": "A lightweight, regex-based Node.js web framework built for speed and simplicity.",
+  "type": "module",
+  "main": "vibe.js",
+  "types": "vibe.d.ts",
+  "exports": {
+    ".": {
+      "import": "./vibe.js",
+      "types": "./vibe.d.ts"
+    }
+  },
+  "files": [
+    "vibe.js",
+    "vibe.d.ts",
+    "utils/"
+  ],
+  "scripts": {
+    "test": "echo \"No tests yet\"",
+    "start": "node server.js"
+  },
+  "keywords": [
+    "node",
+    "framework",
+    "http",
+    "router",
+    "middleware",
+    "web",
+    "backend",
+    "regex-router",
+    "express-alternative"
+  ],
+  "author": "Nnamdi \"Joe\" Amaga",
+  "license": "MIT",
+  "dependencies": {
+    "busboy": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "express": "^5.2.1",
+    "fastify": "^5.7.4"
+  }
+}

package/utils/core/handler.js

@@ -0,0 +1,219 @@
+import os from "os";
+import { color } from "../helpers/colors.js";
+
+/**
+ * Parses query string from URL into an object.
+ * @param {string} url
+ * @returns {Object}
+ */
+export function extractQuery(url) {
+  const query = {};
+  if (!url.includes("?")) return query;
+  for (const rq of url.split("?")[1].split("&")) {
+    const parts = rq.split("=");
+    if (parts.length === 2) {
+      query[parts[0]] = parts[1];
+    }
+  }
+  return query;
+}
+
+/**
+ * Extracts raw parameters from URL based on route definition.
+ * @param {string} routePath
+ * @param {string} requestPath
+ * @returns {Object}
+ */
+export function extractParams(routePath, requestPath) {
+  const routeSegments = routePath.split("/").filter(Boolean);
+  const requestSegments = requestPath.split("/").filter(Boolean);
+  const params = {};
+
+  routeSegments.forEach((segment, index) => {
+    if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      params[paramName] = requestSegments[index];
+    }
+  });
+
+  return params;
+}
+
+/**
+ * Checks if the request URL matches the route Regex.
+ * @param {RegExp} pathRegex
+ * @param {string} requestPath
+ * @returns {RegExpExecArray | null}
+ */
+export function matchPath(pathRegex, requestPath) {
+  return pathRegex.exec(requestPath);
+}
+
+/**
+ * Converts a route path string (e.g., "/users/:id") into a RegExp.
+ * Captures named groups for parameters.
+ * * @param {string} path - The path to register
+ * @returns {{ pathRegex: RegExp, paramKeys: string[] }}
+ */
+export function PathToRegex(path) {
+  const pathSegments = path.split("/").filter(Boolean);
+  const paramKeys = [];
+
+  // Handle root path specially
+  if (pathSegments.length === 0) {
+    return { pathRegex: /^\/$/, paramKeys: [] };
+  }
+
+  let pathRegex = "^";
+  for (let index = 0; index < pathSegments.length; index++) {
+    const segment = pathSegments[index];
+    if (segment.startsWith(":")) {
+      paramKeys.push(segment.slice(1));
+      pathRegex += `/(?<${segment.slice(1)}>[^/]+)`;
+      continue;
+    }
+
+    if (segment === "*") {
+      pathRegex += "/(.*)";
+      continue;
+    }
+
+    pathRegex += `/${segment}`;
+  }
+
+  pathRegex += "$";
+  pathRegex = new RegExp(pathRegex);
+
+  return { pathRegex, paramKeys };
+}
+
+/**
+ * Validates if data is safe to send via HTTP (string, number, boolean, object).
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isSendAble(value) {
+  return (
+    (value !== null && typeof value === "object") ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  );
+}
+
+/**
+ * Executes a list of interceptor functions (middleware).
+ * Stops execution if response is ended.
+ * * @param {Function | Function[]} intercept - Single function or array of functions
+ * @param {import("../vibe.js").VibeRequest} req
+ * @param {import("../vibe.js").VibeResponse} res
+ * @param {boolean} [isRoute=true] - Context flag for error messages
+ * @returns {Promise<boolean>} - Returns false if response ended, true otherwise
+ */
+export async function runIntercept(intercept, req, res, isRoute = true) {
+  if (!intercept || (Array.isArray(intercept) && intercept.length === 0))
+    return true;
+
+  const funcs = Array.isArray(intercept) ? intercept : [intercept];
+
+  for (const func of funcs) {
+    if (typeof func !== "function") {
+      throw new Error(
+        `All ${isRoute ? "Route" : "Global"} intercepts must be functions`,
+      );
+    }
+
+    await func(req, res);
+
+    if (res.writableEnded) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Centralized error handler for routes.
+ * In production, only logs error message (not full stack).
+ * @param {Error} error
+ * @param {import("../../vibe.js").VibeRequest} req
+ * @param {import("../../vibe.js").VibeResponse} res
+ */
+export function handleError(error, req, res) {
+  const isDev = process.env.NODE_ENV !== "production";
+
+  // Log error (full stack in dev, message only in production)
+  if (isDev) {
+    console.error("[VIBE ERROR]:", error);
+  } else {
+    console.error("[VIBE ERROR]:", error.message || "Unknown error");
+  }
+
+  if (!res.headersSent) {
+    res.writeHead(500, { "content-type": "application/json" });
+
+    // Only expose error details in development
+    const responseBody = isDev
+      ? { error: "Internal Server Error", message: error.message }
+      : { error: "Internal Server Error" };
+
+    res.end(JSON.stringify(responseBody));
+  }
+}
+
+/**
+ * Finds the local network IP address (IPv4)
+ * @param {string} host
+ * @param {number} port
+ * @returns {void}
+ */
+export function getNetworkIP(host, port) {
+  const interfaces = os.networkInterfaces();
+  const addresses = [];
+
+  for (const name of Object.keys(interfaces)) {
+    addresses.push(
+      ...interfaces[name]
+        .map((iface) =>
+          iface.address === "::1"
+            ? { address: "[::1]", fam: iface.family }
+            : { address: iface.address, fam: iface.family },
+        )
+        .filter((addr) => !addr.address.startsWith("fe80")),
+    );
+  }
+
+  for (const addrs of addresses) {
+    if (host === "0.0.0.0") {
+      // => listens on all ipv4 hosts
+      if (addrs.fam === "IPv4")
+        log(`Server listening at - \x1b[4mhttp://${addrs.address}:${port}`);
+    }
+
+    if (host === "::") {
+      // => listens on all ipv6/ipv4 hosts
+      log(`Server listening at - \x1b[4mhttp://${addrs.address}:${port}`);
+    }
+
+    if (addrs.address === host) {
+      log(`Server listening at - \x1b[4mhttp://${addrs.address}:${port}`);
+    }
+  }
+}
+
+/**
+ * Logs a message with a prefix.
+ * @param {string} message
+ */
+export function log(message) {
+  process.stdout.write(
+    `${color.green("[VIBE LOG]:")} ${color.bright(message)}\n`,
+  );
+}
+
+/**
+ * Logs an error with a prefix.
+ * @param {string} message
+ */
+export function error(message) {
+  process.stderr.write(`${color.red(`[VIBE ERROR]: ${message}`)}\n`);
+}

package/utils/core/parser.js

@@ -0,0 +1,242 @@
+import busboy from "busboy";
+import fs from "fs";
+import crypto from "crypto";
+import path from "path";
+import { EventEmitter } from "events";
+
+/**
+ * Default streaming threshold (1MB)
+ */
+const DEFAULT_STREAM_THRESHOLD = 1024 * 1024;
+
+/**
+ * Parses incoming request bodies.
+ * Supports JSON and multipart/form-data (file uploads).
+ *
+ * Streaming mode: For large files, emits events instead of buffering:
+ * - req.emit("file", fieldName, stream, info) for each file
+ *
+ * @param {import("../vibe.js").VibeRequest} req - Incoming request
+ * @param {import("../vibe.js").VibeResponse} res - Response object
+ * @param {import("../vibe.js").MediaOptions} [media={}] - Route-specific file config
+ * @param {import("../vibe.js").VibeConfig} [options={}] - Global framework config
+ * @returns {Promise<void>} Resolves when parsing completes
+ */
+export default function bodyParser(req, res, media = {}, options = {}) {
+  return new Promise((resolve, reject) => {
+    const contentType = req.headers["content-type"];
+    if (!contentType) return resolve();
+
+    req.body ||= {};
+    req.files ||= [];
+
+    /* ---------- Multipart / File Uploads ---------- */
+    if (contentType.includes("multipart/form-data")) {
+      parseMultipart(req, res, media, options, resolve, reject);
+      return;
+    }
+
+    /* ---------- JSON ---------- */
+    if (contentType.includes("application/json")) {
+      parseJson(req, res, media, options, resolve, reject);
+      return;
+    }
+
+    // Other content-types are ignored
+    resolve();
+  });
+}
+
+/**
+ * Parse multipart/form-data with optional streaming support
+ */
+function parseMultipart(req, res, media, options, resolve, reject) {
+  let bb;
+  let fileError = null;
+  const streaming = media.streaming === true;
+
+  try {
+    bb = busboy({
+      headers: req.headers,
+      limits: {
+        fileSize: media.maxSize || 10 * 1024 * 1024,
+      },
+    });
+  } catch (err) {
+    console.error("Busboy init failed:", err);
+    return resolve();
+  }
+
+  bb.on("field", (name, value) => {
+    req.body[name] = value;
+  });
+
+  bb.on("file", (name, file, info) => {
+    const { filename, mimeType } = info;
+    if (!filename) return file.resume();
+
+    // File type validation
+    if (media.allowedTypes && Array.isArray(media.allowedTypes)) {
+      if (!media.allowedTypes.includes(mimeType)) {
+        fileError = new Error(
+          `File type '${mimeType}' not allowed. Allowed: ${media.allowedTypes.join(", ")}`,
+        );
+        return file.resume();
+      }
+    }
+
+    // STREAMING MODE: Emit file event, let handler deal with it
+    if (streaming) {
+      req.emit("file", name, file, { filename, mimeType });
+      return;
+    }
+
+    // BUFFERING MODE: Write to disk
+    const parent = media.public ? options.publicFolder || "" : "";
+    const dest = path.resolve(
+      path.join(parent, media.dest || (media.public ? "uploads" : "private")),
+    );
+
+    // Prevent path traversal
+    if (
+      media.public &&
+      !dest.startsWith(path.resolve(options.publicFolder || ""))
+    ) {
+      console.warn("Attempted upload outside public folder, skipping");
+      return file.resume();
+    }
+
+    try {
+      if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+    } catch (err) {
+      console.error("Failed to create upload folder:", err);
+      return file.resume();
+    }
+
+    const ext =
+      path.extname(filename) ||
+      (mimeType?.includes("/") ? "." + mimeType.split("/")[1] : "");
+
+    const safeName = `${path.basename(filename, ext)}-${crypto
+      .randomBytes(3)
+      .toString("hex")}${ext}`;
+    const filePath = path.join(dest, safeName);
+
+    const writeStream = fs.createWriteStream(filePath);
+    let size = 0;
+    let truncated = false;
+
+    file.on("data", (d) => (size += d.length));
+
+    // Handle file size limit exceeded
+    file.on("limit", () => {
+      truncated = true;
+      fileError = new Error(
+        `File '${filename}' exceeds max size of ${media.maxSize || 10 * 1024 * 1024} bytes`,
+      );
+      file.unpipe(writeStream);
+      writeStream.end();
+      // Clean up partial file
+      fs.unlink(filePath, () => {});
+    });
+
+    file.on("error", (err) => {
+      console.error("File stream error:", err);
+      writeStream.end();
+    });
+
+    writeStream.on("error", (err) => {
+      console.error("Write stream error:", err);
+      file.resume();
+    });
+
+    writeStream.on("finish", () => {
+      if (!truncated) {
+        req.files.push({
+          filename: safeName,
+          originalName: filename,
+          type: mimeType,
+          filePath,
+          size,
+        });
+      }
+    });
+
+    file.pipe(writeStream);
+  });
+
+  bb.on("error", (err) => {
+    console.error("Busboy error:", err);
+    req.unpipe(bb);
+    reject(err);
+  });
+
+  bb.on("finish", () => {
+    if (fileError) {
+      reject(fileError);
+    } else {
+      resolve();
+    }
+  });
+
+  req.pipe(bb);
+}
+
+/**
+ * Parse JSON body with streaming support for large payloads
+ */
+function parseJson(req, res, media, options, resolve, reject) {
+  const limit = options.maxJsonSize || 1e6;
+  const streamThreshold = media.streamThreshold || DEFAULT_STREAM_THRESHOLD;
+  const contentLength = parseInt(req.headers["content-length"] || "0", 10);
+
+  // STREAMING MODE: For very large JSON, let handler process incrementally
+  if (media.streaming && contentLength > streamThreshold) {
+    req.body = null; // Signal that body should be consumed via stream
+    req.emit("jsonStream", req);
+    resolve();
+    return;
+  }
+
+  // BUFFERING MODE: Collect and parse
+  let body = "";
+
+  req.on("data", (chunk) => {
+    body += chunk;
+    if (body.length > limit) {
+      console.warn("JSON payload too large, destroying connection");
+      req.destroy();
+    }
+  });
+
+  req.on("end", () => {
+    try {
+      req.body = JSON.parse(body || "{}");
+    } catch {
+      req.body = {};
+    }
+    resolve();
+  });
+}
+
+/**
+ * Stream JSON parser helper
+ * Use with streaming mode to parse large JSON incrementally
+ *
+ * @param {NodeJS.ReadableStream} stream
+ * @returns {Promise<any>}
+ */
+export async function parseJsonStream(stream) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    stream.on("data", (chunk) => (body += chunk));
+    stream.on("end", () => {
+      try {
+        resolve(JSON.parse(body));
+      } catch (err) {
+        reject(err);
+      }
+    });
+    stream.on("error", reject);
+  });
+}