feat: add support for building Next.JS apps that use suspending flags.

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

@@ -5,18 +5,24 @@ import type {
   EventHandler,
   FlagEvaluationOptions,
   FlagValue,
-  JsonValue} from '@openfeature/web-sdk';
-import {
-  ProviderEvents,
-  ProviderStatus,
+  JsonValue,
 } from '@openfeature/web-sdk';
+import { ProviderEvents, ProviderStatus } from '@openfeature/web-sdk';
 import { useEffect, useRef, useState } from 'react';
+import {
+  DEFAULT_OPTIONS,
+  isEqual,
+  normalizeOptions,
+  suspendUntilInitialized,
+  suspendUntilReconciled,
+  useProviderOptions,
+} from '../internal';
 import type { ReactFlagEvaluationNoSuspenseOptions, ReactFlagEvaluationOptions } from '../options';
-import { DEFAULT_OPTIONS, isEqual, normalizeOptions, suspendUntilReady, useProviderOptions } from '../internal';
 import { useOpenFeatureClient } from '../provider/use-open-feature-client';
 import { useOpenFeatureClientStatus } from '../provider/use-open-feature-client-status';
+import { useOpenFeatureProvider } from '../provider/use-open-feature-provider';
 import type { FlagQuery } from '../query';
-import { HookFlagQuery } from './hook-flag-query';
+import { HookFlagQuery } from '../internal/hook-flag-query';
 
 // This type is a bit wild-looking, but I think we need it.
 // We have to use the conditional, because otherwise useFlag('key', false) would return false, not boolean (too constrained).
@@ -280,15 +286,16 @@ function attachHandlersAndResolve<T extends FlagValue>(
   const defaultedOptions = { ...DEFAULT_OPTIONS, ...useProviderOptions(), ...normalizeOptions(options) };
   const client = useOpenFeatureClient();
   const status = useOpenFeatureClientStatus();
+  const provider = useOpenFeatureProvider();
+
   const controller = new AbortController();
 
-  // suspense
   if (defaultedOptions.suspendUntilReady && status === ProviderStatus.NOT_READY) {
-    suspendUntilReady(client);
+    suspendUntilInitialized(provider, client);
   }
 
   if (defaultedOptions.suspendWhileReconciling && status === ProviderStatus.RECONCILING) {
-    suspendUntilReady(client);
+    suspendUntilReconciled(client);
   }
 
   const [evaluationDetails, setEvaluationDetails] = useState<EvaluationDetails<T>>(

packages/react/src/internal/context.ts

@@ -5,7 +5,8 @@ import { normalizeOptions } from '.';
 
 /**
  * The underlying React context.
- * DO NOT EXPORT PUBLICLY
+ *
+ * **DO NOT EXPORT PUBLICLY**
  * @internal
  */
 export const Context = React.createContext<
@@ -14,7 +15,8 @@ export const Context = React.createContext<
 
 /**
  * Get a normalized copy of the options used for this OpenFeatureProvider, see {@link normalizeOptions}.
- * DO NOT EXPORT PUBLICLY
+ *
+ * **DO NOT EXPORT PUBLICLY**
  * @internal
  * @returns {NormalizedOptions} normalized options the defaulted options, not defaulted or normalized.
  */

packages/react/src/internal/errors.ts

@@ -0,0 +1,11 @@
+
+
+const context = 'Components using OpenFeature must be wrapped with an <OpenFeatureProvider>.';
+const tip = 'If you are seeing this in a test, see: https://openfeature.dev/docs/reference/technologies/client/web/react#testing';
+
+export class MissingContextError extends Error {
+  constructor(reason: string) {
+    super(`${reason}: ${context} ${tip}`);
+    this.name = 'MissingContextError';
+  }
+}

packages/react/src/internal/suspense.ts

@@ -1,21 +1,57 @@
-import type { Client} from '@openfeature/web-sdk';
-import { ProviderEvents } from '@openfeature/web-sdk';
+import type { Client, Provider } from '@openfeature/web-sdk';
+import { NOOP_PROVIDER, ProviderEvents } from '@openfeature/web-sdk';
+import { use } from './use';
+
+/**
+ * A weak map is used to store the global suspense status for each provider. It's
+ * important for this to be global to avoid rerender loops. Using useRef won't
+ * work because the value isn't preserved when a promise is thrown in a component,
+ * which is how suspense operates.
+ */
+const globalProviderSuspenseStatus = new WeakMap<Provider, Promise<unknown>>();
 
 /**
  * Suspends until the client is ready to evaluate feature flags.
- * DO NOT EXPORT PUBLICLY
- * @param {Client} client OpenFeature client
+ *
+ * **DO NOT EXPORT PUBLICLY**
+ * @internal
+ * @param {Provider} provider the provider to suspend for
+ * @param {Client} client the client to check for readiness
  */
-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);
-  });
+export function suspendUntilInitialized(provider: Provider, client: Client) {
+  const statusPromiseRef = globalProviderSuspenseStatus.get(provider);
+  if (!statusPromiseRef) {
+    // Noop provider is never ready, so we resolve immediately
+    const statusPromise = provider !== NOOP_PROVIDER ? isProviderReady(client) : Promise.resolve();
+    // Storing the promise globally because
+    globalProviderSuspenseStatus.set(provider, statusPromise);
+    // Use will throw the promise and React will trigger a rerender when it's resolved
+    use(statusPromise);
+  } else {
+    // Reuse the existing promise, use won't rethrow if the promise has settled.
+    use(statusPromiseRef);
+  }
+}
+
+/**
+ * Suspends until the provider has finished reconciling.
+ *
+ * **DO NOT EXPORT PUBLICLY**
+ * @internal
+ * @param {Client} client the client to check for readiness
+ */
+export function suspendUntilReconciled(client: Client) {
+  use(isProviderReady(client));
+}
+
+async function isProviderReady(client: Client) {
+  const controller = new AbortController();
+  try {
+    return await new Promise((resolve, reject) => {
+      client.addHandler(ProviderEvents.Ready, resolve, { signal: controller.signal });
+      client.addHandler(ProviderEvents.Error, reject, { signal: controller.signal });
+    });
+  } finally {
+    controller.abort();
+  }
 }

packages/react/src/internal/use.ts

@@ -0,0 +1,53 @@
+/// <reference types="react/experimental" />
+// This function is adopted from https://github.com/vercel/swr
+import React from 'react';
+
+/**
+ * Extends a Promise-like value to include status tracking.
+ * The extra properties are used to manage the lifecycle of the Promise, indicating its current state.
+ * More information can be found in the React RFE for the use hook.
+ * @see https://github.com/reactjs/rfcs/pull/229
+ */
+export type UsePromise<T> =
+  Promise<T> & {
+    status?: 'pending' | 'fulfilled' | 'rejected';
+    value?: T;
+    reason?: unknown;
+  };
+
+/**
+ * React.use is a React API that lets you read the value of a resource like a Promise or context.
+ * It was officially added in React 19, so needs to be polyfilled to support older React versions.
+ * @param {UsePromise} thenable A thenable object that represents a Promise-like value.
+ * @returns {unknown} The resolved value of the thenable or throws if it's still pending or rejected.
+ */
+export const use =
+  React.use ||
+  // This extra generic is to avoid TypeScript mixing up the generic and JSX syntax
+  // and emitting an error.
+  // We assume that this is only for the `use(thenable)` case, not `use(context)`.
+  // https://github.com/facebook/react/blob/aed00dacfb79d17c53218404c52b1c7aa59c4a89/packages/react-server/src/ReactFizzThenable.js#L45
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  (<T, _>(thenable: UsePromise<T>): T => {
+    switch (thenable.status) {
+      case 'pending':
+        throw thenable;
+      case 'fulfilled':
+        return thenable.value as T;
+      case 'rejected':
+        throw thenable.reason;
+      default:
+        thenable.status = 'pending';
+        thenable.then(
+          (v) => {
+            thenable.status = 'fulfilled';
+            thenable.value = v;
+          },
+          (e) => {
+            thenable.status = 'rejected';
+            thenable.reason = e;
+          },
+        );
+        throw thenable;
+    }
+  });

packages/react/src/provider/provider.tsx

@@ -31,7 +31,7 @@ type ProviderProps = {
    * @param {ProviderProps} properties props for the context provider
    * @returns {OpenFeatureProvider} context provider
    */
-export function OpenFeatureProvider({ client, domain, children, ...options }: ProviderProps) {
+export function OpenFeatureProvider({ client, domain, children, ...options }: ProviderProps): JSX.Element {
   if (!client) {
     client = OpenFeature.getClient(domain);
   }

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

@@ -1,6 +1,7 @@
 import React from 'react';
 import { Context } from '../internal';
-import type { Client } from '@openfeature/web-sdk';
+import { type Client } from '@openfeature/web-sdk';
+import { MissingContextError } from '../internal/errors';
 
 /**
  * Get the {@link Client} instance for this OpenFeatureProvider context.
@@ -11,9 +12,7 @@ export function useOpenFeatureClient(): Client {
   const { client } = React.useContext(Context) || {};
 
   if (!client) {
-    throw new Error(
-      'No OpenFeature client available - components using OpenFeature must be wrapped with an <OpenFeatureProvider>. If you are seeing this in a test, see: https://openfeature.dev/docs/reference/technologies/client/web/react#testing',
-    );
+    throw new MissingContextError('No OpenFeature client available');
   }
 
   return client;

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

@@ -0,0 +1,21 @@
+import React from 'react';
+import { Context } from '../internal';
+import { OpenFeature } from '@openfeature/web-sdk';
+import type { Provider } from '@openfeature/web-sdk';
+import { MissingContextError } from '../internal/errors';
+
+/**
+ * Get the {@link Provider} bound to the domain specified in the OpenFeatureProvider context.
+ * Note that it isn't recommended to interact with the provider directly, but rather through
+ * an OpenFeature client.
+ * @returns {Provider} provider for this scope
+ */
+export function useOpenFeatureProvider(): Provider {
+  const openFeatureContext = React.useContext(Context);
+
+  if (!openFeatureContext) {
+    throw new MissingContextError('No OpenFeature context available');
+  }
+
+  return OpenFeature.getProvider(openFeatureContext.domain);
+}

packages/react/src/provider/use-when-provider-ready.ts

@@ -2,7 +2,8 @@ import { ProviderStatus } from '@openfeature/web-sdk';
 import { useOpenFeatureClient } from './use-open-feature-client';
 import { useOpenFeatureClientStatus } from './use-open-feature-client-status';
 import type { ReactFlagEvaluationOptions } from '../options';
-import { DEFAULT_OPTIONS, useProviderOptions, normalizeOptions, suspendUntilReady } from '../internal';
+import { DEFAULT_OPTIONS, useProviderOptions, normalizeOptions, suspendUntilInitialized } from '../internal';
+import { useOpenFeatureProvider } from './use-open-feature-provider';
 
 type Options = Pick<ReactFlagEvaluationOptions, 'suspendUntilReady'>;
 
@@ -14,14 +15,14 @@ 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 client = useOpenFeatureClient();
-  const status = useOpenFeatureClientStatus();
   // highest priority > evaluation hook options > provider options > default options > lowest priority
   const defaultedOptions = { ...DEFAULT_OPTIONS, ...useProviderOptions(), ...normalizeOptions(options) };
+  const client = useOpenFeatureClient();
+  const status = useOpenFeatureClientStatus();
+  const provider = useOpenFeatureProvider();
 
-  // suspense
   if (defaultedOptions.suspendUntilReady && status === ProviderStatus.NOT_READY) {
-    suspendUntilReady(client);
+    suspendUntilInitialized(provider, client);
   }
 
   return status === ProviderStatus.READY;