Components

Os componentes são pedaços de software autocontidos projetados como caixas-pretas que recebem outros componentes (ou nenhum) para executar suas tarefas. O objetivo principal é desacoplar seções de código e maximizar a testabilidade.

Estrutura de Diretórios

Todos os componentes DEVEM ser definidos dentro de um diretório dedicado contendo pelo menos estes quatro arquivos:

• component.ts - Contém o código de implementação do componente

• types.ts - Contém a interface do componente e os tipos expostos

• errors.ts - Contém todas as classes de erro exportadas

• index.ts - Exporta a API pública do componente

Exemplo de Estrutura

src/
└── components/
    └── my-component/
        ├── component.ts
        ├── types.ts
        ├── errors.ts
        └── index.ts

Arquivo de Tipos

Os componentes obedecem a uma interface que define sua API pública. Essa interface pode ser compartilhada entre componentes intercambiáveis ou usada para entender os métodos expostos pelo componente.

Todos os componentes que possuem sua própria interface DEVEM defini-la em um types.ts arquivo dentro do diretório do componente.

Outros tipos expostos pelo componente TAMBÉM DEVEM ser colocados neste arquivo.

Exemplo: types.ts

export type Something = {
  aValue: boolean
  anotherValue: string
}

export interface IMyComponent {
  myFunction: () => boolean
  getSomething: () => Something
}

Tipos Compartilhados

Tipos compartilhados entre múltiplos componentes, como interfaces comuns, DEVEM ser colocados em um types.ts arquivo no diretório raiz do código-fonte do projeto (/src/types.ts).

Arquivo do Componente

O arquivo do componente contém a função criadora do componente. Essa função segue uma convenção específica de nomeação e estrutura.

Convenção de Nomeação

As funções criadoras de componentes DEVEM ser nomeadas como: create + ComponentName + Component

Exemplo: createMyNewComponent

Assinatura da Função

A função criadora DEVE:

1. Receber um objeto components como primeiro parâmetro contendo todas as dependências

2. Opcionalmente receber parâmetros adicionais de configuração

3. Retornar um objeto contendo os métodos expostos (públicos)

Estrutura do Componente

No início da função criadora do componente:

1. Extrair dependências do objeto components

2. Inicializar variáveis comuns (por exemplo, loggers, configuração)

3. Definir funções auxiliares internas

4. Definir métodos públicos

5. Retornar a API pública

Exemplo: component.ts

import { IMyComponent, Something } from './types'
import { WrongStringError } from './errors'

export function createMyNewComponent(
  components: Pick<AppComponents, 'logs'>
): IMyComponent {
  const { logs } = components
  const logger = logs.getLogger('my-component')

  // Método interno - não exposto
  function computeString(fstString: string, sndString: string): string {
    if (fstString.length === 0) {
      throw new WrongStringError()
    }
    
    return fstString + ' ' + sndString
  }

  // Método público - exposto no objeto retornado
  function myFunction(): boolean {
    return true
  }

  // Método público - exposto no objeto retornado
  function getSomething(): Something {
    logger.info('Getting something')
    
    return {
      aValue: true,
      anotherValue: computeString('aString', 'anotherString')
    }
  }

  // Retornar a API pública
  return {
    myFunction,
    getSomething
  }
}

Arquivo de Erros

O arquivo de erros contém classes de erro customizadas que um componente pode lançar. Esses erros podem ser usados em outros componentes ou controladores para identificar e tratar corretamente condições de erro específicas.

Exemplo: errors.ts

export class WrongStringError extends Error {
  constructor(message?: string) {
    super(message || 'Incorrect String')
    this.name = 'WrongStringError'
  }
}

export class ComponentNotInitializedError extends Error {
  constructor() {
    super('Component has not been initialized')
    this.name = 'ComponentNotInitializedError'
  }
}

Boas Práticas de Tratamento de Erros

• Criar classes de erro específicas para diferentes condições de erro

• Incluir mensagens de erro significativas

• Defina o name property to match the class name for easier debugging

• Documentar quais erros podem ser lançados por cada método público

Arquivo Index

O arquivo index serve como ponto de entrada público para o componente, exportando apenas o que deve ser acessível para outras partes da aplicação.

Exemplo: index.ts

export { createMyNewComponent } from './component'
export type { IMyComponent, Something } from './types'
export { WrongStringError } from './errors'

Boas Práticas

1. Responsabilidade Única - Cada componente deve ter um propósito claro

2. Dependências Explícitas - Todas as dependências devem ser injetadas através do parâmetro components

3. Imutabilidade - Preferir estruturas de dados imutáveis sempre que possível

4. Tratamento de Erros - Usar classes de erro customizadas para diferentes condições de erro

5. Registro (Logging) - Usar o logger para depuração e monitoramento

6. Segurança de Tipos - Aproveitar o sistema de tipos do TypeScript ao máximo

7. Documentação - Documentar métodos complexos e lógica de negócio

Ciclo de Vida do Componente

Alguns componentes podem precisar executar operações de configuração ou limpeza. WKC fornece métodos de ciclo de vida:

• [START_COMPONENT] - Chamado quando o componente inicia

• [STOP_COMPONENT] - Chamado quando o componente para

Veja a Adaptadores seção para exemplos de componentes usando métodos de ciclo de vida.