@openfeature/web-sdk 0.4.8 → 0.4.9

package/dist/types.d.ts

@@ -130,7 +130,10 @@ interface ManageContext<T> {
     setContext(context: EvaluationContext): T;
 }
 
-declare enum ProviderEvents {
+/**
+ * An enumeration of possible events for server-sdk providers.
+ */
+declare enum ServerProviderEvents {
     /**
      * The provider is ready to evaluate flags.
      */
@@ -148,15 +151,46 @@ declare enum ProviderEvents {
      */
     Stale = "PROVIDER_STALE"
 }
+/**
+ * An enumeration of possible events for web-sdk providers.
+ */
+declare enum ClientProviderEvents {
+    /**
+     * The provider is ready to evaluate flags.
+     */
+    Ready = "PROVIDER_READY",
+    /**
+     * The provider is in an error state.
+     */
+    Error = "PROVIDER_ERROR",
+    /**
+     * The flag configuration in the source-of-truth has changed.
+     */
+    ConfigurationChanged = "PROVIDER_CONFIGURATION_CHANGED",
+    /**
+     * The context associated with the provider has changed, and the provider has reconciled it's associated state.
+     */
+    ContextChanged = "PROVIDER_CONTEXT_CHANGED",
+    /**
+     * The provider's cached state is no longer valid and may not be up-to-date with the source of truth.
+     */
+    Stale = "PROVIDER_STALE"
+}
+
+/**
+ * A type representing any possible ProviderEvent (server or client side).
+ * If you are implementing a hook or provider, you probably want to import `ProviderEvents` from the respective SDK.
+ */
+type AnyProviderEvent = ServerProviderEvents | ClientProviderEvents;
 
 /**
  * Returns true if the provider's status corresponds to the event.
  * If the provider's status is not defined, it matches READY.
- * @param {ProviderEvents} event event to match
+ * @param {AnyProviderEvent} event event to match
  * @param {ProviderStatus} status  status of provider
  * @returns {boolean} boolean indicating if the provider status corresponds to the event.
  */
-declare const statusMatchesEvent: (event: ProviderEvents, status?: ProviderStatus) => boolean;
+declare const statusMatchesEvent: <T extends AnyProviderEvent>(event: T, status?: ProviderStatus) => boolean;
 
 type EventMetadata = {
     [key: string]: string | boolean | number;
@@ -176,34 +210,35 @@ type ConfigChangeEvent = CommonEventProps & {
     flagsChanged?: string[];
 };
 type EventMap = {
-    [ProviderEvents.Ready]: ReadyEvent;
-    [ProviderEvents.Error]: ErrorEvent;
-    [ProviderEvents.Stale]: StaleEvent;
-    [ProviderEvents.ConfigurationChanged]: ConfigChangeEvent;
+    [ClientProviderEvents.Ready]: ReadyEvent;
+    [ClientProviderEvents.Error]: ErrorEvent;
+    [ClientProviderEvents.Stale]: StaleEvent;
+    [ClientProviderEvents.ContextChanged]: CommonEventProps;
+    [ClientProviderEvents.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;
+type EventContext<U extends Record<string, unknown> = Record<string, unknown>> = EventMap[ClientProviderEvents] & U;
+type EventDetails = EventContext & CommonEventDetails;
+type EventHandler = (eventDetails?: EventDetails) => Promise<unknown> | unknown;
 interface Eventing {
     /**
      * Adds a handler for the given provider event type.
      * The handlers are called in the order they have been added.
-     * @param {ProviderEvents} eventType The provider event type to listen to
+     * @param {AnyProviderEvent} eventType The provider event type to listen to
      * @param {EventHandler} handler The handler to run on occurrence of the event type
      */
-    addHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
+    addHandler(eventType: AnyProviderEvent, handler: EventHandler): void;
     /**
      * Removes a handler for the given provider event type.
-     * @param {ProviderEvents} eventType The provider event type to remove the listener for
+     * @param {AnyProviderEvent} eventType The provider event type to remove the listener for
      * @param {EventHandler} handler The handler to remove for the provider event type
      */
-    removeHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
+    removeHandler(eventType: AnyProviderEvent, handler: EventHandler): void;
     /**
      * Gets the current handlers for the given provider event type.
-     * @param {ProviderEvents} eventType The provider event type to get the current handlers for
+     * @param {AnyProviderEvent} eventType The provider event type to get the current handlers for
      * @returns {EventHandler[]} The handlers currently attached to the given provider event type
      */
-    getHandlers<T extends ProviderEvents>(eventType: T): EventHandler<T>[];
+    getHandlers(eventType: AnyProviderEvent): EventHandler[];
 }
 
 interface Logger {
@@ -248,17 +283,17 @@ declare class SafeLogger implements Logger {
  * The GenericEventEmitter should only be used within the SDK. It supports additional properties that can be included
  * in the event details.
  */
-declare abstract class GenericEventEmitter<AdditionalContext extends Record<string, unknown> = Record<string, unknown>> implements ManageLogger<GenericEventEmitter<AdditionalContext>> {
+declare abstract class GenericEventEmitter<E extends AnyProviderEvent, AdditionalContext extends Record<string, unknown> = Record<string, unknown>> implements ManageLogger<GenericEventEmitter<E, AdditionalContext>> {
     private readonly globalLogger?;
     protected abstract readonly eventEmitter: PlatformEventEmitter;
     private readonly _handlers;
     private _eventLogger?;
     constructor(globalLogger?: (() => Logger) | undefined);
-    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<T extends ProviderEvents>(eventType: T): EventHandler<T>[];
+    emit(eventType: E, context?: EventContext): void;
+    addHandler(eventType: AnyProviderEvent, handler: EventHandler): void;
+    removeHandler(eventType: AnyProviderEvent, handler: EventHandler): void;
+    removeAllHandlers(eventType?: AnyProviderEvent): void;
+    getHandlers(eventType: AnyProviderEvent): EventHandler[];
     setLogger(logger: Logger): this;
     protected get _logger(): Logger | undefined;
 }
@@ -341,7 +376,7 @@ interface CommonProvider {
      * An event emitter for ProviderEvents.
      * @see ProviderEvents
      */
-    events?: GenericEventEmitter;
+    events?: GenericEventEmitter<AnyProviderEvent>;
     /**
      * 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.
@@ -500,15 +535,15 @@ declare function isObject<T extends object>(value: unknown): value is T;
 declare function objectOrUndefined<T extends object>(value: unknown): T | undefined;
 
 declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonProvider, H extends BaseHook = BaseHook> implements Eventing, EvaluationLifeCycle<OpenFeatureCommonAPI<P>>, ManageLogger<OpenFeatureCommonAPI<P>> {
-    protected abstract _createEventEmitter(): GenericEventEmitter;
+    protected abstract _createEventEmitter(): GenericEventEmitter<AnyProviderEvent>;
     protected abstract _defaultProvider: P;
-    protected abstract readonly _events: GenericEventEmitter;
+    protected abstract readonly _events: GenericEventEmitter<AnyProviderEvent>;
     protected _hooks: H[];
     protected _context: EvaluationContext;
     protected _logger: Logger;
     private readonly _clientEventHandlers;
     protected _clientProviders: Map<string, P>;
-    protected _clientEvents: Map<string | undefined, GenericEventEmitter>;
+    protected _clientEvents: Map<string | undefined, GenericEventEmitter<AnyProviderEvent>>;
     protected _runsOn: Paradigm;
     constructor(category: Paradigm);
     addHooks(...hooks: H[]): this;
@@ -516,30 +551,37 @@ declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonPro
     clearHooks(): this;
     setLogger(logger: Logger): this;
     /**
-     * Get metadata about registered provider.
+     * Get metadata about the default provider.
      * @returns {ProviderMetadata} Provider Metadata
      */
     get providerMetadata(): ProviderMetadata;
+    /**
+     * Get metadata about a registered provider using the client name.
+     * An unbound or empty client name will return metadata from the default provider.
+     * @param {string} [clientName] The name to identify the client
+     * @returns {ProviderMetadata} Provider Metadata
+     */
+    getProviderMetadata(clientName?: string): ProviderMetadata;
     /**
      * Adds a handler for the given provider event type.
      * The handlers are called in the order they have been added.
      * API (global) events run for all providers.
-     * @param {ProviderEvents} eventType The provider event type to listen to
+     * @param {AnyProviderEvent} eventType The provider event type to listen to
      * @param {EventHandler} handler The handler to run on occurrence of the event type
      */
-    addHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
+    addHandler<T extends AnyProviderEvent>(eventType: T, handler: EventHandler): void;
     /**
      * Removes a handler for the given provider event type.
-     * @param {ProviderEvents} eventType The provider event type to remove the listener for
+     * @param {AnyProviderEvent} eventType The provider event type to remove the listener for
      * @param {EventHandler} handler The handler to remove for the provider event type
      */
-    removeHandler<T extends ProviderEvents>(eventType: T, handler: EventHandler<T>): void;
+    removeHandler<T extends AnyProviderEvent>(eventType: T, handler: EventHandler): void;
     /**
      * Gets the current handlers for the given provider event type.
-     * @param {ProviderEvents} eventType The provider event type to get the current handlers for
+     * @param {AnyProviderEvent} eventType The provider event type to get the current handlers for
      * @returns {EventHandler[]} The handlers currently attached to the given provider event type
      */
-    getHandlers<T extends ProviderEvents>(eventType: T): EventHandler<T>[];
+    getHandlers<T extends AnyProviderEvent>(eventType: T): EventHandler[];
     /**
      * Sets the default provider for flag evaluations and returns a promise that resolves when the provider is ready.
      * This provider will be used by unnamed clients and named clients to which no provider is bound.
@@ -581,9 +623,9 @@ declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonPro
     setProvider(clientName: string, provider: P): this;
     private setAwaitableProvider;
     protected getProviderForClient(name?: string): P;
-    protected buildAndCacheEventEmitterForClient(name?: string): GenericEventEmitter;
+    protected buildAndCacheEventEmitterForClient(name?: string): GenericEventEmitter<AnyProviderEvent>;
     private getUnboundEmitters;
-    private getAssociatedEventEmitters;
+    protected getAssociatedEventEmitters(clientName: string | undefined): GenericEventEmitter<AnyProviderEvent, Record<string, unknown>>[];
     private transferListeners;
     close(): Promise<void>;
     protected clearProvidersAndSetDefault(defaultProvider: P): Promise<void>;
@@ -681,12 +723,29 @@ interface Client extends EvaluationLifeCycle<Client>, Features, ManageLogger<Cli
     readonly providerStatus: ProviderStatus;
 }
 
+/**
+ * A subset of events that can be directly emitted by providers.
+ */
+type ProviderEmittableEvents = Exclude<ClientProviderEvents, ClientProviderEvents.ContextChanged>;
+
+/**
+ * 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<ProviderEmittableEvents> {
+    protected readonly eventEmitter: EventEmitter;
+    constructor();
+}
+
 /**
  * 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.
  */
-declare abstract class InternalEventEmitter extends GenericEventEmitter<CommonEventDetails> {
+declare abstract class InternalEventEmitter extends GenericEventEmitter<ClientProviderEvents, CommonEventDetails> {
 }
 
 type Hook = BaseHook<FlagValue, void, void>;
@@ -746,18 +805,6 @@ declare class NoopFeatureProvider implements Provider {
 }
 declare const NOOP_PROVIDER: NoopFeatureProvider;
 
-/**
- * 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 {
-    protected readonly eventEmitter: EventEmitter;
-    constructor();
-}
-
 /**
  * Don't export types from this file publicly.
  * It might cause confusion since these types are not a part of the general API,
@@ -834,9 +881,9 @@ declare class OpenFeatureClient implements Client {
     constructor(providerAccessor: () => Provider, emitterAccessor: () => InternalEventEmitter, globalLogger: () => Logger, options: OpenFeatureClientOptions);
     get metadata(): ClientMetadata;
     get providerStatus(): ProviderStatus;
-    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>[];
+    addHandler(eventType: ClientProviderEvents, handler: EventHandler): void;
+    removeHandler(notificationType: ClientProviderEvents, handler: EventHandler): void;
+    getHandlers(eventType: ClientProviderEvents): EventHandler[];
     setLogger(logger: Logger): this;
     addHooks(...hooks: Hook[]): this;
     getHooks(): Hook[];
@@ -859,7 +906,7 @@ declare class OpenFeatureClient implements Client {
 }
 
 declare class OpenFeatureAPI extends OpenFeatureCommonAPI<Provider, Hook> implements ManageContext<Promise<void>> {
-    protected _events: OpenFeatureEventEmitter;
+    protected _events: GenericEventEmitter<ClientProviderEvents>;
     protected _defaultProvider: Provider;
     protected _createEventEmitter: () => OpenFeatureEventEmitter;
     protected _namedProviderContext: Map<string, EvaluationContext>;
@@ -940,4 +987,4 @@ declare class OpenFeatureAPI extends OpenFeatureCommonAPI<Provider, Hook> implem
  */
 declare const OpenFeature: OpenFeatureAPI;
 
-export { BaseHook, 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, GenericEventEmitter, Hook, HookContext, HookHints, InMemoryProvider, InvalidContextError, JsonArray, JsonObject, JsonValue, LOG_LEVELS, Logger, ManageContext, ManageLogger, Metadata, NOOP_PROVIDER, OpenFeature, OpenFeatureAPI, OpenFeatureClient, OpenFeatureCommonAPI, OpenFeatureError, OpenFeatureEventEmitter, Paradigm, ParseError, PrimitiveValue, Provider, ProviderEvents, ProviderMetadata, ProviderNotReadyError, ProviderStatus, ReadyEvent, ResolutionDetails, ResolutionReason, SafeLogger, StaleEvent, StandardResolutionReasons, TargetingKeyMissingError, TypeMismatchError, isObject, isString, objectOrUndefined, statusMatchesEvent, stringOrUndefined };
+export { ClientProviderEvents as AllProviderEvents, AnyProviderEvent, BaseHook, BeforeHookContext, Client, ClientMetadata, ClientProviderEvents, CommonEventDetails, CommonProvider, ConfigChangeEvent, DefaultLogger, ErrorCode, ErrorEvent, EvaluationContext, EvaluationContextValue, EvaluationDetails, EvaluationLifeCycle, EventContext, EventDetails, EventHandler, EventMetadata, Eventing, Features, FlagEvaluationOptions, FlagMetadata, FlagNotFoundError, FlagValue, FlagValueType, GeneralError, GenericEventEmitter, Hook, HookContext, HookHints, InMemoryProvider, InvalidContextError, JsonArray, JsonObject, JsonValue, LOG_LEVELS, Logger, ManageContext, ManageLogger, Metadata, NOOP_PROVIDER, OpenFeature, OpenFeatureAPI, OpenFeatureClient, OpenFeatureCommonAPI, OpenFeatureError, OpenFeatureEventEmitter, Paradigm, ParseError, PrimitiveValue, Provider, ProviderEmittableEvents, ClientProviderEvents as ProviderEvents, ProviderMetadata, ProviderNotReadyError, ProviderStatus, ReadyEvent, ResolutionDetails, ResolutionReason, SafeLogger, ServerProviderEvents, StaleEvent, StandardResolutionReasons, TargetingKeyMissingError, TypeMismatchError, isObject, isString, objectOrUndefined, statusMatchesEvent, stringOrUndefined };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfeature/web-sdk",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "OpenFeature SDK for Web",
   "main": "./dist/cjs/index.js",
   "files": [
@@ -46,9 +46,9 @@
   },
   "homepage": "https://github.com/open-feature/js-sdk#readme",
   "peerDependencies": {
-    "@openfeature/core": "0.0.20"
+    "@openfeature/core": "0.0.22"
   },
   "devDependencies": {
-    "@openfeature/core": "0.0.20"
+    "@openfeature/core": "0.0.22"
   }
 }