Portas e adaptadores para isolamento do domínio

Why Isolate the Domain?

The Dependency Rule

Defining a Driven Port

export interface Order {
  id: string;
  customerId: string;
  totalCents: number;
  status: 'PENDING' | 'PAID' | 'CANCELLED';
}

// Driven (outbound) port: owned by the application/domain layer.
export interface OrderRepositoryPort {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

A Driving Port: The Use Case

export interface PlaceOrderCommand {
  orderId: string;
  customerId: string;
  totalCents: number;
}

// Driving (inbound) port: the application's public contract.
export interface PlaceOrderPort {
  execute(cmd: PlaceOrderCommand): Promise<void>;
}

Implementing the Use Case

import { Injectable, Inject } from '@nestjs/common';
import { PlaceOrderPort, PlaceOrderCommand } from './place-order.port';
import { OrderRepositoryPort } from './order-repository.port';
import { ORDER_REPOSITORY } from './tokens';

@Injectable()
export class PlaceOrderUseCase implements PlaceOrderPort {
  constructor(
    @Inject(ORDER_REPOSITORY)
    private readonly orders: OrderRepositoryPort,
  ) {}

  async execute(cmd: PlaceOrderCommand): Promise<void> {
    if (cmd.totalCents <= 0) {
      throw new Error('Order total must be positive');
    }
    await this.orders.save({
      id: cmd.orderId,
      customerId: cmd.customerId,
      totalCents: cmd.totalCents,
      status: 'PENDING',
    });
  }
}

Injection Tokens for Interfaces

export const ORDER_REPOSITORY = Symbol('OrderRepositoryPort');
export const PLACE_ORDER = Symbol('PlaceOrderPort');

// Usage at an injection site:
// constructor(@Inject(ORDER_REPOSITORY) repo: OrderRepositoryPort) {}

Writing a Driven Adapter

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { OrderRepositoryPort, Order } from '../application/order-repository.port';
import { OrderEntity } from './order.entity';

@Injectable()
export class TypeOrmOrderRepository implements OrderRepositoryPort {
  constructor(
    @InjectRepository(OrderEntity)
    private readonly repo: Repository<OrderEntity>,
  ) {}

  async save(order: Order): Promise<void> {
    await this.repo.save(this.repo.create(order));
  }

  async findById(id: string): Promise<Order | null> {
    const row = await this.repo.findOne({ where: { id } });
    return row ? { ...row } : null;
  }
}

Wiring Ports to Adapters in a Module

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { OrderEntity } from './infrastructure/order.entity';
import { TypeOrmOrderRepository } from './infrastructure/typeorm-order.repository';
import { PlaceOrderUseCase } from './application/place-order.usecase';
import { ORDER_REPOSITORY, PLACE_ORDER } from './application/tokens';

@Module({
  imports: [TypeOrmModule.forFeature([OrderEntity])],
  providers: [
    { provide: ORDER_REPOSITORY, useClass: TypeOrmOrderRepository },
    { provide: PLACE_ORDER, useClass: PlaceOrderUseCase },
  ],
  exports: [PLACE_ORDER],
})
export class OrdersModule {}

The Controller is Just Another Adapter

import { Body, Controller, Inject, Post } from '@nestjs/common';
import { PlaceOrderPort } from '../application/place-order.port';
import { PLACE_ORDER } from '../application/tokens';

@Controller('orders')
export class OrdersController {
  constructor(
    @Inject(PLACE_ORDER) private readonly placeOrder: PlaceOrderPort,
  ) {}

  @Post()
  async create(@Body() body: { orderId: string; customerId: string; totalCents: number }) {
    await this.placeOrder.execute(body);
    return { status: 'accepted' };
  }
}

Testing With an In-Memory Adapter

interface Order {
  id: string;
  customerId: string;
  totalCents: number;
  status: 'PENDING' | 'PAID' | 'CANCELLED';
}

interface OrderRepositoryPort {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

class InMemoryOrderRepo implements OrderRepositoryPort {
  private store = new Map<string, Order>();
  async save(o: Order) { this.store.set(o.id, o); }
  async findById(id: string) { return this.store.get(id) ?? null; }
}

class PlaceOrderUseCase {
  constructor(private readonly orders: OrderRepositoryPort) {}
  async execute(cmd: { orderId: string; customerId: string; totalCents: number }) {
    if (cmd.totalCents <= 0) throw new Error('Order total must be positive');
    await this.orders.save({ ...cmd, id: cmd.orderId, status: 'PENDING' });
  }
}

async function main() {
  const repo = new InMemoryOrderRepo();
  const useCase = new PlaceOrderUseCase(repo);
  await useCase.execute({ orderId: 'o1', customerId: 'c1', totalCents: 4200 });
  const saved = await repo.findById('o1');
  console.log(saved?.status === 'PENDING' ? 'PASS' : 'FAIL');
}

main();

Anti-Corruption at the Boundary

import { PaymentPort } from '../application/payment.port';

// Adapter translates a vendor payload into a domain-friendly result.
export class StripePaymentAdapter implements PaymentPort {
  async charge(customerId: string, amountCents: number): Promise<{ paid: boolean }> {
    const vendorResp = await this.callStripe(customerId, amountCents);
    // Map vendor shape -> domain shape (anti-corruption).
    return { paid: vendorResp.status === 'succeeded' };
  }

  private async callStripe(_c: string, _a: number) {
    return { status: 'succeeded' as const };
  }
}

Quick Check

Recap