@starci/hfs 4.2.13 → 4.2.15

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

@@ -0,0 +1,114 @@
+import type { GraphQLRequestContext, GraphQLRequestContextWillSendResponse, GraphQLResponse } from "@apollo/server"
+import { mock } from "@starci/jest-preset"
+import type { Request } from "express"
+import type { GraphQLFormattedError } from "graphql"
+import type { ErrorsService } from "@modules/platform/errors"
+import type { RequestLocale } from "@modules/platform/i18n"
+import type { GraphqlContext } from "./graphql.contracts"
+import { localizeError, localizeErrorsPlugin } from "./localize-errors.mapper"
+
+const singleResponse = (errors?: ReadonlyArray<GraphQLFormattedError>): GraphQLResponse =>
+    mock<GraphQLResponse>({ body: { kind: "single", singleResult: { errors } } })
+
+const requestContext = (
+    response: GraphQLResponse,
+    headers: Request["headers"],
+): GraphQLRequestContextWillSendResponse<GraphqlContext> =>
+    mock<GraphQLRequestContextWillSendResponse<GraphqlContext>>({
+        contextValue: { req: mock<Request>({ headers }), res: mock<GraphqlContext["res"]>() },
+        response,
+    })
+
+const sendResponse = async (
+    errors: ErrorsService,
+    requestLocale: RequestLocale,
+    context: GraphQLRequestContextWillSendResponse<GraphqlContext>,
+): Promise<void> => {
+    const listener = await localizeErrorsPlugin(errors, requestLocale).requestDidStart?.(
+        mock<GraphQLRequestContext<GraphqlContext>>(),
+    )
+    await listener?.willSendResponse?.(context)
+}
+
+describe("localizeError", () => {
+    it("returns an error without a string code unchanged", () => {
+        const errors = mock<ErrorsService>()
+        const error: GraphQLFormattedError = { message: "syntax error", extensions: { kind: "invalid" } }
+
+        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>()
+        errors.text.mockReturnValue("The item was not found")
+        const error: GraphQLFormattedError = {
+            message: "ITEM_NOT_FOUND",
+            extensions: { code: "ITEM_NOT_FOUND", params: { id: "i-1", retries: 2, transient: false } },
+        }
+
+        expect(localizeError(errors, "en", error)).toEqual({ ...error, message: "The item was not found" })
+        expect(errors.text).toHaveBeenCalledWith("ITEM_NOT_FOUND", { id: "i-1", retries: 2 }, "en")
+    })
+
+    it.each([undefined, null, ["i-1"], "i-1"])("interpolates no params when extensions.params is %p", (params) => {
+        const errors = mock<ErrorsService>()
+        errors.text.mockReturnValue("The item was not found")
+        const error: GraphQLFormattedError = {
+            message: "ITEM_NOT_FOUND",
+            extensions: { code: "ITEM_NOT_FOUND", params },
+        }
+
+        expect(localizeError(errors, "en", error).message).toBe("The item was not found")
+        expect(errors.text).toHaveBeenCalledWith("ITEM_NOT_FOUND", {}, "en")
+    })
+})
+
+describe("localizeErrorsPlugin", () => {
+    it("localizes a coded error in the language the x-locale header declares", async () => {
+        const errors = mock<ErrorsService>()
+        const requestLocale = mock<RequestLocale>()
+        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])
+
+        const context = requestContext(response, { "x-locale": "vi", "accept-language": "en" })
+
+        await sendResponse(errors, requestLocale, context)
+
+        expect(requestLocale.of).toHaveBeenCalledWith("vi")
+        expect(response.body.kind === "single" && response.body.singleResult.errors).toEqual([
+            { ...coded, message: "localized: not found" },
+        ])
+    })
+
+    it.each([{}, { "x-locale": "" }])(
+        "falls back to Accept-Language when the x-locale header is absent or empty (%p)",
+        async (declared) => {
+            const errors = mock<ErrorsService>()
+            const requestLocale = mock<RequestLocale>()
+            requestLocale.of.mockReturnValue("en")
+            errors.text.mockReturnValue("The item was not found")
+            const coded: GraphQLFormattedError = { message: "ITEM_NOT_FOUND", extensions: { code: "ITEM_NOT_FOUND" } }
+
+            await sendResponse(
+                errors,
+                requestLocale,
+                requestContext(singleResponse([coded]), { ...declared, "accept-language": "en" }),
+            )
+
+            expect(requestLocale.of).toHaveBeenCalledWith("en")
+        },
+    )
+
+    it("leaves a response without errors alone", async () => {
+        const errors = mock<ErrorsService>()
+        const requestLocale = mock<RequestLocale>()
+
+        await sendResponse(errors, requestLocale, requestContext(singleResponse(), { "accept-language": "en" }))
+
+        expect(requestLocale.of).not.toHaveBeenCalled()
+        expect(errors.text).not.toHaveBeenCalled()
+    })
+})

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

@@ -0,0 +1,51 @@
+import type { ApolloServerPlugin } from "@apollo/server"
+import type { GraphQLFormattedError } from "graphql"
+import type { ErrorParams, ErrorsService } from "@modules/platform/errors"
+import type { Locale, RequestLocale } from "@modules/platform/i18n"
+import type { GraphqlContext } from "./graphql.contracts"
+
+/** The interpolation params of an error: the string and number entries of its `extensions.params` record. */
+const paramsOf = (value: unknown): ErrorParams => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return {}
+    const params: Record<string, string | number> = {}
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry === "string" || typeof entry === "number") params[key] = entry
+    }
+    return params
+}
+
+/** The language a request asks for: the `x-locale` header the front end's locale link writes, else Accept-Language. */
+const requestedLocale = (context: GraphqlContext): string | undefined => {
+    const declared = context.req.headers["x-locale"]
+    return typeof declared === "string" && declared !== "" ? declared : context.req.headers["accept-language"]
+}
+
+/** Replaces the message of an error carrying a code with the catalog text of that code in `locale`; other errors pass unchanged. */
+export const localizeError = (
+    errors: ErrorsService,
+    locale: Locale,
+    error: GraphQLFormattedError,
+): GraphQLFormattedError => {
+    const code = error.extensions?.code
+    if (typeof code !== "string") return error
+    return { ...error, message: errors.text(code, paramsOf(error.extensions?.params), locale) }
+}
+
+/** An Apollo plugin that localizes every coded error of a response in the language of the request. */
+export const localizeErrorsPlugin = (
+    errors: ErrorsService,
+    requestLocale: RequestLocale,
+): ApolloServerPlugin<GraphqlContext> => ({
+    requestDidStart: () =>
+        Promise.resolve({
+            willSendResponse: ({ contextValue, response }) => {
+                if (response.body.kind === "single" && response.body.singleResult.errors) {
+                    const locale = requestLocale.of(requestedLocale(contextValue))
+                    response.body.singleResult.errors = response.body.singleResult.errors.map((error) =>
+                        localizeError(errors, locale, error),
+                    )
+                }
+                return Promise.resolve()
+            },
+        }),
+})

package/templates/be/skeleton/src/modules/platform/errors/errors.filter.spec.ts

@@ -12,6 +12,17 @@ const build = () => {
 }
 
 describe("ErrorsFilter", () => {
+    it("hands a failure in a GraphQL context back untouched for the GraphQL error formatter", () => {
+        const { filter, errors } = build()
+        const failure = new Error("resolver failed")
+        const host = mock<ArgumentsHost>()
+        host.getType.mockReturnValue("graphql")
+
+        expect(filter.catch(failure, host)).toBe(failure)
+        expect(errors.describe).not.toHaveBeenCalled()
+        expect(host.switchToHttp).not.toHaveBeenCalled()
+    })
+
     it("writes a localized description and its status to an HTTP response", () => {
         const { filter, errors, requestLocale } = build()
         const failure = new Error("note missing")

package/templates/be/skeleton/src/modules/platform/errors/errors.filter.ts

@@ -7,15 +7,19 @@ import { InjectErrorsService } from "./errors.decorators"
 import type { ErrorsService } from "./errors.service"
 
 @Catch()
-/** The one exception filter of an app: answers `{ code, kind, message, params }` with the status of the kind. */
+/**
+ * The one REST exception filter of an app: answers `{ code, kind, message, params }` with the status of the kind. In a GraphQL
+ * context it hands the failure back untouched, so the GraphQL error formatter (platform/graphql) answers it.
+ */
 export class ErrorsFilter implements ExceptionFilter {
     constructor(
         @InjectErrorsService() private readonly errors: ErrorsService,
         @InjectRequestLocale() private readonly requestLocale: RequestLocale,
     ) {}
 
-    /** Writes the description of `exception` on the HTTP response. */
-    catch(exception: unknown, host: ArgumentsHost): void {
+    /** Writes the description of `exception` on the HTTP response, or returns it unchanged for GraphQL. */
+    catch(exception: unknown, host: ArgumentsHost): unknown {
+        if (host.getType<string>() === "graphql") return exception
         const http = host.switchToHttp()
         const request = http.getRequest<Request>()
         const description = this.errors.describe(exception)
@@ -28,5 +32,6 @@ export class ErrorsFilter implements ExceptionFilter {
                 message: this.errors.text(description.code, description.params, locale),
                 params: description.params,
             })
+        return undefined
     }
 }

package/templates/be/skeleton/src/modules/platform/http-security/execution-request.mapper.spec.ts

@@ -4,13 +4,25 @@ import { mock } from "@starci/jest-preset"
 import { requestOf } from "./execution-request.mapper"
 
 describe("requestOf", () => {
-    it("reads the HTTP request behind an execution context", () => {
+    it("reads the HTTP request behind an HTTP execution context", () => {
         const request = mock<Request>()
         const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
         http.getRequest.mockReturnValue(request)
         const context = mock<ExecutionContext>()
+        context.getType.mockReturnValue("http")
         context.switchToHttp.mockReturnValue(http)
 
         expect(requestOf(context)).toBe(request)
+        expect(context.getArgs).not.toHaveBeenCalled()
+    })
+
+    it("reads the request of the GraphQL context behind a resolver's execution context", () => {
+        const request = mock<Request>()
+        const context = mock<ExecutionContext>()
+        context.getType.mockReturnValue("graphql")
+        context.getArgs.mockReturnValue([undefined, {}, { req: request }, undefined])
+
+        expect(requestOf(context)).toBe(request)
+        expect(context.switchToHttp).not.toHaveBeenCalled()
     })
 })

package/templates/be/skeleton/src/modules/platform/http-security/execution-request.mapper.ts

@@ -1,5 +1,14 @@
 import type { ExecutionContext } from "@nestjs/common"
+import { GqlExecutionContext } from "@nestjs/graphql"
 import type { Request } from "express"
 
-/** The HTTP request behind an execution context. */
-export const requestOf = (context: ExecutionContext): Request => context.switchToHttp().getRequest<Request>()
+/** The GraphQL context the Apollo driver builds: the HTTP request the operation arrived on. */
+interface GraphqlRequestContext {
+    readonly req: Request
+}
+
+/** The HTTP request behind an execution context, whether the door is a REST controller or a GraphQL resolver. */
+export const requestOf = (context: ExecutionContext): Request =>
+    context.getType<string>() === "graphql"
+        ? GqlExecutionContext.create(context).getContext<GraphqlRequestContext>().req
+        : context.switchToHttp().getRequest<Request>()

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

@@ -0,0 +1,21 @@
+import type { Principal } from "@modules/platform/cqrs"
+import { admit } from "./admission.policy"
+import { IdentityErrorCode } from "./errors/identity.error"
+import { PublicReason } from "./identity.contracts"
+
+const principal: Principal = { id: "user-1", role: "authenticated" }
+
+describe("admit", () => {
+    it("admits a door that states why it is public, with or without a caller", () => {
+        expect(admit({ reason: PublicReason.Health }, undefined)).toSucceedWith(PublicReason.Health)
+        expect(admit({ reason: PublicReason.SignedWebhook }, principal)).toSucceedWith(PublicReason.SignedWebhook)
+    })
+
+    it("admits the verified principal of a door that is not public", () => {
+        expect(admit(undefined, principal)).toSucceedWith(principal)
+    })
+
+    it("refuses a door that is not public when no principal was verified", () => {
+        expect(admit(undefined, undefined)).toBeRefused(IdentityErrorCode.Unauthenticated)
+    })
+})

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

@@ -0,0 +1,94 @@
+import type { ExecutionContext } from "@nestjs/common"
+import { Reflector } from "@nestjs/core"
+import { Test } from "@nestjs/testing"
+import type { Request } from "express"
+import { mock } from "@starci/jest-preset"
+import type { Principal } from "@modules/platform/cqrs"
+import { ok, refused } from "@modules/platform/primitives"
+import { SupabaseErrorCode } from "@modules/integrations/supabase"
+import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import { AuthGuard } from "./auth.guard"
+import { IdentityErrorCode } from "./errors/identity.error"
+import type { PublicMetadata } from "./identity.contracts"
+import { PublicReason } from "./identity.contracts"
+import { ACCESS_TOKEN_VERIFIER } from "./identity.decorators"
+
+const principal: Principal = { id: "user-1", role: "authenticated" }
+
+const build = async (metadata: PublicMetadata | undefined, verify: VerifySupabaseAccessToken) => {
+    const reflector = mock<Reflector>()
+    reflector.getAllAndOverride.mockReturnValue(metadata)
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            AuthGuard,
+            { provide: Reflector, useValue: reflector },
+            { provide: ACCESS_TOKEN_VERIFIER, useValue: verify },
+        ],
+    }).compile()
+    return moduleRef.get(AuthGuard)
+}
+
+const contextOf = (authorization: string | undefined) => {
+    const request = mock<Request>()
+    request.headers = authorization === undefined ? {} : { authorization }
+    request.principal = undefined
+    const http = mock<ReturnType<ExecutionContext["switchToHttp"]>>()
+    http.getRequest.mockReturnValue(request)
+    const context = mock<ExecutionContext>()
+    context.getHandler.mockReturnValue(() => undefined)
+    context.getClass.mockReturnValue(class Door {})
+    context.switchToHttp.mockReturnValue(http)
+    return { context, request }
+}
+
+const unauthenticated = expect.objectContaining({ code: IdentityErrorCode.Unauthenticated })
+
+describe("AuthGuard", () => {
+    it("lets a public door through without reading a token", async () => {
+        const verify = jest.fn<ReturnType<VerifySupabaseAccessToken>, Parameters<VerifySupabaseAccessToken>>()
+        const guard = await build({ reason: PublicReason.Health }, verify)
+        const { context } = contextOf("Bearer token")
+
+        await expect(guard.canActivate(context)).resolves.toBe(true)
+
+        expect(verify).not.toHaveBeenCalled()
+    })
+
+    it("admits a door that is not public for a verified bearer token and records the principal on the request", async () => {
+        const verify = jest.fn<ReturnType<VerifySupabaseAccessToken>, Parameters<VerifySupabaseAccessToken>>()
+        verify.mockResolvedValue(ok(principal))
+        const guard = await build(undefined, verify)
+        const { context, request } = contextOf("Bearer signed-token")
+
+        await expect(guard.canActivate(context)).resolves.toBe(true)
+
+        expect(verify).toHaveBeenCalledWith("signed-token")
+        expect(request.principal).toEqual(principal)
+    })
+
+    it("refuses a door that is not public when the token fails verification", async () => {
+        const verify = jest.fn<ReturnType<VerifySupabaseAccessToken>, Parameters<VerifySupabaseAccessToken>>()
+        verify.mockResolvedValue(refused(SupabaseErrorCode.AccessTokenInvalid))
+        const guard = await build(undefined, verify)
+        const { context, request } = contextOf("bearer forged-token")
+
+        await expect(guard.canActivate(context)).rejects.toThrow(unauthenticated)
+
+        expect(request.principal).toBeUndefined()
+    })
+
+    it.each([
+        ["no authorization header", undefined],
+        ["another scheme", "Basic dXNlcjpwYXNz"],
+        ["a scheme without a token", "Bearer"],
+        ["a token followed by more text", "Bearer one two"],
+    ])("refuses a door that is not public with %s, without calling the verifier", async (_label, authorization) => {
+        const verify = jest.fn<ReturnType<VerifySupabaseAccessToken>, Parameters<VerifySupabaseAccessToken>>()
+        const guard = await build(undefined, verify)
+        const { context } = contextOf(authorization)
+
+        await expect(guard.canActivate(context)).rejects.toThrow(unauthenticated)
+
+        expect(verify).not.toHaveBeenCalled()
+    })
+})

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

@@ -1,7 +1,6 @@
 import { Injectable } from "@nestjs/common"
 import type { CanActivate, ExecutionContext } from "@nestjs/common"
 import type { Reflector } from "@nestjs/core"
-import { InjectSupabaseAccessTokenVerifier } from "@modules/integrations/supabase"
 import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
 import { InjectReflector } from "@modules/platform/composition"
 import type { Principal } from "@modules/platform/cqrs"
@@ -10,7 +9,7 @@ import { unwrapOutcome } from "@modules/platform/primitives"
 import { admit } from "./admission.policy"
 import { IdentityError } from "./errors/identity.error"
 import type { PublicMetadata } from "./identity.contracts"
-import { PUBLIC_KEY } from "./identity.decorators"
+import { InjectAccessTokenVerifier, PUBLIC_KEY } from "./identity.decorators"
 
 const bearerToken = (authorization: string | undefined): string | undefined => {
     const [scheme, token, extra] = authorization?.split(" ") ?? []
@@ -22,8 +21,7 @@ const bearerToken = (authorization: string | undefined): string | undefined => {
 export class AuthGuard implements CanActivate {
     constructor(
         @InjectReflector() private readonly reflector: Reflector,
-        @InjectSupabaseAccessTokenVerifier()
-        private readonly verifyAccessToken: VerifySupabaseAccessToken,
+        @InjectAccessTokenVerifier() private readonly verifyAccessToken: VerifySupabaseAccessToken,
     ) {}
 
     /** Verifies the bearer token when the door is not public, then applies the admission policy. */

package/templates/be/skeleton-lite/src/modules/domain/identity/identity.decorators.ts

@@ -1,10 +1,20 @@
 import { SetMetadata, createParamDecorator } from "@nestjs/common"
 import type { ExecutionContext } from "@nestjs/common"
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
 import { requestOf } from "@modules/platform/http-security"
 import type { Principal } from "@modules/platform/cqrs"
 import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
 import type { PublicMetadata } from "./identity.contracts"
 
+/** Token of the access-token verifier the composition root hands to identity. */
+export const ACCESS_TOKEN_VERIFIER: unique symbol = Symbol("domain.identity.access-token-verifier")
+
+/** Injects the access-token verifier identity was registered with. Parameter type: VerifySupabaseAccessToken. */
+export const InjectAccessTokenVerifier = (): TypedParameterDecorator<VerifySupabaseAccessToken> =>
+    injector<VerifySupabaseAccessToken>(ACCESS_TOKEN_VERIFIER)
+
 /** Metadata key of `@Public`. */
 export const PUBLIC_KEY = "domain.identity.public"
 

package/templates/be/skeleton-lite/src/modules/domain/identity/identity.module.ts

@@ -1,7 +1,7 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
-import { SUPABASE_ACCESS_TOKEN_VERIFIER } from "@modules/integrations/supabase"
 import { AuthGuard } from "./auth.guard"
+import { ACCESS_TOKEN_VERIFIER } from "./identity.decorators"
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./identity.module-definition"
 
 @Module({})
@@ -15,7 +15,7 @@ export class IdentityModule extends ConfigurableModuleClass {
             providers: [
                 ...(base.providers ?? []),
                 {
-                    provide: SUPABASE_ACCESS_TOKEN_VERIFIER,
+                    provide: ACCESS_TOKEN_VERIFIER,
                     useValue: options.verifyAccessToken,
                 },
                 AuthGuard,

package/templates/be/skeleton-lite/src/modules/integrations/supabase/index.ts

@@ -1,10 +1,6 @@
 export { createSupabaseAdminClient } from "./supabase.client"
 export { parseSupabaseConfig } from "./supabase.config"
-export {
-    InjectSupabaseAccessTokenVerifier,
-    SUPABASE_ACCESS_TOKEN_VERIFIER,
-    SUPABASE_ADMIN_CLIENT,
-} from "./supabase.decorators"
-export { SUPABASE_ERROR_KINDS } from "./errors/supabase.error"
+export { SUPABASE_ACCESS_TOKEN_VERIFIER, SUPABASE_ADMIN_CLIENT } from "./supabase.decorators"
+export { SUPABASE_ERROR_KINDS, SupabaseErrorCode } from "./errors/supabase.error"
 export { createSupabaseAccessTokenVerifier } from "./supabase.jwks"
 export type { SupabaseOptions, VerifySupabaseAccessToken } from "./supabase.options"

package/templates/be/skeleton-lite/src/modules/integrations/supabase/supabase.client.spec.ts

@@ -0,0 +1,15 @@
+import { Secret } from "@modules/platform/config"
+import { createSupabaseAdminClient } from "./supabase.client"
+
+describe("createSupabaseAdminClient", () => {
+    it("exposes only the Auth administration and Storage surfaces of a session-less service client", () => {
+        const client = createSupabaseAdminClient({
+            url: "http://127.0.0.1:54321",
+            serviceRoleKey: new Secret("service-role"),
+        })
+
+        expect(Object.keys(client).sort()).toEqual(["auth", "storage"])
+        expect(typeof client.auth.createUser).toBe("function")
+        expect(typeof client.storage.from).toBe("function")
+    })
+})

package/templates/be/skeleton-lite/src/modules/platform/i18n/index.ts

@@ -1,4 +1,4 @@
 export type { Locale, MessageBundle } from "./i18n.contracts"
-export { InjectMessageCatalog, InjectRequestLocale } from "./i18n.decorators"
+export { InjectMessageCatalog, InjectRequestLocale, MESSAGE_CATALOG } from "./i18n.decorators"
 export { I18nModule } from "./i18n.module"
 export type { MessageCatalog, RequestLocale } from "./i18n.port"

package/templates/be/skeleton-lite/src/modules/platform/logging/index.ts

@@ -1,5 +1,5 @@
 export { createJsonLogger } from "./json-logger.service"
-export { InjectLogger } from "./logging.decorators"
+export { InjectLogger, LOGGER } from "./logging.decorators"
 export { LoggingLogEvent } from "./logging.log-events"
 export { LoggingModule } from "./logging.module"
 export type { Logger } from "./logging.port"

package/templates/be/table/api/create.command.ts.tpl

@@ -0,0 +1,10 @@
+import { Command } from "@nestjs/cqrs"
+import type { ExecuteParams } from "@modules/platform/cqrs"
+import type { Create{{Singular}}Request, Create{{Singular}}Result } from "./create-{{singular}}.contracts"
+
+/** Asks to create one {{singular}} row owned by the authenticated caller. */
+export class Create{{Singular}}Command extends Command<Create{{Singular}}Result> {
+    constructor(readonly params: ExecuteParams<Create{{Singular}}Request>) {
+        super()
+    }
+}

package/templates/be/table/api/create.contracts.ts.tpl

@@ -0,0 +1,8 @@
+/** What create-{{singular}} takes: nothing beyond the caller, who owns the new row. */
+export type Create{{Singular}}Request = Record<never, never>
+
+/** What create-{{singular}} answers. */
+export interface Create{{Singular}}Result {
+    /** The id of the new {{singular}} row. */
+    readonly id: string
+}

package/templates/be/table/api/create.handler.ts.tpl

@@ -0,0 +1,22 @@
+import { CommandHandler } from "@nestjs/cqrs"
+import { {{Name}}Service } from "@modules/domain/{{name}}"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { Create{{Singular}}Command } from "./create-{{singular}}.command"
+import type { Create{{Singular}}Result } from "./create-{{singular}}.contracts"
+
+@CommandHandler(Create{{Singular}}Command)
+/** Creates one {{singular}} row for the authenticated principal through one domain-service call. */
+export class Create{{Singular}}Handler extends ICQRSHandler<Create{{Singular}}Command, Create{{Singular}}Result> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly {{nameCamel}}Service: {{Name}}Service,
+    ) {
+        super(logger)
+    }
+
+    protected override process(command: Create{{Singular}}Command): Promise<Create{{Singular}}Result> {
+        return this.{{nameCamel}}Service.create{{Singular}}(command.params.principal.id)
+    }
+}

package/templates/be/table/api/create.mapper.ts.tpl

@@ -0,0 +1,5 @@
+import type { Create{{Singular}}Result } from "../../application/create-{{singular}}.contracts"
+import type { Create{{Singular}}Type } from "./dto/create-{{singular}}.type"
+
+/** Maps the result to the GraphQL type. */
+export const toCreate{{Singular}}Type = (result: Create{{Singular}}Result): Create{{Singular}}Type => ({ id: result.id })

package/templates/be/table/api/create.resolver.ts.tpl

@@ -0,0 +1,21 @@
+import { Mutation, Resolver } from "@nestjs/graphql"
+import type { CommandBus } from "@nestjs/cqrs"
+import { CurrentPrincipal } from "@modules/domain/identity"
+import { InjectCommandBus } from "@modules/platform/cqrs"
+import type { Principal } from "@modules/platform/cqrs"
+import { Create{{Singular}}Command } from "../../application/create-{{singular}}.command"
+import { toCreate{{Singular}}Type } from "./create-{{singular}}.mapper"
+import { Create{{Singular}}Type } from "./dto/create-{{singular}}.type"
+
+@Resolver()
+/** GraphQL door of create-{{singular}}: a new {{singular}} row owned by the caller. */
+export class Create{{Singular}}Resolver {
+    constructor(@InjectCommandBus() private readonly commandBus: CommandBus) {}
+
+    /** Creates one {{singular}} row for the caller. */
+    @Mutation(() => Create{{Singular}}Type, { name: "create{{Singular}}" })
+    async create{{Singular}}(@CurrentPrincipal() principal: Principal): Promise<Create{{Singular}}Type> {
+        const result = await this.commandBus.execute(new Create{{Singular}}Command({ request: {}, principal }))
+        return toCreate{{Singular}}Type(result)
+    }
+}

package/templates/be/table/api/create.type.ts.tpl

@@ -0,0 +1,9 @@
+import { Field, ID, ObjectType } from "@nestjs/graphql"
+
+@ObjectType()
+/** The create-{{singular}} answer. */
+export class Create{{Singular}}Type {
+    /** The id of the new {{singular}} row. */
+    @Field(() => ID)
+    id!: string
+}

package/templates/be/table/api/feature.index.ts.tpl

@@ -0,0 +1 @@
+export { {{Name}}GraphqlModule } from "./transport/graphql/{{name}}-graphql.module"

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

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common"
+import { Create{{Singular}}Handler } from "./application/create-{{singular}}.handler"
+import { Get{{Singular}}Handler } from "./application/get-{{singular}}.handler"
+
+@Module({ providers: [Get{{Singular}}Handler, Create{{Singular}}Handler] })
+/** The {{name}} feature: the handlers of its application. */
+export class {{Name}}ApiModule {}

package/templates/be/table/api/get.contracts.ts.tpl

@@ -0,0 +1,11 @@
+/** What get-{{singular}} takes. */
+export interface Get{{Singular}}Request {
+    /** The id of the {{singular}} row. */
+    readonly id: string
+}
+
+/** What get-{{singular}} answers. */
+export interface Get{{Singular}}Result {
+    /** The id of the {{singular}} row. */
+    readonly id: string
+}

package/templates/be/table/api/get.handler.ts.tpl

@@ -0,0 +1,22 @@
+import { QueryHandler } from "@nestjs/cqrs"
+import { {{Name}}Service } from "@modules/domain/{{name}}"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import type { Get{{Singular}}Result } from "./get-{{singular}}.contracts"
+import { Get{{Singular}}Query } from "./get-{{singular}}.query"
+
+@QueryHandler(Get{{Singular}}Query)
+/** Answers one {{singular}} row of the authenticated principal through one domain-service call. */
+export class Get{{Singular}}Handler extends ICQRSHandler<Get{{Singular}}Query, Get{{Singular}}Result> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly {{nameCamel}}Service: {{Name}}Service,
+    ) {
+        super(logger)
+    }
+
+    protected override process(query: Get{{Singular}}Query): Promise<Get{{Singular}}Result> {
+        return this.{{nameCamel}}Service.{{nameCamel}}(query.params.principal.id, query.params.request.id)
+    }
+}

package/templates/be/table/api/get.input.ts.tpl

@@ -0,0 +1,12 @@
+import { Field, ID, InputType } from "@nestjs/graphql"
+import { IsUUID, MaxLength } from "class-validator"
+
+@InputType()
+/** The get-{{singular}} arguments: the id of the row. */
+export class Get{{Singular}}Input {
+    /** The id of the {{singular}} row. */
+    @Field(() => ID)
+    @IsUUID()
+    @MaxLength(36)
+    id!: string
+}