@ismael1361/router 1.0.1 → 1.0.6

package/dist/router.d.ts

@@ -1,236 +1,207 @@
 import type swaggerJSDoc from "swagger-jsdoc";
-import { ExpressRouter, HandlerFC, MiddlewareFC, RouterMethods, Request, Response } from "./type";
-import { RequestHandler, PreparedHandler } from "./handler";
+import type { MiddlewareCallback, MiddlewareFCDoc, NextFunction, Request, Response, SwaggerOptions } from "./type";
+import { Handler, RequestHandler } from "./handler";
+import { Layer } from "./Layer";
+import * as http from "http";
+import { Express } from "express";
 /**
- * A classe `Router` é um wrapper em torno do roteador do Express, oferecendo uma API fluente
- * e encadeável para a definição de rotas. Ela aprimora a experiência de desenvolvimento com
- * segurança de tipos e geração de documentação OpenAPI/Swagger integrada.
+ * A classe principal do roteador, que encapsula e aprimora o roteador do Express.
+ * Fornece uma API fluente e fortemente tipada para definir rotas, aplicar middlewares
+ * e gerar documentação OpenAPI (Swagger/ReDoc) de forma integrada.
  *
- * @template Rq - O tipo base para o objeto de requisição (request) em todas as rotas deste roteador.
- * @template Rs - O tipo base para o objeto de resposta (response) em todas as rotas.
+ * @template Rq - O tipo base de `Request` para este roteador.
+ * @template Rs - O tipo base de `Response` para este roteador.
  *
  * @example
- * import express, { Request, Response } from "express";
- * import { Router } from "./router"; // Ajuste o caminho do import conforme sua estrutura.
- * import swaggerUi from "swagger-ui-express";
+ * import { create, Middlewares } from '@ismael1361/router';
  *
- * // 1. Crie uma nova instância do Router.
- * const userRouter = new Router();
+ * const app = create();
+ * app.middleware(Middlewares.json());
  *
- * // 2. Defina uma rota com um manipulador e documentação.
- * userRouter
- *   .get("/:id")
- *   .handler((req: Request<{ id: string }>, res: Response) => {
- *     const { id } = req.params;
- *     res.json({ id: Number(id), name: "John Doe" });
- *   })
- *   .doc({
- *     summary: "Obter um usuário pelo ID",
- *     tags: ["Usuários"],
- *     parameters: [
- *       {
- *         name: "id",
- *         in: "path",
- *         required: true,
- *         description: "O ID do usuário",
- *         schema: { type: "integer" },
- *       },
- *     ],
- *     responses: {
- *       "200": {
- *         description: "Detalhes do usuário.",
- *         content: {
- *           "application/json": {
- *             schema: {
- *               type: "object",
- *               properties: {
- *                 id: { type: "integer" },
- *                 name: { type: "string" },
- *               },
- *             },
- *           },
- *         },
- *       },
- *       "404": {
- *         description: "Usuário não encontrado",
- *       }
- *     },
+ * app.get('/health', { summary: 'Verifica a saúde da API' })
+ *   .handler((req, res) => {
+ *     res.status(200).send('OK');
  *   });
  *
- * // 3. Crie um aplicativo Express e use o roteador.
- * const app = express();
- * app.use(express.json());
- *
- * // A propriedade `.router` contém a instância do roteador Express, pronta para ser usada.
- * app.use("/users", userRouter.router);
- *
- * // 4. (Opcional) Gere e sirva a documentação Swagger.
- * const swaggerOptions = userRouter.getSwagger({
- *   openapi: "3.0.0",
- *   info: {
- *     title: "API de Usuários",
- *     version: "1.0.0",
- *   },
- * });
- * app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerOptions));
- *
  * app.listen(3000, () => {
- *   console.log("Servidor rodando em http://localhost:3000");
- *   console.log("Documentação da API em http://localhost:3000/api-docs");
+ *   console.log('Servidor rodando na porta 3000');
  * });
  */
 export declare class Router<Rq extends Request = Request, Rs extends Response = Response> {
-    readonly middlewares: MiddlewareFC<any, any>[];
-    readonly router: ExpressRouter;
-    readonly rootPath: string;
-    readonly previousRouter?: Router | undefined;
-    constructor(middlewares?: MiddlewareFC<any, any>[], router?: ExpressRouter, rootPath?: string, previousRouter?: Router | undefined);
+    readonly routePath: string;
+    readonly layers: Layer;
+    /** A instância subjacente do Express. */
+    app: Express;
+    private express_router;
     /**
-     * Adiciona um middleware que será aplicado a todas as rotas definidas subsequentemente
-     * nesta cadeia de roteamento.
-     *
-     * Este método é imutável: ele retorna uma **nova instância** do `Router` com o middleware
-     * adicionado, permitindo o encadeamento seguro e a composição de diferentes conjuntos de middlewares.
-     * A tipagem dos objetos `Request` e `Response` é aprimorada para refletir as modificações
-     * feitas pelo middleware.
+     * @internal
+     * @param {string} [routePath=""] - O prefixo de caminho para este roteador.
+     * @param {Layer} [layers=new Layer()] - A camada interna para gerenciar rotas e middlewares.
+     */
+    constructor(routePath?: string, layers?: Layer);
+    /**
+     * Anexa documentação OpenAPI a um grupo de rotas (um roteador).
+     * Útil para definir informações comuns, como tags, para um conjunto de rotas.
      *
-     * @template Req - O tipo de `Request` que o middleware adiciona ou modifica.
-     * @template Res - O tipo de `Response` que o middleware adiciona ou modifica.
+     * @param {swaggerJSDoc.Operation} operation - O objeto de operação OpenAPI.
+     * @param {swaggerJSDoc.Components} [components={}] - Componentes OpenAPI.
+     */
+    doc(operation: swaggerJSDoc.Operation, components?: swaggerJSDoc.Components): void;
+    /**
+     * Aplica um middleware a todas as rotas subsequentes definidas neste roteador.
      *
-     * @param {MiddlewareFC<Rq & Req, Rs & Res>} callback - A função de middleware a ser adicionada.
-     *   Esta função pode modificar os objetos `req` e `res`, e suas tipagens serão propagadas
-     *   para os manipuladores de rota subsequentes.
+     * @template Req - Tipo de `Request` estendido pelo middleware.
+     * @template Res - Tipo de `Response` estendido pelo middleware.
+     * @param {MiddlewareCallback<Rq & Req, Rs & Res>} callback - A função ou componente de middleware.
+     * @param {MiddlewareFCDoc} [doc] - Documentação OpenAPI opcional para este middleware.
+     * @returns {Router<Rq & Req, Rs & Res>} A instância do roteador com os tipos atualizados.
+     */
+    middleware<Req extends Request = Request, Res extends Response = Response>(callback: MiddlewareCallback<Rq & Req, Rs & Res>, doc?: MiddlewareFCDoc): Router<Rq & Req, Rs & Res>;
+    /**
+     * Executa a cadeia de middlewares globais aplicados diretamente a esta instância do roteador.
+     * Este método é útil principalmente para testes, permitindo invocar a lógica dos middlewares
+     * do roteador de forma isolada, sem a necessidade de um servidor HTTP completo.
      *
-     * @returns {Router<Rq & Req, Rs & Res>} Uma nova instância do `Router` com o middleware
-     *   e os tipos de requisição/resposta atualizados.
+     * @param {Rq} request - O objeto de requisição (ou um mock para testes).
+     * @param {Rs} response - O objeto de resposta (ou um mock para testes).
+     * @param {NextFunction} next - A função `next` a ser chamada ao final da cadeia de middlewares.
+     * @returns {Promise<void>} Uma promessa que resolve quando a execução da cadeia é concluída.
      *
      * @example
-     * import { Router } from "./router";
-     * import { Request, Response, NextFunction } from "express";
-     *
-     * // Middleware de autenticação que adiciona 'user' ao objeto de requisição.
-     * interface AuthenticatedRequest {
-     *   user: { id: number; name: string };
-     * }
+     * import { create, Request, Response, NextFunction } from '@ismael1361/router';
      *
-     * const authMiddleware = (req: Request, res: Response, next: NextFunction) => {
-     *   // Em um cenário real, você validaria um token aqui.
-     *   (req as Request & AuthenticatedRequest).user = { id: 1, name: "Admin" };
+     * // 1. Crie um roteador e adicione middlewares globais a ele
+     * const app = create();
+     * app.middleware<{ traceId: string }>((req, res, next) => {
+     *   req.traceId = 'xyz-123';
      *   next();
-     * };
+     * });
      *
-     * const baseRouter = new Router();
-     * const authenticatedRouter = baseRouter.middleware<AuthenticatedRequest>(authMiddleware);
+     * // 2. Crie mocks para os objetos de requisição, resposta e next
+     * const mockRequest = {} as Request & { traceId: string };
      *
-     * authenticatedRouter.get("/profile").handler((req, res) => {
-     *   // `req.user` está disponível e corretamente tipado.
-     *   res.json({ message: `Bem-vindo, ${req.user.name}!` });
-     * });
+     * // 3. Execute a cadeia de middlewares do roteador
+     * await app.executeMiddlewares(mockRequest, {} as Response, () => {});
+     * console.log(mockRequest.traceId); // Output: 'xyz-123'
      */
-    middleware<Req extends Request = Request, Res extends Response = Response>(callback: MiddlewareFC<Rq & Req, Rs & Res>): Router<Rq & Req, Rs & Res>;
+    executeMiddlewares(request: Rq, response: Rs, next: NextFunction): Promise<any>;
     /**
-     * Encapsula uma função de handler final e todos os middlewares encadeados anteriormente
-     * em uma única instância reutilizável de `PreparedHandler`.
-     *
-     * Este método é o ponto final para a criação de "controllers" ou "actions" modulares.
-     * Ele pega a lógica do handler e a combina com os middlewares definidos na cadeia do roteador
-     * (`.middleware(...)`), produzindo um objeto que pode ser passado para o método `.handler()`
-     * de uma definição de rota (por exemplo, `router.get(...).handler(controller)`).
-     *
-     * @template Req - Tipos de requisição adicionais inferidos a partir do handler.
-     * @template Res - Tipos de resposta adicionais inferidos a partir do handler.
-     * @param {HandlerFC<Rq & Req, Rs & Res>} callback - A função de handler final ou uma instância de `PreparedHandler` já existente. Se um `PreparedHandler` for fornecido, seus middlewares serão combinados com os middlewares da cadeia atual.
-     * @returns {PreparedHandler<Rq & Req, Rs & Res>} Uma nova instância de `PreparedHandler` que encapsula o handler e a cadeia completa de middlewares.
+     * Cria um componente de manipulador (handler) reutilizável.
+     * Este método é um atalho para a função `handler` exportada, permitindo criar
+     * um manipulador completo e reutilizável que pode encapsular uma ou mais funções de middleware
+     * e um manipulador final.
      *
      * @example
-     * // 1. Defina middlewares para autenticação e autorização.
-     * interface AuthRequest extends Request { user: { id: number; role: string }; }
-     * const authMiddleware: MiddlewareFC<AuthRequest> = (req, res, next) => {
-     *   req.user = { id: 1, role: 'admin' }; // Simula a autenticação
-     *   next();
-     * };
-     *
-     * const adminOnlyMiddleware: MiddlewareFC<AuthRequest> = (req, res, next) => {
-     *   if (req.user.role !== 'admin') return res.status(403).send('Forbidden');
-     *   next();
-     * };
-     *
-     * // 2. Defina o handler final que depende dos middlewares.
-     * const getDashboard: HandlerFC<AuthRequest> = (req, res) => {
-     *   res.send(`Welcome, admin user ${req.user.id}`);
-     * };
-     *
-     * // 3. Crie um "construtor" de controller encadeando os middlewares.
-     * const controllerBuilder = new Router().middleware(authMiddleware).middleware(adminOnlyMiddleware);
-     *
-     * // 4. Use o método `.handler()` para criar o controller reutilizável.
-     * const getDashboardController = controllerBuilder.handler(getDashboard);
-     *
-     * // 5. Agora, `getDashboardController` pode ser usado em qualquer rota.
-     * const mainRouter = new Router();
-     * mainRouter.get('/admin/dashboard').handler(getDashboardController);
-     * // A rota acima aplicará automaticamente `authMiddleware` e `adminOnlyMiddleware`
-     * // antes de executar `getDashboard`.
+     * // Crie um manipulador reutilizável que primeiro executa um middleware e depois a lógica principal.
+     * const processDataHandler = app.handler(
+     *   middleware(dataValidationMiddleware)
+     *     .handler((req, res) => {
+     *       // A lógica principal do handler aqui.
+     *       res.json({ processedData: req.validatedData });
+     *     })
+     * );
+     *
+     * // Use o manipulador reutilizável em uma rota.
+     * app.post('/process', { summary: 'Processar dados' })
+     *   .handler(processDataHandler);
+     *
+     * @param {MiddlewareCallback<Rq & Req, Rs & Res>} callback - A função ou componente de middleware/handler.
+     * @param {MiddlewareFCDoc} [doc] - Documentação OpenAPI opcional para este manipulador.
+     * @returns {Handler<Rq & Req, Rs & Res>} Uma instância de `Handler` que pode ser usada em rotas.
      */
-    handler<Req extends Request = Request, Res extends Response = Response>(callback: HandlerFC<Rq & Req, Rs & Res>): PreparedHandler<Rq & Req, Rs & Res>;
+    handler<Req extends Request = Request, Res extends Response = Response>(callback: MiddlewareCallback<Rq & Req, Rs & Res>, doc?: MiddlewareFCDoc): Handler<Rq & Req, Rs & Res>;
     /**
-     * Cria um manipulador de rota para requisições GET.
-     * @param {string} path O caminho da rota.
+     * Inicia a definição de uma rota para o método HTTP GET.
+     *
+     * @example
+     * router.get('/users/:id', { summary: 'Obter um usuário' })
+     *   .handler((req, res) => {
+     *     // req.params.id está disponível
+     *     res.json({ id: req.params.id, name: 'John Doe' });
+     *   });
+     *
+     * @param {string} path - O caminho da rota (ex: '/users', '/users/:id').
+     * @param {MiddlewareFCDoc} doc - (Opcional) Documentação OpenAPI para o manipulador de rota.
      * @returns {RequestHandler<Rq, Rs>} Uma instância de `RequestHandler` para encadear middlewares e o manipulador final.
      */
-    get(path: string): RequestHandler<Rq, Rs>;
+    get(path: string, doc?: MiddlewareFCDoc): RequestHandler<Rq, Rs>;
     /**
-     * Cria um manipulador de rota para requisições POST.
-     * @param {string} path O caminho da rota.
+     * Inicia a definição de uma rota para o método HTTP POST.
+     *
+     * @example
+     * router.post('/users', { summary: 'Criar um usuário' })
+     *   .handler((req, res) => {
+     *     const newUser = req.body;
+     *     res.status(201).json({ id: 'new-id', ...newUser });
+     *   });
+     *
+     * @param {string} path - O caminho da rota.
+     * @param {MiddlewareFCDoc} doc - (Opcional) Documentação OpenAPI para o manipulador de rota.
      * @returns {RequestHandler<Rq, Rs>} Uma instância de `RequestHandler` para encadear middlewares e o manipulador final.
      */
-    post(path: string): RequestHandler<Rq, Rs>;
+    post(path: string, doc?: MiddlewareFCDoc): RequestHandler<Rq, Rs>;
     /**
-     * Cria um manipulador de rota para requisições PUT.
-     * @param {string} path O caminho da rota.
+     * Inicia a definição de uma rota para o método HTTP PUT.
+     * @param {string} path - O caminho da rota.
+     * @param {MiddlewareFCDoc} doc - (Opcional) Documentação OpenAPI para o manipulador de rota.
      * @returns {RequestHandler<Rq, Rs>} Uma instância de `RequestHandler` para encadear middlewares e o manipulador final.
      */
-    put(path: string): RequestHandler<Rq, Rs>;
+    put(path: string, doc?: MiddlewareFCDoc): RequestHandler<Rq, Rs>;
     /**
-     * Cria um manipulador de rota para requisições DELETE.
-     * @param {string} path O caminho da rota.
+     * Inicia a definição de uma rota para o método HTTP DELETE.
+     * @param {string} path - O caminho da rota.
+     * @param {MiddlewareFCDoc} doc - (Opcional) Documentação OpenAPI para o manipulador de rota.
      * @returns {RequestHandler<Rq, Rs>} Uma instância de `RequestHandler` para encadear middlewares e o manipulador final.
      */
-    delete(path: string): RequestHandler<Rq, Rs>;
+    delete(path: string, doc?: MiddlewareFCDoc): RequestHandler<Rq, Rs>;
     /**
-     * Cria um manipulador de rota para requisições PATCH.
-     * @param {string} path O caminho da rota.
+     * Inicia a definição de uma rota para o método HTTP PATCH.
+     * @param {string} path - O caminho da rota.
+     * @param {MiddlewareFCDoc} doc - (Opcional) Documentação OpenAPI para o manipulador de rota.
      * @returns {RequestHandler<Rq, Rs>} Uma instância de `RequestHandler` para encadear middlewares e o manipulador final.
      */
-    patch(path: string): RequestHandler<Rq, Rs>;
+    patch(path: string, doc?: MiddlewareFCDoc): RequestHandler<Rq, Rs>;
     /**
-     * Cria um manipulador de rota para requisições OPTIONS.
-     * @param {string} path O caminho da rota.
+     * Inicia a definição de uma rota para o método HTTP OPTIONS.
+     * @param {string} path - O caminho da rota.
+     * @param {MiddlewareFCDoc} doc - (Opcional) Documentação OpenAPI para o manipulador de rota.
      * @returns {RequestHandler<Rq, Rs>} Uma instância de `RequestHandler` para encadear middlewares e o manipulador final.
      */
-    options(path: string): RequestHandler<Rq, Rs>;
+    options(path: string, doc?: MiddlewareFCDoc): RequestHandler<Rq, Rs>;
     /**
-     * Cria um manipulador de rota para requisições HEAD.
-     * @param {string} path O caminho da rota.
+     * Inicia a definição de uma rota para o método HTTP HEAD.
+     * @param {string} path - O caminho da rota.
+     * @param {MiddlewareFCDoc} doc - (Opcional) Documentação OpenAPI para o manipulador de rota.
      * @returns {RequestHandler<Rq, Rs>} Uma instância de `RequestHandler` para encadear middlewares e o manipulador final.
      */
-    head(path: string): RequestHandler<Rq, Rs>;
+    head(path: string, doc?: MiddlewareFCDoc): RequestHandler<Rq, Rs>;
     /**
-     * Aplica um middleware a um caminho específico. Corresponde a todos os métodos HTTP.
-     * @param {string} path O caminho da rota.
+     * Inicia a definição de uma rota que corresponde a todos os métodos HTTP.
+     * @param {string} path - O caminho da rota.
+     * @param {MiddlewareFCDoc} doc - (Opcional) Documentação OpenAPI para o manipulador de rota.
      * @returns {RequestHandler<Rq, Rs>} Uma instância de `RequestHandler` para encadear middlewares e o manipulador final.
      */
-    all(path: string): RequestHandler<Rq, Rs>;
+    all(path: string, doc?: MiddlewareFCDoc): RequestHandler<Rq, Rs>;
     /**
-     * Aplica um middleware a um caminho específico. Corresponde a todos os métodos HTTP.
-     * @param {string} path O caminho da rota.
+     * Aplica um middleware a um caminho específico, correspondendo a todos os métodos HTTP.
+     *
+     * @example
+     * // Aplica um middleware de log para todas as rotas sob /api
+     * router.use('/api', { tags: ['Logging'] })
+     *   .handler((req, res, next) => {
+     *     console.log('API call:', req.method, req.path);
+     *     next();
+     *   });
+     *
+     * @param {string} path - O caminho da rota.
+     * @param {MiddlewareFCDoc} doc - (Opcional) Documentação OpenAPI para o manipulador de rota.
      * @returns {RequestHandler<Rq, Rs>} Uma instância de `RequestHandler` para encadear middlewares e o manipulador final.
      */
-    use(path: string): RequestHandler<Rq, Rs>;
+    use(path?: string, doc?: MiddlewareFCDoc): RequestHandler<Rq, Rs>;
     /**
-     * Obtém uma lista de todas as rotas e middlewares registrados nesta instância do roteador.
-     * Útil para introspecção e depuração.
-     * @returns {Array<{path: string, methods: string[], type: 'ROUTE' | 'MIDDLEWARE', swagger?: object}>}
+     * Retorna uma lista achatada de todas as rotas finais registradas,
+     * com middlewares e caminhos resolvidos. Útil para depuração.
+     * @returns {Array<object>} Uma lista de objetos de rota.
      */
     get routes(): {
         path: string;
@@ -239,180 +210,86 @@ export declare class Router<Rq extends Request = Request, Rs extends Response =
         swagger?: Pick<swaggerJSDoc.OAS3Definition, "paths" | "components">;
     }[];
     /**
-     * Agrega toda a documentação de rota (definida via `.doc()`) e de middlewares
-     * para gerar uma especificação completa do OpenAPI v3.
-     *
-     * Este método percorre todas as rotas registradas, coleta suas definições de OpenAPI
-     * e as mescla em um único objeto de especificação, que pode ser usado diretamente
-     * com ferramentas como `swagger-ui-express`.
-     *
-     * @param {swaggerJSDoc.OAS3Definition} [options] - Um objeto de definição base do OpenAPI.
-     *   Use-o para fornecer informações globais como `info`, `servers`, `security`, etc.
-     *   A documentação gerada (`paths`, `components`) será mesclada a este objeto.
-     *
-     * @param {swaggerJSDoc.Responses} [defaultResponses={}] - Um objeto contendo respostas padrão
-     *   (por exemplo, `400`, `401`, `500`) que serão adicionadas a **todas** as rotas.
-     *   Se uma rota definir uma resposta com o mesmo código de status, a definição da rota
-     *   terá precedência.
-     *
-     * @returns {swaggerJSDoc.Options} Um objeto de opções completo, pronto para ser usado
-     *   pelo `swagger-jsdoc` ou `swagger-ui-express`.
-     *
-     * @example
-     * import express from "express";
-     * import swaggerUi from "swagger-ui-express";
-     * import { Router } from "./router";
-     *
-     * const apiRouter = new Router();
-     *
-     * apiRouter.get("/health")
-     *   .handler((req, res) => res.send("OK"))
-     *   .doc({
-     *     summary: "Verifica a saúde da API",
-     *     tags: ["Status"],
-     *     responses: { "200": { description: "API está operacional" } }
-     *   });
-     *
-     * // Definições base para o Swagger
-     * const swaggerDefinition = {
-     *   openapi: "3.0.0",
-     *   info: { title: "Minha API", version: "1.0.0" },
-     *   servers: [{ url: "http://localhost:3000" }],
-     * };
-     *
-     * // Respostas padrão para todas as rotas
-     * const defaultResponses = {
-     *   "400": { description: "Requisição inválida" },
-     *   "500": { description: "Erro interno do servidor" },
-     * };
-     *
-     * // Gera as opções do Swagger
-     * const swaggerOptions = apiRouter.getSwagger(swaggerDefinition, defaultResponses);
-     *
-     * // Integra com o Express
-     * const app = express();
-     * app.use('/api', apiRouter.router);
-     * app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerOptions));
-     *
-     * app.listen(3000);
+     * Gera a especificação OpenAPI completa com base na documentação definida.
+     * @param {swaggerJSDoc.OAS3Definition} [options] - Opções de base para a definição OpenAPI.
+     * @param {swaggerJSDoc.Responses} [defaultResponses={}] - Respostas padrão a serem mescladas em todas as rotas.
+     * @returns {swaggerJSDoc.Options} O objeto de opções pronto para ser usado por `swagger-jsdoc`.
      */
     getSwagger(options?: swaggerJSDoc.OAS3Definition, defaultResponses?: swaggerJSDoc.Responses): swaggerJSDoc.Options;
     /**
-     * Cria e retorna um novo sub-roteador que é montado em um prefixo de caminho específico.
-     *
-     * Este método é ideal para organizar rotas relacionadas em módulos. Todas as rotas
-     * definidas no roteador retornado serão prefixadas com o `path` fornecido.
-     * A nova instância do roteador herda os middlewares do roteador pai.
-     *
-     * @param {string} path - O prefixo do caminho para o sub-roteador.
-     * @returns {Router<Rq, Rs>} Uma nova instância de `Router` para definir rotas dentro do caminho especificado.
+     * Define as opções globais de documentação OpenAPI para este roteador.
      *
      * @example
-     * import { Router } from "./router";
-     * import express from "express";
-     *
-     * const app = express();
-     * const mainRouter = new Router();
-     *
-     * // Cria um sub-roteador para a seção de administração.
-     * const adminRouter = mainRouter.route("/admin");
-     *
-     * // Adiciona uma rota ao sub-roteador. O caminho final será "/admin/dashboard".
-     * adminRouter.get("/dashboard").handler((req, res) => {
-     *   res.send("Bem-vindo ao painel de administração!");
+     * app.defineSwagger({
+     *   openapi: '3.0.0',
+     *   info: { title: 'Minha API', version: '1.0.0' },
+     *   path: '/api-docs', // Caminho base para as UIs de documentação
+     *   defaultResponses: {
+     *     500: { description: 'Erro Interno do Servidor' }
+     *   }
      * });
      *
-     * // Usa o roteador principal no aplicativo Express.
-     * app.use(mainRouter.router);
+     * @param {SwaggerOptions} options - As opções de configuração.
      */
-    route(path: string): Router<Rq, Rs>;
+    defineSwagger(options: SwaggerOptions): void;
     /**
-     * Monta um sub-roteador no caminho base da instância atual do roteador.
-     *
-     * Este método permite compor a aplicação anexando um roteador pré-configurado
-     * (seja uma instância de `Router` ou `express.Router`) como um middleware.
-     * Todas as rotas definidas no roteador fornecido serão acessíveis a partir do
-     * ponto de montagem do roteador atual.
-     *
-     * @param {Router | ExpressRouter} router - A instância do roteador a ser montada.
-     * @returns {this} A instância atual do `Router`, permitindo encadeamento de métodos.
+     * Cria um sub-roteador aninhado sob um prefixo de caminho.
      *
      * @example
-     * // ---- user.routes.ts ----
-     * import { Router } from './router';
-     *
-     * const userRouter = new Router();
-     * userRouter.get('/', (req, res) => res.send('Lista de usuários'));
-     * userRouter.get('/:id', (req, res) => res.send(`Detalhes do usuário ${req.params.id}`));
-     *
-     * export default userRouter;
+     * const adminRouter = router.route('/admin');
+     * adminRouter.get('/dashboard', ...); // Rota final: /admin/dashboard
      *
-     * // ---- app.ts ----
-     * import express from 'express';
-     * import { Router } from './router';
-     * import userRouter from './user.routes';
+     * @param {string} path - O prefixo do caminho para o sub-roteador.
+     * @returns {Router<Rq, Rs>} Uma nova instância de `Router` para o sub-roteador.
+     */
+    route(path?: string): Router<Rq, Rs>;
+    /**
+     * Anexa um roteador existente (sub-roteador) a este roteador.
      *
-     * const app = express();
-     * const apiRouter = new Router();
+     * @example
+     * const usersRouter = route('/users');
+     * // ... define rotas em usersRouter ...
      *
-     * // Monta o userRouter no apiRouter.
-     * apiRouter.by(userRouter);
+     * const app = create();
+     * app.by(usersRouter); // Anexa o roteador de usuários ao principal
      *
-     * // Usa o roteador principal na aplicação sob o prefixo '/api'.
-     * // As rotas de userRouter agora são acessíveis em '/api/' e '/api/:id'.
-     * app.use('/api', apiRouter.router);
+     * @param {Router} router - A instância do roteador a ser anexada.
+     * @returns {this} A instância atual do roteador para encadeamento.
      */
-    by(router: Router | ExpressRouter): this;
-}
-/**
- * Representa as propriedades de uma rota finalizada, permitindo a adição de metadados, como a documentação Swagger.
- * Esta classe é retornada pelo método `.handler()` e seu principal objetivo é fornecer o método `.doc()`
- * para anexar a documentação OpenAPI a um endpoint.
- *
- * @example
- * // ... continuação do exemplo do RouterContext
- * router.get("/users/:id")
- *   .handler((req, res) => {
- *     res.json({ id: req.params.id, name: "Exemplo" });
- *   })
- *   // O método .doc() é chamado na instância de RouterProps retornada por .handler()
- *   .doc({
- *     summary: "Obtém um usuário pelo ID",
- *     description: "Retorna os detalhes de um usuário específico.",
- *     tags: ["Users"],
- *     parameters: [{
- *       name: "id",
- *       in: "path",
- *       required: true,
- *       schema: { type: "integer" }
- *     }],
- *     responses: {
- *       "200": {
- *         description: "Usuário encontrado."
- *       }
- *     }
- *   });
- */
-export declare class RouterProps {
-    readonly type: RouterMethods;
-    readonly middlewares: MiddlewareFC<any, any>[];
-    readonly handler: Function;
-    readonly hierarchicalMiddleware: MiddlewareFC<any, any>[];
+    by(router: Router): this;
+    /** Delega para o método `app.engine()` do Express. */
+    engine(ext: string, fn: (path: string, options: object, callback: (e: any, rendered?: string) => void) => void): this;
+    enabled(setting: string): boolean;
+    /** Delega para o método `app.disabled()` do Express. */
+    disabled(setting: string): boolean;
+    /** Delega para o método `app.enable()` do Express. */
+    enable(setting: string): this;
+    /** Delega para o método `app.disable()` do Express. */
+    disable(setting: string): this;
     /**
-     * @param {RouterMethods} type O método HTTP da rota.
-     * @param {MiddlewareFC<any, any>[]} middlewares A lista de middlewares aplicados à rota.
-     * @param {Function} handler A função de handler final da rota.
-     */
-    constructor(type: RouterMethods, middlewares: MiddlewareFC<any, any>[] | undefined, handler: Function, hierarchicalMiddleware?: MiddlewareFC<any, any>[]);
-    /**
-     * Anexa a documentação Swagger/OpenAPI a uma rota.
-     * Esta função mescla a documentação fornecida com qualquer documentação
-     * definida nos middlewares (`middleware.doc`) que foram aplicados à rota.
+     * Inicia o servidor HTTP.
+     * Este método deve ser chamado por último, após todas as rotas e middlewares terem sido definidos.
+     * Ele compila todas as camadas de rotas, configura os endpoints de documentação (se definidos)
+     * e inicia o servidor Express para ouvir as requisições.
+     *
+     * @example
+     * app.listen(3000, () => {
+     *   console.log('Servidor rodando em http://localhost:3000');
+     *   console.log('Documentação Swagger em http://localhost:3000/api-docs/swagger');
+     *   console.log('Documentação ReDoc em http://localhost:3000/api-docs/redoc');
+     * });
      *
-     * @param {swaggerJSDoc.Operation} operation O objeto de operação do OpenAPI que descreve o endpoint.
-     * @param {swaggerJSDoc.Components} [components={}] Definições de componentes reutilizáveis (schemas, securitySchemes, etc.).
-     * @returns {this} Retorna a própria instância de `RouterProps` para permitir encadeamento futuro (se houver).
+     * @param {number} port - A porta em que o servidor irá ouvir.
+     * @param {string} [hostname] - O nome do host.
+     * @param {number} [backlog] - O número máximo de conexões pendentes.
+     * @param {Function} [callback] - Uma função a ser chamada quando o servidor estiver ouvindo.
+     * @returns {http.Server} A instância do servidor HTTP subjacente.
      */
-    doc(operation: swaggerJSDoc.Operation, components?: swaggerJSDoc.Components): this;
+    listen(port: number, hostname: string, backlog: number, callback?: (error?: Error) => void): http.Server;
+    listen(port: number, hostname: string, callback?: (error?: Error) => void): http.Server;
+    listen(port: number, callback?: (error?: Error) => void): http.Server;
+    listen(callback?: (error?: Error) => void): http.Server;
+    listen(path: string, callback?: (error?: Error) => void): http.Server;
+    listen(handle: any, listeningListener?: (error?: Error) => void): http.Server;
 }
 //# sourceMappingURL=router.d.ts.map