@starci/hfs 4.0.8 → 4.0.9

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

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

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

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

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

@@ -0,0 +1,13 @@
+import { Field, ID, InputType } from "@nestjs/graphql"
+import { IsNotEmpty, IsString, MaxLength } from "class-validator"
+
+@InputType()
+/** The @@actionCamel@@ arguments: the id of the subject. */
+export class @@Action@@Input {
+    /** The id of the subject. */
+    @Field(() => ID)
+    @IsString()
+    @IsNotEmpty()
+    @MaxLength(64)
+    id!: string
+}

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

@@ -0,0 +1,9 @@
+import type { @@Action@@Request, @@Action@@Result } from "../../application/@@action@@.contracts"
+import type { @@Action@@Input } from "./dto/@@action@@.input"
+import type { @@Action@@Type } from "./dto/@@action@@.type"
+
+/** Maps the GraphQL input to the command request. */
+export const to@@Action@@Request = (input: @@Action@@Input): @@Action@@Request => ({ id: input.id })
+
+/** Maps the result to the GraphQL type. */
+export const to@@Action@@Type = (result: @@Action@@Result): @@Action@@Type => ({ id: result.id })

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

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

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

@@ -0,0 +1,27 @@
+import { Args, 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 { @@Action@@Command } from "../../application/@@action@@.command"
+import { to@@Action@@Request, to@@Action@@Type } from "./@@action@@.mapper"
+import { @@Action@@Input } from "./dto/@@action@@.input"
+import { @@Action@@Type } from "./dto/@@action@@.type"
+
+@Resolver()
+/** GraphQL door of @@actionCamel@@. */
+export class @@Action@@Resolver {
+    constructor(@InjectCommandBus() private readonly commandBus: CommandBus) {}
+
+    /** Runs @@action@@ for the caller. */
+    @Mutation(() => @@Action@@Type, { name: "@@actionCamel@@" })
+    async @@actionCamel@@(
+        @CurrentPrincipal() principal: Principal,
+        @Args("input") input: @@Action@@Input,
+    ): Promise<@@Action@@Type> {
+        const result = await this.commandBus.execute(
+            new @@Action@@Command({ request: to@@Action@@Request(input), principal }),
+        )
+        return to@@Action@@Type(result)
+    }
+}

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

@@ -0,0 +1,9 @@
+import { Field, ID, ObjectType } from "@nestjs/graphql"
+
+@ObjectType()
+/** The @@actionCamel@@ answer. */
+export class @@Action@@Type {
+    /** The id of the subject. */
+    @Field(() => ID)
+    id!: string
+}

package/templates/be/patterns/api/http.controller.ts.tpl

@@ -0,0 +1,27 @@
+import { Body, Controller, Post } from "@nestjs/common"
+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 { @@Action@@Command } from "../../application/@@action@@.command"
+import { to@@Action@@Request, to@@Action@@Response } from "./@@action@@.mapper"
+import { @@Action@@Request } from "./dto/@@action@@.request"
+import { @@Action@@Response } from "./dto/@@action@@.response"
+
+@Controller("@@feature@@")
+/** HTTP door of @@actionCamel@@. */
+export class @@Action@@Controller {
+    constructor(@InjectCommandBus() private readonly commandBus: CommandBus) {}
+
+    /** Runs @@action@@ for the authenticated caller. */
+    @Post()
+    async @@actionCamel@@(
+        @CurrentPrincipal() principal: Principal,
+        @Body() input: @@Action@@Request,
+    ): Promise<@@Action@@Response> {
+        const result = await this.commandBus.execute(
+            new @@Action@@Command({ request: to@@Action@@Request(input), principal }),
+        )
+        return to@@Action@@Response(result)
+    }
+}

package/templates/be/patterns/api/http.mapper.ts.tpl

@@ -0,0 +1,9 @@
+import type { @@Action@@Request, @@Action@@Result } from "../../application/@@action@@.contracts"
+import type { @@Action@@Request as @@Action@@HttpRequest } from "./dto/@@action@@.request"
+import type { @@Action@@Response } from "./dto/@@action@@.response"
+
+/** Maps the HTTP request to the command request. */
+export const to@@Action@@Request = (input: @@Action@@HttpRequest): @@Action@@Request => ({ id: input.id })
+
+/** Maps the command result to the HTTP response. */
+export const to@@Action@@Response = (result: @@Action@@Result): @@Action@@Response => ({ id: result.id })

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

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common"
+import { @@Feature@@ApiModule } from "../../@@feature@@.module"
+import { @@Action@@Controller } from "./@@action@@.controller"
+
+@Module({ imports: [@@Feature@@ApiModule], controllers: [@@Action@@Controller] })
+/** The HTTP transport of the @@feature@@ feature. */
+export class @@Feature@@HttpModule {}

package/templates/be/patterns/api/http.request.ts.tpl

@@ -0,0 +1,10 @@
+import { IsNotEmpty, IsString, MaxLength } from "class-validator"
+
+/** The bounded HTTP request of @@actionCamel@@. */
+export class @@Action@@Request {
+    /** The id of the subject. */
+    @IsString()
+    @IsNotEmpty()
+    @MaxLength(64)
+    id!: string
+}

package/templates/be/patterns/api/http.response.ts.tpl

@@ -0,0 +1,5 @@
+/** The HTTP response of @@actionCamel@@. */
+export class @@Action@@Response {
+    /** The id of the subject. */
+    id!: string
+}

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

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

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

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

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

@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common"
+import { @@Group@@Cli } from "./@@group@@.cli"
+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 {}

package/templates/be/patterns/cli/sub.run.cli.spec.ts.tpl

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

package/templates/be/patterns/cli/sub.run.cli.ts.tpl

@@ -0,0 +1,15 @@
+import { CommandRunner, SubCommand } from "nest-commander"
+import { @@service@@ } from "@@serviceModule@@"
+
+@SubCommand({ name: "run", description: "Run @@group@@" })
+/** `cli @@group@@ run`: delegates the run to the injected runner service; no decision here. */
+export class RunCli extends CommandRunner {
+    constructor(private readonly @@serviceCamel@@: @@service@@) {
+        super()
+    }
+
+    /** Runs @@group@@ through the runner service. */
+    async run(): Promise<void> {
+        await this.@@serviceCamel@@.run()
+    }
+}

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

@@ -0,0 +1,22 @@
+import { DomainError } from "@modules/platform/errors"
+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. */
+    DeadLetterUnknown = "EVENT_BUS_DEAD_LETTER_UNKNOWN",
+}
+
+/** 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",
+}
+
+/** The one error class of the event-bus capability. */
+export class EventBusError extends DomainError<EventBusErrorCode> {}

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

@@ -0,0 +1,19 @@
+import type { EnvSource } from "@modules/platform/config"
+import type { EventBusOptions } from "./event-bus.options"
+
+/** What the app's `main.ts` reads for the bus; the connection token is the app root's choice. */
+export type EventBusConfig = Omit<EventBusOptions, "connections">
+
+/** Reads the event bus options: the brokers and the group are required, the rest are tunables with literal defaults. */
+export const parseEventBusConfig = (env: EnvSource): EventBusConfig => ({
+    brokers: env
+        .string("EVENT_BUS_BROKERS")
+        .split(",")
+        .map((broker) => broker.trim())
+        .filter((broker) => broker.length > 0),
+    groupId: env.string("EVENT_BUS_GROUP_ID"),
+    topicPrefix: env.optional("EVENT_BUS_TOPIC_PREFIX") ?? "",
+    relayIntervalMs: env.duration("EVENT_BUS_RELAY_INTERVAL", 200),
+    relayBatch: env.int("EVENT_BUS_RELAY_BATCH", 50),
+    timeoutMs: env.duration("EVENT_BUS_TIMEOUT", 3000),
+})

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

@@ -0,0 +1,58 @@
+/** The base of every typed event (`modules/events/<service>/<event>.event.ts`): who it is and what it carries. */
+export abstract class BaseEvent {
+    /** The stable event id: the same logical event always carries the same id, so a receiver can dedupe. */
+    abstract readonly eventId: string
+
+    /** The event name, `<service>.<what>`: an entry of the vendored contract `be/contracts/<service>/events.json`. */
+    abstract readonly eventName: string
+
+    /** The data of the event. */
+    abstract readonly payload: object
+}
+
+/** What reading a received envelope answers: the event, or null when the envelope does not have the shape of the event. */
+export type ParsedEvent<Event extends BaseEvent> = Event | null
+
+/** The class side of a typed event: its name and version (the vendored contract), and how a received envelope is read back. */
+export interface EventClass<Event extends BaseEvent> {
+    /** The event name. */
+    readonly eventName: string
+    /** The contract version of the payload. */
+    readonly version: number
+    /** Reads a received envelope `{ eventId, payload }` back into the event; null when it does not have the shape. */
+    parse(envelope: unknown): ParsedEvent<Event>
+}
+
+/** An event as a consumer receives it. */
+export interface EventDelivery<Event extends BaseEvent> {
+    /** The stable event id: the dedupe key of the receiver. */
+    readonly eventId: string
+    /** The event. */
+    readonly event: Event
+    /** How many deliveries were started, this one included. */
+    readonly attempt: number
+}
+
+/** An event that ran out of attempts and waits for an operator. */
+export interface EventDeadLetter {
+    /** The id of the dead letter, what `requeue` takes. */
+    readonly id: string
+    /** The event name. */
+    readonly eventName: string
+    /** The stable event id. */
+    readonly eventId: string
+    /** Why the last delivery failed. */
+    readonly reason: string
+    /** How many deliveries were tried. */
+    readonly attempts: number
+}
+
+/** The envelope of an event on the wire: what the outbox row stores and a consumer reads back. */
+export interface EventEnvelope {
+    /** The stable event id. */
+    readonly eventId: string
+    /** The event name. */
+    readonly eventName: string
+    /** The data of the event. */
+    readonly payload: object
+}

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

@@ -0,0 +1,46 @@
+import type { EntityManager } from "typeorm"
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { EventBusOptions } from "./event-bus.options"
+import type { EventBus, EventConsumerRegistry } from "./event-bus.port"
+import type { EventTransport, KafkaFactory } from "./event-transport.port"
+
+/** Token of the options of the event bus, exported so a spec can provide it. */
+export const EVENT_BUS_OPTIONS: unique symbol = Symbol("platform.event-bus.options")
+
+/** Token of the EventBus port. */
+export const EVENT_BUS: unique symbol = Symbol("platform.event-bus")
+
+/** Token of the consumer registry of the bus. */
+export const EVENT_CONSUMER_REGISTRY: unique symbol = Symbol("platform.event-bus.registry")
+
+/** Token of the broker port; it is also the health probe token of the bus. */
+export const EVENT_TRANSPORT: unique symbol = Symbol("platform.event-bus.transport")
+
+/** Token of the entity managers of the connections whose outbox the relay reads, in the order the options name them. */
+export const EVENT_RELAY_MANAGERS: unique symbol = Symbol("platform.event-bus.relay-managers")
+
+/** Token of the factory that builds the Kafka driver, exported so a spec can provide it. */
+export const KAFKA_FACTORY: unique symbol = Symbol("platform.event-bus.kafka-factory")
+
+/** Injects the options of the event bus. Parameter type: EventBusOptions. */
+export const InjectEventBusOptions = (): TypedParameterDecorator<EventBusOptions> =>
+    injector<EventBusOptions>(EVENT_BUS_OPTIONS)
+
+/** Injects the EventBus port. Parameter type: EventBus. */
+export const InjectEventBus = (): TypedParameterDecorator<EventBus> => injector<EventBus>(EVENT_BUS)
+
+/** Injects the consumer registry a message transport registers its consumers with. Parameter type: EventConsumerRegistry. */
+export const InjectEventConsumerRegistry = (): TypedParameterDecorator<EventConsumerRegistry> =>
+    injector<EventConsumerRegistry>(EVENT_CONSUMER_REGISTRY)
+
+/** Injects the broker port. Parameter type: EventTransport. */
+export const InjectEventTransport = (): TypedParameterDecorator<EventTransport> =>
+    injector<EventTransport>(EVENT_TRANSPORT)
+
+/** Injects the entity managers the relay reads the outbox of. Parameter type: ReadonlyArray<EntityManager>. */
+export const InjectEventRelayManagers = (): TypedParameterDecorator<ReadonlyArray<EntityManager>> =>
+    injector<ReadonlyArray<EntityManager>>(EVENT_RELAY_MANAGERS)
+
+/** Injects the factory that builds the Kafka driver. Parameter type: KafkaFactory. */
+export const InjectKafkaFactory = (): TypedParameterDecorator<KafkaFactory> => injector<KafkaFactory>(KAFKA_FACTORY)

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

@@ -0,0 +1,12 @@
+/** Log events of the event bus. */
+export enum EventBusLogEvent {
+    /** A consumer threw for a delivery; the cause rides with the event and the attempt. */
+    DeliveryFailed = "event-bus.delivery.failed",
+    /** A delivery failed and the event waits on the retry topic; the event and the attempt ride in the fields. */
+    DeliveryRetried = "event-bus.delivery.retried",
+    /** An event ran out of attempts and was put on the dead-letter topic. */
+    DeliveryBuried = "event-bus.delivery.buried",
+    /** A relay pass over the outbox failed; the next pass tries again. */
+    /** A received message is not an envelope of a registered event and was left alone. */
+    MessageSkipped = "event-bus.message.skipped",
+}

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

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

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

@@ -0,0 +1,52 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { Kafka, logLevel } from "kafkajs"
+import type { EntityManager } from "typeorm"
+import {
+    EVENT_BUS,
+    EVENT_RELAY_MANAGERS,
+    EVENT_CONSUMER_REGISTRY,
+    EVENT_TRANSPORT,
+    KAFKA_FACTORY,
+} from "./event-bus.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./event-bus.module-definition"
+import { EventBusService } from "./event-bus.service"
+import { EventRelayService } from "./event-relay.service"
+import { EventRunnerService } from "./event-runner.service"
+import type { KafkaDriver, KafkaDriverConfig } from "./event-transport.port"
+import { KafkaEventTransportClient } from "./kafka-event-transport.client"
+
+@Module({})
+/** The event bus of a service: the outbox writer, its relay, the consumer runner and the Kafka transport, registered once per app over the connection that holds its outbox. */
+export class EventBusModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app that publishes or consumes events. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [
+                ...(base.providers ?? []),
+                {
+                    provide: EVENT_RELAY_MANAGERS,
+                    useFactory: (...managers: Array<EntityManager>) => managers,
+                    inject: [...options.connections],
+                },
+                {
+                    provide: KAFKA_FACTORY,
+                    useValue: {
+                        create: (config: KafkaDriverConfig): KafkaDriver =>
+                            new Kafka({ ...config, brokers: [...config.brokers], logLevel: logLevel.NOTHING }),
+                    },
+                },
+                KafkaEventTransportClient,
+                { provide: EVENT_TRANSPORT, useExisting: KafkaEventTransportClient },
+                EventBusService,
+                EventRelayService,
+                EventRunnerService,
+                { provide: EVENT_BUS, useExisting: EventBusService },
+                { provide: EVENT_CONSUMER_REGISTRY, useExisting: EventRunnerService },
+            ],
+            exports: [EVENT_BUS, EVENT_CONSUMER_REGISTRY, EVENT_TRANSPORT],
+        }
+    }
+}

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

@@ -0,0 +1,19 @@
+import type { InjectionToken } from "@nestjs/common"
+
+/** What the event bus of one app needs: where the broker is, who the app is to it, and the connection whose outbox it relays. */
+export interface EventBusOptions {
+    /** The broker addresses, `host:port`. */
+    readonly brokers: ReadonlyArray<string>
+    /** The consumer group of the app: every instance of one app shares it. */
+    readonly groupId: string
+    /** What every topic name starts with: empty in a deployment, the run prefix of a test world. */
+    readonly topicPrefix: string
+    /** The pause between two relay passes over the outbox. */
+    readonly relayIntervalMs: number
+    /** The most outbox rows one relay pass hands to the broker. */
+    readonly relayBatch: number
+    /** The deadline of one broker call. */
+    readonly timeoutMs: number
+    /** The tokens of the shared entity managers of the connections that hold an outbox of the app: the relay reads each of them. */
+    readonly connections: ReadonlyArray<InjectionToken>
+}

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

@@ -0,0 +1,28 @@
+import type { EntityManager } from "typeorm"
+import type { BaseEvent, EventClass, EventDeadLetter, EventDelivery } from "./event-bus.contracts"
+
+/** The event bus of a service: events leave it through `publish`, called by a domain service in the transaction of the change they report. */
+export interface EventBus {
+    /** Writes the event in the outbox of the transaction `tx` carries; the relay hands it to the broker once the transaction commits. */
+    publish(event: BaseEvent, tx: EntityManager): Promise<void>
+    /** How many deliveries of the class wait on the retry topic for their backoff to pass. */
+    pendingRetries(event: EventClass<BaseEvent>): Promise<number>
+    /** The events of the class that ran out of attempts. */
+    deadLetters(event: EventClass<BaseEvent>): Promise<ReadonlyArray<EventDeadLetter>>
+    /** Puts a dead letter back to be delivered again. */
+    requeue(deadLetterId: string): Promise<void>
+}
+
+/** One consumer of one event; a transport class in `transport/message` implements it. */
+export interface EventConsumer<Event extends BaseEvent> {
+    /** The class of the event this consumer reads. */
+    readonly event: EventClass<Event>
+    /** Handles one delivery; a throw schedules a retry with the backoff of the bus, a return acknowledges it. */
+    handle(delivery: EventDelivery<Event>): Promise<void>
+}
+
+/** Where a message transport module registers its consumers. */
+export interface EventConsumerRegistry {
+    /** Registers the consumer of its event. */
+    add<Event extends BaseEvent>(consumer: EventConsumer<Event>): void
+}