@openfeature/web-sdk 0.3.7-experimental → 0.3.9-experimental

package/dist/types.d.ts

@@ -20,13 +20,28 @@ declare enum ProviderEvents {
 type EventMetadata = {
     [key: string]: string | boolean | number;
 };
-type EventDetails = {
+type CommonEventDetails = {
     clientName?: string;
+};
+type CommonEventProps = {
     message?: string;
-    flagsChanged?: string[];
     metadata?: EventMetadata;
 };
-type EventHandler = (eventDetails?: EventDetails) => Promise<unknown> | unknown;
+type ReadyEvent = CommonEventProps;
+type ErrorEvent = CommonEventProps;
+type StaleEvent = CommonEventProps;
+type ConfigChangeEvent = CommonEventProps & {
+    flagsChanged?: string[];
+};
+type EventMap = {
+    [ProviderEvents.Ready]: ReadyEvent;
+    [ProviderEvents.Error]: ErrorEvent;
+    [ProviderEvents.Stale]: StaleEvent;
+    [ProviderEvents.ConfigurationChanged]: ConfigChangeEvent;
+};
+type EventContext<T extends ProviderEvents, U extends Record<string, unknown> = Record<string, unknown>> = EventMap[T] & U;
+type EventDetails<T extends ProviderEvents> = EventContext<T> & CommonEventDetails;
+type EventHandler<T extends ProviderEvents> = (eventDetails?: EventDetails<T>) => Promise<unknown> | unknown;
 interface Eventing {
     /**
      * Adds a handler for the given provider event type.
@@ -34,19 +49,19 @@ interface Eventing {
      * @param {ProviderEvents} eventType The provider event type to listen to
      * @param {EventHandler} handler The handler to run on occurrence of the event type
      */
-    addHandler(eventType: ProviderEvents, handler: EventHandler): void;
+    addHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
     /**
      * Removes a handler for the given provider event type.
      * @param {ProviderEvents} eventType The provider event type to remove the listener for
      * @param {EventHandler} handler The handler to remove for the provider event type
      */
-    removeHandler(eventType: ProviderEvents, handler: EventHandler): void;
+    removeHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
     /**
      * Gets the current handlers for the given provider event type.
      * @param {ProviderEvents} eventType The provider event type to get the current handlers for
      * @returns {EventHandler[]} The handlers currently attached to the given provider event type
      */
-    getHandlers(eventType: ProviderEvents): EventHandler[];
+    getHandlers<T extends ProviderEvents>(eventType: T): EventHandler<T>[];
 }
 
 interface Logger {
@@ -87,20 +102,36 @@ declare class SafeLogger implements Logger {
     private log;
 }
 
-declare class OpenFeatureEventEmitter implements ManageLogger<OpenFeatureEventEmitter> {
+declare abstract class GenericEventEmitter<AdditionalContext extends Record<string, unknown> = Record<string, unknown>> implements ManageLogger<GenericEventEmitter<AdditionalContext>> {
     private readonly globalLogger?;
     private readonly _handlers;
     private readonly eventEmitter;
     private _eventLogger?;
     constructor(globalLogger?: (() => Logger) | undefined);
-    emit(eventType: ProviderEvents, context?: EventDetails): void;
-    addHandler(eventType: ProviderEvents, handler: EventHandler): void;
-    removeHandler(eventType: ProviderEvents, handler: EventHandler): void;
+    emit<T extends ProviderEvents>(eventType: T, context?: EventContext<T, AdditionalContext>): void;
+    addHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
+    removeHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
     removeAllHandlers(eventType?: ProviderEvents): void;
-    getHandlers(eventType: ProviderEvents): EventHandler[];
+    getHandlers<T extends ProviderEvents>(eventType: T): EventHandler<T>[];
     setLogger(logger: Logger): this;
     private get _logger();
 }
+/**
+ * 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.
+ */
+declare class OpenFeatureEventEmitter extends GenericEventEmitter {
+}
+/**
+ * The InternalEventEmitter should only be used within the SDK. It extends the
+ * OpenFeatureEventEmitter to include additional properties that can be included
+ * in the event details.
+ */
+declare class InternalEventEmitter extends GenericEventEmitter<CommonEventDetails> {
+}
 
 interface Metadata {
 }
@@ -235,26 +266,53 @@ interface ManageContext<T> {
     setContext(context: EvaluationContext): T;
 }
 
+/**
+ * The state of the provider.
+ */
 declare enum ProviderStatus {
+    /**
+     * The provider has not been initialized and cannot yet evaluate flags.
+     */
     NOT_READY = "NOT_READY",
+    /**
+     * The provider is ready to resolve flags.
+     */
     READY = "READY",
+    /**
+     * The provider is in an error state and unable to evaluate flags.
+     */
     ERROR = "ERROR"
 }
+/**
+ * Static data about the provider.
+ */
 interface ProviderMetadata extends Metadata {
     readonly name: string;
 }
 interface CommonProvider {
     readonly metadata: ProviderMetadata;
+    /**
+     * Returns a representation of the current readiness of the provider.
+     * If the provider needs to be initialized, it should return {@link ProviderStatus.READY}.
+     * If the provider is in an error state, it should return {@link ProviderStatus.ERROR}.
+     * If the provider is functioning normally, it should return {@link ProviderStatus.NOT_READY}.
+     *
+     * _Providers which do not implement this method are assumed to be ready immediately._
+     */
     readonly status?: ProviderStatus;
     /**
      * An event emitter for ProviderEvents.
      * @see ProviderEvents
      */
     events?: OpenFeatureEventEmitter;
+    /**
+     * A function used to shut down the provider.
+     * Called when this provider is replaced with a new one, or when the OpenFeature is shut down.
+     */
     onClose?(): Promise<void>;
     /**
-     * A handler function used to setup the provider.
-     * Called by the SDK after the provider is set.
+     * A function used to setup the provider.
+     * Called by the SDK after the provider is set if the provider's status is {@link ProviderStatus.NOT_READY}.
      * 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.
@@ -460,7 +518,7 @@ declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonPro
     private readonly _events;
     private readonly _clientEventHandlers;
     protected _clientProviders: Map<string, P>;
-    protected _clientEvents: Map<string | undefined, OpenFeatureEventEmitter>;
+    protected _clientEvents: Map<string | undefined, InternalEventEmitter>;
     addHooks(...hooks: Hook<FlagValue>[]): this;
     getHooks(): Hook<FlagValue>[];
     clearHooks(): this;
@@ -477,19 +535,19 @@ declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonPro
      * @param {ProviderEvents} eventType The provider event type to listen to
      * @param {EventHandler} handler The handler to run on occurrence of the event type
      */
-    addHandler(eventType: ProviderEvents, handler: EventHandler): void;
+    addHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
     /**
      * Removes a handler for the given provider event type.
      * @param {ProviderEvents} eventType The provider event type to remove the listener for
      * @param {EventHandler} handler The handler to remove for the provider event type
      */
-    removeHandler(eventType: ProviderEvents, handler: EventHandler): void;
+    removeHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
     /**
      * Gets the current handlers for the given provider event type.
      * @param {ProviderEvents} eventType The provider event type to get the current handlers for
      * @returns {EventHandler[]} The handlers currently attached to the given provider event type
      */
-    getHandlers(eventType: ProviderEvents): EventHandler[];
+    getHandlers<T extends ProviderEvents>(eventType: T): EventHandler<T>[];
     /**
      * Sets the default provider for flag evaluations.
      * This provider will be used by unnamed clients and named clients to which no provider is bound.
@@ -509,8 +567,9 @@ declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonPro
      */
     setProvider(clientName: string, provider: P): this;
     protected getProviderForClient(name?: string): P;
-    protected getAndCacheEventEmitterForClient(name?: string): OpenFeatureEventEmitter;
+    protected buildAndCacheEventEmitterForClient(name?: string): InternalEventEmitter;
     private getUnboundEmitters;
+    private getAssociatedEventEmitters;
     private transferListeners;
     close(): Promise<void>;
     private handleShutdownError;
@@ -674,13 +733,13 @@ declare class OpenFeatureClient implements Client {
     private _clientLogger?;
     constructor(providerAccessor: () => Provider, emitterAccessor: () => OpenFeatureEventEmitter, globalLogger: () => Logger, options: OpenFeatureClientOptions);
     get metadata(): ClientMetadata;
-    addHandler(eventType: ProviderEvents, handler: EventHandler): void;
-    removeHandler(notificationType: ProviderEvents, handler: EventHandler): void;
-    getHandlers(eventType: ProviderEvents): EventHandler[];
-    setLogger(logger: Logger): OpenFeatureClient;
-    addHooks(...hooks: Hook<FlagValue>[]): OpenFeatureClient;
+    addHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
+    removeHandler<T extends ProviderEvents>(notificationType: T, handler: EventHandler<T>): void;
+    getHandlers(eventType: ProviderEvents): EventHandler<ProviderEvents>[];
+    setLogger(logger: Logger): this;
+    addHooks(...hooks: Hook<FlagValue>[]): this;
     getHooks(): Hook<FlagValue>[];
-    clearHooks(): OpenFeatureClient;
+    clearHooks(): this;
     getBooleanValue(flagKey: string, defaultValue: boolean, options?: FlagEvaluationOptions): boolean;
     getBooleanDetails(flagKey: string, defaultValue: boolean, options?: FlagEvaluationOptions): EvaluationDetails<boolean>;
     getStringValue<T extends string = string>(flagKey: string, defaultValue: T, options?: FlagEvaluationOptions): T;
@@ -728,4 +787,4 @@ declare class OpenFeatureAPI extends OpenFeatureCommonAPI<Provider> implements M
  */
 declare const OpenFeature: OpenFeatureAPI;
 
-export { BeforeHookContext, Client, ClientMetadata, CommonProvider, DefaultLogger, ErrorCode, EvaluationContext, EvaluationContextValue, EvaluationDetails, EvaluationLifeCycle, EventDetails, EventHandler, EventMetadata, Eventing, Features, FlagEvaluationOptions, FlagMetadata, FlagNotFoundError, FlagValue, FlagValueType, GeneralError, Hook, HookContext, HookHints, InvalidContextError, JsonArray, JsonObject, JsonValue, LOG_LEVELS, Logger, ManageContext, ManageLogger, ManageTransactionContextPropagator, Metadata, NOOP_PROVIDER, NOOP_TRANSACTION_CONTEXT_PROPAGATOR, OpenFeature, OpenFeatureAPI, OpenFeatureClient, OpenFeatureCommonAPI, OpenFeatureError, OpenFeatureEventEmitter, ParseError, PrimitiveValue, Provider, ProviderEvents, ProviderMetadata, ProviderStatus, ResolutionDetails, ResolutionReason, SafeLogger, StandardResolutionReasons, TargetingKeyMissingError, TransactionContext, TransactionContextPropagator, TypeMismatchError, isObject, isString, objectOrUndefined, stringOrUndefined };
+export { BeforeHookContext, Client, ClientMetadata, CommonEventDetails, CommonProvider, ConfigChangeEvent, DefaultLogger, ErrorCode, ErrorEvent, EvaluationContext, EvaluationContextValue, EvaluationDetails, EvaluationLifeCycle, EventContext, EventDetails, EventHandler, EventMetadata, Eventing, Features, FlagEvaluationOptions, FlagMetadata, FlagNotFoundError, FlagValue, FlagValueType, GeneralError, Hook, HookContext, HookHints, InternalEventEmitter, InvalidContextError, JsonArray, JsonObject, JsonValue, LOG_LEVELS, Logger, ManageContext, ManageLogger, ManageTransactionContextPropagator, Metadata, NOOP_PROVIDER, NOOP_TRANSACTION_CONTEXT_PROPAGATOR, OpenFeature, OpenFeatureAPI, OpenFeatureClient, OpenFeatureCommonAPI, OpenFeatureError, OpenFeatureEventEmitter, ParseError, PrimitiveValue, Provider, ProviderEvents, ProviderMetadata, ProviderStatus, ReadyEvent, ResolutionDetails, ResolutionReason, SafeLogger, StaleEvent, StandardResolutionReasons, TargetingKeyMissingError, TransactionContext, TransactionContextPropagator, TypeMismatchError, isObject, isString, objectOrUndefined, stringOrUndefined };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfeature/web-sdk",
-  "version": "0.3.7-experimental",
+  "version": "0.3.9-experimental",
   "description": "OpenFeature SDK for Web",
   "main": "./dist/cjs/index.js",
   "files": [