ddd-ts-kit 0.0.0-stage → 0.1.1

package/templates/repository/knex/table.tpl

@@ -0,0 +1,23 @@
+@@imports
+{{#if tenant.scoped}}
+import { auditColumns, tenantColumn } from '@ddd-ts-kit/knex';
+{{/if}}
+{{#unless tenant.scoped}}
+import { auditColumns } from '@ddd-ts-kit/knex';
+{{/unless}}
+@@tables
+await create{{aggregate.pascal}}Table(knex);
+@@definitions
+function create{{aggregate.pascal}}Table(knex: Knex): Promise<void> {
+  return knex.schema.withSchema({{context.constant}}_SCHEMA).createTable('{{aggregate.table}}', (table) => {
+    table.text('id').primary();
+    table.timestamp('registered_at', { useTz: true }).notNullable();
+    // TODO(domain): add one column per field of {{aggregate.pascal}}State (and to {{aggregate.pascal}}Columns of {{aggregate.kebab}}-row.schema.ts), with the type and the constraints the storage must enforce.
+    table.integer('version').notNullable();
+{{#if tenant.scoped}}
+    tenantColumn(table);
+    table.index(['tenant_id', 'id'], '{{aggregate.table}}_tenant_idx');
+{{/if}}
+    auditColumns(table);
+  });
+}

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

@@ -0,0 +1,13 @@
+// ddd-ts-kit:imports
+import type { Knex } from 'knex';
+import { {{context.constant}}_SCHEMA } from '{{alias.context}}/infrastructure/persistence/{{context.kebab}}.schema.js';
+// /ddd-ts-kit:imports
+
+export async function create{{context.pascal}}Tables(knex: Knex): Promise<void> {
+  await knex.schema.createSchemaIfNotExists({{context.constant}}_SCHEMA);
+  // ddd-ts-kit:tables
+  // /ddd-ts-kit:tables
+}
+
+// ddd-ts-kit:definitions
+// /ddd-ts-kit:definitions

package/templates/repository/none/repository.ts.tpl

@@ -0,0 +1,48 @@
+import { ConcurrencyError } from '@ddd-ts-kit/kernel';
+{{#if style.declared}}
+import { Repository } from '@ddd-ts-kit/kernel/declarations';
+{{/if}}
+import { {{aggregate.pascal}}, type {{aggregate.pascal}}State } 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}}
+
+interface Stored{{aggregate.pascal}} {
+  readonly state: {{aggregate.pascal}}State;
+  readonly version: number;
+}
+
+{{#if style.declared}}
+@Repository({{aggregate.pascal}}Repository)
+{{/if}}
+export class InMemory{{aggregate.pascal}}Repository implements {{aggregate.pascal}}Repository {
+  private readonly rows = new Map<string, Stored{{aggregate.pascal}}>();
+
+  async findById(id: string): Promise<{{aggregate.pascal}} | undefined> {
+    const row = this.rows.get(id);
+
+    if (row === undefined) {
+      return undefined;
+    }
+
+    const found = {{aggregate.pascal}}.rehydrate(id, structuredClone(row.state));
+
+    found.version = row.version;
+
+    return found;
+  }
+
+  async save(saved: {{aggregate.pascal}}): Promise<void> {
+    const stored = this.rows.get(saved.id)?.version ?? 0;
+
+    if (stored !== saved.version) {
+      throw new ConcurrencyError(saved.id);
+    }
+
+    saved.version = stored + 1;
+    this.rows.set(saved.id, { state: structuredClone(saved.toState()), version: saved.version });
+  }
+}

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

@@ -0,0 +1,21 @@
+import type { AuditStamp } from '@ddd-ts-kit/kernel';
+import { {{aggregate.pascal}} } from '{{alias.context}}/domain/aggregates/{{aggregate.kebab}}.aggregate.js';
+import type { {{context.pascal}}{{aggregate.pascal}} as {{aggregate.pascal}}Row } from '{{alias.generated}}/prisma/client.js';
+
+export type {{aggregate.pascal}}Columns = Omit<{{aggregate.pascal}}Row, 'version' | keyof AuditStamp>;
+
+export const {{aggregate.pascal}}Mapper = {
+  toDomain(row: {{aggregate.pascal}}Row): {{aggregate.pascal}} {
+    // TODO(domain): rebuild each value object of {{aggregate.pascal}}State from its fields.
+    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 fields; nothing of the row type leaves this file.
+    return { id: saved.id, ...saved.toState() };
+  },
+};

package/templates/repository/prisma/model.tpl

@@ -0,0 +1,14 @@
+@@models
+model {{context.pascal}}{{aggregate.pascal}} {
+  id           String   @id
+  registeredAt DateTime @map("registered_at") @db.Timestamptz(3)
+  // TODO(domain): add one field per field of {{aggregate.pascal}}State, with the type and the constraints the storage must enforce; then run `npm run db:client` and `npm run db:generate`.
+  version      Int
+  createdAt    DateTime @map("created_at") @db.Timestamptz(3)
+  createdBy    String   @map("created_by")
+  updatedAt    DateTime @map("updated_at") @db.Timestamptz(3)
+  updatedBy    String   @map("updated_by")
+
+  @@map("{{aggregate.table}}")
+  @@schema("{{context.schema}}")
+}

package/templates/repository/prisma/repository.ts.tpl

@@ -0,0 +1,55 @@
+{{#if style.declared}}
+import { Clock, ExecutionScope, stampCreation, stampUpdate } from '@ddd-ts-kit/kernel';
+import { Repository } from '@ddd-ts-kit/kernel/declarations';
+{{/if}}
+{{#unless style.declared}}
+import { stampCreation, stampUpdate, type Clock, type ExecutionScope } from '@ddd-ts-kit/kernel';
+{{/unless}}
+import { optimisticUpdate } from '@ddd-ts-kit/prisma';
+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.pascal}}Mapper } from '{{alias.context}}/infrastructure/persistence/{{aggregate.kebab}}.mapper.js';
+
+{{#if style.declared}}
+@Repository({{aggregate.pascal}}Repository, [Database, ExecutionScope, Clock])
+{{/if}}
+export class Prisma{{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> {
+    const row = await this.database.client().{{context.camel}}{{aggregate.pascal}}.findUnique({ where: { id } });
+
+    return row === null ? undefined : {{aggregate.pascal}}Mapper.toDomain(row);
+  }
+
+  async save(saved: {{aggregate.pascal}}): Promise<void> {
+    const table = this.database.client().{{context.camel}}{{aggregate.pascal}};
+
+    await optimisticUpdate(saved, async ({ expected, next }) => {
+      const state = { ...{{aggregate.pascal}}Mapper.toRow(saved), version: next };
+
+      const written =
+        expected === 0
+          ? await table.createMany({
+              data: [{ ...state, ...stampCreation(this.scope, this.clock) }],
+              skipDuplicates: true,
+            })
+          : await table.updateMany({
+              where: { id: saved.id, version: expected },
+              data: { ...state, ...stampUpdate(this.scope, this.clock) },
+            });
+
+      return written.count;
+    });
+  }
+}

package/templates/repository/repository.ts.tpl

@@ -0,0 +1,6 @@
+import { Repository } from '@ddd-ts-kit/kernel';
+import type { {{aggregate.pascal}} } from '{{alias.context}}/domain/aggregates/{{aggregate.kebab}}.aggregate.js';
+
+export abstract class {{aggregate.pascal}}Repository extends Repository<{{aggregate.pascal}}> {
+  // TODO(domain): add only the lookups a use case needs, as abstract methods named in the ubiquitous language (for example `abstract findByNumber(number: InvoiceNumber): Promise<{{aggregate.pascal}} | undefined>`); queries for screens go through a read port instead.
+}

package/templates/repository/typeorm/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.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/typeorm/repository.ts.tpl

@@ -0,0 +1,58 @@
+{{#if style.declared}}
+import { Clock, ExecutionScope, stampCreation, stampUpdate } from '@ddd-ts-kit/kernel';
+import { Repository } from '@ddd-ts-kit/kernel/declarations';
+{{/if}}
+{{#unless style.declared}}
+import { stampCreation, stampUpdate, type Clock, type ExecutionScope } from '@ddd-ts-kit/kernel';
+{{/unless}}
+import { {{storage.typeormImport}}, insertIgnoringConflict, optimisticUpdate } from '@ddd-ts-kit/typeorm';
+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 { {{aggregate.tableCamel}} } 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 } from '{{alias.context}}/infrastructure/persistence/{{aggregate.kebab}}-row.schema.js';
+
+type Versioned{{aggregate.pascal}} = {{aggregate.pascal}}Columns & { version: number };
+
+{{#if style.declared}}
+@Repository({{aggregate.pascal}}Repository, [TypeOrmContext, ExecutionScope, Clock])
+{{/if}}
+export class TypeOrm{{aggregate.pascal}}Repository implements {{aggregate.pascal}}Repository {
+  constructor(
+    private readonly database: TypeOrmContext,
+    private readonly scope: ExecutionScope,
+    private readonly clock: Clock,
+  ) {}
+
+  async findById(id: string): Promise<{{aggregate.pascal}} | undefined> {
+    const row = await this.database.manager().findOneBy({{aggregate.tableCamel}}, { id });
+
+    return row === null ? 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, ...stampCreation(this.scope, this.clock) };
+
+    return (await insertIgnoringConflict(this.database.manager(), {{aggregate.tableCamel}}, row)) ? 1 : 0;
+  }
+
+  private async update(state: Versioned{{aggregate.pascal}}, expected: number): Promise<number> {
+    const row = { ...state, ...stampUpdate(this.scope, this.clock) };
+    const updated = await this.database.manager().update({{aggregate.tableCamel}}, { id: state.id, version: expected }, row);
+
+    return updated.affected ?? 0;
+  }
+}

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

@@ -0,0 +1,11 @@
+import type { AuditStamp } from '@ddd-ts-kit/kernel';
+
+export interface {{aggregate.pascal}}Columns {
+  id: string;
+  registeredAt: Date;
+  // TODO(domain): add one field per field of {{aggregate.pascal}}State, as the entity schema of {{context.kebab}}.schema.ts declares it.
+}
+
+export interface {{aggregate.pascal}}Row extends {{aggregate.pascal}}Columns, AuditStamp {
+  version: number;
+}

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

@@ -0,0 +1,4 @@
+@@imports
+import { {{aggregate.tableCamel}} } from '{{alias.context}}/infrastructure/persistence/{{context.kebab}}.schema.js';
+@@schemas
+{{aggregate.tableCamel}},

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

@@ -0,0 +1,9 @@
+// ddd-ts-kit:imports
+import { EntitySchema } from 'typeorm';
+import { auditColumns, schemaNameOf } from '@ddd-ts-kit/typeorm';
+// /ddd-ts-kit:imports
+
+const {{context.constant}}_SCHEMA = schemaNameOf('{{context.kebab}}');
+
+// ddd-ts-kit:tables
+// /ddd-ts-kit:tables

package/templates/repository/typeorm/table.tpl

@@ -0,0 +1,15 @@
+@@imports
+import type { {{aggregate.pascal}}Row } from '{{alias.context}}/infrastructure/persistence/{{aggregate.kebab}}-row.schema.js';
+@@tables
+export const {{aggregate.tableCamel}} = new EntitySchema<{{aggregate.pascal}}Row>({
+  name: '{{context.pascal}}{{aggregate.pascal}}',
+  tableName: '{{aggregate.table}}',
+  schema: {{context.constant}}_SCHEMA,
+  columns: {
+    id: { type: 'text', primary: true },
+    registeredAt: { name: 'registered_at', type: 'timestamptz' },
+    // TODO(domain): add one column per field of {{aggregate.pascal}}State (and to {{aggregate.pascal}}Columns of {{aggregate.kebab}}-row.schema.ts), with the type and the constraints the storage must enforce; then run `npm run db:generate`.
+    version: { type: 'int' },
+    ...auditColumns(),
+  },
+});

package/templates/repository/wiring.manual.tpl

@@ -0,0 +1,9 @@
+@@imports
+import { {{adapter.pascal}}{{aggregate.pascal}}Repository } from '{{alias.context}}/infrastructure/persistence/{{adapter.kebab}}-{{aggregate.kebab}}.repository.js';
+@@registrations
+{{#if adapter.needsDatabase}}
+const {{aggregate.camel}}Repository = platform.adapter(new {{adapter.pascal}}{{aggregate.pascal}}Repository(platform.persistence.database, platform.scope, platform.clock), { kind: 'repository', context: '{{context.kebab}}', token: '{{aggregate.pascal}}Repository' });
+{{/if}}
+{{#unless adapter.needsDatabase}}
+const {{aggregate.camel}}Repository = platform.adapter(new {{adapter.pascal}}{{aggregate.pascal}}Repository(), { kind: 'repository', context: '{{context.kebab}}', token: '{{aggregate.pascal}}Repository' });
+{{/unless}}

package/templates/repository/wiring.tsyringe.tpl

@@ -0,0 +1,14 @@
+@@imports
+{{#if adapter.needsDatabase}}
+import { Clock, ExecutionScope } from '@ddd-ts-kit/kernel';
+{{storage.moduleImport}}
+{{/if}}
+import { {{aggregate.pascal}}Repository } from '{{alias.context}}/domain/repositories/{{aggregate.kebab}}.repository.js';
+import { {{adapter.pascal}}{{aggregate.pascal}}Repository } from '{{alias.context}}/infrastructure/persistence/{{adapter.kebab}}-{{aggregate.kebab}}.repository.js';
+@@registrations
+{{#if adapter.needsDatabase}}
+builder.bind({{aggregate.pascal}}Repository).toClass({{adapter.pascal}}{{aggregate.pascal}}Repository, [{{storage.token}}, ExecutionScope, Clock]).as('repository');
+{{/if}}
+{{#unless adapter.needsDatabase}}
+builder.bind({{aggregate.pascal}}Repository).toClass({{adapter.pascal}}{{aggregate.pascal}}Repository).as('repository');
+{{/unless}}

package/templates/route/dto.accepted.ts.tpl

@@ -0,0 +1,6 @@
+import { IsString } from 'class-validator';
+
+export class {{name.pascal}}Accepted {
+  @IsString()
+  id = '';
+}

package/templates/route/dto.answer.ts.tpl

@@ -0,0 +1,3 @@
+export class {{name.pascal}}Answer {
+  // TODO(domain): declare the fields of {{name.pascal}}Result that are part of the public contract, each with its class-validator decorators.
+}

package/templates/route/dto.body.ts.tpl

@@ -0,0 +1,3 @@
+export class {{name.pascal}}Body {
+  // TODO(domain): declare the fields the client sends for "{{name.words}}", each with its class-validator decorators (shape constraints only; business rules stay in the domain).
+}

package/templates/route/dto.line.ts.tpl

@@ -0,0 +1,8 @@
+import { IsString } from 'class-validator';
+
+export class {{name.pascal}}Line {
+  @IsString()
+  id = '';
+
+  // TODO(domain): declare the fields of {{name.pascal}}Item that are part of the public contract, each with its class-validator decorators.
+}

package/templates/route/dto.params.ts.tpl

@@ -0,0 +1,5 @@
+import { IsString } from 'class-validator';
+
+export class {{name.pascal}}Params {
+  {{route.dtoParams}}
+}

package/templates/route/route.class-validator.ts.tpl

@@ -0,0 +1,70 @@
+{{#if route.protected}}
+import { actorOf } from '@ddd-ts-kit/auth';
+{{/if}}
+import { defineRoute, type Route } from '@ddd-ts-kit/http';
+import type { {{route.busType}} } from '@ddd-ts-kit/kernel';
+import { classSchema } from '@ddd-ts-kit/validation/class-validator';
+{{route.useCaseImport}}
+{{route.dtoImports}}
+
+{{#if route.hasParams}}
+const params = classSchema({{name.pascal}}Params);
+{{/if}}
+{{#if route.hasBody}}
+// TODO(domain): once {{name.pascal}}Body has its decorated fields, drop the second argument: it only lets a class without any decorated field through.
+const body = classSchema({{name.pascal}}Body, { validator: { forbidUnknownValues: false } });
+{{/if}}
+{{#if route.returnsId}}
+const accepted = classSchema({{name.pascal}}Accepted);
+{{/if}}
+{{#if route.isQuery}}
+// TODO(domain): once {{name.pascal}}Answer has its decorated fields, drop the second argument: it only lets a class without any decorated field through.
+const answer = classSchema({{name.pascal}}Answer, { validator: { forbidUnknownValues: false } });
+{{/if}}
+
+export function {{name.camel}}Route({{route.bus}}: {{route.busType}}): Route {
+  return defineRoute(
+    {
+      method: '{{route.method}}',
+      path: '{{route.path}}',
+      operationId: '{{name.camel}}',
+      summary: '{{name.title}}',
+      tags: ['{{context.kebab}}'],
+      {{#if route.hasRequest}}
+      request: { {{route.requestParts}} },
+      {{/if}}
+      {{#if route.returnsId}}
+      responses: { {{route.status}}: { description: 'Done; the body carries the identifier.', body: accepted } },
+      {{/if}}
+      {{#if route.returnsNothing}}
+      responses: { {{route.status}}: { description: 'Done.' } },
+      {{/if}}
+      {{#if route.isQuery}}
+      responses: { {{route.status}}: { description: 'The answer.', body: answer } },
+      {{/if}}
+      // TODO(domain): list the codes of the DomainErrors "{{name.words}}" can raise, so that they appear in the contract with their status.
+      errors: [{{route.errorCodes}}],
+      security: {{route.security}},
+    },
+    async (input) => {
+      {{#if route.isQuery}}
+      // TODO(domain): build the query from `input` (params, query string); the actor is already there and map its answer to the public fields.
+      await {{route.bus}}.execute(new {{route.input}}({{route.actor}}));
+
+      return { status: {{route.status}}, body: {} };
+      {{/if}}
+      {{#if route.returnsId}}
+      // TODO(domain): build the command from `input` (body, params); the actor is already there.
+      const id = await {{route.bus}}.execute(new {{route.input}}({{route.actor}}));
+
+      return { status: {{route.status}}, body: { id } };
+      {{/if}}
+      {{#if route.returnsNothing}}
+      // TODO(domain): build the command from `input` (body, params); the actor is already there.
+      await {{route.bus}}.execute(new {{route.input}}({{route.actor}}));
+
+      return { status: {{route.status}} };
+      {{/if}}
+    },
+  );
+}

package/templates/route/route.none.ts.tpl

@@ -0,0 +1,89 @@
+{{#if route.protected}}
+import { actorOf } from '@ddd-ts-kit/auth';
+{{/if}}
+import { defineRoute, type Route } from '@ddd-ts-kit/http';
+{{#if route.usesSchema}}
+import { err, ok, type {{route.busType}} } from '@ddd-ts-kit/kernel';
+import { customSchema } from '@ddd-ts-kit/validation';
+{{/if}}
+{{#unless route.usesSchema}}
+import type { {{route.busType}} } from '@ddd-ts-kit/kernel';
+{{/unless}}
+{{route.useCaseImport}}
+
+{{#if route.usesAnyObject}}
+const anyObject = customSchema<Record<string, unknown>>(
+  (input) =>
+    typeof input === 'object' && input !== null && !Array.isArray(input)
+      ? ok({ ...input })
+      : err([{ path: '', code: 'invalid_type', message: 'An object is expected.' }]),
+  { type: 'object' },
+);
+
+{{/if}}
+{{#if route.hasBody}}
+// TODO(domain): replace `anyObject` by a schema checking the fields the client sends for "{{name.words}}" (shape constraints only; business rules stay in the domain) and describing them in JSON Schema.
+const body = anyObject;
+
+{{/if}}
+{{#if route.returnsId}}
+const accepted = customSchema<{ readonly id: string }>(
+  (input) =>
+    typeof input === 'object' && input !== null && 'id' in input && typeof input.id === 'string'
+      ? ok({ id: input.id })
+      : err([{ path: 'id', code: 'invalid_type', message: 'An identifier is expected.' }]),
+  { type: 'object', required: ['id'], properties: { id: { type: 'string' } } },
+);
+
+{{/if}}
+{{#if route.isQuery}}
+// TODO(domain): replace `anyObject` by a schema of the fields of {{name.pascal}}Result that are part of the public contract.
+const answer = anyObject;
+
+{{/if}}
+export function {{name.camel}}Route({{route.bus}}: {{route.busType}}): Route {
+  return defineRoute(
+    {
+      method: '{{route.method}}',
+      path: '{{route.path}}',
+      operationId: '{{name.camel}}',
+      summary: '{{name.title}}',
+      tags: ['{{context.kebab}}'],
+      {{#if route.hasBody}}
+      request: { body },
+      {{/if}}
+      {{#if route.returnsId}}
+      responses: { {{route.status}}: { description: 'Done; the body carries the identifier.', body: accepted } },
+      {{/if}}
+      {{#if route.returnsNothing}}
+      responses: { {{route.status}}: { description: 'Done.' } },
+      {{/if}}
+      {{#if route.isQuery}}
+      responses: { {{route.status}}: { description: 'The answer.', body: answer } },
+      {{/if}}
+      // TODO(domain): list the codes of the DomainErrors "{{name.words}}" can raise, so that they appear in the contract with their status.
+      errors: [{{route.errorCodes}}],
+      security: {{route.security}},
+    },
+    async (input) => {
+      {{#if route.isQuery}}
+      // TODO(domain): build the query from `input` (params, query string); the actor is already there and map its answer to the public fields.
+      await {{route.bus}}.execute(new {{route.input}}({{route.actor}}));
+
+      return { status: {{route.status}}, body: {} };
+      {{/if}}
+      {{#if route.returnsId}}
+      // TODO(domain): build the command from `input` (body, params); the actor is already there.
+      const id = await {{route.bus}}.execute(new {{route.input}}({{route.actor}}));
+
+      return { status: {{route.status}}, body: { id } };
+      {{/if}}
+      {{#if route.returnsNothing}}
+      // TODO(domain): build the command from `input` (body, params); the actor is already there.
+      await {{route.bus}}.execute(new {{route.input}}({{route.actor}}));
+
+      return { status: {{route.status}} };
+      {{/if}}
+    },
+  );
+}

package/templates/route/route.search.ts.tpl

@@ -0,0 +1,82 @@
+{{#if validation.zod}}
+import { z } from 'zod';
+{{/if}}
+import { actorOf } from '@ddd-ts-kit/auth';
+import { defineRoute, pageQuerySchema, pageResponse, pageSchemaOf, type Route } from '@ddd-ts-kit/http';
+{{#if search.customSchema}}
+import { err, ok, type QueryBus } from '@ddd-ts-kit/kernel';
+import { customSchema } from '@ddd-ts-kit/validation';
+{{/if}}
+{{#unless search.customSchema}}
+import type { QueryBus } from '@ddd-ts-kit/kernel';
+{{/unless}}
+{{#if validation.zod}}
+import { zodSchema } from '@ddd-ts-kit/validation/zod';
+{{/if}}
+{{#if validation.classValidator}}
+import { classSchema } from '@ddd-ts-kit/validation/class-validator';
+{{/if}}
+{{route.useCaseImport}}
+{{#if validation.classValidator}}
+import { {{name.pascal}}Line } from '{{alias.context}}/presentation/http/{{name.kebab}}-line.dto.js';
+{{/if}}
+
+// TODO(domain): list here the fields of {{name.pascal}}Sort a client may sort by, and bound the size of a page.
+const query = pageQuerySchema({ sortable: ['id'], maxSize: 100 });
+
+{{#if validation.zod}}
+const line = zodSchema(
+  z.object({
+    id: z.string(),
+    // TODO(domain): declare the fields of {{name.pascal}}Item that are part of the public contract.
+  }),
+  { io: 'output' },
+);
+{{/if}}
+{{#if validation.classValidator}}
+const line = classSchema({{name.pascal}}Line);
+{{/if}}
+{{#if search.customSchema}}
+interface {{name.pascal}}Line {
+  readonly id: string;
+  // TODO(domain): declare the fields of {{name.pascal}}Item that are part of the public contract, here and in the schema below.
+}
+
+const line = customSchema<{{name.pascal}}Line>(
+  (input) => (isLine(input) ? ok(input) : err([{ path: 'id', code: 'invalid_type', message: 'Expected a text.' }])),
+  {
+    type: 'object',
+    required: ['id'],
+    properties: { id: { type: 'string' } },
+  },
+);
+{{/if}}
+
+export function {{name.camel}}Route(queries: QueryBus): Route {
+  return defineRoute(
+    {
+      method: '{{route.method}}',
+      path: '{{route.path}}',
+      operationId: '{{name.camel}}',
+      summary: '{{name.title}}',
+      tags: ['{{context.kebab}}'],
+      request: { query },
+      responses: { 200: { description: 'One page of the search.', body: pageSchemaOf(line) } },
+      // TODO(domain): list the codes of the DomainErrors "{{name.words}}" can raise, so that they appear in the contract with their status.
+      errors: ['UNAUTHORIZED', 'FORBIDDEN'],
+      security: {{route.security}},
+    },
+    async (input) => {
+      // TODO(domain): hand the criteria of the query over too, once the query schema declares them next to the page; map each line to its public fields.
+      const page = await queries.execute(new {{route.input}}(actorOf(input.context.principal), input.query));
+
+      return { status: 200, body: pageResponse(page, (item) => ({ id: item.id })) };
+    },
+  );
+}
+{{#if search.customSchema}}
+
+function isLine(input: unknown): input is {{name.pascal}}Line {
+  return typeof input === 'object' && input !== null && 'id' in input && typeof input.id === 'string';
+}
+{{/if}}

package/templates/route/route.spec.ts.tpl

@@ -0,0 +1,42 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { executeRoute } from '@ddd-ts-kit/http';
+import { {{route.busClass}} } from '@ddd-ts-kit/kernel';
+{{route.messageImport}}
+import { {{name.camel}}Route } from '{{alias.context}}/presentation/http/{{name.kebab}}.route.js';
+
+describe('{{route.method}} {{route.path}}', () => {
+  it('answers {{route.status}} when the use case succeeds', async () => {
+    {{#if route.isPlainQuery}}
+    const {{route.bus}} = new {{route.busClass}}().register({{route.input}}, {
+      execute: async () => ({}),
+    });
+    {{/if}}
+    {{#if route.isSearch}}
+    const {{route.bus}} = new {{route.busClass}}().register({{route.input}}, {
+      execute: async () => ({ items: [{ id: '{{name.kebab}}-1' }], total: 1 }),
+    });
+    {{/if}}
+    {{#if route.returnsId}}
+    const {{route.bus}} = new {{route.busClass}}().register({{route.input}}, {
+      execute: async () => '{{name.kebab}}-1',
+    });
+    {{/if}}
+    {{#if route.returnsNothing}}
+    const {{route.bus}} = new {{route.busClass}}().register({{route.input}}, {
+      execute: async () => undefined,
+    });
+    {{/if}}
+
+    const response = await executeRoute(
+      {{name.camel}}Route({{route.bus}}),
+      { params: {{route.sampleParams}}, query: {}, headers: {}, body: {}, raw: undefined },
+      { validateResponses: true },
+    );
+
+    expect(response.status).toBe({{route.status}});
+  });
+
+  // TODO(domain): replace each entry below by a test of the contract a client relies on.
+  it.todo('refuses an input that does not have the expected shape with 422');
+  it.todo('answers the documented status for each error code of the use case');
+});