@openfeature/web-sdk 0.4.0 → 0.4.2

package/dist/types.d.ts

@@ -1,3 +1,133 @@
+type FlagValueType = 'boolean' | 'string' | 'number' | 'object';
+type PrimitiveValue = null | boolean | string | number;
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+type JsonArray = JsonValue[];
+/**
+ * Represents a JSON node value.
+ */
+type JsonValue = PrimitiveValue | JsonObject | JsonArray;
+/**
+ * Represents a JSON node value, or Date.
+ */
+type FlagValue = boolean | string | number | JsonValue;
+type ResolutionReason = keyof typeof StandardResolutionReasons | (string & Record<never, never>);
+/**
+ * A structure which supports definition of arbitrary properties, with keys of type string, and values of type boolean, string, or number.
+ *
+ * This structure is populated by a provider for use by an Application Author (via the Evaluation API) or an Application Integrator (via hooks).
+ */
+type FlagMetadata = Record<string, string | number | boolean>;
+type ResolutionDetails<U> = {
+    value: U;
+    variant?: string;
+    flagMetadata?: FlagMetadata;
+    reason?: ResolutionReason;
+    errorCode?: ErrorCode;
+    errorMessage?: string;
+};
+type EvaluationDetails<T extends FlagValue> = {
+    flagKey: string;
+    flagMetadata: Readonly<FlagMetadata>;
+} & ResolutionDetails<T>;
+declare const StandardResolutionReasons: {
+    /**
+     * The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting.
+     */
+    readonly TARGETING_MATCH: "TARGETING_MATCH";
+    /**
+     * The resolved value was the result of pseudorandom assignment.
+     */
+    readonly SPLIT: "SPLIT";
+    /**
+     * The resolved value was the result of the flag being disabled in the management system.
+     */
+    readonly DISABLED: "DISABLED";
+    /**
+     *  The resolved value was configured statically, or otherwise fell back to a pre-configured value.
+     */
+    readonly DEFAULT: "DEFAULT";
+    /**
+     * The reason for the resolved value could not be determined.
+     */
+    readonly UNKNOWN: "UNKNOWN";
+    /**
+     * The resolved value is static (no dynamic evaluation).
+     */
+    readonly STATIC: "STATIC";
+    /**
+     * The resolved value was retrieved from cache.
+     */
+    readonly CACHED: "CACHED";
+    /**
+     * The resolved value was the result of an error.
+     *
+     * Note: The `errorCode` and `errorMessage` fields may contain additional details of this error.
+     */
+    readonly ERROR: "ERROR";
+};
+declare enum ErrorCode {
+    /**
+     * The value was resolved before the provider was ready.
+     */
+    PROVIDER_NOT_READY = "PROVIDER_NOT_READY",
+    /**
+     * The flag could not be found.
+     */
+    FLAG_NOT_FOUND = "FLAG_NOT_FOUND",
+    /**
+     * An error was encountered parsing data, such as a flag configuration.
+     */
+    PARSE_ERROR = "PARSE_ERROR",
+    /**
+     * The type of the flag value does not match the expected type.
+     */
+    TYPE_MISMATCH = "TYPE_MISMATCH",
+    /**
+     * The provider requires a targeting key and one was not provided in the evaluation context.
+     */
+    TARGETING_KEY_MISSING = "TARGETING_KEY_MISSING",
+    /**
+     * The evaluation context does not meet provider requirements.
+     */
+    INVALID_CONTEXT = "INVALID_CONTEXT",
+    /**
+     * An error with an unspecified code.
+     */
+    GENERAL = "GENERAL"
+}
+
+type EvaluationContextValue = PrimitiveValue | Date | {
+    [key: string]: EvaluationContextValue;
+} | EvaluationContextValue[];
+/**
+ * A container for arbitrary contextual data that can be used as a basis for dynamic evaluation
+ */
+type EvaluationContext = {
+    /**
+     * A string uniquely identifying the subject (end-user, or client service) of a flag evaluation.
+     * Providers may require this field for fractional flag evaluation, rules, or overrides targeting specific users.
+     * Such providers may behave unpredictably if a targeting key is not specified at flag resolution.
+     */
+    targetingKey?: string;
+} & Record<string, EvaluationContextValue>;
+interface ManageContext<T> {
+    /**
+     * Access the evaluation context set on the receiver.
+     * @returns {EvaluationContext} Evaluation context
+     */
+    getContext(): EvaluationContext;
+    /**
+     * Sets evaluation context that will be used during flag evaluations
+     * on this receiver.
+     * @template T The type of the receiver
+     * @param {EvaluationContext} context Evaluation context
+     * @returns {T} The receiver (this object)
+     */
+    setContext(context: EvaluationContext): T;
+}
+
 declare enum ProviderEvents {
     /**
      * The provider is ready to evaluate flags.
@@ -17,10 +147,20 @@ declare enum ProviderEvents {
     Stale = "PROVIDER_STALE"
 }
 
+/**
+ * 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 {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;
+
 type EventMetadata = {
     [key: string]: string | boolean | number;
 };
 type CommonEventDetails = {
+    providerName: string;
     clientName?: string;
 };
 type CommonEventProps = {
@@ -136,135 +276,10 @@ declare class InternalEventEmitter extends GenericEventEmitter<CommonEventDetail
 interface Metadata {
 }
 
-type FlagValueType = 'boolean' | 'string' | 'number' | 'object';
-type PrimitiveValue = null | boolean | string | number;
-type JsonObject = {
-    [key: string]: JsonValue;
-};
-type JsonArray = JsonValue[];
-/**
- * Represents a JSON node value.
- */
-type JsonValue = PrimitiveValue | JsonObject | JsonArray;
 /**
- * Represents a JSON node value, or Date.
+ * Defines where the library is intended to be run.
  */
-type FlagValue = boolean | string | number | JsonValue;
-type ResolutionReason = keyof typeof StandardResolutionReasons | (string & Record<never, never>);
-/**
- * A structure which supports definition of arbitrary properties, with keys of type string, and values of type boolean, string, or number.
- *
- * This structure is populated by a provider for use by an Application Author (via the Evaluation API) or an Application Integrator (via hooks).
- */
-type FlagMetadata = Record<string, string | number | boolean>;
-type ResolutionDetails<U> = {
-    value: U;
-    variant?: string;
-    flagMetadata?: FlagMetadata;
-    reason?: ResolutionReason;
-    errorCode?: ErrorCode;
-    errorMessage?: string;
-};
-type EvaluationDetails<T extends FlagValue> = {
-    flagKey: string;
-    flagMetadata: Readonly<FlagMetadata>;
-} & ResolutionDetails<T>;
-declare const StandardResolutionReasons: {
-    /**
-     * The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting.
-     */
-    readonly TARGETING_MATCH: "TARGETING_MATCH";
-    /**
-     * The resolved value was the result of pseudorandom assignment.
-     */
-    readonly SPLIT: "SPLIT";
-    /**
-     * The resolved value was the result of the flag being disabled in the management system.
-     */
-    readonly DISABLED: "DISABLED";
-    /**
-     *  The resolved value was configured statically, or otherwise fell back to a pre-configured value.
-     */
-    readonly DEFAULT: "DEFAULT";
-    /**
-     * The reason for the resolved value could not be determined.
-     */
-    readonly UNKNOWN: "UNKNOWN";
-    /**
-     * The resolved value is static (no dynamic evaluation).
-     */
-    readonly STATIC: "STATIC";
-    /**
-     * The resolved value was retrieved from cache.
-     */
-    readonly CACHED: "CACHED";
-    /**
-     * The resolved value was the result of an error.
-     *
-     * Note: The `errorCode` and `errorMessage` fields may contain additional details of this error.
-     */
-    readonly ERROR: "ERROR";
-};
-declare enum ErrorCode {
-    /**
-     * The value was resolved before the provider was ready.
-     */
-    PROVIDER_NOT_READY = "PROVIDER_NOT_READY",
-    /**
-     * The flag could not be found.
-     */
-    FLAG_NOT_FOUND = "FLAG_NOT_FOUND",
-    /**
-     * An error was encountered parsing data, such as a flag configuration.
-     */
-    PARSE_ERROR = "PARSE_ERROR",
-    /**
-     * The type of the flag value does not match the expected type.
-     */
-    TYPE_MISMATCH = "TYPE_MISMATCH",
-    /**
-     * The provider requires a targeting key and one was not provided in the evaluation context.
-     */
-    TARGETING_KEY_MISSING = "TARGETING_KEY_MISSING",
-    /**
-     * The evaluation context does not meet provider requirements.
-     */
-    INVALID_CONTEXT = "INVALID_CONTEXT",
-    /**
-     * An error with an unspecified code.
-     */
-    GENERAL = "GENERAL"
-}
-
-type EvaluationContextValue = PrimitiveValue | Date | {
-    [key: string]: EvaluationContextValue;
-} | EvaluationContextValue[];
-/**
- * A container for arbitrary contextual data that can be used as a basis for dynamic evaluation
- */
-type EvaluationContext = {
-    /**
-     * A string uniquely identifying the subject (end-user, or client service) of a flag evaluation.
-     * Providers may require this field for fractional flag evaluation, rules, or overrides targeting specific users.
-     * Such providers may behave unpredictably if a targeting key is not specified at flag resolution.
-     */
-    targetingKey?: string;
-} & Record<string, EvaluationContextValue>;
-interface ManageContext<T> {
-    /**
-     * Access the evaluation context set on the receiver.
-     * @returns {EvaluationContext} Evaluation context
-     */
-    getContext(): EvaluationContext;
-    /**
-     * Sets evaluation context that will be used during flag evaluations
-     * on this receiver.
-     * @template T The type of the receiver
-     * @param {EvaluationContext} context Evaluation context
-     * @returns {T} The receiver (this object)
-     */
-    setContext(context: EvaluationContext): T;
-}
+type Paradigm = 'server' | 'client';
 
 /**
  * The state of the provider.
@@ -281,7 +296,11 @@ declare enum ProviderStatus {
     /**
      * The provider is in an error state and unable to evaluate flags.
      */
-    ERROR = "ERROR"
+    ERROR = "ERROR",
+    /**
+     * The provider's cached state is no longer valid and may not be up-to-date with the source of truth.
+     */
+    STALE = "STALE"
 }
 /**
  * Static data about the provider.
@@ -291,6 +310,11 @@ interface ProviderMetadata extends Metadata {
 }
 interface CommonProvider {
     readonly metadata: ProviderMetadata;
+    /**
+     * Represents where the provider is intended to be run. If defined,
+     * the SDK will enforce that the defined paradigm at runtime.
+     */
+    readonly runsOn?: Paradigm;
     /**
      * Returns a representation of the current readiness of the provider.
      * If the provider needs to be initialized, it should return {@link ProviderStatus.READY}.
@@ -432,58 +456,6 @@ declare class InvalidContextError extends OpenFeatureError {
     constructor(message?: string);
 }
 
-/**
- * Transaction context is a mechanism for adding transaction specific context that
- * is merged with evaluation context prior to flag evaluation. Examples of potential
- * transaction specific context include: a user id, user agent, or request path.
- */
-type TransactionContext = EvaluationContext;
-interface ManageTransactionContextPropagator<T> extends TransactionContextPropagator {
-    /**
-     * EXPERIMENTAL: Transaction context propagation is experimental and subject to change.
-     * The OpenFeature Enhancement Proposal regarding transaction context can be found [here](https://github.com/open-feature/ofep/pull/32).
-     *
-     * Sets a transaction context propagator on this receiver. The transaction context
-     * propagator is responsible for persisting context for the duration of a single
-     * transaction.
-     * @experimental
-     * @template T The type of the receiver
-     * @param {TransactionContextPropagator} transactionContextPropagator The context propagator to be used
-     * @returns {T} The receiver (this object)
-     */
-    setTransactionContextPropagator(transactionContextPropagator: TransactionContextPropagator): T;
-}
-interface TransactionContextPropagator {
-    /**
-     * EXPERIMENTAL: Transaction context propagation is experimental and subject to change.
-     * The OpenFeature Enhancement Proposal regarding transaction context can be found [here](https://github.com/open-feature/ofep/pull/32).
-     *
-     * Returns the currently defined transaction context using the registered transaction
-     * context propagator.
-     * @experimental
-     * @returns {TransactionContext} The current transaction context
-     */
-    getTransactionContext(): TransactionContext;
-    /**
-     * EXPERIMENTAL: Transaction context propagation is experimental and subject to change.
-     * The OpenFeature Enhancement Proposal regarding transaction context can be found [here](https://github.com/open-feature/ofep/pull/32).
-     *
-     * Sets the transaction context using the registered transaction context propagator.
-     * @experimental
-     * @template R The return value of the callback
-     * @param {TransactionContext} transactionContext The transaction specific context
-     * @param {(...args: unknown[]) => R} callback Callback function used to set the transaction context on the stack
-     * @param {...unknown[]} args Optional arguments that are passed to the callback function
-     */
-    setTransactionContext<R>(transactionContext: TransactionContext, callback: (...args: unknown[]) => R, ...args: unknown[]): void;
-}
-
-declare class NoopTransactionContextPropagator implements TransactionContextPropagator {
-    getTransactionContext(): EvaluationContext;
-    setTransactionContext(_: EvaluationContext, callback: () => void): void;
-}
-declare const NOOP_TRANSACTION_CONTEXT_PROPAGATOR: NoopTransactionContextPropagator;
-
 /**
  * Checks whether the parameter is a string.
  * @param {unknown} value The value to check
@@ -509,9 +481,8 @@ 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> implements Eventing, EvaluationLifeCycle<OpenFeatureCommonAPI<P>>, ManageLogger<OpenFeatureCommonAPI<P>>, ManageTransactionContextPropagator<OpenFeatureCommonAPI<P>> {
+declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonProvider> implements Eventing, EvaluationLifeCycle<OpenFeatureCommonAPI<P>>, ManageLogger<OpenFeatureCommonAPI<P>> {
     protected _hooks: Hook[];
-    protected _transactionContextPropagator: TransactionContextPropagator;
     protected _context: EvaluationContext;
     protected _logger: Logger;
     protected abstract _defaultProvider: P;
@@ -519,6 +490,8 @@ declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonPro
     private readonly _clientEventHandlers;
     protected _clientProviders: Map<string, P>;
     protected _clientEvents: Map<string | undefined, InternalEventEmitter>;
+    protected _runsOn: Paradigm;
+    constructor(category: Paradigm);
     addHooks(...hooks: Hook<FlagValue>[]): this;
     getHooks(): Hook<FlagValue>[];
     clearHooks(): this;
@@ -531,7 +504,7 @@ declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonPro
     /**
      * Adds a handler for the given provider event type.
      * The handlers are called in the order they have been added.
-     * When changing the provider, the currently attached handlers will listen to the events of the new provider.
+     * API (global) events run for all providers.
      * @param {ProviderEvents} eventType The provider event type to listen to
      * @param {EventHandler} handler The handler to run on occurrence of the event type
      */
@@ -548,13 +521,34 @@ declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonPro
      * @returns {EventHandler[]} The handlers currently attached to the given provider event type
      */
     getHandlers<T extends ProviderEvents>(eventType: T): EventHandler<T>[];
+    /**
+     * 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.
+     * Setting a provider supersedes the current provider used in new and existing clients without a name.
+     * @template P
+     * @param {P} provider The provider responsible for flag evaluations.
+     * @returns {Promise<void>}
+     * @throws Uncaught exceptions thrown by the provider during initialization.
+     */
+    setProviderAndWait(provider: P): Promise<void>;
+    /**
+     * Sets the provider that OpenFeature will use for flag evaluations of providers with the given name.
+     * A promise is returned that resolves when the provider is ready.
+     * Setting a provider supersedes the current provider used in new and existing clients with that name.
+     * @template P
+     * @param {string} clientName The name to identify the client
+     * @param {P} provider The provider responsible for flag evaluations.
+     * @returns {Promise<void>}
+     * @throws Uncaught exceptions thrown by the provider during initialization.
+     */
+    setProviderAndWait(clientName: string, provider: P): Promise<void>;
     /**
      * Sets the default provider for flag evaluations.
      * This provider will be used by unnamed clients and named clients to which no provider is bound.
      * Setting a provider supersedes the current provider used in new and existing clients without a name.
      * @template P
      * @param {P} provider The provider responsible for flag evaluations.
-     * @returns {OpenFeatureCommonAPI} OpenFeature API
+     * @returns {this} OpenFeature API
      */
     setProvider(provider: P): this;
     /**
@@ -566,16 +560,15 @@ declare abstract class OpenFeatureCommonAPI<P extends CommonProvider = CommonPro
      * @returns {this} OpenFeature API
      */
     setProvider(clientName: string, provider: P): this;
+    private setAwaitableProvider;
     protected getProviderForClient(name?: string): P;
     protected buildAndCacheEventEmitterForClient(name?: string): InternalEventEmitter;
     private getUnboundEmitters;
     private getAssociatedEventEmitters;
     private transferListeners;
     close(): Promise<void>;
+    protected clearProvidersAndSetDefault(defaultProvider: P): Promise<void>;
     private handleShutdownError;
-    setTransactionContextPropagator(transactionContextPropagator: TransactionContextPropagator): OpenFeatureCommonAPI<P>;
-    setTransactionContext<R>(transactionContext: TransactionContext, callback: (...args: unknown[]) => R, ...args: unknown[]): void;
-    getTransactionContext(): TransactionContext;
 }
 
 interface FlagEvaluationOptions {
@@ -780,6 +773,11 @@ declare class OpenFeatureAPI extends OpenFeatureCommonAPI<Provider> implements M
      * @returns {Client} OpenFeature Client
      */
     getClient(name?: string, version?: string): Client;
+    /**
+     * Clears all registered providers and resets the default provider.
+     * @returns {Promise<void>}
+     */
+    clearProviders(): Promise<void>;
 }
 /**
  * A singleton instance of the OpenFeature API.
@@ -787,4 +785,4 @@ declare class OpenFeatureAPI extends OpenFeatureCommonAPI<Provider> implements M
  */
 declare const OpenFeature: OpenFeatureAPI;
 
-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 };
+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, Metadata, NOOP_PROVIDER, OpenFeature, OpenFeatureAPI, OpenFeatureClient, OpenFeatureCommonAPI, OpenFeatureError, OpenFeatureEventEmitter, Paradigm, ParseError, PrimitiveValue, Provider, ProviderEvents, ProviderMetadata, ProviderStatus, ReadyEvent, ResolutionDetails, ResolutionReason, SafeLogger, StaleEvent, StandardResolutionReasons, TargetingKeyMissingError, TypeMismatchError, isObject, isString, objectOrUndefined, statusMatchesEvent, stringOrUndefined };

package/package.json

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