BlogEnsaio

Um comando é um arquivo

Uma feature inteira com event sourcing em dois arquivos pequenos, e as cinco coisas que você deixa de escrever para chegar lá. De onde vem esse formato, e o que ele custa.

5 min de leitura

Tradução automática do original em inglês. Ler o original · Avisar de um erro

Veja funcionando na demo

Event sourcing tem fama de cerimônia. Antes de guardar o primeiro fato, você já escreveu uma classe de agregado, um tipo de estado, uma classe de comando, uma exceção para cada falha, um handler registrado em algum lugar e um bus para enviá-lo. Vi equipe atrás de equipe parar a um passo do event sourcing, e a ideia nunca foi o motivo. O motivo era a maquinaria.

O Bounda aposta num formato menor. Aqui está uma feature inteira. Depois, vamos contar o que não está ali.

A feature inteira

Um teatro vende lugares. Um comprador reserva alguns antes de pagar; um lugar já reservado está ocupado, e ninguém reserva mais do que o espetáculo permite.

// app/domain/show/commands/hold-seats.ts
import type { Command } from "./+types/hold-seats";

export const payload = ({ z }: Command.PayloadArgs) =>
  z.object({
    showId: z.string().min(1),
    bookingId: z.uuid(),
    buyerId: z.string().min(1),
    seats: z.array(z.string()).min(1),
  });

export const rejections = ({ command, state }: Command.RejectionsArgs) => {
  const taken = command.payload.seats.filter((s) => state.holders?.[s]);

  return {
    NotOnSale: "This show is not on sale",
    SeatTaken: `Already taken: ${taken.join(", ")}`,
    LimitReached: `At most ${state.limit} seats per person`,
  };
};

export const handler = ({ command, state, events, reject }: Command.HandlerArgs) => {
  if (state.status !== "on-sale") return reject("NotOnSale");

  const { bookingId, buyerId, seats } = command.payload;
  if (seats.some((seat) => state.holders[seat])) return reject("SeatTaken");

  const held = Object.values(state.holders);
  const mine = held.filter((holder) => holder === buyerId).length;
  if (mine + seats.length > state.limit) return reject("LimitReached");

  return [events.seatsHeld({ bookingId, buyerId, seats })];
};
// app/domain/show/seats-held.ts
import type { Event } from "./+types/seats-held";

export const payload = ({ z }: Event.PayloadArgs) =>
  z.object({
    bookingId: z.uuid(),
    buyerId: z.string(),
    seats: z.array(z.string()).min(1),
  });

export const evolve = ({ event, state }: Event.EvolveArgs) => {
  const { buyerId, seats } = event.payload;
  const held = Object.fromEntries(seats.map((seat) => [seat, buyerId]));

  return { holders: { ...state.holders, ...held } };
};

É só isso: um comando que decide e um evento que lembra. payload é o pedido, rejections as maneiras como ele pode dizer não, handler a decisão, evolve o que o evento muda. O runtime carrega os eventos do espetáculo antes de o handler rodar e guarda o que ele devolve.

Cinco coisas que você não escreve

A classe de agregado

Não há classe Show nem tipo ShowState. O estado é o que os eventos do espetáculo devolvem: o evento que o abre constrói status, holders e limit, e SeatsHeld acrescenta a holders. Acrescente um campo ali e state passa a tê-lo em todos os handlers.

O registro

O lugar e o nome do arquivo são a declaração. seats-held.ts na raiz de show/ é o evento SeatsHeld do espetáculo; commands/hold-seats.ts é app.commands.holdSeats(). Nenhum módulo, decorator ou config os lista de novo, e a pasta se lê como um índice:

app/
  domain/
    show/
      show-scheduled.ts      ShowScheduled, which opens a show
      seats-held.ts          SeatsHeld
      commands/
        hold-seats.ts        holdSeats
  read/
    holds/
      view.ts                its columns
      projections/show/
        seats-held.ts        projects the show's SeatsHeld
      queries/
        get-hold.ts          getHold

Os tipos

Cada módulo importa os tipos dos seus argumentos de um arquivo +types que o bounda generate escreve ao lado dele. command.payload vem do schema, events oferece só os eventos do espetáculo, e reject aceita só os códigos que o comando declara:

reject("SoldOut");    // error: not a code this command declares
events.orderPlaced;   // error: not an event of the show

Rode o gerador em modo watch e os tipos acompanham você a cada vez que salva.

A exceção para cada não

Uma rejeição é uma resposta, não um fato: nada é guardado para o comprador que pediu um lugar a mais. Quem chama recebe um erro com rejected: "LimitReached", um dos códigos que o comando declara, e uma mensagem escrita ao lado do motivo. Quando o negócio quer, sim, lembrar uma recusa, ela passa a ser um evento, e Not every no is a fact traça essa linha.

A checagem de null que você esqueceu

Se algo pode faltar, o tipo diz. Uma query que busca uma reserva devolve a linha ou null, então a página que a mostra tem que decidir como é uma reserva desconhecida antes de compilar:

const hold = await app.queries.getHold({ bookingId });

hold.seats;           // error: 'hold' is possibly 'null'

O mesmo vale para dados pessoais, que são lidos como string | null porque um dia terão sido esquecidos. O compilador leva você aos lugares que, de outro jeito, você encontraria em produção.

De onde vem o formato

O React Router ensinou muitos devs de TypeScript a escrever uma rota como um arquivo de exports nomeados, com tipos gerados ao lado:

// app/routes/product.tsx
import type { Route } from "./+types/product";

export function loader({ params }: Route.LoaderArgs) {
  return { planet: `world #${params.id}` };
}

Pegou porque nada ali é fiação: você escreve o que a rota faz, e o framework resolve o resto. O Bounda leva isso ao domínio: a pasta diz a qual agregado um evento pertence, ou qual evento uma projeção trata.

Por que funções, e não classes

Os frameworks de event sourcing já consolidados modelam o agregado como uma classe: uma classe anotada no Axon, uma classe simples que faz o fold com métodos Apply no Marten. É um design sólido, comprovado ao longo de anos, e é o que permite ao Axon rodar o mesmo handler numa frota de serviços. Para um único app TypeScript, porém, funções em arquivos dão três coisas que uma classe não dá:

  • Um estado que não pode se desviar dos eventos. Ele é o que os eventos devolvem, então não há uma segunda declaração para manter em sincronia à mão.
  • Um não que faz parte do contrato. Os códigos são declarados com o comando e tipados: reject só aceita esses, e uma policy que despacha o comando os recebe de volta como um valor sobre o qual decidir.
  • Um app conhecido antes de rodar. O gerador lê nomes, não código, então um arquivo fora do lugar falha quando você salva, não quando o app sobe.

O preço é que os nomes têm peso: o nome do arquivo é o tipo do evento no log, então renomear um evento é uma mudança de schema, não um refactor.

Experimente

A demo ao vivo é a bilheteria de um teatro escrita exatamente assim. Abra Ask for too much (peça demais), reserve mais lugares do que o espetáculo permite, e o código que recusou você está na tela. Depois comece um projeto seu:

npm create bounda@latest my-shop

O Getting started leva você até um comando testado em quinze minutos. E se esse formato parece errado para o seu domínio, me diga onde.