Nesse post vamos aprofundar o conhecimento em Generics, mais especificamente nesses três conceitos: Invariância, Covariância e Contravariância.

Antes de começar, vamos recordar do uso de Generics

class Box<T>(val content: T) {
    val list = mutableListOf<T>()

    fun store() {
        list.add(content)
    }
}

T aqui não é um tipo especifico, que exista no Kotlin, mas um alias, que diz: olha, esse T pode ser qualquer tipo declarado quando a classe for instanciada.

Num cenário onde Generics não existisse, teríamos que contornar o suporte criando múltiplas declarações similar a acima para cada tipo que precisássemos.

Aprofundando

Agora que revisamos o conhecimento sobre Generics, vamos ao foco desse post: Invariância, Covariância e Contravariância.

Esses três conceitos são características de um tipo Genérico, que define o comportamento dele em relação à hierarquia de tipos.

Invariância

Dizemos que um tipo genérico <T> é invariante quando nenhuma substituição de tipo é permitida, garantindo que o tipo seja o mesmo na leitura e na escrita:

open class Food(val name: String)
class Vegetable(name: String) : Food(name)

class Box<T>(val content: T) {
    val list = mutableListOf<T>()

    fun store() {
        list.add(content)
    }
}

val foodBox: Box<Food> = Box(Food("beans")) // funciona
val vegBox: Box<Vegetable> = Box(Vegetable("carrot")) // funciona

val invalidBox: Box<Food> = vegBox // Não funciona

No exemplo não funcional o tipo Vegetablenão pode ser atribuído à variável invalidBox, pois espera-se exatamente o que foi definido um tipo Box<Food>.

Isso é um comportamento que chamamos de invariante em um tipo genérico.

Covariância

Agora, um tipo genérico <T> é covariante quando a substituição por subtipos é permitida, mas apenas na leitura, confuso? Vamos ao exemplo pra ficar mais claro:

open class Food(val name: String)
class Vegetable(name: String) : Food(name)

class Box<out T>(val content: T) {
    fun first(): T = content
    fun print(msg: T) { // 1. Não funciona, T não pode ser usado na entrada
        println(msg)
    }
}

val foodBox: Box<Food> = Box(Food("beans")) // funciona
val vegBox: Box<Vegetable> = Box(Vegetable("carrot")) // funciona
val vegLeafBox: Box<Food> = Box(Vegetable("lettuce")) // funciona

val invalidFood: Box<Vegetable> = foodBox // 2. Não funciona

vegLeafBox.first() // Funciona

No código acima há duas violações da covariância

1. Substituição de tipos na escrita/entrada
2. Atribuição de supertipo à um subtipo

Se não houvesse essa restrição (covariância só permitir leitura), poderíamos quebrar a segurança de tipos, por exemplo, colocando um Food genérico em um lugar que espera um Vegetable ou subtipo, gerando problemas em tempo de execução.

Contravariância

Aqui, um tipo genérico <T> é contravariante quando a substituição por supertipos é permitida, mas apenas na escrita, justamente o oposto da covariância.

  open class Food(val name: String)
  class Vegetable(name: String) : Food(name)
  class Fruit(name: String) : Food(name)
  
  class Box<in T> {
      fun print(item: T) {
          println(item)
      }
  
      fun printWithTitle(item: T): T { // 1. Uso inválido de T no retorno
          println("----- list -----")
          println(item)
      }
  }
  
  // Removendo o trecho inválido (1) e chamando o método
  val foodBox: Box<Food> = Box<Food>() // funciona
  val vegetableBox: Box<Vegetable> = foodBox // funciona 
  val fruitBox: Box<Food> = Box<Fruit>()// (2). Não funciona

  foodBox.print(Food("beans")) // Funciona
  foodBox.print(Fruit("apple")) // (3). Não funciona

Já no código acima há outras duas da contravariância, inversas a covariância

1. Substituição de tipos na leitura/saída
2. Em (2) e (3) há atribuição de subtipo à um supertipo

Se não houvesse essa restrição (contravariância só permitir escrita), poderíamos quebrar a segurança de tipos, por exemplo, colocando um subtipo Fruit em um lugar que espera um tipo Vegetable ou supertipo, causando problemas em tempo de execução.

Bônus

No Kotlin, há uma palavra reservada: where. Apesar de não ter relação com os conceitos anteriores, ela pode ser combinada com in e out.

Em resumo ela nos permite detalhar as restrições do tipo genérico, por exemplo:

interface Food
interface Warm
interface Book

class MyBook: Book
class MyFood: Food
class WarmBox: Warm
class WarmFoodBox: Warm, Food

class Box<T>(val content: T) where T:Food, T:Warm

val box = Box(MyBook()) // Não funciona
val foodBox = Box(MyFood()) // Não funciona
val warmBox = Box(WarmBox()) // Não funciona
val warmFoodBox = Box(WarmFoodBox()) // Funciona

Ou seja, nesse exemplo acima é como dizer: o conteúdo da caixa pode ser apenas do tipo FoodeWarm.

Combinando com covariância

interface Food
interface Warm
interface Book

class MyBook: Book
class MyFood: Food
class WarmBox: Warm
class WarmFoodBox: Warm, Food

class Box<out T>(val content: T) where T : Food, T : Warm {
    fun first(): T = content
}

val box = Box(MyBook()) // Não funciona
val foodBox = Box(MyFood()) // Não funciona
val warmBox = Box(WarmBox()) // Não funciona
val warmFoodBox = Box(WarmFoodBox()) // Funciona

warmFoodBox.first() // Funciona

Combinando com contravariância

interface Food
interface Warm
interface Book

class MyBook: Book
class MyFood: Food
class WarmBox: Warm
class WarmFoodBox: Warm, Food

class Box<in T> where T : Food, T : Warm {
    fun show(item: T) {
        println(item)
    }
}
val box = Box<MyBook>() // Não funciona
val foodBox = Box<MyFood>() // Não funciona
val warmBox = Box<WarmBox>() // Não funciona
val warmFoodBox = Box<WarmFoodBox>() // Funciona

val warmFoodBox = Box<WarmFoodBox>() // Funciona

warmFoodBox.show(WarmFoodBox())

Conclusão

Em suma, os conceitos discutidos definem o comportamento do tipo Genérico em relação a hierarquia de tipos, eles são essenciais em linguagens de programação com tipagem estática para garantir que nenhuma operação com tipagem inválida passe despercebida pelo compilador, gerando insegurança de tipos em tempo de execução.

Essa insegurança de tipo é justamente uma caraterística de linguagens com tipagem dinâmica como o JavaScript, Python e Ruby. O que não as tornam, de maneira alguma, linguagens inferiores, mas apenas linguagens com o objetivo oposto das estaticamente tipadas: flexibilidade.

E claro, essa flexibilidade traz mais liberdade, no entanto, com consequências: o risco de detectar problemas somente em tempo de execução. Por outro lado, linguagens estaticamente tipadas costumam ser mais “burocráticas com tipos”, ou seja, menos flexíveis, porém menos propensa a problemas detectados somente em tempo de execução.

A escolha entre elas depende do tipo de problema a ser resolvido, mas se escolher as estaticamente tipadas os conceitos de Invariância, Covariância e Contravariâcia no uso de Generics estarão presentes, mesmo que com diferenças sutis na forma como são aplicados em cada linguagem.

Contextualizando

Web Assembly é uma compilação alvo portátil para linguagens de programação, similar ao Assembly, de baixo nível. Com ele é possível gerar, a partir de qualquer linguagem, código executável pelo browser, desde que exista um compilador adequado e um ambiente de execução adaptado.

Isso abre um leque de possibilidades, pois superamos a limitação de só poder executar JavaScript no navegador, obviamente que Web Assembly não existe como uma solução para substituí-lo, mas para complementá-lo.

Por muito tempo, a criação de interações ricas e performáticas na web, como jogos, processamento de imagens e animações 3D, que fosse performática e não comprometesse a experiência do usuário, era muito custoso de desenvolver, dado as características do próprio JavaScript e de como os navegadores funcionavam.

Principais conceitos

Antes de partirmos para uma abordagem mais prática, precisamos entender alguns conceitos fundamentais por trás do Web Assembly

Módulo

Ele representa um binário (o que foi gerado por uma linguagem origem) que foi compilado pelo navegador em um código de máquina, esse módulo pode ser compartilhado entre janelas e workers.

Memória

Um ArrayBuffer de tamanho variável, que contém o Array de bytes que são lidos e escritos pelas instruções de memória, de baixo nível, do Web Assembly.

Tabela

Um array tipado contendo referências, à funções, variáveis, etc.

Instância

Se trata de um módulo que contém todo o estado que utiliza em tempo de execução, como a memória e a tabela, além de um conjunto de valores importados. É similar a um ES module que é carregado em algum escopo global particular.

Casos de uso

Pra ter uma ideia do potencial dessa tecnologia, podemos listar alguns casos de uso reais

• Figma — Utiliza Web Assembly para renderizar gráficos e manipular imagens no navegador de forma muito rápida, já que esse tipo de atividade exige cálculos intensivos.
• Squoosh — Ferramenta de compressão de imagem criada pelo Google, que usa Web Assembly para rodar codecs de imagem, como WebP, AVIF, etc. Diretamente no navegador.
• Unity — Usa Web Assembly com WebGL pra rodar jogos e aplicações 3D no navegador.
• Capcut Web — Escrito em C++, mas usa Emscripten para compilar e código para Web Assembly, otimizando tarefas relacionadas a edição de vídeo no navegador
• PyScript — Permite rodar python no browser, graças ao Pyodide.

Esses são só alguns dos exemplos de uso do Web Assembly, existe uma lista extensa de outros casos de uso, disponível aqui.

Na prática

Vamos colocar a mão na massa!

Criaremos um módulo usando Golang e o compilremos para Web Assembly, para que seja integrado em uma página web.

Passo 1: Criando o módulo em Golang

// Crie um diretório
mkdir go-wasm

// Inicie um projeto Go
go mod init go-wasm

Em seguida, vamos criar arquivo main.go e incluir nele o seguinte:

package main

// da lib syscall/js, 
import (
  // para trabalhar inteiros muito grandes
 "math/big"
  // para fazer ponte entre o Go e o JavaScript
 "syscall/js"
)

// Calculamos o fatorial de forma iterativa com o parâmetro passado 
func factorial(this js.Value, param []js.Value) interface{} {
 num := param[0].Int()
 result := big.NewInt(1)

 for i := 2; i <= num; i++ {
  result.Mul(result, big.NewInt(int64(i)))
 }

 return js.ValueOf(result.String())
}

func main() {
 c := make(chan struct{}, 0)

 // Registramos a função factorial, que ficará disponível
 // para ser chamada pelo código JavaScript
 js.Global().Set("factorial", js.FuncOf(factorial))

 // Precisamos disso para impedir que o programa Go finalize
 <-c
}

Passo 2: Compilando para Web Assembly

Golang possui suporte a compilação para WASM desde a sua versão 1.11, e o processo é bem simples.

Com o compilador do Golang instalado, é só executar o comando abaixo no seu bash:

GOOS=js GOARCH=wasm go build -o result/main.wasm

Com isso, o binário main.wasm será gerado, contendo:

• As instruções do módulo que calcula o fatorial
• Instruções Web Assembly, que são executadas por navegadores compatíveis
• Estrutura do runtime do go embutida, como o garbage collector, por exemplo.

Passo 3: Integrando na nossa página

Antes de começar, é fundamental destacar que precisamos do código JavaScript, que vem junto com a instalação do compilador do Go, para o para poder executar o binário compilado a partir do GO, se estiver usando bash pode copiá-lo para o diretório result/ do projeto.

cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" result

Você também pode localizar a instalação do Go na sua máquina e copiar o arquivo direto para a pasta result/.

Em seguida, crie um arquivo index.html em result/, contendo:

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport"
        content="width=device-width, initial-scale=1.0">
    <title>GO - WASM</title>
    <script src="./wasm_exec.js"></script>
</head>

<body>
    <div>
        <h3 for="value">Factorial</h3>
        <input type="text" id="value">
        <button id="calculate">Calculate</button>
    </div>
    <br>
    <label>Result: </label>
    <label id="result"></label>

    <script>
        function initWasm() {
            // Cria do gerenciador de execução do Go para WebAssembly
            const go = new Go();
            // Carrega o binário
            WebAssembly.instantiateStreaming(fetch("main.wasm"), go.importObject).then((result) => {
                // Executa o código Go após a instância do WebAssembly
                // ser criada
                go.run(result.instance);
            });
        }

        initWasm();

        const button = document.getElementById('calculate');

        const formatOutput = (output) => {
            return String(output).replace(/\B(?=(\d{3})+(?!\d))/g, ".");
        }

        const calculateFactorial = () => {
            const num = document.getElementById('value').value;
            // Realizamos a chamada de factorial, disponível globalmente,
            // após a execução de go.run, pois havia sido registrada
            // através do syscall/js citado anteriormente
            const result = BigInt(factorial(parseInt(num)));

            // Formatamos a visualização, que tem a leitura 
            // comprometida para fatoriais muito grandes
            document.getElementById('result').innerHTML = formatOutput(result);
        }

        button.addEventListener('click', calculateFactorial);
    </script>

</body>

</html>

E ao interagir com a página após abrir a aplicação no navegador, temos algo como:

Legal né? O nosso código JavaScript está interagindo com o código escrito em Go, que foi compilado para WASM.

Nesse exemplo, o código está sendo executado na thread principal do navegador, mas podemos ir além, imagina o que podemos alcançar ao combinar isso com Web Workers, mais, compilar a partir de outras linguagens, como C++ e Rust!

Mas isso talvez seja tema pra um próximo post do assunto.

Conclusão

Apesar da evolução de frameworks, bibliotecas, e do próprio JavaScript nos últimos anos, o que podia ser feito do lado cliente sempre esbarrava nas limitações impostas pelas características dos navegadores e do próprio JavaScript.

Web Assembly estendeu as capacidades do que pode ser executado no cliente, e combinado com outros API’s, hoje é case de sucesso em grandes projetos e empresas, é claro, ele continua em evolução, e assim como toda ferramenta não resolve todos os problemas, mas o fato dela existir abre o leque de como pensamos em soluções onde a performance do lado cliente é um critério importante.

Espero que tenha curtido o post, até logo!

Contextualizando

Observabilidade é a prática de coletar, analisar e entender dados gerados por um sistema para garantir que ele esteja funcionando corretamente e para identificar e solucionar problemas quando eles ocorrerem. Essa prática se baseia em três pilares, popularmente conhecidos com Pilares da Observabilidade, que são Métricas, Logs e Traces.

• Métricas — São dados referentes à infraestrutura ou ao sistema, capturados em um período de tempo, que ajudam a compreender a saúde da aplicação e da infraestrutura. Como exemplos podemos citar taxa de erros de respostas, uso de memória, uso de CPU, etc.
• Logs — São registros detalhados de operações que ocorrem dentro da aplicação, muito importantes para compreender o que aconteceu dentro da aplicação em um determinado período.
• Traces — São informações referente ao percurso de uma requisição através dos diferentes componentes do sistema, que nos permite rastrear uma operação desde a sua origem até o seu destino.

No contexto de aplicações web client-side o conceito ainda está caminhando apesar de ser bastante difundido em aplicações server-side, a falta de maturidade na aplicação desse conceito em aplicações Front-end leva a uma série de desafios no que diz respeito a garantir a performance, a satisfação dos usuários e à solução rápida de problemas.

Além disso, a falta de visão sobre como o usuário interage com a aplicação, por onde navega, onde clica, qual navegador utiliza e como a aplicação está realmente se comportando pode dificultar a investigação e solução de possíveis problemas, bem como o entendimento de qual aspecto da aplicação precisa ser melhorado de forma assertiva baseado em dados de usuários reais.

Felizmente, nos últimos anos tem surgido algumas ferramentas com esse objetivo, e hoje vamos falar sobre uma delas, o Grafana Faro!

Grafana Faro

O Grafana Faro é um SDK JavaScritpt Open Source, anunciado em 2022 pela Grafana Labs, que pode ser integrado em aplicações web para coletar dados de monitoramento de usuários reais, tais como métricas de performance, logs, eventos, exceções e traces.

Esses dados passam por um fluxo envolvendo ferramentas como o Grafana Loki, Grafana Tempo e os dashboards de visualização do Grafana. Além disso, o SDK pode enviar dados para diversas outras ferramentas de observabilidade.

Integrando ao Angular

Para tanto vamos dividir a tarefa em duas etapas:

1. Primeiro precisamos configurar a infraestrutura que irá receber, processar e permitir que os dados sejam visualizados graficamente.
2. Integrar o SDK na nossa aplicação Angular para coletar e enviar os dados.

Preparando a infraestrutura

Vamos utilizar o Docker para configurar os componentes necessários.

version: '3'
services:
  # aqui configuramos o grafana como ferramenta de visualização dos dados
  grafana:
    image: grafana/grafana:latest
    environment:
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_BASIC_ENABLED=false
      - GF_FEATURE_TOGGLES_ENABLE=accessControlOnCall
      - GF_INSTALL_PLUGINS=https://storage.googleapis.com/integration-artifacts/grafana-lokiexplore-app/grafana-lokiexplore-app-latest.zip;grafana-lokiexplore-app
    ports:
      - 3000:3000/tcp

  # configuramos o grafana loki
  loki:
    image: grafana/loki:main
    command: '-config.file=/etc/loki/loki-config.yaml'
    ports:
      - 3100:3100
    volumes:
      - ./loki-config.yaml:/etc/loki/loki-config.yaml
  
  # configuramos o grafana alloy, que será o ponto
  # de entrada para onde o grafana faro irá enviar os dados
  faro_collector:
    image: grafana/alloy:latest
    ports:
      - 12345:12345
      - 3333:3333
    volumes:
      - ./config.alloy:/etc/alloy/config.alloy
    command: run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data /etc/alloy/config.alloy
    depends_on:
      - tempo

  # definimos uma etapa de inicialização do grafana tempo, 
  # criando um container temporário somente para configurar 
  # permissões no volume
  init_tempo:
    image: &tempo_image grafana/tempo:latest
    user: root
    entrypoint:
      - "chown"
      - "10001:10001"
      - "/var/tempo"
    volumes:
      - ./tempo-data:/var/tempo
  # e por fim configuramos o container do grafana tempo
  tempo:
    image: *tempo_image
    ports:
      - 3200:3200
      - 4318:4318
    volumes:
      - ./tempo.yaml:/etc/tempo.yaml 
      - ./tempo-data:/var/tempo

    command: [ "-config.file=/etc/tempo.yaml" ]
    depends_on:
      - init_tempo

Além disso, precisamos definir as configurações para o Grafana Loki, bem como para o Grafana Tempo. Porém, para não estender demais o artigo, vamos focar apenas na configuração do agente (arquivo config.alloy). As demais configurações estão disponíveis nesse repositório.

Configuração do agente

// configura o agente que irá receber os dados vindo do frontend
faro.receiver "integrations_app_agent_receiver" {
    server {
        cors_allowed_origins = ["*"]
        listen_address = "0.0.0.0"
        listen_port = 3333
        max_allowed_payload_size = "10MiB"

        rate_limiting {
            rate = 100
        }
    }

    output {
        // repassa os logs para a etapa de processamento e rotulamento
        logs   = [loki.process.add_label.receiver]
        // repassa os traces para a etapa de persistência no Grafana Tempo
        traces = [otelcol.exporter.otlphttp.trace_write.input]    
   }
}

// essa etapa é responsável por definir os rótulos criados a partir 
// dos campos nos logs, para criar filtros no dashboard do grafana
loki.process "add_label" {
   stage.logfmt {
        mapping = {
            "level" = "",
            "kind" = "",
            "type"="",
            "app_name"="",
            "message"= "",
            "browser_name"= "",
            "browser_version" = "",
        }
    }

    stage.labels {
        values = {
            "level" = "level",
            "kind" = "kind",
            "type" = "type",
            "app_name" = "app_name",
            "message" = "message",
            "browser_name" = "browser_name",
            "browser_version" = "",

        }
    }
    // repassa para a etapa de persistência de logs no Grafana Loki
    forward_to = [loki.write.logs_write_client.receiver]
}

// envia os logs para o endpoint do servidor do Grafana oki
loki.write "logs_write_client" {
    endpoint {
        url = "http://loki:3100/loki/api/v1/push"
    }
}
// aqui, definimos o exportador usando uma configuração para o 
// coletor do Open Telemetry, ele irá coletar os traces e enviá-los 
// via HTTP para o Grafana Tempo
otelcol.exporter.otlphttp "trace_write" {

    client {
        endpoint = "http://tempo:4318"
        tls {  
            insecure             = true
            insecure_skip_verify = true
        }
    }
}

A primeira etapa está finalizada, agora é só executar o comando abaixo e verificar se todos os containers estão de pé!

docker compose up

Integrando o SDK ao Angular

Vamos usar uma aplicação Angular de exemplo, disponível nesse repositório: https://github.com/danilolmc/angular-observability

O processo é bastante simples, precisamos somente inicializar o SDK antes que a aplicação Angular seja completamente carregada, por isso usamos o Injection Token APP_INITIALIZER.

import { APP_INITIALIZER, ApplicationConfig, ErrorHandler, NgZone } from '@angular/core';
import { TracingInstrumentation } from '@grafana/faro-web-tracing';

import { provideHttpClient } from '@angular/common/http';
import { provideRouter } from '@angular/router';
import { routes } from './app.routes';
import { getWebInstrumentations, initializeFaro, MetaSession, ViewInstrumentation, WebVitalsInstrumentation } from '@grafana/faro-web-sdk';
import { GlobalErrorHandler } from './shared/error/global.handler';


export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideHttpClient(),
    provideApiEndpoint(),
    {
      provide: APP_INITIALIZER,
      useFactory: (zone: NgZone) => {
          return function () {
              zone.runOutsideAngular(() => {
                  initializeFaro({
                      url: 'http://localhost:3333/collect',
                      app: {
                          name: 'Product App',
                          version: '1.0',
                      },
                      sessionTracking: {
                          enabled: true,
                          persistent: true,
                          maxSessionPersistenceTime: 1 * 60 * 2000,
                          onSessionChange: (oldSession: MetaSession | null, newSession: MetaSession) => {
                              console.log(`Session ${oldSession == null ? 'created' : 'changed'}`, { oldSession, newSession })
                          },
                      },
                      instrumentations: [
                          # desabilidando a captura de erros do console do usuário
                          ...getWebInstrumentations({
                              captureConsole: false,
                          }),
                          # instrumentação para gerar métricas do Core Web Vitals
                          new WebVitalsInstrumentation(),
                          # instrumentação para gerar dados de tracing
                          new TracingInstrumentation(),
                      ]
                  })
              });
          }
      },
      multi: true,
      deps: [NgZone]
  },
  {
      provide: ErrorHandler,
      useClass: GlobalErrorHandler
  }

  ]
};

Detalhe que, como o SDK não consegue capturar automaticamente os erros lançados pelo Angular no console do navegador, precisamos configurar um handler para que ele seja disparado automaticamente quando um erro ocorrer.

Por fim, é só executar a aplicação e ver a mágica acontecer! Ao olhar na aba de Rede do DevTools do browser, você vai perceber que o SDK enviou automaticamente os dados de telemetria da aplicação Angular.

Para visualizar esses dados no Grafana é simples:

• Acesse a ferramenta de visualização do Grafana em http://localhost:3000
• Adicione o Grafana Loki e o Grafana tempo como fontes de dados (Data Sources) de acordo com a instrução no repositório: https://github.com/danilolmc/angular-observability?tab=readme-ov-file#setting-up-data-sources-in-grafana
• Após isso será possível visualizar os dados de tracing e de logs, métricas e afins, direto pela ferramenta Explorer do Grafana, interagindo com os filtros definidos na etapa de configuração do agente.
• Você também pode configurar seu próprio dashboard gráfico a partir desses dados, ou importar um, como esse: https://github.com/grafana/faro-web-sdk/blob/main/dashboards/frontend-application.json

E esse é o resultado, após interagir com a aplicação Angular por alguns minutos:

Com isso, conseguimos visualizar diversos dados de um usuário real da aplicação, como métricas de Web Vitals, qual navegador o usuário está usando, em qual versão, número de erros acontecendo na aplicação, tipos de erros, número de acessos, quantas vezes o usuário iniciou e encerrou a sessão, dados detalhados de requisições e muito mais.

E não para por aí: o limite da customização depende do que você quer monitorar na sua aplicação, o que significa que dashboards ainda mais completos podem ser criados.

Conclusão

O Grafana Faro é uma ferramenta muito interessante no contexto abordado neste post, principalmente pela facilidade de integração e pelas possibilidades de extensão. Ele oferece uma visão mais palpável de como nossa aplicação se comporta diante de usuários reais. No entanto, é evidente que existe uma complexidade na manutenção desse tipo de infraestrutura. Apesar de soluções como o Grafana Cloud facilitarem a configuração e manutenção da infraestrutura para receber e lidar com dados de telemetria vindos do SDK, é importante avaliar a real necessidade desse tipo de solução para suas aplicações antes de considerar uma solução com essa complexidade.

Bem, é isso! A ideia era introduzir o tema, que ainda tem muito espaço para ser discutido no contexto de aplicações client-side. Espero que tenha curtido!

Repositório do projeto: https://github.com/danilolmc/angular-observability

Mais sobre o Grafana Faro SDK: https://grafana.com/oss/faro/

Mais sobre o Grafana Cloud: https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/

Até logo, dev! 😉

Contextualizando

Desde a versão 17 o Angular vem passando por um processo de modernização e renascimento, caracterizado pela introdução de uma série de recursos que buscam melhorar a experiência de desenvolvimento, diminuir a curva de aprendizado e tornar o framework mais performático e completo.

Um desses novos recursos foram as Deferrable Views, que nos permite fazer o lazy loading dos elementos da nossa aplicação a nível de template, por exemplo:

@defer {
  <app-list [posts]="posts()"/>
} @loading {
  <p>Carregando posts...</p>
} @error {
  <p>Erro ao tentar carregar posts...</p>
}

Usamos a declaração @defer no nosso template para indicar que tudo que está no bloco entre a sua chave de abertura e fechamento deve ser carregado de forma tardia, nesse exemplo estamos adiando o carregamento de um componente que renderiza uma lista até que os dados estejam disponíveis para ser renderizado.

Podemos ainda declarar um bloco @loading para renderizar um estado de carregamento e um bloco @error para dar um feedback ao usuário caso houver problema ao carregar o componente de lista.

Testando Deferrable Views

Bem, toda essa inclusão de recursos levanta a discussão sobre testes, e com as Deferrable Views não é diferente, e é disso que vamos aprofundar agora.

O Angular gerencia a renderização dos blocos no contexto das Deferrable Views, ele decide quando cada bloco será renderizado para o usuário, no entanto, num contexto de teste onde queremos reproduzir e validar os comportamentos da nossa View o ideal é que tenhamos mais controle sobre isso.

Felizmente o Angular disponibiliza uma API que nos permite disparar os diferentes estados respectivos a cada um desses blocos, por exemplo:

// Renderiza o estado final
await deferBlockFixture.render(DeferBlockState.Complete);

// Renderiza o estado de loading respectivo ao bloco @loading
await deferBlockFixture.render(DeferBlockState.Loading);

// Renderiza o estado de erro respectivo ao bloco @error
await deferBlockFixture.render(DeferBlockState.Error);

// Não incluímos no nosso exemplo, mas 
// caso tivesse poderiamos renderizar o estado respectivo 
// ao bloco @placeholder
await deferBlockFixture.render(DeferBlockState.Placeholder);

Basicamente, podemos controlar a renderização manualmente e consequentemente controlar o comportamento da nossa View, vamos ver um exemplo completo agora…

Preparando o ambiente

Vamos implementar alguns testes no nosso componente anterior, que serão o seguinte:

• Testar o cenário feliz, onde a lista de posts foi renderizada;
• Testar o cenário infeliz, em que houve um erro ao renderizar a lista;
• Testar o cenário de carregamento, onde o componente de lista ainda está sendo preparado para renderizar;
• E um plus, testando cenário onde a lista carrega com sucesso, porém está vazia.

Porém, antes de começar, precisamos configurar o ambiente, vamos usar o seguinte biblioteca Angular Testing Library e o Jest, para configurar no seu ambiente use os links abaixo:

• Jest: https://timdeschryver.dev/blog/integrate-jest-into-an-angular-application-and-library#
• Angular Testing Library: https://timdeschryver.dev/blog/good-testing-practices-with-angular-testing-library#

Escrevendo os testes

Bora pro primeiro teste, nosso componente responsável por renderizar a lista usa um serviço que requisita dados de uma API, vamos criar um mock para o nosso serviço:

Criando nosso mock

const mockedPosts: Post[] = [
  {
    "id": 1,
    "title": "First Post",
    "body": "This is the first post",
    "tags": [],
    "reactions": {
      "likes": 192,
      "dislikes": 25
    },
    "views": 305,
    "userId": 121
  },
  {
    "id": 2,
    "title": "Second Post",
    "body": "This is the second post",
    "tags": [],
    "reactions": {
      "likes": 192,
      "dislikes": 25
    },  
    "views": 305,
    "userId": 121
  },
]

Configurando o teste

describe('AppComponent', () => {
  const defaultConfig = {
    // Perceba que precisamos mudar o comportamento dos blocos defer 
    // para manual
    deferBlockBehavior: DeferBlockBehavior.Manual,
    providers: [
      {
        provide: PostService,
        useValue: {
          getPosts() {
            return of({
              limit: 10,
              posts: mockedPosts,
              skip: 0,
              total: mockedPosts.length
            } as GetPostsResponse)
          }
        }
      }
    ],
  }
// ...

Testando o cenário feliz — lista renderizada

  it('should display post list', async () => {

    const { fixture } = await render(AppComponent, {
        ...defaultConfig
    });

    // Obtemos referência ao nosso bloco @defer no template
    const deferBlockFixture = (await fixture.getDeferBlocks())[0];

    // Renderizamos o estado final
    await deferBlockFixture.render(DeferBlockState.Complete);    

    // Verificamos se os dois itens da lista estão renderizados
    expect(screen.getByText(mockedPosts[0].title)).toBeInTheDocument();
    expect(screen.getByText(mockedPosts[1].title)).toBeInTheDocument();
  });

Testando cenário de carregamento

  it('show display loading message while posts are still being fetched', async () => {

    const { fixture } = await render(AppComponent, {
        ...defaultConfig
    });

    const deferBlockFixture = (await fixture.getDeferBlocks())[0];

    await deferBlockFixture.render(DeferBlockState.Loading);    

    expect(screen.getByText(/Carregando posts.../i)).toBeInTheDocument();
  });

Testando o cenário infeliz — erro ao carregar posts

it('show display error message when fetching posts returns an error', async () => {

    // Sobrescrevemos o provider para simular
    // um erro vindo do PostService usando a função throwError do RxJS
    const { fixture } = await render(AppComponent, {
        ...defaultConfig,
        providers: [
          {
            provide: PostService,
            useValue: {
              getPosts(){
                return throwError(() => new Error('Error on loading posts'))
              }
            }
          }
        ]
    });

    const deferBlockFixture = (await fixture.getDeferBlocks())[0];

    await deferBlockFixture.render(DeferBlockState.Error);    
     
    const errorMsgRegex = /Erro ao tentar carregar posts.../i;

    expect(screen.getByText(errorMsgRegex)).toBeInTheDocument();
  });

Testando cenário de lista vazia

O nosso componente de lista utiliza o novo Control Flow do Angular, que foi um dos recursos introduzidos nas novas versões.

Aqui usamos a declaração @for para iterar sobre a lista de posts e renderizar cada um dos itens, o interessante é que podemos definir um bloco @empty, que renderiza um conteúdo quando a lista estiver vazia.

<ul>
  @for (item of posts(); track item) {
    <li data-test="post">
      <h2>{{item.title}}</h2>
      <p>{{item.body}}</p>
      <div>
        <span>Views: {{item.views}}</span>
        <span>Likes {{item.reactions.likes}}</span>
      </div>
    </li>
  } @empty {
    <p>Nenhum post para ser exibido</p>
  }
  </ul>

E para testar, só precisamos renderizar o estado final do bloco @defer:

  it('show display empty state message when fetching posts returns an empty list', async () => {

    const { fixture } = await render(AppComponent, {
        ...defaultConfig,
        // Sobrescrevemos o PostService para retornar uma lista vazia
        providers: [
          {
            provide: PostService,
            useValue: {
              getPosts(){
                return of([])
              }
            }
          }
        ]
    });

    const deferBlockFixture = (await fixture.getDeferBlocks())[0];

    // Renderizando o estado completo do bloco
    await deferBlockFixture.render(DeferBlockState.Complete);    
   
    const emptyStateMsg = /Nenhum post para ser exibido/i;

    expect(screen.getByText(emptyStateMsg)).toBeInTheDocument();
  });

Resultado dos nossos testes:

Conclusão

As Deferrable Views são um dos melhores recursos incluídos no Angular nos últimos tempos, com ela podemos adiar o carregamento de componentes, diretivas, pipes e qualquer CSS associado a eles.

E adiar o carregamento também significa que o Angular cria um bundle separado para esses elementos. A API é muito poderosa e recomendo dar uma olhada com mais profundidade, podemos ir muito além, só para mencionar, podemos adiar o carregamento de uma View até a iteração do usuário com a UI, por exemplo.

Os testes nesse recurso também traz desafios, mas com uma API simples a experiência de desenvolvimento dos testes se torna mais suave!

E ai, o que achou ?

Se quiser apoiar o meu trabalho reaja a esse post se te ajudei de alguma forma, compartilhe e me siga por aqui ou nas outras redes pra ficar por dentro dos próximos conteúdos.

Até logo, dev! 😉

Nesse post vamos entender como o Design Pattern Bridge, junto com alguns recursos do Angular pode tornar os componentes da nossa aplicação altamente reutilizáveis e flexíveis, diminuindo o acoplamento.

Antes de mais nada… o que é o Design Pattern Bridge?

Ele é um Design Pattern estrutural que permite separar abstração da implementação e evoluí-las de forma independente. A ideia é evitar o acoplamento direto entre abstrações e suas implementações.

Tomemos por exemplo um fluxo de escolha do método de pagamento:

interface PaymentMethod {
  process_payment(): void;
}

interface PaymentProcessor {
  process(): void;
}

class CardPaymentProcessor implements PaymentProcessor {
  process(): void {
   console.log('Prosseguindo para a inserção dos dados do cartão...');
  }
}

class PixPaymentProcessor implements PaymentProcessor {
  process(): void {
    console.log('Gerando o código pix para pagamento...');  
  }
}

class BoletoPaymentProcessor implements PaymentProcessor {
  process(): void {
    console.log('Gerando o boleto para pagamento...');
  }
}

class PaymentMethodImpl implements PaymentMethod {
  constructor(paymentProcessor: PaymentProcessor){}

  process_payment(){
    this.paymentProcessor.process();
  }
}


const cardPaymentMethod = new CardPaymentMethod();
const paymentMethodImpl = new PaymentMethodImpl(cardPaymentMethod);

paymentMethodImpl.process_payment();

Perceba que no exemplo acima, podemos trocar a implementação de PaymentMethodImpl sem mexer nas classes que implementa o PaymentProcessor e também passá-las para a implementação do método de pagamento, tornando nosso código bastante flexível a mudanças.

Agora vamos ver como implementar esse mesmo padrão no Angular, usando um fluxo de escolha de método de pagamento.

Para isso vamos precisar resolver os seguintes desafios:

• Precisamos de componentes que vão representar um PaymentProcessor para os diferentes métodos de pagamento (Boleto, Pix, etc.);
• Também vamos precisar de um componente orquestrador;
• O usuário deve ser capaz de escolher um método de pagamento e clicar em prosseguir;
• E o mais importante, precisamos que o componente orquestrador se comunique com os orquestrados.

Componente de método de pagamento

export interface PaymentProcessorComponent {
    METHOD: PaymentMethod
    process(): void;
    parentContainer: ControlContainer;

    get formGroup(): FormGroup;
}

@Component({
  selector: 'app-payment-method[pix]',
  standalone: true,
  imports: [ReactiveFormsModule],
  template: `
      <ng-container [formGroup]="formGroup">
        <label for="payment-method-pix">
            <input type="radio"
                value="pix"
                name="payment_method"
                id="payment-method-pix"
                formControlName="payment_method">
            <ng-content />
        </label>
    </ng-container>
  `,
})
export class PixMethodPaymentComponent implements PaymentProcessorComponent {

  METHOD: PaymentMethod = 'pix';
  parentContainer = inject(ControlContainer);

  get formGroup() {
    return this.parentContainer.control as FormGroup;
  }

  public process(): void {
    console.log('Gerando o código pix para pagamento...');
  }
}

Todos os componentes que representam um método de pagamento devem implementar a interface PaymentProcessorComponent, essa interface força esses componentes a terem um contrato único:

• Um METHOD, indicando qual o método de pagamento;
• Uma propriedade parentContainer para acessar o formulário que estará dentro do contexto do elemento pai onde esse componente for inserido;
• Um método get que retorna a referência do formulário que está dentro do componente pai;
• E por último, o método para processar o pagamento desse método de pagamento em si

Componente orquestrador

// ... importações omitidas

export type PaymentMethod = ['cartao', 'pix', 'boleto'][number]
export const PAYMENT_METHOD = new InjectionToken<PaymentProcessorComponent>('PAYMENT_METHOD')

@Component({
  selector: 'app-payment-wrapper',
  standalone: true,
  imports: [ReactiveFormsModule],
  template: `
    <div>
      <h2>Método de pagamento</h2>
      <h6>Selecione um método de pagamento para prosseguir</h6>
      
      <ng-content></ng-content>
      <button (click)="process_choice()">Prosseguir</button>
    </div>
  `,
  styleUrl: './payment-wrapper.component.scss',
})
export class PaymentWrapperComponent {
  formGroupDirective = inject(FormGroupDirective);
  paymentMethods = contentChildren(PAYMENT_METHOD);

  process_choice() {

    if(!this.paymentMethods().length) {
      console.log('Nenhum método de pagamento encontrado');
      return;
    }

    if(this.formGroupDirective){
      const selectedPaymentMethod = this.formGroupDirective?.control.get('payment_method')?.value
      const method = this.paymentMethods().find(paymentOption => paymentOption.METHOD == selectedPaymentMethod);
      if(!method){
        console.log('Nenhuma opção de pagamento selecionada!')
        return;
      }
      method.process();
    }
  }
}

Esse componente será responsável por descobrir a forma de pagamento escolhida pelo usuário e chamar o método correspondente. Ele fará isso obtendo a lista dos componentes projetados que implementam a interface associada ao injection token PAYMENT_METHOD quando o botão Prosseguir for clicado.

Para ver isso em ação vamos declarar o nosso template no componente app-root:

import { Component, inject } from '@angular/core';
import { FormBuilder, FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { CardPaymentMethodComponent } from './payments-method/card/card.component';
import { PixMethodPaymentComponent } from "./payments-method/pix/pix.component";
import { PaymentMethod, PaymentWrapperComponent } from './payment-options/payment-wrapper/payment-wrapper.component';
import { BoletoPaymentMethodComponent } from './payments-method/boleto/boleto.component';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    ReactiveFormsModule,
    PaymentWrapperComponent,
    PixMethodPaymentComponent,
  ],
  template: `
    <app-payment-wrapper [formGroup]="form">
      <app-payment-method pix>PIX</app-payment-method>
    </app-payment-wrapper>
  `,
  styleUrl: './app.component.scss'
})
export class AppComponent {
  form: FormGroup;
  formBuilder = inject(FormBuilder);

  ngOnInit(): void {
    this.form = this.formBuilder.group({
      payment_method: new FormControl<PaymentMethod>('pix'),
    })
  }

}

Ao executar a sua aplicação você verá um formulário customizado, com a opção de PIX pré-selecionada:

Porém, ao clicar em Prosseguir a mensagem “Nenhum método de pagamento encontrado” aparecerá no console do navegador.

Mas por que isso? Como que o componente pai vai obter os componentes filhos sem referenciar as suas respectivas implementações, consequentemente criando acoplamento?

O segredo está relacionado a como a Injeção de Dependências funciona no Angular, mais especificamente ao mapeamento de dependências. Por exemplo, é comum declararmos um serviço como dependência de componentes para que o sistema de injeção de dependências do Angular forneça uma instância dele automaticamente.

@Component({
  selector: 'app-payment-method[pix]',
  standalone: true,
  imports: [ReactiveFormsModule],
  template: `
    <p>pix</p>
  `,
  providers: [PaymentService]
})
export class PixMethodPaymentComponent {}

O Angular possui configuradores de providers: useClass, useValue, useFactory e useExisting. Com eles podemos fazer o mapeamento das dependências do nosso componente, por exemplo:

@Component({
  selector: 'app-payment-method[pix]',
  standalone: true,
  imports: [ReactiveFormsModule],
  template: `
    <p>pix</p>
  `,
  providers: [
     { provide: PaymentService, useValue: 'This is a replacement'}
  ]
})
export class PixMethodPaymentComponent {}

Dessa forma, toda vez que for solicitado uma instância do serviço PaymentService, será fornecido o valor definido em useValue. Porém, esses configurares de providers não se limita a valores estáticos, e é aí que está o a dica para resolver o nosso problema anterior, associando o nosso componente ao Injection token PAYMENT_METHOD:

@Component({
  selector: 'app-payment-method[pix]',
  standalone: true,
  imports: [ReactiveFormsModule],
  template: `
    <p>pix</p>
  `,
  providers: [
     { provide: PAYMENT_METHOD, useExisting: PixMethodPaymentComponent }
  ]
})
export class PixMethodPaymentComponent {}

Agora, ao executar a nossa aplicação novamente, tudo funcionará como o esperado, veremos a mensagem “Gerando código pix para pagamento…” no console do browser:

Com isso, podemos incluir, remover ou modificar diversos outros componentes que implementam outras opções de pagamentos, como pagamento por cartão, boleto… e desde que eles sigam a interface tudo funcionará bem, como no exemplo a seguir:

Se quisermos flexibilizar ainda mais, podemos criar uma abstração para o componente orquestrador app-payment-wrapper, assim poderíamos trocá-lo por um componente concreto, que implemente a abstração, e ele continuará funcionando sem precisarmos mexer nos componentes filhos e vice-versa.

Conclusão

O time do Design Pattern Bridge, ControlContainer, Projeção de conteúdo e Injeção de Dependências no Angular é uma combinação poderosíssima, com ela podemos criar composições de componentes extremamente flexíveis, fácil de modificar e de testar. Com esse Pattern diminuímos o acoplamento entre os componentes, fazendo com que eles só precisem obedecer aos contratos estabelecidos pelas suas respectivas abstrações.

Até logo, dev! 😉

Antes de adentrarmos na aplicação prática dos conceitos, precisamos entender do que se trata a arquitetura hexagonal, que em resumo:

É um padrão de design de software que busca promover a separação clara entre a lógica de negócio e os aspectos externos da aplicação.

Ao usar essa abordagem usamos alguns componentes fundamentais que promovem o objetivo de tornar a lógica de negócio independe de tecnologia, são eles:

• Camada de aplicação/domínio: Aqui reside a lógica de negócio com as regras mais fundamentais do sistema, que é independente de tecnologia e do mundo exterior à aplicação.
• Portas: São interfaces que definem as portas de entrada e saída para o núcleo mais interno da aplicação, ou seja, o domínio. Elas são usadas pelo domínio da aplicação para interagir com o mundo externo e vice-versa.
• Adaptadores: São implementações das portas, eles traduzem as chamadas do domínio à recursos externos e vice-versa.
• Drivers: Os drivers são os atores primários e externos, que interagem com a camada de aplicação, são por exemplo, aplicações SPAs, Filas de mensagem, casos de teste, aplicativos e etc.
• Driven Actors: Os driven actors são os atores, também externos, com quem a camada de aplicação vai interagir, como por exemplo, um banco de dados, uma aplicação de terceiros, uma fila de mensagem, um servidor de e-mail e etc.

Entendido o conceito, é hora de colocar a mão na massa.

Vamos criar uma pequena aplicação Angular que lista alguns produtos e permite que sejam adicionados ao carrinho de compras, vamos distribuir os componentes, diretivas e serviços de forma que a arquitetura hexagonal fique gritante no nosso código e depois vamos discutir o que fizemos.

Camada de aplicação

Na arquitetura hexagonal, essa é a camada mais interna, onde fica as regras de negócio, é a camada de domínio, com toda lógica que é independente do framework, aqui também fica os nossos “use cases”.

Nossa aplicação possui duas entidades de domínios a princípio, uma de Produto e outra de Carrinho, além de dois respectivos casos de uso, um para listar produtos e outro para adicionar um produto ao carrinho.

Entidade de Carrinho

import { Product } from './product';

export interface CartProduct { product: Product; amountOnCart: number; }

export class Cart {

    constructor(public cartList: CartProduct[], private _cartSubTotal = 0) { }

    get subtotal() {
        return this._cartSubTotal;
    }

    set subtotal(total: number) {
        this._cartSubTotal = total;
    }

    addToCart(productToAddOnCart: Product) {

        const productOnCart = this.cartList.find(item => item.product.id == productToAddOnCart.id) ?? null;

        const hasStock = productToAddOnCart.isAvailable();
        console.log(hasStock)

        if (!productToAddOnCart || !hasStock) return null;

        let product: CartProduct | null = null

        if (productOnCart) {
            productOnCart.amountOnCart = productOnCart.amountOnCart + 1;
            product = productOnCart;
        }

        if (!productOnCart) {
            const newCartProduct: CartProduct = { product: productToAddOnCart, amountOnCart: 1 }
            this.cartList.push(newCartProduct);
            product = newCartProduct;
        }

        this.subtotal = this.calcSubtotal();

        return product;
    }

    private calcSubtotal() {
        const total = this.cartList.reduce((acc, curr) => {
            return acc + (curr.amountOnCart * curr.product.price)
        }, this._cartSubTotal)

        return total;
    }


    getCartProduct(productId: number) {
        const targetProduct = this.cartList.find((item) => item.product.id === productId);

        if (!targetProduct) return null;

        return targetProduct;
    }
}

Essa entidade contém toda a regra de negócio para que um produto seja adicionado ao carrinho, validando se o produto está em estoque, incrementando a quantidade do produto caso ele já esteja no carrinho, além de manter subtotal atualizado.

Podemos incluir outros métodos como para remover um produto do carrinho, esvaziar o carrinho… aqui é a camada onde definimos as regras que qualquer um interessado em interagir com essa entidade precisará seguir.

Entidade de Produto

export interface Dimensions { width: number; height: number; depth: number; }

export interface Review {
  rating: number;
  comment: string;
  date: string;
  reviewerName: string;
  reviewerEmail: string;
}

export interface Meta {
  createdAt: string;
  updatedAt: string;
  barcode: string;
  qrCode: string;
}

export class Product {

  constructor(  
    private _id: number,
    private _title: string,
    private _price: number,
    private _stock: number,
    private _description?: string,
    private _thumbnail?: string,
  ) {}

  public isAvailable(): boolean {
    return this._stock !== undefined && this._stock > 0;
  }

  get id(): number {
    return this._id;
  }

  get title(): string {
    return this._title;
  }

  get price(): number {
    return this._price;
  }

  get description(): string | undefined {
    return this._description;
  }

  get stock(): number {
    return this._stock;
  }

  get thumbnail(): string | undefined {
    return this._thumbnail;
  }

  set id(id: number) {
    this._id = id;
  }

  set title(title: string) {
    this._title = title;
  }

  set thumbnail(thumbnail: string) {
    this._thumbnail = thumbnail;
  }


  set price(price: number) {
    if (this._price < 0) {
      throw new Error('Price cannot be negative');
    }
    this._price = price;
  }

  set description(description: string) {
    this._description = description;
  }

  set stock(stock: number) {
    if (stock < 0) {
      throw new Error('Stock cannot be negative');
    }
    this._stock = stock;
  }
}    

Nossa entidade de produtos é bem simples, apenas com os métodos getters/setters que encapsulam a definição e recuperação de atributos da nossa classe.

Portas

As portas são interfaces que vão definir como o mundo externo interage com o a camada de domínio da aplicação e como essa camada interage com o mundo externo. Os adaptadores irão implementar essas portas, dessa forma a camada de domínio fica totalmente agnóstica, e não importa quem está se comunicando com o núcleo da aplicação e vice versa, desde que respeite essas portas.

A principio, vamos definir duas delas para cada entidade de domínio, uma de entrada e uma de saída, a interface de entrada será a porta por onde o mundo externo irá interagir com a camada de domínio e a interface de saída será a porta por onde a camada de domínio interagirá com o mundo externo:

No contexto do Angular, podemos aproveitar o seu poderoso sistema de injeção de dependências combinado com InjectionTokens:

Produtos

Porta de entrada

import { InjectionToken } from "@angular/core";
import { Product } from "@application/domain/entities/product";
import { Observable } from 'rxjs';

export interface ProductList {
    total: number
    skip: number
    limit: number
    products: Product[]
}

export interface IproductInputPort {
    getProducts(): Observable<ProductList>;
    nextPage(): void;
    prevPage(): void;
}

export const PRODUCT_INPUT_PORT = new InjectionToken<IproductInputPort>('PRODUCT_INPUT_PORT')

Porta de saída

import { InjectionToken } from "@angular/core";
import { Observable } from "rxjs";
import { ProductList } from "./input.port";

export interface IproductOutputPort {
    getProducts(limit: number, skip: number): Observable<ProductList>;
}

export const PRODUCT_OUTPUT_PORT = new InjectionToken<IproductOutputPort>('PRODUCT_OUTPUT_PORT')

Carrinho

Porta de entrada

import { InjectionToken } from "@angular/core"
import { CartProduct } from "@application/domain/entities/cart"
import { Product } from "@application/domain/entities/product"
import { Observable } from "rxjs"

export interface ICartInputPort {
    addToCart(cart: Product): Observable<CartProduct | null>
}

export const CART_INPUT_PORT = new InjectionToken<ICartInputPort>('CART_INPUT_PORT')

Porta de saída

import { InjectionToken } from "@angular/core"
import { Cart, CartProduct } from "@application/domain/entities/cart"
import { Product } from "@application/domain/entities/product"
import { Observable } from "rxjs"

export interface ICartOutputPort {
    persistCart(cart: Cart): Observable<Cart | null>
    getPersistedCart(): Observable<Cart | null>
    getCartItem(productId: number): Observable<CartProduct | null>
    getCartItemFromServer(productId: number): Observable<Product | null>
}
export const CART_OUTPUT_PORT = new InjectionToken<ICartOutputPort>('CART_OUTPUT_PORT')

Adapters

Agora vamos definir nossos adaptadores, que vão ser as implementações concretas das nossas portas de entrada e saída para a camada de aplicação.

Eles podem ser serviços comuns do Angular.

Produtos

Adaptador de entrada

import { Injectable, Provider, inject } from "@angular/core";
import { Product } from "@application/domain/entities/product";
import { AddToCartService } from "@application/domain/use_cases/AddToCart";
import { CART_INPUT_PORT, ICartInputPort } from "@application/ports/cart/input";
import { CART_OUTPUT_PORT } from "@application/ports/cart/output";

@Injectable({ providedIn: 'root' })
export class CartInputAdapter implements ICartInputPort {

    private cartOutPort = inject(CART_OUTPUT_PORT);
    private cartApplication = new AddToCartService(this.cartOutPort);

    addToCart(product: Product) {
        const productAdded = this.cartApplication.addToCart(product);
        return productAdded;
    }
}

export function provideCartInputAdapter(): Provider {
    return {
        provide: CART_INPUT_PORT,
        useClass: CartInputAdapter,
    }
}

Adaptador de saída

import { HttpClient } from "@angular/common/http";
import { Injectable, inject } from "@angular/core";
import { Cart } from "@application/domain/entities/cart";
import { Product } from "@application/domain/entities/product";
import { ICartOutputPort } from "@application/ports/cart/output";
import { API_URL } from "@resources/api";
import { of } from "rxjs";

@Injectable({ providedIn: 'root' })
export class CartOutputAdapter implements ICartOutputPort {
    private httpClient = inject(HttpClient)
    private apiEndpoint = inject(API_URL)

    persistCart(cart: Cart) {
        sessionStorage.setItem('cart', JSON.stringify(cart));

        const stored = sessionStorage.getItem('cart');

        if (!stored) return of(null);

        return of(JSON.parse(stored) as Cart);
    }

    getPersistedCart() {
        const cart = sessionStorage.getItem('cart');

        if (!cart) return of(null);

        const parsed = JSON.parse(cart) as Cart;

        return of(parsed);
    }

    getProductFromCart(productId: number) {
        const cart = sessionStorage.getItem('cart');

        if (!cart) return of(null);

        const product = (JSON.parse(cart) as Cart).getCartProduct(productId);

        return of(product)
    }

    getProductFromServer(productId: number) {
        return this.httpClient.get<Product | null>(`${this.apiEndpoint}/${productId}`);
    }
}

Carrinho

Adaptador de entrada

import { Injectable, Provider, inject } from "@angular/core";
import { Product } from "@application/domain/entities/product";
import { AddToCartService } from "@application/domain/use_cases/AddToCart";
import { CART_INPUT_PORT, ICartInputPort } from "@application/ports/cart/input";
import { CART_OUTPUT_PORT } from "@application/ports/cart/output";

@Injectable({ providedIn: 'root' })
export class CartInputAdapter implements ICartInputPort {

    private cartOutPort = inject(CART_OUTPUT_PORT);
    private cartApplication = new AddToCartService(this.cartOutPort);

    addToCart(product: Product) {
        const productAdded = this.cartApplication.addToCart(product);
        return productAdded;
    }
}

export function provideCartInputAdapter(): Provider {
    return {
        provide: CART_INPUT_PORT,
        useClass: CartInputAdapter,
    }
}

Adaptador de saída

import { HttpClient } from "@angular/common/http";
import { Injectable, inject } from "@angular/core";
import { Cart } from "@application/domain/entities/cart";
import { Product } from "@application/domain/entities/product";
import { ICartOutputPort } from "@application/ports/cart/output";
import { API_URL } from "@resources/api";
import { of } from "rxjs";

@Injectable({ providedIn: 'root' })
export class CartOutputAdapter implements ICartOutputPort {
    private httpClient = inject(HttpClient)
    private apiEndpoint = inject(API_URL)

    persistCart(cart: Cart) {
        sessionStorage.setItem('cart', JSON.stringify(cart));

        const stored = sessionStorage.getItem('cart');

        if (!stored) return of(null);

        return of(JSON.parse(stored) as Cart);
    }

    getPersistedCart() {
        const cart = sessionStorage.getItem('cart');

        if (!cart) return of(null);

        const parsed = JSON.parse(cart) as Cart;

        return of(parsed);
    }

    getCartItem(productId: number) {
        const cart = sessionStorage.getItem('cart');

        if (!cart) return of(null);

        const product = (JSON.parse(cart) as Cart).getCartProduct(productId);

        return of(product)
    }

    getCartItemFromServer(productId: number) {
        return this.httpClient.get<Product | null>(`${this.apiEndpoint}/${productId}`);
    }
}

Se quisermos garantir ainda mais flexibilidade também podemos defini-los como sem o uso do decorator @Injectable e usar os providers useValue ou useFactory do Angular para prover uma instancia dessa classe como dependência quando solicitada.

Além disso, perceba que criamos portas de entrada e saída com interfaces distintas, porém, dependendo do cenário, poderíamos usar a mesma para ambas e diminuir a quantidade de código. No entanto, a ideia aqui é mostrar a flexibilidade que segregar essas interfaces pode trazer.

E e a propósito, você deve ter percebido que a interface ICartOutputPort possui mais assinaturas de métodos, dependendo do tamanho da interface, é interessante até mesmo segregar em portas menores e mais específicas

export interface ICartOutputPort {
    persistCart(cart: Cart): Observable<Cart | null>
    getPersistedCart(): Observable<Cart | null>
    getCartItem(productId: number): Observable<CartProduct | null>
    getCartItemFromServer(productId: number): Observable<Product | null>
}

Drivers e Driven Actors

Drivers

No contexto da nossa aplicação, os drivers serão componentes, diretivas, pipes e outros serviços, ou seja, qualquer ator que precisar interagir com a camada de aplicação mais interna.

Como o componente e a diretiva a seguir:

import { CommonModule } from "@angular/common";
import { Component, inject } from "@angular/core";
import { PRODUCT_INPUT_PORT } from "@application/ports/products/input.port";
import { AddToCartDirective } from "@drivers/directives/addToCart.directive";
import { provideCartAdapters } from "@resources/adapters/cart/cart.providers";
import { provideProductsAdapters } from "@resources/adapters/products/products.providers";
import { provideApi } from "@resources/api";

@Component({
    selector: 'app-products',
    templateUrl: './products.component.html',
    styleUrl: './products.component.scss',
    standalone: true,
    imports: [AddToCartDirective, CommonModule],
    providers: [
        provideApi('product'),
        ...provideCartAdapters(),
        ...provideProductsAdapters(),
    ],
    template: `
    <div class="container">
    <h1>Products</h1>
    <h4>Choice your product today!</h4>

    <div class="listControl">
        <button (click)="productService.prevPage()"
            class="prev">Previous page</button>
        <button (click)="productService.nextPage()"
            class="next">Next page</button>
    </div>

    <ul>
        @for (item of (products | async)?.products; track item.id) {
        <li [attr.data-id]="item.id">
            <div>
                <img [src]="item.thumbnail"
                    [alt]="item.description">
                <div>
                    <h2>{{item.title}}</h2>
                    <p>{{item.description}}</p>
                    <h1>{{item.price | currency }}</h1>
                </div>
                <button class="addToCart"
                    addToCart
                    [product]="item">Add to Cart</button>
            </div>
        </li>}@empty {
        <div class="empty">Nada por aqui!</div>
        }
    </ul>
</div>
    `,
})
export class HomeProductComponent {
    productService = inject(PRODUCT_INPUT_PORT);
    products = this.productService.getProducts();   
}

Aqui o nosso componente faz uso do conceito de inversão de dependência, ele não ideia de quem é esse serviço de produto, estamos dizendo a ele quais são através dos providers:

import { Provider } from "@angular/core";
import { PRODUCT_INPUT_PORT } from "@application/ports/products/input.port";
import { PRODUCT_OUTPUT_PORT } from "@application/ports/products/output.port";
import { API_URL } from "@resources/api";
import { ProductsInputAdapter } from "./products.input.adapter";
import { ProductsOutPutAdapter } from "./products.output.adapter";

export function provideProductsInputAdapter(): Provider {
    return {
        provide: PRODUCT_INPUT_PORT,
        useClass: ProductsInputAdapter,
    }
}

export function provideProductsOutputAdapter(): Provider {
    return {
        provide: PRODUCT_OUTPUT_PORT,
        useClass: ProductsOutPutAdapter,
        deps: [API_URL]
    }
}


export function provideProductsAdapters(): Provider[] {
    return [
        provideProductsInputAdapter(),
        provideProductsOutputAdapter(),
    ];
}

O mesmo se aplica para a diretiva AddToCartDirective, que encapsula funcionalidade de adicionar um produto ao carrinho de compras:

import { DestroyRef, Directive, inject, input } from "@angular/core";
import { takeUntilDestroyed } from "@angular/core/rxjs-interop";
import { Product } from "@application/domain/entities/product";
import { CART_INPUT_PORT } from "@application/ports/cart/input";

@Directive({
    selector: '[addToCart]',
    standalone: true,
    host: {
        '(click)': 'add()'
    }
})
export class AddToCartDirective {
    cartService = inject(CART_INPUT_PORT);
    product = input<Product>({} as Product);
    destroyRef = inject(DestroyRef);

    add() {
        this.cartService.addToCart(this.product()).pipe(takeUntilDestroyed(this.destroyRef)).subscribe()
    }
}

Driven Actors

Já os Driven Actors, será qualquer recurso externo a nossa aplicação, por exemplo, o serviço CartOutputAdapter interage com a sessionStorage do navegador, o serviço ProductOutputAdapter interage com uma API externa para buscar os produtos.

Esses são atores com quem a camada de aplicação irá interagir, até mesmo o gerenciamento de estado da aplicação poderia ser um Driven Actor, o benefício disso a possiblidade de fazer modificações nessa camada sem afetar o funcionamento da aplicação, desde que as interfaces das portas sejam respeitadas.

Aplicação

Conclusão

Nesse post procuramos explorar o conceito da Arquitetura Hexagonal no contexto do Angular, percebe-se que é perfeitamente possível aplicá-lo, aproveitando os benefícios de desacoplamento, facilidade de manutenção e principalmente (o que eu gostaria de mostrar numa próxima oportunidade, inclusive) os testes, já que podemos trocar facilmente as dependências por mocks, stubs e etc. Além de isolarmos as regras da nossa aplicação, tornando elas mais agnósticas ao framework e bibliotecas.

No entanto, é importante observar que utilizar essa abordagem traz uma grau de complexidade para a aplicação, um que talvez a sua aplicação não precise. O Angular é um framework poderoso, muitos dos conceitos que aproveitamos aqui já são nativos dele, como os InjectionsTokens e os providers com inversão de dependências.

No fim, essa abordagem pode ser ótima na medida que você entender a maturidade da sua aplicação, além de analisar se os conceitos de “Ports and Adapters” vai mais ajudar do que atrapalhar o seu projeto. A maturidade e conhecimento do time também é importante, analise os trade-offs com sabedoria.

Espero que tenham gostado, até a próxima!

Link do projeto no github: https://github.com/danilolmc/hexagonal-arch-angular

Vamos dividir esse objetivo em algumas tarefas:

• Vamos configurar o repositório da nossa aplicação e criar um pipeline com o Github Actions
• Além disso, vamos configurar um provedor de identidade usando AWS IAM para uso no nosso pipeline, caso não tenha uma conta você pode aproveitar o nível gratuito criando uma conta por aqui;
• Também vamos usar o CloudFormation e o S3 para automatizar a implantação e orquestração da nossa aplicação microfrontend.

O código da final do projeto que vamos deployar na AWS pode ser encontrado nesse repositório.

Overview da a aplicação

Nossa aplicação se trata de um e-commerce com funcionalidades de listagem de produtos e carrinho, que é composta por uma aplicação shell e dois microfrontends, e usa a estratégia de integração por rotas:

• apps/shopping-shell: é a aplicação container, responsável por orquestrar os dois microfrontends, ela que decide qual aplicação que será carregada baseado nas rotas;
• apps/cart: é a aplicação responsável por gerenciar o carrinho de compras do usuário, com funcionalidades de adicionar mais itens e removê-los, calcular subtotal da compra e esvaziar carrinho;
• apps/shop: aplicação principal, responsável por listar os produtos partir desta fake API gratuita, além de permitir que os produtos sejam adicionados ao carrinho.

Além disso, nossa aplicação faz uso de duas bibliotecas compartilhadas existentes no nosso monorepo:

• libs/shared/api: biblioteca responsável por abstrair a comunicação com a API de produtos;
• libs/shared/state: biblioteca responsável por gerenciar o estado global da nossa aplicação.

Criando os scripts de deploy

Agora, vamos criar os scripts de implantação para cada uma das nossas aplicações, eles nos ajudarão a separar como e onde cada aplicação será implantada na AWS. A criação do nossos scripts envolverá dois passos:

1. Criar um shell script reutilizável entre as nossas aplicações, ele será responsável por se comunicar com o CloudFormation e o S3
2. Em cada aplicação dentro do monorepo vamos configurar um script que será responsável por chamar o shell script reutilizável passando os parâmetro necessários para implantar cada aplicação.

Para visualizar o código final e ver a estrutura da aplicação clone o repositório nesse link e siga as instruções do README do projeto para instalação das dependências.

Criando o script reutilizável

Na raiz do nosso projeto criamos o diretório scripts/deploy.sh, com a estrutura explicada em detalhes abaixo:

#!/bin/bash

# definimos os parâmetros esperados pelo script para provisionar 
# os recursos e implantar o microfrontend
# URL do template do CloudFormation
TEMPLATE_URL=$1
# Nome do bucket do microfrontend
BUCKET_NAME=$2
# Nome do microfrontend
APP_NAME=$3
# Nome da stack do CloudFormation
STACK_NAME=$4
# URL do app shell implantad (nesse contexto será uma URL HTTP no padrão do S3)
SHELL_APP=$5
# verificamos se o bucket não existe
if ! aws s3api head-bucket --bucket $BUCKET_NAME; then
    echo "Validating Template..."
    
    # valida o template do cloudformation antes de fazer o deploy dele
    if aws cloudformation validate-template --template-body file://$TEMPLATE_URL; then 
        echo;
        echo "Template validate successfully"
        echo;
        echo "Bucket $BUCKET_NAME does not exist."
        echo;
        echo "Creating bucket $BUCKET_NAME..."
        # se o template for válido, faz o deploy dele para provisionar 
        # o bucket do microfrontend
        if aws cloudformation deploy \
            --template-file "$TEMPLATE_URL" \
            --stack-name "$STACK_NAME" \
            --parameter-overrides BucketName=$BUCKET_NAME ShellAppBucketUrl=$SHELL_APP \
            --capabilities "CAPABILITY_IAM"
        then
            echo "Stack created successfully"
        else
            echo "Failed to create stack"
            exit 1
        fi
    else 
        echo "Invalid template"
        exit 1
    fi
fi

echo Deploying $APP_NAME app...
# se tudo correr bem com o provisionamento dos recursos, movemos os arquivos
# do microfrontend para o bucket S3 que acabou de ser criado pela stack 
# do CloudFormation
if ! aws s3 sync dist/apps/$APP_NAME s3://$BUCKET_NAME --delete; then
    echo Error on move $APP_NAME app files to S3
    exit 1;
fi
echo;
echo $APP_NAME app deployed successfully

Com esse script temos uma sequência de passos padrão que será reaproveitada por qualquer microfrontend no nosso monorepo, o próximo passo será configurar nossos MFE’s para que façam uso desse script.

Definindo os scripts de cada aplicação

O Nx nos permite adicionar scripts customizados para cada uma das nossas aplicações dentro do monorepo, modificando o arquivo project.json vamos criar um script de deploy específico a cada aplicação.

Esse script poderá ser executado através dos comandos padrões do Nx, como:

nx affected -t=deploy e nx run shop:deploy

Vamos exemplificar a definindo o script do microfrontend shop…

"deploy": {
  "builder": "nx:run-commands",
  "command": "bash -c 'chmod +x ./scripts/deploy.sh; ./scripts/deploy.sh apps/shop/template.yaml $S3_BUCKET_APP_SHOP shop shop-app-stack $APP_SHELL_URL'",
  "parallel": false
}

Observe que esse script de deploy chama nosso script reutilizável passando alguns parâmetros:

• apps/shop/template.yaml: o diretório do template do CloudFormation respectivo a aplicação shop;
• $S3_BUCKET_APP_SHOP: é uma referência a uma variável de ambiente, nela precisaremos definir o nome do bucket S3 onde será armazenado os arquivos desse microfrontend depois de compilados pelo Web, definiremos como app-shop.
• shop: é apenas o nome da aplicação a ser usado pelo script reutilizável para identificar melhor qual aplicação está sendo implantada.
• shop-app-stack: nome dado a stack do CloudFormation da aplicação;
• $APP_SHELL_URL: outra referência á uma variável de ambiente, nela precisaremos definir a url http do bucket S3 onde ficará armazenado a aplicação shell, que será
  https://app-shopping-shell.s3.amazonaws.com.

Essa configuração será idêntica para as outras duas aplicações, shopping-shell e cart. O que irá mudar é apenas os parâmetros passados, dê uma olhada no repositório do projeto com o código final para visualizar como está configurado para os outros dois microfrontends.

Preparando o ambiente

Configurando o pipeline do GitHub Actions

Vamos entender nosso workflow que automatizará a implantação das nossas aplicações na AWS.

Precisamos criar um workflow no diretório .github/workflows/deploy.yaml com a seguinte estrutura:

name: Build and Deploy to Amazon S3
on:
  push:
    branches:
      - main
jobs:
  build_and_deploy: 
    runs-on: ubuntu-latest
    # Faremos uso de OICD para permitir
    # que nosso pipeline gerencie recursos da AWS sem precisar de
    # pares de chaves
    permissions:
      contents: read
      id-token: write
    env:
      APP_SHELL_URL: ${{ secrets.APP_SHELL_URL }}
      APP_SHOP_URL: ${{ secrets.APP_SHOP_URL }}
      APP_CART_URL: ${{ secrets.APP_CART_URL }}
      S3_BUCKET_APP_SHELL: ${{ secrets.S3_BUCKET_APP_SHELL }}
      S3_BUCKET_APP_SHOP: ${{ secrets.S3_BUCKET_APP_SHOP }}
      S3_BUCKET_APP_CART: ${{ secrets.S3_BUCKET_APP_CART }}
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      # esse passo vai nos ajudar a definir qual o último commit e branch base
      # para que o comando nx affected possa identificar os projetos afetados 
      # pela mudança do commit
      - name: Set base and head SHAs
        uses: nrwl/nx-set-shas@v3
      - name: Install dependencies
        run: npm ci
      # buildando somente os projetos e bibliotecas que foram modificados
      - name: Build Affected Projects
        run: npx nx affected --target=build --base=$NX_BASE --head=$NX_HEAD --configuration=production
      - name: Run Tests for Affected Projects
        run: npm run test:all
      # aqui nosso pipeline assume temporariamente as permissões necessárias
      # para se comunicar com a AWS
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-region: ${{ secrets.AWS_REGION }}
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          role-session-name: ${{ secrets.AWS_ROLE_SESSION_NAME }}
      # e aqui enfim, deployamos as aplicações/bibliotecas afetadas 
      # pelo commit atual
      - name: Deploy Affected Projects to S3
        run: npx nx affected --target=deploy --base=$NX_BASE --head=$NX_HEAD

Configurando o provedor de identidade no IAM

Apesar de ser possível fazer o uso de secret access keys no nosso workflow, vamos configurar um provedor de identidade com o AWS IAM para que nosso pipeline assuma permissões temporariamente, suficientes para prover os recursos através das stacks do CloudFormation e para mover os arquivos compilados para os respectivos buckets no S3.

Para configurá-lo, siga esse artigo.

Para fins de teste, no passo de adicionar permissões ao provedor de identidade indicado no artigo, adicione as permissões AmazonS3FullAccess e AWSCloudFormationFullAccess.

Num cenário real de implantação você deve configurar essas permissões seguindo o princípio do menor privilégio.

Definindo as variáveis de ambiente

Nosso projeto utiliza algumas variáveis de ambiente, precisamos defini-las como secrets do repositório.

Para isso, com o repositório criado, navegue até Settings > Security >Actions e crie os secrets de acordo com os exemplos abaixo:

APP_CART_URL=https://app-cart.s3.amazonaws.com,
APP_SHOP_URL=https://app-shop.s3.amazonaws.com
APP_SHELL_URL=https://app-shopping-shell.s3.amazonaws.com
AWS_REGION=us-east-1
AWS_ROLE_SESSION_NAME=github_workflow
# Aqui você substituirá o valor da variável pelo ARN da role que foi 
# criado anteriormente, quando configuramos o provedor de identidade no IAM
AWS_ROLE_TO_ASSUME=arn:aws:iam::123456789012:role/NomeDaSuaRole
S3_BUCKET_APP_CART=app-cart
S3_BUCKET_APP_SHELL=app-shopping-shell
S3_BUCKET_APP_SHOP=app-shop

Implantando a aplicação

Por fim, só precisamos fazer o push do projeto para branch main do nosso repositório, se tudo estiver configurado corretamente a nossa aplicação deve ser implantada com sucesso.

E então você verá os buckets criados na sua conta AWS.

Bem como as stacks que os criaram executadas pelo CloudFormation.

Assim, temos um fluxo de implantação totalmente automatizado, que realizará o deploy somente das aplicações que forem afetadas pelas alterações contidas no commit mais recente.

E para acessar nossa aplicação você pode usar o endereço do objeto index.html armazenado no bucket S3 app-shopping-shell!

E então interagir com a aplicação!

Conclusão

Neste artigo, exploramos como implementar uma aplicação microfrontend utilizando o Nx para gerenciamento de monorepos e a estratégia de Module Federation do Webpack. Além disso, detalhamos como usar o GitHub Actions para automatizar o provisionamento de recursos por meio da Infraestrutura como Código, utilizando o CloudFormation.

É importante lembrar que há outras estratégias para a aplicação shell orquestrar os microfrontends, como a recuperação via requisição HTTP. Também é possível configurar uma distribuição com o CloudFront para evitar o uso direto das URLs do Bucket ao acessar a aplicação.

Mas esses são tópicos que podemos explorar em detalhes em um próximo artigo.

Fique a vontade para dar uma olhada no código final do projeto, segue o link do repositório: https://github.com/danilolmc/ecommerce-mfe

Enfim, é isso, espero que tenha curtido o artigo!

Até a próxima! 😉

O mundo do desenvolvimento Front-end Web é marcado pela diversidade de ferramentas para a construção de aplicações baseadas em componentes. Essa variedade introduz vários desafios, especialmente porque cada ferramenta apresenta suas próprias abordagens em relação a conceitos fundamentais como componentes, gerenciamento de estado e etc.

Além disso, o ecossistema único de cada uma dessas ferramentas complica a reutilização do código desenvolvido, criando barreiras no aproveitamento de soluções entre projetos.

No entanto, felizmente, existe uma estratégia para tornar o desenvolvimento de aplicações web mais agnóstico em termos de ferramentas e favorecer o reaproveitamento de código. Essa solução é conhecida como Web Components.

De acordo com o site MDN, Web Components são…”

um conjunto de diferentes tecnologias que permitem criar elementos personalizados reutilizáveis — com sua funcionalidade encapsulada, separada do resto do seu código — e utilizá-los em suas aplicações web.

Ou seja, podemos utilizar web components para encapsular nosso código JavaScript na forma de componentes e reutilizá-los entre nossas aplicações!!

Nesse contexto, vamos entender como faríamos isso com o Angular!

Usando Web components no Angular

Vamos dividir esse objetivo em dois passos:

1. Vamos criar um componente switch usando Web Components;
2. Integrar o web component na nossa aplicação Angular.

Criando o web component

Em um arquivo switch.component.js vamos declarar o seguinte código:

class SwitchComponent extends HTMLElement {
    
    constructor() {
        super();

        this.attachShadow({ mode: 'open' });

        const template = document.createElement('template');
        template.innerHTML = `
            <style>
                .switch-element {
                    --width: 60px;
                    display: flex;
                    background: none;
                    align-items: baseline;
                    padding: 0.15rem;
                    position: relative;
                    height: 30px;
                    cursor: pointer;
                    width: var(--width);
                    border-radius: 50px;
                    border: 2px solid #000;
                    box-sizing: border-box;
                }

                .switch-element label {
                    width: 22px;
                    height: 22px;
                    display: inline-block;
                    line-height: 20px;
                    background-color: #000;
                    border-radius: 55px;
                    transform: translatex(0);
                    transition: 0.2s ease;
                    box-sizing: border-box;
                }
            
                :host {
                    display: inline-block;
                }

                .switch-element.--open label{
                    transform: translatex(calc(var(--width) * 0.5));
                }
            </style>
            <button class="switch-element" tabindex>
                <label></label>
            </button>
        `;

        this.shadowRoot.appendChild(template.content.cloneNode(true));
        this.switchElement = this.shadowRoot.querySelector('.switch-element');
    }

    static get observedAttributes() {
        return ['open'];
    }

    attributeChangedCallback() {
        this.hasAttribute('open')
            ? this.switchElement.classList.add('--open')
            : this.switchElement.classList.remove('--open');
            this.#dispatchChangeEvent()
    }

    #dispatchChangeEvent(){
        this.dispatchEvent(new CustomEvent('change', {
            detail: this.hasAttribute('open')
        }))
    }

    connectedCallback() {
        this.addEventListener('click', () => {
            !this.hasAttribute('open')
                ? this.setAttribute('open', '')
                : this.removeAttribute('open')
        })
    }
}
customElements.define('switch-component', SwitchComponent);

Vamos entender alguns métodos do nosso web component:

• observeAttributes: vai nos ajudar a observar alterações no atributo open , definido no nosso componente hospedeiro: switch-component.
• connectedCalback: é o método executado quando o nosso web component for adicionado ao DOM.
• attributeChangedCallback: método executado quando houver alteração no valor das propriedades observadas por observeAttributes.

Integrando nosso web component no Angular

Agora que temos nosso web component, é hora de integrá-lo a nossa aplicação, para simplificar vamos importar o componente diretamente do diretório do projeto em tempo build.

No entanto, também poderíamos importá-lo de outras formas, seja como um pacote npm, uma url num bucket S3 e por aí vai.

Primeiro vamos criar uma aplicação Angular:

ng new webcomponents

Depois, dentro do diretório src/app/assets, vamos criar um diretório web_components e nele colocar nosso arquivo switch.component.js, criado anteriormente.

Em outros cenários, é comum que web components estejam hospedados externamente à nossa aplicação. Nesses casos é necessário especificar a localização do web component externo. Isso é feito declarando a propriedade scripts no arquivo angular.json, indicando o caminho até o componente.

E por fim, só precisamos declarar o web component switch-componentno template Angular.

import { CUSTOM_ELEMENTS_SCHEMA, Component, computed, signal } from '@angular/core';

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  styles: [`
    button {
      display: block;
      margin: 1rem 0;
    }
  `],
  template: `
    <switch-component (change)="log($event)" [attr.open]="isOpenAttribute()"/>
    <button (click)="toggleSwitchState()">Atualizar estado</button>
  `,
})
export class AppComponent {

  isOpen = signal(false);
  isOpenAttribute = computed(() => this.isOpen() ? '' : null);

  toggleSwitchState() {
    this.isOpen.update(value => !value)
  }

  log(event: Event){
    const data = event as CustomEvent;
    console.log("isActive", data.detail)
  }
}

Sempre que estamos importando um elemento customizado precisamos definir CUSTOM_ELEMENTS_SCHEMA, caso contrário o Angular lançará o erro https://angular.io/errors/NG8001

E eis o resultado, clicando no botão mudamos o estado do switch para aberto:

E clicando novamente, mudamos o estado para fechado:

Além disso, exibimos o estado atual do web component no console, fazendo o Angular ouvir o disparo de um evento customizado de dentro do switch-component.

E enfim temos um web component integrado na nossa aplicação Angular, legal né?!

Conclusão

Os Web Componentes são uma solução bastante interessante quando falamos de reutilização de código e diminuição de retrabalho, um dos casos de uso mais comuns são Microfrontends e bibliotecas de componentes, com destaque para este último.

Em bibliotecas de componentes, por exemplo, podemos desenvolver um componente apenas uma vez, e independente do framework que estiver utilizando, será possível reutilizá-lo.

E é isso! Obrigado por ter chegado até aqui, espero que tenha curtido o conteúdo!

Até a próxima, Dev!

Porém, com a especificação do HTML 5 isso mudou um pouco, e nesse contexto vamos explorar a API de Web Workers no cenário do Angular, o intuito é te familiarizar sobre como interagir com a API de Web Workers tanto ao usar puramente JavaScript e também com o framework, vamos nessa!

O que são Web Workers?

No contexto web, ele é um termo popular que se refere a API de Web Workers, que começou a ser especificada em 2004 com o HTML 5, e foi lançada oficialmente em 2014, o intuito dessa especificação foi permitir que código JavaScript pudesse ser executado em paralelo a thread principal.

Isto abriu uma série de possibilidades, pois agora é possível executar tarefas complexas do lado do cliente, em um ambiente que possui seu próprio escopo, sem afetar a experiência do usuário.

Processamento de dados, Operações I/O assíncronas, Tarefas em segundo plano, Cache, Simulações e Modelagens são apenas algumas das tarefas que podemos executar com um worker, que, se fossem executadas na thread principal do JavaScript, certamente impactariam negativamente a experiência do usuário da sua aplicação.

Implementando Web Workers

Chega de falar!

Vamos colocar a mão na massa, a implementação é relativamente simples e nesse exemplo vamos precisar apenas de uma página carregando alguns scripts.

Nossa página

Vamos criar uma página HTML bem simples…

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Web Worker - Exemplo</title>
</head>
<body>
    <h1 id="result"></h1>
</body>
</html>

Adicionando nosso script

Vamos incluir o script que irá se comunicar com nosso worker, perceba que a comunicação entre eles é baseada em eventos, é extremamente simples:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Web Worker - Exemplo</title>
    <script>
        // Verifica se os Web Workers são suportados pelo seu browser
        if (window.Worker) {
            // Criamos um novo Web Worker
            const myWorker = new Worker('worker.js');
            
            // Enviamos uma mensagem para o Web Worker
            myWorker.postMessage(10);

            // Aqui escutamos por mensagens vindas do Web Worker
            myWorker.onmessage = function({ data }) {
                const element = document.querySelector("#result");
                element.innerText = data;
            };

            // Apesar de não ser o foco desse post,
            // também podemos escutar por erros no Web Worker
            myWorker.onerror = function(error) {
                console.error('error:', error);
            };
        } else {
            console.log('Seu navegador não tem suporte para Web Workers.');
        }
    </script>
</head>
<body>
    <h1 id="result"></h1>
</body>
</html>

Adicionando nosso Web Worker

Não tem muita novidade, o worker é só um código JavaScript que vamos criar em um arquivo worker.jsno mesmo diretório…

function fib(n) {
  if(n <= 1){
    return n;
  }else {
    return fib(n-1) + fib(n - 2);
  }
}

// Enviamos a mensagem de volta para o script que chamou o worker
addEventListener('message', ({ data }) => {
  const response = fib(data);
  postMessage(response);
});

Usei uma extensão do VSCODE para servir o arquivo HTML e voilà! Eis o nosso resultado!

Apareceu bem rápido, mas você pode passar valores acima de 10 para o worker e perceber que não impacta na performance da página que você está visualizando esperando o resultado, apesar de levar algum tempo para o worker processar.

Mas como funciona no Angular?

No angular é mamão com açúcar.

Primeiro, garanta que tenha o Angular CLI instalado e crie um projeto novo:

ng new app-worker

Com o projeto criado, navegue com o terminal até o diretório do projeto e execute o comando abaixo:

ng g web-worker app

A CLI do Angular vai alterar algumas coisas no seu projeto para deixá-lo no jeitinho pra você usar os Web Workers no Framework, ele basicamente:

1. Altera o arquivo a configuração de build no arquivo angular.json do seu projeto
2. Cria um arquivo app.worker.ts com um código Typescript de exemplo, que vamos substituir a seguir;
3. Cria um arquivo tsconfig.worker.json com algumas configurações;
4. E também inclui um código Typescript chamando o worker a partir do seu arquivo app.component.ts;

E só precisaremos de dois passos :

1. Trazendo o código do nosso worker para arquivo app.worker.ts

/// <reference lib="webworker" />
function fib(n: number) {
  if(n <= 1){
    return n;
  }else {
    return fib(n-1) + fib(n - 2);
  }
}
addEventListener('message', ({ data }) => {
  const response = fib(data);
  postMessage(response);
});

2. Ajustando a chamada ao nosso worker ao estilo Angular

import { Component, OnInit, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [FormsModule],
  template: '<h1>{{ result() }}</h1>',
})
export class AppComponent implements OnInit {
  result = signal(0);
  ngOnInit(): void {
    if (window.Worker) {
      const worker = new Worker(new URL('./app.worker', import.meta.url));
      worker.onmessage = ({ data }) => {
        this.result.set(data);
      };
      worker.postMessage(10);
    }
  }
}

Agora é só executar:

npm start

E esse é nosso resultado:

Conclusão

E é isso meu querido(a), as possiblidades com Web Workers são muitas no que diz respeito principalmente a performance das suas aplicações web, você não tem desculpa para poluir a thread principal do JavaScript com processamento pesado agora que tem essa ferramenta, aliás, isso não era recomendação nem quando os Web Workers ainda não existiam!

Claro que, seria ótimo poder processar o máximo que pudermos nos web workers, mas como nem tudo são flores, você pode se deparar com algumas limitações, por isso sugiro que leia mais sobre essa API para entender onde ela se encaixa na sua aplicação da melhor forma.

Muito obrigado por ter chegado até aqui, já que está aqui, apoie meu trabalho clicando no botãozinho de palmas ali em baixo, quem sabe não chega esse post não chegue para alguém que precisa entender sobre workers.

Me me siga aqui na plataforma para ficar por dentro dos próximos posts, bem como no Linkedin, produzo conteúdo por lá também

Te vejo numa próxima, dev! 😉

https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers

Desde a versão 15, o Angular tem passado por modernizações notáveis, incluindo as Standalone APIs e aprimoramentos no Server-Side Rendering (SSR), agora integrado ao framework. Também foram introduzidos o novo Control Flow e os Signals, visando melhorar a performance e a experiência de desenvolvimento. O Angular está implementando gradualmente os Signals, permitindo aos desenvolvedores alternar entre Observables e Signals. Um destaque é a introdução da função toSignal, facilitando essa transição e marcando um avanço significativo para uma programação mais eficaz e intuitiva.

O que são Signals?

De forma resumida, eles se referem a um tipo de valor que pode ser monitorado por outras partes do sistema. Quando o estado ou valor do signal muda, ele automaticamente envia uma notificação para todos os inscritos.

Nesse sistema um Consumer pode ser qualquer parte do nosso código, como uma função, um método ou um objeto… talvez isso te lembra alguma coisa.

A palavra que talvez deve estar procurando se chama “reatividade”, que é um dos conceitos fundamentais que está presente em aplicações SPA, que define como a interface apresentada ao usuário responde a mudança de estado a partir de interações do usuário.

Os signals possui essa característica reativa, e é especialmente útil nesses tipos de aplicações que exigem uma experiência de usuário fluida e dinâmica capaz de reagir automaticamente as mudanças de estado dentro do sistema.

Signals no contexto do Angular

O SolidJS, uma biblioteca declarativa de construção de interfaces, foi uma das ferramentas que popularizaram os Signals nos últimos anos, mas esse não é um conceito novo. Desde então alguns frameworks e bibliotecas começaram a oferecer suporte a essa solução e dentre eles está o Angular.

Por isso, desde a versão 16 eles foram introduzidos no Angular através do Angular Signals, pensando principalmente no mecanismo de detecção de mudanças do framework, atualmente o Angular faz uso do ZoneJS, que monitora a execução de eventos no navegador e notifica o Angular de possíveis mudanças na sua árvore de componentes, disparando seu algorítmo de detecção de mudanças que é responsável por atualizar a interface para refletir o estado atual da aplicação.

No entanto, com o ZoneJS, o Angular não é capaz de saber onde exatamente aconteceu a mudança, somente que aconteceu alguma mudança e, assim, o algoritmo percorre toda a árvore de componentes desde o root, mesmo que apenas um componente tenha que ser re-renderizado.

Com a introdução dos signals no Angular isso tende a mudar, e a detecção de mudança e atualização da iterface tende a ser feita de maneira mais granular trazendo ganhos de performance realmente significativos.

toSignal: Interoperabilidade com Observables

Um dos esforços realizados pelo time do Angular e pela comunidade já nos permite, no momento que escrevo esse post, ter uma integração suave entre os Signals e os Observables, este último que é largamente utilizado no framework através da biblioteca RxJS, assim evita que tenhamos que reescrever todo nosso código, que normalmente usa Observables, para desfrutar do potencial que os Signals pode oferecer, com toSignal podemos facilmente transformar um Observable em um Signal.

Vamos dar uma olhada em um exemplo de código:

import { AsyncPipe } from '@angular/common';
import { Component } from '@angular/core';
import { of } from 'rxjs';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [AsyncPipe],
  template: `
   <div>{{$message | async}}</div>
  `,
  styleUrls: ['./app.component.scss']
})
export class AppComponent  {

  $message = this.getMessage();

  getMessage(){
    return of("Hello World")
  }
}

Aqui temos um componente bem simples e tradicional no Angular que exibe a mensagem “Hello World” no template usando o async pipe para automaticamente se inscrever e desinscrever do observable atribuido a $message, mas como que fazemos para utilizar signals sem ter que reescrever todo o nosso código atual?

Usamos a função toSignal para isso, veja o exemplo:

import { AsyncPipe } from '@angular/common';
import { Component } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop'
import { of } from 'rxjs';

@Component({
  selector: 'app-root',
  standalone: true,
  template: `
    <div>{{messageSignal()}}</div>
  `,
  styleUrls: ['./app.component.scss']
})
export class AppComponent {

  $message = this.getMessage();

  messageSignal = toSignal(this.$message)

  getMessage() {
    return of("Hello World")
  }
}

O resultado na interface é exatamente o mesmo! O que muda é a forma que referenciar o messageSignal no template, com parenteses, semelhante a chamada de um função e, além disso, não precisamos mais do async pipe.

Legal né?! Vamos olhar como isso funciona por debaixo dos panos.

toSignal por debaixo dos panos

A conversão de Observables para Signals parece mágica, porém vamos da ruma olhada como isso funciona por debaixo dos panos e entender como esse processo é feito analisando o código fonte do Angular:

A função toSignal espera receber dois parâmetros, o primeiro seria o Observable que queremos converter num signal e o segundo é um parâmetro opcional que espera um objeto contendo algumas propriedades, como initialValue por exemplo.

Em seguida é definido algumas variáveis, como:

• requiresCleanup: que espera um boleano que indica se a inscrição deve ser automaticamente finalizada (via DestroyRef) quando o contexto de criação de toObservable for destruído.
• A próxima linha é executada caso requiresCleanup for true e o injector não tiver sido definido, isso para garantir que o código atual tenha acesso a um injetor, que é necessário para resolver dependências.
• E a cleanupRef é atribuido uma referência a DestroyRef

export function toSignal<T, U = undefined>(
  source: Observable<T>|Subscribable<T>,
  options?: ToSignalOptions&{initialValue?: U}): Signal<T|U> {
  ngDevMode &&
      assertNotInReactiveContext(
          toSignal,
          'Invoking `toSignal` causes new subscriptions every time. ' +
              'Consider moving `toSignal` outside of the reactive context and read the signal value where needed.');

  const requiresCleanup = !options?.manualCleanup;
  requiresCleanup && !options?.injector && assertInInjectionContext(toSignal);
  const cleanupRef =
      requiresCleanup ? options?.injector?.get(DestroyRef) ?? ionject(DestroyRef) : null;

Seguindo a nossa exploração:

• Define o estado do signal como sendo do tipo NoValue caso seja necessário que o observable emita de sincronamente quando toSignal se inscreve, garantindo que o observable produza um valor imediatamente após a inscrição.
• Caso requireSync for falso o bloco else é executado e um signal recebendo um objeto como parâmetro, com um tipo um valor, é atribuído a variavel state.

  let state: WritableSignal<State<T|U>>;
  if (options?.requireSync) {
   state = signal({kind: StateKind.NoValue});
  } else {
   state = signal<State<T|U>>({kind: StateKind.Value, value: options?.initialValue as U});
  }

Continuando…

• Aqui é feita uma inscrição no observable que foi passado para ser transformado num signal chamando o método subscribe e passando um objeto com três propriedades:
• next: contendo a função que irá atualizar o valor do signal, anteriormente armazenado na variável state, sempre que for emitido um novo valor para o observable original (source).
• error: contendo a função que será executada caso seja emitido um erro no observable original, aqui será tomado dois caminhos: se options.rejectErros for verdadeiro, então o erro será enviado de volta para o RxJS, que será tratada como exceções não capturadas, as famosas uncaught exceptions. Caso options.rejectErros for falso o erro não será enviado de volta para o RxJS mas será atribuído ao signal armazenado em state

const sub = source.subscribe({
  next: value => state.set({kind: StateKind.Value, value}),
  error: error => {
    if (options?.rejectErrors) {
     throw error;
    }
    state.set({kind: StateKind.Error, error});
  },
});

Quase acabando…

• Aqui, caso ngDevMode seja verdadeiro, ou seja, a aplicação estiver executando em ambiente de desenvolvimento, e se foi definido que o observable original deverá emitir assim que toSignal se inscrever mas o tipo do signal for NoValue então dispara um erro em tempo de execução
• Depois disso, cancela inscrição quando o contexto atual for destruído, caso solicitado.

  if (ngDevMode && options?.requireSync && state().kind === StateKind.NoValue) {
    throw new ɵRuntimeError(
        ɵRuntimeErrorCode.REQUIRE_SYNC_WITHOUT_SYNC_EMIT,
        '`toSignal()` called with `requireSync` but `Observable` did not emit synchronously.');
  }

  cleanupRef?.onDestroy(sub.unsubscribe.bind(sub));

Em fim chegamos…

• Em resumo, o signal retornado é um ‘computed signal’ que mapeia estados para valores ou erros. Ele atualiza sempre que o ‘state’, que armazena o signal, é alterado — isto é, a cada novo valor emitido pelo observable original.
• E detalhe, o último caso do switch em geral não executa pois o caso onde o tipo NoValue já foi tratado anteriormente.

 return computed(() => {
    const current = state();
    switch (current.kind) {
      case StateKind.Value:
        return current.value;
      case StateKind.Error:
        throw current.error;
      case StateKind.NoValue:
       throw new ɵRuntimeError(
            ɵRuntimeErrorCode.REQUIRE_SYNC_WITHOUT_SYNC_EMIT,
            '`toSignal()` called with `requireSync` but `Observable` did not emit synchronously.');
    }
  });

Conclusão

Bem, o Angular vem evoluindo com a implementação dos Signals e a função que abordamos é fundamental no contexto de interoperabilidade entre Observables e Signals, claro que para essa interoperabilidade ser completa precisamos fazer o caminho contrário, ou seja, convertendo um Signal em um Observable, isso também é possível, porém esse será um papo para outro post.

É importante ressaltar que a função abordada nesse artigo ainda está em developer preview, porém logo deve ser lançada oficialmente.

Finalizando, se você chegou até aqui você é um guerreiro, então muito obrigado, espero que esse post possa te ajudar a entender com profundidade como foi implementado essa funcionalidade no Angular.

Me siga nas outras redes para ficar por dentro de mais conteúdo, até a próxima!