@coloneldev/framework 0.1.0

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@coloneldev/framework",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Http/HttpRequest.ts

@@ -0,0 +1,56 @@
+import type { HttpRequestProps } from "./interfaces/HttpRequestPropsInterface";
+
+export class HttpRequest {
+    readonly method: string;
+    readonly url: URL;
+    readonly headers: Headers;
+    readonly query: URLSearchParams;
+    readonly body: unknown;
+    private _params: Record<string, string> = {};
+
+    constructor (props: HttpRequestProps) {
+        this.method = props.method.toUpperCase();
+        this.url = new URL(props.url);
+        this.headers = props.headers;
+        this.query = props.query;
+        this.body = props.body;
+    }
+
+    json <T = any>(): T | null {
+        return typeof this.body === "object" ? (this.body as T) : null;
+    }
+
+    header (name: string): string | null {
+        return this.headers.get(name);
+    }
+
+    input (key: string): unknown {
+        return this.query.get(key);
+    }
+
+    params (key: string): string | undefined {
+        return this._params[key];
+    }
+
+    path (): string {
+        return new URL (this.url).pathname;
+    }
+
+    all (): Record<string, unknown> {
+        const queryObj = Object.fromEntries(this.query.entries());
+        const bodyObj = typeof this.body === "object" && this.body !== null ?
+            this.body as Record<string, unknown> : {};
+
+        return { ...queryObj, ...bodyObj };
+    }
+
+    isJson (): boolean {
+        return (this.headers.get("content-type") || "").includes("application/json");
+    }
+
+    setParams (params: Record<string, string>) {
+        this._params = params;
+    }
+
+
+}

package/src/Http/HttpResponse.ts

@@ -0,0 +1,11 @@
+export const redirect = (
+        to: string ,
+    status: 301 | 302 | 303 | 307 | 308 = 302): Response => {
+        console.info(`Redirecting to ${to} with status ${status}`)
+        return new Response(null, {
+            status,
+            headers: {
+                "Location": to
+            },
+        });
+    };

package/src/Http/Kernel.ts

@@ -0,0 +1,237 @@
+import { HttpRequest } from './HttpRequest';
+import { Router } from './Router';
+//import { Container } from '../Container/Container';
+import type { HttpMethod } from './types/HttpMethod';
+import { join, resolve } from 'node:path';
+import ejs from 'ejs';
+import type { RouteHandler } from './types/RouteHandler';
+
+type ControllerClass = new () => Record<string, unknown>;
+type ControllerResolver = (name: string) => Promise<ControllerClass>;
+
+interface KernelOptions {
+    controllerResolver?: ControllerResolver;
+    viewsRoot?: string;
+}
+
+type ViewPayload = [
+    template: string,
+    data?: Record<string, any>,
+    layout?: string | null,
+    footerPartial?: string,
+    titlePartial?: string
+];
+
+const isViewPayload = (value: any): value is ViewPayload => {
+    if (!Array.isArray(value)) return false;
+    if (typeof value[0] !== "string") return false;
+    if (value[1] !== undefined && (typeof value[1] !== "object" || value[1] === null)) return false;
+    if (value[2] !== undefined && typeof value[2] !== "string" && value[2] !== null) return false;
+    if (value[3] !== undefined && typeof value[3] !== "string") return false;
+    if (value[4] !== undefined && typeof value[4] !== "string") return false;
+    return true;
+};
+
+const safeViewPath = (view: string) => view.replace(/\.\./g, '').replace(/\/+/g, '/');
+
+export class Kernel {
+    constructor(
+        private router = new Router(),
+        //private container = new Container(),
+        private middleware: Array<Function> = [],
+        private options: KernelOptions = {}
+    ) {}
+
+    private async resolveController(name: string): Promise<ControllerClass> {
+        if (!this.options.controllerResolver) {
+            throw new Error(`No controller resolver configured for handler ${name}`);
+        }
+
+        return this.options.controllerResolver(name);
+    }
+
+    private viewRoot(): string {
+        return this.options.viewsRoot ?? join(resolve(), "resources", "views");
+    }
+
+    /**
+     * Main entrypoint for every HTTP request.
+     */
+    async handle(request: Request): Promise<Response> {
+        const url = new URL(request.url);
+        const httpRequest = new HttpRequest({
+            method: request.method,
+            url: url,
+            headers: request.headers,
+            query: url.searchParams,
+            body: await request.json().catch(() => null)
+        });
+
+        try {
+            // Run middleware pipeline
+            const response = await this.runMiddlewarePipeline(httpRequest, async () => {
+                return this.dispatchToRouter(httpRequest)
+            });
+
+            return await this.normalizeResponse(response);
+        } catch (error) {
+            console.error(error);
+            return this.handleException("Middleware couldn't process the request", 500);
+        }
+    }
+
+    /**
+     * Run middleware in sequence
+     */
+    private async runMiddlewarePipeline(req: HttpRequest, finalHandler: Function) {
+        let index = -1;
+
+        const runner = async (i: number): Promise<Response> => {
+            if (i <= index) throw new Error("next() called multiple times");
+            index = i;
+
+            const middleware = this.middleware[i];
+            if (!middleware) return finalHandler(req);
+
+            return middleware(req, () => runner(i + 1));
+        }
+
+        return runner(0);
+    }
+
+    /** 
+     * Ask the router to resolve the route and call the controller
+     */
+    private async dispatchToRouter(req: HttpRequest) {
+
+        const route = this.router.match(req.method as HttpMethod, req.path());
+
+        if (!route) return new Response("Not Found", { status: 404 });
+        
+        req.setParams(route.params);
+
+        // Allows functional routes
+        if (typeof route.handler === "function") {
+            return route.handler(req);
+        }
+
+        const handler = route.handler as RouteHandler;
+
+        if (typeof handler !== "string") {
+            return new Response("Invalid route handler type", { status: 500 });
+        }
+
+        const parts: string[] = handler.split("@");
+
+        if (parts.length !== 2) {
+            return new Response("Invalid route handler format", { status: 500 });
+        }
+
+        const [controllerName, method] = parts;
+
+        const ImportedControllerClass = await this.resolveController(controllerName!);
+
+        const controllerInstance = new ImportedControllerClass();
+
+        const action = (controllerInstance as any)[method!] as (req: HttpRequest) => Promise<Response> | Response;
+
+        if (typeof action !== "function") return new Response("Action not found", { status: 500 });
+
+        const result = await action.call(controllerInstance, req);
+
+        return result;
+    }
+
+    /**
+     * Convert controller output into a proper Response
+     */
+    private async normalizeResponse(result: any): Promise<Response> {
+        if (result instanceof Response) return result;
+
+        if (isViewPayload(result)) {
+            const [
+                template,
+                data = {},
+                layout = "base/layouts/main",
+                footerPartial = "base/partials/footer",
+                titlePartial = "base/partials/title",
+            ] = result;
+
+            const safeTemplate = safeViewPath(template);
+            
+            // Inject env appName into titleData if available
+            process.env.appName ? data.titleData = `${data.titleData} | ${process.env.appName}`: null; 
+
+            try {
+                const childPath = join(this.viewRoot(), `${safeTemplate}.ejs`);
+                const bodyHtml = await ejs.renderFile(childPath, data || {});
+
+                // Wrap in layout if provided
+                if (layout) {
+                    const returnPath = async (path: string): Promise<string> => 
+                        join(this.viewRoot(), `${safeViewPath(path)}.ejs`);
+                    
+                    const [layoutPath, footerPath, titlePath] = await Promise.all([
+                        returnPath(layout),
+                        returnPath(footerPartial),
+                        returnPath(titlePartial)
+                    ]);
+
+                    console.info(`Rendering layout: ${layoutPath}`);
+
+                    const [bodyHtml, footerHtml, titleHtml] = await Promise.all([
+                        ejs.renderFile(childPath, data || {}),
+                        ejs.renderFile(footerPath, {
+                            footerData:(data as any).footerData 
+                            || ''
+                        }),
+                        ejs.renderFile(titlePath, {
+                            titleData: (data as any).titleData
+                            || ''
+                        })
+                    ]);
+
+                    console.info(`Rendering view: ${childPath}`);
+
+                    const finalHtml = await ejs.renderFile(layoutPath, { 
+                        ...(data ?? {}), 
+                        body: bodyHtml,
+                        footer: footerHtml,
+                        title: titleHtml
+                    });
+
+                    return new Response(finalHtml, {
+                        headers: { "Content-Type": "text/html; charset=utf-8" }
+                    });
+                }
+
+                // No layout, return child as-is
+                return new Response(bodyHtml, {
+                    headers: { "Content-Type": "text/html; charset=utf-8" }
+                });
+            } catch (err) {
+                console.error(err);
+                return this.handleException("Error rendering value", 500)
+            }
+        }
+
+        if (typeof result === "object" && result !== null) {
+            return new Response(JSON.stringify(result), {
+                headers: { "Content-Type": "application/json" }
+            });
+        }
+
+        return new Response(String(result ?? ""), { status: 200 });
+    }
+
+    /** 
+     * Centralized error handling
+     */
+    private handleException(error: any, code: number): Response {
+        console.error(error);
+        const errorString = error ?? "Internal Server Error";
+        return new Response(errorString, { 
+            status: code 
+        });
+    }
+}

package/src/Http/Router.ts

@@ -0,0 +1,63 @@
+import type { RouteDefinitionInterface } from './interfaces/RouteDefinitionInterface';
+import type { RouteMatchInterface } from './interfaces/RouteMatchInterface';
+import type { HttpMethod } from './types/HttpMethod';
+import type { RouteHandler } from './types/RouteHandler';
+
+export class Router {
+    private routes: RouteDefinitionInterface[] = [];
+
+    get(path: string, handler: RouteHandler) {
+        this.add("GET", path, handler);
+    }
+
+    post(path: string, handler: RouteHandler) {
+        this.add("POST", path, handler);
+    }
+
+    put(path: string, handler: RouteHandler) {
+        this.add("PUT", path, handler);
+    }
+
+    delete(path: string, handler: RouteHandler) {
+        this.add("DELETE", path, handler);
+    }
+
+    match(method: HttpMethod, requestPath: string): RouteMatchInterface | null {
+        for (const route of this.routes) {
+            if (route.method !== method) continue;
+
+            const params = this.matchPath(route.path, requestPath);
+            if (params) {
+                return { handler: route.handler, params };
+            }
+        }
+        return null;
+    }
+
+    add(method: HttpMethod, path: string, handler: RouteHandler): void {
+        this.routes.push({ method, path, handler });
+    }
+
+    private matchPath(routePath: string, requestPath: string): Record<string, string> | null {
+        const routeParts: string[] = routePath.split('/').filter(Boolean);
+        const reqParts: string[] = requestPath.split('/').filter(Boolean);
+
+        if (routeParts.length !== reqParts.length) return null;
+
+        const params: Record<string, string> = {};
+
+        if (routeParts.length === reqParts.length) {
+            for (let i = 0; i < routeParts.length; i++) {
+                const r: string = routeParts[i]!;
+                const q: string = reqParts[i]!;
+
+                if (r?.startsWith(":")) {
+                    params[r.slice(1)] = q;
+                } else if (r !== q) {
+                    return null;
+                }
+            }
+        }
+        return params;
+    }
+}

package/src/Http/factories/fromWebRequest.ts

@@ -0,0 +1,23 @@
+import { HttpRequest } from "../HttpRequest";
+
+export async function fromWebRequest(req: Request): Promise<HttpRequest> {
+    const url = new URL (req.url);
+
+    let body: unknown = null;
+    const contentType = req.headers.get("content-type") || "";
+
+    if (contentType.includes("application/json")) {
+        body = await req.json().catch(() => null);
+    } else if (contentType.includes("application/x-www-form-urlencoded")) {
+        const text = await req.text();
+        body = Object.fromEntries(new URLSearchParams(text));
+    }
+
+    return new HttpRequest({
+        method: req.method,
+        url: url,
+        headers: req.headers,
+        query: url.searchParams,
+        body,
+    });
+}

package/src/Http/interfaces/HttpRequestPropsInterface.ts

@@ -0,0 +1,7 @@
+export interface HttpRequestProps {
+    method: string;
+    url: URL;
+    headers: Headers;
+    query: URLSearchParams;
+    body: unknown;
+}

package/src/Http/interfaces/RouteDefinitionInterface.ts

@@ -0,0 +1,10 @@
+import type { HttpMethod } from '../types/HttpMethod';
+import type { RouteHandler } from '../types/RouteHandler';
+
+
+
+export interface RouteDefinitionInterface {
+    method: HttpMethod;
+    path: string;
+    handler: RouteHandler;
+}

package/src/Http/interfaces/RouteMatchInterface.ts

@@ -0,0 +1,6 @@
+import type { RouteHandler } from "../types/RouteHandler";
+
+export interface RouteMatchInterface {
+    handler: RouteHandler;
+    params: Record<string, string>;
+}

package/src/Http/staticFiles.ts

@@ -0,0 +1,61 @@
+/**
+ * Determines if the given pathname matches any of the configured static paths.
+ * @param pathname 
+ * @param staticPaths 
+ * @returns boolean
+ */
+export const isStaticPath =(pathname: string, staticPaths: string[]): boolean => 
+    staticPaths.some((staticPath) => {
+        // Directory-style static paths keep prefix matching (e.g. /assets/...).
+        if (staticPath.endsWith("/")) {
+            return pathname.startsWith(staticPath);
+        }
+
+        // File-style static paths must match exactly (e.g. /favicon.png).
+        return pathname === staticPath;
+    });
+
+/**
+ * Defines the file system path for a given URL pathname, ensuring it maps to the public directory.
+ * @param pathname 
+ * @param join 
+ * @returns string
+ */
+export const toPublicFilePath = (pathname: string, path: {
+    resolve: (...parts: string[]) => string;
+    normalize: (p: string) => string;
+    sep: string;
+}, publicRootInput?: string): string => {
+    const {  resolve, normalize, sep } = path;
+    const publicRoot = publicRootInput ? resolve(publicRootInput) : resolve(process.cwd(), "public");
+
+    const cleaned = normalize(
+        pathname.replace(/^\/(static|assets|public)\//, "")
+    );
+
+    const resolved = resolve(publicRoot, "." + cleaned);
+    const root = publicRoot.endsWith(sep) ? publicRoot : publicRoot + sep;
+
+    if (resolved !== publicRoot && !resolved.startsWith(root)) {
+        throw new Error("Invalid static file path");
+    }
+    return resolved;
+}
+
+/**
+ * Determines the content type for a given file path based on its extension.
+ * @param pathname 
+ * @param exts 
+ * @param extname 
+ * @returns string
+ */
+export const contentTypeFor = (pathname: string, exts: Record<string, string>, extname: Function): string => {
+    const ext = extname(pathname).split('.').pop()?.toLowerCase() || '';
+
+    if (exts[ext]) {
+        console.info(`Matched content type: ${exts[ext]}`);
+        return exts[ext];
+    }
+
+    return "application/octet-stream";
+}

package/src/Http/types/HttpMethod.ts

@@ -0,0 +1 @@
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";

package/src/Http/types/RouteHandler.ts

@@ -0,0 +1,3 @@
+import type { HttpRequest } from '../HttpRequest';
+
+export type RouteHandler = | string | ((request: HttpRequest) => Response | Promise<Response>);

package/src/View/View.ts

@@ -0,0 +1,9 @@
+export default class View {
+    static render(template: string, data: Record<string, any>): Promise<Response> {
+        return new Promise<Response>((resolve) => {
+            resolve(new Response(JSON.stringify({ template, data }), {
+                headers: { "Content-Type": "application/json" }
+            }));
+        });
+    }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./Http/Kernel";
+export * from "./Http/Router";
+export * from "./Http/HttpRequest";
+export * from "./Http/HttpResponse";
+export * from "./Http/staticFiles";