@starci/hfs 5.0.8 → 5.1.0

package/runtime/scripts/hfs/explicit-surface-rule.d.mts

@@ -0,0 +1,58 @@
+import type { TypeScript } from '../lib/ts-ast.mjs';
+/** The part of an ESLint rule context the rule reads (typescript-eslint's context satisfies it). */
+export interface SurfaceContext {
+    readonly filename: string;
+    readonly sourceCode: {
+        readonly text: string;
+        getLocFromIndex(index: number): {
+            line: number;
+            column: number;
+        };
+        readonly parserServices?: {
+            readonly program?: {
+                getCompilerOptions(): {
+                    module?: number;
+                };
+            } | null;
+        } | undefined;
+    };
+    report(descriptor: {
+        loc: {
+            start: {
+                line: number;
+                column: number;
+            };
+            end: {
+                line: number;
+                column: number;
+            };
+        };
+        messageId: string;
+        data: Record<string, string>;
+    }): void;
+}
+/** The rule module the factory returns: a plain ESLint rule with one message. */
+export interface SurfaceRule {
+    meta: {
+        type: 'problem';
+        docs: {
+            description: string;
+        };
+        schema: [];
+        messages: {
+            inferred: string;
+        };
+    };
+    create(context: SurfaceContext): {
+        Program(): void;
+    };
+}
+/**
+ * The rule. `ts` is the canon's own TypeScript (its peer dependency); the side's `module` option comes from the typed program when the file is linted with one.
+ *
+ * @param input - `ts` is the compiler.
+ * @returns An ESLint rule reporting each export of a TypeScript source whose type is inferred.
+ */
+export declare const explicitSurfaceRule: ({ ts }: {
+    ts: TypeScript;
+}) => SurfaceRule;

package/runtime/scripts/hfs/explicit-surface-rule.mjs

@@ -0,0 +1,59 @@
+import { declarationSurface, isEmittableSource } from '../lib/declaration-surface.mjs';
+/** What to write, by what the classifier says to annotate. */
+const HINTS = {
+    'return type': 'Write the return type after the parameter list: `(): Result =>` or `function name(): Result`.',
+    'variable type': 'Give the variable a type: `export const name: Result = ...`.',
+    'parameter type': 'Give the parameter a type: `(value: Input)`.',
+    'property type': 'Give the property a type: `name: Result = ...`.',
+    'accessor type': 'Give the accessor a type: `get name(): Result` (a setter takes it from its parameter).',
+    'destructured export': 'A destructuring pattern cannot carry a type per name: export each name as its own variable with a type, `export const name: Type = source.name`.',
+    'exported value': 'Declare the type (an interface or a type alias) and annotate the export with it: `export const name: Shape = ...`.',
+};
+/** The `--isolatedDeclarations` flag name TypeScript ends its reasons with says nothing to the reader. */
+const plain = (reason) => reason.replace(/ with --isolatedDeclarations\.?/, '').replace(/\.$/, '');
+/**
+ * The rule. `ts` is the canon's own TypeScript (its peer dependency); the side's `module` option comes from the typed program when the file is linted with one.
+ *
+ * @param input - `ts` is the compiler.
+ * @returns An ESLint rule reporting each export of a TypeScript source whose type is inferred.
+ */
+export const explicitSurfaceRule = ({ ts }) => ({
+    meta: {
+        type: 'problem',
+        docs: { description: 'An exported declaration states its type: the return type, variable type or parameter type is written, not inferred from a body or from other files.' },
+        schema: [],
+        messages: {
+            inferred: 'HFS_EXPLICIT_EXPORT_SURFACE: `{{name}}` is exported with an inferred type ({{reason}}), so importers cannot read it from this file and every one of them is linted again whenever the file changes. Annotate the {{annotate}}. {{hint}}',
+        },
+    },
+    create(context) {
+        return {
+            Program() {
+                const file = context.filename;
+                if (!isEmittableSource(file))
+                    return;
+                const { sourceCode } = context;
+                const module = sourceCode.parserServices?.program?.getCompilerOptions().module;
+                const whole = { start: { line: 1, column: 0 }, end: { line: 1, column: 0 } };
+                let surface;
+                try {
+                    surface = declarationSurface(ts, file, sourceCode.text, module);
+                }
+                catch {
+                    surface = null;
+                }
+                if (surface === null) {
+                    context.report({ loc: whole, messageId: 'inferred', data: { name: 'this file', reason: 'the declaration emit could not read it', annotate: 'exported value', hint: HINTS['exported value'] } });
+                    return;
+                }
+                for (const problem of surface.problems) {
+                    context.report({
+                        loc: { start: sourceCode.getLocFromIndex(problem.start), end: sourceCode.getLocFromIndex(problem.start + problem.length) },
+                        messageId: 'inferred',
+                        data: { name: problem.name, reason: plain(problem.reason), annotate: problem.annotate, hint: HINTS[problem.annotate] },
+                    });
+                }
+            },
+        };
+    },
+});

package/runtime/scripts/lib/declaration-surface.d.mts

@@ -0,0 +1,35 @@
+import type { TypeScript } from './ts-ast.mjs';
+/** What the declaration emit cannot write without reading other files, and where: one export (or one part of it) the author must annotate. */
+export interface SurfaceProblem {
+    /** The TypeScript diagnostic code (9007: function without a return type, 9010: variable without a type, ...). */
+    code: number;
+    /** The offset and length of the offending span in the file's text. */
+    start: number;
+    length: number;
+    /** The name of the export (or member) the span sits in, or `default export`. */
+    name: string;
+    /** What to annotate: `return type`, `variable type`, `parameter type`, `property type`, `accessor type`, `destructured export` or `exported value`. */
+    annotate: string;
+    /** TypeScript's own reason, one sentence. */
+    reason: string;
+}
+/** The declaration emit of one file: its text (the digest of the type surface) and the exports it could not write explicitly. */
+export interface DeclarationSurface {
+    outputText: string;
+    problems: SurfaceProblem[];
+}
+/** A script file (`.js`, `.mjs`, `.cjs`, `.jsx`): it has no declaration emit and stands for its content. */
+export declare const SCRIPT: RegExp;
+/** A declaration file: it is its own surface. */
+export declare const DECLARATION: RegExp;
+/** A TypeScript source file whose surface the declaration emit writes. */
+export declare const TYPESCRIPT: RegExp;
+/** Whether `file` is a TypeScript source (not a declaration file) the declaration emit reads. */
+export declare const isEmittableSource: (file: string) => boolean;
+/**
+ * The declaration emit of one TypeScript source and the exports it could not write explicitly (a type inferred from bodies and other files), or null
+ * when the compiler has no `transpileDeclaration` (before TypeScript 5.5). A declaration whose only diagnostics are components returning JSX has the
+ * surface its emit shows. `module` is the side's `module` compiler option, which the emit reads. A throw from the compiler propagates: the caller
+ * decides what an unreadable file means.
+ */
+export declare function declarationSurface(ts: TypeScript, file: string, text: string, module?: number): DeclarationSurface | null;

package/runtime/scripts/lib/declaration-surface.mjs

@@ -0,0 +1,112 @@
+/** A script file (`.js`, `.mjs`, `.cjs`, `.jsx`): it has no declaration emit and stands for its content. */
+export const SCRIPT = /\.(?:[cm]?jsx?)$/;
+/** A declaration file: it is its own surface. */
+export const DECLARATION = /\.d\.[cm]?ts$/;
+/** A TypeScript source file whose surface the declaration emit writes. */
+export const TYPESCRIPT = /\.(?:[cm]?tsx?)$/;
+/** Whether `file` is a TypeScript source (not a declaration file) the declaration emit reads. */
+export const isEmittableSource = (file) => TYPESCRIPT.test(file) && !DECLARATION.test(file);
+/** Whether `expression` is a JSX element, fragment, `null` or `undefined`, or a conditional of those: its type does not depend on any other file. */
+function isJsxValue(ts, expression) {
+    if (expression === undefined)
+        return false;
+    let node = expression;
+    while (ts.isParenthesizedExpression(node))
+        node = node.expression;
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node) || node.kind === ts.SyntaxKind.NullKeyword)
+        return true;
+    if (ts.isIdentifier(node))
+        return node.text === 'undefined';
+    return ts.isConditionalExpression(node) && isJsxValue(ts, node.whenTrue) && isJsxValue(ts, node.whenFalse);
+}
+/**
+ * Whether the function (or method) the declaration diagnostic at `start` points at has the type `JSX.Element | null | undefined` whatever its body
+ * reads: not async, not a generator, and every `return` of its own (and its concise body) a JSX value. A React component written without a return
+ * type is the common case; its inferred type is one the JSX namespace of the installed packages gives, which a lockfile change dirties as a whole.
+ */
+function returnsOnlyJsx(ts, source, start) {
+    let found;
+    const find = (node) => {
+        if (found !== undefined || start < node.getFullStart() || start >= node.end)
+            return;
+        const named = (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name !== undefined && node.name.getStart(source) === start;
+        if (named || ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.getStart(source) === start)) {
+            found = node;
+            return;
+        }
+        ts.forEachChild(node, find);
+    };
+    find(source);
+    const fn = found;
+    if (fn === undefined || fn.type !== undefined || fn.body === undefined)
+        return false;
+    if (fn.asteriskToken !== undefined || (ts.getCombinedModifierFlags(fn) & ts.ModifierFlags.Async) !== 0)
+        return false;
+    if (!ts.isBlock(fn.body))
+        return isJsxValue(ts, fn.body);
+    let only = true;
+    const visit = (node) => {
+        if (!only || ts.isFunctionLike(node) || ts.isClassLike(node))
+            return;
+        if (ts.isReturnStatement(node) && node.expression !== undefined && !isJsxValue(ts, node.expression))
+            only = false;
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(fn.body, visit);
+    return only;
+}
+/** What to annotate for each isolated-declaration diagnostic code; any other code asks for the exported value's type. */
+const ANNOTATE = new Map([
+    [9007, 'return type'], [9008, 'return type'], [9009, 'accessor type'], [9010, 'variable type'], [9011, 'parameter type'], [9012, 'property type'],
+    [9019, 'destructured export'], [9025, 'parameter type'],
+]);
+/** The declaration kinds whose name labels the export a diagnostic sits in, innermost first. */
+function nameOf(ts, source, start) {
+    let innermost = source;
+    const descend = (node) => {
+        if (start < node.getFullStart() || start >= node.end)
+            return;
+        innermost = node;
+        ts.forEachChild(node, descend);
+    };
+    ts.forEachChild(source, descend);
+    for (let node = innermost; node !== undefined && node !== source; node = node.parent) {
+        if (ts.isExportAssignment(node))
+            return 'default export';
+        if (ts.isBindingElement(node) && ts.isIdentifier(node.name))
+            return node.name.text;
+        if ((ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) || ts.isPropertyAssignment(node) || ts.isGetAccessorDeclaration(node)) && node.name !== undefined && ts.isIdentifier(node.name))
+            return node.name.text;
+        if (ts.isFunctionDeclaration(node) && (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Default) !== 0)
+            return 'default export';
+    }
+    return 'default export';
+}
+/**
+ * The declaration emit of one TypeScript source and the exports it could not write explicitly (a type inferred from bodies and other files), or null
+ * when the compiler has no `transpileDeclaration` (before TypeScript 5.5). A declaration whose only diagnostics are components returning JSX has the
+ * surface its emit shows. `module` is the side's `module` compiler option, which the emit reads. A throw from the compiler propagates: the caller
+ * decides what an unreadable file means.
+ */
+export function declarationSurface(ts, file, text, module) {
+    const emit = ts.transpileDeclaration;
+    if (emit === undefined)
+        return null;
+    const declared = emit.call(ts, text, { compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, ...(module === undefined ? {} : { module }) }, fileName: file, reportDiagnostics: true });
+    const diagnostics = (declared.diagnostics ?? []);
+    if (diagnostics.length === 0)
+        return { outputText: declared.outputText, problems: [] };
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const problems = [];
+    for (const diagnostic of diagnostics) {
+        const exempt = (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start);
+        if (exempt)
+            continue;
+        const start = diagnostic.start ?? 0;
+        problems.push({
+            code: diagnostic.code, start, length: diagnostic.length ?? 0, name: nameOf(ts, source, start), annotate: ANNOTATE.get(diagnostic.code) ?? 'exported value',
+            reason: ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('\n')[0] ?? '',
+        });
+    }
+    return { outputText: declared.outputText, problems };
+}

package/templates/be/inbox/delivery-recorded.event.ts.tpl

@@ -10,10 +10,10 @@ export interface @@Provider@@DeliveryRecordedPayload {
 
 /** Version 1 of `@@provider@@.delivery-recorded`, published once by the provider inbox intake. */
 export class @@Provider@@DeliveryRecordedEvent extends BaseEvent {
-    static readonly eventName = "@@provider@@.delivery-recorded"
+    static readonly eventName: string = "@@provider@@.delivery-recorded"
     static readonly version = 1
 
-    readonly eventName = @@Provider@@DeliveryRecordedEvent.eventName
+    readonly eventName: string = @@Provider@@DeliveryRecordedEvent.eventName
 
     private constructor(
         readonly eventId: string,

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

@@ -1,4 +1,4 @@
 import { @@Provider@@InboxEntity } from "./@@provider@@-inbox.entity"
 
 /** The entities of the @@provider@@-inbox capability, named in PRIMARY_ENTITIES of platform/database/entities.ts. */
-export const @@providerCamel@@InboxEntities = [@@Provider@@InboxEntity]
+export const @@providerCamel@@InboxEntities: ReadonlyArray<typeof @@Provider@@InboxEntity> = [@@Provider@@InboxEntity]

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

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { @@Provider@@InboxOptions } from "./@@provider@@-inbox.options"
 
-export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<@@Provider@@InboxOptions>()
+const built = new ConfigurableModuleBuilder<@@Provider@@InboxOptions>()
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
     .build()
+type Host = ConfigurableModuleHost<@@Provider@@InboxOptions, "register", "create", { isGlobal: boolean }>
+
+/** The configurable-module class the module extends. */
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

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

@@ -1,6 +1,14 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { EventBusOptions } from "./event-bus.options"
 
-export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = new ConfigurableModuleBuilder<EventBusOptions>()
+const built = new ConfigurableModuleBuilder<EventBusOptions>()
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
     .build()
+type Host = ConfigurableModuleHost<EventBusOptions, "register", "create", { isGlobal: boolean }>
+
+/** The configurable-module class the module extends. */
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The injection token of the registered options. */
+export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

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

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { InboxOptions } from "./inbox.options"
 
-export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<InboxOptions>()
+const built = new ConfigurableModuleBuilder<InboxOptions>()
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
     .build()
+type Host = ConfigurableModuleHost<InboxOptions, "register", "create", { isGlobal: boolean }>
+
+/** The configurable-module class the module extends. */
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

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

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { @@Feature@@ApiOptions } from "./@@feature@@.options"
 
+const built = new ConfigurableModuleBuilder<@@Feature@@ApiOptions>().setClassMethodName("register").build()
+type Host = ConfigurableModuleHost<@@Feature@@ApiOptions, "register", "create", {}>
+
 /** The configurable-module base of the @@feature@@ module. */
-export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
-    new ConfigurableModuleBuilder<@@Feature@@ApiOptions>().setClassMethodName("register").build()
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The injection token of the registered options. */
+export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

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

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { @@Feature@@GraphqlOptions } from "./@@feature@@-graphql.options"
 
+const built = new ConfigurableModuleBuilder<@@Feature@@GraphqlOptions>().setClassMethodName("register").build()
+type Host = ConfigurableModuleHost<@@Feature@@GraphqlOptions, "register", "create", {}>
+
 /** The configurable-module base of the @@feature@@-graphql module. */
-export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
-    new ConfigurableModuleBuilder<@@Feature@@GraphqlOptions>().setClassMethodName("register").build()
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The injection token of the registered options. */
+export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

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

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { @@Group@@Options } from "./@@group@@.options"
 
+const built = new ConfigurableModuleBuilder<@@Group@@Options>().setClassMethodName("register").build()
+type Host = ConfigurableModuleHost<@@Group@@Options, "register", "create", {}>
+
 /** The configurable-module base of the @@group@@ module. */
-export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
-    new ConfigurableModuleBuilder<@@Group@@Options>().setClassMethodName("register").build()
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The injection token of the registered options. */
+export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

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

@@ -1,10 +1,15 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } 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>({
+const built = new ConfigurableModuleBuilder<EventBusOptions>({
     optionsInjectionToken: EVENT_BUS_OPTIONS,
 })
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
     .build()
+type Host = ConfigurableModuleHost<EventBusOptions, "register", "create", { isGlobal: boolean }>
+
+/** The configurable-module base of the event bus; `isGlobal` is decided by the app root. */
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

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

@@ -1,8 +1,9 @@
+import type { DatabaseConnectionOptions } from "@modules/platform/database"
 import { EventOutboxEntity } from "./entities/event-outbox.entity"
 import { CreateEventOutbox@@epochMs13@@ } from "./migrations/@@epochMs13@@-create-event-outbox"
 
 /** The entities of the event bus, for every connection that publishes events. */
-export const eventBusEntities = [EventOutboxEntity]
+export const eventBusEntities: DatabaseConnectionOptions["entities"] = [EventOutboxEntity]
 
 /** The migrations of the event bus, in the order they run. */
-export const eventBusMigrations = [CreateEventOutbox@@epochMs13@@]
+export const eventBusMigrations: DatabaseConnectionOptions["migrations"] = [CreateEventOutbox@@epochMs13@@]

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

@@ -1,12 +1,13 @@
 import { sql } from "@modules/platform/database"
+import type { SqlText } from "@modules/platform/database"
 
 /** Writes one event in the outbox ($1 event id, $2 event name, $3 topic, $4 key, $5 envelope, $6 instant, $7 correlation id). */
-export const INSERT_OUTBOX_ROW = sql`INSERT INTO event_outbox (event_id, event_name, topic, message_key, envelope, created_at, correlation_id)
+export const INSERT_OUTBOX_ROW: SqlText = sql`INSERT INTO event_outbox (event_id, event_name, topic, message_key, envelope, created_at, correlation_id)
     VALUES ($1, $2, $3, $4, $5, $6, $7)`
 
 /** Locks and reads the oldest rows that wait ($1 batch size); a second relay skips the rows this one holds. */
-export const SELECT_WAITING_ROWS = sql`SELECT id, topic, message_key, envelope, correlation_id FROM event_outbox
+export const SELECT_WAITING_ROWS: SqlText = sql`SELECT id, topic, message_key, envelope, correlation_id FROM event_outbox
     WHERE sent_at IS NULL ORDER BY id LIMIT $1 FOR UPDATE SKIP LOCKED`
 
 /** Marks the rows as handed to the broker ($1 ids, $2 instant). */
-export const MARK_ROWS_SENT = sql`UPDATE event_outbox SET sent_at = $2 WHERE id = ANY($1::bigint[])`
+export const MARK_ROWS_SENT: SqlText = sql`UPDATE event_outbox SET sent_at = $2 WHERE id = ANY($1::bigint[])`

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

@@ -1,7 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { InboxOptions } from "./inbox.options"
 
-/** The configurable-module base of the inbox capability; `isGlobal` is decided by the app root. */
-export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<InboxOptions>()
+const built = new ConfigurableModuleBuilder<InboxOptions>()
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
     .build()
+type Host = ConfigurableModuleHost<InboxOptions, "register", "create", { isGlobal: boolean }>
+
+/** The configurable-module base of the inbox capability; `isGlobal` is decided by the app root. */
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

package/templates/be/patterns/idempotency/platform/inbox/persistence/connection.ts.tpl

@@ -1,9 +1,10 @@
+import type { DatabaseConnectionOptions } from "@modules/platform/database"
 import { InboxClaimEntity } from "./entities/inbox-claim.entity"
 import { CreateInboxClaims1789800005000 } from "./migrations/1789800005000-create-inbox-claims"
 import { ClientOperationOutcomes1792800000000 } from "./migrations/1792800000000-client-operation-outcomes"
 
 /** The entities of the inbox capability, for the connection that holds them. */
-export const inboxEntities = [InboxClaimEntity]
+export const inboxEntities: DatabaseConnectionOptions["entities"] = [InboxClaimEntity]
 
 /** The migrations of the inbox capability, in the order they run. */
-export const inboxMigrations = [CreateInboxClaims1789800005000, ClientOperationOutcomes1792800000000]
+export const inboxMigrations: DatabaseConnectionOptions["migrations"] = [CreateInboxClaims1789800005000, ClientOperationOutcomes1792800000000]

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

@@ -1,20 +1,21 @@
 import { sql } from "@modules/platform/database"
+import type { SqlText } from "@modules/platform/database"
 
 /** Claims the event ($1 source, $2 event id, $3 instant); answers one row when this call won and none when it was claimed before. */
-export const CLAIM_EVENT = sql`INSERT INTO inbox_claims (source, event_id, claimed_at) VALUES ($1, $2, $3)
+export const CLAIM_EVENT: SqlText = sql`INSERT INTO inbox_claims (source, event_id, claimed_at) VALUES ($1, $2, $3)
     ON CONFLICT (source, event_id) DO NOTHING RETURNING event_id`
 
 /** Gives a delivery claim back; client outcomes can expire only through the retention API. */
-export const RELEASE_EVENT = sql`DELETE FROM inbox_claims WHERE source = $1 AND event_id = $2 AND request_fingerprint IS NULL`
+export const RELEASE_EVENT: SqlText = sql`DELETE FROM inbox_claims WHERE source = $1 AND event_id = $2 AND request_fingerprint IS NULL`
 
 /** A conflicting insert locks the existing row and returns its committed fingerprint and outcome after the winner commits. */
-export const CLAIM_CLIENT = sql`INSERT INTO inbox_claims (source, event_id, request_fingerprint, claimed_at)
+export const CLAIM_CLIENT: SqlText = sql`INSERT INTO inbox_claims (source, event_id, request_fingerprint, claimed_at)
 VALUES ($1, $2, $3, $4)
 ON CONFLICT (source, event_id) DO UPDATE SET outcome = COALESCE(inbox_claims.outcome, '{}'::jsonb)
 RETURNING request_fingerprint, outcome, (outcome IS NOT NULL AND (jsonb_typeof(outcome) <> 'object' OR NOT (outcome ? 'value'))) AS incomplete`
 
 /** The JSON envelope distinguishes a completed null result from an uncompleted claim in this transaction. */
-export const SAVE_CLIENT_OUTCOME = sql`WITH saved AS (
+export const SAVE_CLIENT_OUTCOME: SqlText = sql`WITH saved AS (
     UPDATE inbox_claims SET outcome = $3::jsonb
     WHERE source = $1 AND event_id = $2
     RETURNING outcome
@@ -22,7 +23,7 @@ export const SAVE_CLIENT_OUTCOME = sql`WITH saved AS (
 SELECT outcome FROM saved LIMIT 1`
 
 /** Retention never deletes delivery rows or an incomplete claim; its bounded batch skips rows held by active retries. */
-export const SWEEP_CLIENTS = sql`WITH expired AS (
+export const SWEEP_CLIENTS: SqlText = sql`WITH expired AS (
     SELECT source, event_id FROM inbox_claims
     WHERE source LIKE 'client:%' AND request_fingerprint IS NOT NULL AND outcome IS NOT NULL AND jsonb_typeof(outcome) = 'object' AND outcome ? 'value' AND claimed_at < $1
     ORDER BY claimed_at, source, event_id LIMIT $2 FOR UPDATE SKIP LOCKED
@@ -34,6 +35,6 @@ RETURNING claims.event_id
 SELECT count(*)::int AS deleted_count FROM deleted`
 
 /** Imports an already completed legacy operation without replacing a key another migration has already transferred. */
-export const BACKFILL_CLIENT_OUTCOME = sql`INSERT INTO inbox_claims (source, event_id, request_fingerprint, claimed_at, outcome)
+export const BACKFILL_CLIENT_OUTCOME: SqlText = sql`INSERT INTO inbox_claims (source, event_id, request_fingerprint, claimed_at, outcome)
 VALUES ($1, $2, $3, $4, $5::jsonb)
 ON CONFLICT (source, event_id) DO NOTHING`

package/templates/be/patterns/jobs/job.module-definition.ts.tpl

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { @@Job@@Options } from "./@@job@@.options"
 
+const built = new ConfigurableModuleBuilder<@@Job@@Options>().setClassMethodName("register").build()
+type Host = ConfigurableModuleHost<@@Job@@Options, "register", "create", {}>
+
 /** The configurable-module base of the @@job@@ module. */
-export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
-    new ConfigurableModuleBuilder<@@Job@@Options>().setClassMethodName("register").build()
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The injection token of the registered options. */
+export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

package/templates/be/patterns/jobs/job.processor.ts.tpl

@@ -7,7 +7,7 @@ import { @@Step@@Step } from "../../steps/@@step@@.step"
 @Injectable()
 /** The processor of the @@job@@ job: the runner claims and settles, `process` runs the steps in order. */
 export class @@Job@@Processor extends FencedProcessor {
-    readonly queue = @@jobUpper@@_QUEUE
+    readonly queue: string = @@jobUpper@@_QUEUE
 
     constructor(private readonly @@stepCamel@@Step: @@Step@@Step) {
         super()

package/templates/be/patterns/jobs/job.queue.module-definition.ts.tpl

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { @@Job@@QueueOptions } from "./@@job@@-queue.options"
 
+const built = new ConfigurableModuleBuilder<@@Job@@QueueOptions>().setClassMethodName("register").build()
+type Host = ConfigurableModuleHost<@@Job@@QueueOptions, "register", "create", {}>
+
 /** The configurable-module base of the @@job@@-queue module. */
-export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
-    new ConfigurableModuleBuilder<@@Job@@QueueOptions>().setClassMethodName("register").build()
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The injection token of the registered options. */
+export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

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

@@ -1,10 +1,15 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import { JOBS_OPTIONS } from "./jobs.decorators"
 import type { JobsOptions } from "./jobs.options"
 
-/** The configurable-module base of the jobs; `isGlobal` is decided by the app root. */
-export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<JobsOptions>({
+const built = new ConfigurableModuleBuilder<JobsOptions>({
     optionsInjectionToken: JOBS_OPTIONS,
 })
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
     .build()
+type Host = ConfigurableModuleHost<JobsOptions, "register", "create", { isGlobal: boolean }>
+
+/** The configurable-module base of the jobs; `isGlobal` is decided by the app root. */
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

package/templates/be/patterns/jobs/platform/persistence.connection.ts.tpl

@@ -1,8 +1,9 @@
+import type { DatabaseConnectionOptions } from "@modules/platform/database"
 import { JobEntity } from "./entities/job.entity"
 import { CreateJobs@@epochMs13@@ } from "./migrations/@@epochMs13@@-create-jobs"
 
 /** The entities of the jobs, for every connection that runs jobs. */
-export const jobsEntities = [JobEntity]
+export const jobsEntities: DatabaseConnectionOptions["entities"] = [JobEntity]
 
 /** The migrations of the jobs, in the order they run. */
-export const jobsMigrations = [CreateJobs@@epochMs13@@]
+export const jobsMigrations: DatabaseConnectionOptions["migrations"] = [CreateJobs@@epochMs13@@]