Componentes lógicos

Esta sección está actualmente en desarrollo. Vuelve pronto para obtener documentación completa sobre los componentes de lógica.

Los componentes de lógica son piezas de software que contienen la lógica de negocio de tu aplicación. Están organizados semánticamente por dominio o funcionalidad y sirven como la capa de orquestación entre controllers y adapters.

Propósito

Componentes de lógica:

• Implementan las reglas de negocio y la lógica del dominio

• Orquestan operaciones a través de múltiples adapters

• Encapsulan flujos de trabajo complejos

• Permiten permanecer independientes de las preocupaciones de la capa de transporte (HTTP, WebSocket)

• Pueden ser completamente probados con unit tests sin dependencias de I/O

Ubicación

Los componentes de lógica DEBERÍAN colocarse bajo src/logic o src/components el directorio, organizados por dominio:

src/
└── logic/
    ├── users/
    ├── content/
    ├── permissions/
    └── notifications/

Características

1. Consumo de Adapters

Los componentes de lógica son los principales consumidores de adapters. Usan adapters para interactuar con recursos externos mientras se enfocan en las reglas de negocio.

export function createUserLogic(
  components: Pick<AppComponents, 'database' | 'cache' | 'logs'>
): IUserLogic {
  const { database, cache, logs } = components
  const logger = logs.getLogger('user-logic')

  async function getUserProfile(userId: string): Promise<UserProfile> {
    // Revisar la cache primero
    const cached = await cache.get(`user:${userId}`)
    if (cached) {
      return cached
    }

    // Obtener de la database
    const user = await database.query('SELECT * FROM users WHERE id = $1', [userId])
    
    // Aplicar lógica de negocio
    const profile = transformUserToProfile(user)
    
    // Cachear el resultado
    await cache.set(`user:${userId}`, profile, { ttl: 3600 })
    
    return profile
  }

  return {
    getUserProfile
  }
}

2. Reglas de Negocio

Los componentes de lógica hacen cumplir las reglas de negocio y la validación:

async function createUser(userData: CreateUserInput): Promise<User> {
  // Regla de negocio: el nombre de usuario debe ser único
  const existing = await database.query(
    'SELECT id FROM users WHERE username = $1',
    [userData.username]
  )
  
  if (existing.rows.length > 0) {
    throw new UserAlreadyExistsError(userData.username)
  }

  // Regla de negocio: validar los datos del usuario
  if (!isValidEmail(userData.email)) {
    throw new InvalidEmailError(userData.email)
  }

  // Crear el usuario
  const user = await database.query(
    'INSERT INTO users (username, email) VALUES ($1, $2) RETURNING *',
    [userData.username, userData.email]
  )

  logger.info('User created', { userId: user.id })
  
  return user
}

3. Orquestación de Flujos de Trabajo

Los componentes de lógica coordinan operaciones complejas de múltiples pasos:

async function publishContent(
  userId: string,
  content: ContentInput
): Promise<PublishedContent> {
  // Paso 1: Validar permisos
  const canPublish = await permissions.canUserPublish(userId)
  if (!canPublish) {
    throw new UnauthorizedError('User cannot publish content')
  }

  // Paso 2: Procesar el contenido
  const processed = await processContent(content)

  // Paso 3: Almacenar el contenido
  const stored = await storage.save(processed)

  // Paso 4: Actualizar índices
  await searchIndex.index(stored)

  // Paso 5: Notificar a los suscriptores
  await notifications.notifySubscribers(userId, stored)

  logger.info('Content published', { contentId: stored.id, userId })

  return stored
}

Buenas prácticas

1. Responsabilidad Única

Cada componente de lógica debe centrarse en un dominio o contexto acotado:

// Bueno: Enfocado en el dominio de usuario
createUserLogic()
createContentLogic()
createPermissionsLogic()

// Evitar: Responsabilidades mezcladas
createUserAndContentLogic()

2. Inyección de Dependencias

Siempre inyectar las dependencias a través del parámetro components:

export function createOrderLogic(
  components: Pick<AppComponents, 'database' | 'payments' | 'inventory' | 'logs'>
): IOrderLogic {
  // Usar las dependencias inyectadas
}

3. Manejo de Errores

Lanzar errores de dominio significativos que los controllers puedan capturar y manejar:

// Definir errores específicos del dominio
export class InsufficientInventoryError extends Error {
  constructor(public readonly productId: string, public readonly requested: number) {
    super(`Insufficient inventory for product ${productId}. Requested: ${requested}`)
    this.name = 'InsufficientInventoryError'
  }
}

4. Lógica de Negocio Pura

Mantén los componentes de lógica libres de preocupaciones de la capa de transporte:

// Bueno: Lógica de negocio pura
async function calculateOrderTotal(items: OrderItem[]): Promise<number> {
  return items.reduce((total, item) => total + item.price * item.quantity, 0)
}

// Evitar: preocupaciones de HTTP/capa de transporte
async function calculateOrderTotal(req: Request, res: Response): Promise<void> {
  // No hagas esto en los componentes de lógica
}

Pruebas de Componentes de Lógica

Los componentes de lógica deben ser probados exhaustivamente con unit tests. Consulta la Testing Services (WKC) documentación para más detalles.

describe('when creating a user', () => {
  let userLogic: IUserLogic
  let mockDatabase: jest.Mocked<IDatabase>

  beforeEach(() => {
    mockDatabase = createMockDatabase()
    userLogic = createUserLogic({ database: mockDatabase, logs: mockLogs })
  })

  describe('and the username already exists', () => {
    beforeEach(() => {
      mockDatabase.query.mockResolvedValueOnce({ rows: [{ id: '123' }] })
    })

    it('should throw UserAlreadyExistsError', async () => {
      await expect(
        userLogic.createUser({ username: 'existing', email: '[email protected]' })
      ).rejects.toThrow(UserAlreadyExistsError)
    })
  })
})

Próximamente

Esta sección se ampliará con:

• Ejemplos detallados de componentes de lógica orientados al dominio

• Patrones para manejar flujos de trabajo complejos

• Directrices para organizar lógica de dominio a gran escala

• Integración con sistemas de eventos

• Estrategias de caching

• Patrones de gestión de transacciones