@open-rlb/nestjs-amqp 2.1.1 → 2.2.0

package/schematics/nest-add/init.schema.d.ts

@@ -23,4 +23,5 @@ export interface InitOptions {
     routeQueue?: string;
     serviceName?: string;
     skills?: boolean;
+    config?: string;
 }

package/schematics/nest-add/init.schema.ts

@@ -85,4 +85,7 @@ export interface InitOptions {
    * Copy the Claude skill files into .claude/skills. Defaults to true.
    */
   skills?: boolean;
+
+  /** Path to config.yaml (default: auto-detected, typically config/config.yaml). */
+  config?: string;
 }

package/schematics/nest-add/schema.json

@@ -4,12 +4,6 @@
   "title": "Init Schema",
   "type": "object",
   "properties": {
-    "path": {
-      "type": "string",
-      "format": "path",
-      "description": "The path to create the init.",
-      "visible": false
-    },
     "project": {
       "type": "string",
       "description": "The name of the project.",
@@ -17,46 +11,13 @@
         "$source": "projectName"
       }
     },
-    "gatewayConfig": {
+    "skills": {
       "type": "boolean",
-      "description": "Create a gateway (HTTP/WebSocket) configuration. Prompted interactively when omitted; defaults to false (a plain microservice) in non-interactive runs."
-    },
-    "features": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Features to include. Gateway (gatewayConfig=true): acl, gateway-admin, route-reception. Microservice (gatewayConfig=false): auto-config-publish. Prompted interactively when omitted."
-    },
-    "exchange": {
-      "type": "string",
-      "description": "Main AMQP exchange backing the ACL / gateway-admin queues. Default: rlb."
-    },
-    "aclQueue": {
-      "type": "string",
-      "description": "Queue backing the (fixed) rlb-acl topic. Default: rlb-acl."
-    },
-    "adminQueue": {
-      "type": "string",
-      "description": "Queue backing the (fixed) rlb-gateway-admin topic. Default: rlb-gateway-admin."
+      "description": "Copy the Claude skills / project docs into .claude/skills. Prompted when omitted; defaults to true."
     },
-    "controlTopic": {
+    "config": {
       "type": "string",
-      "description": "Broadcast control/reload topic name. Default: rlb-gateway-control."
-    },
-    "routeExchange": {
-      "type": "string",
-      "description": "Route auto-discovery fanout exchange (must match between publisher and gateway). Default: rlb-route-discovery."
-    },
-    "routeQueue": {
-      "type": "string",
-      "description": "Route-sync durable queue (gateway consumer side). Default: rlb-route-sync."
-    },
-    "serviceName": {
-      "type": "string",
-      "description": "Service name used for route auto-publish (route ownership + AMQP connection_name). Default: the project name."
-    },
-    "skills": {
-      "type": "boolean",
-      "description": "Copy the Claude skill files into .claude/skills. Prompted when omitted; defaults to true."
+      "description": "Path to config.yaml (default: auto-detected, typically config/config.yaml)."
     }
   }
 }

package/schematics/set-connection-name/index.d.ts

@@ -0,0 +1,3 @@
+import { Rule } from '@angular-devkit/schematics';
+import { SetConnectionNameOptions } from './schema';
+export declare function main(options: SetConnectionNameOptions): Rule;

package/schematics/set-connection-name/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const schematic_prompt_util_1 = require("../utils/schematic-prompt.util");
+const yaml_config_util_1 = require("../utils/yaml-config.util");
+const CONNECTION_NAME_PATH = [
+    'broker',
+    'connectionManagerOptions',
+    'connectionOptions',
+    'clientProperties',
+    'connection_name',
+];
+function main(options) {
+    return async (tree, context) => {
+        const flagsProvided = options.name !== undefined;
+        const prompts = (0, schematic_prompt_util_1.loadPrompts)(context, flagsProvided);
+        const raw = options.name || (await (0, schematic_prompt_util_1.askText)(prompts, 'Logical connection name?', ''));
+        const name = raw.trim();
+        if (!name) {
+            context.logger.error('[rlb-amqp] set-connection-name: a name is required.');
+            return tree;
+        }
+        const configPath = (0, yaml_config_util_1.findConfigYaml)(tree, options.config);
+        const { doc, existed } = (0, yaml_config_util_1.readConfigDoc)(tree, configPath);
+        if (!existed)
+            context.logger.info(`[rlb-amqp] ${configPath} not found — creating it.`);
+        const outcome = (0, yaml_config_util_1.setIn)(doc, CONNECTION_NAME_PATH, name);
+        (0, schematic_prompt_util_1.logOutcome)(context, `connection_name '${name}'`, outcome);
+        context.logger.info('[rlb-amqp] logical name; the library appends -hostname-pid per instance.');
+        (0, yaml_config_util_1.writeConfigDoc)(tree, configPath, doc);
+        return tree;
+    };
+}
+//# sourceMappingURL=index.js.map

package/schematics/set-connection-name/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../libs/rlb-nestjs-amqp/src/schematics/set-connection-name/index.ts"],"names":[],"mappings":";;AAkBA,oBAuBC;AAxCD,0EAAkF;AAClF,gEAAiG;AAGjG,MAAM,oBAAoB,GAAG;IAC3B,QAAQ;IACR,0BAA0B;IAC1B,mBAAmB;IACnB,kBAAkB;IAClB,iBAAiB;CAClB,CAAC;AAOF,SAAgB,IAAI,CAAC,OAAiC;IACpD,OAAO,KAAK,EAAE,IAAU,EAAE,OAAyB,EAAE,EAAE;QACrD,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC;QACjD,MAAM,OAAO,GAAG,IAAA,mCAAW,EAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAEpD,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,MAAM,IAAA,+BAAO,EAAC,OAAO,EAAE,0BAA0B,EAAE,EAAE,CAAC,CAAC,CAAC;QACrF,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;YAC5E,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,UAAU,GAAG,IAAA,iCAAc,EAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACxD,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,IAAA,gCAAa,EAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,UAAU,2BAA2B,CAAC,CAAC;QAEvF,MAAM,OAAO,GAAG,IAAA,wBAAK,EAAC,GAAG,EAAE,oBAAoB,EAAE,IAAI,CAAC,CAAC;QACvD,IAAA,kCAAU,EAAC,OAAO,EAAE,oBAAoB,IAAI,GAAG,EAAE,OAAO,CAAC,CAAC;QAC1D,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,0EAA0E,CAAC,CAAC;QAEhG,IAAA,iCAAc,EAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC"}

package/schematics/set-connection-name/index.spec.ts

@@ -0,0 +1,48 @@
+import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
+import { parseDocument } from 'yaml';
+import { main } from './index';
+import { SetConnectionNameOptions } from './schema';
+
+/** Invoke the factory Rule directly (SchematicTestRunner eagerly loads ESM `ora`). */
+const ctx = { logger: { info() {}, warn() {}, error() {} } } as unknown as SchematicContext;
+
+async function run(options: SetConnectionNameOptions, tree: Tree): Promise<Tree> {
+  const rule = main(options) as Rule;
+  const result = await (rule as (t: Tree, c: SchematicContext) => Promise<Tree>)(tree, ctx);
+  return result || tree;
+}
+
+function read(tree: Tree, path = 'config/config.yaml'): string {
+  return tree.read(path)!.toString('utf-8');
+}
+function doc(tree: Tree) {
+  return parseDocument(read(tree));
+}
+const PATH = ['broker', 'connectionManagerOptions', 'connectionOptions', 'clientProperties', 'connection_name'];
+
+function seedConfig(): Tree {
+  const tree = Tree.empty();
+  tree.create('config/config.yaml', ['# my config', 'broker:', '  uri: amqp://localhost', 'topics: []', ''].join('\n'));
+  return tree;
+}
+
+describe('set-connection-name schematic', () => {
+  it('sets the nested connection_name, trimming but not normalizing', async () => {
+    const tree = await run({ name: '  My Service  ' }, seedConfig());
+    expect(String(doc(tree).getIn(PATH))).toBe('My Service');
+    expect(read(tree)).toContain('# my config');
+  });
+
+  it('is idempotent: re-running with the same value leaves the file unchanged', async () => {
+    let tree = await run({ name: 'my-service' }, seedConfig());
+    const first = read(tree);
+    tree = await run({ name: 'my-service' }, tree);
+    expect(read(tree)).toBe(first);
+  });
+
+  it('creates the full nested path when missing', async () => {
+    const tree = await run({ name: 'gateway' }, Tree.empty());
+    expect(tree.exists('config/config.yaml')).toBe(true);
+    expect(String(doc(tree).getIn(PATH))).toBe('gateway');
+  });
+});

package/schematics/set-connection-name/index.ts

@@ -0,0 +1,42 @@
+import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
+import { askText, loadPrompts, logOutcome } from '../utils/schematic-prompt.util';
+import { findConfigYaml, readConfigDoc, setIn, writeConfigDoc } from '../utils/yaml-config.util';
+import { SetConnectionNameOptions } from './schema';
+
+const CONNECTION_NAME_PATH = [
+  'broker',
+  'connectionManagerOptions',
+  'connectionOptions',
+  'clientProperties',
+  'connection_name',
+];
+
+/**
+ * `set-connection-name` — set the LOGICAL connection_name. In 2.1.x the library auto-appends
+ * `-<hostname>-<pid>` per instance, so replicas can share one config while still showing up
+ * distinctly in the broker. The name is trimmed but intentionally NOT kebab-normalized.
+ */
+export function main(options: SetConnectionNameOptions): Rule {
+  return async (tree: Tree, context: SchematicContext) => {
+    const flagsProvided = options.name !== undefined;
+    const prompts = loadPrompts(context, flagsProvided);
+
+    const raw = options.name || (await askText(prompts, 'Logical connection name?', ''));
+    const name = raw.trim();
+    if (!name) {
+      context.logger.error('[rlb-amqp] set-connection-name: a name is required.');
+      return tree;
+    }
+
+    const configPath = findConfigYaml(tree, options.config);
+    const { doc, existed } = readConfigDoc(tree, configPath);
+    if (!existed) context.logger.info(`[rlb-amqp] ${configPath} not found — creating it.`);
+
+    const outcome = setIn(doc, CONNECTION_NAME_PATH, name);
+    logOutcome(context, `connection_name '${name}'`, outcome);
+    context.logger.info('[rlb-amqp] logical name; the library appends -hostname-pid per instance.');
+
+    writeConfigDoc(tree, configPath, doc);
+    return tree;
+  };
+}

package/schematics/set-connection-name/schema.d.ts

@@ -0,0 +1,5 @@
+export interface SetConnectionNameOptions {
+    name?: string;
+    overwrite?: boolean;
+    config?: string;
+}

package/schematics/set-connection-name/schema.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=schema.js.map

package/schematics/set-connection-name/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../libs/rlb-nestjs-amqp/src/schematics/set-connection-name/schema.ts"],"names":[],"mappings":""}

package/schematics/set-connection-name/schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "SchematicsRlbAmqpSetConnectionName",
+  "title": "Set the logical AMQP connection_name in config.yaml",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The logical connection name (trimmed; the library appends -hostname-pid per instance).",
+      "x-prompt": "Logical connection name?",
+      "$default": { "$source": "argv", "index": 0 }
+    },
+    "overwrite": {
+      "type": "boolean",
+      "default": false,
+      "description": "Update the value if it already exists."
+    },
+    "config": {
+      "type": "string",
+      "description": "Path to config.yaml (default: auto-detected)."
+    }
+  },
+  "required": []
+}

package/schematics/set-connection-name/schema.ts

@@ -0,0 +1,8 @@
+export interface SetConnectionNameOptions {
+  /** The LOGICAL connection name. Trimmed but NOT kebab-normalized. Prompted when omitted. */
+  name?: string;
+  /** Update the value when it already exists (default: leave it untouched). */
+  overwrite?: boolean;
+  /** Path to config.yaml (default: auto-detected, typically config/config.yaml). */
+  config?: string;
+}

package/schematics/utils/broker-yaml.util.d.ts

@@ -0,0 +1,53 @@
+import { Document } from 'yaml';
+import { UpsertOptions, UpsertOutcome } from './yaml-config.util';
+export type ExchangeType = 'direct' | 'topic' | 'fanout' | 'headers';
+export type TopicMode = 'rpc' | 'handle' | 'broadcast' | 'event';
+export declare function exchangeExists(doc: Document, name: string): boolean;
+export declare function queueExists(doc: Document, name: string): boolean;
+export declare function topicExists(doc: Document, name: string): boolean;
+export declare function getExchangeType(doc: Document, name: string): ExchangeType | undefined;
+export interface ExchangeSpec {
+    name: string;
+    type?: ExchangeType;
+    createExchangeIfNotExists?: boolean;
+    durable?: boolean;
+    autoDelete?: boolean;
+    internal?: boolean;
+}
+export declare function ensureExchange(doc: Document, spec: ExchangeSpec, opts?: UpsertOptions): UpsertOutcome;
+export interface QueueSpec {
+    name: string;
+    exchange: string;
+    routingKey?: string | string[];
+    createQueueIfNotExists?: boolean;
+    durable?: boolean;
+    exclusive?: boolean;
+    autoDelete?: boolean;
+    messageTtl?: number;
+    maxLength?: number;
+    expires?: number;
+}
+export declare function ensureQueue(doc: Document, spec: QueueSpec, opts?: UpsertOptions): UpsertOutcome;
+export interface RetrySpec {
+    maxAttempts?: number;
+    delayMs?: number;
+    onExhausted?: 'dead-letter' | 'drop';
+    deadLetter?: {
+        exchange: string;
+        routingKey?: string;
+    };
+}
+export interface TopicSpec {
+    name: string;
+    mode: TopicMode;
+    queue?: string;
+    exchange?: string;
+    routingKey?: string | string[];
+    errorBehavior?: 'ack' | 'nack' | 'requeue';
+    retry?: RetrySpec;
+    mandatory?: boolean;
+    persistent?: boolean;
+    toObservable?: boolean;
+}
+export declare function ensureTopic(doc: Document, spec: TopicSpec, opts?: UpsertOptions): UpsertOutcome;
+export declare function routingKeyRequired(doc: Document, exchangeName: string): boolean;

package/schematics/utils/broker-yaml.util.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exchangeExists = exchangeExists;
+exports.queueExists = queueExists;
+exports.topicExists = topicExists;
+exports.getExchangeType = getExchangeType;
+exports.ensureExchange = ensureExchange;
+exports.ensureQueue = ensureQueue;
+exports.ensureTopic = ensureTopic;
+exports.routingKeyRequired = routingKeyRequired;
+const yaml_config_util_1 = require("./yaml-config.util");
+const EXCHANGES = ['broker', 'exchanges'];
+const QUEUES = ['broker', 'queues'];
+const TOPICS = ['topics'];
+function exchangeExists(doc, name) {
+    return (0, yaml_config_util_1.seqItemExists)(doc, EXCHANGES, 'name', name);
+}
+function queueExists(doc, name) {
+    return (0, yaml_config_util_1.seqItemExists)(doc, QUEUES, 'name', name);
+}
+function topicExists(doc, name) {
+    return (0, yaml_config_util_1.seqItemExists)(doc, TOPICS, 'name', name);
+}
+function getExchangeType(doc, name) {
+    const item = (0, yaml_config_util_1.findSeqItemByKey)(doc, EXCHANGES, 'name', name);
+    return item ? item.get('type') : undefined;
+}
+function ensureExchange(doc, spec, opts = {}) {
+    const options = pruneEmpty({
+        durable: spec.durable,
+        autoDelete: spec.autoDelete,
+        internal: spec.internal,
+    });
+    return (0, yaml_config_util_1.upsertSeqItemByKey)(doc, EXCHANGES, 'name', {
+        name: spec.name,
+        type: spec.type ?? 'direct',
+        createExchangeIfNotExists: spec.createExchangeIfNotExists ?? true,
+        ...(options ? { options } : {}),
+    }, opts);
+}
+function ensureQueue(doc, spec, opts = {}) {
+    const options = pruneEmpty({
+        durable: spec.durable,
+        exclusive: spec.exclusive,
+        autoDelete: spec.autoDelete,
+        messageTtl: spec.messageTtl,
+        maxLength: spec.maxLength,
+        expires: spec.expires,
+    });
+    return (0, yaml_config_util_1.upsertSeqItemByKey)(doc, QUEUES, 'name', {
+        name: spec.name,
+        exchange: spec.exchange,
+        routingKey: spec.routingKey,
+        createQueueIfNotExists: spec.createQueueIfNotExists ?? true,
+        ...(options ? { options } : {}),
+    }, opts);
+}
+function ensureTopic(doc, spec, opts = {}) {
+    const retry = spec.retry
+        ? pruneEmpty({
+            maxAttempts: spec.retry.maxAttempts,
+            delayMs: spec.retry.delayMs,
+            onExhausted: spec.retry.onExhausted,
+            deadLetter: spec.retry.deadLetter,
+        })
+        : undefined;
+    return (0, yaml_config_util_1.upsertSeqItemByKey)(doc, TOPICS, 'name', {
+        name: spec.name,
+        mode: spec.mode,
+        queue: spec.queue,
+        exchange: spec.exchange,
+        routingKey: spec.routingKey,
+        errorBehavior: spec.errorBehavior,
+        retry,
+        mandatory: spec.mandatory,
+        persistent: spec.persistent,
+        toObservable: spec.toObservable,
+    }, opts);
+}
+function routingKeyRequired(doc, exchangeName) {
+    return getExchangeType(doc, exchangeName) === 'topic';
+}
+function pruneEmpty(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+//# sourceMappingURL=broker-yaml.util.js.map

package/schematics/utils/broker-yaml.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker-yaml.util.js","sourceRoot":"","sources":["../../../libs/rlb-nestjs-amqp/src/schematics/utils/broker-yaml.util.ts"],"names":[],"mappings":"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"}

package/schematics/utils/broker-yaml.util.ts

@@ -0,0 +1,172 @@
+import { Document } from 'yaml';
+import {
+  findSeqItemByKey,
+  seqItemExists,
+  upsertSeqItemByKey,
+  UpsertOptions,
+  UpsertOutcome,
+} from './yaml-config.util';
+
+/**
+ * Domain helpers for the `broker` section, layered on the generic YAML upsert. They encode the
+ * cross-reference invariants the gotchas warn about (exchange type ⇒ routingKey required, topic
+ * needs a queue for rpc/handle, dead-letter exchange must be declared, …) so each schematic's
+ * index.ts stays a thin "read doc → ensureX → write doc".
+ */
+
+export type ExchangeType = 'direct' | 'topic' | 'fanout' | 'headers';
+export type TopicMode = 'rpc' | 'handle' | 'broadcast' | 'event';
+
+const EXCHANGES = ['broker', 'exchanges'];
+const QUEUES = ['broker', 'queues'];
+const TOPICS = ['topics'];
+
+// --- existence / lookups ----------------------------------------------------
+
+export function exchangeExists(doc: Document, name: string): boolean {
+  return seqItemExists(doc, EXCHANGES, 'name', name);
+}
+export function queueExists(doc: Document, name: string): boolean {
+  return seqItemExists(doc, QUEUES, 'name', name);
+}
+export function topicExists(doc: Document, name: string): boolean {
+  return seqItemExists(doc, TOPICS, 'name', name);
+}
+
+/** The declared type of an exchange (used to decide whether a queue/topic needs a routingKey). */
+export function getExchangeType(doc: Document, name: string): ExchangeType | undefined {
+  const item = findSeqItemByKey(doc, EXCHANGES, 'name', name);
+  return item ? (item.get('type') as ExchangeType | undefined) : undefined;
+}
+
+// --- ensure (idempotent upsert) --------------------------------------------
+
+export interface ExchangeSpec {
+  name: string;
+  type?: ExchangeType;
+  createExchangeIfNotExists?: boolean;
+  durable?: boolean;
+  autoDelete?: boolean;
+  internal?: boolean;
+}
+
+export function ensureExchange(doc: Document, spec: ExchangeSpec, opts: UpsertOptions = {}): UpsertOutcome {
+  const options = pruneEmpty({
+    durable: spec.durable,
+    autoDelete: spec.autoDelete,
+    internal: spec.internal,
+  });
+  return upsertSeqItemByKey(
+    doc,
+    EXCHANGES,
+    'name',
+    {
+      name: spec.name,
+      type: spec.type ?? 'direct',
+      createExchangeIfNotExists: spec.createExchangeIfNotExists ?? true,
+      ...(options ? { options } : {}),
+    },
+    opts,
+  );
+}
+
+export interface QueueSpec {
+  name: string;
+  exchange: string;
+  /** Required (and only meaningful) when the exchange is a `topic` exchange. */
+  routingKey?: string | string[];
+  createQueueIfNotExists?: boolean;
+  durable?: boolean;
+  exclusive?: boolean;
+  autoDelete?: boolean;
+  /** Growth bounds (2.1.x hardening): message TTL / max length / unused-queue TTL, all in the queue options. */
+  messageTtl?: number;
+  maxLength?: number;
+  expires?: number;
+}
+
+export function ensureQueue(doc: Document, spec: QueueSpec, opts: UpsertOptions = {}): UpsertOutcome {
+  const options = pruneEmpty({
+    durable: spec.durable,
+    exclusive: spec.exclusive,
+    autoDelete: spec.autoDelete,
+    messageTtl: spec.messageTtl,
+    maxLength: spec.maxLength,
+    expires: spec.expires,
+  });
+  return upsertSeqItemByKey(
+    doc,
+    QUEUES,
+    'name',
+    {
+      name: spec.name,
+      exchange: spec.exchange,
+      routingKey: spec.routingKey,
+      createQueueIfNotExists: spec.createQueueIfNotExists ?? true,
+      ...(options ? { options } : {}),
+    },
+    opts,
+  );
+}
+
+export interface RetrySpec {
+  maxAttempts?: number;
+  delayMs?: number;
+  onExhausted?: 'dead-letter' | 'drop';
+  deadLetter?: { exchange: string; routingKey?: string };
+}
+
+export interface TopicSpec {
+  name: string;
+  mode: TopicMode;
+  queue?: string;
+  exchange?: string;
+  routingKey?: string | string[];
+  errorBehavior?: 'ack' | 'nack' | 'requeue';
+  retry?: RetrySpec;
+  mandatory?: boolean;
+  persistent?: boolean;
+  toObservable?: boolean;
+}
+
+export function ensureTopic(doc: Document, spec: TopicSpec, opts: UpsertOptions = {}): UpsertOutcome {
+  const retry = spec.retry
+    ? pruneEmpty({
+        maxAttempts: spec.retry.maxAttempts,
+        delayMs: spec.retry.delayMs,
+        onExhausted: spec.retry.onExhausted,
+        deadLetter: spec.retry.deadLetter,
+      })
+    : undefined;
+  return upsertSeqItemByKey(
+    doc,
+    TOPICS,
+    'name',
+    {
+      name: spec.name,
+      mode: spec.mode,
+      queue: spec.queue,
+      exchange: spec.exchange,
+      routingKey: spec.routingKey,
+      errorBehavior: spec.errorBehavior,
+      retry,
+      mandatory: spec.mandatory,
+      persistent: spec.persistent,
+      toObservable: spec.toObservable,
+    },
+    opts,
+  );
+}
+
+/** `true` when the exchange is a topic exchange, so a bound queue/topic MUST carry a routingKey. */
+export function routingKeyRequired(doc: Document, exchangeName: string): boolean {
+  return getExchangeType(doc, exchangeName) === 'topic';
+}
+
+function pruneEmpty<T extends Record<string, unknown>>(obj: T): T | undefined {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return Object.keys(out).length ? (out as T) : undefined;
+}

package/schematics/utils/nest-wiring.util.d.ts

@@ -0,0 +1,30 @@
+import { Tree } from '@angular-devkit/schematics';
+export declare function findFileInTree(tree: Tree, fileName: string): string | undefined;
+export declare function findAppModule(tree: Tree): string | undefined;
+export declare function findMainTs(tree: Tree): string | undefined;
+export declare function ensureLibImport(source: string, symbols: string[]): string;
+export declare function ensureImportLine(source: string, line: string, marker: string): string;
+export declare function insertIntoImportsArray(source: string, moduleEntry: string): string;
+export interface WireEntry {
+    code: string;
+    sentinel: string;
+}
+export interface WireAppModuleOptions {
+    libSymbols: string[];
+    importLines?: {
+        line: string;
+        marker: string;
+    }[];
+    entries: WireEntry[];
+}
+export declare function wireAppModule(tree: Tree, opts: WireAppModuleOptions): string | undefined;
+export declare function coreLibSymbols(): string[];
+export declare function coreImportLines(): {
+    line: string;
+    marker: string;
+}[];
+export declare function configModuleEntry(): WireEntry;
+export declare function brokerModuleEntry(): WireEntry;
+export declare function createConfigLoader(tree: Tree): void;
+export declare function configureMainForGateway(tree: Tree): boolean;
+export declare function addDeps(tree: Tree, deps: Record<string, string>): void;