Accept a validateContext as option instead

Author: MattIPv4

packages/web/src/open-feature.ts

@@ -18,9 +18,13 @@ import { NOOP_PROVIDER, ProviderStatus } from './provider';
 
 interface SetProviderOptions {
   /**
-   * If true, delays provider initialization until the first context change.
+   * 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.
    */
-  delayed?: boolean;
+  validateContext?: (context: EvaluationContext) => boolean;
 }
 
 // use a symbol as a key for the global singleton
@@ -93,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 {SetProviderOptions} [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?: SetProviderOptions): 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.
@@ -114,22 +119,33 @@ 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 {SetProviderOptions} [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?: SetProviderOptions): Promise<void>;
   async setProviderAndWait(
     clientOrProvider?: string | Provider,
     providerContextOrUndefined?: Provider | EvaluationContext,
-    contextOrUndefined?: EvaluationContext,
+    contextOptionsOrUndefined?: EvaluationContext | SetProviderOptions,
+    optionsOrUndefined?: SetProviderOptions,
   ): 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<SetProviderOptions>(optionsOrUndefined)
+      : objectOrUndefined<SetProviderOptions>(contextOptionsOrUndefined);
+
+    let skipInitialization = false;
+    if (typeof options?.validateContext === 'function' && context) {
+      // allow any error to propagate here to reject the promise
+      skipInitialization = !options.validateContext(context);
+    }
 
     if (context) {
       // synonymously setting context prior to provider initialization.
@@ -141,7 +157,7 @@ export class OpenFeatureAPI
       }
     }
 
-    await this.setAwaitableProvider(domain, provider);
+    await this.setAwaitableProvider(domain, provider, skipInitialization);
   }
 
   /**
@@ -161,7 +177,7 @@ export class OpenFeatureAPI
    * @param {SetProviderOptions} [options] Options for setting the provider.
    * @returns {this} OpenFeature API
    */
-  setProvider<T extends SetProviderOptions>(provider: Provider, context: T extends { delayed: true } ? Record<never, never> : EvaluationContext, options?: T): this;
+  setProvider(provider: Provider, context: EvaluationContext, options?: SetProviderOptions): 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.
@@ -179,7 +195,7 @@ export class OpenFeatureAPI
    * @param {SetProviderOptions} [options] Options for setting the provider.
    * @returns {this} OpenFeature API
    */
-  setProvider<T extends SetProviderOptions>(domain: string, provider: Provider, context: T extends { delayed: true } ? Record<never, never> : EvaluationContext, options?: T): this;
+  setProvider(domain: string, provider: Provider, context: EvaluationContext, options?: SetProviderOptions): this;
   setProvider(
     domainOrProvider?: string | Provider,
     providerContextOrUndefined?: Provider | EvaluationContext,
@@ -197,6 +213,26 @@ export class OpenFeatureAPI
       ? objectOrUndefined<SetProviderOptions>(optionsOrUndefined)
       : objectOrUndefined<SetProviderOptions>(contextOptionsOrUndefined);
 
+    let skipInitialization = false;
+    let validateContextError: unknown;
+    if (typeof options?.validateContext === 'function' && context) {
+      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.`,
+        );
+      }
+    }
+
     if (context) {
       // synonymously setting context prior to provider initialization.
       // No context change event will be emitted.
@@ -207,7 +243,34 @@ export class OpenFeatureAPI
       }
     }
 
-    const maybePromise = this.setAwaitableProvider(domain, provider, options?.delayed);
+    const maybePromise = this.setAwaitableProvider(domain, provider, skipInitialization);
+
+    // If there was a validation error, move the provider to ERROR state.
+    // In this situation we should never have a promise returned from initialization.
+    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
@@ -262,6 +325,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) {