feat: add support for multiple transactional adapters (#114)

* fix: rework how plugins are registered (internals)

Previously all plugins' providers were mixed into one module,
now each plugin gets its own module.

* feat: add multiple transactional adapters support

* Add tests for multiple named connections

* Add docs for multiple connections

Author: Papooch

docs/docs/06_plugins/01_available-plugins/01-transactional/index.md

@@ -305,8 +305,76 @@ The `@Transactional` decorator can be used to wrap a method call in the `withTra
 -   **_`@Transactional`_**`(options)`
 -   **_`@Transactional`_**`(propagation, options)`
 
-## Considerations
+Or when using named connections:
 
-Please note that at this time, the `@nestjs-cls/transactional` plugin only supports a _single_ database connection per application. This means that if you have multiple databases, you can only use one of them with the transactional plugin.
+-   **_`@Transactional`_**`(connectionName, propagation?, options?)`
 
-This is a subject to change in the future, as there are plans to support multiple `TransactionHost` instances, each with their own adapter and a database connection.
+## Multiple databases
+
+Similar to other `@nestjs/<orm>` libraries, the `@nestjs-cls/transactional` plugin can be used to manage transactions for multiple database connections, or even multiple database libraries altogether.
+
+### Registration
+
+To use multiple connections, register multiple instances of the `ClsPluginTransactional`, each with an unique `connectionName`:
+
+```ts
+ClsModule.forRoot({
+    plugins: [
+        new ClsPluginTransactional({
+            // highlight-start
+            connectionName: 'prisma-connection',
+            // highlight-end
+            imports: [PrismaModule],
+            adapter: new TransactionalAdapterPrisma({
+                prismaInjectionToken: PrismaClient,
+            }),
+        }),
+        new ClsPluginTransactional({
+            // highlight-start
+            connectionName: 'knex-connection',
+            // highlight-end
+            imports: [KnexModule],
+            adapter: new TransactionalAdapterKnex({
+                knexInstanceToken: KNEX,
+            }),
+        }),
+    ],
+}),
+```
+
+This works for any number of connections and any number of database libraries.
+
+### Usage
+
+To use the `TransactionHost` for a specific connection, you _need to_ use `@InjectTransactionHost('connectionName')` decorator to inject the `TransactionHost`. Otherwise Nest will try to inject the default unnamed instance which will result in an injection error.
+
+```ts
+@Injectable()
+class UserService {
+    constructor(
+        // highlight-start
+        @InjectTransactionHost('prisma-connection')
+        private readonly // highlight-end
+        private readonly txHost: TransactionHost<TransactionalAdapterPrisma>,
+    ) {}
+
+    // ...
+}
+
+```
+
+:::note
+
+`@InjectTransactionHost('connectionName')` is a short for `@Inject(getTransactionHostToken('connectionName'))`. The `getTransactionHostToken` function is useful for when you need to mock the `TransactionHost` in unit tests.
+
+:::
+
+In a similar fashion, using the `@Transactional` decorator requires the `connectionName` to be passed as the first argument.
+
+```ts
+@Transactional('prisma-connection')
+async createUser(name: string): Promise<User> {
+    await this.accountService.createAccountForUser(user.id);
+    return user;
+}
+```

packages/core/src/lib/cls.module.ts

@@ -36,7 +36,8 @@ import {
     ClsModuleOptions,
 } from './cls.options';
 import { ClsService } from './cls.service';
-import { ClsPluginModule } from './plugin/cls-plugin.module';
+import { ClsPluginManager } from './plugin/cls-plugin-manager';
+
 import { ProxyProviderManager } from './proxy-provider/proxy-provider-manager';
 import { ClsModuleProxyProviderOptions } from './proxy-provider/proxy-provider.interfaces';
 
@@ -103,7 +104,7 @@ export class ClsModule implements NestModule {
 
         return {
             module: ClsModule,
-            imports: [ClsPluginModule.forRoot(options.plugins)],
+            imports: ClsPluginManager.registerPlugins(options.plugins),
             providers: [
                 {
                     provide: CLS_MODULE_OPTIONS,
@@ -132,7 +133,7 @@ export class ClsModule implements NestModule {
             module: ClsModule,
             imports: [
                 ...(asyncOptions.imports ?? []),
-                ClsPluginModule.forRoot(asyncOptions.plugins),
+                ...ClsPluginManager.registerPlugins(asyncOptions.plugins),
             ],
             providers: [
                 {

packages/core/src/lib/plugin/cls-plugin-manager.ts

@@ -1,41 +1,23 @@
 import { globalClsService } from '../cls-service.globals';
 import { ClsPlugin } from './cls-plugin.interface';
+import { createClsPluginModule } from './cls-plugin.module';
 
 export class ClsPluginManager {
     private static clsService = globalClsService;
     private static plugins: ClsPlugin[] = [];
 
-    static add(plugins: ClsPlugin[] = []) {
+    static registerPlugins(plugins: ClsPlugin[] = []) {
         this.plugins.push(...plugins);
+        return plugins.map((plugin) => createClsPluginModule(plugin));
     }
 
     static getPlugins() {
         return this.plugins;
     }
 
-    static getPluginImports() {
-        return this.plugins.flatMap((plugin) => plugin.imports ?? []);
-    }
-
-    static getPluginProviders() {
-        return this.plugins.flatMap((plugin) => plugin.providers ?? []);
-    }
-
     static async onClsInit() {
         for (const plugin of this.plugins) {
             await plugin.onClsInit?.(this.clsService);
         }
     }
-
-    static async onModuleInit() {
-        for (const plugin of this.plugins) {
-            await plugin.onModuleInit?.();
-        }
-    }
-
-    static async onModuleDestroy() {
-        for (const plugin of this.plugins) {
-            await plugin.onModuleDestroy?.();
-        }
-    }
 }

packages/core/src/lib/plugin/cls-plugin.module.ts

@@ -1,27 +1,26 @@
 import { Global } from '@nestjs/common';
-import { ClsPluginManager } from './cls-plugin-manager';
 import { ClsPlugin } from './cls-plugin.interface';
 
-@Global()
-export class ClsPluginModule {
-    static forRoot(plugins: ClsPlugin[] = []) {
-        ClsPluginManager.add(plugins);
-        const imports = ClsPluginManager.getPluginImports();
-        const providers = ClsPluginManager.getPluginProviders();
+export function createClsPluginModule(plugin: ClsPlugin) {
+    @Global()
+    class ClsPluginModule {
+        static forRoot() {
+            return {
+                module: ClsPluginModule,
+                imports: plugin.imports,
+                providers: plugin.providers,
+                exports: plugin.exports,
+            };
+        }
 
-        return {
-            module: ClsPluginModule,
-            imports: imports,
-            providers: providers,
-            exports: providers,
-        };
-    }
+        async onModuleInit() {
+            await plugin.onModuleInit?.();
+        }
 
-    async onModuleInit() {
-        await ClsPluginManager.onModuleInit();
+        async onModuleDestroy() {
+            await plugin.onModuleDestroy?.();
+        }
     }
 
-    async onModuleDestroy() {
-        await ClsPluginManager.onModuleDestroy();
-    }
+    return ClsPluginModule.forRoot();
 }

packages/transactional/src/lib/interfaces.ts

@@ -7,6 +7,11 @@ export interface TransactionalAdapterOptions<TTx, TOptions> {
     getFallbackInstance: () => TTx;
 }
 
+export interface TransactionalAdapterOptionsWithName<TTx, TOptions>
+    extends TransactionalAdapterOptions<TTx, TOptions> {
+    connectionName: string;
+}
+
 export type TransactionalOptionsAdapterFactory<TConnection, TTx, TOptions> = (
     connection: TConnection,
 ) => TransactionalAdapterOptions<TTx, TOptions>;
@@ -32,8 +37,18 @@ export interface TransactionalAdapter<TConnection, TTx, TOptions> {
 }
 
 export interface TransactionalPluginOptions<TConnection, TTx, TOptions> {
+    /**
+     * An instance of the transactional adapter.
+     */
     adapter: TransactionalAdapter<TConnection, TTx, TOptions>;
+    /**
+     * An array of modules that export providers required by the adapter.
+     */
     imports?: any[];
+    /**
+     * An optional name of the connection. Useful when there are multiple TransactionalPlugins registered in the app.
+     */
+    connectionName?: string;
 }
 
 export type TTxFromAdapter<TAdapter> = TAdapter extends TransactionalAdapter<

packages/transactional/src/lib/plugin-transactional.ts

@@ -5,26 +5,44 @@ import {
     TRANSACTIONAL_ADAPTER_OPTIONS,
     TRANSACTION_CONNECTION,
 } from './symbols';
-import { TransactionHost } from './transaction-host';
+import { getTransactionHostToken, TransactionHost } from './transaction-host';
 
 export class ClsPluginTransactional implements ClsPlugin {
-    name: 'cls-plugin-transactional';
+    name: string;
     providers: Provider[];
     imports?: any[];
+    exports?: any[];
 
     constructor(options: TransactionalPluginOptions<any, any, any>) {
+        this.name = options.connectionName
+            ? `cls-plugin-transactional-${options.connectionName}`
+            : 'cls-plugin-transactional';
         this.imports = options.imports;
+        const transactionHostToken = getTransactionHostToken(
+            options.connectionName,
+        );
         this.providers = [
-            TransactionHost,
             {
                 provide: TRANSACTION_CONNECTION,
                 useExisting: options.adapter.connectionToken,
             },
             {
                 provide: TRANSACTIONAL_ADAPTER_OPTIONS,
                 inject: [TRANSACTION_CONNECTION],
-                useFactory: options.adapter.optionsFactory,
+                useFactory: (connection: any) => {
+                    const adapterOptions =
+                        options.adapter.optionsFactory(connection);
+                    return {
+                        ...adapterOptions,
+                        connectionName: options.connectionName,
+                    };
+                },
+            },
+            {
+                provide: transactionHostToken,
+                useClass: TransactionHost,
             },
         ];
+        this.exports = [transactionHostToken];
     }
 }

packages/transactional/src/lib/symbols.ts

@@ -1,3 +1,9 @@
 export const TRANSACTION_CONNECTION = Symbol('TRANSACTION_CONNECTION');
-export const TRANSACTIONAL_INSTANCE = Symbol('TRANSACTIONAL_CLIENT');
 export const TRANSACTIONAL_ADAPTER_OPTIONS = Symbol('TRANSACTIONAL_OPTIONS');
+
+const TRANSACTIONAL_INSTANCE = Symbol('TRANSACTIONAL_CLIENT');
+
+export const getTransactionalInstanceSymbol = (connectionName?: string) =>
+    connectionName
+        ? Symbol.for(`${TRANSACTIONAL_INSTANCE.toString()}_${connectionName}`)
+        : TRANSACTIONAL_INSTANCE;

packages/transactional/src/lib/transaction-host.ts

@@ -1,9 +1,9 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
 import { ClsServiceManager } from 'nestjs-cls';
 import {
-    TTxFromAdapter,
     TOptionsFromAdapter,
-    TransactionalAdapterOptions,
+    TransactionalAdapterOptionsWithName,
+    TTxFromAdapter,
 } from './interfaces';
 import {
     Propagation,
@@ -12,22 +12,27 @@ import {
     TransactionPropagationError,
 } from './propagation';
 import {
+    getTransactionalInstanceSymbol,
     TRANSACTIONAL_ADAPTER_OPTIONS,
-    TRANSACTIONAL_INSTANCE,
 } from './symbols';
 
 @Injectable()
 export class TransactionHost<TAdapter = never> {
     private readonly cls = ClsServiceManager.getClsService();
     private readonly logger = new Logger(TransactionHost.name);
+    private readonly transactionalInstanceSymbol: symbol;
 
     constructor(
         @Inject(TRANSACTIONAL_ADAPTER_OPTIONS)
-        private readonly _options: TransactionalAdapterOptions<
+        private readonly _options: TransactionalAdapterOptionsWithName<
             TTxFromAdapter<TAdapter>,
             TOptionsFromAdapter<TAdapter>
         >,
-    ) {}
+    ) {
+        this.transactionalInstanceSymbol = getTransactionalInstanceSymbol(
+            this._options.connectionName,
+        );
+    }
 
     /**
      * The instance of the transaction object.
@@ -42,7 +47,7 @@ export class TransactionHost<TAdapter = never> {
             return this._options.getFallbackInstance();
         }
         return (
-            this.cls.get(TRANSACTIONAL_INSTANCE) ??
+            this.cls.get(this.transactionalInstanceSymbol) ??
             this._options.getFallbackInstance()
         );
     }
@@ -211,14 +216,33 @@ export class TransactionHost<TAdapter = never> {
         if (!this.cls.isActive()) {
             return false;
         }
-        return !!this.cls.get(TRANSACTIONAL_INSTANCE);
+        return !!this.cls.get(this.transactionalInstanceSymbol);
     }
 
     private setTxInstance(txInstance?: TTxFromAdapter<TAdapter>) {
-        this.cls.set(TRANSACTIONAL_INSTANCE, txInstance);
+        this.cls.set(this.transactionalInstanceSymbol, txInstance);
     }
 }
 
 function isNotEmpty(obj: any) {
     return obj && Object.keys(obj).length > 0;
 }
+
+/**
+ * Get the injection token for a TransactionHost for a named connection.
+ * If name is omitted, the default instance is used.
+ */
+export function getTransactionHostToken(connectionName?: string) {
+    return connectionName
+        ? Symbol.for(`${TransactionHost.name}_${connectionName}`)
+        : TransactionHost;
+}
+
+/**
+ * Inject a TransactionHost for a named connection. Only needed if you want to inject a named instance.
+ *
+ * A shorthand for `Inject(getTransactionHostToken(connectionName))`
+ */
+export function InjectTransactionHost(connectionName?: string) {
+    return Inject(getTransactionHostToken(connectionName));
+}