chore: update sdk readmes

Signed-off-by: OpenFeature Bot <[email protected]>
open-feature · Aug 26, 2024 · 4fa6a43 · 4fa6a43
1 parent b47ba4d
commit 4fa6a43
Show file tree

Hide file tree

Showing 13 changed files with 140 additions and 78 deletions.
diff --git a/docs/reference/technologies/client/kotlin.mdx b/docs/reference/technologies/client/kotlin.mdx
@@ -10,7 +10,7 @@ This content has been automatically generated from kotlin-sdk.
 Edits should be made here: https://github.com/open-feature/kotlin-sdk
 Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs
 
-Last updated at Thu Jun 13 2024 08:07:56 GMT+0000 (Coordinated Universal Time)
+Last updated at Mon Aug 26 2024 17:24:12 GMT+0000 (Coordinated Universal Time)
 -->
 
 <p align="center" class="github-badges">

diff --git a/docs/reference/technologies/client/swift.mdx b/docs/reference/technologies/client/swift.mdx
@@ -10,7 +10,7 @@ This content has been automatically generated from swift-sdk.
 Edits should be made here: https://github.com/open-feature/swift-sdk
 Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs
 
-Last updated at Thu Jun 13 2024 08:07:56 GMT+0000 (Coordinated Universal Time)
+Last updated at Mon Aug 26 2024 17:24:12 GMT+0000 (Coordinated Universal Time)
 -->
 
 <p align="center" class="github-badges">
@@ -20,8 +20,8 @@ Last updated at Thu Jun 13 2024 08:07:56 GMT+0000 (Coordinated Universal Time)
   </a>
 
 
-  <a href="https://github.com/open-feature/swift-sdk/releases/tag/0.1.0">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.1.0&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/swift-sdk/releases/tag/0.2.0">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.2.0&color=blue&style=for-the-badge" />
   </a>
 
 
@@ -58,7 +58,7 @@ First, ensure you have your GitHub account added as an option (+ > Add Source Co
 If you manage dependencies through SPM, in the dependencies section of Package.swift add:
 
 ```swift
-.package(url: "[email protected]:open-feature/swift-sdk.git", from: "0.1.0")
+.package(url: "[email protected]:open-feature/swift-sdk.git", from: "0.2.0")
 ```
 
 and in the target dependencies section add:

diff --git a/docs/reference/technologies/client/web/index.mdx b/docs/reference/technologies/client/web/index.mdx
@@ -10,16 +10,16 @@ This content has been automatically generated from js-sdk.
 Edits should be made here: https://github.com/open-feature/js-sdk
 Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs
 
-Last updated at Thu Jun 13 2024 08:07:56 GMT+0000 (Coordinated Universal Time)
+Last updated at Mon Aug 26 2024 17:24:12 GMT+0000 (Coordinated Universal Time)
 -->
 
 <p align="center" class="github-badges">
   <a href="https://github.com/open-feature/spec/releases/tag/v0.8.0">
     <img alt="Specification" src="https://img.shields.io/static/v1?label=specification&message=v0.8.0&color=yellow&style=for-the-badge" />
   </a>
 
-  <a href="https://github.com/open-feature/js-sdk/releases/tag/web-sdk-v1.2.1">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v1.2.1&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/web-sdk-v1.2.2">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v1.2.2&color=blue&style=for-the-badge" />
   </a>
 
   <br/>

diff --git a/docs/reference/technologies/client/web/react.mdx b/docs/reference/technologies/client/web/react.mdx
@@ -10,16 +10,16 @@ This content has been automatically generated from js-sdk.
 Edits should be made here: https://github.com/open-feature/js-sdk
 Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs
 
-Last updated at Thu Jun 13 2024 08:07:56 GMT+0000 (Coordinated Universal Time)
+Last updated at Mon Aug 26 2024 17:24:12 GMT+0000 (Coordinated Universal Time)
 -->
 
 <p align="center" class="github-badges">
   <a href="https://github.com/open-feature/spec/releases/tag/v0.8.0">
     <img alt="Specification" src="https://img.shields.io/static/v1?label=specification&message=v0.8.0&color=yellow&style=for-the-badge" />
   </a>
 
-  <a href="https://github.com/open-feature/js-sdk/releases/tag/react-sdk-v0.4.1">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.4.1&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/react-sdk-v0.4.3">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.4.3&color=blue&style=for-the-badge" />
   </a>
 
   <br/>
@@ -51,6 +51,7 @@ In addition to the feature provided by the [web sdk](/docs/reference/technologie
     - [Re-rendering with Context Changes](#re-rendering-with-context-changes)
     - [Re-rendering with Flag Configuration Changes](#re-rendering-with-flag-configuration-changes)
     - [Suspense Support](#suspense-support)
+  - [Testing](#testing)
 - [FAQ and troubleshooting](#faq-and-troubleshooting)
 - [Resources](#resources)
 
@@ -274,6 +275,65 @@ function Fallback() {
 
 This can be disabled in the hook options (or in the [OpenFeatureProvider](#openfeatureprovider-context-provider)).
 
+### Testing
+
+The React SDK includes a built-in context provider for testing.
+This allows you to easily test components that use evaluation hooks, such as `useFlag`.
+If you try to test a component (in this case, `MyComponent`) which uses an evaluation hook, you might see an error message like:
+
+> No OpenFeature client available - components using OpenFeature must be wrapped with an `<OpenFeatureProvider>`.
+
+You can resolve this by simply wrapping your component under test in the OpenFeatureTestProvider:
+
+```tsx
+// use default values for all evaluations
+<OpenFeatureTestProvider>
+  <MyComponent />
+</OpenFeatureTestProvider>
+```
+
+The basic configuration above will simply use the default value provided in code.
+If you'd like to control the values returned by the evaluation hooks, you can pass a map of flag keys and values:
+
+```tsx
+// return `true` for all evaluations of `'my-boolean-flag'`
+<OpenFeatureTestProvider flagValueMap={{ 'my-boolean-flag': true }}>
+  <MyComponent />
+</OpenFeatureTestProvider>
+```
+
+Additionally, you can pass an artificial delay for the provider startup to test your suspense boundaries or loaders/spinners impacted by feature flags:
+
+```tsx
+// delay the provider start by 1000ms and then return `true` for all evaluations of `'my-boolean-flag'`
+<OpenFeatureTestProvider delayMs={1000} flagValueMap={{ 'my-boolean-flag': true }}>
+  <MyComponent />
+</OpenFeatureTestProvider>
+```
+
+For maximum control, you can also pass your own mock provider implementation.
+The type of this option is `Partial<Provider>`, so you can pass an incomplete implementation:
+
+```tsx
+class MyTestProvider implements Partial<Provider> {
+  // implement the relevant resolver
+  resolveBooleanEvaluation(): ResolutionDetails<boolean> {
+    return {
+      value: true,
+      variant: 'my-variant',
+      reason: 'MY_REASON',
+    };
+  }
+}
+```
+
+```tsx
+// use your custom testing provider
+<OpenFeatureTestProvider provider={new MyTestProvider()}>
+  <MyComponent />
+</OpenFeatureTestProvider>,
+```
+
 ## FAQ and troubleshooting
 
 > I get an error that says something like: `A React component suspended while rendering, but no fallback UI was specified.`

diff --git a/docs/reference/technologies/server/dotnet.mdx b/docs/reference/technologies/server/dotnet.mdx
@@ -10,13 +10,13 @@ This content has been automatically generated from dotnet-sdk.
 Edits should be made here: https://github.com/open-feature/dotnet-sdk
 Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs
 
-Last updated at Thu Jun 13 2024 08:07:55 GMT+0000 (Coordinated Universal Time)
+Last updated at Mon Aug 26 2024 17:24:11 GMT+0000 (Coordinated Universal Time)
 -->
 
 [![Specification](https://img.shields.io/static/v1?label=specification&message=v0.7.0&color=yellow&style=for-the-badge)](https://github.com/open-feature/spec/releases/tag/v0.7.0)
 [
-  ![Release](https://img.shields.io/static/v1?label=release&message=v1.5.0&color=blue&style=for-the-badge) 
-](https://github.com/open-feature/dotnet-sdk/releases/tag/v1.5.0) 
+  ![Release](https://img.shields.io/static/v1?label=release&message=v2.0.0&color=blue&style=for-the-badge) 
+](https://github.com/open-feature/dotnet-sdk/releases/tag/v2.0.0) 
 
 [![Slack](https://img.shields.io/badge/slack-%40cncf%2Fopenfeature-brightgreen?style=flat&logo=slack)](https://cloud-native.slack.com/archives/C0344AANLA1)
 [![Codecov](https://codecov.io/gh/open-feature/dotnet-sdk/branch/main/graph/badge.svg?token=MONAVJBXUJ)](https://codecov.io/gh/open-feature/dotnet-sdk)
@@ -53,13 +53,13 @@ dotnet add package OpenFeature
 public async Task Example()
 {
     // Register your feature flag provider
-    await Api.Instance.SetProvider(new InMemoryProvider());
+    await Api.Instance.SetProviderAsync(new InMemoryProvider());
 
     // Create a new client
     FeatureClient client = Api.Instance.GetClient();
 
     // Evaluate your feature flag
-    bool v2Enabled = await client.GetBooleanValue("v2_enabled", false);
+    bool v2Enabled = await client.GetBooleanValueAsync("v2_enabled", false);
 
     if ( v2Enabled )
     {
@@ -70,16 +70,16 @@ public async Task Example()
 
 ## Features
 
-| Status | Features                        | Description                                                                                                                        |
-| ------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| ✅     | [Providers](#providers)         | Integrate with a commercial, open source, or in-house feature management tool.                                                     |
-| ✅     | [Targeting](#targeting)         | Contextually-aware flag evaluation using [evaluation context](/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) | Contextually-aware flag evaluation using [evaluation context](/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.                                                                                |
 
 > Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌
 
@@ -93,11 +93,11 @@ 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:
 
 ```csharp
-await Api.Instance.SetProvider(new MyProvider());
+await Api.Instance.SetProviderAsync(new MyProvider());
 ```
 
 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.
 
 ### Targeting
 
@@ -124,7 +124,7 @@ builder = EvaluationContext.Builder();
 builder.Set("region", "us-east-1");
 EvaluationContext reqCtx = builder.Build();
 
-bool flagValue = await client.GetBooleanValue("some-flag", false, reqCtx);
+bool flagValue = await client.GetBooleanValuAsync("some-flag", false, reqCtx);
 
 ```
 
@@ -145,34 +145,36 @@ var client = Api.Instance.GetClient();
 client.AddHooks(new ExampleClientHook());
 
 // add a hook for this evaluation only
-var value = await client.GetBooleanValue("boolFlag", false, context, new FlagEvaluationOptions(new ExampleInvocationHook()));
+var value = await client.GetBooleanValueAsync("boolFlag", false, context, new FlagEvaluationOptions(new ExampleInvocationHook()));
 ```
 
 ### Logging
 
 The .NET SDK uses Microsoft.Extensions.Logging. See the [manual](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line) for complete documentation.
 
-### 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.
 
 ```csharp
 // registering the default provider
-await Api.Instance.SetProvider(new LocalProvider());
+await Api.Instance.SetProviderAsync(new LocalProvider());
 
-// registering a named provider
-await Api.Instance.SetProvider("clientForCache", new CachedProvider());
+// registering a provider to a domain
+await Api.Instance.SetProviderAsync("clientForCache", new CachedProvider());
 
 // a client backed by default provider
 FeatureClient clientDefault = Api.Instance.GetClient();
 
 // a client backed by CachedProvider
-FeatureClient clientNamed = Api.Instance.GetClient("clientForCache");
-
+FeatureClient scopedClient = Api.Instance.GetClient("clientForCache");
 ```
 
+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,
@@ -205,7 +207,7 @@ EventHandlerDelegate callback = EventHandler;
 var myClient = Api.Instance.GetClient("my-client");
 
 var provider = new ExampleProvider();
-await Api.Instance.SetProvider(myClient.GetMetadata().Name, provider);
+await Api.Instance.SetProviderAsync(myClient.GetMetadata().Name, provider);
 
 myClient.AddHandler(ProviderEventTypes.ProviderReady, callback);
 ```
@@ -216,7 +218,7 @@ The OpenFeature API provides a close function to perform a cleanup of all regist
 
 ```csharp
 // Shut down all providers
-await Api.Instance.Shutdown();
+await Api.Instance.ShutdownAsync();
 ```
 
 ## Extending
@@ -235,27 +237,27 @@ public class MyProvider : FeatureProvider
         return new Metadata("My Provider");
     }
 
-    public override Task<ResolutionDetails<bool>> ResolveBooleanValue(string flagKey, bool defaultValue, EvaluationContext context = null)
+    public override Task<ResolutionDetails<bool>> ResolveBooleanValueAsync(string flagKey, bool defaultValue, EvaluationContext? context = null, CancellationToken cancellationToken = default)
     {
         // resolve a boolean flag value
     }
 
-    public override Task<ResolutionDetails<double>> ResolveDoubleValue(string flagKey, double defaultValue, EvaluationContext context = null)
+    public override Task<ResolutionDetails<string>> ResolveStringValueAsync(string flagKey, string defaultValue, EvaluationContext? context = null, CancellationToken cancellationToken = default)
     {
-        // resolve a double flag value
+        // resolve a string flag value
     }
 
-    public override Task<ResolutionDetails<int>> ResolveIntegerValue(string flagKey, int defaultValue, EvaluationContext context = null)
+    public override Task<ResolutionDetails<int>> ResolveIntegerValueAsync(string flagKey, int defaultValue, EvaluationContext context = null)
     {
         // resolve an int flag value
     }
 
-    public override Task<ResolutionDetails<string>> ResolveStringValue(string flagKey, string defaultValue, EvaluationContext context = null)
+    public override Task<ResolutionDetails<double>> ResolveDoubleValueAsync(string flagKey, double defaultValue, EvaluationContext? context = null, CancellationToken cancellationToken = default)
     {
-        // resolve a string flag value
+        // resolve a double flag value
     }
 
-    public override Task<ResolutionDetails<Value>> ResolveStructureValue(string flagKey, Value defaultValue, EvaluationContext context = null)
+    public override Task<ResolutionDetails<Value>> ResolveStructureValueAsync(string flagKey, Value defaultValue, EvaluationContext? context = null, CancellationToken cancellationToken = default)
     {
         // resolve an object flag value
     }
@@ -272,25 +274,25 @@ To satisfy the interface, all methods (`Before`/`After`/`Finally`/`Error`) need
 ```csharp
 public class MyHook : Hook
 {
-  public Task<EvaluationContext> Before<T>(HookContext<T> context,
+  public ValueTask<EvaluationContext> BeforeAsync<T>(HookContext<T> context,
       IReadOnlyDictionary<string, object> hints = null)
   {
     // code to run before flag evaluation
   }
 
-  public virtual Task After<T>(HookContext<T> context, FlagEvaluationDetails<T> details,
+  public ValueTask AfterAsync<T>(HookContext<T> context, FlagEvaluationDetails<T> details,
       IReadOnlyDictionary<string, object> hints = null)
   {
     // code to run after successful flag evaluation
   }
 
-  public virtual Task Error<T>(HookContext<T> context, Exception error,
+  public ValueTask ErrorAsync<T>(HookContext<T> context, Exception error,
       IReadOnlyDictionary<string, object> hints = null)
   {
     // code to run if there's an error during before hooks or during flag evaluation
   }
 
-  public virtual Task Finally<T>(HookContext<T> context, IReadOnlyDictionary<string, object> hints = null)
+  public ValueTask FinallyAsync<T>(HookContext<T> context, IReadOnlyDictionary<string, object> hints = null)
   {
     // code to run after all other stages, regardless of success/failure
   }

diff --git a/docs/reference/technologies/server/go.mdx b/docs/reference/technologies/server/go.mdx
@@ -9,7 +9,7 @@ This content has been automatically generated from go-sdk.
 Edits should be made here: https://github.com/open-feature/go-sdk
 Once a repo has been updated, docs can be generated by running: yarn update:sdk-docs
 
-Last updated at Thu Jun 13 2024 08:07:55 GMT+0000 (Coordinated Universal Time)
+Last updated at Mon Aug 26 2024 17:24:11 GMT+0000 (Coordinated Universal Time)
 -->
 
 <p align="center" class="github-badges">