@alveolus/arch 0.2.0 → 0.4.0

package/docs/rules/strategic/no-unmapped-context.md

@@ -0,0 +1,114 @@
+---
+description: "Architecture rule: a bounded context consumes only the contexts its context map declares, and two contexts never depend on each other."
+---
+
+# no-unmapped-context
+
+A bounded context consumes the contexts its context map declares, and nothing else: two contexts
+never depend on each other.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>strategic/no-unmapped-context</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#strategic">Strategic</a>: what crosses a bounded context</dd>
+	<dt>Reports</dt><dd>An import of another context that <code>contextMap</code> does not allow</dd>
+	<dt>Applies to</dt><dd>Every file of every bounded context</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"strategic/no-unmapped-context": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`Payments` reads balances from `Ledger`, through its open host service, as it should. A year
+later `Ledger` asks `Payments` whether a transfer is pending, through *its* open host service.
+Each import is clean on its own; together they tie the two contexts: neither can be deployed,
+extracted or rewritten without the other. In a system that lives for years, that knot is what
+turns "change this module" into "rewrite the application".
+
+::: tip The fix
+Write the context map, as DDD asks: which context is upstream of which. `alveolus.config.ts`
+requires it, so the code can no longer stray from it. A dependency that goes against the map is
+reversed: `Ledger` publishes an event, `Payments` reacts. Adding a line to the map is the other
+way out, and it is a strategic decision: take it in a review, not in a fix.
+:::
+
+## What it checks
+
+Every import from a file of one bounded context to a file of another, open host service or
+composition root alike: the importing context lists the imported one under `consumes` in
+`contextMap`.
+
+The map itself is checked when the configuration loads, before any rule runs: a context left out
+of the map, a context the map names that `boundedContexts` does not declare, a context that
+consumes itself, or a cycle, is an error. Two contexts that depend on each other are therefore
+never allowed, whichever way the code is written.
+
+Imports of the shared kernel are not consumptions: every context may import it.
+
+## What it reports
+
+```
+src/ledger/driven/payments/adapters/payment-status.adapter.ts
+  2  error  strategic/no-unmapped-context: ledger consumes payments, which the
+     context map does not allow: reverse the dependency, or if ledger
+     really is downstream of payments, add payments to
+     contextMap.ledger.consumes.
+```
+
+A map that would allow it is refused before the check:
+
+```
+Invalid configuration in alveolus.config.ts:
+contextMap has a cycle: ledger → payments → ledger. Two contexts that depend
+on each other can no longer change alone: reverse one dependency.
+```
+
+## Fix it
+
+### Declare the context map
+
+So that the direction of every dependency is a decision, not an accident, list for each context
+the ones it consumes. Each line reads as a sentence: `payments` consumes `ledger` and `customers`.
+
+```ts [alveolus.config.ts]
+export default defineConfig({
+	boundedContexts: { customers: "customers", ledger: "ledger", payments: "payments" },
+	contextMap: {
+		customers: { consumes: [] },
+		ledger: { consumes: ["customers"] },
+		payments: { consumes: ["ledger", "customers"] },
+	},
+	root: "src",
+	subdomains: { core: ["ledger", "payments"], generic: ["customers"] },
+});
+```
+
+Every context is in the map. `consumes: []` is a decision too: that context goes its separate
+way, and the day it needs another one, the import is reported and the map is updated on purpose.
+
+### Reverse a dependency with an event
+
+So that `Ledger` stays upstream, it does not ask `Payments` anything: it publishes
+`TransferSettled` in its [published language](../../core/strategic/published-language.md), and
+`Payments` reacts to it.
+
+## Limits
+
+::: warning What the rule cannot see
+- A dependency that goes through the database, a queue or an HTTP call to another context's API
+  written as a string: the map covers imports. In review, every consumption of another context
+  is an import of its open host service.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "strategic/no-unmapped-context": "off" },
+```
+
+## See also
+
+- [Open host services](../../core/strategic/open-host-services.md) and
+  [Anti-corruption layers](../../core/strategic/anti-corruption-layers.md), how a context consumes another
+- [`strategic/no-cross-context-import`](./no-cross-context-import.md), which keeps the open host
+  service the only door
+- Vaughn Vernon, *Domain-Driven Design Distilled*, chapter 4, "Strategic Design with Context Mapping"
+- [Rules](../index.md), every rule by category

package/docs/rules/tactical/no-aggregate-reference.md

@@ -0,0 +1,139 @@
+---
+description: "Architecture rule: an aggregate refers to another aggregate by its identifier, never by holding it, to keep transactions and loading small."
+---
+
+# no-aggregate-reference
+
+An aggregate refers to another aggregate by its identifier, never by holding it.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-aggregate-reference</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A building block holding another aggregate, an entity held by two aggregates</dd>
+	<dt>Applies to</dt><dd>Every class that extends <code>AggregateRoot</code>, <code>Entity</code>, <code>ValueObject</code> or <code>DomainEvent</code>, in core bounded contexts and the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-aggregate-reference": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`Order` holds a `Customer`. The next handler that places an order also updates the customer, in
+the same transaction, because it is right there. Loading an order now drags the customer along,
+two users editing either one conflict, and the two boundaries have merged without anyone deciding
+it.
+
+::: tip The fix
+The order keeps a `CustomerId`. Each aggregate stays a consistency boundary of its own, loaded,
+changed and saved alone. The command handler loads the customer when it really needs it, and
+changes to it happen in their own transaction, usually in reaction to an event.
+:::
+
+## What it checks
+
+### No aggregate held
+
+In every aggregate, entity, value object and domain event, no property, no constructor parameter,
+no value object props and no event payload holds another aggregate, however deep it is:
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title">Alone or in a union</span><code>customer: Customer | undefined</code></div>
+<div class="al-card"><span class="al-card-title">In a generic</span>An array, a tuple, a <code>Map</code>, a <code>Record</code>, a <code>Pick</code>, a <code>Promise</code>, or a generic of your own.</div>
+<div class="al-card"><span class="al-card-title">In an object type</span><code>{ customer: Customer }</code>, or an interface of the project.</div>
+<div class="al-card"><span class="al-card-title">Loaded lazily</span><code>load: () =&gt; Promise&lt;Customer&gt;</code>: what a function returns counts.</div>
+<div class="al-card"><span class="al-card-title">In value object props</span><code>ValueObject&lt;{ customer: Customer }&gt;</code></div>
+<div class="al-card"><span class="al-card-title">In an event payload</span><code>DomainEvent&lt;OrderId, { customer: Customer }&gt;</code></div>
+</div>
+
+The parameters of a function do not count: `onChange: (customer: Customer) => void` receives a
+customer, it does not hold one.
+
+### One owner per entity
+
+An entity other than a root belongs to one aggregate. The rule finds every entity each aggregate
+holds, directly or through its entities and value objects, and reports an entity held by two
+aggregates: the `Address` of a `Customer` cannot be held by an `Order` too.
+
+## What it reports
+
+```
+src/ordering/domain/aggregates/order.aggregate.ts
+  6  error  tactical/no-aggregate-reference: Order.customer holds the
+  aggregate Customer: reference it by its identifier instead.
+
+src/ordering/domain/value-objects/buyer.value-object.ts
+  3  error  tactical/no-aggregate-reference: Buyer holds the aggregate
+  Customer in its Props: reference it by its identifier instead.
+
+src/ordering/domain/aggregates/order.aggregate.ts
+  8  error  tactical/no-aggregate-reference: Order.shipping holds the entity
+  Address, which Customer holds too: an entity belongs to one
+  aggregate.
+```
+
+## Fix it
+
+### Hold the identifier instead
+
+So that each aggregate stays its own boundary, replace the property with the
+[identifier](../../core/domain/value-objects.md#identifier) of the other aggregate, and put that
+identifier in the snapshot.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/aggregates/order.aggregate.ts]
+import { AggregateRoot } from "@alveolus/core";
+
+import type { Customer } from "./customer.aggregate";
+
+export class Order extends AggregateRoot<OrderId> {
+	private readonly customer: Customer;
+}
+```
+
+```ts [✅ Prefer: src/ordering/domain/aggregates/order.aggregate.ts]
+import { AggregateRoot } from "@alveolus/core";
+
+import type { CustomerId } from "../value-objects/customer-id.identifier";
+
+export class Order extends AggregateRoot<OrderId> {
+	private readonly customerId: CustomerId;
+}
+```
+
+</div>
+
+### Give each aggregate its own entity
+
+When two aggregates need the same kind of data, each one owns its own: the customer keeps its
+`Address` entity, the order keeps a `ShippingAddress` value object copied from it when the order
+is placed. Changing the customer's address no longer changes past orders.
+
+### Load the other aggregate in the handler
+
+When a rule needs data from the other aggregate, the
+[command handler](../../core/application/command-handlers.md) loads it through its repository and
+passes what the rule needs to the business method. When the other aggregate must change too, a
+second handler does it on the event, in its own transaction.
+
+## Limits
+
+::: warning What the rule cannot see
+- An interface with the shape of another aggregate, such as `CustomerLike`: TypeScript types are
+  structural, so the rule cannot tell that a `Customer` will be passed in. Hold the identifier.
+- The parameters of a callback are not followed: `onChange: (customer: Customer) => void` is
+  accepted, and a closure can still capture the aggregate it receives.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-aggregate-reference": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new code keeps the rule while you rework the old references.
+
+## See also
+
+- [Aggregates: refer to other aggregates by identity](../../core/domain/aggregates.md)
+- [`tactical/no-thrown-failure`](./no-thrown-failure.md), another rule on aggregates
+- [Rules](../index.md), every rule by category

package/docs/rules/tactical/no-foreign-command-dependency.md

@@ -0,0 +1,119 @@
+---
+description: "Architecture rule for command handlers: a command handler receives command repositories, ports, event translators, domain services and value objects, never a view or another handler."
+---
+
+# no-foreign-command-dependency
+
+A command handler receives what changes aggregates and what they need: nothing that reads views,
+and no other handler.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-foreign-command-dependency</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A command handler that receives a query repository, another handler or a class that is no building block</dd>
+	<dt>Applies to</dt><dd>The constructor parameters and fields of every <code>CommandHandler</code> of a core bounded context or the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-foreign-command-dependency": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`PlaceOrderHandler` checks the order summary to decide whether the order may be placed. The view is
+shaped for reading: it may be denormalised, stale or partial, and it protects no rule. Injecting
+`GetOrderSummaryHandler` instead changes nothing, and injecting `PayOrderHandler` hides a second
+transaction inside the first one.
+
+::: tip The fix
+A command loads the aggregate and lets it decide. What a handler may receive is a short list:
+everything else is reported, so a new way of reaching a view does not slip through.
+:::
+
+## What it checks
+
+Every constructor parameter and every field of each `CommandHandler`, followed into `Pick`,
+generics and objects such as `deps: { … }`:
+
+| Receives | Allowed |
+| --- | --- |
+| A `CommandRepository` | ✅ |
+| A `Port`: `Clock`, `IdGenerator`, `UnitOfWork`, `Outbox`, your own ports | ✅ |
+| An `EventTranslator`, a `DomainService` | ✅ |
+| A value object, an identifier, a plain value such as a `number` | ✅ |
+| A class of a package listed in `applicationDependencies` | ✅ |
+| A `QueryRepository`, even though it is a `Port` | ❌ |
+| An `EventPublisher`, even though it is a `Port`: events leave through the outbox, and the relay publishes them | ❌ |
+| A `CommandHandler` or a `QueryHandler` | ❌ |
+| Any other class of the project | ❌ |
+
+A parameter counts by what its type extends: `OrderSummaries` extends
+`QueryRepository<OrderSummary>`.
+
+## What it reports
+
+```
+src/ordering/application/commands/place-order.command.ts
+  2  error  tactical/no-foreign-command-dependency: The CommandHandler
+  PlaceOrderHandler receives OrderSummaries, a QueryRepository: a
+  command handler receives command repositories, ports, event
+  translators, domain services and value objects.
+```
+
+## Fix it
+
+### Decide from the aggregate
+
+So that the decision is taken by what keeps the rules, a command handler loads the aggregate
+through its [command repository](../../core/domain/repositories.md) and lets it decide.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/application/commands/place-order.command.ts]
+export class PlaceOrderHandler extends CommandHandler<PlaceOrder> {
+	constructor(private readonly summaries: OrderSummaries) {
+		super();
+	}
+}
+```
+
+```ts [✅ Prefer: src/ordering/application/commands/place-order.command.ts]
+export class PlaceOrderHandler extends CommandHandler<PlaceOrder> {
+	constructor(private readonly orders: Orders) {
+		super();
+	}
+}
+```
+
+</div>
+
+### React to an event instead of calling another handler
+
+So that each command stays one transaction, a handler never calls another one. When placing an
+order must also do something else, the other handler reacts to the domain event, in its own
+transaction.
+
+## Limits
+
+::: warning What the rule cannot see
+- A plain `Port` whose adapter reads the views: the rule sees a port, not what its adapter does.
+  In review, a port named like a read (`OrderStats`, `…Summary`) used by a command is a query in
+  disguise.
+- An interface that a query repository happens to satisfy: an interface is no class, so the rule
+  cannot tell what will be injected. Type dependencies with the port class itself.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-foreign-command-dependency": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new commands keep to their list while you rework the old ones.
+
+## See also
+
+- [Command handlers](../../core/application/command-handlers.md), what is checked
+- [Repositories](../../core/domain/repositories.md) and [Ports](../../core/domain/ports.md), what a
+  command handler receives
+- [`tactical/no-foreign-query-dependency`](./no-foreign-query-dependency.md), the same list for
+  query handlers
+- [Rules](../index.md), every rule by category

package/docs/rules/tactical/no-foreign-query-dependency.md

@@ -0,0 +1,201 @@
+---
+description: "Architecture rule for query handlers: a query handler receives query repositories, ports that do not write and value objects, never what changes state."
+---
+
+# no-foreign-query-dependency
+
+A query handler receives what reads: nothing that writes or changes state.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-foreign-query-dependency</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A query handler that receives a command repository, an outbox, a unit of work, an event publisher, a handler, a domain service, an event translator or a class that is no building block</dd>
+	<dt>Applies to</dt><dd>The constructor parameters and fields of every <code>QueryHandler</code> of a core bounded context or the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-foreign-query-dependency": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`GetOrderSummaryHandler` receives the unit of work: a read can now change state, and the caller who
+asked a question gets a side effect too. A command handler injected into it does the same, one
+step removed.
+
+A domain service is different: it is pure, so injecting it changes nothing. What it changes is
+where the business rule runs. `GetSafeguardingReconciliationHandler` receives
+`SafeguardingReconciliation` and computes the reconciliation at each read: two readers at two
+moments see two different results, nothing records which one was reported, and the rule now runs
+on two paths, the command's and the query's, that drift apart. The read side delivers data shaped
+for the reader; the domain's behaviour runs on the write side, once, and leaves a fact.
+
+::: tip The fix
+A query reads a view through a query repository, and writes nothing. A query that seems to need a
+write is a command, or a command followed by a query. A query that seems to need a domain service
+is reading a fact nobody recorded, or holding a calculation that belongs to a value object.
+:::
+
+## What it checks
+
+Every constructor parameter and every field of each `QueryHandler`, followed into `Pick`,
+generics and objects such as `deps: { … }`:
+
+| Receives | Allowed |
+| --- | --- |
+| A `QueryRepository` | ✅ |
+| A `Port` that does not write, such as `Clock` or your own ports | ✅ |
+| A value object, an identifier, a plain value such as a `number` | ✅ |
+| A class of a package listed in `applicationDependencies` | ✅ |
+| A `CommandRepository`, an `Outbox`, a `UnitOfWork`, an `EventPublisher` | ❌ |
+| A `CommandHandler`, a `QueryHandler`, a `DomainService`, an `EventTranslator` | ❌ |
+| Any other class of the project | ❌ |
+
+A parameter counts by what its type extends: `Orders` extends `CommandRepository<Order>`.
+
+## What it reports
+
+```
+src/ordering/application/queries/get-order-summary.query.ts
+  3  error  tactical/no-foreign-query-dependency: The QueryHandler
+  GetOrderSummaryHandler receives UnitOfWork, a UnitOfWork: a query
+  handler receives query repositories, ports that do not write, and
+  value objects.
+```
+
+## Fix it
+
+### Read a view, and nothing else
+
+So that a read never changes state, a [query handler](../../core/application/query-handlers.md)
+receives only query repositories.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/application/queries/get-order-summary.query.ts]
+constructor(
+	private readonly summaries: OrderSummaries,
+	private readonly unitOfWork: UnitOfWork,
+) {
+	super();
+}
+```
+
+```ts [✅ Prefer: src/ordering/application/queries/get-order-summary.query.ts]
+constructor(private readonly summaries: OrderSummaries) {
+	super();
+}
+```
+
+</div>
+
+### Record the fact, then read it
+
+So that a result the reader relies on exists once, with its date, a domain service runs in a
+command handler that records its outcome, and the query reads the record. A reconciliation, a
+regulatory figure, a score: when the reader asks "what was it", the answer is a fact to keep, not
+a calculation to redo.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/safeguarding/application/queries/get-reconciliation.query.ts]
+constructor(
+	private readonly balances: SafeguardingBalances,
+	private readonly reconciliation: SafeguardingReconciliation,
+) {
+	super();
+}
+
+async handle(query: GetReconciliation): Promise<Result<ReconciliationView, NotFound>> {
+	const balances = await this.balances.on(query.date);
+	return ok(this.reconciliation.reconcile(balances));
+}
+```
+
+```ts [✅ Prefer: src/safeguarding/application/commands/reconcile-safeguarding.command.ts]
+constructor(
+	private readonly accounts: SafeguardingAccounts,
+	private readonly reconciliation: SafeguardingReconciliation,
+	private readonly unitOfWork: UnitOfWork,
+) {
+	super();
+}
+
+async handle(command: ReconcileSafeguarding): Promise<Result<void, NotFound>> {
+	const account = await this.accounts.of(command.accountId);
+	account.reconcile(this.reconciliation.reconcile(account.balances()), command.at);
+	await this.unitOfWork.commit();
+	return ok();
+}
+```
+
+</div>
+
+The query handler then receives `Reconciliations`, a query repository, and returns the
+reconciliation of the date asked. The aggregate records the outcome, so the domain service keeps
+one caller.
+
+### Move a calculation into a value object
+
+So that a figure derived from the values of a view is computed where values are computed, the
+calculation becomes a static factory of a [value object](../../core/domain/value-objects.md),
+which a query may use: a projection, a conversion, a total. Nothing is recorded because nothing
+happened.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/safeguarding/application/queries/get-own-funds-requirement.query.ts]
+constructor(
+	private readonly figures: SafeguardingFigures,
+	private readonly calculator: OwnFundsRequirementCalculator,
+) {
+	super();
+}
+
+async handle(query: GetOwnFundsRequirement): Promise<Result<OwnFundsRequirementView, NotFound>> {
+	const figures = await this.figures.of(query.firmId);
+	return ok({ amount: this.calculator.compute(figures) });
+}
+```
+
+```ts [✅ Prefer: src/safeguarding/application/queries/get-own-funds-requirement.query.ts]
+constructor(private readonly figures: SafeguardingFigures) {
+	super();
+}
+
+async handle(query: GetOwnFundsRequirement): Promise<Result<OwnFundsRequirementView, NotFound>> {
+	const figures = await this.figures.of(query.firmId);
+	return ok({ amount: OwnFundsRequirement.of(figures).amount });
+}
+```
+
+</div>
+
+Which of the two? If the reader asks for the figure as it was declared or decided, record it. If
+the reader asks what the figure would be from the values on the screen, calculate it.
+
+## Limits
+
+::: warning What the rule cannot see
+- A plain `Port` whose adapter writes: the rule sees a port, not what its adapter does. In review,
+  a port with a verb such as `mark…`, `record…` or `save…` has no place in a query.
+- An interface that a command repository happens to satisfy: an interface is no class, so the rule
+  cannot tell what will be injected. Type dependencies with the port class itself.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-foreign-query-dependency": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new queries keep to reading while you split the old ones.
+
+## See also
+
+- [Query handlers](../../core/application/query-handlers.md), what is checked
+- [Repositories](../../core/domain/repositories.md) and [Views](../../core/domain/views.md), what
+  a query reads
+- [Domain services](../../core/domain/domain-services.md), called by the command handler, and
+  [value objects](../../core/domain/value-objects.md), the home of a calculation
+- [`tactical/no-foreign-command-dependency`](./no-foreign-command-dependency.md), the same list for
+  command handlers
+- [Rules](../index.md), every rule by category