routeify-express

routeify-express é uma biblioteca npm que simplifica a criação de rotas no Express através do uso de decorators em classes de controller.

📦 Instalação

Utilize o gerenciador de pacotes de sua preferência para instalar:

pnpm add routeify-express

npm i routeify-express

Para poder utilizar os decorators, é necessário habilitar a opção experimentalDecorators no seu tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

Como usar?

Aqui está um exemplo básico de como usar a biblioteca:

1 - Criar um Controller

controller.ts

import { Controller, Get } from "routeify-express";

@Controller("hello")
class HelloController {
  @Get("world")
  execute() {
    return "Hello World!";
  }
}

2️ - Aplicar o Controller ao seu servidor Express

main.ts

import { createExpressServer } from "routeify-express";
import { HelloController } from "./controller.ts";

const app = createExpressServer({
  controllers: [HelloController],
});

app.listen(3001, () => console.log("Servidor rodando na porta 3001"));

Com este setup, agora temos uma rota GET /hello/world que retorna Hello World!.

Inicializando o servidor

Para inicializar o servidor, você precisa importar o método createExpressServer e passar um objeto de configuração com a lista de controllers.

import { createExpressServer } from "routeify-express";
import { HelloController } from "./controller.ts";

const app = createExpressServer({
  controllers: [HelloController], // Lista de controllers
  defaultExpressJson: true, // Habilita o uso do express.json()
  globalPrefix: "/api", // Prefixo global para todas as rotas
  useGlobalMiddlewares: [], // Lista de middlewares globais
}).listen(3001, () => console.log("Servidor rodando na porta 3001"));

Decorators

• @Controller(path: string): Marca uma classe como um controller.

• @Get(path: string): Define um método como um manipulador de requisição GET.

• @Post(path: string): Define um método como um manipulador de requisição POST.

• @Put(path: string): Define um método como um manipulador de requisição PUT.

• @Delete(path: string): Define um método como um manipulador de requisição DELETE.

• @Patch(path: string): Define um método como um manipulador de requisição PATCH.

• @Status(code: number | StatusCodes): Define o status code da resposta. Pode ser usado em conjunto com os decorators de rota.

  import { Status, StatusCodes, Controller, Post } from "routeify-express";
  @Controller("/users")
  class HelloController {
    @Post()
    @Status(StatusCodes.CREATED)
    createUser() {
      return "User created!";
    }
  }

• @Use(middleware: RequestHandler): Adiciona um middleware à rota.

  import {
    Use,
    Controller,
    Get,
    Request,
    Response,
    NextFunction,
  } from "routeify-express";
  
  function logger(req: Request, res: Response, next: NextFunction) {
    console.log("Request...");
    next();
  }
  
  @Controller("/users")
  class HelloController {
    @Use(logger) // sempre ultilize o middleware antes do método
    @Get()
    getUsers() {
      return "Users";
    }
  }

• @BodyValidator(classValidator: class): Valida o corpo da requisição com a biblioteca class-validator.

  import { IsString } from "class-validator";
  import { BodyValidator, Controller, Post } from "routeify-express";
  
  class CreateUserDto {
    @IsString()
    name: string;
  }
  
  @Controller("/users")
  class HelloController {
    @Post()
    @BodyValidator(CreateUserDto)
    createUser() {
      return "User created!";
    }
  }

  Para ultilizar o BodyValidator é necessário instalar a biblioteca class-validator;

  pnpm add class-validator

[!TIP] 💡 StatusCodes é um enum com os status codes HTTP mais comuns. ele pode ser importado de dentro da biblioteca.

Exeptions

A routeify-express fornece algumas exceções customizadas para cenários comuns em APIs.

HttpException

• Classe base para todas as exceções relacionadas à API.
• Inclui propriedades para código de status, mensagem e detalhes adicionais.

Lista Completa de Exceções Customizadas

• BadRequestException (400 Bad Request): Erro para entrada de dados inválida ou incompleta.
• UnauthorizedException (401 Unauthorized): Erro de autenticação, geralmente quando não há credenciais válidas.
• ForbiddenException (403 Forbidden): Erro de autorização, geralmente quando o usuário não tem permissão para acessar o recurso.
• NotFoundException (404 Not Found): Erro quando o recurso solicitado não foi encontrado.
• MethodNotAllowedException (405 Method Not Allowed): Erro quando o método HTTP utilizado não é permitido para o recurso.
• ConflictException (409 Conflict): Erro quando há um conflito de dados, como tentar criar um registro com um ID já existente.
• InternalServerErrorException (500 Internal Server Error): Erro inesperado no servidor.
• NotImplementedException (501 Not Implemented): Erro quando a funcionalidade solicitada ainda não foi implementada.
• ServiceUnavailableException (503 Service Unavailable): Erro quando o serviço está indisponível temporariamente.
• GatewayTimeoutException (504 Gateway Timeout): Erro de tempo limite ao se comunicar com outro serviço.
• RequestTimeoutException (504 Request Timeout): Erro de tempo limite na requisição do cliente.
• LengthRequiredException (400 Bad Request): Erro quando um campo obrigatório não é fornecido ou está vazio.
• TooManyRequestsException (429 Too Many Requests): Erro quando o cliente excedeu a taxa de requisições permitida.

Exemplo de uso:

import { Controller, Get, BadRequestException } from "routeify-express";

@Controller("hello")
class HelloController {
  @Get("world")
  execute() {
    throw new BadRequestException("Bad Request");
  }
}

Exemplo de resposta:

{
  "message": "Bad Request",
  "status": 400
}

Observações

• As exceções customizadas da routeify-express estendem a classe HttpException.
• Você pode criar suas próprias exceções customizadas extendendo a classe HttpException.
• Ao utilizar as exceções customizadas, você pode personalizar a mensagem de erro e os detalhes da resposta HTTP.

Ultilidades

logger - Objeto com métodos para logar mensagens no console.

import { logger } from "routeify-express";

logger.info("Info message");
logger.warn("Warning message");
logger.error("Error message");

Para mais exemplos, veja a pasta example

📄 Licença

MIT

Autores

• @piazin