@wxn0brp/falcon-frame 0.8.1 → 0.8.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 wxn0brP
+Copyright (c) 2026 wxn0brP
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,25 +1,24 @@
 # FalconFrame
 
-> Lightweight modular TypeScript web framework built for speed and clarity.
+A minimal, modular TypeScript web library.
 
-**FalconFrame** is a minimalist web framework inspired by the middleware-first style, with routing similar to Express, but written in pure TypeScript. It supports static files, data validation, and cookie management, all without external dependencies apart from a logger.
+## Features
 
-## ✨ Features
+- Zero-dependency routing engine
+- Middleware chaining
+- Static file serving
+- Request validation via inline schemas
+- OpenAPI document generation
+- Cookie management
+- Debuggable logger
 
-- 🚀 Zero-dependency routing engine
-- 🧱 Middleware chaining
-- 📁 Static file serving
-- 📦 Request validation via inline schemas
-- 🍪 Cookie management
-- 🔍 Debuggable logger
-
-## 📦 Installation
+## Installation
 
 ```bash
-yarn add @wxn0brp/falcon-frame
+bun add @wxn0brp/falcon-frame
 ```
 
-## 🚦 Usage Example
+## Usage Example
 
 ```ts
 import FalconFrame, { validateBody } from "@wxn0brp/falcon-frame";
@@ -83,13 +82,13 @@ app.post(
 // Protected route
 app.get("/dashboard", requireAuth, (req, res) => {
     return {
-        message: `👑 Welcome to the dashboard, ${req.cookies.session}`,
+        message: `Welcome to the dashboard, ${req.cookies.session}`,
     });
 });
 
 app.post("/logout", (req, res) => {
     res.cookie("session", "", { maxAge: 0 });
-    res.json({ message: "👋 Logged out" });
+    res.json({ message: "Logged out" });
 });
 
 // if no route matches
@@ -101,6 +100,6 @@ app.set404((req, res) => {
 app.l(3000);
 ```
 
-## 📜 License
+## License
 
-Published under the MIT license
+Published under the MIT license.

package/dist/compress.js

@@ -1,5 +1,8 @@
 import { createDeflate, createGzip } from "zlib";
 export function compression(req, res) {
+    if (req._compression)
+        return;
+    req._compression = true;
     const encoding = req.headers["accept-encoding"];
     if (!encoding || typeof encoding !== "string" || res.headersSent) {
         return;

package/dist/helpers.d.ts

@@ -1,5 +1,4 @@
-import { Cookies, RouteHandler, StaticServeOptions } from "./types.js";
+import { Cookies } from "./types.js";
 export declare function parseCookies(cookieHeader: string): Cookies;
 export declare function getContentType(filePath: string, utf8?: boolean): string;
-export declare function handleStaticFiles(dirPath: string, opts: StaticServeOptions): RouteHandler;
 export declare const ensureLeadingDot: (str: string) => string;

package/dist/helpers.js

@@ -1,4 +1,3 @@
-import fs from "fs";
 import path from "path";
 export function parseCookies(cookieHeader) {
     const cookies = {};
@@ -33,86 +32,4 @@ export function getContentType(filePath, utf8 = false) {
         contentType += "; charset=utf-8";
     return contentType;
 }
-export function handleStaticFiles(dirPath, opts) {
-    opts = {
-        utf8: true,
-        render: true,
-        renderData: {},
-        etag: true,
-        errorIfDirNotFound: true,
-        ...opts,
-    };
-    if (opts.errorIfDirNotFound && !fs.existsSync(dirPath)) {
-        throw new Error(`Directory ${dirPath} does not exist`);
-    }
-    const serveFile = (req, res, filePath, stats) => {
-        if (opts.render) {
-            const defaultRenderer = res.FF.getVar("view engine");
-            const renderStatement = (defaultRenderer && filePath.endsWith(ensureLeadingDot(defaultRenderer))) ||
-                (!opts.notRenderHtml && filePath.endsWith(".html"));
-            if (renderStatement) {
-                const relativePath = filePath.replace(dirPath + "/", "").replace(".html", "");
-                res.render(filePath, opts.renderData?.[relativePath] || {}, { notUseViews: true });
-                return true;
-            }
-        }
-        if (opts.etag) {
-            const etag = `W/"${stats.size}-${stats.mtime.getTime()}"`;
-            if (req.headers["if-none-match"] === etag) {
-                res.status(304).end();
-                return true;
-            }
-            res.setHeader("ETag", etag);
-        }
-        res.ct(getContentType(filePath, opts.utf8));
-        fs.createReadStream(filePath).pipe(res);
-        return true;
-    };
-    return (req, res, next) => {
-        if (req.method.toLowerCase() !== "get")
-            return next();
-        const apiPath = req.middleware.path;
-        const unsafePath = req.path.replace(apiPath, "");
-        const filePath = path.join(dirPath, path.normalize(unsafePath));
-        const resolvedPath = path.resolve(filePath);
-        const resolvedDir = path.resolve(dirPath);
-        if (!resolvedPath.startsWith(resolvedDir))
-            return next();
-        try {
-            const stats = fs.statSync(filePath);
-            if (stats.isFile()) {
-                return serveFile(req, res, filePath, stats);
-            }
-            if (stats.isDirectory()) {
-                const indexPath = path.join(filePath, "index.html");
-                try {
-                    const indexStats = fs.statSync(indexPath);
-                    if (indexStats.isFile()) {
-                        if (!req.path.endsWith("/")) {
-                            res.redirect(req.path + "/");
-                            return true;
-                        }
-                        return serveFile(req, res, indexPath, indexStats);
-                    }
-                }
-                catch (e) {
-                    /* index.html not found, do nothing */
-                }
-            }
-        }
-        catch (e) {
-            /* file/dir not found, proceed to check for .html */
-        }
-        try {
-            const htmlPath = filePath + ".html";
-            const htmlStats = fs.statSync(htmlPath);
-            if (htmlStats.isFile())
-                return serveFile(req, res, htmlPath, htmlStats);
-        }
-        catch (e) {
-            /* .html file not found, fall through to next() */
-        }
-        next();
-    };
-}
 export const ensureLeadingDot = (str) => (str.startsWith(".") ? str : "." + str);

package/dist/req.d.ts

@@ -1,4 +1,4 @@
 import FalconFrame from "./index.js";
 import { FFResponse } from "./res.js";
 import { FFRequest } from "./types.js";
-export declare function handleRequest(req: FFRequest, res: FFResponse, FF: FalconFrame<any>): void;
+export declare function handleRequest(req: FFRequest, res: FFResponse, FF: FalconFrame<any>, reRoute?: boolean): void;

package/dist/req.js

@@ -1,17 +1,20 @@
+import { randomUUID } from "crypto";
 import { URL } from "url";
 import { parseCookies } from "./helpers.js";
 import { getMiddlewares, matchMiddleware } from "./middleware.js";
 import { FFResponse } from "./res.js";
 import { validate } from "./valid.js";
-export function handleRequest(req, res, FF) {
-    Object.setPrototypeOf(res, FFResponse.prototype);
-    req.FF = FF;
-    res.FF = FF;
-    const originalEnd = res.end;
-    res.end = function (...any) {
-        res._ended = true;
-        return originalEnd.call(res, ...any);
-    };
+export function handleRequest(req, res, FF, reRoute = false) {
+    if (!reRoute) {
+        Object.setPrototypeOf(res, FFResponse.prototype);
+        req.FF = FF;
+        res.FF = FF;
+        const originalEnd = res.end;
+        res.end = function (...any) {
+            res._ended = true;
+            return originalEnd.call(res, ...any);
+        };
+    }
     const { logger } = FF;
     try {
         const [path, params] = (req.url || "").split("?");
@@ -28,6 +31,16 @@ export function handleRequest(req, res, FF) {
     req.cookies = parseCookies(req.headers.cookie || "");
     req.params = {};
     req.valid = (schema) => validate(schema, req.body);
+    req.reRoute = (fn) => {
+        fn(req);
+        handleRequest(req, res, FF, true);
+    };
+    if (FF.opts.xRequestId !== "disable") {
+        if (req.headers["x-request-id"])
+            res.setHeader("x-request-id", req.headers["x-request-id"]);
+        else if (FF.opts.xRequestId === "auto")
+            res.setHeader("x-request-id", randomUUID());
+    }
     logger.info(`Incoming request: ${req.method} ${req.url}`);
     const middlewaresPath = req.path + "/";
     const middlewares = getMiddlewares(FF.middlewares, middlewaresPath.replace(/\/+/g, "/"));
@@ -98,6 +111,11 @@ export function handleRequest(req, res, FF) {
         next();
         return;
     }
+    if (reRoute) {
+        logger.debug("Re-route. Executing middlewares");
+        next();
+        return;
+    }
     req.body = {};
     let bodyParserIndex = 0;
     function nextBodyParser() {

package/dist/res.d.ts

@@ -38,13 +38,14 @@ export declare class FFResponse extends http.ServerResponse {
      */
     status(code: number): this;
     /**
-     * Set status code to 302 and set location header to the provided url.
+     * Set status code to 303 and set location header to the provided url.
      * If end is true, ends the response.
      * @param url The url to redirect to
+     * @param status Status code to set
      * @param end Whether to end the response after setting the headers
      * @returns The response object
      */
-    redirect(url: string, end?: boolean): this;
+    redirect(url: string, status?: number, end?: boolean): this;
     /**
      * Sends a file as the response.
      * Sets the "Content-Type" header based on the provided contentType or the file's extension.

package/dist/res.js

@@ -67,14 +67,15 @@ export class FFResponse extends http.ServerResponse {
         return this;
     }
     /**
-     * Set status code to 302 and set location header to the provided url.
+     * Set status code to 303 and set location header to the provided url.
      * If end is true, ends the response.
      * @param url The url to redirect to
+     * @param status Status code to set
      * @param end Whether to end the response after setting the headers
      * @returns The response object
      */
-    redirect(url, end = true) {
-        this.statusCode = 302;
+    redirect(url, status = 303, end = true) {
+        this.statusCode = status;
         this.setHeader("Location", url);
         if (end)
             this.end();

package/dist/router.js

@@ -1,5 +1,5 @@
-import { handleStaticFiles } from "./helpers.js";
 import { SSEManager } from "./sse.js";
+import { handleStaticFiles } from "./static.js";
 export class Router {
     middlewares = [];
     addRoute(method, path, ...handlers) {

package/dist/sse.d.ts

@@ -1,7 +1,10 @@
 import { FFResponse } from "./res.js";
 import type { FFRequest, RouteHandler } from "./types.js";
 export declare class SSEManager {
-    private clients;
+    _clients: Map<string, {
+        req: FFRequest;
+        res: FFResponse;
+    }>;
     getMiddleware(lastHandler?: RouteHandler): RouteHandler;
     getClients(): Map<string, {
         req: FFRequest;

package/dist/sse.js

@@ -1,37 +1,37 @@
 import { randomUUID } from "crypto";
 export class SSEManager {
-    clients = new Map();
+    _clients = new Map();
     getMiddleware(lastHandler) {
         return (req, res, next) => {
             res.sseInit();
             const id = randomUUID();
-            this.clients.set(id, { req, res });
+            this._clients.set(id, { req, res });
             req.on("close", () => {
-                this.clients.delete(id);
+                this._clients.delete(id);
             });
             req.sseId = id;
             lastHandler?.(req, res, next);
         };
     }
     getClients() {
-        return this.clients;
+        return this._clients;
     }
     sendAll(data) {
-        for (const { res } of this.clients.values()) {
+        for (const { res } of this._clients.values()) {
             res.sseSend(data);
         }
     }
     sendTo(id, data) {
-        const client = this.clients.get(id);
+        const client = this._clients.get(id);
         if (client) {
             client.res.sseSend(data);
         }
     }
     disconnect(id) {
-        const client = this.clients.get(id);
+        const client = this._clients.get(id);
         if (client) {
             client.res.end();
-            this.clients.delete(id);
+            this._clients.delete(id);
         }
     }
 }

package/dist/static.d.ts

@@ -0,0 +1,2 @@
+import { RouteHandler, StaticServeOptions } from "./types.js";
+export declare function handleStaticFiles(dirPath: string, opts: StaticServeOptions): RouteHandler;

package/dist/static.js

@@ -0,0 +1,85 @@
+import fs from "fs";
+import path from "path";
+import { ensureLeadingDot, getContentType } from "./helpers.js";
+export function handleStaticFiles(dirPath, opts) {
+    opts = {
+        utf8: true,
+        render: true,
+        renderData: {},
+        etag: true,
+        errorIfDirNotFound: true,
+        ...opts,
+    };
+    if (opts.errorIfDirNotFound && !fs.existsSync(dirPath)) {
+        throw new Error(`Directory ${dirPath} does not exist`);
+    }
+    const serveFile = (req, res, filePath, stats) => {
+        if (opts.render) {
+            const defaultRenderer = res.FF.getVar("view engine");
+            const renderStatement = (defaultRenderer && filePath.endsWith(ensureLeadingDot(defaultRenderer))) ||
+                (!opts.notRenderHtml && filePath.endsWith(".html"));
+            if (renderStatement) {
+                const relativePath = filePath.replace(dirPath + "/", "").replace(".html", "");
+                res.render(filePath, opts.renderData?.[relativePath] || {}, { notUseViews: true });
+                return true;
+            }
+        }
+        if (opts.etag) {
+            const etag = `W/"${stats.size}-${stats.mtime.getTime()}"`;
+            if (req.headers["if-none-match"] === etag) {
+                res.status(304).end();
+                return true;
+            }
+            res.setHeader("ETag", etag);
+        }
+        res.ct(getContentType(filePath, opts.utf8));
+        fs.createReadStream(filePath).pipe(res);
+        return true;
+    };
+    return (req, res, next) => {
+        if (req.method.toLowerCase() !== "get")
+            return next();
+        const apiPath = req.middleware.path;
+        const unsafePath = req.path.replace(apiPath, "");
+        const filePath = path.join(dirPath, path.normalize(unsafePath));
+        const resolvedPath = path.resolve(filePath);
+        const resolvedDir = path.resolve(dirPath);
+        if (!resolvedPath.startsWith(resolvedDir))
+            return next();
+        try {
+            const stats = fs.statSync(filePath);
+            if (stats.isFile()) {
+                return serveFile(req, res, filePath, stats);
+            }
+            if (stats.isDirectory()) {
+                const indexPath = path.join(filePath, "index.html");
+                try {
+                    const indexStats = fs.statSync(indexPath);
+                    if (indexStats.isFile()) {
+                        if (!req.path.endsWith("/")) {
+                            res.redirect(req.path + "/");
+                            return true;
+                        }
+                        return serveFile(req, res, indexPath, indexStats);
+                    }
+                }
+                catch (e) {
+                    /* index.html not found, do nothing */
+                }
+            }
+        }
+        catch (e) {
+            /* file/dir not found, proceed to check for .html */
+        }
+        try {
+            const htmlPath = filePath + ".html";
+            const htmlStats = fs.statSync(htmlPath);
+            if (htmlStats.isFile())
+                return serveFile(req, res, htmlPath, htmlStats);
+        }
+        catch (e) {
+            /* .html file not found, fall through to next() */
+        }
+        next();
+    };
+}

package/dist/types.d.ts

@@ -31,6 +31,8 @@ export declare class FFRequest extends http.IncomingMessage {
     valid: (schema: ValidationSchema) => ValidationResult;
     middleware: Middleware;
     sseId?: string;
+    reRoute: (fn: (req: FFRequest) => void) => void;
+    _compression?: true;
 }
 export interface Middleware {
     path: string;
@@ -80,6 +82,7 @@ export interface FFOpts {
     bodyLimit?: string;
     disableJsonParser?: boolean;
     disableUrlencodedParser?: boolean;
+    xRequestId?: "auto" | "disable" | "manual";
 }
 export type FFVars = {
     "render data": Record<string, any>;

package/dist/types.js

@@ -9,4 +9,6 @@ export class FFRequest extends http.IncomingMessage {
     valid;
     middleware;
     sseId;
+    reRoute;
+    _compression;
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@wxn0brp/falcon-frame",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "wxn0brP",
   "license": "MIT",
   "type": "module",
-  "description": "Lightweight modular TypeScript web framework",
+  "description": "Lightweight modular TypeScript web library",
   "homepage": "https://github.com/wxn0brP/FalconFrame",
   "repository": {
     "type": "git",
@@ -15,7 +15,6 @@
   "keywords": [
     "http",
     "web",
-    "framework",
     "typescript",
     "modular",
     "lightweight",
@@ -26,10 +25,10 @@
   "devDependencies": {
     "@types/node": "*",
     "tsc-alias": "*",
-    "typescript": "^6"
+    "typescript": "^7"
   },
   "dependencies": {
-    "@wxn0brp/lucerna-log": "^0.2.2"
+    "@wxn0brp/lucerna-log": "^0.2.4"
   },
   "files": [
     "dist"