ddd-ts-kit 0.0.0-stage → 0.1.1

package/templates/pipeline/renovate.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended", ":semanticCommits", ":semanticCommitTypeAll(chore)"],
+  "timezone": "Etc/UTC",
+  "schedule": ["before 6am on monday"],
+  "prConcurrentLimit": 5,
+  "prHourlyLimit": 0,
+  "minimumReleaseAge": "7 days",
+  "rangeStrategy": "bump",
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": ["before 6am on the first day of the month"]
+  },
+  "vulnerabilityAlerts": {
+    "enabled": true,
+    "schedule": ["at any time"],
+    "minimumReleaseAge": null
+  },
+  "packageRules": [
+    {
+      "groupName": "production dependencies (minor and patch)",
+      "matchDepTypes": ["dependencies"],
+      "matchUpdateTypes": ["minor", "patch"]
+    },
+    {
+      "groupName": "development dependencies (minor and patch)",
+      "matchDepTypes": ["devDependencies"],
+      "matchUpdateTypes": ["minor", "patch"]
+    },
+    {
+      "groupName": "container images",
+      "matchManagers": ["dockerfile", "docker-compose"]
+    },
+    {
+      "groupName": "CI",
+      "matchManagers": ["github-actions", "gitlabci", "gitlabci-include"],
+      "semanticCommitType": "ci"
+    },
+    {
+      "groupName": "tests",
+      "matchPackageNames": ["vitest", "@vitest/**", "@faker-js/faker"]
+    },
+    {
+      "groupName": "git hooks",
+      "matchPackageNames": ["lefthook", "@commitlint/**"]
+    },
+    {
+      "description": "Static analysis: typescript-eslint pins the TypeScript range it supports.",
+      "groupName": "static analysis",
+      "matchPackageNames": [
+        "eslint",
+        "eslint-*",
+        "@eslint/**",
+        "typescript-eslint",
+        "@typescript-eslint/**",
+        "typescript",
+        "knip",
+        "dependency-cruiser"
+      ]
+    },
+    {
+      "description": "The kit moves as one: runtime packages, checker and lint plugin share a release.",
+      "groupName": "ddd-ts-kit",
+      "matchPackageNames": ["ddd-ts-kit", "@ddd-ts-kit/**"]
+    }
+  ]
+}

package/templates/pipeline/vitest.config.ts.tpl

@@ -0,0 +1,52 @@
+import { governedCoverage, unaffectedContexts } from '@ddd-ts-kit/testing/coverage';
+{{#if decorators.standard}}
+import { decorators } from '@ddd-ts-kit/testing/vitest';
+{{/if}}
+{{#if decorators.legacy}}
+import { decoratorCoverage } from '@ddd-ts-kit/testing/vitest';
+{{/if}}
+import { defineConfig } from 'vitest/config';
+
+const INTEGRATION_SPECS = '{{config.contextsDir}}/*/test/integration/**/*.spec.ts';
+const INTEGRATION_MODE = 'integration';
+// A pull request names the contexts its change reaches (DDD_TS_KIT_AFFECTED, from `ddd-ts-kit affected`): the specs of the others are left to the default branch.
+const NOT_AFFECTED = unaffectedContexts().map((directory) => `${directory}**`);
+
+export default defineConfig(({ mode }) => ({
+  {{#if decorators.standard}}
+  // Vitest does not lower standard (TC39) decorators, which every class of a declared context carries: the compiler the project builds with does.
+  plugins: [decorators({ compiler: '@typescript/native' })],
+  {{/if}}
+  {{#if decorators.legacy}}
+  // Under `emitDecoratorMetadata` the transform guards every type a decorated class names with a branch no test can take: the statements that apply decorators are kept out of the measure.
+  plugins: [decoratorCoverage()],
+  {{/if}}
+  // An import alias is resolved from the "paths" of tsconfig.json, which name the sources.
+  resolve: { tsconfigPaths: true },
+  test: {
+    // The integration project has no spec before the first repository or adapter of the project: its run passes until then.
+    passWithNoTests: mode === INTEGRATION_MODE,
+    {{#if assembly.discovery}}
+    // Discovery imports the role files of a context itself: inlined, the package loads them through the runner, which compiles them.
+    server: { deps: { inline: ['@ddd-ts-kit/di'] } },
+    {{/if}}
+    projects: [
+      {
+        extends: true,
+        test: {
+          name: 'unit',
+          include: ['{{config.sourceRoot}}/**/*.spec.ts', 'test/architecture/**/*.spec.ts'],
+          exclude: [INTEGRATION_SPECS, ...NOT_AFFECTED],
+        },
+      },
+      { extends: true, test: { name: INTEGRATION_MODE, include: [INTEGRATION_SPECS], exclude: NOT_AFFECTED } },
+    ],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'cobertura', 'lcov'],
+      reportsDirectory: 'coverage',
+      // What is measured and the floor of each layer come from "coverage" in ddd-ts-kit.config.json, the reference when it is absent: a threshold is written nowhere else.
+      ...governedCoverage(mode),
+    },
+  },
+}));

package/templates/policy/policy.declared.ts.tpl

@@ -0,0 +1,11 @@
+import { isAuthenticated, type Actor } from '@ddd-ts-kit/kernel';
+import { Policy } from '@ddd-ts-kit/kernel/declarations';
+import { {{context.camel}}Permissions } from '{{alias.context}}/application/authorization/{{context.kebab}}.permissions.js';
+
+// TODO(domain): give `allows` the aggregate "{{name.words}}" reads as its second parameter, add `appliesTo(subject: unknown): boolean { return subject instanceof <Aggregate>; }`, and decide from the actor, the loaded element and `now`; the handler asks it through `Access.authorize(command.actor, permission, element)`.
+@Policy({{context.camel}}Permissions['{{access.permission}}'], { name: '{{context.kebab}}.{{name.kebab}}' })
+export class {{name.pascal}}Policy {
+  allows(actor: Actor): boolean {
+    return isAuthenticated(actor);
+  }
+}

package/templates/policy/policy.spec.declared.ts.tpl

@@ -0,0 +1,26 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { anActor } from '@ddd-ts-kit/auth/testing';
+import { anonymousActor } from '@ddd-ts-kit/kernel';
+import { declarationOf } from '@ddd-ts-kit/kernel/declarations';
+import { {{name.pascal}}Policy } from '{{alias.context}}/application/authorization/{{name.kebab}}.policy.js';
+
+describe('{{name.title}}', () => {
+  it('bears on the permission {{access.permission}}, under a name of its own', () => {
+    expect(declarationOf({{name.pascal}}Policy)).toMatchObject({
+      role: 'policy',
+      name: '{{context.kebab}}.{{name.kebab}}',
+      permission: { id: '{{context.kebab}}:{{access.permission}}' },
+    });
+  });
+
+  it('refuses a caller nobody identified', () => {
+    const policy = new {{name.pascal}}Policy();
+
+    expect(policy.allows(anonymousActor())).toBe(false);
+    expect(policy.allows(anActor().build())).toBe(true);
+  });
+
+  // TODO(domain): replace each entry below by a case of the rule, with an element built by the builders of test/builders.
+  it.todo('allows the actor the rule is written for');
+  it.todo('refuses every other actor, whatever their role');
+});

package/templates/policy/policy.spec.ts.tpl

@@ -0,0 +1,21 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { anActor } from '@ddd-ts-kit/auth/testing';
+import { anonymousActor } from '@ddd-ts-kit/kernel';
+import { {{name.camel}} } from '{{alias.context}}/application/authorization/{{name.kebab}}.policy.js';
+
+const now = new Date('2026-01-01T00:00:00.000Z');
+
+describe('{{name.title}}', () => {
+  it('bears on the permission {{access.permission}}', () => {
+    expect({{name.camel}}.permission.id).toBe('{{context.kebab}}:{{access.permission}}');
+  });
+
+  it('refuses a caller nobody identified', () => {
+    expect({{name.camel}}.allows(anonymousActor(), {}, { now })).toBe(false);
+    expect({{name.camel}}.allows(anActor().build(), {}, { now })).toBe(true);
+  });
+
+  // TODO(domain): replace each entry below by a case of the rule, with an element built by the builders of test/builders.
+  it.todo('allows the actor the rule is written for');
+  it.todo('refuses every other actor, whatever their role');
+});

package/templates/policy/policy.ts.tpl

@@ -0,0 +1,10 @@
+import { definePolicy } from '@ddd-ts-kit/auth';
+import { isAuthenticated } from '@ddd-ts-kit/kernel';
+import { {{context.camel}}Permissions } from '{{alias.context}}/application/authorization/{{context.kebab}}.permissions.js';
+
+// TODO(domain): replace `unknown` by the aggregate "{{name.words}}" reads, add `appliesTo: (subject): subject is <Aggregate> => subject instanceof <Aggregate>`, and decide from the actor, the loaded element and `now`; the handler asks it through `Access.authorize(command.actor, permission, element)`.
+export const {{name.camel}} = definePolicy<unknown>({
+  name: '{{name.kebab}}',
+  permission: {{context.camel}}Permissions['{{access.permission}}'],
+  allows: (actor) => isAuthenticated(actor),
+});

package/templates/policy/registration.tpl

@@ -0,0 +1,4 @@
+@@imports
+import { {{name.camel}} } from '{{alias.context}}/application/authorization/{{name.kebab}}.policy.js';
+@@policies
+{{name.camel}},

package/templates/port/fake.ts.tpl

@@ -0,0 +1,5 @@
+import type { {{name.pascal}} } from '{{alias.context}}/application/ports/{{name.kebab}}.port.js';
+
+export class Fake{{name.pascal}} implements {{name.pascal}} {
+  // TODO(domain): implement each operation of {{name.pascal}} in memory, and expose what was received so that a test can assert on it without a mocking library.
+}

package/templates/port/port.ts.tpl

@@ -0,0 +1,3 @@
+export abstract class {{name.pascal}} {
+  // TODO(domain): declare what the application needs from the outside world as abstract methods, in its own words and types (for example `abstract charge(amount: Money): Promise<PaymentReference>`); nothing here names a technology.
+}

package/templates/query/handler.declared.ts.tpl

@@ -0,0 +1,14 @@
+import { QueryHandler } from '@ddd-ts-kit/kernel/declarations';
+import { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port.js';
+import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import type { {{name.pascal}}Result } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+
+@QueryHandler({{name.pascal}}Query, [{{name.pascal}}Reader])
+export class {{name.pascal}}Handler implements QueryHandler<{{name.pascal}}Query> {
+  constructor(private readonly reader: {{name.pascal}}Reader) {}
+
+  async execute(query: {{name.pascal}}Query): Promise<{{name.pascal}}Result> {
+    // TODO(domain): narrow what is read to what the asker may see: ask `Access.scope(query.actor, permission, '<type>')` for the scope and hand it to the reader, never filter in memory after loading; a query never changes state.
+    return this.reader.read(query);
+  }
+}

package/templates/query/handler.spec.buses.ts.tpl

@@ -0,0 +1,54 @@
+import { describe, expect, it } from '{{tests.module}}';
+{{#if access.protected}}
+import { AuthorizationMap, RoleBasedAuthorizer, authorizationMiddleware, requires } from '@ddd-ts-kit/auth';
+import { anActor } from '@ddd-ts-kit/auth/testing';
+{{/if}}
+import { createTestBuses } from '@ddd-ts-kit/testing';
+{{#if access.protected}}
+import { {{context.camel}}Permissions } from '{{alias.context}}/application/authorization/{{context.kebab}}.permissions.js';
+{{/if}}
+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 type { {{name.pascal}}Result } 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';
+{{#if access.protected}}
+
+const holders = authorizationMiddleware({
+  authorizer: new RoleBasedAuthorizer({
+    roles: { holder: [{{context.camel}}Permissions['{{access.permission}}']] },
+  }),
+  map: AuthorizationMap.of(requires({{name.pascal}}Query, {{context.camel}}Permissions['{{access.permission}}'])),
+});
+
+const holder = anActor().withRole('holder').build();
+{{/if}}
+
+describe('{{name.title}}', () => {
+  it('answers what the read model holds', async () => {
+    const answer: {{name.pascal}}Result = {};
+    const queryBus = arrange(answer);
+    const query = new {{name.pascal}}Query({{access.holder}});
+
+    expect(await queryBus.execute(query)).toEqual(answer);
+  });
+  {{#if access.protected}}
+
+  it('is refused to an actor who does not hold the permission {{access.permission}}', async () => {
+    const queryBus = arrange({});
+    const query = new {{name.pascal}}Query(anActor().build());
+
+    await expect(queryBus.execute(query)).rejects.toMatchObject({ code: 'FORBIDDEN' });
+  });
+  {{/if}}
+
+  // TODO(domain): replace each entry below by a test named after what "{{name.words}}" shows and to whom.
+  it.todo('answers only what the asker is allowed to see');
+  it.todo('applies each criterion of the query');
+});
+
+function arrange(answer: {{name.pascal}}Result) {
+  const { queryBus } = createTestBuses();
+  const handler = new {{name.pascal}}Handler(new Fake{{name.pascal}}Reader(answer));
+
+  return queryBus{{spec.guard}}.register({{name.pascal}}Query, handler);
+}

package/templates/query/handler.spec.tsyringe.ts.tpl

@@ -0,0 +1,64 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { RoleBasedAuthorizer } from '@ddd-ts-kit/auth';
+import { authorizationModule } from '@ddd-ts-kit/auth/di';
+{{#if access.protected}}
+import { anActor } from '@ddd-ts-kit/auth/testing';
+{{/if}}
+{{spec.diWithFake}}
+{{spec.contextImports}}
+import { platformTestModule } from '{{alias.platform}}/platform-test.module.js';
+{{#if access.protected}}
+import { {{context.camel}}Permissions } from '{{alias.context}}/application/authorization/{{context.kebab}}.permissions.js';
+{{/if}}
+import { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port.js';
+import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import type { {{name.pascal}}Result } 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';
+{{#if access.protected}}
+
+const holders = authorizationModule({
+  authorizer: new RoleBasedAuthorizer({
+    roles: { holder: [{{context.camel}}Permissions['{{access.permission}}']] },
+  }),
+});
+
+const holder = anActor().withRole('holder').build();
+{{/if}}
+{{#if access.public}}
+
+const authorization = authorizationModule({ authorizer: new RoleBasedAuthorizer({ roles: {} }) });
+{{/if}}
+
+describe('{{name.title}}', () => {
+  it('answers what the read model holds', async () => {
+    const answer: {{name.pascal}}Result = {};
+    const application = {{spec.await}}arrange(answer);
+    const query = new {{name.pascal}}Query({{access.holder}});
+
+    expect(await application.queryBus.execute(query)).toEqual(answer);
+  });
+{{#if access.protected}}
+
+  it('is refused to an actor who does not hold the permission {{access.permission}}', async () => {
+    const application = {{spec.await}}arrange({});
+    const query = new {{name.pascal}}Query(anActor().build());
+
+    await expect(application.queryBus.execute(query)).rejects.toMatchObject({ code: 'FORBIDDEN' });
+  });
+{{/if}}
+
+  // TODO(domain): replace each entry below by a test named after what "{{name.words}}" shows and to whom.
+  it.todo('answers only what the asker is allowed to see');
+  it.todo('applies each criterion of the query');
+});
+
+{{spec.async}}function arrange(answer: {{name.pascal}}Result) {
+{{#if spec.assembles}}
+  const context = {{spec.context}};
+
+{{/if}}
+  return createTestApplication({
+    modules: [{{spec.modules}}],
+    fakes: [fake({{name.pascal}}Reader, new Fake{{name.pascal}}Reader(answer))],
+  });
+}

package/templates/query/handler.ts.tpl

@@ -0,0 +1,13 @@
+import type { QueryHandler } from '@ddd-ts-kit/kernel';
+import type { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port.js';
+import type { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import type { {{name.pascal}}Result } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+
+export class {{name.pascal}}Handler implements QueryHandler<{{name.pascal}}Query> {
+  constructor(private readonly reader: {{name.pascal}}Reader) {}
+
+  async execute(query: {{name.pascal}}Query): Promise<{{name.pascal}}Result> {
+    // TODO(domain): narrow what is read to what the asker may see: ask `Access.scope(query.actor, permission, '<type>')` for the scope and hand it to the reader, never filter in memory after loading; a query never changes state.
+    return this.reader.read(query);
+  }
+}

package/templates/query/query.ts.tpl

@@ -0,0 +1,13 @@
+import { {{access.queryBase}} } from '@ddd-ts-kit/kernel';
+{{#if style.declared}}
+import { {{access.decorator}} } from '@ddd-ts-kit/kernel/declarations';
+{{access.useCasePermissionsImport}}
+{{/if}}
+import type { {{name.pascal}}Result } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+
+{{#if style.declared}}
+@{{access.decoration}}
+{{/if}}
+export class {{name.pascal}}Query extends {{access.queryBase}}<{{name.pascal}}Result> {
+  // TODO(domain): declare the criteria of "{{name.words}}" as a constructor with readonly primitives (filters, page), for example `{{access.constructorSample}}`.
+}

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

@@ -0,0 +1,8 @@
+import type { {{name.pascal}}Result } 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 answer: {{name.pascal}}Result) {
+    super();
+  }
+}

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

@@ -0,0 +1,21 @@
+{{#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}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import type { {{name.pascal}}Result } 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 answer: {{name.pascal}}Result = {};
+
+  async read(query: {{name.pascal}}Query): Promise<{{name.pascal}}Result> {
+    // TODO(domain): replace this canned answer by a real read of the projection, filtered by `query`; a production adapter (SQL view, search index) implements the same port next to this file.
+    return this.answer;
+  }
+}

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

@@ -0,0 +1,6 @@
+import type { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import type { {{name.pascal}}Result } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+
+export abstract class {{name.pascal}}Reader {
+  abstract read(query: {{name.pascal}}Query): Promise<{{name.pascal}}Result>;
+}

package/templates/query/result.ts.tpl

@@ -0,0 +1,3 @@
+export interface {{name.pascal}}Result {
+  // TODO(domain): declare the answer exactly as the reader needs it, flat and serializable; this is a read model, not the aggregate.
+}

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

@@ -0,0 +1,21 @@
+import { Access } from '@ddd-ts-kit/auth';
+import { QueryHandler } from '@ddd-ts-kit/kernel/declarations';
+import { {{context.camel}}Permissions } from '{{alias.context}}/application/authorization/{{context.kebab}}.permissions.js';
+import { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port.js';
+import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import type { {{name.pascal}}Result } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+
+@QueryHandler({{name.pascal}}Query, [{{name.pascal}}Reader, Access])
+export class {{name.pascal}}Handler implements QueryHandler<{{name.pascal}}Query> {
+  constructor(
+    private readonly reader: {{name.pascal}}Reader,
+    private readonly access: Access,
+  ) {}
+
+  async execute(query: {{name.pascal}}Query): Promise<{{name.pascal}}Result> {
+    // TODO(domain): name the searched element as the authorization model knows it, in place of '{{search.resource}}'; the scope it answers is handed to the read port, which filters in the statement and never in memory after loading.
+    const scope = await this.access.scope(query.actor, {{context.camel}}Permissions['{{access.permission}}'], '{{search.resource}}');
+
+    return this.reader.search(scope, query.page);
+  }
+}

package/templates/query/search.handler.spec.buses.ts.tpl

@@ -0,0 +1,59 @@
+import { describe, expect, it } from '{{tests.module}}';
+import {
+  AuthorizationMap,
+  PolicyAccess,
+  RoleBasedAuthorizer,
+  authorizationMiddleware,
+  requires,
+} from '@ddd-ts-kit/auth';
+import { anActor } from '@ddd-ts-kit/auth/testing';
+import { FixedClock, offsetPage } from '@ddd-ts-kit/kernel';
+import { createTestBuses } from '@ddd-ts-kit/testing';
+import { {{context.camel}}Permissions } from '{{alias.context}}/application/authorization/{{context.kebab}}.permissions.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 type { {{name.pascal}}Item } 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 authorizer = new RoleBasedAuthorizer({
+  roles: { holder: [{{context.camel}}Permissions['{{access.permission}}']] },
+});
+
+const holders = authorizationMiddleware({
+  authorizer,
+  map: AuthorizationMap.of(requires({{name.pascal}}Query, {{context.camel}}Permissions['{{access.permission}}'])),
+});
+
+const holder = anActor().withRole('holder').build();
+const SEARCHED = ['{{search.resource}}-1', '{{search.resource}}-2', '{{search.resource}}-3'];
+const LINES: readonly {{name.pascal}}Item[] = SEARCHED.map((id) => ({ id }));
+
+describe('{{name.title}}', () => {
+  it('answers one page of what the actor may see, with the total', async () => {
+    const queryBus = arrange(LINES);
+    const query = new {{name.pascal}}Query(holder, offsetPage({ limit: 2 }));
+
+    const page = await queryBus.execute(query);
+
+    expect(page).toEqual({ items: LINES.slice(0, 2), total: 3 });
+  });
+
+  it('is refused to an actor who does not hold the permission {{access.permission}}', async () => {
+    const queryBus = arrange(LINES);
+    const query = new {{name.pascal}}Query(anActor().build(), offsetPage());
+
+    await expect(queryBus.execute(query)).rejects.toMatchObject({ code: 'FORBIDDEN' });
+  });
+
+  // TODO(domain): replace each entry below by a test named after what "{{name.words}}" shows and to whom.
+  it.todo('lists only what the access scope of the actor covers');
+  it.todo('applies each criterion of the query');
+});
+
+function arrange(lines: readonly {{name.pascal}}Item[]) {
+  const { queryBus } = createTestBuses();
+  const access = new PolicyAccess({ authorizer, clock: new FixedClock(new Date('2026-01-01T00:00:00.000Z')) });
+  const handler = new {{name.pascal}}Handler(new Fake{{name.pascal}}Reader(lines), access);
+
+  return queryBus.use(holders).register({{name.pascal}}Query, handler);
+}

package/templates/query/search.handler.spec.tsyringe.ts.tpl

@@ -0,0 +1,58 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { RoleBasedAuthorizer } from '@ddd-ts-kit/auth';
+import { authorizationModule } from '@ddd-ts-kit/auth/di';
+import { anActor } from '@ddd-ts-kit/auth/testing';
+{{spec.diWithFake}}
+{{spec.contextImports}}
+import { offsetPage } from '@ddd-ts-kit/kernel';
+import { platformTestModule } from '{{alias.platform}}/platform-test.module.js';
+{{#if access.protected}}
+import { {{context.camel}}Permissions } from '{{alias.context}}/application/authorization/{{context.kebab}}.permissions.js';
+{{/if}}
+import { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port.js';
+import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import type { {{name.pascal}}Item } 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 holders = authorizationModule({
+  authorizer: new RoleBasedAuthorizer({
+    roles: { holder: [{{context.camel}}Permissions['{{access.permission}}']] },
+  }),
+});
+
+const holder = anActor().withRole('holder').build();
+const SEARCHED = ['{{search.resource}}-1', '{{search.resource}}-2', '{{search.resource}}-3'];
+const LINES: readonly {{name.pascal}}Item[] = SEARCHED.map((id) => ({ id }));
+
+describe('{{name.title}}', () => {
+  it('answers one page of what the actor may see, with the total', async () => {
+    const application = {{spec.await}}arrange(LINES);
+    const query = new {{name.pascal}}Query(holder, offsetPage({ limit: 2 }));
+
+    const page = await application.queryBus.execute(query);
+
+    expect(page).toEqual({ items: LINES.slice(0, 2), total: 3 });
+  });
+
+  it('is refused to an actor who does not hold the permission {{access.permission}}', async () => {
+    const application = {{spec.await}}arrange(LINES);
+    const query = new {{name.pascal}}Query(anActor().build(), offsetPage());
+
+    await expect(application.queryBus.execute(query)).rejects.toMatchObject({ code: 'FORBIDDEN' });
+  });
+
+  // TODO(domain): replace each entry below by a test named after what "{{name.words}}" shows and to whom.
+  it.todo('lists only what the access scope of the actor covers');
+  it.todo('applies each criterion of the query');
+});
+
+{{spec.async}}function arrange(lines: readonly {{name.pascal}}Item[]) {
+{{#if spec.assembles}}
+  const context = {{spec.context}};
+
+{{/if}}
+  return createTestApplication({
+    modules: [{{spec.modules}}],
+    fakes: [fake({{name.pascal}}Reader, new Fake{{name.pascal}}Reader(lines))],
+  });
+}

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

@@ -0,0 +1,20 @@
+import type { Access } from '@ddd-ts-kit/auth';
+import type { QueryHandler } from '@ddd-ts-kit/kernel';
+import { {{context.camel}}Permissions } from '{{alias.context}}/application/authorization/{{context.kebab}}.permissions.js';
+import type { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port.js';
+import type { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query.js';
+import type { {{name.pascal}}Result } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result.js';
+
+export class {{name.pascal}}Handler implements QueryHandler<{{name.pascal}}Query> {
+  constructor(
+    private readonly reader: {{name.pascal}}Reader,
+    private readonly access: Access,
+  ) {}
+
+  async execute(query: {{name.pascal}}Query): Promise<{{name.pascal}}Result> {
+    // TODO(domain): name the searched element as the authorization model knows it, in place of '{{search.resource}}'; the scope it answers is handed to the read port, which filters in the statement and never in memory after loading.
+    const scope = await this.access.scope(query.actor, {{context.camel}}Permissions['{{access.permission}}'], '{{search.resource}}');
+
+    return this.reader.search(scope, query.page);
+  }
+}

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();
+  }
+}