fix: add setProviderAndWait examples (#614)

## This PR - adds `setProviderAndWait` example on the server readme - adds `setProviderAndWait` example on the client readme - fixed invalid link on the server readme ### Related Issues Fixes #613 ### Notes The React SDK wasn't updated in this PR. Signed-off-by: Michael Beemer <[email protected]> --------- Signed-off-by: Michael Beemer <[email protected]> Signed-off-by: Todd Baert <[email protected]> Co-authored-by: Todd Baert <[email protected]>
open-feature · Nov 3, 2023 · 6b3a4e3 · 6b3a4e3
1 parent cb7d2be
commit 6b3a4e3
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 24 deletions.
diff --git a/packages/client/README.md b/packages/client/README.md
@@ -70,7 +70,7 @@ yarn add @openfeature/web-sdk @openfeature/core
 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();
@@ -110,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.
 
@@ -131,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
 
@@ -238,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);
 });
 ```
 
@@ -272,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',

diff --git a/packages/server/README.md b/packages/server/README.md
@@ -67,7 +67,7 @@ yarn add @openfeature/server-sdk @openfeature/core
 import { OpenFeature } from '@openfeature/server-sdk';
 
 // Register your feature flag provider
-OpenFeature.setProvider(new YourProviderOfChoice());
+await OpenFeature.setProviderAndWait(new YourProviderOfChoice());
 
 // create a new client
 const client = OpenFeature.getClient();
@@ -107,10 +107,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 details below.
 
@@ -211,6 +225,9 @@ const clientWithDefault = OpenFeature.getClient();
 const clientForCache = OpenFeature.getClient("otherClient");
 ```
 
+Named providers can be set in an awaitable or synchronous way.
+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.
@@ -224,13 +241,13 @@ import { OpenFeature, ProviderEvents } from '@openfeature/server-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);
 });
 ```
 
@@ -258,6 +275,8 @@ import { JsonValue, Provider, ResolutionDetails } from '@openfeature/server-sdk'
 
 // implement the provider interface
 class MyProvider implements Provider {
+  // Adds runtime validation that the provider is used with the expected SDK
+  public readonly runsOn = 'server';
 
   readonly metadata = {
     name: 'My Provider',