feat(transactional): enable adapters to opt out of transactional proxy support

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

@@ -212,7 +212,11 @@ class AccountService {
 
 When a transaction is not active, the `Transaction` instance refers to the default non-transactional instance. However, if the CLS context is _not active_, the `Transaction` instance will be `undefined` instead, which could cause runtime errors.
 
-Therefore, this feature works reliably only when the CLS context is active _prior to starting the transaction_, which should be the case in most cases, however, for that reason, this is an opt-in feature that must be explicitly enabled with the `enableTransactionProxy: true` option of the `ClsPluginTransactional` constructor.
+Therefore, this feature works reliably only when the CLS context is active _prior to starting the transaction_.
+
+Additionally, _some adapters do not support this feature_ due to the nature of how transactions work in the library they implement.
+
+For these reasons, this is an opt-in feature that must be explicitly enabled with the `enableTransactionProxy: true` option of the `ClsPluginTransactional` constructor.
 
 ```ts
 new ClsPluginTransactional({
@@ -223,7 +227,7 @@ new ClsPluginTransactional({
     // highlight-start
     enableTransactionProxy: true,
     // highlight-end
-}),
+});
 ```
 
 :::

packages/transactional/src/lib/interfaces.ts

@@ -20,7 +20,6 @@ export interface MergedTransactionalAdapterOptions<TTx, TOptions>
     connectionName: string | undefined;
     enableTransactionProxy: boolean;
     defaultTxOptions: Partial<TOptions>;
-    onModuleInit?: () => void | Promise<void>;
 }
 
 export type TransactionalOptionsAdapterFactory<TConnection, TTx, TOptions> = (
@@ -59,6 +58,15 @@ export interface TransactionalAdapter<TConnection, TTx, TOptions>
         TTx,
         TOptions
     >;
+
+    /**
+     * Whether this adapter support the {@link TransactionalPluginOptions.enableTransactionProxy} option.
+     *
+     * The default is `true`. Set to `false` to explicitly forbid this feature.
+     *
+     * When set to `false`, and {@link TransactionalPluginOptions.enableTransactionProxy} is `true`, an error will be thrown.
+     */
+    supportsTransactionProxy?: boolean;
 }
 
 export interface TransactionalPluginOptions<TConnection, TTx, TOptions> {
@@ -78,6 +86,8 @@ export interface TransactionalPluginOptions<TConnection, TTx, TOptions> {
      * Whether to enable injecting the Transaction instance directly using `@InjectTransaction()`
      *
      * Default: `false`
+     *
+     * Note: Not all adapters support this feature, please refer to the docs for the adapter you are using.
      */
     enableTransactionProxy?: boolean;
 }

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

@@ -4,6 +4,7 @@ import { getTransactionToken } from './inject-transaction.decorator';
 import {
     MergedTransactionalAdapterOptions,
     OptionalLifecycleHooks,
+    TransactionalAdapter,
     TransactionalPluginOptions,
 } from './interfaces';
 import {
@@ -60,6 +61,9 @@ export class ClsPluginTransactional implements ClsPlugin {
         this.exports.push(transactionHostToken);
 
         if (options.enableTransactionProxy) {
+            if (options.adapter.supportsTransactionProxy === false) {
+                throw new TransactionProxyUnsupportedError(options.adapter);
+            }
             const transactionProxyToken = getTransactionToken(
                 options.connectionName,
             );
@@ -98,3 +102,11 @@ export class ClsPluginTransactional implements ClsPlugin {
         };
     }
 }
+
+export class TransactionProxyUnsupportedError extends Error {
+    constructor(adapter: TransactionalAdapter<any, any, any>) {
+        super(
+            `The adapter ${adapter.constructor.name} does not support the "Transaction Proxy" feature, please disable the "enableTransactionProxy" option.`,
+        );
+    }
+}

packages/transactional/test/inject-transaction.spec.ts

@@ -8,6 +8,7 @@ import {
     Transaction,
     Transactional,
     TransactionHost,
+    TransactionProxyUnsupportedError,
 } from '../src';
 import {
     MockDbConnection,
@@ -201,3 +202,29 @@ describe('InjectTransaction with multiple named connections', () => {
         });
     });
 });
+
+class TransactionAdapterMockWithoutTransactionProxySupport extends TransactionAdapterMock {
+    supportsTransactionProxy = false;
+}
+
+describe('Using enableTransactionProxy when the adapter does not support it', () => {
+    it('should throw an error', async () => {
+        const modulePromise = () =>
+            Test.createTestingModule({
+                imports: [
+                    ClsModule.forRoot({
+                        plugins: [
+                            new ClsPluginTransactional({
+                                enableTransactionProxy: true,
+                                adapter:
+                                    new TransactionAdapterMockWithoutTransactionProxySupport(
+                                        { connectionToken: MockDbConnection1 },
+                                    ),
+                            }),
+                        ],
+                    }),
+                ],
+            }).compile();
+        expect(modulePromise).toThrowError(TransactionProxyUnsupportedError);
+    });
+});