@alveolus/arch 0.2.0 → 0.3.0

package/docs/core/application/event-publishers.md

@@ -0,0 +1,234 @@
+---
+description: "Event publishers in TypeScript: the port that sends integration events to a message broker such as Kafka, a webhook, or other bounded contexts."
+---
+
+# Event publishers
+
+An event publisher is the port that sends [integration events](./integration-events.md) out of the
+bounded context: to a broker, a webhook, or the other contexts of the same process.
+
+<dl class="al-glance">
+	<dt>Layer</dt><dd>Application (a port)</dd>
+	<dt>File</dt><dd><code>shared-kernel/driven/kafka/adapters/kafka-event-publisher.adapter.ts</code> (your adapter)</dd>
+	<dt>Extends</dt><dd><a href="#api"><code>EventPublisher</code></a></dd>
+	<dt>Called by</dt><dd>The <a href="/core/application/outbox"><code>OutboxRelay</code></a>, never a command handler</dd>
+	<dt>Checked by</dt><dd><a href="/rules/layers/no-portless-adapter"><code>layers/no-portless-adapter</code></a>, <a href="/rules/tactical/no-misplaced-class"><code>tactical/no-misplaced-class</code></a></dd>
+</dl>
+
+## Why
+
+Shipping must learn that an order was placed. The ordering context should not know whether that
+goes through Kafka, RabbitMQ or a function call: if the relay used the Kafka client directly,
+changing the broker, or testing without one, would mean changing application code.
+
+::: tip The fix
+The application talks to an abstract `EventPublisher` with one method, `publish(events)`. A driven
+adapter implements it with the technology you use. The [outbox relay](./outbox.md) calls it; nothing
+else does.
+:::
+
+## How it works
+
+`publish` receives a batch of integration events, already JSON, and must either send them all or
+throw.
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span>Send in order</span>Publish the events in the order received: <code>OrderPlaced</code> before a later <code>OrderCancelled</code>.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span>Throw on failure</span>A broker down is technical: throw. The relay keeps the events pending and retries.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span>Expect duplicates</span>Delivery is at least once. Consumers ignore an event whose <code>id</code> they already handled.</div>
+</div>
+
+## Where it fits
+
+The publisher is the second step of the outbox relay, run in the background after the order was
+saved.
+
+<div class="al-diagram">
+<svg viewBox="0 0 680 240" role="img" aria-label="A timer job calls the OutboxRelay, which reads pending events from the outbox, calls the event publisher, and marks the events as published.">
+	<defs>
+		<marker id="publisher-flow-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+			<path class="arrow" d="M 0 0 L 10 5 L 0 10 z" />
+		</marker>
+	</defs>
+	<rect class="box" x="8" y="92" width="130" height="56" rx="8" />
+	<text class="label" x="73" y="116" text-anchor="middle">Timer job</text>
+	<text class="note" x="73" y="136" text-anchor="middle">driving adapter</text>
+	<path class="link" d="M 138 120 L 178 120" marker-end="url(#publisher-flow-arrow)" />
+	<rect class="box" x="180" y="92" width="180" height="56" rx="8" />
+	<text class="label" x="270" y="116" text-anchor="middle">OutboxRelay</text>
+	<text class="note" x="270" y="136" text-anchor="middle">relay()</text>
+	<rect class="box" x="440" y="24" width="232" height="48" rx="8" />
+	<text class="label" x="556" y="44" text-anchor="middle">1 · outbox.pending(n)</text>
+	<text class="note" x="556" y="62" text-anchor="middle">reads a batch</text>
+	<rect class="boundary" x="440" y="96" width="232" height="48" rx="8" />
+	<text class="label" x="556" y="116" text-anchor="middle">2 · publisher.publish(events)</text>
+	<text class="note" x="556" y="134" text-anchor="middle">this page: sends them</text>
+	<rect class="box" x="440" y="168" width="232" height="48" rx="8" />
+	<text class="label" x="556" y="188" text-anchor="middle">3 · outbox.markPublished(ids)</text>
+	<text class="note" x="556" y="206" text-anchor="middle">skips them next time</text>
+	<path class="link" d="M 360 120 L 438 48" marker-end="url(#publisher-flow-arrow)" />
+	<path class="link" d="M 360 120 L 438 120" marker-end="url(#publisher-flow-arrow)" />
+	<path class="link" d="M 360 120 L 438 192" marker-end="url(#publisher-flow-arrow)" />
+</svg>
+</div>
+
+::: tip
+If `publish` throws, step 3 never runs: the same events are published on the next call.
+:::
+
+## API
+
+```ts
+import { EventPublisher } from "@alveolus/core";
+// or: import { EventPublisher } from "@alveolus/core/event-publishers";
+```
+
+### `publish(events)` <Badge type="info" text="abstract" /> <Badge type="tip" text="you implement it" /> <Badge type="tip" text="called by the OutboxRelay" />
+
+```ts
+abstract publish(
+	events: readonly AnyIntegrationEvent[],
+): Promise<void>
+```
+
+Sends the integration events, in order, and throws on failure. The `OutboxRelay` calls it with one
+batch of pending events.
+
+::: warning Caveats
+- A failure to publish is technical: the adapter throws instead of returning a `Result`.
+- Delivery is at least once: an event may be published twice. Consumers ignore duplicates by `id`.
+- `EventPublisher` extends `Port`: it is an injection token, and its adapters live in
+  `driven/<technology>/adapters/`.
+:::
+
+## Usage
+
+Build a publisher for Kafka. Each step shows the whole file: added lines are highlighted, replaced lines are struck out.
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span><a href="#_1-pick-the-broker">Pick the broker</a></span>One adapter per technology.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span><a href="#_2-declare-the-adapter">Declare the adapter</a></span>Extend the port.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span><a href="#_3-publish-each-event">Publish each event</a></span>In order, one topic per event type.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">4</span><a href="#_4-key-each-message-by-its-id">Key each message by its id</a></span>Let consumers ignore duplicates.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">5</span><a href="#_5-wire-it-to-the-relay">Wire it to the relay</a></span>Only the relay calls it.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">6</span><a href="#_6-check-it">Check it</a></span>Let the rules keep it that way.</div>
+</div>
+
+### 1. Pick the broker
+
+`EventPublisher` is a port of `@alveolus/core`: you only write its adapter, under the name of its technology, here `driven/kafka/adapters/`, in the shared kernel.
+
+### 2. Declare the adapter
+
+The adapter extends `EventPublisher` and receives the client of the broker in its constructor, built by the composition root.
+
+```ts [src/shared-kernel/driven/kafka/adapters/kafka-event-publisher.adapter.ts]
+import { EventPublisher } from "@alveolus/core";
+import type { Producer } from "kafkajs";
+
+export class KafkaEventPublisher extends EventPublisher {
+	constructor(private readonly producer: Producer) {
+		super();
+	}
+}
+```
+
+TypeScript now asks for `publish()`: the next step adds it.
+
+### 3. Publish each event
+
+The relay hands over a batch in the order the events were added. Sending them one by one keeps that order, and a failure throws: the events stay pending in the outbox and are sent again.
+
+```ts [src/shared-kernel/driven/kafka/adapters/kafka-event-publisher.adapter.ts]
+import { EventPublisher } from "@alveolus/core"; // [!code --]
+import { type AnyIntegrationEvent, EventPublisher } from "@alveolus/core"; // [!code ++]
+import type { Producer } from "kafkajs";
+
+export class KafkaEventPublisher extends EventPublisher {
+	constructor(private readonly producer: Producer) {
+		super();
+	}
+
+	async publish( // [!code ++]
+		events: readonly AnyIntegrationEvent[], // [!code ++]
+	): Promise<void> { // [!code ++]
+		for (const event of events) { // [!code ++]
+			await this.producer.send({ // [!code ++]
+				messages: [{ value: JSON.stringify(event) }], // [!code ++]
+				topic: `${event.source}.${event.type}`, // [!code ++]
+			}); // [!code ++]
+		} // [!code ++]
+	} // [!code ++]
+}
+```
+
+### 4. Key each message by its id
+
+An event may be sent twice, after a failure between sending and marking it published. Its id, as the message key, lets consumers recognise and ignore a duplicate.
+
+```ts [src/shared-kernel/driven/kafka/adapters/kafka-event-publisher.adapter.ts]
+import { type AnyIntegrationEvent, EventPublisher } from "@alveolus/core";
+import type { Producer } from "kafkajs";
+
+export class KafkaEventPublisher extends EventPublisher {
+	constructor(private readonly producer: Producer) {
+		super();
+	}
+
+	async publish(
+		events: readonly AnyIntegrationEvent[],
+	): Promise<void> {
+		for (const event of events) {
+			await this.producer.send({
+				messages: [{ value: JSON.stringify(event) }], // [!code --]
+				messages: [ // [!code ++]
+					{ key: event.id, value: JSON.stringify(event) }, // [!code ++]
+				], // [!code ++]
+				topic: `${event.source}.${event.type}`,
+			});
+		}
+	}
+}
+```
+
+This is the complete publisher.
+
+### 5. Wire it to the relay
+
+The composition root passes the publisher to the [`OutboxRelay`](./outbox.md#usage), the only caller of `publish`.
+
+```ts [src/app.module.ts]
+const relay = new OutboxRelay(
+	outbox,
+	new KafkaEventPublisher(producer),
+	100,
+);
+```
+
+### 6. Check it
+
+Run the checks. Two rules keep the publisher the way it is now:
+
+```sh
+npx alveolus arch check
+```
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><a href="../../rules/layers/no-portless-adapter"><code>no-portless-adapter</code></a></span>It extends the port it implements.</div>
+<div class="al-card"><span class="al-card-title"><a href="../../rules/tactical/no-misplaced-class"><code>no-misplaced-class</code></a></span>It stays alone in <code>driven/kafka/adapters/*.adapter.ts</code>.</div>
+</div>
+
+The same class without <code>extends EventPublisher</code> is reported:
+
+```
+src/shared-kernel/driven/kafka/adapters/kafka-event-publisher.adapter.ts
+  4  error  layers/no-portless-adapter: KafkaEventPublisher is a driven
+  adapter but extends no Port: extend the port it implements.
+```
+
+## See also
+
+- [Outbox](./outbox.md), whose relay calls the publisher
+- [Integration events](./integration-events.md), what is published
+- [Ports](../domain/ports.md), what an event publisher is
+- Rules: [`layers/no-portless-adapter`](../../rules/layers/no-portless-adapter.md), [`tactical/no-misplaced-class`](../../rules/tactical/no-misplaced-class.md)

package/docs/core/application/event-translators.md

@@ -0,0 +1,329 @@
+---
+description: "Event translators in TypeScript: turn the domain events of an aggregate into integration events, plain JSON that other bounded contexts can read."
+---
+
+# Event translators
+
+An event translator turns the [domain events](../domain/domain-events.md) of an aggregate into
+[integration events](./integration-events.md): plain JSON that other bounded contexts can read.
+
+<dl class="al-glance">
+	<dt>Layer</dt><dd>Application</dd>
+	<dt>File</dt><dd><code>application/translators/order-events.translator.ts</code></dd>
+	<dt>Extends</dt><dd><a href="#api"><code>EventTranslator&lt;Event, Output&gt;</code></a></dd>
+	<dt>Called by</dt><dd><a href="/core/application/command-handlers">Command handlers</a></dd>
+	<dt>Checked by</dt><dd><a href="/rules/tactical/no-misplaced-class"><code>tactical/no-misplaced-class</code></a>, <a href="/rules/layers/no-outward-import"><code>layers/no-outward-import</code></a></dd>
+</dl>
+
+## Why
+
+The billing context wants to know when an order is placed. Send it the `OrderPlaced` domain event
+as is, and billing now depends on your classes: an `OrderId` object, a `Date`, field names you
+chose for your own model. Rename one of them and billing breaks, without a single line of billing
+changing.
+
+::: tip The fix
+An event translator maps each domain event to an integration event declared in your
+[published language](../strategic/published-language.md): JSON, with a name and a version. It is
+the one place where your model meets the contract other contexts read, so a refactoring of the
+domain never reaches them by accident.
+:::
+
+## How it works
+
+For each domain event it receives, the translator does three things:
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span>Recognize the event</span>Tell the events of the aggregate apart with <code>instanceof</code>.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span>Write the contract</span>Choose the <code>type</code>, the <code>version</code> and a JSON <code>payload</code>: identifiers and value objects become strings and numbers.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span>Wrap it</span><code>wrap</code> adds the id and the date of the domain event, the <code>source</code> and the correlation ids.</div>
+</div>
+
+```ts
+translate(
+	event: OrderPlaced,
+	context: IntegrationEventContext,
+): OrderPlacedRepresentation {
+	return this.wrap(event, context, {
+		type: "OrderPlaced",
+		version: 1,
+		payload: {
+			orderId: event.aggregateId.value,
+			customerId: event.payload.customerId,
+		},
+	});
+}
+```
+
+## Where it fits
+
+The translator runs inside the command handler, after the aggregate is saved and before its events
+go to the outbox. Before it, events are domain objects; after it, they are JSON.
+
+<div class="al-diagram">
+<svg viewBox="0 0 680 130" role="img" aria-label="The Order records an OrderPlaced domain event. The PlaceOrderHandler pulls it and gives it to the OrderEventsTranslator, which returns an integration event that the handler adds to the outbox.">
+	<defs>
+		<marker id="translator-flow-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+			<path class="arrow" d="M 0 0 L 10 5 L 0 10 z" />
+		</marker>
+	</defs>
+	<rect class="box" x="8" y="36" width="130" height="56" rx="8" />
+	<text class="label" x="73" y="60" text-anchor="middle">Order</text>
+	<text class="note" x="73" y="80" text-anchor="middle">records event</text>
+	<path class="link" d="M 138 64 L 168 64" marker-end="url(#translator-flow-arrow)" />
+	<rect class="box" x="170" y="36" width="170" height="56" rx="8" />
+	<text class="label" x="255" y="60" text-anchor="middle">PlaceOrderHandler</text>
+	<text class="note" x="255" y="80" text-anchor="middle">pulls events</text>
+	<path class="link" d="M 340 64 L 370 64" marker-end="url(#translator-flow-arrow)" />
+	<rect class="boundary" x="372" y="36" width="180" height="56" rx="8" />
+	<text class="label" x="462" y="60" text-anchor="middle">OrderEventsTranslator</text>
+	<text class="note" x="462" y="80" text-anchor="middle">this page</text>
+	<path class="link" d="M 552 64 L 582 64" marker-end="url(#translator-flow-arrow)" />
+	<rect class="box" x="584" y="36" width="88" height="56" rx="8" />
+	<text class="label" x="628" y="60" text-anchor="middle">Outbox</text>
+	<text class="note" x="628" y="80" text-anchor="middle">JSON</text>
+	<text class="note" x="173" y="116" text-anchor="middle">domain events</text>
+	<text class="note" x="560" y="116" text-anchor="middle">integration events</text>
+</svg>
+</div>
+
+::: tip
+The domain never knows the translator. It records events in its own words; the application decides
+what leaves the bounded context, and in which form.
+:::
+
+## API
+
+```ts
+import {
+	EventTranslator,
+	type IntegrationEventContext,
+} from "@alveolus/core";
+// or: from "@alveolus/core/event-translators"
+```
+
+### Type parameters
+
+```ts
+abstract class EventTranslator<
+	Event extends AnyDomainEvent,
+	Output extends AnyIntegrationEvent = AnyIntegrationEvent,
+> { … }
+```
+
+| Parameter | What it is | Constraint |
+| --- | --- | --- |
+| `Event` | The domain events it translates: one class, or a union. | extends `DomainEvent` |
+| `Output` | The integration events it produces, declared in the published language. | extends `IntegrationEvent`; any by default |
+
+### `source` <Badge type="info" text="protected · abstract · readonly" /> <Badge type="tip" text="you implement it" />
+
+```ts
+protected abstract readonly source: string
+```
+
+The bounded context the events come from, such as `"ordering"`. `wrap` copies it into every
+integration event.
+
+### `translate(event, context)` <Badge type="info" text="abstract" /> <Badge type="tip" text="you implement it" /> <Badge type="tip" text="called by the command handler" />
+
+```ts
+abstract translate(
+	event: Event,
+	context: IntegrationEventContext,
+): Output
+```
+
+Turns one domain event into its integration event. The command handler calls it for each pulled
+event, before adding the result to the outbox.
+
+### `wrap(event, context, contract)` <Badge type="info" text="protected" /> <Badge type="tip" text="inside your methods" />
+
+```ts
+protected wrap<Type extends string, Payload extends JsonValue>(
+	event: Event,
+	context: IntegrationEventContext,
+	contract: {
+		readonly type: Type;
+		readonly version: number;
+		readonly payload: Payload;
+	},
+): IntegrationEvent<Type, Payload>
+```
+
+Builds the integration event from the contract: copies `id` and `occurredAt` from the domain
+event, and adds `source`, `correlationId` and, when the context has one, `causationId`.
+
+::: warning Caveats
+- `occurredAt` becomes an ISO 8601 string, and `causationId` is only set when the context has one.
+- The payload type is constrained to `JsonValue`: an `Identifier` or a `Money` does not compile.
+- The translator lives in the application layer: it reads the domain and the published language,
+  and the domain never imports it.
+:::
+
+## Usage
+
+Build the translator of the `Order` aggregate. Each step shows the whole file: added lines are highlighted, replaced lines are struck out.
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span><a href="#_1-declare-the-representation">Declare the representation</a></span>Know what you publish.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span><a href="#_2-declare-the-translator">Declare the translator</a></span>One translator per aggregate.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span><a href="#_3-wrap-the-event">Wrap the event</a></span>Let wrap fill the envelope.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">4</span><a href="#_4-publish-what-consumers-need">Publish what consumers need</a></span>Add the fields other contexts read.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">5</span><a href="#_5-call-it-from-the-handler">Call it from the handler</a></span>Translate after saving.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">6</span><a href="#_6-check-it">Check it</a></span>Let the rules keep it that way.</div>
+</div>
+
+### 1. Declare the representation
+
+The translator produces an [integration event](./integration-events.md) declared in the published language of the context: `OrderPlacedRepresentation`. Declare it first.
+
+### 2. Declare the translator
+
+The translator extends `EventTranslator` with the domain events it reads and the representations it writes. `source` names the context that emits them, once for all its events.
+
+```ts [src/ordering/application/translators/order-events.translator.ts]
+import { EventTranslator } from "@alveolus/core";
+
+import type {
+	OrderPlaced,
+} from "../../domain/events/order-placed.event";
+import type {
+	OrderPlacedRepresentation,
+} from "../../published-language/order-placed.representation";
+
+export class OrderEventsTranslator extends EventTranslator<
+	OrderPlaced,
+	OrderPlacedRepresentation
+> {
+	protected readonly source = "ordering";
+}
+```
+
+TypeScript now asks for `translate()`: the next step adds it.
+
+### 3. Wrap the event
+
+So that every event carries the same envelope, `translate` gives `wrap` only the name, the version and the payload: `wrap` fills the id, the source, the date and the correlation. The payload holds plain values, never an identifier or a value object.
+
+```ts [src/ordering/application/translators/order-events.translator.ts]
+import { EventTranslator } from "@alveolus/core"; // [!code --]
+import { // [!code ++]
+	EventTranslator, // [!code ++]
+	type IntegrationEventContext, // [!code ++]
+} from "@alveolus/core"; // [!code ++]
+
+import type {
+	OrderPlaced,
+} from "../../domain/events/order-placed.event";
+import type {
+	OrderPlacedRepresentation,
+} from "../../published-language/order-placed.representation";
+
+export class OrderEventsTranslator extends EventTranslator<
+	OrderPlaced,
+	OrderPlacedRepresentation
+> {
+	protected readonly source = "ordering";
+
+	translate( // [!code ++]
+		event: OrderPlaced, // [!code ++]
+		context: IntegrationEventContext, // [!code ++]
+	): OrderPlacedRepresentation { // [!code ++]
+		return this.wrap(event, context, { // [!code ++]
+			type: "OrderPlaced", // [!code ++]
+			version: 1, // [!code ++]
+			payload: { // [!code ++]
+				orderId: event.aggregateId.value, // [!code ++]
+			}, // [!code ++]
+		}); // [!code ++]
+	} // [!code ++]
+}
+```
+
+### 4. Publish what consumers need
+
+A consumer cannot load the order: everything it needs must be in the payload. Add the customer, as a plain string read from the domain event.
+
+```ts [src/ordering/application/translators/order-events.translator.ts]
+import {
+	EventTranslator,
+	type IntegrationEventContext,
+} from "@alveolus/core";
+
+import type {
+	OrderPlaced,
+} from "../../domain/events/order-placed.event";
+import type {
+	OrderPlacedRepresentation,
+} from "../../published-language/order-placed.representation";
+
+export class OrderEventsTranslator extends EventTranslator<
+	OrderPlaced,
+	OrderPlacedRepresentation
+> {
+	protected readonly source = "ordering";
+
+	translate(
+		event: OrderPlaced,
+		context: IntegrationEventContext,
+	): OrderPlacedRepresentation {
+		return this.wrap(event, context, {
+			type: "OrderPlaced",
+			version: 1,
+			payload: {
+				orderId: event.aggregateId.value,
+				customerId: event.payload.customerId, // [!code ++]
+			},
+		});
+	}
+}
+```
+
+This is the complete translator.
+
+### 5. Call it from the handler
+
+The [command handler](./command-handlers.md#usage) translates each event it pulls from the order, after saving it, and adds the results to the [outbox](./outbox.md).
+
+```ts [src/ordering/application/commands/place-order.command.ts]
+await this.orders.save(order);
+const events = order
+	.pullDomainEvents()
+	.map((event) =>
+		this.translator.translate(event, {
+			correlationId: orderId,
+		}),
+	);
+await this.outbox.add(events);
+```
+
+### 6. Check it
+
+Run the checks. Two rules keep the translator the way it is now:
+
+```sh
+npx alveolus arch check
+```
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><a href="../../rules/tactical/no-misplaced-class"><code>no-misplaced-class</code></a></span>It stays alone in <code>application/translators/*.translator.ts</code>.</div>
+<div class="al-card"><span class="al-card-title"><a href="../../rules/layers/no-outward-import"><code>no-outward-import</code></a></span>It imports the domain, the application and its own published language, never an adapter.</div>
+</div>
+
+An import of a database adapter is reported:
+
+```
+src/ordering/application/translators/order-events.translator.ts
+  3  error  layers/no-outward-import: The application layer imports
+  src/ordering/driven/pg/adapters/pg-orders.adapter.ts
+  (ordering driven): it may only import domain, application,
+  published-language.
+```
+
+## See also
+
+- [Integration events](./integration-events.md), what it produces
+- [Domain events](../domain/domain-events.md), what it reads
+- [Published Language](../strategic/published-language.md), where the contracts are declared
+- [Outbox](./outbox.md), where the translated events go