Add setProvider option to delay initialization

Author: MattIPv4

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) {

packages/web/src/open-feature.ts

@@ -16,6 +16,13 @@ import type { Hook } from './hooks';
 import type { Provider} from './provider';
 import { NOOP_PROVIDER, ProviderStatus } from './provider';
 
+interface SetProviderOptions {
+  /**
+   * If true, delays provider initialization until the first context change.
+   */
+  delayed?: boolean;
+}
+
 // use a symbol as a key for the global singleton
 const GLOBAL_OPENFEATURE_API_KEY = Symbol.for('@openfeature/web-sdk/api');
 
@@ -150,10 +157,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 {SetProviderOptions} [options] Options for setting the provider.
    * @returns {this} OpenFeature API
    */
-  setProvider(provider: Provider, context: EvaluationContext): this;
+  setProvider<T extends SetProviderOptions>(provider: Provider, context: T extends { delayed: true } ? Record<never, never> : EvaluationContext, options?: T): 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,22 +175,27 @@ 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 {SetProviderOptions} [options] Options for setting the provider.
    * @returns {this} OpenFeature API
    */
-  setProvider(domain: string, provider: Provider, context: EvaluationContext): this;
+  setProvider<T extends SetProviderOptions>(domain: string, provider: Provider, context: T extends { delayed: true } ? Record<never, never> : EvaluationContext, options?: T): this;
   setProvider(
     domainOrProvider?: string | Provider,
     providerContextOrUndefined?: Provider | EvaluationContext,
-    contextOrUndefined?: EvaluationContext,
+    contextOptionsOrUndefined?: EvaluationContext | SetProviderOptions,
+    optionsOrUndefined?: SetProviderOptions,
   ): 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<SetProviderOptions>(optionsOrUndefined)
+      : objectOrUndefined<SetProviderOptions>(contextOptionsOrUndefined);
 
     if (context) {
       // synonymously setting context prior to provider initialization.
@@ -194,7 +207,7 @@ export class OpenFeatureAPI
       }
     }
 
-    const maybePromise = this.setAwaitableProvider(domain, provider);
+    const maybePromise = this.setAwaitableProvider(domain, provider, options?.delayed);
 
     // 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