feat: allow non-singleton access to OpenFeatureAPI

packages/react/src/context/use-context-mutator.ts

@@ -35,6 +35,7 @@ export type ContextMutation = {
 export function useContextMutator(options: ContextMutationOptions = { defaultContext: false }): ContextMutation {
   const { client } = useContext(Context) || {};
   const domain = client?.metadata.domain;
+  const sdk = client?.metadata.sdk || OpenFeature;
 
   // TODO: Replace this warning with a thrown error in a future major release,
   //       to match the behavior of `useOpenFeatureProvider` + `useOpenFeatureClient`,
@@ -60,14 +61,14 @@ export function useContextMutator(options: ContextMutationOptions = { defaultCon
     async (
       updatedContext: EvaluationContext | ((currentContext: EvaluationContext) => EvaluationContext),
     ): Promise<void> => {
-      const previousContext = OpenFeature.getContext(options?.defaultContext ? undefined : domain);
+      const previousContext = sdk.getContext(options?.defaultContext ? undefined : domain);
       const resolvedContext = typeof updatedContext === 'function' ? updatedContext(previousContext) : updatedContext;
 
       if (previousContext !== resolvedContext) {
         if (!domain || options?.defaultContext) {
-          await OpenFeature.setContext(resolvedContext);
+          await sdk.setContext(resolvedContext);
         } else {
-          await OpenFeature.setContext(domain, resolvedContext);
+          await sdk.setContext(domain, resolvedContext);
         }
       }
     },

packages/react/src/provider/provider.tsx

@@ -1,4 +1,4 @@
-import type { Client } from '@openfeature/web-sdk';
+import type { Client, OpenFeatureAPI } from '@openfeature/web-sdk';
 import { OpenFeature } from '@openfeature/web-sdk';
 import * as React from 'react';
 import type { ReactFlagEvaluationOptions } from '../options';
@@ -11,6 +11,11 @@ type ClientOrDomain =
        * @see OpenFeature.setProvider() and overloads.
        */
       domain?: string;
+      /**
+       * An instance of the OpenFeature API to use.
+       * @see OpenFeature.getIsolated for more details.
+       */
+      sdk?: OpenFeatureAPI;
       client?: never;
     }
   | {
@@ -19,6 +24,7 @@ type ClientOrDomain =
        */
       client?: Client;
       domain?: never;
+      sdk?: never;
     };
 
 type ProviderProps = {
@@ -31,8 +37,8 @@ type ProviderProps = {
  * @param {ProviderProps} properties props for the context provider
  * @returns {OpenFeatureProvider} context provider
  */
-export function OpenFeatureProvider({ client, domain, children, ...options }: ProviderProps) {
-  const stableClient = React.useMemo(() => client || OpenFeature.getClient(domain), [client, domain]);
+export function OpenFeatureProvider({ client, domain, sdk, children, ...options }: ProviderProps) {
+  const stableClient = React.useMemo(() => client || (sdk ?? OpenFeature).getClient(domain), [client, domain]);
 
   return <Context.Provider value={{ client: stableClient, options }}>{children}</Context.Provider>;
 }

packages/react/src/provider/test-provider.tsx

@@ -83,16 +83,16 @@ class TestProvider extends InMemoryProvider {
  * @returns {OpenFeatureProvider} OpenFeatureTestProvider
  */
 export function OpenFeatureTestProvider(testProviderOptions: TestProviderProps) {
-  const { flagValueMap, provider } = testProviderOptions;
+  const { flagValueMap, provider, sdk } = testProviderOptions;
   const effectiveProvider = (
     flagValueMap ? new TestProvider(flagValueMap, testProviderOptions.delayMs) : mixInNoop(provider) || NOOP_PROVIDER
   ) as Provider;
   testProviderOptions.domain
-    ? OpenFeature.setProvider(testProviderOptions.domain, effectiveProvider)
-    : OpenFeature.setProvider(effectiveProvider);
+    ? (sdk ?? OpenFeature).setProvider(testProviderOptions.domain, effectiveProvider)
+    : (sdk ?? OpenFeature).setProvider(effectiveProvider);
 
   return (
-    <OpenFeatureProvider {...(testProviderOptions as NormalizedOptions)} domain={testProviderOptions.domain}>
+    <OpenFeatureProvider {...(testProviderOptions as NormalizedOptions)} sdk={sdk} domain={testProviderOptions.domain}>
       {testProviderOptions.children}
     </OpenFeatureProvider>
   );

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

@@ -17,5 +17,5 @@ export function useOpenFeatureProvider(): Provider {
     throw new MissingContextError('No OpenFeature context available');
   }
 
-  return OpenFeature.getProvider(openFeatureContext.client.metadata.domain);
+  return (openFeatureContext.client.metadata.sdk ?? OpenFeature).getProvider(openFeatureContext.client.metadata.domain);
 }

packages/react/test/provider.spec.tsx

@@ -11,6 +11,7 @@ import {
   useStringFlagValue,
 } from '../src';
 import { TestingProvider } from './test.utils';
+import { useOpenFeatureProvider } from '../src/provider/use-open-feature-provider';
 
 describe('OpenFeatureProvider', () => {
   /**
@@ -53,6 +54,7 @@ describe('OpenFeatureProvider', () => {
 
   beforeEach(async () => {
     await OpenFeature.clearContexts();
+    await OpenFeature.clearProviders();
   });
 
   describe('useOpenFeatureClient', () => {
@@ -99,6 +101,43 @@ describe('OpenFeatureProvider', () => {
     });
   });
 
+  describe('useOpenFeatureProvider', () => {
+    const DOMAIN = 'useOpenFeatureProvider';
+
+    it('should return provider from the global singleton when no SDK is specified', () => {
+      const provider = new InMemoryProvider();
+      OpenFeature.setProvider(DOMAIN, provider);
+
+      const wrapper = ({ children }: Parameters<typeof OpenFeatureProvider>[0]) => (
+        <OpenFeatureProvider domain={DOMAIN}>{children}</OpenFeatureProvider>
+      );
+
+      const { result } = renderHook(() => useOpenFeatureProvider(), { wrapper });
+
+      expect(result.current).toEqual(provider);
+    });
+
+    it('should return provider from the specified SDK when one is provided', () => {
+      const provider = new InMemoryProvider();
+      OpenFeature.setProvider(DOMAIN, provider);
+
+      const isolatedInstance = OpenFeature.getIsolated();
+      const isolatedProvider = new InMemoryProvider();
+      isolatedInstance.setProvider(DOMAIN, isolatedProvider);
+
+      const wrapper = ({ children }: Parameters<typeof OpenFeatureProvider>[0]) => (
+        <OpenFeatureProvider sdk={isolatedInstance} domain={DOMAIN}>
+          {children}
+        </OpenFeatureProvider>
+      );
+
+      const { result } = renderHook(() => useOpenFeatureProvider(), { wrapper });
+
+      expect(result.current).toEqual(isolatedProvider);
+      expect(result.current).not.toEqual(provider);
+    });
+  });
+
   describe('useWhenProviderReady', () => {
     describe('suspendUntilReady=true (default)', () => {
       it('should suspend until ready and then return provider status', async () => {
@@ -165,6 +204,7 @@ describe('OpenFeatureProvider', () => {
       });
     });
   });
+
   describe('useMutateContext', () => {
     const MutateButton = ({ setter }: { setter?: (prevContext: EvaluationContext) => EvaluationContext }) => {
       const { setContext } = useContextMutator();

packages/react/test/test-provider.spec.tsx

@@ -2,7 +2,7 @@ import type { Provider, ResolutionDetails } from '@openfeature/web-sdk';
 import '@testing-library/jest-dom'; // see: https://testing-library.com/docs/react-testing-library/setup
 import { render, screen } from '@testing-library/react';
 import * as React from 'react';
-import { OpenFeatureTestProvider, useFlag } from '../src';
+import { OpenFeature, OpenFeatureTestProvider, useFlag } from '../src';
 
 const FLAG_KEY = 'thumbs';
 
@@ -17,6 +17,11 @@ function TestComponent(props: { suspend: boolean }) {
 }
 
 describe('OpenFeatureTestProvider', () => {
+  beforeEach(async () => {
+    await OpenFeature.clearContexts();
+    await OpenFeature.clearProviders();
+  });
+
   describe('no args', () => {
     it('renders default', async () => {
       render(
@@ -128,4 +133,25 @@ describe('OpenFeatureTestProvider', () => {
       });
     });
   });
+
+  describe('sdk and flagValueMap set', () => {
+    it('uses the sdk provided', async () => {
+      const sdk = OpenFeature.getIsolated();
+
+      render(
+        <OpenFeatureTestProvider sdk={sdk} flagValueMap={{ [FLAG_KEY]: true }}>
+          <TestComponent suspend={false} />
+        </OpenFeatureTestProvider>,
+      );
+
+      expect(sdk.getClient().getBooleanDetails(FLAG_KEY, false)).toMatchObject({
+        value: true,
+        reason: 'STATIC',
+      });
+      expect(OpenFeature.getClient().getBooleanDetails(FLAG_KEY, false)).toMatchObject({
+        value: false,
+        reason: 'ERROR',
+      });
+    });
+  });
 });

packages/web/src/client/client.ts

@@ -3,10 +3,15 @@ import type { Features } from '../evaluation';
 import type { ProviderStatus } from '../provider';
 import type { ProviderEvents } from '../events';
 import type { Tracking } from '../tracking';
+import type { OpenFeatureAPI } from '../open-feature';
+
+export interface ClientMetadataWithSDK extends ClientMetadata {
+  readonly sdk?: OpenFeatureAPI;
+}
 
 export interface Client
   extends EvaluationLifeCycle<Client>, Features, ManageLogger<Client>, Eventing<ProviderEvents>, Tracking {
-  readonly metadata: ClientMetadata;
+  readonly metadata: ClientMetadataWithSDK;
   /**
    * Returns the status of the associated provider.
    */

packages/web/src/client/internal/open-feature-client.ts

@@ -1,5 +1,4 @@
 import type {
-  ClientMetadata,
   EvaluationContext,
   EvaluationDetails,
   EventHandler,
@@ -30,7 +29,8 @@ import type { InternalEventEmitter } from '../../events/internal/internal-event-
 import type { Hook } from '../../hooks';
 import type { Provider } from '../../provider';
 import { ProviderStatus } from '../../provider';
-import type { Client } from './../client';
+import type { Client, ClientMetadataWithSDK } from './../client';
+import type { OpenFeatureAPI } from '../../open-feature';
 
 type OpenFeatureClientOptions = {
   /**
@@ -39,6 +39,7 @@ type OpenFeatureClientOptions = {
   name?: string;
   domain?: string;
   version?: string;
+  sdk?: OpenFeatureAPI;
 };
 
 /**
@@ -62,12 +63,13 @@ export class OpenFeatureClient implements Client {
     private readonly options: OpenFeatureClientOptions,
   ) {}
 
-  get metadata(): ClientMetadata {
+  get metadata(): ClientMetadataWithSDK {
     return {
       // Use domain if name is not provided
       name: this.options.domain ?? this.options.name,
       domain: this.options.domain ?? this.options.name,
       version: this.options.version,
+      sdk: this.options.sdk,
       providerMetadata: this.providerAccessor().metadata,
     };
   }

packages/web/src/open-feature.ts

@@ -39,11 +39,16 @@ export class OpenFeatureAPI
   }
 
   /**
-   * Gets a singleton instance of the OpenFeature API.
+   * Gets a instance of the OpenFeature API.
    * @ignore
+   * @param {boolean} singleton Whether to get the global (window) singleton instance or an isolated non-singleton instance.
    * @returns {OpenFeatureAPI} OpenFeature API
    */
-  static getInstance(): OpenFeatureAPI {
+  static getInstance(singleton = true): OpenFeatureAPI {
+    if (!singleton) {
+      return new OpenFeatureAPI();
+    }
+
     const globalApi = _globalThis[GLOBAL_OPENFEATURE_API_KEY];
     if (globalApi) {
       return globalApi;
@@ -357,7 +362,7 @@ export class OpenFeatureAPI
       (domain?: string) => this.getContext(domain),
       () => this.getHooks(),
       () => this._logger,
-      { domain, version },
+      { domain, version, sdk: this },
     );
   }
 
@@ -421,8 +426,58 @@ export class OpenFeatureAPI
   }
 }
 
+interface OpenFeatureAPIWithIsolated extends OpenFeatureAPI {
+  /**
+   * Create a new isolated, non-singleton instance of the OpenFeature API.
+   *
+   * By default, the OpenFeature API is exposed as a global singleton instance (stored on `window` in browsers).
+   * While this can be very convenient as domains, providers, etc., are shared across an entire application,
+   * this can mean that in multi-frontend architectures (e.g. micro-frontends) different parts of an application
+   * can think they're loading different versions of OpenFeature, when they're actually all sharing the same instance.
+   *
+   * The `getIsolated` method allows different parts of a multi-frontend application to have their own isolated
+   * OpenFeature API instances, avoiding potential conflicts and ensuring they're using the expected version of the SDK,
+   * and don't risk colliding with any other usages of OpenFeature on the same page.
+   * @example
+   * import { OpenFeature } from '@openfeature/web-sdk';
+   *
+   * OpenFeature.setProvider(new MyGlobalProvider()); // Sets the provider for the default domain on the global instance
+   * const globalClient = OpenFeature.getClient(); // Uses MyGlobalProvider, the provider for the default domain on the global instance
+   *
+   * export const OpenFeatureIsolated = OpenFeature.getIsolated(); // Create a new isolated instance of the OpenFeature API and export it
+   * OpenFeatureIsolated.setProvider(new MyIsolatedProvider()); // Sets the provider for the default domain on the isolated instance
+   * const isolatedClient = OpenFeatureIsolated.getClient(); // Uses MyIsolatedProvider, the provider for the default domain on the isolated instance
+   *
+   * // In the same micro-frontend, in a different file ...
+   * import { OpenFeature } from '@openfeature/web-sdk';
+   * import { OpenFeatureIsolated } from './other-file';
+   *
+   * const globalClient = OpenFeature.getClient(); // Uses MyGlobalProvider, the provider for the default domain on the global instance
+   * const isolatedClient = OpenFeatureIsolated.getClient(); // Uses MyIsolatedProvider, the provider for the default domain on the isolated instance
+   *
+   * const OpenFeatureIsolatedOther = OpenFeature.getIsolated(); // Create another new isolated instance of the OpenFeature API
+   * const isolatedOtherClient = OpenFeatureIsolatedOther.getClient(); // Uses the NOOP provider, as this is a different isolated instance
+   *
+   * // In another micro-frontend, after the above has executed ...
+   * import { OpenFeature } from '@openfeature/web-sdk';
+   *
+   * const globalClient = OpenFeature.getClient(); // Uses MyGlobalProvider, the provider for the default domain on the global instance
+   *
+   * const OpenFeatureIsolated = OpenFeature.getIsolated(); // Create a new isolated instance of the OpenFeature API
+   * const isolatedClient = OpenFeatureIsolated.getClient(); // Uses the NOOP provider, as this is a different isolated instance
+   */
+  getIsolated: () => OpenFeatureAPI;
+}
+
+const createOpenFeatureAPI = (): OpenFeatureAPIWithIsolated =>
+  Object.assign(OpenFeatureAPI.getInstance(), {
+    getIsolated() {
+      return OpenFeatureAPI.getInstance(false);
+    },
+  });
+
 /**
  * A singleton instance of the OpenFeature API.
- * @returns {OpenFeatureAPI} OpenFeature API
+ * @returns {OpenFeatureAPIWithIsolated} OpenFeature API
  */
-export const OpenFeature = OpenFeatureAPI.getInstance();
+export const OpenFeature = createOpenFeatureAPI();