@starci/hfs 4.0.7 → 4.0.9

package/templates/be/skeleton/apps/__app__/src/__app__.options.ts

@@ -1,5 +1,6 @@
 import type { HttpSecurityOptions } from "@modules/platform/http-security"
 import type { ServerOptions } from "@modules/platform/config"
+import type { DatabaseConnectionConfig } from "@modules/platform/database"
 
 /** Everything the {{app}} app needs from its environment, parsed once by `main.ts` and handed to `AppModule.register`. */
 export interface {{appPascal}}Options {
@@ -7,4 +8,6 @@ export interface {{appPascal}}Options {
     readonly server: ServerOptions
     /** The origin allowlist and rate limits. */
     readonly httpSecurity: HttpSecurityOptions
+    /** The primary database connection. */
+    readonly database: DatabaseConnectionConfig
 }

package/templates/be/skeleton/apps/__app__/src/app.module.ts

@@ -1,12 +1,14 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { APP_FILTER, APP_GUARD } from "@nestjs/core"
-import { SystemHealthHttpModule } from "@features/system-health"
+import { SystemHealthHttpModule } from "@features/api/system-health"
 import { AuthGuard, IDENTITY_ERROR_KINDS, IDENTITY_MESSAGES, IdentityModule } from "@modules/domain/identity"
 import { LivenessModule } from "@modules/domain/liveness"
+import { NOTE_ERROR_KINDS, NoteModule, noteEntities, noteMigrations } from "@modules/domain/note"
 import { ClockModule } from "@modules/platform/clock"
 import { CONFIG_ERROR_KINDS } from "@modules/platform/config"
 import { CqrsModule } from "@modules/platform/cqrs"
+import { DATABASE_ERROR_KINDS, DatabaseModule } from "@modules/platform/database"
 import { ERRORS_MESSAGES, ErrorsFilter, ErrorsModule } from "@modules/platform/errors"
 import {
     HTTP_SECURITY_ERROR_KINDS,
@@ -35,12 +37,23 @@ export class AppModule {
                 }),
                 ErrorsModule.register({
                     isGlobal: true,
-                    kinds: [CONFIG_ERROR_KINDS, HTTP_SECURITY_ERROR_KINDS, IDENTITY_ERROR_KINDS],
+                    kinds: [
+                        CONFIG_ERROR_KINDS,
+                        DATABASE_ERROR_KINDS,
+                        HTTP_SECURITY_ERROR_KINDS,
+                        IDENTITY_ERROR_KINDS,
+                        NOTE_ERROR_KINDS,
+                    ],
                 }),
                 CqrsModule.register({ isGlobal: true }),
                 HttpSecurityModule.register({ isGlobal: true, ...options.httpSecurity }),
+                DatabaseModule.register({
+                    isGlobal: true,
+                    connections: [{ ...options.database, entities: noteEntities, migrations: noteMigrations }],
+                }),
                 IdentityModule.register({ isGlobal: true }),
                 LivenessModule.register({ isGlobal: true }),
+                NoteModule.register({ isGlobal: true }),
                 SystemHealthHttpModule,
             ],
             providers: [

package/templates/be/skeleton/apps/__app__/src/main.ts

@@ -1,6 +1,7 @@
 import { NestFactory } from "@nestjs/core"
 import { SystemClockService } from "@modules/platform/clock"
 import { EnvSource, parseServerConfig } from "@modules/platform/config"
+import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
 import { parseHttpSecurityConfig } from "@modules/platform/http-security"
 import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
 import { AppModule } from "./app.module"
@@ -9,18 +10,9 @@ import type { {{appPascal}}Options } from "./{{app}}.options"
 /** Reads the environment once, composes the app from the parsed options and serves until a shutdown signal. */
 const bootstrap = async (): Promise<void> => {
     const env = EnvSource.fromProcess()
-    const options: {{appPascal}}Options = { server: parseServerConfig(env), httpSecurity: parseHttpSecurityConfig(env) }
-    const app = await NestFactory.create(AppModule.register(options))
-    app.enableCors({ origin: [...options.httpSecurity.allowedOrigins] })
-    app.enableShutdownHooks()
-    await app.listen(options.server.port)
-    createJsonLogger(new SystemClockService()).info(LoggingLogEvent.ServerStarted, {
-        service: "{{app}}",
-        port: options.server.port,
-    })
-}
-
-bootstrap().catch((error: unknown) => {
-    createJsonLogger(new SystemClockService()).error(LoggingLogEvent.StartupFailed, error, { service: "{{app}}" })
-    process.exitCode = 1
-})
+    const options: {{appPascal}}Options = {
+        server: parseServerConfig(env),
+        httpSecurity: parseHttpSecurityConfig(env),
+        database: parsePrimaryDatabaseConfig(env),
+    }
+{{> be/common/main-listen.ts.partial}}

package/templates/be/skeleton/apps/cli/src/app.module.ts

@@ -0,0 +1,30 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { CliModule } from "@features/cli"
+import { ClockModule } from "@modules/platform/clock"
+import { DatabaseModule } from "@modules/platform/database"
+import { LoggingModule } from "@modules/platform/logging"
+import type { CliAppOptions } from "./cli.options"
+
+@Module({})
+/**
+ * The composition root of the cli: the clock and the logger every command logs through, the database capability over every
+ * connection with its entities and migrations, and the cli feature root.
+ */
+export class AppModule {
+    /** Builds the cli from its parsed options. */
+    static register(options: CliAppOptions): DynamicModule {
+        return {
+            module: AppModule,
+            imports: [
+                ClockModule.register({ isGlobal: true }),
+                LoggingModule.register({ isGlobal: true }),
+                DatabaseModule.register({
+                    isGlobal: true,
+                    connections: options.connections,
+                }),
+                CliModule,
+            ],
+        }
+    }
+}

package/templates/be/skeleton/apps/cli/src/cli.options.ts

@@ -0,0 +1,22 @@
+import { noteEntities, noteMigrations } from "@modules/domain/note"
+import type { EnvSource } from "@modules/platform/config"
+import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
+import type { DatabaseConnectionOptions } from "@modules/platform/database"
+
+/** Everything the cli app needs from its environment: every connection with the entities and migrations of its owners. */
+export interface CliAppOptions {
+    /** The connections the migrate and seed commands run on, in the order they run them. */
+    readonly connections: ReadonlyArray<DatabaseConnectionOptions>
+}
+
+/** The primary database: the notes. */
+export const primaryConnectionOf = (env: EnvSource): DatabaseConnectionOptions => ({
+    ...parsePrimaryDatabaseConfig(env),
+    entities: noteEntities,
+    migrations: noteMigrations,
+})
+
+/** Parses the cli options from the environment: one entry per connection, each built by its own function above. */
+export const parseCliAppOptions = (env: EnvSource): CliAppOptions => ({
+    connections: [primaryConnectionOf(env)],
+})

package/templates/be/skeleton/apps/cli/src/main.ts

@@ -0,0 +1,24 @@
+import "reflect-metadata"
+import { CommandFactory } from "nest-commander"
+import { SystemClockService } from "@modules/platform/clock"
+import { EnvSource } from "@modules/platform/config"
+import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
+import { AppModule } from "./app.module"
+import { parseCliAppOptions } from "./cli.options"
+
+/** The command line of the back end: reads the environment once and runs the command its arguments name (`cli migrate run`). */
+async function bootstrap(): Promise<void> {
+    const logger = createJsonLogger(new SystemClockService())
+    await CommandFactory.run(AppModule.register(parseCliAppOptions(EnvSource.fromProcess())), {
+        logger: false,
+        errorHandler: (error: Error) => {
+            logger.error(LoggingLogEvent.StartupFailed, error, { service: "cli" })
+            process.exit(1)
+        },
+    })
+}
+
+bootstrap().catch((error: unknown) => {
+    createJsonLogger(new SystemClockService()).error(LoggingLogEvent.StartupFailed, error, { service: "cli" })
+    process.exit(1)
+})

package/templates/be/skeleton/src/features/cli/cli.module.ts

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common"
+import { MigrateModule } from "./migrate/migrate.module"
+import { SeedModule } from "./seed/seed.module"
+
+@Module({ imports: [MigrateModule, SeedModule] })
+/** The cli feature root: every command group of the back end, compiled only into apps/cli. */
+export class CliModule {}

package/templates/be/skeleton/src/features/cli/index.ts

@@ -0,0 +1 @@
+export { CliModule } from "./cli.module"

package/templates/be/skeleton/src/features/cli/migrate/migrate.cli.spec.ts

@@ -0,0 +1,17 @@
+import { Test } from "@nestjs/testing"
+import { MigrateCli } from "./migrate.cli"
+
+describe("MigrateCli", () => {
+    it("shows the help of the group, and runs nothing else, when no sub-command is named", async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [MigrateCli],
+        }).compile()
+        const group = moduleRef.get(MigrateCli)
+        const help = jest.fn()
+        Object.defineProperty(group, "command", { value: { help } })
+
+        await expect(group.run()).resolves.toBeUndefined()
+
+        expect(help).toHaveBeenCalledTimes(1)
+    })
+})

package/templates/be/skeleton/src/features/cli/migrate/migrate.cli.ts

@@ -0,0 +1,15 @@
+import { Command, CommandRunner } from "nest-commander"
+import { RunCli } from "./subs/run.cli"
+
+@Command({
+    name: "migrate",
+    description: "The schema of every connection",
+    subCommands: [RunCli],
+})
+/** `cli migrate`: the migration group; its commands are the sub-commands (`cli migrate run`). */
+export class MigrateCli extends CommandRunner {
+    /** Without a sub-command the group shows its help. */
+    async run(): Promise<void> {
+        this.command.help()
+    }
+}

package/templates/be/skeleton/src/features/cli/migrate/migrate.module.ts

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common"
+import { MigrateCli } from "./migrate.cli"
+import { RunCli } from "./subs/run.cli"
+
+@Module({ providers: [MigrateCli, RunCli] })
+/** The migrate group: its command and its sub-commands; the connections come from the database capability. */
+export class MigrateModule {}

package/templates/be/skeleton/src/features/cli/migrate/subs/run.cli.spec.ts

@@ -0,0 +1,17 @@
+import { mock } from "@starci/jest-preset"
+import { Test } from "@nestjs/testing"
+import { MigrationRunnerService } from "@modules/platform/database"
+import { RunCli } from "./run.cli"
+
+describe("RunCli", () => {
+    it("delegates the migration run to the migration runner once", async () => {
+        const migrations = mock<MigrationRunnerService>()
+        const moduleRef = await Test.createTestingModule({
+            providers: [RunCli, { provide: MigrationRunnerService, useValue: migrations }],
+        }).compile()
+
+        await expect(moduleRef.get(RunCli).run()).resolves.toBeUndefined()
+
+        expect(migrations.run).toHaveBeenCalledTimes(1)
+    })
+})

package/templates/be/skeleton/src/features/cli/migrate/subs/run.cli.ts

@@ -0,0 +1,18 @@
+import { CommandRunner, SubCommand } from "nest-commander"
+import { MigrationRunnerService } from "@modules/platform/database"
+
+@SubCommand({
+    name: "run",
+    description: "Apply the pending migrations of every connection",
+})
+/** `cli migrate run`: migrates every connection of the back end, in order, and logs what it applied. */
+export class RunCli extends CommandRunner {
+    constructor(private readonly migrations: MigrationRunnerService) {
+        super()
+    }
+
+    /** Runs the migrations of every connection and logs the applied names. */
+    async run(): Promise<void> {
+        await this.migrations.run()
+    }
+}

package/templates/be/skeleton/src/features/cli/seed/seed.cli.spec.ts

@@ -0,0 +1,17 @@
+import { Test } from "@nestjs/testing"
+import { SeedCli } from "./seed.cli"
+
+describe("SeedCli", () => {
+    it("shows the help of the group, and runs nothing else, when no sub-command is named", async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [SeedCli],
+        }).compile()
+        const group = moduleRef.get(SeedCli)
+        const help = jest.fn()
+        Object.defineProperty(group, "command", { value: { help } })
+
+        await expect(group.run()).resolves.toBeUndefined()
+
+        expect(help).toHaveBeenCalledTimes(1)
+    })
+})

package/templates/be/skeleton/src/features/cli/seed/seed.cli.ts

@@ -0,0 +1,15 @@
+import { Command, CommandRunner } from "nest-commander"
+import { RunSeedsCli } from "./subs/run.cli"
+
+@Command({
+    name: "seed",
+    description: "The seed data of every connection",
+    subCommands: [RunSeedsCli],
+})
+/** `cli seed`: the seed group; its commands are the sub-commands (`cli seed run`). */
+export class SeedCli extends CommandRunner {
+    /** Without a sub-command the group shows its help. */
+    async run(): Promise<void> {
+        this.command.help()
+    }
+}

package/templates/be/skeleton/src/features/cli/seed/seed.module.ts

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common"
+import { SeedCli } from "./seed.cli"
+import { RunSeedsCli } from "./subs/run.cli"
+
+@Module({ providers: [SeedCli, RunSeedsCli] })
+/** The seed group: its command and its sub-commands; the connections and the seed file reader come from the database capability. */
+export class SeedModule {}

package/templates/be/skeleton/src/features/cli/seed/subs/run.cli.spec.ts

@@ -0,0 +1,33 @@
+import { mock } from "@starci/jest-preset"
+import { Test } from "@nestjs/testing"
+import { SeedRunnerService } from "@modules/platform/database"
+import { RunSeedsCli } from "./run.cli"
+
+const build = async (seeds: SeedRunnerService) => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [RunSeedsCli, { provide: SeedRunnerService, useValue: seeds }],
+    }).compile()
+    return moduleRef.get(RunSeedsCli)
+}
+
+describe("RunSeedsCli", () => {
+    it("delegates the seed run of the named environment to the seed runner once", async () => {
+        const seeds = mock<SeedRunnerService>()
+        const command = await build(seeds)
+
+        await command.run([], { env: "staging" })
+
+        expect(seeds.run).toHaveBeenCalledWith("staging")
+        expect(seeds.run).toHaveBeenCalledTimes(1)
+    })
+
+    it("delegates with no environment when none is named, and takes --env as given", async () => {
+        const seeds = mock<SeedRunnerService>()
+        const command = await build(seeds)
+
+        await command.run([])
+
+        expect(seeds.run).toHaveBeenCalledWith(undefined)
+        expect(command.parseEnv("staging")).toBe("staging")
+    })
+})

package/templates/be/skeleton/src/features/cli/seed/subs/run.cli.ts

@@ -0,0 +1,34 @@
+import { CommandRunner, Option, SubCommand } from "nest-commander"
+import { DEFAULT_SEED_ENV, SeedRunnerService } from "@modules/platform/database"
+
+/** The options of `cli seed run`. */
+export interface SeedRunOptions {
+    /** The stack environment whose `.starcistacks/<env>/seeds` run. */
+    readonly env?: string
+}
+
+@SubCommand({
+    name: "run",
+    description: "Run every seed file of a stack environment on the connection it names",
+})
+/** `cli seed run [--env <name>]`: seeds every connection of the back end from `.starcistacks/<env>/seeds` and logs what it ran. */
+export class RunSeedsCli extends CommandRunner {
+    constructor(private readonly seeds: SeedRunnerService) {
+        super()
+    }
+
+    /** `--env <name>`: the stack environment whose seeds run. */
+    @Option({
+        flags: "--env <name>",
+        description: "The stack environment whose seeds run",
+        defaultValue: DEFAULT_SEED_ENV,
+    })
+    parseEnv(value: string): string {
+        return value
+    }
+
+    /** Reads the seed files of the environment, runs them on their connections and logs the report. */
+    async run(_passed: Array<string>, options?: SeedRunOptions): Promise<void> {
+        await this.seeds.run(options?.env)
+    }
+}

package/templates/be/skeleton/src/modules/domain/identity/admission.policy.spec.ts

@@ -0,0 +1,13 @@
+import { admit } from "./admission.policy"
+import { IdentityErrorCode } from "./errors/identity.error"
+import { PublicReason } from "./identity.contracts"
+
+describe("admit", () => {
+    it("admits a door that states why it is public", () => {
+        expect(admit({ reason: PublicReason.Health })).toSucceedWith(PublicReason.Health)
+    })
+
+    it("refuses a door that is not public", () => {
+        expect(admit(undefined)).toBeRefused(IdentityErrorCode.Unauthenticated)
+    })
+})

package/templates/be/skeleton/src/modules/domain/identity/auth.guard.spec.ts

@@ -0,0 +1,40 @@
+import type { ExecutionContext } from "@nestjs/common"
+import { Reflector } from "@nestjs/core"
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { AuthGuard } from "./auth.guard"
+import { IdentityErrorCode } from "./errors/identity.error"
+import type { PublicMetadata } from "./identity.contracts"
+import { PublicReason } from "./identity.contracts"
+
+const build = async (metadata: PublicMetadata | undefined) => {
+    const reflector = mock<Reflector>()
+    reflector.getAllAndOverride.mockReturnValue(metadata)
+    const moduleRef = await Test.createTestingModule({
+        providers: [AuthGuard, { provide: Reflector, useValue: reflector }],
+    }).compile()
+    return { guard: moduleRef.get(AuthGuard), reflector }
+}
+
+const contextOf = () => {
+    const context = mock<ExecutionContext>()
+    context.getHandler.mockReturnValue(() => undefined)
+    context.getClass.mockReturnValue(class Door {})
+    return context
+}
+
+describe("AuthGuard", () => {
+    it("lets a door through when it states why it is public", async () => {
+        const { guard } = await build({ reason: PublicReason.Health })
+
+        expect(guard.canActivate(contextOf())).toBe(true)
+    })
+
+    it("refuses every door that is not public", async () => {
+        const { guard } = await build(undefined)
+
+        expect(() => guard.canActivate(contextOf())).toThrow(
+            expect.objectContaining({ code: IdentityErrorCode.Unauthenticated }),
+        )
+    })
+})

package/templates/be/skeleton/src/modules/domain/identity/messages/identity.messages.ts

@@ -3,7 +3,7 @@ import type { MessageBundle } from "@modules/platform/i18n"
 /** Display text of the identity codes, Vietnamese and English. */
 export const IDENTITY_MESSAGES: MessageBundle = {
     vi: {
-        "errors.IDENTITY_UNAUTHENTICATED": "Bạn cần đăng nhập để thực hiện thao tác này.",
+        "errors.IDENTITY_UNAUTHENTICATED": "B\u1ea1n c\u1ea7n \u0111\u0103ng nh\u1eadp \u0111\u1ec3 th\u1ef1c hi\u1ec7n thao t\u00e1c n\u00e0y.",
     },
     en: {
         "errors.IDENTITY_UNAUTHENTICATED": "You need to sign in to do this.",

package/templates/be/skeleton/src/modules/domain/note/errors/note.error.ts

@@ -0,0 +1,16 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the note capability. */
+export enum NoteErrorCode {
+    /** The write did not answer the note it should have stored; a defect, never a business refusal. */
+    NoteMissing = "NOTE_MISSING",
+}
+
+/** How each note code travels. */
+export const NOTE_ERROR_KINDS: Record<NoteErrorCode, ErrorKind> = {
+    [NoteErrorCode.NoteMissing]: "internal",
+}
+
+/** The one error class of the note capability. */
+export class NoteError extends DomainError<NoteErrorCode> {}

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

@@ -0,0 +1,3 @@
+export { noteEntities, noteMigrations } from "./persistence/connection"
+export { NoteModule } from "./note.module"
+export { NOTE_ERROR_KINDS } from "./errors/note.error"

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

@@ -0,0 +1,19 @@
+import type { EntityManager } from "typeorm"
+
+/** One note as the doors answer it. */
+export interface Note {
+    /** The note id. */
+    readonly id: string
+    /** The text of the note. */
+    readonly body: string
+    /** When the note was written, as an ISO 8601 instant. */
+    readonly createdAt: string
+}
+
+/** What writing a note needs; the write joins the caller transaction. */
+export interface CreateNoteParams {
+    /** The transaction manager of the caller. */
+    readonly manager: EntityManager
+    /** The text of the note. */
+    readonly body: string
+}

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

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { NoteService } from "./note.service"
+
+/** Token of the NoteService of this capability, for the capabilities that use it. */
+export const NOTE_SERVICE: unique symbol = Symbol("domain.note.service")
+
+/** Injects the NoteService. Parameter type: NoteService. */
+export const InjectNoteService = (): TypedParameterDecorator<NoteService> => injector<NoteService>(NOTE_SERVICE)

package/templates/be/skeleton/src/modules/domain/note/note.module-definition.ts

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

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

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./note.module-definition"
+import { NOTE_SERVICE } from "./note.decorators"
+import { NoteService } from "./note.service"
+
+@Module({})
+/** The note capability over the primary database. */
+export class NoteModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), NoteService, { provide: NOTE_SERVICE, useExisting: NoteService }],
+            exports: [NOTE_SERVICE],
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+/** The note capability takes no options; the empty record keeps `isGlobal` assignable through the configurable module. */
+export type NoteOptions = Record<never, never>

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

@@ -0,0 +1,76 @@
+import { FakeClock, mockEntityManager } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import { Test } from "@nestjs/testing"
+import { CLOCK } from "@modules/platform/clock"
+import { LIST_ROWS_MAX, PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { NoteErrorCode } from "./errors/note.error"
+import { NoteService } from "./note.service"
+import { NoteEntity } from "./persistence/entities/note.entity"
+import { INSERT_NOTE } from "./persistence/note.sql"
+
+const NOW = "2026-01-01T00:00:00.000Z"
+
+const build = async (entityManager: MockEntityManager) => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            NoteService,
+            { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },
+            { provide: CLOCK, useValue: new FakeClock(NOW) },
+        ],
+    }).compile()
+    return moduleRef.get(NoteService)
+}
+
+describe("NoteService", () => {
+    describe("list", () => {
+        it("returns the newest notes first, capped at the list maximum", async () => {
+            const em = mockEntityManager({
+                find: [
+                    NoteEntity,
+                    [
+                        { id: "n-2", body: "second", createdAt: new Date("2026-01-02T00:00:00.000Z") },
+                        { id: "n-1", body: "first", createdAt: new Date("2026-01-01T00:00:00.000Z") },
+                    ],
+                ],
+            })
+            const service = await build(em)
+
+            const notes = await service.list()
+
+            expect(notes).toEqual([
+                { id: "n-2", body: "second", createdAt: "2026-01-02T00:00:00.000Z" },
+                { id: "n-1", body: "first", createdAt: "2026-01-01T00:00:00.000Z" },
+            ])
+            expect(em.find).toHaveBeenCalledWith(NoteEntity, { order: { createdAt: "DESC" }, take: LIST_ROWS_MAX })
+        })
+
+        it("returns no note when none was written", async () => {
+            const service = await build(mockEntityManager({ find: [NoteEntity, []] }))
+
+            await expect(service.list()).resolves.toEqual([])
+        })
+    })
+
+    describe("create", () => {
+        it("writes through the caller transaction manager, stamped by the clock, and returns the stored note", async () => {
+            const manager = mockEntityManager({
+                query: [INSERT_NOTE, [{ id: "n-1", body: "hello", created_at: new Date(NOW) }]],
+            })
+            const service = await build(mockEntityManager())
+
+            const note = await service.create({ manager, body: "hello" })
+
+            expect(note).toEqual({ id: "n-1", body: "hello", createdAt: NOW })
+            expect(manager.query).toHaveBeenCalledWith(INSERT_NOTE, ["hello", new Date(NOW)])
+        })
+
+        it("throws the note missing error when the insert answers no row", async () => {
+            const manager = mockEntityManager({ query: [INSERT_NOTE, []] })
+            const service = await build(mockEntityManager())
+
+            await expect(service.create({ manager, body: "hello" })).rejects.toMatchObject({
+                code: NoteErrorCode.NoteMissing,
+            })
+        })
+    })
+})

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

@@ -0,0 +1,37 @@
+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 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 { INSERT_NOTE } from "./persistence/note.sql"
+
+@Injectable()
+/** The notes of the app over the primary database: written in the caller transaction, read newest first. */
+export class NoteService {
+    constructor(
+        @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
+        @InjectClock() private readonly clock: Clock,
+    ) {}
+
+    /** The newest notes, capped at the list maximum. */
+    async list(): Promise<Array<Note>> {
+        const rows = await this.entityManager.find(NoteEntity, {
+            order: { createdAt: "DESC" },
+            take: LIST_ROWS_MAX,
+        })
+        return rows.map((row) => ({ id: row.id, body: row.body, createdAt: row.createdAt.toISOString() }))
+    }
+
+    /** 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 note = toNote(rows)
+        if (note === null) throw new NoteError({ code: NoteErrorCode.NoteMissing })
+        return note
+    }
+}