@openfeature/react-sdk 0.2.3-experimental → 0.3.0-experimental

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/react-sdk-v0.2.3-experimental">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.2.3-experimental&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/js-sdk/releases/tag/react-sdk-v0.3.0-experimental">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.3.0-experimental&color=blue&style=for-the-badge" />
   </a>
   <!-- x-release-please-end -->
   <br/>
@@ -50,10 +50,13 @@ In addition to the feature provided by the [web sdk](https://openfeature.dev/doc
     - [yarn](#yarn)
     - [Required peer dependencies](#required-peer-dependencies)
   - [Usage](#usage)
-  - [Multiple Providers and Domains](#multiple-providers-and-domains)
-  - [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)
+    - [OpenFeatureProvider context provider](#openfeatureprovider-context-provider)
+    - [Evaluation hooks](#evaluation-hooks)
+    - [Multiple Providers and Domains](#multiple-providers-and-domains)
+    - [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)
+- [FAQ and troubleshooting](#faq-and-troubleshooting)
 - [Resources](#resources)
 
 ## Quick start
@@ -87,10 +90,14 @@ The following list contains the peer dependencies of `@openfeature/react-sdk` wi
 
 ### Usage
 
+#### OpenFeatureProvider context provider
+
+The `OpenFeatureProvider` is a [React context provider](https://react.dev/reference/react/createContext#provider) which represents a scope for feature flag evaluations within a React application.
+It binds an OpenFeature client to all evaluations within child components, and allows the use of evaluation hooks.
 The example below shows how to use the `OpenFeatureProvider` with OpenFeature's `InMemoryProvider`.
 
 ```tsx
-import { EvaluationContext, OpenFeatureProvider, useBooleanFlagValue, useBooleanFlagDetails, OpenFeature, InMemoryProvider } from '@openfeature/react-sdk';
+import { EvaluationContext, OpenFeatureProvider, useFlag, OpenFeature, InMemoryProvider } from '@openfeature/react-sdk';
 
 const flagConfig = {
   'new-message': {
@@ -109,8 +116,11 @@ const flagConfig = {
   },
 };
 
+// Instantiate and set our provider (be sure this only happens once)!
+// Note: there's no need to await its initialization, the React SDK handles re-rendering and suspense for you!
 OpenFeature.setProvider(new InMemoryProvider(flagConfig));
 
+// Enclose your content in the configured provider
 function App() {
   return (
     <OpenFeatureProvider>
@@ -118,26 +128,39 @@ function App() {
     </OpenFeatureProvider>
   );
 }
+```
+
+#### Evaluation hooks
 
+Within the provider, you can use the various evaluation hooks to evaluate flags. 
+
+```tsx
 function Page() {
-  const newMessage = useBooleanFlagValue('new-message', false);
+  // Use the "query-style" flag evaluation hook, specifying a flag-key and a default value.
+  const { value: showNewMessage } = useFlag('new-message', true);
   return (
     <div className="App">
       <header className="App-header">
-        {newMessage ? <p>Welcome to this OpenFeature-enabled React app!</p> : <p>Welcome to this React app.</p>}
+        {showNewMessage ? <p>Welcome to this OpenFeature-enabled React app!</p> : <p>Welcome to this React app.</p>}
       </header>
     </div>
   )
 }
-
-export default App;
 ```
 
-You use the detailed flag evaluation hooks to evaluate the flag and get additional information about the flag and the evaluation.
+You can use the strongly-typed flag value and flag evaluation detail hooks as well, if you prefer.
+
+```tsx
+import { useBooleanFlagValue } from '@openfeature/react-sdk';
+
+// boolean flag evaluation
+const value = useBooleanFlagValue('new-message', false);
+```
 
 ```tsx
 import { useBooleanFlagDetails } from '@openfeature/react-sdk';
 
+// "detailed" boolean flag evaluation
 const {
   value,
   variant,
@@ -146,8 +169,7 @@ const {
 } = useBooleanFlagDetails('new-message', false);
 ```
 
-### Multiple Providers and Domains
-
+#### Multiple Providers and Domains
 
 Multiple providers can be used by passing a `domain` to the `OpenFeatureProvider`:
 
@@ -170,15 +192,15 @@ OpenFeature.getClient('my-domain');
 
 For more information about `domains`, refer to the [web SDK](https://github.com/open-feature/js-sdk/blob/main/packages/client/README.md).
 
-### Re-rendering with Context Changes
+#### Re-rendering with Context Changes
 
 By default, if the OpenFeature [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context) is modified, components will be re-rendered.
 This is useful in cases where flag values are dependant on user-attributes or other application state (user logged in, items in card, etc).
-You can disable this feature in the hook options:
+You can disable this feature in the hook options (or in the [OpenFeatureProvider](#openfeatureprovider-context-provider)):
 
 ```tsx
 function Page() {
-  const newMessage = useBooleanFlagValue('new-message', false, { updateOnContextChanged: false });
+  const showNewMessage = useBooleanFlagValue('new-message', false, { updateOnContextChanged: false });
   return (
     <MyComponents></MyComponents>
   )
@@ -187,15 +209,15 @@ function Page() {
 
 For more information about how evaluation context works in the React SDK, see the documentation on OpenFeature's [static context SDK paradigm](https://openfeature.dev/specification/glossary/#static-context-paradigm).
 
-### Re-rendering with Flag Configuration Changes
+#### Re-rendering with Flag Configuration Changes
 
 By default, if the underlying provider emits a `ConfigurationChanged` event, components will be re-rendered.
 This is useful if you want your UI to immediately reflect changes in the backend flag configuration.
-You can disable this feature in the hook options:
+You can disable this feature in the hook options (or in the [OpenFeatureProvider](#openfeatureprovider-context-provider)):
 
 ```tsx
 function Page() {
-  const newMessage = useBooleanFlagValue('new-message', false, { updateOnConfigurationChanged: false });
+  const showNewMessage = useBooleanFlagValue('new-message', false, { updateOnConfigurationChanged: false });
   return (
     <MyComponents></MyComponents>
   )
@@ -204,11 +226,11 @@ function Page() {
 
 Note that if your provider doesn't support updates, this configuration has no impact.
 
-### Suspense Support
+#### Suspense Support
 
 Frequently, providers need to perform some initial startup tasks.
-It may be desireable not to display components with feature flags until this is complete.
-Built-in [suspense](https://react.dev/reference/react/Suspense) support makes this easy: 
+It may be desireable not to display components with feature flags until this is complete, or when the context changes.
+Built-in [suspense](https://react.dev/reference/react/Suspense) support makes this easy.
 
 ```tsx
 function Content() {
@@ -222,11 +244,11 @@ function Content() {
 
 function Message() {
   // component to render after READY.
-  const newMessage = useBooleanFlagValue('new-message', false);
+  const showNewMessage = useBooleanFlagValue('new-message', false);
 
   return (
     <>
-      {newMessage ? (
+      {showNewMessage ? (
         <p>Welcome to this OpenFeature-enabled React app!</p>
       ) : (
         <p>Welcome to this plain old React app!</p>
@@ -239,6 +261,37 @@ function Fallback() {
   // component to render before READY.
   return <p>Waiting for provider to be ready...</p>;
 }
+
+```
+
+This can be disabled in the hook options (or in the [OpenFeatureProvider](#openfeatureprovider-context-provider)).
+
+## FAQ and troubleshooting
+
+> I get an error that says something like: `A React component suspended while rendering, but no fallback UI was specified.`
+
+The OpenFeature React SDK features built-in [suspense support](#suspense-support).
+This means that it will render your loading fallback automatically while the your provider starts up, and during context reconciliation for any of your components using feature flags!
+However, you will see this error if you neglect to create a suspense boundary around any components using feature flags; add a suspense boundary to resolve this issue.
+Alternatively, you can disable this feature by setting `suspendWhileReconciling=false` and `suspendUntilReady=false` in the [evaluation hooks](#evaluation-hooks) or the [OpenFeatureProvider](#openfeatureprovider-context-provider) (which applies to all evaluation hooks in child components).
+
+> I get odd rendering issues, or errors when components mount, if I use the suspense features.
+
+In React 16/17's "Legacy Suspense", when a component suspends, its sibling components initially mount and then are hidden.
+This can cause surprising effects and inconsistencies if sibling components are rendered while the provider is still getting ready.
+To fix this, you can upgrade to React 18, which uses "Concurrent Suspense", in which siblings are not mounted until their suspended sibling resolves.
+Alternatively, if you cannot upgrade to React 18, you can use the `useWhenProviderReady` utility hook in any sibling components to prevent them from mounting until the provider is ready.
+
+> I am using multiple `OpenFeatureProvider` contexts, but they are sharing the same provider or evaluation context. Why?
+
+The `OpenFeatureProvider` binds a `client` to all child components, but the provider and context associated with that client is controlled by the `domain` parameter.
+This is consistent with all OpenFeature SDKs.
+To scope an OpenFeatureProvider to a particular provider/context set the `domain` parameter on your `OpenFeatureProvider`:
+
+```tsx
+<OpenFeatureProvider domain={'my-domain'}>
+  <Page></Page>
+</OpenFeatureProvider>
 ```
 
 ## Resources

package/dist/cjs/index.js

@@ -34,90 +34,179 @@ __export(src_exports, {
   OpenFeatureProvider: () => OpenFeatureProvider,
   useBooleanFlagDetails: () => useBooleanFlagDetails,
   useBooleanFlagValue: () => useBooleanFlagValue,
+  useFlag: () => useFlag,
   useNumberFlagDetails: () => useNumberFlagDetails,
   useNumberFlagValue: () => useNumberFlagValue,
   useObjectFlagDetails: () => useObjectFlagDetails,
   useObjectFlagValue: () => useObjectFlagValue,
   useOpenFeatureClient: () => useOpenFeatureClient,
   useStringFlagDetails: () => useStringFlagDetails,
-  useStringFlagValue: () => useStringFlagValue
+  useStringFlagValue: () => useStringFlagValue,
+  useWhenProviderReady: () => useWhenProviderReady
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/use-feature-flag.ts
+// src/evaluation/use-feature-flag.ts
 var import_web_sdk2 = require("@openfeature/web-sdk");
-var import_react = require("react");
+var import_react3 = require("react");
 
-// src/provider.tsx
-var React = __toESM(require("react"));
-var import_web_sdk = require("@openfeature/web-sdk");
-var Context = React.createContext(void 0);
-var OpenFeatureProvider = ({ client, domain, children }) => {
-  if (!client) {
-    client = import_web_sdk.OpenFeature.getClient(domain);
-  }
-  return /* @__PURE__ */ React.createElement(Context.Provider, { value: client }, children);
+// src/common/options.ts
+var DEFAULT_OPTIONS = {
+  updateOnContextChanged: true,
+  updateOnConfigurationChanged: true,
+  suspendUntilReady: true,
+  suspendWhileReconciling: true
 };
-var useOpenFeatureClient = () => {
-  const client = React.useContext(Context);
+var normalizeOptions = (options) => {
+  const defaultOptionsIfMissing = !options ? {} : options;
+  const suspendUntilReady = "suspendUntilReady" in defaultOptionsIfMissing ? defaultOptionsIfMissing.suspendUntilReady : defaultOptionsIfMissing.suspend;
+  const suspendWhileReconciling = "suspendWhileReconciling" in defaultOptionsIfMissing ? defaultOptionsIfMissing.suspendWhileReconciling : defaultOptionsIfMissing.suspend;
+  return {
+    updateOnContextChanged: defaultOptionsIfMissing.updateOnContextChanged,
+    updateOnConfigurationChanged: defaultOptionsIfMissing.updateOnConfigurationChanged,
+    // only return these if properly set (no undefined to allow overriding with spread)
+    ...typeof suspendUntilReady === "boolean" && { suspendUntilReady },
+    ...typeof suspendWhileReconciling === "boolean" && { suspendWhileReconciling }
+  };
+};
+
+// src/common/suspend.ts
+var import_web_sdk = require("@openfeature/web-sdk");
+function suspend(client, updateState, ...resumeEvents) {
+  let suspendResolver;
+  const suspendPromise = new Promise((resolve) => {
+    suspendResolver = () => {
+      resolve();
+      resumeEvents.forEach((e) => {
+        client.removeHandler(e, suspendResolver);
+      });
+      client.removeHandler(import_web_sdk.ProviderEvents.Error, suspendResolver);
+    };
+    resumeEvents.forEach((e) => {
+      client.addHandler(e, suspendResolver);
+    });
+    client.addHandler(import_web_sdk.ProviderEvents.Error, suspendResolver);
+  });
+  updateState(suspenseWrapper(suspendPromise));
+}
+function suspenseWrapper(promise) {
+  let status = 0 /* Pending */;
+  let result;
+  const suspended = promise.then((value) => {
+    status = 1 /* Success */;
+    result = value;
+  }).catch((error) => {
+    status = 2 /* Error */;
+    result = error;
+  });
+  return () => {
+    switch (status) {
+      case 0 /* Pending */:
+        throw suspended;
+      case 1 /* Success */:
+        return result;
+      case 2 /* Error */:
+        throw result;
+      default:
+        throw new Error("Suspending promise is in an unknown state.");
+    }
+  };
+}
+
+// src/provider/context.ts
+var import_react = __toESM(require("react"));
+var Context = import_react.default.createContext(void 0);
+function useProviderOptions() {
+  const { options } = import_react.default.useContext(Context) || {};
+  return normalizeOptions(options);
+}
+
+// src/provider/use-open-feature-client.ts
+var import_react2 = __toESM(require("react"));
+function useOpenFeatureClient() {
+  const { client } = import_react2.default.useContext(Context) || {};
   if (!client) {
     throw new Error(
       "No OpenFeature client available - components using OpenFeature must be wrapped with an <OpenFeatureProvider>"
     );
   }
   return client;
-};
+}
 
-// src/use-feature-flag.ts
-var DEFAULT_OPTIONS = {
-  updateOnContextChanged: true,
-  updateOnConfigurationChanged: true,
-  suspendUntilReady: true,
-  suspendWhileReconciling: false
-};
+// src/evaluation/use-feature-flag.ts
+function useFlag(flagKey, defaultValue, options) {
+  const query = typeof defaultValue === "boolean" ? new HookFlagQuery(useBooleanFlagDetails(flagKey, defaultValue, options)) : typeof defaultValue === "number" ? new HookFlagQuery(useNumberFlagDetails(flagKey, defaultValue, options)) : typeof defaultValue === "string" ? new HookFlagQuery(useStringFlagDetails(flagKey, defaultValue, options)) : new HookFlagQuery(useObjectFlagDetails(flagKey, defaultValue, options));
+  return query;
+}
 function useBooleanFlagValue(flagKey, defaultValue, options) {
   return useBooleanFlagDetails(flagKey, defaultValue, options).value;
 }
 function useBooleanFlagDetails(flagKey, defaultValue, options) {
-  return attachHandlersAndResolve(flagKey, defaultValue, (client) => {
-    return client.getBooleanDetails;
-  }, options);
+  return attachHandlersAndResolve(
+    flagKey,
+    defaultValue,
+    (client) => {
+      return client.getBooleanDetails;
+    },
+    options
+  );
 }
 function useStringFlagValue(flagKey, defaultValue, options) {
   return useStringFlagDetails(flagKey, defaultValue, options).value;
 }
 function useStringFlagDetails(flagKey, defaultValue, options) {
-  return attachHandlersAndResolve(flagKey, defaultValue, (client) => {
-    return client.getStringDetails;
-  }, options);
+  return attachHandlersAndResolve(
+    flagKey,
+    defaultValue,
+    (client) => {
+      return client.getStringDetails;
+    },
+    options
+  );
 }
 function useNumberFlagValue(flagKey, defaultValue, options) {
   return useNumberFlagDetails(flagKey, defaultValue, options).value;
 }
 function useNumberFlagDetails(flagKey, defaultValue, options) {
-  return attachHandlersAndResolve(flagKey, defaultValue, (client) => {
-    return client.getNumberDetails;
-  }, options);
+  return attachHandlersAndResolve(
+    flagKey,
+    defaultValue,
+    (client) => {
+      return client.getNumberDetails;
+    },
+    options
+  );
 }
 function useObjectFlagValue(flagKey, defaultValue, options) {
   return useObjectFlagDetails(flagKey, defaultValue, options).value;
 }
 function useObjectFlagDetails(flagKey, defaultValue, options) {
-  return attachHandlersAndResolve(flagKey, defaultValue, (client) => {
-    return client.getObjectDetails;
-  }, options);
+  return attachHandlersAndResolve(
+    flagKey,
+    defaultValue,
+    (client) => {
+      return client.getObjectDetails;
+    },
+    options
+  );
 }
 function attachHandlersAndResolve(flagKey, defaultValue, resolver, options) {
-  const defaultedOptions = { ...DEFAULT_OPTIONS, ...options };
-  const [, updateState] = (0, import_react.useState)();
+  const defaultedOptions = { ...DEFAULT_OPTIONS, ...useProviderOptions(), ...normalizeOptions(options) };
+  const [, updateState] = (0, import_react3.useState)();
   const client = useOpenFeatureClient();
   const forceUpdate = () => {
     updateState({});
   };
   const suspendRef = () => {
-    suspend(client, updateState, import_web_sdk2.ProviderEvents.ContextChanged, import_web_sdk2.ProviderEvents.ConfigurationChanged, import_web_sdk2.ProviderEvents.Ready);
+    suspend(
+      client,
+      updateState,
+      import_web_sdk2.ProviderEvents.ContextChanged,
+      import_web_sdk2.ProviderEvents.ConfigurationChanged,
+      import_web_sdk2.ProviderEvents.Ready
+    );
   };
-  (0, import_react.useEffect)(() => {
+  (0, import_react3.useEffect)(() => {
     if (client.providerStatus === import_web_sdk2.ProviderStatus.NOT_READY) {
       client.addHandler(import_web_sdk2.ProviderEvents.Ready, forceUpdate);
       if (defaultedOptions.suspendUntilReady) {
@@ -136,7 +225,7 @@ function attachHandlersAndResolve(flagKey, defaultValue, resolver, options) {
       client.removeHandler(import_web_sdk2.ProviderEvents.Reconciling, suspendRef);
     };
   }, []);
-  (0, import_react.useEffect)(() => {
+  (0, import_react3.useEffect)(() => {
     if (defaultedOptions.updateOnConfigurationChanged) {
       client.addHandler(import_web_sdk2.ProviderEvents.ConfigurationChanged, forceUpdate);
     }
@@ -146,48 +235,65 @@ function attachHandlersAndResolve(flagKey, defaultValue, resolver, options) {
   }, []);
   return resolver(client).call(client, flagKey, defaultValue);
 }
-function suspend(client, updateState, ...resumeEvents) {
-  let suspendResolver;
-  const suspendPromise = new Promise((resolve) => {
-    suspendResolver = () => {
-      resolve();
-      resumeEvents.forEach((e) => {
-        client.removeHandler(e, suspendResolver);
-      });
-      client.removeHandler(import_web_sdk2.ProviderEvents.Error, suspendResolver);
-    };
-    resumeEvents.forEach((e) => {
-      client.addHandler(e, suspendResolver);
-    });
-    client.addHandler(import_web_sdk2.ProviderEvents.Error, suspendResolver);
-  });
-  updateState(suspenseWrapper(suspendPromise));
+var HookFlagQuery = class {
+  constructor(_details) {
+    this._details = _details;
+  }
+  get details() {
+    return this._details;
+  }
+  get value() {
+    return this._details?.value;
+  }
+  get variant() {
+    return this._details.variant;
+  }
+  get flagMetadata() {
+    return this._details.flagMetadata;
+  }
+  get reason() {
+    return this._details.reason;
+  }
+  get isError() {
+    return !!this._details?.errorCode || this._details.reason == import_web_sdk2.StandardResolutionReasons.ERROR;
+  }
+  get errorCode() {
+    return this._details?.errorCode;
+  }
+  get errorMessage() {
+    return this._details?.errorMessage;
+  }
+  get isAuthoritative() {
+    return !this.isError && this._details.reason != import_web_sdk2.StandardResolutionReasons.STALE && this._details.reason != import_web_sdk2.StandardResolutionReasons.DISABLED;
+  }
+  get type() {
+    return typeof this._details.value;
+  }
+};
+
+// src/provider/provider.tsx
+var import_web_sdk3 = require("@openfeature/web-sdk");
+var React3 = __toESM(require("react"));
+function OpenFeatureProvider({ client, domain, children, ...options }) {
+  if (!client) {
+    client = import_web_sdk3.OpenFeature.getClient(domain);
+  }
+  return /* @__PURE__ */ React3.createElement(Context.Provider, { value: { client, options } }, children);
 }
-function suspenseWrapper(promise) {
-  let status = 0 /* Pending */;
-  let result;
-  const suspended = promise.then(
-    (value) => {
-      status = 1 /* Success */;
-      result = value;
-    },
-    (error) => {
-      status = 2 /* Error */;
-      result = error;
-    }
-  );
-  return () => {
-    switch (status) {
-      case 0 /* Pending */:
-        throw suspended;
-      case 1 /* Success */:
-        return result;
-      case 2 /* Error */:
-        throw result;
-      default:
-        throw new Error("Suspending promise is in an unknown state.");
+
+// src/provider/use-when-provider-ready.ts
+var import_web_sdk4 = require("@openfeature/web-sdk");
+var import_react4 = require("react");
+function useWhenProviderReady(options) {
+  const [, updateState] = (0, import_react4.useState)();
+  const client = useOpenFeatureClient();
+  const defaultedOptions = { ...DEFAULT_OPTIONS, ...useProviderOptions(), ...normalizeOptions(options) };
+  (0, import_react4.useEffect)(() => {
+    if (defaultedOptions.suspendUntilReady && client.providerStatus === import_web_sdk4.ProviderStatus.NOT_READY) {
+      suspend(client, updateState, import_web_sdk4.ProviderEvents.Ready);
     }
-  };
+  }, []);
+  return client.providerStatus === import_web_sdk4.ProviderStatus.READY;
 }
 
 // src/index.ts