feat(core): introduce hooks for the Plugin API

BREAKING CHANGE: The experimental Plugin API has been changed

Author: Papooch

packages/core/src/index.ts

@@ -10,6 +10,7 @@ export * from './lib/cls.options';
 export * from './lib/cls.service';
 export * from './lib/inject-cls.decorator';
 export * from './lib/plugin/cls-plugin.interface';
+export * from './lib/plugin/cls-plugin-base';
 export * from './lib/proxy-provider/injectable-proxy.decorator';
 export * from './lib/proxy-provider/proxy-provider.exceptions';
 export * from './lib/proxy-provider/proxy-provider.interfaces';

packages/core/src/lib/cls-initializers/cls.guard.ts

@@ -8,6 +8,8 @@ import { ClsServiceManager } from '../cls-service-manager';
 import { CLS_CTX, CLS_ID } from '../cls.constants';
 import { CLS_GUARD_OPTIONS } from '../cls.internal-constants';
 import { ClsGuardOptions } from '../cls.options';
+import { ClsEnhancerInitContext } from '../plugin/cls-plugin.interface';
+import { ClsPluginsHooksHost } from '../plugin/cls-plugin-hooks-host';
 import { ContextClsStoreMap } from './utils/context-cls-store-map';
 
 @Injectable()
@@ -16,20 +18,28 @@ export class ClsGuard implements CanActivate {
 
     constructor(
         @Inject(CLS_GUARD_OPTIONS)
-        options: Omit<ClsGuardOptions, 'mount'>,
+        options: Omit<ClsGuardOptions, 'mount'> | undefined,
     ) {
         this.options = { ...new ClsGuardOptions(), ...options };
     }
 
     async canActivate(context: ExecutionContext): Promise<boolean> {
         const cls = ClsServiceManager.getClsService();
         const existingStore = ContextClsStoreMap.get(context);
+        const pluginHooks = ClsPluginsHooksHost.getInstance();
         if (existingStore) {
             cls.enter({ ifNested: 'reuse' });
         } else {
             cls.enterWith({});
             ContextClsStoreMap.set(context, cls.get());
         }
+        const pluginCtx: ClsEnhancerInitContext = {
+            kind: 'guard',
+            ctx: context,
+        };
+        if (this.options.initializePlugins) {
+            await pluginHooks.beforeSetup(pluginCtx);
+        }
         if (this.options.generateId) {
             const id = await this.options.idGenerator?.(context);
             cls.setIfUndefined<any>(CLS_ID, id);
@@ -41,7 +51,7 @@ export class ClsGuard implements CanActivate {
             await this.options.setup(cls, context);
         }
         if (this.options.initializePlugins) {
-            await cls.initializePlugins();
+            await pluginHooks.afterSetup(pluginCtx);
         }
         if (this.options.resolveProxyProviders) {
             await cls.resolveProxyProviders();

packages/core/src/lib/cls-initializers/cls.interceptor.ts

@@ -10,6 +10,8 @@ import { ClsServiceManager } from '../cls-service-manager';
 import { CLS_CTX, CLS_ID } from '../cls.constants';
 import { CLS_INTERCEPTOR_OPTIONS } from '../cls.internal-constants';
 import { ClsInterceptorOptions } from '../cls.options';
+import { ClsEnhancerInitContext } from '../plugin/cls-plugin.interface';
+import { ClsPluginsHooksHost } from '../plugin/cls-plugin-hooks-host';
 import { ContextClsStoreMap } from './utils/context-cls-store-map';
 
 @Injectable()
@@ -18,17 +20,25 @@ export class ClsInterceptor implements NestInterceptor {
 
     constructor(
         @Inject(CLS_INTERCEPTOR_OPTIONS)
-        options?: Omit<ClsInterceptorOptions, 'mount'>,
+        options?: Omit<ClsInterceptorOptions, 'mount'> | undefined,
     ) {
         this.options = { ...new ClsInterceptorOptions(), ...options };
     }
 
     intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
         const cls = ClsServiceManager.getClsService<any>();
         const clsStore = ContextClsStoreMap.get(context) ?? {};
+        const pluginHooks = ClsPluginsHooksHost.getInstance();
         ContextClsStoreMap.set(context, clsStore);
         return new Observable((subscriber) => {
             cls.runWith(clsStore, async () => {
+                const pluginCtx: ClsEnhancerInitContext = {
+                    kind: 'interceptor',
+                    ctx: context,
+                };
+                if (this.options.initializePlugins) {
+                    await pluginHooks.beforeSetup(pluginCtx);
+                }
                 if (this.options.generateId) {
                     const id = await this.options.idGenerator?.(context);
                     cls.setIfUndefined<any>(CLS_ID, id);
@@ -40,7 +50,7 @@ export class ClsInterceptor implements NestInterceptor {
                     await this.options.setup(cls, context);
                 }
                 if (this.options.initializePlugins) {
-                    await cls.initializePlugins();
+                    await pluginHooks.afterSetup(pluginCtx);
                 }
                 if (this.options.resolveProxyProviders) {
                     await cls.resolveProxyProviders();

packages/core/src/lib/cls-initializers/cls.middleware.ts

@@ -1,26 +1,37 @@
 import { Inject, Injectable, NestMiddleware } from '@nestjs/common';
 import { ClsServiceManager } from '../cls-service-manager';
 import { CLS_ID, CLS_REQ, CLS_RES } from '../cls.constants';
+import { CLS_MIDDLEWARE_OPTIONS } from '../cls.internal-constants';
 import { ClsMiddlewareOptions } from '../cls.options';
+import { ClsMiddlewareInitContext } from '../plugin/cls-plugin.interface';
+import { ClsPluginsHooksHost } from '../plugin/cls-plugin-hooks-host';
 import { ContextClsStoreMap } from './utils/context-cls-store-map';
-import { CLS_MIDDLEWARE_OPTIONS } from '../cls.internal-constants';
 
 @Injectable()
 export class ClsMiddleware implements NestMiddleware {
     private readonly options: Omit<ClsMiddlewareOptions, 'mount'>;
 
     constructor(
         @Inject(CLS_MIDDLEWARE_OPTIONS)
-        options?: Omit<ClsMiddlewareOptions, 'mount'>,
+        options: Omit<ClsMiddlewareOptions, 'mount'> | undefined,
     ) {
         this.options = { ...new ClsMiddlewareOptions(), ...options };
     }
     use = async (req: any, res: any, next: (err?: any) => any) => {
         const cls = ClsServiceManager.getClsService();
+        const pluginHooks = ClsPluginsHooksHost.getInstance();
         const callback = async () => {
             try {
+                const pluginCtx: ClsMiddlewareInitContext = {
+                    kind: 'middleware',
+                    req,
+                    res,
+                };
                 this.options.useEnterWith && cls.enter();
                 ContextClsStoreMap.setByRaw(req, cls.get());
+                if (this.options.initializePlugins) {
+                    await pluginHooks.beforeSetup(pluginCtx);
+                }
                 if (this.options.generateId) {
                     const id = await this.options.idGenerator?.(req);
                     cls.setIfUndefined<any>(CLS_ID, id);
@@ -31,7 +42,7 @@ export class ClsMiddleware implements NestMiddleware {
                     await this.options.setup(cls, req, res);
                 }
                 if (this.options.initializePlugins) {
-                    await cls.initializePlugins();
+                    await pluginHooks.afterSetup(pluginCtx);
                 }
                 if (this.options.resolveProxyProviders) {
                     await cls.resolveProxyProviders();

packages/core/src/lib/cls-initializers/use-cls.decorator.ts

@@ -3,6 +3,8 @@ import { copyMethodMetadata } from '../../utils/copy-method-metadata';
 import { ClsServiceManager } from '../cls-service-manager';
 import { CLS_ID } from '../cls.constants';
 import { ClsDecoratorOptions } from '../cls.options';
+import { ClsDecoratorInitContext } from '../plugin/cls-plugin.interface';
+import { ClsPluginsHooksHost } from '../plugin/cls-plugin-hooks-host';
 
 /**
  * Wraps the decorated method in a CLS context.
@@ -42,24 +44,37 @@ export function UseCls<TArgs extends any[]>(
                 `The @UseCls decorator can be only used on functions, but ${propertyKey.toString()} is not a function.`,
             );
         }
-        descriptor.value = function (...args: TArgs) {
-            return cls.run(options.runOptions ?? {}, async () => {
-                if (options.generateId) {
-                    const id = await options.idGenerator?.apply(this, args);
-                    cls.set<string>(CLS_ID, id);
-                }
-                if (options.setup) {
-                    await options.setup.apply(this, [cls, ...args]);
-                }
-                if (options.initializePlugins) {
-                    await cls.initializePlugins();
-                }
-                if (options.resolveProxyProviders) {
-                    await cls.resolveProxyProviders();
-                }
-                return original.apply(this, args);
-            });
-        };
+        descriptor.value = new Proxy(original, {
+            apply: function (_, outerThis, args: TArgs[]) {
+                const pluginHooks = ClsPluginsHooksHost.getInstance();
+                return cls.run(options.runOptions ?? {}, async () => {
+                    const pluginCtx: ClsDecoratorInitContext = {
+                        kind: 'decorator',
+                        args,
+                    };
+                    if (options.initializePlugins) {
+                        await pluginHooks.beforeSetup(pluginCtx);
+                    }
+                    if (options.generateId) {
+                        const id = await options.idGenerator?.apply(
+                            outerThis,
+                            args,
+                        );
+                        cls.set<string>(CLS_ID, id);
+                    }
+                    if (options.setup) {
+                        await options.setup.apply(outerThis, [cls, ...args]);
+                    }
+                    if (options.initializePlugins) {
+                        await pluginHooks.afterSetup(pluginCtx);
+                    }
+                    if (options.resolveProxyProviders) {
+                        await cls.resolveProxyProviders();
+                    }
+                    return original.apply(outerThis, args);
+                });
+            },
+        });
         copyMethodMetadata(original, descriptor.value);
     };
 }

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

@@ -17,6 +17,7 @@ import {
     HttpAdapterHost,
     ModuleRef,
 } from '@nestjs/core';
+import { isNonNullable } from '../../utils/is-non-nullable';
 import { ClsGuard } from '../cls-initializers/cls.guard';
 import { ClsInterceptor } from '../cls-initializers/cls.interceptor';
 import { ClsMiddleware } from '../cls-initializers/cls.middleware';
@@ -33,7 +34,7 @@ import {
     ClsModuleAsyncOptions,
     ClsModuleOptions,
 } from '../cls.options';
-import { ClsPluginManager } from '../plugin/cls-plugin-manager';
+import { ClsPluginsModule } from '../plugin/cls-plugins.module';
 import { ProxyProviderManager } from '../proxy-provider/proxy-provider-manager';
 import { ClsCommonModule } from './cls-common.module';
 import { getMiddlewareMountPoint } from './middleware.utils';
@@ -43,7 +44,8 @@ import { getMiddlewareMountPoint } from './middleware.utils';
  */
 @Global()
 @Module({
-    imports: [ClsCommonModule],
+    imports: [ClsCommonModule, ClsPluginsModule.registerPluginHooks()],
+    exports: [ClsPluginsModule],
 })
 export class ClsRootModule implements NestModule, OnModuleInit {
     private static logger = new Logger('ClsModule');
@@ -85,7 +87,7 @@ export class ClsRootModule implements NestModule, OnModuleInit {
 
         return {
             module: ClsRootModule,
-            imports: ClsPluginManager.registerPlugins(options.plugins),
+            imports: [],
             providers: [
                 {
                     provide: CLS_MODULE_OPTIONS,
@@ -94,7 +96,10 @@ export class ClsRootModule implements NestModule, OnModuleInit {
                 ...providers,
                 ...proxyProviders,
             ],
-            exports: [...exports, ...proxyProviders.map((p) => p.provide)],
+            exports: [
+                ...exports,
+                ...proxyProviders.map((p) => p.provide),
+            ].filter(isNonNullable),
             global: false,
         };
     }
@@ -112,10 +117,7 @@ export class ClsRootModule implements NestModule, OnModuleInit {
 
         return {
             module: ClsRootModule,
-            imports: [
-                ...(asyncOptions.imports ?? []),
-                ...ClsPluginManager.registerPlugins(asyncOptions.plugins),
-            ],
+            imports: asyncOptions.imports ?? [],
             providers: [
                 {
                     provide: CLS_MODULE_OPTIONS,

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

@@ -1,8 +1,8 @@
 import { DynamicModule, Module, Type } from '@nestjs/common';
 import { ClsModuleAsyncOptions, ClsModuleOptions } from '../cls.options';
-import { ClsPluginManager } from '../plugin/cls-plugin-manager';
 
 import { ClsPlugin } from '../plugin/cls-plugin.interface';
+import { ClsPluginsModule } from '../plugin/cls-plugins.module';
 import { ProxyProviderManager } from '../proxy-provider/proxy-provider-manager';
 import { ClsModuleProxyProviderOptions } from '../proxy-provider/proxy-provider.interfaces';
 import { ClsCommonModule } from './cls-common.module';
@@ -24,7 +24,10 @@ export class ClsModule {
     static forRoot(options?: ClsModuleOptions): DynamicModule {
         return {
             module: ClsModule,
-            imports: [ClsRootModule.forRoot(options)],
+            imports: [
+                ClsRootModule.forRoot(options),
+                ...ClsPluginsModule.createPluginModules(options?.plugins),
+            ],
             global: options?.global,
         };
     }
@@ -37,7 +40,10 @@ export class ClsModule {
     static forRootAsync(asyncOptions: ClsModuleAsyncOptions): DynamicModule {
         return {
             module: ClsModule,
-            imports: [ClsRootModule.forRootAsync(asyncOptions)],
+            imports: [
+                ClsRootModule.forRootAsync(asyncOptions),
+                ...ClsPluginsModule.createPluginModules(asyncOptions.plugins),
+            ],
             global: asyncOptions?.global,
         };
     }
@@ -87,7 +93,7 @@ export class ClsModule {
     static registerPlugins(plugins: ClsPlugin[]): DynamicModule {
         return {
             module: ClsModule,
-            imports: ClsPluginManager.registerPlugins(plugins),
+            imports: ClsPluginsModule.createPluginModules(plugins),
         };
     }
 }

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

@@ -235,18 +235,4 @@ export class ClsService<S extends ClsStore = ClsStore> {
             : [];
         await ProxyProviderManager.resolveProxyProviders(proxySymbols);
     }
-
-    /**
-     * @deprecated This method will be removed in a future release and replaced
-     * with a different mechanism for plugin initialization.
-     *
-     * Since the plugin API is still experimental, this method will become a np-op
-     * and will be eventually removed, possibly in a minor release.
-     */
-    async initializePlugins() {
-        const { ClsPluginManager } = await import(
-            './plugin/cls-plugin-manager'
-        );
-        await ClsPluginManager.onClsInit();
-    }
 }

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

@@ -0,0 +1,62 @@
+import { Provider, InjectionToken } from '@nestjs/common';
+import { ClsPlugin, ClsPluginHooks } from './cls-plugin.interface';
+
+/**
+ * Extend this class to create a new ClsPlugin
+ *
+ * It contains the basic structure for a plugin, including
+ * some helper methods for common operations.
+ */
+export abstract class ClsPluginBase implements ClsPlugin {
+    imports: any[] = [];
+    providers: Provider[] = [];
+    exports: any[] = [];
+
+    /**
+     * @param name {@link ClsPlugin.name}
+     */
+    constructor(public readonly name: string) {}
+
+    protected get hooksProviderToken() {
+        return getPluginHooksToken(this.name);
+    }
+
+    /**
+     * Register the plugin hooks provider
+     *
+     * This is a shorthand for manually registering a provider
+     * that returns the plugin hooks object provided under
+     * the `hooksProviderToken` token.
+     *
+     * @example
+     * ```
+     * this.registerHooks({
+     *   inject: [OPTIONS],
+     *   useFactory: (options: PluginOptions<any>): ClsPluginHooks => ({
+     *     afterSetup: (cls: ClsService) => {
+     *       cls.set('some-key', options.pluginData);
+     *     }
+     *   })
+     * })
+     * ```
+     */
+    protected registerHooks(opts: {
+        inject: InjectionToken<any>[];
+        useFactory: (...args: any[]) => ClsPluginHooks;
+    }) {
+        this.providers.push({
+            provide: this.hooksProviderToken,
+            inject: opts.inject,
+            useFactory: opts.useFactory,
+        });
+        this.exports.push(this.hooksProviderToken);
+    }
+}
+
+export function getPluginHooksToken(name: string) {
+    return `CLS_PLUGIN_HOOKS_${name}`;
+}
+
+export function isPluginHooksToken(token: string | symbol) {
+    return typeof token === 'string' && token.startsWith('CLS_PLUGIN_HOOKS_');
+}