@wxn0brp/falcon-frame 0.0.1

package/.github/workflows/build.yml

@@ -0,0 +1,20 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - "*"
+
+  workflow_dispatch:
+
+jobs:
+  build:
+    uses: wxn0brP/workflow-dist/.github/workflows/build-ts.yml@main
+    with:
+      scriptsHandling: "remove-all"
+      publishToNpm: true
+    
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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
+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,113 @@
+# FalconFrame
+
+> Lightweight modular TypeScript web framework built for speed and clarity.
+
+**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
+
+- 🚀 Zero-dependency routing engine
+- 🧱 Middleware chaining
+- 📁 Static file serving
+- 📦 Request validation via inline schemas
+- 🍪 Cookie management
+- 🔍 Debuggable logger
+
+---
+
+## 📦 Installation
+
+```bash
+yarn add github:wxn0brP/FalconFrame#dist
+```
+
+## 🚦 Usage Example
+
+```ts
+import FalconFrame from "@wxn0brp/falcon-frame";
+const app = new FalconFrame();
+
+const USERS = {
+    admin: "hunter2",
+};
+
+// Global middleware
+app.use((req, res, next) => {
+    console.log(`[${req.method}] ${req.path}`);
+    next();
+});
+
+// Middleware: auth check
+const requireAuth = (req, res, next) => {
+    if (req.cookies.session === "admin") {
+        return next();
+    }
+    res.status(401).json({ error: "Unauthorized" });
+};
+
+// Static files
+app.static("/", "public");
+
+app.post("/login", (req, res) => {
+    const { valid, validErrors } = req.valid({
+        username: "required|string",
+        password: "required|string",
+    });
+
+    if (!valid) {
+        return res.status(400).json({ status: "error", errors: validErrors });
+    }
+
+    const { username, password } = req.body;
+    if (USERS[username] === password) {
+        res.cookie("session", username, { httpOnly: true });
+        return res.redirect("/dashboard");
+    }
+
+    res.status(401).json({ status: "fail", message: "Invalid credentials" });
+});
+
+app.post("/register", (req, res, next) => {
+    const { valid, validErrors } = req.valid({
+        username: "required|string|min:3|max:20",
+        password: "required|string|min:8",
+    });
+
+    if (!valid) {
+        return res.status(400).json({ status: "error", errors: validErrors });
+    }
+
+    next();
+}, (req, res) => {
+    const { username, password } = req.body;
+    USERS[username] = password;
+    return { status: "success", message: "User registered successfully" };
+});
+
+// Protected route
+app.get("/dashboard", requireAuth, (req, res) => {
+    return {
+        message: `👑 Welcome to the dashboard, ${req.cookies.session}`,
+    });
+});
+
+app.post("/logout", (req, res) => {
+    res.cookie("session", "", { maxAge: 0 });
+    res.json({ message: "👋 Logged out" });
+});
+
+// if no route matches
+app.all("*", (req, res) => {
+    res.status(404).json({ error: "Not found" });
+});
+
+app.listen(3000, () => {
+    console.log("Server running on http://localhost:3000");
+});
+```
+
+## 📜 License
+
+Published under the MIT license

package/dist/helpers.d.ts

@@ -0,0 +1,5 @@
+import { Body, Cookies, RouteHandler } from "./types.js";
+export declare function parseCookies(cookieHeader: string): Cookies;
+export declare function parseBody(contentType: string, body: string): Body;
+export declare function getContentType(filePath: string): string;
+export declare function handleStaticFiles(apiPath: string, dirPath: string): RouteHandler;

package/dist/helpers.js

@@ -0,0 +1,73 @@
+import fs from "fs";
+import path from "path";
+import querystring from "querystring";
+export function parseCookies(cookieHeader) {
+    const cookies = {};
+    cookieHeader.split(";").forEach(cookie => {
+        const [name, ...valueParts] = cookie.split("=");
+        const value = decodeURIComponent(valueParts.join("=").trim());
+        cookies[name.trim()] = value;
+    });
+    return cookies;
+}
+export function parseBody(contentType, body) {
+    if (contentType.includes("application/json")) {
+        try {
+            return JSON.parse(body);
+        }
+        catch {
+            return {};
+        }
+    }
+    else if (contentType.includes("application/x-www-form-urlencoded")) {
+        return querystring.parse(body);
+    }
+    return {};
+}
+export function getContentType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    switch (ext) {
+        case ".html":
+            return "text/html";
+        case ".css":
+            return "text/css";
+        case ".js":
+            return "application/javascript";
+        case ".json":
+            return "application/json";
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".gif":
+            return "image/gif";
+        case ".svg":
+            return "image/svg+xml";
+        default:
+            return "application/octet-stream";
+    }
+}
+export function handleStaticFiles(apiPath, dirPath) {
+    return (req, res, next) => {
+        if (!req.path.startsWith(apiPath))
+            return next();
+        const filePath = path.join(dirPath, req.path.slice(apiPath.length));
+        if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+            res.setHeader("Content-Type", getContentType(filePath));
+            fs.createReadStream(filePath).pipe(res);
+            return true;
+        }
+        if (req.path.endsWith("/")) {
+            if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
+                const indexPath = path.join(filePath, "index.html");
+                if (fs.existsSync(indexPath) && fs.statSync(indexPath).isFile()) {
+                    res.setHeader("Content-Type", getContentType(indexPath));
+                    fs.createReadStream(indexPath).pipe(res);
+                    return true;
+                }
+            }
+        }
+        next();
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { Logger, LoggerOptions } from "@wxn0brp/wts-logger";
+import http from "http";
+import { FFResponse } from "./res.js";
+import { FFRequest, Method, Middleware, RouteHandler } from "./types.js";
+export declare class FalconFrame {
+    middlewares: Middleware[];
+    logger: Logger;
+    constructor(loggerOpts?: LoggerOptions);
+    addRoute(method: Method, path: string, ...handlers: RouteHandler[]): void;
+    use(path?: string | RouteHandler, middleware?: RouteHandler, method?: Method): void;
+    get(path: string, ...handlers: RouteHandler[]): void;
+    post(path: string, ...handlers: RouteHandler[]): void;
+    put(path: string, ...handlers: RouteHandler[]): void;
+    delete(path: string, ...handlers: RouteHandler[]): void;
+    all(path: string, ...handlers: RouteHandler[]): void;
+    static(apiPath: string, dirPath: string): void;
+    listen(port: number, callback?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+    getApp(): (req: any, res: any) => void;
+}
+export default FalconFrame;
+export { FFResponse, FFRequest, RouteHandler, };

package/dist/index.js

@@ -0,0 +1,69 @@
+import { Logger } from "@wxn0brp/wts-logger";
+import http from "http";
+import { handleStaticFiles } from "./helpers.js";
+import { handleRequest } from "./req.js";
+import { FFResponse } from "./res.js";
+import { FFRequest } from "./types.js";
+export class FalconFrame {
+    middlewares = [];
+    logger;
+    constructor(loggerOpts) {
+        this.logger = new Logger({
+            loggerName: "falcon-frame",
+            ...loggerOpts
+        });
+    }
+    addRoute(method, path, ...handlers) {
+        const handler = handlers.pop();
+        handlers.forEach(middleware => this.use(path, middleware));
+        this.middlewares.push({ path, middleware: handler, method });
+    }
+    use(path = "/", middleware, method = "all") {
+        if (typeof path === "function") {
+            middleware = path;
+            path = "/";
+        }
+        this.middlewares.push({ path, middleware, method, use: true });
+    }
+    get(path, ...handlers) {
+        this.addRoute("get", path, ...handlers);
+    }
+    post(path, ...handlers) {
+        this.addRoute("post", path, ...handlers);
+    }
+    put(path, ...handlers) {
+        this.addRoute("put", path, ...handlers);
+    }
+    delete(path, ...handlers) {
+        this.addRoute("delete", path, ...handlers);
+    }
+    all(path, ...handlers) {
+        this.addRoute("all", path, ...handlers);
+    }
+    static(apiPath, dirPath) {
+        this.middlewares.push({
+            path: (apiPath + "/*").replace("//", "/"),
+            method: "get",
+            middleware: handleStaticFiles(apiPath, dirPath)
+        });
+        this.middlewares.push({
+            path: apiPath,
+            method: "get",
+            middleware: handleStaticFiles(apiPath, dirPath)
+        });
+    }
+    listen(port, callback) {
+        const server = http.createServer((req, res) => {
+            handleRequest(req, res, this);
+        });
+        server.listen(port, callback);
+        return server;
+    }
+    getApp() {
+        return (req, res) => {
+            handleRequest(req, res, this);
+        };
+    }
+}
+export default FalconFrame;
+export { FFResponse, FFRequest, };

package/dist/req.d.ts

@@ -0,0 +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): void;

package/dist/req.js

@@ -0,0 +1,109 @@
+import { URL } from "url";
+import { parseBody, parseCookies } from "./helpers.js";
+import { FFResponse } from "./res.js";
+import { validate } from "./valid.js";
+export function handleRequest(req, res, FF) {
+    Object.setPrototypeOf(res, FFResponse.prototype);
+    const originalEnd = res.end;
+    res.end = function (...any) {
+        res._ended = true;
+        return originalEnd.call(res, ...any);
+    };
+    const { logger, middlewares } = FF;
+    const parsedUrl = new URL(req.url || "", "http://localhost");
+    req.path = parsedUrl.pathname || "/";
+    req.query = Object.fromEntries(parsedUrl.searchParams);
+    req.cookies = parseCookies(req.headers.cookie || "");
+    req.params = {};
+    req.valid = (schema) => validate(schema, req.body);
+    logger.info(`Incoming request: ${req.method} ${req.url}`);
+    let body = "";
+    req.on("data", chunk => (body += chunk.toString()));
+    req.on("end", () => {
+        const contentType = req.headers["content-type"] || "";
+        req.body = parseBody(contentType, body);
+        logger.debug(`Request body: ${JSON.stringify(req.body)}`);
+        const matchedTypeMiddlewares = middlewares.filter(middleware => middleware.method === req.method.toLocaleLowerCase() || middleware.method === "all");
+        const matchedMiddlewares = matchMiddleware(req.path, matchedTypeMiddlewares);
+        if (matchedMiddlewares.length === 0) {
+            return res.status(404).end("404: File had second thoughts.");
+        }
+        logger.debug("Matched middlewares: " + matchedMiddlewares.map(middleware => middleware.path).join(", "));
+        let middlewareIndex = 0;
+        const next = async () => {
+            if (middlewareIndex >= matchedMiddlewares.length) {
+                return res.status(404).end("404: File had second thoughts");
+            }
+            const middleware = matchedMiddlewares[middlewareIndex++];
+            logger.debug(`Executing middleware ${middlewareIndex} of ${matchedMiddlewares.length} matched for path [${middleware.path}]`);
+            if (middleware.path.includes(":")) {
+                const middlewareParts = middleware.path.split("/");
+                const reqPathParts = req.path.split("/");
+                req.params = {};
+                for (let i = 0; i < middlewareParts.length; i++) {
+                    if (middlewareParts[i].startsWith(":")) {
+                        const paramName = middlewareParts[i].slice(1);
+                        req.params[paramName] = reqPathParts[i];
+                    }
+                }
+            }
+            const result = await middleware.middleware(req, res, next);
+            if (result && !res._ended) {
+                if (typeof result === "string") {
+                    return res.end(result);
+                }
+                else if (typeof result === "object") {
+                    return res.json(result);
+                }
+            }
+        };
+        next();
+    });
+}
+function matchMiddleware(url, middlewares) {
+    const matchedMiddlewares = [];
+    url = url.replace(/\/$/, "");
+    for (const middleware of middlewares) {
+        const cleanedMiddleware = middleware.path.replace(/\/$/, "");
+        if (middleware.use) {
+            if (url.startsWith(cleanedMiddleware)) {
+                matchedMiddlewares.push(middleware);
+            }
+        }
+        else if (cleanedMiddleware === "*") {
+            matchedMiddlewares.push(middleware);
+        }
+        else if (cleanedMiddleware.endsWith("/*")) {
+            const prefix = cleanedMiddleware.slice(0, -2);
+            if (url.startsWith(prefix)) {
+                matchedMiddlewares.push(middleware);
+            }
+        }
+        else if (cleanedMiddleware.includes(":")) {
+            const middlewareParts = cleanedMiddleware.split("/");
+            const urlParts = url.split("/");
+            if (middlewareParts.length !== urlParts.length) {
+                continue;
+            }
+            let matches = true;
+            for (let i = 0; i < middlewareParts.length; i++) {
+                if (middlewareParts[i].startsWith(":")) {
+                    continue;
+                }
+                else if (middlewareParts[i] !== urlParts[i]) {
+                    matches = false;
+                    break;
+                }
+            }
+            if (matches) {
+                matchedMiddlewares.push(middleware);
+            }
+        }
+        else {
+            if (url === cleanedMiddleware) {
+                matchedMiddlewares.push(middleware);
+            }
+        }
+    }
+    return matchedMiddlewares;
+}

package/dist/res.d.ts

@@ -0,0 +1,10 @@
+import http from "http";
+import { CookieOptions } from "./types.js";
+export declare class FFResponse extends http.ServerResponse {
+    _ended: boolean;
+    json(data: any): void;
+    cookie(name: string, value: string, options?: CookieOptions): this;
+    status(code: number): this;
+    redirect(url: string): this;
+    sendFile(filePath: string): this;
+}

package/dist/res.js

@@ -0,0 +1,39 @@
+import http from "http";
+import { getContentType } from "./helpers.js";
+import { createReadStream } from "fs";
+export class FFResponse extends http.ServerResponse {
+    _ended = false;
+    json(data) {
+        this.setHeader("Content-Type", "application/json");
+        this.end(JSON.stringify(data));
+    }
+    cookie(name, value, options = {}) {
+        let cookie = `${name}=${encodeURIComponent(value)}`;
+        if (options.maxAge)
+            cookie += `; Max-Age=${options.maxAge}`;
+        if (options.path)
+            cookie += `; Path=${options.path}`;
+        if (options.httpOnly)
+            cookie += `; HttpOnly`;
+        if (options.secure)
+            cookie += `; Secure`;
+        if (options.sameSite)
+            cookie += `; SameSite=${options.sameSite}`;
+        this.setHeader("Set-Cookie", cookie);
+        return this;
+    }
+    status(code) {
+        this.statusCode = code;
+        return this;
+    }
+    redirect(url) {
+        this.statusCode = 302;
+        this.setHeader("Location", url);
+        return this;
+    }
+    sendFile(filePath) {
+        this.setHeader("Content-Type", getContentType(filePath));
+        createReadStream(filePath).pipe(this);
+        return this;
+    }
+}

package/dist/test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test.js

@@ -0,0 +1,60 @@
+import FalconFrame from "./index.js";
+const app = new FalconFrame({
+    logLevel: "INFO",
+});
+app.use((req, res, next) => {
+    console.log(`[${req.method}] ${req.path}`);
+    next();
+});
+app.static("/", "public");
+app.get("/hello", (req, res) => {
+    const name = req.query.name || "World";
+    res.json({
+        message: `Hello, ${name}?`,
+        query: req.query,
+    });
+});
+app.get("/hello/*", (req, res) => {
+    res.json({
+        message: `Hello, ${req.params.name}!`,
+        query: req.query,
+    });
+});
+app.get("/greet/:name", (req, res, next) => {
+    console.log(req.params);
+    next();
+}, (req, res) => {
+    res.json({
+        message: `Hello, ${req.params.name}!`,
+    });
+});
+app.post("/submit", (req, res, next) => {
+    const { validErrors, valid } = req.valid({
+        login: "required|string",
+        password: "required|string|min:8",
+    });
+    if (!valid) {
+        res.status(400).json({
+            status: "error",
+            errors: validErrors,
+        });
+    }
+    else
+        next();
+}, async (req, res) => {
+    console.log("run");
+    res.redirect("/hello?name=" + req.body.login);
+    return {
+        status: "success",
+        data: `Hello ${req.body.login}`,
+    };
+});
+app.use((req, res) => {
+    res.status(404);
+    res.json({
+        message: "Not found",
+    });
+});
+app.listen(3000, () => {
+    console.log("Server running on http://localhost:3000");
+});

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+import { FFResponse } from "./res.js";
+import http from "http";
+export type RouteHandler = (req: FFRequest, res: FFResponse, next?: () => void) => void | any;
+export type Method = "get" | "post" | "put" | "delete" | "all";
+export interface Params {
+    [key: string]: string;
+}
+export interface Cookies {
+    [key: string]: string;
+}
+export interface Query {
+    [key: string]: string | string[];
+}
+export interface Body {
+    [key: string]: any;
+}
+export declare class FFRequest extends http.IncomingMessage {
+    path: string;
+    query: Query;
+    params: Params;
+    cookies: Cookies;
+    body: Body;
+    valid: (schema: ValidationSchema) => ValidationResult;
+}
+export interface Middleware {
+    path: string;
+    method: Method;
+    middleware: RouteHandler;
+    use?: true;
+}
+export interface CookieOptions {
+    maxAge?: number;
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+export interface ValidationSchema {
+    [key: string]: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    validErrors: {
+        [key: string]: string[];
+    };
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+import http from "http";
+export class FFRequest extends http.IncomingMessage {
+    path;
+    query;
+    params;
+    cookies;
+    body;
+    valid;
+}

package/dist/valid.d.ts

@@ -0,0 +1,2 @@
+import { ValidationResult, ValidationSchema } from "./types.js";
+export declare function validate(schema: ValidationSchema, data: any): ValidationResult;

package/dist/valid.js

@@ -0,0 +1,56 @@
+export function validate(schema, data) {
+    const errors = {};
+    let isValid = true;
+    for (const key in schema) {
+        const rules = schema[key].split("|");
+        const value = data[key];
+        const fieldErrors = [];
+        for (const rule of rules) {
+            const [ruleName, param] = rule.split(":");
+            switch (ruleName) {
+                case "required":
+                    if (!value && value !== 0) {
+                        fieldErrors.push(`${key} is required`);
+                    }
+                    break;
+                case "string":
+                    if (typeof value !== "string") {
+                        fieldErrors.push(`${key} must be a string`);
+                    }
+                    break;
+                case "number":
+                    if (typeof value !== "number") {
+                        fieldErrors.push(`${key} must be a number`);
+                    }
+                    break;
+                case "min":
+                    if (typeof value === "string" && value.length < parseInt(param)) {
+                        fieldErrors.push(`${key} must be at least ${param} characters long`);
+                    }
+                    if (typeof value === "number" && value < parseInt(param)) {
+                        fieldErrors.push(`${key} must be at least ${param}`);
+                    }
+                    break;
+                case "max":
+                    if (typeof value === "string" && value.length > parseInt(param)) {
+                        fieldErrors.push(`${key} must not exceed ${param} characters`);
+                    }
+                    if (typeof value === "number" && value > parseInt(param)) {
+                        fieldErrors.push(`${key} must not exceed ${param}`);
+                    }
+                    break;
+                case "email":
+                    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+                    if (!emailRegex.test(value)) {
+                        fieldErrors.push(`${key} must be a valid email`);
+                    }
+                    break;
+            }
+        }
+        if (fieldErrors.length > 0) {
+            isValid = false;
+            errors[key] = fieldErrors;
+        }
+    }
+    return { valid: isValid, validErrors: errors };
+}