feat: set context during provider init on web (#919)

## This PR

- overloads the set provider methods to support defining context in the
web SDK
- updates the web sdk readme

## Related Issues

Fixes #748

## Notes

I decided to only support setting context in the web SDK because it is
less valuable on the server and the expected behavior was less clear due
to `domains`.

The behavior may need to be spec'd out. An issue in the spec repo has
been created.
open-feature/spec#219

---------

Signed-off-by: Michael Beemer <[email protected]>
Co-authored-by: Todd Baert <[email protected]>

Author: beeme1mr

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "cSpell.words": [
+    "domainless"
+  ]
+}

packages/client/README.md

@@ -121,7 +121,7 @@ To register a provider and ensure it is ready before further actions are taken,
 
 ```ts
 await OpenFeature.setProviderAndWait(new MyProvider());
-```  
+```
 
 #### Synchronous
 
@@ -158,9 +158,16 @@ Sometimes, the value of a flag must consider some dynamic criteria about the app
 In OpenFeature, we refer to this as [targeting](https://openfeature.dev/specification/glossary#targeting).
 If the flag management system you're using supports targeting, you can provide the input data using the [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context).
 
+```ts
+// Sets global context during provider registration
+await OpenFeature.setProvider(new MyProvider(), { origin: document.location.host });
+```
+
+Change context after the provider has been registered using `setContext`.
+
 ```ts
 // Set a value to the global context
-await OpenFeature.setContext({ origin: document.location.host });
+await OpenFeature.setContext({ targetingKey: localStorage.getItem("targetingKey") });
 ```
 
 Context is global and setting it is `async`.
@@ -233,6 +240,24 @@ const domainScopedClient = OpenFeature.getClient("my-domain");
 Domains can be defined on a provider during registration.
 For more details, please refer to the [providers](#providers) section.
 
+#### Manage evaluation context for domains
+
+By default, domain-scoped clients use the global context.
+This can be overridden by explicitly setting context when registering the provider or by references the domain when updating context:
+
+```ts
+OpenFeature.setProvider("my-domain", new NewCachedProvider(), { targetingKey: localStorage.getItem("targetingKey") });
+```
+
+To change context after the provider has been registered, use `setContext` with a name:
+
+```ts
+await OpenFeature.setContext("my-domain", { targetingKey: localStorage.getItem("targetingKey") })
+```
+
+Once context has been defined for a named client, it will override the global context for all clients using the associated provider.
+Context can be cleared using for a named provider using `OpenFeature.clearContext("my-domain")` or call `OpenFeature.clearContexts()` to reset all context.
+
 ### Eventing
 
 Events allow you to react to state changes in the provider or underlying flag management system, such as flag definition changes, provider readiness, or error conditions.

packages/client/src/open-feature.ts

@@ -69,6 +69,140 @@ export class OpenFeatureAPI
     return this._domainScopedProviders.get(domain)?.status ?? this._defaultProvider.status;
   }
 
+  /**
+   * Sets the default provider for flag evaluations and returns a promise that resolves when the provider is ready.
+   * This provider will be used by domainless clients and clients associated with domains to which no provider is bound.
+   * Setting a provider supersedes the current provider used in new and existing unbound clients.
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @returns {Promise<void>}
+   * @throws Uncaught exceptions thrown by the provider during initialization.
+   */
+  setProviderAndWait(provider: Provider): Promise<void>;
+  /**
+   * Sets the default provider for flag evaluations and returns a promise that resolves when the provider is ready.
+   * This provider will be used by domainless clients and clients associated with domains to which no provider is bound.
+   * Setting a provider supersedes the current provider used in new and existing unbound clients.
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @param {EvaluationContext} context The evaluation context to use for flag evaluations.
+   * @returns {Promise<void>}
+   * @throws Uncaught exceptions thrown by the provider during initialization.
+   */
+  setProviderAndWait(provider: Provider, context: EvaluationContext): Promise<void>;
+  /**
+   * Sets the provider that OpenFeature will use for flag evaluations on clients bound to the same domain.
+   * A promise is returned that resolves when the provider is ready.
+   * Setting a provider supersedes the current provider used in new and existing clients bound to the same domain.
+   * @param {string} domain The name to identify the client
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @returns {Promise<void>}
+   * @throws Uncaught exceptions thrown by the provider during initialization.
+   */
+  setProviderAndWait(domain: string, provider: Provider): Promise<void>;
+  /**
+   * Sets the provider that OpenFeature will use for flag evaluations on clients bound to the same domain.
+   * A promise is returned that resolves when the provider is ready.
+   * Setting a provider supersedes the current provider used in new and existing clients bound to the same domain.
+   * @param {string} domain The name to identify the client
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @param {EvaluationContext} context The evaluation context to use for flag evaluations.
+   * @returns {Promise<void>}
+   * @throws Uncaught exceptions thrown by the provider during initialization.
+   */
+  setProviderAndWait(domain: string, provider: Provider, context: EvaluationContext): Promise<void>;
+  async setProviderAndWait(
+    clientOrProvider?: string | Provider,
+    providerContextOrUndefined?: Provider | EvaluationContext,
+    contextOrUndefined?: EvaluationContext,
+  ): Promise<void> {
+    const domain = stringOrUndefined(clientOrProvider);
+    const provider = domain
+      ? objectOrUndefined<Provider>(providerContextOrUndefined)
+      : objectOrUndefined<Provider>(clientOrProvider);
+    const context = domain
+      ? objectOrUndefined<EvaluationContext>(contextOrUndefined)
+      : objectOrUndefined<EvaluationContext>(providerContextOrUndefined);
+
+    if (context) {
+      // synonymously setting context prior to provider initialization.
+      // No context change event will be emitted.
+      if (domain) {
+        this._domainScopedContext.set(domain, context);
+      } else {
+        this._context = context;
+      }
+    }
+
+    await this.setAwaitableProvider(domain, provider);
+  }
+
+  /**
+   * Sets the default provider for flag evaluations.
+   * This provider will be used by domainless clients and clients associated with domains to which no provider is bound.
+   * Setting a provider supersedes the current provider used in new and existing unbound clients.
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @returns {this} OpenFeature API
+   */
+  setProvider(provider: Provider): this;
+  /**
+   * Sets the default provider and evaluation context for flag evaluations.
+   * This provider will be used by domainless clients and clients associated with domains to which no provider is bound.
+   * Setting a provider supersedes the current provider used in new and existing unbound clients.
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @param context {EvaluationContext} The evaluation context to use for flag evaluations.
+   * @returns {this} OpenFeature API
+   */
+  setProvider(provider: Provider, context: EvaluationContext): this;
+  /**
+   * Sets the provider for flag evaluations of providers with the given name.
+   * Setting a provider supersedes the current provider used in new and existing clients bound to the same domain.
+   * @param {string} domain The name to identify the client
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @returns {this} OpenFeature API
+   */
+  setProvider(domain: string, provider: Provider): this;
+  /**
+   * Sets the provider and evaluation context flag evaluations of providers with the given name.
+   * Setting a provider supersedes the current provider used in new and existing clients bound to the same domain.
+   * @param {string} domain The name to identify the client
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @param context {EvaluationContext} The evaluation context to use for flag evaluations.
+   * @returns {this} OpenFeature API
+   */
+  setProvider(domain: string, provider: Provider, context: EvaluationContext): this;
+  setProvider(
+    domainOrProvider?: string | Provider,
+    providerContextOrUndefined?: Provider | EvaluationContext,
+    contextOrUndefined?: EvaluationContext,
+  ): this {
+    const domain = stringOrUndefined(domainOrProvider);
+    const provider = domain
+      ? objectOrUndefined<Provider>(providerContextOrUndefined)
+      : objectOrUndefined<Provider>(domainOrProvider);
+    const context = domain
+      ? objectOrUndefined<EvaluationContext>(contextOrUndefined)
+      : objectOrUndefined<EvaluationContext>(providerContextOrUndefined);
+
+    if (context) {
+      // synonymously setting context prior to provider initialization.
+      // No context change event will be emitted.
+      if (domain) {
+        this._domainScopedContext.set(domain, context);
+      } else {
+        this._context = context;
+      }
+    }
+
+    const maybePromise = this.setAwaitableProvider(domain, provider);
+
+    // The setProvider method doesn't return a promise so we need to catch and
+    // log any errors that occur during provider initialization to avoid having
+    // an unhandled promise rejection.
+    Promise.resolve(maybePromise).catch((err) => {
+      this._logger.error('Error during provider initialization:', err);
+    });
+    return this;
+  }
+
   /**
    * Sets the evaluation context globally.
    * This will be used by all providers that have not bound to a domain.
@@ -135,7 +269,7 @@ export class OpenFeatureAPI
    * @param {string} domain An identifier which logically binds clients with providers
    * @returns {EvaluationContext} Evaluation context
    */
-  getContext(domain?: string): EvaluationContext;
+  getContext(domain?: string | undefined): EvaluationContext;
   getContext(domainOrUndefined?: string): EvaluationContext {
     const domain = stringOrUndefined(domainOrUndefined);
     if (domain) {

packages/client/test/evaluation-context.spec.ts

@@ -1,12 +1,16 @@
 import { EvaluationContext, JsonValue, OpenFeature, Provider, ProviderMetadata, ResolutionDetails } from '../src';
 
+const initializeMock = jest.fn();
+
 class MockProvider implements Provider {
   readonly metadata: ProviderMetadata;
 
   constructor(options?: { name?: string }) {
     this.metadata = { name: options?.name ?? 'mock-provider' };
   }
 
+  initialize = initializeMock;
+
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   onContextChange(oldContext: EvaluationContext, newContext: EvaluationContext): Promise<void> {
     return Promise.resolve();
@@ -15,7 +19,7 @@ class MockProvider implements Provider {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   resolveBooleanEvaluation = jest.fn((flagKey: string, defaultValue: boolean, context: EvaluationContext) => {
     return {
-      value: true
+      value: true,
     };
   });
 
@@ -35,6 +39,7 @@ class MockProvider implements Provider {
 describe('Evaluation Context', () => {
   afterEach(async () => {
     await OpenFeature.clearContexts();
+    jest.clearAllMocks();
   });
 
   describe('Requirement 3.2.2', () => {
@@ -59,6 +64,42 @@ describe('Evaluation Context', () => {
       expect(OpenFeature.getContext('invalid')).toEqual(defaultContext);
     });
 
+    describe('Set context during provider registration', () => {
+      it('should set the context for the default provider', () => {
+        const context: EvaluationContext = { property1: false };
+        const provider = new MockProvider();
+        OpenFeature.setProvider(provider, context);
+        expect(OpenFeature.getContext()).toEqual(context);
+      });
+
+      it('should set the context for a domain', async () => {
+        const context: EvaluationContext = { property1: false };
+        const domain = 'test';
+        const provider = new MockProvider({ name: domain });
+        OpenFeature.setProvider(domain, provider, context);
+        expect(OpenFeature.getContext()).toEqual({});
+        expect(OpenFeature.getContext(domain)).toEqual(context);
+      });
+
+      it('should set the context for the default provider prior to initialization', async () => {
+        const context: EvaluationContext = { property1: false };
+        const provider = new MockProvider();
+        await OpenFeature.setProviderAndWait(provider, context);
+        expect(initializeMock).toHaveBeenCalledWith(context);
+        expect(OpenFeature.getContext()).toEqual(context);
+      });
+
+      it('should set the context for a domain prior to initialization', async () => {
+        const context: EvaluationContext = { property1: false };
+        const domain = 'test';
+        const provider = new MockProvider({ name: domain });
+        await OpenFeature.setProviderAndWait(domain, provider, context);
+        expect(OpenFeature.getContext()).toEqual({});
+        expect(OpenFeature.getContext(domain)).toEqual(context);
+        expect(initializeMock).toHaveBeenCalledWith(context);
+      });
+    });
+
     describe('Context Management', () => {
       it('should reset global context', async () => {
         const globalContext: EvaluationContext = { scope: 'global' };

packages/react/test/options.spec.ts

@@ -27,7 +27,7 @@ describe('normalizeOptions', () => {
     });
   });
 
-  // we fallback the more specific suspense props (`ssuspendUntilReady` and `suspendWhileReconciling`) to `suspend`
+  // we fallback the more specific suspense props (`suspendUntilReady` and `suspendWhileReconciling`) to `suspend`
   describe('suspend fallback', () => {
     it('should fallback to true suspend value', () => {
       const normalized = normalizeOptions({

packages/server/README.md

@@ -161,6 +161,9 @@ const requestContext = {
 const boolValue = await client.getBooleanValue('some-flag', false, requestContext);
 ```
 
+Context is merged by the SDK before a flag evaluation occurs.
+The merge order is defined [here](https://openfeature.dev/specification/sections/evaluation-context#requirement-323) in the OpenFeature specification.
+
 ### Hooks
 
 [Hooks](https://openfeature.dev/docs/reference/concepts/hooks) allow for custom logic to be added at well-defined points of the flag evaluation life-cycle.

packages/server/src/open-feature.ts

@@ -73,6 +73,68 @@ export class OpenFeatureAPI
     return this._domainScopedProviders.get(domain)?.status ?? this._defaultProvider.status;
   }
 
+  /**
+   * Sets the default provider for flag evaluations and returns a promise that resolves when the provider is ready.
+   * This provider will be used by domainless clients and clients associated with domains to which no provider is bound.
+   * Setting a provider supersedes the current provider used in new and existing unbound clients.
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @returns {Promise<void>}
+   * @throws Uncaught exceptions thrown by the provider during initialization.
+   */
+  setProviderAndWait(provider: Provider): Promise<void>;
+  /**
+   * Sets the provider that OpenFeature will use for flag evaluations on clients bound to the same domain.
+   * A promise is returned that resolves when the provider is ready.
+   * Setting a provider supersedes the current provider used in new and existing clients bound to the same domain.
+   * @param {string} domain The name to identify the client
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @returns {Promise<void>}
+   * @throws Uncaught exceptions thrown by the provider during initialization.
+   */
+  setProviderAndWait(domain: string, provider: Provider): Promise<void>;
+  async setProviderAndWait(domainOrProvider?: string | Provider, providerOrUndefined?: Provider): Promise<void> {
+    const domain = stringOrUndefined(domainOrProvider);
+    const provider = domain
+      ? objectOrUndefined<Provider>(providerOrUndefined)
+      : objectOrUndefined<Provider>(domainOrProvider);
+
+    await this.setAwaitableProvider(domain, provider);
+  }
+
+  /**
+   * Sets the default provider for flag evaluations.
+   * This provider will be used by domainless clients and clients associated with domains to which no provider is bound.
+   * Setting a provider supersedes the current provider used in new and existing unbound clients.
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @returns {this} OpenFeature API
+   */
+  setProvider(provider: Provider): this;
+  /**
+   * Sets the provider for flag evaluations of providers with the given name.
+   * Setting a provider supersedes the current provider used in new and existing clients bound to the same domain.
+   * @param {string} domain The name to identify the client
+   * @param {Provider} provider The provider responsible for flag evaluations.
+   * @returns {this} OpenFeature API
+   */
+  setProvider(domain: string, provider: Provider): this;
+  setProvider(clientOrProvider?: string | Provider, providerOrUndefined?: Provider): this {
+    const domain = stringOrUndefined(clientOrProvider);
+    const provider = domain
+      ? objectOrUndefined<Provider>(providerOrUndefined)
+      : objectOrUndefined<Provider>(clientOrProvider);
+
+    const maybePromise = this.setAwaitableProvider(domain, provider);
+
+    // The setProvider method doesn't return a promise so we need to catch and
+    // log any errors that occur during provider initialization to avoid having
+    // an unhandled promise rejection.
+    Promise.resolve(maybePromise).catch((err) => {
+      this._logger.error('Error during provider initialization:', err);
+    });
+
+    return this;
+  }
+
   setContext(context: EvaluationContext): this {
     this._context = context;
     return this;