feat!: use node style events, add initialize (#379)

Adds and `initialize` handler, and uses node-style event emitters.

---------

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

Author: toddbaert

package-lock.json

@@ -35,6 +35,7 @@
     "@openfeature/flagd-provider": "~0.7.0",
     "@rollup/plugin-alias": "^4.0.3",
     "@rollup/plugin-typescript": "^11.0.0",
+    "@types/events": "^3.0.0",
     "@types/jest": "^29.0.0",
     "@types/node": "^18.0.3",
     "@typescript-eslint/eslint-plugin": "^5.23.0",
@@ -47,6 +48,7 @@
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-jest": "^27.0.1",
     "eslint-plugin-jsdoc": "^39.3.6",
+    "events": "^3.3.0",
     "jest": "^29.4.3",
     "jest-config": "^29.4.3",
     "jest-cucumber": "^3.0.1",

package.json

@@ -1,4 +1,4 @@
-import { OpenFeatureError } from '@openfeature/shared';
+import { EvaluationContext, OpenFeatureError } from '@openfeature/shared';
 import { SafeLogger } from '@openfeature/shared';
 import {
   ApiEvents,
@@ -15,8 +15,9 @@ import {
   ResolutionDetails,
   StandardResolutionReasons
 } from '@openfeature/shared';
+import { EventEmitter } from 'events';
 import { OpenFeature } from './open-feature';
-import { Client, EventProvider, FlagEvaluationOptions, Hook, Provider } from './types';
+import { Client, FlagEvaluationOptions, Hook, Provider } from './types';
 
 type OpenFeatureClientOptions = {
   name?: string;
@@ -35,9 +36,11 @@ export class OpenFeatureClient implements Client {
   private _handlerWrappers: HandlerWrapper[] = [];
 
   constructor(
-    // we always want the client to use the current provider,
-    // so pass a function to always access the currently registered one.
-    private readonly providerAccessor: () => Provider & Partial<EventProvider>,
+    // functions are passed here to make sure that these values are always up to date,
+    // and so we don't have to make these public properties on the API class. 
+    private readonly providerAccessor: () => Provider,
+    private readonly providerReady: () => boolean,
+    apiEvents: () => EventEmitter,
     private readonly globalLogger: () => Logger,
     options: OpenFeatureClientOptions,
   ) {
@@ -47,12 +50,14 @@ export class OpenFeatureClient implements Client {
     } as const;
 
     this.attachListeners();
-    window.dispatchEvent(new CustomEvent(ApiEvents.ProviderChanged));
+    apiEvents().on(ApiEvents.ProviderChanged, () => {
+      this.attachListeners();      
+    });
   }
 
   addHandler(eventType: ProviderEvents, handler: Handler): void {
     this._handlerWrappers.push({eventType, handler});
-    if (eventType === ProviderEvents.Ready && this.providerAccessor().ready) {
+    if (eventType === ProviderEvents.Ready && this.providerReady()) {
       // run immediately, we're ready.
       handler();
     }
@@ -166,6 +171,7 @@ export class OpenFeatureClient implements Client {
     resolver: (
       flagKey: string,
       defaultValue: T,
+      context: EvaluationContext,
       logger: Logger
     ) => ResolutionDetails<T>,
     defaultValue: T,
@@ -182,7 +188,6 @@ export class OpenFeatureClient implements Client {
     ];
     const allHooksReversed = [...allHooks].reverse();
 
-    // merge global and client contexts
     const context = {
       ...OpenFeature.getContext(),
     };
@@ -203,7 +208,7 @@ export class OpenFeatureClient implements Client {
       this.beforeHooks(allHooks, hookContext, options);
 
       // run the referenced resolver, binding the provider.
-      const resolution = resolver.call(this._provider, flagKey, defaultValue, this._logger);
+      const resolution = resolver.call(this._provider, flagKey, defaultValue, context, this._logger);
 
       const evaluationDetails = {
         ...resolution,
@@ -289,7 +294,7 @@ export class OpenFeatureClient implements Client {
     }
   }
 
-  private get _provider(): Provider & Partial<EventProvider> {
+  private get _provider(): Provider {
     return this.providerAccessor();
   }
 
@@ -300,7 +305,7 @@ export class OpenFeatureClient implements Client {
   private attachListeners() {
     // iterate over the event types
     Object.values(ProviderEvents)
-      .forEach(eventType => window.addEventListener(eventType, () => {
+      .forEach(eventType => this._provider.events?.on(eventType, () => {
         // on each event type, fire the associated handlers
         this._handlerWrappers
           .filter(wrapper => wrapper.eventType === eventType)

packages/client/src/client.ts

@@ -1,7 +1,7 @@
-import { NOOP_PROVIDER } from './no-op-provider';
-import { Logger, OpenFeatureCommonAPI, SafeLogger } from '@openfeature/shared';
-import { ApiEvents, EvaluationContext, FlagValue, ProviderMetadata } from '@openfeature/shared';
+import { ApiEvents, EvaluationContext, FlagValue, Logger, OpenFeatureCommonAPI, ProviderEvents, ProviderMetadata, SafeLogger } from '@openfeature/shared';
+import { EventEmitter } from 'events';
 import { OpenFeatureClient } from './client';
+import { NOOP_PROVIDER } from './no-op-provider';
 import { Client, Hook, Provider } from './types';
 
 // use a symbol as a key for the global singleton
@@ -14,10 +14,11 @@ const _globalThis = globalThis as OpenFeatureGlobal;
 
 export class OpenFeatureAPI extends OpenFeatureCommonAPI {
 
+  private _apiEvents = new EventEmitter();
+  private _providerReady = false;
   protected _hooks: Hook[] = [];
   protected _provider: Provider = NOOP_PROVIDER;
 
-
   // eslint-disable-next-line @typescript-eslint/no-empty-function
   private constructor() {
     super();
@@ -79,7 +80,24 @@ export class OpenFeatureAPI extends OpenFeatureCommonAPI {
     if (this._provider !== provider) {
       const oldProvider = this._provider;
       this._provider = provider;
-      window.dispatchEvent(new CustomEvent(ApiEvents.ProviderChanged));
+      this._providerReady = false;
+
+      if (!this._provider.events) {
+        this._provider.events = new EventEmitter();
+      }
+
+      if (typeof this._provider?.initialize === 'function') {
+        this._provider.initialize?.(this._context)?.then(() => {
+          this._providerReady = true;
+          this._provider.events?.emit(ProviderEvents.Ready);
+        })?.catch(() => {
+          this._provider.events?.emit(ProviderEvents.Error);
+        });
+      } else {
+        this._providerReady = true;
+        this._provider.events?.emit(ProviderEvents.Ready);
+      }
+      this._apiEvents.emit(ApiEvents.ProviderChanged);
       oldProvider?.onClose?.();
     }
     return this;
@@ -91,7 +109,11 @@ export class OpenFeatureAPI extends OpenFeatureCommonAPI {
 
   getClient(name?: string, version?: string): Client {
     return new OpenFeatureClient(
+      // functions are passed here to make sure that these values are always up to date,
+      // and so we don't have to make these public properties on the API class. 
       () => this._provider,
+      () => this._providerReady,
+      () => this._apiEvents,
       () => this._logger,
       { name, version },
     );

packages/client/src/open-feature.ts

@@ -16,6 +16,7 @@ import {
   ProviderMetadata,
   ResolutionDetails,
 } from '@openfeature/shared';
+import EventEmitter from 'events';
 
 /**
  * Interface that providers must implement to resolve flag values for their particular
@@ -33,18 +34,43 @@ export interface Provider extends CommonProvider {
    */
   readonly hooks?: Hook[];
 
-  // client vs global context?
+  /**
+   * An event emitter for ProviderEvents.
+   * @see ProviderEvents
+   */
+  events?: EventEmitter;
+
+  /**
+   * A handler function to reconcile changes when the static context.
+   * Called by the SDK when the context is changed.
+   * 
+   * @param oldContext 
+   * @param newContext 
+   */
   onContextChange?(oldContext: EvaluationContext, newContext: EvaluationContext): Promise<void>
 
   // TODO: move to common Provider type when we want close in server
   onClose?(): Promise<void>;
 
+  // TODO: move to common Provider type when we want close in server
+  /**
+   * A handler function used to setup the provider.
+   * Called by the SDK after the provider is set.
+   * When the returned promise resolves, the SDK fires the ProviderEvents.Ready event.
+   * If the returned promise rejects, the SDK fires the ProviderEvents.Error event.
+   * Use this function to perform any context-dependent setup within the provider.
+   * 
+   * @param context 
+   */
+  initialize?(context: EvaluationContext): Promise<void>;
+
   /**
    * Resolve a boolean flag and its evaluation details.
    */
   resolveBooleanEvaluation(
     flagKey: string,
     defaultValue: boolean,
+    context: EvaluationContext,
     logger: Logger
   ): ResolutionDetails<boolean>;
 
@@ -54,6 +80,7 @@ export interface Provider extends CommonProvider {
   resolveStringEvaluation(
     flagKey: string,
     defaultValue: string,
+    context: EvaluationContext,
     logger: Logger
   ): ResolutionDetails<string>;
 
@@ -63,6 +90,7 @@ export interface Provider extends CommonProvider {
   resolveNumberEvaluation(
     flagKey: string,
     defaultValue: number,
+    context: EvaluationContext,
     logger: Logger
   ): ResolutionDetails<number>;
 
@@ -72,6 +100,7 @@ export interface Provider extends CommonProvider {
   resolveObjectEvaluation<T extends JsonValue>(
     flagKey: string,
     defaultValue: T,
+    context: EvaluationContext,
     logger: Logger
   ): ResolutionDetails<T>;
 }
@@ -340,8 +369,4 @@ export interface GlobalApi
    * @returns {GlobalApi} OpenFeature API
    */
   setProvider(provider: Provider): GlobalApi;
-}
-
-export interface EventProvider {
-  readonly ready: boolean;
 }