BlogEnsayo
Un comando es un fichero
Una funcionalidad entera con event sourcing en dos ficheros pequeños, y las cinco cosas que ya no escribes para llegar ahí. De dónde viene esa forma y lo que cuesta.
Traducido del original en inglés. Leer el original
Míralo funcionar en la demoEl event sourcing tiene fama de ceremonioso. Antes de guardar el primer hecho ya has escrito una clase de agregado, un tipo para el estado, una clase de comando, una excepción por cada fallo, un handler registrado en algún sitio y un bus por el que mandarlo. He visto a un equipo tras otro quedarse a un paso del event sourcing, y nunca fue por la idea. Fue por la maquinaria.
Bounda apuesta por una forma más pequeña. Aquí va una funcionalidad entera. Luego contamos lo que no está.
La funcionalidad entera
Un teatro vende butacas. Quien compra reserva algunas antes de pagar; una butaca ya reservada está ocupada, y nadie reserva más de las que permite el espectáculo.
// 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 } };
};
Ya está: un comando que decide y un evento que recuerda. payload es la petición, rejections
las maneras de decir que no, handler la decisión, evolve lo que cambia el evento. El runtime
carga los eventos del espectáculo antes de que corra el handler y guarda lo que devuelve.
Cinco cosas que no escribes
La clase del agregado
No hay clase Show ni tipo ShowState. El estado es lo que devuelven los eventos del
espectáculo: el evento que lo abre construye status, holders y limit, y SeatsHeld añade a
holders. Añade ahí un campo y state lo tiene en todos los handlers.
El registro
El sitio y el nombre del fichero son su declaración. seats-held.ts en la raíz de show/ es el
evento SeatsHeld del espectáculo; commands/hold-seats.ts es app.commands.holdSeats().
Ningún módulo, decorador ni fichero de configuración los vuelve a enumerar, y la carpeta se lee
como un í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
Los tipos
Cada módulo importa los tipos de sus argumentos de un fichero +types que bounda generate
escribe a su lado. command.payload sale del esquema, events solo ofrece los eventos del
espectáculo y reject solo acepta los códigos que declara el comando:
reject("SoldOut"); // error: not a code this command declares
events.orderPlaced; // error: not an event of the show
Lanza el generador en modo watch y los tipos te siguen mientras guardas.
La excepción para cada no
Un rechazo es una respuesta, no un hecho: no se guarda nada del comprador que pidió una butaca de
más. Quien llama recibe un error con rejected: "LimitReached", uno de los códigos que declara
el comando, y un mensaje escrito junto al motivo. Cuando el negocio sí quiere recordar una
negativa, es un evento, y
Not every no is a fact traza esa línea.
El null que se te olvidó comprobar
Si algo puede faltar, el tipo lo dice. Una query que busca una reserva devuelve la fila o null,
así que la página que la enseña tiene que decidir cómo se ve una reserva desconocida antes de
compilar:
const hold = await app.queries.getHold({ bookingId });
hold.seats; // error: 'hold' is possibly 'null'
Lo mismo pasa con los datos personales, que se leen como string | null porque algún día habrán
sido olvidados. El compilador te lleva a los
sitios que si no encontrarías en producción.
De dónde viene esta forma
React Router enseñó a muchos developers de TypeScript a escribir una ruta como un fichero de exports con nombre, con tipos generados a su lado:
// app/routes/product.tsx
import type { Route } from "./+types/product";
export function loader({ params }: Route.LoaderArgs) {
return { planet: `world #${params.id}` };
}
Cuajó porque nada en él es cableado: escribes lo que hace la ruta y el framework se encarga del resto. Bounda lleva eso al dominio: la carpeta dice a qué agregado pertenece un evento, o qué evento maneja una proyección.
Por qué funciones y no clases
Los frameworks de event sourcing más asentados modelan el agregado como una clase: una con
anotaciones en
Axon,
una normal que se pliega con métodos Apply en
Marten. Es un diseño sólido,
probado durante años, y es lo que permite a Axon correr el mismo handler en una flota de
servicios. Pero para una app de TypeScript, las funciones en ficheros te dan tres cosas que una
clase no te da:
- Un estado que no puede desviarse de los eventos. Es lo que devuelven los eventos, así que no hay una segunda declaración que mantener sincronizada a mano.
- Un no que es parte del contrato. Los códigos se declaran con el comando y están tipados:
rejectsolo acepta esos, y una policy que despacha el comando los recibe como un valor sobre el que decidir. - Una app conocida antes de arrancar. El generador lee nombres, no código, así que un fichero mal colocado falla al guardarlo, no cuando arranca la app.
El precio es que los nombres pesan: el nombre del fichero es el tipo del evento en el log, así que renombrar un evento es un cambio de esquema, no un refactor.
Pruébalo
La demo en vivo es la taquilla de un teatro escrita exactamente así. Abre Ask for too much (pide demasiado), reserva más butacas de las que permite el espectáculo, y el código que te dijo que no está en pantalla. Después, empieza el tuyo:
npm create bounda@latest my-shop
Getting started lo lleva a un comando con tests en quince minutos. Y si esta forma te parece la equivocada para tu dominio, dime dónde.