fix: delayed suspense causes "flicker" (#921)

<!-- Please use this template for your pull request. -->
<!-- Please use the sections that you need and delete other sections -->

## This PR
<!-- add the description of the PR here -->

- Add an internal `useOpenFeatureClientStatus()` function to make it
slightly easier to keep track of the state of the current Client, and
know when to suspend or not.

- Replaces the `suspend()` function with a `suspendUntilReady()`
function. The `suspendUntilReady()` function fires immediatly during the
first render or when the component cannot render due to the client
having changed status.

- Put the Client status and the feature flag details inside React
states. This is required to make APIs like `startTransition` work
properly with the library

### Related Issues
<!-- add here the GitHub issue that this PR resolves if applicable -->

Fixes #920

### Notes
<!-- any additional notes for this PR -->

### Follow-up Tasks

- [x] Add more tests. Suspense and Transitions are very tricky. While
these changes don't seem to have broken any existing tests, we should
add new tests to make sure Suspense and Transitions continue to work
properly in the future.

- [ ] ~I think there might still be some reactivity issues with some
parts of the codebase. The client returned by `useOpenFeatureClient()`
didn't seem to update properly when the client changed, which made
`useOpenFeatureClientStatus()` not update properly.~ Out of the scope of
this PR

### How to test
<!-- if applicable, add testing instructions under this section -->

I built the application with `npm build`, then `npm pack`. I used the
modified code on a local project to see if it fixed the issues.

I built projects in CodeSanbox that demonstrate the issues.

For Suspense:
https://codesandbox.io/embed/openfeature-suspense-bug-5j7yll?fontsize=14&hidenavigation=1&theme=dark

For Transitions:
https://codesandbox.io/embed/openfeature-suspense-bug-forked-lqhyf3?fontsize=14&hidenavigation=1&theme=dark

---------

Signed-off-by: Tommy Josépovic <[email protected]>

Author: tjosepo

packages/react/src/common/suspend.ts

@@ -0,0 +1,20 @@
+import { Client, ProviderEvents } from '@openfeature/web-sdk';
+
+/**
+ * Suspends until the client is ready to evaluate feature flags.
+ * DO NOT EXPORT PUBLICLY
+ * @param {Client} client OpenFeature client
+ */
+export function suspendUntilReady(client: Client): Promise<void> {
+  let resolve: (value: unknown) => void;
+  let reject: () => void;
+  throw new Promise((_resolve, _reject) => {
+    resolve = _resolve;
+    reject = _reject;
+    client.addHandler(ProviderEvents.Ready, resolve);
+    client.addHandler(ProviderEvents.Error, reject);
+  }).finally(() => {
+    client.removeHandler(ProviderEvents.Ready, resolve);
+    client.removeHandler(ProviderEvents.Ready, reject);
+  });
+}

packages/react/src/common/suspense.ts

@@ -10,9 +10,10 @@ import {
 } from '@openfeature/web-sdk';
 import { useEffect, useState } from 'react';
 import { DEFAULT_OPTIONS, ReactFlagEvaluationOptions, normalizeOptions } from '../common/options';
-import { suspend } from '../common/suspend';
+import { suspendUntilReady } from '../common/suspense';
 import { useProviderOptions } from '../provider/context';
 import { useOpenFeatureClient } from '../provider/use-open-feature-client';
+import { useOpenFeatureClientStatus } from '../provider/use-open-feature-client-status';
 import { FlagQuery } from '../query';
 
 // This type is a bit wild-looking, but I think we need it.
@@ -246,58 +247,56 @@ function attachHandlersAndResolve<T extends FlagValue>(
   options?: ReactFlagEvaluationOptions,
 ): EvaluationDetails<T> {
   // highest priority > evaluation hook options > provider options > default options > lowest priority
-  const defaultedOptions = { ...DEFAULT_OPTIONS, ...useProviderOptions(), ...normalizeOptions(options)};
-  const [, updateState] = useState<object | undefined>();
+  const defaultedOptions = { ...DEFAULT_OPTIONS, ...useProviderOptions(), ...normalizeOptions(options) };
   const client = useOpenFeatureClient();
-  const forceUpdate = () => {
-    updateState({});
-  };
-  const suspendRef = () => {
-    suspend(
-      client,
-      updateState,
-      ProviderEvents.ContextChanged,
-      ProviderEvents.ConfigurationChanged,
-      ProviderEvents.Ready,
-    );
+  const status = useOpenFeatureClientStatus();
+
+  // suspense
+  if (defaultedOptions.suspendUntilReady && status === ProviderStatus.NOT_READY) {
+    suspendUntilReady(client);
+  }
+
+  if (defaultedOptions.suspendWhileReconciling && status === ProviderStatus.RECONCILING) {
+    suspendUntilReady(client);
+  }
+
+  const [evalutationDetails, setEvaluationDetails] = useState<EvaluationDetails<T>>(
+    resolver(client).call(client, flagKey, defaultValue, options),
+  );
+
+  const updateEvaluationDetailsRef = () => {
+    setEvaluationDetails(resolver(client).call(client, flagKey, defaultValue, options));
   };
 
   useEffect(() => {
-    if (client.providerStatus === ProviderStatus.NOT_READY) {
+    if (status === ProviderStatus.NOT_READY) {
       // update when the provider is ready
-      client.addHandler(ProviderEvents.Ready, forceUpdate);
-      if (defaultedOptions.suspendUntilReady) {
-        suspend(client, updateState, ProviderEvents.Ready);
-      }
+      client.addHandler(ProviderEvents.Ready, updateEvaluationDetailsRef);
     }
 
     if (defaultedOptions.updateOnContextChanged) {
       // update when the context changes
-      client.addHandler(ProviderEvents.ContextChanged, forceUpdate);
-      if (defaultedOptions.suspendWhileReconciling) {
-        client.addHandler(ProviderEvents.Reconciling, suspendRef);
-      }
+      client.addHandler(ProviderEvents.ContextChanged, updateEvaluationDetailsRef);
     }
     return () => {
       // cleanup the handlers
-      client.removeHandler(ProviderEvents.Ready, forceUpdate);
-      client.removeHandler(ProviderEvents.ContextChanged, forceUpdate);
-      client.removeHandler(ProviderEvents.Reconciling, suspendRef);
+      client.removeHandler(ProviderEvents.Ready, updateEvaluationDetailsRef);
+      client.removeHandler(ProviderEvents.ContextChanged, updateEvaluationDetailsRef);
     };
   }, []);
 
   useEffect(() => {
     if (defaultedOptions.updateOnConfigurationChanged) {
       // update when the provider configuration changes
-      client.addHandler(ProviderEvents.ConfigurationChanged, forceUpdate);
+      client.addHandler(ProviderEvents.ConfigurationChanged, updateEvaluationDetailsRef);
     }
     return () => {
       // cleanup the handlers
-      client.removeHandler(ProviderEvents.ConfigurationChanged, forceUpdate);
+      client.removeHandler(ProviderEvents.ConfigurationChanged, updateEvaluationDetailsRef);
     };
   }, []);
 
-  return resolver(client).call(client, flagKey, defaultValue, options);
+  return evalutationDetails;
 }
 
 // FlagQuery implementation, do not export

packages/react/src/evaluation/use-feature-flag.ts

@@ -0,0 +1,32 @@
+import { useEffect, useState } from 'react';
+import { useOpenFeatureClient } from './use-open-feature-client';
+import { ProviderEvents, ProviderStatus } from '@openfeature/web-sdk';
+
+/**
+ * Get the {@link ProviderStatus} for the OpenFeatureClient.
+ * @returns {ProviderStatus} status of the client for this scope
+ */
+export function useOpenFeatureClientStatus(): ProviderStatus {
+  const client = useOpenFeatureClient();
+  const [status, setStatus] = useState(client.providerStatus);
+
+  useEffect(() => {
+    const updateStatus = () => setStatus(client.providerStatus);
+    client.addHandler(ProviderEvents.ConfigurationChanged, updateStatus);
+    client.addHandler(ProviderEvents.ContextChanged, updateStatus);
+    client.addHandler(ProviderEvents.Error, updateStatus);
+    client.addHandler(ProviderEvents.Ready, updateStatus);
+    client.addHandler(ProviderEvents.Stale, updateStatus);
+    client.addHandler(ProviderEvents.Reconciling, updateStatus);
+    return () => {
+      client.removeHandler(ProviderEvents.ConfigurationChanged, updateStatus);
+      client.removeHandler(ProviderEvents.ContextChanged, updateStatus);
+      client.removeHandler(ProviderEvents.Error, updateStatus);
+      client.removeHandler(ProviderEvents.Ready, updateStatus);
+      client.removeHandler(ProviderEvents.Stale, updateStatus);
+      client.removeHandler(ProviderEvents.Reconciling, updateStatus);
+    };
+  }, [client]);
+
+  return status;
+}

packages/react/src/provider/use-open-feature-client-status.ts

@@ -1,9 +1,9 @@
-import { ProviderEvents, ProviderStatus } from '@openfeature/web-sdk';
-import { useEffect, useState } from 'react';
+import { ProviderStatus } from '@openfeature/web-sdk';
 import { DEFAULT_OPTIONS, ReactFlagEvaluationOptions, normalizeOptions } from '../common/options';
-import { suspend } from '../common/suspend';
 import { useProviderOptions } from './context';
 import { useOpenFeatureClient } from './use-open-feature-client';
+import { useOpenFeatureClientStatus } from './use-open-feature-client-status';
+import { suspendUntilReady } from '../common/suspense';
 
 type Options = Pick<ReactFlagEvaluationOptions, 'suspendUntilReady'>;
 
@@ -15,28 +15,15 @@ type Options = Pick<ReactFlagEvaluationOptions, 'suspendUntilReady'>;
  * @returns {boolean} boolean indicating if provider is {@link ProviderStatus.READY}, useful if suspense is disabled and you want to handle loaders on your own
  */
 export function useWhenProviderReady(options?: Options): boolean {
-  const [, updateState] = useState<object | undefined>();
   const client = useOpenFeatureClient();
+  const status = useOpenFeatureClientStatus();
   // highest priority > evaluation hook options > provider options > default options > lowest priority
   const defaultedOptions = { ...DEFAULT_OPTIONS, ...useProviderOptions(), ...normalizeOptions(options) };
-  const updateStateRef = () => {
-    updateState({});
-  };
 
-  useEffect(() => {
-    if (client.providerStatus === ProviderStatus.NOT_READY) {
-      // re-render when provider is ready
-      client.addHandler(ProviderEvents.Ready, updateStateRef);
-      if (defaultedOptions.suspendUntilReady) {
-        // suspend and update when the provider is ready
-        suspend(client, updateState, ProviderEvents.Ready);
-      }
-    }
-    return () => {
-      // cleanup the handler
-      client.removeHandler(ProviderEvents.Ready, updateStateRef);
-    };
-  }, []);
+  // suspense
+  if (defaultedOptions.suspendUntilReady && status === ProviderStatus.NOT_READY) {
+    suspendUntilReady(client);
+  }
 
-  return client.providerStatus === ProviderStatus.READY;
+  return status === ProviderStatus.READY;
 }