@zenofolio/hyper-decor 1.0.68 → 1.0.71

package/dist/__internals/constants.d.ts

@@ -14,8 +14,8 @@ export declare const KEY_PARAMS_MIDDLEWARES = "hyper:type:middlewares";
 export declare const KEY_PARAMS_SCOPE = "hyper:type:scope";
 export declare const KEY_PARAMS_ROLE = "hyper:type:role";
 export declare const KEY_PARAMS_PASS = "hyper:type:pass";
-export declare const KEY_PARAMS_TRANSFORM = "hyper:type:transform";
-export type KeyParams = typeof KEY_PARAMS_APP | typeof KEY_PARAMS_CONTROLLER | typeof KEY_PARAMS_MODULE | typeof KEY_PARAMS_ROUTE | typeof KEY_PARAMS_PARAM | typeof KEY_PARAMS_MIDDLEWARES | typeof KEY_PARAMS_SCOPE | typeof KEY_PARAMS_ROLE | typeof KEY_PARAMS_PASS | typeof KEY_PARAMS_TRANSFORM;
+export declare const KEY_OUTPUT_SCHEMA = "hyper:output:schema";
+export type KeyParams = typeof KEY_PARAMS_APP | typeof KEY_PARAMS_CONTROLLER | typeof KEY_PARAMS_MODULE | typeof KEY_PARAMS_ROUTE | typeof KEY_PARAMS_PARAM | typeof KEY_PARAMS_MIDDLEWARES | typeof KEY_PARAMS_SCOPE | typeof KEY_PARAMS_ROLE | typeof KEY_PARAMS_PASS | typeof KEY_OUTPUT_SCHEMA;
 export declare const KEY_STATE_UPDATED = "hyper:state:updated";
 export declare const KEY_STATE_CREATED = "hyper:state:created";
 export declare const KEY_STATE_PREPARED = "hyper:state:prepared";

package/dist/__internals/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FULL_ACCESS = exports.METADATA_STATE_KEYS = exports.METADATA_PARAMS_KEYS = exports.METADATA_METHOD_KEYS = exports.METADATA_STORE_KEYS = exports.METADATA_KEYS = exports.METADATA_HYPER_TYPE = exports.DESIGN_TYPE = exports.DESIGN_RETURNTYPE = exports.DESIGN_PARAMTYPES = exports.KEY_STATE_BY_PASS = exports.KEY_STATE_PREPARED = exports.KEY_STATE_CREATED = exports.KEY_STATE_UPDATED = exports.KEY_PARAMS_TRANSFORM = exports.KEY_PARAMS_PASS = exports.KEY_PARAMS_ROLE = exports.KEY_PARAMS_SCOPE = exports.KEY_PARAMS_MIDDLEWARES = exports.KEY_PARAMS_PARAM = exports.KEY_PARAMS_ROUTE = exports.KEY_PARAMS_MODULE = exports.KEY_PARAMS_CONTROLLER = exports.KEY_PARAMS_APP = exports.KEY_TYPE_GUARD = exports.KEY_TYPE_SERVICE = exports.KEY_TYPE_ROUTE = exports.KEY_TYPE_MODULE = exports.KEY_TYPE_CONTROLLER = exports.KEY_TYPE_APP = void 0;
+exports.FULL_ACCESS = exports.METADATA_STATE_KEYS = exports.METADATA_PARAMS_KEYS = exports.METADATA_METHOD_KEYS = exports.METADATA_STORE_KEYS = exports.METADATA_KEYS = exports.METADATA_HYPER_TYPE = exports.DESIGN_TYPE = exports.DESIGN_RETURNTYPE = exports.DESIGN_PARAMTYPES = exports.KEY_STATE_BY_PASS = exports.KEY_STATE_PREPARED = exports.KEY_STATE_CREATED = exports.KEY_STATE_UPDATED = exports.KEY_OUTPUT_SCHEMA = exports.KEY_PARAMS_PASS = exports.KEY_PARAMS_ROLE = exports.KEY_PARAMS_SCOPE = exports.KEY_PARAMS_MIDDLEWARES = exports.KEY_PARAMS_PARAM = exports.KEY_PARAMS_ROUTE = exports.KEY_PARAMS_MODULE = exports.KEY_PARAMS_CONTROLLER = exports.KEY_PARAMS_APP = exports.KEY_TYPE_GUARD = exports.KEY_TYPE_SERVICE = exports.KEY_TYPE_ROUTE = exports.KEY_TYPE_MODULE = exports.KEY_TYPE_CONTROLLER = exports.KEY_TYPE_APP = void 0;
 //////////////////////////////
 /// Types constants
 //////////////////////////////
@@ -22,7 +22,7 @@ exports.KEY_PARAMS_MIDDLEWARES = "hyper:type:middlewares";
 exports.KEY_PARAMS_SCOPE = "hyper:type:scope";
 exports.KEY_PARAMS_ROLE = "hyper:type:role";
 exports.KEY_PARAMS_PASS = "hyper:type:pass";
-exports.KEY_PARAMS_TRANSFORM = "hyper:type:transform";
+exports.KEY_OUTPUT_SCHEMA = "hyper:output:schema";
 //////////////////////////////
 /// State constants
 //////////////////////////////

package/dist/__internals/creators/request.creator.d.ts

@@ -8,4 +8,4 @@ import { ParameterResolver } from "../../decorators";
  * @param {IParamsResolver} resolver - Resolver function to handle the parameter.
  * @returns {ParameterDecorator} - The parameter decorator function.
  */
-export default function createParamDecorator(key: keyof Request | "req" | "res", decoratorName: string, resolver: ParameterResolver): ParameterDecorator;
+export default function createParamDecorator(key: keyof Request | "req" | "res", decoratorName: string, resolver: ParameterResolver, schema?: any, isWholeSource?: boolean): ParameterDecorator;

package/dist/__internals/creators/request.creator.js

@@ -17,7 +17,7 @@ const function_util_1 = require("../utils/function.util");
  * @param {IParamsResolver} resolver - Resolver function to handle the parameter.
  * @returns {ParameterDecorator} - The parameter decorator function.
  */
-function createParamDecorator(key, decoratorName, resolver) {
+function createParamDecorator(key, decoratorName, resolver, schema, isWholeSource) {
     const _key = key;
     return (0, decorator_base_1.DecoratorHelper)({
         type: constants_1.KEY_TYPE_CONTROLLER,
@@ -42,6 +42,8 @@ function createParamDecorator(key, decoratorName, resolver) {
                     key: _key,
                     method: propertyKey.toString(),
                     resolver,
+                    schema,
+                    isWholeSource,
                 });
                 // sort by index
                 saved.params[propertyKey].sort((a, b) => a.index - b.index);

package/dist/__internals/decorator-base.js

@@ -61,7 +61,7 @@ function DecoratorHelper({ key, type, options, targetResolver, onDefineData }, .
 const METADATA_CACHE = new WeakMap();
 const defineDecorData = (key, options, target, property, descriptor) => {
     let value = options;
-    if (typeof options === "function") {
+    if (typeof options === "function" && !(options.prototype && options.prototype.constructor === options)) {
         const old = (0, exports.getDecorData)(key, target, property);
         value = Object.assign(Object.assign({}, old), options(old, target, property, descriptor));
     }

package/dist/__internals/helpers/prepare.helper.js

@@ -24,7 +24,6 @@ const middleware_transform_1 = __importDefault(require("../transform/middleware.
 const tsyringe_1 = require("tsyringe");
 const path_util_1 = require("../utils/path.util");
 const imports_helper_1 = require("./imports.helper");
-const constants_2 = require("../constants");
 const message_bus_1 = require("../../common/message-bus");
 const transport_1 = require("../../common/transport");
 const transform_registry_1 = require("../transform/transform.registry");
@@ -243,11 +242,66 @@ function prepareTarget(_a) {
         };
     });
 }
+/**
+ * Resolves method parameters and applies adaptive transformations.
+ * Optimized: Metadata is resolved once and passed here.
+ */
+function resolveMethodParams(req, res, params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const len = params.length;
+        const args = new Array(len);
+        for (let i = 0; i < len; i++) {
+            const param = params[i];
+            let val = yield param.resolver(req, res);
+            if (param.schema) {
+                val = yield transform_registry_1.transformRegistry.resolve({
+                    data: val,
+                    schema: param.schema,
+                    options: { isWholeSource: param.isWholeSource },
+                    req,
+                    res,
+                    from: param.key,
+                });
+            }
+            args[i] = val;
+        }
+        return args;
+    });
+}
+/**
+ * Handles output transformation and sends the response.
+ * Optimized: outputSchema is pre-resolved outside the request hotpath.
+ */
+function handleResponse(req, res, result, outputSchema) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (result === undefined || res.completed)
+            return;
+        if (outputSchema && outputSchema !== Object && outputSchema !== Promise) {
+            const transformed = yield transform_registry_1.transformRegistry.resolve({
+                data: result,
+                schema: outputSchema,
+                options: {},
+                req,
+                res,
+                from: "response",
+            });
+            if (transformed !== undefined && !res.completed) {
+                res.json(transformed);
+                return;
+            }
+        }
+        if (!res.completed) {
+            if (typeof result === "object" && result !== null) {
+                res.json(result);
+            }
+            else {
+                res.send(result);
+            }
+        }
+    });
+}
 /**
  * Prepare the routes for the target class.
- *
- * @param param0
- * @returns
  */
 function prepareRoutes(_a) {
     return __awaiter(this, arguments, void 0, function* ({ target, router, route, instance, namespace, log, }) {
@@ -256,63 +310,41 @@ function prepareRoutes(_a) {
         const metadata = getData(handler);
         const params = (_d = (_c = (_b = metadata.params) === null || _b === void 0 ? void 0 : _b.params) === null || _c === void 0 ? void 0 : _c[propertyKey]) !== null && _d !== void 0 ? _d : [];
         const $fn = Reflect.get(router, method);
-        const hasParams = params.length > 0;
         if (!$fn)
             return;
         const middlewares = [...metadata.middlewares];
-        // Agnostic Transform Integration
-        const transform = (0, decorator_base_1.getDecorData)(constants_2.KEY_PARAMS_TRANSFORM, target.prototype || target, propertyKey);
-        if (transform) {
-            middlewares.push((req, res, next) => __awaiter(this, void 0, void 0, function* () {
-                try {
-                    const from = transform.options.from || "body";
-                    let data;
-                    if (from === "body") {
-                        data = req.body !== undefined ? req.body : yield req.json();
-                    }
-                    else {
-                        data = req[from];
-                    }
-                    // Resolve through the chain of responsibility
-                    const transformed = yield transform_registry_1.transformRegistry.resolve({
-                        data,
-                        schema: transform.schema,
-                        options: transform.options,
-                        req,
-                        res,
-                        from
-                    });
-                    // Update the request object
-                    req[from] = transformed;
-                    next();
-                }
-                catch (err) {
-                    next(err);
-                }
-            }));
-        }
+        const proto = target.prototype || target;
+        // Pre-resolve Output-Metadata
+        const outputSchema = Reflect.getMetadata(constants_1.KEY_OUTPUT_SCHEMA, proto, propertyKey) ||
+            Reflect.getMetadata(constants_1.DESIGN_RETURNTYPE, proto, propertyKey);
         (0, role_transform_1.default)(metadata.roles, (middleware) => middlewares.push(middleware));
         (0, scope_transfrom_1.default)(metadata.scopes, (middleware, scopes) => {
             middlewares.push(middleware);
             stores_1.ScopeStore.addAll(scopes);
         });
-        log("routes", `${namespace}/${propertyKey} ${method.toUpperCase()} { ${path} }`);
-        if (!hasParams) {
-            if (method === "ws" && options) {
-                router.ws(path, options, handler.bind(instance));
-                return;
+        log("routes", `${namespace}/${propertyKey.toString()} ${method.toUpperCase()} { ${path} }`);
+        const routeHandler = (req, res) => __awaiter(this, void 0, void 0, function* () {
+            try {
+                const args = params.length > 0
+                    ? yield resolveMethodParams(req, res, params)
+                    : [req, res];
+                const result = yield handler.apply(instance, args);
+                yield handleResponse(req, res, result, outputSchema);
             }
-            $fn.call(router, path, ...middlewares, handler.bind(instance));
-        }
-        else {
-            $fn.call(router, path, ...middlewares, (req, res) => __awaiter(this, void 0, void 0, function* () {
-                const len = params.length;
-                const args = new Array(len);
-                for (let i = 0; i < len; i++) {
-                    args[i] = yield params[i].resolver(req, res);
+            catch (err) {
+                if (!res.completed) {
+                    const error = err;
+                    res.status(error.status || 500).json({
+                        error: error.message || "Internal Server Error",
+                        code: error.code,
+                    });
                 }
-                return handler.apply(instance, args);
-            }));
+            }
+        });
+        if (method === "ws" && options) {
+            router.ws(path, options, handler.bind(instance));
+            return;
         }
+        $fn.call(router, path, ...middlewares, routeHandler);
     });
 }

package/dist/decorators/File.d.ts

@@ -1,31 +1,17 @@
 import { Request } from "hyper-express/types";
 /**
  * File upload restrictions
- *
- * @param allowedMimeTypes Allowed MIME types
- * @param maxFileSize Maximum file size in bytes
- *
  */
-export interface FileUplopadRestrictions {
+export interface FileUploadRestrictions {
     allowedMimeTypes: string[];
     maxFileSize: number;
 }
 /**
  * File restrictions resolver
- *
- * @param request Request object
- * @returns File restrictions
- *
  */
-export type FileRestrictions = FileUplopadRestrictions | ((request: Request) => FileUplopadRestrictions | Promise<FileUplopadRestrictions>);
+export type FileRestrictions = FileUploadRestrictions | ((request: Request) => FileUploadRestrictions | Promise<FileUploadRestrictions>);
 /**
  * File decorator options
- *
- * @param fieldName Field name to extract from the request
- * @param restrictions File restrictions
- * @param required If the file is required
- *
- *
  */
 export interface FileOptions {
     fieldName: string | string[];
@@ -33,33 +19,19 @@ export interface FileOptions {
     required?: boolean;
 }
 export interface UploadedFile {
+    field: string;
     name: string;
     filename: string;
     mimeType: string;
     size: number;
-    ext: string;
+    extension: string;
     buffer: Buffer;
 }
 /**
  * Decorator to extract file from the request
- *
- * @param param0
  */
 export declare const File: {
     (options: FileOptions | string): ParameterDecorator;
-    /**
-     *
-     * Helper function to create a file decorator with options
-     *
-     * @param options
-     * @returns
-     */
     options(options: FileOptions, required?: boolean): (fieldName: string | string[]) => ParameterDecorator;
-    /**
-     * Helper function to create a file decorator with restrictions
-     *
-     * @param restrictions
-     * @returns
-     */
     restrictions(restrictions: FileRestrictions): (fieldName: string | string[], required?: boolean) => ParameterDecorator;
 };

package/dist/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/decorators/Http.d.ts

@@ -5,28 +5,35 @@ import { ParameterResolver } from "./types";
  * @param key
  * @returns
  */
-export declare const Query: (key?: string, transfrom?: (data: any) => any) => ParameterDecorator;
 /**
- * Get the body of the request
+ * Get the value of a key from the request object or transform the entire query.
  *
- * @param resolver
- * @returns
+ * @example
+ * \@Query('id')
+ * \@Query('id', IntSchema)
+ * \@Query(UserQueryDto)
  */
-export declare const Body: <T, R>(resolver?: (data: T) => R) => ParameterDecorator;
+export declare function Query(keyOrSchema?: string | any, schemaOrTransform?: any): any;
 /**
- * Get the params from the request
+ * Get the body of the request or transform it via a schema.
  *
- * @param k
- * @returns
+ * @example
+ * \@Body()
+ * \@Body(CreateUserDto)
  */
-export declare const Param: (k?: string, validator?: (data: any) => any) => ParameterDecorator;
+export declare function Body(schemaOrResolver?: any): any;
 /**
- * get the headers from the request
+ * Get the params from the request or transform via schema.
  *
- * @param key
- * @returns
+ * @example
+ * \@Param('id')
+ * \@Param('id', IntSchema)
+ */
+export declare function Param(keyOrSchema: string | any, schemaOrValidator?: any): any;
+/**
+ * Get the headers from the request.
  */
-export declare const Headers: <T extends string>(key?: T) => ParameterDecorator;
+export declare function Headers(keyOrSchema?: string | any, schema?: any): any;
 export declare const Req: () => ParameterDecorator;
 export declare const Res: () => ParameterDecorator;
 /**

package/dist/decorators/Http.js

@@ -12,7 +12,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createCustomRequestDecorator = exports.Res = exports.Req = exports.Headers = exports.Param = exports.Body = exports.Query = void 0;
+exports.createCustomRequestDecorator = exports.Res = exports.Req = void 0;
+exports.Query = Query;
+exports.Body = Body;
+exports.Param = Param;
+exports.Headers = Headers;
 const request_creator_1 = __importDefault(require("../__internals/creators/request.creator"));
 const object_util_1 = require("../__internals/utils/object.util");
 /**
@@ -21,45 +25,87 @@ const object_util_1 = require("../__internals/utils/object.util");
  * @param key
  * @returns
  */
-const Query = (key, transfrom) => (0, request_creator_1.default)("query", "Query", (request) => {
-    const value = (0, object_util_1.$get)(request.query, key, request.query);
-    if (!transfrom)
-        return value;
-    return value;
-});
-exports.Query = Query;
 /**
- * Get the body of the request
+ * Get the value of a key from the request object or transform the entire query.
  *
- * @param resolver
- * @returns
+ * @example
+ * \@Query('id')
+ * \@Query('id', IntSchema)
+ * \@Query(UserQueryDto)
  */
-const Body = (resolver) => (0, request_creator_1.default)("req", "BODY", (request) => __awaiter(void 0, void 0, void 0, function* () {
-    const value = request.body !== undefined ? request.body : yield request.json();
-    return resolver ? resolver(value) : value;
-}));
-exports.Body = Body;
+function Query(keyOrSchema, schemaOrTransform) {
+    // Case: @Query(UserQueryDto)
+    if (typeof keyOrSchema === 'function' && !schemaOrTransform) {
+        return (0, request_creator_1.default)("query", "Query", (request) => request.query, keyOrSchema, true);
+    }
+    // Case: @Query('id', IntSchema) or @Query('id', data => ...)
+    const key = keyOrSchema;
+    const resolver = (request) => (0, object_util_1.$get)(request.query, key, request.query);
+    if (typeof schemaOrTransform === 'function' && schemaOrTransform.prototype === undefined) {
+        // It's a legacy transform function: data => ...
+        return (0, request_creator_1.default)("query", "Query", (request) => {
+            const value = resolver(request);
+            return schemaOrTransform(value);
+        });
+    }
+    // It's either a schema/DTO class or just a key
+    return (0, request_creator_1.default)("query", "Query", resolver, schemaOrTransform, false);
+}
 /**
- * Get the params from the request
+ * Get the body of the request or transform it via a schema.
  *
- * @param k
- * @returns
+ * @example
+ * \@Body()
+ * \@Body(CreateUserDto)
  */
-const Param = (k, validator) => (0, request_creator_1.default)("params", "Param", (req) => {
-    const value = (0, object_util_1.$get)(req.params, k, req.params);
-    if (typeof validator === "function")
-        return validator(value);
-    return value;
-});
-exports.Param = Param;
+function Body(schemaOrResolver) {
+    const resolver = (request) => __awaiter(this, void 0, void 0, function* () {
+        return request.body !== undefined ? request.body : yield request.json();
+    });
+    if (typeof schemaOrResolver === 'function' && schemaOrResolver.prototype !== undefined) {
+        // Case: @Body(CreateUserDto)
+        return (0, request_creator_1.default)("req", "BODY", resolver, schemaOrResolver, true);
+    }
+    // Case: @Body(data => ...) (Legacy) or @Body()
+    return (0, request_creator_1.default)("req", "BODY", (request) => __awaiter(this, void 0, void 0, function* () {
+        const value = yield resolver(request);
+        return typeof schemaOrResolver === 'function' ? schemaOrResolver(value) : value;
+    }));
+}
 /**
- * get the headers from the request
+ * Get the params from the request or transform via schema.
  *
- * @param key
- * @returns
+ * @example
+ * \@Param('id')
+ * \@Param('id', IntSchema)
  */
-const Headers = (key) => (0, request_creator_1.default)("headers", "Headers", (req) => (0, object_util_1.$get)(req.headers, key, req.headers));
-exports.Headers = Headers;
+function Param(keyOrSchema, schemaOrValidator) {
+    // Case: @Param(ParamsDto)
+    if (typeof keyOrSchema === 'function' && !schemaOrValidator) {
+        return (0, request_creator_1.default)("params", "Param", (req) => req.params, keyOrSchema, true);
+    }
+    const key = keyOrSchema;
+    const resolver = (req) => (0, object_util_1.$get)(req.params, key, req.params);
+    if (typeof schemaOrValidator === 'function' && schemaOrValidator.prototype === undefined) {
+        // Legacy validator function
+        return (0, request_creator_1.default)("params", "Param", (req) => {
+            const value = resolver(req);
+            return schemaOrValidator(value);
+        });
+    }
+    return (0, request_creator_1.default)("params", "Param", resolver, schemaOrValidator, false);
+}
+/**
+ * Get the headers from the request.
+ */
+function Headers(keyOrSchema, schema) {
+    if (typeof keyOrSchema === 'function' && !schema) {
+        return (0, request_creator_1.default)("headers", "Headers", (req) => req.headers, keyOrSchema, true);
+    }
+    const key = keyOrSchema;
+    const resolver = (req) => (0, object_util_1.$get)(req.headers, key, req.headers);
+    return (0, request_creator_1.default)("headers", "Headers", resolver, schema, false);
+}
 const Req = () => (0, request_creator_1.default)("req", "Req", (req) => req);
 exports.Req = Req;
 const Res = () => (0, request_creator_1.default)("res", "Res", (req, res) => res);

package/dist/decorators/Output.d.ts

@@ -0,0 +1,9 @@
+import "reflect-metadata";
+/**
+ * Decorator to explicitly mark a method for response transformation and OpenAPI documentation.
+ *
+ * @param schema The schema or DTO class for the successful response (200).
+ * @example
+ * \@Output(UserDto)
+ */
+export declare function Output(schema?: any): (target: any, propertyKey?: any, descriptor?: PropertyDescriptor) => void;

package/dist/decorators/Output.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Output = Output;
+require("reflect-metadata");
+const decorator_base_1 = require("../__internals/decorator-base");
+const constants_1 = require("../__internals/constants");
+/**
+ * Decorator to explicitly mark a method for response transformation and OpenAPI documentation.
+ *
+ * @param schema The schema or DTO class for the successful response (200).
+ * @example
+ * \@Output(UserDto)
+ */
+function Output(schema) {
+    return (target, propertyKey, descriptor) => {
+        (0, decorator_base_1.defineDecorData)(constants_1.KEY_OUTPUT_SCHEMA, schema, target, propertyKey);
+    };
+}

package/dist/decorators/index.d.ts

@@ -11,4 +11,4 @@ export * from "./Http";
 export * from "./Pass";
 export * from "./File";
 export * from "./Messaging";
-export * from "./Transform";
+export * from "./Output";

package/dist/decorators/index.js

@@ -27,4 +27,4 @@ __exportStar(require("./Http"), exports);
 __exportStar(require("./Pass"), exports);
 __exportStar(require("./File"), exports);
 __exportStar(require("./Messaging"), exports);
-__exportStar(require("./Transform"), exports);
+__exportStar(require("./Output"), exports);

package/dist/decorators/types.d.ts

@@ -74,6 +74,8 @@ export type HyperParameterMetadata = {
         name: string;
         method: string;
         resolver: ParameterResolver;
+        schema?: any;
+        isWholeSource?: boolean;
     }[]>;
 };
 export type HyperParamDecorator = (key: string) => (target: any, key: string, index: number) => void;

package/dist/exeptions/HyperException.d.ts

@@ -2,6 +2,7 @@ import { ExceptionType } from "./types";
 export default class HyperException extends Error {
     code: ExceptionType;
     additionalInfo: any;
-    constructor(message: string, code?: ExceptionType, additionalInfo?: any);
+    status: number;
+    constructor(message: string, code?: ExceptionType, additionalInfo?: any, status?: number);
     static throw(message: string, code?: ExceptionType, additionalInfo?: {}): void;
 }

package/dist/exeptions/HyperException.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 class HyperException extends Error {
-    constructor(message, code = "HyperException", additionalInfo = {}) {
+    constructor(message, code = "HyperException", additionalInfo = {}, status = 500) {
         super(message);
         this.code = code;
         this.additionalInfo = additionalInfo;
+        this.status = status;
     }
     static throw(message, code, additionalInfo = {}) {
         throw new this(message, code, additionalInfo);

package/dist/exeptions/HyperFileException.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const HyperException_1 = __importDefault(require("./HyperException"));
 class HyperFileException extends HyperException_1.default {
     constructor(message, additional) {
-        super(message, "HyperFileException", additional);
+        super(message, "HyperFileException", additional, 400);
     }
 }
 exports.default = HyperFileException;

package/dist/index.d.ts

@@ -11,3 +11,5 @@ export * from "./stores";
 export * from "./type";
 export * from "./common/transport";
 export * from "./common/message-bus";
+export * from "./__internals/transform/transform.registry";
+export * from "./lib/openapi";

package/dist/index.js

@@ -27,3 +27,5 @@ __exportStar(require("./stores"), exports);
 __exportStar(require("./type"), exports);
 __exportStar(require("./common/transport"), exports);
 __exportStar(require("./common/message-bus"), exports);
+__exportStar(require("./__internals/transform/transform.registry"), exports);
+__exportStar(require("./lib/openapi"), exports);

package/dist/lib/openapi/collectors/method.collector.js

@@ -4,7 +4,6 @@ exports.collectMethodMetadata = collectMethodMetadata;
 const constants_1 = require("../constants");
 const param_collector_1 = require("./param.collector");
 const constants_2 = require("../../../__internals/constants");
-const decorator_base_1 = require("../../../__internals/decorator-base");
 const transform_registry_1 = require("../../../__internals/transform/transform.registry");
 function collectMethodMetadata(target, methodName) {
     const methodMetadata = {};
@@ -22,20 +21,34 @@ function collectMethodMetadata(target, methodName) {
         description: Reflect.getMetadata(constants_1.REQUEST_BODY_DESCRIPTION, target, methodName),
         content: Reflect.getMetadata(constants_1.REQUEST_BODY_CONTENT, target, methodName),
     };
-    // Bridging @Transform to OpenAPI
-    const transform = (0, decorator_base_1.getDecorData)(constants_2.KEY_PARAMS_TRANSFORM, target, methodName);
-    if (transform) {
-        const openApiSchema = transform_registry_1.transformRegistry.getOpenApiSchema(transform.schema);
-        if (openApiSchema) {
-            const from = transform.options.from || 'body';
-            if (from === 'body') {
-                requestBody.content = requestBody.content || {};
-                requestBody.content['application/json'] = {
-                    schema: openApiSchema
-                };
+    // Bridge @Body to OpenAPI
+    const hyperParams = Reflect.getMetadata(constants_2.KEY_PARAMS_PARAM, target[methodName]);
+    if (hyperParams && hyperParams.params[methodName]) {
+        const bodyParam = hyperParams.params[methodName].find(p => ['body', 'BODY', 'req'].includes(p.key));
+        if (bodyParam) {
+            const targetSchema = bodyParam.schema;
+            if (targetSchema) {
+                const bodySchema = transform_registry_1.transformRegistry.getOpenApiSchema(targetSchema);
+                if (bodySchema) {
+                    requestBody.content = requestBody.content || {};
+                    requestBody.content['application/json'] = {
+                        schema: bodySchema
+                    };
+                }
             }
         }
     }
+    // Bridging @Output / return type to OpenAPI
+    const outputSchema = Reflect.getMetadata(constants_2.KEY_OUTPUT_SCHEMA, target, methodName)
+        || Reflect.getMetadata(constants_2.DESIGN_RETURNTYPE, target, methodName);
+    if (outputSchema && outputSchema !== Object && outputSchema !== Promise) {
+        const schema = transform_registry_1.transformRegistry.getOpenApiSchema(outputSchema);
+        if (schema) {
+            responses['200'] = responses['200'] || { description: 'Success' };
+            responses['200'].content = responses['200'].content || {};
+            responses['200'].content['application/json'] = { schema };
+        }
+    }
     // Asignamos las propiedades al objeto de metadata solo si existen
     if (summary)
         methodMetadata.summary = summary;

package/dist/lib/openapi/collectors/param.collector.d.ts

@@ -1,3 +1,2 @@
-import "reflect-metadata";
-import { Parameter } from "../types";
-export declare function collectParameterMetadata(target: any, methodName: string): Parameter[];
+import { OpenApiParameter } from "../types";
+export declare function collectParameterMetadata(target: any, methodName: string): OpenApiParameter[];

package/dist/lib/openapi/collectors/param.collector.js

@@ -1,26 +1,63 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.collectParameterMetadata = collectParameterMetadata;
-require("reflect-metadata");
 const constants_1 = require("../constants");
+const constants_2 = require("../../../__internals/constants");
+const transform_registry_1 = require("../../../__internals/transform/transform.registry");
 const function_util_1 = require("../../../__internals/utils/function.util");
 function collectParameterMetadata(target, methodName) {
     const parameters = Reflect.getMetadata(constants_1.PARAMETERS, target, methodName) || [];
-    const methodParams = Reflect.getMetadata("design:paramtypes", target, methodName) || [];
-    // Intentamos obtener los nombres de los parámetros utilizando extractArgsNames
-    const paramNames = (0, function_util_1.extractArgsNames)(target[methodName]);
-    // Si no se encuentran parámetros en los metadatos y hay tipos de parámetros disponibles
-    if (parameters.length === 0 && methodParams.length > 0) {
+    const hyperParams = Reflect.getMetadata(constants_2.KEY_PARAMS_PARAM, target[methodName]);
+    if (hyperParams && hyperParams.params[methodName]) {
+        hyperParams.params[methodName].forEach((p) => {
+            // Ignore body, req, res as they are not standard "parameters" in OpenAPI terms (body is separate)
+            if (['req', 'res', 'body', 'BODY'].includes(p.key))
+                return;
+            const locationMap = {
+                'query': 'query',
+                'params': 'path',
+                'headers': 'header',
+                'cookie': 'cookie'
+            };
+            const location = locationMap[p.key] || 'query';
+            if (p.isWholeSource && p.schema) {
+                const schema = transform_registry_1.transformRegistry.getOpenApiSchema(p.schema);
+                if (schema && schema.properties) {
+                    Object.keys(schema.properties).forEach((propKey) => {
+                        parameters.push({
+                            name: propKey,
+                            in: location,
+                            required: (schema.required || []).includes(propKey),
+                            schema: schema.properties[propKey]
+                        });
+                    });
+                }
+            }
+            else {
+                parameters.push({
+                    name: p.name,
+                    in: location,
+                    required: true, // TODO: detect optionality from design:paramtypes or metadata
+                    schema: p.schema ? transform_registry_1.transformRegistry.getOpenApiSchema(p.schema) : { type: 'string' }
+                });
+            }
+        });
+    }
+    // Fallback to design:paramtypes if no hyper-decor metadata found
+    if (parameters.length === 0) {
+        const methodParams = Reflect.getMetadata("design:paramtypes", target, methodName) || [];
+        const paramNames = (0, function_util_1.extractArgsNames)(target[methodName]);
         methodParams.forEach((paramType, index) => {
-            const param = {
-                name: paramNames && paramNames[index] ? paramNames[index] : `param${index}`, // Asignamos nombre genérico o el nombre inferido
-                in: "query", // Definir el tipo de parámetro, se puede modificar según sea necesario
+            var _a;
+            const name = paramNames && paramNames[index] ? paramNames[index] : `param${index}`;
+            parameters.push({
+                name,
+                in: "query",
                 required: true,
                 schema: {
-                    type: paramType.name.toLowerCase(), // Inferimos el tipo del parámetro
+                    type: ((_a = paramType === null || paramType === void 0 ? void 0 : paramType.name) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === 'number' ? 'number' : 'string',
                 },
-            };
-            parameters.push(param);
+            });
         });
     }
     return parameters;

package/dist/lib/openapi/decorators/api-parameter.decorator.d.ts

@@ -1,3 +1,3 @@
 import 'reflect-metadata';
-import { Parameter } from '../types';
-export declare function ApiParameter(options: Parameter): (target: any, propertyKey: any) => void;
+import { OpenApiParameter } from '../types';
+export declare function ApiParameter(options: OpenApiParameter): (target: any, propertyKey: any) => void;

package/dist/lib/openapi/decorators/api-response.decorator.d.ts

@@ -1,3 +1,3 @@
 import "reflect-metadata";
-import { Responses } from "../types";
-export declare function ApiResponse(options: Responses): (target: any, propertyKey?: any, descriptor?: any) => any;
+import { OpenApiResponses } from "../types";
+export declare function ApiResponse(options: OpenApiResponses): (target: any, propertyKey?: any, descriptor?: any) => any;

package/dist/lib/openapi/decorators/api-tag.decorator.d.ts

@@ -1,3 +1,3 @@
 import 'reflect-metadata';
 import { Tag } from '../types';
-export declare function ApiTag(options: Tag): (target: any) => void;
+export declare function ApiTag(options: Tag | string): (target: any) => void;

package/dist/lib/openapi/decorators/api-tag.decorator.js

@@ -5,6 +5,9 @@ require("reflect-metadata");
 const tag_helper_1 = require("../helpers/tag.helper");
 function ApiTag(options) {
     return (target) => {
+        if (typeof options === 'string') {
+            options = { name: options };
+        }
         (0, tag_helper_1.apiTag)(target, options);
     };
 }

package/dist/lib/openapi/helpers/parameter.helper.d.ts

@@ -1,3 +1,3 @@
 import 'reflect-metadata';
-import { Parameter } from '../types';
-export declare function apiParameter(target: any, propertyKey: string, options: Parameter): void;
+import { OpenApiParameter } from '../types';
+export declare function apiParameter(target: any, propertyKey: string, options: OpenApiParameter): void;

package/dist/lib/openapi/helpers/response.helper.d.ts

@@ -1,3 +1,3 @@
 import "reflect-metadata";
-import { Responses } from "../types";
-export declare function apiResponse(target: any, propertyKey: string | symbol, options: Responses): void;
+import { OpenApiResponses } from "../types";
+export declare function apiResponse(target: any, propertyKey: string | symbol, options: OpenApiResponses): void;

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

@@ -41,12 +41,12 @@ export interface Operation {
     description?: string;
     operationId?: string;
     tags?: Tag[];
-    parameters?: Parameter[];
+    parameters?: OpenApiParameter[];
     requestBody?: RequestBody;
-    responses: Responses;
+    responses: OpenApiResponses;
     security?: SecurityRequirement[];
 }
-export interface Parameter {
+export interface OpenApiParameter {
     name: string;
     in: "query" | "header" | "path" | "cookie";
     description?: string;
@@ -64,10 +64,10 @@ export interface RequestBody {
 export interface MediaType {
     schema: Schema;
 }
-export interface Responses {
-    [statusCode: string]: Response;
+export interface OpenApiResponses {
+    [statusCode: string]: OpenApiResponse;
 }
-export interface Response {
+export interface OpenApiResponse {
     description: string;
     content?: {
         [mediaType: string]: MediaType;
@@ -103,10 +103,10 @@ export interface Components {
         [schemaName: string]: Schema;
     };
     responses?: {
-        [responseName: string]: Response;
+        [responseName: string]: OpenApiResponse;
     };
     parameters?: {
-        [parameterName: string]: Parameter;
+        [parameterName: string]: OpenApiParameter;
     };
     securitySchemes?: {
         [schemeName: string]: SecurityScheme;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenofolio/hyper-decor",
-  "version": "1.0.68",
+  "version": "1.0.71",
   "description": "Project core with utilities and features",
   "main": "dist/index.js",
   "author": "zenozaga",
@@ -21,12 +21,12 @@
     "@vitest/ui": "^4.0.18",
     "nodemon": "3.1.7",
     "typescript": "5.6.2",
+    "undici": "^7.24.0",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.0.18"
   },
   "dependencies": {
     "core-decorators": "^0.20.0",
-    "delay": "^7.0.0",
     "eventemitter3": "^5.0.4",
     "file-type": "^19.5.0",
     "reflect-metadata": "^0.2.2",