framework-do-dede 3.4.0 → 4.0.0

package/README.md

@@ -15,7 +15,7 @@ Um framework TypeScript simples para construir APIs HTTP com controllers, use ca
   - Entity e Serialização
   - Hooks Before/After ToEntity
   - Storage Gateway
-  - DI (Registry/Inject)
+  - DI (Container/Inject)
   - Errors
   - Protocolos de Repositório
 - Exemplos
@@ -23,6 +23,7 @@ Um framework TypeScript simples para construir APIs HTTP com controllers, use ca
   - Elysia
   - Fila com AfterToEntity
 - Testes
+- Benchmark
 
 ## Instalação
 
@@ -62,17 +63,19 @@ class HelloUseCase extends UseCase<{ name?: string }, { message: string }> {
   }
 }
 
-await Dede.start({
+const app = await Dede.create({
   framework: { use: 'express', port: 3000 },
   registries: []
 });
+app.registerControllers([HelloController]);
+app.listen();
 ```
 
 ## Conceitos
 
 ### Controllers e Rotas
 
-Use decorators para expor métodos como rotas HTTP. O Controller registra o class loader no Registry e o ControllerHandler monta as rotas em runtime.
+Use decorators para expor métodos como rotas HTTP. O Controller define metadados, e o ControllerHandler monta as rotas em runtime a partir da lista de controllers passada ao `app.registerControllers(...)`.
 
 ```ts
 import { Controller, Get, Post, Put, Delete, Patch } from './src';
@@ -105,6 +108,7 @@ Opções de rota (comuns):
 - `params`, `query`, `headers`, `body`: array de strings no formato `campo|tipo`
 - `bodyFilter`: `"restrict" | "none"`
 - `responseType`: `"json" | "text" | "html"`
+- `validator`: pode ser uma classe com decorators do `class-validator` **ou** um objeto com `validate(data)` (sync/async)
 
 ### Input, params e filtros
 
@@ -121,7 +125,7 @@ Tipos suportados no filtro:
 
 - `boolean`, `integer`, `string`, `number`
 
-Exemplo:
+Exemplos:
 
 ```ts
 @Put({
@@ -129,13 +133,38 @@ Exemplo:
   query: ['active|boolean'],
   headers: ['x-type|string'],
   body: ['name|string'],
-  bodyFilter: 'restrict'
+  bodyFilter: 'restrict',
+  validator: CreateUserDto
 })
 async update(request: { data: any }) {
   // request.data: { id, active, 'x-type', name }
 }
 ```
 
+```ts
+import 'reflect-metadata'
+import { IsEmail, IsNotEmpty } from 'class-validator'
+
+class CreateUserDto {
+  @IsNotEmpty({ message: 'O nome é obrigatório.' })
+  name!: string
+
+  @IsEmail({}, { message: 'Email inválido.' })
+  email?: string
+}
+```
+
+```ts
+@Put({
+  body: ['name|string', 'email|string'],
+  bodyFilter: 'restrict',
+  validator: CreateUserDto
+})
+async update(request: { data: any }) {}
+```
+
+Obs: o framework usa `class-validator` como `peerDependency`, então o projeto que consome deve ter a mesma versão instalada.
+
 Suporte a notacao com colchetes:
 
 ```json
@@ -229,6 +258,8 @@ Entities suportam:
 - `toData()` e `toAsyncData()`
 - `@Serialize`, `@Restrict`, `@VirtualProperty`, `@GetterPrefix`
 
+Obs: a serializacao fica na camada de infraestrutura, mas a API continua sendo exposta pelo framework (importe direto de `./src`).
+
 ```ts
 import { Entity, Serialize, Restrict, VirtualProperty, GetterPrefix } from './src';
 
@@ -319,21 +350,22 @@ class FileService {
 }
 ```
 
-### DI (Registry/Inject)
+### DI (Container/Inject)
 
-Registre dependencias ao iniciar o server:
+Registre dependencias ao iniciar o server (usando o container padrão):
 
 ```ts
 import { Dede } from './src';
 
 class UserRepository { /* ... */ }
 
-await Dede.start({
+const app = await Dede.create({
   framework: { use: 'express', port: 3000 },
   registries: [
     { name: 'UserRepository', classLoader: UserRepository }
   ]
 });
+app.listen();
 ```
 
 Use `@Inject('Name')` para injetar dependencias:
@@ -363,7 +395,7 @@ Erros de dominio disponiveis:
 - `UnprocessableEntity` (422)
 - `InternalServerError` (500)
 
-Quando um erro e lancado, o handler padroniza a resposta. Se o erro for `CustomServerError`, o payload customizado sera retornado diretamente.
+Quando um erro e lancado, o handler padroniza a resposta. Erros de dominio (`AppError`) sao mapeados para HTTP. Se o erro for `CustomServerError`, o payload customizado sera retornado diretamente.
 
 ### Protocolos de Repositorio
 
@@ -385,7 +417,7 @@ Interfaces tipadas para padrao de repositorio:
 
 ```ts
 import { Dede } from './src/dede';
-import './example/express_app/example.controller';
+import { ExampleController } from './example/express_app/example.controller';
 
 class UserRepository {
   async findById(id: string) {
@@ -393,28 +425,32 @@ class UserRepository {
   }
 }
 
-await Dede.start({
+const app = await Dede.create({
   framework: { use: 'express', port: 3000 },
   registries: [{ name: 'UserRepository', classLoader: UserRepository }]
 });
+app.registerControllers([ExampleController]);
+app.listen();
 ```
 
 ### Elysia
 
 ```ts
 import { Dede } from './src/dede';
-import './example/express_app/example.controller';
+import { ExampleController } from './example/express_app/example.controller';
 
-await Dede.start({
+const app = await Dede.create({
   framework: { use: 'elysia', port: 3001 },
   registries: []
 });
+app.registerControllers([ExampleController]);
+app.listen();
 ```
 
 ### Fila com AfterToEntity
 
 ```ts
-import { Entity, AfterToEntity } from './src/application/entity';
+import { Entity, AfterToEntity } from './src';
 
 type QueueJob = { type: string; payload: Record<string, any> };
 
@@ -461,3 +497,30 @@ const serialized = entity.toEntity();
 ```bash
 npm test -- tests/src/application/entity.spec.ts --runInBand
 ```
+
+Testes de integração (exemplos):
+
+```bash
+RUN_EXAMPLE_TESTS=true npm test -- example/tests/main.test.ts
+```
+
+Obs: os testes de Elysia só rodam no runtime do Bun (em Node eles são ignorados).
+
+## Benchmark
+
+Resultados locais ficam em `bench/results.md`. Para rodar:
+
+```bash
+npm run bench:compare
+```
+
+Parâmetros (opcional):
+
+```bash
+BENCH_REQUESTS=5000 BENCH_CONCURRENCY=50 BENCH_WARMUP=200 npm run bench:compare
+```
+
+Resumo (média de 3 rodadas locais, 5000 req / conc 50 / warmup 200):
+
+- Express: avg 3.34 ms, p50 2.45 ms, p95 8.54 ms, 8298.61 req/s
+- Elysia: avg 3.16 ms, p50 2.63 ms, p95 6.98 ms, 8765.78 req/s

package/dist/application/controller.d.ts

@@ -1,4 +1,5 @@
 import 'reflect-metadata';
+import type { ValidatorLike } from "../interface/validation/validator";
 export interface Middleware {
     execute(input: Input<any>): Promise<any>;
 }
@@ -28,8 +29,6 @@ export interface Input<T, K = any> {
 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 getControllers(): any[];
-export declare function flushControllers(): void;
 export declare function UseMiddleware(middlewareClass: MiddlewareDefinition): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export declare function UseMiddlewares(middlewareClasses: MiddlewareDefinition[]): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export declare function Post(config?: {
@@ -41,6 +40,7 @@ export declare function Post(config?: {
     body?: string[];
     bodyFilter?: BodyFilter;
     responseType?: 'json' | 'text' | 'html';
+    validator?: ValidatorLike;
 }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export declare function Get(config?: {
     path?: string;
@@ -49,6 +49,7 @@ export declare function Get(config?: {
     query?: string[];
     headers?: string[];
     responseType?: 'json' | 'text' | 'html';
+    validator?: ValidatorLike;
 }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export declare function Put(config?: {
     path?: string;
@@ -59,6 +60,7 @@ export declare function Put(config?: {
     body?: string[];
     bodyFilter?: BodyFilter;
     responseType?: 'json' | 'text' | 'html';
+    validator?: ValidatorLike;
 }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export declare function Patch(config?: {
     path?: string;
@@ -69,6 +71,7 @@ export declare function Patch(config?: {
     body?: string[];
     bodyFilter?: BodyFilter;
     responseType?: 'json' | 'text' | 'html';
+    validator?: ValidatorLike;
 }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export declare function Delete(config?: {
     path?: string;
@@ -79,5 +82,6 @@ export declare function Delete(config?: {
     body?: string[];
     bodyFilter?: BodyFilter;
     responseType?: 'json' | 'text' | 'html';
+    validator?: ValidatorLike;
 }): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 export {};

package/dist/application/controller.js

@@ -1,14 +1,10 @@
 import 'reflect-metadata';
 import { FrameworkError } from "../http/errors/framework";
-import { Registry } from "../infra/di/registry";
-let controllers = [];
 export function Controller(basePath = '/') {
     return function (target) {
         if (!basePath)
             throw new FrameworkError('basePath cannot be empty');
         Reflect.defineMetadata('basePath', basePath, target);
-        controllers.push(target.name);
-        Registry.load(target.name, target);
     };
 }
 export function Tracing(tracer) {
@@ -21,15 +17,6 @@ export function Tracing(tracer) {
         }
     };
 }
-export function getControllers() {
-    return controllers.map((controller) => Registry.inject(controller));
-}
-export function flushControllers() {
-    controllers.map((controller) => {
-        Registry.remove(controller);
-    });
-    controllers = [];
-}
 function isClass(fn) {
     return /^\s*class\s/.test(Function.prototype.toString.call(fn));
 }
@@ -78,7 +65,8 @@ export function Post(config = {}) {
             body: config.body,
             bodyFilter: config.bodyFilter || 'none',
             statusCode: config.statusCode || 200,
-            responseType: config.responseType || 'json'
+            responseType: config.responseType || 'json',
+            validator: config.validator
         }, target, propertyKey);
     };
 }
@@ -91,7 +79,8 @@ export function Get(config = {}) {
             query: config.query,
             headers: config.headers,
             statusCode: config.statusCode || 200,
-            responseType: config.responseType || 'json'
+            responseType: config.responseType || 'json',
+            validator: config.validator
         }, target, propertyKey);
     };
 }
@@ -106,7 +95,8 @@ export function Put(config = {}) {
             body: config.body,
             bodyFilter: config.bodyFilter || 'none',
             statusCode: config.statusCode || 200,
-            responseType: config.responseType || 'json'
+            responseType: config.responseType || 'json',
+            validator: config.validator
         }, target, propertyKey);
     };
 }
@@ -121,7 +111,8 @@ export function Patch(config = {}) {
             body: config.body,
             bodyFilter: config.bodyFilter || 'none',
             statusCode: config.statusCode || 200,
-            responseType: config.responseType || 'json'
+            responseType: config.responseType || 'json',
+            validator: config.validator
         }, target, propertyKey);
     };
 }
@@ -136,7 +127,8 @@ export function Delete(config = {}) {
             body: config.body,
             bodyFilter: config.bodyFilter || 'none',
             statusCode: config.statusCode || 200,
-            responseType: config.responseType || 'json'
+            responseType: config.responseType || 'json',
+            validator: config.validator
         }, target, propertyKey);
     };
 }

package/dist/application/index.d.ts

@@ -1,5 +1,5 @@
 import { Controller, Post, Get, Put, Delete, Patch, UseMiddleware, UseMiddlewares, Tracing, type Middleware, type Input, type Tracer, type TracerData } from './controller';
-import { Entity, Restrict, VirtualProperty, Serialize, GetterPrefix, BeforeToEntity, AfterToEntity } from './entity';
+import { Entity, Restrict, VirtualProperty, Serialize, GetterPrefix, BeforeToEntity, AfterToEntity } from '../infra/serialization/entity';
 import { DecorateUseCase, UseCase } from './usecase';
 import { Storage, type StorageGateway } from './services';
 export { Controller, UseMiddleware, UseMiddlewares, Post, Get, Put, Delete, Patch, Tracing, DecorateUseCase, UseCase, Storage, Entity, Restrict, VirtualProperty, Serialize, GetterPrefix, BeforeToEntity, AfterToEntity, };

package/dist/application/index.js

@@ -1,5 +1,5 @@
 import { Controller, Post, Get, Put, Delete, Patch, UseMiddleware, UseMiddlewares, Tracing } from './controller';
-import { Entity, Restrict, VirtualProperty, Serialize, GetterPrefix, BeforeToEntity, AfterToEntity } from './entity';
+import { Entity, Restrict, VirtualProperty, Serialize, GetterPrefix, BeforeToEntity, AfterToEntity } from '../infra/serialization/entity';
 import { DecorateUseCase, UseCase } from './usecase';
 import { Storage } from './services';
 export { Controller, UseMiddleware, UseMiddlewares, Post, Get, Put, Delete, Patch, Tracing, DecorateUseCase, UseCase, Storage, Entity, Restrict, VirtualProperty, Serialize, GetterPrefix, BeforeToEntity, AfterToEntity, };

package/dist/application/services.d.ts

@@ -1,7 +1,8 @@
+import { Container } from "../infra/di/registry";
 import 'reflect-metadata';
 export interface StorageGateway {
     save(file: File, path: string): Promise<void>;
     get(key: string): Promise<string>;
     delete(key: string): Promise<boolean>;
 }
-export declare function Storage(gatewayName: string): (target: any, propertyKey: string) => void;
+export declare function Storage(gatewayName: string, container?: Container): (target: any, propertyKey: string) => void;

package/dist/application/services.js

@@ -1,12 +1,12 @@
-import { Registry } from "../infra/di/registry";
+import { DefaultContainer } from "../infra/di/registry";
 import 'reflect-metadata';
-export function Storage(gatewayName) {
+export function Storage(gatewayName, container = DefaultContainer) {
     return function (target, propertyKey) {
         let dependency;
         Object.defineProperty(target, propertyKey, {
             get: function () {
                 if (!dependency) {
-                    dependency = Registry.inject(gatewayName);
+                    dependency = container.inject(gatewayName);
                 }
                 if (!dependency.save || !dependency.get || !dependency.delete) {
                     throw new Error(`${gatewayName} is not a valid StorageGateway`);

package/dist/dede.d.ts

@@ -1,3 +1,4 @@
+import { Container } from "./infra/di/registry";
 export type Register = {
     name: string;
     classLoader: any;
@@ -8,15 +9,23 @@ export type Options = {
         port?: number;
         middlewares?: CallableFunction[];
     };
+    controllers?: any[];
     registries: Register[];
     defaultServerError?: string;
+    container?: Container;
 };
 export declare class Dede {
     private readonly framework;
     private readonly defaultServerError?;
+    private readonly container;
     private readonly httpServer;
+    private readonly port?;
+    private controllersRegistered;
     private constructor();
-    static start({ framework, registries, defaultServerError }: Options): Promise<Dede>;
+    static create({ framework, registries, defaultServerError, container }: Options): Promise<Dede>;
+    static start({ framework, registries, defaultServerError, container, controllers }: Options): Promise<Dede>;
     stop(): Promise<void>;
+    registerControllers(controllers: any[]): void;
+    listen(port?: number): void;
     private static loadRegistries;
 }

package/dist/dede.js

@@ -1,11 +1,14 @@
 import ControllerHandler from "./http/controller.handler";
 import { ElysiaServerAdapter } from "./http/elysia-server.adapter";
 import { ExpressServerAdapter } from "./http/express-server.adapter";
-import { Registry } from "./infra/di/registry";
+import { Container, DefaultContainer, setDefaultContainer } from "./infra/di/registry";
 export class Dede {
-    constructor(framework, defaultServerError) {
+    constructor(framework, defaultServerError, container = DefaultContainer) {
         this.framework = framework;
         this.defaultServerError = defaultServerError;
+        this.container = container;
+        this.controllersRegistered = false;
+        this.port = framework.port;
         if (framework.use === 'elysia') {
             this.httpServer = new ElysiaServerAdapter(framework.middlewares || []);
         }
@@ -14,19 +17,37 @@ export class Dede {
         }
         if (defaultServerError)
             this.httpServer.setDefaultMessageError(defaultServerError);
-        new ControllerHandler(this.httpServer, framework.port || 80);
     }
-    static async start({ framework, registries, defaultServerError }) {
-        await this.loadRegistries(registries);
-        return new Dede(framework, defaultServerError);
+    static async create({ framework, registries, defaultServerError, container }) {
+        const appContainer = container ?? new Container();
+        setDefaultContainer(appContainer);
+        await this.loadRegistries(appContainer, registries);
+        return new Dede(framework, defaultServerError, appContainer);
+    }
+    static async start({ framework, registries, defaultServerError, container, controllers }) {
+        const app = await Dede.create({ framework, registries, defaultServerError, container, controllers });
+        if (controllers && controllers.length > 0) {
+            app.registerControllers(controllers);
+        }
+        app.listen();
+        return app;
     }
     async stop() {
         await this.httpServer.close();
     }
-    static async loadRegistries(registries) {
+    registerControllers(controllers) {
+        if (this.controllersRegistered)
+            return;
+        new ControllerHandler(this.httpServer, controllers);
+        this.controllersRegistered = true;
+    }
+    listen(port) {
+        const resolvedPort = port ?? this.port ?? 80;
+        this.httpServer.listen(resolvedPort);
+    }
+    static async loadRegistries(container, registries) {
         registries.forEach(({ classLoader, name }) => {
-            Registry.load(name, classLoader);
+            container.load(name, classLoader);
         });
-        return new Promise(resolve => setTimeout(resolve, 500));
     }
 }

package/dist/domain/entity.d.ts

@@ -0,0 +1,4 @@
+export declare abstract class Entity {
+    [x: string]: any;
+    protected generateGetters(): void;
+}

package/dist/domain/entity.js

@@ -0,0 +1,25 @@
+export class Entity {
+    generateGetters() {
+        for (const property of Object.keys(this)) {
+            if (typeof this[property] === 'function')
+                continue;
+            let prefixName = null;
+            // @ts-ignore
+            if (this.constructor.propertiesConfigs && this.constructor.propertiesConfigs[property] && this.constructor.propertiesConfigs[property].prefix) {
+                // @ts-ignore
+                prefixName = this.constructor.propertiesConfigs[property].prefix;
+            }
+            else {
+                const isBoolean = this[property] ? typeof this[property] === 'boolean' : false;
+                prefixName = isBoolean ? 'is' : 'get';
+            }
+            let getterName = null;
+            if (property[0]) {
+                getterName = `${prefixName}${property[0].toUpperCase()}${property.slice(1)}`;
+                if (this[getterName])
+                    continue;
+                this[getterName] = () => this[property];
+            }
+        }
+    }
+}

package/dist/domain/errors/app-error.d.ts

@@ -0,0 +1,12 @@
+export type AppErrorData = {
+    message: string;
+    code?: string;
+    details?: Record<string, any>;
+};
+export declare abstract class AppError extends Error {
+    private readonly statusCode;
+    private readonly data?;
+    constructor(message: string, statusCode: number, data?: AppErrorData);
+    getStatusCode(): number;
+    getData(): AppErrorData | undefined;
+}

package/dist/domain/errors/app-error.js

@@ -0,0 +1,14 @@
+export class AppError extends Error {
+    constructor(message, statusCode, data) {
+        super(message);
+        this.name = this.constructor.name;
+        this.statusCode = statusCode;
+        this.data = data;
+    }
+    getStatusCode() {
+        return this.statusCode;
+    }
+    getData() {
+        return this.data;
+    }
+}

package/dist/domain/errors/http-errors.d.ts

@@ -0,0 +1,42 @@
+import { AppError } from './app-error';
+export declare class BadRequest extends AppError {
+    constructor(message: string, data?: {
+        code?: string;
+        details?: Record<string, any>;
+    });
+}
+export declare class Unauthorized extends AppError {
+    constructor(message: string, data?: {
+        code?: string;
+        details?: Record<string, any>;
+    });
+}
+export declare class Forbidden extends AppError {
+    constructor(message: string, data?: {
+        code?: string;
+        details?: Record<string, any>;
+    });
+}
+export declare class NotFound extends AppError {
+    constructor(message: string, data?: {
+        code?: string;
+        details?: Record<string, any>;
+    });
+}
+export declare class Conflict extends AppError {
+    constructor(message: string, data?: {
+        code?: string;
+        details?: Record<string, any>;
+    });
+}
+export declare class UnprocessableEntity extends AppError {
+    constructor(message: string, data?: {
+        code?: string;
+        details?: Record<string, any>;
+    });
+}
+export declare class InternalServerError extends AppError {
+    private readonly unexpectedError;
+    constructor(unexpectedError: string, defaultMessage?: string);
+    getUnexpectedError(): string;
+}

package/dist/domain/errors/http-errors.js

@@ -0,0 +1,40 @@
+import { AppError } from './app-error';
+export class BadRequest extends AppError {
+    constructor(message, data) {
+        super(message, 400, data ? { message, ...data } : undefined);
+    }
+}
+export class Unauthorized extends AppError {
+    constructor(message, data) {
+        super(message, 401, data ? { message, ...data } : undefined);
+    }
+}
+export class Forbidden extends AppError {
+    constructor(message, data) {
+        super(message, 403, data ? { message, ...data } : undefined);
+    }
+}
+export class NotFound extends AppError {
+    constructor(message, data) {
+        super(message, 404, data ? { message, ...data } : undefined);
+    }
+}
+export class Conflict extends AppError {
+    constructor(message, data) {
+        super(message, 409, data ? { message, ...data } : undefined);
+    }
+}
+export class UnprocessableEntity extends AppError {
+    constructor(message, data) {
+        super(message, 422, data ? { message, ...data } : undefined);
+    }
+}
+export class InternalServerError extends AppError {
+    constructor(unexpectedError, defaultMessage = 'Ops, An unexpected error occurred') {
+        super(defaultMessage, 500, { message: defaultMessage });
+        this.unexpectedError = unexpectedError;
+    }
+    getUnexpectedError() {
+        return this.unexpectedError;
+    }
+}

package/dist/domain/index.d.ts

@@ -0,0 +1,2 @@
+import { Entity } from './entity';
+export { Entity };

package/dist/domain/index.js

@@ -0,0 +1,2 @@
+import { Entity } from './entity';
+export { Entity };

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

@@ -1,10 +1,9 @@
 import HttpServer from "../http/http-server";
 export default class ControllerHandler {
-    constructor(httpServer: HttpServer, port: number);
-    private executeMiddlewares;
+    private readonly requestMapper;
+    private readonly middlewareExecutor;
+    private readonly errorMapper;
+    constructor(httpServer: HttpServer, controllers?: any[]);
     private registryControllers;
     private resolveMiddleware;
-    private filter;
-    private extractError;
-    private normalizeBracketNotation;
 }