Merge pull request #43 from expressots/feature/update-compression

Update compressio tutorial

docs/tutorials/compression.md

@@ -6,51 +6,63 @@ sidebar_position: 1
 
 The npm compression package is a middleware that can compress response bodies for requests that traverse through it. This helps reduce the size of data that's sent over the network, leading to quicker response times and lower bandwidth usage. It uses the zlib library to perform gzip or deflate compression, both of which are widely supported by modern web browsers.
 
-## Compression Package
-
-- Performance: It can significantly reduce the size of the response body, thereby decreasing the time it takes for a client to download the response and render the content.
-
-- Efficiency: It helps in reducing bandwidth consumption which is especially useful if your server is sending large amounts of data or if you have limited bandwidth.
-
-- Overhead: While compression reduces the size of the response body, it does add some computational overhead on the server-side as the server must compress the response body before sending it.
-
-:::caution COMPRESSION OVERHEAD
-This might not be ideal for high traffic websites where server resources are at a premium.
-
-Not all content benefits from compression. Binary files like images and videos are already compressed and trying to compress them further can sometimes increase their size.
-:::
-
-## When to Use
-
-Deciding on when to use compression depends on the use case. If your website serves a lot of textual data (HTML, CSS, JS, JSON, XML etc.), then using the npm compression package can result in significant bandwidth savings and performance benefits. However, if your website is extremely high traffic, the additional computational overhead of compression might start to become a bottleneck.
-
-In high traffic scenarios, it might be more beneficial to use a reverse proxy or a CDN (Content Delivery Network) which can serve static assets and perform caching. This can offload some of the traffic from your main servers and also serve content from locations geographically closer to users, resulting in faster response times. These services usually handle compression themselves, meaning you wouldn't need to use the npm compression package.
-
-Modern approaches could involve a combination of techniques - serving static assets from a CDN, caching responses where appropriate, utilizing HTTP/2 for multiplexing, and splitting up your application into microservices to distribute the load.
-
-Remember, these approaches aren't mutually exclusive. Often the best approach is to use a combination of these techniques based on the specific requirements of your application. Testing and monitoring your application under realistic workloads can help you make the best decision.
-
-## Use with ExpressoTS
+## How to Use Compression in ExpressoTS
 
 Install the npm compression middleware.
 
 ```bash
 npm i compression
+npm i -D @types/compression
 ```
 
-After installation, you can add the middleware to your ExpressoTS app.
+### Add Middleware Globally
+
+**Non-opinionated template**: add the compression middleware in the `AppFactory` create method.
 
 ```typescript
 import compression from "compression";
 
-// Add in the application create method in the middleware array
-AppInstance.create(container, [compression()]);
+async function bootstrap() {
+    const app = await AppFactory.create(container, [compression()]);
+    await app.listen(3001, ServerEnvironment.Development);
+}
+
+bootstrap();
+```
+
+**Opinionated template**: configure the compression middleware in the `App` provider class. In the opinionated template common `expressjs` middlewares are offered out-of-the-box. Explore the options in `this.middleware` property.
+
+```typescript
+@provide(App)
+export class App extends AppExpress {
+    private middleware: IMiddleware;
+    private provider: IProvider;
+
+    constructor() {
+        super();
+        this.middleware = container.get<IMiddleware>(Middleware);
+        this.provider = container.get<IProvider>(Provider);
+    }
+
+    protected configureServices(): void {
+        this.middleware.addCompression();
+    }
+
+    protected postServerInitialization(): void {
+        if (this.isDevelopment()) {
+            this.provider.envValidator.checkAll();
+        }
+    }
+
+    protected serverShutdown(): void {}
+}
 ```
 
-Here is another example: using compress with filters, filtering requests that contain payload bodies larger than 100 * 1024 bytes:
+Using compress with filters, filtering requests that contain payload bodies larger than 100 \* 1024 bytes:
 
 ```typescript
-AppInstance.create(container, [
+async function bootstrap() {
+    const app = await AppFactory.create(container, [
         compression({
             level: 6,
             threshold: 100 * 1024,
@@ -62,21 +74,58 @@ AppInstance.create(container, [
             },
         }),
     ]);
+    await app.listen(3001, ServerEnvironment.Development);
+}
+
+bootstrap();
+```
+
+### Add Middleware to a Route
+
+This is valid for both templates. You can add the compression middleware to a specific route.
+
+```typescript
+@Get("/", compression())
+execute(){};
 ```
 
 :::tip
 For more information about the npm compression package, please visit the **[npm compression package](https://www.npmjs.com/package/compression)**.
 :::
 
+## Compression Package
+
+-   Performance: It can significantly reduce the size of the response body, thereby decreasing the time it takes for a client to download the response and render the content.
+
+-   Efficiency: It helps in reducing bandwidth consumption which is especially useful if your server is sending large amounts of data or if you have limited bandwidth.
+
+-   Overhead: While compression reduces the size of the response body, it does add some computational overhead on the server-side as the server must compress the response body before sending it.
+
+:::caution COMPRESSION OVERHEAD
+This might not be ideal for high traffic websites where server resources are at a premium.
+
+Not all content benefits from compression. Binary files like images and videos are already compressed and trying to compress them further can sometimes increase their size.
+:::
+
+## When to Use
+
+Deciding on when to use compression depends on the use case. If your website serves a lot of textual data (HTML, CSS, JS, JSON, XML etc.), then using the npm compression package can result in significant bandwidth savings and performance benefits. However, if your website is extremely high traffic, the additional computational overhead of compression might start to become a bottleneck.
+
+In high traffic scenarios, it might be more beneficial to use a reverse proxy or a CDN (Content Delivery Network) which can serve static assets and perform caching. This can offload some of the traffic from your main servers and also serve content from locations geographically closer to users, resulting in faster response times. These services usually handle compression themselves, meaning you wouldn't need to use the npm compression package.
+
+Modern approaches could involve a combination of techniques - serving static assets from a CDN, caching responses where appropriate, utilizing HTTP/2 for multiplexing, and splitting up your application into microservices to distribute the load.
+
+Remember, these approaches aren't mutually exclusive. Often the best approach is to use a combination of these techniques based on the specific requirements of your application. Testing and monitoring your application under realistic workloads can help you make the best decision.
+
 ---
 
 ## Support the Project
 
 ExpressoTS is an MIT-licensed open source project. It's an independent project with ongoing development made possible thanks to your support. If you'd like to help, please consider:
 
-- Become a **[sponsor on GitHub](https://github.com/sponsors/expressots)**
-- Follow the **[organization](https://github.com/expressots)** on GitHub and Star ⭐ the project
-- Subscribe to the Twitch channel: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)**
-- Join our **[Discord](https://discord.com/invite/PyPJfGK)**
-- Contribute submitting **[issues and pull requests](https://github.com/expressots/expressots/issues/new/choose)**
-- Share the project with your friends and colleagues
+-   Become a **[sponsor on GitHub](https://github.com/sponsors/expressots)**
+-   Follow the **[organization](https://github.com/expressots)** on GitHub and Star ⭐ the project
+-   Subscribe to the Twitch channel: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)**
+-   Join our **[Discord](https://discord.com/invite/PyPJfGK)**
+-   Contribute submitting **[issues and pull requests](https://github.com/expressots/expressots/issues/new/choose)**
+-   Share the project with your friends and colleagues

i18n/pt/docusaurus-plugin-content-docs/current/tutorials/compression.md

@@ -6,52 +6,63 @@ sidebar_position: 1
 
 O pacote npm compression é um middleware que pode comprimir corpos de resposta para solicitações que passam por ele, o que pode ajudar a reduzir o tamanho dos dados que são enviados pela rede, levando a tempos de resposta mais rápidos e uso menor de largura de banda. Ele usa a biblioteca zlib para realizar a compressão gzip ou deflate, ambos amplamente suportados pelos navegadores da web modernos.
 
-## Pacote de compressão
-
-- Desempenho: Pode reduzir significativamente o tamanho do corpo da resposta, diminuindo assim o tempo que um cliente leva para baixar a resposta e renderizar o conteúdo.
-
-- Eficiência: Ajuda na redução do consumo de largura de banda, o que é especialmente útil se o seu servidor estiver enviando grandes quantidades de dados ou se você tiver largura de banda limitada.
-Contras do pacote npm Compression:
-
-- Sobrecarga: Embora a compressão reduza o tamanho do corpo da resposta, ela adiciona alguma sobrecarga computacional do lado do servidor, pois o servidor deve comprimir o corpo da resposta antes de enviá-lo.
-
-:::caution SOBRECARGA DA COMPRESSÃO
-Isso pode não ser ideal para sites de alto tráfego onde os recursos do servidor estão em alta demanda.
-:::
-
-Nem todo conteúdo se beneficia da compressão. Arquivos binários como imagens e vídeos já são comprimidos e tentar comprimi-los ainda mais às vezes pode até aumentar o tamanho deles.
-
-## Quando usar
-
-Decidir quando usar a compressão depende do caso de uso. Se o seu site serve muitos dados textuais (HTML, CSS, JS, JSON, XML etc.), então usar o pacote de compressão npm pode resultar em economias significativas de largura de banda e benefícios de desempenho. No entanto, se o seu site tem um tráfego extremamente alto, a sobrecarga computacional adicional da compressão pode começar a se tornar um gargalo.
-
-Em cenários de alto tráfego, pode ser mais benéfico usar um proxy reverso ou uma CDN (Rede de Entrega de Conteúdo) que pode servir ativos estáticos e realizar caching. Isso pode desviar parte do tráfego dos seus servidores principais e também servir conteúdo de locais geograficamente mais próximos dos usuários, resultando em tempos de resposta mais rápidos. Esses serviços geralmente lidam com a compressão por conta própria, o que significa que você não precisaria usar o pacote de compressão npm.
-
-As abordagens modernas podem envolver uma combinação de técnicas - servir ativos estáticos de uma CDN, armazenar em cache respostas quando apropriado, utilizar HTTP/2 para multiplexação e dividir seu aplicativo em microserviços para distribuir a carga.
-
-Lembre-se, essas abordagens não são mutuamente exclusivas. Muitas vezes, a melhor abordagem é usar uma combinação dessas técnicas com base nos requisitos específicos do seu aplicativo. Testar e monitorar seu aplicativo sob cargas de trabalho realistas pode ajudá-lo a tomar a melhor decisão.
-
-## Usar com ExpressoTS
+## Como usar Compression no ExpressoTS
 
 Instale o middleware de compressão npm.
 
 ```bash
 npm i compression
+npm i -D @types/compression
 ```
 
-Após a instalação, você pode adicionar o middleware ao seu aplicativo ExpressoTS.
+### Adicione o Middleware Globalmente
+
+**Modelo não opinativo**: adicione o middleware de compressão no método `create` da classe `AppFactory`.
 
 ```typescript
 import compression from "compression";
 
-// Adicione no método de criação do aplicativo no array de middleware
-AppInstance.create(container, [compression()]);
+async function bootstrap() {
+    const app = await AppFactory.create(container, [compression()]);
+    await app.listen(3001, ServerEnvironment.Development);
+}
+
+bootstrap();
+```
+
+**Modelo opinativo**: configure o middleware de compressão na classe `App` do provedor. No modelo opinativo, middlewares comuns do `expressjs` são oferecidos por padrão para uso. Explore as opções na propriedade `this.middleware`.
+
+```typescript
+@provide(App)
+export class App extends AppExpress {
+    private middleware: IMiddleware;
+    private provider: IProvider;
+
+    constructor() {
+        super();
+        this.middleware = container.get<IMiddleware>(Middleware);
+        this.provider = container.get<IProvider>(Provider);
+    }
+
+    protected configureServices(): void {
+        this.middleware.addCompression();
+    }
+
+    protected postServerInitialization(): void {
+        if (this.isDevelopment()) {
+            this.provider.envValidator.checkAll();
+        }
+    }
+
+    protected serverShutdown(): void {}
+}
 ```
 
-Aqui está outro exemplo: usando compressão com filtros, filtrando solicitações que contêm corpos de carga útil maiores que 100 * 1024 bytes:
+Um exemplo usando compressão com filtros, selecionando solicitações que contêm payloads de carga útil maiores que 100 \* 1024 bytes:
 
 ```typescript
-AppInstance.create(container, [
+async function bootstrap() {
+    const app = await AppFactory.create(container, [
         compression({
             level: 6,
             threshold: 100 * 1024,
@@ -63,21 +74,59 @@ AppInstance.create(container, [
             },
         }),
     ]);
+    await app.listen(3001, ServerEnvironment.Development);
+}
+
+bootstrap();
+```
+
+### Adicione o Middleware a Rotas Específicas
+
+O código a seguir adiciona o middleware de compressão a rotas específicas validos em ambos os modelos opinativo e não opinativo.
+
+```typescript
+@Get("/", compression())
+execute(){};
 ```
 
 :::tip
 Para mais informações sobre o pacote de compressão npm, por favor visite o **[pacote compression do npm](https://www.npmjs.com/package/compression)**.
 :::
 
+## Pacote de compressão
+
+-   Desempenho: Pode reduzir significativamente o tamanho do corpo da resposta, diminuindo assim o tempo que um cliente leva para baixar a resposta e renderizar o conteúdo.
+
+-   Eficiência: Ajuda na redução do consumo de largura de banda, o que é especialmente útil se o seu servidor estiver enviando grandes quantidades de dados ou se você tiver largura de banda limitada.
+    Contras do pacote npm Compression:
+
+-   Sobrecarga: Embora a compressão reduza o tamanho do corpo da resposta, ela adiciona alguma sobrecarga computacional do lado do servidor, pois o servidor deve comprimir o corpo da resposta antes de enviá-lo.
+
+:::caution SOBRECARGA DA COMPRESSÃO
+Isso pode não ser ideal para sites de alto tráfego onde os recursos do servidor estão em alta demanda.
+:::
+
+Nem todo conteúdo se beneficia da compressão. Arquivos binários como imagens e vídeos já são comprimidos e tentar comprimi-los ainda mais às vezes pode até aumentar o tamanho deles.
+
+## Quando usar
+
+Decidir quando usar a compressão depende do caso de uso. Se o seu site serve muitos dados textuais (HTML, CSS, JS, JSON, XML etc.), então usar o pacote de compressão npm pode resultar em economias significativas de largura de banda e benefícios de desempenho. No entanto, se o seu site tem um tráfego extremamente alto, a sobrecarga computacional adicional da compressão pode começar a se tornar um gargalo.
+
+Em cenários de alto tráfego, pode ser mais benéfico usar um proxy reverso ou uma CDN (Rede de Entrega de Conteúdo) que pode servir ativos estáticos e realizar caching. Isso pode desviar parte do tráfego dos seus servidores principais e também servir conteúdo de locais geograficamente mais próximos dos usuários, resultando em tempos de resposta mais rápidos. Esses serviços geralmente lidam com a compressão por conta própria, o que significa que você não precisaria usar o pacote de compressão npm.
+
+As abordagens modernas podem envolver uma combinação de técnicas - servir ativos estáticos de uma CDN, armazenar em cache respostas quando apropriado, utilizar HTTP/2 para multiplexação e dividir seu aplicativo em microserviços para distribuir a carga.
+
+Lembre-se, essas abordagens não são mutuamente exclusivas. Muitas vezes, a melhor abordagem é usar uma combinação dessas técnicas com base nos requisitos específicos do seu aplicativo. Testar e monitorar seu aplicativo sob cargas de trabalho realistas pode ajudá-lo a tomar a melhor decisão.
+
 ---
 
 ## 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
+-   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