skyguard-js 1.1.0 → 1.1.2

package/README.md

@@ -35,6 +35,11 @@ At its current stage, the framework focuses on **routing**, **internal architect
 
 ---
 
+> [!NOTE]
+> It is recommended to develop with `TypeScript` for a more secure and efficient development process; the framework already has native support for `TypeScript` and includes the necessary types.
+
+---
+
 ## 📦 Installation
 
 ```bash
@@ -160,17 +165,17 @@ app.staticFiles(join(__dirname, "..", "static"));
 
 ## ⛔ Data Validation
 
-Skyguard.js provides a **declarative validation system** using schemas.
+To validate data in the body of client requests, the framework provides the creation of validation schemas, which are created as follows:
 
 ```ts
-import { validator } from "skyguard-js/validation";
-
-const userSchema = validator.schema({
-  name: validator.string({ maxLength: 60 }),
-  email: validator.email().required(),
-  age: validator.number({ min: 18 }),
-  active: validator.boolean().required(),
-  birthdate: validator.date({ max: new Date() }),
+import { v, schema } from "skyguard-js";
+
+const userSchema = schema({
+  name: v.string({ maxLength: 60 }),
+  email: v.email(),
+  age: v.number({ min: 18 }),
+  active: v.boolean().default(false),
+  birthdate: v.date({ max: new Date() }),
 });
 
 app.post("/users", (request: Request) => {
@@ -183,6 +188,8 @@ app.post("/users", (request: Request) => {
 });
 ```
 
+By default each property you define in the schema is required, to define it optional you use the `.optional()` or `.default(value)` function
+
 Validation is:
 
 - Fail-fast per field
@@ -331,43 +338,46 @@ app.post(
 
 ## 📄 Views & Template Engine
 
-To render HTML views, use the `render` helper.
+To render views, you must first set up the template engine using the `engineTemplates` method of the `app`, set the view path with the `views` method of the `app`, and then you can use the `render` method within your handlers to render the views with the data you want to pass.
 
 ```ts
-import { render } from "skyguard-js/helpers";
+import { engine } from "express-handlebars";
+import ejs from "ejs";
+import { join } from "node:path";
+
+app.views(__dirname, "views");
+
+// Config for Express Handlebars
+app.engineTemplates(
+  "hbs",
+  engine({
+    extname: "hbs",
+    layoutsDir: join(__dirname, "views"),
+    defaultLayout: "main",
+  }),
+);
+
+// Config for EJS
+app.engineTemplates("ejs", (templatePath, data) => {
+  return ejs.renderFile(templatePath, data);
+});
 
 app.get("/home", () => {
-  return render(
-    "home",
-    {
-      title: "Products",
-      products: [
-        { name: "Laptop", price: 999.99 },
-        { name: "Mouse", price: 29.99 },
-      ],
-      user: { name: "John", role: "admin" },
-    },
-    "main",
-  );
+  return render("index", {
+    title: "Home Page",
+    message: "Welcome to the home page!",
+  });
 });
 ```
 
-### Supported features
-
-- Variable interpolation (`{{ variable }}`)
-- Conditionals (`{{#if}}`)
-- Loops (`{{#each}}`)
-- Layouts
-- Partials
-- Built-in helpers (`upper`, `lower`, `date`)
-- Custom helpers
+Currently, it works with third-party template engines such as **Express Handlebars**, **Pug**, and **EJS**, but the idea is to implement its own template engine in the future.
 
 ---
 
 ## 🔮 Roadmap (Tentative)
 
 - Middleware system (✅)
-- Template engine (✅)
+- Template engines supported (✅)
 - Request / Response abstraction (✅)
 - Data validation (✅)
 - Error handling improvements (✅)

package/dist/app.d.ts

@@ -1,6 +1,6 @@
 import { RouterGroup } from "./routing";
-import { type View } from "./views";
 import type { Middleware, RouteHandler } from "./types";
+import { type TemplateEngineFunction } from "./views/engineTemplate";
 /**
  * The `App` class acts as the **execution kernel** and **lifecycle orchestrator**
  * of the framework.
@@ -22,16 +22,14 @@ import type { Middleware, RouteHandler } from "./types";
 export declare class App {
     /** Main routing system */
     private router;
-    /**
-     * View engine used to render templates.
-     *
-     * Typically consumed inside controllers to generate HTML responses.
-     */
-    view: View;
     /** Static file handler (optional) */
     private staticFileHandler;
+    /** Logger instance for request logging */
     private logger;
+    /** Timestamp marking the start of request processing (for logging) */
     private startTime;
+    /** View engine for rendering templates (optional) */
+    private viewEngine;
     /**
      * Bootstraps and configures the application.
      *
@@ -67,6 +65,42 @@ export declare class App {
      * // /public/css/style.css → /css/style.css
      */
     staticFiles(publicPath: string): void;
+    /**
+     * Configures the views directory for template rendering.
+     *
+     * @param pathSegments Path segments leading to the views directory
+     * @example
+     * app.views(__dirname, "views");
+     */
+    views(...pathSegments: string[]): void;
+    /**
+     * Configures the template engine for rendering views.
+     *
+     * @param extension - File extension associated with the template engine (e.g. "hbs", "ejs")
+     * @param engine - Function that renders a template given its path and data
+     *
+     * @example
+     * app.engineTemplates("hbs", (templatePath, data) => {
+     *   const content = fs.readFileSync(templatePath, "utf-8");
+     *   return content.replace(/{{\s*(\w+)\s*}}/g, (_, key) => {
+     *     return data[key] ?? "";
+     *   });
+     * });
+     *
+     * // With express-handlebars
+     * app.engineTemplates(
+     *   "hbs",
+     *   engine({
+     *     extname: "hbs",
+     *     layoutsDir: join(__dirname, "views"),
+     *     defaultLayout: "main",
+     *   }),
+     * );
+     *
+     * The `extension` parameter allows the framework to automatically select the correct
+     * template engine based on the file extension of the view being rendered.
+     */
+    engineTemplates(extension: string, engine: TemplateEngineFunction): void;
     /**
      * Starts the HTTP server on the given port.
      *

package/dist/app.js

@@ -4,12 +4,12 @@ exports.createApp = exports.App = void 0;
 const routing_1 = require("./routing");
 const http_1 = require("./http");
 const validationException_1 = require("./exceptions/validationException");
-const views_1 = require("./views");
 const node_path_1 = require("node:path");
-const app_1 = require("./helpers/app");
 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");
 /**
  * The `App` class acts as the **execution kernel** and **lifecycle orchestrator**
  * of the framework.
@@ -31,16 +31,14 @@ const httpExceptions_1 = require("./exceptions/httpExceptions");
 class App {
     /** Main routing system */
     router;
-    /**
-     * View engine used to render templates.
-     *
-     * Typically consumed inside controllers to generate HTML responses.
-     */
-    view;
     /** Static file handler (optional) */
     staticFileHandler = null;
+    /** Logger instance for request logging */
     logger;
+    /** Timestamp marking the start of request processing (for logging) */
     startTime;
+    /** View engine for rendering templates (optional) */
+    viewEngine;
     /**
      * Bootstraps and configures the application.
      *
@@ -51,10 +49,10 @@ class App {
      * @returns The singleton `App` instance
      */
     static bootstrap() {
-        const app = (0, app_1.singleton)(App);
+        const app = container_1.Container.singleton(App);
         app.router = new routing_1.Router();
-        app.view = new views_1.RaptorEngine((0, node_path_1.join)(__dirname, "..", "views"));
         app.logger = new http_1.Logger();
+        app.viewEngine = container_1.Container.singleton(engineTemplate_1.ViewEngine);
         return app;
     }
     /**
@@ -100,6 +98,46 @@ class App {
     staticFiles(publicPath) {
         this.staticFileHandler = new fileStaticHandler_1.StaticFileHandler(publicPath);
     }
+    /**
+     * Configures the views directory for template rendering.
+     *
+     * @param pathSegments Path segments leading to the views directory
+     * @example
+     * app.views(__dirname, "views");
+     */
+    views(...pathSegments) {
+        this.viewEngine.setViewsPath((0, node_path_1.join)(...pathSegments));
+    }
+    /**
+     * Configures the template engine for rendering views.
+     *
+     * @param extension - File extension associated with the template engine (e.g. "hbs", "ejs")
+     * @param engine - Function that renders a template given its path and data
+     *
+     * @example
+     * app.engineTemplates("hbs", (templatePath, data) => {
+     *   const content = fs.readFileSync(templatePath, "utf-8");
+     *   return content.replace(/{{\s*(\w+)\s*}}/g, (_, key) => {
+     *     return data[key] ?? "";
+     *   });
+     * });
+     *
+     * // With express-handlebars
+     * app.engineTemplates(
+     *   "hbs",
+     *   engine({
+     *     extname: "hbs",
+     *     layoutsDir: join(__dirname, "views"),
+     *     defaultLayout: "main",
+     *   }),
+     * );
+     *
+     * The `extension` parameter allows the framework to automatically select the correct
+     * template engine based on the file extension of the view being rendered.
+     */
+    engineTemplates(extension, engine) {
+        this.viewEngine.setEngine(extension, engine);
+    }
     /**
      * Starts the HTTP server on the given port.
      *
@@ -177,19 +215,19 @@ class App {
      */
     handleError(error, adapter) {
         if (error instanceof httpExceptions_1.HttpException) {
-            adapter.sendResponse(http_1.Response.json(error.toJSON()).setStatus(error.statusCode));
+            adapter.sendResponse(http_1.Response.json(error.toJSON()).setStatusCode(error.statusCode));
             return;
         }
         if (error instanceof validationException_1.ValidationException) {
             adapter.sendResponse(http_1.Response.json({
                 errors: error.getErrorsByField(),
-            }).setStatus(400));
+            }).setStatusCode(400));
             return;
         }
         adapter.sendResponse(http_1.Response.json({
             statusCode: 500,
             message: "Internal Server Error",
-        }).setStatus(500));
+        }).setStatusCode(500));
         console.error(error);
     }
 }

package/dist/crypto/jwt.js

@@ -85,7 +85,7 @@ const verifyJWT = (token, secret) => {
             return null;
         return payload;
     }
-    catch (error) {
+    catch {
         return null;
     }
 };
@@ -105,7 +105,7 @@ const decodeJWT = (token) => {
         const payload = JSON.parse(base64UrlDecode(parts[1]));
         return { header, payload };
     }
-    catch (error) {
+    catch {
         return null;
     }
 };

package/dist/helpers/http.d.ts

@@ -1,4 +1,3 @@
-import type { TemplateContext } from "../types";
 import { Response } from "../http/response";
 /**
  * Creates an HTTP response with a JSON body.
@@ -56,4 +55,4 @@ export declare function download(path: string, filename?: string, headers?: Reco
  * @example
  * return await render("users/profile", { user }, "main");
  */
-export declare function render(view: string, params: TemplateContext, layout?: string): Promise<Response>;
+export declare function render(data: string, params?: Record<string, unknown>): Promise<Response>;

package/dist/helpers/http.js

@@ -70,6 +70,6 @@ async function download(path, filename, headers) {
  * @example
  * return await render("users/profile", { user }, "main");
  */
-async function render(view, params, layout) {
-    return await response_1.Response.render(view, params, layout);
+async function render(data, params) {
+    return await response_1.Response.render(data, params);
 }

package/dist/http/logger.js

@@ -13,7 +13,7 @@ class Logger {
         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}`;
+        const logLine = `${method} ${url} ${coloredStatus} ${responseTime} ms - ${contentLength.toString()}`;
         this.stream.write(logLine + "\n");
     }
     colorizeStatus(statusCode) {

package/dist/http/response.d.ts

@@ -1,4 +1,4 @@
-import type { Headers, TemplateContext } from "../types";
+import type { Headers } from "../types";
 /**
  * Represents an outgoing response sent to the client.
  *
@@ -29,7 +29,7 @@ export declare class Response {
      */
     private _content;
     get statusCode(): number;
-    setStatus(newStatus: number): this;
+    setStatusCode(newStatus: number): this;
     get headers(): Headers;
     setHeaders(headers: Headers): this;
     private merge;
@@ -115,5 +115,5 @@ export declare class Response {
      * return Response.render("users/profile", { user });
      * return Response.render("auth/login", {}, "auth");
      */
-    static render(view: string, params: TemplateContext, layout?: string): Promise<Response>;
+    static render(data: string, params?: Record<string, unknown>): Promise<Response>;
 }

package/dist/http/response.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Response = void 0;
 const statusCodes_1 = require("./statusCodes");
 const invalidHttpStatusException_1 = require("../exceptions/invalidHttpStatusException");
-const app_1 = require("../helpers/app");
 const fileDownload_1 = require("../static/fileDownload");
+const engineTemplate_1 = require("../views/engineTemplate");
+const container_1 = require("../container/container");
 /**
  * Represents an outgoing response sent to the client.
  *
@@ -37,7 +38,7 @@ class Response {
     get statusCode() {
         return this._statusCode;
     }
-    setStatus(newStatus) {
+    setStatusCode(newStatus) {
         const status = statusCodes_1.statusCodes[newStatus] ?? null;
         if (!status)
             throw new invalidHttpStatusException_1.InvalidHttpStatusException(newStatus);
@@ -155,7 +156,7 @@ class Response {
      * });
      */
     static redirect(url) {
-        return new this().setStatus(302).setHeader("location", url);
+        return new this().setStatusCode(302).setHeader("location", url);
     }
     static async download(path, filename, headers) {
         const downloadClass = new fileDownload_1.FileDownloadHelper();
@@ -176,9 +177,13 @@ class Response {
      * return Response.render("users/profile", { user });
      * return Response.render("auth/login", {}, "auth");
      */
-    static async render(view, params, layout = null) {
-        const content = await (0, app_1.app)().view.render(view, params, layout);
-        return new this().setContentType("text/html").setContent(content);
+    static async render(data, params) {
+        const viewEngine = container_1.Container.resolve(engineTemplate_1.ViewEngine);
+        if (viewEngine.hasEngine())
+            data = await viewEngine.render(data, params ?? {});
+        return new this()
+            .setContentType("text/html; charset=utf-8")
+            .setContent(Buffer.from(data, "utf-8"));
     }
 }
 exports.Response = Response;

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export { FileSessionStorage, MemorySessionStorage } from "./sessions";
 export { HttpMethods } from "./http/httpMethods";
 export { createUploader } from "./storage/uploader";
 export { StorageType } from "./storage/types";
+export { v, schema } from "./validators/validationSchema";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StorageType = exports.createUploader = exports.HttpMethods = exports.MemorySessionStorage = exports.FileSessionStorage = exports.RouterGroup = exports.Response = exports.Request = exports.createApp = void 0;
+exports.schema = exports.v = exports.StorageType = exports.createUploader = exports.HttpMethods = exports.MemorySessionStorage = exports.FileSessionStorage = exports.RouterGroup = exports.Response = exports.Request = exports.createApp = void 0;
 var app_1 = require("./app");
 Object.defineProperty(exports, "createApp", { enumerable: true, get: function () { return app_1.createApp; } });
 var http_1 = require("./http");
@@ -17,3 +17,6 @@ var uploader_1 = require("./storage/uploader");
 Object.defineProperty(exports, "createUploader", { enumerable: true, get: function () { return uploader_1.createUploader; } });
 var types_1 = require("./storage/types");
 Object.defineProperty(exports, "StorageType", { enumerable: true, get: function () { return types_1.StorageType; } });
+var validationSchema_1 = require("./validators/validationSchema");
+Object.defineProperty(exports, "v", { enumerable: true, get: function () { return validationSchema_1.v; } });
+Object.defineProperty(exports, "schema", { enumerable: true, get: function () { return validationSchema_1.schema; } });

package/dist/middlewares/cors.js

@@ -75,7 +75,7 @@ const cors = (options = {}) => {
             corsHeaders["Access-Control-Max-Age"] = String(config.maxAge);
             if (!config.preflightContinue)
                 return new http_1.Response()
-                    .setStatus(204)
+                    .setStatusCode(204)
                     .setContent(null)
                     .setHeaders(corsHeaders);
         }

package/dist/parsers/multipartParser.d.ts

@@ -6,6 +6,16 @@ import { type MultipartData } from "./parserInterface";
  * Parses multipart payloads into fields and files.
  */
 export declare class MultipartParser implements ContentParser {
+    private readonly maxParts;
+    private readonly maxFieldSize;
+    private readonly maxFileSize;
+    private readonly maxHeaderSize;
+    constructor(options?: {
+        maxParts?: number;
+        maxFieldSize?: number;
+        maxFileSize?: number;
+        maxHeaderSize?: number;
+    });
     /**
      * Checks whether the given content type is `multipart/form-data`.
      *
@@ -32,4 +42,5 @@ export declare class MultipartParser implements ContentParser {
     private splitBuffer;
     private parsePart;
     private parseHeaders;
+    private trimEndingCRLF;
 }

package/dist/parsers/multipartParser.js

@@ -9,6 +9,16 @@ const parserInterface_1 = require("./parserInterface");
  * Parses multipart payloads into fields and files.
  */
 class MultipartParser {
+    maxParts;
+    maxFieldSize;
+    maxFileSize;
+    maxHeaderSize;
+    constructor(options = {}) {
+        this.maxParts = options.maxParts ?? 1000;
+        this.maxFieldSize = options.maxFieldSize ?? 1024 * 1024; // 1MB
+        this.maxFileSize = options.maxFileSize ?? 10 * 1024 * 1024; // 10MB
+        this.maxHeaderSize = options.maxHeaderSize ?? 16 * 1024; // 16KB
+    }
     /**
      * Checks whether the given content type is `multipart/form-data`.
      *
@@ -50,24 +60,33 @@ class MultipartParser {
         };
         const boundaryBuffer = Buffer.from(`--${boundary}`);
         const parts = this.splitBuffer(buffer, boundaryBuffer);
+        if (parts.length > this.maxParts) {
+            throw new httpExceptions_1.UnprocessableContentError(`Multipart parts limit exceeded: ${this.maxParts}`);
+        }
         for (const part of parts) {
             if (part.length === 0 || part.toString().trim() === "--")
                 continue;
             const parsed = this.parsePart(part);
-            if (parsed) {
-                if (parsed.filename) {
-                    result.files.push({
-                        fieldName: parsed.name,
-                        filename: parsed.filename,
-                        mimetype: parsed.contentType || parserInterface_1.contentTypes["application-octet-stream"],
-                        data: parsed.data,
-                        size: parsed.data.length,
-                    });
-                }
-                else {
-                    result.fields[parsed.name] = parsed.data.toString("utf-8");
+            if (!parsed)
+                continue;
+            const size = parsed.data.length;
+            if (parsed.filename) {
+                if (size > this.maxFileSize) {
+                    throw new httpExceptions_1.UnprocessableContentError(`File size limit exceeded: ${this.maxFileSize} bytes`);
                 }
+                result.files.push({
+                    fieldName: parsed.name,
+                    filename: parsed.filename,
+                    mimetype: parsed.contentType ?? parserInterface_1.contentTypes["application-octet-stream"],
+                    data: parsed.data,
+                    size,
+                });
+                continue;
+            }
+            if (size > this.maxFieldSize) {
+                throw new httpExceptions_1.UnprocessableContentError(`Field size limit exceeded: ${this.maxFieldSize} bytes`);
             }
+            result.fields[parsed.name] = parsed.data.toString("utf-8");
         }
         return result;
     }
@@ -87,8 +106,11 @@ class MultipartParser {
         const headerEndIndex = part.indexOf("\r\n\r\n");
         if (headerEndIndex === -1)
             return null;
+        if (headerEndIndex > this.maxHeaderSize) {
+            throw new httpExceptions_1.UnprocessableContentError(`Multipart headers too large: ${this.maxHeaderSize} bytes`);
+        }
         const headerSection = part.subarray(0, headerEndIndex).toString("utf-8");
-        const bodySection = part.subarray(headerEndIndex + 4);
+        const bodySection = this.trimEndingCRLF(part.subarray(headerEndIndex + 4));
         const headers = this.parseHeaders(headerSection);
         const disposition = headers["content-disposition"];
         if (!disposition)
@@ -117,5 +139,13 @@ class MultipartParser {
         }
         return headers;
     }
+    trimEndingCRLF(data) {
+        if (data.length < 2)
+            return data;
+        const end = data.subarray(-2).toString("utf-8");
+        if (end === "\r\n")
+            return data.subarray(0, data.length - 2);
+        return data;
+    }
 }
 exports.MultipartParser = MultipartParser;

package/dist/routing/router.js

@@ -73,14 +73,22 @@ class Router {
      * const response = await router.resolve(request);
      */
     resolve(request) {
-        const layer = this.resolveLayer(request);
-        if (layer.hasParameters())
-            request.setParams(layer.parseParameters(request.url));
-        const action = layer.getAction;
-        const allMiddlewares = [...this.globalMiddlewares, ...layer.getMiddlewares];
-        if (allMiddlewares.length > 0)
-            return this.runMiddlewares(request, allMiddlewares, action);
-        return action(request);
+        const executeLayer = (req) => {
+            const layer = this.resolveLayer(req);
+            if (layer.hasParameters()) {
+                req.setParams(layer.parseParameters(req.url));
+            }
+            const action = layer.getAction;
+            const routeMiddlewares = layer.getMiddlewares;
+            if (routeMiddlewares.length > 0) {
+                return this.runMiddlewares(req, routeMiddlewares, action);
+            }
+            return action(req);
+        };
+        if (this.globalMiddlewares.length > 0) {
+            return this.runMiddlewares(request, this.globalMiddlewares, executeLayer);
+        }
+        return executeLayer(request);
     }
     /**
      * Runs a middleware chain using the onion model.

package/dist/sessions/fileSessionStorage.js

@@ -213,10 +213,7 @@ class FileSessionStorage {
             }
             catch {
                 // Corrupt/unreadable → best-effort cleanup
-                try {
-                    await (0, promises_1.unlink)(full);
-                }
-                catch { }
+                await (0, promises_1.unlink)(full);
             }
         }));
     }
@@ -280,7 +277,9 @@ class FileSessionStorage {
         try {
             await (0, promises_1.unlink)(path);
         }
-        catch { }
+        catch {
+            /** eslint-disable-next-line no-empty */
+        }
     }
     /**
      * Generates a cryptographically strong session id (64 hex chars).

package/dist/sessions/sessionStorage.d.ts

@@ -67,7 +67,7 @@ export interface SessionStorage {
      * Removes all associated data and invalidates the session
      * for subsequent requests.
      */
-    destroy(): void;
+    destroy(): void | Promise<void>;
 }
 /**
  * Internal representation of persisted session data.

package/dist/static/contentDisposition.js

@@ -59,7 +59,12 @@ class ContentDisposition {
     }
     sanitizeFilename(filename) {
         return filename
-            .replace(/[\x00-\x1F\x7F-\x9F]/g, "")
+            .split("")
+            .filter(char => {
+            const code = char.charCodeAt(0);
+            return !(code <= 0x1f || (code >= 0x7f && code <= 0x9f));
+        })
+            .join("")
             .replace(/["\r\n]/g, "")
             .replace(/[/\\]/g, "")
             .replace(/\s+/g, " ")

package/dist/static/fileStaticHandler.js

@@ -86,7 +86,7 @@ class StaticFileHandler {
                 "last-modified": stats.mtime.toUTCString(),
                 ETag: `"${stats.size}-${stats.mtime.getTime()}"`,
             })
-                .setStatus(200);
+                .setStatusCode(200);
         }
         catch {
             return null;