@relaybus/nestjs 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,14 +1,93 @@
-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';
+import { Catalog, SubscribeOptions, EventOf, HandlerContext, CatalogEventSelection, CatalogEntry, RelayBus, RelayBusOptions, EventStoreStatistics, CatalogDeclaration, EventClass, EventEnvelope } from '@relaybus/core';
 export { RelayBus } from '@relaybus/core';
+import * as _nestjs_common from '@nestjs/common';
+import { OnModuleInit, OnApplicationBootstrap, BeforeApplicationShutdown, OnApplicationShutdown, DynamicModule } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner, ModulesContainer } from '@nestjs/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
+ * Options of {@link RelayBusCatalogConsumer}: the core {@link SubscribeOptions} applied to
+ * every handler of the class, except `id`, which is always
+ * `${ClassName}.on${EventName}`, and optionally the events the class consumes.
+ */
+type RelayBusCatalogConsumerOptions<TCatalog extends Catalog = Catalog, TName extends keyof TCatalog = keyof TCatalog> = Omit<SubscribeOptions, 'id'> & CatalogEventSelection<TName>;
+/** What one `@RelayBusCatalogConsumer` decorator recorded on a class. */
+interface RelayBusCatalogConsumerMetadata {
+    readonly catalog: Catalog;
+    /** Subscribe options applied to every handler of the class. */
+    readonly options: Omit<SubscribeOptions, 'id'>;
+    /**
+     * Entries named by `options.events`, whose methods are all required;
+     * undefined when the class consumes whichever handler methods it defines.
+     */
+    readonly selectedEntries: readonly CatalogEntry[] | undefined;
+}
+/**
+ * A class whose instances have a handler method for each of the named catalog
+ * events. The event parameter is checked strictly; the context is typed
+ * `HandlerContext<never>` so a method may declare any transaction type.
+ */
+type RelayBusCatalogConsumerClass<TCatalog extends Catalog, TName extends keyof TCatalog> = abstract new (...args: never[]) => {
+    readonly [TKey in TName & string as `on${TKey}`]: (event: EventOf<TCatalog[TKey]>, context: HandlerContext<never>) => unknown;
+};
+/**
+ * Subscribes a provider class to the events of a catalog: its
+ * `on${EventName}` methods are registered when the module initialises, under
+ * the stable id `${ClassName}.on${EventName}`, with `this` bound to the
+ * provider instance.
+ *
+ * - Without `events`, every handler method the class defines is registered; a
+ *   class that defines none fails the boot, which catches misspelled names.
+ *   `implements HandlersOf<typeof Catalog>` makes the compiler require all of them.
+ * - With `events`, exactly the methods of those events are registered (methods
+ *   of other events are ignored), and a class missing one of them fails to
+ *   compile and fails the boot. This is how a service consumes its part of a
+ *   catalog shared between services.
+ *
+ * `catalogs: [consume(Catalog, { events })]` in the module options makes the
+ * application fail to boot if no provider handles a consumed event. Works next
+ * to `@RelayBusConsumer` in the same class (give a method that carries both a
+ * distinct `@RelayBusConsumer` id). The provider must be a singleton. Declarations
+ * are inherited; a subclass that declares the same catalog again replaces the
+ * inherited declaration of that catalog, and declaring one catalog twice on
+ * the same class throws a {@link ConfigurationError}.
+ *
+ * ```ts
+ * @Injectable()
+ * @RelayBusCatalogConsumer(OrderEvents, { events: ['OrderPlaced'], transactional: true })
+ * export class BillingHandlers {
+ *   onOrderPlaced(event: EventOf<typeof OrderPlaced>) {}
+ * }
+ * ```
+ */
+declare function RelayBusCatalogConsumer<TCatalog extends Catalog>(catalog: TCatalog, options?: Omit<SubscribeOptions, 'id'> & {
+    readonly events?: undefined;
+}): ClassDecorator;
+declare function RelayBusCatalogConsumer<TCatalog extends Catalog, const TName extends keyof TCatalog>(catalog: TCatalog, options: Omit<SubscribeOptions, 'id'> & {
+    readonly events: readonly TName[];
+}): (target: RelayBusCatalogConsumerClass<TCatalog, TName>) => void;
+/**
+ * With options whose `events` are not statically known (a variable typed
+ * {@link RelayBusCatalogConsumerOptions}), the selection is checked when the module
+ * initialises instead of at compile time.
+ */
+declare function RelayBusCatalogConsumer<TCatalog extends Catalog>(catalog: TCatalog, options: RelayBusCatalogConsumerOptions<TCatalog>): ClassDecorator;
+/**
+ * @deprecated Renamed to {@link RelayBusCatalogConsumer}, which behaves identically; this alias is
+ * removed in 1.0.0.
+ */
+declare const EventConsumer: typeof RelayBusCatalogConsumer;
+/** @deprecated Renamed to {@link RelayBusCatalogConsumerOptions}; this alias is removed in 1.0.0. */
+type EventConsumerOptions<TCatalog extends Catalog = Catalog, TName extends keyof TCatalog = keyof TCatalog> = RelayBusCatalogConsumerOptions<TCatalog, TName>;
+/** @deprecated Renamed to {@link RelayBusCatalogConsumerMetadata}; this alias is removed in 1.0.0. */
+type EventConsumerMetadata = RelayBusCatalogConsumerMetadata;
+/** @deprecated Renamed to {@link RelayBusCatalogConsumerClass}; this alias is removed in 1.0.0. */
+type EventConsumerClass<TCatalog extends Catalog, TName extends keyof TCatalog> = RelayBusCatalogConsumerClass<TCatalog, TName>;
+
+/**
+ * Finds every `@RelayBusConsumer` method and every `@RelayBusCatalogConsumer` class among the
+ * singleton providers of the application and registers them on the bus before
+ * the bus starts. Providers that are request-scoped or transient, directly or
+ * through a dependency, and use either decorator 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.
  */
@@ -16,8 +95,17 @@ declare class RelayBusHandlerExplorer implements OnModuleInit {
     private readonly discovery;
     private readonly metadataScanner;
     private readonly bus;
-    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, bus: RelayBus);
+    private readonly modules;
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, bus: RelayBus, modules: ModulesContainer);
     onModuleInit(): void;
+    /** Checks the `RelayBusModule.forFeature` contract of every module that imports one. */
+    private assertModuleContracts;
+    private importersOf;
+    /** Records the event types the provider of `wrapper` consumes under the provider's module. */
+    private recordConsumedTypes;
+    private registerProvider;
+    private registerSubscribedMethod;
+    private registerEventConsumers;
     private subscribedMethods;
     /**
      * Request-scoped and transient wrappers have no usable instance (a factory
@@ -78,19 +166,52 @@ declare class RelayBusHealth {
 
 /**
  * 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.
+ * bootstrapped, and stops it (draining running handlers, within `dispatcher.shutdownTimeout`) on
+ * shutdown: `bus.stop()` resolves at that deadline at the latest, so a hung query or broker cannot
+ * hold `app.close()` until the platform kills the process. A start
+ * failure rejects the hook, so the application does not boot. `@RelayBusTransaction()`
+ * methods find the bus from module initialisation until the application has shut down.
  */
-declare class RelayBusLifecycle implements OnApplicationBootstrap, BeforeApplicationShutdown {
+declare class RelayBusLifecycle implements OnModuleInit, OnApplicationBootstrap, BeforeApplicationShutdown, OnApplicationShutdown {
     private readonly bus;
     constructor(bus: RelayBus);
+    onModuleInit(): void;
     onApplicationBootstrap(): Promise<void>;
     beforeApplicationShutdown(): Promise<void>;
+    /** After the bus stopped, so handlers still draining at shutdown can open transactions. */
+    onApplicationShutdown(): void;
+}
+
+/**
+ * What one feature module consumes and produces, given to `RelayBusModule.forFeature`. Each item is
+ * a whole catalog or a `consume(...)` / `produce(...)` declaration of some of its events.
+ */
+interface RelayBusFeatureOptions {
+    /** Events the importing module handles: each needs a `@RelayBusConsumer` method (or a catalog consumer) among its providers. */
+    readonly consumes?: readonly (Catalog | CatalogDeclaration)[];
+    /** Events the importing module publishes for other services: each needs a route to a transport. */
+    readonly produces?: readonly (Catalog | CatalogDeclaration)[];
+}
+/** One event of a feature contract, named for error messages. */
+type ContractEvent = {
+    /** `Catalog.EventName`. */
+    readonly label: string;
+    readonly type: string;
+};
+/**
+ * The contract of the module that imports `RelayBusModule.forFeature(...)`, checked when the
+ * application initialises.
+ */
+declare class RelayBusFeatureContract {
+    readonly consumes: readonly ContractEvent[];
+    readonly produces: readonly ContractEvent[];
+    /** @throws ConfigurationError for a `produce(...)` in `consumes`, a `consume(...)` in `produces`, or something that is not a catalog. */
+    constructor(options: RelayBusFeatureOptions);
 }
 
 /**
- * Registers one {@link RelayBus} for the application, discovers `@Subscribe`
- * handlers in every module, starts the bus after bootstrap and stops it on
+ * Registers one {@link RelayBus} for the application, discovers `@RelayBusConsumer` and `@RelayBusCatalogConsumer`
+ * handlers in every module, runs `@RelayBusTransaction()` methods on the bus, starts the bus after bootstrap and stops it on
  * shutdown. Global unless `isGlobal: false`.
  *
  * ```ts
@@ -98,28 +219,124 @@ declare class RelayBusLifecycle implements OnApplicationBootstrap, BeforeApplica
  * ```
  */
 declare 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: RelayBusFeatureOptions): DynamicModule;
+}
+
+/**
+ * Carries the contract of `RelayBusModule.forFeature(...)` into the module that imports it. The
+ * contract is checked against that module's providers when the application initialises.
+ */
+declare class RelayBusFeatureModule {
+}
+
+/**
+ * Hands repositories the transaction of the enclosing `@RelayBusTransaction()` method (or
+ * `bus.transaction`, transactional handler, `transactionResolver`), typed as the store's
+ * transaction handle: `PoolClient` for `pg`, a Kysely `Transaction`, a TypeORM `EntityManager`,
+ * a Prisma transaction client, a MongoDB `ClientSession`.
+ *
+ * ```ts
+ * @Injectable()
+ * export class OrderRepository {
+ *   constructor(private readonly transactions: RelayBusTransactionHost<PoolClient>) {}
+ *
+ *   async insert(orderId: string): Promise<void> {
+ *     await this.transactions.current().query('INSERT INTO orders (id) VALUES ($1)', [orderId]);
+ *   }
+ * }
+ * ```
+ */
+declare class RelayBusTransactionHost<TTransaction = unknown> {
+    private readonly bus;
+    constructor(bus: RelayBus<TTransaction>);
+    /**
+     * The active transaction.
+     *
+     * @throws TransactionRequiredError when the caller runs outside every transaction.
+     */
+    current(): TTransaction;
+    /** The active transaction, or undefined outside every transaction. */
+    find(): TTransaction | undefined;
 }
 
+/** The compile error a `@RelayBusTransaction()` on a method that does not return a Promise reads. */
+type RelayBusTransactionNeedsAsyncMethod = '@RelayBusTransaction() needs a method that returns a Promise: make the method async';
+/**
+ * Accepts the descriptor of a method that returns a Promise; any other method fails to compile
+ * with {@link RelayBusTransactionNeedsAsyncMethod} in the message.
+ */
+type AsyncMethodDescriptor<TMethod> = TypedPropertyDescriptor<TMethod> & (TMethod extends (...args: never[]) => PromiseLike<unknown> ? unknown : RelayBusTransactionNeedsAsyncMethod);
+/** What `@RelayBusTransaction()` returns: a method decorator for async methods only. */
+type RelayBusTransactionDecorator = <TMethod extends (...args: never[]) => unknown>(target: object, propertyKey: string | symbol, descriptor: AsyncMethodDescriptor<TMethod>) => void;
+/**
+ * Runs the method in a relaybus transaction: `bus.publish(...)` inside it, and in everything it
+ * awaits, joins the transaction without passing `{ transaction }`, and a repository reads it with
+ * `bus.currentTransaction()` or {@link RelayBusTransactionHost}. The transaction commits when the
+ * method resolves and rolls back when it rejects; it is held to the bus `transactionTimeout`.
+ *
+ * - The method itself is replaced, so `this.other()` calls of decorated methods are transactional
+ *   too, unlike interceptor-based decorators.
+ * - A decorated method called while a transaction is active (another decorated method,
+ *   `bus.transaction`, a transactional handler, or the `transactionResolver`, for example
+ *   `@nestjs-cls/transactional`) joins it instead of opening a second one.
+ * - The bus is the one of the application's `RelayBusModule`; the class does not inject it.
+ * - Only methods that return a Promise compile.
+ *
+ * ```ts
+ * @Injectable()
+ * export class OrderService {
+ *   @RelayBusTransaction()
+ *   async place(orderId: string): Promise<void> {
+ *     await this.orders.insert(orderId);
+ *     await this.bus.publish(new OrderPlaced({ orderId }));
+ *   }
+ * }
+ * ```
+ */
+declare function RelayBusTransaction(): RelayBusTransactionDecorator;
+
 /**
- * Options of {@link Subscribe}: the core {@link SubscribeOptions}, except that
+ * Options of {@link RelayBusConsumer}: the core {@link SubscribeOptions}, except that
  * `id` is optional and defaults to `ClassName.methodName`.
  */
-type SubscribeDecoratorOptions = Omit<SubscribeOptions, 'id'> & {
+type RelayBusConsumerOptions = 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.
+     * several `@RelayBusConsumer` decorators.
      */
     readonly id?: string;
 };
-/** What one `@Subscribe` decorator recorded on a method. */
-interface SubscribeMetadata {
+/** What one `@RelayBusConsumer` decorator recorded on a method. */
+interface RelayBusConsumerMetadata {
     readonly event: EventClass<unknown> | string;
-    readonly options: SubscribeDecoratorOptions;
+    readonly options: RelayBusConsumerOptions;
 }
+/** @deprecated Renamed to {@link RelayBusConsumerOptions}; this alias is removed in 1.0.0. */
+type SubscribeDecoratorOptions = RelayBusConsumerOptions;
+/** @deprecated Renamed to {@link RelayBusConsumerMetadata}; this alias is removed in 1.0.0. */
+type SubscribeMetadata = RelayBusConsumerMetadata;
 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;
+type HandlerDecorator<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`
@@ -132,12 +349,17 @@ type SubscribeDecorator<TPayload> = <TMethod extends HandlerMethod<TPayload>>(ta
  * ```ts
  * @Injectable()
  * export class ShippingHandlers {
- *   @Subscribe(OrderPlaced, { transactional: true })
+ *   @RelayBusConsumer(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>;
+declare function RelayBusConsumer<TPayload>(event: EventClass<TPayload>, options?: RelayBusConsumerOptions): HandlerDecorator<TPayload>;
+declare function RelayBusConsumer(eventType: string, options?: RelayBusConsumerOptions): HandlerDecorator<never>;
+/**
+ * @deprecated Renamed to {@link RelayBusConsumer}, which behaves identically; this alias is
+ * removed in 1.0.0.
+ */
+declare const Subscribe: typeof RelayBusConsumer;
 
-export { RelayBusHandlerExplorer, RelayBusHealth, type RelayBusHealthReport, RelayBusLifecycle, RelayBusModule, type RelayBusModuleExtras, type RelayBusModuleOptions, type RelayBusModuleOptionsFactory, Subscribe, type SubscribeDecoratorOptions, type SubscribeMetadata };
+export { type AsyncMethodDescriptor, type ContractEvent, EventConsumer, type EventConsumerClass, type EventConsumerMetadata, type EventConsumerOptions, RelayBusCatalogConsumer, type RelayBusCatalogConsumerClass, type RelayBusCatalogConsumerMetadata, type RelayBusCatalogConsumerOptions, RelayBusConsumer, type RelayBusConsumerMetadata, type RelayBusConsumerOptions, RelayBusFeatureContract, RelayBusFeatureModule, type RelayBusFeatureOptions, RelayBusHandlerExplorer, RelayBusHealth, type RelayBusHealthReport, RelayBusLifecycle, RelayBusModule, type RelayBusModuleExtras, type RelayBusModuleOptions, type RelayBusModuleOptionsFactory, RelayBusTransaction, type RelayBusTransactionDecorator, RelayBusTransactionHost, type RelayBusTransactionNeedsAsyncMethod, Subscribe, type SubscribeDecoratorOptions, type SubscribeMetadata };