fix(core): proxy provider improvements - optional deps, better error messages, docs caveats

[Papooch]

Changes

Support OptionalFactoryDependency in inject arrays (closes #381)

Factory proxy providers now accept { token: T, optional: true } in inject:

ClsModule.forFeatureAsync({
  provide: MY_PROXY,
  inject: [{ token: SomeService, optional: true }],
  useFactory: (svc?: SomeService) => ({ value: svc?.getValue() ?? 'default' }),
});

@Optional() on class proxy constructor params already worked.

Throw on invalid factory return values (closes #375)

Factories returning null, undefined, or a primitive now throw ProxyProviderInvalidReturnTypeException instead of silently producing a broken proxy.

Docs

• Strict mode section: names ProxyProviderNotResolvedException explicitly (ProxyProviderNotResolvedException thrown even after resolveProxyProviders(...) #375)
• New caveat: proxy providers are unavailable until onApplicationBootstrap — accessing them in onModuleInit (e.g. BullMQ) will fail (closes Regression: Tenant connection mix-up after upgrading from 2.5.1 to 2.6.0 #404)
• New caveat: never inject Scope.REQUEST providers into proxy provider factories — shows the correct CLS_REQ pattern

[Copilot]

Pull request overview

Improves Proxy Provider ergonomics and reliability in nestjs-cls by supporting Nest’s optional factory injection syntax, adding stricter validation of factory return values during proxy resolution, and documenting common lifecycle/scope pitfalls.

Changes:

• Extend Proxy Provider/Plugin factory inject typing to accept OptionalFactoryDependency (e.g. { token, optional: true }) and add tests for optional injection behavior and ordering.
• Validate resolved Proxy Provider factory return values and throw ProxyProviderInvalidReturnTypeException for null/undefined/primitives; track “resolved” providers explicitly per CLS context.
• Update docs with stricter-mode wording and new caveats around bootstrap timing and REQUEST-scoped providers.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/core/test/proxy-providers/for-feature.spec.ts	Adds tests for @Optional() in class proxies and OptionalFactoryDependency in factory proxy inject arrays (including ordering).
packages/core/src/lib/proxy-provider/proxy-provider.interfaces.ts	Widens inject/dependencies types to include OptionalFactoryDependency.
packages/core/src/lib/proxy-provider/proxy-provider.exceptions.ts	Introduces ProxyProviderInvalidReturnTypeException with an explanatory message.
packages/core/src/lib/proxy-provider/proxy-provider-resolver.ts	Extracts tokens from optional deps for dependency ordering; adds per-context resolved tracking; throws on invalid factory return values.
packages/core/src/lib/proxy-provider/proxy-provider-manager.spec.ts	Adds coverage for invalid return type handling and “don’t re-resolve” behavior.
packages/core/src/lib/plugin/cls-plugin-base.ts	Updates plugin hook provider inject typing to accept OptionalFactoryDependency.
docs/docs/03_features-and-use-cases/06_proxy-providers.md	Updates strict-mode wording and adds new caveats (bootstrap timing, REQUEST-scoped mixing, primitive returns).
docs/docs/03_features-and-use-cases/04_usage-outside-of-web-request.md	Adds a warning about background workers and Proxy Provider availability timing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/core/src/lib/proxy-provider/proxy-provider-resolver.ts:163

• getAllNeededProviderSymbols only adds direct dependencies of the requested providers. When resolving a subset (e.g. cls.proxy.resolve([B])) and B -> A -> C (transitively), C is never added to resolutionPromisesMap, so A will not actually wait for C (because dependencyPromises.get(C) is undefined) and can resolve out of order. This breaks the “resolve dependencies first” guarantee for selective resolution. Consider computing the full transitive closure of proxy-provider dependencies (DFS/BFS) and/or throwing if a dependency symbol is missing from dependencyPromises.

    private getAllNeededProviderSymbols(providerSymbols: symbol[]) {
        const resolvedSet = this.getOrCreateCurrentResolvedSet();
        return new Set<symbol>(
            providerSymbols
                .filter((providerSymbol) => !resolvedSet.has(providerSymbol))
                .map((providerSymbol) => {
                    const deps =
                        this.proxyProviderDependenciesMap.get(providerSymbol) ??
                        [];
                    return [providerSymbol, ...deps];
                })
                .flat(),
        );
    }

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.