@ismael1361/router 1.2.91 → 2.0.0

package/README.md

@@ -4,33 +4,49 @@
 [![License](https://img.shields.io/npm/l/@ismael1361/router.svg)](https://github.com/ismael1361/router/blob/main/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-Um módulo moderno e robusto para criar e gerenciar rotas em Express.js com tipagem encadeada forte, útil para tipar conteúdo de escopo e propriedades de requisição como `body`, `params` e `query`. Oferece geração automática de documentação OpenAPI/Swagger integrada.
+Módulo para Express.js com tipagem encadeada forte para `body`, `params`, `query` e propriedades customizadas de `Request`/`Response`. Gera automaticamente documentação OpenAPI 3.0 (Swagger UI, ReDoc e Markdown), code snippets multi-linguagem e oferece sistema de logging por stacks integrado.
 
 ## 📋 Índice
 
 - [Características](#-características)
 - [Instalação](#-instalação)
 - [Início Rápido](#-início-rápido)
-- [API Completa](#-api-completa)
-  - [create](#create)
-  - [middleware](#middleware)
-  - [route](#route)
-  - [Classe Router](#classe-router)
-- [Exemplos Avançados](#-exemplos-avançados)
+- [API](#-api)
+  - [`create()`](#create)
+  - [`router()`](#router)
+  - [`handler()`](#handler)
+  - [`middleware()`](#middleware)
+  - [`HandleError`](#handleerror)
+  - [`Middlewares`](#middlewares)
+- [Interfaces e Tipos](#-interfaces-e-tipos)
+  - [`IApplication`](#iapplication)
+  - [`IRouter`](#irouter)
+  - [`IHandler`](#ihandler)
+  - [`IMiddleware`](#imiddleware)
+  - [`Request`](#request)
+  - [`Response`](#response)
+  - [`SwaggerOptions`](#swaggeroptions)
+- [Métodos HTTP](#-métodos-http)
+- [Rotas e Sub-routers](#-rotas-e-sub-routers)
 - [Documentação OpenAPI/Swagger](#-documentação-openapiswagger)
-- [TypeScript](#-typescript)
+- [Sistema de Stacks (Logging)](#-sistema-de-stacks-logging)
+- [Exemplos Avançados](#-exemplos-avançados)
 - [Contribuindo](#-contribuindo)
 - [Licença](#-licença)
 
 ## ✨ Características
 
-- 🔒 **Tipagem Forte**: Suporte completo a TypeScript com tipos encadeados
-- 📚 **Documentação Automática**: Geração de documentação OpenAPI/Swagger integrada
-- 🔗 **API Fluente**: Interface encadeável e intuitiva para definição de rotas
-- 🛡️ **Middlewares Documentados**: Middlewares com documentação automática
-- 🎯 **Organização Modular**: Suporte a sub-roteadores e rotas agrupadas
-- ⚡ **Performance**: Construído sobre Express.js, mantendo sua eficiência
-- 🧩 **Extensível**: Fácil de estender com tipos personalizados
+- **Tipagem Forte Encadeada** — tipos de `Request` e `Response` acumulados automaticamente a cada `.handler()` encadeado via `JoinRequest`/`JoinResponse`
+- **Inferência de Parâmetros de Rota** — `req.params` tipado diretamente a partir da string de rota (ex.: `"/users/:id"` → `req.params.id: string`)
+- **Documentação OpenAPI 3.0 Automática** — geração de spec, Swagger UI, ReDoc e Markdown a partir de `.doc()` em handlers, middlewares e rotas
+- **Code Snippets** — geração automática de exemplos de código em 20+ linguagens (cURL, Python, Node.js, C#, Go, etc.)
+- **Middlewares Tipados com `.doc()`** — middlewares criados via `middleware()` carregam documentação OpenAPI que é mesclada automaticamente na spec
+- **Sub-routers Modulares** — `router()` e `.route()` permitem compor APIs em módulos independentes com prefixos
+- **Tratamento de Erros Centralizado** — `HandleError` com código HTTP, nível de log e integração automática com o sistema de stacks
+- **Sistema de Stacks** — logging automatizado de erros, warnings e informações em arquivo, com UI HTML acessível por rota
+- **CORS Configurável** — middleware `Middlewares.cors()` com controle granular de origens, métodos, headers e credenciais
+- **Upload de Arquivos** — middleware `Middlewares.files()` com parsing de `multipart/form-data` e filtragem por MIME type
+- **Execução Única de Middleware** — `req.executeOnce()` impede re-execução de middlewares em rotas aninhadas
 
 ## 📦 Instalação
 
@@ -38,8 +54,6 @@ Um módulo moderno e robusto para criar e gerenciar rotas em Express.js com tipa
 npm install @ismael1361/router
 ```
 
-ou
-
 ```bash
 yarn add @ismael1361/router
 ```
@@ -47,680 +61,1123 @@ yarn add @ismael1361/router
 ## 🚀 Início Rápido
 
 ```typescript
-import { create, Middlewares } from '@ismael1361/router';
+import { create, router, middleware, Middlewares, Request } from "@ismael1361/router";
 
 const app = create();
 
-app.middleware(Middlewares.json());
-
-// Crie o roteador com middleware JSON
-const router = app.route();
+// Middlewares globais
+app.use(Middlewares.json());
+app.use(Middlewares.cors({ allowOrigin: "*" }));
 
-// Defina rotas com documentação
-router
-  .get('/users/:id')
-  .handle((req, res) => {
-    res.json({ 
-      id: req.params.id, 
-      name: 'John Doe' 
-    });
+// Rota simples com inferência de parâmetros
+app.get("/users/:id")
+  .handler((req, res) => {
+    // req.params.id é automaticamente inferido como string
+    res.json({ id: req.params.id, name: "John Doe" });
   })
   .doc({
-    summary: 'Obter usuário por ID',
-    description: 'Retorna os detalhes de um usuário específico',
-    tags: ['Users'],
-    params: {
-      id: {
-        description: 'ID do usuário',
-        type: 'string',
-        required: true
-      }
-    },
+    tags: ["Users"],
+    summary: "Obter usuário por ID",
+    parameters: [
+      { name: "id", in: "path", required: true, schema: { type: "string" } },
+    ],
     responses: {
-      200: { description: 'Usuário encontrado' },
-      404: { description: 'Usuário não encontrado' }
-    }
+      200: { description: "Usuário encontrado" },
+      404: { description: "Usuário não encontrado" },
+    },
   });
 
+// Documentação Swagger
+app.defineSwagger({
+  openapi: "3.0.0",
+  info: { title: "Minha API", version: "1.0.0" },
+});
+
 app.listen(3000, () => {
-  console.log('🚀 Servidor rodando na porta 3000');
+  console.log("Servidor: http://localhost:3000");
+  console.log("Swagger:  http://localhost:3000/doc/swagger");
+  console.log("ReDoc:    http://localhost:3000/doc/redoc");
 });
 ```
 
-## 📖 API Completa
+---
+
+## 📖 API
 
-### create
+### `create()`
 
-Cria uma nova instância do roteador aprimorado.
+Cria uma instância de `IApplication`, que encapsula uma aplicação Express com roteamento tipado, documentação OpenAPI e sistema de stacks.
 
 ```typescript
-create<Req extends Request, Res extends Response>(): Router<Req, Res>
+function create(): IApplication;
 ```
 
-**Retorno:** Nova instância do Router com métodos encadeáveis
-
-**Exemplo:**
+**Retorno:** `IApplication` — herda todos os métodos de `IRouter` (`.get()`, `.post()`, `.route()`, `.use()`, `.defineSwagger()`) e métodos do Express (`listen`, `enable`, `disable`, etc.).
 
 ```typescript
-import { create, Request, Response } from '@ismael1361/router';
+import { create } from "@ismael1361/router";
 
-interface CustomRequest extends Request {
-  user?: { id: string; name: string };
-}
+const app = create();
 
-const router = create<CustomRequest>()
-  .middleware(express.json());
+app.get("/hello/:name")
+  .handler((req, res) => {
+    res.send(`Hello, ${req.params.name}!`);
+  });
+
+app.listen(3000, () => {
+  console.log("Server is running on http://localhost:3000");
+});
 ```
 
-### middleware
+---
+
+### `router()`
 
-Cria middlewares reutilizáveis com documentação integrada.
+Cria uma instância independente de `IRouter` para modularizar a API. Pode ser montado em outro router ou aplicação via `.route()` ou `.use()`.
+
+```typescript
+function router(): IRouter;
+```
 
 ```typescript
-middleware<Req extends Request, Res extends Response>(
-  callback: MiddlewareFC<Req, Res>,
-  doc?: MiddlewareFCDoc
-): MiddlewareFC<Req, Res>
+import { create, router } from "@ismael1361/router";
+
+const app = create();
+
+const usersRouter = router();
+
+usersRouter.get("/")
+  .handler((req, res) => {
+    res.json([{ id: "1", name: "Alice" }]);
+  })
+  .doc({ tags: ["Users"], summary: "Listar usuários" });
+
+usersRouter.post("/")
+  .handler((req, res) => {
+    res.status(201).json({ id: "2", ...req.body });
+  })
+  .doc({ tags: ["Users"], summary: "Criar usuário" });
+
+// Montar com prefixo
+app.route("/users", usersRouter);
 ```
 
-**Parâmetros:**
-- `callback`: Função de middleware padrão do Express `(req, res, next)`
-- `doc` (opcional): Objeto com metadados para documentação OpenAPI
+---
 
-**Retorno:** Função de middleware com metadados de documentação anexados
+### `handler()`
 
-**Exemplo:**
+Cria um handler encadeável que combina execução de middlewares com documentação OpenAPI. Cada chamada a `.handler()` adiciona um middleware à cadeia e mescla os tipos de `Request` e `Response` via `JoinRequest`/`JoinResponse`.
 
 ```typescript
-import { middleware, Request } from '@ismael1361/router';
+function handler<Rq extends Request, Rs extends Response>(
+  fn: RequestHandler<Rq, Rs>
+): IHandler<Rq, Rs>;
+```
 
-interface AuthRequest extends Request<
-  "api_key" | "token", 
-  { 
-    api_key?: string; 
-    token?: string 
-  }
-> {
-  user: { id: string; roles: string[] };
-}
+```typescript
+import { handler } from "@ismael1361/router";
 
-const isAuthenticated = middleware<AuthRequest>(
-  (req, res, next) => {
-    const token = req.headers.authorization;
-    
-    if (token === 'Bearer meu-token-secreto') {
-      req.user = { id: '123', roles: ['admin', 'user'] };
-      return next();
-    }
-    
-    res.status(401).json({ message: 'Não autorizado' });
-  },
-  {
-    security: [{ bearerAuth: [] }],
-    responses: {
-      401: { 
-        description: 'Token de autenticação inválido ou não fornecido' 
-      }
-    }
-  }
-);
-
-// Usar o middleware
-router
-  .get('/profile')
-  .middleware(isAuthenticated)
-  .handle((req, res) => {
-    res.json({ user: req.user });
+const myHandler = handler((req, res, next) => {
+  console.log("Primeiro middleware");
+  next();
+})
+  .handler((req, res) => {
+    res.json({ status: "ok" });
+  })
+  .doc({
+    tags: ["Health"],
+    summary: "Health check",
   });
 ```
 
-### route
+> Na maioria dos casos, `handler()` é usado internamente pelo router ao registrar rotas (`.get()`, `.post()`, etc.). O uso direto é raro.
+
+---
 
-Cria uma instância de rota para agrupar múltiplos métodos HTTP sob o mesmo caminho.
+### `middleware()`
+
+Cria um middleware reutilizável com suporte a documentação OpenAPI. Os tipos genéricos do middleware são mesclados automaticamente quando encadeado via `.handler()`.
 
 ```typescript
-route<Req extends Request, Res extends Response>(
-  path?: string
-): Router<Req, Res>
+function middleware<Req extends Request, Res extends Response>(
+  fn: RequestHandler<Req, Res>
+): IMiddleware<Req, Res>;
 ```
 
-**Parâmetros:**
-- `path`: Caminho da URL para a rota
-
-**Retorno:** Nova instância do Router "travada" no path especificado
+O middleware retornado **não** possui o método `.handler()` — apenas `.doc()`. Ele deve ser encadeado via `.handler()` de um `IHandler`.
 
-**Exemplo:**
+#### Middleware simples
 
 ```typescript
-import { route } from '@ismael1361/router';
+import { middleware } from "@ismael1361/router";
 
-const tasksRouter = route('/tasks');
+const logMiddleware = middleware((req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
+});
 
-// GET /tasks/items
-tasksRouter
-  .get('/items')
-  .handle((req, res) => {
-    res.json([{ id: 1, title: 'Aprender @ismael1361/router' }]);
-  })
-  .doc({
-    summary: 'Listar todas as tarefas',
-    tags: ['Tasks'],
-    responses: { 200: { description: 'Lista de tarefas' } }
+app.get("/users")
+  .handler(logMiddleware)
+  .handler((req, res) => {
+    res.json([]);
   });
+```
 
-// POST /tasks/item
-tasksRouter
-  .post('/item')
-  .handle((req, res) => {
-    const newTask = req.body;
-    res.status(201).json({ id: 2, ...newTask });
-  })
-  .doc({
-    summary: 'Criar nova tarefa',
-    tags: ['Tasks'],
-    body: { description: 'Dados da nova tarefa' },
-    responses: { 201: { description: 'Tarefa criada' } }
+#### Middleware com tipo customizado e documentação
+
+```typescript
+import { middleware, Request } from "@ismael1361/router";
+
+interface AuthRequest extends Request {
+  user: { userId: string; roles: string[] };
+}
+
+const authMiddleware = middleware((req: AuthRequest, res, next) => {
+  const token = req.headers.authorization?.replace("Bearer ", "");
+  if (!token) {
+    res.status(401).json({ error: "Token ausente" });
+    return;
+  }
+  req.user = { userId: "123", roles: ["admin"] };
+  next();
+}).doc({
+  security: [{ bearerAuth: [] }],
+  components: {
+    securitySchemes: {
+      bearerAuth: { type: "http", scheme: "bearer" },
+    },
+  },
+});
+
+// Ao encadear, req.user é inferido automaticamente
+app.get("/profile")
+  .handler(authMiddleware)
+  .handler((req, res) => {
+    // req.user.userId está disponível com tipagem
+    res.json({ userId: req.user.userId });
   });
+```
 
-// Adicionar ao roteador principal
-mainRouter.by(tasksRouter);
+#### Middleware de validação de body
+
+```typescript
+interface BodyRequest extends Request<string, { name: string; email: string }> {}
+
+const validateBody = middleware((req: BodyRequest, res, next) => {
+  if (!req.body.name || !req.body.email) {
+    res.status(400).json({ error: "name e email são obrigatórios" });
+    return;
+  }
+  next();
+}).doc({
+  requestBody: {
+    required: true,
+    content: {
+      "application/json": {
+        schema: {
+          type: "object",
+          required: ["name", "email"],
+          properties: {
+            name: { type: "string" },
+            email: { type: "string", format: "email" },
+          },
+        },
+      },
+    },
+  },
+});
+
+app.post("/users")
+  .handler(validateBody)
+  .handler((req, res) => {
+    // req.body.name e req.body.email inferidos como string
+    res.status(201).json({ name: req.body.name, email: req.body.email });
+  });
 ```
 
-### Classe Router
+---
 
-A classe principal que encapsula o roteador do Express com API fluente e tipada.
+### `HandleError`
 
-#### Propriedades
+Classe de erro para tratamento padronizado de erros HTTP. Integra-se automaticamente com o sistema de stacks e o tratamento centralizado de erros do router.
 
-##### `.app`
 ```typescript
-router: express.Express
+class HandleError extends Error {
+  constructor(
+    message: string,
+    name?: string,                   // default: "DEFAULT"
+    cause?: number | Error | string, // código HTTP ou causa
+    level?: "ERROR" | "WARN" | "INFO" | "NONE", // default: "ERROR"
+    source?: string,
+    duration?: number,
+  );
+
+  get code(): number;   // código HTTP extraído de cause
+  get status(): { code: number; message: string };
+  get meta(): any;
+}
 ```
-Instância do Express subjacente.
 
-##### `.routes`
 ```typescript
-routes: Array<{
-  path: string;
-  methods: string[];
-  type: "ROUTE" | "MIDDLEWARE";
-  swagger?: Pick<swaggerJSDoc.OAS3Definition, "paths" | "components">;
-}>
-```
-Array de rotas e middlewares registrados para geração de documentação.
+import { HandleError } from "@ismael1361/router";
 
-#### Métodos HTTP
+// Erro 404
+throw new HandleError("Recurso não encontrado", "NOT_FOUND", 404);
 
-##### `.get(path: string, doc?: MiddlewareFCDoc)`
-Registra uma rota GET.
+// Erro de validação (nível WARN, não polui logs de erro)
+throw new HandleError("Campo email inválido", "VALIDATION_ERROR", 400, "WARN");
 
-```typescript
-router
-  .get('/status')
-  .handle((req, res) => {
-    res.json({ status: 'ok' });
-  })
-  .doc({
-    summary: 'Verificar status da API',
-    tags: ['Health'],
-    responses: { 200: { description: 'API funcionando' } }
+// Uso em handler
+app.get("/users/:id")
+  .handler((req, res) => {
+    const user = findUser(req.params.id);
+    if (!user) {
+      throw new HandleError("Usuário não encontrado", "NOT_FOUND", 404);
+    }
+    res.json(user);
   });
 ```
 
-##### `.post(path: string, doc?: MiddlewareFCDoc)`
-Registra uma rota POST.
+O erro é capturado automaticamente pelo sistema interno (`tryHandler`) e retorna resposta JSON padronizada:
 
-```typescript
-router
-  .post('/users')
-  .handle((req, res) => {
-    const newUser = req.body;
-    res.status(201).json({ id: Date.now(), ...newUser });
-  })
-  .doc({
-    summary: 'Criar novo usuário',
-    tags: ['Users'],
-    body: {
-      description: 'Dados do usuário',
-      schema: {
-        type: 'object',
-        properties: {
-          name: { type: 'string' },
-          email: { type: 'string' }
-        }
-      }
-    },
-    responses: { 201: { description: 'Usuário criado' } }
-  });
+```json
+{ "message": "Usuário não encontrado", "name": "NOT_FOUND", "code": 404 }
 ```
 
-##### `.put(path: string, doc?: MiddlewareFCDoc)`
-Registra uma rota PUT para substituição completa de recursos.
+---
 
-##### `.patch(path: string, doc?: MiddlewareFCDoc)`
-Registra uma rota PATCH para atualizações parciais.
+### `Middlewares`
 
-##### `.delete(path: string, doc?: MiddlewareFCDoc)`
-Registra uma rota DELETE para remoção de recursos.
+Namespace com middlewares prontos para uso, importável via `Middlewares`.
 
-##### `.options(path: string, doc?: MiddlewareFCDoc)`
-Registra uma rota OPTIONS para requisições de pré-voo CORS.
+```typescript
+import { Middlewares } from "@ismael1361/router";
+```
+
+#### `Middlewares.json(options?)`
 
-##### `.head(path: string, doc?: MiddlewareFCDoc)`
-Registra uma rota HEAD para obter metadados sem corpo de resposta.
+Analisa corpos de requisição JSON. Wrapper de `body-parser.json()`.
 
-##### `.all(path: string, doc?: MiddlewareFCDoc)`
-Registra uma rota que responde a todos os métodos HTTP.
+```typescript
+app.use(Middlewares.json());
+app.use(Middlewares.json({ limit: "10mb" }));
+```
 
-#### Métodos de Configuração
+#### `Middlewares.raw(options?)`
 
-##### `.use(path?: string, doc?: MiddlewareFCDoc)`
-Monta middlewares em um caminho específico.
+Analisa corpos de requisição como `Buffer`.
 
 ```typescript
-router.use('/api').handle((req, res, next) => {
-  console.log(`[${new Date().toISOString()}] ${req.method} ${req.originalUrl}`);
-  next();
-});
+app.use(Middlewares.raw({ type: "application/octet-stream", limit: "10mb" }));
 ```
 
-##### `.route(path?: string)`
-Cria um sub-roteador com prefixo.
+#### `Middlewares.text(options?)`
+
+Analisa corpos de requisição como texto.
 
 ```typescript
-const usersRouter = mainRouter.route('/users');
+app.use(Middlewares.text({ type: "text/plain" }));
+```
 
-usersRouter
-  .get('/')
-  .handle((req, res) => {
-    res.json([{ id: '1', name: 'Alice' }]);
-  });
+#### `Middlewares.urlencoded(options?)`
+
+Analisa dados de formulário `application/x-www-form-urlencoded`.
+
+```typescript
+app.use(Middlewares.urlencoded({ extended: true }));
 ```
 
-##### `.middleware(callback: MiddlewareFC, doc?: MiddlewareFCDoc)`
-Aplica middleware a todas as rotas subsequentes.
+#### `Middlewares.cors(options?)`
+
+Configura CORS com controle granular.
 
 ```typescript
-const router = create(app)
-  .middleware(express.json())
-  .middleware(authMiddleware);
+// Permitir todas as origens
+app.use(Middlewares.cors({ allowOrigin: "*" }));
+
+// Origem específica com opções
+app.use(Middlewares.cors({
+  allowOrigin: "https://meusite.com",
+  allowedMethods: ["GET", "POST", "PUT", "DELETE"],
+  allowedHeaders: ["Content-Type", "Authorization"],
+  credentials: true,
+  exposeHeaders: ["Content-Length"],
+}));
+
+// Sintaxe alternativa: string + objeto
+app.use(Middlewares.cors("https://meusite.com", {
+  allowedMethods: ["GET", "POST"],
+  credentials: true,
+}));
 ```
 
-##### `.handler(callback: HandlerFC, doc?: MiddlewareFCDoc)`
-Define a função controladora para processar requisições.
+**`CorsOptions`:**
+
+| Propriedade      | Tipo                        | Descrição                                                        |
+|------------------|-----------------------------|------------------------------------------------------------------|
+| `allowOrigin`    | `string`                    | Origem permitida (`"*"` para todas)                              |
+| `allowedMethods` | `string[] \| string`        | Métodos HTTP permitidos                                          |
+| `allowedHeaders` | `string[] \| string`        | Headers que o cliente pode enviar                                |
+| `credentials`    | `boolean`                   | Permite cookies e headers de autenticação                        |
+| `exposeHeaders`  | `string[] \| string`        | Headers adicionais legíveis pelo cliente                         |
+
+#### `Middlewares.files(...allowedMimes)`
+
+Parsing de arquivos `multipart/form-data`. Os arquivos ficam disponíveis em `req.file` (primeiro) e `req.files` (todos).
 
 ```typescript
-router
-  .get('/status')
+import { Middlewares } from "@ismael1361/router";
+
+// Aceitar qualquer tipo de arquivo
+app.post("/upload")
+  .handler(Middlewares.files())
   .handler((req, res) => {
-    res.json({ status: 'ok' });
+    // req.file: FileInfo (primeiro arquivo)
+    // req.files: FileInfo[] (todos os arquivos)
+    res.json({
+      filename: req.file.originalname,
+      size: req.file.size,
+      mimetype: req.file.mimetype,
+    });
+  });
+
+// Aceitar apenas imagens e PDFs
+app.post("/upload-docs")
+  .handler(Middlewares.files("image/jpeg", "image/png", "application/pdf"))
+  .handler((req, res) => {
+    res.json({ count: req.files.length });
   });
 ```
 
-##### `.by(router: ExpressRouter | Router)`
-Anexa um roteador existente ao atual.
+**`FileInfo`:**
 
-```typescript
-const productsRouter = route('/products');
-// ... definir rotas
+| Propriedade    | Tipo       | Descrição                   |
+|----------------|------------|-----------------------------|
+| `fieldname`    | `string`   | Nome do campo do formulário |
+| `originalname` | `string`   | Nome original do arquivo    |
+| `mimetype`     | `string`   | Tipo MIME do arquivo        |
+| `size`         | `number`   | Tamanho em bytes            |
+| `buffer`       | `Buffer`   | Conteúdo do arquivo         |
+| `stream`       | `Readable` | Stream legível              |
 
-mainRouter.by(productsRouter);
+---
+
+## 🔷 Interfaces e Tipos
+
+### `IApplication`
+
+Estende `IRouter` com capacidades de servidor HTTP e sistema de stacks.
+
+```typescript
+interface IApplication extends IRouter {
+  listen: express.Application["listen"];
+  disable: express.Application["disable"];
+  enable: express.Application["enable"];
+  disabled: express.Application["disabled"];
+  enabled: express.Application["enabled"];
+  engine: express.Application["engine"];
+  param: express.Application["param"];
+  render: express.Application["render"];
+
+  getStacks(): IStackLog[];
+  defineStacks(options?: IStacksOptions): { stacksPath: string };
+}
 ```
 
-##### `.defineSwagger(options: SwaggerOptions)`
-Gera as rotas de documentação para a especificação OpenAPI completa.
+---
+
+### `IRouter`
+
+Interface principal do router. Expõe métodos HTTP, sub-rotas, middlewares e configuração Swagger.
 
 ```typescript
-import { create } from '@ismael1361/router';
+interface IRouter extends RequestHandler {
+  // Métodos HTTP — retornam IHandler com parâmetros inferidos da rota
+  all:     IRouterMatcher<"all">;
+  get:     IRouterMatcher<"get">;
+  post:    IRouterMatcher<"post">;
+  put:     IRouterMatcher<"put">;
+  delete:  IRouterMatcher<"delete">;
+  patch:   IRouterMatcher<"patch">;
+  options: IRouterMatcher<"options">;
+  head:    IRouterMatcher<"head">;
+
+  parent: IRouter | null;
+  path: string;
 
-const router = create();
+  param: express.Application["param"];
 
-const swaggerDefinition = {
-  openapi: '3.0.0',
-  info: {
-    title: 'Minha API',
-    version: '1.0.0',
-    description: 'API com documentação automática'
-  },
-  servers: [{ url: 'http://localhost:3000' }],
-  components: {
-    securitySchemes: {
-      bearerAuth: {
-        type: 'http',
-        scheme: 'bearer',
-        bearerFormat: 'JWT'
-      }
-    }
-  },
-  defaultResponses: {
-    400: { description: "Dados inválidos" },
-    401: {
-      description: "Falha na autenticação",
-    },
-    403: { description: "Acesso negado" },
-    500: { description: "Erro interno do servidor" },
-  },
-};
+  route(prefix: string, doc?: MiddlewareFCDoc): IRouter;
+  route(prefix: string, router: IRouter, doc?: MiddlewareFCDoc): IRouter;
+  route(router: IRouter, doc?: MiddlewareFCDoc): IRouter;
 
-router.defineSwagger(swaggerDefinition);
-// By swagger json -> /doc/swagger/definition.json
-// By swagger      -> /doc/swagger
-// By redoc        -> /doc/redoc
+  use(prefix: string, doc?: MiddlewareFCDoc): IHandler;
+  use(prefix: string, handler: IRouter | RequestHandler, doc?: MiddlewareFCDoc): void;
+  use(handler: IRouter | RequestHandler, doc?: MiddlewareFCDoc): void;
+
+  defineSwagger(options: SwaggerOptions): void;
+  getSwagger(): swaggerJSDoc.Options;
+}
 ```
 
-## 🎯 Exemplos Avançados
+---
 
-### Autenticação e Autorização
+### `IHandler`
+
+Handler encadeável que combina execução de middlewares com documentação OpenAPI. Cada `.handler()` mescla tipos cumulativamente.
 
 ```typescript
-import { create, middleware, Middlewares, Request } from '@ismael1361/router';
+interface IHandler<Rq extends Request, Rs extends Response> extends RequestHandler<Rq, Rs> {
+  handler<Req extends Request, Res extends Response>(
+    fn: RequestHandler<Req & Rq, Res & Rs> | IHandler<Req & Rq, Res & Rs>
+  ): IHandler<JoinRequest<Rq, Req>, JoinResponse<Rs, Res>>;
+
+  doc(
+    operation: MiddlewareFCDoc | swaggerJSDoc.Operation,
+    components?: swaggerJSDoc.Components
+  ): IHandler<Rq, Rs>;
+}
+```
+
+**Encadeamento e mesclagem de tipos:**
 
+```typescript
 interface AuthRequest extends Request {
   user: { id: string; roles: string[] };
 }
 
-// Middleware de autenticação
-const authenticate = middleware<AuthRequest>(
-  (req, res, next) => {
-    const token = req.headers.authorization?.replace('Bearer ', '');
-    
-    if (!token) {
-      return res.status(401).json({ message: 'Token não fornecido' });
-    }
-    
-    // Validar token (exemplo simplificado)
-    req.user = { id: '123', roles: ['user'] };
-    next();
-  },
-  {
-    security: [{ bearerAuth: [] }],
-    responses: {
-      401: { description: 'Não autorizado' }
-    }
-  }
-);
-
-// Middleware de autorização
-const authorize = (...roles: string[]) => 
-  middleware<AuthRequest>(
-    (req, res, next) => {
-      if (!req.user.roles.some(role => roles.includes(role))) {
-        return res.status(403).json({ message: 'Acesso negado' });
-      }
-      next();
-    },
-    {
-      responses: {
-        403: { description: 'Acesso negado' }
-      }
-    }
-  );
-
-const app = create<AuthRequest>()
-  .middleware(Middlewares.json());
+interface PaginatedRequest extends Request<string, any, { page: number; limit: number }> {}
 
-// Rota protegida
-app
-  .get('/admin/users')
-  .middleware(authenticate)
-  .middleware(authorize('admin'))
-  .handle((req, res) => {
-    res.json({ users: [] });
-  })
-  .doc({
-    summary: 'Listar usuários (Admin)',
-    tags: ['Admin'],
-    responses: { 200: { description: 'Lista de usuários' } }
+app.get("/items")
+  .handler(authMiddleware)          // req agora tem .user
+  .handler(paginationMiddleware)    // req agora tem .user + .query.page + .query.limit
+  .handler((req, res) => {
+    // Todos os tipos estão disponíveis simultaneamente
+    console.log(req.user.id);       // string
+    console.log(req.query.page);    // number
+    res.json([]);
   });
 ```
 
-### Validação de Dados
+---
+
+### `IMiddleware`
+
+Middleware sem `.handler()`, apenas `.doc()`. Deve ser encadeado dentro de um `IHandler`.
 
 ```typescript
-import { middleware, Request } from '@ismael1361/router';
+interface IMiddleware<Rq extends Request, Rs extends Response> extends RequestHandler<Rq, Rs> {
+  doc(
+    operation: MiddlewareFCDoc | swaggerJSDoc.Operation,
+    components?: swaggerJSDoc.Components
+  ): IMiddleware<Rq, Rs>;
+}
+```
 
-interface ValidatedRequest extends Request {
-  validated: {
-    body?: any;
-    params?: any;
-    query?: any;
-  };
+---
+
+### `Request`
+
+Estende `express.Request` com parâmetros genéricos tipados.
+
+```typescript
+interface Request<
+  P extends string = string,      // Parâmetros de rota
+  ReqBody = {},                   // Corpo da requisição
+  ReqQuery = core.Query,          // Query string
+  ResBody = any                   // Corpo da resposta
+> extends core.Request<ParamsDictionary<P>, ResBody, ReqBody, ReqQuery> {
+  clientIp?: string;
+  executeOnce?: (isOnce?: boolean) => void;
 }
+```
 
-const validate = (schema: any) => 
-  middleware<ValidatedRequest>(
-    (req, res, next) => {
-      // Implementar validação (ex: usando Zod, Joi, etc)
-      const result = schema.safeParse(req.body);
-      
-      if (!result.success) {
-        return res.status(400).json({ 
-          message: 'Dados inválidos',
-          errors: result.error.errors 
-        });
-      }
-      
-      req.validated = { body: result.data };
-      next();
-    },
-    {
-      responses: {
-        400: { description: 'Dados de entrada inválidos' }
-      }
-    }
-  );
+```typescript
+// Parâmetros inferidos da rota
+app.get("/users/:userId/posts/:postId")
+  .handler((req, res) => {
+    req.params.userId;  // string ✓
+    req.params.postId;  // string ✓
+  });
 
-router
-  .post('/users')
-  .middleware(validate(userSchema))
-  .handle((req, res) => {
-    const validatedData = req.validated.body;
-    res.status(201).json(validatedData);
+// Tipo explícito de body
+interface CreateUser extends Request<string, { name: string; email: string }> {}
+
+app.post("/users")
+  .handler((req: CreateUser, res) => {
+    req.body.name;   // string ✓
+    req.body.email;  // string ✓
   });
 ```
 
-### Organização Modular
+---
+
+### `Response`
+
+Estende `express.Response`.
 
 ```typescript
-// routes/users.routes.ts
-import { route } from '@ismael1361/router';
+interface Response<ResBody = any> extends core.Response<ResBody> {}
+```
 
-export const usersRouter = route('/users');
+---
 
-usersRouter
-  .get('/')
-  .handle((req, res) => {
-    res.json([]);
+### `SwaggerOptions`
+
+Configuração para geração de documentação OpenAPI.
+
+```typescript
+interface SwaggerOptions extends swaggerJSDoc.OAS3Definition {
+  path?: string;                    // Prefixo das rotas de doc (default: "/doc")
+  defaultResponses?: Responses;     // Respostas padrão para todas as rotas
+  targets?: SnippetTargets[];       // Linguagens para code snippets
+}
+```
+
+**`SnippetTargets` disponíveis:**
+
+`c_libcurl`, `csharp_restsharp`, `csharp_httpclient`, `go_native`, `java_okhttp`, `java_unirest`, `javascript_jquery`, `javascript_xhr`, `node_native`, `node_request`, `node_unirest`, `objc_nsurlsession`, `ocaml_cohttp`, `php_curl`, `php_http1`, `php_http2`, `python_python3`, `python_requests`, `ruby_native`, `shell_curl`, `shell_httpie`, `shell_wget`, `swift_nsurlsession`
+
+---
+
+## 🔀 Métodos HTTP
+
+Todos os métodos HTTP retornam um `IHandler` com inferência automática de parâmetros de rota.
+
+```typescript
+// Assinatura
+app.get<Path extends string>(path: Path, doc?: MiddlewareFCDoc): IHandler<Request<ExtractRouteParameters<Path>>>;
+```
+
+**Métodos disponíveis:** `get`, `post`, `put`, `delete`, `patch`, `options`, `head`, `all`
+
+```typescript
+// GET — leitura de recursos
+app.get("/status")
+  .handler((req, res) => {
+    res.json({ status: "ok" });
+  })
+  .doc({ tags: ["Health"], summary: "Status da API" });
+
+// POST — criação de recursos
+app.post("/users")
+  .handler((req, res) => {
+    res.status(201).json({ id: Date.now(), ...req.body });
   })
   .doc({
-    summary: 'Listar usuários',
-    tags: ['Users']
+    tags: ["Users"],
+    summary: "Criar usuário",
+    requestBody: {
+      required: true,
+      content: {
+        "application/json": {
+          schema: {
+            type: "object",
+            required: ["name", "email"],
+            properties: {
+              name: { type: "string" },
+              email: { type: "string", format: "email" },
+            },
+          },
+        },
+      },
+    },
+    responses: { 201: { description: "Usuário criado" } },
   });
 
-usersRouter
-  .post('/')
-  .handle((req, res) => {
-    res.status(201).json(req.body);
+// PUT — substituição completa
+app.put("/users/:id")
+  .handler((req, res) => {
+    res.json({ id: req.params.id, ...req.body });
   })
-  .doc({
-    summary: 'Criar usuário',
-    tags: ['Users']
+  .doc({ tags: ["Users"], summary: "Substituir usuário" });
+
+// PATCH — atualização parcial
+app.patch("/users/:id")
+  .handler((req, res) => {
+    res.json({ id: req.params.id, updated: true });
+  })
+  .doc({ tags: ["Users"], summary: "Atualizar usuário parcialmente" });
+
+// DELETE — remoção
+app.delete("/users/:id")
+  .handler((req, res) => {
+    res.sendStatus(204);
+  })
+  .doc({ tags: ["Users"], summary: "Remover usuário" });
+
+// ALL — responde a qualquer método
+app.all("/proxy/*")
+  .handler((req, res) => {
+    res.json({ method: req.method, url: req.url });
   });
+```
+
+**Documentação inline via segundo argumento:**
+
+```typescript
+app.post("/items", { tags: ["Items"], summary: "Criar item" })
+  .handler((req, res) => {
+    res.status(201).json({ id: 1 });
+  });
+```
+
+---
+
+## 🔗 Rotas e Sub-routers
+
+### `.route()` — Sub-router com prefixo
+
+```typescript
+// Criar sub-router inline
+const usersRoute = app.route("/users");
+usersRoute.get("/").handler((req, res) => res.json([]));
+usersRoute.get("/:id").handler((req, res) => res.json({ id: req.params.id }));
+
+// Anexar router existente com documentação global
+const v1 = router();
+
+v1.get("/items")
+  .handler((req, res) => res.json([]))
+  .doc({ tags: ["Items"], summary: "Listar itens" });
+
+v1.post("/items")
+  .handler((req, res) => res.status(201).json(req.body))
+  .doc({ tags: ["Items"], summary: "Criar item" });
+
+// Documentação aplicada a todas as rotas do sub-router
+app.route("/v1", v1, {
+  security: [{ bearerAuth: [] }],
+  responses: {
+    400: { description: "Dados inválidos" },
+    404: { description: "Não encontrado" },
+  },
+});
+```
+
+### `.use()` — Middleware ou sub-router
+
+```typescript
+// Middleware global
+app.use((req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
+});
+
+// Middleware em prefixo (retorna IHandler encadeável)
+app.use("/api")
+  .handler((req, res, next) => {
+    console.log("Requisição na /api");
+    next();
+  });
+
+// Sub-router via use
+const adminRouter = router();
+app.use("/admin", adminRouter);
+```
+
+### Organização modular
+
+```typescript
+// routes/users.ts
+import { router } from "@ismael1361/router";
+
+export const usersRouter = router();
+
+usersRouter.get("/")
+  .handler((req, res) => res.json([]))
+  .doc({ tags: ["Users"], summary: "Listar usuários" });
+
+usersRouter.post("/")
+  .handler((req, res) => res.status(201).json(req.body))
+  .doc({ tags: ["Users"], summary: "Criar usuário" });
 
-// routes/products.routes.ts
-export const productsRouter = route('/products');
-// ... definir rotas
+// routes/products.ts
+import { router } from "@ismael1361/router";
+
+export const productsRouter = router();
+
+productsRouter.get("/")
+  .handler((req, res) => res.json([]))
+  .doc({ tags: ["Products"], summary: "Listar produtos" });
 
 // app.ts
-import { create } from '@ismael1361/router';
-import { usersRouter } from './routes/users.routes';
-import { productsRouter } from './routes/products.routes';
+import { create, Middlewares } from "@ismael1361/router";
+import { usersRouter } from "./routes/users";
+import { productsRouter } from "./routes/products";
+
+const app = create();
+app.use(Middlewares.json());
 
-const app = express();
-const router = create(app)
-  .middleware(express.json());
+app.route("/users", usersRouter);
+app.route("/products", productsRouter);
+
+app.defineSwagger({
+  openapi: "3.0.0",
+  info: { title: "API Modular", version: "1.0.0" },
+});
 
-router
-  .by(usersRouter)
-  .by(productsRouter);
+app.listen(3000);
 ```
 
+---
+
 ## 📚 Documentação OpenAPI/Swagger
 
-O módulo gera automaticamente documentação OpenAPI 3.0 compatível com Swagger UI.
+### `.doc()` — Documentação em handlers e middlewares
 
-### Configuração Completa
+Anexa metadados OpenAPI sem alterar o fluxo de execução. Pode ser chamado em qualquer ponto da cadeia.
 
 ```typescript
-import { create, Middlewares } from '@ismael1361/router';
+app.get("/users/:userId")
+  .handler(authMiddleware)
+  .doc({
+    tags: ["Users"],
+    summary: "Buscar usuário por ID",
+    parameters: [
+      { name: "userId", in: "path", required: true, schema: { type: "string" } },
+    ],
+  })
+  .handler((req, res) => {
+    res.json({ userId: req.params.userId });
+  });
+```
 
-const app = create().middleware(Middlewares.json());
+**`.doc()` com componentes:**
 
-// Definir rotas com documentação
-app
-  .get('/users/:id')
-  .handle((req, res) => {
-    res.json({ id: req.params.id, name: 'John Doe' });
-  })
-  .doc({
-    summary: 'Obter usuário',
-    description: 'Retorna um usuário pelo ID',
-    tags: ['Users'],
-    params: {
-      id: {
-        description: 'ID do usuário',
-        type: 'string',
-        required: true,
-        example: '123'
-      }
+```typescript
+app.delete("/users/:id")
+  .handler(authMiddleware)
+  .doc(
+    {
+      tags: ["Users"],
+      summary: "Remover usuário",
+      security: [{ bearerAuth: [] }],
     },
-    responses: {
-      200: {
-        description: 'Usuário encontrado',
-        content: {
-          'application/json': {
-            schema: {
-              type: 'object',
-              properties: {
-                id: { type: 'string' },
-                name: { type: 'string' }
-              }
-            }
-          }
-        }
+    {
+      securitySchemes: {
+        bearerAuth: { type: "http", scheme: "bearer" },
       },
-      404: { description: 'Usuário não encontrado' }
-    }
+    },
+  )
+  .handler((req, res) => {
+    res.sendStatus(204);
   });
+```
+
+### `.defineSwagger()` — Configuração completa
+
+Habilita a geração de documentação e cria automaticamente as seguintes rotas:
+
+| Rota                          | Descrição                        |
+|-------------------------------|----------------------------------|
+| `/doc/swagger`                | Interface Swagger UI             |
+| `/doc/swagger/definition.json`| Spec OpenAPI JSON                |
+| `/doc/redoc`                  | Interface ReDoc                  |
+| `/doc/markdown`               | Documentação em Markdown         |
+| `/doc/.md`                    | Markdown raw                     |
 
-// Configurar Swagger
+```typescript
 app.defineSwagger({
-  openapi: '3.0.0',
+  openapi: "3.0.0",
   info: {
-    title: 'API de Exemplo',
-    version: '1.0.0',
-    description: 'Documentação automática gerada com @ismael1361/router',
-    contact: {
-      name: 'Suporte',
-      email: 'suporte@exemplo.com'
-    }
+    title: "API de Exemplo",
+    version: "1.0.0",
+    description: "Documentação completa da API",
+    contact: { name: "Suporte", email: "suporte@example.com" },
   },
   servers: [
-    {
-      url: 'http://localhost:3000',
-      description: 'Servidor de desenvolvimento'
-    },
-    {
-      url: 'https://api.exemplo.com',
-      description: 'Servidor de produção'
-    }
+    { url: "http://localhost:3000", description: "Desenvolvimento" },
+    { url: "https://api.exemplo.com", description: "Produção" },
   ],
   components: {
     securitySchemes: {
       bearerAuth: {
-        type: 'http',
-        scheme: 'bearer',
-        bearerFormat: 'JWT',
-        description: 'Token JWT no formato Bearer'
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "JWT",
       },
-      apiKey: {
-        type: 'apiKey',
-        in: 'header',
-        name: 'X-API-Key'
-      }
-    }
+    },
   },
+  // Respostas de erro aplicadas a todas as rotas
   defaultResponses: {
-    500: { description: 'Erro interno do servidor' },
-    429: { description: 'Muitas requisições' }
-  }
+    400: { description: "Dados inválidos" },
+    401: { description: "Falha na autenticação" },
+    403: { description: "Acesso negado" },
+    500: { description: "Erro interno do servidor" },
+  },
+  // Linguagens de code snippets (opcional)
+  targets: ["shell_curl", "javascript_xhr", "node_native", "python_python3"],
 });
+```
 
-app.listen(3000, () => {
-  console.log('🚀 Servidor: http://localhost:3000');
-  console.log('📚 Docs-swagger: http://localhost:3000/docs/swagger');
-  console.log('📚 Docs-redoc: http://localhost:3000/docs/redoc');
+### `.getSwagger()` — Obter spec programaticamente
+
+```typescript
+const spec = app.getSwagger();
+console.log(JSON.stringify(spec.definition, null, 2));
+```
+
+---
+
+## 📊 Sistema de Stacks (Logging)
+
+Disponível apenas em `IApplication` (criado via `create()`). Registra erros, warnings e informações em arquivo de log, com UI HTML acessível por rota.
+
+### `.defineStacks(options?)`
+
+```typescript
+interface IStacksOptions {
+  path?: string;       // Rota da UI (default: "/stacks")
+  limit?: number;      // Máximo de registros no arquivo (default: 100)
+  filePath?: string;   // Caminho do arquivo de log (default: "./stacks.log")
+  beforeStack?(...stacks: IStackLog[]): Array<IStackLog | string | Error>;
+}
+```
+
+```typescript
+const { stacksPath } = app.defineStacks({
+  path: "/stacks",
+  limit: 200,
+  filePath: "./logs/stacks.log",
+  beforeStack(...stacks) {
+    // Filtrar ou transformar antes de salvar
+    return stacks.filter((s) => typeof s !== "string" && s.level === "ERROR");
+  },
 });
+
+console.log(`Stacks UI: http://localhost:3000${stacksPath}`);
 ```
 
-## 🔷 TypeScript
+Ao ativar stacks, `console.error()`, `console.warn()` e `console.info()` são interceptados automaticamente e registrados no arquivo de log. Erros não capturados (`unhandledRejection`, `uncaughtException`) também são registrados.
 
-O módulo é totalmente tipado e oferece excelente suporte ao TypeScript.
+### `.getStacks()`
 
-### Tipos Personalizados
+```typescript
+const logs: IStackLog[] = app.getStacks();
+logs.forEach((log) => {
+  console.log(`[${log.level}] ${log.name}: ${log.message} (${log.duration}ms)`);
+});
+```
+
+**`IStackLog`:**
+
+| Propriedade  | Tipo                                        | Descrição                      |
+|--------------|---------------------------------------------|--------------------------------|
+| `time`       | `Date`                                      | Timestamp do registro          |
+| `level`      | `"ERROR" \| "WARN" \| "INFO" \| "DEBUG"`   | Nível de severidade            |
+| `name`       | `string`                                    | Nome/categoria do log          |
+| `message`    | `string`                                    | Mensagem descritiva            |
+| `source`     | `string`                                    | Origem do log                  |
+| `statusCode` | `number`                                    | Código HTTP associado          |
+| `duration`   | `number`                                    | Duração em ms                  |
+| `meta`       | `string`                                    | Metadados adicionais           |
+
+---
+
+## 🎯 Exemplos Avançados
+
+### Autenticação e Autorização
 
 ```typescript
-import { Request, Response } from '@ismael1361/router';
+import { create, middleware, Middlewares, Request } from "@ismael1361/router";
 
-// Estender Request
-interface CustomRequest extends Request {
-  user?: {
-    id: string;
-    email: string;
-    roles: string[];
-  };
-  requestId: string;
-  startTime: number;
+interface AuthRequest extends Request {
+  user: { id: string; roles: string[] };
 }
 
-// Estender Response
-interface CustomResponse extends Response {
-  sendSuccess: (data: any) => void;
-  sendError: (message: string, code?: number) => void;
+const authenticate = middleware((req: AuthRequest, res, next) => {
+  const token = req.headers.authorization?.replace("Bearer ", "");
+  if (!token) {
+    res.status(401).json({ error: "Token não fornecido" });
+    return;
+  }
+  req.user = { id: "123", roles: ["admin"] };
+  next();
+}).doc({
+  security: [{ bearerAuth: [] }],
+  components: {
+    securitySchemes: {
+      bearerAuth: { type: "http", scheme: "bearer" },
+    },
+  },
+});
+
+const authorize = (...roles: string[]) =>
+  middleware((req: AuthRequest, res, next) => {
+    if (!req.user.roles.some((r) => roles.includes(r))) {
+      res.status(403).json({ error: "Acesso negado" });
+      return;
+    }
+    next();
+  });
+
+const app = create();
+app.use(Middlewares.json());
+
+app.get("/admin/users")
+  .handler(authenticate)
+  .handler(authorize("admin"))
+  .handler((req, res) => {
+    // req.user está tipado
+    res.json({ adminId: req.user.id, users: [] });
+  })
+  .doc({
+    tags: ["Admin"],
+    summary: "Listar usuários (Admin)",
+    responses: { 200: { description: "Lista de usuários" } },
+  });
+```
+
+### Encadeamento de múltiplos handlers com tipos acumulados
+
+```typescript
+interface AuthRequest extends Request {
+  user: { userId: string; id: string; roles: string[] };
 }
 
-// Usar tipos personalizados
-const router = create<CustomRequest, CustomResponse>(app);
+const authMiddleware = middleware((req: AuthRequest, res, next) => {
+  req.user = { userId: "123", id: "abc", roles: ["admin"] };
+  next();
+}).doc({
+  security: [{ bearerAuth: [] }],
+});
+
+app.get("/hello/:userId/:id")
+  .handler(authMiddleware)        // req ganha .user
+  .handler((req, res, next) => {
+    // req.user e req.params.userId/id estão disponíveis
+    console.log(`Usuário: ${req.user.userId}`);
+    next();
+  })
+  .doc({
+    tags: ["Users"],
+    summary: "Saudação personalizada",
+    parameters: [
+      { name: "userId", in: "path", required: true, schema: { type: "string" } },
+      { name: "id", in: "path", required: true, schema: { type: "string" } },
+    ],
+  })
+  .handler((req, res) => {
+    res.send(`Hello, ${req.params.userId}! ID: ${req.user.id}`);
+  });
+```
+
+### Execução única de middleware
+
+```typescript
+const expensiveMiddleware = middleware((req, res, next) => {
+  req.executeOnce?.(); // Garante uma única execução por requisição
+  console.log("Operação custosa executada uma vez");
+  next();
+});
+
+// Mesmo aplicado em vários níveis, executa apenas uma vez
+app.use("/api")
+  .handler(expensiveMiddleware)
+  .handler((req, res, next) => { next(); });
 
-router
-  .get('/profile')
-  .handle((req, res) => {
-    // req.user está totalmente tipado
-    // res.sendSuccess está disponível
-    res.sendSuccess({ user: req.user });
+app.get("/api/data")
+  .handler(expensiveMiddleware) // Não executa novamente
+  .handler((req, res) => {
+    res.json({ data: [] });
   });
 ```
 
-### Inferência de Tipos
+### Aplicação completa com sub-routers, Swagger e stacks
 
 ```typescript
-import { Request } from '@ismael1361/router';
+import { create, router, middleware, Middlewares, Request } from "@ismael1361/router";
+
+const app = create();
 
-// Os tipos são inferidos automaticamente
-router
-  .get('/users/:id')
-  .handle<Request<any, any, "id">>((req, res) => {
-    // req.params é Record<"id", any>
-    // req.params.id é any
-    // req.query é Record<string, any>
-    // req.body é any (pode ser tipado com middleware)
-    const userId: string = req.params.id;
+app.use(Middlewares.json());
+app.use(Middlewares.cors({ allowOrigin: "*" }));
+
+// --- Middleware de autenticação ---
+interface AuthRequest extends Request<"userId" | "id"> {
+  user: { userId: string; id: string; roles: string[] };
+}
+
+const authMiddleware = middleware((req: AuthRequest, res, next) => {
+  const { userId = "", id = "" } = req.params;
+  req.user = { userId, id, roles: ["admin"] };
+  next();
+}).doc({
+  security: [{ bearerAuth: [] }],
+  components: {
+    securitySchemes: {
+      bearerAuth: { type: "http", scheme: "bearer" },
+    },
+  },
+});
+
+// --- Rota direta na aplicação ---
+app.get("/hello/:userId/:id")
+  .handler(authMiddleware)
+  .handler((req, res, next) => {
+    console.log(`Hello, ${req.user.id}!`);
+    next();
+  })
+  .doc({ tags: ["Users"] })
+  .handler((req, res) => {
+    res.send(`Hello, ${req.params.userId}! ID: ${req.user.userId}`);
+  })
+  .doc({
+    summary: "Saudação com autenticação",
+    parameters: [
+      { name: "userId", in: "path", required: true, schema: { type: "string" } },
+      { name: "id", in: "path", required: true, schema: { type: "string" } },
+    ],
   });
+
+// --- Sub-router v1 ---
+const v1 = router();
+
+v1.get("/test/route")
+  .handler((req, res) => {
+    res.send("Hello from route!");
+  })
+  .doc({ tags: ["V1"], summary: "Rota de teste v1" });
+
+app.route("/v1", v1, {
+  security: [{ bearerAuth: [] }],
+  responses: {
+    400: { description: "Account not found" },
+    404: { description: "Not found" },
+  },
+});
+
+// --- Swagger ---
+app.defineSwagger({
+  openapi: "3.0.0",
+  info: { title: "My API", version: "1.0.0" },
+  defaultResponses: {
+    400: { description: "Dados inválidos" },
+    401: { description: "Falha na autenticação" },
+    403: { description: "Acesso negado" },
+    500: { description: "Erro interno do servidor" },
+  },
+});
+
+// --- Stacks ---
+app.defineStacks({
+  path: "/stacks",
+  limit: 100,
+  filePath: "./stacks.log",
+});
+
+app.listen(8080, () => {
+  console.log("Server: http://localhost:8080");
+  console.log("Swagger: http://localhost:8080/doc/swagger");
+  console.log("ReDoc:   http://localhost:8080/doc/redoc");
+  console.log("Stacks:  http://localhost:8080/stacks");
+});
 ```
 
-## 🤝 Contribuindo
+---
 
-Contribuições são bem-vindas! Por favor, siga estas etapas:
+## 🤝 Contribuindo
 
 1. Faça um fork do projeto
 2. Crie uma branch para sua feature (`git checkout -b feature/MinhaFeature`)
@@ -732,12 +1189,6 @@ Contribuições são bem-vindas! Por favor, siga estas etapas:
 
 Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](MIT) para mais detalhes.
 
-## 🙏 Agradecimentos
-
-- Express.js pela base sólida
-- Swagger/OpenAPI pela especificação de documentação
-- A comunidade TypeScript
-
 ---
 
-Desenvolvido com ❤️ por [Ismael Souza Silva](https://github.com/ismael1361)
+Desenvolvido com ❤️ por [Ismael Souza Silva](https://github.com/ismael1361)