@zdavison/matador 3.0.8 → 4.0.1

package/dist/topology/builder.d.ts

@@ -1,5 +1,5 @@
 import type { HasDescription } from '../errors/index.js';
-import type { DeadLetterConfig, QueueDefinition, RetryConfig, Topology } from './types.js';
+import type { DeadLetterConfig, QueueDefinition, ResourcePrefix, RetryConfig, Topology, TopologyNaming } from './types.js';
 /**
  * Options for adding a queue.
  * Excludes 'name' as that is provided as the first argument to addQueue.
@@ -25,10 +25,37 @@ export declare class TopologyBuilder {
     private queues;
     private deadLetter;
     private retry;
+    private naming;
+    private prefix;
     /**
      * Sets the namespace prefix for all queues.
      */
     withNamespace(namespace: string): this;
+    /**
+     * Sets the prefix prepended to every default-derived broker resource name
+     * (e.g. `matador.{namespace}.{queue}`), so Matador-managed queues and
+     * exchanges are identifiable. Pass `null` to disable prefixing.
+     *
+     * Only applies to default names — a {@link withNaming} override fully owns
+     * its output and is never prefixed.
+     *
+     * Pass `null` or `undefined` to disable prefixing.
+     *
+     * @default 'matador'
+     * @example
+     * TopologyBuilder.create().withNamespace('myapp')            // matador.myapp.events
+     * TopologyBuilder.create().withNamespace('myapp').withGlobalPrefix('acme')  // acme.myapp.events
+     * TopologyBuilder.create().withNamespace('myapp').withGlobalPrefix(null)    // myapp.events
+     */
+    withGlobalPrefix(prefix: ResourcePrefix): this;
+    /**
+     * Overrides how broker resource names are derived.
+     * Use during migrations to keep pre-existing queue/exchange names so a
+     * rolling deploy keeps routing through the resources already declared on
+     * the broker.
+     * @see TopologyNaming
+     */
+    withNaming(naming: TopologyNaming): this;
     /**
      * Adds a queue to the topology.
      * @param definition - A complete QueueDefinition object

package/dist/topology/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/topology/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AAWzD;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAM,YAAW,cAAc;aASxD,MAAM,EAAE,SAAS,MAAM,EAAE;IAR3C,QAAQ,CAAC,WAAW,SAIuC;gBAGzD,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,SAAS,MAAM,EAAE;CAK5C;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,MAAM,CAAC,MAAM,IAAI,eAAe;IAIhC,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,UAAU,CAGhB;IACF,OAAO,CAAC,KAAK,CAIX;IAEF;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKtC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAapD;;;OAGG;IACH,KAAK,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IACxC;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAWjD;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAQvD;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAS7C;;OAEG;IACH,YAAY,IAAI,IAAI;IAKpB;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAQzB;;OAEG;IACH,QAAQ,IAAI,SAAS,MAAM,EAAE;IAQ7B;;;OAGG;IACH,KAAK,IAAI,QAAQ;CAgBlB"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/topology/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,WAAW,EACX,QAAQ,EACR,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AAWzD;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAM,YAAW,cAAc;aASxD,MAAM,EAAE,SAAS,MAAM,EAAE;IAR3C,QAAQ,CAAC,WAAW,SAIuC;gBAGzD,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,SAAS,MAAM,EAAE;CAK5C;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,MAAM,CAAC,MAAM,IAAI,eAAe;IAIhC,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,UAAU,CAGhB;IACF,OAAO,CAAC,KAAK,CAIX;IACF,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,MAAM,CAA6B;IAE3C;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKtC;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAK9C;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKxC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAapD;;;OAGG;IACH,KAAK,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IACxC;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAWjD;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAQvD;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAS7C;;OAEG;IACH,YAAY,IAAI,IAAI;IAKpB;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAQzB;;OAEG;IACH,QAAQ,IAAI,SAAS,MAAM,EAAE;IAU7B;;;OAGG;IACH,KAAK,IAAI,QAAQ;CAkBlB"}

package/dist/topology/builder.js

@@ -40,6 +40,8 @@ export class TopologyBuilder {
         defaultDelayMs: 1000,
         maxDelayMs: 300000, // 5 minutes
     };
+    naming;
+    prefix = 'matador';
     /**
      * Sets the namespace prefix for all queues.
      */
@@ -47,6 +49,37 @@ export class TopologyBuilder {
         this.namespace = namespace;
         return this;
     }
+    /**
+     * Sets the prefix prepended to every default-derived broker resource name
+     * (e.g. `matador.{namespace}.{queue}`), so Matador-managed queues and
+     * exchanges are identifiable. Pass `null` to disable prefixing.
+     *
+     * Only applies to default names — a {@link withNaming} override fully owns
+     * its output and is never prefixed.
+     *
+     * Pass `null` or `undefined` to disable prefixing.
+     *
+     * @default 'matador'
+     * @example
+     * TopologyBuilder.create().withNamespace('myapp')            // matador.myapp.events
+     * TopologyBuilder.create().withNamespace('myapp').withGlobalPrefix('acme')  // acme.myapp.events
+     * TopologyBuilder.create().withNamespace('myapp').withGlobalPrefix(null)    // myapp.events
+     */
+    withGlobalPrefix(prefix) {
+        this.prefix = prefix;
+        return this;
+    }
+    /**
+     * Overrides how broker resource names are derived.
+     * Use during migrations to keep pre-existing queue/exchange names so a
+     * rolling deploy keeps routing through the resources already declared on
+     * the broker.
+     * @see TopologyNaming
+     */
+    withNaming(naming) {
+        this.naming = naming;
+        return this;
+    }
     addQueue(nameOrDefinition, options = {}) {
         if (isQueueDefinition(nameOrDefinition)) {
             this.queues.push(nameOrDefinition);
@@ -106,8 +139,10 @@ export class TopologyBuilder {
     validate() {
         return [
             ...validateNamespace(this.namespace),
+            ...validatePrefix(this.prefix),
             ...validateQueues(this.queues),
             ...validateRetry(this.retry),
+            ...validateNaming(this.naming),
         ];
     }
     /**
@@ -124,6 +159,8 @@ export class TopologyBuilder {
             queues: [...this.queues],
             deadLetter: this.deadLetter,
             retry: this.retry,
+            naming: this.naming,
+            prefix: this.prefix,
         };
     }
 }
@@ -139,6 +176,21 @@ function validateNamespace(namespace) {
     }
     return [];
 }
+function validatePrefix(prefix) {
+    // null/undefined explicitly disable prefixing.
+    if (prefix == null) {
+        return [];
+    }
+    if (prefix.trim() === '') {
+        return ['Prefix must be a non-empty string, or null to disable prefixing'];
+    }
+    if (!IDENTIFIER_PATTERN.test(prefix)) {
+        return [
+            'Prefix must start with a letter and contain only alphanumeric characters, underscores, and hyphens',
+        ];
+    }
+    return [];
+}
 function validateQueueName(queue, seen) {
     if (!queue.name || queue.name.trim() === '') {
         return ['Queue name cannot be empty'];
@@ -176,6 +228,28 @@ function validateQueues(queues) {
     }
     return issues;
 }
+function validateNaming(naming) {
+    if (!naming)
+        return [];
+    const issues = [];
+    for (const field of [
+        'queue',
+        'mainExchange',
+        'dlxExchange',
+        'delayedExchange',
+    ]) {
+        const value = naming[field];
+        if (value !== undefined && typeof value !== 'function') {
+            issues.push(`Naming override "${field}" must be a function`);
+        }
+    }
+    if (naming.dlxExchangeType !== undefined &&
+        naming.dlxExchangeType !== 'direct' &&
+        naming.dlxExchangeType !== 'topic') {
+        issues.push(`Naming override "dlxExchangeType" must be 'direct' or 'topic'`);
+    }
+    return issues;
+}
 function validateRetry(retry) {
     if (!retry.enabled)
         return [];

package/dist/topology/builder.test.js

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'bun:test';
+import { UnknownQueueReferenceError } from '../errors/matador-errors.js';
 import { TopologyBuilder, TopologyValidationError } from './builder.js';
-import { resolveQueueName } from './types.js';
+import { findQueueDefinition, getDeadLetterQueueName, getQualifiedQueueName, getRetryQueueName, resolveQueueName, resolveTargetQueueName, } from './types.js';
 describe('TopologyBuilder', () => {
     describe('withNamespace', () => {
         it('should set the namespace', () => {
@@ -358,3 +359,189 @@ describe('resolveQueueName', () => {
         expect(resolveQueueName('myapp', queueDef)).toBe('matador.shared.id-platform');
     });
 });
+describe('TopologyNaming', () => {
+    const v1Naming = {
+        queue: (ns, q) => `matador.${ns}.${q}`,
+        mainExchange: (ns) => `matador.${ns}`,
+        dlxExchange: (ns) => `matador.${ns}.dlx-undeliverable`,
+        dlxExchangeType: 'topic',
+        delayedExchange: (ns) => `matador.${ns}.delayed`,
+    };
+    describe('builder validation', () => {
+        it('should accept a valid naming configuration', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withNaming(v1Naming)
+                .addQueue('events')
+                .build();
+            expect(topology.naming?.queue?.('myapp', 'events')).toBe('matador.myapp.events');
+            expect(topology.naming?.mainExchange?.('myapp')).toBe('matador.myapp');
+        });
+        it('should accept partial naming overrides', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withNaming({ queue: (ns, q) => `legacy.matador.${ns}.${q}` })
+                .addQueue('events')
+                .build();
+            expect(topology.naming?.queue?.('myapp', 'events')).toBe('legacy.matador.myapp.events');
+        });
+        it('should reject a non-function naming override', () => {
+            expect(() => TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withNaming({ queue: 'matador.' })
+                .addQueue('events')
+                .build()).toThrow(TopologyValidationError);
+        });
+        it('should reject an invalid dlxExchangeType', () => {
+            expect(() => TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withNaming({
+                dlxExchangeType: 'fanout',
+            })
+                .addQueue('events')
+                .build()).toThrow(TopologyValidationError);
+        });
+    });
+    describe('name resolution with naming overrides', () => {
+        const topology = TopologyBuilder.create()
+            .withNamespace('myapp')
+            .withNaming({ queue: (ns, q) => `matador.${ns}.${q}` })
+            .addQueue('events')
+            .addQueue({
+            name: 'matador.shared.id-platform',
+            exact: true,
+        })
+            .build();
+        it('should build qualified queue names via the strategy', () => {
+            expect(getQualifiedQueueName('myapp', 'events', topology.naming)).toBe('matador.myapp.events');
+        });
+        it('should build resolved queue definitions via the strategy', () => {
+            const queueDef = { name: 'events' };
+            expect(resolveQueueName('myapp', queueDef, topology.naming)).toBe('matador.myapp.events');
+        });
+        it('should not transform exact queue definitions', () => {
+            const queueDef = { name: 'matador.shared.id-platform', exact: true };
+            expect(resolveQueueName('myapp', queueDef, topology.naming)).toBe('matador.shared.id-platform');
+        });
+        it('should resolve a target queue by exact name as-is', () => {
+            expect(resolveTargetQueueName(topology, 'matador.shared.id-platform')).toBe('matador.shared.id-platform');
+        });
+        it('should build non-exact target queues via the strategy', () => {
+            expect(resolveTargetQueueName(topology, 'events')).toBe('matador.myapp.events');
+        });
+        it('should derive retry and DLQ names from the strategy name', () => {
+            expect(getRetryQueueName('myapp', 'events', topology.naming)).toBe('matador.myapp.events.retry');
+            expect(getDeadLetterQueueName('myapp', 'events', 'unhandled', topology.naming)).toBe('matador.myapp.events.unhandled');
+        });
+        it('should find queue definitions by name', () => {
+            expect(findQueueDefinition(topology, 'events')?.name).toBe('events');
+            expect(findQueueDefinition(topology, 'matador.shared.id-platform')?.name).toBe('matador.shared.id-platform');
+            expect(findQueueDefinition(topology, 'missing')).toBeUndefined();
+        });
+        it('should throw for a queue reference not declared in the topology', () => {
+            // A targetQueue/consumeFrom name that was never added to the topology
+            // must fail loudly rather than be silently namespace-qualified and
+            // routed to a queue nobody consumes.
+            expect(() => resolveTargetQueueName(topology, 'ext-service.payments')).toThrow(UnknownQueueReferenceError);
+        });
+    });
+});
+describe('resource name prefix', () => {
+    describe('default', () => {
+        it('prefixes resource names with "matador" by default', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('myapp')
+                .addQueue('events')
+                .build();
+            expect(topology.prefix).toBe('matador');
+            expect(resolveTargetQueueName(topology, 'events')).toBe('matador.myapp.events');
+        });
+        it('inherits the default prefix into retry and DLQ names', () => {
+            expect(getRetryQueueName('myapp', 'events', undefined, 'matador')).toBe('matador.myapp.events.retry');
+            expect(getDeadLetterQueueName('myapp', 'events', 'unhandled', undefined, 'matador')).toBe('matador.myapp.events.unhandled');
+        });
+    });
+    describe('withGlobalPrefix', () => {
+        it('uses a custom prefix string', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withGlobalPrefix('acme')
+                .addQueue('events')
+                .build();
+            expect(topology.prefix).toBe('acme');
+            expect(resolveTargetQueueName(topology, 'events')).toBe('acme.myapp.events');
+        });
+        it('disables prefixing when set to null', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withGlobalPrefix(null)
+                .addQueue('events')
+                .build();
+            expect(topology.prefix).toBeNull();
+            expect(resolveTargetQueueName(topology, 'events')).toBe('myapp.events');
+        });
+        it('disables prefixing when set to undefined', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withGlobalPrefix(undefined)
+                .addQueue('events')
+                .build();
+            expect(topology.prefix).toBeUndefined();
+            expect(resolveTargetQueueName(topology, 'events')).toBe('myapp.events');
+        });
+    });
+    describe('helper-level prefixing', () => {
+        it('applies a non-null prefix to the default qualified name', () => {
+            expect(getQualifiedQueueName('myapp', 'events', undefined, 'acme')).toBe('acme.myapp.events');
+        });
+        it('omits the prefix when null or undefined', () => {
+            expect(getQualifiedQueueName('myapp', 'events', undefined, null)).toBe('myapp.events');
+            expect(getQualifiedQueueName('myapp', 'events', undefined, undefined)).toBe('myapp.events');
+        });
+    });
+    describe('composition with withNaming', () => {
+        it('does not prefix names produced by a withNaming override', () => {
+            const topology = TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withGlobalPrefix('matador')
+                .withNaming({ queue: (_ns, q) => `legacy-${q}` })
+                .addQueue('events')
+                .build();
+            // The override fully owns the name; the prefix is not prepended.
+            expect(resolveTargetQueueName(topology, 'events')).toBe('legacy-events');
+        });
+    });
+    describe('validation', () => {
+        it('rejects an empty-string prefix', () => {
+            expect(() => TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withGlobalPrefix('')
+                .addQueue('events')
+                .build()).toThrow(TopologyValidationError);
+        });
+        it('rejects a prefix that is not a valid identifier', () => {
+            expect(() => TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withGlobalPrefix('1bad')
+                .addQueue('events')
+                .build()).toThrow(TopologyValidationError);
+            expect(() => TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withGlobalPrefix('has space')
+                .addQueue('events')
+                .build()).toThrow(TopologyValidationError);
+        });
+        it('accepts null (no prefix) and valid identifier prefixes', () => {
+            expect(() => TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withGlobalPrefix(null)
+                .addQueue('events')
+                .build()).not.toThrow();
+            expect(() => TopologyBuilder.create()
+                .withNamespace('myapp')
+                .withGlobalPrefix('acme_co-1')
+                .addQueue('events')
+                .build()).not.toThrow();
+        });
+    });
+});

package/dist/topology/index.d.ts

@@ -1,5 +1,5 @@
-export type { DeadLetterConfig, DeadLetterQueueConfig, QueueDefinition, RabbitMQQueueDefinition, RabbitMQQueueOptions, RetryConfig, Topology, TransportQueueOptions, } from './types.js';
-export { getDeadLetterQueueName, getQualifiedQueueName, getRetryQueueName, resolveQueueName, } from './types.js';
+export type { DeadLetterConfig, DeadLetterQueueConfig, QueueDefinition, RabbitMQQueueDefinition, RabbitMQQueueOptions, ResourcePrefix, RetryConfig, Topology, TopologyNaming, TransportQueueOptions, } from './types.js';
+export { applyPrefix, findQueueDefinition, getDeadLetterQueueName, getQualifiedQueueName, getRetryQueueName, resolveQueueName, resolveTargetQueueName, } from './types.js';
 export type { QueueOptions } from './builder.js';
 export { TopologyBuilder, TopologyValidationError } from './builder.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/topology/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/topology/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,WAAW,EACX,QAAQ,EACR,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/topology/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,cAAc,EACd,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC"}

package/dist/topology/index.js

@@ -1,2 +1,2 @@
-export { getDeadLetterQueueName, getQualifiedQueueName, getRetryQueueName, resolveQueueName, } from './types.js';
+export { applyPrefix, findQueueDefinition, getDeadLetterQueueName, getQualifiedQueueName, getRetryQueueName, resolveQueueName, resolveTargetQueueName, } from './types.js';
 export { TopologyBuilder, TopologyValidationError } from './builder.js';

package/dist/topology/types.d.ts

@@ -1,3 +1,15 @@
+/**
+ * A prefix prepended to every default-derived broker resource name so
+ * Matador-managed queues and exchanges are identifiable
+ * (e.g. `matador.{namespace}.{queue}`).
+ *
+ * A string is prepended as `${prefix}.`; `null` or `undefined` disables
+ * prefixing. Only applies to default names — a {@link TopologyNaming}
+ * override fully owns its output and is never prefixed.
+ *
+ * @example 'matador'
+ */
+export type ResourcePrefix = string | null | undefined;
 /**
  * Transport-agnostic topology definition.
  * Matador owns the topology; transports translate and apply it.
@@ -11,6 +23,83 @@ export interface Topology {
     readonly deadLetter: DeadLetterConfig;
     /** Retry queue configuration */
     readonly retry: RetryConfig;
+    /**
+     * Optional overrides for how broker resource names are derived.
+     * Intended for migrations: lets an adopter keep pre-existing queue and
+     * exchange names (e.g. from Matador v1) so a rolling deploy keeps using
+     * the broker resources already in place.
+     */
+    readonly naming?: TopologyNaming | undefined;
+    /**
+     * Prefix prepended to every default-derived broker resource name so
+     * Matador-managed queues and exchanges are identifiable
+     * (e.g. `matador.{namespace}.{queue}`).
+     *
+     * `null` disables prefixing. Only applies to default names — a `naming`
+     * override fully owns its output and is never prefixed.
+     *
+     * Topologies built via {@link TopologyBuilder} default this to `'matador'`.
+     * When absent (e.g. a hand-built topology literal) no prefix is applied.
+     *
+     * @default 'matador'
+     */
+    readonly prefix?: ResourcePrefix;
+}
+/**
+ * Strategy for deriving broker resource names.
+ *
+ * Each builder receives the namespace as an explicit argument and returns the
+ * final name, so the namespace is always an input to the strategy — it is
+ * never applied separately on top of the result. Provide only the builders you
+ * want to override; the rest keep Matador's defaults:
+ *  - work queue: `${namespace}.${queueName}`
+ *  - main exchange: `${namespace}.exchange`
+ *  - dead-letter exchange: `${namespace}.dlx`
+ *  - delayed exchange: `${namespace}.delayed`
+ *
+ * Retry queues and DLQs have no builder of their own: they are derived from the
+ * work-queue name (`<queue>.retry`, `<queue>.unhandled`, `<queue>.undeliverable`),
+ * so overriding `queue` carries your prefix into them automatically.
+ *
+ * Intended for migrations: an adopter can keep pre-existing names (e.g. from
+ * Matador v1) so a rolling deploy keeps using the broker resources already in
+ * place instead of draining or dual-consuming.
+ *
+ * @example Keep Matador v1 names (`matador.{namespace}.{queue}`):
+ * ```typescript
+ * TopologyBuilder.create()
+ *   .withNamespace('myapp')
+ *   .withNaming({
+ *     queue: (ns, q) => `matador.${ns}.${q}`,
+ *     mainExchange: (ns) => `matador.${ns}`,
+ *     dlxExchange: (ns) => `matador.${ns}.dlx-undeliverable`,
+ *     dlxExchangeType: 'topic',
+ *     delayedExchange: (ns) => `matador.${ns}.delayed`,
+ *   })
+ * ```
+ */
+export interface TopologyNaming {
+    /**
+     * Builds the qualified work-queue name from the namespace and queue name.
+     * Retry queues and DLQs are derived from the result automatically
+     * (`<queue>.retry`, `<queue>.unhandled`, `<queue>.undeliverable`).
+     * Default builds `${namespace}.${queueName}`.
+     */
+    readonly queue?: ((namespace: string, queueName: string) => string) | undefined;
+    /** Builds the main exchange name. Default builds `${namespace}.exchange`. */
+    readonly mainExchange?: ((namespace: string) => string) | undefined;
+    /** Builds the dead-letter exchange name. Default builds `${namespace}.dlx`. */
+    readonly dlxExchange?: ((namespace: string) => string) | undefined;
+    /**
+     * Exchange type used when asserting the dead-letter exchange.
+     * Useful when an existing DLX was declared as `topic` — asserting it as
+     * `direct` would fail with PRECONDITION_FAILED. Literal (non-wildcard)
+     * binding keys behave identically on a topic exchange.
+     * Default: `'direct'`.
+     */
+    readonly dlxExchangeType?: 'direct' | 'topic' | undefined;
+    /** Builds the delayed-message exchange name. Default builds `${namespace}.delayed`. */
+    readonly delayedExchange?: ((namespace: string) => string) | undefined;
 }
 /**
  * Individual queue definition.
@@ -109,20 +198,45 @@ export interface RetryConfig {
     readonly maxDelayMs: number;
 }
 /**
- * Gets the fully qualified queue name with namespace prefix.
+ * Prepends a resource-name prefix unless it is disabled.
+ * `null`/`undefined` mean no prefix; a string is prepended as `${prefix}.`.
+ */
+export declare function applyPrefix(prefix: ResourcePrefix, name: string): string;
+/**
+ * Gets the fully qualified work-queue name.
+ * An optional naming strategy may override how the name is derived; otherwise
+ * the default is `${namespace}.${queueName}`, optionally prefixed.
  */
-export declare function getQualifiedQueueName(namespace: string, queueName: string): string;
+export declare function getQualifiedQueueName(namespace: string, queueName: string, naming?: TopologyNaming, prefix?: ResourcePrefix): string;
 /**
  * Gets the dead-letter queue name for a given queue.
  */
-export declare function getDeadLetterQueueName(namespace: string, queueName: string, dlqType: 'unhandled' | 'undeliverable'): string;
+export declare function getDeadLetterQueueName(namespace: string, queueName: string, dlqType: 'unhandled' | 'undeliverable', naming?: TopologyNaming, prefix?: ResourcePrefix): string;
 /**
  * Gets the retry queue name for a given queue.
  */
-export declare function getRetryQueueName(namespace: string, queueName: string): string;
+export declare function getRetryQueueName(namespace: string, queueName: string, naming?: TopologyNaming, prefix?: ResourcePrefix): string;
 /**
  * Resolves the actual queue name for a given queue definition.
- * When exact: true, returns name as-is. Otherwise, returns namespace.name.
+ * When exact: true, returns name as-is. Otherwise, returns the
+ * namespace-qualified name (honoring any naming overrides and prefix).
+ */
+export declare function resolveQueueName(namespace: string, queueDef: QueueDefinition, naming?: TopologyNaming, prefix?: ResourcePrefix): string;
+/**
+ * Finds the queue definition a local queue reference points at.
+ */
+export declare function findQueueDefinition(topology: Topology, queueName: string): QueueDefinition | undefined;
+/**
+ * Resolves a local queue reference (a subscriber's `targetQueue` or a
+ * `consumeFrom` entry) to the transport-level queue name.
+ *
+ * The reference must be declared in the topology via `.addQueue(...)`:
+ * an exact queue resolves to its name as-is; a Matador-owned queue is
+ * namespace-qualified (honoring any naming overrides). An undeclared
+ * reference throws {@link UnknownQueueReferenceError} rather than being
+ * silently qualified and routed to a queue nobody consumes.
+ *
+ * @throws UnknownQueueReferenceError if `queueName` is not in `topology.queues`.
  */
-export declare function resolveQueueName(namespace: string, queueDef: QueueDefinition): string;
+export declare function resolveTargetQueueName(topology: Topology, queueName: string): string;
 //# sourceMappingURL=types.d.ts.map

package/dist/topology/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/topology/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/topology/types.ts"],"names":[],"mappings":"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"}

package/dist/topology/types.js

@@ -1,28 +1,68 @@
+import { UnknownQueueReferenceError } from '../errors/matador-errors.js';
 /**
- * Gets the fully qualified queue name with namespace prefix.
+ * Prepends a resource-name prefix unless it is disabled.
+ * `null`/`undefined` mean no prefix; a string is prepended as `${prefix}.`.
  */
-export function getQualifiedQueueName(namespace, queueName) {
-    return `${namespace}.${queueName}`;
+export function applyPrefix(prefix, name) {
+    return prefix == null ? name : `${prefix}.${name}`;
+}
+/**
+ * Gets the fully qualified work-queue name.
+ * An optional naming strategy may override how the name is derived; otherwise
+ * the default is `${namespace}.${queueName}`, optionally prefixed.
+ */
+export function getQualifiedQueueName(namespace, queueName, naming, prefix) {
+    return (naming?.queue?.(namespace, queueName) ??
+        applyPrefix(prefix, `${namespace}.${queueName}`));
 }
 /**
  * Gets the dead-letter queue name for a given queue.
  */
-export function getDeadLetterQueueName(namespace, queueName, dlqType) {
-    return `${namespace}.${queueName}.${dlqType}`;
+export function getDeadLetterQueueName(namespace, queueName, dlqType, naming, prefix) {
+    return `${getQualifiedQueueName(namespace, queueName, naming, prefix)}.${dlqType}`;
 }
 /**
  * Gets the retry queue name for a given queue.
  */
-export function getRetryQueueName(namespace, queueName) {
-    return `${namespace}.${queueName}.retry`;
+export function getRetryQueueName(namespace, queueName, naming, prefix) {
+    return `${getQualifiedQueueName(namespace, queueName, naming, prefix)}.retry`;
 }
 /**
  * Resolves the actual queue name for a given queue definition.
- * When exact: true, returns name as-is. Otherwise, returns namespace.name.
+ * When exact: true, returns name as-is. Otherwise, returns the
+ * namespace-qualified name (honoring any naming overrides and prefix).
  */
-export function resolveQueueName(namespace, queueDef) {
+export function resolveQueueName(namespace, queueDef, naming, prefix) {
     if (queueDef.exact) {
         return queueDef.name;
     }
-    return `${namespace}.${queueDef.name}`;
+    return getQualifiedQueueName(namespace, queueDef.name, naming, prefix);
+}
+/**
+ * Finds the queue definition a local queue reference points at.
+ */
+export function findQueueDefinition(topology, queueName) {
+    return topology.queues.find((q) => q.name === queueName);
+}
+/**
+ * Resolves a local queue reference (a subscriber's `targetQueue` or a
+ * `consumeFrom` entry) to the transport-level queue name.
+ *
+ * The reference must be declared in the topology via `.addQueue(...)`:
+ * an exact queue resolves to its name as-is; a Matador-owned queue is
+ * namespace-qualified (honoring any naming overrides). An undeclared
+ * reference throws {@link UnknownQueueReferenceError} rather than being
+ * silently qualified and routed to a queue nobody consumes.
+ *
+ * @throws UnknownQueueReferenceError if `queueName` is not in `topology.queues`.
+ */
+export function resolveTargetQueueName(topology, queueName) {
+    const def = findQueueDefinition(topology, queueName);
+    if (def === undefined) {
+        throw new UnknownQueueReferenceError(queueName);
+    }
+    if (def.exact) {
+        return def.name;
+    }
+    return getQualifiedQueueName(topology.namespace, queueName, topology.naming, topology.prefix);
 }

package/dist/transport/local/local-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-transport.d.ts","sourceRoot":"","sources":["../../../src/transport/local/local-transport.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACV,MAAM,iBAAiB,CAAC;AAiCzB;;;GAGG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,QAAQ,CAAC,IAAI,WAAW;IACxB,QAAQ,CAAC,YAAY,wBAAqB;IAE1C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2C;IACzE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAwB;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4C;IAC1E,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,CAAC,EAAE,MAAM;IAIrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBjC,WAAW,IAAI,OAAO;IAIhB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBhD,IAAI,CACR,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAe7B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;YAkBhB,OAAO;YAgBP,oBAAoB;IA+B5B,SAAS,CACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,YAAY,CAAC;IAsClB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhD,gBAAgB,CACpB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAMnC;;OAEG;IACH,YAAY,IAAI,SAAS,cAAc,EAAE;IAIzC;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,QAAQ,EAAE;IAMtD;;OAEG;IACH,KAAK,IAAI,IAAI;IAYb;;;OAGG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI,CAAC;IAmBlE,OAAO,CAAC,gBAAgB;CAQzB"}
+{"version":3,"file":"local-transport.d.ts","sourceRoot":"","sources":["../../../src/transport/local/local-transport.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACV,MAAM,iBAAiB,CAAC;AAiCzB;;;GAGG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,QAAQ,CAAC,IAAI,WAAW;IACxB,QAAQ,CAAC,YAAY,wBAAqB;IAE1C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2C;IACzE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAwB;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4C;IAC1E,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,CAAC,EAAE,MAAM;IAIrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBjC,WAAW,IAAI,OAAO;IAIhB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBhD,IAAI,CACR,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAe7B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;YAkBhB,OAAO;YAgBP,oBAAoB;IAoC5B,SAAS,CACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,YAAY,CAAC;IAsClB,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhD,gBAAgB,CACpB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAMnC;;OAEG;IACH,YAAY,IAAI,SAAS,cAAc,EAAE;IAIzC;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,QAAQ,EAAE;IAMtD;;OAEG;IACH,KAAK,IAAI,IAAI;IAYb;;;OAGG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI,CAAC;IAmBlE,OAAO,CAAC,gBAAgB;CAQzB"}