@relaybus/nestjs 0.2.0 → 0.3.1

package/dist/index.cjs

@@ -15,7 +15,7 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
 var EVENT_CONSUMER_METADATA_KEY = /* @__PURE__ */ Symbol.for("relaybus.nestjs.event-consumer");
-function EventConsumer(catalog, {
+function RelayBusCatalogConsumer(catalog, {
   events,
   ...options
 } = {}) {
@@ -25,7 +25,7 @@ function EventConsumer(catalog, {
     const existing = Reflect.getOwnMetadata(EVENT_CONSUMER_METADATA_KEY, target) ?? [];
     if (existing.some((metadata) => metadata.catalog === catalog)) {
       throw new core.ConfigurationError(
-        `@EventConsumer(${name ?? "catalog"}) is declared twice on ${target.name}; merge the declarations into one`
+        `@RelayBusCatalogConsumer(${name ?? "catalog"}) is declared twice on ${target.name}; merge the declarations into one`
       );
     }
     Reflect.defineMetadata(
@@ -35,7 +35,8 @@ function EventConsumer(catalog, {
     );
   };
 }
-function readEventConsumerMetadata(target) {
+var EventConsumer = RelayBusCatalogConsumer;
+function readCatalogConsumerMetadata(target) {
   const lineage = [];
   for (let current = target; current !== Function.prototype; ) {
     lineage.unshift(current);
@@ -50,8 +51,69 @@ function readEventConsumerMetadata(target) {
   }
   return [...byCatalog.values()];
 }
+var RelayBusFeatureContract = class {
+  consumes;
+  produces;
+  /** @throws ConfigurationError for a `produce(...)` in `consumes`, a `consume(...)` in `produces`, or something that is not a catalog. */
+  constructor(options) {
+    this.consumes = contractEvents(options.consumes ?? [], "consume");
+    this.produces = contractEvents(options.produces ?? [], "produce");
+  }
+};
+function contractEvents(items, role) {
+  return items.flatMap((item) => {
+    const declaration = isDeclaration(item) ? item : role === "consume" ? core.consume(item) : core.produce(item);
+    const name = core.describeCatalog(declaration.catalog).name ?? "catalog";
+    if (declaration.role !== role) {
+      throw new core.ConfigurationError(
+        `RelayBusModule.forFeature ${role}s takes catalogs and ${role}(...) declarations, received ${declaration.role}(${name})`
+      );
+    }
+    return declaration.entries.map((entry) => ({
+      label: `${name}.${entry.name}`,
+      type: entry.eventClass.type
+    }));
+  });
+}
+function isDeclaration(item) {
+  return typeof item["role"] === "string" && Array.isArray(item["entries"]);
+}
+var runningBuses = /* @__PURE__ */ new Set();
+var busOfInstance = /* @__PURE__ */ new WeakMap();
+function registerBus(bus) {
+  runningBuses.add(bus);
+}
+function unregisterBus(bus) {
+  runningBuses.delete(bus);
+}
+function bindInstance(instance, bus) {
+  busOfInstance.set(instance, bus);
+}
+function resolveBus(instance, method) {
+  const bound = typeof instance === "object" && instance !== null ? busOfInstance.get(instance) : void 0;
+  if (bound !== void 0) {
+    if (!runningBuses.has(bound)) {
+      throw new core.ConfigurationError(
+        `@RelayBusTransaction() ${method} was called after its application shut down`
+      );
+    }
+    return bound;
+  }
+  const [only, ...others] = runningBuses;
+  if (only === void 0) {
+    throw new core.ConfigurationError(
+      `@RelayBusTransaction() ${method} found no running RelayBusModule: import RelayBusModule.forRoot(...) and call the method after the application initialised (app.init() or app.listen())`
+    );
+  }
+  if (others.length > 0) {
+    throw new core.ConfigurationError(
+      `@RelayBusTransaction() ${method} cannot tell which of ${runningBuses.size} running applications it belongs to; call it on a singleton provider of one of them`
+    );
+  }
+  return only;
+}
 var SUBSCRIBE_METADATA_KEY = /* @__PURE__ */ Symbol.for("relaybus.nestjs.subscribe");
-function Subscribe(event, options = {}) {
+function RelayBusConsumer(event, options = {}) {
   return (target, propertyKey) => {
     const existing = Reflect.getOwnMetadata(SUBSCRIBE_METADATA_KEY, target, propertyKey) ?? [];
     Reflect.defineMetadata(
@@ -62,94 +124,160 @@ function Subscribe(event, options = {}) {
     );
   };
 }
-function readSubscribeMetadata(prototype, propertyKey) {
+var Subscribe = RelayBusConsumer;
+function readConsumerMetadata(prototype, propertyKey) {
   return Reflect.getMetadata(SUBSCRIBE_METADATA_KEY, prototype, propertyKey) ?? [];
 }
 
 // src/handler-explorer.ts
 exports.RelayBusHandlerExplorer = class RelayBusHandlerExplorer {
-  constructor(discovery, metadataScanner, bus) {
+  constructor(discovery, metadataScanner, bus, modules) {
     this.discovery = discovery;
     this.metadataScanner = metadataScanner;
     this.bus = bus;
+    this.modules = modules;
   }
   discovery;
   metadataScanner;
   bus;
+  modules;
   onModuleInit() {
-    const registeredBy = /* @__PURE__ */ new Map();
-    const visited = /* @__PURE__ */ new Map();
-    const consumers = /* @__PURE__ */ new WeakSet();
+    const discovery = {
+      registeredBy: /* @__PURE__ */ new Map(),
+      visited: /* @__PURE__ */ new Map(),
+      consumers: /* @__PURE__ */ new WeakSet(),
+      consumedByModule: /* @__PURE__ */ new Map()
+    };
     for (const wrapper of this.discovery.getProviders()) {
-      if (wrapper.isTransient || !wrapper.isDependencyTreeStatic()) {
-        this.assertNoHandlers(wrapper);
-        continue;
-      }
-      const instance = wrapper.instance;
-      if (typeof instance !== "object" || instance === null) {
-        continue;
-      }
-      const prototype = Object.getPrototypeOf(instance);
-      if (prototype === null) {
+      this.registerProvider(wrapper, discovery);
+    }
+    this.assertModuleContracts(discovery.consumedByModule);
+  }
+  /** Checks the `RelayBusModule.forFeature` contract of every module that imports one. */
+  assertModuleContracts(consumedByModule) {
+    const routed = new Set(
+      this.bus.handlers().filter((handler) => handler.forwardsToTransport).map((handler) => handler.eventType)
+    );
+    const violations = [];
+    for (const wrapper of this.discovery.getProviders()) {
+      const contract = wrapper.instance;
+      if (!(contract instanceof RelayBusFeatureContract)) {
         continue;
       }
-      const className = instance.constructor.name;
-      for (const { methodName, declarations } of this.subscribedMethods(prototype)) {
-        const seen = visited.get(instance) ?? /* @__PURE__ */ new Set();
-        visited.set(instance, seen);
-        if (seen.has(methodName)) {
-          continue;
+      for (const module of this.importersOf(wrapper.host)) {
+        const consumed = consumedByModule.get(module);
+        for (const event of contract.consumes.filter(({ type }) => !consumed.has(type))) {
+          violations.push(`${module.name}: ${event.label} (${event.type}) has no consumer`);
         }
-        seen.add(methodName);
-        const method = instance[methodName];
-        const location = `${className}.${methodName}`;
-        for (const { event, options } of declarations) {
-          const id = options.id ?? location;
-          const previous = registeredBy.get(id);
-          if (previous !== void 0) {
-            throw new core.ConfigurationError(
-              `Handler id '${id}' is used by both ${previous} and ${location}; pass a unique { id } to @Subscribe`
-            );
-          }
-          registeredBy.set(id, location);
-          this.bus.subscribe(
-            event,
-            (envelope, context) => method.call(instance, envelope, context),
-            { ...options, id }
+        for (const event of contract.produces.filter(({ type }) => !routed.has(type))) {
+          violations.push(
+            `${module.name}: ${event.label} (${event.type}) has no route to a transport`
           );
         }
       }
-      if (!consumers.has(instance)) {
-        consumers.add(instance);
-        this.registerEventConsumers(instance, className, registeredBy);
-      }
+    }
+    if (violations.length > 0) {
+      throw new core.ConfigurationError(
+        `[RelayBusHandlerExplorer](assertModuleContracts) ${violations.join("; ")}`
+      );
     }
   }
-  registerEventConsumers(instance, className, registeredBy) {
+  importersOf(contractModule) {
+    return [...this.modules.values()].filter((module) => module.imports.has(contractModule));
+  }
+  /** Records the event types the provider of `wrapper` consumes under the provider's module. */
+  recordConsumedTypes(wrapper, { instance, discovery }) {
+    const types = discovery.consumedByModule.get(wrapper.host) ?? /* @__PURE__ */ new Set();
+    discovery.consumedByModule.set(wrapper.host, types);
     const lookup = instance;
-    for (const { catalog, options, selectedEntries } of readEventConsumerMetadata(
-      instance.constructor
+    for (const { declarations } of this.subscribedMethods(
+      Object.getPrototypeOf(instance)
     )) {
-      const { name, entries } = core.describeCatalog(catalog);
-      const label = name ?? "catalog";
-      const handlers = selectedEntries ?? entries.filter((entry) => isMethod(lookup, entry));
-      const missing = handlers.filter((entry) => !isMethod(lookup, entry));
-      if (missing.length > 0) {
-        throw new core.ConfigurationError(
-          `${className} uses @EventConsumer(${label}) but lacks the handler methods of events it consumes: ${missing.map((entry) => entry.handlerName).join(", ")}`
-        );
+      for (const { event } of declarations) {
+        types.add(typeof event === "string" ? event : event.type);
+      }
+    }
+    for (const { catalog, selectedEntries } of readCatalogConsumerMetadata(instance.constructor)) {
+      const entries = selectedEntries ?? core.describeCatalog(catalog).entries.filter((entry) => isMethod(lookup, entry));
+      for (const entry of entries) {
+        types.add(entry.eventClass.type);
       }
-      if (handlers.length === 0) {
+    }
+  }
+  registerProvider(wrapper, discovery) {
+    if (wrapper.isTransient || !wrapper.isDependencyTreeStatic()) {
+      this.assertNoHandlers(wrapper);
+      return;
+    }
+    const instance = wrapper.instance;
+    if (typeof instance !== "object" || instance === null) {
+      return;
+    }
+    const prototype = Object.getPrototypeOf(instance);
+    if (prototype === null) {
+      return;
+    }
+    bindInstance(instance, this.bus);
+    this.recordConsumedTypes(wrapper, { instance, discovery });
+    const className = instance.constructor.name;
+    for (const subscribed of this.subscribedMethods(prototype)) {
+      this.registerSubscribedMethod(instance, { subscribedMethod: subscribed, discovery });
+    }
+    if (!discovery.consumers.has(instance)) {
+      discovery.consumers.add(instance);
+      this.registerEventConsumers(instance, { className, registeredBy: discovery.registeredBy });
+    }
+  }
+  registerSubscribedMethod(instance, {
+    subscribedMethod: { methodName, declarations },
+    discovery: { registeredBy, visited }
+  }) {
+    const seen = visited.get(instance) ?? /* @__PURE__ */ new Set();
+    visited.set(instance, seen);
+    if (seen.has(methodName)) {
+      return;
+    }
+    seen.add(methodName);
+    const method = instance[methodName];
+    const location = `${instance.constructor.name}.${methodName}`;
+    for (const { event, options } of declarations) {
+      const id = options.id ?? location;
+      const previous = registeredBy.get(id);
+      if (previous !== void 0) {
         throw new core.ConfigurationError(
-          `${className} uses @EventConsumer(${label}) but defines none of its handler methods (${entries.map((entry) => entry.handlerName).join(", ")})`
+          `Handler id '${id}' is used by both ${previous} and ${location}; pass a unique { id } to @RelayBusConsumer`
         );
       }
+      registeredBy.set(id, location);
+      this.bus.subscribe(
+        event,
+        (envelope, context) => method.call(instance, envelope, context),
+        { ...options, id }
+      );
+    }
+  }
+  registerEventConsumers(instance, {
+    className,
+    registeredBy
+  }) {
+    const lookup = instance;
+    for (const { catalog, options, selectedEntries } of readCatalogConsumerMetadata(
+      instance.constructor
+    )) {
+      const { name, entries } = core.describeCatalog(catalog);
+      const label = name ?? "catalog";
+      const handlers = this.catalogHandlers(lookup, {
+        className,
+        label,
+        entries,
+        selected: selectedEntries
+      });
       for (const entry of handlers) {
         const id = `${className}.${entry.handlerName}`;
         const previous = registeredBy.get(id);
         if (previous !== void 0) {
           throw new core.ConfigurationError(
-            `Handler id '${id}' of @EventConsumer(${label}) is already used by ${previous}; give the @Subscribe a unique { id } or drop it`
+            `Handler id '${id}' of @RelayBusCatalogConsumer(${label}) is already used by ${previous}; give the @RelayBusConsumer a unique { id } or drop it`
           );
         }
         registeredBy.set(id, `${className}.${entry.handlerName}`);
@@ -162,10 +290,31 @@ exports.RelayBusHandlerExplorer = class RelayBusHandlerExplorer {
       }
     }
   }
+  /** The catalog entries `lookup` handles: the selected ones, else every entry it has a method for. */
+  catalogHandlers(lookup, {
+    className,
+    label,
+    entries,
+    selected
+  }) {
+    const handlers = selected ?? entries.filter((entry) => isMethod(lookup, entry));
+    const missing = handlers.filter((entry) => !isMethod(lookup, entry));
+    if (missing.length > 0) {
+      throw new core.ConfigurationError(
+        `${className} uses @RelayBusCatalogConsumer(${label}) but lacks the handler methods of events it consumes: ${missing.map((entry) => entry.handlerName).join(", ")}`
+      );
+    }
+    if (handlers.length === 0) {
+      throw new core.ConfigurationError(
+        `${className} uses @RelayBusCatalogConsumer(${label}) but defines none of its handler methods (${entries.map((entry) => entry.handlerName).join(", ")})`
+      );
+    }
+    return handlers;
+  }
   subscribedMethods(prototype) {
     const methods = [];
     for (const methodName of this.metadataScanner.getAllMethodNames(prototype)) {
-      const declarations = readSubscribeMetadata(prototype, methodName);
+      const declarations = readConsumerMetadata(prototype, methodName);
       if (declarations.length > 0) {
         methods.push({ methodName, declarations });
       }
@@ -179,16 +328,16 @@ exports.RelayBusHandlerExplorer = class RelayBusHandlerExplorer {
    */
   assertNoHandlers(wrapper) {
     const type = wrapper.isFactory ? wrapper.token : wrapper.metatype;
-    if (typeof type === "function" && readEventConsumerMetadata(type).length > 0) {
+    if (typeof type === "function" && readCatalogConsumerMetadata(type).length > 0) {
       throw new core.ConfigurationError(
-        `${type.name} uses @EventConsumer but its provider is request-scoped or transient (directly or through a dependency); handlers must be singleton providers`
+        `${type.name} uses @RelayBusCatalogConsumer but its provider is request-scoped or transient (directly or through a dependency); handlers must be singleton providers`
       );
     }
     const prototype = typeof type === "function" ? type.prototype : null;
     const [first] = prototype === null ? [] : this.subscribedMethods(prototype);
     if (first !== void 0) {
       throw new core.ConfigurationError(
-        `${prototype.constructor.name}.${first.methodName} uses @Subscribe but its provider is request-scoped or transient (directly or through a dependency); handlers must be singleton providers`
+        `${prototype.constructor.name}.${first.methodName} uses @RelayBusConsumer but its provider is request-scoped or transient (directly or through a dependency); handlers must be singleton providers`
       );
     }
   }
@@ -197,7 +346,8 @@ exports.RelayBusHandlerExplorer = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Inject(core$1.DiscoveryService)),
   __decorateParam(1, common.Inject(core$1.MetadataScanner)),
-  __decorateParam(2, common.Inject(core.RelayBus))
+  __decorateParam(2, common.Inject(core.RelayBus)),
+  __decorateParam(3, common.Inject(core$1.ModulesContainer))
 ], exports.RelayBusHandlerExplorer);
 function isMethod(instance, entry) {
   return typeof instance[entry.handlerName] === "function";
@@ -258,18 +408,86 @@ exports.RelayBusLifecycle = class RelayBusLifecycle {
     this.bus = bus;
   }
   bus;
+  onModuleInit() {
+    registerBus(this.bus);
+  }
   async onApplicationBootstrap() {
     await this.bus.start();
   }
   async beforeApplicationShutdown() {
     await this.bus.stop();
   }
+  /** After the bus stopped, so handlers still draining at shutdown can open transactions. */
+  onApplicationShutdown() {
+    unregisterBus(this.bus);
+  }
 };
 exports.RelayBusLifecycle = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Inject(core.RelayBus))
 ], exports.RelayBusLifecycle);
+exports.RelayBusFeatureModule = class RelayBusFeatureModule {
+};
+exports.RelayBusFeatureModule = __decorateClass([
+  common.Module({})
+], exports.RelayBusFeatureModule);
+exports.RelayBusTransactionHost = class RelayBusTransactionHost {
+  constructor(bus) {
+    this.bus = bus;
+  }
+  bus;
+  /**
+   * The active transaction.
+   *
+   * @throws TransactionRequiredError when the caller runs outside every transaction.
+   */
+  current() {
+    const transaction = this.bus.currentTransaction();
+    if (transaction === void 0) {
+      throw new core.TransactionRequiredError(
+        "No relaybus transaction is active: call the repository from a @RelayBusTransaction() method or inside bus.transaction()"
+      );
+    }
+    return transaction;
+  }
+  /** The active transaction, or undefined outside every transaction. */
+  find() {
+    return this.bus.currentTransaction();
+  }
+};
+exports.RelayBusTransactionHost = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(core.RelayBus))
+], exports.RelayBusTransactionHost);
+
+// src/relay-bus.module.ts
 exports.RelayBusModule = class RelayBusModule extends RelayBusConfigurableModule {
+  /**
+   * The relaybus contract of a feature module: import it in the module whose providers consume
+   * and produce the events. When the application initialises, every consumed event needs a
+   * `@RelayBusConsumer` method (or a `@RelayBusCatalogConsumer` class) among the providers of
+   * that module, spread over any classes and method names, and every produced event needs a
+   * route to a transport; otherwise the application fails to start naming the module and each
+   * missing event. Needs `RelayBusModule.forRoot` in the application.
+   *
+   * ```ts
+   * @Module({
+   *   imports: [RelayBusModule.forFeature({ consumes: [OrderEvents], produces: [produce(BillingEvents)] })],
+   *   providers: [OrderPlacedHandlers, OrderCancelledHandlers],
+   * })
+   * export class BillingModule {}
+   * ```
+   *
+   * @throws ConfigurationError for a `produce(...)` in `consumes` or a `consume(...)` in `produces`.
+   */
+  static forFeature(options) {
+    return {
+      module: exports.RelayBusFeatureModule,
+      providers: [
+        { provide: RelayBusFeatureContract, useValue: new RelayBusFeatureContract(options) }
+      ]
+    };
+  }
 };
 exports.RelayBusModule = __decorateClass([
   common.Module({
@@ -282,17 +500,40 @@ exports.RelayBusModule = __decorateClass([
       },
       exports.RelayBusHandlerExplorer,
       exports.RelayBusLifecycle,
-      exports.RelayBusHealth
+      exports.RelayBusHealth,
+      exports.RelayBusTransactionHost
     ],
-    exports: [core.RelayBus, exports.RelayBusHealth]
+    exports: [core.RelayBus, exports.RelayBusHealth, exports.RelayBusTransactionHost]
   })
 ], exports.RelayBusModule);
+function RelayBusTransaction() {
+  return (target, propertyKey, descriptor) => {
+    const original = descriptor.value;
+    const label = `${target.constructor.name}.${String(propertyKey)}`;
+    const transactional = async function(...args) {
+      const bus = resolveBus(this, label);
+      if (bus.currentTransaction() !== void 0) {
+        return original.apply(this, args);
+      }
+      return bus.transaction(() => original.apply(this, args));
+    };
+    Object.defineProperty(transactional, "name", { value: original.name });
+    for (const key of Reflect.getOwnMetadataKeys(original)) {
+      Reflect.defineMetadata(key, Reflect.getOwnMetadata(key, original), transactional);
+    }
+    descriptor.value = transactional;
+  };
+}
 
 Object.defineProperty(exports, "RelayBus", {
   enumerable: true,
   get: function () { return core.RelayBus; }
 });
 exports.EventConsumer = EventConsumer;
+exports.RelayBusCatalogConsumer = RelayBusCatalogConsumer;
+exports.RelayBusConsumer = RelayBusConsumer;
+exports.RelayBusFeatureContract = RelayBusFeatureContract;
+exports.RelayBusTransaction = RelayBusTransaction;
 exports.Subscribe = Subscribe;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map