@starci/hfs 4.0.8 → 4.0.10

package/templates/be/patterns/queues/platform/queue-transport.port.ts.tpl

@@ -0,0 +1,115 @@
+import type { QueueHandler, QueueSchedulerDefinition } from "./queue.contracts"
+
+/** BullMQ as the queue capability sees it: the one port the BullMQ client implements. */
+export interface QueueTransport {
+    /** Adds the job to its queue with `jobId`; adding an id BullMQ already holds changes nothing, so a repeated relay pass is harmless. */
+    add(queue: string, jobId: string, payload: object): Promise<void>
+    /** Creates or updates a job scheduler by its id. */
+    upsertScheduler(scheduler: QueueSchedulerDefinition): Promise<void>
+    /** Starts a worker of the queue the handler names that runs it for every job, `concurrency` at a time. */
+    work(handler: QueueHandler, concurrency: number): Promise<void>
+    /** Resolves after `ms` milliseconds: the only clock of the relay loop. */
+    wait(ms: number): Promise<void>
+    /** Closes every queue and worker. */
+    close(): Promise<void>
+}
+
+/** The Redis a driver object connects to. */
+export interface BullmqRedis {
+    /** The host. */
+    readonly host: string
+    /** The port. */
+    readonly port: number
+    /** BullMQ answers to commands only through a client that does not retry on its own. */
+    readonly maxRetriesPerRequest: number | null
+}
+
+/** The Redis options every queue and worker of the app shares. */
+export interface BullmqConnection {
+    /** The key prefix of the app. */
+    readonly prefix: string
+    /** The Redis the driver connects to. */
+    readonly connection: BullmqRedis
+}
+
+/** The options a worker is built with: the shared connection plus its concurrency. */
+export interface BullmqWorkerOptions extends BullmqConnection {
+    /** How many jobs the worker runs at a time. */
+    readonly concurrency: number
+}
+
+/** The wait between two tries of a job. */
+export interface BullmqBackoff {
+    /** The backoff shape. */
+    readonly type: string
+    /** The first wait, in milliseconds. */
+    readonly delay: number
+}
+
+/** How long a finished job is kept. */
+export interface BullmqRetention {
+    /** The seconds a finished job is kept. */
+    readonly age: number
+}
+
+/** The options the transport fixes on every job it adds. */
+export interface BullmqJobOptions {
+    /** The id BullMQ dedupes on: the outbox row id. */
+    readonly jobId: string
+    /** How many times BullMQ tries the job. */
+    readonly attempts: number
+    /** The wait between two tries. */
+    readonly backoff: BullmqBackoff
+    /** How long a finished job is kept. */
+    readonly removeOnComplete: BullmqRetention
+}
+
+/** The options a scheduler fixes on the jobs it fires. */
+export interface BullmqSchedulerJobOptions {
+    /** How many times BullMQ tries the tick. */
+    readonly attempts: number
+}
+
+/** The job a scheduler fires. */
+export interface BullmqJobTemplate {
+    /** The job name, which is the queue name. */
+    readonly name: string
+    /** The payload of every tick. */
+    readonly data: object
+    /** The options of every tick. */
+    readonly opts: BullmqSchedulerJobOptions
+}
+
+/** A queue as the transport uses it. */
+export interface BullmqQueue {
+    /** Adds the job; an id BullMQ already holds makes the add a no-op. */
+    add(name: string, payload: object, options: BullmqJobOptions): Promise<unknown>
+    /** Creates or updates the scheduler by its id. */
+    upsertJobScheduler(id: string, repeat: { readonly every: number }, template: BullmqJobTemplate): Promise<unknown>
+    /** Closes the queue. */
+    close(): Promise<void>
+}
+
+/** A job as a worker receives it: the fields the transport translates into a QueueDelivery. */
+export interface BullmqJob {
+    /** The job id; a tick the scheduler fires can have none. */
+    readonly id?: string
+    /** The payload the producer wrote. */
+    readonly data: object
+    /** How many deliveries were started before this one. */
+    readonly attemptsMade: number
+}
+
+/** A worker as the transport uses it. */
+export interface BullmqWorker {
+    /** Stops the worker; `force` drops the jobs it is still running. */
+    close(force?: boolean): Promise<void>
+}
+
+/** Builds the BullMQ objects; the module provides it so a spec can double it through the injection token. */
+export interface QueueFactory {
+    /** The queue of the name over the shared connection. */
+    queue(name: string, options: BullmqConnection): BullmqQueue
+    /** A worker that runs the processor for every job of the queue. */
+    worker(name: string, processor: (job: BullmqJob) => Promise<void>, options: BullmqWorkerOptions): BullmqWorker
+}

package/templates/be/patterns/queues/platform/queue-worker.service.spec.ts.tpl

@@ -0,0 +1,91 @@
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { LOGGER } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import type { QueueHandler } from "./queue.contracts"
+import { QUEUE_OPTIONS, QUEUE_TRANSPORT } from "./queue.decorators"
+import { QueueLogEvent } from "./queue.log-events"
+import type { QueueOptions } from "./queue.options"
+import type { QueueTransport } from "./queue-transport.port"
+import { QueueWorkerService } from "./queue-worker.service"
+
+const options: QueueOptions = {
+    redisHost: "localhost",
+    redisPort: 6379,
+    prefix: "test",
+    relayIntervalMs: 100,
+    relayBatch: 2,
+    concurrency: 3,
+    connections: [],
+    schedulers: [{ queue: "sweep", id: "sweep-every-minute", everyMs: 60000 }],
+}
+
+const handlerOf = (queue: string): QueueHandler => ({ queue, handle: () => Promise.resolve() })
+
+const build = async () => {
+    const transport = mock<QueueTransport>()
+    transport.upsertScheduler.mockResolvedValue(undefined)
+    const logger = mock<Logger>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            QueueWorkerService,
+            { provide: QUEUE_OPTIONS, useValue: options },
+            { provide: QUEUE_TRANSPORT, useValue: transport },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    return { workers: moduleRef.get(QueueWorkerService), transport, logger }
+}
+
+describe("QueueWorkerService", () => {
+    describe("onApplicationBootstrap", () => {
+        it("starts one worker per registered queue with the configured concurrency and registers the schedulers", async () => {
+            const { workers, transport } = await build()
+            const mailHandler = handlerOf("mail")
+            const sweepHandler = handlerOf("sweep")
+            workers.add(mailHandler)
+            workers.add(sweepHandler)
+
+            await workers.onApplicationBootstrap()
+
+            expect(transport.work).toHaveBeenCalledWith(mailHandler, 3)
+            expect(transport.work).toHaveBeenCalledWith(sweepHandler, 3)
+            expect(transport.upsertScheduler).toHaveBeenCalledWith(options.schedulers[0])
+        })
+
+        it("keeps the last handler registered for a queue", async () => {
+            const { workers, transport } = await build()
+            const first = handlerOf("mail")
+            const second = handlerOf("mail")
+            workers.add(first)
+            workers.add(second)
+
+            await workers.onApplicationBootstrap()
+
+            expect(transport.work).toHaveBeenCalledTimes(1)
+            expect(transport.work).toHaveBeenCalledWith(second, 3)
+        })
+
+        it("logs a scheduler that cannot be registered and still starts the app", async () => {
+            const { workers, transport, logger } = await build()
+            const failure = new Error("redis down")
+            transport.upsertScheduler.mockRejectedValue(failure)
+
+            await expect(workers.onApplicationBootstrap()).resolves.toBeUndefined()
+
+            expect(logger.error).toHaveBeenCalledWith(QueueLogEvent.SchedulerFailed, failure, {
+                scheduler: "sweep-every-minute",
+            })
+        })
+    })
+
+    describe("onApplicationShutdown", () => {
+        it("closes the workers and the queues", async () => {
+            const { workers, transport } = await build()
+
+            await workers.onApplicationShutdown()
+
+            expect(transport.close).toHaveBeenCalledTimes(1)
+        })
+    })
+})

package/templates/be/patterns/queues/platform/queue-worker.service.ts.tpl

@@ -0,0 +1,45 @@
+import { Injectable } from "@nestjs/common"
+import type { OnApplicationBootstrap, OnApplicationShutdown } from "@nestjs/common"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import type { QueueHandler } from "./queue.contracts"
+import { InjectQueueOptions, InjectQueueTransport } from "./queue.decorators"
+import { QueueLogEvent } from "./queue.log-events"
+import type { QueueOptions } from "./queue.options"
+import type { QueueWorkerRegistry } from "./queue.port"
+import type { QueueTransport } from "./queue-transport.port"
+
+@Injectable()
+/**
+ * The consuming side of the queues: the registry the processors fill, and the workers and schedulers started when the app has
+ * registered every handler. A scheduler that cannot be registered is logged and does not stop the app: the next boot upserts it again.
+ */
+export class QueueWorkerService implements QueueWorkerRegistry, OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly handlers = new Map<string, QueueHandler>()
+
+    constructor(
+        @InjectQueueOptions() private readonly options: QueueOptions,
+        @InjectQueueTransport() private readonly transport: QueueTransport,
+        @InjectLogger() private readonly logger: Logger,
+    ) {}
+
+    /** Registers the handler under the queue it names; a second handler for the same queue replaces the first. */
+    add(handler: QueueHandler): void {
+        this.handlers.set(handler.queue, handler)
+    }
+
+    /** Starts one worker per registered queue, then registers the schedulers of the options. */
+    async onApplicationBootstrap(): Promise<void> {
+        for (const handler of this.handlers.values()) await this.transport.work(handler, this.options.concurrency)
+        for (const scheduler of this.options.schedulers) {
+            await this.transport.upsertScheduler(scheduler).catch((cause: unknown) => {
+                this.logger.error(QueueLogEvent.SchedulerFailed, cause, { scheduler: scheduler.id })
+            })
+        }
+    }
+
+    /** Closes the workers and the queues. */
+    async onApplicationShutdown(): Promise<void> {
+        await this.transport.close()
+    }
+}

package/templates/be/patterns/queues/platform/queue.config.ts.tpl

@@ -0,0 +1,15 @@
+import type { EnvSource } from "@modules/platform/config"
+import type { QueueOptions } from "./queue.options"
+
+/** What the app's `main.ts` reads for the queues; the connections and the schedulers are the app root's choice. */
+export type QueueConfig = Omit<QueueOptions, "connections" | "schedulers">
+
+/** Reads the queue options: the Redis address is required, the rest are tunables with literal defaults. */
+export const parseQueueConfig = (env: EnvSource): QueueConfig => ({
+    redisHost: env.string("QUEUE_REDIS_HOST"),
+    redisPort: env.int("QUEUE_REDIS_PORT", 6379),
+    prefix: env.optional("QUEUE_PREFIX") ?? "queue",
+    relayIntervalMs: env.duration("QUEUE_RELAY_INTERVAL", 200),
+    relayBatch: env.int("QUEUE_RELAY_BATCH", 50),
+    concurrency: env.int("QUEUE_CONCURRENCY", 5),
+})

package/templates/be/patterns/queues/platform/queue.contracts.ts.tpl

@@ -0,0 +1,31 @@
+/** A recurring task: BullMQ upserts it by `id`, so every replica of an app may register it and the deployment still fires it once per interval. */
+export interface QueueSchedulerDefinition {
+    /** The queue the ticks go to; its processor handles every tick like any other job. */
+    readonly queue: string
+    /** The stable id of the scheduler. */
+    readonly id: string
+    /** The interval between two ticks, in milliseconds. */
+    readonly everyMs: number
+    /** The payload of every tick. */
+    readonly payload?: object
+}
+
+/** One job as a handler receives it. */
+export interface QueueDelivery {
+    /** The BullMQ job id: the outbox row id of an enqueued job, the tick id of a scheduled one. */
+    readonly id: string
+    /** The queue. */
+    readonly queue: string
+    /** The payload the producer wrote. */
+    readonly payload: object
+    /** How many deliveries were started, this one included. */
+    readonly attempt: number
+}
+
+/** The handler of one queue: it receives every delivery of the queue; a return completes the BullMQ job and a throw lets BullMQ retry it. */
+export interface QueueHandler {
+    /** The queue this handler consumes. */
+    readonly queue: string
+    /** Handles one delivery. */
+    handle(delivery: QueueDelivery): Promise<void>
+}

package/templates/be/patterns/queues/platform/queue.decorators.ts.tpl

@@ -0,0 +1,45 @@
+import type { EntityManager } from "typeorm"
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { QueueOptions } from "./queue.options"
+import type { QueueOutbox, QueueWorkerRegistry } from "./queue.port"
+import type { QueueFactory, QueueTransport } from "./queue-transport.port"
+
+/** Token of the options of the queues, exported so a spec can provide it. */
+export const QUEUE_OPTIONS: unique symbol = Symbol("platform.queue.options")
+
+/** Token of the QueueOutbox port. */
+export const QUEUE_OUTBOX: unique symbol = Symbol("platform.queue.outbox")
+
+/** Token of the registry a processor registers its queue handler with. */
+export const QUEUE_WORKER_REGISTRY: unique symbol = Symbol("platform.queue.worker-registry")
+
+/** Token of the BullMQ port; it is also the health probe token of the queues. */
+export const QUEUE_TRANSPORT: unique symbol = Symbol("platform.queue.transport")
+
+/** Token of the entity managers of the connections whose outbox the relay reads, in the order the options name them. */
+export const QUEUE_RELAY_MANAGERS: unique symbol = Symbol("platform.queue.relay-managers")
+
+/** Token of the factory that builds the BullMQ objects, exported so a spec can provide it. */
+export const QUEUE_FACTORY: unique symbol = Symbol("platform.queue.factory")
+
+/** Injects the options of the queues. Parameter type: QueueOptions. */
+export const InjectQueueOptions = (): TypedParameterDecorator<QueueOptions> => injector<QueueOptions>(QUEUE_OPTIONS)
+
+/** Injects the QueueOutbox port. Parameter type: QueueOutbox. */
+export const InjectQueueOutbox = (): TypedParameterDecorator<QueueOutbox> => injector<QueueOutbox>(QUEUE_OUTBOX)
+
+/** Injects the worker registry. Parameter type: QueueWorkerRegistry. */
+export const InjectQueueWorkerRegistry = (): TypedParameterDecorator<QueueWorkerRegistry> =>
+    injector<QueueWorkerRegistry>(QUEUE_WORKER_REGISTRY)
+
+/** Injects the BullMQ port. Parameter type: QueueTransport. */
+export const InjectQueueTransport = (): TypedParameterDecorator<QueueTransport> =>
+    injector<QueueTransport>(QUEUE_TRANSPORT)
+
+/** Injects the entity managers the relay reads the outbox of. Parameter type: ReadonlyArray<EntityManager>. */
+export const InjectQueueRelayManagers = (): TypedParameterDecorator<ReadonlyArray<EntityManager>> =>
+    injector<ReadonlyArray<EntityManager>>(QUEUE_RELAY_MANAGERS)
+
+/** Injects the factory that builds the BullMQ objects. Parameter type: QueueFactory. */
+export const InjectQueueFactory = (): TypedParameterDecorator<QueueFactory> => injector<QueueFactory>(QUEUE_FACTORY)

package/templates/be/patterns/queues/platform/queue.index.ts.tpl

@@ -0,0 +1,7 @@
+export { parseQueueConfig } from "./queue.config"
+export type { QueueConfig } from "./queue.config"
+export type { QueueDelivery, QueueSchedulerDefinition } from "./queue.contracts"
+export { InjectQueueOutbox, InjectQueueWorkerRegistry, QUEUE_WORKER_REGISTRY } from "./queue.decorators"
+export { QueueModule } from "./queue.module"
+export type { QueueOutbox, QueueWorkerRegistry } from "./queue.port"
+export { queueEntities, queueMigrations } from "./persistence/connection"

package/templates/be/patterns/queues/platform/queue.log-events.ts.tpl

@@ -0,0 +1,5 @@
+/** Log events of the queues. */
+export enum QueueLogEvent {
+    /** A scheduler could not be registered at boot. */
+    SchedulerFailed = "queue.scheduler.failed",
+}

package/templates/be/patterns/queues/platform/queue.module-definition.ts.tpl

@@ -0,0 +1,10 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { QUEUE_OPTIONS } from "./queue.decorators"
+import type { QueueOptions } from "./queue.options"
+
+/** The configurable-module base of the queues; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<QueueOptions>({
+    optionsInjectionToken: QUEUE_OPTIONS,
+})
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/patterns/queues/platform/queue.module.ts.tpl

@@ -0,0 +1,62 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { Queue, Worker } from "bullmq"
+import type { EntityManager } from "typeorm"
+import {
+    QUEUE_FACTORY,
+    QUEUE_OUTBOX,
+    QUEUE_RELAY_MANAGERS,
+    QUEUE_TRANSPORT,
+    QUEUE_WORKER_REGISTRY,
+} from "./queue.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./queue.module-definition"
+import { BullmqQueueTransportClient } from "./bullmq-queue-transport.client"
+import type {
+    BullmqConnection,
+    BullmqJob,
+    BullmqQueue,
+    BullmqWorker,
+    BullmqWorkerOptions,
+} from "./queue-transport.port"
+import { QueueOutboxService } from "./queue-outbox.service"
+import { QueueRelayService } from "./queue-relay.service"
+import { QueueWorkerService } from "./queue-worker.service"
+
+@Module({})
+/** The queues of a service: the outbox writer, its relay into BullMQ, the workers and the schedulers, registered once per app over the connections that hold an outbox. */
+export class QueueModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app that enqueues or processes jobs. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [
+                ...(base.providers ?? []),
+                {
+                    provide: QUEUE_RELAY_MANAGERS,
+                    useFactory: (...managers: Array<EntityManager>) => managers,
+                    inject: [...options.connections],
+                },
+                {
+                    provide: QUEUE_FACTORY,
+                    useValue: {
+                        queue: (name: string, options: BullmqConnection): BullmqQueue => new Queue(name, options),
+                        worker: (
+                            name: string,
+                            processor: (job: BullmqJob) => Promise<void>,
+                            options: BullmqWorkerOptions,
+                        ): BullmqWorker => new Worker<object>(name, processor, options),
+                    },
+                },
+                BullmqQueueTransportClient,
+                { provide: QUEUE_TRANSPORT, useExisting: BullmqQueueTransportClient },
+                QueueOutboxService,
+                QueueRelayService,
+                QueueWorkerService,
+                { provide: QUEUE_OUTBOX, useExisting: QueueOutboxService },
+                { provide: QUEUE_WORKER_REGISTRY, useExisting: QueueWorkerService },
+            ],
+            exports: [QUEUE_OUTBOX, QUEUE_WORKER_REGISTRY, QUEUE_TRANSPORT],
+        }
+    }
+}

package/templates/be/patterns/queues/platform/queue.options.ts.tpl

@@ -0,0 +1,22 @@
+import type { InjectionToken } from "@nestjs/common"
+import type { QueueSchedulerDefinition } from "./queue.contracts"
+
+/** What the queues of one app need: where Redis is, how the relay and the workers run, which connections hold an outbox, and the schedulers it registers. */
+export interface QueueOptions {
+    /** The Redis host BullMQ talks to. */
+    readonly redisHost: string
+    /** The Redis port. */
+    readonly redisPort: number
+    /** What every BullMQ key starts with: the shared default in a deployment, the run prefix of a test world. */
+    readonly prefix: string
+    /** The pause between two relay passes over an empty outbox. */
+    readonly relayIntervalMs: number
+    /** The most outbox rows one relay pass hands to BullMQ. */
+    readonly relayBatch: number
+    /** How many jobs one worker of the app runs at once. */
+    readonly concurrency: number
+    /** The tokens of the shared entity managers of the connections that hold a queue outbox of the app: the relay reads each of them. */
+    readonly connections: ReadonlyArray<InjectionToken>
+    /** The job schedulers the app registers at boot; BullMQ upserts them by id, so a pool of replicas fires each one once per interval. */
+    readonly schedulers: ReadonlyArray<QueueSchedulerDefinition>
+}

package/templates/be/patterns/queues/platform/queue.policy.spec.ts.tpl

@@ -0,0 +1,19 @@
+import { ATTEMPTS, BACKOFF_MS, KEEP_COMPLETED_SECONDS, jobNameOf } from "./queue.policy"
+
+describe("queue policy", () => {
+    it("declares the retry and retention budget of every job", () => {
+        expect({
+            attempts: ATTEMPTS,
+            backoffMs: BACKOFF_MS,
+            keepCompletedSeconds: KEEP_COMPLETED_SECONDS,
+        }).toEqual({
+            attempts: 5,
+            backoffMs: 1000,
+            keepCompletedSeconds: 3600,
+        })
+    })
+
+    it("uses the queue name as the BullMQ job name", () => {
+        expect(jobNameOf("orders")).toBe("orders")
+    })
+})

package/templates/be/patterns/queues/platform/queue.policy.ts.tpl

@@ -0,0 +1,11 @@
+/** How many deliveries BullMQ gives a job before it keeps it as failed. */
+export const ATTEMPTS = 5
+
+/** The pause after the first failed delivery; BullMQ doubles it with every further failure. */
+export const BACKOFF_MS = 1000
+
+/** How long BullMQ keeps a completed job (seconds): long enough that a repeated relay pass finds its job id and adds nothing. */
+export const KEEP_COMPLETED_SECONDS = 3600
+
+/** The name the jobs of every queue carry inside their queue. */
+export const jobNameOf = (queue: string): string => queue

package/templates/be/patterns/queues/platform/queue.port.ts.tpl

@@ -0,0 +1,14 @@
+import type { EntityManager } from "typeorm"
+import type { QueueHandler } from "./queue.contracts"
+
+/** The queue outbox: a typed producer writes a job row in the transaction of the caller, the relay hands it to BullMQ after commit. */
+export interface QueueOutbox {
+    /** Writes the job in the outbox of the transaction `tx`, so it exists exactly when the change that needs it commits. */
+    write(tx: EntityManager, queue: string, payload: object): Promise<void>
+}
+
+/** Where a processor registers the handler of its queue; the workers start when the app has registered every handler. */
+export interface QueueWorkerRegistry {
+    /** Registers the handler under the queue it names; a second handler for the same queue replaces the first. */
+    add(handler: QueueHandler): void
+}

package/templates/be/patterns/queues/queue.index.ts.tpl

@@ -0,0 +1,3 @@
+export { @@Queue@@Module } from "./@@queue@@.module"
+export { @@Queue@@Queue, @@queueUpper@@_QUEUE } from "./@@queue@@.queue"
+export type { @@Queue@@Payload } from "./@@queue@@.queue"

package/templates/be/patterns/queues/queue.module.ts.tpl

@@ -0,0 +1,6 @@
+import { Module } from "@nestjs/common"
+import { @@Queue@@Queue } from "./@@queue@@.queue"
+
+@Module({ providers: [@@Queue@@Queue], exports: [@@Queue@@Queue] })
+/** The @@queue@@ queue: its typed producer, imported by the domain module whose service enqueues. */
+export class @@Queue@@Module {}

package/templates/be/patterns/queues/queue.queue.ts.tpl

@@ -0,0 +1,23 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { InjectQueueOutbox } from "@modules/platform/queue"
+import type { QueueOutbox } from "@modules/platform/queue"
+
+/** The queue name: the contract between this producer and the processor of the job. */
+export const @@queueUpper@@_QUEUE = "@@queue@@"
+
+/** The payload of one @@queue@@ job: ids only. */
+export interface @@Queue@@Payload {
+    readonly id: string
+}
+
+@Injectable()
+/** The typed producer of the @@queue@@ queue. */
+export class @@Queue@@Queue {
+    constructor(@InjectQueueOutbox() private readonly outbox: QueueOutbox) {}
+
+    /** Enqueues one @@queue@@ job in the transaction of the caller: the job exists exactly when the change that needs it commits. */
+    enqueue@@Queue@@(payload: @@Queue@@Payload, tx: EntityManager): Promise<void> {
+        return this.outbox.write(tx, @@queueUpper@@_QUEUE, payload)
+    }
+}

package/templates/be/patterns/reactors/application.command.ts.tpl

@@ -0,0 +1,10 @@
+import { Command } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { @@Action@@Request, @@Action@@Result } from "./@@action@@.contracts"
+
+/** Asks to apply one delivered @@event@@ event; the @@event@@ consumer sends it for every delivery. */
+export class @@Action@@Command extends Command<@@Action@@Result> {
+    constructor(readonly params: PublicExecuteParams<@@Action@@Request>) {
+        super()
+    }
+}

package/templates/be/patterns/reactors/application.contracts.ts.tpl

@@ -0,0 +1,12 @@
+import type { @@Event@@Event } from "@modules/events/@@from@@"
+
+/** What applying one delivered @@event@@ event takes. */
+export interface @@Action@@Request {
+    /** The id of the delivered event; the domain service claims it in the inbox inside its own transaction. */
+    readonly eventId: string
+    /** The delivered event. */
+    readonly event: @@Event@@Event
+}
+
+/** Applying an event answers nothing: a redelivery is a no-op. */
+export type @@Action@@Result = void

package/templates/be/patterns/reactors/application.handler.ts.tpl

@@ -0,0 +1,22 @@
+import { CommandHandler } from "@nestjs/cqrs"
+import { @@service@@ } from "@@serviceModule@@"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import type { @@Action@@Result } from "./@@action@@.contracts"
+import { @@Action@@Command } from "./@@action@@.command"
+
+@CommandHandler(@@Action@@Command)
+/** Hands the delivered @@event@@ event to the domain service, which claims the event id and applies the change in one transaction. */
+export class @@Action@@Handler extends ICQRSHandler<@@Action@@Command, @@Action@@Result> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly @@serviceCamel@@: @@service@@,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: @@Action@@Command): Promise<@@Action@@Result> {
+        return this.@@serviceCamel@@.apply(command.params.request)
+    }
+}

package/templates/be/patterns/reactors/consumer.ts.tpl

@@ -0,0 +1,19 @@
+import { Injectable } from "@nestjs/common"
+import type { CommandBus } from "@nestjs/cqrs"
+import { @@Event@@Event } from "@modules/events/@@from@@"
+import { InjectCommandBus } from "@modules/platform/cqrs"
+import type { EventConsumer, EventDelivery } from "@modules/platform/event-bus"
+import { @@Action@@Command } from "../../application/@@action@@.command"
+
+@Injectable()
+/** The consumer door of the @@event@@ event in the @@reactor@@ reactor: it dispatches one command and forwards the event id. */
+export class @@Event@@Consumer implements EventConsumer<@@Event@@Event> {
+    readonly event = @@Event@@Event
+
+    constructor(@InjectCommandBus() private readonly commandBus: CommandBus) {}
+
+    /** Delivery is at least once: the domain service the command reaches claims `eventId` in the inbox inside its own transaction. */
+    async handle(delivery: EventDelivery<@@Event@@Event>): Promise<void> {
+        await this.commandBus.execute(new @@Action@@Command({ request: { eventId: delivery.eventId, event: delivery.event } }))
+    }
+}

package/templates/be/patterns/reactors/message.module.ts.tpl

@@ -0,0 +1,20 @@
+import { Module } from "@nestjs/common"
+import type { OnModuleInit } from "@nestjs/common"
+import { InjectEventConsumerRegistry } from "@modules/platform/event-bus"
+import type { EventConsumerRegistry } from "@modules/platform/event-bus"
+import { @@Reactor@@Module } from "../../@@reactor@@.module"
+import { @@Event@@Consumer } from "./@@event@@.consumer"
+
+@Module({ imports: [@@Reactor@@Module], providers: [@@Event@@Consumer] })
+/** The message transport of the @@reactor@@ reactor: registers its consumers with the event bus; a worker or api app composes it. */
+export class @@Reactor@@MessageModule implements OnModuleInit {
+    constructor(
+        @InjectEventConsumerRegistry() private readonly registry: EventConsumerRegistry,
+        private readonly @@eventCamel@@Consumer: @@Event@@Consumer,
+    ) {}
+
+    /** Hands every consumer to the registry. */
+    onModuleInit(): void {
+        this.registry.add(this.@@eventCamel@@Consumer)
+    }
+}

package/templates/be/patterns/reactors/reactor.index.ts.tpl

@@ -0,0 +1 @@
+export { @@Reactor@@MessageModule } from "./transport/message/@@reactor@@-message.module"

package/templates/be/patterns/reactors/reactor.module.ts.tpl

@@ -0,0 +1,6 @@
+import { Module } from "@nestjs/common"
+import { @@Action@@Handler } from "./application/@@action@@.handler"
+
+@Module({ providers: [@@Action@@Handler] })
+/** The @@reactor@@ reactor: the handler its consumers dispatch to. */
+export class @@Reactor@@Module {}