@relaybus/nestjs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Berkcan Şavur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,238 @@
-# Temporary Holding Version
+# @relaybus/nestjs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+NestJS integration for [relaybus](../core): one module, one decorator, correct lifecycle.
+
+## Install
+
+```bash
+npm install @relaybus/core @relaybus/nestjs
+```
+
+Peer dependencies: `@nestjs/common` and `@nestjs/core` (`^11 || ^12`), `reflect-metadata`, `rxjs`.
+
+## Quick start
+
+```ts
+// app.module.ts
+@Module({
+  imports: [RelayBusModule.forRoot({ store: new PostgresEventStore({ pool }), source: 'orders' })],
+})
+export class AppModule {}
+
+// shipping.handlers.ts - any provider of any module
+@Injectable()
+export class ShippingHandlers {
+  @Subscribe(OrderPlaced)
+  async onOrderPlaced(event: EventEnvelope<{ orderId: string }>) {
+    /* ... */
+  }
+}
+
+// order.service.ts
+await this.bus.transaction(async (tx) => {
+  await tx.query('INSERT INTO orders ...');
+  await this.bus.publish(new OrderPlaced({ orderId }), { transaction: tx });
+});
+```
+
+That is all: the module is global, the handler is discovered, the bus starts after bootstrap and
+stops on shutdown. Inject the bus anywhere with `constructor(private readonly bus: RelayBus) {}`;
+add the transaction type when you want it typed: `RelayBus<PoolClient>` (the generic is erased at
+runtime, so DI is unaffected).
+
+Call `app.enableShutdownHooks()` in `main.ts` so SIGTERM/SIGINT close the app and let the bus
+drain running handlers (`dispatcher.shutdownTimeout`, default 30s).
+
+## `RelayBusModule`
+
+- `forRoot(options)`
+- `forRootAsync({ imports?, inject?, useFactory })`, or `useClass` / `useExisting` (a class with
+  `create(): RelayBusModuleOptions | Promise<RelayBusModuleOptions>`, see `RelayBusModuleOptionsFactory`)
+
+Both accept `isGlobal` next to the options. It defaults to `true`; with `false`, import the module
+wherever `RelayBus` is injected. `RelayBus` and `RelayBusHealth` are exported.
+
+### Options
+
+Everything of core's `RelayBusOptions` passes through unchanged, except `logger`: the bus always
+logs through a Nest `Logger` with context `RelayBus`, so `app.useLogger(...)` controls it.
+
+| Option                                        | Default                   | Notes                                                                            |
+| --------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------- |
+| `store`                                       | required                  | An `EventStore`: `@relaybus/postgres`, `@relaybus/mongodb`, `InMemoryEventStore` |
+| `source`                                      | `'relaybus'`              | Service name recorded on every event; set it to your app name                    |
+| `transactionMode`                             | `'required'`              | `'optional'` lets `publish` open its own transaction                             |
+| `transactionResolver`                         | none                      | Finds the caller's active transaction (see below)                                |
+| `retry`                                       | core default              | Default retry policy of every handler and route                                  |
+| `handlerTimeout`                              | `false`                   | Default handler timeout                                                          |
+| `dispatcher.enabled`                          | `true`                    | `false` on publish-only processes (API pods, scripts)                            |
+| `dispatcher.concurrency`                      | `10`                      | Handlers running at once                                                         |
+| `dispatcher.batchSize`                        | concurrency               | Deliveries claimed per query                                                     |
+| `dispatcher.pollInterval`                     | `'1s'`                    | Wait between claims when idle                                                    |
+| `dispatcher.leaseDuration`                    | `'30s'`                   | Renewed every third of it                                                        |
+| `dispatcher.shutdownTimeout`                  | `'30s'`                   | How long shutdown waits for running handlers                                     |
+| `retention.completed` / `.dead` / `.interval` | `'7d'` / `false` / `'1h'` | Cleanup of finished deliveries                                                   |
+| `transports`, `routes`, `subscriptions`       | none                      | Broker fan-out and fan-in (`@relaybus/kafka`, `@relaybus/rabbitmq`)              |
+| `setupStore`                                  | `true`                    | Create tables/indexes on start                                                   |
+| `observers`                                   | none                      | Metrics and tracing hooks                                                        |
+| `clock`, `generateIdentifier`, `random`       | system                    | Mainly for tests                                                                 |
+| `isGlobal`                                    | `true`                    | Module-level, see above                                                          |
+
+## `@Subscribe(event, options?)`
+
+```ts
+@Subscribe(OrderPlaced)                                   // class
+@Subscribe('order.placed.v1', { concurrency: 2 })         // type string
+@Subscribe(OrderPlaced, { id: 'billing.invoice', transactional: true, timeout: '10s' })
+```
+
+Options are core's `SubscribeOptions` with `id` optional. Methods receive `(envelope, context)`;
+with a class argument the envelope payload is typed from the event.
+
+**Why `@Subscribe`:** `@nestjs/event-emitter` already owns `@OnEvent`, and the two are commonly
+installed together. `@Subscribe` mirrors core's `bus.subscribe` and cannot collide.
+
+Rules, all enforced at boot (the application fails to start, no silent skips):
+
+- **Stable ids.** The default id is `ClassName.methodName`. Deliveries are stored under the id, so
+  renaming the class or method orphans pending deliveries; pin `{ id }` on handlers that matter.
+- **Duplicate ids** fail init with both locations named. A method with several `@Subscribe`
+  decorators must give each an explicit `id`.
+- **Singletons only.** Handlers on request-scoped or transient providers (or default-scoped
+  providers that depend on one) are rejected: deliveries run outside any request, so there is no
+  request instance to call. This covers class, `useClass` and `useFactory` providers (a factory is
+  checked through its class token; a request-scoped factory under a string token cannot be
+  inspected). Providers without `@Subscribe` are never inspected for scope.
+- `this` is bound to the provider instance. Only providers are scanned, in every module. A handler
+  reachable through several tokens (`useExisting`) is registered once. Declarations are stored per
+  class and method, so decorators that wrap the method later do not drop them, and subclasses
+  inherit the handlers of their base class.
+
+## Lifecycle
+
+1. `onModuleInit`: handlers are discovered and registered on the bus.
+2. `onApplicationBootstrap`: `bus.start()` creates the schema (unless `setupStore: false`),
+   connects transports and starts the dispatcher. If it rejects (database down, broker
+   unreachable) the application does not boot.
+3. `beforeApplicationShutdown`: `bus.stop()` stops claiming, waits for running handlers up to
+   `shutdownTimeout`, then closes transports and the store. Needs `app.enableShutdownHooks()` for
+   signals; `app.close()` runs it regardless. Nest runs `onApplicationShutdown` hooks (where
+   TypeORM, Mongoose and most pools disconnect) after this, so handlers still have their
+   connections while draining. If your own provider disconnects in `onModuleDestroy` (common with
+   Prisma), move it to `onApplicationShutdown`.
+
+## Transactions
+
+Inside `bus.transaction(fn)` every `publish` joins the transaction. Without it, publish needs a
+transaction: pass `{ transaction }`, configure `transactionResolver`, or set
+`transactionMode: 'optional'` (event stays durable but is no longer atomic with your writes).
+
+### Transactional handlers
+
+```ts
+@Subscribe(PaymentCaptured, { id: 'ledger.record-capture', transactional: true })
+async record(event: EventEnvelope<{ paymentId: string }>, context: HandlerContext<PoolClient>) {
+  // Writes through context.transaction commit atomically with the delivery completion:
+  // effectively-once processing. Keep these handlers short.
+  await context.transaction!.query('INSERT INTO ledger ...', [event.payload.paymentId]);
+  await this.bus.publish(new LedgerUpdated({ ... }), { transaction: context.transaction! });
+}
+```
+
+Non-transactional handlers are at-least-once: make them idempotent (deduplicate on `event.id`).
+
+### ORM integration
+
+Prefer `transactionResolver`, so services call `bus.publish(event)` inside whatever transaction
+the ORM already opened. The resolver is called synchronously and must return `undefined` when
+there is no active transaction.
+
+```ts
+// @nestjs-cls/transactional (not a dependency of this package)
+RelayBusModule.forRootAsync({
+  inject: [TransactionHost],
+  useFactory: (txHost: TransactionHost) => ({
+    store,
+    transactionResolver: () => (txHost.isTransactionActive() ? txHost.tx : undefined),
+  }),
+});
+```
+
+- **Prisma / raw `pg`:** `@relaybus/postgres` store; Prisma's interactive transaction client is
+  adapted by the store package, see its README.
+- **TypeORM:** `@relaybus/postgres` over the same `DataSource` connection; resolve the active
+  `EntityManager`'s query runner in `transactionResolver`.
+- **MongoDB:** `@relaybus/mongodb` store; the transaction is the `ClientSession` (needs a replica set).
+
+## Health
+
+`RelayBusHealth` (exported by the module) has no `@nestjs/terminus` dependency.
+
+```ts
+const report = await health.check();
+// { status: 'up' | 'down', running, ready, handlers, statistics?, lagMilliseconds?, error? }
+```
+
+`down` when the bus is not running, a transport is not ready (`ready` is `bus.isReady()`: for
+example a dead Kafka consumer or a disconnected RabbitMQ channel) or the store cannot be queried.
+`lagMilliseconds` is how long the oldest due delivery has waited (measured with the `clock` from
+the module options, the system clock by default), a good alert signal. With terminus 11:
+
+```ts
+@Injectable()
+export class RelayBusIndicator {
+  constructor(
+    private readonly indicators: HealthIndicatorService,
+    private readonly relayBus: RelayBusHealth,
+  ) {}
+
+  async isHealthy(key = 'relaybus') {
+    const indicator = this.indicators.check(key);
+    const { status, ...details } = await this.relayBus.check();
+    return status === 'up' ? indicator.up(details) : indicator.down(details);
+  }
+}
+```
+
+## Startup failure and restarts
+
+The bus starts during application bootstrap. If the start fails (store setup, transport connect),
+application boot fails with that error. A bus whose start failed is stopped for good and cannot be
+started again: restart the process rather than retrying in place.
+
+## Testing
+
+Use `@nestjs/testing` with `InMemoryEventStore` and turn the dispatcher off so tests control time:
+
+```ts
+const moduleRef = await Test.createTestingModule({
+  imports: [
+    RelayBusModule.forRoot({ store: new InMemoryEventStore(), dispatcher: { enabled: false } }),
+    AppFeatureModule,
+  ],
+}).compile();
+await moduleRef.init();
+
+await moduleRef.get(OrderService).place('o-1');
+await moduleRef.get(RelayBus).drain(); // runs every due delivery, including handlers' follow-up events
+// assert on side effects
+await moduleRef.close();
+```
+
+- `bus.runOnce()` runs a single batch; `bus.drain()` loops until nothing is due.
+- Retries and delays are scheduled in the future: pass `clock: new FakeClock()` from
+  `@relaybus/testing`, `clock.advance(5_000)`, then `drain()` again.
+- `bus.listDeliveries({ status: 'dead' })` shows handlers that exhausted their retries.
+
+## Troubleshooting
+
+- **`Nest can't resolve dependencies of ... (?)`** when injecting `RelayBus`: the module is not
+  global (`isGlobal: false`) and not imported by the consuming module.
+- **Handler never runs:** the provider is not listed in any module `providers`, the process runs
+  with `dispatcher.enabled: false`, or the event type differs (check `bus.handlers()`).
+- **`uses @Subscribe but its provider is request-scoped or transient`:** make the provider a
+  singleton; inject request data through the event payload instead.
+- **Vitest/esbuild:** esbuild does not emit decorator metadata; use explicit `@Inject(Token)` in
+  test classes.
+- **App hangs on shutdown:** a handler ignores `context.signal`; it is waited for until
+  `dispatcher.shutdownTimeout`.

package/dist/index.cjs

@@ -0,0 +1,211 @@
+'use strict';
+
+var common = require('@nestjs/common');
+var core$1 = require('@nestjs/core');
+var core = require('@relaybus/core');
+require('reflect-metadata');
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+var SUBSCRIBE_METADATA_KEY = /* @__PURE__ */ Symbol.for("relaybus.nestjs.subscribe");
+function Subscribe(event, options = {}) {
+  return (target, propertyKey) => {
+    const existing = Reflect.getOwnMetadata(SUBSCRIBE_METADATA_KEY, target, propertyKey) ?? [];
+    Reflect.defineMetadata(
+      SUBSCRIBE_METADATA_KEY,
+      [...existing, { event, options }],
+      target,
+      propertyKey
+    );
+  };
+}
+function readSubscribeMetadata(prototype, propertyKey) {
+  return Reflect.getMetadata(SUBSCRIBE_METADATA_KEY, prototype, propertyKey) ?? [];
+}
+
+// src/handler-explorer.ts
+exports.RelayBusHandlerExplorer = class RelayBusHandlerExplorer {
+  constructor(discovery, metadataScanner, bus) {
+    this.discovery = discovery;
+    this.metadataScanner = metadataScanner;
+    this.bus = bus;
+  }
+  discovery;
+  metadataScanner;
+  bus;
+  onModuleInit() {
+    const registeredBy = /* @__PURE__ */ new Map();
+    const visited = /* @__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) {
+        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;
+        }
+        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 }
+          );
+        }
+      }
+    }
+  }
+  subscribedMethods(prototype) {
+    const methods = [];
+    for (const methodName of this.metadataScanner.getAllMethodNames(prototype)) {
+      const declarations = readSubscribeMetadata(prototype, methodName);
+      if (declarations.length > 0) {
+        methods.push({ methodName, declarations });
+      }
+    }
+    return methods;
+  }
+  /**
+   * Request-scoped and transient wrappers have no usable instance (a factory
+   * wrapper has none at all), so the decorated prototype is taken from the
+   * provider class, or from the provider token for factories when it is a class.
+   */
+  assertNoHandlers(wrapper) {
+    const type = wrapper.isFactory ? wrapper.token : wrapper.metatype;
+    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`
+      );
+    }
+  }
+};
+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))
+], exports.RelayBusHandlerExplorer);
+var {
+  ConfigurableModuleClass: RelayBusConfigurableModule,
+  MODULE_OPTIONS_TOKEN: RELAYBUS_MODULE_OPTIONS
+} = new common.ConfigurableModuleBuilder().setClassMethodName("forRoot").setExtras({ isGlobal: true }, (definition, extras) => ({
+  ...definition,
+  global: extras.isGlobal === true
+})).build();
+
+// src/relay-bus-health.ts
+exports.RelayBusHealth = class RelayBusHealth {
+  constructor(bus, options) {
+    this.bus = bus;
+    this.options = options;
+  }
+  bus;
+  options;
+  async check() {
+    const running = this.bus.isRunning;
+    const ready = this.bus.isReady();
+    const handlers = this.bus.handlers().length;
+    if (!running) {
+      return { status: "down", running, ready, handlers };
+    }
+    try {
+      const statistics = await this.bus.statistics();
+      const clock = this.options.clock ?? core.systemClock;
+      const lagMilliseconds = statistics.oldestDueAt === null ? 0 : Math.max(0, clock.now().getTime() - statistics.oldestDueAt.getTime());
+      return {
+        status: ready ? "up" : "down",
+        running,
+        ready,
+        handlers,
+        statistics,
+        lagMilliseconds
+      };
+    } catch (error) {
+      return {
+        status: "down",
+        running,
+        ready,
+        handlers,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+};
+exports.RelayBusHealth = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(core.RelayBus)),
+  __decorateParam(1, common.Inject(RELAYBUS_MODULE_OPTIONS))
+], exports.RelayBusHealth);
+exports.RelayBusLifecycle = class RelayBusLifecycle {
+  constructor(bus) {
+    this.bus = bus;
+  }
+  bus;
+  async onApplicationBootstrap() {
+    await this.bus.start();
+  }
+  async beforeApplicationShutdown() {
+    await this.bus.stop();
+  }
+};
+exports.RelayBusLifecycle = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(core.RelayBus))
+], exports.RelayBusLifecycle);
+exports.RelayBusModule = class RelayBusModule extends RelayBusConfigurableModule {
+};
+exports.RelayBusModule = __decorateClass([
+  common.Module({
+    imports: [core$1.DiscoveryModule],
+    providers: [
+      {
+        provide: core.RelayBus,
+        inject: [RELAYBUS_MODULE_OPTIONS],
+        useFactory: (options) => new core.RelayBus({ ...options, logger: new common.Logger("RelayBus") })
+      },
+      exports.RelayBusHandlerExplorer,
+      exports.RelayBusLifecycle,
+      exports.RelayBusHealth
+    ],
+    exports: [core.RelayBus, exports.RelayBusHealth]
+  })
+], exports.RelayBusModule);
+
+Object.defineProperty(exports, "RelayBus", {
+  enumerable: true,
+  get: function () { return core.RelayBus; }
+});
+exports.Subscribe = Subscribe;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/subscribe.decorator.ts","../src/handler-explorer.ts","../src/module-options.ts","../src/relay-bus-health.ts","../src/relay-bus-lifecycle.ts","../src/relay-bus.module.ts"],"names":["RelayBusHandlerExplorer","ConfigurationError","Injectable","DiscoveryService","MetadataScanner","RelayBus","ConfigurableModuleBuilder","RelayBusHealth","systemClock","Inject","RelayBusLifecycle","RelayBusModule","Module","DiscoveryModule","Logger"],"mappings":"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","file":"index.cjs","sourcesContent":["import 'reflect-metadata';\nimport type { EventClass, EventEnvelope, HandlerContext, SubscribeOptions } from '@relaybus/core';\n\n/**\n * Options of {@link Subscribe}: the core {@link SubscribeOptions}, except that\n * `id` is optional and defaults to `ClassName.methodName`.\n */\nexport type SubscribeDecoratorOptions = Omit<SubscribeOptions, 'id'> & {\n  /**\n   * Stable id of the handler. Deliveries are recorded under it, so renaming it\n   * (or the class or method it is derived from) orphans pending deliveries.\n   * Default: `${ClassName}.${methodName}`. Required when one method carries\n   * several `@Subscribe` decorators.\n   */\n  readonly id?: string;\n};\n\n/** What one `@Subscribe` decorator recorded on a method. */\nexport interface SubscribeMetadata {\n  readonly event: EventClass<unknown> | string;\n  readonly options: SubscribeDecoratorOptions;\n}\n\nconst SUBSCRIBE_METADATA_KEY = Symbol.for('relaybus.nestjs.subscribe');\n\ntype HandlerMethod<TPayload> = (\n  event: EventEnvelope<TPayload>,\n  context: HandlerContext<never>,\n) => unknown;\n\ntype SubscribeDecorator<TPayload> = <TMethod extends HandlerMethod<TPayload>>(\n  target: object,\n  propertyKey: string | symbol,\n  descriptor: TypedPropertyDescriptor<TMethod>,\n) => void;\n\n/**\n * Subscribes a provider method to an event class or type. The method is\n * registered with `bus.subscribe` when the module initialises, with `this`\n * bound to the provider instance, and receives `(envelope, context)`.\n *\n * The provider must be a singleton (default scope) and belong to any module of\n * the application. The decorator name differs from `@nestjs/event-emitter`'s\n * `@OnEvent` so both can be used in one application.\n *\n * ```ts\n * @Injectable()\n * export class ShippingHandlers {\n *   @Subscribe(OrderPlaced, { transactional: true })\n *   async onOrderPlaced(event: EventEnvelope<{ orderId: string }>, context: HandlerContext) {}\n * }\n * ```\n */\nexport function Subscribe<TPayload>(\n  event: EventClass<TPayload>,\n  options?: SubscribeDecoratorOptions,\n): SubscribeDecorator<TPayload>;\nexport function Subscribe(\n  eventType: string,\n  options?: SubscribeDecoratorOptions,\n): SubscribeDecorator<never>;\nexport function Subscribe(\n  event: EventClass<unknown> | string,\n  options: SubscribeDecoratorOptions = {},\n): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void {\n  return (target, propertyKey) => {\n    // Keyed by (prototype, property) rather than stored on the method function, so a\n    // decorator that later replaces the method does not drop the subscription.\n    const existing =\n      (Reflect.getOwnMetadata(SUBSCRIBE_METADATA_KEY, target, propertyKey) as\n        SubscribeMetadata[] | undefined) ?? [];\n    Reflect.defineMetadata(\n      SUBSCRIBE_METADATA_KEY,\n      [...existing, { event, options }],\n      target,\n      propertyKey,\n    );\n  };\n}\n\n/**\n * Reads the `@Subscribe` declarations of a method, in declaration order. The\n * prototype chain is searched, so a subclass inherits the declarations of the\n * nearest ancestor that declares them.\n */\nexport function readSubscribeMetadata(\n  prototype: object,\n  propertyKey: string | symbol,\n): readonly SubscribeMetadata[] {\n  return (\n    (Reflect.getMetadata(SUBSCRIBE_METADATA_KEY, prototype, propertyKey) as\n      SubscribeMetadata[] | undefined) ?? []\n  );\n}\n","import { Inject, Injectable, type OnModuleInit } from '@nestjs/common';\nimport { DiscoveryService, MetadataScanner } from '@nestjs/core';\nimport type { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper.js';\nimport { ConfigurationError, RelayBus, type EventHandler } from '@relaybus/core';\nimport { readSubscribeMetadata, type SubscribeMetadata } from './subscribe.decorator.js';\n\ninterface SubscribedMethod {\n  readonly methodName: string;\n  readonly declarations: readonly SubscribeMetadata[];\n}\n\n/**\n * Finds every `@Subscribe` method of every singleton provider in the\n * application and registers it on the bus before the bus starts. Providers\n * that are request-scoped or transient, directly or through a dependency, and\n * declare `@Subscribe` methods fail the boot. A request-scoped provider whose\n * token is neither a class nor an instance carrying the decorated prototype\n * (for example a string-token factory) cannot be inspected and is skipped.\n */\n@Injectable()\nexport class RelayBusHandlerExplorer implements OnModuleInit {\n  constructor(\n    @Inject(DiscoveryService) private readonly discovery: DiscoveryService,\n    @Inject(MetadataScanner) private readonly metadataScanner: MetadataScanner,\n    @Inject(RelayBus) private readonly bus: RelayBus,\n  ) {}\n\n  onModuleInit(): void {\n    const registeredBy = new Map<string, string>();\n    const visited = new Map<object, Set<string>>();\n    for (const wrapper of this.discovery.getProviders()) {\n      if (wrapper.isTransient || !wrapper.isDependencyTreeStatic()) {\n        this.assertNoHandlers(wrapper);\n        continue;\n      }\n      const instance = wrapper.instance as unknown;\n      if (typeof instance !== 'object' || instance === null) {\n        continue;\n      }\n      const prototype = Object.getPrototypeOf(instance) as object | null;\n      if (prototype === null) {\n        continue;\n      }\n      const className = instance.constructor.name;\n      for (const { methodName, declarations } of this.subscribedMethods(prototype)) {\n        // A `useExisting` alias exposes the same instance under another token.\n        const seen = visited.get(instance) ?? new Set<string>();\n        visited.set(instance, seen);\n        if (seen.has(methodName)) {\n          continue;\n        }\n        seen.add(methodName);\n        const method = (instance as Record<string, unknown>)[methodName] as (\n          ...args: Parameters<EventHandler>\n        ) => unknown;\n        const location = `${className}.${methodName}`;\n        for (const { event, options } of declarations) {\n          const id = options.id ?? location;\n          const previous = registeredBy.get(id);\n          if (previous !== undefined) {\n            throw new ConfigurationError(\n              `Handler id '${id}' is used by both ${previous} and ${location}; ` +\n                `pass a unique { id } to @Subscribe`,\n            );\n          }\n          registeredBy.set(id, location);\n          // Core resolves both classes and type strings; the overloads cannot express the union.\n          this.bus.subscribe(\n            event as never,\n            (envelope, context) => method.call(instance, envelope, context),\n            { ...options, id },\n          );\n        }\n      }\n    }\n  }\n\n  private subscribedMethods(prototype: object): SubscribedMethod[] {\n    const methods: SubscribedMethod[] = [];\n    for (const methodName of this.metadataScanner.getAllMethodNames(prototype)) {\n      const declarations = readSubscribeMetadata(prototype, methodName);\n      if (declarations.length > 0) {\n        methods.push({ methodName, declarations });\n      }\n    }\n    return methods;\n  }\n\n  /**\n   * Request-scoped and transient wrappers have no usable instance (a factory\n   * wrapper has none at all), so the decorated prototype is taken from the\n   * provider class, or from the provider token for factories when it is a class.\n   */\n  private assertNoHandlers(wrapper: InstanceWrapper): void {\n    const type = (wrapper.isFactory ? wrapper.token : wrapper.metatype) as unknown;\n    const prototype = typeof type === 'function' ? (type.prototype as object) : null;\n    const [first] = prototype === null ? [] : this.subscribedMethods(prototype);\n    if (first !== undefined) {\n      throw new ConfigurationError(\n        `${(prototype as { constructor: { name: string } }).constructor.name}.${first.methodName} ` +\n          `uses @Subscribe but its provider is request-scoped or transient ` +\n          `(directly or through a dependency); handlers must be singleton providers`,\n      );\n    }\n  }\n}\n","import { ConfigurableModuleBuilder } from '@nestjs/common';\nimport type { RelayBusOptions } from '@relaybus/core';\n\n/**\n * Options of {@link RelayBusModule}: everything {@link RelayBusOptions} accepts\n * except `logger`, which is always a Nest `Logger` with context `RelayBus`\n * (configure it with `app.useLogger`). Only `store` is required.\n */\nexport type RelayBusModuleOptions<TTransaction = unknown> = Omit<\n  RelayBusOptions<TTransaction>,\n  'logger'\n>;\n\n/** Module-level extras accepted next to the options by `forRoot` and `forRootAsync`. */\nexport interface RelayBusModuleExtras {\n  /** Make `RelayBus` and `RelayBusHealth` injectable everywhere. Default true. */\n  readonly isGlobal?: boolean;\n}\n\n/** Implemented by classes passed as `useClass` / `useExisting` to `forRootAsync`. */\nexport interface RelayBusModuleOptionsFactory {\n  create(): Promise<RelayBusModuleOptions> | RelayBusModuleOptions;\n}\n\nexport const {\n  ConfigurableModuleClass: RelayBusConfigurableModule,\n  MODULE_OPTIONS_TOKEN: RELAYBUS_MODULE_OPTIONS,\n} = new ConfigurableModuleBuilder<RelayBusModuleOptions>()\n  .setClassMethodName('forRoot')\n  .setExtras<RelayBusModuleExtras>({ isGlobal: true }, (definition, extras) => ({\n    ...definition,\n    global: extras.isGlobal === true,\n  }))\n  .build();\n","import { Inject, Injectable } from '@nestjs/common';\nimport { RelayBus, systemClock, type EventStoreStatistics } from '@relaybus/core';\nimport { RELAYBUS_MODULE_OPTIONS, type RelayBusModuleOptions } from './module-options.js';\n\n/** Result of {@link RelayBusHealth.check}. */\nexport interface RelayBusHealthReport {\n  /**\n   * `down` when the bus is not running, a transport reports itself not ready\n   * (dead Kafka consumer, disconnected RabbitMQ) or the store cannot be queried.\n   */\n  readonly status: 'up' | 'down';\n  readonly running: boolean;\n  /** `bus.isReady()`: running and every transport ready. */\n  readonly ready: boolean;\n  /** Number of registered handlers and routes. */\n  readonly handlers: number;\n  /** Delivery counts; absent when the bus is not running or the store failed. */\n  readonly statistics?: EventStoreStatistics;\n  /** Milliseconds the oldest due delivery has waited; 0 when nothing is due. */\n  readonly lagMilliseconds?: number;\n  /** Message of the store error, when the statistics query failed. */\n  readonly error?: string;\n}\n\n/**\n * Health probe of the bus without a dependency on `@nestjs/terminus`. Wrap\n * {@link check} in a terminus indicator (see the README). The lag is measured\n * with the `clock` given to the module options (the system clock by default),\n * the same clock the bus uses.\n */\n@Injectable()\nexport class RelayBusHealth {\n  constructor(\n    @Inject(RelayBus) private readonly bus: RelayBus,\n    @Inject(RELAYBUS_MODULE_OPTIONS) private readonly options: RelayBusModuleOptions,\n  ) {}\n\n  async check(): Promise<RelayBusHealthReport> {\n    const running = this.bus.isRunning;\n    const ready = this.bus.isReady();\n    const handlers = this.bus.handlers().length;\n    if (!running) {\n      return { status: 'down', running, ready, handlers };\n    }\n    try {\n      const statistics = await this.bus.statistics();\n      const clock = this.options.clock ?? systemClock;\n      const lagMilliseconds =\n        statistics.oldestDueAt === null\n          ? 0\n          : Math.max(0, clock.now().getTime() - statistics.oldestDueAt.getTime());\n      return {\n        status: ready ? 'up' : 'down',\n        running,\n        ready,\n        handlers,\n        statistics,\n        lagMilliseconds,\n      };\n    } catch (error) {\n      return {\n        status: 'down',\n        running,\n        ready,\n        handlers,\n        error: error instanceof Error ? error.message : String(error),\n      };\n    }\n  }\n}\n","import {\n  Inject,\n  Injectable,\n  type BeforeApplicationShutdown,\n  type OnApplicationBootstrap,\n} from '@nestjs/common';\nimport { RelayBus } from '@relaybus/core';\n\n/**\n * Starts the bus once every handler is registered and the application has\n * bootstrapped, and stops it (draining running handlers) on shutdown. A start\n * failure rejects the hook, so the application does not boot.\n */\n@Injectable()\nexport class RelayBusLifecycle implements OnApplicationBootstrap, BeforeApplicationShutdown {\n  constructor(@Inject(RelayBus) private readonly bus: RelayBus) {}\n\n  async onApplicationBootstrap(): Promise<void> {\n    await this.bus.start();\n  }\n\n  async beforeApplicationShutdown(): Promise<void> {\n    await this.bus.stop();\n  }\n}\n","import { Logger, Module } from '@nestjs/common';\nimport { DiscoveryModule } from '@nestjs/core';\nimport { RelayBus } from '@relaybus/core';\nimport { RelayBusHandlerExplorer } from './handler-explorer.js';\nimport {\n  RELAYBUS_MODULE_OPTIONS,\n  RelayBusConfigurableModule,\n  type RelayBusModuleOptions,\n} from './module-options.js';\nimport { RelayBusHealth } from './relay-bus-health.js';\nimport { RelayBusLifecycle } from './relay-bus-lifecycle.js';\n\n/**\n * Registers one {@link RelayBus} for the application, discovers `@Subscribe`\n * handlers in every module, starts the bus after bootstrap and stops it on\n * shutdown. Global unless `isGlobal: false`.\n *\n * ```ts\n * RelayBusModule.forRoot({ store: new PostgresEventStore({ pool }), source: 'orders' })\n * ```\n */\n@Module({\n  imports: [DiscoveryModule],\n  providers: [\n    {\n      provide: RelayBus,\n      inject: [RELAYBUS_MODULE_OPTIONS],\n      useFactory: (options: RelayBusModuleOptions) =>\n        new RelayBus({ ...options, logger: new Logger('RelayBus') }),\n    },\n    RelayBusHandlerExplorer,\n    RelayBusLifecycle,\n    RelayBusHealth,\n  ],\n  exports: [RelayBus, RelayBusHealth],\n})\nexport class RelayBusModule extends RelayBusConfigurableModule {}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,143 @@
+import * as _nestjs_common from '@nestjs/common';
+import { OnModuleInit, OnApplicationBootstrap, BeforeApplicationShutdown } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import { RelayBus, RelayBusOptions, EventStoreStatistics, EventClass, SubscribeOptions, EventEnvelope, HandlerContext } from '@relaybus/core';
+export { RelayBus } from '@relaybus/core';
+
+/**
+ * Finds every `@Subscribe` method of every singleton provider in the
+ * application and registers it on the bus before the bus starts. Providers
+ * that are request-scoped or transient, directly or through a dependency, and
+ * declare `@Subscribe` methods fail the boot. A request-scoped provider whose
+ * token is neither a class nor an instance carrying the decorated prototype
+ * (for example a string-token factory) cannot be inspected and is skipped.
+ */
+declare class RelayBusHandlerExplorer implements OnModuleInit {
+    private readonly discovery;
+    private readonly metadataScanner;
+    private readonly bus;
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, bus: RelayBus);
+    onModuleInit(): void;
+    private subscribedMethods;
+    /**
+     * Request-scoped and transient wrappers have no usable instance (a factory
+     * wrapper has none at all), so the decorated prototype is taken from the
+     * provider class, or from the provider token for factories when it is a class.
+     */
+    private assertNoHandlers;
+}
+
+/**
+ * Options of {@link RelayBusModule}: everything {@link RelayBusOptions} accepts
+ * except `logger`, which is always a Nest `Logger` with context `RelayBus`
+ * (configure it with `app.useLogger`). Only `store` is required.
+ */
+type RelayBusModuleOptions<TTransaction = unknown> = Omit<RelayBusOptions<TTransaction>, 'logger'>;
+/** Module-level extras accepted next to the options by `forRoot` and `forRootAsync`. */
+interface RelayBusModuleExtras {
+    /** Make `RelayBus` and `RelayBusHealth` injectable everywhere. Default true. */
+    readonly isGlobal?: boolean;
+}
+/** Implemented by classes passed as `useClass` / `useExisting` to `forRootAsync`. */
+interface RelayBusModuleOptionsFactory {
+    create(): Promise<RelayBusModuleOptions> | RelayBusModuleOptions;
+}
+declare const RelayBusConfigurableModule: _nestjs_common.ConfigurableModuleCls<RelayBusModuleOptions<unknown>, "forRoot", "create", RelayBusModuleExtras>;
+
+/** Result of {@link RelayBusHealth.check}. */
+interface RelayBusHealthReport {
+    /**
+     * `down` when the bus is not running, a transport reports itself not ready
+     * (dead Kafka consumer, disconnected RabbitMQ) or the store cannot be queried.
+     */
+    readonly status: 'up' | 'down';
+    readonly running: boolean;
+    /** `bus.isReady()`: running and every transport ready. */
+    readonly ready: boolean;
+    /** Number of registered handlers and routes. */
+    readonly handlers: number;
+    /** Delivery counts; absent when the bus is not running or the store failed. */
+    readonly statistics?: EventStoreStatistics;
+    /** Milliseconds the oldest due delivery has waited; 0 when nothing is due. */
+    readonly lagMilliseconds?: number;
+    /** Message of the store error, when the statistics query failed. */
+    readonly error?: string;
+}
+/**
+ * Health probe of the bus without a dependency on `@nestjs/terminus`. Wrap
+ * {@link check} in a terminus indicator (see the README). The lag is measured
+ * with the `clock` given to the module options (the system clock by default),
+ * the same clock the bus uses.
+ */
+declare class RelayBusHealth {
+    private readonly bus;
+    private readonly options;
+    constructor(bus: RelayBus, options: RelayBusModuleOptions);
+    check(): Promise<RelayBusHealthReport>;
+}
+
+/**
+ * Starts the bus once every handler is registered and the application has
+ * bootstrapped, and stops it (draining running handlers) on shutdown. A start
+ * failure rejects the hook, so the application does not boot.
+ */
+declare class RelayBusLifecycle implements OnApplicationBootstrap, BeforeApplicationShutdown {
+    private readonly bus;
+    constructor(bus: RelayBus);
+    onApplicationBootstrap(): Promise<void>;
+    beforeApplicationShutdown(): Promise<void>;
+}
+
+/**
+ * Registers one {@link RelayBus} for the application, discovers `@Subscribe`
+ * handlers in every module, starts the bus after bootstrap and stops it on
+ * shutdown. Global unless `isGlobal: false`.
+ *
+ * ```ts
+ * RelayBusModule.forRoot({ store: new PostgresEventStore({ pool }), source: 'orders' })
+ * ```
+ */
+declare class RelayBusModule extends RelayBusConfigurableModule {
+}
+
+/**
+ * Options of {@link Subscribe}: the core {@link SubscribeOptions}, except that
+ * `id` is optional and defaults to `ClassName.methodName`.
+ */
+type SubscribeDecoratorOptions = Omit<SubscribeOptions, 'id'> & {
+    /**
+     * Stable id of the handler. Deliveries are recorded under it, so renaming it
+     * (or the class or method it is derived from) orphans pending deliveries.
+     * Default: `${ClassName}.${methodName}`. Required when one method carries
+     * several `@Subscribe` decorators.
+     */
+    readonly id?: string;
+};
+/** What one `@Subscribe` decorator recorded on a method. */
+interface SubscribeMetadata {
+    readonly event: EventClass<unknown> | string;
+    readonly options: SubscribeDecoratorOptions;
+}
+type HandlerMethod<TPayload> = (event: EventEnvelope<TPayload>, context: HandlerContext<never>) => unknown;
+type SubscribeDecorator<TPayload> = <TMethod extends HandlerMethod<TPayload>>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<TMethod>) => void;
+/**
+ * Subscribes a provider method to an event class or type. The method is
+ * registered with `bus.subscribe` when the module initialises, with `this`
+ * bound to the provider instance, and receives `(envelope, context)`.
+ *
+ * The provider must be a singleton (default scope) and belong to any module of
+ * the application. The decorator name differs from `@nestjs/event-emitter`'s
+ * `@OnEvent` so both can be used in one application.
+ *
+ * ```ts
+ * @Injectable()
+ * export class ShippingHandlers {
+ *   @Subscribe(OrderPlaced, { transactional: true })
+ *   async onOrderPlaced(event: EventEnvelope<{ orderId: string }>, context: HandlerContext) {}
+ * }
+ * ```
+ */
+declare function Subscribe<TPayload>(event: EventClass<TPayload>, options?: SubscribeDecoratorOptions): SubscribeDecorator<TPayload>;
+declare function Subscribe(eventType: string, options?: SubscribeDecoratorOptions): SubscribeDecorator<never>;
+
+export { RelayBusHandlerExplorer, RelayBusHealth, type RelayBusHealthReport, RelayBusLifecycle, RelayBusModule, type RelayBusModuleExtras, type RelayBusModuleOptions, type RelayBusModuleOptionsFactory, Subscribe, type SubscribeDecoratorOptions, type SubscribeMetadata };

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+import * as _nestjs_common from '@nestjs/common';
+import { OnModuleInit, OnApplicationBootstrap, BeforeApplicationShutdown } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import { RelayBus, RelayBusOptions, EventStoreStatistics, EventClass, SubscribeOptions, EventEnvelope, HandlerContext } from '@relaybus/core';
+export { RelayBus } from '@relaybus/core';
+
+/**
+ * Finds every `@Subscribe` method of every singleton provider in the
+ * application and registers it on the bus before the bus starts. Providers
+ * that are request-scoped or transient, directly or through a dependency, and
+ * declare `@Subscribe` methods fail the boot. A request-scoped provider whose
+ * token is neither a class nor an instance carrying the decorated prototype
+ * (for example a string-token factory) cannot be inspected and is skipped.
+ */
+declare class RelayBusHandlerExplorer implements OnModuleInit {
+    private readonly discovery;
+    private readonly metadataScanner;
+    private readonly bus;
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, bus: RelayBus);
+    onModuleInit(): void;
+    private subscribedMethods;
+    /**
+     * Request-scoped and transient wrappers have no usable instance (a factory
+     * wrapper has none at all), so the decorated prototype is taken from the
+     * provider class, or from the provider token for factories when it is a class.
+     */
+    private assertNoHandlers;
+}
+
+/**
+ * Options of {@link RelayBusModule}: everything {@link RelayBusOptions} accepts
+ * except `logger`, which is always a Nest `Logger` with context `RelayBus`
+ * (configure it with `app.useLogger`). Only `store` is required.
+ */
+type RelayBusModuleOptions<TTransaction = unknown> = Omit<RelayBusOptions<TTransaction>, 'logger'>;
+/** Module-level extras accepted next to the options by `forRoot` and `forRootAsync`. */
+interface RelayBusModuleExtras {
+    /** Make `RelayBus` and `RelayBusHealth` injectable everywhere. Default true. */
+    readonly isGlobal?: boolean;
+}
+/** Implemented by classes passed as `useClass` / `useExisting` to `forRootAsync`. */
+interface RelayBusModuleOptionsFactory {
+    create(): Promise<RelayBusModuleOptions> | RelayBusModuleOptions;
+}
+declare const RelayBusConfigurableModule: _nestjs_common.ConfigurableModuleCls<RelayBusModuleOptions<unknown>, "forRoot", "create", RelayBusModuleExtras>;
+
+/** Result of {@link RelayBusHealth.check}. */
+interface RelayBusHealthReport {
+    /**
+     * `down` when the bus is not running, a transport reports itself not ready
+     * (dead Kafka consumer, disconnected RabbitMQ) or the store cannot be queried.
+     */
+    readonly status: 'up' | 'down';
+    readonly running: boolean;
+    /** `bus.isReady()`: running and every transport ready. */
+    readonly ready: boolean;
+    /** Number of registered handlers and routes. */
+    readonly handlers: number;
+    /** Delivery counts; absent when the bus is not running or the store failed. */
+    readonly statistics?: EventStoreStatistics;
+    /** Milliseconds the oldest due delivery has waited; 0 when nothing is due. */
+    readonly lagMilliseconds?: number;
+    /** Message of the store error, when the statistics query failed. */
+    readonly error?: string;
+}
+/**
+ * Health probe of the bus without a dependency on `@nestjs/terminus`. Wrap
+ * {@link check} in a terminus indicator (see the README). The lag is measured
+ * with the `clock` given to the module options (the system clock by default),
+ * the same clock the bus uses.
+ */
+declare class RelayBusHealth {
+    private readonly bus;
+    private readonly options;
+    constructor(bus: RelayBus, options: RelayBusModuleOptions);
+    check(): Promise<RelayBusHealthReport>;
+}
+
+/**
+ * Starts the bus once every handler is registered and the application has
+ * bootstrapped, and stops it (draining running handlers) on shutdown. A start
+ * failure rejects the hook, so the application does not boot.
+ */
+declare class RelayBusLifecycle implements OnApplicationBootstrap, BeforeApplicationShutdown {
+    private readonly bus;
+    constructor(bus: RelayBus);
+    onApplicationBootstrap(): Promise<void>;
+    beforeApplicationShutdown(): Promise<void>;
+}
+
+/**
+ * Registers one {@link RelayBus} for the application, discovers `@Subscribe`
+ * handlers in every module, starts the bus after bootstrap and stops it on
+ * shutdown. Global unless `isGlobal: false`.
+ *
+ * ```ts
+ * RelayBusModule.forRoot({ store: new PostgresEventStore({ pool }), source: 'orders' })
+ * ```
+ */
+declare class RelayBusModule extends RelayBusConfigurableModule {
+}
+
+/**
+ * Options of {@link Subscribe}: the core {@link SubscribeOptions}, except that
+ * `id` is optional and defaults to `ClassName.methodName`.
+ */
+type SubscribeDecoratorOptions = Omit<SubscribeOptions, 'id'> & {
+    /**
+     * Stable id of the handler. Deliveries are recorded under it, so renaming it
+     * (or the class or method it is derived from) orphans pending deliveries.
+     * Default: `${ClassName}.${methodName}`. Required when one method carries
+     * several `@Subscribe` decorators.
+     */
+    readonly id?: string;
+};
+/** What one `@Subscribe` decorator recorded on a method. */
+interface SubscribeMetadata {
+    readonly event: EventClass<unknown> | string;
+    readonly options: SubscribeDecoratorOptions;
+}
+type HandlerMethod<TPayload> = (event: EventEnvelope<TPayload>, context: HandlerContext<never>) => unknown;
+type SubscribeDecorator<TPayload> = <TMethod extends HandlerMethod<TPayload>>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<TMethod>) => void;
+/**
+ * Subscribes a provider method to an event class or type. The method is
+ * registered with `bus.subscribe` when the module initialises, with `this`
+ * bound to the provider instance, and receives `(envelope, context)`.
+ *
+ * The provider must be a singleton (default scope) and belong to any module of
+ * the application. The decorator name differs from `@nestjs/event-emitter`'s
+ * `@OnEvent` so both can be used in one application.
+ *
+ * ```ts
+ * @Injectable()
+ * export class ShippingHandlers {
+ *   @Subscribe(OrderPlaced, { transactional: true })
+ *   async onOrderPlaced(event: EventEnvelope<{ orderId: string }>, context: HandlerContext) {}
+ * }
+ * ```
+ */
+declare function Subscribe<TPayload>(event: EventClass<TPayload>, options?: SubscribeDecoratorOptions): SubscribeDecorator<TPayload>;
+declare function Subscribe(eventType: string, options?: SubscribeDecoratorOptions): SubscribeDecorator<never>;
+
+export { RelayBusHandlerExplorer, RelayBusHealth, type RelayBusHealthReport, RelayBusLifecycle, RelayBusModule, type RelayBusModuleExtras, type RelayBusModuleOptions, type RelayBusModuleOptionsFactory, Subscribe, type SubscribeDecoratorOptions, type SubscribeMetadata };

package/dist/index.js

@@ -0,0 +1,206 @@
+import { Injectable, Inject, ConfigurableModuleBuilder, Module, Logger } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner, DiscoveryModule } from '@nestjs/core';
+import { RelayBus, systemClock, ConfigurationError } from '@relaybus/core';
+export { RelayBus } from '@relaybus/core';
+import 'reflect-metadata';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+var SUBSCRIBE_METADATA_KEY = /* @__PURE__ */ Symbol.for("relaybus.nestjs.subscribe");
+function Subscribe(event, options = {}) {
+  return (target, propertyKey) => {
+    const existing = Reflect.getOwnMetadata(SUBSCRIBE_METADATA_KEY, target, propertyKey) ?? [];
+    Reflect.defineMetadata(
+      SUBSCRIBE_METADATA_KEY,
+      [...existing, { event, options }],
+      target,
+      propertyKey
+    );
+  };
+}
+function readSubscribeMetadata(prototype, propertyKey) {
+  return Reflect.getMetadata(SUBSCRIBE_METADATA_KEY, prototype, propertyKey) ?? [];
+}
+
+// src/handler-explorer.ts
+var RelayBusHandlerExplorer = class {
+  constructor(discovery, metadataScanner, bus) {
+    this.discovery = discovery;
+    this.metadataScanner = metadataScanner;
+    this.bus = bus;
+  }
+  discovery;
+  metadataScanner;
+  bus;
+  onModuleInit() {
+    const registeredBy = /* @__PURE__ */ new Map();
+    const visited = /* @__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) {
+        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;
+        }
+        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 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 }
+          );
+        }
+      }
+    }
+  }
+  subscribedMethods(prototype) {
+    const methods = [];
+    for (const methodName of this.metadataScanner.getAllMethodNames(prototype)) {
+      const declarations = readSubscribeMetadata(prototype, methodName);
+      if (declarations.length > 0) {
+        methods.push({ methodName, declarations });
+      }
+    }
+    return methods;
+  }
+  /**
+   * Request-scoped and transient wrappers have no usable instance (a factory
+   * wrapper has none at all), so the decorated prototype is taken from the
+   * provider class, or from the provider token for factories when it is a class.
+   */
+  assertNoHandlers(wrapper) {
+    const type = wrapper.isFactory ? wrapper.token : wrapper.metatype;
+    const prototype = typeof type === "function" ? type.prototype : null;
+    const [first] = prototype === null ? [] : this.subscribedMethods(prototype);
+    if (first !== void 0) {
+      throw new 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`
+      );
+    }
+  }
+};
+RelayBusHandlerExplorer = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(DiscoveryService)),
+  __decorateParam(1, Inject(MetadataScanner)),
+  __decorateParam(2, Inject(RelayBus))
+], RelayBusHandlerExplorer);
+var {
+  ConfigurableModuleClass: RelayBusConfigurableModule,
+  MODULE_OPTIONS_TOKEN: RELAYBUS_MODULE_OPTIONS
+} = new ConfigurableModuleBuilder().setClassMethodName("forRoot").setExtras({ isGlobal: true }, (definition, extras) => ({
+  ...definition,
+  global: extras.isGlobal === true
+})).build();
+
+// src/relay-bus-health.ts
+var RelayBusHealth = class {
+  constructor(bus, options) {
+    this.bus = bus;
+    this.options = options;
+  }
+  bus;
+  options;
+  async check() {
+    const running = this.bus.isRunning;
+    const ready = this.bus.isReady();
+    const handlers = this.bus.handlers().length;
+    if (!running) {
+      return { status: "down", running, ready, handlers };
+    }
+    try {
+      const statistics = await this.bus.statistics();
+      const clock = this.options.clock ?? systemClock;
+      const lagMilliseconds = statistics.oldestDueAt === null ? 0 : Math.max(0, clock.now().getTime() - statistics.oldestDueAt.getTime());
+      return {
+        status: ready ? "up" : "down",
+        running,
+        ready,
+        handlers,
+        statistics,
+        lagMilliseconds
+      };
+    } catch (error) {
+      return {
+        status: "down",
+        running,
+        ready,
+        handlers,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+};
+RelayBusHealth = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(RelayBus)),
+  __decorateParam(1, Inject(RELAYBUS_MODULE_OPTIONS))
+], RelayBusHealth);
+var RelayBusLifecycle = class {
+  constructor(bus) {
+    this.bus = bus;
+  }
+  bus;
+  async onApplicationBootstrap() {
+    await this.bus.start();
+  }
+  async beforeApplicationShutdown() {
+    await this.bus.stop();
+  }
+};
+RelayBusLifecycle = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(RelayBus))
+], RelayBusLifecycle);
+var RelayBusModule = class extends RelayBusConfigurableModule {
+};
+RelayBusModule = __decorateClass([
+  Module({
+    imports: [DiscoveryModule],
+    providers: [
+      {
+        provide: RelayBus,
+        inject: [RELAYBUS_MODULE_OPTIONS],
+        useFactory: (options) => new RelayBus({ ...options, logger: new Logger("RelayBus") })
+      },
+      RelayBusHandlerExplorer,
+      RelayBusLifecycle,
+      RelayBusHealth
+    ],
+    exports: [RelayBus, RelayBusHealth]
+  })
+], RelayBusModule);
+
+export { RelayBusHandlerExplorer, RelayBusHealth, RelayBusLifecycle, RelayBusModule, Subscribe };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/subscribe.decorator.ts","../src/handler-explorer.ts","../src/module-options.ts","../src/relay-bus-health.ts","../src/relay-bus-lifecycle.ts","../src/relay-bus.module.ts"],"names":["Injectable","Inject","RelayBus"],"mappings":"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","file":"index.js","sourcesContent":["import 'reflect-metadata';\nimport type { EventClass, EventEnvelope, HandlerContext, SubscribeOptions } from '@relaybus/core';\n\n/**\n * Options of {@link Subscribe}: the core {@link SubscribeOptions}, except that\n * `id` is optional and defaults to `ClassName.methodName`.\n */\nexport type SubscribeDecoratorOptions = Omit<SubscribeOptions, 'id'> & {\n  /**\n   * Stable id of the handler. Deliveries are recorded under it, so renaming it\n   * (or the class or method it is derived from) orphans pending deliveries.\n   * Default: `${ClassName}.${methodName}`. Required when one method carries\n   * several `@Subscribe` decorators.\n   */\n  readonly id?: string;\n};\n\n/** What one `@Subscribe` decorator recorded on a method. */\nexport interface SubscribeMetadata {\n  readonly event: EventClass<unknown> | string;\n  readonly options: SubscribeDecoratorOptions;\n}\n\nconst SUBSCRIBE_METADATA_KEY = Symbol.for('relaybus.nestjs.subscribe');\n\ntype HandlerMethod<TPayload> = (\n  event: EventEnvelope<TPayload>,\n  context: HandlerContext<never>,\n) => unknown;\n\ntype SubscribeDecorator<TPayload> = <TMethod extends HandlerMethod<TPayload>>(\n  target: object,\n  propertyKey: string | symbol,\n  descriptor: TypedPropertyDescriptor<TMethod>,\n) => void;\n\n/**\n * Subscribes a provider method to an event class or type. The method is\n * registered with `bus.subscribe` when the module initialises, with `this`\n * bound to the provider instance, and receives `(envelope, context)`.\n *\n * The provider must be a singleton (default scope) and belong to any module of\n * the application. The decorator name differs from `@nestjs/event-emitter`'s\n * `@OnEvent` so both can be used in one application.\n *\n * ```ts\n * @Injectable()\n * export class ShippingHandlers {\n *   @Subscribe(OrderPlaced, { transactional: true })\n *   async onOrderPlaced(event: EventEnvelope<{ orderId: string }>, context: HandlerContext) {}\n * }\n * ```\n */\nexport function Subscribe<TPayload>(\n  event: EventClass<TPayload>,\n  options?: SubscribeDecoratorOptions,\n): SubscribeDecorator<TPayload>;\nexport function Subscribe(\n  eventType: string,\n  options?: SubscribeDecoratorOptions,\n): SubscribeDecorator<never>;\nexport function Subscribe(\n  event: EventClass<unknown> | string,\n  options: SubscribeDecoratorOptions = {},\n): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void {\n  return (target, propertyKey) => {\n    // Keyed by (prototype, property) rather than stored on the method function, so a\n    // decorator that later replaces the method does not drop the subscription.\n    const existing =\n      (Reflect.getOwnMetadata(SUBSCRIBE_METADATA_KEY, target, propertyKey) as\n        SubscribeMetadata[] | undefined) ?? [];\n    Reflect.defineMetadata(\n      SUBSCRIBE_METADATA_KEY,\n      [...existing, { event, options }],\n      target,\n      propertyKey,\n    );\n  };\n}\n\n/**\n * Reads the `@Subscribe` declarations of a method, in declaration order. The\n * prototype chain is searched, so a subclass inherits the declarations of the\n * nearest ancestor that declares them.\n */\nexport function readSubscribeMetadata(\n  prototype: object,\n  propertyKey: string | symbol,\n): readonly SubscribeMetadata[] {\n  return (\n    (Reflect.getMetadata(SUBSCRIBE_METADATA_KEY, prototype, propertyKey) as\n      SubscribeMetadata[] | undefined) ?? []\n  );\n}\n","import { Inject, Injectable, type OnModuleInit } from '@nestjs/common';\nimport { DiscoveryService, MetadataScanner } from '@nestjs/core';\nimport type { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper.js';\nimport { ConfigurationError, RelayBus, type EventHandler } from '@relaybus/core';\nimport { readSubscribeMetadata, type SubscribeMetadata } from './subscribe.decorator.js';\n\ninterface SubscribedMethod {\n  readonly methodName: string;\n  readonly declarations: readonly SubscribeMetadata[];\n}\n\n/**\n * Finds every `@Subscribe` method of every singleton provider in the\n * application and registers it on the bus before the bus starts. Providers\n * that are request-scoped or transient, directly or through a dependency, and\n * declare `@Subscribe` methods fail the boot. A request-scoped provider whose\n * token is neither a class nor an instance carrying the decorated prototype\n * (for example a string-token factory) cannot be inspected and is skipped.\n */\n@Injectable()\nexport class RelayBusHandlerExplorer implements OnModuleInit {\n  constructor(\n    @Inject(DiscoveryService) private readonly discovery: DiscoveryService,\n    @Inject(MetadataScanner) private readonly metadataScanner: MetadataScanner,\n    @Inject(RelayBus) private readonly bus: RelayBus,\n  ) {}\n\n  onModuleInit(): void {\n    const registeredBy = new Map<string, string>();\n    const visited = new Map<object, Set<string>>();\n    for (const wrapper of this.discovery.getProviders()) {\n      if (wrapper.isTransient || !wrapper.isDependencyTreeStatic()) {\n        this.assertNoHandlers(wrapper);\n        continue;\n      }\n      const instance = wrapper.instance as unknown;\n      if (typeof instance !== 'object' || instance === null) {\n        continue;\n      }\n      const prototype = Object.getPrototypeOf(instance) as object | null;\n      if (prototype === null) {\n        continue;\n      }\n      const className = instance.constructor.name;\n      for (const { methodName, declarations } of this.subscribedMethods(prototype)) {\n        // A `useExisting` alias exposes the same instance under another token.\n        const seen = visited.get(instance) ?? new Set<string>();\n        visited.set(instance, seen);\n        if (seen.has(methodName)) {\n          continue;\n        }\n        seen.add(methodName);\n        const method = (instance as Record<string, unknown>)[methodName] as (\n          ...args: Parameters<EventHandler>\n        ) => unknown;\n        const location = `${className}.${methodName}`;\n        for (const { event, options } of declarations) {\n          const id = options.id ?? location;\n          const previous = registeredBy.get(id);\n          if (previous !== undefined) {\n            throw new ConfigurationError(\n              `Handler id '${id}' is used by both ${previous} and ${location}; ` +\n                `pass a unique { id } to @Subscribe`,\n            );\n          }\n          registeredBy.set(id, location);\n          // Core resolves both classes and type strings; the overloads cannot express the union.\n          this.bus.subscribe(\n            event as never,\n            (envelope, context) => method.call(instance, envelope, context),\n            { ...options, id },\n          );\n        }\n      }\n    }\n  }\n\n  private subscribedMethods(prototype: object): SubscribedMethod[] {\n    const methods: SubscribedMethod[] = [];\n    for (const methodName of this.metadataScanner.getAllMethodNames(prototype)) {\n      const declarations = readSubscribeMetadata(prototype, methodName);\n      if (declarations.length > 0) {\n        methods.push({ methodName, declarations });\n      }\n    }\n    return methods;\n  }\n\n  /**\n   * Request-scoped and transient wrappers have no usable instance (a factory\n   * wrapper has none at all), so the decorated prototype is taken from the\n   * provider class, or from the provider token for factories when it is a class.\n   */\n  private assertNoHandlers(wrapper: InstanceWrapper): void {\n    const type = (wrapper.isFactory ? wrapper.token : wrapper.metatype) as unknown;\n    const prototype = typeof type === 'function' ? (type.prototype as object) : null;\n    const [first] = prototype === null ? [] : this.subscribedMethods(prototype);\n    if (first !== undefined) {\n      throw new ConfigurationError(\n        `${(prototype as { constructor: { name: string } }).constructor.name}.${first.methodName} ` +\n          `uses @Subscribe but its provider is request-scoped or transient ` +\n          `(directly or through a dependency); handlers must be singleton providers`,\n      );\n    }\n  }\n}\n","import { ConfigurableModuleBuilder } from '@nestjs/common';\nimport type { RelayBusOptions } from '@relaybus/core';\n\n/**\n * Options of {@link RelayBusModule}: everything {@link RelayBusOptions} accepts\n * except `logger`, which is always a Nest `Logger` with context `RelayBus`\n * (configure it with `app.useLogger`). Only `store` is required.\n */\nexport type RelayBusModuleOptions<TTransaction = unknown> = Omit<\n  RelayBusOptions<TTransaction>,\n  'logger'\n>;\n\n/** Module-level extras accepted next to the options by `forRoot` and `forRootAsync`. */\nexport interface RelayBusModuleExtras {\n  /** Make `RelayBus` and `RelayBusHealth` injectable everywhere. Default true. */\n  readonly isGlobal?: boolean;\n}\n\n/** Implemented by classes passed as `useClass` / `useExisting` to `forRootAsync`. */\nexport interface RelayBusModuleOptionsFactory {\n  create(): Promise<RelayBusModuleOptions> | RelayBusModuleOptions;\n}\n\nexport const {\n  ConfigurableModuleClass: RelayBusConfigurableModule,\n  MODULE_OPTIONS_TOKEN: RELAYBUS_MODULE_OPTIONS,\n} = new ConfigurableModuleBuilder<RelayBusModuleOptions>()\n  .setClassMethodName('forRoot')\n  .setExtras<RelayBusModuleExtras>({ isGlobal: true }, (definition, extras) => ({\n    ...definition,\n    global: extras.isGlobal === true,\n  }))\n  .build();\n","import { Inject, Injectable } from '@nestjs/common';\nimport { RelayBus, systemClock, type EventStoreStatistics } from '@relaybus/core';\nimport { RELAYBUS_MODULE_OPTIONS, type RelayBusModuleOptions } from './module-options.js';\n\n/** Result of {@link RelayBusHealth.check}. */\nexport interface RelayBusHealthReport {\n  /**\n   * `down` when the bus is not running, a transport reports itself not ready\n   * (dead Kafka consumer, disconnected RabbitMQ) or the store cannot be queried.\n   */\n  readonly status: 'up' | 'down';\n  readonly running: boolean;\n  /** `bus.isReady()`: running and every transport ready. */\n  readonly ready: boolean;\n  /** Number of registered handlers and routes. */\n  readonly handlers: number;\n  /** Delivery counts; absent when the bus is not running or the store failed. */\n  readonly statistics?: EventStoreStatistics;\n  /** Milliseconds the oldest due delivery has waited; 0 when nothing is due. */\n  readonly lagMilliseconds?: number;\n  /** Message of the store error, when the statistics query failed. */\n  readonly error?: string;\n}\n\n/**\n * Health probe of the bus without a dependency on `@nestjs/terminus`. Wrap\n * {@link check} in a terminus indicator (see the README). The lag is measured\n * with the `clock` given to the module options (the system clock by default),\n * the same clock the bus uses.\n */\n@Injectable()\nexport class RelayBusHealth {\n  constructor(\n    @Inject(RelayBus) private readonly bus: RelayBus,\n    @Inject(RELAYBUS_MODULE_OPTIONS) private readonly options: RelayBusModuleOptions,\n  ) {}\n\n  async check(): Promise<RelayBusHealthReport> {\n    const running = this.bus.isRunning;\n    const ready = this.bus.isReady();\n    const handlers = this.bus.handlers().length;\n    if (!running) {\n      return { status: 'down', running, ready, handlers };\n    }\n    try {\n      const statistics = await this.bus.statistics();\n      const clock = this.options.clock ?? systemClock;\n      const lagMilliseconds =\n        statistics.oldestDueAt === null\n          ? 0\n          : Math.max(0, clock.now().getTime() - statistics.oldestDueAt.getTime());\n      return {\n        status: ready ? 'up' : 'down',\n        running,\n        ready,\n        handlers,\n        statistics,\n        lagMilliseconds,\n      };\n    } catch (error) {\n      return {\n        status: 'down',\n        running,\n        ready,\n        handlers,\n        error: error instanceof Error ? error.message : String(error),\n      };\n    }\n  }\n}\n","import {\n  Inject,\n  Injectable,\n  type BeforeApplicationShutdown,\n  type OnApplicationBootstrap,\n} from '@nestjs/common';\nimport { RelayBus } from '@relaybus/core';\n\n/**\n * Starts the bus once every handler is registered and the application has\n * bootstrapped, and stops it (draining running handlers) on shutdown. A start\n * failure rejects the hook, so the application does not boot.\n */\n@Injectable()\nexport class RelayBusLifecycle implements OnApplicationBootstrap, BeforeApplicationShutdown {\n  constructor(@Inject(RelayBus) private readonly bus: RelayBus) {}\n\n  async onApplicationBootstrap(): Promise<void> {\n    await this.bus.start();\n  }\n\n  async beforeApplicationShutdown(): Promise<void> {\n    await this.bus.stop();\n  }\n}\n","import { Logger, Module } from '@nestjs/common';\nimport { DiscoveryModule } from '@nestjs/core';\nimport { RelayBus } from '@relaybus/core';\nimport { RelayBusHandlerExplorer } from './handler-explorer.js';\nimport {\n  RELAYBUS_MODULE_OPTIONS,\n  RelayBusConfigurableModule,\n  type RelayBusModuleOptions,\n} from './module-options.js';\nimport { RelayBusHealth } from './relay-bus-health.js';\nimport { RelayBusLifecycle } from './relay-bus-lifecycle.js';\n\n/**\n * Registers one {@link RelayBus} for the application, discovers `@Subscribe`\n * handlers in every module, starts the bus after bootstrap and stops it on\n * shutdown. Global unless `isGlobal: false`.\n *\n * ```ts\n * RelayBusModule.forRoot({ store: new PostgresEventStore({ pool }), source: 'orders' })\n * ```\n */\n@Module({\n  imports: [DiscoveryModule],\n  providers: [\n    {\n      provide: RelayBus,\n      inject: [RELAYBUS_MODULE_OPTIONS],\n      useFactory: (options: RelayBusModuleOptions) =>\n        new RelayBus({ ...options, logger: new Logger('RelayBus') }),\n    },\n    RelayBusHandlerExplorer,\n    RelayBusLifecycle,\n    RelayBusHealth,\n  ],\n  exports: [RelayBus, RelayBusHealth],\n})\nexport class RelayBusModule extends RelayBusConfigurableModule {}\n"]}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@relaybus/nestjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "NestJS module for relaybus: decorator-based event handlers, forRoot/forRootAsync configuration and lifecycle integration.",
+  "license": "MIT",
+  "author": "Berkcan Şavur <berkcansavur@gmail.com>",
+  "homepage": "https://github.com/berkcansavur/relaybus#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/berkcansavur/relaybus.git",
+    "directory": "packages/nestjs"
+  },
+  "bugs": "https://github.com/berkcansavur/relaybus/issues",
+  "keywords": [
+    "relaybus",
+    "event-bus",
+    "outbox",
+    "nestjs",
+    "nest",
+    "decorator",
+    "module"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0 || ^12.0.0",
+    "@nestjs/core": "^11.0.0 || ^12.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
+    "rxjs": "^7.1.0",
+    "@relaybus/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "12.1.3",
+    "@nestjs/core": "12.1.3",
+    "@nestjs/testing": "12.1.3",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "@relaybus/testing": "0.1.0",
+    "@relaybus/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit"
+  }
 }