ddd-ts-kit 0.0.0-stage → 0.1.0

package/templates/query/search.query.ts.tpl

@@ -0,0 +1,19 @@
+import { AuthorizedQuery, type Actor, type PageRequest } from '@ddd-ts-kit/kernel';
+{{#if style.declared}}
+import { Requires } from '@ddd-ts-kit/kernel/declarations';
+{{access.useCasePermissionsImport}}
+{{/if}}
+import type { {{name.pascal}}Result, {{name.pascal}}Sort } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+
+{{#if style.declared}}
+@{{access.decoration}}
+{{/if}}
+export class {{name.pascal}}Query extends AuthorizedQuery<{{name.pascal}}Result> {
+  // TODO(domain): add the criteria of "{{name.words}}" as readonly primitives after the page (a status, a period).
+  constructor(
+    actor: Actor,
+    readonly page: PageRequest<{{name.pascal}}Sort>,
+  ) {
+    super(actor);
+  }
+}

package/templates/query/search.reader.fake.ts.tpl

@@ -0,0 +1,8 @@
+import type { {{name.pascal}}Item } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+import { InMemory{{name.pascal}}Reader } from '{{alias.context}}/infrastructure/persistence/{{reader.file}}.js';
+
+export class Fake{{name.pascal}}Reader extends InMemory{{name.pascal}}Reader {
+  constructor(protected override readonly items: readonly {{name.pascal}}Item[]) {
+    super();
+  }
+}

package/templates/query/search.reader.in-memory.ts.tpl

@@ -0,0 +1,72 @@
+import type { AccessScope } from '@ddd-ts-kit/auth';
+import { InvalidPageRequestError, decodeCursor, encodeCursor, pageOf, type PageRequest } from '@ddd-ts-kit/kernel';
+{{#if style.declared}}
+import { Repository } from '@ddd-ts-kit/kernel/declarations';
+import { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port.js';
+{{/if}}
+{{#unless style.declared}}
+import type { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port.js';
+{{/unless}}
+import type {
+  {{name.pascal}}Item,
+  {{name.pascal}}Result,
+  {{name.pascal}}Sort,
+} from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+
+{{#if style.declared}}
+@Repository({{name.pascal}}Reader)
+{{/if}}
+export class InMemory{{name.pascal}}Reader implements {{name.pascal}}Reader {
+  protected readonly items: readonly {{name.pascal}}Item[] = [];
+
+  async search(scope: AccessScope, page: PageRequest<{{name.pascal}}Sort>): Promise<{{name.pascal}}Result> {
+    // TODO(domain): replace these canned lines by a real read of the projection; a production adapter (SQL view, search index) implements the same port next to this file, turns the scope into a condition of its statement, and orders by the sort field then by `id` in the same direction, so that a cursor resumes on a total order.
+    const visible = this.items.filter((item) => isVisible(item, scope)).sort(inOrder(page));
+    const start = page.kind === 'offset' ? page.offset : positionAfter(visible, page.cursor);
+    const items = visible.slice(start, start + page.limit);
+
+    if (page.kind === 'offset') {
+      return pageOf(items, { total: visible.length });
+    }
+
+    const last = items.at(-1);
+
+    return pageOf(
+      items,
+      last !== undefined && start + page.limit < visible.length ? { nextCursor: encodeCursor({ id: last.id }) } : {},
+    );
+  }
+}
+
+function isVisible(item: {{name.pascal}}Item, scope: AccessScope): boolean {
+  switch (scope.kind) {
+    case 'all':
+      return true;
+    case 'none':
+      return false;
+    case 'ids':
+      return scope.ids.includes(item.id);
+    case 'filter':
+      return Object.entries(scope.filter).every(([field, value]) => Reflect.get(item, field) === value);
+  }
+}
+
+function inOrder(page: PageRequest<{{name.pascal}}Sort>): (left: {{name.pascal}}Item, right: {{name.pascal}}Item) => number {
+  const toward = page.sort[0]?.direction === 'desc' ? -1 : 1;
+
+  return (left, right) => toward * left.id.localeCompare(right.id);
+}
+
+function positionAfter(visible: readonly {{name.pascal}}Item[], cursor: string | undefined): number {
+  if (cursor === undefined) {
+    return 0;
+  }
+
+  const { id } = decodeCursor(cursor);
+
+  if (typeof id !== 'string') {
+    throw new InvalidPageRequestError('The cursor of a page is the nextCursor of a previous page');
+  }
+
+  return visible.findIndex((item) => item.id === id) + 1;
+}

package/templates/query/search.reader.port.ts.tpl

@@ -0,0 +1,7 @@
+import type { AccessScope } from '@ddd-ts-kit/auth';
+import type { PageRequest } from '@ddd-ts-kit/kernel';
+import type { {{name.pascal}}Result, {{name.pascal}}Sort } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+
+export abstract class {{name.pascal}}Reader {
+  abstract search(scope: AccessScope, page: PageRequest<{{name.pascal}}Sort>): Promise<{{name.pascal}}Result>;
+}

package/templates/query/search.reader.spec.ts.tpl

@@ -0,0 +1,46 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { cursorPage, encodeCursor, offsetPage } from '@ddd-ts-kit/kernel';
+import type { {{name.pascal}}Sort } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+import { Fake{{name.pascal}}Reader } from '{{alias.context}}/test/fakes/{{name.kebab}}-reader.fake.js';
+
+const LINES = [{ id: '{{name.kebab}}-1' }, { id: '{{name.kebab}}-2' }, { id: '{{name.kebab}}-3' }];
+const [first, second, third] = LINES;
+
+describe('InMemory{{name.pascal}}Reader', () => {
+  it('shows only what the access scope covers: everything, nothing, some identifiers, a filter', async () => {
+    const reader = new Fake{{name.pascal}}Reader(LINES);
+    const some = await reader.search({ kind: 'ids', ids: ['{{name.kebab}}-2'] }, offsetPage());
+    const filtered = await reader.search({ kind: 'filter', filter: { id: '{{name.kebab}}-3' } }, offsetPage());
+
+    expect(await reader.search({ kind: 'all' }, offsetPage())).toEqual({ items: LINES, total: 3 });
+    expect(await reader.search({ kind: 'none' }, offsetPage())).toEqual({ items: [], total: 0 });
+    expect(some.items).toEqual([second]);
+    expect(filtered.items).toEqual([third]);
+  });
+
+  it('pages by offset in the direction of the sort, with the total', async () => {
+    const reader = new Fake{{name.pascal}}Reader(LINES);
+    const descending = offsetPage({ offset: 1, limit: 2, sort: [{ field: 'id', direction: 'desc' }] });
+
+    expect(await reader.search({ kind: 'all' }, descending)).toEqual({ items: [second, first], total: 3 });
+  });
+
+  it('pages by cursor until the last page, which gives no cursor', async () => {
+    const reader = new Fake{{name.pascal}}Reader(LINES);
+    const opening = await reader.search({ kind: 'all' }, cursorPage<{{name.pascal}}Sort>({ limit: 2 }));
+    const closing = await reader.search({ kind: 'all' }, cursorPage<{{name.pascal}}Sort>({ limit: 2, cursor: opening.nextCursor ?? '' }));
+
+    expect(opening.items).toEqual([first, second]);
+    expect(closing).toEqual({ items: [third] });
+  });
+
+  it('refuses a cursor that is not the cursor of a previous page', async () => {
+    const reader = new Fake{{name.pascal}}Reader(LINES);
+    const forged = cursorPage<{{name.pascal}}Sort>({ cursor: encodeCursor({ id: 3 }) });
+
+    await expect(reader.search({ kind: 'all' }, forged)).rejects.toMatchObject({ code: 'INVALID_PAGE_REQUEST' });
+  });
+
+  // TODO(domain): once the reader reads the real projection, hold its production adapter to the same expectations.
+  it.todo('orders by each sort field of the result, then by id');
+});

package/templates/query/search.result.ts.tpl

@@ -0,0 +1,11 @@
+import type { Page } from '@ddd-ts-kit/kernel';
+
+export interface {{name.pascal}}Item {
+  readonly id: string;
+  // TODO(domain): declare the rest of one line of the search exactly as the reader needs it, flat and serializable; this is a read model, not the aggregate.
+}
+
+// TODO(domain): name the fields a client may sort "{{name.words}}" by; the read port orders by one of them and then by `id`.
+export type {{name.pascal}}Sort = 'id';
+
+export type {{name.pascal}}Result = Page<{{name.pascal}}Item>;

package/templates/query/search.wiring.manual.tpl

@@ -0,0 +1,12 @@
+@@imports
+{{access.manualImport}}
+{{access.permissionsImport}}
+import { {{name.pascal}}Handler } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.handler.js';
+import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import { InMemory{{name.pascal}}Reader } from '{{alias.context}}/infrastructure/persistence/{{reader.file}}.js';
+@@registrations
+const {{name.camel}}Reader = platform.adapter(new InMemory{{name.pascal}}Reader(), { kind: 'repository', context: '{{context.kebab}}' });
+
+platform.queries.register({{name.pascal}}Query, new {{name.pascal}}Handler({{name.camel}}Reader, platform.access), { context: '{{context.kebab}}' });
+@@authorization
+{{access.manualDeclaration}}

package/templates/query/search.wiring.tsyringe.tpl

@@ -0,0 +1,10 @@
+@@imports
+import { Access } from '@ddd-ts-kit/auth';
+{{access.permissionsImport}}
+import { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port.js';
+import { {{name.pascal}}Handler } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.handler.js';
+import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import { InMemory{{name.pascal}}Reader } from '{{alias.context}}/infrastructure/persistence/{{reader.file}}.js';
+@@registrations
+builder.bind({{name.pascal}}Reader).toClass(InMemory{{name.pascal}}Reader).as('repository');
+builder.query({{name.pascal}}Query){{access.declaration}}.handledBy({{name.pascal}}Handler, [{{name.pascal}}Reader, Access]);

package/templates/query/wiring.manual.tpl

@@ -0,0 +1,12 @@
+@@imports
+{{access.manualImport}}
+{{access.permissionsImport}}
+import { {{name.pascal}}Handler } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.handler.js';
+import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import { InMemory{{name.pascal}}Reader } from '{{alias.context}}/infrastructure/persistence/{{reader.file}}.js';
+@@registrations
+const {{name.camel}}Reader = platform.adapter(new InMemory{{name.pascal}}Reader(), { kind: 'repository', context: '{{context.kebab}}' });
+
+platform.queries.register({{name.pascal}}Query, new {{name.pascal}}Handler({{name.camel}}Reader), { context: '{{context.kebab}}' });
+@@authorization
+{{access.manualDeclaration}}

package/templates/query/wiring.tsyringe.tpl

@@ -0,0 +1,9 @@
+@@imports
+{{access.permissionsImport}}
+import { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port.js';
+import { {{name.pascal}}Handler } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.handler.js';
+import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import { InMemory{{name.pascal}}Reader } from '{{alias.context}}/infrastructure/persistence/{{reader.file}}.js';
+@@registrations
+builder.bind({{name.pascal}}Reader).toClass(InMemory{{name.pascal}}Reader).as('repository');
+builder.query({{name.pascal}}Query){{access.declaration}}.handledBy({{name.pascal}}Handler, [{{name.pascal}}Reader]);

package/templates/repository/contract.spec.ts.tpl

@@ -0,0 +1,96 @@
+{{#if adapter.needsDatabase}}
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from '{{tests.module}}';
+{{/if}}
+{{#unless adapter.needsDatabase}}
+import { afterEach, beforeEach, describe, expect, it } from '{{tests.module}}';
+{{/unless}}
+{{#if adapter.needsDatabase}}
+import {
+  FixedClock,
+  FixedExecutionScope,
+  executionContext,
+  type Actor,
+  type ExecutionContext,
+} from '@ddd-ts-kit/kernel';
+{{/if}}
+import { repositoryContract } from '@ddd-ts-kit/testing/contracts';
+import type { {{aggregate.pascal}} } from '{{alias.context}}/domain/aggregates/{{aggregate.kebab}}.aggregate.js';
+import { {{adapter.pascal}}{{aggregate.pascal}}Repository } from '{{alias.context}}/infrastructure/persistence/{{adapter.kebab}}-{{aggregate.kebab}}.repository.js';
+{{#if adapter.needsDatabase}}
+import { openTestDatabase, type TestDatabase } from '{{alias.platform}}/database/open-test-database.js';
+{{/if}}
+import { {{aggregate.article}}{{aggregate.pascal}} } from '{{alias.context}}/test/builders/{{aggregate.kebab}}.builder.js';
+import { Fake{{aggregate.pascal}}Repository } from '{{alias.context}}/test/fakes/{{aggregate.kebab}}.repository.fake.js';
+
+const runner = { describe, it, expect, beforeEach, afterEach };
+
+const expectations = {
+  createAggregate: () => {{aggregate.article}}{{aggregate.pascal}}().build(),
+  mutate: (changed: {{aggregate.pascal}}) => {
+    // TODO(domain): call a business method of {{aggregate.pascal}} on `changed` that alters its state, so that the suite proves an update is really stored.
+  },
+  idOf: (subject: {{aggregate.pascal}}) => subject.id,
+  stateOf: (subject: {{aggregate.pascal}}) => subject.toState(),
+};
+
+repositoryContract<{{aggregate.pascal}}>(runner, {
+  ...expectations,
+  name: 'Fake{{aggregate.pascal}}Repository',
+  createRepository: () => new Fake{{aggregate.pascal}}Repository(),
+});
+
+{{#if adapter.needsDatabase}}
+const clock = new FixedClock(new Date('2026-01-01T00:00:00.000Z'));
+let database: TestDatabase;
+
+beforeAll(async () => {
+  database = await openTestDatabase();
+});
+
+afterAll(async () => {
+  await database.close();
+});
+
+repositoryContract<{{aggregate.pascal}}>(runner, {
+  ...expectations,
+  name: '{{adapter.pascal}}{{aggregate.pascal}}Repository',
+  createRepository: async () => {
+    await database.reset();
+
+    const scope = new FixedExecutionScope(workOf('acme'));
+
+    return new {{adapter.pascal}}{{aggregate.pascal}}Repository(database.persistence.database, scope, clock);
+  },
+});
+{{#if tenant.scoped}}
+
+describe('{{adapter.pascal}}{{aggregate.pascal}}Repository, tenant by tenant', () => {
+  it('hides from a tenant what another tenant saved', async () => {
+    await database.reset();
+
+    const scope = new FixedExecutionScope(workOf('acme'));
+    const repository = new {{adapter.pascal}}{{aggregate.pascal}}Repository(database.persistence.database, scope, clock);
+    const saved = {{aggregate.article}}{{aggregate.pascal}}().build();
+
+    await repository.save(saved);
+
+    scope.enter(workOf('globex'));
+
+    expect(await repository.findById(saved.id)).toBeUndefined();
+  });
+});
+{{/if}}
+
+function workOf(tenantId: string): ExecutionContext {
+  const actor: Actor = { id: 'member-of-' + tenantId, type: 'user', tenantId, roles: [], attributes: {} };
+
+  return executionContext({ correlationId: 'contract-spec', actor, origin: 'test' });
+}
+{{/if}}
+{{#unless adapter.needsDatabase}}
+repositoryContract<{{aggregate.pascal}}>(runner, {
+  ...expectations,
+  name: '{{adapter.pascal}}{{aggregate.pascal}}Repository',
+  createRepository: () => new {{adapter.pascal}}{{aggregate.pascal}}Repository(),
+});
+{{/unless}}

package/templates/repository/drizzle/mapper.ts.tpl

@@ -0,0 +1,28 @@
+{{#if tenant.scoped}}
+import type { AuditStamp, TenantScoped } from '@ddd-ts-kit/kernel';
+{{/if}}
+{{#unless tenant.scoped}}
+import type { AuditStamp } from '@ddd-ts-kit/kernel';
+{{/unless}}
+import { {{aggregate.pascal}} } from '{{alias.context}}/domain/aggregates/{{aggregate.kebab}}.aggregate.js';
+import type { {{aggregate.tableCamel}} } from '{{alias.context}}/infrastructure/persistence/{{context.kebab}}.schema.js';
+
+type {{aggregate.pascal}}Row = typeof {{aggregate.tableCamel}}.$inferSelect;
+
+export type {{aggregate.pascal}}Columns = Omit<{{aggregate.pascal}}Row, 'version' | keyof AuditStamp{{#if tenant.scoped}} | keyof TenantScoped{{/if}}>;
+
+export const {{aggregate.pascal}}Mapper = {
+  toDomain(row: {{aggregate.pascal}}Row): {{aggregate.pascal}} {
+    // TODO(domain): rebuild each value object of {{aggregate.pascal}}State from its columns.
+    const loaded = {{aggregate.pascal}}.rehydrate(row.id, { registeredAt: row.registeredAt });
+
+    loaded.version = row.version;
+
+    return loaded;
+  },
+
+  toRow(saved: {{aggregate.pascal}}): {{aggregate.pascal}}Columns {
+    // TODO(domain): flatten each value object of {{aggregate.pascal}}State into its columns; nothing of the row type leaves this file.
+    return { id: saved.id, ...saved.toState() };
+  },
+};

package/templates/repository/drizzle/repository.ts.tpl

@@ -0,0 +1,90 @@
+import { and, eq } from 'drizzle-orm';
+import { optimisticUpdate } from '@ddd-ts-kit/drizzle/postgres';
+{{#if style.declared}}
+{{#if tenant.scoped}}
+import { Clock, ExecutionScope, stampCreation, stampUpdate, tenantScopeOf } from '@ddd-ts-kit/kernel';
+{{/if}}
+{{#unless tenant.scoped}}
+import { Clock, ExecutionScope, stampCreation, stampUpdate } from '@ddd-ts-kit/kernel';
+{{/unless}}
+import { Repository } from '@ddd-ts-kit/kernel/declarations';
+{{/if}}
+{{#unless style.declared}}
+{{#if tenant.scoped}}
+import { stampCreation, stampUpdate, tenantScopeOf, type Clock, type ExecutionScope } from '@ddd-ts-kit/kernel';
+{{/if}}
+{{#unless tenant.scoped}}
+import { stampCreation, stampUpdate, type Clock, type ExecutionScope } from '@ddd-ts-kit/kernel';
+{{/unless}}
+{{/unless}}
+import type { {{aggregate.pascal}} } from '{{alias.context}}/domain/aggregates/{{aggregate.kebab}}.aggregate.js';
+{{#if style.declared}}
+import { {{aggregate.pascal}}Repository } from '{{alias.context}}/domain/repositories/{{aggregate.kebab}}.repository.js';
+{{/if}}
+{{#unless style.declared}}
+import type { {{aggregate.pascal}}Repository } from '{{alias.context}}/domain/repositories/{{aggregate.kebab}}.repository.js';
+{{/unless}}
+{{storage.adapterImport}}
+import { {{aggregate.tableCamel}} } from '{{alias.context}}/infrastructure/persistence/{{context.kebab}}.schema.js';
+import { {{aggregate.pascal}}Mapper, type {{aggregate.pascal}}Columns } from '{{alias.context}}/infrastructure/persistence/{{aggregate.kebab}}.mapper.js';
+
+type Versioned{{aggregate.pascal}} = {{aggregate.pascal}}Columns & { readonly version: number };
+
+{{#if style.declared}}
+@Repository({{aggregate.pascal}}Repository, [Database, ExecutionScope, Clock])
+{{/if}}
+export class Drizzle{{aggregate.pascal}}Repository implements {{aggregate.pascal}}Repository {
+  constructor(
+    private readonly database: Database,
+    private readonly scope: ExecutionScope,
+    private readonly clock: Clock,
+  ) {}
+
+  async findById(id: string): Promise<{{aggregate.pascal}} | undefined> {
+{{#if tenant.scoped}}
+    const mine = and(eq({{aggregate.tableCamel}}.id, id), this.ownTenant());
+    const [row] = await this.database.executor().select().from({{aggregate.tableCamel}}).where(mine);
+{{/if}}
+{{#unless tenant.scoped}}
+    const byId = eq({{aggregate.tableCamel}}.id, id);
+    const [row] = await this.database.executor().select().from({{aggregate.tableCamel}}).where(byId);
+{{/unless}}
+
+    return row === undefined ? undefined : {{aggregate.pascal}}Mapper.toDomain(row);
+  }
+
+  async save(saved: {{aggregate.pascal}}): Promise<void> {
+    await optimisticUpdate(saved, async ({ expected, next }) => {
+      const state = { ...{{aggregate.pascal}}Mapper.toRow(saved), version: next };
+      const written = expected === 0 ? await this.insert(state) : await this.update(state, expected);
+
+      return written.length;
+    });
+  }
+
+  private insert(state: Versioned{{aggregate.pascal}}) {
+    const row = { ...state, {{#if tenant.scoped}}...tenantScopeOf(this.scope), {{/if}}...stampCreation(this.scope, this.clock) };
+
+    const insertion = this.database.executor().insert({{aggregate.tableCamel}}).values(row);
+
+    return insertion.onConflictDoNothing().returning({ id: {{aggregate.tableCamel}}.id });
+  }
+
+  private update(state: Versioned{{aggregate.pascal}}, expected: number) {
+    const sameId = eq({{aggregate.tableCamel}}.id, state.id);
+    const sameVersion = eq({{aggregate.tableCamel}}.version, expected);
+
+    return this.database
+      .executor()
+      .update({{aggregate.tableCamel}})
+      .set({ ...state, ...stampUpdate(this.scope, this.clock) })
+      .where(and(sameId, sameVersion{{#if tenant.scoped}}, this.ownTenant(){{/if}}))
+      .returning({ id: {{aggregate.tableCamel}}.id });
+  }
+{{#if tenant.scoped}}
+
+  private ownTenant() {
+    return eq({{aggregate.tableCamel}}.tenantId, tenantScopeOf(this.scope).tenantId);
+  }
+{{/if}}
+}

package/templates/repository/drizzle/schema-export.tpl

@@ -0,0 +1,2 @@
+@@schemas
+export * from '{{alias.context}}/infrastructure/persistence/{{context.kebab}}.schema.js';

package/templates/repository/drizzle/schema.ts.tpl

@@ -0,0 +1,9 @@
+// ddd-ts-kit:imports
+import { integer, text, timestamp } from 'drizzle-orm/pg-core';
+import { contextSchema } from '@ddd-ts-kit/drizzle/postgres';
+// /ddd-ts-kit:imports
+
+export const {{context.camel}}Schema = contextSchema('{{context.kebab}}');
+
+// ddd-ts-kit:tables
+// /ddd-ts-kit:tables

package/templates/repository/drizzle/table.tpl

@@ -0,0 +1,32 @@
+@@imports
+{{#if tenant.scoped}}
+import { index } from 'drizzle-orm/pg-core';
+import { auditColumns, tenantColumn } from '@ddd-ts-kit/drizzle/postgres';
+{{/if}}
+{{#unless tenant.scoped}}
+import { auditColumns } from '@ddd-ts-kit/drizzle/postgres';
+{{/unless}}
+@@tables
+{{#if tenant.scoped}}
+export const {{aggregate.tableCamel}} = {{context.camel}}Schema.table(
+  '{{aggregate.table}}',
+  {
+    id: text('id').primaryKey(),
+    registeredAt: timestamp('registered_at', { withTimezone: true, mode: 'date' }).notNull(),
+    // TODO(domain): add one column per field of {{aggregate.pascal}}State, with the type and the constraints the storage must enforce; then run `npm run db:generate`.
+    version: integer('version').notNull(),
+    ...tenantColumn(),
+    ...auditColumns(),
+  },
+  (table) => [index('{{aggregate.table}}_tenant_idx').on(table.tenantId, table.id)],
+);
+{{/if}}
+{{#unless tenant.scoped}}
+export const {{aggregate.tableCamel}} = {{context.camel}}Schema.table('{{aggregate.table}}', {
+  id: text('id').primaryKey(),
+  registeredAt: timestamp('registered_at', { withTimezone: true, mode: 'date' }).notNull(),
+  // TODO(domain): add one column per field of {{aggregate.pascal}}State, with the type and the constraints the storage must enforce; then run `npm run db:generate`.
+  version: integer('version').notNull(),
+  ...auditColumns(),
+});
+{{/unless}}

package/templates/repository/fake.ts.tpl

@@ -0,0 +1,16 @@
+import { InMemoryRepository, snapshots } from '@ddd-ts-kit/testing';
+import { {{aggregate.pascal}} } from '{{alias.context}}/domain/aggregates/{{aggregate.kebab}}.aggregate.js';
+import type { {{aggregate.pascal}}Repository } from '{{alias.context}}/domain/repositories/{{aggregate.kebab}}.repository.js';
+
+export class Fake{{aggregate.pascal}}Repository extends InMemoryRepository<{{aggregate.pascal}}> implements {{aggregate.pascal}}Repository {
+  constructor() {
+    super(
+      snapshots({
+        toSnapshot: (stored: {{aggregate.pascal}}) => ({ id: stored.id, state: stored.toState() }),
+        fromSnapshot: ({ id, state }) => {{aggregate.pascal}}.rehydrate(id, state),
+      }),
+    );
+  }
+
+  // TODO(domain): implement each lookup of {{aggregate.pascal}}Repository over `this.all()`, so that handlers are tested against a working repository.
+}

package/templates/repository/knex/mapper.ts.tpl

@@ -0,0 +1,18 @@
+import { {{aggregate.pascal}} } from '{{alias.context}}/domain/aggregates/{{aggregate.kebab}}.aggregate.js';
+import type { {{aggregate.pascal}}Columns, {{aggregate.pascal}}Row } from '{{alias.context}}/infrastructure/persistence/{{aggregate.kebab}}-row.schema.js';
+
+export const {{aggregate.pascal}}Mapper = {
+  toDomain(row: {{aggregate.pascal}}Row): {{aggregate.pascal}} {
+    // TODO(domain): rebuild each value object of {{aggregate.pascal}}State from its columns.
+    const loaded = {{aggregate.pascal}}.rehydrate(row.id, { registeredAt: row.registered_at });
+
+    loaded.version = row.version;
+
+    return loaded;
+  },
+
+  toRow(saved: {{aggregate.pascal}}): {{aggregate.pascal}}Columns {
+    // TODO(domain): flatten each value object of {{aggregate.pascal}}State into its columns; nothing of the row type leaves this file.
+    return { id: saved.id, registered_at: saved.toState().registeredAt };
+  },
+};

package/templates/repository/knex/repository.ts.tpl

@@ -0,0 +1,117 @@
+import type { Knex } from 'knex';
+{{#if style.declared}}
+{{#if tenant.scoped}}
+import { Clock, ExecutionScope, stampCreation, stampUpdate, tenantScopeOf } from '@ddd-ts-kit/kernel';
+{{/if}}
+{{#unless tenant.scoped}}
+import { Clock, ExecutionScope, stampCreation, stampUpdate } from '@ddd-ts-kit/kernel';
+{{/unless}}
+import { Repository } from '@ddd-ts-kit/kernel/declarations';
+{{/if}}
+{{#unless style.declared}}
+{{#if tenant.scoped}}
+import { stampCreation, stampUpdate, tenantScopeOf, type Clock, type ExecutionScope } from '@ddd-ts-kit/kernel';
+{{/if}}
+{{#unless tenant.scoped}}
+import { stampCreation, stampUpdate, type Clock, type ExecutionScope } from '@ddd-ts-kit/kernel';
+{{/unless}}
+{{/unless}}
+{{#if tenant.scoped}}
+{{#if style.declared}}
+import {
+  KnexContext,
+  auditRow,
+  insertIgnoringConflict,
+  optimisticUpdate,
+  tenantRow,
+  type TenantRow,
+} from '@ddd-ts-kit/knex';
+{{/if}}
+{{#unless style.declared}}
+import {
+  type KnexContext,
+  auditRow,
+  insertIgnoringConflict,
+  optimisticUpdate,
+  tenantRow,
+  type TenantRow,
+} from '@ddd-ts-kit/knex';
+{{/unless}}
+{{/if}}
+{{#unless tenant.scoped}}
+import { {{storage.knexImport}}, auditRow, insertIgnoringConflict, optimisticUpdate } from '@ddd-ts-kit/knex';
+{{/unless}}
+import type { {{aggregate.pascal}} } from '{{alias.context}}/domain/aggregates/{{aggregate.kebab}}.aggregate.js';
+{{#if style.declared}}
+import { {{aggregate.pascal}}Repository } from '{{alias.context}}/domain/repositories/{{aggregate.kebab}}.repository.js';
+{{/if}}
+{{#unless style.declared}}
+import type { {{aggregate.pascal}}Repository } from '{{alias.context}}/domain/repositories/{{aggregate.kebab}}.repository.js';
+{{/unless}}
+import { {{context.constant}}_SCHEMA } from '{{alias.context}}/infrastructure/persistence/{{context.kebab}}.schema.js';
+import { {{aggregate.pascal}}Mapper } from '{{alias.context}}/infrastructure/persistence/{{aggregate.kebab}}.mapper.js';
+import type { {{aggregate.pascal}}Columns, {{aggregate.pascal}}Row } from '{{alias.context}}/infrastructure/persistence/{{aggregate.kebab}}-row.schema.js';
+
+type Versioned{{aggregate.pascal}} = {{aggregate.pascal}}Columns & { readonly version: number };
+
+{{#if style.declared}}
+@Repository({{aggregate.pascal}}Repository, [KnexContext, ExecutionScope, Clock])
+{{/if}}
+export class Knex{{aggregate.pascal}}Repository implements {{aggregate.pascal}}Repository {
+  constructor(
+    private readonly database: KnexContext,
+    private readonly scope: ExecutionScope,
+    private readonly clock: Clock,
+  ) {}
+
+  async findById(id: string): Promise<{{aggregate.pascal}} | undefined> {
+{{#if tenant.scoped}}
+    const row = await tableOf(this.database)
+      .where({ id, ...this.ownTenant() })
+      .first();
+{{/if}}
+{{#unless tenant.scoped}}
+    const row = await tableOf(this.database).where({ id }).first();
+{{/unless}}
+
+    return row === undefined ? undefined : {{aggregate.pascal}}Mapper.toDomain(row);
+  }
+
+  async save(saved: {{aggregate.pascal}}): Promise<void> {
+    await optimisticUpdate(saved, async ({ expected, next }) => {
+      const state = { ...{{aggregate.pascal}}Mapper.toRow(saved), version: next };
+
+      return expected === 0 ? this.insert(state) : this.update(state, expected);
+    });
+  }
+
+  private async insert(state: Versioned{{aggregate.pascal}}): Promise<number> {
+    const row = { ...state, {{#if tenant.scoped}}...this.ownTenant(), {{/if}}...auditRow(stampCreation(this.scope, this.clock)) };
+
+    const inserted = await insertIgnoringConflict(this.database.executor(), tableOf(this.database), {
+      row,
+      conflict: 'id',
+    });
+
+    return inserted ? 1 : 0;
+  }
+
+  private async update(state: Versioned{{aggregate.pascal}}, expected: number): Promise<number> {
+    return tableOf(this.database)
+      .where({ id: state.id, version: expected{{#if tenant.scoped}}, ...this.ownTenant(){{/if}} })
+      .update({ ...state, ...auditRow(stampUpdate(this.scope, this.clock)) });
+  }
+{{#if tenant.scoped}}
+
+  private ownTenant(): TenantRow {
+    return tenantRow(tenantScopeOf(this.scope));
+  }
+{{/if}}
+}
+
+/** A function and not a method: a query builder is thenable, and a method that answers one is read as asynchronous by whatever wraps the adapter (tracing), which then answers a promise. */
+function tableOf(database: KnexContext): Knex.QueryBuilder<{{aggregate.pascal}}Row, {{aggregate.pascal}}Row[]> {
+  const table = database.executor()<{{aggregate.pascal}}Row, {{aggregate.pascal}}Row[]>('{{aggregate.table}}');
+
+  return table.withSchema({{context.constant}}_SCHEMA);
+}

package/templates/repository/knex/row.ts.tpl

@@ -0,0 +1,16 @@
+{{#if tenant.scoped}}
+import type { AuditRow, TenantRow } from '@ddd-ts-kit/knex';
+{{/if}}
+{{#unless tenant.scoped}}
+import type { AuditRow } from '@ddd-ts-kit/knex';
+{{/unless}}
+
+export interface {{aggregate.pascal}}Columns {
+  readonly id: string;
+  readonly registered_at: Date;
+  // TODO(domain): add one column per field of {{aggregate.pascal}}State, as the table of create-{{context.kebab}}-tables.schema.ts declares it.
+}
+
+export interface {{aggregate.pascal}}Row extends {{aggregate.pascal}}Columns, {{#if tenant.scoped}}TenantRow, {{/if}}AuditRow {
+  readonly version: number;
+}