@openfeature/web-sdk 0.4.11 → 0.4.13

package/README.md

@@ -16,8 +16,8 @@
     <img alt="Specification" src="https://img.shields.io/static/v1?label=specification&message=v0.7.0&color=yellow&style=for-the-badge" />
   </a>
   <!-- x-release-please-start-version -->
-  <a href="https://github.com/open-feature/js-sdk/releases/tag/web-sdk-v0.4.11">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.4.11&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/web-sdk-v0.4.13">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.4.13&color=blue&style=for-the-badge" />
   </a>
   <!-- x-release-please-end -->
   <br/>
@@ -89,16 +89,16 @@ See [here](https://open-feature.github.io/js-sdk/modules/_openfeature_web_sdk.ht
 
 ## 🌟 Features
 
-| Status | Features                        | Description                                                                                                                        |
-| ------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| ✅      | [Providers](#providers)         | Integrate with a commercial, open source, or in-house feature management tool.                                                     |
-| ✅      | [Targeting](#targeting-and-context)         | Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context). |
-| ✅      | [Hooks](#hooks)                 | Add functionality to various stages of the flag evaluation life-cycle.                                                             |
-| ✅      | [Logging](#logging)             | Integrate with popular logging packages.                                                                                           |
-| ✅      | [Named clients](#named-clients) | Utilize multiple providers in a single application.                                                                                |
-| ✅      | [Eventing](#eventing)           | React to state changes in the provider or flag management system.                                                                  |
-| ✅      | [Shutdown](#shutdown)           | Gracefully clean up a provider during application shutdown.                                                                        |
-| ✅      | [Extending](#extending)         | Extend OpenFeature with custom providers and hooks.                                                                                |
+| Status | Features                            | Description                                                                                                                        |
+| ------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| ✅      | [Providers](#providers)             | Integrate with a commercial, open source, or in-house feature management tool.                                                     |
+| ✅      | [Targeting](#targeting-and-context) | Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context). |
+| ✅      | [Hooks](#hooks)                     | Add functionality to various stages of the flag evaluation life-cycle.                                                             |
+| ✅      | [Logging](#logging)                 | Integrate with popular logging packages.                                                                                           |
+| ✅      | [Domains](#domains)                 | Logically bind clients with providers.                                                                                             |
+| ✅      | [Eventing](#eventing)               | React to state changes in the provider or flag management system.                                                                  |
+| ✅      | [Shutdown](#shutdown)               | Gracefully clean up a provider during application shutdown.                                                                        |
+| ✅      | [Extending](#extending)             | Extend OpenFeature with custom providers and hooks.                                                                                |
 
 <sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>
 
@@ -129,7 +129,7 @@ OpenFeature.setProvider(new MyProvider());
 Once the provider has been registered, the status can be tracked using [events](#eventing).
 
 In some situations, it may be beneficial to register multiple providers in the same application.
-This is possible using [named clients](#named-clients), which is covered in more detail below.
+This is possible using [domains](#domains), which is covered in more detail below.
 
 ### Flag evaluation flow
 
@@ -159,12 +159,13 @@ await OpenFeature.setContext({ origin: document.location.host });
 ```
 
 Context is global and setting it is `async`.
-Providers may implement an `onContextChanged` method that receives the old context and the newer one.
-This method is used internally by the provider to detect if, given the context change, the flags values cached on client side are invalid. If needed a request will be made to the provider with the new context in order to get the correct flags values.
+Providers may implement an `onContextChanged` method that receives the old and newer contexts.
+Given a context change, providers can use this method internally to detect if the flag values cached on the client are still valid.
+If needed, a request will be made to the provider with the new context in order to get the correct flag values.
 
 ### Hooks
 
-[Hooks](https://openfeature.dev/docs/reference/concepts/hooks) allow for custom logic to be added at well-defined points of the flag evaluation life-cycle
+[Hooks](https://openfeature.dev/docs/reference/concepts/hooks) allow for custom logic to be added at well-defined points of the flag evaluation life-cycle.
 Look [here](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Hook&instant_search%5BrefinementList%5D%5Bcategory%5D%5B0%5D=Client-side&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=JavaScript) for a complete list of available hooks.
 If the hook you're looking for hasn't been created yet, see the [develop a hook](#develop-a-hook) section to learn how to build it yourself.
 
@@ -186,7 +187,7 @@ const boolValue = client.getBooleanValue("bool-flag", false, { hooks: [new Examp
 
 ### Logging
 
-The JS SDK will log warnings and errors to the console by default.
+The Web SDK will log warnings and errors to the console by default.
 This behavior can be overridden by passing a custom logger either globally or per client.
 A custom logger must implement the [Logger interface](../shared/src/logger/logger.ts).
 
@@ -204,26 +205,29 @@ const client = OpenFeature.getClient();
 client.setLogger(logger);
 ```
 
-### Named clients
+### Domains
 
-Clients can be given a name.
-A name is a logical identifier that can be used to associate clients with a particular provider.
-If a name has no associated provider, the global provider is used.
+Clients can be assigned to a domain.
+A domain is a logical identifier which can be used to associate clients with a particular provider.
+If a domain has no associated provider, the default provider is used.
 
 ```ts
-import { OpenFeature } from "@openfeature/web-sdk";
+import { OpenFeature, InMemoryProvider } from "@openfeature/web-sdk";
 
 // Registering the default provider
-OpenFeature.setProvider(NewLocalProvider());
-// Registering a named provider
-OpenFeature.setProvider("clientForCache", new NewCachedProvider());
+OpenFeature.setProvider(InMemoryProvider(myFlags));
+// Registering a provider to a domain
+OpenFeature.setProvider("my-domain", new InMemoryProvider(someOtherFlags));
 
-// A Client backed by default provider
+// A Client bound to the default provider
 const clientWithDefault = OpenFeature.getClient();
-// A Client backed by NewCachedProvider
-const clientForCache = OpenFeature.getClient("clientForCache");
+// A Client bound to the InMemoryProvider provider
+const domainScopedClient = OpenFeature.getClient("my-domain");
 ```
 
+Domains can be defined on a provider during registration.
+For more details, please refer to the [providers](#providers) section.
+
 ### Eventing
 
 Events allow you to react to state changes in the provider or underlying flag management system, such as flag definition changes, provider readiness, or error conditions.
@@ -267,43 +271,52 @@ This can be a new repository or included in [the existing contrib repository](ht
 You’ll then need to write the provider by implementing the [Provider interface](./src/provider/provider.ts) exported by the OpenFeature SDK.
 
 ```ts
-import { JsonValue, Provider, ResolutionDetails } from '@openfeature/web-sdk';
+import {
+  AnyProviderEvent,
+  EvaluationContext,
+  Hook,
+  JsonValue,
+  Logger,
+  Provider,
+  ProviderEventEmitter,
+  ProviderStatus,
+  ResolutionDetails
+} from '@openfeature/web-sdk';
 
 // implement the provider interface
 class MyProvider implements Provider {
   // Adds runtime validation that the provider is used with the expected SDK
   public readonly runsOn = 'client';
-
   readonly metadata = {
     name: 'My Provider',
   } as const;
-
   // Optional provider managed hooks
-  hooks?: Hook<FlagValue>[];
-
+  hooks?: Hook[];
   resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context: EvaluationContext, logger: Logger): ResolutionDetails<boolean> {
     // code to evaluate a boolean
   }
-
   resolveStringEvaluation(flagKey: string, defaultValue: string, context: EvaluationContext, logger: Logger): ResolutionDetails<string> {
     // code to evaluate a string
   }
-
   resolveNumberEvaluation(flagKey: string, defaultValue: number, context: EvaluationContext, logger: Logger): ResolutionDetails<number> {
     // code to evaluate a number
   }
-
   resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T, context: EvaluationContext, logger: Logger): ResolutionDetails<T> {
     // code to evaluate an object
   }
 
+  onContextChange?(oldContext: EvaluationContext, newContext: EvaluationContext): Promise<void> {
+    // reconcile the provider's cached flags, if applicable
+  }
+
   status?: ProviderStatus | undefined;
-  events?: OpenFeatureEventEmitter | undefined;
+
+  // implement with "new OpenFeatureEventEmitter()", and use "emit()" to emit events
+  events?: ProviderEventEmitter<AnyProviderEvent> | undefined; 
 
   initialize?(context?: EvaluationContext | undefined): Promise<void> {
     // code to initialize your provider
   }
-
   onClose?(): Promise<void> {
     // code to shut down your provider
   }

package/dist/cjs/index.js

@@ -474,11 +474,11 @@ var import_core5 = require("@openfeature/core");
 
 // src/provider/in-memory-provider/variant-not-found-error.ts
 var import_core4 = require("@openfeature/core");
-var VariantNotFoundError = class extends import_core4.OpenFeatureError {
+var VariantNotFoundError = class _VariantNotFoundError extends import_core4.OpenFeatureError {
   code;
   constructor(message) {
     super(message);
-    Object.setPrototypeOf(this, VariantNotFoundError.prototype);
+    Object.setPrototypeOf(this, _VariantNotFoundError.prototype);
     this.name = "VariantNotFoundError";
     this.code = import_core4.ErrorCode.GENERAL;
   }
@@ -588,11 +588,10 @@ var InMemoryProvider = class {
 // src/open-feature.ts
 var GLOBAL_OPENFEATURE_API_KEY = Symbol.for("@openfeature/web-sdk/api");
 var _globalThis = globalThis;
-var OpenFeatureAPI = class extends import_core6.OpenFeatureCommonAPI {
+var OpenFeatureAPI = class _OpenFeatureAPI extends import_core6.OpenFeatureCommonAPI {
   _events = new OpenFeatureEventEmitter();
   _defaultProvider = NOOP_PROVIDER;
   _createEventEmitter = () => new OpenFeatureEventEmitter();
-  _namedProviderContext = /* @__PURE__ */ new Map();
   constructor() {
     super("client");
   }
@@ -606,64 +605,64 @@ var OpenFeatureAPI = class extends import_core6.OpenFeatureCommonAPI {
     if (globalApi) {
       return globalApi;
     }
-    const instance = new OpenFeatureAPI();
+    const instance = new _OpenFeatureAPI();
     _globalThis[GLOBAL_OPENFEATURE_API_KEY] = instance;
     return instance;
   }
-  async setContext(nameOrContext, contextOrUndefined) {
-    const clientName = (0, import_core6.stringOrUndefined)(nameOrContext);
-    const context = (0, import_core6.objectOrUndefined)(nameOrContext) ?? (0, import_core6.objectOrUndefined)(contextOrUndefined) ?? {};
-    if (clientName) {
-      const provider = this._clientProviders.get(clientName);
+  async setContext(domainOrContext, contextOrUndefined) {
+    const domain = (0, import_core6.stringOrUndefined)(domainOrContext);
+    const context = (0, import_core6.objectOrUndefined)(domainOrContext) ?? (0, import_core6.objectOrUndefined)(contextOrUndefined) ?? {};
+    if (domain) {
+      const provider = this._domainScopedProviders.get(domain);
       if (provider) {
-        const oldContext = this.getContext(clientName);
-        this._namedProviderContext.set(clientName, context);
-        await this.runProviderContextChangeHandler(clientName, provider, oldContext, context);
+        const oldContext = this.getContext(domain);
+        this._domainScopedContext.set(domain, context);
+        await this.runProviderContextChangeHandler(domain, provider, oldContext, context);
       } else {
-        this._namedProviderContext.set(clientName, context);
+        this._domainScopedContext.set(domain, context);
       }
     } else {
       const oldContext = this._context;
       this._context = context;
-      const defaultContextNameProviders = Array.from(this._clientProviders.entries()).filter(([name]) => !this._namedProviderContext.has(name)).reduce((acc, [name, provider]) => {
-        acc.push({ name, provider });
+      const unboundProviders = Array.from(this._domainScopedProviders.entries()).filter(([domain2]) => !this._domainScopedContext.has(domain2)).reduce((acc, [domain2, provider]) => {
+        acc.push({ domain: domain2, provider });
         return acc;
       }, []);
       const allProviders = [
-        // add in the default (no name)
-        { name: void 0, provider: this._defaultProvider },
-        ...defaultContextNameProviders
+        // add in the default (no domain)
+        { domain: void 0, provider: this._defaultProvider },
+        ...unboundProviders
       ];
       await Promise.all(
         allProviders.map(
-          (tuple) => this.runProviderContextChangeHandler(tuple.name, tuple.provider, oldContext, context)
+          (tuple) => this.runProviderContextChangeHandler(tuple.domain, tuple.provider, oldContext, context)
         )
       );
     }
   }
-  getContext(nameOrUndefined) {
-    const clientName = (0, import_core6.stringOrUndefined)(nameOrUndefined);
-    if (clientName) {
-      const context = this._namedProviderContext.get(clientName);
+  getContext(domainOrUndefined) {
+    const domain = (0, import_core6.stringOrUndefined)(domainOrUndefined);
+    if (domain) {
+      const context = this._domainScopedContext.get(domain);
       if (context) {
         return context;
       } else {
-        this._logger.debug(`Unable to find context for '${clientName}'.`);
+        this._logger.debug(`Unable to find context for '${domain}'.`);
       }
     }
     return this._context;
   }
-  async clearContext(nameOrUndefined) {
-    const clientName = (0, import_core6.stringOrUndefined)(nameOrUndefined);
-    if (clientName) {
-      const provider = this._clientProviders.get(clientName);
+  async clearContext(domainOrUndefined) {
+    const domain = (0, import_core6.stringOrUndefined)(domainOrUndefined);
+    if (domain) {
+      const provider = this._domainScopedProviders.get(domain);
       if (provider) {
-        const oldContext = this.getContext(clientName);
-        this._namedProviderContext.delete(clientName);
+        const oldContext = this.getContext(domain);
+        this._domainScopedContext.delete(domain);
         const newContext = this.getContext();
-        await this.runProviderContextChangeHandler(clientName, provider, oldContext, newContext);
+        await this.runProviderContextChangeHandler(domain, provider, oldContext, newContext);
       } else {
-        this._namedProviderContext.delete(clientName);
+        this._domainScopedContext.delete(domain);
       }
     } else {
       return this.setContext({});
@@ -671,11 +670,11 @@ var OpenFeatureAPI = class extends import_core6.OpenFeatureCommonAPI {
   }
   /**
    * Resets the global evaluation context and removes the evaluation context for
-   * all named clients.
+   * all domains.
    */
   async clearContexts() {
     await this.clearContext();
-    await Promise.allSettled(Array.from(this._clientProviders.keys()).map((name) => this.clearContext(name)));
+    await Promise.allSettled(Array.from(this._domainScopedProviders.keys()).map((domain) => this.clearContext(domain)));
   }
   /**
    * A factory function for creating new named OpenFeature clients. Clients can contain
@@ -684,18 +683,18 @@ var OpenFeatureAPI = class extends import_core6.OpenFeatureCommonAPI {
    *
    * If there is already a provider bound to this name via {@link this.setProvider setProvider}, this provider will be used.
    * Otherwise, the default provider is used until a provider is assigned to that name.
-   * @param {string} name The name of the client
+   * @param {string} domain An identifier which logically binds clients with providers
    * @param {string} version The version of the client (only used for metadata)
    * @returns {Client} OpenFeature Client
    */
-  getClient(name, version) {
+  getClient(domain, version) {
     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.getProviderForClient(name),
-      () => this.buildAndCacheEventEmitterForClient(name),
+      () => this.getProviderForClient(domain),
+      () => this.buildAndCacheEventEmitterForClient(domain),
       () => this._logger,
-      { name, version }
+      { domain, version }
     );
   }
   /**
@@ -704,24 +703,24 @@ var OpenFeatureAPI = class extends import_core6.OpenFeatureCommonAPI {
    */
   async clearProviders() {
     await super.clearProvidersAndSetDefault(NOOP_PROVIDER);
-    this._namedProviderContext.clear();
+    this._domainScopedContext.clear();
   }
-  async runProviderContextChangeHandler(clientName, provider, oldContext, newContext) {
+  async runProviderContextChangeHandler(domain, provider, oldContext, newContext) {
     const providerName = provider.metadata.name;
     try {
       await provider.onContextChange?.(oldContext, newContext);
-      this.getAssociatedEventEmitters(clientName).forEach((emitter) => {
-        emitter?.emit(import_core2.ClientProviderEvents.ContextChanged, { clientName, providerName });
+      this.getAssociatedEventEmitters(domain).forEach((emitter) => {
+        emitter?.emit(import_core2.ClientProviderEvents.ContextChanged, { clientName: domain, domain, providerName });
       });
-      this._events?.emit(import_core2.ClientProviderEvents.ContextChanged, { clientName, providerName });
+      this._events?.emit(import_core2.ClientProviderEvents.ContextChanged, { clientName: domain, domain, providerName });
     } catch (err) {
       const error = err;
       const message = `Error running ${provider?.metadata?.name}'s context change handler: ${error?.message}`;
       this._logger?.error(`${message}`, err);
-      this.getAssociatedEventEmitters(clientName).forEach((emitter) => {
-        emitter?.emit(import_core2.ClientProviderEvents.Error, { clientName, providerName, message });
+      this.getAssociatedEventEmitters(domain).forEach((emitter) => {
+        emitter?.emit(import_core2.ClientProviderEvents.Error, { clientName: domain, domain, providerName, message });
       });
-      this._events?.emit(import_core2.ClientProviderEvents.Error, { clientName, providerName, message });
+      this._events?.emit(import_core2.ClientProviderEvents.Error, { clientName: domain, domain, providerName, message });
     }
   }
 };
@@ -739,7 +738,9 @@ var OpenFeatureClient = class {
   _clientLogger;
   get metadata() {
     return {
-      name: this.options.name,
+      // Use domain if name is not provided
+      name: this.options.domain ?? this.options.name,
+      domain: this.options.domain ?? this.options.name,
       version: this.options.version,
       providerMetadata: this.providerAccessor().metadata
     };
@@ -752,7 +753,11 @@ var OpenFeatureClient = class {
     const shouldRunNow = (0, import_core7.statusMatchesEvent)(eventType, this._provider.status);
     if (shouldRunNow) {
       try {
-        handler({ clientName: this.metadata.name, providerName: this._provider.metadata.name });
+        handler({
+          clientName: this.metadata.name,
+          domain: this.metadata.domain,
+          providerName: this._provider.metadata.name
+        });
       } catch (err) {
         this._logger?.error("Error running event handler:", err);
       }
@@ -826,7 +831,7 @@ var OpenFeatureClient = class {
     ];
     const allHooksReversed = [...allHooks].reverse();
     const context = {
-      ...OpenFeature.getContext(this?.options?.name)
+      ...OpenFeature.getContext(this?.options?.domain)
     };
     const hookContext = {
       flagKey,