skyguard-js 1.2.1 → 1.2.2

package/dist/middlewares/rateLimiter.js

@@ -3,35 +3,146 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.rateLimit = void 0;
 const http_1 = require("../http");
 const httpExceptions_1 = require("../exceptions/httpExceptions");
+const node_net_1 = require("node:net");
 /**
- * Default key generator used by the rate limiter to uniquely identify a client.
+ * Default in-memory implementation of {@link RateLimitStore}.
  *
- * The function attempts to extract the client IP address from common proxy
- * headers in order of priority:
- *
- * 1. `x-forwarded-for` → typically used by reverse proxies and load balancers.
- *    If multiple IPs are present, the first one is assumed to be the client IP.
- * 2. `x-real-ip` → used by some proxies (e.g., Nginx).
- * 3. `cf-connecting-ip` → used by Cloudflare to forward the original client IP.
+ * Use a shared external store (e.g. Redis) for distributed environments.
+ */
+class MemoryRateLimitStore {
+    maxKeys;
+    store = new Map();
+    /**
+     * @param maxKeys - Maximum number of retained keys in memory.
+     */
+    constructor(maxKeys) {
+        this.maxKeys = maxKeys;
+    }
+    /**
+     * Increments an in-memory counter for the provided key.
+     *
+     * If the window is expired (or absent), a new window starts at `now`.
+     */
+    increment(key, windowMs, now) {
+        let entry = this.store.get(key);
+        if (!entry || now > entry.resetTime) {
+            entry = { count: 1, resetTime: now + windowMs };
+            this.store.set(key, entry);
+            this.trimIfNeeded(now);
+            return entry;
+        }
+        entry.count += 1;
+        return entry;
+    }
+    /**
+     * Removes expired entries from the internal map.
+     */
+    cleanup(now) {
+        for (const [key, value] of this.store.entries()) {
+            if (now > value.resetTime)
+                this.store.delete(key);
+        }
+    }
+    /**
+     * Enforces `maxKeys` and avoids unbounded memory growth.
+     */
+    trimIfNeeded(now) {
+        if (this.store.size <= this.maxKeys)
+            return;
+        this.cleanup(now);
+        while (this.store.size > this.maxKeys) {
+            const oldestKey = this.store.keys().next().value;
+            if (!oldestKey)
+                break;
+            this.store.delete(oldestKey);
+        }
+    }
+}
+/**
+ * Normalizes a candidate IP address into a canonical value.
  *
- * If none of these headers are available, the request `Host` header is used as
- * a fallback identifier. If that is also missing, `"anonymous"` is returned.
+ * Supported inputs:
+ * - Plain IPv4/IPv6
+ * - IPv4-mapped IPv6 (`::ffff:x.x.x.x`)
+ * - Bracketed IPv6 (`[2001:db8::1]`)
+ * - IPv4 with port (`x.x.x.x:port`)
  *
- * @param request - Incoming HTTP request.
- * @returns A string key used to track request counts per client.
+ * @param value - Raw address candidate.
+ * @returns Normalized IP, or `null` when the input is not a valid IP.
  */
-const defaultKeyGenerator = (request) => {
-    const forwardedFor = request.headers["x-forwarded-for"];
-    const realIp = request.headers["x-real-ip"];
-    const cfIp = request.headers["cf-connecting-ip"];
-    if (typeof forwardedFor === "string") {
-        return forwardedFor.split(",")[0]?.trim() ?? "anonymous";
+const normalizeAddress = (value) => {
+    if (!value)
+        return null;
+    const candidate = value.trim();
+    if (!candidate)
+        return null;
+    if ((0, node_net_1.isIP)(candidate))
+        return candidate;
+    if (candidate.startsWith("::ffff:")) {
+        const mapped = candidate.slice("::ffff:".length);
+        if ((0, node_net_1.isIP)(mapped))
+            return mapped;
     }
-    if (typeof realIp === "string")
-        return realIp;
-    if (typeof cfIp === "string")
+    const withoutBrackets = candidate.startsWith("[") && candidate.endsWith("]")
+        ? candidate.slice(1, -1)
+        : candidate;
+    if ((0, node_net_1.isIP)(withoutBrackets))
+        return withoutBrackets;
+    const ipv4WithPort = withoutBrackets.match(/^(\d{1,3}(?:\.\d{1,3}){3}):\d+$/);
+    if (ipv4WithPort && (0, node_net_1.isIP)(ipv4WithPort[1]))
+        return ipv4WithPort[1];
+    return null;
+};
+/**
+ * Returns the first value when a header can be `string | string[]`.
+ */
+const pickFirstHeaderValue = (value) => Array.isArray(value) ? value[0] : value;
+/**
+ * Parses `x-forwarded-for` into an ordered list of candidates.
+ *
+ * @param value - Raw `x-forwarded-for` header value.
+ * @returns A trimmed list of forwarded addresses.
+ */
+const parseForwardedFor = (value) => {
+    const firstValue = pickFirstHeaderValue(value);
+    if (!firstValue)
+        return [];
+    return firstValue
+        .split(",")
+        .map(item => item.trim())
+        .filter(Boolean);
+};
+/**
+ * Builds the default key generator used by the rate limiter.
+ *
+ * Behavior:
+ * - `trustProxy: false` -> uses only socket `remoteAddress` (plus host fallback).
+ * - `trustProxy: true` -> allows proxy headers in this priority:
+ *   1) `cf-connecting-ip`
+ *   2) `x-real-ip`
+ *   3) first valid item in `x-forwarded-for`
+ *   4) socket `remoteAddress` fallback
+ *
+ * @param trustProxy - Whether proxy headers are trusted.
+ * @returns A key generator function for rate-limit identity.
+ */
+const buildDefaultKeyGenerator = (trustProxy) => (context) => {
+    const remoteAddress = normalizeAddress(context.remoteAddress);
+    if (!trustProxy)
+        return remoteAddress ?? context.headers.host ?? "anonymous";
+    const cfIp = normalizeAddress(pickFirstHeaderValue(context.headers["cf-connecting-ip"]));
+    if (cfIp)
         return cfIp;
-    return request.headers.host ?? "anonymous";
+    const realIp = normalizeAddress(pickFirstHeaderValue(context.headers["x-real-ip"]));
+    if (realIp)
+        return realIp;
+    const forwardedCandidates = parseForwardedFor(context.headers["x-forwarded-for"]);
+    for (const candidate of forwardedCandidates) {
+        const trustedIp = normalizeAddress(candidate);
+        if (trustedIp)
+            return trustedIp;
+    }
+    return remoteAddress ?? context.headers.host ?? "anonymous";
 };
 /**
  * Generates HTTP headers describing the current rate limit state.
@@ -112,46 +223,44 @@ const getRateLimitHeaders = (limit, current, resetTime, now, includeStandardHead
  * ]);
  */
 const rateLimit = (options = {}) => {
+    const trustProxy = options.trustProxy ?? false;
+    const memoryStoreMaxKeys = Math.max(options.maxKeys ?? 50_000, 1);
+    const store = options.store ?? new MemoryRateLimitStore(memoryStoreMaxKeys);
     const config = {
         windowMs: options.windowMs ?? 60_000,
         max: options.max ?? 5,
         message: options.message ?? "Too many requests, please try again later.",
         statusCode: options.statusCode ?? 429,
-        keyGenerator: options.keyGenerator ?? defaultKeyGenerator,
+        keyGenerator: options.keyGenerator ?? buildDefaultKeyGenerator(trustProxy),
         skip: options.skip,
         standardHeaders: options.standardHeaders ?? true,
         legacyHeaders: options.legacyHeaders ?? false,
         handler: options.handler,
     };
-    const store = new Map();
-    return async (request, next) => {
-        if (config.skip && (await config.skip(request))) {
-            return next(request);
+    const cleanupIntervalMs = Math.max(options.cleanupIntervalMs ?? config.windowMs, 1000);
+    let nextCleanupAt = Date.now() + cleanupIntervalMs;
+    return async (context, next) => {
+        if (config.skip && (await config.skip(context))) {
+            return next(context);
         }
         const now = Date.now();
-        const key = config.keyGenerator(request);
-        const current = store.get(key);
-        if (!current || now > current.resetTime) {
-            store.set(key, {
-                count: 1,
-                resetTime: now + config.windowMs,
-            });
-        }
-        else {
-            current.count += 1;
+        if (now >= nextCleanupAt && store.cleanup) {
+            await store.cleanup(now);
+            nextCleanupAt = now + cleanupIntervalMs;
         }
-        const entry = store.get(key);
+        const key = config.keyGenerator(context) || "anonymous";
+        const entry = await store.increment(key, config.windowMs, now);
         const headers = getRateLimitHeaders(config.max, entry.count, entry.resetTime, now, config.standardHeaders, config.legacyHeaders);
         if (entry.count > config.max) {
             const retryAfter = Math.max(Math.ceil((entry.resetTime - now) / 1000), 0);
             headers["Retry-After"] = String(retryAfter);
             const blockedResponse = config.handler
-                ? await config.handler(request)
+                ? await config.handler(context)
                 : http_1.Response.json(new httpExceptions_1.TooManyRequestsError(config.message).toJSON()).setStatusCode(config.statusCode);
             blockedResponse.setHeaders(headers);
             return blockedResponse;
         }
-        const response = await next(request);
+        const response = await next(context);
         response.setHeaders(headers);
         return response;
     };

package/dist/middlewares/session.js

@@ -68,17 +68,17 @@ const sessions = (StorageClass, options = {}) => {
             path: options.cookie?.path ?? "/",
         },
     };
-    return async (request, next) => {
-        const cookies = (0, cookies_1.parseCookies)(request.headers.cookie);
+    return async (context, next) => {
+        const cookies = (0, cookies_1.parseCookies)(context.headers.cookie);
         const sessionIdFromCookie = cookies[config.name];
         const storage = new StorageClass(config.cookie.maxAge);
         await loadSessionFromCookie(storage, sessionIdFromCookie);
         const session = new sessions_1.Session(storage);
-        request.setSession(session);
+        context.req.setSession(session);
         const sessionIdBefore = storage.id();
         if (!sessionIdBefore && config.saveUninitialized)
             await storage.start();
-        const response = await next(request);
+        const response = await next(context);
         const sessionIdAfter = storage.id();
         if (sessionIdAfter && config.rolling)
             await storage.touch();

package/dist/routing/routeResolveFunc.d.ts

@@ -0,0 +1,10 @@
+import type { HandlerOrMiddlewares, RouteHandler, Middleware } from "../types";
+/**
+ * Normalizes route registration args to support both signatures:
+ * - (path, action, middlewares?)
+ * - (path, middlewares, action)
+ */
+export declare const normalizeRouteArgs: (handlerOrMiddlewares: HandlerOrMiddlewares, handler?: RouteHandler) => {
+    action: RouteHandler;
+    middlewares: Middleware[];
+};

package/dist/routing/routeResolveFunc.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeRouteArgs = void 0;
+/**
+ * Normalizes route registration args to support both signatures:
+ * - (path, action, middlewares?)
+ * - (path, middlewares, action)
+ */
+const normalizeRouteArgs = (handlerOrMiddlewares, handler) => {
+    if (Array.isArray(handlerOrMiddlewares)) {
+        return {
+            action: handler,
+            middlewares: handlerOrMiddlewares,
+        };
+    }
+    return {
+        action: handlerOrMiddlewares,
+        middlewares: Array.isArray(handler) ? handler : [],
+    };
+};
+exports.normalizeRouteArgs = normalizeRouteArgs;

package/dist/routing/router.d.ts

@@ -1,5 +1,5 @@
 import type { Middleware, RouteHandler } from "../types";
-import { Request, Response } from "../http";
+import { Context, Response } from "../http";
 import { Layer } from "./layer";
 import { RouterGroup } from "./routerGroup";
 /**
@@ -26,7 +26,7 @@ export declare class Router {
      * @returns The matching {@link Layer}
      * @throws {HttpNotFoundException} If no route matches
      */
-    resolveLayer(request: Request): Layer;
+    resolveLayer(context: Context): Layer;
     /**
      * Resolves and executes a request.
      *
@@ -39,14 +39,15 @@ export declare class Router {
      * @param request - Request to process
      * @returns The handler/middleware response (sync or async)
      */
-    resolve(request: Request): Promise<Response> | Response;
+    resolve(request: Context): Promise<Response> | Response;
+    private ensureContext;
     /**
      * Runs a middleware chain using the onion model.
      *
-     * Each middleware receives `(request, next)` and can run code
+     * Each middleware receives `(context, next)` and can run code
      * before/after calling `next()`.
      *
-     * @param request - Incoming request
+     * @param context - Incoming context
      * @param middlewares - Remaining middlewares to execute
      * @param target - Final route handler
      * @returns The response returned by a middleware or the final handler
@@ -87,13 +88,18 @@ export declare class Router {
      */
     middlewares(middlewares: Middleware[]): this;
     /** Registers a GET route. */
-    get(path: string, action: RouteHandler, middlewares?: Middleware[]): Layer;
+    get(path: string, action: RouteHandler): Layer;
+    get(path: string, middlewares: Middleware[], action: RouteHandler): Layer;
     /** Registers a POST route. */
-    post(path: string, action: RouteHandler, middlewares?: Middleware[]): Layer;
+    post(path: string, action: RouteHandler): Layer;
+    post(path: string, middlewares: Middleware[], action: RouteHandler): Layer;
     /** Registers a PATCH route. */
-    patch(path: string, action: RouteHandler, middlewares?: Middleware[]): Layer;
+    patch(path: string, action: RouteHandler): Layer;
+    patch(path: string, middlewares: Middleware[], action: RouteHandler): Layer;
     /** Registers a PUT route. */
-    put(path: string, action: RouteHandler, middlewares?: Middleware[]): Layer;
+    put(path: string, action: RouteHandler): Layer;
+    put(path: string, middlewares: Middleware[], action: RouteHandler): Layer;
     /** Registers a DELETE route. */
-    delete(path: string, action: RouteHandler, middlewares?: Middleware[]): Layer;
+    delete(path: string, action: RouteHandler): Layer;
+    delete(path: string, middlewares: Middleware[], action: RouteHandler): Layer;
 }

package/dist/routing/router.js

@@ -6,6 +6,7 @@ const httpExceptions_1 = require("../exceptions/httpExceptions");
 const layer_1 = require("./layer");
 const routerGroup_1 = require("./routerGroup");
 const buildFullPath_1 = require("./buildFullPath");
+const routeResolveFunc_1 = require("./routeResolveFunc");
 /**
  * Central routing system of the framework.
  *
@@ -34,10 +35,10 @@ class Router {
      * @returns The matching {@link Layer}
      * @throws {HttpNotFoundException} If no route matches
      */
-    resolveLayer(request) {
-        const routes = this.routes[request.method];
+    resolveLayer(context) {
+        const routes = this.routes[context.req.method];
         for (const route of routes) {
-            if (route.matches(request.url))
+            if (route.matches(context.req.url))
                 return route;
         }
         throw new httpExceptions_1.NotFoundError("Route not found");
@@ -55,38 +56,44 @@ class Router {
      * @returns The handler/middleware response (sync or async)
      */
     resolve(request) {
-        const executeLayer = (req) => {
-            const layer = this.resolveLayer(req);
+        const context = this.ensureContext(request);
+        const executeLayer = (ctx) => {
+            const layer = this.resolveLayer(ctx);
             if (layer.hasParameters()) {
-                req.setParams(layer.parseParameters(req.url));
+                ctx.req.setParams(layer.parseParameters(ctx.req.url));
             }
             const action = layer.getAction;
             const routeMiddlewares = layer.getMiddlewares;
             if (routeMiddlewares.length > 0) {
-                return this.runMiddlewares(req, routeMiddlewares, action);
+                return this.runMiddlewares(ctx, routeMiddlewares, action);
             }
-            return action(req);
+            return action(ctx);
         };
         if (this.globalMiddlewares.length > 0) {
-            return this.runMiddlewares(request, this.globalMiddlewares, executeLayer);
+            return this.runMiddlewares(context, this.globalMiddlewares, executeLayer);
         }
-        return executeLayer(request);
+        return executeLayer(context);
+    }
+    ensureContext(request) {
+        if (request instanceof http_1.Context)
+            return request;
+        return new http_1.Context(request);
     }
     /**
      * Runs a middleware chain using the onion model.
      *
-     * Each middleware receives `(request, next)` and can run code
+     * Each middleware receives `(context, next)` and can run code
      * before/after calling `next()`.
      *
-     * @param request - Incoming request
+     * @param context - Incoming context
      * @param middlewares - Remaining middlewares to execute
      * @param target - Final route handler
      * @returns The response returned by a middleware or the final handler
      */
-    runMiddlewares(request, middlewares, target) {
+    runMiddlewares(context, middlewares, target) {
         if (middlewares.length === 0)
-            return target(request);
-        return middlewares[0](request, request => this.runMiddlewares(request, middlewares.slice(1), target));
+            return target(context);
+        return middlewares[0](context, nextContext => this.runMiddlewares(this.ensureContext(nextContext), middlewares.slice(1), target));
     }
     /**
      * Registers a route and returns the created {@link Layer}.
@@ -138,24 +145,24 @@ class Router {
         this.globalMiddlewares.push(...middlewares);
         return this;
     }
-    /** Registers a GET route. */
-    get(path, action, middlewares) {
+    get(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
         return this.registerRoute(http_1.HttpMethods.get, path, action, middlewares);
     }
-    /** Registers a POST route. */
-    post(path, action, middlewares) {
+    post(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
         return this.registerRoute(http_1.HttpMethods.post, path, action, middlewares);
     }
-    /** Registers a PATCH route. */
-    patch(path, action, middlewares) {
+    patch(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
         return this.registerRoute(http_1.HttpMethods.patch, path, action, middlewares);
     }
-    /** Registers a PUT route. */
-    put(path, action, middlewares) {
+    put(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
         return this.registerRoute(http_1.HttpMethods.put, path, action, middlewares);
     }
-    /** Registers a DELETE route. */
-    delete(path, action, middlewares) {
+    delete(path, handlerOrMiddlewares, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddlewares, handler);
         return this.registerRoute(http_1.HttpMethods.delete, path, action, middlewares);
     }
 }

package/dist/routing/routerGroup.d.ts

@@ -51,13 +51,18 @@ export declare class RouterGroup {
      */
     private addRoute;
     /** Registers a GET route within the group. */
-    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 within the group. */
-    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 within the group. */
-    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 within the group. */
-    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 within the group. */
-    delete(path: string, action: RouteHandler, middlewares?: Middleware[]): void;
+    delete(path: string, action: RouteHandler): void;
+    delete(path: string, middlewares: Middleware[], action: RouteHandler): void;
 }

package/dist/routing/routerGroup.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RouterGroup = void 0;
 const buildFullPath_1 = require("./buildFullPath");
+const routeResolveFunc_1 = require("./routeResolveFunc");
 /**
  * Route group helper.
  *
@@ -64,24 +65,24 @@ class RouterGroup {
         if (totalMiddlewares.length > 0)
             layer.setMiddlewares(totalMiddlewares);
     }
-    /** Registers a GET route within the group. */
-    get(path, action, middlewares) {
+    get(path, handlerOrMiddleware, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddleware, handler);
         this.addRoute("get", path, action, middlewares);
     }
-    /** Registers a POST route within the group. */
-    post(path, action, middlewares) {
+    post(path, handlerOrMiddleware, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddleware, handler);
         this.addRoute("post", path, action, middlewares);
     }
-    /** Registers a PUT route within the group. */
-    put(path, action, middlewares) {
+    put(path, handlerOrMiddleware, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddleware, handler);
         this.addRoute("put", path, action, middlewares);
     }
-    /** Registers a PATCH route within the group. */
-    patch(path, action, middlewares) {
+    patch(path, handlerOrMiddleware, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddleware, handler);
         this.addRoute("patch", path, action, middlewares);
     }
-    /** Registers a DELETE route within the group. */
-    delete(path, action, middlewares) {
+    delete(path, handlerOrMiddleware, handler) {
+        const { action, middlewares } = (0, routeResolveFunc_1.normalizeRouteArgs)(handlerOrMiddleware, handler);
         this.addRoute("delete", path, action, middlewares);
     }
 }

package/dist/storage/storage.d.ts

@@ -1,6 +1,6 @@
 import { type Storage, type StorageOptions } from "./types";
-import { Request } from "../http/request";
 import type { UploadedFile } from "../parsers/parserInterface";
+import { Context } from "../http/context";
 /**
  * Disk-based storage engine responsible for persisting uploaded files
  * to the local filesystem.
@@ -51,7 +51,7 @@ export declare class DiskStorage implements Storage {
      *
      * @throws UploadException if the file cannot be written to disk.
      */
-    handleFile(request: Request, file: Partial<UploadedFile>, fileData: Buffer): Promise<UploadedFile>;
+    handleFile(context: Context, file: Partial<UploadedFile>, fileData: Buffer): Promise<UploadedFile>;
     /**
      * Removes a previously stored file from disk.
      *
@@ -99,6 +99,6 @@ export declare class MemoryStorage implements Storage {
     private ttlMs;
     private computeChecksum;
     constructor(options?: StorageOptions);
-    handleFile(request: Request, file: Partial<UploadedFile>, fileData: Buffer): UploadedFile;
+    handleFile(context: Context, file: Partial<UploadedFile>, fileData: Buffer): UploadedFile;
     removeFile(file: UploadedFile): void;
 }

package/dist/storage/storage.js

@@ -60,10 +60,10 @@ class DiskStorage {
      *
      * @throws UploadException if the file cannot be written to disk.
      */
-    async handleFile(request, file, fileData) {
+    async handleFile(context, file, fileData) {
         try {
-            const destination = await this.resolveDestination(request, file);
-            const filename = await this.filenameGenerator(request, file);
+            const destination = await this.resolveDestination(context, file);
+            const filename = await this.filenameGenerator(context, file);
             const filePath = (0, node_path_1.join)(destination, filename);
             await (0, promises_1.mkdir)(destination, { recursive: true });
             await (0, promises_1.writeFile)(filePath, fileData);
@@ -102,9 +102,9 @@ class DiskStorage {
      * If a resolver function was provided, it will be executed.
      * Otherwise the static directory is returned.
      */
-    async resolveDestination(request, file) {
+    async resolveDestination(context, file) {
         if (typeof this.destination === "function") {
-            return await this.destination(request, file);
+            return await this.destination(context, file);
         }
         return this.destination;
     }
@@ -119,7 +119,7 @@ class DiskStorage {
      * Example:
      *  1700000000000-a3f9b1c2d4e5f678.png
      */
-    generateUniqueFilename(request, file) {
+    generateUniqueFilename(context, file) {
         const timestamp = Date.now();
         const randomString = (0, node_crypto_1.randomBytes)(8).toString("hex");
         const ext = (0, node_path_1.extname)(file.originalname || "");
@@ -151,7 +151,7 @@ class MemoryStorage {
         this.ttlMs = options.memory.ttlMs ?? 0;
         this.computeChecksum = options.memory.computeChecksum ?? false;
     }
-    handleFile(request, file, fileData) {
+    handleFile(context, file, fileData) {
         // Enforce per-file size if configured
         if (this.maxFileSize !== undefined && fileData.length > this.maxFileSize) {
             throw new uploadException_1.UploadException(`File too large. Max size: ${this.maxFileSize} bytes`, types_1.UploadErrorCode.LIMIT_FILE_SIZE, file.fieldName);

package/dist/storage/types.d.ts

@@ -1,5 +1,5 @@
 import type { UploadedFile } from "../parsers/parserInterface";
-import { Request } from "../http/request";
+import { Context } from "../http/context";
 /**
  * Available storage engine types.
  *
@@ -35,12 +35,12 @@ interface DiskStorageOptions {
      * Destination directory or resolver function.
      * If a function is provided, it receives the request and file metadata.
      */
-    destination?: string | ((req: Request, file: Partial<UploadedFile>) => string | Promise<string>);
+    destination?: string | ((ctx: Context, file: Partial<UploadedFile>) => string | Promise<string>);
     /**
      * Custom filename generator.
      * Receives the request and partial file metadata.
      */
-    filename?: (req: Request, file: Partial<UploadedFile>) => string | Promise<string>;
+    filename?: (ctx: Context, file: Partial<UploadedFile>) => string | Promise<string>;
 }
 interface MemoryStoreOptions {
     /** Maximum total bytes allowed to be stored in memory (default: 50MB) */
@@ -76,7 +76,7 @@ export interface Storage {
      * @param fileData Raw file buffer.
      * @returns Final uploaded file metadata.
      */
-    handleFile(request: Request, file: Partial<UploadedFile>, fileData: Buffer): Promise<UploadedFile> | UploadedFile;
+    handleFile(context: Context, file: Partial<UploadedFile>, fileData: Buffer): Promise<UploadedFile> | UploadedFile;
     /**
      * Removes a stored file.
      *
@@ -99,7 +99,7 @@ export type FileFilterCallback = (error: Error | null, acceptFile: boolean) => v
  *
  * The callback must be invoked to accept or reject the file.
  */
-export type FileFilter = (request: Request, file: Partial<UploadedFile>, callback: FileFilterCallback) => void | Promise<void>;
+export type FileFilter = (context: Context, file: Partial<UploadedFile>, callback: FileFilterCallback) => void | Promise<void>;
 /**
  * Global uploader configuration.
  */