Componentes

Los componentes son piezas de software autocontenidas, diseñadas como cajas negras que reciben otros componentes (o ninguno) para realizar sus tareas. El objetivo principal es desacoplar secciones de código y maximizar la capacidad de prueba.

Estructura de directorios

Todos los componentes DEBEN definirse dentro de un directorio dedicado que contenga al menos estos cuatro archivos:

• component.ts - Contiene el código de implementación del componente

• types.ts - Contiene la interfaz del componente y los tipos expuestos

• errors.ts - Contiene todas las clases de error exportadas

• index.ts - Exporta la API pública del componente

Estructura de ejemplo

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

Archivo de tipos

Los componentes se ajustan a una interfaz que define su API pública. Esta interfaz puede compartirse entre componentes intercambiables o usarse para entender los métodos expuestos por el componente.

Todos los componentes que tengan su propia interfaz DEBEN definirla en un types.ts archivo dentro del directorio del componente.

Otros tipos expuestos por el componente TAMBIÉN DEBEN colocarse en este archivo.

Ejemplo: types.ts

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

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

Tipos compartidos

Los tipos compartidos entre varios componentes, como las interfaces comunes, DEBEN colocarse en un types.ts archivo en el directorio raíz del código fuente del proyecto (/src/types.ts).

Archivo del componente

El archivo del componente contiene la función creadora del componente. Esta función sigue una convención específica de nombres y estructura.

Convención de nombres

Las funciones creadoras de componentes DEBEN nombrarse así: create + ComponentName + Component

Ejemplo: createMyNewComponent

Firma de la función

La función creadora DEBE:

1. Recibir un objeto components como primer parámetro que contenga todas las dependencias

2. Recibir opcionalmente parámetros de configuración adicionales

3. Devolver un objeto que contenga los métodos expuestos (públicos)

Estructura del componente

Al inicio de la función creadora del componente:

1. Extraer las dependencias del objeto components

2. Inicializar variables comunes (p. ej., loggers, configuración)

3. Definir funciones auxiliares internas

4. Definir métodos públicos

5. Devolver la API pública

Ejemplo: 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 - no expuesto
  function computeString(fstString: string, sndString: string): string {
    if (fstString.length === 0) {
      throw new WrongStringError()
    }
    
    return fstString + ' ' + sndString
  }

  // Método público - expuesto en el objeto de retorno
  function myFunction(): boolean {
    return true
  }

  // Método público - expuesto en el objeto de retorno
  function getSomething(): Something {
    logger.info('Obteniendo algo')
    
    return {
      aValue: true,
      anotherValue: computeString('aString', 'anotherString')
    }
  }

  // Devolver la API pública
  return {
    myFunction,
    getSomething
  }
}

Archivo de errores

El archivo de errores contiene clases de error personalizadas que un componente puede lanzar. Estos errores pueden usarse en otros componentes o controladores para identificar y gestionar correctamente condiciones de error específicas.

Ejemplo: errors.ts

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

export class ComponentNotInitializedError extends Error {
  constructor() {
    super('El componente no ha sido inicializado')
    this.name = 'ComponentNotInitializedError'
  }
}

Buenas prácticas para el manejo de errores

• Crea clases de error específicas para diferentes condiciones de error

• Incluye mensajes de error significativos

• Establezca el name propiedad para que coincida con el nombre de la clase y facilite la depuración

• Documenta qué errores puede lanzar cada método público

Archivo de índice

El archivo de índice sirve como punto de entrada público del componente, exportando solo lo que debe ser accesible para otras partes de la aplicación.

Ejemplo: index.ts

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

Buenas prácticas

1. Responsabilidad única - Cada componente debe tener un único propósito claro

2. Dependencias explícitas - Todas las dependencias deben inyectarse a través del parámetro components

3. Inmutabilidad - Preferir estructuras de datos inmutables siempre que sea posible

4. Manejo de errores - Usa clases de error personalizadas para diferentes condiciones de error

5. Registro - Usa el logger para depuración y monitorización

6. Seguridad de tipos - Aprovecha al máximo el sistema de tipos de TypeScript

7. Documentación - Documenta los métodos complejos y la lógica de negocio

Ciclo de vida del componente

Algunos componentes pueden necesitar realizar operaciones de configuración o limpieza. WKC proporciona métodos de ciclo de vida:

• [START_COMPONENT] - Se llama cuando el componente se inicia

• [STOP_COMPONENT] - Se llama cuando el componente se detiene

Consulta la Adaptadores sección para ejemplos de componentes que usan métodos de ciclo de vida.