skyguard-js 1.2.0 → 1.2.2

package/dist/app.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createApp = exports.App = void 0;
+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");
@@ -35,6 +37,10 @@ class App {
     staticFileHandler = null;
     /** View engine for rendering templates (optional) */
     viewEngine;
+    /** Logger configuration */
+    loggerOptions = {
+        format: "dev",
+    };
     /**
      * Bootstraps and configures the application.
      *
@@ -66,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) {
@@ -142,14 +148,40 @@ class App {
      *
      * @param port - TCP port to listen on
      */
-    run(port, callback, hostname = "127.0.0.1") {
+    run(port = 3000, callback, hostname = "localhost") {
         (0, node_http_1.createServer)((req, res) => {
-            const adapter = new http_1.NodeHttpAdapter(req, res);
+            const adapter = new http_1.NodeHttpAdapter(req, res, this.loggerOptions);
             void this.handle(adapter);
         }).listen(port, hostname, () => {
-            callback();
+            if (callback)
+                callback();
         });
     }
+    /**
+     * Configures HTTP request logger output format and optional file output.
+     *
+     * Supported formats are inspired by morgan:
+     * - "combined"
+     * - "common"
+     * - "dev"
+     * - "short"
+     * - "tiny"
+     *
+     * @example
+     * app.logger("common");
+     * app.logger("combined", "./logs/http.log");
+     */
+    logger(format = "dev", filePath) {
+        this.loggerOptions = {
+            ...this.loggerOptions,
+            format,
+        };
+        if (filePath) {
+            this.loggerOptions.fileStream = (0, node_fs_1.createWriteStream)(filePath, {
+                flags: "a",
+            });
+        }
+    }
     /**
      * Sets a global prefix for all routes.
      *
@@ -162,25 +194,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.
@@ -188,9 +220,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);
@@ -222,6 +254,7 @@ class App {
         }
         if (error instanceof validationException_1.ValidationException) {
             adapter.sendResponse(http_1.Response.json({
+                message: "Validation Error",
                 errors: error.getErrorsByField(),
             }).setStatusCode(400));
             return;
@@ -234,7 +267,6 @@ class App {
         console.error(error);
     }
 }
-exports.App = App;
 const createApp = () => {
     return App.bootstrap();
 };

package/dist/crypto/hasher.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Hasher = void 0;
+const container_1 = require("../container/container");
 const node_crypto_1 = require("node:crypto");
 const node_util_1 = require("node:util");
 /**
@@ -257,4 +258,4 @@ class HasherCrypto {
  * - scrypt is intentionally expensive; concurrency is bounded in batch methods to help prevent
  *   resource exhaustion (especially relevant in containers and small instances).
  */
-exports.Hasher = new HasherCrypto();
+exports.Hasher = container_1.Container.singleton(HasherCrypto);

package/dist/crypto/jwt.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JWT = void 0;
+const container_1 = require("../container/container");
 const baseException_1 = require("../exceptions/baseException");
 const node_crypto_1 = require("node:crypto");
 class JWTGeneratorException extends baseException_1.BaseException {
@@ -308,4 +309,4 @@ class Jwt {
  * - Expiration handling is **strict**: `verify()` expects `exp` to exist and be in the future.
  * - Input parsing is defensive: malformed tokens or unsupported algorithms yield `null` on verify/decode.
  */
-exports.JWT = new Jwt();
+exports.JWT = container_1.Container.singleton(Jwt);

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,6 +1,8 @@
 export { Response } from "./response";
 export { Request } from "./request";
+export { Context } from "./context";
 export { NodeHttpAdapter } from "./nodeNativeHttp";
 export { HttpMethods } from "./httpMethods";
 export { HttpAdapter } from "./httpAdapter";
 export { Logger } from "./logger";
+export type { LogFormat, LoggerOptions } from "./logger";

package/dist/http/index.js

@@ -1,10 +1,12 @@
 "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.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 httpMethods_1 = require("./httpMethods");

package/dist/http/logger.d.ts

@@ -1,4 +1,10 @@
 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;
+};
 /**
  * Minimal HTTP request logger.
  *
@@ -17,7 +23,9 @@ import { IncomingMessage, ServerResponse } from "node:http";
  */
 export declare class Logger {
     private stream;
-    constructor();
+    private fileStream?;
+    private format;
+    constructor(options?: LoggerOptions);
     /**
      * Logs an HTTP request/response pair.
      *
@@ -37,6 +45,7 @@ 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;
+    private buildLogLine;
     /**
      * Applies ANSI color codes to an HTTP status code for terminal output.
      *

package/dist/http/logger.js

@@ -19,8 +19,12 @@ exports.Logger = void 0;
  */
 class Logger {
     stream;
-    constructor() {
-        this.stream = process.stdout;
+    fileStream;
+    format;
+    constructor(options = {}) {
+        this.stream = options.stream || process.stdout;
+        this.fileStream = options.fileStream;
+        this.format = options.format || "dev";
     }
     /**
      * Logs an HTTP request/response pair.
@@ -41,14 +45,46 @@ class Logger {
      * @param startTime - High-resolution timestamp captured at request start using `process.hrtime.bigint()`.
      */
     log(req, res, startTime) {
-        const method = req.method || "-";
-        const url = req.url || "-";
-        const contentLength = res.getHeader("content-length") || "-";
         const diff = process.hrtime.bigint() - startTime;
         const responseTime = (Number(diff) / 1_000_000).toFixed(3);
-        const coloredStatus = this.colorizeStatus(res.statusCode);
-        const logLine = `${method} ${url} ${coloredStatus} ${responseTime} ms - ${contentLength.toString()}`;
-        this.stream.write(logLine + "\n");
+        const consoleLine = this.buildLogLine(req, res, responseTime, true);
+        const fileLine = this.buildLogLine(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 || "-";
+        const statusCode = useColor
+            ? this.colorizeStatus(res.statusCode)
+            : String(res.statusCode);
+        const contentLength = res.getHeader("content-length")?.toString() || "-";
+        const remoteAddr = req.socket.remoteAddress || "-";
+        const httpVersion = req.httpVersion || "1.1";
+        const referrerHeader = req.headers.referer || req.headers.referrer;
+        const referrer = Array.isArray(referrerHeader)
+            ? referrerHeader.join(", ")
+            : referrerHeader || "-";
+        const userAgentHeader = req.headers["user-agent"];
+        const userAgent = Array.isArray(userAgentHeader)
+            ? userAgentHeader.join(", ")
+            : userAgentHeader || "-";
+        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.

package/dist/http/nodeNativeHttp.d.ts

@@ -1,7 +1,8 @@
 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.
  *
@@ -23,14 +24,14 @@ export declare class NodeHttpAdapter implements HttpAdapter {
      * @param req - Native Node.js incoming request
      * @param res - Native Node.js server response
      */
-    constructor(req: IncomingMessage, res: ServerResponse);
+    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}.