Accept a validateContext to skip initialization

MattIPv4 · MattIPv4 · commit 6990b6359191 · 2025-11-25T21:25:42.000Z
diff --git a/packages/shared/src/open-feature.ts b/packages/shared/src/open-feature.ts
@@ -228,13 +228,15 @@ export abstract class OpenFeatureCommonAPI<
   abstract setProviderAndWait(
     clientOrProvider?: string | P,
     providerContextOrUndefined?: P | EvaluationContext,
-    contextOrUndefined?: EvaluationContext,
+    contextOptionsOrUndefined?: EvaluationContext | Record<never, never>,
+    optionsOrUndefined?: Record<never, never>,
   ): Promise<void>;
 
   abstract setProvider(
     clientOrProvider?: string | P,
     providerContextOrUndefined?: P | EvaluationContext,
-    contextOrUndefined?: EvaluationContext,
+    contextOptionsOrUndefined?: EvaluationContext | Record<never, never>,
+    optionsOrUndefined?: Record<never, never>,
   ): this;
 
   protected initializeProviderForDomain(wrapper: ProviderWrapper<P, AnyProviderStatus>, domain?: string): Promise<void> | void {
@@ -285,7 +287,7 @@ export abstract class OpenFeatureCommonAPI<
       });
     }
 
-  protected setAwaitableProvider(domainOrProvider?: string | P, providerOrUndefined?: P): Promise<void> | void {
+  protected setAwaitableProvider(domainOrProvider?: string | P, providerOrUndefined?: P, skipInitialization = false): Promise<void> | void {
     const domain = stringOrUndefined(domainOrProvider);
     const provider = objectOrUndefined<P>(domainOrProvider) ?? objectOrUndefined<P>(providerOrUndefined);
 
@@ -318,17 +320,19 @@ export abstract class OpenFeatureCommonAPI<
       this._statusEnumType,
     );
 
-    // initialize the provider if it's not already registered and it implements "initialize"
-    if (!this.allProviders.includes(provider)) {
-      initializationPromise = this.initializeProviderForDomain(wrappedProvider, domain);
-    }
+    if (!skipInitialization) {
+      // initialize the provider if it's not already registered and it implements "initialize"
+      if (!this.allProviders.includes(provider)) {
+        initializationPromise = this.initializeProviderForDomain(wrappedProvider, domain);
+      }
 
-    if (!initializationPromise) {
-      wrappedProvider.status = this._statusEnumType.READY;
-      emitters.forEach((emitter) => {
-        emitter?.emit(AllProviderEvents.Ready, { clientName: domain, domain, providerName });
-      });
-      this._apiEmitter?.emit(AllProviderEvents.Ready, { clientName: domain, domain, providerName });
+      if (!initializationPromise) {
+        wrappedProvider.status = this._statusEnumType.READY;
+        emitters.forEach((emitter) => {
+          emitter?.emit(AllProviderEvents.Ready, { clientName: domain, domain, providerName });
+        });
+        this._apiEmitter?.emit(AllProviderEvents.Ready, { clientName: domain, domain, providerName });
+      }
     }
 
     if (domain) {
diff --git a/packages/web/src/open-feature.ts b/packages/web/src/open-feature.ts
@@ -16,6 +16,17 @@ import type { Hook } from './hooks';
 import type { Provider} from './provider';
 import { NOOP_PROVIDER, ProviderStatus } from './provider';
 
+interface ProviderOptions {
+  /**
+   * If provided, will be used to check if the current context is valid during initialization and context changes.
+   * When calling `setProvider`, returning `false` will skip provider initialization. Throwing will move the provider to the ERROR state.
+   * When calling `setProviderAndWait`, returning `false` will skip provider initialization. Throwing will reject the promise.
+   * TODO: When calling `setContext`, returning `false` will skip provider context change handling. Throwing will move the provider to the ERROR state.
+   * @param context The evaluation context to validate.
+   */
+  validateContext?: (context: EvaluationContext) => boolean;
+}
+
 // use a symbol as a key for the global singleton
 const GLOBAL_OPENFEATURE_API_KEY = Symbol.for('@openfeature/web-sdk/api');
 
@@ -86,10 +97,11 @@ export class OpenFeatureAPI
    * 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.
+   * @param {ProviderOptions} [options] Options for setting the provider.
    * @returns {Promise<void>}
    * @throws {Error} If the provider throws an exception during initialization.
    */
-  setProviderAndWait(provider: Provider, context: EvaluationContext): Promise<void>;
+  setProviderAndWait(provider: Provider, context: EvaluationContext, options?: ProviderOptions): 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.
@@ -107,24 +119,41 @@ export class OpenFeatureAPI
    * @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.
+   * @param {ProviderOptions} [options] Options for setting the provider.
    * @returns {Promise<void>}
    * @throws {Error} If the provider throws an exception during initialization.
    */
-  setProviderAndWait(domain: string, provider: Provider, context: EvaluationContext): Promise<void>;
+  setProviderAndWait(domain: string, provider: Provider, context: EvaluationContext, options?: ProviderOptions): Promise<void>;
   async setProviderAndWait(
     clientOrProvider?: string | Provider,
     providerContextOrUndefined?: Provider | EvaluationContext,
-    contextOrUndefined?: EvaluationContext,
+    contextOptionsOrUndefined?: EvaluationContext | ProviderOptions,
+    optionsOrUndefined?: ProviderOptions,
   ): Promise<void> {
     const domain = stringOrUndefined(clientOrProvider);
     const provider = domain
       ? objectOrUndefined<Provider>(providerContextOrUndefined)
       : objectOrUndefined<Provider>(clientOrProvider);
     const context = domain
-      ? objectOrUndefined<EvaluationContext>(contextOrUndefined)
+      ? objectOrUndefined<EvaluationContext>(contextOptionsOrUndefined)
       : objectOrUndefined<EvaluationContext>(providerContextOrUndefined);
+    const options = domain
+      ? objectOrUndefined<ProviderOptions>(optionsOrUndefined)
+      : objectOrUndefined<ProviderOptions>(contextOptionsOrUndefined);
 
+    let skipInitialization = false;
     if (context) {
+      // validate the context to decide if we should initialize the provider with it.
+      if (typeof options?.validateContext === 'function') {
+        // allow any error to propagate here to reject the promise.
+        skipInitialization = !options.validateContext(context);
+        if (skipInitialization) {
+          this._logger.debug(
+            `Skipping provider initialization during setProviderAndWait for domain '${domain ?? 'default'}' due to validateContext returning false.`,
+          );
+        }
+      }
+
       // synonymously setting context prior to provider initialization.
       // No context change event will be emitted.
       if (domain) {
@@ -134,7 +163,7 @@ export class OpenFeatureAPI
       }
     }
 
-    await this.setAwaitableProvider(domain, provider);
+    await this.setAwaitableProvider(domain, provider, skipInitialization);
   }
 
   /**
@@ -150,10 +179,11 @@ export class OpenFeatureAPI
    * 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.
+   * @param {EvaluationContext} context The evaluation context to use for flag evaluations. Ignored if 'delayed' option is set.
+   * @param {ProviderOptions} [options] Options for setting the provider.
    * @returns {this} OpenFeature API
    */
-  setProvider(provider: Provider, context: EvaluationContext): this;
+  setProvider(provider: Provider, context: EvaluationContext, options?: ProviderOptions): 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.
@@ -167,24 +197,50 @@ export class OpenFeatureAPI
    * 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.
+   * @param {EvaluationContext} context The evaluation context to use for flag evaluations. Ignored if 'delayed' option is set.
+   * @param {ProviderOptions} [options] Options for setting the provider.
    * @returns {this} OpenFeature API
    */
-  setProvider(domain: string, provider: Provider, context: EvaluationContext): this;
+  setProvider(domain: string, provider: Provider, context: EvaluationContext, options?: ProviderOptions): this;
   setProvider(
     domainOrProvider?: string | Provider,
     providerContextOrUndefined?: Provider | EvaluationContext,
-    contextOrUndefined?: EvaluationContext,
+    contextOptionsOrUndefined?: EvaluationContext | ProviderOptions,
+    optionsOrUndefined?: ProviderOptions,
   ): this {
     const domain = stringOrUndefined(domainOrProvider);
     const provider = domain
       ? objectOrUndefined<Provider>(providerContextOrUndefined)
       : objectOrUndefined<Provider>(domainOrProvider);
     const context = domain
-      ? objectOrUndefined<EvaluationContext>(contextOrUndefined)
+      ? objectOrUndefined<EvaluationContext>(contextOptionsOrUndefined)
       : objectOrUndefined<EvaluationContext>(providerContextOrUndefined);
+    const options = domain
+      ? objectOrUndefined<ProviderOptions>(optionsOrUndefined)
+      : objectOrUndefined<ProviderOptions>(contextOptionsOrUndefined);
 
+    let skipInitialization = false;
+    let validateContextError: unknown;
     if (context) {
+      // validate the context to decide if we should initialize the provider with it.
+      if (typeof options?.validateContext === 'function') {
+        try {
+          skipInitialization = !options.validateContext(context);
+          if (skipInitialization) {
+            this._logger.debug(
+              `Skipping provider initialization during setProvider for domain '${domain ?? 'default'}' due to validateContext returning false.`,
+            );
+          }
+        } catch (err) {
+          // capture the error to move the provider to ERROR state after setting it.
+          validateContextError = err;
+          skipInitialization = true;
+          this._logger.debug(
+            `Skipping provider initialization during setProvider for domain '${domain ?? 'default'}' due to validateContext throwing an error.`,
+          );
+        }
+      }
+
       // synonymously setting context prior to provider initialization.
       // No context change event will be emitted.
       if (domain) {
@@ -194,7 +250,34 @@ export class OpenFeatureAPI
       }
     }
 
-    const maybePromise = this.setAwaitableProvider(domain, provider);
+    const maybePromise = this.setAwaitableProvider(domain, provider, skipInitialization);
+
+    // If there was a validation error with the context, move the newly created provider to ERROR state.
+    // We know we've skipped initialization if this happens, so no need to worry about the promise changing the state later.
+    if (validateContextError) {
+      const wrapper = domain
+        ? this._domainScopedProviders.get(domain)
+        : this._defaultProvider;
+      if (wrapper) {
+        wrapper.status = this._statusEnumType.ERROR;
+        const providerName = wrapper.provider?.metadata?.name || 'unnamed-provider';
+        this.getAssociatedEventEmitters(domain).forEach((emitter) => {
+          emitter?.emit(ProviderEvents.Error, {
+            clientName: domain,
+            domain,
+            providerName,
+            message: `Error validating context during setProvider: ${validateContextError instanceof Error ? validateContextError.message : String(validateContextError)}`,
+          });
+        });
+        this._apiEmitter?.emit(ProviderEvents.Error, {
+          clientName: domain,
+          domain,
+          providerName,
+          message: `Error validating context during setProvider: ${validateContextError instanceof Error ? validateContextError.message : String(validateContextError)}`,
+        });
+        this._logger.error('Error validating context during setProvider:', validateContextError);
+      }
+    }
 
     // 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
@@ -249,6 +332,8 @@ export class OpenFeatureAPI
     const domain = stringOrUndefined(domainOrContext);
     const context = objectOrUndefined<T>(domainOrContext) ?? objectOrUndefined(contextOrUndefined) ?? {};
 
+    // TODO: We need to store and call `validateContext` here if provided in `setProvider` options
+
     if (domain) {
       const wrapper = this._domainScopedProviders.get(domain);
       if (wrapper) {
