v3.x → v4.x

The v4 major version should be largely backwards compatible with v3. However, breaking changes were introduced in some less-used APIs that should be mentioned.

Changed base type of Proxy Providers

The default underlying value of Proxy Providers was changed to {}. This means that the typeof operator will now return 'object', which is more intuitive. (Link to original discussion)

The use-case of using a Proxy Provider as a function is still supported, but now requires the type option to be set to 'function'.

ClsModule.forFeature({
    provide: 'class-proxy',
    useClass: SomeClass,
});
ClsModule.forFeature({
    provide: 'function-proxy',
    useFactory: () => someFunction,
    type: 'function',
});

@Injectable()
class SomeService {
    constructor(
        @Inject('class-proxy')
        private readonly someClass: SomeClass,
        @Inject('function-proxy')
        private readonly functionProvider: () => void,
    ) {
        console.log(typeof this.someClass); // 'object'
        console.log(typeof this.functionProvider); // 'function'
    }
}

Changed default of ifNested option

The default of the ifNested option was changed from override to inherit, which more closely aligns with most real-world use-cases.

If you used the ClsService#run method without explicitly setting the ifNested option, you should check if the new default behavior is compatible with your use-case and adjust accordingly.

this.cls.run(
    { ifNested: 'override' },
    () => {
        // ... rest of the code
    },
);

Changed default of resolveProxyProviders in UseCls decorator

This value was undocumented in v3, but the default was false. It was changed to true in v4 to align with the default behavior of other enhancers.

This change should not affect most use-cases, because you either don't use Proxy Providers at all, or you use them and therefore had to set it to true anyway. The only case where this might be a breaking change is if you used the @UseCls in a module where you explicitly did not want to resolve Proxy Providers and therefore did not import their dependencies. In that case, you should set the resolveProxyProviders option to false in the decorator.