@starci/hfs 4.11.13 → 4.11.16

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

@@ -1,9 +1,17 @@
 import { Injectable } from "@nestjs/common"
-import type { EntityManager } from "typeorm"
+import type { EntityManager, ObjectLiteral } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
-import { BATCH_ROWS, DatabaseError, DatabaseErrorCode, callDbFunction } from "@modules/platform/database"
-import type { ClientOperation, ClientOperationEffect, Inbox, InboxEventId } from "./inbox.port"
+import { BATCH_ROWS, DatabaseError, DatabaseErrorCode, callDbFunction, returnedRows, rowShape } from "@modules/platform/database"
+import type {
+    ClientOperation,
+    ClientOperationEffect,
+    EntityInbox,
+    Inbox,
+    InboxEntityReceipt,
+    InboxEventId,
+    InboxReceiptId,
+} from "./inbox.port"
 import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
 import { InboxError, InboxErrorCode } from "./errors/inbox.error"
 import { clientSource } from "./client-operation.policy"
@@ -43,19 +51,43 @@ interface InboxSweepRow {
     readonly deleted_count: number
 }
 
+/** The row a receipt insert returns to the transaction that won it. */
+const isReceiptRow = rowShape({ id: "string" })
+
+/** The provider's delivery id, trimmed; a missing or blank one is refused before anything is claimed or written. */
+const deliveryIdOf = (eventId: InboxEventId): string => {
+    const deliveryId = eventId?.trim()
+    if (!deliveryId) throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
+    return deliveryId
+}
+
 @Injectable()
 /** Claims a delivery with the receipt transaction, so a failure can be retried without losing the delivery. */
-export class PostgresInbox implements Inbox {
+export class PostgresInbox implements Inbox, EntityInbox {
     constructor(@InjectClock() private readonly clock: Clock) {}
 
     /** 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 = await callDbFunction<InboxEventRow>(tx, "public.inbox_claim_event", [source, normalizedEventId])
-        return rows.length > 0
+        return this.claimDelivery(source, deliveryIdOf(eventId), tx)
+    }
+
+    /** The claim first; only its winner inserts the receipt row, and a row that already exists is left as it is. */
+    async claimRow<Row extends ObjectLiteral>(
+        source: string,
+        eventId: InboxEventId,
+        tx: EntityManager,
+        receipt: InboxEntityReceipt<Row>,
+    ): Promise<InboxReceiptId> {
+        const deliveryId = deliveryIdOf(eventId)
+        if (!(await this.claimDelivery(source, deliveryId, tx))) return undefined
+        const inserted = await tx
+            .createQueryBuilder(receipt.entity, "receipt")
+            .insert()
+            .values(receipt.row(deliveryId))
+            .orIgnore()
+            .returning("id")
+            .execute()
+        return returnedRows(inserted.raw, isReceiptRow)[0]?.id
     }
 
     /** Runs once in the domain transaction, returning the persisted JSON outcome on both the first call and every retry. */
@@ -99,4 +131,10 @@ export class PostgresInbox implements Inbox {
         const rows = await callDbFunction<InboxSweepRow>(tx, "public.inbox_sweep_clients", [cutoff, BATCH_ROWS])
         return rows[0]?.deleted_count ?? 0
     }
+
+    /** Claims a normalized delivery id; an answered row means this transaction holds the first claim. */
+    private async claimDelivery(source: string, deliveryId: string, tx: EntityManager): Promise<boolean> {
+        const rows = await callDbFunction<InboxEventRow>(tx, "public.inbox_claim_event", [source, deliveryId])
+        return rows.length > 0
+    }
 }

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

@@ -1,5 +1,5 @@
-export { INBOX, InjectInbox } from "./inbox.decorators"
+export { INBOX, InjectEntityInbox, InjectInbox } from "./inbox.decorators"
 export { InboxModule } from "./inbox.module"
-export type { Inbox, InboxEventId } from "./inbox.port"
+export type { EntityInbox, Inbox, InboxEntityReceipt, InboxEventId } from "./inbox.port"
 export { INBOX_ERROR_KINDS } from "./errors/inbox.error"
 export { INBOX_MESSAGES } from "./messages/inbox.messages"

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

@@ -1,19 +1,19 @@
 import { fakeInbox, fakeTransaction, mockEntityManager, recordingEventBus } from "@starci/jest-preset"
 import { Test } from "@nestjs/testing"
-import { PRIMARY_ENTITY_MANAGER, webhookReceiptInsert } from "@modules/platform/database"
+import { DatabaseErrorCode, 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 { @@Provider@@InboxEntity } from "./persistence/entities/@@provider@@-inbox.entity"
 import { @@Provider@@InboxService } from "./@@provider@@-inbox.service"
 
 const DELIVERY = { id: "delivery-1" }
-const INSERT_@@providerUpper@@_INBOX = webhookReceiptInsert("@@table@@")
+const SOURCE = "webhook.@@provider@@"
 
-const build = async (fresh: boolean, recorded: ReadonlyArray<{ readonly id: string }> = [{ id: "inbox-1" }]) => {
-    const entityManager = mockEntityManager({ query: [INSERT_@@providerUpper@@_INBOX, recorded] })
+const build = async () => {
+    const entityManager = mockEntityManager()
     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: [
@@ -28,41 +28,65 @@ const build = async (fresh: boolean, recorded: ReadonlyArray<{ readonly id: stri
 
 describe("@@Provider@@InboxService", () => {
     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)
+        it("claims, records the receipt row and publishes a typed event in the same transaction", async () => {
+            const { inbox, claims, events, entityManager, transaction } = await build()
 
             await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })
 
-            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(claims.claims).toEqual([{ source: SOURCE, eventId: "delivery-1" }])
+            expect(claims.receipts).toEqual([
+                {
+                    id: "receipt-1",
+                    source: SOURCE,
+                    eventId: "delivery-1",
+                    entity: @@Provider@@InboxEntity,
+                    row: { provider: "@@provider@@", deliveryId: "delivery-1", payload: DELIVERY },
+                    tx: events.entries[0]?.tx,
+                    inTransaction: true,
+                },
+            ])
+            expect(events.events).toEqual([@@Provider@@DeliveryRecordedEvent.create({ receiptId: "receipt-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)
+            const { inbox, claims, events, transaction } = await build()
+            claims.seen(SOURCE, "delivery-1")
 
             await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })
 
-            expect(entityManager.query).not.toHaveBeenCalled()
+            expect(claims.receipts).toEqual([])
             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, [])
+            const { inbox, claims, events, transaction } = await build()
+            claims.receiptExists(SOURCE, "delivery-1")
 
             await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })
 
+            expect(claims.receipts).toEqual([])
             expect(events.events).toEqual([])
             expect(transaction.commits).toBe(1)
         })
 
+        it("refuses a delivery without an id before recording anything", async () => {
+            const { inbox, claims, events, transaction } = await build()
+
+            await expect(inbox.record@@Provider@@Delivery({ eventId: undefined, delivery: DELIVERY, correlationId: "request-1" })).rejects.toMatchObject({
+                code: DatabaseErrorCode.WebhookDeliveryIdRequired,
+            })
+
+            expect(claims.receipts).toEqual([])
+            expect(events.events).toEqual([])
+            expect(transaction.rollbacks).toBe(1)
+        })
+
         it("rolls back the receipt when publishing fails", async () => {
-            const { inbox, events, transaction } = await build(true)
+            const { inbox, events, transaction } = await build()
             const failure = new Error("event bus unavailable")
             events.failNext("publish", failure)
 

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

@@ -1,11 +1,12 @@
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
-import { InjectPrimaryEntityManager, recordWebhookDelivery } from "@modules/platform/database"
+import { InjectPrimaryEntityManager } 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 { InjectEntityInbox } from "@modules/platform/inbox"
+import type { EntityInbox, InboxEntityReceipt } from "@modules/platform/inbox"
+import { @@Provider@@InboxEntity } from "./persistence/entities/@@provider@@-inbox.entity"
 
 interface @@Provider@@Delivery {
     readonly id: string
@@ -23,21 +24,20 @@ interface @@Provider@@DeliveryRequest {
 export class @@Provider@@InboxService {
     constructor(
         @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
-        @InjectInbox() private readonly inbox: Inbox,
+        @InjectEntityInbox() private readonly inbox: EntityInbox,
         @InjectEventBus() private readonly eventBus: EventBus,
     ) {}
 
-    /** A duplicate is acknowledged without creating another pending row; this intake never dispatches a command. */
+    /**
+     * The claim and the pending receipt row commit together: the winning claim inserts the row keyed by the delivery id the
+     * claim normalized; a duplicate is acknowledged without another pending row, and 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,
-                table: "@@table@@",
-                provider: "@@provider@@",
-                deliveryId: request.eventId,
-                payload: request.delivery,
-            })
+            const receiptId = await this.inbox.claimRow("webhook.@@provider@@", request.eventId, manager, {
+                entity: @@Provider@@InboxEntity,
+                row: (deliveryId) => ({ provider: "@@provider@@", deliveryId, payload: request.delivery }),
+            } satisfies InboxEntityReceipt<@@Provider@@InboxEntity>)
             if (receiptId === undefined) return
             await this.eventBus.publish(@@Provider@@DeliveryRecordedEvent.create({ receiptId }), manager, request.correlationId)
         })

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

@@ -5,7 +5,7 @@ import { Test } from "@nestjs/testing"
 import type { Request } from "express"
 import { @@Provider@@InboxService } from "@modules/domain/@@provider@@-inbox"
 import { Secret } from "@modules/platform/config"
-import { HttpSecurityModule, WebhookSignatureService } from "@modules/platform/http-security"
+import { HttpSecurityModule, ReadinessService, WebhookSignatureService } from "@modules/platform/http-security"
 import type { HttpSecurityOptions } from "@modules/platform/http-security"
 import type { CorrelationRequest } from "@modules/platform/logging"
 import { @@Event@@Request } from "./dto/@@event@@.request"
@@ -46,6 +46,9 @@ const build = async (deliveries: @@Provider@@InboxService) => {
     })
         .overrideProvider(WebhookSignatureService)
         .useValue(new WebhookSignatureService(OPTIONS, new FakeClock(AT)))
+        // The module also provides the readiness probe, which needs the database and retry timer this door never reaches.
+        .overrideProvider(ReadinessService)
+        .useValue(mock<ReadinessService>())
         .compile()
     return moduleRef.get(@@Provider@@Webhook)
 }

package/templates/be/platform/errors-graphql/graphql-error.mapper.spec.ts

@@ -1,13 +1,23 @@
+import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
 import { GraphQLError } from "graphql"
+import { ERRORS_SERVICE } from "./errors.decorators"
 import type { ErrorsService } from "./errors.service"
 import { formatGraphqlError } from "./graphql-error.mapper"
 
 const formatted = { message: "raw", path: ["item"], locations: [{ line: 1, column: 3 }] }
 
+const build = async () => {
+    const double = mock<ErrorsService>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: ERRORS_SERVICE, useValue: double }],
+    }).compile()
+    return moduleRef.get<typeof double>(ERRORS_SERVICE)
+}
+
 describe("formatGraphqlError", () => {
-    it("keeps the message of a malformed operation and marks it invalid without describing it", () => {
-        const errors = mock<ErrorsService>()
+    it("keeps the message of a malformed operation and marks it invalid without describing it", async () => {
+        const errors = await build()
 
         expect(formatGraphqlError(errors, formatted, new GraphQLError("GRAPHQL_VALIDATION_FAILED"))).toEqual({
             message: "raw",
@@ -18,8 +28,8 @@ describe("formatGraphqlError", () => {
         expect(errors.describe).not.toHaveBeenCalled()
     })
 
-    it("describes the original failure of a resolver and travels its code, kind and params", () => {
-        const errors = mock<ErrorsService>()
+    it("describes the original failure of a resolver and travels its code, kind and params", async () => {
+        const errors = await build()
         const cause = new Error("not found")
         errors.describe.mockReturnValue({
             code: "ITEM_NOT_FOUND",
@@ -37,8 +47,8 @@ describe("formatGraphqlError", () => {
         expect(errors.describe).toHaveBeenCalledWith(cause)
     })
 
-    it("describes a failure that is not a GraphQL error as it is", () => {
-        const errors = mock<ErrorsService>()
+    it("describes a failure that is not a GraphQL error as it is", async () => {
+        const errors = await build()
         const cause = new Error("boom")
         errors.describe.mockReturnValue({ code: "ERRORS_INTERNAL", kind: "internal", status: 500, params: {} })
 
@@ -50,9 +60,9 @@ describe("formatGraphqlError", () => {
         expect(errors.describe).toHaveBeenCalledWith(cause)
     })
 
-    it("leaves out the locations and path a formatted error does not carry", () => {
+    it("leaves out the locations and path a formatted error does not carry", async () => {
         const subject = formatGraphqlError
-        const errors = mock<ErrorsService>()
+        const errors = await build()
         errors.describe.mockReturnValue({ code: "ERRORS_INTERNAL", kind: "internal", status: 500, params: {} })
 
         expect(subject(errors, { message: "raw" }, new GraphQLError("GRAPHQL_PARSE_FAILED"))).toEqual({

package/templates/be/platform/graphql/graphql-depth.policy.spec.ts

@@ -1,3 +1,4 @@
+import { Test } from "@nestjs/testing"
 import { buildSchema, parse, validate } from "graphql"
 import { depthLimitRule } from "./graphql-depth.policy"
 
@@ -12,10 +13,17 @@ const schema = buildSchema(`
     }
 `)
 
-const validateDepth = (source: string, maxDepth = 2) => validate(schema, parse(source), [depthLimitRule(maxDepth)])
+const DEPTH_LIMIT = Symbol("spec.depth-limit")
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({ providers: [{ provide: DEPTH_LIMIT, useValue: 2 }] }).compile()
+    const maxDepth = moduleRef.get<number>(DEPTH_LIMIT)
+    return (source: string) => validate(schema, parse(source), [depthLimitRule(maxDepth)])
+}
 
 describe("depthLimitRule", () => {
-    it("accepts an operation nested exactly to the depth limit", () => {
+    it("accepts an operation nested exactly to the depth limit", async () => {
+        const validateDepth = await build()
         const errors = validateDepth(`
             query {
                 item {
@@ -27,7 +35,8 @@ describe("depthLimitRule", () => {
         expect(errors).toEqual([])
     })
 
-    it("rejects the first selection set deeper than the limit", () => {
+    it("rejects the first selection set deeper than the limit", async () => {
+        const validateDepth = await build()
         const errors = validateDepth(`
             query {
                 item {

package/templates/be/platform/graphql/localize-errors.mapper.spec.ts

@@ -1,12 +1,36 @@
 import type { GraphQLRequestContext, GraphQLRequestContextWillSendResponse, GraphQLResponse } from "@apollo/server"
+import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
 import type { Request } from "express"
 import type { GraphQLFormattedError } from "graphql"
+import { ERRORS_SERVICE } from "@modules/platform/errors"
 import type { ErrorsService } from "@modules/platform/errors"
+import { REQUEST_LOCALE } from "@modules/platform/i18n"
 import type { RequestLocale } from "@modules/platform/i18n"
 import type { GraphqlContext } from "./graphql.contracts"
 import { localizeError, localizeErrorsPlugin } from "./localize-errors.mapper"
 
+const build = async () => {
+    const errorsDouble = mock<ErrorsService>()
+    const localeDouble = mock<RequestLocale>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            { provide: ERRORS_SERVICE, useValue: errorsDouble },
+            { provide: REQUEST_LOCALE, useValue: localeDouble },
+        ],
+    }).compile()
+    return {
+        errors: moduleRef.get<typeof errorsDouble>(ERRORS_SERVICE),
+        requestLocale: moduleRef.get<typeof localeDouble>(REQUEST_LOCALE),
+    }
+}
+
+const errorWith = (extensions?: GraphQLFormattedError["extensions"]): GraphQLFormattedError =>
+    extensions === undefined ? { message: "syntax error" } : { message: "syntax error", extensions }
+
+const acceptLanguage = (language?: string): Request["headers"] =>
+    language === undefined ? {} : { "accept-language": language }
+
 const singleResponse = (errors?: ReadonlyArray<GraphQLFormattedError>): GraphQLResponse =>
     mock<GraphQLResponse>({ body: { kind: "single", singleResult: errors === undefined ? {} : { errors } } })
 
@@ -33,17 +57,17 @@ const sendResponse = async (
 describe("localizeError", () => {
     it.each([undefined, {}, { code: 400 }, { code: null }, { code: false }])(
         "returns an error without a string code unchanged (%p)",
-        (extensions) => {
-            const errors = mock<ErrorsService>()
-            const error: GraphQLFormattedError = { message: "syntax error", extensions }
+        async (extensions) => {
+            const { errors } = await build()
+            const error = errorWith(extensions)
 
             expect(localizeError(errors, "en", error)).toBe(error)
             expect(errors.text).not.toHaveBeenCalled()
         },
     )
 
-    it("replaces a coded error's message with the catalog text and keeps only string and number params", () => {
-        const errors = mock<ErrorsService>()
+    it("replaces a coded error's message with the catalog text and keeps only string and number params", async () => {
+        const { errors } = await build()
         errors.text.mockReturnValue("The item was not found")
         const error: GraphQLFormattedError = {
             message: "ITEM_NOT_FOUND",
@@ -67,8 +91,8 @@ describe("localizeError", () => {
 
     it.each([undefined, null, ["i-1"], "i-1", 42, false])(
         "interpolates no params when extensions.params is %p",
-        (params) => {
-            const errors = mock<ErrorsService>()
+        async (params) => {
+            const { errors } = await build()
             errors.text.mockReturnValue("The item was not found")
             const error: GraphQLFormattedError = {
                 message: "ITEM_NOT_FOUND",
@@ -83,8 +107,7 @@ describe("localizeError", () => {
 
 describe("localizeErrorsPlugin", () => {
     it("forwards the Accept-Language preferences and localizes every coded error in the resolved locale", async () => {
-        const errors = mock<ErrorsService>()
-        const requestLocale = mock<RequestLocale>()
+        const { errors, requestLocale } = await build()
         requestLocale.of.mockReturnValue("vi")
         errors.text.mockReturnValueOnce("localized: not found").mockReturnValueOnce("localized: denied")
         const coded: GraphQLFormattedError = { message: "ITEM_NOT_FOUND", extensions: { code: "ITEM_NOT_FOUND" } }
@@ -115,15 +138,14 @@ describe("localizeErrorsPlugin", () => {
     it.each([undefined, ""])(
         "delegates an absent or empty Accept-Language header to the locale default (%p)",
         async (language) => {
-            const errors = mock<ErrorsService>()
-            const requestLocale = mock<RequestLocale>()
+            const { errors, requestLocale } = await build()
             requestLocale.of.mockReturnValue("vi")
             errors.text.mockReturnValue("localized: not found")
             const coded: GraphQLFormattedError = { message: "ITEM_NOT_FOUND", extensions: { code: "ITEM_NOT_FOUND" } }
 
             const response = singleResponse([coded])
 
-            await sendResponse(errors, requestLocale, requestContext(response, { "accept-language": language }))
+            await sendResponse(errors, requestLocale, requestContext(response, acceptLanguage(language)))
 
             expect(requestLocale.of).toHaveBeenCalledWith(language)
             expect(errors.text).toHaveBeenCalledWith("ITEM_NOT_FOUND", {}, "vi")
@@ -132,10 +154,11 @@ describe("localizeErrorsPlugin", () => {
             ])
         },
     )
+})
 
+describe("localizeErrorsPlugin on a response with nothing to localize", () => {
     it("leaves a response without errors alone", async () => {
-        const errors = mock<ErrorsService>()
-        const requestLocale = mock<RequestLocale>()
+        const { errors, requestLocale } = await build()
 
         const response = singleResponse()
         const body = response.body
@@ -149,14 +172,13 @@ describe("localizeErrorsPlugin", () => {
     })
 
     it("leaves an incremental response alone", async () => {
-        const errors = mock<ErrorsService>()
-        const requestLocale = mock<RequestLocale>()
+        const { errors, requestLocale } = await build()
         const coded: GraphQLFormattedError = { message: "ITEM_NOT_FOUND", extensions: { code: "ITEM_NOT_FOUND" } }
         const response = mock<GraphQLResponse>({
             body: {
                 kind: "incremental",
                 initialResult: { errors: [coded], hasNext: true },
-                subsequentResults: mock<AsyncGenerator>(),
+                subsequentResults: mock<AsyncIterable<never>>(),
             },
         })
         const body = response.body

package/templates/be/skeleton/src/modules/domain/note/note.service.ts

@@ -2,12 +2,11 @@ import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
-import { InjectPrimaryEntityManager, LIST_ROWS_MAX } from "@modules/platform/database"
+import { InjectPrimaryEntityManager, LIST_ROWS_MAX, returnedRows } from "@modules/platform/database"
 import type { CreateNoteParams, Note } from "./note.contracts"
 import { NoteError, NoteErrorCode } from "./errors/note.error"
 import { NoteEntity } from "./persistence/entities/note.entity"
-import { toNote } from "./persistence/note.rows"
-import type { NoteRow } from "./persistence/note.rows"
+import { isNoteRow, toNote } from "./persistence/note.rows"
 import { INSERT_NOTE } from "./persistence/note.sql"
 
 @Injectable()
@@ -29,7 +28,7 @@ export class NoteService {
 
     /** Writes one note in the caller transaction, stamped by the clock, and answers it as stored. */
     async create(params: CreateNoteParams): Promise<Note> {
-        const rows: Array<NoteRow> = await params.manager.query(INSERT_NOTE, [params.body, this.clock.now()])
+        const rows = returnedRows(await params.manager.query(INSERT_NOTE, [params.body, this.clock.now()]), isNoteRow)
         const note = toNote(rows)
         if (note === null) throw new NoteError({ code: NoteErrorCode.NoteMissing })
         return note

package/templates/be/skeleton/src/modules/domain/note/persistence/note.rows.ts

@@ -1,3 +1,4 @@
+import { rowShape } from "@modules/platform/database"
 import type { Note } from "../note.contracts"
 
 /** The row INSERT_NOTE answers. */
@@ -10,6 +11,9 @@ export interface NoteRow {
     created_at: Date
 }
 
+/** Proves one row INSERT_NOTE answered is a NoteRow. */
+export const isNoteRow: (value: unknown) => value is NoteRow = rowShape({ id: "string", body: "string", created_at: "date" })
+
 /** The note of the row an insert answers, or null when it answered none. */
 export const toNote = (rows: ReadonlyArray<NoteRow>): Note | null => {
     const row = rows[0]

package/templates/be/skeleton/src/modules/platform/database/errors/database.error.ts

@@ -5,11 +5,14 @@ import type { ErrorKind } from "@modules/platform/errors"
 export enum DatabaseErrorCode {
     /** A dynamic SQL identifier was not on the list of names its caller allows. */
     IdentifierRejected = "DATABASE_IDENTIFIER_REJECTED",
+    /** A RETURNING statement answered something other than rows of the shape its caller expects. */
+    ReturningRowRejected = "DATABASE_RETURNING_ROW_REJECTED",
 }
 
 /** How each database code travels. */
 export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {
     [DatabaseErrorCode.IdentifierRejected]: "internal",
+    [DatabaseErrorCode.ReturningRowRejected]: "internal",
 }
 
 /** The one error class of the database capability. */

package/templates/be/skeleton/src/modules/platform/database/index.ts

@@ -7,5 +7,6 @@ export { SeedRunnerService } from "./seed-runner.service"
 export type { DatabaseConnectionConfig, DatabaseConnectionOptions } from "./database.options"
 export { LIST_ROWS_MAX, sql } from "./database.sql"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
+export { returnedRows, rowShape } from "./returned-rows.policy"
 export { parsePrimaryDatabaseConfig } from "./primary.config"
 export { InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"

package/templates/be/skeleton/src/modules/platform/database/returned-rows.policy.spec.ts

@@ -0,0 +1,84 @@
+import { Test } from "@nestjs/testing"
+import { DatabaseErrorCode } from "./errors/database.error"
+import { returnedRows, rowShape } from "./returned-rows.policy"
+
+const RETURNED_ROWS_POLICY: unique symbol = Symbol("database.returned-rows")
+
+/** The policy under test, resolved through a testing module as the unit spec standard asks. */
+interface ReturnedRowsPolicy {
+    readonly returnedRows: typeof returnedRows
+    readonly rowShape: typeof rowShape
+}
+
+const AT = new Date("2026-02-03T04:05:06.000Z")
+
+describe("returned rows", () => {
+    let subject: ReturnedRowsPolicy
+
+    beforeEach(async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [{ provide: RETURNED_ROWS_POLICY, useFactory: (): ReturnedRowsPolicy => ({ returnedRows, rowShape }) }],
+        }).compile()
+        subject = moduleRef.get<ReturnedRowsPolicy>(RETURNED_ROWS_POLICY)
+    })
+
+    describe("rowShape", () => {
+        it("admits a row holding every named column with a value of its kind", () => {
+            const isRow = subject.rowShape({ id: "string", hits: "number", open: "boolean", created_at: "date", payload: "json" })
+
+            expect(isRow({ id: "row-1", hits: 2, open: true, created_at: AT, payload: { a: 1 }, extra: "kept" })).toBe(true)
+        })
+
+        it("admits null only for a kind that ends in ?", () => {
+            const isRow = subject.rowShape({ note: "string?", hits: "number?", open: "boolean?", seen_at: "date?" })
+
+            expect(isRow({ note: null, hits: null, open: null, seen_at: null })).toBe(true)
+            expect(isRow({ note: "n", hits: 1, open: false, seen_at: AT })).toBe(true)
+            expect(subject.rowShape({ note: "string" })({ note: null })).toBe(false)
+            expect(subject.rowShape({ payload: "json" })({ payload: null })).toBe(true)
+        })
+
+        it.each([
+            ["a column the statement did not return", { hits: 1 }],
+            ["a value of another kind", { id: 7, hits: 1 }],
+            ["a number returned as text", { id: "row-1", hits: "1" }],
+            ["a value that is not a row", "row-1"],
+            ["null", null],
+        ])("refuses %s", (_case, value) => {
+            expect(subject.rowShape({ id: "string", hits: "number" })(value)).toBe(false)
+        })
+
+        it("refuses a json column the statement did not return", () => {
+            expect(subject.rowShape({ payload: "json" })({})).toBe(false)
+        })
+    })
+
+    describe("returnedRows", () => {
+        it("answers every row, typed by its guard, in the order the statement returned them", () => {
+            const rows = subject.returnedRows([{ id: "a" }, { id: "b" }], subject.rowShape({ id: "string" }))
+
+            expect(rows.map((row) => row.id)).toEqual(["a", "b"])
+        })
+
+        it("answers no rows for a statement that returned none", () => {
+            expect(subject.returnedRows([], subject.rowShape({ id: "string" }))).toEqual([])
+        })
+
+        it("refuses a row of another shape instead of reading it", () => {
+            expect(() => subject.returnedRows([{ id: "a" }, { id: 2 }], subject.rowShape({ id: "string" }))).toThrow(
+                expect.objectContaining({ code: DatabaseErrorCode.ReturningRowRejected }),
+            )
+        })
+
+        it("refuses a result that is not a list of rows, such as the [rows, count] of a bare UPDATE", () => {
+            const isRow = subject.rowShape({ id: "string" })
+
+            expect(() => subject.returnedRows({ id: "a" }, isRow)).toThrow(
+                expect.objectContaining({ code: DatabaseErrorCode.ReturningRowRejected }),
+            )
+            expect(() => subject.returnedRows([[{ id: "a" }], 1], isRow)).toThrow(
+                expect.objectContaining({ code: DatabaseErrorCode.ReturningRowRejected }),
+            )
+        })
+    })
+})