feat: expose js sdk identity on client metadata

[jonathannorris]

Summary

• split ClientMetadata into separate JS package identity and runtime identity fields
• set sdk to js-web / js-server, and add paradigm as client / server
• keep framework metadata as-is for react, angular, and nest
• avoid redundant Angular directive client initialization when the domain input already initialized the client

Motivation

Relates to #1375.

The original version of this PR overloaded sdk to represent runtime identity. I think it probably makes sense to keep those concerns separate:

• sdk identifies the JS package family: js-web or js-server
• paradigm identifies the runtime model: client or server
• framework continues to identify wrapper SDKs like react, angular, and nest

This keeps the metadata more explicit and avoids conflating package family with runtime paradigm.

Usage

const client = OpenFeature.getClient('my-domain');

client.metadata;
// web-sdk:
// {
//   domain: 'my-domain',
//   sdk: 'js-web',
//   paradigm: 'client',
//   providerMetadata: { name: '...' }
// }

hook.before = (hookContext) => {
  hookContext.clientMetadata;
  // react-sdk:
  // {
  //   domain: 'my-domain',
  //   sdk: 'js-web',
  //   paradigm: 'client',
  //   framework: 'react',
  //   providerMetadata: { name: '...' }
  // }
};

Implementation

• ClientMetadata now exposes both sdk and paradigm
• the base web/server clients populate those fields directly
• the framework SDKs still use the small Proxy wrapper so framework metadata is visible both via client.metadata and from evaluations that read this.metadata
• Angular keeps its existing service/client behavior; I did not cache wrapped clients there because OpenFeature.getClient() in this SDK returns a new client instance rather than a singleton

Notes

• the Angular directive still initializes from the domain input setter, but now avoids the redundant second initClient() call from ngOnInit()
• this keeps the existing initialization behavior while removing duplicate setup/teardown work

Related Issues

• Relates to [FEATURE] Expose JS SDK/framework identity on ClientMetadata #1375

[gemini-code-assist]

Code Review

This pull request introduces framework-specific metadata (Angular, Nest, and React) and SDK family identification ('web' or 'server') into OpenFeature clients. This is achieved by wrapping clients in a Proxy that intercepts metadata access. The changes include new utility functions for each framework, updates to the respective SDK providers/services to apply these wrappers, and expanded unit tests to verify metadata propagation. Review feedback highlights potential performance improvements in the Angular SDK, specifically regarding redundant client initialization in the directive and the need for caching proxied client instances in the service to avoid overhead during frequent flag evaluations.

[jonathannorris]

Hum... should sdk actually reuse Paradigm instead of introducing a new union on ClientMetadata?

Right now this PR uses sdk?: 'web' | 'server', but Paradigm is already 'server' | 'client'.

I think it probably makes sense to decide whether this field is meant to represent JS package family (web | server) or runtime paradigm (client | server) before we merge this.

[MattIPv4]

Hum... should sdk actually reuse Paradigm instead of introducing a new union on ClientMetadata?

Right now this PR uses sdk?: 'web' | 'server', but Paradigm is already 'server' | 'client'.

I think it probably makes sense to decide whether this field is meant to represent JS package family (web | server) or runtime paradigm (client | server) before we merge this.

Reusing makes sense to me. I think they are essentially representing the same thing? The server package sets its runsOn to 'server', and the web package sets its runsOn to 'client'. Seems silly to introduce a new union to also represent the same thing with different values?

[jonathannorris]

sdk is now JS package identity (js-web / js-server), and paradigm is the runtime identity (client / server).

I think this setup probably makes more sense if we ever expand this metadata shape into something more standard across other OpenFeature SDKs, since package identity and runtime paradigm won't necessarily be the same thing in every implementation.

[jonathannorris]

@MattIPv4 @beeme1mr @toddbaert @lukas-reining

I put together an alternate implementation in #1377 if you want to compare the two approaches directly.

The main difference is that this PR (#1376) uses a Proxy wrapper to inject framework metadata, while #1377 avoids Proxy entirely and instead marks the concrete SDK-owned client instances directly. Both end up exposing the same sdk / paradigm / framework metadata to providers and hooks, but the implementation tradeoff is different:

#1376: cleaner encapsulation, but framework identity comes from a wrapper layer
#1377: no Proxy, no public getClient(...) API change, and metadata comes from the real client instance, but the framework SDKs do need a small internal cast-and-mark helper

Would be good to get feedback on which direction feels cleaner to merge.

[MattIPv4]

👀 Took a look at the alternative, and I think I prefer this approach with a Proxy, as it isolates the metadata change to just where we know for sure the client is being used within that framework -- your other PR mutates the actual client itself, which in the case of at least the React PR, could result in the framework metadata leaking beyond the framework?

[toddbaert]

One thing I want to make sure we've considered: since @openfeature/web-sdk is a peer dependency of the React (and Angular) SDKs, it's possible for users to import OpenFeature.getClient() directly from @openfeature/web-sdk in a React app, bypassing OpenFeatureProvider (this isn't a problem, we re-export everything, so until now these have always been exactly the same objects and imports, even in terms of instanceof checks, etc - they are literally nominatively the same classes, etc.

However, with this change, there's a difference - in the case above,, sdk and paradigm would be populated, but framework would be undefined.

I think that's arguably correct; if you're not going through the framework wrapper, the metadata should reflect that. But worth calling out since a hook or provider branching on framework === 'react' could get inconsistent results depending on how the client was obtained.

WDYT? Worth a note in the docs/JSDoc, or is this fine as-is?

(Note this impacts both implementations)

[toddbaert]

After looking at #1377, I think I prefer this, and I don't think there's much risk in the proxy after digging into it. The ref test made me nervous but I don't think it will actually have an impact in anyone's prod code.

Consider this though - not sure if this is a deal-breaker for you @jonathannorris (it's not for me).