@alveolus/arch 0.2.0 → 0.4.0

package/docs/core/application/index.md

@@ -0,0 +1,99 @@
+---
+description: "The application layer in Domain-Driven Design with TypeScript: command and query handlers that run use cases atomically and reliably."
+---
+
+# Application
+
+The application runs the use cases: one handler per request, which calls the domain and makes the
+change atomic and reliable. It lives in `application/`; the adapters of its contracts live in
+`driven/`.
+
+## Why
+
+A controller that loads an order, checks it, saves it and sends an email mixes HTTP, rules and
+storage. A second entry point, a consumer or a CLI, copies it. If the email leaves before the save
+fails, the customer is told about an order that does not exist.
+
+::: tip The fix
+Each use case is one handler that only coordinates: load, call the domain, save, hand over the
+events. The save and the events commit together, and the events are sent after.
+:::
+
+## How a request flows
+
+<div class="al-diagram">
+<svg viewBox="0 0 680 310" role="img" aria-label="A command goes from a controller to PlaceOrderHandler, which in one unit of work saves the order and adds the events translated by OrderEventsTranslator to the outbox. Later, OutboxRelay reads the outbox and the event publisher sends the integration events to other contexts. A query goes from a controller to GetOrderSummaryHandler, which reads a view through a query repository.">
+	<defs>
+		<marker id="application-overview-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>
+	<text class="note" x="8" y="20">command</text>
+	<rect class="box" x="8" y="50" width="120" height="48" rx="8" />
+	<text class="label" x="68" y="70" text-anchor="middle">Controller</text>
+	<text class="note" x="68" y="88" text-anchor="middle">driving</text>
+	<rect class="boundary" x="146" y="28" width="526" height="80" rx="12" />
+	<text class="note" x="160" y="44">one unit of work</text>
+	<rect class="box" x="160" y="52" width="160" height="44" rx="8" />
+	<text class="label" x="240" y="70" text-anchor="middle">PlaceOrderHandler</text>
+	<text class="note" x="240" y="87" text-anchor="middle">command handler</text>
+	<rect class="box" x="342" y="52" width="160" height="44" rx="8" />
+	<text class="label" x="422" y="70" text-anchor="middle">OrderEventsTranslator</text>
+	<text class="note" x="422" y="87" text-anchor="middle">event translator</text>
+	<rect class="box" x="524" y="52" width="136" height="44" rx="8" />
+	<text class="label" x="592" y="70" text-anchor="middle">Outbox</text>
+	<text class="note" x="592" y="87" text-anchor="middle">with the save</text>
+	<path class="link" d="M 128 74 L 158 74" marker-end="url(#application-overview-arrow)" />
+	<path class="link" d="M 320 74 L 340 74" marker-end="url(#application-overview-arrow)" />
+	<path class="link" d="M 502 74 L 522 74" marker-end="url(#application-overview-arrow)" />
+	<text class="note" x="8" y="136">later</text>
+	<rect class="box" x="524" y="150" width="148" height="48" rx="8" />
+	<text class="label" x="598" y="170" text-anchor="middle">OutboxRelay</text>
+	<text class="note" x="598" y="188" text-anchor="middle">reads pending</text>
+	<rect class="box" x="342" y="150" width="160" height="48" rx="8" />
+	<text class="label" x="422" y="170" text-anchor="middle">EventPublisher</text>
+	<text class="note" x="422" y="188" text-anchor="middle">sends them</text>
+	<rect class="box" x="160" y="150" width="160" height="48" rx="8" />
+	<text class="label" x="240" y="170" text-anchor="middle">Other contexts</text>
+	<text class="note" x="240" y="188" text-anchor="middle">integration events</text>
+	<path class="link" d="M 598 108 L 598 148" marker-end="url(#application-overview-arrow)" />
+	<path class="link" d="M 524 174 L 504 174" marker-end="url(#application-overview-arrow)" />
+	<path class="link" d="M 342 174 L 322 174" marker-end="url(#application-overview-arrow)" />
+	<text class="note" x="8" y="226">query</text>
+	<rect class="box" x="8" y="244" width="120" height="48" rx="8" />
+	<text class="label" x="68" y="264" text-anchor="middle">Controller</text>
+	<text class="note" x="68" y="282" text-anchor="middle">driving</text>
+	<rect class="box" x="160" y="244" width="204" height="48" rx="8" />
+	<text class="label" x="262" y="264" text-anchor="middle">GetOrderSummaryHandler</text>
+	<text class="note" x="262" y="282" text-anchor="middle">query handler</text>
+	<rect class="box" x="396" y="244" width="200" height="48" rx="8" />
+	<text class="label" x="496" y="264" text-anchor="middle">OrderSummaries</text>
+	<text class="note" x="496" y="282" text-anchor="middle">query repository · a view</text>
+	<path class="link" d="M 128 268 L 158 268" marker-end="url(#application-overview-arrow)" />
+	<path class="link" d="M 364 268 L 394 268" marker-end="url(#application-overview-arrow)" />
+</svg>
+</div>
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span>Change</span>A <a href="/core/application/command-handlers">command handler</a> loads an aggregate, calls it and saves it, inside a <a href="/core/application/unit-of-work">unit of work</a>.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span>Announce</span>An <a href="/core/application/event-translators">event translator</a> turns domain events into <a href="/core/application/integration-events">integration events</a>, stored in the <a href="/core/application/outbox">outbox</a> with the change.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span>Deliver</span>The relay hands them to an <a href="/core/application/event-publishers">event publisher</a>. A <a href="/core/application/query-handlers">query handler</a> reads, on its own path.</div>
+</div>
+
+## The building blocks
+
+| Building block | What it is | Use it when |
+| --- | --- | --- |
+| [Command handlers](./command-handlers.md) | The application service of one use case that changes the system. | A request changes state: create, place, cancel. |
+| [Query handlers](./query-handlers.md) | The application service of one read. | A request only reads. |
+| [Event translators](./event-translators.md) | Turns domain events into integration events. | Other contexts must hear about a change. |
+| [Integration events](./integration-events.md) | What other contexts receive when something happens: JSON. | You define what leaves your context. |
+| [Event publishers](./event-publishers.md) | Sends integration events to the rest of the system. | You plug in a broker, or deliver in process. |
+| [Unit of Work](./unit-of-work.md) | Makes a use case atomic: commit on success, roll back otherwise. | A use case writes more than once, or writes and records events. |
+| [Outbox](./outbox.md) | Stores integration events with the change, then relays them, so none is lost. | Events must not be lost nor sent for a change that failed. |
+
+## See also
+
+- [Domain](../domain/index.md), what the handlers call
+- [Strategic](../strategic/index.md), how contexts meet
+- Rules: [`layers/no-outward-import`](../../rules/layers/no-outward-import.md), [`tactical/no-foreign-command-dependency`](../../rules/tactical/no-foreign-command-dependency.md), [`tactical/no-foreign-query-dependency`](../../rules/tactical/no-foreign-query-dependency.md)

package/docs/core/application/integration-events.md

@@ -0,0 +1,277 @@
+---
+description: "Integration events in Domain-Driven Design with TypeScript: versioned JSON messages that tell other bounded contexts what happened in yours."
+---
+
+# Integration events
+
+An integration event is what other bounded contexts receive when something happens in yours: plain
+JSON with a name, a version and the operation it belongs to.
+
+<dl class="al-glance">
+	<dt>Layer</dt><dd>Published language</dd>
+	<dt>File</dt><dd><code>published-language/order-placed.representation.ts</code></dd>
+	<dt>Type</dt><dd><a href="#api"><code>IntegrationEvent&lt;Type, Payload&gt;</code></a></dd>
+	<dt>Built by</dt><dd><a href="/core/application/event-translators">Event translators</a></dd>
+	<dt>Used by</dt><dd><a href="/core/application/outbox">Outbox</a>, <a href="/core/application/event-publishers">Event publishers</a>, consumers in other contexts</dd>
+	<dt>Checked by</dt><dd><a href="/rules/strategic/no-cross-context-import"><code>strategic/no-cross-context-import</code></a>, <a href="/rules/layers/no-outward-import"><code>layers/no-outward-import</code></a></dd>
+</dl>
+
+## Why
+
+When an order is placed, billing must know. The `OrderPlaced` domain event is a class holding an
+`OrderId` and a `Date`: it cannot be stored in the outbox and read back as is, a broker cannot carry
+it, and billing would have to import your classes to read it. Every change to your model would
+become a change to billing.
+
+::: tip The fix
+An integration event is a JSON type you declare in your
+[published language](../strategic/published-language.md). It is stored, carried and read as is, and
+the consumer shares no code with you. The [domain event](../domain/domain-events.md) stays internal;
+an [event translator](./event-translators.md) builds the integration event from it.
+:::
+
+## How it works
+
+Every integration event carries the same envelope around its payload:
+
+<div class="al-cards al-cards-2">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span>Identity</span><code>id</code> is the id of the domain event. Consumers use it to ignore a duplicate.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span>Contract</span><code>type</code> names the event and <code>version</code> the shape of its payload.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span>Origin</span><code>source</code> is the bounded context, <code>occurredAt</code> the date, as an ISO 8601 string.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">4</span>Tracing</span><code>correlationId</code> is the operation it belongs to; <code>causationId</code> the message that caused it.</div>
+</div>
+
+```json
+{
+	"id": "0b8f6c1e-5d2a-4c4e-9a51-3f7c2e1d9b40",
+	"type": "OrderPlaced",
+	"version": 1,
+	"source": "ordering",
+	"occurredAt": "2026-10-05T09:30:00.000Z",
+	"correlationId": "order-42",
+	"payload": { "orderId": "order-42", "customerId": "customer-7" }
+}
+```
+
+## Where it fits
+
+The integration event is born in the command handler, from a translated domain event, and travels
+as JSON until another context reads it.
+
+<div class="al-diagram">
+<svg viewBox="0 0 680 150" role="img" aria-label="The event translator builds the integration event, the outbox stores it, the event publisher sends it, and the billing context consumes it. The integration event travels as JSON across all of them.">
+	<defs>
+		<marker id="integration-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="24" width="150" height="56" rx="8" />
+	<text class="label" x="83" y="48" text-anchor="middle">Translator</text>
+	<text class="note" x="83" y="68" text-anchor="middle">builds it</text>
+	<path class="link" d="M 158 52 L 180 52" marker-end="url(#integration-flow-arrow)" />
+	<rect class="box" x="182" y="24" width="150" height="56" rx="8" />
+	<text class="label" x="257" y="48" text-anchor="middle">Outbox</text>
+	<text class="note" x="257" y="68" text-anchor="middle">stores it</text>
+	<path class="link" d="M 332 52 L 354 52" marker-end="url(#integration-flow-arrow)" />
+	<rect class="box" x="356" y="24" width="150" height="56" rx="8" />
+	<text class="label" x="431" y="48" text-anchor="middle">Event publisher</text>
+	<text class="note" x="431" y="68" text-anchor="middle">sends it</text>
+	<path class="link" d="M 506 52 L 528 52" marker-end="url(#integration-flow-arrow)" />
+	<rect class="box" x="530" y="24" width="142" height="56" rx="8" />
+	<text class="label" x="601" y="48" text-anchor="middle">Billing</text>
+	<text class="note" x="601" y="68" text-anchor="middle">reads it</text>
+	<rect class="boundary" x="8" y="100" width="664" height="36" rx="8" />
+	<text class="note" x="340" y="123" text-anchor="middle">this page: OrderPlaced v1, the same JSON all the way</text>
+</svg>
+</div>
+
+::: tip
+Delivery is at least once: the same event may arrive twice. Consumers deduplicate by `id`.
+:::
+
+## API
+
+```ts
+import type {
+	IntegrationEvent,
+	PublishedLanguage,
+} from "@alveolus/core";
+// or: from "@alveolus/core/integration-events"
+```
+
+`IntegrationEvent` is a type: nothing exists at runtime. Values are built by an
+[event translator](./event-translators.md).
+
+### Type parameters
+
+```ts
+type IntegrationEvent<
+	Type extends string = string,
+	Payload extends JsonValue = JsonValue,
+> = PublishedLanguage<{ … }>;
+```
+
+| Parameter | What it is | Constraint |
+| --- | --- | --- |
+| `Type` | The name of the event in the contract. | extends `string` |
+| `Payload` | The data of the event. | extends `JsonValue` |
+
+### Fields you declare
+
+| Field | What it is |
+| --- | --- |
+| `type` | The name of the event in the contract, such as `"OrderPlaced"`. A string you choose, not a class name. |
+| `payload` | The data of the event, in JSON only. |
+
+### Fields filled for you
+
+The [event translator](./event-translators.md) fills them through `wrap`.
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `id` | `string` | The id of the domain event, used to deduplicate. |
+| `version` | `number` | The version of the payload schema, given to `wrap`. |
+| `source` | `string` | The bounded context that emitted the event. |
+| `occurredAt` | `string` | When the domain event happened, as an ISO 8601 string. |
+| `correlationId` | `string` | The operation the event belongs to, across contexts. |
+| `causationId` | `string`, optional | The message that caused this event. |
+
+### `IntegrationEventContext` <Badge type="info" text="type" /> <Badge type="tip" text="passed by the command handler" />
+
+```ts
+interface IntegrationEventContext {
+	readonly correlationId: string;
+	readonly causationId?: string;
+}
+```
+
+Passed to `translate`: its values become the `correlationId` and `causationId` of the event.
+Import it from `@alveolus/core` as a type.
+
+### `AnyIntegrationEvent` <Badge type="info" text="type" /> <Badge type="tip" text="used by the outbox and the publisher" />
+
+```ts
+type AnyIntegrationEvent = IntegrationEvent;
+```
+
+Any integration event, whatever its type and payload.
+
+::: warning Caveats
+- One integration event per domain event: both share the same `id`.
+- The payload type is constrained to `JsonValue`: a class, a `Date` or `undefined` does not
+  compile.
+:::
+
+## Usage
+
+Build the event that ordering publishes when an order is placed. 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-start-from-the-domain-event">Start from the domain event</a></span>Know what happened.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span><a href="#_2-name-it-in-the-contract">Name it in the contract</a></span>A type and a name that never change.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span><a href="#_3-publish-what-consumers-need">Publish what consumers need</a></span>Plain fields, nothing internal.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">4</span><a href="#_4-mark-it-as-published-language">Mark it as published language</a></span>Say it is a contract.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">5</span><a href="#_5-build-it-in-a-translator">Build it in a translator</a></span>One place turns events into JSON.</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. Start from the domain event
+
+An integration event announces a [domain event](../domain/domain-events.md), here `OrderPlaced`, to other contexts: it exists first.
+
+### 2. Name it in the contract
+
+Other contexts depend on the name, not on a class: give the event a stable `type` string and a payload in JSON only. The file lives in `published-language/`, where other contexts look.
+
+```ts [src/ordering/published-language/order-placed.representation.ts]
+import type { IntegrationEvent } from "@alveolus/core";
+
+export type OrderPlacedRepresentation = IntegrationEvent<
+	"OrderPlaced",
+	{ readonly orderId: string }
+>;
+```
+
+### 3. Publish what consumers need
+
+A consumer cannot load the order: add every field it needs, as plain JSON values. An identifier or a `Date` would not compile.
+
+```ts [src/ordering/published-language/order-placed.representation.ts]
+import type { IntegrationEvent } from "@alveolus/core";
+
+export type OrderPlacedRepresentation = IntegrationEvent<
+	"OrderPlaced",
+	{ readonly orderId: string } // [!code --]
+	{ readonly orderId: string; readonly customerId: string } // [!code ++]
+>;
+```
+
+### 4. Mark it as published language
+
+`PublishedLanguage` says that this type is a contract with other contexts: changing it means a new `version`, not an edit.
+
+```ts [src/ordering/published-language/order-placed.representation.ts]
+import type { IntegrationEvent } from "@alveolus/core"; // [!code --]
+import type { // [!code ++]
+	IntegrationEvent, // [!code ++]
+	PublishedLanguage, // [!code ++]
+} from "@alveolus/core"; // [!code ++]
+
+export type OrderPlacedRepresentation = IntegrationEvent< // [!code --]
+	"OrderPlaced", // [!code --]
+	{ readonly orderId: string; readonly customerId: string } // [!code --]
+export type OrderPlacedRepresentation = PublishedLanguage< // [!code ++]
+	IntegrationEvent< // [!code ++]
+		"OrderPlaced", // [!code ++]
+		{ readonly orderId: string; readonly customerId: string } // [!code ++]
+	> // [!code ++]
+>;
+```
+
+This is the complete representation.
+
+### 5. Build it in a translator
+
+The [event translator](./event-translators.md#usage) builds the value, and the outbox stores it as this JSON:
+
+```json
+{
+	"id": "0b9f6c1e-4d1a-4c8e-9a51-2f3e7d6b8a10",
+	"type": "OrderPlaced",
+	"version": 1,
+	"source": "ordering",
+	"occurredAt": "2026-10-06T09:30:00.000Z",
+	"correlationId": "o-42",
+	"payload": { "orderId": "o-42", "customerId": "c-7" }
+}
+```
+
+### 6. Check it
+
+Run the checks. Two rules keep the representation 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/strategic/no-cross-context-import"><code>no-cross-context-import</code></a></span>A consumer redeclares the fields it reads: it never imports this type.</div>
+<div class="al-card"><span class="al-card-title"><a href="../../rules/layers/no-outward-import"><code>no-outward-import</code></a></span>The published language imports only its own types and the published-language types of core.</div>
+</div>
+
+A consumer that imports it from ordering is reported:
+
+```
+src/shipping/published-language/order-placed.representation.ts
+  1  error  strategic/no-cross-context-import: Imports the published
+  language of ordering: redeclare the fields you read in your
+  own published-language/.
+```
+
+## See also
+
+- [Event translators](./event-translators.md), which build integration events
+- [Outbox](./outbox.md) and [Event publishers](./event-publishers.md), which store and send them
+- [Domain events](../domain/domain-events.md), what they are built from
+- [Published Language](../strategic/published-language.md), where they are declared
+- Rules: [`strategic/no-cross-context-import`](../../rules/strategic/no-cross-context-import.md), [`layers/no-outward-import`](../../rules/layers/no-outward-import.md)