skyguard-js 1.2.1 → 1.2.2

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,6 +2,7 @@
 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");
@@ -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,13 @@ 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, this.loggerOptions);
             void this.handle(adapter);
         }).listen(port, hostname, () => {
-            callback();
+            if (callback)
+                callback();
         });
     }
     /**
@@ -192,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.
@@ -218,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);
@@ -252,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;

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

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/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);
     }
 }

package/dist/http/request.d.ts

@@ -29,6 +29,8 @@ export declare class Request {
     private _params;
     /** Session associated with the request */
     private _session;
+    /** Network peer address (adapter-provided). */
+    private _remoteAddress?;
     /**
      * Per-request shared state container.
      *
@@ -52,6 +54,8 @@ export declare class Request {
     setBody(body: Record<string, any>): void;
     get session(): Session;
     setSession(session: Session): void;
+    get remoteAddress(): string | undefined;
+    setRemoteAddress(remoteAddress: string): void;
     /**
      * Returns all request cookies as a key-value object.
      */

package/dist/http/request.js

@@ -29,6 +29,8 @@ class Request {
     _params = Object.create(null);
     /** Session associated with the request */
     _session;
+    /** Network peer address (adapter-provided). */
+    _remoteAddress;
     /**
      * Per-request shared state container.
      *
@@ -80,6 +82,12 @@ class Request {
     setSession(session) {
         this._session = session;
     }
+    get remoteAddress() {
+        return this._remoteAddress;
+    }
+    setRemoteAddress(remoteAddress) {
+        this._remoteAddress = remoteAddress;
+    }
     /**
      * Returns all request cookies as a key-value object.
      */

package/dist/http/response.d.ts

@@ -1,5 +1,6 @@
 import { type CookieOptions } from "../sessions/cookies";
 import { IncomingHttpHeaders } from "node:http";
+import { Readable } from "node:stream";
 /**
  * Represents an outgoing response sent to the client.
  *
@@ -56,8 +57,18 @@ export declare class Response {
      *   .setContent("<h1>Hello</h1>");
      */
     setContentType(value: string): this;
-    get content(): string | Buffer | null;
-    setContent(content: string | Buffer): this;
+    get content(): string | Buffer | Readable | null;
+    setContent(content: string | Buffer | Readable): this;
+    /**
+     * Sets a readable stream as the response body.
+     *
+     * Use this when you need to send large payloads in chunks without
+     * buffering the full content in memory first.
+     *
+     * @param stream - Node.js readable stream
+     * @returns The current {@link Response} instance
+     */
+    stream(stream: Readable): this;
     /**
      * Prepares the response before being sent to the client.
      *
@@ -97,6 +108,14 @@ export declare class Response {
      * });
      */
     static text(data: string): Response;
+    /**
+     * Creates a response whose body is streamed.
+     *
+     * @param stream - Node.js readable stream
+     * @param headers - Optional headers to include in the response
+     * @returns A {@link Response} configured for streaming
+     */
+    static stream(stream: Readable, headers?: Record<string, string>): Response;
     /**
      * Creates an HTTP redirect response.
      *