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,56 @@
-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();
+    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;

packages/react/test/evaluation.spec.tsx

@@ -6,12 +6,7 @@ import '@testing-library/jest-dom'; // see: https://testing-library.com/docs/rea
 import { act, render, renderHook, screen, waitFor } from '@testing-library/react';
 import * as React from 'react';
 import { startTransition, useState } from 'react';
-import type {
-  EvaluationContext,
-  EvaluationDetails,
-  EventContext,
-  Hook
-} from '../src/';
+import type { EvaluationContext, EvaluationDetails, EventContext, Hook } from '../src/';
 import {
   ErrorCode,
   InMemoryProvider,
@@ -27,15 +22,18 @@ import {
   useObjectFlagValue,
   useStringFlagDetails,
   useStringFlagValue,
-  useSuspenseFlag
+  useSuspenseFlag,
 } from '../src/';
-import { HookFlagQuery } from '../src/evaluation/hook-flag-query';
+import { HookFlagQuery } from '../src/internal/hook-flag-query';
 import { TestingProvider } from './test.utils';
 
 // custom provider to have better control over the emitted events
 class CustomEventInMemoryProvider extends InMemoryProvider {
-
-  putConfigurationWithCustomEvent(flagConfiguration: FlagConfiguration, event: ProviderEmittableEvents, eventContext: EventContext) {
+  putConfigurationWithCustomEvent(
+    flagConfiguration: FlagConfiguration,
+    event: ProviderEmittableEvents,
+    eventContext: EventContext,
+  ) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     this['_flagConfiguration'] = { ...flagConfiguration }; // private access hack
     this.events.emit(event, eventContext);
@@ -395,16 +393,19 @@ describe('evaluation', () => {
 
         expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
         await act(async () => {
-          await rerenderProvider.putConfigurationWithCustomEvent({
-            ...FLAG_CONFIG,
-            [BOOL_FLAG_KEY]: {
-              ...FLAG_CONFIG[BOOL_FLAG_KEY],
-              // Change the default; this should be ignored and not cause a re-render because flagsChanged is empty
-              defaultVariant: 'off',
+          await rerenderProvider.putConfigurationWithCustomEvent(
+            {
+              ...FLAG_CONFIG,
+              [BOOL_FLAG_KEY]: {
+                ...FLAG_CONFIG[BOOL_FLAG_KEY],
+                // Change the default; this should be ignored and not cause a re-render because flagsChanged is empty
+                defaultVariant: 'off',
+              },
+              // if the flagsChanged is empty, we know nothing has changed, so we don't bother diffing
             },
-             // if the flagsChanged is empty, we know nothing has changed, so we don't bother diffing
-          }, ClientProviderEvents.ConfigurationChanged, { flagsChanged: [] });
-
+            ClientProviderEvents.ConfigurationChanged,
+            { flagsChanged: [] },
+          );
         });
 
         expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
@@ -420,16 +421,19 @@ describe('evaluation', () => {
 
         expect(screen.queryByTestId('render-count')).toHaveTextContent('1');
         await act(async () => {
-          await rerenderProvider.putConfigurationWithCustomEvent({
-            ...FLAG_CONFIG,
-            [BOOL_FLAG_KEY]: {
-              ...FLAG_CONFIG[BOOL_FLAG_KEY],
-              // Change the default variant to trigger a rerender since not only do we check flagsChanged, but we also diff the value
-              defaultVariant: 'off',
+          await rerenderProvider.putConfigurationWithCustomEvent(
+            {
+              ...FLAG_CONFIG,
+              [BOOL_FLAG_KEY]: {
+                ...FLAG_CONFIG[BOOL_FLAG_KEY],
+                // Change the default variant to trigger a rerender since not only do we check flagsChanged, but we also diff the value
+                defaultVariant: 'off',
+              },
+              // if the flagsChanged is falsy, we don't know what flags changed - so we attempt to diff everything
             },
-             // if the flagsChanged is falsy, we don't know what flags changed - so we attempt to diff everything
-          }, ClientProviderEvents.ConfigurationChanged, { flagsChanged: undefined });
-
+            ClientProviderEvents.ConfigurationChanged,
+            { flagsChanged: undefined },
+          );
         });
 
         expect(screen.queryByTestId('render-count')).toHaveTextContent('2');
@@ -573,10 +577,41 @@ describe('evaluation', () => {
       },
     };
 
+    afterEach(() => {
+      OpenFeature.clearProviders();
+    });
+
     const suspendingProvider = () => {
       return new TestingProvider(CONFIG, DELAY); // delay init by 100ms
     };
 
+    describe('when using the noop provider', () => {
+      function TestComponent() {
+        const { value } = useSuspenseFlag(SUSPENSE_FLAG_KEY, DEFAULT);
+        return (
+          <>
+            <div>{value}</div>
+          </>
+        );
+      }
+      it('should fallback to the default value on the next rerender', async () => {
+        render(
+          <OpenFeatureProvider>
+            <React.Suspense fallback={<div>{FALLBACK}</div>}>
+              <TestComponent></TestComponent>
+            </React.Suspense>
+          </OpenFeatureProvider>,
+        );
+        // The loading indicator should be shown on the first render
+        expect(screen.queryByText(FALLBACK)).toBeInTheDocument();
+
+        // The default value should be shown on the next render
+        await waitFor(() => expect(screen.queryByText(DEFAULT)).toBeInTheDocument(), {
+          timeout: DELAY,
+        });
+      });
+    });
+
     describe('updateOnConfigurationChanged=true (default)', () => {
       function TestComponent() {
         const { value } = useFlag(SUSPENSE_FLAG_KEY, DEFAULT);

packages/server/src/open-feature.ts

@@ -138,6 +138,27 @@ export class OpenFeatureAPI
     return this;
   }
 
+  /**
+   * Get the default provider.
+   *
+   * Note that it isn't recommended to interact with the provider directly, but rather through
+   * an OpenFeature client.
+   * @returns {Provider} Default Provider
+   */
+  getProvider(): Provider;
+  /**
+   * Get the provider bound to the specified domain.
+   *
+   * Note that it isn't recommended to interact with the provider directly, but rather through
+   * an OpenFeature client.
+   * @param {string} domain An identifier which logically binds clients with providers
+   * @returns {Provider} Domain-scoped provider
+   */
+  getProvider(domain?: string): Provider;
+  getProvider(domain?: string): Provider {
+    return this.getProviderForClient(domain);
+  }
+
   setContext(context: EvaluationContext): this {
     this._context = context;
     return this;

packages/server/test/open-feature.spec.ts

@@ -74,8 +74,8 @@ describe('OpenFeature', () => {
     it('should set the default provider if no domain is provided', () => {
       const provider = mockProvider();
       OpenFeature.setProvider(provider);
-      const client = OpenFeature.getClient();
-      expect(client.metadata.providerMetadata.name).toEqual(provider.metadata.name);
+      const registeredProvider = OpenFeature.getProvider();
+      expect(registeredProvider).toEqual(provider);
     });
 
     it('should not change providers associated with a domain when setting a new default provider', () => {
@@ -85,11 +85,11 @@ describe('OpenFeature', () => {
       OpenFeature.setProvider(provider);
       OpenFeature.setProvider(domain, fakeProvider);
 
-      const defaultClient = OpenFeature.getClient();
-      const domainSpecificClient = OpenFeature.getClient(domain);
+      const defaultProvider = OpenFeature.getProvider();
+      const domainSpecificProvider = OpenFeature.getProvider(domain);
 
-      expect(defaultClient.metadata.providerMetadata.name).toEqual(provider.metadata.name);
-      expect(domainSpecificClient.metadata.providerMetadata.name).toEqual(fakeProvider.metadata.name);
+      expect(defaultProvider).toEqual(provider);
+      expect(domainSpecificProvider).toEqual(fakeProvider);
     });
 
     it('should bind a new provider to existing clients in a matching domain', () => {

packages/web/src/open-feature.ts

@@ -205,6 +205,27 @@ export class OpenFeatureAPI
     return this;
   }
 
+  /**
+   * Get the default provider.
+   *
+   * Note that it isn't recommended to interact with the provider directly, but rather through
+   * an OpenFeature client.
+   * @returns {Provider} Default Provider
+   */
+  getProvider(): Provider;
+  /**
+   * Get the provider bound to the specified domain.
+   *
+   * Note that it isn't recommended to interact with the provider directly, but rather through
+   * an OpenFeature client.
+   * @param {string} domain An identifier which logically binds clients with providers
+   * @returns {Provider} Domain-scoped provider
+   */
+  getProvider(domain?: string): Provider;
+  getProvider(domain?: string): Provider {
+    return this.getProviderForClient(domain);
+  }
+
   /**
    * Sets the evaluation context globally.
    * This will be used by all providers that have not bound to a domain.
@@ -325,9 +346,9 @@ export class OpenFeatureAPI
   }
 
   /**
-   * A factory function for creating new named OpenFeature clients. Clients can contain
-   * their own state (e.g. logger, hook, context). Multiple clients can be used
-   * to segment feature flag configuration.
+   * A factory function for creating new domain-scoped OpenFeature clients. Clients
+   * can contain their own state (e.g. logger, hook, context). Multiple domains
+   * can be used to segment feature flag configuration.
    *
    * If there is already a provider bound to this name via {@link this.setProvider setProvider}, this provider will be used.
    * Otherwise, the default provider is used until a provider is assigned to that name.

packages/web/test/open-feature.spec.ts

@@ -75,8 +75,8 @@ describe('OpenFeature', () => {
     it('should set the default provider if no domain is provided', () => {
       const provider = mockProvider();
       OpenFeature.setProvider(provider);
-      const client = OpenFeature.getClient();
-      expect(client.metadata.providerMetadata.name).toEqual(provider.metadata.name);
+      const registeredProvider = OpenFeature.getProvider();
+      expect(registeredProvider).toEqual(provider);
     });
 
     it('should not change providers associated with a domain when setting a new default provider', () => {
@@ -86,11 +86,11 @@ describe('OpenFeature', () => {
       OpenFeature.setProvider(provider);
       OpenFeature.setProvider(domain, fakeProvider);
 
-      const defaultClient = OpenFeature.getClient();
-      const domainSpecificClient = OpenFeature.getClient(domain);
+      const defaultProvider = OpenFeature.getProvider();
+      const domainSpecificProvider = OpenFeature.getProvider(domain);
 
-      expect(defaultClient.metadata.providerMetadata.name).toEqual(provider.metadata.name);
-      expect(domainSpecificClient.metadata.providerMetadata.name).toEqual(fakeProvider.metadata.name);
+      expect(defaultProvider).toEqual(provider);
+      expect(domainSpecificProvider).toEqual(fakeProvider);
     });
 
     it('should bind a new provider to existing clients in a matching domain', () => {