skyguard-js 1.2.0 → 1.2.2

package/README.md

@@ -31,7 +31,7 @@ Skyguard.js currently delivers a solid core that includes **routing**, **type-sa
 - HTTP routing by method (GET, POST, PUT, PATCH, DELETE)
 - Route groups with prefixes
 - Global, group, and route-level middlewares
-- Request / Response abstractions
+- Unified `Context` abstraction (`ctx.req` + response helpers)
 - Declarative data validation
 - Support for template motors (handlebars, pugs, ejs, etc.)
 - Built-in HTTP exceptions
@@ -73,479 +73,22 @@ npm install skyguard-js
 ## 🏁 Quick Start
 
 ```ts
-import { createApp, Response } from "skyguard-js";
+import { createApp } from "skyguard-js";
 
 const app = createApp();
 
-const PORT = 3000;
+app.get("/", ctx => ctx.json({ status: "ok" }));
 
-app.get("/health", () => {
-  return Response.json({ status: "ok" });
-});
-
-app.run(PORT, () => {
-  console.log(`Server running in port: http://localhost:${PORT}`);
-});
-```
-
----
-
-## 🛣️ Routing
-
-Routes are registered using HTTP methods on the `app` instance.
-
-```ts
-app.get("/posts/{id}", (request: Request) => {
-  return Response.json(request.params);
-});
-
-app.post("/posts", (request: Request) => {
-  return Response.json(request.data);
-});
-```
-
-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", () => res.json({ message: "Users" }));
-  api.get("/products", () => res.json({ message: "Products" }));
-});
-```
-
----
-
-## 🛠️ Middlewares
-
-Middlewares can be registered **globally**, **per group**, or **per route**.
-
-```ts
-import { Request, Response, json, RouteHandler } from "skyguard-js";
-
-const authMiddleware = async (
-  request: Request,
-  next: RouteHandler,
-): Promise<Response> => {
-  if (request.headers["authorization"] !== "secret") {
-    return 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", () => json({ ok: true }));
-});
-
-// Route-level middleware
-app.get("/secure", () => json({ secure: true }), [authMiddleware]);
-```
-
----
-
-## 🌐 CORS Middleware
-
-To enable CORS, use the built-in `cors` middleware.
-
-```ts
-import { cors, HttpMethods } from "skyguard-js";
-
-app.middlewares(
-  cors({
-    origin: ["http://localhost:3000", "https://myapp.com"],
-    methods: [HttpMethods.get, HttpMethods.post],
-    allowedHeaders: ["Content-Type", "Authorization"],
-    credentials: true,
-  }),
-);
-```
-
----
-
-## 🛡️ CSRF Middleware
-
-Use the built-in `csrf` middleware to protect endpoints against CSRF attacks.
-
-```ts
-import { csrf, json } from "skyguard-js";
-
-app.middlewares(
-  csrf({
-    cookieName: "XSRF-TOKEN",
-    headerNames: ["x-csrf-token"],
-  }),
-);
-
-app.post("/transfer", () => {
-  return json({ ok: true });
-});
-```
-
-The middleware follows a hardened **double-submit cookie** strategy:
-
-- It issues a CSRF cookie when missing (including first GET/HEAD/OPTIONS and failed protected requests).
-- For state-changing requests (POST/PUT/PATCH/DELETE), it validates the token from header/body against the cookie value.
-- It validates `Origin`/`Referer` for protected requests (and requires `Referer` on HTTPS when `Origin` is missing).
-- It rejects duplicated CSRF header values to avoid ambiguous token parsing.
-
-### Example: CSRF token in HTML templates (Express Handlebars)
-
-When you render server-side HTML, you can pass the CSRF token to your template and include it as a hidden field in forms.
-
-```ts
-import { createApp, csrf, render, json } from "skyguard-js";
-import { engine } from "express-handlebars";
-import { join } from "node:path";
-
-const app = createApp();
-
-app.views(__dirname, "views");
-app.engineTemplates(
-  "hbs",
-  engine({
-    extname: "hbs",
-    layoutsDir: join(__dirname, "views"),
-    defaultLayout: "main",
-  }),
-);
-
-app.middlewares(
-  csrf({
-    cookieName: "XSRF-TOKEN",
-    headerNames: ["x-csrf-token"],
-  }),
-);
-
-app.get("/transfer", request => {
-  return render("transfer", {
-    csrfToken: request.cookies["XSRF-TOKEN"],
-  });
-});
-
-app.post("/transfer", request => {
-  // If middleware passes, token is valid
-  return json({ ok: true, amount: request.body.amount });
-});
-```
-
-`views/transfer.hbs`:
-
-```hbs
-<form action="/transfer" method="POST">
-  <input type="hidden" name="csrf" value="{{csrfToken}}" />
-  <input type="number" name="amount" />
-  <button type="submit">Send</button>
-</form>
-```
-
-For `fetch`/AJAX requests, send the same token in headers:
-
-```html
-<script>
-  const csrfToken = "{{csrfToken}}";
-
-  async function sendTransfer() {
-    await fetch("/transfer", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "x-csrf-token": csrfToken,
-      },
-      body: JSON.stringify({ amount: 150 }),
-    });
-  }
-</script>
-```
-
----
-
-## 🚦 Rate Limit Middleware
-
-You can limit requests with the built-in `rateLimit` middleware.
-
-```ts
-import { rateLimit, Response } from "skyguard-js";
-
-const apiRateLimit = rateLimit({
-  windowMs: 60_000, // 1 minute
-  max: 100,
-  message: "Too many requests from this IP",
-});
-
-app.get(
-  "/api/users",
-  () => {
-    return Response.json([{ id: 1 }]);
-  },
-  [apiRateLimit],
-);
+app.run();
 ```
 
 ---
 
-## 📌 Static Files
-
-To serve static files, use the application's `staticFiles` method with the directory path. The name of the folder will determine the initial route prefix.
-
-```ts
-import { join } from "node:path";
-
-app.staticFiles(join(__dirname, "..", "static"));
-
-// Route http://localhost:3000/static/style.css will serve the file located at ./static/style.css
-```
-
----
-
-## ⛔ Data Validation
-
-To validate the data in the body of client requests, the framework provides the creation of validation schemes and a middleware function to validate the body of HTTP requests, used as follows:
-
-```ts
-import { v, schema, validateRequest, json } from "skyguard-js";
-
-// Created Schema
-const userSchema = schema({
-  body: {
-    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(
-  "/test",
-  (request: Request) => {
-    const data = request.body;
-    return json(data).setStatusCode(201);
-  },
-  [validateRequest(userSchema)],
-);
-```
-
-To type the request body, an interface is used and the .getData() method is used, which allows returning the typed bodym. 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
-- Fully typed
-- Reusable
-- Decoupled from transport layer
-
----
-
-## 🚨 Exceptions & Error Handling
-
-The framework provides a set of built-in HTTP exceptions that can be thrown from route handlers or middleware. When an exception is thrown, the framework detects it and sends an appropriate HTTP response with the status code and message you specified in the class.
-
-```ts
-import { NotFoundError, InternalServerError, json } from "skyguard-js";
-
-const listResources = ["1", "2", "3"];
-
-app.get("/resource/{id}", (request: Request) => {
-  const resource = request.params["id"];
-
-  if (!listResources.includes(resource)) {
-    throw new NotFoundError("Resource not found");
-  }
-
-  return json(resource);
-});
-
-app.get("/divide", (request: Request) => {
-  try {
-    const { a, b } = request.query;
-    const result = Number(a) / Number(b);
-
-    return json({ result });
-  } catch (error) {
-    throw new InternalServerError(
-      "An error occurred while processing your request",
-    );
-  }
-});
-```
-
----
-
-## 🧱 Sessions
-
-To handle sessions, you must use the framework’s built-in middleware. Depending on where you want to store them (in memory, in files, or in a database), you need to use the corresponding storage class.
-
-```ts
-import { sessions, FileSessionStorage, json } from "skyguard-js";
-
-app.middlewares(
-  sessions(FileSessionStorage, {
-    name: "connect.sid",
-    rolling: true,
-    saveUninitialized: false,
-    cookie: {
-      maxAge: 60 * 60 * 24,
-      httpOnly: true,
-      sameSite: "Lax",
-      secure: false,
-      path: "/",
-    },
-  }),
-);
-
-app.post("/login", (request: Request) => {
-  const { username, password } = request.data;
-
-  if (username === "admin" && password === "secret") {
-    request.session.set("user", {
-      id: 1,
-      username: "admin",
-      role: "admin",
-    });
-
-    return json({ message: "Logged in" });
-  }
-
-  throw new UnauthorizedError("Invalid credentials");
-});
-
-app.get("/me", (request: Request) => {
-  const user = request.session.get("user");
-
-  if (!user) throw new UnauthorizedError("Not authenticated");
-  return json({ user });
-});
-```
-
----
-
-## 🛡️ Security
-
-The framework includes some password hashing and JWT token generation functions, and also includes JWT authentication middleware.
-
-```ts
-import { Hasher, JWT, json } from "skyguard-js";
-
-app.post("/register", async (request: Request) => {
-  const { username, password } = request.data;
-  const hashedPassword = await Hasher.hash(password);
-
-  // Save username and hashedPassword to database
-  // ...
-
-  return json({ message: "User registered" });
-});
-
-app.post("/login", async (request: Request) => {
-  const { username, password } = request.data;
-
-  // Retrieve user from database by username
-  // ...
-
-  const isValid = await Hasher.verify(password, user.hashedPassword);
-
-  if (!isValid) {
-    throw new UnauthorizedError("Invalid credentials");
-  }
-
-  const token = JWT.create({ sub: "123" }, "secret-key", {
-    algorithm: "HS256",
-    expiresIn: "1h",
-  });
-
-  return json({ token });
-});
-```
-
----
-
-## 📂 File Uploads
-
-To handle file uploads, use the built-in `createUploader` function to create an uploader middleware with the desired storage configuration.
-
-```ts
-import { createUploader, StorageType, json } from "skyguard-js";
-
-const uploader = createUploader({
-  storageType: StorageType.DISK,
-  storageOptions: {
-    disk: {
-      destination: "./uploads",
-    },
-  },
-});
-
-app.post(
-  "/upload",
-  (request: Request) => {
-    return json({
-      message: "File uploaded successfully",
-      file: request.file,
-    });
-  },
-  [uploader.single("file")],
-);
-```
-
-Depending on the `Storage Type` you have selected, the storage options will contain two properties: `disk` and `memory`
-
----
-
-## 📄 Views & Template Engine
-
-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 { engine } from "express-handlebars";
-import ejs from "ejs";
-import { join } from "node:path";
-import { render } from "skyguard-js";
-
-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("index", {
-    title: "Home Page",
-    message: "Welcome to the home page!",
-  });
-});
-```
-
-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 engines supported (✅)
-- Request / Response abstraction (✅)
+- Context abstraction (✅)
 - Data validation (✅)
 - Error handling improvements (✅)
 - Sessions & cookies (✅)
@@ -554,3 +97,7 @@ Currently, it works with third-party template engines such as **Express Handleba
 - Database & ORM integration
 - Authentication & authorization
 - WebSockets
+
+## License
+
+MIT

package/dist/app.d.ts

@@ -1,4 +1,5 @@
 import { RouterGroup } from "./routing";
+import { type LogFormat } from "./http";
 import type { Middleware, RouteHandler } from "./types";
 import { type TemplateEngineFunction } from "./views/engineTemplate";
 /**
@@ -19,13 +20,15 @@ import { type TemplateEngineFunction } from "./views/engineTemplate";
  * from the runtime platform (Node, Bun, Deno, etc.)
  * through {@link HttpAdapter} and {@link Server}.
  */
-export declare class App {
+declare class App {
     /** Main routing system */
     private router;
     /** Static file handler (optional) */
     private staticFileHandler;
     /** View engine for rendering templates (optional) */
     private viewEngine;
+    /** Logger configuration */
+    private loggerOptions;
     /**
      * Bootstraps and configures the application.
      *
@@ -106,7 +109,22 @@ export 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.
+     *
+     * Supported formats are inspired by morgan:
+     * - "combined"
+     * - "common"
+     * - "dev"
+     * - "short"
+     * - "tiny"
+     *
+     * @example
+     * app.logger("common");
+     * app.logger("combined", "./logs/http.log");
+     */
+    logger(format?: LogFormat, filePath?: string): void;
     /**
      * Sets a global prefix for all routes.
      *
@@ -118,24 +136,29 @@ export 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);
@@ -159,3 +182,4 @@ export declare class App {
     private handleError;
 }
 export declare const createApp: () => App;
+export {};