@alveolus/arch 0.1.0 → 0.3.0

package/docs/core/application/query-handlers.md

@@ -0,0 +1,292 @@
+---
+description: "Query handlers in CQRS with TypeScript: run one read that returns a view through a query repository, without loading aggregates or changing anything."
+---
+
+# Query handlers
+
+A query handler runs one read: it returns a [view](../domain/views.md) read through a query
+repository, without loading the aggregate and without changing anything.
+
+<dl class="al-glance">
+	<dt>Layer</dt><dd>Application</dd>
+	<dt>File</dt><dd><code>application/queries/get-order-summary.query.ts</code></dd>
+	<dt>Extends</dt><dd><a href="#api"><code>QueryHandler&lt;Input, Output, Error&gt;</code></a></dd>
+	<dt>Called by</dt><dd>Driving adapters: controllers, resolvers, scripts</dd>
+	<dt>Checked by</dt><dd><a href="/rules/tactical/no-misplaced-class"><code>tactical/no-misplaced-class</code></a>, <a href="/rules/tactical/no-foreign-query-dependency"><code>tactical/no-foreign-query-dependency</code></a>, <a href="/rules/layers/no-outward-import"><code>layers/no-outward-import</code></a></dd>
+</dl>
+
+## Why
+
+A screen lists the latest orders with their status and number of lines. Built from the `Order`
+aggregate, it loads every order with all its lines, then asks the aggregate for getters it only
+exposes for that screen. The aggregate grows to serve displays, and every read pays for rules it
+never uses.
+
+::: tip The fix
+A query handler reads a view: a plain shape built for the reader, read straight from storage
+through a query repository. The aggregate is not loaded, and nothing is saved or published.
+:::
+
+## How it works
+
+A query handler receives a query, the data of one read, and returns a
+[`Result`](../utilities/result.md):
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span>Read the view</span>Ask a <a href="/core/domain/repositories">query repository</a> for the view, in the shape the reader needs.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span>Handle what is missing</span>When nothing matches, return a <a href="/core/domain/domain-errors">domain error</a>.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span>Return it</span>Return the view in a <code>Result</code>. Nothing else happens.</div>
+</div>
+
+```ts
+async handle({
+	orderId,
+}: GetOrderSummary): Promise<Result<OrderSummary, OrderNotFound>> {
+	const summary = await this.summaries.summaryOf(new OrderId(orderId));
+	if (summary === undefined) {
+		return err(new OrderNotFound({ orderId }));
+	}
+	return ok(summary);
+}
+```
+
+## Where it fits
+
+A query takes its own path through the system. The command side, with its aggregates, unit of
+work and outbox, is never involved.
+
+<div class="al-diagram">
+<svg viewBox="0 0 680 150" role="img" aria-label="A controller calls the GetOrderSummaryHandler, which reads an OrderSummary view through the OrderSummaries query repository, which reads the storage.">
+	<defs>
+		<marker id="query-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="40" width="130" height="56" rx="8" />
+	<text class="label" x="73" y="64" text-anchor="middle">Controller</text>
+	<text class="note" x="73" y="84" text-anchor="middle">driving adapter</text>
+	<path class="link" d="M 138 68 L 164 68" marker-end="url(#query-flow-arrow)" />
+	<rect class="boundary" x="166" y="40" width="190" height="56" rx="8" />
+	<text class="label" x="261" y="64" text-anchor="middle">GetOrderSummaryHandler</text>
+	<text class="note" x="261" y="84" text-anchor="middle">this page</text>
+	<path class="link" d="M 356 68 L 382 68" marker-end="url(#query-flow-arrow)" />
+	<rect class="box" x="384" y="40" width="160" height="56" rx="8" />
+	<text class="label" x="464" y="64" text-anchor="middle">OrderSummaries</text>
+	<text class="note" x="464" y="84" text-anchor="middle">query repository</text>
+	<path class="link" d="M 544 68 L 570 68" marker-end="url(#query-flow-arrow)" />
+	<rect class="box" x="572" y="40" width="100" height="56" rx="8" />
+	<text class="label" x="622" y="64" text-anchor="middle">Storage</text>
+	<text class="note" x="622" y="84" text-anchor="middle">tables</text>
+	<text class="note" x="340" y="130" text-anchor="middle">returns OrderSummary, a view: no aggregate loaded</text>
+</svg>
+</div>
+
+::: tip
+A query handler only receives query repositories. It cannot change state, even by mistake.
+:::
+
+## API
+
+```ts
+import { QueryHandler } from "@alveolus/core";
+// or: import { QueryHandler } from "@alveolus/core/query-handlers";
+```
+
+### Type parameters
+
+```ts
+abstract class QueryHandler<
+	Input,
+	Output,
+	Error extends AnyDomainError = never,
+> { … }
+```
+
+| Parameter | What it is | Constraint |
+| --- | --- | --- |
+| `Input` | The query: the data the handler needs. | any type |
+| `Output` | What the read returns, usually a view or a list of views. | any type |
+| `Error` | The union of the [domain errors](../domain/domain-errors.md) it may return. | extends `DomainError`; `never` by default |
+
+### `constructor(…)` <Badge type="tip" text="you implement it" />
+
+```ts
+constructor(private readonly summaries: OrderSummaries) {
+	super();
+}
+```
+
+`QueryHandler` declares no constructor: yours takes the query repositories it reads and calls
+`super()`.
+
+### `handle(query)` <Badge type="info" text="abstract" /> <Badge type="tip" text="you implement it" /> <Badge type="tip" text="called by a driving adapter" />
+
+```ts
+abstract handle(query: Input): Promise<Result<Output, Error>>
+```
+
+Runs the read and returns its outcome. The driving adapter that calls it turns the `Result` into
+a response.
+
+::: warning Caveats
+- There is no separate read model: views are read from the same storage, through a query
+  repository.
+- `Output` has no default, unlike `CommandHandler`: a read always returns something.
+:::
+
+## Usage
+
+Build the handler that reads the summary of an order. 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-prepare-the-view">Prepare the view</a></span>Know what the screen reads.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span><a href="#_2-declare-the-query">Declare the query</a></span>Say what the caller provides.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span><a href="#_3-declare-the-handler">Declare the handler</a></span>One class, one question.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">4</span><a href="#_4-return-a-missing-view-as-a-failure">Return a missing view as a failure</a></span>No undefined for callers to check.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">5</span><a href="#_5-call-it-from-a-driving-adapter">Call it from a driving adapter</a></span>Turn the Result into a response.</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. Prepare the view
+
+A query reads a [view](../domain/views.md), `OrderSummary`, through a query [repository](../domain/repositories.md), `OrderSummaries`: declare them first.
+
+### 2. Declare the query
+
+So that a driving adapter knows what to provide, the query is a plain type named after the question, in the file of its handler.
+
+```ts [src/ordering/application/queries/get-order-summary.query.ts]
+export interface GetOrderSummary {
+	readonly orderId: string;
+}
+```
+
+### 3. Declare the handler
+
+The handler extends `QueryHandler` and receives the query repository as an abstract class. It reads the view and returns it, without loading an aggregate.
+
+```ts [src/ordering/application/queries/get-order-summary.query.ts]
+import { ok, QueryHandler, type Result } from "@alveolus/core"; // [!code ++]
+
+import { // [!code ++]
+	OrderSummaries, // [!code ++]
+} from "../../domain/repositories/order-summaries.repository"; // [!code ++]
+import { OrderId } from "../../domain/value-objects/order-id.identifier"; // [!code ++]
+import type { OrderSummary } from "../../domain/views/order-summary.view"; // [!code ++]
+
+export interface GetOrderSummary {
+	readonly orderId: string;
+}
+
+export class GetOrderSummaryHandler extends QueryHandler< // [!code ++]
+	GetOrderSummary, // [!code ++]
+	OrderSummary | undefined // [!code ++]
+> { // [!code ++]
+	constructor(private readonly summaries: OrderSummaries) { // [!code ++]
+		super(); // [!code ++]
+	} // [!code ++]
+
+	async handle({ // [!code ++]
+		orderId, // [!code ++]
+	}: GetOrderSummary): Promise< // [!code ++]
+		Result<OrderSummary | undefined, never> // [!code ++]
+	> { // [!code ++]
+		return ok( // [!code ++]
+			await this.summaries.summaryOf(new OrderId(orderId)), // [!code ++]
+		); // [!code ++]
+	} // [!code ++]
+} // [!code ++]
+```
+
+### 4. Return a missing view as a failure
+
+Returning `undefined` pushes the check to every caller, who may forget it. The handler declares `OrderNotFound` instead, so the signature says what can go wrong.
+
+```ts [src/ordering/application/queries/get-order-summary.query.ts]
+import { ok, QueryHandler, type Result } from "@alveolus/core"; // [!code --]
+import { err, ok, QueryHandler, type Result } from "@alveolus/core"; // [!code ++]
+
+import { OrderNotFound } from "../../domain/errors/order-not-found.error"; // [!code ++]
+import {
+	OrderSummaries,
+} from "../../domain/repositories/order-summaries.repository";
+import { OrderId } from "../../domain/value-objects/order-id.identifier";
+import type { OrderSummary } from "../../domain/views/order-summary.view";
+
+export interface GetOrderSummary {
+	readonly orderId: string;
+}
+
+export class GetOrderSummaryHandler extends QueryHandler<
+	GetOrderSummary,
+	OrderSummary | undefined // [!code --]
+	OrderSummary, // [!code ++]
+	OrderNotFound // [!code ++]
+> {
+	constructor(private readonly summaries: OrderSummaries) {
+		super();
+	}
+
+	async handle({
+		orderId,
+	}: GetOrderSummary): Promise< // [!code --]
+		Result<OrderSummary | undefined, never> // [!code --]
+	> { // [!code --]
+		return ok( // [!code --]
+			await this.summaries.summaryOf(new OrderId(orderId)), // [!code --]
+	}: GetOrderSummary): Promise<Result<OrderSummary, OrderNotFound>> { // [!code ++]
+		const summary = await this.summaries.summaryOf( // [!code ++]
+			new OrderId(orderId), // [!code ++]
+		);
+		if (summary === undefined) { // [!code ++]
+			return err(new OrderNotFound({ orderId })); // [!code ++]
+		} // [!code ++]
+		return ok(summary); // [!code ++]
+	}
+}
+```
+
+This is the complete handler.
+
+### 5. Call it from a driving adapter
+
+A controller builds the query, calls `handle` and turns the `Result` into a response: the failure becomes a 404 there, and nowhere else.
+
+```ts [src/ordering/driving/http/controllers/orders.controller.ts]
+const summary = await this.getOrderSummary.handle({ orderId });
+if (!summary.ok) {
+	return { status: 404, body: { error: summary.error.type } };
+}
+return { status: 200, body: summary.value };
+```
+
+### 6. Check it
+
+Run the checks. Three rules keep the handler 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-foreign-query-dependency"><code>no-foreign-query-dependency</code></a></span>It receives query repositories, ports that do not write and value objects: a read never writes.</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>application/queries/*.query.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 and the application, never an adapter.</div>
+</div>
+
+A command repository added to its constructor is reported:
+
+```
+src/ordering/application/queries/get-order-summary.query.ts
+  20  error  tactical/no-foreign-query-dependency: The QueryHandler
+  GetOrderSummaryHandler receives Orders, a CommandRepository: a
+  query handler receives query repositories, ports that do not
+  write, and value objects.
+```
+
+## See also
+
+- [Views](../domain/views.md), what a query returns
+- [Repositories](../domain/repositories.md), for `QueryRepository`
+- [Command handlers](./command-handlers.md), for requests that change state
+- Rules: [`tactical/no-foreign-query-dependency`](../../rules/tactical/no-foreign-query-dependency.md), [`tactical/no-misplaced-class`](../../rules/tactical/no-misplaced-class.md)

package/docs/core/application/unit-of-work.md

@@ -0,0 +1,352 @@
+---
+description: "The Unit of Work pattern in TypeScript: run all the writes of one use case in a single transaction, so all of them are kept or none."
+---
+
+# Unit of Work
+
+A unit of work runs the writes of one use case in one transaction: all of them are kept, or none.
+
+<dl class="al-glance">
+	<dt>Layer</dt><dd>Application (a port)</dd>
+	<dt>File</dt><dd><code>shared-kernel/driven/pg/adapters/pg-unit-of-work.adapter.ts</code> (your adapter)</dd>
+	<dt>Extends</dt><dd><a href="#api"><code>UnitOfWork</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/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
+
+Placing an order writes twice: the `Order` is saved, then its `OrderPlaced` event is added to the
+[outbox](./outbox.md). If the process stops between the two, the order is placed and nobody hears
+about it. If the second write fails, the first one stays.
+
+::: tip The fix
+The command handler runs its work inside `unitOfWork.run(…)`. Every write made inside belongs to the
+same transaction. The work returns a [`Result`](../utilities/result.md): `ok` commits, `err` rolls
+back.
+:::
+
+## How it works
+
+`run` opens a transaction, runs the work, and reads its outcome:
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span><code>ok</code>: commit</span>The writes are kept, and the result is returned.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span><code>err</code>: roll back</span>A business failure, such as <code>EmptyOrder</code>. Nothing is kept, and the same <code>err</code> is returned.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span>Thrown: roll back</span>A bug or a lost connection. Nothing is kept, and the error is thrown again.</div>
+</div>
+
+```ts
+return this.unitOfWork.run(async () => {
+	await this.orders.save(order);
+	await this.outbox.add(events);
+	return ok();
+});
+```
+
+The unit of work tracks nothing: it does not know which aggregates were loaded. The handler saves
+each change explicitly, inside `run`.
+
+## Where it fits
+
+The unit of work wraps the whole PlaceOrder use case: loading the order, placing it, saving it and
+adding its events to the outbox.
+
+<div class="al-diagram">
+<svg viewBox="0 0 680 320" role="img" aria-label="A request goes from a controller to the PlaceOrderHandler. One unit of work wraps its four steps: load the Order, call order.place, save the order and add its events to the outbox. It commits on ok and rolls back otherwise.">
+	<defs>
+		<marker id="uow-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="boundary" x="426" y="8" width="252" height="304" rx="12" />
+	<text class="note" x="552" y="28" text-anchor="middle">unitOfWork.run(…) · this page</text>
+	<rect class="box" x="8" y="132" width="130" height="56" rx="8" />
+	<text class="label" x="73" y="156" text-anchor="middle">Controller</text>
+	<text class="note" x="73" y="176" text-anchor="middle">driving adapter</text>
+	<path class="link" d="M 138 160 L 178 160" marker-end="url(#uow-flow-arrow)" />
+	<rect class="box" x="180" y="132" width="180" height="56" rx="8" />
+	<text class="label" x="270" y="156" text-anchor="middle">PlaceOrderHandler</text>
+	<text class="note" x="270" y="176" text-anchor="middle">command handler</text>
+	<rect class="box" x="440" y="40" width="224" height="48" rx="8" />
+	<text class="label" x="552" y="60" text-anchor="middle">1 · orders.findById(id)</text>
+	<text class="note" x="552" y="78" text-anchor="middle">loads the Order</text>
+	<rect class="box" x="440" y="102" width="224" height="48" rx="8" />
+	<text class="label" x="552" y="122" text-anchor="middle">2 · order.place(…)</text>
+	<text class="note" x="552" y="140" text-anchor="middle">rules + event</text>
+	<rect class="box" x="440" y="164" width="224" height="48" rx="8" />
+	<text class="label" x="552" y="184" text-anchor="middle">3 · orders.save(order)</text>
+	<text class="note" x="552" y="202" text-anchor="middle">same transaction</text>
+	<rect class="box" x="440" y="226" width="224" height="48" rx="8" />
+	<text class="label" x="552" y="246" text-anchor="middle">4 · outbox.add(events)</text>
+	<text class="note" x="552" y="264" text-anchor="middle">same transaction</text>
+	<text class="note" x="552" y="298" text-anchor="middle">ok → commit · err → rollback</text>
+	<path class="link" d="M 360 160 L 424 160" marker-end="url(#uow-flow-arrow)" />
+</svg>
+</div>
+
+::: tip
+One transaction per use case. A command handler never calls another one: two nested `run` calls
+open two transactions.
+:::
+
+## API
+
+```ts
+import { Transaction, UnitOfWork } from "@alveolus/core";
+// or: from "@alveolus/core/unit-of-work"
+```
+
+### Type parameters
+
+```ts
+abstract class UnitOfWork extends Port {
+	run<T, E>(
+		work: () => Promise<Result<T, E>>,
+	): Promise<Result<T, E>>;
+}
+```
+
+| Parameter | What it is | Constraint |
+| --- | --- | --- |
+| `T` | The value of a success. | inferred from `work` |
+| `E` | The error of a failure. | inferred from `work` |
+
+### `begin()` <Badge type="info" text="protected · abstract" /> <Badge type="tip" text="you implement it" />
+
+```ts
+protected abstract begin(): Promise<Transaction>
+```
+
+Opens a transaction and returns it. `run` calls it once per call.
+
+### `Transaction.commit()` <Badge type="info" text="abstract" /> <Badge type="tip" text="you implement it" />
+
+```ts
+abstract commit(): Promise<void>
+```
+
+Makes the writes of the transaction permanent.
+
+### `Transaction.rollback()` <Badge type="info" text="abstract" /> <Badge type="tip" text="you implement it" />
+
+```ts
+abstract rollback(): Promise<void>
+```
+
+Discards the writes of the transaction.
+
+### `run(work)` <Badge type="tip" text="called by the command handler" />
+
+```ts
+run<T, E>(
+	work: () => Promise<Result<T, E>>,
+): Promise<Result<T, E>>
+```
+
+Begins a transaction and runs `work`. Commits when it returns `ok`, rolls back when it returns
+`err`, and rolls back then throws again when it throws.
+
+::: warning Caveats
+- The unit of work tracks nothing: the handler saves each aggregate explicitly inside `run`.
+- A failure to commit is technical: it is thrown.
+- Nested calls to `run` open nested transactions through `begin`. Avoid calling a command handler
+  from another one.
+:::
+
+## Usage
+
+Build a unit of work in PostgreSQL. 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-choose-how-to-share-the-connection">Choose how to share the connection</a></span>One connection per transaction.</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-open-a-transaction">Open a transaction</a></span>Begin, then commit or roll back.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">4</span><a href="#_4-share-the-connection">Share the connection</a></span>Repositories and outbox write in it.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">5</span><a href="#_5-release-the-connection">Release the connection</a></span>Give it back to the pool.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">6</span><a href="#_6-wire-it-and-run-in-it">Wire it and run in it</a></span>Same storage everywhere.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">7</span><a href="#_7-check-it">Check it</a></span>Let the rules keep it that way.</div>
+</div>
+
+### 1. Choose how to share the connection
+
+The repositories and the outbox must write on the connection of the transaction without receiving it: an `AsyncLocalStorage`, created once by the composition root, carries it.
+
+### 2. Declare the adapter
+
+The adapter extends `UnitOfWork` and receives the pool and the storage of the current connection. `run` is already written: you only open the transaction.
+
+```ts [src/shared-kernel/driven/pg/adapters/pg-unit-of-work.adapter.ts]
+import type { AsyncLocalStorage } from "node:async_hooks";
+
+import { UnitOfWork } from "@alveolus/core";
+import type { Pool, PoolClient } from "pg";
+
+export class PgUnitOfWork extends UnitOfWork {
+	constructor(
+		private readonly pool: Pool,
+		private readonly current: AsyncLocalStorage<PoolClient>,
+	) {
+		super();
+	}
+}
+```
+
+TypeScript now asks for `begin()`: the next step adds it.
+
+### 3. Open a transaction
+
+`begin` opens a transaction on a connection of the pool and returns how to end it. `Transaction` has no state of its own, so a plain object is enough: no second class.
+
+```ts [src/shared-kernel/driven/pg/adapters/pg-unit-of-work.adapter.ts]
+import type { AsyncLocalStorage } from "node:async_hooks";
+
+import { UnitOfWork } from "@alveolus/core"; // [!code --]
+import { type Transaction, UnitOfWork } from "@alveolus/core"; // [!code ++]
+import type { Pool, PoolClient } from "pg";
+
+export class PgUnitOfWork extends UnitOfWork {
+	constructor(
+		private readonly pool: Pool,
+		private readonly current: AsyncLocalStorage<PoolClient>,
+	) {
+		super();
+	}
+
+	protected async begin(): Promise<Transaction> { // [!code ++]
+		const client = await this.pool.connect(); // [!code ++]
+		await client.query("BEGIN"); // [!code ++]
+		return { // [!code ++]
+			commit: async () => { // [!code ++]
+				await client.query("COMMIT"); // [!code ++]
+			}, // [!code ++]
+			rollback: async () => { // [!code ++]
+				await client.query("ROLLBACK"); // [!code ++]
+			}, // [!code ++]
+		}; // [!code ++]
+	} // [!code ++]
+}
+```
+
+### 4. Share the connection
+
+So that every adapter called inside `run` writes in the same transaction, `begin` puts the connection in the storage they read.
+
+```ts [src/shared-kernel/driven/pg/adapters/pg-unit-of-work.adapter.ts]
+import type { AsyncLocalStorage } from "node:async_hooks";
+
+import { type Transaction, UnitOfWork } from "@alveolus/core";
+import type { Pool, PoolClient } from "pg";
+
+export class PgUnitOfWork extends UnitOfWork {
+	constructor(
+		private readonly pool: Pool,
+		private readonly current: AsyncLocalStorage<PoolClient>,
+	) {
+		super();
+	}
+
+	protected async begin(): Promise<Transaction> {
+		const client = await this.pool.connect();
+		await client.query("BEGIN");
+		this.current.enterWith(client); // [!code ++]
+		return {
+			commit: async () => {
+				await client.query("COMMIT");
+			},
+			rollback: async () => {
+				await client.query("ROLLBACK");
+			},
+		};
+	}
+}
+```
+
+### 5. Release the connection
+
+A connection that is never released exhausts the pool. Each way out of the transaction gives it back.
+
+```ts [src/shared-kernel/driven/pg/adapters/pg-unit-of-work.adapter.ts]
+import type { AsyncLocalStorage } from "node:async_hooks";
+
+import { type Transaction, UnitOfWork } from "@alveolus/core";
+import type { Pool, PoolClient } from "pg";
+
+export class PgUnitOfWork extends UnitOfWork {
+	constructor(
+		private readonly pool: Pool,
+		private readonly current: AsyncLocalStorage<PoolClient>,
+	) {
+		super();
+	}
+
+	protected async begin(): Promise<Transaction> {
+		const client = await this.pool.connect();
+		await client.query("BEGIN");
+		this.current.enterWith(client);
+		return {
+			commit: async () => {
+				await client.query("COMMIT");
+				client.release(); // [!code ++]
+			},
+			rollback: async () => {
+				await client.query("ROLLBACK");
+				client.release(); // [!code ++]
+			},
+		};
+	}
+}
+```
+
+This is the complete unit of work.
+
+### 6. Wire it and run in it
+
+The composition root passes the same storage to the unit of work and to every adapter that writes in it:
+
+```ts [src/app.module.ts]
+const current = new AsyncLocalStorage<PoolClient>();
+const unitOfWork = new PgUnitOfWork(pool, current);
+const outbox = new PgOutbox(pool, current);
+```
+
+The [command handler](./command-handlers.md#usage) then wraps its work in `run`: a returned failure or a thrown error rolls everything back.
+
+```ts [src/ordering/application/commands/place-order.command.ts]
+return this.unitOfWork.run(async () => {
+	const order = await this.orders.findById(new OrderId(orderId));
+	…
+	await this.orders.save(order);
+	await this.outbox.add(events);
+	return ok();
+});
+```
+
+### 7. Check it
+
+Run the checks. Two rules keep the unit of work 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 its file: no second class for the transaction.</div>
+</div>
+
+A transaction class declared in the same file is reported:
+
+```
+src/shared-kernel/driven/pg/adapters/pg-unit-of-work.adapter.ts
+  30  error  tactical/no-misplaced-class: PgTransaction shares its file
+  with PgUnitOfWork: one class per file.
+```
+
+## See also
+
+- [Outbox](./outbox.md), written in the same transaction
+- [Command handlers](./command-handlers.md), which run their work in it
+- [Repositories](../domain/repositories.md), which write through it
+- [Result](../utilities/result.md), whose outcome decides commit or rollback
+- Rules: [`layers/no-portless-adapter`](../../rules/layers/no-portless-adapter.md), [`tactical/no-misplaced-class`](../../rules/tactical/no-misplaced-class.md)