@openfeature/web-sdk 0.4.2 → 0.4.4

package/README.md

@@ -12,19 +12,19 @@
 <!-- x-hide-in-docs-end -->
 <!-- The 'github-badges' class is used in the docs -->
 <p align="center" class="github-badges">
-  <a href="https://github.com/open-feature/spec/tree/v0.7.0">
+  <a href="https://github.com/open-feature/spec/releases/tag/v0.7.0">
     <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.2">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.4.2&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/web-sdk-v0.4.4">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.4.4&color=blue&style=for-the-badge" />
   </a>
   <!-- x-release-please-end -->
   <br/>
   <a href="https://www.repostatus.org/#wip">
     <img alt="Project Status" src="https://www.repostatus.org/badges/latest/wip.svg" />
   </a>
-  <a href="https://open-feature.github.io/js-sdk/modules/OpenFeature_Web_SDK.html">
+  <a href="https://open-feature.github.io/js-sdk/modules/_openfeature_web_sdk.html">
     <img alt="API Reference" src="https://img.shields.io/badge/reference-teal?logo=javascript&logoColor=white" />
   </a>
   <a href="https://www.npmjs.com/package/@openfeature/web-sdk">
@@ -39,7 +39,7 @@
 </p>
 <!-- x-hide-in-docs-start -->
 
-[OpenFeature](https://openfeature.dev) is an open standard that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool.
+[OpenFeature](https://openfeature.dev) is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool.
 
 <!-- x-hide-in-docs-end -->
 
@@ -60,7 +60,8 @@ npm install --save @openfeature/web-sdk
 #### yarn
 
 ```sh
-yarn add @openfeature/web-sdk
+# yarn requires manual installation of the @openfeature/core peer-dependency
+yarn add @openfeature/web-sdk @openfeature/core
 ```
 
 ### Usage
@@ -69,7 +70,7 @@ yarn add @openfeature/web-sdk
 import { OpenFeature } from '@openfeature/web-sdk';
 
 // Register your feature flag provider
-OpenFeature.setProvider(new YourProviderOfChoice());
+await OpenFeature.setProviderAndWait(new YourProviderOfChoice());
 
 // create a new client
 const client = OpenFeature.getClient();
@@ -84,7 +85,7 @@ if (v2Enabled) {
 
 ### API Reference
 
-See [here](https://open-feature.github.io/js-sdk/modules/OpenFeature_Web_SDK.html) for the complete API documentation.
+See [here](https://open-feature.github.io/js-sdk/modules/_openfeature_web_sdk.html) for the complete API documentation.
 
 ## 🌟 Features
 
@@ -109,10 +110,24 @@ If the provider you're looking for hasn't been created yet, see the [develop a p
 
 Once you've added a provider as a dependency, it can be registered with OpenFeature like this:
 
+#### Awaitable
+
+To register a provider and ensure it is ready before further actions are taken, you can use the `setProviderAndWait` method as shown below:
+
+```ts
+await OpenFeature.setProviderAndWait(new MyProvider());
+```  
+
+#### Synchronous
+
+To register a provider in a synchronous manner, you can use the `setProvider` method as shown below:
+
 ```ts
-OpenFeature.setProvider(new MyProvider())
+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.
 
@@ -130,22 +145,7 @@ sequenceDiagram
 In (1) the Client sends a request to the provider backend in order to get all values from all feature flags that it has.
 Once the provider backend replies (2) the client holds all flag values and therefore the flag evaluation process is synchronous.
 
-In order to prevent flag evaluation to the default value while flags are still being fetched, it is highly recommended to only look for flag value after the provider has emitted the `Ready` event.
-The following code snippet provides an example.
-
-```ts
-import { OpenFeature, ProviderEvents } from '@openfeature/web-sdk';
-
-OpenFeature.setProvider( /*set a provider*/ );
-
-// OpenFeature API
-OpenFeature.addHandler(ProviderEvents.Ready, () => {
-  const client = OpenFeature.getClient();
-  const stringFlag = client.getStringValue('string-flag', "default value"))
-
-  //use stringFlag from this point
-});
-```
+In order to prevent flag evaluations from defaulting while the provider is initializing, it is highly recommended to evaluate flags only after the provider is ready. This can be done using the `setProviderAndWait` method or using the `setProvider` method and listening for the `READY` [event](#eventing).
 
 ### Targeting and Context
 
@@ -237,13 +237,13 @@ import { OpenFeature, ProviderEvents } from '@openfeature/web-sdk';
 
 // OpenFeature API
 OpenFeature.addHandler(ProviderEvents.Ready, (eventDetails) => {
-  console.log(`Ready event from: ${eventDetails?.clientName}:`, eventDetails);
+  console.log(`Ready event from: ${eventDetails?.providerName}:`, eventDetails);
 });
 
 // Specific client
 const client = OpenFeature.getClient();
 client.addHandler(ProviderEvents.Error, (eventDetails) => {
-  console.log(`Error event from: ${eventDetails?.clientName}:`, eventDetails);
+  console.log(`Error event from: ${eventDetails?.providerName}:`, eventDetails);
 });
 ```
 
@@ -271,6 +271,8 @@ import { JsonValue, Provider, 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',