@zenofolio/hyper-decor 1.0.7 → 1.0.8

package/dist/lib/openapi/decorators.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiSummary = ApiSummary;
+exports.ApiDescription = ApiDescription;
+exports.ApiOperationId = ApiOperationId;
+exports.ApiTag = ApiTag;
+exports.ApiResponse = ApiResponse;
+exports.ApiParameter = ApiParameter;
+exports.ApiRequestBody = ApiRequestBody;
+exports.ApiSecurity = ApiSecurity;
+exports.ApiBearerAuth = ApiBearerAuth;
+exports.ApiMethod = ApiMethod;
+exports.ApiNamespace = ApiNamespace;
+exports.ApiIgnore = ApiIgnore;
+const metadata_1 = require("./metadata");
+/**
+ * 📝 OpenAPI Decorators consolidated for better performance and clean imports.
+ */
+function ApiSummary(summary) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { summary });
+    };
+}
+function ApiDescription(description) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { description });
+    };
+}
+function ApiOperationId(operationId) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { operationId });
+    };
+}
+function ApiTag(options) {
+    const tag = typeof options === 'string' ? { name: options } : options;
+    return (target, propertyKey) => {
+        if (propertyKey) {
+            const current = metadata_1.SwaggerMeta.get(target, propertyKey);
+            const tags = [...(current.tags || []), tag];
+            // Use Map to deduplicate by name
+            const uniqueTags = Array.from(new Map(tags.map(t => [t.name, t])).values());
+            metadata_1.SwaggerMeta.set(target, propertyKey, { tags: uniqueTags });
+        }
+        else {
+            const current = metadata_1.SwaggerMeta.get(target);
+            const tags = [...(current.tags || []), tag];
+            const uniqueTags = Array.from(new Map(tags.map(t => [t.name, t])).values());
+            metadata_1.SwaggerMeta.set(target, undefined, { tags: uniqueTags });
+        }
+    };
+}
+function ApiResponse(options) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { responses: options });
+    };
+}
+function ApiParameter(options) {
+    return (target, propertyKey) => {
+        const current = metadata_1.SwaggerMeta.get(target, propertyKey);
+        const parameters = [...(current.parameters || []), options];
+        metadata_1.SwaggerMeta.set(target, propertyKey, { parameters });
+    };
+}
+function ApiRequestBody(options) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { requestBody: options });
+    };
+}
+function ApiSecurity(options) {
+    return (target, propertyKey) => {
+        const current = metadata_1.SwaggerMeta.get(target, propertyKey);
+        const security = [...(current.security || []), options];
+        metadata_1.SwaggerMeta.set(target, propertyKey, { security });
+    };
+}
+function ApiBearerAuth(name = 'bearerAuth') {
+    return ApiSecurity({ [name]: [] });
+}
+function ApiMethod(options) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, options);
+    };
+}
+function ApiNamespace(name) {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { namespace: name });
+    };
+}
+function ApiIgnore() {
+    return (target, propertyKey) => {
+        metadata_1.SwaggerMeta.set(target, propertyKey, { ignore: true });
+    };
+}

package/dist/lib/openapi/index.d.ts

@@ -1,6 +1,30 @@
-export * from "./metadata.registry";
-export * from "./constants";
-export * from "./collectors";
-export * from "./decorators";
-export * from "./helpers";
 export * from "./types";
+import { ApiBearerAuth, ApiDescription, ApiOperationId, ApiParameter, ApiRequestBody, ApiResponse, ApiSecurity, ApiSummary, ApiTag, ApiMethod, ApiNamespace, ApiIgnore } from "./decorators";
+export declare const OpenApi: {
+    Summary: typeof ApiSummary;
+    Description: typeof ApiDescription;
+    OperationId: typeof ApiOperationId;
+    Tag: typeof ApiTag;
+    Response: typeof ApiResponse;
+    Parameter: typeof ApiParameter;
+    RequestBody: typeof ApiRequestBody;
+    Security: typeof ApiSecurity;
+    BearerAuth: typeof ApiBearerAuth;
+    Method: typeof ApiMethod;
+    Namespace: typeof ApiNamespace;
+    Ignore: typeof ApiIgnore;
+};
+export { ApiBearerAuth, ApiDescription, ApiOperationId, ApiParameter, ApiRequestBody, ApiResponse, ApiSecurity, ApiSummary, ApiTag, ApiMethod, ApiNamespace, ApiIgnore, };
+import { Constructor } from "../server/decorators/types";
+import { OpenAPIDocument } from "./types";
+/**
+ * Generates an OpenAPI specification object from a HyperApp class.
+ *
+ * @param App The Root Application Class
+ * @param options Generator options
+ * @returns OpenAPI Spec Object
+ */
+export declare function getOpenAPI(App: Constructor, options?: {
+    includeNamespaces?: string[];
+    excludeNamespaces?: string[];
+}): OpenAPIDocument;

package/dist/lib/openapi/index.js

@@ -14,9 +14,123 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./metadata.registry"), exports);
-__exportStar(require("./constants"), exports);
-__exportStar(require("./collectors"), exports);
-__exportStar(require("./decorators"), exports);
-__exportStar(require("./helpers"), exports);
+exports.ApiIgnore = exports.ApiNamespace = exports.ApiMethod = exports.ApiTag = exports.ApiSummary = exports.ApiSecurity = exports.ApiResponse = exports.ApiRequestBody = exports.ApiParameter = exports.ApiOperationId = exports.ApiDescription = exports.ApiBearerAuth = exports.OpenApi = void 0;
+exports.getOpenAPI = getOpenAPI;
 __exportStar(require("./types"), exports);
+const decorators_1 = require("./decorators");
+Object.defineProperty(exports, "ApiBearerAuth", { enumerable: true, get: function () { return decorators_1.ApiBearerAuth; } });
+Object.defineProperty(exports, "ApiDescription", { enumerable: true, get: function () { return decorators_1.ApiDescription; } });
+Object.defineProperty(exports, "ApiOperationId", { enumerable: true, get: function () { return decorators_1.ApiOperationId; } });
+Object.defineProperty(exports, "ApiParameter", { enumerable: true, get: function () { return decorators_1.ApiParameter; } });
+Object.defineProperty(exports, "ApiRequestBody", { enumerable: true, get: function () { return decorators_1.ApiRequestBody; } });
+Object.defineProperty(exports, "ApiResponse", { enumerable: true, get: function () { return decorators_1.ApiResponse; } });
+Object.defineProperty(exports, "ApiSecurity", { enumerable: true, get: function () { return decorators_1.ApiSecurity; } });
+Object.defineProperty(exports, "ApiSummary", { enumerable: true, get: function () { return decorators_1.ApiSummary; } });
+Object.defineProperty(exports, "ApiTag", { enumerable: true, get: function () { return decorators_1.ApiTag; } });
+Object.defineProperty(exports, "ApiMethod", { enumerable: true, get: function () { return decorators_1.ApiMethod; } });
+Object.defineProperty(exports, "ApiNamespace", { enumerable: true, get: function () { return decorators_1.ApiNamespace; } });
+Object.defineProperty(exports, "ApiIgnore", { enumerable: true, get: function () { return decorators_1.ApiIgnore; } });
+exports.OpenApi = {
+    Summary: decorators_1.ApiSummary,
+    Description: decorators_1.ApiDescription,
+    OperationId: decorators_1.ApiOperationId,
+    Tag: decorators_1.ApiTag,
+    Response: decorators_1.ApiResponse,
+    Parameter: decorators_1.ApiParameter,
+    RequestBody: decorators_1.ApiRequestBody,
+    Security: decorators_1.ApiSecurity,
+    BearerAuth: decorators_1.ApiBearerAuth,
+    Method: decorators_1.ApiMethod,
+    Namespace: decorators_1.ApiNamespace,
+    Ignore: decorators_1.ApiIgnore,
+};
+const tree_1 = require("../tree/tree");
+const metadata_registry_1 = require("./metadata.registry");
+// --- Registration ---
+const collectors_1 = require("./collectors");
+metadata_registry_1.openApiRegistry.registerCollector("class", collectors_1.collectClassMetadata);
+metadata_registry_1.openApiRegistry.registerCollector("method", collectors_1.collectMethodMetadata);
+/**
+ * Generates an OpenAPI specification object from a HyperApp class.
+ *
+ * @param App The Root Application Class
+ * @param options Generator options
+ * @returns OpenAPI Spec Object
+ */
+function getOpenAPI(App, options = {}) {
+    const tree = (0, tree_1.getAppTree)(App);
+    const spec = {
+        openapi: "3.0.0",
+        info: {
+            title: tree.app.name || "HyperApp API",
+            version: tree.app.version || "1.0.0",
+        },
+        paths: {},
+    };
+    const processController = (ctrl, parentNamespace) => {
+        const ctrlOpenApi = ctrl.openapi;
+        if (ctrlOpenApi === null || ctrlOpenApi === void 0 ? void 0 : ctrlOpenApi.ignore)
+            return;
+        const ctrlNamespace = (ctrlOpenApi === null || ctrlOpenApi === void 0 ? void 0 : ctrlOpenApi.namespace) || parentNamespace;
+        ctrl.routes.forEach((route) => {
+            var _a, _b;
+            const routeOpenApi = route.openapi;
+            if (!routeOpenApi || routeOpenApi.ignore)
+                return;
+            const path = normalizePath(route.fullPath);
+            if (!spec.paths[path])
+                spec.paths[path] = {};
+            const methodNamespace = routeOpenApi.namespace || ctrlNamespace;
+            // Filtering logic
+            if (options.includeNamespaces && options.includeNamespaces.length > 0) {
+                if (!methodNamespace || !options.includeNamespaces.includes(methodNamespace))
+                    return;
+            }
+            if (options.excludeNamespaces && options.excludeNamespaces.length > 0) {
+                if (methodNamespace && options.excludeNamespaces.includes(methodNamespace))
+                    return;
+            }
+            // --- Merge Metadata Inheritance ---
+            const ctrlData = (ctrl.openapi || {});
+            const finalOperation = Object.assign(Object.assign(Object.assign({ responses: {} }, ctrlData), routeOpenApi), { 
+                // Merge Tags (unique by name)
+                tags: Array.from(new Map([
+                    ...(ctrlData.tags || []).map(t => [t.name, t]),
+                    ...(routeOpenApi.tags || []).map(t => [t.name, t])
+                ]).values()), 
+                // Merge Security (additive)
+                security: [
+                    ...(ctrlData.security || []),
+                    ...(routeOpenApi.security || [])
+                ] });
+            // Remove empty fields to keep spec clean
+            if (((_a = finalOperation.tags) === null || _a === void 0 ? void 0 : _a.length) === 0)
+                delete finalOperation.tags;
+            if (((_b = finalOperation.security) === null || _b === void 0 ? void 0 : _b.length) === 0)
+                delete finalOperation.security;
+            spec.paths[path] = Object.assign(Object.assign({}, spec.paths[path]), { [route.method.toLowerCase()]: finalOperation });
+        });
+        // Clean up empty paths if all methods were filtered out
+        Object.keys(spec.paths).forEach(path => {
+            if (Object.keys(spec.paths[path]).length === 0) {
+                delete spec.paths[path];
+            }
+        });
+    };
+    function normalizePath(path) {
+        let normalized = path.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+        // Remove trailing slash if it's not the root path
+        if (normalized.length > 1 && normalized.endsWith('/')) {
+            normalized = normalized.slice(0, -1);
+        }
+        return normalized;
+    }
+    const processModule = (mod) => {
+        var _a;
+        const modNamespace = (_a = mod.openapi) === null || _a === void 0 ? void 0 : _a.namespace;
+        Object.values(mod.controllers).forEach(ctrl => processController(ctrl, modNamespace));
+        Object.values(mod.modules).forEach(processModule);
+    };
+    Object.values(tree.modules).forEach(processModule);
+    return spec;
+}

package/dist/lib/openapi/metadata.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 🚀 Metadata accessor for OpenAPI/Swagger documentation
+ */
+export declare const SwaggerMeta: {
+    set: (target: object, propertyKey: any, data: object) => void;
+    get: (target: object, propertyKey?: any) => object;
+};

package/dist/lib/openapi/metadata.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwaggerMeta = void 0;
+const meta_store_1 = require("../../__internals/stores/meta.store");
+/**
+ * 🚀 Metadata accessor for OpenAPI/Swagger documentation
+ */
+exports.SwaggerMeta = meta_store_1.Metadata.prefix('hyper:openapi');

package/dist/lib/openapi/metadata.registry.d.ts

@@ -1,4 +1,4 @@
-import { AppTree } from "../../__internals/helpers/tree.helper";
+import { AppTree } from "../tree/tree";
 export type CollectorType = "class" | "method" | "param";
 export type CollectorFn = (target: any, propertyKey?: string) => any;
 export type TreeProcessorFn = (tree: AppTree) => void;

package/dist/lib/server/decorators/File.d.ts

@@ -0,0 +1,37 @@
+import { Request } from "hyper-express/types";
+/**
+ * File upload restrictions
+ */
+export interface FileUploadRestrictions {
+    allowedMimeTypes: string[];
+    maxFileSize: number;
+}
+/**
+ * File restrictions resolver
+ */
+export type FileRestrictions = FileUploadRestrictions | ((request: Request) => FileUploadRestrictions | Promise<FileUploadRestrictions>);
+/**
+ * File decorator options
+ */
+export interface FileOptions {
+    fieldName: string | string[];
+    restrictions?: FileRestrictions;
+    required?: boolean;
+}
+export interface UploadedFile {
+    field: string;
+    name: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    extension: string;
+    buffer: Buffer;
+}
+/**
+ * Decorator to extract file from the request
+ */
+export declare const File: {
+    (options: FileOptions | string): (target: object, propertyKey: string | symbol, index: number) => void;
+    options(options: FileOptions, required?: boolean): (fieldName: string | string[]) => (target: object, propertyKey: string | symbol, index: number) => void;
+    restrictions(restrictions: FileRestrictions): (fieldName: string | string[], required?: boolean) => (target: object, propertyKey: string | symbol, index: number) => void;
+};

package/dist/{decorators → lib/server/decorators}/File.js

@@ -8,46 +8,37 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.File = void 0;
 const Http_1 = require("./Http");
-const consumers_1 = require("stream/consumers");
 const HyperFileException_1 = __importDefault(require("../exeptions/HyperFileException"));
 /**
  * Decorator to extract file from the request
- *
- * @param param0
  */
 const File = (options) => {
     const _options = typeof options === "string" ? { fieldName: options } : options;
     return (0, Http_1.createCustomRequestDecorator)("File", (request) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a, _b;
+        var _a;
         const { allowedMimeTypes, maxFileSize } = yield resolveRestrictions(request, _options.restrictions);
         const passTypes = allowedMimeTypes.includes("*") || allowedMimeTypes.length === 0;
         const passSize = maxFileSize === Infinity;
         const contentType = (_a = request.headers) === null || _a === void 0 ? void 0 : _a["content-type"];
-        const fileSize = Number((_b = request.headers) === null || _b === void 0 ? void 0 : _b["content-length"]);
         const isMultipart = contentType === null || contentType === void 0 ? void 0 : contentType.includes("multipart/form-data");
         if (!isMultipart) {
             throw new HyperFileException_1.default("Invalid request, expected multipart form data", {
                 fieldName: _options.fieldName,
             });
         }
-        if (isNaN(fileSize) || fileSize <= 0) {
-            throw new HyperFileException_1.default(`File ${_options.fieldName} is missing or empty`, {
-                fieldName: _options.fieldName,
-                fileSize,
-            });
-        }
-        if (!passSize && fileSize > maxFileSize) {
-            throw new HyperFileException_1.default(`File ${_options.fieldName} is too large. Max size is ${maxFileSize} bytes`, {
-                fieldName: _options.fieldName,
-                maxFileSize,
-            });
-        }
         const files = yield extractFiles(request, {
             maxSize: passSize ? undefined : maxFileSize,
             mimeTypes: passTypes ? undefined : allowedMimeTypes,
@@ -64,35 +55,16 @@ const File = (options) => {
     }));
 };
 exports.File = File;
-/**
- *
- * Helper function to create a file decorator with options
- *
- * @param options
- * @returns
- */
 exports.File.options = (options, required = false) => {
     return (fieldName) => {
         return (0, exports.File)(Object.assign(Object.assign({}, options), { required, fieldName }));
     };
 };
-/**
- * Helper function to create a file decorator with restrictions
- *
- * @param restrictions
- * @returns
- */
 exports.File.restrictions = (restrictions) => {
     return (fieldName, required = false) => {
         return (0, exports.File)({ fieldName, restrictions, required });
     };
 };
-/////////////////////////////
-// Types
-/////////////////////////////
-/////////////////////////////
-/// Utility
-/////////////////////////////
 const resolveRestrictions = (request, restrictions) => __awaiter(void 0, void 0, void 0, function* () {
     if (typeof restrictions === "function") {
         return yield restrictions(request);
@@ -103,63 +75,78 @@ const resolveRestrictions = (request, restrictions) => __awaiter(void 0, void 0,
     });
 });
 /**
- * Extract files from a request with validation, transformation, and required files check.
- *
- * @param request
- * @param options Validation and transformation options
- * @returns Transformed or raw file details
+ * Extract files from a request with validation and secure streaming.
  */
 const extractFiles = (request, options) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
-    const contentType = (_a = request.headers) === null || _a === void 0 ? void 0 : _a["content-type"];
-    if (!(contentType === null || contentType === void 0 ? void 0 : contentType.includes("multipart/form-data"))) {
-        throw new Error("Invalid request, expected multipart form data");
-    }
     const filesMap = {};
+    // Track if we are already over total limit (Content-Length check as first line of defense)
+    const totalLength = Number((_a = request.headers) === null || _a === void 0 ? void 0 : _a["content-length"]);
+    if ((options === null || options === void 0 ? void 0 : options.maxSize) && !isNaN(totalLength) && totalLength > options.maxSize + 1024 * 10) { // Buffer for boundaries
+        // Content-Length is significantly larger than allowed file size
+        // We don't throw yet because multipart might have multiple files or large fields
+    }
     yield request.multipart((field) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a, _b, _c, _d;
+        var _a, e_1, _b, _c;
+        var _d, _e;
         if (field.file && field.file.stream) {
-            const bufferFile = yield (0, consumers_1.buffer)(field.file.stream);
-            const type = yield (yield import("file-type")).fileTypeFromBuffer(bufferFile);
-            if (!type) {
-                throw new HyperFileException_1.default(`Invalid file type`, {
-                    field: field.name,
-                });
+            const chunks = [];
+            let totalRead = 0;
+            try {
+                // Safe stream reading with early exit
+                for (var _f = true, _g = __asyncValues(field.file.stream), _h; _h = yield _g.next(), _a = _h.done, !_a; _f = true) {
+                    _c = _h.value;
+                    _f = false;
+                    const chunk = _c;
+                    totalRead += chunk.length;
+                    if ((options === null || options === void 0 ? void 0 : options.maxSize) && totalRead > options.maxSize) {
+                        throw new HyperFileException_1.default(`File '${field.name}' exceeds the maximum limit of ${options.maxSize} bytes`, { field: field.name, maxSize: options.maxSize });
+                    }
+                    chunks.push(chunk);
+                }
             }
-            const mimeType = type.mime;
-            const extention = type.ext;
-            // Validate MIME type early
-            if ((options === null || options === void 0 ? void 0 : options.mimeTypes) && !options.mimeTypes.includes(mimeType)) {
-                throw new HyperFileException_1.default(`Invalid file type, only ${options.mimeTypes.join(", ")} is allowed`, {
-                    field: field.name,
-                    allowedMimeTypes: options.mimeTypes,
-                    mimeType,
-                });
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_f && !_a && (_b = _g.return)) yield _b.call(_g);
+                }
+                finally { if (e_1) throw e_1.error; }
             }
-            if (!type) {
-                throw new HyperFileException_1.default(`Invalid file type`, {
-                    field: field.name,
-                });
+            const bufferFile = Buffer.concat(chunks);
+            const { fileTypeFromBuffer } = yield import("file-type");
+            const type = yield fileTypeFromBuffer(bufferFile);
+            const mimeType = (type === null || type === void 0 ? void 0 : type.mime) || "unknown/unrecognized";
+            const extension = (type === null || type === void 0 ? void 0 : type.ext) || "bin";
+            // Validate MIME type early if unrecognized
+            if (!type && (options === null || options === void 0 ? void 0 : options.mimeTypes) && options.mimeTypes.length > 0) {
+                throw new HyperFileException_1.default(`Invalid file type for field '${field.name}'. Could not recognize file signature. Expected one of: ${options.mimeTypes.join(", ")}`, { field: field.name, allowedMimeTypes: options.mimeTypes });
             }
-            if ((options === null || options === void 0 ? void 0 : options.maxSize) && bufferFile.byteLength > options.maxSize) {
-                throw new HyperFileException_1.default(`File '${field.name}' size exceeds the maximum limit of ${options.maxSize} bytes`, {
+            // Validate MIME type if recognized
+            if ((options === null || options === void 0 ? void 0 : options.mimeTypes) && !options.mimeTypes.includes(mimeType)) {
+                throw new HyperFileException_1.default(`Invalid file type for field '${field.name}'. Expected: ${options.mimeTypes.join(", ")}, Received: ${mimeType}`, {
                     field: field.name,
-                    maxSize: options.maxSize,
+                    allowedMimeTypes: options.mimeTypes,
+                    receivedMimeType: mimeType,
                 });
             }
-            if ((options === null || options === void 0 ? void 0 : options.requireName) && !((_a = field.file) === null || _a === void 0 ? void 0 : _a.name)) {
-                throw new HyperFileException_1.default(`File name is required`, {
+            if ((options === null || options === void 0 ? void 0 : options.requireName) && !((_d = field.file) === null || _d === void 0 ? void 0 : _d.name)) {
+                throw new HyperFileException_1.default(`File name is required for field '${field.name}'`, {
                     field: field.name,
                 });
             }
-            // Derive file details
-            const name = (_d = (_c = (_b = field.file) === null || _b === void 0 ? void 0 : _b.name) === null || _c === void 0 ? void 0 : _c.split(".").shift()) !== null && _d !== void 0 ? _d : field.name;
-            const filename = `${name === null || name === void 0 ? void 0 : name.replace(extention, "")}.${extention}`;
+            // Secure filename resolution
+            const rawName = ((_e = field.file) === null || _e === void 0 ? void 0 : _e.name) || field.name;
+            // Sanitize: remove null bytes, path traversal sequences, and extract base name
+            const sanitizedBase = rawName.replace(/\0/g, "").split(/[\\/]/).pop() || "file";
+            const nameOnly = sanitizedBase.includes(".")
+                ? sanitizedBase.substring(0, sanitizedBase.lastIndexOf("."))
+                : sanitizedBase;
+            const filename = `${nameOnly}.${extension}`;
             filesMap[field.name] = {
                 field: field.name,
-                name: name,
+                name: nameOnly,
                 filename: filename,
-                ext: extention,
+                extension: extension,
                 size: bufferFile.byteLength,
                 mimeType: mimeType,
                 buffer: bufferFile,

package/dist/lib/server/decorators/Http.d.ts

@@ -0,0 +1,12 @@
+import { ParameterResolver } from "./types";
+/**
+ * 🛠️ Helper to create parameter decorators
+ */
+export declare function createParamDecorator(source: "body" | "query" | "params" | "headers" | "req" | "res", decorator: string, keyOrSchema?: string | object | Function, schemaOrTransform?: object | Function, isWholeSource?: boolean, customResolver?: ParameterResolver): (target: object, propertyKey: string | symbol, index: number) => void;
+export declare function Query(keyOrSchema?: string | object | Function, schemaOrTransform?: object | Function): (target: object, propertyKey: string | symbol, index: number) => void;
+export declare function Body(keyOrSchema?: string | object | Function, schemaOrTransform?: object | Function): (target: object, propertyKey: string | symbol, index: number) => void;
+export declare function Param(keyOrSchema: string | object | Function, schemaOrTransform?: object | Function): (target: object, propertyKey: string | symbol, index: number) => void;
+export declare function Headers(keyOrSchema?: string | object | Function, schemaOrTransform?: object | Function): (target: object, propertyKey: string | symbol, index: number) => void;
+export declare const Req: () => (target: object, propertyKey: string | symbol, index: number) => void;
+export declare const Res: () => (target: object, propertyKey: string | symbol, index: number) => void;
+export declare const createCustomRequestDecorator: (decoratorName: string, resolver: ParameterResolver) => (target: object, propertyKey: string | symbol, index: number) => void;

package/dist/lib/server/decorators/Http.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCustomRequestDecorator = exports.Res = exports.Req = void 0;
+exports.createParamDecorator = createParamDecorator;
+exports.Query = Query;
+exports.Body = Body;
+exports.Param = Param;
+exports.Headers = Headers;
+const metadata_1 = require("./metadata");
+/**
+ * 🛠️ Helper to create parameter decorators
+ */
+function createParamDecorator(source, decorator, keyOrSchema, schemaOrTransform, isWholeSource = false, customResolver) {
+    return (target, propertyKey, index) => {
+        var _a;
+        const root = metadata_1.HyperMeta.get(target, propertyKey);
+        const params = ((_a = root.params) === null || _a === void 0 ? void 0 : _a.params) || [];
+        const picker = typeof keyOrSchema === 'string' ? keyOrSchema : undefined;
+        const schema = (typeof keyOrSchema === 'object' || typeof keyOrSchema === 'function')
+            ? keyOrSchema
+            : schemaOrTransform;
+        params.push({
+            index,
+            type: (Reflect.getMetadata("design:paramtypes", target, propertyKey) || [])[index],
+            source,
+            picker,
+            schema,
+            isWholeSource: isWholeSource || (picker === undefined && keyOrSchema !== undefined),
+            decorator,
+            resolver: customResolver,
+        });
+        metadata_1.HyperMeta.set(target, propertyKey, {
+            params: { params }
+        });
+    };
+}
+function Query(keyOrSchema, schemaOrTransform) {
+    return createParamDecorator("query", "Query", keyOrSchema, schemaOrTransform);
+}
+function Body(keyOrSchema, schemaOrTransform) {
+    return createParamDecorator("body", "Body", keyOrSchema, schemaOrTransform);
+}
+function Param(keyOrSchema, schemaOrTransform) {
+    return createParamDecorator("params", "Param", keyOrSchema, schemaOrTransform);
+}
+function Headers(keyOrSchema, schemaOrTransform) {
+    return createParamDecorator("headers", "Headers", keyOrSchema, schemaOrTransform);
+}
+const Req = () => createParamDecorator("req", "Req", undefined, undefined, true, (req) => req);
+exports.Req = Req;
+const Res = () => createParamDecorator("res", "Res", undefined, undefined, true, (_req, res) => res);
+exports.Res = Res;
+const createCustomRequestDecorator = (decoratorName, resolver) => {
+    return createParamDecorator("req", decoratorName, undefined, undefined, true, resolver);
+};
+exports.createCustomRequestDecorator = createCustomRequestDecorator;

package/dist/lib/server/decorators/HyperApp.d.ts

@@ -0,0 +1,7 @@
+import { HyperAppMetadata, Constructor } from "./types";
+/**
+ * 🚀 HyperApp Decorator
+ * Purely injects metadata and a prepare method into the target class.
+ * No class wrapping or modification of the original constructor.
+ */
+export declare function HyperApp(options: HyperAppMetadata): (Target: Constructor) => void;

package/dist/lib/server/decorators/HyperApp.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HyperApp = HyperApp;
+const metadata_1 = require("./metadata");
+/**
+ * 🚀 HyperApp Decorator
+ * Purely injects metadata and a prepare method into the target class.
+ * No class wrapping or modification of the original constructor.
+ */
+function HyperApp(options) {
+    return (Target) => {
+        metadata_1.HyperMeta.set(Target, undefined, Object.assign({ type: "app" }, options));
+    };
+}

package/dist/lib/server/decorators/HyperController.d.ts

@@ -0,0 +1,6 @@
+import { HyperControllerMetadata } from "./types";
+/**
+ * 🚀 HyperController Decorator
+ * Purely injects metadata into the target class.
+ */
+export declare function HyperController(options?: HyperControllerMetadata | string): (Target: any) => void;

package/dist/lib/server/decorators/HyperController.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HyperController = HyperController;
+const metadata_1 = require("./metadata");
+/**
+ * 🚀 HyperController Decorator
+ * Purely injects metadata into the target class.
+ */
+function HyperController(options) {
+    return (Target) => {
+        const isString = typeof options === "string";
+        const data = isString ? { path: options } : (options !== null && options !== void 0 ? options : {});
+        metadata_1.HyperMeta.set(Target, undefined, Object.assign({ type: "controller" }, data));
+    };
+}