@alveolus/arch 0.3.0 → 0.5.0

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

@@ -10,8 +10,8 @@ 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; without a map, an import that closes a cycle between contexts</dd>
-	<dt>Applies to</dt><dd>Every file of every bounded context</dd>
+	<dt>Reports</dt><dd>An import of another context, or a value of another context given in the wiring, that <code>contextMap</code> does not allow</dd>
+	<dt>Applies to</dt><dd>Every file of every bounded context; for the wiring, the composition roots and the files at the root of <code>src/</code></dd>
 	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"strategic/no-unmapped-context": "off"</code></a></dd>
 </dl>
 
@@ -24,40 +24,68 @@ extracted or rewritten without the other. In a system that lives for years, that
 turns "change this module" into "rewrite the application".
 
 ::: tip The fix
-Write the context map, as DDD asks: which context is upstream of which. Declare it in
-`alveolus.config.ts`, and the code can no longer stray from it. A dependency that goes against
-the map is reversed: `Ledger` publishes an event, `Payments` reacts.
+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:
+composition root alike: the importing context lists the imported one under `consumes` in
+`contextMap`.
 
-<div class="al-cards al-cards-2">
-<div class="al-card"><span class="al-card-title">With a context map</span>The importing context lists the imported one in <code>contextMap</code>. The map itself is checked when the configuration loads: an unknown context or a cycle is an error.</div>
-<div class="al-card"><span class="al-card-title">Without a context map</span>The imports observed form no cycle. An import that closes one is reported at both ends.</div>
-</div>
+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.
 
+### The wiring counts too
+
+A context can consume another one without importing it: `app.module.ts` sees every module, and
+can hand a value of one context to another. Ledger declares a port, its adapter calls whatever it
+is given, and the root composition gives it a handler of e-money:
+
+```ts [src/app.module.ts]
+this.ledger = new LedgerModule({
+	redemptions: () => this.emoney.commands.requestRedemption,
+});
+```
+
+No file of ledger imports e-money, yet ledger now consumes it. In the composition roots and the
+files at the root of `src/`, every value given to a class, a function or a field of one context
+(an argument, a property of an object, the body of an arrow function, an assignment, a variable
+typed by that context) is read: when it comes from another context, by where it is declared or by
+its type, the receiving context consumes that one, and the map must say so. A module handed whole,
+such as `new PaymentsModule(this.ledger)`, is not a consumption yet: what that module then takes
+from it is.
+
 ## 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: add payments to contextMap.ledger, or
-     reverse the dependency.
+     context map does not allow: reverse the dependency, or if ledger
+     really is downstream of payments, add payments to
+     contextMap.ledger.consumes.
+
+src/app.module.ts
+ 14  error  strategic/no-unmapped-context: ledger receives
+     this.emoney.commands.requestRedemption from emoney here, which the
+     context map does not allow: reverse the dependency, or if ledger
+     really is downstream of emoney, add emoney to
+     contextMap.ledger.consumes.
 ```
 
-Without a map:
+A map that would allow it is refused before the check:
 
 ```
-src/ledger/driven/payments/adapters/payment-status.adapter.ts
-  2  error  strategic/no-unmapped-context: ledger consumes payments, which
-     consumes ledger back: two contexts that depend on each other can
-     no longer change alone; declare a contextMap and reverse one
-     dependency.
+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
@@ -65,21 +93,23 @@ src/ledger/driven/payments/adapters/payment-status.adapter.ts
 ### 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:
+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: [],
-		ledger: ["customers"],
-		payments: ["ledger", "customers"],
+		customers: { consumes: [] },
+		ledger: { consumes: ["customers"] },
+		payments: { consumes: ["ledger", "customers"] },
 	},
 	root: "src",
+	subdomains: { core: ["ledger", "payments"], generic: ["customers"] },
 });
 ```
 
-A context absent from the map consumes nothing.
+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
 
@@ -91,8 +121,14 @@ So that `Ledger` stays upstream, it does not ask `Payments` anything: it publish
 
 ::: 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.
+  written as a string: the map covers imports and the wiring. In review, every consumption of
+  another context is an import of its open host service.
+- A value whose type is erased on the way: a cast (`as unknown as Handler`, `any`) in the
+  composition root, or a container token written as a string, such as NestJS
+  `{ provide: "redemptions", useFactory: … }`. In review, the composition root holds no cast, and
+  a token is the abstract class of a port.
+- With the rule off, the wiring is no longer checked against the map, even though
+  [`strategic/no-cross-context-import`](./no-cross-context-import.md) still checks what crosses.
 :::
 
 ## Turn it off

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

@@ -17,12 +17,20 @@ A query handler receives what reads: nothing that writes or changes state.
 ## 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 or a domain service injected into it
-does the same, one step removed.
+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.
+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
@@ -78,6 +86,91 @@ constructor(private readonly summaries: OrderSummaries) {
 
 </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
@@ -101,6 +194,8 @@ new queries keep to reading while you split the old ones.
 - [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

package/package.json

@@ -48,7 +48,7 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "scripts": {
     "build": "tsdown && biome check --write package.json",
     "typecheck": "tsc -p tsconfig.json"