@starci/hfs 4.2.17 → 4.4.0

package/templates/be/inbox/service.spec.ts.tpl

@@ -1,46 +1,75 @@
-import { fakeTransaction, mock, mockEntityManager } from "@starci/jest-preset"
+import { fakeInbox, fakeTransaction, mockEntityManager, recordingEventBus } from "@starci/jest-preset"
 import { Test } from "@nestjs/testing"
-import { @@service@@ } from "@@serviceModule@@"
 import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
-import { COMPLETE_@@providerUpper@@_INBOX, INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
+import { @@Provider@@DeliveryRecordedEvent } from "@modules/events/@@provider@@"
+import { EVENT_BUS } from "@modules/platform/event-bus"
+import { INBOX } from "@modules/platform/inbox"
+import { INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
 import { @@Provider@@InboxService } from "./@@provider@@-inbox.service"
 
 const DELIVERY = { id: "delivery-1" }
 
-const build = async (claimed: ReadonlyArray<{ readonly id: string }>) => {
-    const entityManager = mockEntityManager({
-        query: [[INSERT_@@providerUpper@@_INBOX, claimed], [COMPLETE_@@providerUpper@@_INBOX, claimed]],
-    })
+const build = async (fresh: boolean, recorded: ReadonlyArray<{ readonly id: string }> = [{ id: "inbox-1" }]) => {
+    const entityManager = mockEntityManager({ query: [INSERT_@@providerUpper@@_INBOX, recorded] })
     const transaction = fakeTransaction(entityManager)
-    const deliveries = mock<@@service@@>()
+    const claims = fakeInbox()
+    if (!fresh) claims.seen("webhook.@@provider@@", "delivery-1")
+    const events = recordingEventBus<@@Provider@@DeliveryRecordedEvent>()
     const moduleRef = await Test.createTestingModule({
         providers: [
             @@Provider@@InboxService,
             { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },
-            { provide: @@service@@, useValue: deliveries },
+            { provide: INBOX, useValue: claims },
+            { provide: EVENT_BUS, useValue: events },
         ],
     }).compile()
-    return { inbox: moduleRef.get(@@Provider@@InboxService), deliveries, transaction }
+    return { inbox: moduleRef.get(@@Provider@@InboxService), claims, events, entityManager, transaction }
 }
 
 describe("@@Provider@@InboxService", () => {
-    describe("accept@@Provider@@Delivery", () => {
-        it("claims a new @@provider@@ delivery and runs the domain intake inside the claiming transaction", async () => {
-            const { inbox, deliveries, transaction } = await build([{ id: "inbox-1" }])
+    describe("record@@Provider@@Delivery", () => {
+        it("claims, records and publishes a typed event in the same transaction", async () => {
+            const { inbox, claims, events, entityManager, transaction } = await build(true)
+
+            await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })
+
+            expect(entityManager.query).toHaveBeenCalledTimes(1)
+            expect(entityManager.query).toHaveBeenCalledWith(INSERT_@@providerUpper@@_INBOX, ["@@provider@@", "delivery-1", JSON.stringify(DELIVERY)])
+            expect(claims.claims).toEqual([{ source: "webhook.@@provider@@", eventId: "delivery-1" }])
+            expect(events.events).toEqual([@@Provider@@DeliveryRecordedEvent.create({ receiptId: "inbox-1" })])
+            expect(events.allInTransaction).toBe(true)
+            expect(events.entries[0]?.tx).not.toBe(entityManager)
+            expect(transaction.commits).toBe(1)
+        })
+
+        it("acknowledges a duplicate @@provider@@ delivery without further work", async () => {
+            const { inbox, events, entityManager, transaction } = await build(false)
+
+            await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })
+
+            expect(entityManager.query).not.toHaveBeenCalled()
+            expect(events.events).toEqual([])
+            expect(transaction.commits).toBe(1)
+        })
+
+        it("does not publish for an already recorded receipt", async () => {
+            const { inbox, events, transaction } = await build(true, [])
 
-            await inbox.accept@@Provider@@Delivery("delivery-1", DELIVERY)
+            await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })
 
-            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledTimes(1)
-            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY, expect.anything())
+            expect(events.events).toEqual([])
             expect(transaction.commits).toBe(1)
         })
 
-        it("acknowledges a duplicate @@provider@@ delivery without running the domain intake again", async () => {
-            const { inbox, deliveries } = await build([])
+        it("rolls back the receipt when publishing fails", async () => {
+            const { inbox, events, transaction } = await build(true)
+            const failure = new Error("outbox unavailable")
+            events.failNext("publish", failure)
 
-            await inbox.accept@@Provider@@Delivery("delivery-1", DELIVERY)
+            await expect(inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })).rejects.toBe(failure)
 
-            expect(deliveries.accept@@Provider@@Delivery).not.toHaveBeenCalled()
+            expect(transaction.rollbacks).toBe(1)
+            expect(transaction.commits).toBe(0)
         })
     })
 })

package/templates/be/inbox/service.ts.tpl

@@ -1,33 +1,44 @@
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
-import { @@service@@ } from "@@serviceModule@@"
-import { acceptWebhookDelivery, InjectPrimaryEntityManager } from "@modules/platform/database"
-import { COMPLETE_@@providerUpper@@_INBOX, INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
+import { InjectPrimaryEntityManager, recordWebhookDelivery } from "@modules/platform/database"
+import { @@Provider@@DeliveryRecordedEvent } from "@modules/events/@@provider@@"
+import { InjectEventBus } from "@modules/platform/event-bus"
+import type { EventBus } from "@modules/platform/event-bus"
+import { InjectInbox } from "@modules/platform/inbox"
+import type { Inbox } from "@modules/platform/inbox"
+import { INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
 
 interface @@Provider@@Delivery {
     readonly id: string
 }
 
-type @@Provider@@DeliveryId = string | undefined
+interface @@Provider@@DeliveryRequest {
+    readonly eventId: string | undefined
+    readonly delivery: @@Provider@@Delivery
+}
 
 @Injectable()
-/** Claims each @@provider@@ delivery once, then runs the domain intake and completion marker in the same transaction. */
+/** Records each @@provider@@ delivery once. Pending rows are consumed by a separate reactor or job after commit. */
 export class @@Provider@@InboxService {
     constructor(
         @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
-        private readonly deliveries: @@service@@,
+        @InjectInbox() private readonly inbox: Inbox,
+        @InjectEventBus() private readonly eventBus: EventBus,
     ) {}
 
-    /** A duplicate is acknowledged without invoking the domain intake a second time. */
-    accept@@Provider@@Delivery(deliveryId: @@Provider@@DeliveryId, delivery: @@Provider@@Delivery): Promise<void> {
-        return acceptWebhookDelivery({
-            entityManager: this.entityManager,
-            insert: INSERT_@@providerUpper@@_INBOX,
-            complete: COMPLETE_@@providerUpper@@_INBOX,
-            provider: "@@provider@@",
-            deliveryId,
-            payload: delivery,
-            process: (manager) => this.deliveries.accept@@Provider@@Delivery(delivery, manager),
+    /** A duplicate is acknowledged without creating another pending row; this intake never dispatches a command. */
+    record@@Provider@@Delivery(request: @@Provider@@DeliveryRequest): Promise<void> {
+        return this.entityManager.transaction(async (manager) => {
+            if (!(await this.inbox.claim("webhook.@@provider@@", request.eventId, manager))) return
+            const receiptId = await recordWebhookDelivery({
+                manager,
+                insert: INSERT_@@providerUpper@@_INBOX,
+                provider: "@@provider@@",
+                deliveryId: request.eventId,
+                payload: request.delivery,
+            })
+            if (receiptId === undefined) return
+            await this.eventBus.publish(@@Provider@@DeliveryRecordedEvent.create({ receiptId }), manager)
         })
     }
 }

package/templates/be/inbox/sql.ts.tpl

@@ -1,12 +1,12 @@
 import { sql } from "@modules/platform/database"
 
-/** Claims one @@provider@@ delivery and returns its durable inbox identity only to the winning transaction. */
+/** Records one pending @@provider@@ delivery and returns its durable inbox identity only to the winning transaction. */
 export const INSERT_@@providerUpper@@_INBOX = sql`INSERT INTO public.@@table@@ (provider, delivery_id, payload)
 VALUES ($1, $2, $3::jsonb)
 ON CONFLICT (provider, delivery_id) DO NOTHING
 RETURNING id`
 
-/** Marks the claimed delivery complete before the same transaction commits. */
+/** The reactor or job marks a recorded delivery complete in the transaction that applies its effect. Never called by the intake. */
 export const COMPLETE_@@providerUpper@@_INBOX = sql`WITH completed AS (
     UPDATE public.@@table@@
     SET processed_at = now()

package/templates/be/inbox/webhook-door.spec.ts.tpl

@@ -57,8 +57,8 @@ describe("@@Provider@@Webhook", () => {
 
             await door.receive(REQUEST, sign(RAW_BODY, SIGNED_AT), SIGNED_AT, DELIVERY_ID, DELIVERY)
 
-            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledTimes(1)
-            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY_ID, DELIVERY)
+            expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledTimes(1)
+            expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledWith({ eventId: DELIVERY_ID, delivery: DELIVERY })
         })
 
         it("never reaches the inbox when the signature is not the provider's", async () => {
@@ -69,7 +69,7 @@ describe("@@Provider@@Webhook", () => {
                 door.receive(REQUEST, sign(Buffer.from("other body"), SIGNED_AT), SIGNED_AT, DELIVERY_ID, DELIVERY),
             ).rejects.toMatchObject({ code: "HTTP_SECURITY_WEBHOOK_SIGNATURE_INVALID" })
 
-            expect(deliveries.accept@@Provider@@Delivery).not.toHaveBeenCalled()
+            expect(deliveries.record@@Provider@@Delivery).not.toHaveBeenCalled()
         })
     })
 })

package/templates/be/inbox/webhook-door.ts.tpl

@@ -10,7 +10,8 @@ import { @@Event@@Request } from "./dto/@@event@@.request"
 @Controller("webhooks/@@provider@@")
 /**
  * POST /webhooks/@@provider@@, the signed intake door of the @@provider@@ notifier. The signature and replay window are proven
- * first; the verified delivery goes to one domain intake that claims its inbox row and processes it in one transaction.
+ * first; the verified delivery goes to one domain intake that records a receipt and typed outbox event in its transaction. A separate
+ * reactor or job consumes the committed row and dispatches the command.
  */
 export class @@Provider@@Webhook {
     constructor(
@@ -18,7 +19,7 @@ export class @@Provider@@Webhook {
         private readonly deliveries: @@Provider@@InboxService,
     ) {}
 
-    /** Acknowledges with 204 and no body: a duplicate receives the same acknowledgement without being processed again. */
+    /** Acknowledges with 204 and no body: a duplicate receives the same acknowledgement without another inbox row. */
     @Post()
     @HttpCode(HttpStatus.NO_CONTENT)
     @Public({ reason: PublicReason.SignedWebhook })
@@ -31,6 +32,6 @@ export class @@Provider@@Webhook {
         @Body() delivery: @@Event@@Request,
     ): Promise<void> {
         this.signature.verify({ provider: "@@provider@@", rawBody: request.rawBody, signature, timestamp })
-        await this.deliveries.accept@@Provider@@Delivery(deliveryId, delivery)
+        await this.deliveries.record@@Provider@@Delivery({ eventId: deliveryId, delivery })
     }
 }

package/templates/be/patterns/api/feature.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Feature@@ApiOptions } from "./@@feature@@.options"
+
+/** The configurable-module base of the @@feature@@ module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Feature@@ApiOptions>().setClassMethodName("register").build()

package/templates/be/patterns/api/feature.module.ts.tpl

@@ -1,6 +1,7 @@
 import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./@@feature@@.module-definition"
 import { @@Action@@Handler } from "./application/@@action@@.handler"
 
 @Module({ providers: [@@Action@@Handler] })
 /** The @@feature@@ feature: the handlers of its application. */
-export class @@Feature@@ApiModule {}
+export class @@Feature@@ApiModule extends ConfigurableModuleClass {}

package/templates/be/patterns/api/feature.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@feature@@ module takes no options yet. */
+export type @@Feature@@ApiOptions = Record<string, never>

package/templates/be/patterns/api/graphql.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Feature@@GraphqlOptions } from "./@@feature@@-graphql.options"
+
+/** The configurable-module base of the @@feature@@-graphql module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Feature@@GraphqlOptions>().setClassMethodName("register").build()

package/templates/be/patterns/api/graphql.module.ts.tpl

@@ -1,7 +1,8 @@
 import { Module } from "@nestjs/common"
 import { @@Feature@@ApiModule } from "../../@@feature@@.module"
 import { @@Action@@Resolver } from "./@@action@@.resolver"
+import { ConfigurableModuleClass } from "./@@feature@@-graphql.module-definition"
 
-@Module({ imports: [@@Feature@@ApiModule], providers: [@@Action@@Resolver] })
+@Module({ imports: [@@Feature@@ApiModule.register({})], providers: [@@Action@@Resolver] })
 /** The GraphQL transport of the @@feature@@ feature. */
-export class @@Feature@@GraphqlModule {}
+export class @@Feature@@GraphqlModule extends ConfigurableModuleClass {}

package/templates/be/patterns/api/graphql.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@feature@@-graphql module takes no options yet. */
+export type @@Feature@@GraphqlOptions = Record<string, never>

package/templates/be/patterns/cli/group.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Group@@Options } from "./@@group@@.options"
+
+/** The configurable-module base of the @@group@@ module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Group@@Options>().setClassMethodName("register").build()

package/templates/be/patterns/cli/group.module.ts.tpl

@@ -1,7 +1,8 @@
 import { Module } from "@nestjs/common"
 import { @@Group@@Cli } from "./@@group@@.cli"
+import { ConfigurableModuleClass } from "./@@group@@.module-definition"
 import { RunCli } from "./subs/run.cli"
 
 @Module({ providers: [@@Group@@Cli, RunCli] })
 /** The @@group@@ group: its command and its sub-commands; the work is the runner service the sub-command delegates to. */
-export class @@Group@@Module {}
+export class @@Group@@Module extends ConfigurableModuleClass {}

package/templates/be/patterns/cli/group.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@group@@ module takes no options yet. */
+export type @@Group@@Options = Record<string, never>

package/templates/be/patterns/event-bus/platform/errors/event-bus.error.ts.tpl

@@ -3,8 +3,6 @@ import type { ErrorKind } from "@modules/platform/errors"
 
 /** Codes of the event-bus capability. */
 export enum EventBusErrorCode {
-    /** A delivered envelope does not have the shape its consumer's event class reads. */
-    EnvelopeInvalid = "EVENT_BUS_ENVELOPE_INVALID",
     /** The broker did not answer a call within its deadline, or refused it. */
     BrokerUnavailable = "EVENT_BUS_BROKER_UNAVAILABLE",
     /** A dead letter id does not name a message the dead-letter topic holds. */
@@ -13,7 +11,6 @@ export enum EventBusErrorCode {
 
 /** How each event-bus code travels. */
 export const EVENT_BUS_ERROR_KINDS: Record<EventBusErrorCode, ErrorKind> = {
-    [EventBusErrorCode.EnvelopeInvalid]: "internal",
     [EventBusErrorCode.BrokerUnavailable]: "unavailable",
     [EventBusErrorCode.DeadLetterUnknown]: "not-found",
 }

package/templates/be/patterns/event-bus/platform/messages/event-bus.messages.ts.tpl

@@ -3,12 +3,10 @@ import type { MessageBundle } from "@modules/platform/i18n"
 /** Display text of the event-bus codes, Vietnamese and English. */
 export const EVENT_BUS_MESSAGES: MessageBundle = {
     vi: {
-        "errors.EVENT_BUS_ENVELOPE_INVALID": "Sự kiện {{event}} nhận được có nội dung không đúng dạng.",
         "errors.EVENT_BUS_BROKER_UNAVAILABLE": "Kênh sự kiện {{operation}} không phản hồi kịp.",
         "errors.EVENT_BUS_DEAD_LETTER_UNKNOWN": "Không có sự kiện lỗi {{id}} để đưa lại.",
     },
     en: {
-        "errors.EVENT_BUS_ENVELOPE_INVALID": "The received {{event}} event has a payload of the wrong shape.",
         "errors.EVENT_BUS_BROKER_UNAVAILABLE": "The event broker did not answer {{operation}} in time.",
         "errors.EVENT_BUS_DEAD_LETTER_UNKNOWN": "There is no dead letter {{id}} to requeue.",
     },

package/templates/be/patterns/jobs/job.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Job@@Options } from "./@@job@@.options"
+
+/** The configurable-module base of the @@job@@ module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Job@@Options>().setClassMethodName("register").build()

package/templates/be/patterns/jobs/job.module.ts.tpl

@@ -1,6 +1,7 @@
 import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./@@job@@.module-definition"
 import { @@Step@@Step } from "./steps/@@step@@.step"
 
 @Module({ providers: [@@Step@@Step], exports: [@@Step@@Step] })
 /** The application of the @@job@@ job: its steps; the queue transport module imports it. */
-export class @@Job@@Module {}
+export class @@Job@@Module extends ConfigurableModuleClass {}

package/templates/be/patterns/jobs/job.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@job@@ module takes no options yet. */
+export type @@Job@@Options = Record<string, never>

package/templates/be/patterns/jobs/job.queue.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Job@@QueueOptions } from "./@@job@@-queue.options"
+
+/** The configurable-module base of the @@job@@-queue module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Job@@QueueOptions>().setClassMethodName("register").build()

package/templates/be/patterns/jobs/job.queue.module.ts.tpl

@@ -3,15 +3,18 @@ import type { OnModuleInit } from "@nestjs/common"
 import { InjectJobProcessorRegistry } from "@modules/platform/jobs"
 import type { JobProcessorRegistry } from "@modules/platform/jobs"
 import { @@Job@@Module } from "../../@@job@@.module"
+import { ConfigurableModuleClass } from "./@@job@@-queue.module-definition"
 import { @@Job@@Processor } from "./@@job@@.processor"
 
-@Module({ imports: [@@Job@@Module], providers: [@@Job@@Processor] })
+@Module({ imports: [@@Job@@Module.register({})], providers: [@@Job@@Processor] })
 /** The queue transport of the @@job@@ job: its processor, which a worker or api app composes and which subscribes to its queue when the module starts. */
-export class @@Job@@QueueModule implements OnModuleInit {
+export class @@Job@@QueueModule extends ConfigurableModuleClass implements OnModuleInit {
     constructor(
         @InjectJobProcessorRegistry() private readonly registry: JobProcessorRegistry,
         private readonly @@jobCamel@@Processor: @@Job@@Processor,
-    ) {}
+    ) {
+        super()
+    }
 
     /** Hands the processor to the registry. */
     onModuleInit(): void {

package/templates/be/patterns/jobs/job.queue.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@job@@-queue module takes no options yet. */
+export type @@Job@@QueueOptions = Record<string, never>

package/templates/be/patterns/jobs/platform/fenced.processor.spec.ts.tpl

@@ -1,3 +1,4 @@
+import { Test } from "@nestjs/testing"
 import type { ClaimedJob } from "./jobs.contracts"
 import { FencedProcessor } from "./fenced.processor"
 
@@ -21,7 +22,8 @@ class MailProcessor extends FencedProcessor {
 
 describe("FencedProcessor", () => {
     it("lets a processor declare its queue and process a claimed job", async () => {
-        const processor = new MailProcessor()
+        const moduleRef = await Test.createTestingModule({ providers: [MailProcessor] }).compile()
+        const processor = moduleRef.get(MailProcessor)
 
         await processor.process(claimedJob)
 

package/templates/be/patterns/outbox/platform/outbox-relay.policy.spec.ts.tpl

@@ -1,6 +1,10 @@
+import { Test } from "@nestjs/testing"
 import { fakeTransaction, mock, mockEntityManager } from "@starci/jest-preset"
 import type { MockEntityManager } from "@starci/jest-preset"
 import type { EntityManager } from "typeorm"
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import { InjectLogger, LOGGER } from "@modules/platform/logging"
 import type { Logger } from "@modules/platform/logging"
 import { OutboxLogEvent } from "./outbox.log-events"
 import { OutboxRelayPolicy } from "./outbox-relay.policy"
@@ -9,25 +13,37 @@ interface Row {
     readonly id: string
 }
 
+const OUTBOX_MANAGERS: unique symbol = Symbol("spec.outbox.managers")
+
+/** Injects the entity managers of the test relay. Parameter type: ReadonlyArray<EntityManager>. */
+const InjectOutboxManagers = (): TypedParameterDecorator<ReadonlyArray<EntityManager>> =>
+    injector<ReadonlyArray<EntityManager>>(OUTBOX_MANAGERS)
+
 class ProbeRelay extends OutboxRelayPolicy<Row> {
     readonly select = jest.fn<Promise<Array<Row>>, [EntityManager]>()
     readonly deliver = jest.fn<Promise<void>, [ReadonlyArray<Row>]>()
     readonly mark = jest.fn<Promise<void>, [EntityManager, ReadonlyArray<Row>]>()
     readonly idle = jest.fn<Promise<void>, []>()
+    protected readonly outbox = "probe"
 
     constructor(
-        protected readonly managers: ReadonlyArray<EntityManager>,
-        protected readonly logger: Logger,
-        protected readonly outbox = "probe",
+        @InjectOutboxManagers() protected readonly managers: ReadonlyArray<EntityManager>,
+        @InjectLogger() protected readonly logger: Logger,
     ) {
         super()
     }
 }
 
-const build = (...managers: Array<MockEntityManager>) => {
+const build = async (...managers: Array<MockEntityManager>) => {
     const logger = mock<Logger>()
-    const relay = new ProbeRelay(managers, logger)
-    return { relay, logger }
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            ProbeRelay,
+            { provide: OUTBOX_MANAGERS, useValue: [...managers] },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    return { relay: moduleRef.get(ProbeRelay), logger }
 }
 
 describe("OutboxRelayPolicy", () => {
@@ -35,7 +51,7 @@ describe("OutboxRelayPolicy", () => {
         it("delivers and marks every connection's waiting rows in its own transaction", async () => {
             const first = fakeTransaction(mockEntityManager())
             const second = fakeTransaction(mockEntityManager())
-            const { relay } = build(first.em, second.em)
+            const { relay } = await build(first.em, second.em)
             const rows = [{ id: "row-1" }, { id: "row-2" }]
             relay.select.mockResolvedValueOnce(rows).mockResolvedValueOnce([])
             relay.deliver.mockResolvedValue(undefined)
@@ -52,7 +68,7 @@ describe("OutboxRelayPolicy", () => {
 
         it("leaves the rows unmarked when delivery fails", async () => {
             const transaction = fakeTransaction(mockEntityManager())
-            const { relay } = build(transaction.em)
+            const { relay } = await build(transaction.em)
             const failure = new Error("transport down")
             relay.select.mockResolvedValue([{ id: "row-1" }])
             relay.deliver.mockRejectedValue(failure)
@@ -66,7 +82,7 @@ describe("OutboxRelayPolicy", () => {
 
     describe("the loop", () => {
         it("repeats immediately after work, idles after an empty or failed pass, logs the failure and stops on shutdown", async () => {
-            const { relay, logger } = build()
+            const { relay, logger } = await build()
             const failure = new Error("outbox unreadable")
             jest.spyOn(relay, "relay").mockResolvedValueOnce(1).mockResolvedValueOnce(0).mockRejectedValueOnce(failure)
             let waits = 0

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

@@ -2,7 +2,7 @@ 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">
+export type QueueConfig = Omit<QueueOptions, "connections" | "schedulers" | "outboxOnly">
 
 /** Reads the queue options: the Redis address is required, the rest are tunables with literal defaults. */
 export const parseQueueConfig = (env: EnvSource): QueueConfig => ({

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

@@ -1,7 +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 { InjectQueueOutbox, InjectQueueWorkerRegistry, QUEUE_OUTBOX, 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.module-definition.ts.tpl

@@ -1,9 +1,9 @@
 import { ConfigurableModuleBuilder } from "@nestjs/common"
 import { QUEUE_OPTIONS } from "./queue.decorators"
-import type { QueueOptions } from "./queue.options"
+import type { QueueRegistrationOptions } 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>({
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<QueueRegistrationOptions>({
     optionsInjectionToken: QUEUE_OPTIONS,
 })
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))

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

@@ -28,6 +28,17 @@ 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)
+        if (options.outboxOnly === true) {
+            return {
+                ...base,
+                providers: [
+                    ...(base.providers ?? []),
+                    QueueOutboxService,
+                    { provide: QUEUE_OUTBOX, useExisting: QueueOutboxService },
+                ],
+                exports: [QUEUE_OUTBOX],
+            }
+        }
         return {
             ...base,
             providers: [

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

@@ -3,6 +3,8 @@ 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 runtime registration owns the relay, workers and schedulers. */
+    readonly outboxOnly?: false
     /** The Redis host BullMQ talks to. */
     readonly redisHost: string
     /** The Redis port. */
@@ -22,3 +24,11 @@ export interface QueueOptions {
     /** 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>
 }
+
+/** A one-off producer writes an outbox row and exits; the running app owns delivery. */
+export interface QueueOutboxOnlyOptions {
+    readonly outboxOnly: true
+}
+
+/** Registers either the running queue capability or only its transactional writer. */
+export type QueueRegistrationOptions = QueueOptions | QueueOutboxOnlyOptions

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

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Queue@@Options } from "./@@queue@@.options"
+
+/** The configurable-module base of the @@queue@@ module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Queue@@Options>().setClassMethodName("register").build()

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

@@ -1,6 +1,7 @@
 import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./@@queue@@.module-definition"
 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 {}
+export class @@Queue@@Module extends ConfigurableModuleClass {}

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

@@ -0,0 +1,2 @@
+/** The @@queue@@ module takes no options yet. */
+export type @@Queue@@Options = Record<string, never>

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

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Reactor@@MessageOptions } from "./@@reactor@@-message.options"
+
+/** The configurable-module base of the @@reactor@@-message module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Reactor@@MessageOptions>().setClassMethodName("register").build()

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

@@ -4,14 +4,17 @@ 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"
+import { ConfigurableModuleClass } from "./@@reactor@@-message.module-definition"
 
-@Module({ imports: [@@Reactor@@Module], providers: [@@Event@@Consumer] })
+@Module({ imports: [@@Reactor@@Module.register({})], 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 {
+export class @@Reactor@@MessageModule extends ConfigurableModuleClass implements OnModuleInit {
     constructor(
         @InjectEventConsumerRegistry() private readonly registry: EventConsumerRegistry,
         private readonly @@eventCamel@@Consumer: @@Event@@Consumer,
-    ) {}
+    ) {
+        super()
+    }
 
     /** Hands every consumer to the registry. */
     onModuleInit(): void {

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

@@ -0,0 +1,2 @@
+/** The @@reactor@@-message module takes no options yet. */
+export type @@Reactor@@MessageOptions = Record<string, never>

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

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Reactor@@Options } from "./@@reactor@@.options"
+
+/** The configurable-module base of the @@reactor@@ module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<@@Reactor@@Options>().setClassMethodName("register").build()