@ddd-ts-kit/typeorm 0.16.0 → 0.17.0

package/README.fr.md

@@ -0,0 +1,713 @@
+[English](README.md) · **Français**
+<!-- translation-of: README.md sha256:102e8a726437a11d -->
+
+# @ddd-ts-kit/typeorm
+
+Les adaptateurs TypeORM des ports du noyau et des événements : une unité de travail que les
+*repositories* ne voient jamais, le store de l'outbox transactionnelle, le store des événements
+traités, leurs tables sous forme d'objets `EntitySchema`, et un schéma de base de données par
+contexte délimité (bounded context). Les mêmes pièces que `@ddd-ts-kit/drizzle`, pour les
+projets sur TypeORM.
+
+```
+npm i @ddd-ts-kit/typeorm typeorm pg
+```
+
+Tout ici utilise `EntitySchema`, pas des classes décorées : aucun import de `reflect-metadata`,
+pas d'`experimentalDecorators`, et les lignes restent des objets simples qu'un *mapper*
+transforme en agrégats. PostgreSQL d'abord ; voir
+[Couverture des dialectes](#couverture-des-dialectes) pour MySQL et SQLite.
+
+## Sa place dans une application
+
+Rien d'ici n'est importé depuis `domain/` ni `application/`. Un gestionnaire (handler) dépend du
+port de *repository* de son domaine ; l'adaptateur de ce port, dans `infrastructure/`, exécute
+ses instructions sur le `TypeOrmContext` ; la plateforme construit l'unité de travail une fois et
+la lie.
+
+![Un contexte délimité contient un gestionnaire, le port de repository du domaine et le repository TypeORM qui l'implémente ; createTypeOrmUnitOfWork donne un seul objet qui est à la fois le UnitOfWork dans lequel le bus de commandes exécute chaque commande et le TypeOrmContext dont le manager() sert aux requêtes du repository et des stores ; il ouvre dataSource.transaction() sur la DataSource TypeORM, qui écrit dans PostgreSQL les tables du contexte, l'outbox et les événements traités](https://raw.githubusercontent.com/gbourgeat/ddd-ts-kit/main/docs/assets/diagrams/typeorm-place-in-an-application.fr.svg)
+
+L'idée à retenir : **toute instruction passe par `manager()`**. Dans une unité de travail,
+c'est l'`EntityManager` transactionnel de cette unité de travail : la ligne de l'agrégat,
+l'enregistrement d'outbox de l'événement qu'il a publié et la marque d'événement traité d'un
+consommateur sont validés ou annulés ensemble. Hors d'une unité de travail (une requête, un
+script), c'est `dataSource.manager`.
+
+## Schéma
+
+Les tables sont des objets `EntitySchema` : ajoutez-les aux `entities` de la source de données
+et `typeorm migration:generate` écrit leur DDL dans une migration de votre projet.
+
+```ts
+// platform/database/schema.ts
+import { outboxEntity, processedEventEntity, schemaNameOf } from '@ddd-ts-kit/typeorm';
+
+export const outbox = outboxEntity({ schema: 'messaging' }); // messaging.outbox
+export const processedEvents = processedEventEntity({ schema: 'messaging' });
+
+// contexts/billing-core/infrastructure/persistence/invoice-row.schema.ts
+import { EntitySchema } from 'typeorm';
+
+export interface InvoiceRow {
+  id: string;
+  amount: number;
+  status: 'draft' | 'issued';
+  version: number;
+}
+
+export const invoices = new EntitySchema<InvoiceRow>({
+  name: 'Invoice',
+  tableName: 'invoices',
+  schema: schemaNameOf('billing-core'), // billing_core
+  columns: {
+    id: { type: 'text', primary: true },
+    amount: { type: 'int' },
+    status: { type: 'text' },
+    version: { type: 'int' },
+  },
+});
+```
+
+Les options des deux fabriques : `schema` (aucune : le schéma par défaut de la connexion),
+`dialect` (`postgres` par défaut, `mysql`, `sqlite` : il choisit les types des colonnes JSON et
+horodatage), `tableName`, et `name`, le nom de l'entité. Le nom de l'entité vaut par défaut
+`OutboxRecord` ou `ProcessedEvent`, suffixé du schéma (`OutboxRecord_messaging`), si bien que
+chaque contexte peut enregistrer sa propre outbox dans la même source de données.
+
+`outbox` est indexée pour le relais (les enregistrements en attente par prochaine tentative,
+index partiel sur PostgreSQL et SQLite) ; `processed_events` a `(consumer, event_id)` pour clé
+primaire. TypeORM ne crée pas les schémas : créez-les dans la migration
+(`CREATE SCHEMA IF NOT EXISTS`).
+
+## Racine de composition
+
+`createTypeOrmUnitOfWork(dataSource)` donne un seul objet qui est deux ports : le `UnitOfWork`
+du noyau, et `TypeOrmContext`, la poignée sur laquelle les *repositories* et les stores
+exécutent leurs requêtes. Liez-le aux deux :
+
+```ts
+// platform/database/persistence.module.ts
+import { DataSource } from 'typeorm';
+import { defineContextModule } from '@ddd-ts-kit/di';
+import { IntegrationEventPublisher, ProcessedEventStore, UnitOfWork } from '@ddd-ts-kit/kernel';
+import { OutboxPublisher, OutboxStore } from '@ddd-ts-kit/events';
+import {
+  createTypeOrmUnitOfWork,
+  TypeOrmContext,
+  TypeOrmOutboxStore,
+  TypeOrmProcessedEventStore,
+} from '@ddd-ts-kit/typeorm';
+
+export const dataSource = new DataSource({
+  type: 'postgres',
+  url: process.env.DATABASE_URL,
+  entities: [outbox, processedEvents, invoices],
+});
+const unitOfWork = createTypeOrmUnitOfWork(dataSource);
+
+export const persistenceModule = defineContextModule({
+  name: 'persistence',
+  register(builder) {
+    builder.rebind(UnitOfWork).toValue(unitOfWork);
+    builder.bind(TypeOrmContext).toValue(unitOfWork);
+    builder
+      .bind(OutboxStore)
+      .toFactory((resolve) => new TypeOrmOutboxStore(resolve(TypeOrmContext), { entity: outbox }));
+    builder
+      .rebind(ProcessedEventStore)
+      .toFactory((resolve) => new TypeOrmProcessedEventStore(resolve(TypeOrmContext), { entity: processedEvents }));
+    builder.rebind(IntegrationEventPublisher).toClass(OutboxPublisher, [OutboxStore]);
+  },
+  onStart: async () => {
+    await dataSource.initialize();
+  },
+  onStop: () => dataSource.destroy(),
+});
+```
+
+```ts
+// main.ts
+const app = createApplication({ modules: [kernelModule(), persistenceModule, contextModule('billing', billingDeclarations)] });
+
+const relay = new OutboxRelay({ store: app.resolve(OutboxStore), publisher: broker, clock: app.resolve(Clock) });
+relay.start({ intervalMs: 500 });
+```
+
+Placez le module après `kernelModule()` : `rebind` remplace ses valeurs par défaut en mémoire.
+Le bus de commandes du module du noyau exécute chaque commande dans le `UnitOfWork` lié ; les
+gestionnaires n'en savent rien. `contextModule` de `@ddd-ts-kit/di` transforme les classes
+déclarées d'un contexte en son module.
+
+Un projet écrit par la CLI contient le même câblage en deux fichiers :
+`platform/database/persistence-over.ts` construit l'unité de travail et les deux stores une
+fois, et `platform/platform.module.ts` les lie, le *publisher* de l'outbox étant passé à
+`kernelModule({ eventPublisher })`.
+
+Passez à un store l'entité même que la source de données enregistre. Sans `entity`, un store
+utilise `outboxEntity()` ou `processedEventEntity()`, que TypeORM fait correspondre par son nom à
+l'entité par défaut dans le schéma par défaut ; la classe se lie alors directement :
+`builder.bind(OutboxStore).toClass(TypeOrmOutboxStore, [TypeOrmContext])`,
+`builder.rebind(ProcessedEventStore).toClass(TypeOrmProcessedEventStore, [TypeOrmContext])`.
+
+`unitOfWork.run(work)` ouvre `dataSource.transaction` et garde l'`EntityManager` transactionnel
+dans un `AsyncLocalStorage` ; un `run` imbriqué rejoint la transaction englobante (sans point de
+sauvegarde). Comme `append` utilise le *manager* courant, un événement publié par un
+gestionnaire qui échoue ensuite est annulé avec l'écriture métier : c'est toute la raison
+d'être de l'outbox. `createTypeOrmUnitOfWork(dataSource, 'REPEATABLE READ')` fixe le niveau
+d'isolation.
+
+`run` repose sur `withinUnitOfWork` du noyau. Les événements du domaine des agrégats enregistrés
+à l'intérieur attendent que `work` ait rendu la main, puis sont distribués dans la transaction,
+avant la validation (commit) : leurs gestionnaires voient chaque enregistrement, et ce qu'ils
+écrivent est validé ou annulé avec. Si `work`, un gestionnaire ou la validation échoue, il ne
+reste rien : aucune ligne, aucun enregistrement d'outbox, aucun gestionnaire exécuté après la
+validation. Les gestionnaires déclarés `after-commit` s'exécutent une fois la transaction
+validée. Un `run` imbriqué rejoint l'unité de travail en cours : une seule distribution, à la fin
+de la plus externe. Un `run` appelé directement (un consommateur, un script) suit le même
+déroulé qu'une commande. `unitOfWorkContract` de `@ddd-ts-kit/testing/contracts` le prouve, avec
+une contrainte différée pour la validation qui échoue ; sur un vrai PostgreSQL
+(`DDD_TS_KIT_TEST_DATABASE_URL`), il prouve aussi que les lignes d'un gestionnaire
+`before-commit` sont invisibles depuis une autre connexion et visibles des gestionnaires
+`after-commit`. Le README de `@ddd-ts-kit/kernel` dessine ce déroulé
+([Événements du domaine et unité de travail](../kernel/README.fr.md#événements-du-domaine-et-unité-de-travail)).
+
+`TypeOrmContext` est une classe abstraite : elle est donc son propre jeton d'injection. Un projet
+à deux sources de données donne à chacune sa propre classe
+(`export abstract class Ledger extends TypeOrmContext {}` dans `platform/database/`) et lie
+chacune à son unité de travail.
+
+## Repository
+
+Le port vit dans le domaine, l'adaptateur dans l'infrastructure. Un *repository* reçoit le
+contexte, jamais une transaction : `manager()` est le *manager* transactionnel de l'unité de
+travail s'il y en a une, et `dataSource.manager` sinon.
+
+```ts
+// contexts/billing-core/domain/repositories/invoice.repository.ts
+import { Repository } from '@ddd-ts-kit/kernel';
+
+export abstract class InvoiceRepository extends Repository<Invoice> {}
+```
+
+```ts
+// contexts/billing-core/infrastructure/persistence/type-orm-invoice.repository.ts
+import { Repository } from '@ddd-ts-kit/kernel/declarations';
+import { insertIgnoringConflict, optimisticUpdate, TypeOrmContext } from '@ddd-ts-kit/typeorm';
+
+@Repository(InvoiceRepository)
+export class TypeOrmInvoiceRepository implements InvoiceRepository {
+  constructor(private readonly context: TypeOrmContext) {}
+
+  async findById(id: string): Promise<Invoice | undefined> {
+    const row = await this.context.manager().findOneBy(invoices, { id });
+
+    if (row === null) {
+      return undefined;
+    }
+
+    const invoice = Invoice.rehydrate(row);
+    invoice.version = row.version;
+
+    return invoice;
+  }
+
+  async save(invoice: Invoice): Promise<void> {
+    const manager = this.context.manager();
+
+    await optimisticUpdate(invoice, async ({ expected, next }) => {
+      const row = { ...invoice.state, version: next };
+
+      if (expected === 0) {
+        return (await insertIgnoringConflict(manager, invoices, row)) ? 1 : 0;
+      }
+
+      const updated = await manager.update(invoices, { id: invoice.id, version: expected }, row);
+
+      return updated.affected ?? 0;
+    });
+  }
+}
+```
+
+Dans le style explicite, sans le décorateur, la même liaison tient en une ligne de
+`<context>.module.ts` :
+`builder.bind(InvoiceRepository).toClass(TypeOrmInvoiceRepository, [TypeOrmContext])`.
+
+`optimisticUpdate` donne la version attendue et la version à écrire, lève une
+`ConcurrencyError` (une `DomainError` de code `CONCURRENCY_CONFLICT`) quand l'instruction gardée
+n'a écrit aucune ligne, et fait avancer `invoice.version` sinon. `insertIgnoringConflict` insère
+sauf si la clé existe et dit s'il l'a fait ; contrairement à une violation d'unicité
+interceptée, il laisse utilisable la transaction PostgreSQL qui l'entoure. N'utilisez pas
+`manager.save` pour un agrégat : il lit avant d'écrire et choisit seul entre insertion et mise à
+jour, ce qui défait la garde de version. Le `@VersionColumn` de TypeORM n'est pas utilisé pour la
+même raison : la version appartient à l'agrégat.
+
+```ts
+// Au lieu de : une lecture, puis une insertion ou une mise à jour choisie par TypeORM, sans garde de version
+await manager.save(invoices, { ...invoice.state, version: invoice.version + 1 });
+
+// Écrivez : l'instruction gardée, qui n'écrit aucune ligne quand une autre transaction a enregistré avant
+await optimisticUpdate(invoice, async ({ expected, next }) => {
+  // un premier enregistrement (expected 0) insère plutôt avec insertIgnoringConflict, comme dans le repository ci-dessus
+  const updated = await manager.update(invoices, { id: invoice.id, version: expected }, { ...invoice.state, version: next });
+
+  return updated.affected ?? 0;
+});
+```
+
+![optimisticUpdate lit la version à laquelle l'agrégat a été chargé et calcule la suivante ; un premier enregistrement insère avec insertIgnoringConflict, un enregistrement suivant exécute une mise à jour gardée par la version attendue ; une ligne écrite fait avancer la version de l'agrégat, aucune ligne écrite lève ConcurrencyError ; à côté, deux appels concurrents à manager.save réussissent tous les deux et le second efface le premier](https://raw.githubusercontent.com/gbourgeat/ddd-ts-kit/main/docs/assets/diagrams/typeorm-save-an-aggregate.fr.svg)
+
+Ce que fait `optimisticUpdate`, seul, du nombre de lignes que renvoie l'écriture :
+
+<!-- checked sample -->
+```ts
+import { ConcurrencyError, optimisticUpdate } from '@ddd-ts-kit/typeorm';
+
+// Ce qu'un repository passe à optimisticUpdate : l'agrégat, et une écriture qui répond combien de lignes elle a écrites.
+const invoice = { id: 'inv-1', version: 3 }; // lu en version 3
+
+await optimisticUpdate(invoice, async ({ expected, next }) => {
+  // expected = 3 : la garde de l'UPDATE (WHERE id = 'inv-1' AND version = 3)
+  // next = 4 : la version avec laquelle la ligne est écrite
+  return expected === 3 && next === 4 ? 1 : 0;
+});
+// invoice.version vaut maintenant 4 : le même agrégat peut être enregistré de nouveau
+
+try {
+  // Une autre transaction a enregistré inv-1 entre-temps : l'UPDATE gardé ne trouve aucune ligne.
+  await optimisticUpdate(invoice, async () => 0);
+} catch (error) {
+  if (error instanceof ConcurrencyError) {
+    console.log(error.code); // CONCURRENCY_CONFLICT ; invoice.version vaut toujours 4
+  }
+}
+```
+
+La commande qui enregistrait échoue avec cette erreur et son unité de travail est annulée : rien
+de ce qu'elle a écrit ne reste, et l'appelant relit l'agrégat avant de réessayer.
+
+## Colonnes d'audit, restriction au tenant et pages
+
+Les formes de persistance standard du noyau, sur TypeORM. `auditColumns(dialect?)` et
+`tenantColumn()` sont des options de colonnes à étaler dans les `columns` d'un `EntitySchema` :
+leurs propriétés sont celles des `AuditStamp` et `TenantScoped` du noyau, si bien qu'un tampon
+s'étale tel quel dans une insertion, et les colonnes portent les mêmes noms dans tous les projets
+(`created_at`, `created_by`, `updated_at`, `updated_by`, `tenant_id`) : c'est ce qui permet
+d'écrire une seule fois un tableau de bord, un export ou le *package* d'audit.
+
+```ts
+import type { AuditStamp, TenantScoped } from '@ddd-ts-kit/kernel';
+import { auditColumns, schemaNameOf, tenantColumn } from '@ddd-ts-kit/typeorm';
+
+interface InvoiceRow extends VersionedInvoice, TenantScoped, AuditStamp {}
+
+export const invoices = new EntitySchema<InvoiceRow>({
+  name: 'Invoice',
+  tableName: 'invoices',
+  schema: schemaNameOf('billing-core'),
+  columns: {
+    id: { type: 'text', primary: true },
+    amount: { type: 'int' },
+    status: { type: 'text' },
+    version: { type: 'int' },
+    ...tenantColumn(),
+    ...auditColumns(),
+  },
+  indices: [{ name: 'invoices_tenant_amount_idx', columns: ['tenantId', 'amount', 'id'] }],
+});
+```
+
+```ts
+import { Clock, ExecutionScope, stampCreation, stampUpdate, tenantScopeOf } from '@ddd-ts-kit/kernel';
+import { Repository } from '@ddd-ts-kit/kernel/declarations';
+
+@Repository(InvoiceRepository)
+export class TypeOrmInvoiceRepository implements InvoiceRepository {
+  constructor(
+    private readonly context: TypeOrmContext,
+    private readonly scope: ExecutionScope,
+    private readonly clock: Clock,
+  ) {}
+
+  async findById(id: string): Promise<Invoice | undefined> {
+    const row = await this.context.manager().findOneBy(invoices, { id, ...tenantScopeOf(this.scope) });
+
+    return row === null ? undefined : InvoiceMapper.toDomain(row);
+  }
+
+  async save(invoice: Invoice): Promise<void> {
+    await optimisticUpdate(invoice, async ({ expected, next }) => {
+      const state = { ...InvoiceMapper.toRow(invoice), version: next };
+
+      return expected === 0 ? this.insert(state) : this.update(state, expected);
+    });
+  }
+
+  private async insert(state: VersionedInvoice): Promise<number> {
+    const row = { ...state, ...tenantScopeOf(this.scope), ...stampCreation(this.scope, this.clock) };
+
+    return (await insertIgnoringConflict(this.context.manager(), invoices, row)) ? 1 : 0;
+  }
+
+  private async update(state: VersionedInvoice, expected: number): Promise<number> {
+    const guarded = { id: state.id, version: expected, ...tenantScopeOf(this.scope) };
+    const row = { ...state, ...stampUpdate(this.scope, this.clock) };
+
+    return (await this.context.manager().update(invoices, guarded, row)).affected ?? 0;
+  }
+}
+```
+
+Les `@CreateDateColumn` et `@UpdateDateColumn` de TypeORM ne sont pas utilisés : ils prennent
+l'heure du serveur de base de données, pas celle de la `Clock`, et ne savent rien de qui agit.
+
+Une requête de recherche prend la `PageRequest` du noyau et renvoie une `Page`, dans ses deux
+variantes :
+
+```ts
+// contexts/billing-core/application/ports/invoice-queries.port.ts
+export abstract class InvoiceQueries {
+  abstract search(request: PageRequest<'amount'>): Promise<Page<InvoiceSummary>>;
+}
+```
+
+```ts
+// contexts/billing-core/infrastructure/persistence/type-orm-invoice-queries.reader.ts
+import { LessThan, MoreThan, type FindOptionsWhere } from 'typeorm';
+import { ExecutionScope, encodeCursor, pageOf, tenantScopeOf } from '@ddd-ts-kit/kernel';
+import { Repository } from '@ddd-ts-kit/kernel/declarations';
+
+@Repository(InvoiceQueries)
+export class TypeOrmInvoiceQueries implements InvoiceQueries {
+  constructor(
+    private readonly context: TypeOrmContext,
+    private readonly scope: ExecutionScope,
+  ) {}
+
+  async search(request: PageRequest<'amount'>): Promise<Page<InvoiceSummary>> {
+    return request.kind === 'offset' ? this.byOffset(request) : this.byCursor(request);
+  }
+
+  private async byOffset(request: OffsetPageRequest<'amount'>): Promise<Page<InvoiceSummary>> {
+    const [rows, total] = await this.context.manager().findAndCount(invoices, {
+      where: tenantScopeOf(this.scope),
+      order: totalOrder(directionOf(request)),
+      take: request.limit,
+      skip: request.offset,
+    });
+
+    return pageOf(rows.map(toSummary), { total });
+  }
+
+  private async byCursor(request: CursorPageRequest<'amount'>): Promise<Page<InvoiceSummary>> {
+    const direction = directionOf(request);
+    const tenant = tenantScopeOf(this.scope);
+    const rows = await this.context.manager().find(invoices, {
+      where: request.cursor === undefined ? tenant : beyond(positionOf(request.cursor), direction, tenant),
+      order: totalOrder(direction),
+      take: request.limit + 1,
+    });
+    const items = rows.slice(0, request.limit);
+    const last = items.at(-1);
+    const more = rows.length > request.limit && last !== undefined;
+
+    return pageOf(items.map(toSummary), more ? { nextCursor: encodeCursor({ amount: last.amount, id: last.id }) } : {});
+  }
+}
+
+const directionOf = (request: PageRequest<'amount'>) => request.sort[0]?.direction ?? 'asc';
+
+// La clé primaire suit le champ de tri, dans le même sens : l'ordre est total.
+const totalOrder = (direction: SortDirection) => ({ amount: direction, id: direction });
+
+// Les lignes après une position, en comparaison de tuples. Une liste de conditions est un OR en TypeORM,
+// donc chaque alternative répète le tenant.
+function beyond(
+  { amount, id }: { amount: number; id: string },
+  direction: SortDirection,
+  tenant: TenantScoped,
+): FindOptionsWhere<InvoiceRow>[] {
+  const past = direction === 'asc' ? MoreThan : LessThan;
+
+  return [
+    { ...tenant, amount: past(amount) },
+    { ...tenant, amount, id: past(id) },
+  ];
+}
+```
+
+`positionOf(cursor)` décode avec `decodeCursor` et vérifie que `amount` est un nombre et `id`
+une chaîne, en levant `InvalidPageRequestError` sinon.
+
+Un adaptateur de lecture sur la base de données se déclare avec `@Repository`, comme ceux que
+génère la CLI : sa nature est `repository`. Déclaré avec `@Adapter`, il serait `external`, et
+une plateforme générée entoure chaque adaptateur `external` et `gateway` d'une nouvelle
+tentative (retry) et d'une limite de temps, ce qu'une instruction de l'unité de travail ne doit
+pas recevoir.
+
+Les règles que tiennent ces exemples, et que les tests de ce *package* vérifient sur une vraie
+base de données :
+
+- **Les colonnes d'audit** sont remplies par l'adaptateur, jamais par l'agrégat :
+  `stampCreation(scope, clock)` à l'insertion, `stampUpdate(scope, clock)` à la mise à jour, qui
+  laisse `created_at` et `created_by` intacts. L'acteur est celui de la portée d'exécution :
+  l'utilisateur de la requête HTTP, ou `system:<consumer>` pour un événement consommé.
+- **Le tenant fait partie de chaque instruction** : écrit à l'insertion, et dans la condition de
+  chaque lecture et de chaque mise à jour, garde de version comprise. Une ligne d'un autre
+  *tenant* n'est pas trouvée, et une mise à jour qui la vise n'écrit rien, ce que
+  `optimisticUpdate` signale par une `ConcurrencyError`. Un travail qui ne nomme aucun *tenant*
+  lève `NoCurrentTenantError` avant tout SQL.
+- **Une liste a un ordre total.** La clé primaire suit le champ de tri, dans le même sens, pour
+  départager : sans elle, des lignes égales sur le champ de tri n'ont pas d'ordre défini, et une
+  page pourrait en répéter ou en sauter une. L'index couvre `(tenant_id, <sort field>, id)`.
+- **Un curseur est une position, pas un numéro de page** : la valeur de tri et l'id de la
+  dernière ligne, écrits par `encodeCursor`, comparés comme un tuple (`amount > :amount OR
+  (amount = :amount AND id > :id)`). Une ligne de plus que `limit` est lue pour savoir si une
+  page suit, donc aucun comptage n'est nécessaire, et une ligne insérée avant le curseur ne
+  décale pas la page suivante comme elle le fait avec un offset. Un curseur revient d'un client :
+  `decodeCursor` refuse ce qu'il n'a pas écrit, et l'adaptateur vérifie les types de la position
+  avant qu'ils n'atteignent une instruction.
+- **Une page par offset répond `total`**, une page par curseur `nextCursor`. Proposez la forme
+  par offset pour de petites listes que l'on parcourt, et la forme par curseur pour tout ce qui
+  grandit.
+
+## Critères
+
+`criteriaToTypeOrm(builder, plan, { alias })` ajoute un plan de critères du noyau à un
+`SelectQueryBuilder` sur l'entité d'un modèle de lecture : les filtres et le périmètre de
+l'acteur, le *keyset* d'une page par curseur, l'ordre total terminé par le champ qui départage,
+la fenêtre. `predicateToTypeOrm(builder, predicate, { alias })` ajoute les filtres seuls, pour
+un comptage. Les champs du modèle de lecture sont les propriétés de l'entité (`properties`
+renomme celles qui diffèrent). Chaque valeur est un paramètre nommé ; le seul texte composé est
+`alias.property` avec un opérateur d'une liste fermée, tous deux venant de l'adaptateur. Une
+recherche textuelle est `LIKE :p ESCAPE :e`, avec `%`, `_` et `\` échappés.
+
+```ts
+// infrastructure/persistence/type-orm-appointment-queries.reader.ts
+async search(criteria: ScopedCriteria<AppointmentRow>): Promise<Page<AppointmentRow>> {
+  const plan = planCriteria(appointmentCriteria, criteria);
+
+  if (plan.empty) {
+    return pageOfPlan(plan, []);
+  }
+
+  const builder = this.context.manager().createQueryBuilder(appointmentList, 'row');
+
+  return pageOfPlan(plan, await criteriaToTypeOrm(builder, plan, { alias: 'row' }).getMany());
+}
+```
+
+Une page par curseur est lue avec une ligne de plus que demandé : c'est ainsi que `pageOfPlan`
+sait si une autre suit ; une page par offset prend son total de
+`predicateToTypeOrm(...).getCount()`. Un champ déclaré `nullable` est trié `NULLS LAST` en
+ordre croissant et `NULLS FIRST` en ordre décroissant. Deux critères dans une même requête
+prennent des noms de paramètres distincts avec l'option `parameters`.
+
+**Chaînes.** Une colonne de texte est triée et comparée par intervalle selon la collation de la
+colonne ; les critères trient les chaînes par point de code. Déclarez avec `collation: 'C'` les
+colonnes de texte triées ou comparées avec `gt`, `lt` ou `between` : l'index sert alors le tri,
+et l'ordre est le même que dans le *fake*. **Les décimaux** sont une colonne `numeric` et une
+chaîne dans la ligne ; ils reviennent à l'échelle de la colonne. **Les instants** sont
+`timestamptz` et une `Date`. Un entier est `integer` : un `bigint` revient du pilote sous forme
+de chaîne.
+
+## Modèles de lecture
+
+```ts
+// infrastructure/persistence/appointment-list.schema.ts
+export const appointmentList = new EntitySchema<AppointmentRow & ReadModelStamps>({
+  name: 'AppointmentRow',
+  tableName: 'appointment_list',
+  schema: 'scheduling',
+  columns: {
+    id: { type: 'text', primary: true },
+    status: { type: 'text' },
+    startsAt: { name: 'starts_at', type: 'timestamp with time zone', precision: 3 },
+    ...readModelColumns(), // last_event_id, last_event_at, last_event_version, deleted
+  },
+});
+
+// infrastructure/persistence/type-orm-appointment-list.repository.ts
+@Repository(AppointmentList)
+export class TypeOrmAppointmentList extends TypeOrmReadModelStore<AppointmentRow> implements AppointmentList {
+  constructor(context: TypeOrmContext) {
+    super(context, { entity: appointmentList, definition: appointmentCriteria });
+  }
+}
+```
+
+Chaque écriture passe par `TableReadModelStore` du noyau : une ligne n'est écrite que si son
+événement est plus récent que celui qu'elle porte, sur l'exécuteur de l'unité de travail, si
+bien que la ligne et la marque d'événement traité sont validées ensemble. Une ligne supprimée
+reste dans la table avec `deleted` posé : une requête à vous sur la table écarte ces lignes, et
+un index unique aussi (`WHERE NOT deleted`). `store.table` est ce que prend
+`ProjectionRebuild` ; la reconstruction est réservée à PostgreSQL (une copie `<table>__rebuild`
+faite `LIKE ... INCLUDING ALL`, les clés écrites entre-temps dans `<table>__touched`, l'échange
+par renommage en une transaction) et ses garanties et limites sont dans le README de
+`@ddd-ts-kit/kernel` ([Reconstruction](../kernel/README.fr.md#reconstruction)). Le store passe
+`criteriaContract` et `readModelStoreContract` de `@ddd-ts-kit/testing/contracts`, sur PGlite et
+sur PostgreSQL 18.
+Les critères et les modèles de lecture n'ont jamais été exécutés sur MySQL ni SQLite.
+
+La table s'écrit par son entité ; la copie d'une reconstruction, qui n'en a pas, s'écrit colonne
+par colonne avec le même *query builder*.
+
+## Outbox et idempotence
+
+![Deux relais se partagent l'outbox : avec skip-locked, chacun sélectionne les lignes dues FOR UPDATE SKIP LOCKED dans une courte transaction et le relais B saute les lignes que le relais A a verrouillées ; avec compare-and-set, les deux lisent la ligne 7 et tentent une mise à jour gardée par le nombre de tentatives lu, le premier la prend et le second n'écrit aucune ligne et relit ; dans les deux cas, une ligne prise reste cachée jusqu'à la fin de son bail](https://raw.githubusercontent.com/gbourgeat/ddd-ts-kit/main/docs/assets/diagrams/typeorm-outbox-claim.fr.svg)
+
+- `TypeOrmOutboxStore.claimBatch` sélectionne les lignes dues `FOR UPDATE SKIP LOCKED`
+  (`setLock('pessimistic_write').setOnLocked('skip_locked')`) et les prend à bail dans la même
+  courte transaction en repoussant `next_attempt_at` (`leaseMs`, 30 s par défaut) : plusieurs
+  relais se partagent ainsi le travail sans s'attendre, et les enregistrements d'un relais mort
+  reviennent quand le bail expire. La livraison est au moins une fois et, par défaut, sans
+  ordre : `ordering: 'per-key'` de `OutboxRelay`, muni d'un `keyOf` (en général l'identifiant
+  de l'agrégat), garde dans l'ordre les enregistrements d'une même clé, avec un seul relais ([L'ordre par clé](../events/README.fr.md#lordre-par-clé)).
+- Là où la base n'a pas de `SKIP LOCKED` (SQLite), ou quand vous passez
+  `claim: 'compare-and-set'`, la prise lit les lignes dues et prend chacune par une mise à jour
+  gardée par le nombre de tentatives lu : même garantie, aucune clause de verrou, une
+  instruction par enregistrement. La valeur par défaut est `skip-locked` pour les pilotes
+  `postgres`, `aurora-postgres`, `cockroachdb`, `mysql` et `aurora-mysql`, `compare-and-set`
+  pour tous les autres.
+- `TypeOrmProcessedEventStore.markProcessed` est une insertion qui ignore le conflit sur
+  `(consumer, event_id)`. Exécutez le consommateur dans l'unité de travail : la marque est alors
+  validée avec les effets du gestionnaire, et disparaît avec eux s'il échoue.
+
+Les options du store de l'outbox, et le relais qui le lit :
+
+<!-- checked sample -->
+```ts
+import { OutboxRelay } from '@ddd-ts-kit/events';
+import type { Clock, IntegrationEventPublisher } from '@ddd-ts-kit/kernel';
+import { outboxEntity, TypeOrmOutboxStore, type TypeOrmUnitOfWork } from '@ddd-ts-kit/typeorm';
+
+// Depuis la racine de composition : createTypeOrmUnitOfWork(dataSource), l'adaptateur du broker, l'horloge.
+declare const unitOfWork: TypeOrmUnitOfWork;
+declare const broker: IntegrationEventPublisher;
+declare const clock: Clock;
+
+export const outbox = outboxEntity({ schema: 'messaging' }); // l'entité que la source de données enregistre
+
+const store = new TypeOrmOutboxStore(unitOfWork, {
+  entity: outbox,
+  leaseMs: 60_000, // un enregistrement pris par un relais mort redevient dû au bout d'une minute
+  claim: 'compare-and-set', // au lieu de la valeur par défaut du pilote, par exemple sur MySQL 5.7
+});
+
+const relay = new OutboxRelay({ store, publisher: broker, clock });
+
+relay.start({ intervalMs: 500 });
+```
+
+Un consommateur sur le store des événements traités : `consume` de `@ddd-ts-kit/events` exécute
+la marque et le gestionnaire dans une seule unité de travail
+([Consommer de façon idempotente](../events/README.fr.md#consommer-de-façon-idempotente)).
+
+<!-- checked sample -->
+```ts
+import { z } from 'zod';
+import { consume, defineIntegrationEvent } from '@ddd-ts-kit/events';
+import { zodSchema } from '@ddd-ts-kit/validation/zod';
+import { processedEventEntity, TypeOrmProcessedEventStore, type TypeOrmUnitOfWork } from '@ddd-ts-kit/typeorm';
+
+// Depuis la racine de composition et le contexte : l'unité de travail, et ce que fait le consommateur.
+declare const unitOfWork: TypeOrmUnitOfWork;
+declare function issueInvoice(orderId: string): Promise<void>;
+
+// La déclaration du producteur, dans son langage publié.
+const orderPlaced = defineIntegrationEvent({
+  type: 'ordering.order.placed',
+  version: 1,
+  description: 'An order was placed by a customer.',
+  payload: zodSchema(z.object({ orderId: z.string() })),
+});
+
+const processed = new TypeOrmProcessedEventStore(unitOfWork, {
+  entity: processedEventEntity({ schema: 'messaging' }),
+});
+
+// La marque dans messaging.processed_events et les écritures d'issueInvoice sont validées en une transaction :
+// une nouvelle livraison est ignorée, et un événement dont le gestionnaire a levé une erreur est retraité quand il revient.
+export const invoiceOnOrderPlaced = consume(
+  orderPlaced,
+  { consumer: 'billing.invoice-on-order-placed', processed, unitOfWork },
+  async (event) => {
+    await issueInvoice(event.payload.orderId);
+  },
+);
+```
+
+## Event store
+
+```ts
+const dataSource = new DataSource({ type: 'postgres', entities: [...eventStoreEntities({ schema: 'scheduling' })] });
+
+const { events, snapshots, checkpoints, subjectKeys } = createTypeOrmEventSourcing(unitOfWork, { schema: 'scheduling' });
+```
+
+`eventStoreEntities` déclare les tables sous forme d'`EntitySchema`, si bien que
+`typeorm migration:generate` les crée avec les colonnes d'`eventStoreTablesSql` du noyau. Les
+stores ne les chargent jamais comme entités. Les stores de `createTypeOrmEventSourcing` refusent
+une source de données qui n'est pas PostgreSQL : leur première instruction lève une `TypeError`
+qui nomme son type.
+
+Chaque instruction s'exécute sur l'exécuteur du contexte : un ajout rejoint la transaction de
+l'unité de travail, si bien que le flux et les enregistrements d'outbox que publient ses
+événements sont validés ensemble (`eventStoreUnitOfWorkContract`). Les ajouts prennent la tête
+du store, une ligne verrouillée jusqu'à la fin de leur transaction : les positions sont données
+dans l'ordre des validations, sans trou, et deux ajouts ne s'exécutent jamais côte à côte, quels
+que soient leurs flux. PostgreSQL seulement. Les stores sont ceux du noyau (`PostgresEventStore`
+et ses compagnons), tenus ici à `eventStoreContract` ; comment un agrégat en *event sourcing*
+les utilise : le README de `@ddd-ts-kit/kernel`, section
+[Event sourcing](../kernel/README.fr.md#event-sourcing).
+
+## Couverture des dialectes
+
+Ce qui suit concerne ce *package*. La CLI ne génère que pour PostgreSQL : `init --orm typeorm`
+refuse `--database mysql` et `--database sqlite`.
+
+| Base de données | État |
+|---|---|
+| PostgreSQL | Couvert par la suite automatique : suites de contrat de `@ddd-ts-kit/testing`, contrat de *repository*, annulation, unité de travail imbriquée, prises concurrentes. Elle tourne par défaut sur PGlite servi par le protocole réseau de PostgreSQL, et sur un vrai serveur quand `DDD_TS_KIT_TEST_DATABASE_URL` est définie (dernière exécution : PostgreSQL 18). |
+| MySQL 8 | Hors de la suite automatique. Les suites de contrat de l'outbox et des événements traités et l'annulation d'`append` ont été exécutées une fois à la main contre MySQL 8.4 avec `mysql2`, entités construites avec `dialect: 'mysql'`, avec `skip-locked` et `compare-and-set`. |
+| SQLite | Hors de la suite automatique. Les mêmes suites ont été exécutées une fois à la main avec le pilote `better-sqlite3`, entités construites avec `dialect: 'sqlite'`. Pas de `SKIP LOCKED` : la prise est `compare-and-set`. Pas de schémas : omettez `schema` et nommez les tables par contexte. |
+| MariaDB, CockroachDB, SQL Server, Oracle, MongoDB | Jamais exécuté. |
+
+## Limites
+
+- Testé avec TypeORM 1.1. La plage de la *peer dependency* est `^1.0.0` : TypeORM 0.3 n'est pas
+  accepté.
+- Un `EntitySchema` est statique : les types de colonnes dépendent du `dialect` que vous passez,
+  pas de la source de données dans laquelle il est enregistré.
+- Une charge utile JSON `null` est stockée en `NULL` SQL et relue comme `null`.
+- Sur MySQL 5.7, il n'y a pas de `SKIP LOCKED` : passez `claim: 'compare-and-set'`.
+- `synchronize: true` est réservé aux tests. En production, les tables viennent de vos
+  migrations.
+- Par défaut, l'ordre n'est pas garanti, pas même par agrégat : un événement en échec est
+  retenté plus tard pendant que ses successeurs partent. `ordering: 'per-key'` de `OutboxRelay`,
+  muni d'un `keyOf`, ordonne les enregistrements d'une même clé, avec un seul relais en marche.
+  Sans `keyOf`, rien n'est ordonné.
+
+## Tester un adaptateur
+
+L'unité de travail de ce *package* passe `unitOfWorkContract`, et ses stores
+`outboxStoreContract` et `processedEventStoreContract`, de `@ddd-ts-kit/testing/contracts`.
+Tenez vos *repositories* à `repositoryContract` de la même façon, à côté de leur *fake* en
+mémoire. Les tests de ce *package* n'ont besoin d'aucun conteneur :
+
+```
+npx vitest run packages/typeorm
+DDD_TS_KIT_TEST_DATABASE_URL=postgresql://user:password@localhost:5432/postgres npx vitest run packages/typeorm
+```
+
+Avec la variable définie, chaque fichier de *spec* crée sa propre base de données sur ce serveur
+et la supprime ensuite, et les tests qui ont besoin de deux vraies connexions (un relais qui
+saute les lignes verrouillées par un autre) s'exécutent au lieu d'être ignorés.
+
+## Voir aussi
+
+- [Persistance](../../docs/tools/persistence.fr.md) : choisir un ORM, et ce que chaque *package* d'adaptateurs a vérifié
+- [Agrégats](../../docs/concepts/aggregates.fr.md#concurrence-optimiste) : la concurrence optimiste, vue depuis le domaine
+- [L'outbox transactionnelle](../../docs/concepts/transactional-outbox.fr.md) : pourquoi l'enregistrement d'outbox est validé avec l'écriture métier
+- [Livraison et idempotence](../../docs/concepts/delivery-and-idempotency.fr.md) : au moins une fois, et ce qu'un consommateur en fait
+- [`@ddd-ts-kit/drizzle`](../drizzle/README.fr.md) : les mêmes pièces sur Drizzle, la persistance par défaut du kit

package/README.md

@@ -1,3 +1,5 @@
+**English** · [Français](README.fr.md)
+
 # @ddd-ts-kit/typeorm
 
 TypeORM adapters of the kernel and events ports: a unit of work that repositories never see,
@@ -13,6 +15,19 @@ Everything here uses `EntitySchema`, not decorated classes: no `reflect-metadata
 `experimentalDecorators`, and rows stay plain objects that a mapper turns into aggregates.
 PostgreSQL first; see [Dialect coverage](#dialect-coverage) for MySQL and SQLite.
 
+## Where it sits in an application
+
+Nothing here is imported from `domain/` or `application/`. A handler depends on the repository
+port of its domain; the adapter of that port, in `infrastructure/`, runs its statements on the
+`TypeOrmContext`; the platform builds the unit of work once and binds it.
+
+![A bounded context holds a handler, the repository port of the domain and the TypeORM repository that implements it; createTypeOrmUnitOfWork gives one object that is both the UnitOfWork the command bus runs each command in and the TypeOrmContext whose manager() the repository and the stores query through; it opens dataSource.transaction() on the TypeORM DataSource, which writes the tables of the context, the outbox and the processed events in PostgreSQL](https://raw.githubusercontent.com/gbourgeat/ddd-ts-kit/main/docs/assets/diagrams/typeorm-place-in-an-application.svg)
+
+The one idea to keep: **every statement goes through `manager()`**. Inside a unit of work it
+is the transactional `EntityManager` of that unit of work, so the row of the aggregate, the
+outbox record of the event it published and the processed-event mark of a consumer commit or
+roll back together. Outside one (a query, a script) it is `dataSource.manager`.
+
 ## Schema
 
 The tables are `EntitySchema` objects: add them to the `entities` of the data source and
@@ -143,7 +158,8 @@ A `run` called directly (a consumer, a script) has the same timing as a command.
 `unitOfWorkContract` of `@ddd-ts-kit/testing/contracts` proves it, with a deferred constraint
 for the commit that fails; on a real PostgreSQL (`DDD_TS_KIT_TEST_DATABASE_URL`) it also proves
 that the rows of a `before-commit` handler are invisible from another connection and visible
-to the `after-commit` handlers.
+to the `after-commit` handlers. The README of `@ddd-ts-kit/kernel` draws this timeline
+([Domain events and the unit of work](../kernel/README.md#domain-events-and-the-unit-of-work)).
 
 `TypeOrmContext` is an abstract class, so it is its own injection token. A project with two
 data sources gives each a class of its own (`export abstract class Ledger extends TypeOrmContext {}`
@@ -215,6 +231,50 @@ aggregate: it reads before writing and decides by itself between insert and upda
 defeats the version guard. TypeORM's own `@VersionColumn` is not used for the same reason: the
 version belongs to the aggregate.
 
+```ts
+// Instead of: a read, then an insert or an update chosen by TypeORM, with no version guard
+await manager.save(invoices, { ...invoice.state, version: invoice.version + 1 });
+
+// Write: the guarded statement, which writes no row when another transaction saved first
+await optimisticUpdate(invoice, async ({ expected, next }) => {
+  // a first save (expected 0) inserts with insertIgnoringConflict instead, as in the repository above
+  const updated = await manager.update(invoices, { id: invoice.id, version: expected }, { ...invoice.state, version: next });
+
+  return updated.affected ?? 0;
+});
+```
+
+![optimisticUpdate reads the version the aggregate was loaded at and computes the next one; a first save inserts with insertIgnoringConflict, a later save runs an update guarded by the expected version; one row written moves the version of the aggregate on, no row written raises ConcurrencyError; beside it, two concurrent manager.save calls both succeed and the second erases the first](https://raw.githubusercontent.com/gbourgeat/ddd-ts-kit/main/docs/assets/diagrams/typeorm-save-an-aggregate.svg)
+
+What `optimisticUpdate` does with the count the write answers, on its own:
+
+<!-- checked sample -->
+```ts
+import { ConcurrencyError, optimisticUpdate } from '@ddd-ts-kit/typeorm';
+
+// What a repository hands to optimisticUpdate: the aggregate, and a write that answers how many rows it wrote.
+const invoice = { id: 'inv-1', version: 3 }; // read at version 3
+
+await optimisticUpdate(invoice, async ({ expected, next }) => {
+  // expected = 3: the guard of the UPDATE (WHERE id = 'inv-1' AND version = 3)
+  // next = 4: the version the row is written with
+  return expected === 3 && next === 4 ? 1 : 0;
+});
+// invoice.version is now 4: the same aggregate can be saved again
+
+try {
+  // Another transaction saved inv-1 in between: the guarded UPDATE matches no row.
+  await optimisticUpdate(invoice, async () => 0);
+} catch (error) {
+  if (error instanceof ConcurrencyError) {
+    console.log(error.code); // CONCURRENCY_CONFLICT; invoice.version is still 4
+  }
+}
+```
+
+The command that saved fails with that error and its unit of work rolls back: nothing it
+wrote stays, and the caller reads the aggregate again before it retries.
+
 ## Audit columns, tenant scoping and pages
 
 The standard persistence shapes of the kernel, on TypeORM. `auditColumns(dialect?)` and
@@ -464,7 +524,7 @@ a query of your own on the table leaves those rows out, and so does a unique ind
 (`WHERE NOT deleted`). `store.table` is what `ProjectionRebuild` takes; the rebuild is
 PostgreSQL only (a copy `<table>__rebuild` made `LIKE ... INCLUDING ALL`, the keys written
 meanwhile in `<table>__touched`, the swap by rename in one transaction) and its guarantees
-and limits are in the README of `@ddd-ts-kit/kernel` ("Rebuild"). The store passes
+and limits are in the README of `@ddd-ts-kit/kernel` ([Rebuild](../kernel/README.md#rebuild)). The store passes
 `criteriaContract` and `readModelStoreContract` of `@ddd-ts-kit/testing/contracts`, on PGlite
 and on PostgreSQL 18.
 Criteria and read models were never run on MySQL or SQLite.
@@ -474,11 +534,15 @@ column through the same query builder.
 
 ## Outbox and idempotency
 
+![Two relays share the outbox: with skip-locked, each selects the due rows FOR UPDATE SKIP LOCKED in a short transaction and relay B passes over the rows relay A has locked; with compare-and-set, both read row 7 and try an update guarded by the attempt count they read, the first takes it and the second writes no row and reads again; either way a claimed row stays hidden until its lease ends](https://raw.githubusercontent.com/gbourgeat/ddd-ts-kit/main/docs/assets/diagrams/typeorm-outbox-claim.svg)
+
 - `TypeOrmOutboxStore.claimBatch` selects the due rows `FOR UPDATE SKIP LOCKED`
   (`setLock('pessimistic_write').setOnLocked('skip_locked')`) and leases them in the same short
   transaction by pushing `next_attempt_at` forward (`leaseMs`, default 30 s), so several relays
   share the work without waiting for each other, and the records of a relay that died come
-  back when the lease expires. Delivery is at least once, unordered.
+  back when the lease expires. Delivery is at least once and, by default, unordered:
+  `ordering: 'per-key'` of `OutboxRelay`, given a `keyOf` (typically the aggregate id), keeps
+  the records of one key in order, with a single relay ([Ordering per key](../events/README.md#ordering-per-key)).
 - Where the database has no `SKIP LOCKED` (SQLite), or when you pass
   `claim: 'compare-and-set'`, the claim reads the due rows and takes each one with an update
   guarded by the attempt count it read: same guarantee, no lock clause, one statement per
@@ -488,6 +552,69 @@ column through the same query builder.
   `(consumer, event_id)`. Run the consumer inside the unit of work: the mark then commits with
   the effects of the handler, and disappears with them if it fails.
 
+The options of the outbox store, and the relay that reads it:
+
+<!-- checked sample -->
+```ts
+import { OutboxRelay } from '@ddd-ts-kit/events';
+import type { Clock, IntegrationEventPublisher } from '@ddd-ts-kit/kernel';
+import { outboxEntity, TypeOrmOutboxStore, type TypeOrmUnitOfWork } from '@ddd-ts-kit/typeorm';
+
+// From the composition root: createTypeOrmUnitOfWork(dataSource), the broker adapter, the clock.
+declare const unitOfWork: TypeOrmUnitOfWork;
+declare const broker: IntegrationEventPublisher;
+declare const clock: Clock;
+
+export const outbox = outboxEntity({ schema: 'messaging' }); // the entity the data source registers
+
+const store = new TypeOrmOutboxStore(unitOfWork, {
+  entity: outbox,
+  leaseMs: 60_000, // a record claimed by a relay that died is due again after one minute
+  claim: 'compare-and-set', // instead of the default of the driver, e.g. on MySQL 5.7
+});
+
+const relay = new OutboxRelay({ store, publisher: broker, clock });
+
+relay.start({ intervalMs: 500 });
+```
+
+A consumer on the processed-event store: `consume` of `@ddd-ts-kit/events` runs the mark and
+the handler in one unit of work ([Consume idempotently](../events/README.md#consume-idempotently)).
+
+<!-- checked sample -->
+```ts
+import { z } from 'zod';
+import { consume, defineIntegrationEvent } from '@ddd-ts-kit/events';
+import { zodSchema } from '@ddd-ts-kit/validation/zod';
+import { processedEventEntity, TypeOrmProcessedEventStore, type TypeOrmUnitOfWork } from '@ddd-ts-kit/typeorm';
+
+// From the composition root and the context: the unit of work, and what the consumer does.
+declare const unitOfWork: TypeOrmUnitOfWork;
+declare function issueInvoice(orderId: string): Promise<void>;
+
+// The declaration of the producer, in its published language.
+const orderPlaced = defineIntegrationEvent({
+  type: 'ordering.order.placed',
+  version: 1,
+  description: 'An order was placed by a customer.',
+  payload: zodSchema(z.object({ orderId: z.string() })),
+});
+
+const processed = new TypeOrmProcessedEventStore(unitOfWork, {
+  entity: processedEventEntity({ schema: 'messaging' }),
+});
+
+// The mark in messaging.processed_events and the writes of issueInvoice commit in one transaction:
+// a redelivery is skipped, and an event whose handler threw is handled again when it comes back.
+export const invoiceOnOrderPlaced = consume(
+  orderPlaced,
+  { consumer: 'billing.invoice-on-order-placed', processed, unitOfWork },
+  async (event) => {
+    await issueInvoice(event.payload.orderId);
+  },
+);
+```
+
 ## Event store
 
 ```ts
@@ -498,7 +625,8 @@ const { events, snapshots, checkpoints, subjectKeys } = createTypeOrmEventSourci
 
 `eventStoreEntities` declares the tables as `EntitySchema`s, so `typeorm migration:generate`
 creates them with the columns of `eventStoreTablesSql` of the kernel. The stores never load them
-as entities. `createTypeOrmEventSourcing` refuses a data source that is not PostgreSQL.
+as entities. The stores of `createTypeOrmEventSourcing` refuse a data source that is not
+PostgreSQL: their first statement throws a `TypeError` that names its type.
 
 Each statement runs on the executor of the context: an append joins the transaction of the
 unit of work, so the stream and the outbox records its events publish commit together
@@ -506,7 +634,8 @@ unit of work, so the stream and the outbox records its events publish commit tog
 transaction ends: positions are given in commit order, without gaps, and two appends never run
 side by side, whatever their streams. PostgreSQL only. The stores are the ones of the kernel
 (`PostgresEventStore` and its companions), held to `eventStoreContract` here; how an
-event-sourced aggregate uses them: the README of `@ddd-ts-kit/kernel`, section "Event sourcing".
+event-sourced aggregate uses them: the README of `@ddd-ts-kit/kernel`, section
+[Event sourcing](../kernel/README.md#event-sourcing).
 
 ## Dialect coverage
 
@@ -522,14 +651,16 @@ refuses `--database mysql` and `--database sqlite`.
 
 ## Limits
 
-- Tested with TypeORM 1.1. The peer range also admits 0.3, on which nothing was run.
+- Tested with TypeORM 1.1. The peer range is `^1.0.0`: TypeORM 0.3 is not accepted.
 - An `EntitySchema` is static: the column types depend on the `dialect` you pass, not on the
   data source it is registered in.
 - A JSON `null` payload is stored as SQL `NULL` and read back as `null`.
 - On MySQL 5.7 there is no `SKIP LOCKED`: pass `claim: 'compare-and-set'`.
 - `synchronize: true` is for tests. In production the tables come from your migrations.
-- Ordering is not guaranteed, not even per aggregate: a failed event is retried later while its
-  successors go out.
+- By default ordering is not guaranteed, not even per aggregate: a failed event is retried
+  later while its successors go out. `ordering: 'per-key'` of `OutboxRelay`, given a `keyOf`,
+  orders the records of one key, with a single relay running. Without `keyOf` nothing is
+  ordered.
 
 ## Testing an adapter
 
@@ -545,3 +676,11 @@ DDD_TS_KIT_TEST_DATABASE_URL=postgresql://user:password@localhost:5432/postgres
 With the variable set, each spec file creates a database of its own on that server and drops
 it afterwards, and the tests that need two real connections (a relay passing over rows locked
 by another one) run instead of being skipped.
+
+## See also
+
+- [Persistence](../../docs/tools/persistence.md): choosing an ORM, and what each adapter package verified
+- [Aggregates](../../docs/concepts/aggregates.md#optimistic-concurrency): optimistic concurrency, seen from the domain
+- [The transactional outbox](../../docs/concepts/transactional-outbox.md): why the outbox record commits with the business write
+- [Delivery and idempotency](../../docs/concepts/delivery-and-idempotency.md): at least once, and what a consumer does about it
+- [`@ddd-ts-kit/drizzle`](../drizzle/README.md): the same pieces on Drizzle, the default persistence of the kit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ddd-ts-kit/typeorm",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "TypeORM adapters for the kernel ports: unit of work, transactional outbox store, processed-event store, PostgreSQL event store.",
   "license": "MIT",
   "repository": {
@@ -26,15 +26,15 @@
     "dist"
   ],
   "dependencies": {
-    "@ddd-ts-kit/kernel": "0.16.0",
-    "@ddd-ts-kit/events": "0.16.0"
+    "@ddd-ts-kit/kernel": "0.17.0",
+    "@ddd-ts-kit/events": "0.17.0"
   },
   "peerDependencies": {
     "typeorm": "^1.0.0"
   },
   "devDependencies": {
     "typeorm": "^1.1.2",
-    "@ddd-ts-kit/testing": "0.16.0",
+    "@ddd-ts-kit/testing": "0.17.0",
     "pg": "^8.23.1",
     "@types/pg": "^8.23.1",
     "@electric-sql/pglite": "0.5.9",