diff --git a/docs/hello.md b/docs/hello.md index ebeb7b39..c45938c3 100644 --- a/docs/hello.md +++ b/docs/hello.md @@ -12,7 +12,7 @@ We appreciate your support in this endeavor. Let's code efficiently together. ## Navigating the Documentation -This documentation is organized into distinct sections, each focusing on a specific aspect of ExpressoTS. Utilize the sidebar on the left to navigate through the content: +This documentation is organized into distinct sections, each focusing on a specific aspect of ExpressoTS. Use the sidebar on the left to navigate through the content: - **Overview**: Provides general information about ExpressoTS, including project resources, concepts, objectives, and initial setup instructions. - **Code By Example**: Offers practical examples to demonstrate the application of ExpressoTS resources. diff --git a/docs/overview/middleware.md b/docs/overview/middleware.md index 96f2e86e..f7ffd7b6 100644 --- a/docs/overview/middleware.md +++ b/docs/overview/middleware.md @@ -4,7 +4,7 @@ sidebar_position: 5 # Middleware -Middleware functions are pivotal in the request-response cycle of an ExpressoTS application, providing the capability to execute code, modify request and response objects, end the request-response cycle, or call the next middleware in the stack. It's essential to call next() to avoid request timeouts unless your middleware concludes the cycle. +Middleware functions are pivotal in the request-response cycle of an ExpressoTS application, providing the capability to execute code, modify request and response objects, end the request-response cycle, or call the next middleware in the stack. It's essential to call `next()` to avoid request timeouts unless your middleware concludes the cycle. ExpressoTS seamlessly integrates with Express middleware, enabling the use of its extensive ecosystem to enhance your application. @@ -73,7 +73,7 @@ protected configureServices(): void { ## Using `addMiddleware` method -For any other middleware, or a custom middleware, you can add it using the `this.middleware.addMiddleware()` method. Using the `addMiddleware` method, you can add any middleware from NPM Registry, custom Expressjs middleware or a custom ExpressoTS middleware. +For any other middleware, or a custom middleware, you can add it using the `this.middleware.addMiddleware()` method. Using the `addMiddleware` method, you can add any middleware from NPM Registry, custom Expressjs middleware or a custom middleware. NPM Registry middleware: @@ -113,7 +113,7 @@ this.middleware.addMiddleware(new CustomMiddleware()); ## Route Middleware -Middlewares can be added per route in the `App` class through the `this.middleware.addMiddleware()` method. You can add any middleware from NPM Registry, custom Expressjs middleware or a custom ExpressoTS middleware. +Middlewares can be added per route in the `App` class through the `this.middleware.addMiddleware()` method. You can add any middleware from NPM Registry, custom Expressjs middleware or a custom middleware. ```typescript this.middleware.addMiddleware({ path: "/api", middlewares: [] }); diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cli/generate.md b/i18n/pt/docusaurus-plugin-content-docs/current/cli/generate.md index f5f81035..99090aee 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/cli/generate.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cli/generate.md @@ -43,40 +43,27 @@ Nós fornecemos duas estruturas diferentes para estruturar os recursos: ## Tipos de recursos -Recursos atualmente disponíveis para serem gerados: - -| Forma longa | curta | -| ----------- | ----- | -| usecase | u | -| controller | c | -| dto | d | -| provider | p | -| service | s | -| entity | e | -| middleware | m | - -## Exemplo de uso - -| Comando | Resultado esperado | -| -------------------------- | -------------------------------------------------------------------------------------- | -| expressots g u user/find | Caso de uso para ser criado na pasta `useCases` com esta estrutura de pasta: user/find | -| expressots g c user/find | Controlador para ser criado na pasta `useCases` dentro de user/find | -| expressots g d user/find | DTO a ser criado na pasta `useCases` dentro de user/find | -| expressots g p email/email | Provedor a ser criado na pasta `providers` dentro de user/find | -| expressots g s user/find | Serviço cria caso de uso, controladora e dto e os adiciona na pasta user/find | -| expressots g e user | Entidade a ser criada na pasta `entities` com esta estrutura de pasta: user | -| expressots g m auth | Middleware a ser criado na pasta `middlewares` com esta estrutura de pasta: auth | +Recursos disponíveis atualmente: + +| Forma longa | Abreviação | Comando | Resultado esperado | +| -----------| --- | --------------- | -------------------------------------------------------------------------------------- | +| useCase | u | expressots g u user/find | Caso de uso para ser criado na pasta `useCases` com esta estrutura de pasta: user/find | +| controller | c | expressots g c user/find | Controlador para ser criado na pasta `useCases` dentro de user/find | +| dto | d | expressots g d user/find | DTO a ser criado na pasta `useCases` dentro de user/find | +| provider | p | expressots g p email/email | Provedor a ser criado na pasta `providers` dentro de user/find | +| service | s | expressots g s user/find | Serviço cria caso de uso, controladora e dto e os adiciona na pasta user/find | +| entity | e | expressots g e user | Entidade a ser criada na pasta `entities` com esta estrutura de pasta: user | +| middleware | mi | expressots g m auth | Middleware a ser criado na pasta `middlewares` com esta estrutura de pasta: auth | +| module | mo | expressots g mo user | Módulo a ser criado na pasta onde `controllers` e `usecases` estão localizados | Todos os recursos podem ser criados usando a estrutura `pasta/subpasta/recurso.` -Para serviços, você também pode aproveitar para criar o caso de uso, o controlador e o DTO de uma só vez usando a estrutura `entidade_ação` ou `entidade-ação`. Exemplo: `expressots g s user-create.` +## Gerando recursos com hífen nos nomes -:::caution -O que determina onde os recursos serão criados é o arquivo de configuração `expressots.config.ts`, localizado na pasta raiz do projeto. -::: +Para serviços, você pode aproveitar para criar o caso de uso, controlador e DTO de uma vez usando a estrutura `entidade_acao ` ou `entidade-acao `. Exemplo: `expressots g s user-create`. :::info -Todos os casos de uso, controladores e DTOs estão sendo criados dentro da pasta `useCases`. Isso não está definido em pedra e pode mudar em breve. +O arquivo de configuração `expressots.config.ts`, localizado na pasta raiz do projeto, determina onde todos os recursos serão criados. ::: ## ExpressoTS arquivo de configuração @@ -91,7 +78,16 @@ import { ExpressoConfig, Pattern } from "@expressots/core"; const config: ExpressoConfig = { sourceRoot: "src", scaffoldPattern: Pattern.KEBAB_CASE, - opinionated: false, + opinionated: true, + scaffoldSchematics: { + entity: "entity", + provider: "provider", + module: "module", + controller: "controller", + dto: "dto", + middleware: "middleware", + usecase: "useCases", + }, }; export default config; @@ -100,10 +96,11 @@ export default config; - **sourceRoot**: a pasta raiz que será usada pelo CLI para criar os recursos. Padrão: `src` - **scaffoldPattern**: o padrão que será usado para criar os recursos. Padrão: `Pattern.KEBAB_CASE`. Exemplo: `user-create` - **opinionated**: se for verdadeiro, o CLI criará os recursos usando a estrutura de pasta com opinião. +- **scaffoldSchematics**: os nomes de convenção de pastas para cada recurso. Padrão: `useCases`, `entities`, `providers`, `middlewares`, `controllers`, `dtos` ## Recomendações -Tente utilizar o maior número possível de formas de criação de recursos disponíveis. Isso irá ajudá-lo a entender como a CLI funciona e como utilizá-la em seu benefício. Além disso, isso nos ajudará a melhorar a CLI e torná-la mais robusta. +Tente usar o máximo de formas diferentes de criar recursos possível. Isso ajudará você a entender como o CLI funciona e como usá-lo a seu favor. Também nos ajuda a melhorar o CLI para torná-lo mais robusto. --- diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/cli/overview.md b/i18n/pt/docusaurus-plugin-content-docs/current/cli/overview.md index c77f3432..156c7229 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/cli/overview.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/cli/overview.md @@ -40,6 +40,16 @@ Informações dos provedores sobre seu Sistema Operacional, Projeto e versão CL expressots info ``` +### Lista de recursos + +Lista todos os recursos disponíveis para scaffolding: + +```bash +expressots resources or r +``` + +![Resources](../overview/img/scaffold-resources.png) + ## Criando um projeto ExpressoTS Há duas opções para criar um novo projeto, interativamente ou silenciosamente (passando as opções como argumentos). diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/app-container.md b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/app-container.md new file mode 100644 index 00000000..228275df --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/app-container.md @@ -0,0 +1,67 @@ +--- +sidebar_position: 1 +--- +# Contêiner da Aplicação + +O contêiner da aplicação é um contêiner de injeção de dependências. Veja Contêiner da Aplicação para mais informações. + +```typescript +const appContainer = new AppContainer(); + +export const container: Container = appContainer.create([ + // Adicione seus módulos aqui + AppModule, +]); +``` + +## Criando AppContainer + +A classe `AppContainer` aceita um parâmetro opcional: + +- `defaultScope` é o escopo de vinculação padrão. Use `BindingScopeEnum` para definir o escopo padrão (Request, Singleton, Transient). +- `skipBaseClassChecks` é um valor booleano que indica se o contêiner deve pular as verificações de classe base. Isso é útil quando você está usando classes abstratas como identificadores de vinculação ou está estendendo classes de bibliotecas de terceiros. Defina este valor como `true` para pular as verificações de classe base. +- `autoBindInjectable` é um valor booleano que indica se o contêiner deve vincular automaticamente classes injetáveis. Defina este valor como `true` para vincular automaticamente classes injetáveis. + +:::info +O escopo padrão é BindingScopeEnum.Request e skipBaseClassChecks é false. +::: + +```typescript +const appContainer = new AppContainer({ + defaultScope: BindingScopeEnum.Request, + skipBaseClassChecks: true, + autoBindInjectable: false, +}); +``` +O `AppContainer` retorna uma instância de `AppContainer` que te dá acesso aos seguintes métodos: + +- `create()` cria o contêiner da aplicação. +- Container é a instância do contêiner de injeção de dependências. +- `getBindingDictionary()` retorna o mapa do dicionário de vinculação de classes injetadas no sistema de injeção de dependências. +- `getContainerOptions()` retorna as opções do contêiner. + +### Método Create + +O método `create` recebe um parâmetro obrigatório (array de módulos); + +```typescript +export const container: Container = appContainer.create([ + // Adicione seus módulos aqui + AppModule, + UserModule, + ProductModule, +]); +``` + +--- + +## Apoie o projeto + +ExpressoTS é um projeto de código aberto licenciado sob o MIT. É um projeto independente com desenvolvimento contínuo possibilitado graças ao seu suporte. Se você deseja ajudar, por favor considere: + +- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** +- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto +- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** +- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** +- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** +- Compartilhe o projeto com seus amigos e colegas \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/bootstrao.md b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/bootstrao.md new file mode 100644 index 00000000..c88b4dda --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/bootstrao.md @@ -0,0 +1,96 @@ +--- +sidebar_position: 0 +--- + +# Método Bootstrap + +O método `bootstrap` é o ponto de entrada da sua aplicação. É responsável por carregar a configuração da aplicação, registrar middlewares e iniciar a aplicação. + +- O método `AppFactory.create()` é responsável por criar a instância da aplicação. Ele recebe dois parâmetros: + - `container` é o contêiner de injeção de dependências. Veja Contêiner da Aplicação para mais informações. + - `middlewares` ou `App` +- Retorna um instância de `IApplicationExpress` que te dá acesso a dois métodos: + - `app.listen()` inicia a aplicação. + - `app.setEngine()` define o motor de renderização de visualização da aplicação.` + +:::info +**`middlewares`** é um array de middlewares que serão registrados na aplicação. (Template não opinativo) + +**`App`** é a classe da aplicação responsável por toda a configuração da aplicação. (Template opinativo) +::: + +## Bootstrap com array de middlewares + +Use este método se você está usando o template não opinativo. Você tem a liberdade de criar sua própria classe de aplicação e registrar seus middlewares da sua própria maneira. + +```typescript +async function bootstrap() { + const app = await AppFactory.create(container, [cors(), helmet()]); + await app.listen(3000, ServerEnvironment.Development); +} + +bootstrap(); +``` +:::tip +**`AppFactory.create(container, [])`** retorna uma instância de `ApplicationExpress` que te dá acesso direto à instância do `ExpressApp`. +::: + +## Bootstrap com a classe de aplicação + +Use este método se você está usando o template opinativo. Sua classe de aplicação será responsável por toda a configuração da aplicação. + +```typescript +async function bootstrap() { + const app = await AppFactory.create(container, App); + await app.listen(3000, ServerEnvironment.Development); +} + +bootstrap(); +``` +:::tip +**`AppFactory.create(container, App)`** retorna uma instância de `IApplicationExpress` que te dá acesso aos métodos `listen()` e `setEngine()`. +::: + +## Método Listen + +O método `listen` é responsável por iniciar a aplicação. Ele recebe dois parâmetros obrigatórios e um parâmetro opcional: + +- `port` é o número da porta onde a aplicação estará ouvindo. (Obrigatório) +- `environment` é o ambiente onde a aplicação estará rodando. Pode ser development ou production. Use o enum chamado `ServerEnvironment`. (Obrigatório) +- `consoleMessage` é o objeto de mensagem que será exibido no console quando a aplicação iniciar. (Opcional) + +```typescript +await app.listen(3000, ServerEnvironment.Development, { + appName: "Expressots", + appVersion: "1.0.0", +}); +``` + +:::tip +O enum ServerEnvironment define automaticamente a variável de ambiente NODE_ENV. Pode ser `development` ou `production`. +::: + +## Método Set Engine + +O método `setEngine` é responsável por definir o motor de renderização de visualização da aplicação. Por enquanto, o ExpressoTS suporta apenas Handlebars. + +```typescript +app.setEngine({ + extName: "hbs", + viewPath: path.join(__dirname, "..", "views"), + engine: engine({ defaultLayout: "layout", extname: "hbs" }), +}); +``` + +--- + +## Apoie o projeto + +ExpressoTS é um projeto de código aberto licenciado sob o MIT. É um projeto independente com desenvolvimento contínuo possibilitado graças ao seu suporte. Se você deseja ajudar, por favor considere: + +- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** +- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto +- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** +- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** +- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** +- Compartilhe o projeto com seus amigos e colegas \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/controller.md b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/controller.md new file mode 100644 index 00000000..782c7a85 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/controller.md @@ -0,0 +1,111 @@ +--- +sidebar_position: 3 +--- + +# Controladores + +Os controladores são responsáveis por manipular solicitações recebidas e retornar respostas ao cliente. + +- Para informações sobre `BaseController`, veja [BaseController](../overview/controller.md#basecontroller-class). +- Para informações sobre decoradores HTTP e de parâmetros, veja [Decoradores HTTP e de Parâmetros](../overview/decorators.md). +- Os controladores utilizam DTOs para validar o corpo da solicitação, parâmetros de consulta e parâmetros de rota. Veja [DTOs](../overview/controller#dto-pattern) para mais informações. + +```typescript +@controller("/") +export class UserGetController extends BaseController { + constructor() { + super(); + } + + @Get("/") + execute() { + return "Getting a user..."; + } +} +``` + +Para criar um controlador, você precisa criar uma classe e decorá-la com o decorador `@controller`. O decorador `@controller` recebe dois parâmetros: + +- `path` é o caminho do controlador. (Obrigatório) +- `middlewares` é um array de middlewares. (Opcional) + +```typescript +@controller("/", express.json(), express.urlencoded({ extended: true })) +``` +:::info +Definir middlewares no controlador será aplicado a todas as rotas do controlador. +::: + +## Exemplo de um Controlador com Múltiplas Rotas + +```typescript +@controller("/user") +export class UserController extends BaseController { + constructor() { + super(); + } + + @Get("/") + get() { + return "Getting a user..."; + } + + @Post("/create") + create() { + return "Creating a user..."; + } +} +``` + +## Exemplo de Rota com Múltiplos Middlewares + +```typescript +@Get("app", express.json(), express.urlencoded({ extended: true })) +``` + +:::info +Definir middlewares na rota será aplicado apenas à rota específica. +::: + +:::info +O caminho da rota do controlador será concatenado com o caminho da rota individual. + +```typescript +@controller("/user") + @Post("/create") +``` + +A rota final é /user/create. +::: + +## Injetando Dependências no Construtor do Controlador + +Você pode injetar dependências no construtor do controlador da seguinte forma: + +```typescript +@controller("/") +class AppController extends BaseController { + constructor(private yourProvider: YourProvider) { + super(); + } + + @Get("/") + get() { + this.yourProvider.doSomething(); + return "Hello ExpressoTS!"; + } +} +``` + +--- + +## Apoie o projeto + +ExpressoTS é um projeto de código aberto licenciado sob o MIT. É um projeto independente com desenvolvimento contínuo possibilitado graças ao seu suporte. Se você deseja ajudar, por favor considere: + +- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** +- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto +- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** +- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** +- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** +- Compartilhe o projeto com seus amigos e colegas \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/entities.md b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/entities.md new file mode 100644 index 00000000..540c6d9c --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/entities.md @@ -0,0 +1,45 @@ +--- +sidebar_position: 5 +--- + +# Entidades + + +Entidades são o núcleo da sua aplicação. Elas são a representação dos seus objetos de negócio. Para mais informações sobre entidades, veja [Entidades](../overview/entities.md). + +```typescript +@provide(User) +export class User { + id: string; + name: string; + email: string; + + constructor() { + this.id = randomUUID(); + } +} +``` + +:::caution +Não passe tipos primitivos como parâmetros para o construtor das suas entidades. O Contêiner de Injeção de Dependências não será capaz de resolvê-los. + +```typescript +constructor(name: string) { + this.name = name; +} +``` + +::: + +--- + +## Apoie o projeto + +ExpressoTS é um projeto de código aberto licenciado sob o MIT. É um projeto independente com desenvolvimento contínuo possibilitado graças ao seu suporte. Se você deseja ajudar, por favor considere: + +- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** +- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto +- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** +- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** +- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** +- Compartilhe o projeto com seus amigos e colegas \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/modules.md b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/modules.md new file mode 100644 index 00000000..2751dc54 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/modules.md @@ -0,0 +1,47 @@ +--- +sidebar_position: 2 +--- + +# Módulos + +Os módulos são responsáveis por registrar controladores. Veja Módulos para mais informações. + +## Criando um Módulo + +O decorador `CreateModule` recebe dois parâmetros: + +- `controllers` é um array de controladores. (Obrigatório) +- `scope` é o escopo de vinculação. Use `BindingScopeEnum` para definir o escopo (Request, Singleton, Transient). (Opcional) + +:::info +O escopo padrão é `BindingScopeEnum.Request` herdado do `AppContainer`. +::: + +```typescript +export const UserModule = CreateModule([], BindingScopeEnum.Request); +``` + +Exemplo de um módulo com controladores: + +```typescript +export const UserModule = CreateModule([ + UserCreateController, + UserDeleteController, + UserUpdateController, + UserFindController, + UserFindallController, +]); +``` + +--- + +## Apoie o projeto + +ExpressoTS é um projeto de código aberto licenciado sob o MIT. É um projeto independente com desenvolvimento contínuo possibilitado graças ao seu suporte. Se você deseja ajudar, por favor considere: + +- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** +- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto +- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** +- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** +- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** +- Compartilhe o projeto com seus amigos e colegas \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/providers/prisma.md b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/usecase.md similarity index 53% rename from i18n/pt/docusaurus-plugin-content-docs/current/providers/prisma.md rename to i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/usecase.md index 0b64107c..2d1197ad 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/providers/prisma.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/usecase.md @@ -2,9 +2,32 @@ sidebar_position: 4 --- -# Prisma provedor +# Casos de Uso -Em breve... +Casos de uso são a implementação da lógica de negócios da sua aplicação. Para mais informações sobre casos de uso, veja [Casos de Uso](../overview/usecase.md). + +```typescript +@provide(YourUseCase) +export class YourUseUseCase { + execute() { + return "Hello ExpressoTS!"; + } +} +``` + +## Injetando Dependências no Construtor de Casos de Uso + +```typescript +@provide(YourUseCase) +export class YourUseUseCase { + constructor(private yourProvider: YourProvider) {} + + execute() { + this.yourProvider.doSomething(); + return "Hello ExpressoTS!"; + } +} +``` --- @@ -17,4 +40,4 @@ ExpressoTS é um projeto de código aberto licenciado sob o MIT. É um projeto i - Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** - Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** - Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** -- Compartilhe o projeto com seus amigos e colegas +- Compartilhe o projeto com seus amigos e colegas \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/utils.md b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/utils.md new file mode 100644 index 00000000..df0a2908 --- /dev/null +++ b/i18n/pt/docusaurus-plugin-content-docs/current/codebyexample/utils.md @@ -0,0 +1,128 @@ +--- +sidebar_position: 6 +--- + +# Utilitários ExpressoTS + +## Códigos de Status + +É um enum que contém todos os códigos de status HTTP. + +```typescript +StatusCode.OK; +``` + +## Relatando Erros + +Para mais informações sobre Tratamento de Erros, veja [Tratamento de Erros](../overview/error-handling.md). + +Aqui estão os parâmetros do método `error`: + +- error: Uma instância de Error ou uma string que descreve o erro. +- statusCode: O código de status HTTP associado ao erro (padrão é 500). +- service: O nome do serviço associado ao erro. +- @throws: Um objeto do tipo personalizado AppError, que inclui detalhes sobre o erro. + +```typescript +@provide(YourUseCase) +export class YourUseUseCase { + constructor(private report: Report) {} + + execute() { + this.report.error("Something went wrong!"); + return "Hello ExpressoTS!"; + } +} +``` + +## Registro + +Logger é uma classe que fornece um conjunto de métodos para registrar mensagens usando módulos nativos do node para melhor desempenho. + +Logger recebe dois parâmetros: + +- message: A mensagem a ser registrada. +- module: O nome do serviço associado ao log. + +```typescript +export class YourUseUseCase { + constructor(private log: Logger) {} + + execute() { + this.log.info("Testing log message", "YourUseUseCase"); + return "Hello ExpressoTS!"; + } +} +``` + +Existem 4 métodos disponíveis: + +- **info**: Registra uma mensagem informativa. +- **warn**: Registra uma mensagem de aviso. +- **error**: Registra uma mensagem de erro. +- **msg**: Registra uma mensagem de log. + +## Definindo o Prefixo Global de Rotas + +Você pode definir um prefixo global para todas as rotas na sua aplicação. Isso é útil quando você quer versionar suas APIs. + +### Template Não Opinativo + +Você pode definir o prefixo global no método `bootstrap` da sua aplicação. + +```typescript +async function bootstrap() { + const app = await AppFactory.create(container, []); + + app.setGlobalRoutePrefix("/api"); + + await app.listen(3000, ServerEnvironment.Development); +} +``` + +### Template Opinativo + +Você pode definir o prefixo global no método `configureServices` da sua aplicação. + + +```typescript +@provide(App) +class App extends AppExpress { + private middleware: IMiddleware; + private provider: IProvider; + + constructor() { + super(); + this.middleware = container.get(Middleware); + this.provider = container.get(Provider); + } + + protected configureServices(): void { + this.setGlobalRoutePrefix("/v1"); + + this.middleware.addBodyParser(); + this.middleware.setErrorHandler(); + } + + protected postServerInitialization(): void { + if (this.isDevelopment()) { + this.provider.envValidator.checkAll(); + } + } + + protected serverShutdown(): void {} +} +``` + +--- + +## Apoie o projeto + +ExpressoTS é um projeto de código aberto licenciado sob o MIT. É um projeto independente com desenvolvimento contínuo possibilitado graças ao seu suporte. Se você deseja ajudar, por favor considere: + +- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** +- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto +- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** +- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** +- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** +- Compartilhe o projeto com seus amigos e colegas \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/governance.md b/i18n/pt/docusaurus-plugin-content-docs/current/governance.md index c40d202b..6e1d18b7 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/governance.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/governance.md @@ -8,23 +8,7 @@ ExpressoTS é construído pela sua comunidade. Nós acolhemos e apreciamos contr ## Time Principal -Atualmente, temos uma pequena equipe principal de colaboradores constantes. Estamos procurando expandir esta equipe para incluir mais pessoas da comunidade com uma ampla gama de habilidades e interesses. - -Atualmente, essa equipe está supervisionando os seguintes itens: - -- Documentação -- Site -- Gerenciamento da Comunidade -- Presença nas Redes Sociais -- Suporte Técnico -- ExpressoTS Core, CLI e Providers -- Pacotes Extra do ExpressoTS -- Recursos do ExpressoTS e Inovacões -- Problemas e Pull Requests do Expresso -- DevOps -- CI/CD -- Testes -- Roadmap +Atualmente, temos uma pequena equipe principal de contribuidores constantes. Estamos procurando expandir esta equipe para incluir mais pessoas da comunidade com uma ampla gama de habilidades e interesses. ## Tomada de Decisão @@ -34,8 +18,6 @@ Cada decisão importante no ExpressoTS começa com uma proposta. As propostas po Estamos migrando o quadro do projeto e o roteiro de Jira para GitHub Projects. Isso nos permitirá ter um processo mais aberto e transparente, bem como permitir que a comunidade participe de maneira mais ativa no projeto. ::: -**[Corrija um bug ou envie uma proposta](https://github.com/expressots/expressots/issues/new/choose)** - ## Time Conheça a equipe de colaboradores regulares: **[Team](https://expresso-ts.com/team)** diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/hello.md b/i18n/pt/docusaurus-plugin-content-docs/current/hello.md index 86351caa..5adcfdd8 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/hello.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/hello.md @@ -2,47 +2,54 @@ sidebar_position: 0 --- -# Olá, Dev +# Bem-vindo ao ExpressoTS! -Obrigado por embarcar nesta jornada conosco para criar uma experiência de desenvolvedor ambiciosa e emocionante que está melhorando continuamente. 🎉🎉🎉 +ExpressoTS é projetado para simplificar o processo de desenvolvimento de software, permitindo que os desenvolvedores se concentrem na lógica de negócios principal, abstraindo complexidades técnicas. Nosso objetivo é aumentar sua produtividade por meio de uma estrutura que não apenas acelera o desenvolvimento, mas também oferece documentação abrangente e uma experiência de desenvolvedor superior, minimizando a necessidade de código genérico e repetitivo. -O ExpressoTS é tão simples, mas eficiente para fazer o trabalho. Queremos continuar fazendo isso, abstrair todas as complexidades que o mundo do desenvolvimento de software traz e facilitar a construção do seu próximo projeto. +Nosso compromisso é duplo: simplificar seu trabalho de desenvolvimento e aumentar sua produtividade. À medida que embarcamos nesta jornada, convidamos você a se juntar ao nosso projeto impulsionado pela comunidade. Suas percepções, feedback e contribuições são inestimáveis na criação de uma experiência de desenvolvedor ótima para todos. -Se você pensar sobre isso, cada recurso de linguagem de programação, estrutura construída, é para acelerar seu processo de desenvolvimento, no entanto, estamos continuamente falhando em fornecer boa documentação, boa experiência do desenvolvedor, além de reduzir a quantidade de código clichê que você precisa escrever. Tudo deve simplesmente funcionar! +Agradecemos seu apoio neste empreendimento. Vamos codificar de forma eficiente juntos. 🐎 -Este é o nosso compromisso, facilitar a sua vida e torná-lo mais produtivo. +--- -Estamos muito abertos a comentários, ideias e contribuições. Somos um projeto voltado para a comunidade e queremos ouvir você. +## Navegando na documentação -Obrigado novamente por fazer parte desta jornada conosco, Feliz Codificação! 🚀 +Esta documentação está organizada em seções distintas, cada uma focando em um aspecto específico do ExpressoTS. Utilize a barra lateral à esquerda para navegar pelo conteúdo: ---- +- **Visão geral**: Fornece informações gerais sobre o ExpressoTS, incluindo recursos do projeto, conceitos, objetivos e instruções de configuração inicial. +- **Code By Example**: Oferece exemplos práticos para demonstrar a aplicação dos recursos do ExpressoTS. +- **CLI**: detalha a interface da linha de comando, incluindo instruções de uso. +- **Providers**: Descreve os providers disponíveis e sua utilização. +- **Tutorial**: um guia passo a passo abrangente para realizar tarefas específicas no ExpressoTS. +- **Roadmap**: descreve a direção futura e os recursos planejados do ExpressoTS. +- **Governança**: explica o modelo de governança do ExpressoTS e descreve como contribuir para o projeto. -## Como ler a documentação - -- **[links](./overview/intro.md)**: Todos os textos em negrito são links para outras páginas da documentação ou links externos. -- `código`: Ajuda a enfatizar trechos de código e comandos ou termos técnicos importantes. -- Alertas: São usados para destacar informações importantes. - :::note Usado para expressar informações gerais - ::: - :::tip Esta é uma dica - ::: - :::info Informações extras que não são vitais - ::: - :::caution Usado para indicar spoilers - ::: - :::warning Usado para indicar quando algo pode dar errado - ::: +## Compreendendo os tipos de alerta ---- +Ao longo desta documentação, vários formatos são utilizados para chamar a atenção para diferentes tipos de informação: + +- **Links**: O texto em negrito indica hiperlinks para outras páginas de documentação ou recursos externos. +- **Código**: trechos de código, comandos e termos técnicos importantes são destacados. +- **Alertas**: Alertas específicos são empregados para enfatizar informações cruciais, utilizando os seguintes marcadores: + +:::note Transmite informações gerais ou lembretes. +::: +:::tip Fornece sugestões úteis ou práticas recomendadas. +::: +:::info Oferece informações adicionais e não críticas. +::: +:::caution Alertas para potenciais spoilers ou conteúdo sensível. +::: +:::warning Sinaliza possíveis problemas ou riscos que podem impactar o desenvolvimento. +::: ## Apoie o projeto ExpressoTS é um projeto de código aberto licenciado sob o MIT. É um projeto independente com desenvolvimento contínuo possibilitado graças ao seu suporte. Se você deseja ajudar, por favor considere: -- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** -- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto -- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** -- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** -- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** -- Compartilhe o projeto com seus amigos e colegas \ No newline at end of file +- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** +- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto +- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** +- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** +- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** +- Compartilhe o projeto com seus amigos e colegas diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/overview/app-container.md b/i18n/pt/docusaurus-plugin-content-docs/current/overview/app-container.md index 7f4e5a17..43bcc1d8 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/overview/app-container.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/overview/app-container.md @@ -4,45 +4,50 @@ sidebar_position: 3 # App Container -O ExpressoTS usa **[InversifyJS](https://inversify.io/)** como seu ioC (Inversão de Controle) container, pois é uma ferramenta poderosa para gerenciar injeção de dependência. O Inversify é um container com suporte a tipos que pode ser utilizado para gerenciar a instância e resolução de objetos, bem como o gerenciamento do ciclo de vida deles. +O ExpressoTS utiliza o **[InversifyJS](https://inversify.io/)** para suas capacidades de contêiner de Inversão de Controle (IoC), fornecendo um sistema robusto para injeção de dependências. Este contêiner consciente de tipos facilita a instanciação de objetos, resolução e gestão de ciclo de vida, possibilitando a criação de dependências complexas com código mínimo. -O contêiner fornece um local central para gerenciar dependências e criar objetos que dependem de outros objetos. Quando uma classe é registrada no contêiner, suas dependências são automaticamente resolvidas e injetadas em seu construtor quando ela é instanciada. Isso permite a criação de gráficos de objetos complexos com um mínimo de código boilerplate. +O encapsulador AppContainer simplifica a integração, permitindo um registro direto de controladores, casos de uso e provedores dentro da aplicação. -Aproveitando o InversifyJS, criamos um wrapper para reduzir a complexidade sobre como os controladores, casos de uso e provedores são injetados no contêiner de aplicativos. O wrapper é chamado de `AppContainer` e é responsável por registrar todos os módulos da aplicação no contêiner. +## Configurando o contêiner -## Criando o container +O contêiner da aplicação pode ser personalizado com escopos padrões para a vinculação de dependências e opções para pular verificações de classes base, aumentando a flexibilidade na gestão de dependências. -Ao criar o contêiner da aplicação, é possível definir o escopo padrão do contêiner e também configurar para ignorar a verificação da classe base. O escopo padrão é `RequestScope`, o que significa que todas as dependências serão criadas uma vez por solicitação. Esse é o escopo comum para a maioria das aplicações web usadas em outros frameworks, como Spring Boot ou .NET Core. +- **defaultScope**: O escopo padrão, `RequestScope`, cria uma nova instância de uma dependência para cada solicitação, enquanto `SingletonScope` cria uma única instância compartilhada por todas as solicitações. O `TransientScope` cria uma nova instância cada vez que a dependência é solicitada. +- **skipBaseClassChecks**: Quando definido como `true`, o contêiner irá pular as verificações de classes base ao trabalhar com classes derivadas. +- **autoBindInjectable**: Quando definido como `true`, o contêiner irá injetar automaticamente classes que não estão explicitamente vinculadas. Aqui está a definição das opções de interface: ```typescript interface ContainerOptions { - /** - * O escopo padrão para as ligações no contêiner. - * Pode ser definido como Request (padrão), Singleton ou Transient. - */ - defaultScope?: interfaces.BindingScope; - - /** - * Permite ignorar as verificações da classe base ao trabalhar com classes derivadas. - */ - skipBaseClassChecks?: boolean; + /** + * O escopo padrão para as ligações no contêiner. + * Pode ser definido como Request (padrão), Singleton ou Transient. + */ + defaultScope?: interfaces.BindingScope; + + /** + * Permite ignorar as verificações da classe base ao trabalhar com classes derivadas. + */ + skipBaseClassChecks?: boolean; + + /** + * Permite a injeção automática de classes que não estão explicitamente vinculadas ao contêiner. + */ + autoBindInjectable: false; } ``` -Aqui está um exemplo de como criar um container: +Criando o container: ```typescript // Adicionando opções ao contêiner -const appContainer = new AppContainer({ +export const appContainer: AppContainer = new AppContainer({ defaultScope: BindingScopeEnum.Singleton, skipBaseClassChecks: true, + autoBindInjectable: false, }); -// Criando um contêiner sem opções -const appContainer = new AppContainer(); - // Criando um gerenciador de módulos de contêiner const container = appContainer.create([ // Adicione seus módulos aqui @@ -54,47 +59,38 @@ export { container }; ## Definindo o escopo do container -Como mencionado acima, se o `defaultScope` não for fornecido, o padrão é definido como RequestScope. No entanto, é possível alterar o escopo padrão passando o `defaultScope` como uma opção no construtor do contêiner. Isso permite flexibilidade na configuração do contêiner, de modo que ele possa ser personalizado para atender às necessidades específicas da aplicação. +Como mencionado acima, se o `defaultScope` não for fornecido, o padrão é definido como `RequestScope`. No entanto, é possível alterar o escopo padrão passando o `defaultScope` como uma opção no construtor do contêiner. O `BindingScopeEnum` contém os seguintes valores: - `BindingScopeEnum.Singleton` - A dependência será criada uma vez e será compartilhada entre todas as solicitações. - `BindingScopeEnum.Request` - A dependência será criada uma vez por solicitação. - `BindingScopeEnum.Transient` - A dependência será criada toda vez que for solicitada. -```typescript -const appContainer = new AppContainer(); +## Visualizando as vinculações do contêiner -const container = appContainer.create( - [ - // Registrar todos os módulos - ] -); -``` +O contêiner pode ser usado para visualizar todas as vinculações que foram registradas. Isso pode ser útil para fins de depuração ou para entender as dependências que foram registradas. -:::tip -Se você não passar o `defaultScope` o escopo padrão será definido como `RequestScope`. -::: +```typescript +appContainer.viewContainerBindings(); +``` +![Container Bindings View](./img/container-bindings.png) ## Registrando modulos -A classe `AppContainer` tem um método `create` que recebe um array de módulos e retorna o contêiner com todos os módulos registrados. O contêiner aqui criado é o mesmo contêiner usado pela classe `Application` para inicializar o servidor. - -Depois que o contêiner é criado, os desenvolvedores podem registrar **[modules](./module.md)** no contêiner: +O `appContainer` facilita o registro de módulos por meio de seu método `create([])`, que aceita um array de módulos. Esta abordagem simplificada reduz a complexidade da configuração e alinha-se com o objetivo do ExpressoTS de simplificar a arquitetura da aplicação: ```typescript // Cria novo container -const appContainer = new AppContainer(); +const appContainer: AppContainer = new AppContainer(); -const container = appContainer.create([ +const container: Container = appContainer.create([ // Registrar todos os módulos UserModule, PaymentModule, - ProductModule + ProductModule, ]); - -export default container; ``` -A razão pela qual criamos a classe `AppContainer` é reduzir a complexidade de como o container é criado e fornecer uma maneira de registrar módulos sem muita configuração extra. +O uso do `appContainer` abstrai as complexidades do uso direto do InversifyJS, proporcionando um caminho direto para integrar e gerenciar módulos dentro das aplicações ExpressoTS. --- diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/overview/application.md b/i18n/pt/docusaurus-plugin-content-docs/current/overview/application.md index 33d36c3c..e3224d39 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/overview/application.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/overview/application.md @@ -4,176 +4,98 @@ sidebar_position: 2 # Aplicação -A Visão Geral da Aplicação oferece uma demonstração abrangente dos principais componentes de uma aplicação ExpressoTS. No coração de uma aplicação ExpressoTS está a classe Application. Ela serve como base para criar e configurar o servidor. Além disso, a classe Application utiliza o container de aplicação do Inversify para carregar todos os módulos, incluindo suas respectivas rotas [controladores]. Isso garante um processo eficiente para lidar com solicitações recebidas e entregar as respostas apropriadas. +No coração de uma aplicação ExpressoTS está a classe App. Ela serve como a fundação para criar e configurar o servidor. Adicionalmente, a classe App permite que middlewares e provedores sejam configurados no processo de inicialização do servidor. A classe App também oferece hooks (ganchos) de ciclo de vida que permitem aos desenvolvedores executar código antes, depois e durante o desligamento do servidor. Esta seção fornece uma visão geral da arquitetura da aplicação ExpressoTS, seus componentes e o fluxo de trabalho de uma aplicação ExpressoTS. ![Visão Geral da Aplicação](./img/app-overview.png) -ExpressoTS é um framework de aplicação web que fornece um invólucro em torno de servidores HTTP populares, incluindo **[Express](https://expressjs.com)** e **[Fastify](https://www.fastify.io/)**. +## Arquitetura da aplicação -:::info -Atualmente, apenas o Express foi completamente testado pela equipe ExpressoTS. O adaptador Fastify está em desenvolvimento. -::: - -A arquitetura de uma aplicação ExpressoTS é construída em torno do container IoC **[Inversify](https://inversify.io/)**, que é usado para identificar e injetar dependências nos construtores das classes. Essa abordagem permite que o container IoC carregue todos os módulos necessários, incluindo suas respectivas rotas (controladores). Ao utilizar casos de uso e provedores conforme necessário, os roteadores podem lidar com solicitações recebidas. +A arquitetura de uma aplicação ExpressoTS é construída em torno do **[Inversify](https://inversify.io/)**, um contêiner IoC (Inversão de Controle), que é usado para identificar e injetar dependências nos construtores das classes. Essa abordagem permite que o contêiner IoC carregue todos os módulos necessários, incluindo suas respectivas rotas (controllers). Utilizando casos de uso e provedores (providers) conforme necessário, as rotas podem lidar com as solicitações recebidas. -Ao aproveitar o poder do Inversify, o ExpressoTS fornece um sistema personalizado de Injeção de Dependência que é escalável e modular. Isso cria uma arquitetura que ajuda a desacoplar componentes e melhorar a manutenibilidade, permitindo que os desenvolvedores se concentrem em escrever código limpo e sustentável. +## Componentes principais e suas funções -## Descrição dos Componentes da Aplicação +A arquitetura de uma aplicação ExpressoTS é baseada em vários componentes fundamentais: -| Componente | Descrição | -| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| DTO IN / OUT | Objeto de transferência de dados que define o formato da carga útil de entrada e saída da aplicação. | -| Controlador | Componente responsável pelo processamento de solicitações e respostas com base na URL e no método HTTP. Também valida a conformidade dos dados recebidos. | -| Caso de Uso | Componente responsável por implementar a lógica necessária para lidar com solicitações recebidas do controlador. Quando o controlador recebe uma solicitação HTTP e valida os dados recebidos, ele aciona o caso de uso relevante, passando os dados validados para processamento. O caso de uso executa as operações necessárias com base na solicitação e retorna a resposta apropriada ao controlador, que, em seguida, envia a resposta de volta ao cliente. | -| Provedor | Componente responsável por fornecer funcionalidade externa à aplicação. | -| Repositório | Componente responsável por fornecer camada de comunicação com o banco de dados. Facilitando conexão e operações CRUD. | +- **DTO IN/OUT**: Define a estrutura para dados de entrada e saída, garantindo segurança de tipo e consistência em toda a aplicação. +- **Controller**: Gerencia o processamento de solicitações, roteamento baseado na URL e no método HTTP, e validação de dados. +- **Use Case**: Executa lógica específica para o tratamento de solicitações, atuando sobre dados validados pelos controladores para realizar operações e retornar respostas. +- **Provider**: Fornece funcionalidades externas como acesso a banco de dados, serviços de email ou mecanismos de autenticação. +- **Repository**: Facilita a comunicação direta com o banco de dados para operações CRUD, abstraindo a camada de dados. :::info -Provedores e Repositórios são componentes opcionais. Você pode usá-los se precisar fornecer funcionalidade extra à sua aplicação, como integração de banco de dados, sistema de logs, autenticação, email, etc. +Provedores e Repositórios são componentes opcionais. Você pode usá-los se precisar fornecer funcionalidades extras para sua aplicação, como integração com banco de dados, sistema de log, autenticação, email, etc. ::: -## Fluxo de Trabalho +## Fluxo de trabalho da aplicação -O fluxo de trabalho de uma aplicação ExpressoTS é direto, como mostrado no diagrama acima. - -1. Após inicializar a aplicação com todos os seus componentes, incluindo o container, módulos e controladores, o servidor começa a escutar por solicitações recebidas. -2. Quando uma solicitação é recebida, o servidor procura pela rota correspondente e executa o controlador associado, que normalmente expõe endpoints. -3. O controlador então chama o caso de uso relevante, que por sua vez chama o provedor apropriado quando necessário. Provedores são componentes externos que oferecem funcionalidade adicional à aplicação. +O fluxo de trabalho começa com a inicialização do servidor, incluindo a configuração do contêiner, módulos e controladores. Ao receber solicitações, o servidor invoca o controlador relevante, que então aciona o caso de uso correspondente. Se necessário, os casos de uso interagem com provedores para acessar recursos ou serviços externos. :::warning Inicializando a Aplicação sem um controlador -O ExpressoTS impedirá você de inicializar a Aplicação sem um controlador, já que não há ouvintes para lidar com solicitações recebidas. Você verá a seguinte mensagem no console: -**_Nenhum controlador foi encontrado! Certifique-se de ter registrado pelo menos um Controlador._** +O ExpressoTS impedirá que você inicialize a Aplicação sem um controlador, já que não há ouvintes para lidar com as solicitações recebidas. Você verá a seguinte mensagem no console: +**_No controllers have been found! Please ensure that you have register at least one Controller._** ::: ## Classe AppExpress -A classe AppExpress oferece uma forma de criar e configurar o servidor, passando **[middlewares do Express.js](https://expressjs.com/en/guide/writing-middleware.html)** ou outros middlewares na criação do servidor. - -Para criar uma instância de aplicação ExpressoTS, usamos a classe `AppFactory`, que é responsável por criar a instância da aplicação e inicializar o container, módulos e controladores. A função `create()` retorna um IApplicationExpress que fornece um conjunto de métodos para configurar o servidor, incluindo o método `listen()`, que inicia o servidor e escuta por solicitações recebidas. - -### Definição da Classe AppExpress +A classe AppExpress oferece uma maneira de criar e configurar o servidor, passando **[middlewares do Express.js](https://expressjs.com/en/guide/writing-middleware.html)**, registrando provedores externos e configurando o ambiente do servidor. A classe AppExpress fornece três hooks de ciclo de vida que permitem aos desenvolvedores executar código antes, depois e durante o desligamento do servidor. A seguir, está a estrutura da classe AppExpress: ```typescript -class AppExpress { - /** - * Configure serviços que devem ser inicializados antes do início do servidor. - */ - protected configureServices(): void {} - - /** - * Configure serviços que devem ser executados após o início do servidor. - */ - protected postServerInitialization(): void {} - - /** - * Execute ações ou limpeza após o encerramento do servidor. - */ - protected serverShutdown(): void {} - - public async create( - container: Container, - middlewares: Array = [] - ): Promise {} - - public async listen( - port: number, - environment: ServerEnvironment, - consoleMessage?: IApplicationMessageToConsole - ): Promise {} -} -``` +export class App extends AppExpress { + private middleware: IMiddleware; + private provider: ProviderManager; + + constructor() { + super(); + this.middleware = container.get(Middleware); + this.provider = container.get(ProviderManager); + } -### Método Create + protected configureServices(): void { + this.provider.register(Env); -O método `create()` permite aos desenvolvedores passar o container, middlewares e adaptadores de servidor HTTP para o servidor. Para passar um middleware, você não precisa usar `app.use()`, basta passar o middleware e sua configuração como demonstrado abaixo: + this.middleware.addBodyParser(); + this.middleware.setErrorHandler(); + } -```typescript -async function Bootstrap() { - await AppFactory.create(container, [ - express.json(), - express.urlencoded({ extended: true }), - cors({ - origin: "*", - }), - ]); + protected postServerInitialization(): void { + if (this.isDevelopment()) { + this.provider.get(Env).checkAll(); + } + } + + protected serverShutdown(): void {} } ``` :::info -Adaptadores são usados para criar o servidor. Atualmente, o Express é o único adaptador disponível. O adaptador Fastify está em desenvolvimento. -Ao criar uma instância de aplicação, você pode passar o adaptador como o terceiro parâmetro. Se você não passar o adaptador, o Express é usado por padrão. +A classe `App` oferece um conjunto de middlewares e provedores prontos para uso que podem ser utilizados para configurar sua aplicação. Veja a lista completa na **[seção de Middlewares](./middleware.md)** ::: -### Método Listen +## Inicialização da aplicação -O método `listen()` inicia o servidor e fica à espera de solicitações recebidas. No método listen, os desenvolvedores podem definir o número da porta e o ambiente do servidor, que pode ser desenvolvimento, homologação ou produção. Os desenvolvedores também podem configurar o nome e a versão do aplicativo para serem exibidos no console quando o servidor for iniciado, conforme mostrado no exemplo a seguir: +O processo de inicialização da aplicação envolve a criação do servidor, passando o contêiner, a classe App e iniciando o servidor. A classe AppFactory fornece o método create e listen que permite aos desenvolvedores criar o servidor e ouvir solicitações de entrada. A seguir, está a função Bootstrap que cria o servidor: ```typescript -// App listen method -app.listen(3000, ServerEnvironment.Development, { - appName: "Your App Name", - appVersion: "v1.0.0", -}); -``` - -:::tip -O nome e a versão do seu aplicativo podem ser configurados por meio do arquivo .env ou do arquivo package.json. No template opinativo, usamos o arquivo package.json para recuperar o nome e a versão do aplicativo. -::: - -### Ambiente do Servidor da Aplicação - -Este é um enum que define o ambiente do servidor. Atualmente, os ambientes suportados são desenvolvimento e produção. Após a inicialização do servidor, a estrutura subjacente procurará a variável de ambiente NODE_ENV e definirá o ambiente do servidor de acordo. Se a variável de ambiente NODE_ENV não for definida, o ambiente do servidor será configurado como desenvolvimento por padrão. - -Além disso, no provedor da aplicação, o usuário pode realizar lógica condicional com base no ambiente do servidor. - -```typescript -if (this.isDevelopment()) { - // your logic here +async function bootstrap() { + const app = await AppFactory.create(container, App); + await app.listen(3000, ServerEnvironment.Development); } ``` -Aqui estão os valores do enum disponíveis para ambientes de servidor: - -```typescript -ServerEnvironment.Development; -ServerEnvironment.Production; -``` - -## Provedor da Classe App - -O provedor da classe App é o coração do template opinativo da aplicação. É responsável por inicializar a aplicação e fornecer funcionalidades a serem configuradas no processo de inicialização do servidor. Você pode fazer uso dos middlewares e provedores integrados para configurar sua aplicação. +:::info +O framework atualmente suporta o Express como seu adaptador principal, com Fastify e outros possíveis servidores internos em desenvolvimento. +::: -```typescript -class App extends AppExpress { - private middleware: IMiddleware; - private provider: IProvider; - - constructor() { - super(); - this.middleware = container.get(Middleware); - this.provider = container.get(Provider); - } - - protected configureServices(): void { - this.middleware.addBodyParser(); - this.middleware.setErrorHandler(); - } - - protected postServerInitialization(): void { - if (this.isDevelopment()) { - this.provider.envValidator.checkAll(); - } - } +### Gerenciamento de ambiente - protected serverShutdown(): void {} -} -``` +O ambiente do servidor é definido através do enum `ServerEnvironment`, com suporte para os modos `development` (desenvolvimento) e `production` (produção), padrão para desenvolvimento se `NODE_ENV` não estiver configurado. -O provedor da classe App oferece um conjunto de middlewares e provedores prontos para uso que podem ser usados para configurar sua aplicação. Explore as interfaces `IMiddleware` e `IProvider` para ver o que está disponível. +- ServerEnvironment.Development; +- ServerEnvironment.Production; -## Hooks do Ciclo de Vida da Classe App +## Hooks de ciclo de vida da aplicação -Outro aspecto importante da classe de Aplicação são os hooks do ciclo de vida. Esses hooks permitem que os desenvolvedores executem código antes, depois e na desligamento do servidor. É importante observar que, para tirar proveito desses hooks, os desenvolvedores devem criar uma classe App que estenda a classe Application e substituir os métodos conforme necessário. O seguinte exemplo mostra os hooks do ciclo de vida disponíveis no momento: +Um outro aspecto importante da classe Application são os hooks de ciclo de vida. Esses hooks permitem que os desenvolvedores executem código antes, depois e durante o desligamento do servidor. ```typescript /* Add any service that you want to be initialized before the server starts */ @@ -186,25 +108,24 @@ Outro aspecto importante da classe de Aplicação são os hooks do ciclo de vida protected serverShutdown(): void { } ``` -### Hooks Execution Order +### Ordem de execução dos hooks -![Application Lifecycle Hooks](./img/app-life-cycle.png) +![Hooks de ciclo de vida da aplicação](./img/app-life-cycle.png) -## Scripts da Aplicação +## Scripts da aplicação -Abaixo estão os scripts usados para executar, construir e testar sua aplicação. -A coluna de comandos mostra o NPM como gerenciador de pacotes, mas você pode usar o gerenciador de pacotes de sua escolha. +Scripts para construir, executar e testar a aplicação são fornecidos, acomodando diferentes estágios de desenvolvimento e necessidades operacionais, desde o desenvolvimento até a produção. -| Script | Descrição | Comando | -| ---------- | ----------------------------------------------------- | ------------------ | -| build | Constrói o pacote de produção na pasta ./dist. | npm run build | -| dev | Executa em modo de desenvolvimento com observação. | npm run dev | -| prod | Executa em modo de produção com base no pacote built. | npm run prod | -| test | Executa os testes localizados na pasta test. | npm run test | -| test:watch | Executa os testes em modo de observação e interativo. | npm run test:watch | -| test:cov | Gera relatorio de cobertura de testes. | npm run test:cov | -| format | Formatar código usando prettier. | npm run format | -| lint | Lint código usando eslint. | npm run lint | +| Script | Descrição | Comando | +| -------------------- | ----------------------------------------------------- | ------------------ | +| expressots run build | Constrói o pacote de produção na pasta ./dist. | npm run build | +| expressots run dev | Executa em modo de desenvolvimento com observação. | npm run dev | +| expressots run prod | Executa em modo de produção com base no pacote built. | npm run prod | +| test | Executa os testes localizados na pasta test. | npm run test | +| test:watch | Executa os testes em modo de observação e interativo. | npm run test:watch | +| test:cov | Gera relatorio de cobertura de testes. | npm run test:cov | +| format | Formatar código usando prettier. | npm run format | +| lint | Lint código usando eslint. | npm run lint | ## Executando a aplicação @@ -212,6 +133,19 @@ A coluna de comandos mostra o NPM como gerenciador de pacotes, mas você pode us npm run dev ``` -Dependendo do ambiente em que está executando a aplicação, você verá a seguinte mensagem no console: +Isso iniciará a aplicação com saída no console indicando a versão, porta em execução e ambiente, fornecendo um feedback claro sobre o estado de execução da aplicação. `expressots-demo version 1.0.0 is running on port 3000 - Environment: development` + +--- + +## Apoie o projeto + +ExpressoTS é um projeto de código aberto licenciado sob o MIT. É um projeto independente com desenvolvimento contínuo possibilitado graças ao seu suporte. Se você deseja ajudar, por favor considere: + +- Se tornar um **[Sponsor no GitHub](https://github.com/sponsors/expressots)** +- Siga a **[organização](https://github.com/expressots)** no GitHub e de um Star ⭐ no projeto +- Subscreva no nosso canal na Twitch: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)** +- Entre no nosso **[Discord](https://discord.com/invite/PyPJfGK)** +- Contribua submetendo **[issues e pull requests](https://github.com/expressots/expressots/issues/new/choose)** +- Compartilhe o projeto com seus amigos e colegas diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/overview/controller.md b/i18n/pt/docusaurus-plugin-content-docs/current/overview/controller.md index 45cc513a..91ee86c8 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/overview/controller.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/overview/controller.md @@ -126,15 +126,15 @@ Os decoradores de métodos HTTP e parâmetros são um conjunto de anotações us Aqui está uma lista de todos os decoradores `@httpMethods()` disponíveis no ExpressoTS, juntamente com sua descrição e uso: -| Decorador | Descrição | Uso | -| ----------- | -------------------------------------------------------------- | ---------------------------- | -| @httpGet | Vincula um método de controlador a um verbo HTTP GET. | @httpGet("/path") | -| @httpPost | Vincula um método de controlador a um verbo HTTP POST. | @httpPost("/path") | -| @httpPut | Vincula um método de controlador a um verbo HTTP PUT. | @httpPut("/path") | -| @httpPatch | Vincula um método de controlador a um verbo HTTP PATCH. | @httpPatch("/path") | -| @httpHead | Vincula um método de controlador a um verbo HTTP HEAD. | @httpHead("/path") | -| @httpDelete | Vincula um método de controlador a um verbo HTTP DELETE. | @httpDelete("/path") | -| @httpMethod | Vincula um método de controlador a um verbo HTTP especificado. | @httpMethod("verb", "/path") | +| Decorador | Descrição | Uso | +| ----------- | -------------------------------------------------------------- | ------------------------ | +| @Get | Vincula um método de controlador a um verbo HTTP GET. | @Get("/path") | +| @Post | Vincula um método de controlador a um verbo HTTP POST. | @Post("/path") | +| @Put | Vincula um método de controlador a um verbo HTTP PUT. | @Put("/path") | +| @Patch | Vincula um método de controlador a um verbo HTTP PATCH. | @Patch("/path") | +| @Head | Vincula um método de controlador a um verbo HTTP HEAD. | @Head("/path") | +| @Delete | Vincula um método de controlador a um verbo HTTP DELETE. | @Delete("/path") | +| @Method | Vincula um método de controlador a um verbo HTTP especificado. | @Method("verb", "/path") | ### Decoradores de parâmetros diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/overview/first-steps.md b/i18n/pt/docusaurus-plugin-content-docs/current/overview/first-steps.md index 721253ae..3353d82b 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/overview/first-steps.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/overview/first-steps.md @@ -4,21 +4,11 @@ sidebar_position: 1 # Primeiros Passos -Nesta seção, você vai mergulhar nos conceitos centrais do ExpressoTS para se familiarizar com o framework e seus componentes básicos. +Comece sua jornada com o ExpressoTS, um framework TypeScript para construir aplicações Node.js escaláveis e mantíveis. Esta seção orienta você através dos conceitos fundamentais, configuração e arquitetura do ExpressoTS. -## A Tecnologia +## Por que TypeScript? -Acreditamos no poder de linguagens fortemente tipadas, e o **[TypeScript](https://www.typescriptlang.org/)** é essencial quando se trata de estruturar ou construir aplicações em larga escala em **[NodeJS](https://nodejs.org/)**. No exemplo a seguir, usaremos principalmente TypeScript, e aqui estão as razões pelas quais usamos TypeScript: - -- Melhoria da qualidade do código: Tipagem forte ajuda a pegar erros e bugs em tempo de compilação, ao invés de em tempo de execução, o que ajuda a melhorar a qualidade geral do código. Isso pode levar a menos falhas e problemas com o código em produção. - -- Melhor escalabilidade: A tipagem forte pode ajudar a tornar o código mais escalável, permitindo refatorações e manutenções mais fáceis. Isso ocorre porque a tipagem forte garante que as alterações no código sejam consistentes e previsíveis, tornando mais fácil adicionar novos recursos ou modificar os existentes. - -- Aumento da produtividade: A tipagem forte pode aumentar a produtividade do desenvolvedor, fornecendo melhores ferramentas e suporte do editor, como conclusão de código, inferência de tipo e refatoração automática. Isso pode ajudar os desenvolvedores a escrever código mais rápido e com menos erros. - -- Melhoria da colaboração: A tipagem forte pode facilitar a colaboração entre desenvolvedores, fornecendo um entendimento compartilhado dos tipos e interfaces usados no código-fonte. Isso pode ajudar a reduzir mal-entendidos e inconsistências e tornar mais fácil para os desenvolvedores trabalharem juntos no mesmo código-fonte. - -- Melhor documentação: A tipagem forte pode ajudar a tornar o código auto-documentado, fornecendo uma descrição clara e concisa dos tipos e interfaces usados no código. Isso pode ajudar a reduzir a necessidade de comentários extensos e documentação, tornando o código mais fácil de entender e manter. +**[TypeScript](https://www.typescriptlang.org/)** é um elemento chave no desenvolvimento de aplicações robustas do lado do servidor devido à sua tipagem forte, que melhora significativamente a qualidade do código, escalabilidade, produtividade e colaboração. A tipagem forte não apenas ajuda a capturar erros precocemente, mas também aprimora a documentação e manutenção do código, fazendo do TypeScript uma escolha excelente para aplicações de grande escala. ## Pre-requisito @@ -26,97 +16,69 @@ Por favor, verifique se o [Node.js](https://nodejs.org) `version >=18.10.0` est ## Setup -Configurar um novo projeto ExpressoTS é bastante simples com a **[ExpressoTS CLI](../cli/overview.md)**. Com o `NPM` instalar ExpressoTS CLI Globalmente executando o seguinte comando: +Instale o **[CLI do ExpressoTS](../cli/overview.md)** globalmente usando o NPM para começar a configuração do seu projeto: + +Configurar um novo projeto ExpressoTS é bastante simples com o CLI do ExpressoTS. Primeiro, instale o CLI globalmente com o `NPM`: ```bash npm i -g @expressots/cli ``` - -Com a CLI `expressots`, você pode criar um novo projeto executando o seguinte comando: +Crie um novo projeto executando: ```bash expressots new ``` -Ou adicionar o nome do modelo e o gerenciador de pacotes como argumentos: +Para uma estrutura de projeto específica e gerenciador de pacotes, especifique diretamente o template e o gerenciador de pacotes: ```bash -expressots new -t