skyguard-js 1.2.1 → 1.2.3

package/dist/app.d.ts

@@ -109,7 +109,7 @@ declare class App {
      *
      * @param port - TCP port to listen on
      */
-    run(port: number, callback: VoidFunction, hostname?: string): void;
+    run(port?: number, callback?: VoidFunction, hostname?: string): void;
     /**
      * Configures HTTP request logger output format and optional file output.
      *
@@ -136,24 +136,29 @@ declare class App {
      */
     setPrefix(prefix: string): void;
     /** Registers a GET route */
-    get(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    get(path: string, action: RouteHandler): void;
+    get(path: string, middlewares: Middleware[], action: RouteHandler): void;
     /** Registers a POST route */
-    post(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    post(path: string, action: RouteHandler): void;
+    post(path: string, middlewares: Middleware[], action: RouteHandler): void;
     /** Registers a PUT route */
-    put(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    put(path: string, action: RouteHandler): void;
+    put(path: string, middlewares: Middleware[], action: RouteHandler): void;
     /** Registers a PATCH route */
-    patch(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    patch(path: string, action: RouteHandler): void;
+    patch(path: string, middlewares: Middleware[], action: RouteHandler): void;
     /** Registers a DELETE route */
-    delete(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    delete(path: string, action: RouteHandler): void;
+    delete(path: string, middlewares: Middleware[], action: RouteHandler): void;
     /**
      * Registers global middlewares.
      *
      * These are executed for every route.
      *
      * @example
-     * const auth = async (request, next) => {
-     *    console.log(request.header);
-     *    return await next(request);
+     * const auth = async (context, next) => {
+     *    console.log(context.headers);
+     *    return await next(context);
      * }
      *
      * app.middlewares(auth);

package/dist/app.js

@@ -2,15 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createApp = void 0;
 const routing_1 = require("./routing");
+const routeResolveFunc_1 = require("./routing/routeResolveFunc");
 const http_1 = require("./http");
 const validationException_1 = require("./exceptions/validationException");
 const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
 const fileStaticHandler_1 = require("./static/fileStaticHandler");
-const node_http_1 = require("node:http");
 const httpExceptions_1 = require("./exceptions/httpExceptions");
 const engineTemplate_1 = require("./views/engineTemplate");
 const container_1 = require("./container/container");
+const createRuntimeServer_1 = require("./server/createRuntimeServer");
 /**
  * The `App` class acts as the **execution kernel** and **lifecycle orchestrator**
  * of the framework.
@@ -71,15 +72,15 @@ class App {
      */
     async handle(adapter) {
         try {
-            const request = await adapter.getRequest();
-            if (this.staticFileHandler && request.method === http_1.HttpMethods.get) {
-                const staticResponse = await this.staticFileHandler.tryServeFile(request.url);
+            const context = await adapter.getContext();
+            if (this.staticFileHandler && context.req.method === http_1.HttpMethods.get) {
+                const staticResponse = await this.staticFileHandler.tryServeFile(context.req.url);
                 if (staticResponse) {
                     adapter.sendResponse(staticResponse);
                     return;
                 }
             }
-            const response = await this.router.resolve(request);
+            const response = await this.router.resolve(context);
             adapter.sendResponse(response);
         }
         catch (error) {
@@ -147,12 +148,17 @@ class App {
      *
      * @param port - TCP port to listen on
      */
-    run(port, callback, hostname = "127.0.0.1") {
-        (0, node_http_1.createServer)((req, res) => {
-            const adapter = new http_1.NodeHttpAdapter(req, res, this.loggerOptions);
-            void this.handle(adapter);
-        }).listen(port, hostname, () => {
-            callback();
+    run(port = 3000, callback, hostname) {
+        const runtimeServer = (0, createRuntimeServer_1.createRuntimeServer)(this.loggerOptions);
+        runtimeServer.listen(async (adapter) => {
+            await this.handle(adapter);
+        }, {
+            port,
+            hostname,
+            callback: () => {
+                if (callback)
+                    callback();
+            },
         });
     }
     /**
@@ -169,7 +175,7 @@ class App {
      * app.logger("common");
      * app.logger("combined", "./logs/http.log");
      */
-    logger(format = "dev", filePath) {
+    logger(format, filePath) {
         this.loggerOptions = {
             ...this.loggerOptions,
             format,
@@ -192,25 +198,25 @@ class App {
     setPrefix(prefix) {
         this.router.setPrefix(prefix);
     }
-    /** Registers a GET route */
-    get(path, action, middlewares) {
-        this.router.get(path, action, middlewares);
+    get(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
+        this.router.get(path, middlewares, action);
     }
-    /** Registers a POST route */
-    post(path, action, middlewares) {
-        this.router.post(path, action, middlewares);
+    post(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
+        this.router.post(path, middlewares, action);
     }
-    /** Registers a PUT route */
-    put(path, action, middlewares) {
-        this.router.put(path, action, middlewares);
+    put(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
+        this.router.put(path, middlewares, action);
     }
-    /** Registers a PATCH route */
-    patch(path, action, middlewares) {
-        this.router.patch(path, action, middlewares);
+    patch(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
+        this.router.patch(path, middlewares, action);
     }
-    /** Registers a DELETE route */
-    delete(path, action, middlewares) {
-        this.router.delete(path, action, middlewares);
+    delete(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
+        this.router.delete(path, middlewares, action);
     }
     /**
      * Registers global middlewares.
@@ -218,9 +224,9 @@ class App {
      * These are executed for every route.
      *
      * @example
-     * const auth = async (request, next) => {
-     *    console.log(request.header);
-     *    return await next(request);
+     * const auth = async (context, next) => {
+     *    console.log(context.headers);
+     *    return await next(context);
      * }
      *
      * app.middlewares(auth);
@@ -252,6 +258,7 @@ class App {
         }
         if (error instanceof validationException_1.ValidationException) {
             adapter.sendResponse(http_1.Response.json({
+                message: "Validation Error",
                 errors: error.getErrorsByField(),
             }).setStatusCode(400));
             return;

package/dist/http/context.d.ts

@@ -0,0 +1,115 @@
+import { IncomingHttpHeaders } from "node:http";
+import { Request } from "./request";
+import { Response } from "./response";
+import { Readable } from "node:stream";
+import { Session } from "../sessions";
+/**
+ * Unified HTTP context shared by middleware and route handlers.
+ *
+ * This object wraps the current {@link Request} and exposes convenient
+ * read-only accessors (`headers`, `body`, `params`, etc.) plus response
+ * builder helpers (`json`, `text`, `redirect`, `stream`, `download`).
+ *
+ * @example
+ * app.get("/users/{id}", context => {
+ *   return context.json({
+ *     id: context.params.id,
+ *     ip: context.remoteAddress,
+ *   });
+ * });
+ */
+export declare class Context {
+    private readonly _req;
+    /**
+     * @param _req - Current request wrapper instance.
+     */
+    constructor(_req: Request);
+    /**
+     * Returns a new empty response instance.
+     *
+     * Useful when constructing a response manually.
+     */
+    get res(): Response;
+    /**
+     * Returns the underlying request object.
+     */
+    get req(): Request;
+    /**
+     * Returns incoming request headers.
+     */
+    get headers(): IncomingHttpHeaders;
+    /**
+     * Returns the socket peer IP address when available.
+     */
+    get remoteAddress(): string | undefined;
+    /**
+     * Returns parsed request body.
+     */
+    get body(): Record<string, any>;
+    /**
+     * Returns route path parameters.
+     */
+    get params(): Record<string, any>;
+    /**
+     * Returns parsed query string values.
+     */
+    get query(): Record<string, any>;
+    /**
+     * Returns parsed request cookies.
+     */
+    get cookies(): Record<string, string>;
+    /**
+     * Returns request session wrapper.
+     */
+    get session(): Session;
+    /**
+     * Creates a JSON response.
+     *
+     * @param data - Serializable payload.
+     */
+    json(data: unknown): Response;
+    /**
+     * Creates a plain-text response.
+     *
+     * @param data - Text payload.
+     */
+    text(data: string): Response;
+    /**
+     * Creates an HTTP redirect response (302 by default).
+     *
+     * @param url - Redirect target URL.
+     */
+    redirect(url: string): Response;
+    /**
+     * Creates a streaming response.
+     *
+     * @param stream - Readable stream body.
+     * @param headers - Optional extra headers.
+     */
+    stream(stream: Readable, headers?: Record<string, string>): Response;
+    /**
+     * Creates a download response from a filesystem path.
+     *
+     * @param path - File path.
+     * @param filename - Optional download filename.
+     * @param headers - Optional additional headers.
+     */
+    download(path: string, filename?: string, headers?: Record<string, string>): Promise<Response>;
+    /**
+     * Renders a configured template with optional params.
+     *
+     * @param data - Template source or identifier depending on view engine setup.
+     * @param params - Template context values.
+     */
+    render(data: string, params?: Record<string, unknown>): Promise<Response>;
+    /**
+     * Sends a file for inline display.
+     *
+     * @param filePath - File path to send.
+     * @param options - Optional root and headers.
+     */
+    sendFile(filePath: string, options: {
+        headers?: Record<string, string>;
+        root?: string;
+    }): Promise<Response>;
+}

package/dist/http/context.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Context = void 0;
+const response_1 = require("./response");
+/**
+ * Unified HTTP context shared by middleware and route handlers.
+ *
+ * This object wraps the current {@link Request} and exposes convenient
+ * read-only accessors (`headers`, `body`, `params`, etc.) plus response
+ * builder helpers (`json`, `text`, `redirect`, `stream`, `download`).
+ *
+ * @example
+ * app.get("/users/{id}", context => {
+ *   return context.json({
+ *     id: context.params.id,
+ *     ip: context.remoteAddress,
+ *   });
+ * });
+ */
+class Context {
+    _req;
+    /**
+     * @param _req - Current request wrapper instance.
+     */
+    constructor(_req) {
+        this._req = _req;
+        this._req = _req;
+    }
+    /**
+     * Returns a new empty response instance.
+     *
+     * Useful when constructing a response manually.
+     */
+    get res() {
+        return new response_1.Response();
+    }
+    /**
+     * Returns the underlying request object.
+     */
+    get req() {
+        return this._req;
+    }
+    /**
+     * Returns incoming request headers.
+     */
+    get headers() {
+        return this._req.headers;
+    }
+    /**
+     * Returns the socket peer IP address when available.
+     */
+    get remoteAddress() {
+        return this._req.remoteAddress;
+    }
+    /**
+     * Returns parsed request body.
+     */
+    get body() {
+        return this._req.body;
+    }
+    /**
+     * Returns route path parameters.
+     */
+    get params() {
+        return this._req.params;
+    }
+    /**
+     * Returns parsed query string values.
+     */
+    get query() {
+        return this._req.query;
+    }
+    /**
+     * Returns parsed request cookies.
+     */
+    get cookies() {
+        return this._req.cookies;
+    }
+    /**
+     * Returns request session wrapper.
+     */
+    get session() {
+        return this._req.session;
+    }
+    /**
+     * Creates a JSON response.
+     *
+     * @param data - Serializable payload.
+     */
+    json(data) {
+        return response_1.Response.json(data);
+    }
+    /**
+     * Creates a plain-text response.
+     *
+     * @param data - Text payload.
+     */
+    text(data) {
+        return response_1.Response.text(data);
+    }
+    /**
+     * Creates an HTTP redirect response (302 by default).
+     *
+     * @param url - Redirect target URL.
+     */
+    redirect(url) {
+        return response_1.Response.redirect(url);
+    }
+    /**
+     * Creates a streaming response.
+     *
+     * @param stream - Readable stream body.
+     * @param headers - Optional extra headers.
+     */
+    stream(stream, headers) {
+        return response_1.Response.stream(stream, headers);
+    }
+    /**
+     * Creates a download response from a filesystem path.
+     *
+     * @param path - File path.
+     * @param filename - Optional download filename.
+     * @param headers - Optional additional headers.
+     */
+    async download(path, filename, headers) {
+        return await response_1.Response.download(path, filename, headers);
+    }
+    /**
+     * Renders a configured template with optional params.
+     *
+     * @param data - Template source or identifier depending on view engine setup.
+     * @param params - Template context values.
+     */
+    async render(data, params) {
+        return await response_1.Response.render(data, params);
+    }
+    /**
+     * Sends a file for inline display.
+     *
+     * @param filePath - File path to send.
+     * @param options - Optional root and headers.
+     */
+    async sendFile(filePath, options) {
+        return await response_1.Response.sendFile(filePath, options);
+    }
+}
+exports.Context = Context;

package/dist/http/httpAdapter.d.ts

@@ -1,4 +1,4 @@
-import { Request } from "./request";
+import { Context } from "./context";
 import { Response } from "./response";
 /**
  * High-level contract that defines the framework entry port
@@ -9,12 +9,12 @@ import { Response } from "./response";
  */
 export interface HttpAdapter {
     /**
-     * Builds and returns a {@link Request} instance from
+     * Builds and returns a {@link Context} instance from
      * the current connection context.
      *
-     * @returns A promise that resolves to a {@link Request} object
+     * @returns A promise that resolves to a {@link Context} object
      */
-    getRequest(): Promise<Request>;
+    getContext(): Promise<Context>;
     /**
      * Sends a {@link Response} to the client, mapping its status,
      * headers, and body to the underlying runtime protocol.

package/dist/http/index.d.ts

@@ -1,7 +1,9 @@
 export { Response } from "./response";
 export { Request } from "./request";
+export { Context } from "./context";
 export { NodeHttpAdapter } from "./nodeNativeHttp";
+export { WebHttpAdapter } from "./webHttp";
 export { HttpMethods } from "./httpMethods";
-export { HttpAdapter } from "./httpAdapter";
+export type { HttpAdapter } from "./httpAdapter";
 export { Logger } from "./logger";
 export type { LogFormat, LoggerOptions } from "./logger";

package/dist/http/index.js

@@ -1,12 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Logger = exports.HttpMethods = exports.NodeHttpAdapter = exports.Request = exports.Response = void 0;
+exports.Logger = exports.HttpMethods = exports.WebHttpAdapter = exports.NodeHttpAdapter = exports.Context = exports.Request = exports.Response = void 0;
 var response_1 = require("./response");
 Object.defineProperty(exports, "Response", { enumerable: true, get: function () { return response_1.Response; } });
 var request_1 = require("./request");
 Object.defineProperty(exports, "Request", { enumerable: true, get: function () { return request_1.Request; } });
+var context_1 = require("./context");
+Object.defineProperty(exports, "Context", { enumerable: true, get: function () { return context_1.Context; } });
 var nodeNativeHttp_1 = require("./nodeNativeHttp");
 Object.defineProperty(exports, "NodeHttpAdapter", { enumerable: true, get: function () { return nodeNativeHttp_1.NodeHttpAdapter; } });
+var webHttp_1 = require("./webHttp");
+Object.defineProperty(exports, "WebHttpAdapter", { enumerable: true, get: function () { return webHttp_1.WebHttpAdapter; } });
 var httpMethods_1 = require("./httpMethods");
 Object.defineProperty(exports, "HttpMethods", { enumerable: true, get: function () { return httpMethods_1.HttpMethods; } });
 var logger_1 = require("./logger");

package/dist/http/logger.d.ts

@@ -2,8 +2,12 @@ import { IncomingMessage, ServerResponse } from "node:http";
 export type LogFormat = "combined" | "common" | "dev" | "short" | "tiny";
 export type LoggerOptions = {
     format?: LogFormat;
-    stream?: NodeJS.WritableStream;
-    fileStream?: NodeJS.WritableStream;
+    stream?: {
+        write(chunk: string): unknown;
+    };
+    fileStream?: {
+        write(chunk: string): unknown;
+    };
 };
 /**
  * Minimal HTTP request logger.
@@ -45,7 +49,9 @@ export declare class Logger {
      * @param startTime - High-resolution timestamp captured at request start using `process.hrtime.bigint()`.
      */
     log(req: IncomingMessage, res: ServerResponse, startTime: bigint): void;
+    logWeb(req: globalThis.Request, res: globalThis.Response, startTimeMs: number): void;
     private buildLogLine;
+    private buildWebLogLine;
     /**
      * Applies ANSI color codes to an HTTP status code for terminal output.
      *
@@ -60,4 +66,5 @@ export declare class Logger {
      * @returns Colorized status code string suitable for terminal output.
      */
     private colorizeStatus;
+    private getDefaultStream;
 }

package/dist/http/logger.js

@@ -22,7 +22,7 @@ class Logger {
     fileStream;
     format;
     constructor(options = {}) {
-        this.stream = options.stream || process.stdout;
+        this.stream = options.stream || this.getDefaultStream();
         this.fileStream = options.fileStream;
         this.format = options.format || "dev";
     }
@@ -54,6 +54,15 @@ class Logger {
             this.fileStream.write(fileLine + "\n");
         }
     }
+    logWeb(req, res, startTimeMs) {
+        const responseTime = (performance.now() - startTimeMs).toFixed(3);
+        const consoleLine = this.buildWebLogLine(req, res, responseTime, true);
+        const fileLine = this.buildWebLogLine(req, res, responseTime, false);
+        this.stream.write(consoleLine + "\n");
+        if (this.fileStream) {
+            this.fileStream.write(fileLine + "\n");
+        }
+    }
     buildLogLine(req, res, responseTime, useColor) {
         const method = req.method || "-";
         const url = req.url || "-";
@@ -86,6 +95,32 @@ class Logger {
         }
         return `${method} ${url} ${statusCode} ${responseTime} ms - ${contentLength}`;
     }
+    buildWebLogLine(req, res, responseTime, useColor) {
+        const method = req.method || "-";
+        const url = new URL(req.url).pathname || "-";
+        const statusCode = useColor
+            ? this.colorizeStatus(res.status)
+            : String(res.status);
+        const contentLength = res.headers.get("content-length") || "-";
+        const remoteAddr = req.headers.get("x-forwarded-for") || "-";
+        const httpVersion = "1.1";
+        const referrer = req.headers.get("referer") || req.headers.get("referrer") || "-";
+        const userAgent = req.headers.get("user-agent") || "-";
+        const date = new Date().toUTCString();
+        if (this.format === "tiny") {
+            return `${method} ${url} ${statusCode} ${contentLength} - ${responseTime} ms`;
+        }
+        if (this.format === "short") {
+            return `${remoteAddr} ${method} ${url} ${statusCode} ${contentLength} - ${responseTime} ms`;
+        }
+        if (this.format === "common") {
+            return `${remoteAddr} - - [${date}] "${method} ${url} HTTP/${httpVersion}" ${statusCode} ${contentLength}`;
+        }
+        if (this.format === "combined") {
+            return `${remoteAddr} - - [${date}] "${method} ${url} HTTP/${httpVersion}" ${statusCode} ${contentLength} "${referrer}" "${userAgent}"`;
+        }
+        return `${method} ${url} ${statusCode} ${responseTime} ms - ${contentLength}`;
+    }
     /**
      * Applies ANSI color codes to an HTTP status code for terminal output.
      *
@@ -115,5 +150,18 @@ class Logger {
         }
         return statusStr;
     }
+    getDefaultStream() {
+        const maybeProcess = globalThis;
+        if (maybeProcess.process?.stdout?.write) {
+            return maybeProcess.process.stdout;
+        }
+        return {
+            write: (chunk) => {
+                // Use console fallback on runtimes without Node process/stdout.
+                // eslint-disable-next-line no-console
+                console.log(chunk.trimEnd());
+            },
+        };
+    }
 }
 exports.Logger = Logger;

package/dist/http/nodeNativeHttp.d.ts

@@ -1,7 +1,7 @@
 import { IncomingMessage, ServerResponse } from "node:http";
 import type { HttpAdapter } from "./httpAdapter";
 import { Response } from "./response";
-import { Request } from "./request";
+import { Context } from "./context";
 import { type LoggerOptions } from "./logger";
 /**
  * Node.js HTTP adapter.
@@ -26,12 +26,12 @@ export declare class NodeHttpAdapter implements HttpAdapter {
      */
     constructor(req: IncomingMessage, res: ServerResponse, loggerOptions?: LoggerOptions);
     /**
-     * Builds and returns a {@link Request} instance from
+     * Builds and returns a {@link Context} instance from
      * the incoming Node.js request.
      *
-     * @returns A fully constructed {@link Request} instance
+     * @returns A fully constructed {@link Context} instance
      */
-    getRequest(): Promise<Request>;
+    getContext(): Promise<Context>;
     /**
      * Sends a framework {@link Response} to the client by mapping it
      * to the native Node.js {@link ServerResponse}.

package/dist/http/nodeNativeHttp.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeHttpAdapter = void 0;
 const httpMethods_1 = require("./httpMethods");
 const request_1 = require("./request");
+const context_1 = require("./context");
 const contentParserManager_1 = require("../parsers/contentParserManager");
 const logger_1 = require("./logger");
+const node_stream_1 = require("node:stream");
 /**
  * Node.js HTTP adapter.
  *
@@ -34,24 +36,25 @@ class NodeHttpAdapter {
         this.contentParser = new contentParserManager_1.ContentParserManager();
     }
     /**
-     * Builds and returns a {@link Request} instance from
+     * Builds and returns a {@link Context} instance from
      * the incoming Node.js request.
      *
-     * @returns A fully constructed {@link Request} instance
+     * @returns A fully constructed {@link Context} instance
      */
-    async getRequest() {
+    async getContext() {
         const url = new URL(this.req.url || "", `http://${this.req.headers.host}`);
         const request = new request_1.Request(url.pathname);
         request.setMethod(this.req.method || httpMethods_1.HttpMethods.get);
         request.setQuery(Object.fromEntries(url.searchParams.entries()));
         request.setHeaders(this.req.headers);
+        request.setRemoteAddress(this.req.socket?.remoteAddress);
         if (request.method === httpMethods_1.HttpMethods.post ||
             request.method === httpMethods_1.HttpMethods.put ||
             request.method === httpMethods_1.HttpMethods.patch) {
             const parsedData = await this.contentParser.parse(this.req);
             request.setBody(parsedData);
         }
-        return request;
+        return new context_1.Context(request);
     }
     /**
      * Sends a framework {@link Response} to the client by mapping it
@@ -72,6 +75,10 @@ class NodeHttpAdapter {
         if (!response.content)
             this.res.removeHeader("Content-Type");
         this.logger.log(this.req, this.res, this.startTime);
+        if (response.content instanceof node_stream_1.Readable) {
+            response.content.pipe(this.res);
+            return;
+        }
         this.res.end(response.content);
     }
 }