skyguard-js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pipe930
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# 🛡️✈️ Skyguard.js — TypeScript Web Framework
+
+Skyguard.js is a **lightweight and experimental web framework**, inspired by **Express**, written entirely in **TypeScript**.
+
+The main goal of this project is to **learn, experiment, and build a solid foundation** for a more complete backend framework in the future.
+
+At its current stage, the framework focuses on **routing**, **internal architecture**, **type safety**, and **core HTTP abstractions**, leaving advanced features for later iterations.
+
+---
+
+## 🎯 Current Goals
+
+* Provide a simple and expressive API to register and handle HTTP routes
+* Maintain a clean, extensible, and framework-agnostic architecture
+* Leverage TypeScript for strong typing and better developer experience
+* Serve as a learning project with progressive evolution
+
+---
+
+## ✨ Current Features
+
+* TypeScript-first design
+* HTTP routing by method (GET, POST, PUT, PATCH, DELETE)
+* Route groups with prefixes
+* Global, group, and route-level middlewares
+* Request / Response abstractions
+* Declarative data validation
+* Simple template engine with layouts and helpers
+* Static file serving
+* Session handling (via middleware)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install skyguard-js
+```
+
+---
+
+## 🏁 Basic Usage
+
+```ts
+import { createApp } from "skyguard-js";
+import { Response } from "skyguard-js/http";
+
+const app = createApp();
+
+app.get("/health", () => {
+  return Response.json({ status: "ok" });
+});
+
+app.listen(3000);
+```
+
+---
+
+## 🛣️ Routing
+
+Routes are registered using HTTP methods on the `app` instance.
+
+```ts
+app.get("/posts/{id}", (request: Request) => {
+  return Response.json(request.getParams());
+});
+
+app.post("/posts", (request: Request) => {
+  return Response.json(request.getData());
+});
+```
+
+Internally, the framework maps HTTP methods to route layers using an optimized routing table.
+
+---
+
+## 🧩 Route Groups
+
+Route groups allow you to organize endpoints under a shared prefix.
+
+```ts
+app.group("/api", (api) => {
+  api.get("/users", () => Response.json({ message: "Users" }));
+  api.get("/products", () => Response.json({ message: "Products" }));
+});
+```
+
+---
+
+## 🛠️ Middlewares
+
+Middlewares can be registered **globally**, **per group**, or **per route**.
+
+```ts
+import { Request, Response } from "skyguard-js/http";
+import { RouteHandler } from "skyguard-js/types";
+
+const authMiddleware = async (
+  request: Request,
+  next: RouteHandler,
+): Promise<Response> => {
+  if (request.getHeaders["authorization"] !== "secret") {
+    return Response.json({ message: "Unauthorized" }).setStatus(401);
+  }
+
+  return next(request);
+};
+
+// Global middleware
+app.middlewares([authMiddleware]);
+
+// Group middleware
+app.group("/admin", (admin) => {
+  admin.middlewares([authMiddleware]);
+  admin.get("/dashboard", () => Response.json({ ok: true }));
+});
+
+// Route-level middleware
+app.get(
+  "/secure",
+  () => Response.json({ secure: true }),
+  [authMiddleware],
+);
+```
+
+---
+
+## 📦 Data Validation
+
+Skyguard.js provides a **declarative validation system** using schemas.
+
+```ts
+import { ValidationSchema } from "skyguard-js/validation";
+
+export const userSchema = ValidationSchema.create()
+  .field("name")
+    .required("Name is required")
+    .string({ maxLength: 60 })
+  .field("email")
+    .required()
+    .email()
+  .field("age")
+    .number({ min: 18, max: 99 })
+  .field("active")
+    .boolean()
+  .build();
+
+app.post("/users", (request: Request) => {
+  const validatedData = request.validateData(userSchema);
+
+  return Response.json({
+    success: true,
+    data: validatedData,
+  });
+});
+```
+
+Validation is:
+
+* Fail-fast per field
+* Fully typed
+* Reusable
+* Decoupled from transport layer
+
+---
+
+## 📄 Views & Template Engine
+
+To render HTML views, use the `render` helper.
+
+```ts
+import { render } from "skyguard-js/helpers";
+
+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",
+  );
+});
+```
+
+### Supported features
+
+* Variable interpolation (`{{ variable }}`)
+* Conditionals (`{{#if}}`)
+* Loops (`{{#each}}`)
+* Layouts
+* Partials
+* Built-in helpers (`upper`, `lower`, `date`)
+* Custom helpers
+
+---
+
+## 🧱 Project Status
+
+⚠️ **Early-stage project**
+
+* Not production-ready
+* API may change
+* Features are still evolving
+* Intended primarily for learning and experimentation
+
+---
+
+## 🔮 Roadmap (Tentative)
+
+* Middleware system (✅)
+* Template engine (✅)
+* Request / Response abstraction (✅)
+* Data validation (✅)
+* Error handling improvements
+* Database & ORM integration
+* Authentication & authorization
+* Sessions & cookies (in progress)
+* Plugin system
+
+---
+
+## 🧠 Motivation
+
+This project was created to deeply understand how frameworks like **Express**, **Fastify**, and **Koa** work internally, by reimplementing their core ideas with a **modern TypeScript-first approach**.
+
+---
+
+## 📄 License
+
+MIT License
+
+---

package/dist/app.d.ts

@@ -0,0 +1,123 @@
+import { RouterGroup } from "./routing";
+import { type HttpAdapter } from "./http";
+import { type View } from "./views";
+import type { Middleware, RouteHandler } from "./types";
+/**
+ * The `App` class acts as the **execution kernel** and **lifecycle orchestrator**
+ * of the framework.
+ *
+ * It is responsible for:
+ * - Bootstrapping and exposing the routing system
+ * - Receiving normalized HTTP requests through adapters
+ * - Resolving the matching route
+ * - Executing the associated controller
+ * - Dispatching the final response to the client
+ *
+ * This class implements the **Singleton pattern** to guarantee
+ * a single application instance during the process lifecycle.
+ *
+ * The architecture fully decouples the core framework
+ * from the runtime platform (Node, Bun, Deno, etc.)
+ * through {@link HttpAdapter} and {@link Server}.
+ */
+export declare class App {
+    /** Main routing system */
+    private router;
+    /** Underlying HTTP server implementation */
+    private server;
+    /**
+     * View engine used to render templates.
+     *
+     * Typically consumed inside controllers to generate HTML responses.
+     */
+    view: View;
+    /** Static file handler (optional) */
+    private staticFileHandler;
+    /**
+     * Bootstraps and configures the application.
+     *
+     * Acts as the **Composition Root** of the framework:
+     * this is the only place where concrete infrastructure
+     * implementations are instantiated and wired together.
+     *
+     * @returns The singleton `App` instance
+     */
+    static bootstrap(): App;
+    /**
+     * Main execution pipeline.
+     *
+     * Execution flow:
+     * 1. Retrieves the normalized request from the adapter
+     * 2. Attempts to serve a static file (if enabled)
+     * 3. Resolves the matching route
+     * 4. Executes the controller
+     * 5. Sends the response back to the client
+     *
+     * This method is platform-agnostic.
+     *
+     * @param adapter - HTTP adapter bridging the runtime with the framework
+     */
+    handle(adapter: HttpAdapter): Promise<void>;
+    /**
+     * Enables static file serving.
+     *
+     * @param publicPath - Absolute or relative public directory path
+     *
+     * @example
+     * app.staticFiles("public");
+     * // /public/css/style.css → /css/style.css
+     */
+    staticFiles(publicPath: string): void;
+    /**
+     * Starts the HTTP server on the given port.
+     *
+     * @example
+     * app.listen(3000);
+     *
+     * @param port - TCP port to listen on
+     */
+    listen(port: number): void;
+    /**
+     * Sets a global prefix for all routes.
+     *
+     * @param prefix - Route prefix (e.g. "api", "/v1")
+     *
+     * @example
+     * app.setPrefix("api");
+     * app.get("/users", handler); // → /api/users
+     */
+    setPrefix(prefix: string): void;
+    /** Registers a GET route */
+    get(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    /** Registers a POST route */
+    post(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    /** Registers a PUT route */
+    put(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    /** Registers a PATCH route */
+    patch(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    /** Registers a DELETE route */
+    delete(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    /**
+     * Registers global middlewares.
+     *
+     * These are executed for every route.
+     */
+    middlewares(middlewares: Middleware[]): void;
+    /**
+     * Creates a route group with a shared prefix.
+     *
+     * @example
+     * app.group("/api", (api) => {
+     *   api.get("/users", listUsers);
+     *   api.post("/users", createUser);
+     * });
+     */
+    group(prefix: string, callback: (group: RouterGroup) => void): void;
+    /**
+     * Translates domain-level exceptions into HTTP responses.
+     *
+     * This method centralizes error handling and response mapping.
+     */
+    private handleError;
+}
+export declare const createApp: () => App;

package/dist/app.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApp = exports.App = void 0;
+const routing_1 = require("./routing");
+const http_1 = require("./http");
+const exceptions_1 = require("./exceptions");
+const nodeNativeServer_1 = require("./server/nodeNativeServer");
+const views_1 = require("./views");
+const node_path_1 = require("node:path");
+const app_1 = require("./helpers/app");
+const fileStaticHandler_1 = require("./static/fileStaticHandler");
+/**
+ * The `App` class acts as the **execution kernel** and **lifecycle orchestrator**
+ * of the framework.
+ *
+ * It is responsible for:
+ * - Bootstrapping and exposing the routing system
+ * - Receiving normalized HTTP requests through adapters
+ * - Resolving the matching route
+ * - Executing the associated controller
+ * - Dispatching the final response to the client
+ *
+ * This class implements the **Singleton pattern** to guarantee
+ * a single application instance during the process lifecycle.
+ *
+ * The architecture fully decouples the core framework
+ * from the runtime platform (Node, Bun, Deno, etc.)
+ * through {@link HttpAdapter} and {@link Server}.
+ */
+class App {
+    /** Main routing system */
+    router;
+    /** Underlying HTTP server implementation */
+    server;
+    /**
+     * View engine used to render templates.
+     *
+     * Typically consumed inside controllers to generate HTML responses.
+     */
+    view;
+    /** Static file handler (optional) */
+    staticFileHandler = null;
+    /**
+     * Bootstraps and configures the application.
+     *
+     * Acts as the **Composition Root** of the framework:
+     * this is the only place where concrete infrastructure
+     * implementations are instantiated and wired together.
+     *
+     * @returns The singleton `App` instance
+     */
+    static bootstrap() {
+        const app = (0, app_1.singleton)(App);
+        app.router = new routing_1.Router();
+        app.server = new nodeNativeServer_1.NodeServer(app);
+        app.view = new views_1.RaptorEngine((0, node_path_1.join)(__dirname, "..", "views"));
+        return app;
+    }
+    /**
+     * Main execution pipeline.
+     *
+     * Execution flow:
+     * 1. Retrieves the normalized request from the adapter
+     * 2. Attempts to serve a static file (if enabled)
+     * 3. Resolves the matching route
+     * 4. Executes the controller
+     * 5. Sends the response back to the client
+     *
+     * This method is platform-agnostic.
+     *
+     * @param adapter - HTTP adapter bridging the runtime with the framework
+     */
+    async handle(adapter) {
+        try {
+            const request = await adapter.getRequest();
+            if (this.staticFileHandler && request.getMethod === http_1.HttpMethods.get) {
+                const staticResponse = await this.staticFileHandler.tryServeFile(request.getUrl);
+                if (staticResponse) {
+                    adapter.sendResponse(staticResponse);
+                    return;
+                }
+            }
+            const response = await this.router.resolve(request);
+            adapter.sendResponse(response);
+        }
+        catch (error) {
+            this.handleError(error, adapter);
+        }
+    }
+    /**
+     * Enables static file serving.
+     *
+     * @param publicPath - Absolute or relative public directory path
+     *
+     * @example
+     * app.staticFiles("public");
+     * // /public/css/style.css → /css/style.css
+     */
+    staticFiles(publicPath) {
+        this.staticFileHandler = new fileStaticHandler_1.StaticFileHandler(publicPath);
+    }
+    /**
+     * Starts the HTTP server on the given port.
+     *
+     * @example
+     * app.listen(3000);
+     *
+     * @param port - TCP port to listen on
+     */
+    listen(port) {
+        this.server.listen(port);
+    }
+    /**
+     * Sets a global prefix for all routes.
+     *
+     * @param prefix - Route prefix (e.g. "api", "/v1")
+     *
+     * @example
+     * app.setPrefix("api");
+     * app.get("/users", handler); // → /api/users
+     */
+    setPrefix(prefix) {
+        this.router.setPrefix(prefix);
+    }
+    /** Registers a GET route */
+    get(path, action, middlewares) {
+        this.router.get(path, action, middlewares);
+    }
+    /** Registers a POST route */
+    post(path, action, middlewares) {
+        this.router.post(path, action, middlewares);
+    }
+    /** Registers a PUT route */
+    put(path, action, middlewares) {
+        this.router.put(path, action, middlewares);
+    }
+    /** Registers a PATCH route */
+    patch(path, action, middlewares) {
+        this.router.patch(path, action, middlewares);
+    }
+    /** Registers a DELETE route */
+    delete(path, action, middlewares) {
+        this.router.delete(path, action, middlewares);
+    }
+    /**
+     * Registers global middlewares.
+     *
+     * These are executed for every route.
+     */
+    middlewares(middlewares) {
+        this.router.middlewares(middlewares);
+    }
+    /**
+     * Creates a route group with a shared prefix.
+     *
+     * @example
+     * app.group("/api", (api) => {
+     *   api.get("/users", listUsers);
+     *   api.post("/users", createUser);
+     * });
+     */
+    group(prefix, callback) {
+        this.router.group(prefix, callback);
+    }
+    /**
+     * Translates domain-level exceptions into HTTP responses.
+     *
+     * This method centralizes error handling and response mapping.
+     */
+    handleError(error, adapter) {
+        if (error instanceof exceptions_1.HttpNotFoundException) {
+            adapter.sendResponse(http_1.Response.text("Not Found").setStatus(404));
+            return;
+        }
+        if (error instanceof exceptions_1.ContentParserException) {
+            adapter.sendResponse(http_1.Response.json({ message: error.message }).setStatus(422));
+            return;
+        }
+        if (error instanceof exceptions_1.SessionException) {
+            adapter.sendResponse(http_1.Response.json({ message: error.message }).setStatus(401));
+            return;
+        }
+        if (error instanceof exceptions_1.ValidationException) {
+            adapter.sendResponse(http_1.Response.json({
+                success: false,
+                errors: error.getErrorsByField(),
+            }).setStatus(400));
+            return;
+        }
+        adapter.sendResponse(http_1.Response.text("Internal Server Error").setStatus(500));
+        console.error(error);
+    }
+}
+exports.App = App;
+const createApp = () => {
+    return App.bootstrap();
+};
+exports.createApp = createApp;

package/dist/container/container.d.ts

@@ -0,0 +1,60 @@
+import type { Constructor } from "../types";
+/**
+ * Dependency Injection container.
+ *
+ * Stores and resolves application-wide singletons by constructor reference.
+ *
+ * @example
+ * class App {}
+ *
+ * // Create (or return) the singleton instance
+ * const app = Container.singleton(App);
+ *
+ * // Resolve an already-registered singleton
+ * const resolved = Container.resolve(App);
+ */
+export declare class Container {
+    /**
+     * Singleton instances indexed by class constructor.
+     *
+     * @internal
+     */
+    private static instances;
+    /**
+     * Get or create a singleton instance for the given class.
+     *
+     * If no instance exists yet, the container will instantiate the class with
+     * `new classConstructor()` (no constructor arguments) and cache it.
+     *
+     * @typeParam T - Instance type produced by the constructor
+     * @param classConstructor - Class constructor used as the registration key
+     * @returns The singleton instance for the given class
+     *
+     * @example
+     * class Database {
+     *   connect() {
+     *     console.log("Connected");
+     *   }
+     * }
+     *
+     * const db1 = Container.singleton(Database);
+     * const db2 = Container.singleton(Database);
+     * console.log(db1 === db2); // true
+     */
+    static singleton<T>(classConstructor: Constructor<T>): T;
+    /**
+     * Resolve a previously created singleton instance.
+     *
+     * This method does not create instances. If the class was never registered
+     * via {@link Container.singleton}, it returns `null`.
+     *
+     * @typeParam T - Instance type produced by the constructor
+     * @param classConstructor - Class constructor used as the registration key
+     * @returns The singleton instance, or `null` if it is not registered
+     *
+     * @example
+     * const db = Container.resolve(Database);
+     * if (db) db.connect();
+     */
+    static resolve<T>(classConstructor: Constructor<T>): T | null;
+}

package/dist/container/container.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Container = void 0;
+/**
+ * Dependency Injection container.
+ *
+ * Stores and resolves application-wide singletons by constructor reference.
+ *
+ * @example
+ * class App {}
+ *
+ * // Create (or return) the singleton instance
+ * const app = Container.singleton(App);
+ *
+ * // Resolve an already-registered singleton
+ * const resolved = Container.resolve(App);
+ */
+class Container {
+    /**
+     * Singleton instances indexed by class constructor.
+     *
+     * @internal
+     */
+    static instances = new Map();
+    /**
+     * Get or create a singleton instance for the given class.
+     *
+     * If no instance exists yet, the container will instantiate the class with
+     * `new classConstructor()` (no constructor arguments) and cache it.
+     *
+     * @typeParam T - Instance type produced by the constructor
+     * @param classConstructor - Class constructor used as the registration key
+     * @returns The singleton instance for the given class
+     *
+     * @example
+     * class Database {
+     *   connect() {
+     *     console.log("Connected");
+     *   }
+     * }
+     *
+     * const db1 = Container.singleton(Database);
+     * const db2 = Container.singleton(Database);
+     * console.log(db1 === db2); // true
+     */
+    static singleton(classConstructor) {
+        if (!this.instances.has(classConstructor)) {
+            const instance = new classConstructor();
+            this.instances.set(classConstructor, instance);
+        }
+        return this.instances.get(classConstructor);
+    }
+    /**
+     * Resolve a previously created singleton instance.
+     *
+     * This method does not create instances. If the class was never registered
+     * via {@link Container.singleton}, it returns `null`.
+     *
+     * @typeParam T - Instance type produced by the constructor
+     * @param classConstructor - Class constructor used as the registration key
+     * @returns The singleton instance, or `null` if it is not registered
+     *
+     * @example
+     * const db = Container.resolve(Database);
+     * if (db) db.connect();
+     */
+    static resolve(classConstructor) {
+        return this.instances.get(classConstructor) ?? null;
+    }
+}
+exports.Container = Container;