feat: add PROVIDER_CONTEXT_CHANGED event (web-sdk only) (#731)

This PR:

- adds `PROVIDER_CONTEXT_CHANGED` events, which, in the static paradigm,
can be used to inform the SDK that the flags should be re-evaluated
(important for UI repaints in React, for instance (note this event is
only available in the web-sdk)
- runs the associated `PROVIDER_CONTEXT_CHANGED` handlers if the
provider's context handler function ran successfully or `PROVIDER_ERROR`
handlers otherwise.
- adds associated tests

A decent amount of this is just typing magic to reduce duplicated code
while making the new event only available in the web-sdk.

See: [associated spec
change](open-feature/spec#200)

Fixes: #729

---------

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

packages/client/src/client/open-feature-client.ts

@@ -10,14 +10,14 @@ import {
   JsonValue,
   Logger,
   OpenFeatureError,
-  ProviderEvents,
   ProviderStatus,
   ResolutionDetails,
   SafeLogger,
   StandardResolutionReasons,
   statusMatchesEvent
 } from '@openfeature/core';
 import { FlagEvaluationOptions } from '../evaluation';
+import { ProviderEvents } from '../events';
 import { InternalEventEmitter } from '../events/internal/internal-event-emitter';
 import { Hook } from '../hooks';
 import { OpenFeature } from '../open-feature';
@@ -54,7 +54,7 @@ export class OpenFeatureClient implements Client {
     return this.providerAccessor()?.status || ProviderStatus.READY;
   }
 
-  addHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void {
+  addHandler(eventType: ProviderEvents, handler: EventHandler): void {
     this.emitterAccessor().addHandler(eventType, handler);
     const shouldRunNow = statusMatchesEvent(eventType, this._provider.status);
 
@@ -68,7 +68,7 @@ export class OpenFeatureClient implements Client {
     }
   }
 
-  removeHandler<T extends ProviderEvents>(notificationType: T, handler: EventHandler<T>): void {
+  removeHandler(notificationType: ProviderEvents, handler: EventHandler): void {
     this.emitterAccessor().removeHandler(notificationType, handler);
   }
 

packages/client/src/events/events.ts

@@ -0,0 +1,8 @@
+import { ClientProviderEvents } from '@openfeature/core';
+
+export { ClientProviderEvents as ProviderEvents};
+
+/**
+ * A subset of events that can be directly emitted by providers.
+ */
+export type ProviderEmittableEvents = Exclude<ClientProviderEvents, ClientProviderEvents.ContextChanged>;

packages/client/src/events/index.ts

@@ -1 +1,2 @@
-export * from './open-feature-event-emitter';
+export * from './open-feature-event-emitter';
+export * from './events';

packages/client/src/events/internal/internal-event-emitter.ts

@@ -1,8 +1,9 @@
 import { CommonEventDetails, GenericEventEmitter } from '@openfeature/core';
+import { ProviderEvents } from '../events';
 
 /**
  * The InternalEventEmitter is not exported publicly and should only be used within the SDK. It extends the
  * OpenFeatureEventEmitter to include additional properties that can be included
  * in the event details.
  */
-export abstract class InternalEventEmitter extends GenericEventEmitter<CommonEventDetails> {};
+export abstract class InternalEventEmitter extends GenericEventEmitter<ProviderEvents, CommonEventDetails> {};

packages/client/src/events/open-feature-event-emitter.ts

@@ -1,14 +1,14 @@
 import { GenericEventEmitter } from '@openfeature/core';
 import EventEmitter from 'events';
-
+import { ProviderEmittableEvents } from './events';
 /**
  * The OpenFeatureEventEmitter can be used by provider developers to emit
  * events at various parts of the provider lifecycle.
  *
  * NOTE: Ready and error events are automatically emitted by the SDK based on
  * the result of the initialize method.
  */
-export class OpenFeatureEventEmitter extends GenericEventEmitter {
+export class OpenFeatureEventEmitter extends GenericEventEmitter<ProviderEmittableEvents> {
   protected readonly eventEmitter = new EventEmitter({ captureRejections: true });
 
   constructor() {

packages/client/src/open-feature.ts

@@ -1,14 +1,15 @@
 import {
   EvaluationContext,
+  GenericEventEmitter,
   ManageContext,
   OpenFeatureCommonAPI,
   objectOrUndefined,
   stringOrUndefined,
 } from '@openfeature/core';
 import { Client, OpenFeatureClient } from './client';
-import { NOOP_PROVIDER, Provider } from './provider';
-import { OpenFeatureEventEmitter } from './events';
+import { OpenFeatureEventEmitter, ProviderEvents } from './events';
 import { Hook } from './hooks';
+import { NOOP_PROVIDER, Provider } from './provider';
 
 // use a symbol as a key for the global singleton
 const GLOBAL_OPENFEATURE_API_KEY = Symbol.for('@openfeature/web-sdk/api');
@@ -19,7 +20,7 @@ type OpenFeatureGlobal = {
 const _globalThis = globalThis as OpenFeatureGlobal;
 
 export class OpenFeatureAPI extends OpenFeatureCommonAPI<Provider, Hook> implements ManageContext<Promise<void>> {
-  protected _events = new OpenFeatureEventEmitter();
+  protected _events: GenericEventEmitter<ProviderEvents> = new OpenFeatureEventEmitter();
   protected _defaultProvider: Provider = NOOP_PROVIDER;
   protected _createEventEmitter = () => new OpenFeatureEventEmitter();
   protected _namedProviderContext: Map<string, EvaluationContext> = new Map();
@@ -72,7 +73,7 @@ export class OpenFeatureAPI extends OpenFeatureCommonAPI<Provider, Hook> impleme
       if (provider) {
         const oldContext = this.getContext(clientName);
         this._namedProviderContext.set(clientName, context);
-        await this.runProviderContextChangeHandler(provider, oldContext, context);
+        await this.runProviderContextChangeHandler(clientName, provider, oldContext, context);
       } else {
         this._namedProviderContext.set(clientName, context);
       }
@@ -89,7 +90,7 @@ export class OpenFeatureAPI extends OpenFeatureCommonAPI<Provider, Hook> impleme
 
       const allProviders = [this._defaultProvider, ...providersWithoutContextOverride];
       await Promise.all(
-        allProviders.map((provider) => this.runProviderContextChangeHandler(provider, oldContext, context)),
+        allProviders.map((provider) => this.runProviderContextChangeHandler(undefined, provider, oldContext, context)),
       );
     }
   }
@@ -136,7 +137,7 @@ export class OpenFeatureAPI extends OpenFeatureCommonAPI<Provider, Hook> impleme
         const oldContext = this.getContext(clientName);
         this._namedProviderContext.delete(clientName);
         const newContext = this.getContext();
-        await this.runProviderContextChangeHandler(provider, oldContext, newContext);
+        await this.runProviderContextChangeHandler(clientName, provider, oldContext, newContext);
       } else {
         this._namedProviderContext.delete(clientName);
       }
@@ -190,15 +191,24 @@ export class OpenFeatureAPI extends OpenFeatureCommonAPI<Provider, Hook> impleme
   }
 
   private async runProviderContextChangeHandler(
+    clientName: string | undefined,
     provider: Provider,
     oldContext: EvaluationContext,
     newContext: EvaluationContext,
   ): Promise<void> {
-    try {
-      return await provider.onContextChange?.(oldContext, newContext);
-    } catch (err) {
-      this._logger?.error(`Error running ${provider.metadata.name}'s context change handler:`, err);
-    }
+      const providerName = provider.metadata.name;
+      return provider.onContextChange?.(oldContext, newContext).then(() => {
+        this.getAssociatedEventEmitters(clientName).forEach((emitter) => {
+          emitter?.emit(ProviderEvents.ContextChanged, { clientName, providerName });
+        });
+        this._events?.emit(ProviderEvents.ContextChanged, { clientName, providerName });
+      }).catch((err) => {
+        this._logger?.error(`Error running ${provider.metadata.name}'s context change handler:`, err);
+        this.getAssociatedEventEmitters(clientName).forEach((emitter) => {
+          emitter?.emit(ProviderEvents.Error, { clientName, providerName, message: err?.message, });
+        });
+        this._events?.emit(ProviderEvents.Error, { clientName, providerName, message: err?.message, });
+      });
   }
 }
 

packages/client/src/provider/in-memory-provider/in-memory-provider.ts

@@ -6,14 +6,13 @@ import {
   JsonValue,
   Logger,
   OpenFeatureError,
-  ProviderEvents,
   ResolutionDetails,
   StandardResolutionReasons,
   TypeMismatchError,
   ProviderStatus,
 } from '@openfeature/core';
 import { Provider } from '../provider';
-import { OpenFeatureEventEmitter } from '../../events';
+import { OpenFeatureEventEmitter, ProviderEvents } from '../../events';
 import { FlagConfiguration, Flag } from './flag-configuration';
 import { VariantNotFoundError } from './variant-not-found-error';