ddd-ts-kit 0.0.0-stage → 0.1.1

package/templates/integration-handler/integration-handler.ts.tpl

@@ -0,0 +1,26 @@
+{{#if upstream.known}}
+import { systemActor, type CommandBus } from '@ddd-ts-kit/kernel';
+import type { {{upstream.eventType}} } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+{{/if}}
+{{#unless upstream.known}}
+import { systemActor, type CommandBus, type IntegrationEvent } from '@ddd-ts-kit/kernel';
+{{/unless}}
+
+export class {{name.pascal}}IntegrationHandler {
+  static readonly eventType = '{{upstream.eventName}}';
+
+  readonly actor = systemActor('{{context.kebab}}.{{name.kebab}}');
+
+  constructor(private readonly commands: CommandBus) {}
+
+  {{#if upstream.known}}
+  async handle(event: {{upstream.eventType}}): Promise<void> {
+    // TODO(domain): translate `event.payload` (the language of {{upstream.kebab}}) into a command of {{context.kebab}}, built with `this.actor` (nobody is calling: the handler acts as a system actor the authorization model has to grant), and execute it with `this.commands.execute(...)`; delivery is at least once, so the command has to be safe to repeat.
+  }
+  {{/if}}
+  {{#unless upstream.known}}
+  async handle(event: IntegrationEvent): Promise<void> {
+    // TODO(domain): narrow `event.payload` (it is `unknown`: {{upstream.kebab}} declares no contract for this event in this repository), translate it into a command of {{context.kebab}}, built with `this.actor` (nobody is calling: the handler acts as a system actor the authorization model has to grant), and execute it with `this.commands.execute(...)`; delivery is at least once, so the command has to be safe to repeat.
+  }
+  {{/unless}}
+}

package/templates/integration-handler/wiring.manual.tpl

@@ -0,0 +1,32 @@
+@@imports
+{{#if consumer.declarative}}
+import { on, subscribeAll } from '@ddd-ts-kit/events';
+import { {{upstream.definition}} as {{name.camel}}Definition } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+{{/if}}
+{{#if consumer.transactional}}
+import { consume, subscribeAll } from '@ddd-ts-kit/events';
+import { {{upstream.definition}} as {{name.camel}}Definition } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+{{/if}}
+{{#if consumer.untyped}}
+import { idempotent, inEventScope } from '@ddd-ts-kit/kernel';
+{{/if}}
+import { {{name.pascal}}IntegrationHandler } from '{{alias.context}}/application/integration/handlers/{{name.kebab}}.integration-handler.js';
+@@registrations
+const {{name.camel}}IntegrationHandler = new {{name.pascal}}IntegrationHandler(platform.commands);
+
+{{#if consumer.declarative}}
+subscribeAll({{consumer.subscriber}}, [
+  on({{name.camel}}Definition, (event) => {{name.camel}}IntegrationHandler.handle(event), { consumer: '{{context.kebab}}.{{name.kebab}}', processed: platform.persistence.processedEvents, scope: platform.scope }),
+]);
+{{/if}}
+{{#if consumer.transactional}}
+subscribeAll({{consumer.subscriber}}, [
+  consume({{name.camel}}Definition, { consumer: '{{context.kebab}}.{{name.kebab}}', processed: platform.persistence.processedEvents, unitOfWork: platform.persistence.unitOfWork, scope: platform.scope }, (event) => {{name.camel}}IntegrationHandler.handle(event)),
+]);
+{{/if}}
+{{#if consumer.untyped}}
+{{consumer.subscriber}}.subscribe(
+  {{name.pascal}}IntegrationHandler.eventType,
+  idempotent('{{context.kebab}}.{{name.kebab}}', platform.persistence.processedEvents, inEventScope(platform.scope, { consumer: '{{context.kebab}}.{{name.kebab}}' }, (event) => {{name.camel}}IntegrationHandler.handle(event))),
+);
+{{/if}}

package/templates/integration-handler/wiring.tsyringe.tpl

@@ -0,0 +1,23 @@
+@@imports
+{{#if upstream.known}}
+import { CommandBus } from '@ddd-ts-kit/kernel';
+import { {{upstream.definition}} as {{name.camel}}Definition } from '{{alias.contexts}}/{{upstream.kebab}}/published-language/index.js';
+{{/if}}
+{{#unless upstream.known}}
+import { CommandBus, EventSubscribers, ExecutionScope, ProcessedEventStore, idempotent, inEventScope } from '@ddd-ts-kit/kernel';
+{{/unless}}
+import { {{name.pascal}}IntegrationHandler } from '{{alias.context}}/application/integration/handlers/{{name.kebab}}.integration-handler.js';
+@@registrations
+{{#if upstream.known}}
+builder.on({{name.camel}}Definition, { consumer: '{{context.kebab}}.{{name.kebab}}' }).handledBy({{name.pascal}}IntegrationHandler, [CommandBus]);
+{{/if}}
+{{#unless upstream.known}}
+builder.bind({{name.pascal}}IntegrationHandler).toClass({{name.pascal}}IntegrationHandler, [CommandBus]).as('consumer');
+@@start
+resolve(EventSubscribers)
+  .forContext('{{context.kebab}}')
+  .subscribe(
+    {{name.pascal}}IntegrationHandler.eventType,
+    idempotent('{{context.kebab}}.{{name.kebab}}', resolve(ProcessedEventStore), inEventScope(resolve(ExecutionScope), { consumer: '{{context.kebab}}.{{name.kebab}}' }, (event) => resolve({{name.pascal}}IntegrationHandler).handle(event))),
+  );
+{{/unless}}

package/templates/job/job.declared.ts.tpl

@@ -0,0 +1,16 @@
+import { CommandBus{{job.systemActorImport}} } from '@ddd-ts-kit/kernel';
+import { Scheduled, type JobExecution, type ScheduledJob } from '@ddd-ts-kit/kernel/declarations';
+import { {{job.command}}Command } from '{{alias.context}}/application/commands/{{job.commandKebab}}/{{job.commandKebab}}.command.js';
+
+@Scheduled('{{job.name}}', {{job.schedule}}, [CommandBus])
+export class {{name.pascal}}Job implements ScheduledJob {
+  constructor(private readonly commands: CommandBus) {}
+
+  async run(execution: JobExecution): Promise<void> {
+    // TODO(domain): {{job.todo}}
+    {{#if job.ungranted}}
+    // TODO(domain): {{job.grant}}
+    {{/if}}
+    await this.commands.execute(new {{job.command}}Command({{job.arguments}}));
+  }
+}

package/templates/job/job.spec.buses.ts.tpl

@@ -0,0 +1,45 @@
+import { describe, expect, it } from '{{tests.module}}';
+import type { Message } from '@ddd-ts-kit/kernel';
+import { createTestBuses } from '@ddd-ts-kit/testing';
+import { {{job.command}}Command } from '{{alias.context}}/application/commands/{{job.commandKebab}}/{{job.commandKebab}}.command.js';
+import { {{name.pascal}}Job } from '{{alias.context}}/application/scheduling/{{name.kebab}}.job.js';
+
+const occurrence = {
+  scheduledAt: new Date('2026-01-01T07:00:00.000Z'),
+  startedAt: new Date('2026-01-01T07:00:02.000Z'),
+  attempt: 1,
+  signal: new AbortController().signal,
+};
+
+describe('{{name.title}}, when its time comes', () => {
+  it('sends {{job.commandWords}}{{job.asActor}}', async () => {
+    const { job, sent } = arrange();
+
+    await job.run(occurrence);
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toBeInstanceOf({{job.command}}Command);
+    {{#if job.protected}}
+    expect(sent[0]).toMatchObject({ actor: { id: 'system:{{job.name}}', type: 'system' } });
+    {{/if}}
+  });
+
+  // TODO(domain): replace each entry below by a test of what "{{name.words}}" asks of the use case: the period it names from `scheduledAt`, and that a second run of the same occurrence changes nothing.
+  it.todo('names the period of the occurrence, never the instant it really runs');
+  it.todo('has the same outcome when the same occurrence runs twice');
+});
+
+function arrange() {
+  const { commandBus } = createTestBuses();
+  const sent: Message[] = [];
+
+  commandBus.register({{job.command}}Command, {
+    execute: () => Promise.reject(new Error('{{job.command}}Command is recorded before it reaches a handler')),
+  });
+
+  commandBus.use(async (message) => {
+    sent.push(message);
+  });
+
+  return { job: new {{name.pascal}}Job(commandBus), sent };
+}

package/templates/job/job.spec.tsyringe.ts.tpl

@@ -0,0 +1,52 @@
+import { describe, expect, it } from '{{tests.module}}';
+import { RoleBasedAuthorizer } from '@ddd-ts-kit/auth';
+import { authorizationModule } from '@ddd-ts-kit/auth/di';
+{{spec.diPlain}}
+{{spec.contextImports}}
+import type { Message } from '@ddd-ts-kit/kernel';
+import { platformTestModule } from '{{alias.platform}}/platform-test.module.js';
+{{job.permissionsImport}}
+import { {{job.command}}Command } from '{{alias.context}}/application/commands/{{job.commandKebab}}/{{job.commandKebab}}.command.js';
+
+const authorization = authorizationModule({
+  authorizer: new RoleBasedAuthorizer({
+    roles: { scheduler: [{{job.granted}}] },
+    systemRole: 'scheduler',
+  }),
+});
+
+describe('{{name.title}}, when its time comes', () => {
+  it('sends {{job.commandWords}}{{job.asActor}}', async () => {
+    const { application, sent } = {{spec.await}}arrange();
+
+    await application.jobs.runNow('{{job.name}}');
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toBeInstanceOf({{job.command}}Command);
+{{#if job.protected}}
+    expect(sent[0]).toMatchObject({ actor: { id: 'system:{{job.name}}', type: 'system' } });
+{{/if}}
+  });
+
+  // TODO(domain): replace each entry below by a test of what "{{name.words}}" asks of the use case: the period it names from `scheduledAt`, and that a second run of the same occurrence changes nothing.
+  it.todo('names the period of the occurrence, never the instant it really runs');
+  it.todo('has the same outcome when the same occurrence runs twice');
+});
+
+{{spec.async}}function arrange() {
+{{#if spec.assembles}}
+  const context = {{spec.context}};
+
+{{/if}}
+  const application = createTestApplication({
+    modules: [{{spec.modules}}],
+  });
+
+  const sent: Message[] = [];
+
+  application.commandBus.use(async (message) => {
+    sent.push(message);
+  });
+
+  return { application, sent };
+}

package/templates/job/job.ts.tpl

@@ -0,0 +1,14 @@
+import { {{job.systemActorValueImport}}type CommandBus, type JobExecution, type ScheduledJob } from '@ddd-ts-kit/kernel';
+import { {{job.command}}Command } from '{{alias.context}}/application/commands/{{job.commandKebab}}/{{job.commandKebab}}.command.js';
+
+export class {{name.pascal}}Job implements ScheduledJob {
+  constructor(private readonly commands: CommandBus) {}
+
+  async run(execution: JobExecution): Promise<void> {
+    // TODO(domain): {{job.todo}}
+{{#if job.ungranted}}
+    // TODO(domain): {{job.grant}}
+{{/if}}
+    await this.commands.execute(new {{job.command}}Command({{job.arguments}}));
+  }
+}

package/templates/job/settings.tpl

@@ -0,0 +1,2 @@
+@@jobs
+'{{job.name}}': { enabled: environment['{{job.switch}}'] !== 'false' },

package/templates/job/wiring.manual.tpl

@@ -0,0 +1,10 @@
+@@imports
+import { {{name.pascal}}Job } from '{{alias.context}}/application/scheduling/{{name.kebab}}.job.js';
+@@registrations
+const {{name.camel}}Job = new {{name.pascal}}Job(platform.commands);
+
+platform.jobs.register({
+  name: '{{job.name}}',
+  schedule: {{job.schedule}},
+  run: (execution) => {{name.camel}}Job.run(execution),
+});

package/templates/job/wiring.tsyringe.tpl

@@ -0,0 +1,5 @@
+@@imports
+import { CommandBus } from '@ddd-ts-kit/kernel';
+import { {{name.pascal}}Job } from '{{alias.context}}/application/scheduling/{{name.kebab}}.job.js';
+@@registrations
+builder.job('{{job.name}}', {{job.schedule}}).handledBy({{name.pascal}}Job, [CommandBus]);

package/templates/pipeline/biome.json.tpl

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
+  "files": {
+    "includes": [
+      "**/*.ts",
+      "**/*.mts",
+      "**/*.cts",
+      "**/*.js",
+      "**/*.mjs",
+      "**/*.cjs",
+      "**/*.json",
+      "**/*.jsonc",
+      "!**/dist",
+      "!**/coverage",
+      "!**/reports",
+      "!**/generated",
+      "!**/package-lock.json",
+      "!**/.dependency-cruiser.cjs",
+      "!**/openapi/*.json",
+      "!**/asyncapi.json",
+      "!**/migrations/meta"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120,
+    "lineEnding": "lf"
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingCommas": "all",
+      "semicolons": "always",
+      "arrowParentheses": "always"
+    },
+    "parser": {
+      "unsafeParameterDecoratorsEnabled": true
+    }
+  },
+  "linter": {
+    "enabled": false
+  },
+  "assist": {
+    "enabled": false
+  }
+}

package/templates/pipeline/commitlint.config.mjs

@@ -0,0 +1,8 @@
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    // Grouped dependency updates name their group in the title and run past 100.
+    'header-max-length': [2, 'always', 140],
+    'subject-case': [0],
+  },
+};

package/templates/pipeline/eslint.config.mjs.tpl

@@ -0,0 +1,9 @@
+import { dddTsKit } from '@ddd-ts-kit/eslint-plugin';
+
+{{#unless orm.prisma}}
+export default dddTsKit({ tsconfigRootDir: import.meta.dirname });
+{{/unless}}
+{{#if orm.prisma}}
+// The Prisma client under generated/ is a build product: it is not linted.
+export default dddTsKit({ tsconfigRootDir: import.meta.dirname, ignores: ['generated/**'] });
+{{/if}}

package/templates/pipeline/github/actions/setup/action.yml.tpl

@@ -0,0 +1,37 @@
+name: Setup
+description: Node, then the dependencies of the lockfile, restored from the cache when a run already installed them.
+
+inputs:
+  node-version:
+    description: The Node.js release line the pipeline runs on.
+    default: '24'
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v7
+      with:
+        node-version: ${{ inputs.node-version }}
+{{#if pm.corepack}}
+    - name: The package manager package.json pins
+      shell: bash
+      run: corepack enable
+{{/if}}
+    # One install per lockfile, shared by every job and every run. The key holds the lockfile and
+    # package.json: a hit is what a fresh install of that lockfile gives, and a manifest that left
+    # its lockfile behind is installed again, which refuses it.
+    - name: Dependencies, as a run already installed them for this lockfile
+      id: modules
+      uses: actions/cache@v6
+      with:
+        path: node_modules
+        key: modules-${{ runner.os }}-${{ runner.arch }}-node${{ inputs.node-version }}-${{ hashFiles('package-lock.json', 'package.json') }}
+    - name: Install (no run installed this lockfile yet, or the cache was evicted)
+      if: steps.modules.outputs.cache-hit != 'true'
+      shell: bash
+      run: npm ci
+{{#if orm.prisma}}
+    - name: The Prisma client and the schema of the tests, build products of prisma/schema.prisma
+      shell: bash
+      run: npm run db:client
+{{/if}}

package/templates/pipeline/github/branch-protection.md

@@ -0,0 +1,77 @@
+# Branch protection (GitHub)
+
+The workflows only report. These settings make them binding. Nothing here is applied
+automatically: run the commands once, as a repository administrator, after the first green run
+of `CI` on `main` (GitHub only offers a check as "required" once it has reported).
+
+## What is required
+
+| Check | Workflow | Why it is the required one |
+|---|---|---|
+| `gate` | `ci.yml` | Needs every other job of the workflow; a failed, cancelled or skipped job fails it. One required check, so adding a job never needs a settings change. |
+| `Conventional title` | `pr-title.yml` | The squash commit takes the pull request title. |
+| `Analyze` | `codeql.yml` | Optional: require it when code scanning is enabled on the repository. |
+
+## Protect `main`
+
+```bash
+gh api --method PUT "repos/{owner}/{repo}/branches/main/protection" --input - <<'JSON'
+{
+  "required_status_checks": {
+    "strict": true,
+    "checks": [
+      { "context": "gate" },
+      { "context": "Conventional title" }
+    ]
+  },
+  "enforce_admins": true,
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 1,
+    "dismiss_stale_reviews": true,
+    "require_last_push_approval": true
+  },
+  "restrictions": null,
+  "required_linear_history": true,
+  "required_conversation_resolution": true,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}
+JSON
+```
+
+`{owner}` and `{repo}` are filled in by `gh` from the current repository. A solo maintainer sets
+`required_approving_review_count` to `0`.
+
+## Squash only, title as commit subject
+
+```bash
+gh api --method PATCH "repos/{owner}/{repo}" \
+  -F allow_squash_merge=true \
+  -F allow_merge_commit=false \
+  -F allow_rebase_merge=false \
+  -F delete_branch_on_merge=true \
+  -F allow_auto_merge=true \
+  -f squash_merge_commit_title=PR_TITLE \
+  -f squash_merge_commit_message=PR_BODY
+```
+
+## Control
+
+```bash
+gh api "repos/{owner}/{repo}/branches/main/protection" \
+  --jq '{checks: [.required_status_checks.checks[].context], strict: .required_status_checks.strict, admins: .enforce_admins.enabled}'
+```
+
+Expected: `{"checks":["gate","Conventional title"],"strict":true,"admins":true}`.
+
+## Notes
+
+- Dependency review needs the dependency graph: free on public repositories, GitHub Advanced
+  Security (or GitHub Code Security) on private ones. Without it the step fails with an explicit
+  message; remove the step and keep `npm run ci:audit`.
+- CodeQL is free on public repositories and needs GitHub Code Security on private ones.
+- Secret scanning in `ci.yml` runs the gitleaks container, which needs no licence. The
+  `gitleaks/gitleaks-action` wrapper is not used because it requires a licence key for
+  organization accounts.
+- Dependabot (`dependabot.yml`) is GitHub only. `renovate.json` works on both platforms; keep one
+  of the two, not both.

package/templates/pipeline/github/dependabot.yml

@@ -0,0 +1,59 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    ignore:
+      # typescript-eslint and dependency-cruiser need the TypeScript 6 API; the native
+      # compiler is the separate `@typescript/native` alias.
+      - dependency-name: typescript
+        update-types: ['version-update:semver-major']
+    commit-message:
+      prefix: chore
+      include: scope
+    groups:
+      lint:
+        patterns:
+          - 'eslint*'
+          - '@eslint/*'
+          - 'typescript-eslint'
+          - '@typescript-eslint/*'
+          - '@ddd-ts-kit/eslint-plugin'
+          - 'knip'
+          - 'dependency-cruiser'
+      test:
+        patterns:
+          - 'vitest'
+          - '@vitest/*'
+          - '@faker-js/faker'
+      ddd-ts-kit:
+        patterns:
+          - 'ddd-ts-kit'
+          - '@ddd-ts-kit/*'
+      production-minor:
+        dependency-type: production
+        update-types: [minor, patch]
+      development-minor:
+        dependency-type: development
+        update-types: [minor, patch]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: ci
+    groups:
+      actions:
+        patterns: ['*']
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    commit-message:
+      prefix: chore
+      include: scope

package/templates/pipeline/github/scripts/start-postgres.sh

@@ -0,0 +1,47 @@
+#!/bin/sh
+# Starts the PostgreSQL the specs run against and waits until it accepts connections.
+# A `services:` container is pulled once, before the job, and one refusal of a registry fails
+# the run (a public mirror answered "toomanyrequests" once): here the image is pulled with
+# retries, from the next registry when one refuses.
+set -eu
+
+IMAGE="${POSTGRES_IMAGE:-postgres:18}"
+REGISTRIES="${POSTGRES_REGISTRIES:-mirror.gcr.io/library public.ecr.aws/docker/library docker.io/library}"
+
+pulled=""
+
+for attempt in 1 2 3; do
+  for registry in $REGISTRIES; do
+    if docker pull --quiet "$registry/$IMAGE"; then
+      pulled="$registry/$IMAGE"
+      break 2
+    fi
+
+    echo "Pulling $registry/$IMAGE failed (attempt $attempt)."
+  done
+
+  sleep $((attempt * 5))
+done
+
+if [ -z "$pulled" ]; then
+  echo "No registry served $IMAGE." >&2
+  exit 1
+fi
+
+docker run --detach --name postgres --publish 5432:5432 \
+  --env POSTGRES_USER=app --env POSTGRES_PASSWORD=app --env POSTGRES_DB=app \
+  --health-cmd "pg_isready -U app -d app" --health-interval 2s --health-timeout 3s --health-retries 30 \
+  "$pulled" > /dev/null
+
+for second in $(seq 1 60); do
+  if [ "$(docker inspect --format '{{.State.Health.Status}}' postgres)" = "healthy" ]; then
+    echo "PostgreSQL is ready ($pulled, ${second}s)."
+    exit 0
+  fi
+
+  sleep 1
+done
+
+docker logs postgres >&2
+echo "PostgreSQL did not become healthy." >&2
+exit 1