framework-do-dede 6.1.0 → 6.2.0

package/README.md

@@ -111,9 +111,26 @@ Opções de rota (comuns):
 - `statusCode`: number
 - `params`, `query`, `headers`, `body`: array de strings no formato `campo|tipo`
 - `bodyFilter`: `"restrict" | "none"`
-- `responseType`: `"json" | "text" | "html"`
+- `responseType`: `"json" | "text" | "html" | "<mime>/<subtype>"`
+- `useHeaders`: objeto com headers de resposta (`Record<string, string>`)
 - `validator`: pode ser uma classe com decorators do `class-validator` **ou** um objeto com `validate(data)` (sync/async)
 
+Exemplo de resposta binária com headers customizados:
+
+```ts
+@Get({
+  path: '/download',
+  responseType: 'application/octet-stream',
+  useHeaders: {
+    'Content-Disposition': 'attachment; filename="report.bin"',
+    'Cache-Control': 'public, max-age=31536000'
+  }
+})
+async download() {
+  return Buffer.from([0x01, 0x02, 0x03]);
+}
+```
+
 Nota sobre `validator`:
 - Apenas propriedades com decorators do `class-validator` são transformadas pelo `class-transformer`.
 - Propriedades sem decorators têm o valor original preservado.
@@ -253,6 +270,8 @@ class SecureController {
 
 Use `@Tracing` no controller ou em um metodo para capturar metadados de request.
 
+Modo explicito (legado, continua suportado):
+
 ```ts
 import { Tracing, Tracer, TracerData } from './src';
 
@@ -270,6 +289,34 @@ class TraceController {
 }
 ```
 
+Modo via container:
+
+```ts
+import { Tracing } from './src';
+
+@Controller('/trace')
+class TraceController {
+  @Tracing()
+  @Get()
+  async get() { return { ok: true }; }
+}
+```
+
+Quando usar `@Tracing()`, o framework tenta resolver `Tracer` no container (`registries`).
+Se nao encontrar, lança exceção: `Tracer not found in container: Tracer`.
+
+Tracing global sem decorator:
+
+```ts
+const app = await Dede.create({
+  framework: { use: 'express', port: 3000, tracer: true },
+  registries: [{ name: 'Tracer', classLoader: new ConsoleTracer() }]
+});
+```
+
+Com `framework.tracer: true`, todos os controllers/metodos passam a usar tracer por padrao.
+`@Tracing(new MeuTracer())` ainda sobrescreve por controller/metodo.
+
 ### UseCase e Decorators
 
 UseCase provê `data` e `context` do request.
@@ -464,13 +511,20 @@ class QueueService {
 Registre dependencias ao iniciar o server (usando o container padrão):
 
 ```ts
-import { Dede } from './src';
+import { Dede, Tracer, TracerData } from './src';
+
+class ConsoleTracer implements Tracer<void> {
+  trace(data: TracerData) {
+    console.log(data);
+  }
+}
 
 class UserRepository { /* ... */ }
 
 const app = await Dede.create({
-  framework: { use: 'express', port: 3000 },
+  framework: { use: 'express', port: 3000, tracer: true },
   registries: [
+    { name: 'Tracer', classLoader: new ConsoleTracer() },
     { name: 'UserRepository', classLoader: UserRepository }
   ]
 });

package/dist/application/controller.d.ts

@@ -1,4 +1,5 @@
 import 'reflect-metadata';
+import type { HttpResponseHeaders, HttpResponseType } from "../http/http-server";
 import type { ValidatorDefinition } from "../interface/validation/validator";
 export interface Middleware {
     execute(input: Input<any>): Promise<any>;
@@ -22,13 +23,18 @@ export interface TracerData {
 export interface Tracer<R> {
     trace(data: TracerData): R;
 }
+export type TracerFromContainer = {
+    fromContainer: true;
+    token: string;
+};
+export declare const DEFAULT_TRACER_TOKEN = "Tracer";
 export interface Input<T, K = any> {
     data: T;
     context?: K;
 }
 type BodyFilter = "restrict" | "none";
 export declare function Controller(basePath?: string): (target: any) => void;
-export declare function Tracing<R>(tracer: Tracer<R>): (target: any, propertyKey?: string) => void;
+export declare function Tracing<R>(tracer?: Tracer<R>): (target: any, propertyKey?: string) => void;
 export declare function Version(version: number): (target: any, propertyKey?: string) => void;
 export declare function PresetIgnore(ignorePrefix?: boolean, ignoreVersion?: boolean): (target: any, propertyKey?: string) => void;
 export declare function UseMiddleware(middlewareClass: MiddlewareDefinition): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
@@ -39,9 +45,10 @@ export declare function Post(config?: {
     params?: string[];
     query?: string[];
     headers?: string[];
+    useHeaders?: HttpResponseHeaders;
     body?: string[];
     bodyFilter?: BodyFilter;
-    responseType?: 'json' | 'text' | 'html';
+    responseType?: HttpResponseType;
     validator?: ValidatorDefinition;
 }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export declare function Get(config?: {
@@ -50,7 +57,8 @@ export declare function Get(config?: {
     params?: string[];
     query?: string[];
     headers?: string[];
-    responseType?: 'json' | 'text' | 'html';
+    useHeaders?: HttpResponseHeaders;
+    responseType?: HttpResponseType;
     validator?: ValidatorDefinition;
 }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export declare function Put(config?: {
@@ -59,9 +67,10 @@ export declare function Put(config?: {
     params?: string[];
     query?: string[];
     headers?: string[];
+    useHeaders?: HttpResponseHeaders;
     body?: string[];
     bodyFilter?: BodyFilter;
-    responseType?: 'json' | 'text' | 'html';
+    responseType?: HttpResponseType;
     validator?: ValidatorDefinition;
 }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export declare function Patch(config?: {
@@ -70,9 +79,10 @@ export declare function Patch(config?: {
     params?: string[];
     query?: string[];
     headers?: string[];
+    useHeaders?: HttpResponseHeaders;
     body?: string[];
     bodyFilter?: BodyFilter;
-    responseType?: 'json' | 'text' | 'html';
+    responseType?: HttpResponseType;
     validator?: ValidatorDefinition;
 }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export declare function Delete(config?: {
@@ -81,9 +91,10 @@ export declare function Delete(config?: {
     params?: string[];
     query?: string[];
     headers?: string[];
+    useHeaders?: HttpResponseHeaders;
     body?: string[];
     bodyFilter?: BodyFilter;
-    responseType?: 'json' | 'text' | 'html';
+    responseType?: HttpResponseType;
     validator?: ValidatorDefinition;
 }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export {};

package/dist/application/controller.js

@@ -1,5 +1,6 @@
 import 'reflect-metadata';
 import { FrameworkError } from "../http/errors/framework";
+export const DEFAULT_TRACER_TOKEN = 'Tracer';
 export function Controller(basePath = '/') {
     return function (target) {
         if (!basePath)
@@ -9,11 +10,15 @@ export function Controller(basePath = '/') {
 }
 export function Tracing(tracer) {
     return function (target, propertyKey) {
+        const tracerMetadata = tracer ?? {
+            fromContainer: true,
+            token: DEFAULT_TRACER_TOKEN
+        };
         if (!propertyKey) {
-            Reflect.defineMetadata('tracer', tracer, target);
+            Reflect.defineMetadata('tracer', tracerMetadata, target);
         }
         else {
-            Reflect.defineMetadata('tracer', tracer, target, propertyKey);
+            Reflect.defineMetadata('tracer', tracerMetadata, target, propertyKey);
         }
     };
 }
@@ -111,6 +116,7 @@ export function Post(config = {}) {
             params: config.params,
             query: config.query,
             headers: config.headers,
+            useHeaders: config.useHeaders,
             body: config.body,
             bodyFilter: config.bodyFilter || 'none',
             statusCode: config.statusCode || 200,
@@ -127,6 +133,7 @@ export function Get(config = {}) {
             params: config.params,
             query: config.query,
             headers: config.headers,
+            useHeaders: config.useHeaders,
             statusCode: config.statusCode || 200,
             responseType: config.responseType || 'json',
             validator: config.validator
@@ -141,6 +148,7 @@ export function Put(config = {}) {
             params: config.params,
             query: config.query,
             headers: config.headers,
+            useHeaders: config.useHeaders,
             body: config.body,
             bodyFilter: config.bodyFilter || 'none',
             statusCode: config.statusCode || 200,
@@ -157,6 +165,7 @@ export function Patch(config = {}) {
             params: config.params,
             query: config.query,
             headers: config.headers,
+            useHeaders: config.useHeaders,
             body: config.body,
             bodyFilter: config.bodyFilter || 'none',
             statusCode: config.statusCode || 200,
@@ -173,6 +182,7 @@ export function Delete(config = {}) {
             params: config.params,
             query: config.query,
             headers: config.headers,
+            useHeaders: config.useHeaders,
             body: config.body,
             bodyFilter: config.bodyFilter || 'none',
             statusCode: config.statusCode || 200,

package/dist/dede.d.ts

@@ -8,6 +8,7 @@ export type Options = {
         use: 'elysia' | 'express';
         port?: number;
         middlewares?: CallableFunction[];
+        tracer?: boolean;
     };
     controllers?: any[];
     registries: Register[];

package/dist/dede.js

@@ -42,7 +42,11 @@ export class Dede {
     registerControllers(controllers) {
         if (this.controllersRegistered)
             return;
-        new ControllerHandler(this.httpServer, controllers, { prefix: this.prefix, version: this.version });
+        new ControllerHandler(this.httpServer, controllers, {
+            prefix: this.prefix,
+            version: this.version,
+            tracer: this.framework.tracer
+        });
         this.controllersRegistered = true;
     }
     listen(port) {

package/dist/http/controller.handler.d.ts

@@ -5,12 +5,16 @@ export default class ControllerHandler {
     private readonly errorMapper;
     private readonly prefix?;
     private readonly version?;
+    private readonly tracerEnabled;
     constructor(httpServer: HttpServer, controllers?: any[], options?: {
         prefix?: string;
         version?: number;
+        tracer?: boolean;
     });
     private registryControllers;
     private resolveMiddleware;
+    private resolveTracer;
+    private isTracerFromContainer;
     private buildRoute;
     private joinSegments;
     private trimLeadingSlash;

package/dist/http/controller.handler.js

@@ -1,8 +1,10 @@
+import { DEFAULT_TRACER_TOKEN } from "../application/controller";
 import { FrameworkError } from "../http/errors/framework";
 import { HttpRequestMapper } from "../interface/http/request-mapper";
 import { MiddlewareExecutor } from "../interface/http/middleware-executor";
 import { HttpErrorMapper } from "../interface/errors/http-error-mapper";
 import { validateWithClassValidator } from "../interface/validation/class-validator";
+import { DefaultContainer } from "../infra/di/registry";
 export default class ControllerHandler {
     constructor(httpServer, controllers = [], options = {}) {
         this.requestMapper = new HttpRequestMapper();
@@ -10,7 +12,8 @@ export default class ControllerHandler {
         this.errorMapper = new HttpErrorMapper();
         this.prefix = options.prefix;
         this.version = options.version;
-        for (const { handler, middlewares, validator, method, route, statusCode, params, query, headers, body, bodyFilter, responseType } of this.registryControllers(controllers)) {
+        this.tracerEnabled = options.tracer === true;
+        for (const { handler, middlewares, validator, method, route, statusCode, params, query, headers, body, bodyFilter, responseType, useHeaders } of this.registryControllers(controllers)) {
             httpServer.register({
                 method,
                 route,
@@ -21,7 +24,8 @@ export default class ControllerHandler {
                 headers,
                 middlewares,
                 validator,
-                responseType
+                responseType,
+                useHeaders
             }, async (input) => {
                 let requestedAt = new Date();
                 let startTime = 0;
@@ -95,7 +99,8 @@ export default class ControllerHandler {
         for (const controller of controllersList) {
             const basePath = Reflect.getMetadata('basePath', controller);
             const methodNames = Object.getOwnPropertyNames(controller.prototype).filter(method => method !== 'constructor');
-            let tracer = Reflect.getMetadata('tracer', controller) || null;
+            const controllerTracerMetadata = Reflect.getMetadata('tracer', controller)
+                || (this.tracerEnabled ? { fromContainer: true, token: DEFAULT_TRACER_TOKEN } : null);
             const controllerVersion = Reflect.getMetadata('version', controller);
             const controllerPresetIgnore = Reflect.getMetadata('presetIgnore', controller);
             const controllerMiddlewares = Reflect.getMetadata('middlewares', controller) || [];
@@ -104,8 +109,10 @@ export default class ControllerHandler {
                 const routeConfig = Reflect.getMetadata('route', controller.prototype, methodName);
                 const methodMiddlewares = Reflect.getMetadata('middlewares', controller.prototype, methodName) || [];
                 const middlewares = [...controllerMiddlewares, ...methodMiddlewares];
-                const responseType = Reflect.getMetadata('responseType', controller.prototype, methodName) || 'json';
-                tracer = Reflect.getMetadata('tracer', controller.prototype, methodName) || tracer;
+                const responseType = routeConfig.responseType || 'json';
+                const methodTracerMetadata = Reflect.getMetadata('tracer', controller.prototype, methodName);
+                const tracerMetadata = methodTracerMetadata || controllerTracerMetadata;
+                const tracer = this.resolveTracer(tracerMetadata);
                 const methodVersion = Reflect.getMetadata('version', controller.prototype, methodName);
                 const methodPresetIgnore = Reflect.getMetadata('presetIgnore', controller.prototype, methodName);
                 const presetIgnore = methodPresetIgnore ?? controllerPresetIgnore;
@@ -120,6 +127,7 @@ export default class ControllerHandler {
                     params: routeConfig.params,
                     query: routeConfig.query,
                     headers: routeConfig.headers,
+                    useHeaders: routeConfig.useHeaders,
                     body: routeConfig.body,
                     bodyFilter: routeConfig.bodyFilter,
                     statusCode: routeConfig.statusCode,
@@ -157,6 +165,34 @@ export default class ControllerHandler {
         }
         return middleware;
     }
+    resolveTracer(tracer) {
+        if (!tracer)
+            return undefined;
+        if (this.isTracerFromContainer(tracer)) {
+            const token = tracer.token || DEFAULT_TRACER_TOKEN;
+            try {
+                const tracerDependency = DefaultContainer.inject(token);
+                if (!tracerDependency?.trace || typeof tracerDependency.trace !== 'function') {
+                    throw new FrameworkError('Tracer must implement trace()');
+                }
+                return tracerDependency;
+            }
+            catch (error) {
+                throw new FrameworkError(`Tracer not found in container: ${token}`);
+            }
+        }
+        if (!tracer?.trace || typeof tracer.trace !== 'function') {
+            throw new FrameworkError('Tracer must implement trace()');
+        }
+        return tracer;
+    }
+    isTracerFromContainer(value) {
+        return !!value
+            && typeof value === 'object'
+            && 'fromContainer' in value
+            && value.fromContainer === true
+            && 'token' in value;
+    }
     buildRoute(baseRoute, version, prefix) {
         let route = baseRoute;
         if (version !== undefined) {

package/dist/http/http-server.d.ts

@@ -6,6 +6,8 @@ export type Request = {
 };
 export type HttpStatusCode = 200 | 201 | 204 | 401 | 403 | 404 | 409 | 422 | 500;
 export type AllowedMethods = 'get' | 'post' | 'put' | 'delete' | 'patch';
+export type HttpResponseType = 'json' | 'text' | 'html' | `${string}/${string}`;
+export type HttpResponseHeaders = Record<string, string>;
 export type HttpServerParams = {
     method: AllowedMethods;
     route: string;
@@ -14,7 +16,7 @@ export type HttpServerParams = {
         methodName: string;
         tracer?: Tracer<any>;
     };
-    responseType: 'json' | 'text' | 'html';
+    responseType: HttpResponseType;
     middlewares?: Middleware[];
     validator?: ValidatorDefinition;
     statusCode?: number;
@@ -23,6 +25,7 @@ export type HttpServerParams = {
     body?: string[];
     bodyFilter?: 'none' | 'restrict';
     headers?: string[];
+    useHeaders?: HttpResponseHeaders;
 };
 type FrameworkWeb = {
     listen(port: number): void;

package/dist/http/http-server.js

@@ -49,6 +49,20 @@ export default class HttpServer {
                 params,
                 body
             });
+            if (httpServerParams.useHeaders) {
+                for (const [headerName, headerValue] of Object.entries(httpServerParams.useHeaders)) {
+                    set.headers[headerName] = headerValue;
+                }
+            }
+            if (httpServerParams.responseType === 'html') {
+                set.headers['content-type'] = 'text/html; charset=utf-8';
+            }
+            else if (httpServerParams.responseType === 'text') {
+                set.headers['content-type'] = 'text/plain; charset=utf-8';
+            }
+            else if (httpServerParams.responseType !== 'json') {
+                set.headers['content-type'] = httpServerParams.responseType;
+            }
             return output;
         });
     }
@@ -64,8 +78,18 @@ export default class HttpServer {
                 params: request.params,
                 body: method !== 'get' ? request.body : {}
             });
-            const type = httpServerParams.responseType === 'html' ? 'text' : httpServerParams.responseType;
-            return res[type](output);
+            if (httpServerParams.useHeaders) {
+                for (const [headerName, headerValue] of Object.entries(httpServerParams.useHeaders)) {
+                    res.set(headerName, headerValue);
+                }
+            }
+            if (httpServerParams.responseType === 'json')
+                return res.json(output);
+            if (httpServerParams.responseType === 'html')
+                return res.type('text/html').send(output);
+            if (httpServerParams.responseType === 'text')
+                return res.type('text/plain').send(output);
+            return res.type(httpServerParams.responseType).send(output);
         });
     }
     ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framework-do-dede",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",