@starci/hfs 4.3.0 → 4.4.1

package/templates/be/inbox/platform/inbox/inbox.decorators.ts.tpl

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { Inbox } from "./inbox.port"
+
+/** Token of the shared, transaction-owned inbox claims. */
+export const INBOX: unique symbol = Symbol("platform.inbox")
+
+/** Injects the Inbox port. Parameter type: Inbox. */
+export const InjectInbox = (): TypedParameterDecorator<Inbox> => injector<Inbox>(INBOX)

package/templates/be/inbox/platform/inbox/inbox.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { InboxOptions } from "./inbox.options"
+
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<InboxOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/inbox/platform/inbox/inbox.module.ts.tpl

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { INBOX } from "./inbox.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./inbox.module-definition"
+import { PostgresInbox } from "./inbox.service"
+
+@Module({})
+/** Provides the lite Inbox port; all claims use the domain service's own transaction. */
+export class InboxModule extends ConfigurableModuleClass {
+    /** Registers the shared inbox once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), { provide: INBOX, useClass: PostgresInbox }],
+            exports: [INBOX],
+        }
+    }
+}

package/templates/be/inbox/platform/inbox/inbox.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The lite inbox uses the caller's transaction and has no runtime options. */
+export interface InboxOptions {}

package/templates/be/inbox/platform/inbox/inbox.port.ts.tpl

@@ -0,0 +1,10 @@
+import type { EntityManager } from "typeorm"
+
+/** The signed provider header may omit its delivery identity; the adapter refuses that delivery. */
+export type InboxEventId = string | undefined
+
+/** Deduplicates a delivery inside the transaction that records its receipt or applies its effect. */
+export interface Inbox {
+    /** Claims once per source and event id; a rolled-back transaction gives the claim back automatically. */
+    claim(source: string, eventId: InboxEventId, tx: EntityManager): Promise<boolean>
+}

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

@@ -0,0 +1,41 @@
+import { Test } from "@nestjs/testing"
+import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { DatabaseErrorCode } from "@modules/platform/database"
+import { PostgresInbox } from "./inbox.service"
+import { CLAIM_EVENT } from "./persistence/inbox.sql"
+
+describe("PostgresInbox", () => {
+    const build = async () => {
+        const module = await Test.createTestingModule({ providers: [PostgresInbox] }).compile()
+        return module.get(PostgresInbox)
+    }
+
+    it("claims a normalized delivery id through the caller's transaction", async () => {
+        const subject = await build()
+        const transaction = fakeTransaction(mockEntityManager({ query: [CLAIM_EVENT, [{ event_id: "delivery-1" }]] }))
+
+        const fresh = await transaction.em.transaction((manager) => subject.claim("webhook:spec", "  delivery-1  ", manager))
+
+        expect(fresh).toBe(true)
+        expect(transaction.em.query).toHaveBeenCalledWith(CLAIM_EVENT, ["webhook:spec", "delivery-1"])
+        expect(transaction.commits).toBe(1)
+    })
+
+    it("returns false when the source and event id have already been claimed", async () => {
+        const subject = await build()
+        const manager = mockEntityManager({ query: [CLAIM_EVENT, []] })
+
+        await expect(subject.claim("webhook:spec", "delivery-1", manager)).resolves.toBe(false)
+
+        expect(manager.query).toHaveBeenCalledTimes(1)
+    })
+
+    it.each([["no", undefined], ["a blank", "   "]])("refuses %s delivery id before writing a claim", async (_label, eventId) => {
+        const subject = await build()
+        const manager = mockEntityManager()
+
+        await expect(subject.claim("webhook:spec", eventId, manager)).rejects.toMatchObject({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
+
+        expect(manager.query).not.toHaveBeenCalled()
+    })
+})

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

@@ -0,0 +1,19 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { DatabaseError, DatabaseErrorCode } from "@modules/platform/database"
+import type { Inbox, InboxEventId } from "./inbox.port"
+import { CLAIM_EVENT } from "./persistence/inbox.sql"
+
+@Injectable()
+/** Claims a delivery with the receipt transaction, so a failure can be retried without losing the delivery. */
+export class PostgresInbox implements Inbox {
+    /** The first claim wins; the same source and delivery id becomes a no-op on redelivery. */
+    async claim(source: string, eventId: InboxEventId, tx: EntityManager): Promise<boolean> {
+        const normalizedEventId = eventId?.trim()
+        if (!normalizedEventId) {
+            throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
+        }
+        const rows: Array<object> = await tx.query(CLAIM_EVENT, [source, normalizedEventId])
+        return rows.length > 0
+    }
+}

package/templates/be/inbox/platform/inbox/index.ts.tpl

@@ -0,0 +1,3 @@
+export { INBOX, InjectInbox } from "./inbox.decorators"
+export { InboxModule } from "./inbox.module"
+export type { Inbox, InboxEventId } from "./inbox.port"

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

@@ -0,0 +1,7 @@
+import { sql } from "@modules/platform/database"
+
+/** The unique source and delivery id let only one transaction record or process each delivery. */
+export const CLAIM_EVENT = sql`INSERT INTO public.inbox (source, event_id)
+VALUES ($1, $2)
+ON CONFLICT (source, event_id) DO NOTHING
+RETURNING event_id`

package/templates/be/inbox/platform/migration.sql.tpl

@@ -0,0 +1,48 @@
+-- Both the claim and receipt event use the intake transaction; after-commit processing reads the outbox separately.
+create table public.inbox (
+    source text not null check (source <> ''),
+    event_id text not null check (event_id <> ''),
+    claimed_at timestamptz not null default now(),
+    primary key (source, event_id)
+);
+
+alter table public.inbox enable row level security;
+alter table public.inbox force row level security;
+
+create policy "inbox_app_be_select"
+on public.inbox for select to app_be
+using (source <> '');
+
+create policy "inbox_app_be_insert"
+on public.inbox for insert to app_be
+with check (source <> '');
+
+revoke all on table public.inbox from public, anon, authenticated;
+grant select, insert on table public.inbox to app_be;
+
+create table public.event_bus (
+    event_id text primary key check (event_id <> ''),
+    event_name text not null check (event_name <> ''),
+    payload jsonb not null,
+    recorded_at timestamptz not null default now(),
+    delivered_at timestamptz
+);
+
+alter table public.event_bus enable row level security;
+alter table public.event_bus force row level security;
+
+create policy "event_bus_app_be_select"
+on public.event_bus for select to app_be
+using (event_name <> '');
+
+create policy "event_bus_app_be_insert"
+on public.event_bus for insert to app_be
+with check (event_name <> '');
+
+create policy "event_bus_app_be_update"
+on public.event_bus for update to app_be
+using (event_name <> '')
+with check (event_name <> '');
+
+revoke all on table public.event_bus from public, anon, authenticated;
+grant select, insert, update on table public.event_bus to app_be;

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

@@ -1,42 +1,75 @@
-import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { fakeInbox, fakeTransaction, mockEntityManager, recordingEventBus } from "@starci/jest-preset"
 import { Test } from "@nestjs/testing"
 import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+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 (recorded: ReadonlyArray<{ readonly id: string }>) => {
+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 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: INBOX, useValue: claims },
+            { provide: EVENT_BUS, useValue: events },
         ],
     }).compile()
-    return { inbox: moduleRef.get(@@Provider@@InboxService), entityManager, transaction }
+    return { inbox: moduleRef.get(@@Provider@@InboxService), claims, events, entityManager, transaction }
 }
 
 describe("@@Provider@@InboxService", () => {
     describe("record@@Provider@@Delivery", () => {
-        it("records a pending @@provider@@ delivery without business processing or a completion write", async () => {
-            const { inbox, entityManager, transaction } = await build([{ id: "inbox-1" }])
+        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("delivery-1", DELIVERY)
+            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, entityManager, transaction } = await build([])
+            const { inbox, events, entityManager, transaction } = await build(false)
 
-            await inbox.record@@Provider@@Delivery("delivery-1", DELIVERY)
+            await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })
 
-            expect(entityManager.query).toHaveBeenCalledTimes(1)
+            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.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })
+
+            expect(events.events).toEqual([])
             expect(transaction.commits).toBe(1)
         })
+
+        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 expect(inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })).rejects.toBe(failure)
+
+            expect(transaction.rollbacks).toBe(1)
+            expect(transaction.commits).toBe(0)
+        })
     })
 })

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

@@ -1,29 +1,44 @@
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
 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()
 /** 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,
+        @InjectInbox() private readonly inbox: Inbox,
+        @InjectEventBus() private readonly eventBus: EventBus,
     ) {}
 
     /** A duplicate is acknowledged without creating another pending row; this intake never dispatches a command. */
-    record@@Provider@@Delivery(deliveryId: @@Provider@@DeliveryId, delivery: @@Provider@@Delivery): Promise<void> {
-        return recordWebhookDelivery({
-            entityManager: this.entityManager,
-            insert: INSERT_@@providerUpper@@_INBOX,
-            provider: "@@provider@@",
-            deliveryId,
-            payload: delivery,
+    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/webhook-door.spec.ts.tpl

@@ -58,7 +58,7 @@ describe("@@Provider@@Webhook", () => {
             await door.receive(REQUEST, sign(RAW_BODY, SIGNED_AT), SIGNED_AT, DELIVERY_ID, DELIVERY)
 
             expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledTimes(1)
-            expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY_ID, DELIVERY)
+            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 () => {

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

@@ -10,7 +10,7 @@ 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 records a pending inbox row in its transaction. A separate
+ * 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 {
@@ -32,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.record@@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"