Expose creating new instances instead of an isolated singleton

Author: MattIPv4

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

@@ -39,7 +39,7 @@ export function useContextMutator(options: ContextMutationOptions = { defaultCon
     async (
       updatedContext: EvaluationContext | ((currentContext: EvaluationContext) => EvaluationContext),
     ): Promise<void> => {
-      // TODO: Needs to handle `isolated` option like OpenFeatureProvider
+      // TODO: Needs to handle `openfeature` option like OpenFeatureProvider
       const previousContext = OpenFeature.getContext(options?.defaultContext ? undefined : domain);
       const resolvedContext = typeof updatedContext === 'function' ? updatedContext(previousContext) : updatedContext;
 

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';
@@ -12,10 +12,10 @@ type ClientOrDomain =
        */
       domain?: string;
       /**
-       * If the package-local isolated OpenFeature singleton should be used
-       * @see OpenFeature.isolated for more details.
+       * An instance of the OpenFeature API to use.
+       * @see OpenFeature.getIsolated for more details.
        */
-      isolated?: boolean;
+      openfeature?: OpenFeatureAPI;
       client?: never;
     }
   | {
@@ -24,7 +24,7 @@ type ClientOrDomain =
        */
       client?: Client;
       domain?: never;
-      isolated?: never;
+      openfeature?: never;
     };
 
 type ProviderProps = {
@@ -37,11 +37,8 @@ type ProviderProps = {
  * @param {ProviderProps} properties props for the context provider
  * @returns {OpenFeatureProvider} context provider
  */
-export function OpenFeatureProvider({ client, domain, isolated, children, ...options }: ProviderProps) {
-  const stableClient = React.useMemo(
-    () => client || (isolated ? OpenFeature.isolated : OpenFeature).getClient(domain),
-    [client, domain],
-  );
+export function OpenFeatureProvider({ client, domain, openfeature, children, ...options }: ProviderProps) {
+  const stableClient = React.useMemo(() => client || (openfeature ?? OpenFeature).getClient(domain), [client, domain]);
 
   return <Context.Provider value={{ client: stableClient, options, domain }}>{children}</Context.Provider>;
 }

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

@@ -87,7 +87,7 @@ export function OpenFeatureTestProvider(testProviderOptions: TestProviderProps)
   const effectiveProvider = (
     flagValueMap ? new TestProvider(flagValueMap, testProviderOptions.delayMs) : mixInNoop(provider) || NOOP_PROVIDER
   ) as Provider;
-  // TODO: Needs to handle `isolated` option like OpenFeatureProvider
+  // TODO: Needs to handle `openfeature` option like OpenFeatureProvider
   testProviderOptions.domain
     ? OpenFeature.setProvider(testProviderOptions.domain, effectiveProvider)
     : OpenFeature.setProvider(effectiveProvider);

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

@@ -17,6 +17,6 @@ export function useOpenFeatureProvider(): Provider {
     throw new MissingContextError('No OpenFeature context available');
   }
 
-  // TODO: Needs to handle `isolated` option like OpenFeatureProvider
+  // TODO: Needs to handle `openfeature` option like OpenFeatureProvider
   return OpenFeature.getProvider(openFeatureContext.domain);
 }

packages/web/src/open-feature.ts

@@ -19,7 +19,6 @@ type DomainRecord = {
 };
 
 const _globalThis = globalThis as OpenFeatureGlobal;
-const _localThis = {} as OpenFeatureGlobal;
 
 export class OpenFeatureAPI
   extends OpenFeatureCommonAPI<ClientProviderStatus, Provider, Hook>
@@ -40,21 +39,23 @@ export class OpenFeatureAPI
   }
 
   /**
-   * Gets a singleton instance of the OpenFeature API.
+   * Gets a instance of the OpenFeature API.
    * @ignore
-   * @param {boolean} global Whether to get the global (window) singleton instance or a package-local singleton instance.
+   * @param {boolean} singleton Whether to get the global (window) singleton instance or an isolated non-singleton instance.
    * @returns {OpenFeatureAPI} OpenFeature API
    */
-  static getInstance(global = true): OpenFeatureAPI {
-    const store = global ? _globalThis : _localThis;
+  static getInstance(singleton = true): OpenFeatureAPI {
+    if (!singleton) {
+      return new OpenFeatureAPI();
+    }
 
-    const globalApi = store[GLOBAL_OPENFEATURE_API_KEY];
+    const globalApi = _globalThis[GLOBAL_OPENFEATURE_API_KEY];
     if (globalApi) {
       return globalApi;
     }
 
     const instance = new OpenFeatureAPI();
-    store[GLOBAL_OPENFEATURE_API_KEY] = instance;
+    _globalThis[GLOBAL_OPENFEATURE_API_KEY] = instance;
     return instance;
   }
 
@@ -427,55 +428,53 @@ export class OpenFeatureAPI
 
 interface OpenFeatureAPIWithIsolated extends OpenFeatureAPI {
   /**
-   * A package-local singleton instance of the OpenFeature API.
+   * 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 `isolated` property provides access to a package-local singleton instance of the OpenFeature API,
-   * which is not shared globally, isolated from the global singleton. As such, it will not share domains, providers,
-   * etc., with the global singleton instance, and uses its own version of the SDK.
-   *
-   * The `isolated` property 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.
-   * However, it is still a singleton within the package though, so it will share state with other uses of the
-   * `isolated` instance imported from the same package within the same micro-frontend.
+   * 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
-   * OpenFeature.isolated.setProvider(new MyIsolatedProvider()); // Sets the provider for the default domain on the isolated instance
-   *
    * const globalClient = OpenFeature.getClient(); // Uses MyGlobalProvider, the provider for the default domain on the global instance
-   * const isolatedClient = OpenFeature.isolated.getClient(); // Uses MyIsolatedProvider, the provider for the default domain on the isolated 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 = OpenFeature.isolated.getClient(); // Uses MyIsolatedProvider, 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
+   *
+   * 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 isolatedClient = OpenFeature.isolated.getClient(); // Returns the NOOP provider, as this is a different isolated 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
    */
-  readonly isolated: OpenFeatureAPI;
+  getIsolated: () => OpenFeatureAPI;
 }
 
-const createOpenFeatureAPI = (): OpenFeatureAPIWithIsolated => {
-  const globalInstance = OpenFeatureAPI.getInstance();
-  const localInstance = OpenFeatureAPI.getInstance(false);
-
-  return Object.assign(globalInstance, {
-    get isolated() {
-      return localInstance;
+const createOpenFeatureAPI = (): OpenFeatureAPIWithIsolated =>
+  Object.assign(OpenFeatureAPI.getInstance(), {
+    getIsolated() {
+      return OpenFeatureAPI.getInstance(false);
     },
   });
-};
 
 /**
  * A singleton instance of the OpenFeature API.

packages/web/test/isolated.spec.ts

@@ -51,16 +51,22 @@ describe('OpenFeature', () => {
     expect(_globalThis[GLOBAL_OPENFEATURE_API_KEY]).toBe(firstInstance);
   });
 
-  describe('OpenFeature.isolated', () => {
+  describe('OpenFeature.getIsolated', () => {
     it('should not be the same instance as the global singleton', async () => {
       const { OpenFeature } = await import('../src');
 
-      expect(OpenFeature.isolated).not.toBe(OpenFeature);
+      expect(OpenFeature.getIsolated()).not.toBe(OpenFeature);
+    });
+
+    it('should not be the same instance as another isolated instance', async () => {
+      const { OpenFeature } = await import('../src');
+
+      expect(OpenFeature.getIsolated()).not.toBe(OpenFeature.getIsolated());
     });
 
     it('should not share state between global and isolated instances', async () => {
       const { OpenFeature, NOOP_PROVIDER } = await import('../src');
-      const isolatedInstance = OpenFeature.isolated;
+      const isolatedInstance = OpenFeature.getIsolated();
 
       const globalProvider = new MockProvider({ name: 'global-provider' });
       OpenFeature.setProvider(globalProvider);
@@ -75,20 +81,22 @@ describe('OpenFeature', () => {
       expect(isolatedInstance.getProvider()).toBe(isolatedProvider);
     });
 
-    it('should persist when imported multiple times', async () => {
-      const firstIsolatedInstance = (await import('../src')).OpenFeature.isolated;
-      const secondIsolatedInstance = (await import('../src')).OpenFeature.isolated;
+    it('should not share state between two isolated instances', async () => {
+      const { OpenFeature, NOOP_PROVIDER } = await import('../src');
+      const isolatedInstanceOne = OpenFeature.getIsolated();
+      const isolatedInstanceTwo = OpenFeature.getIsolated();
 
-      expect(firstIsolatedInstance).toBe(secondIsolatedInstance);
-    });
+      const isolatedProviderOne = new MockProvider({ name: 'isolated-provider-one' });
+      isolatedInstanceOne.setProvider(isolatedProviderOne);
 
-    it('should not persist via globalThis (window in browsers)', async () => {
-      const firstIsolatedInstance = (await import('../src')).OpenFeature.isolated;
+      expect(isolatedInstanceOne.getProvider()).toBe(isolatedProviderOne);
+      expect(isolatedInstanceTwo.getProvider()).toBe(NOOP_PROVIDER);
 
-      jest.resetModules();
-      const secondIsolatedInstance = (await import('../src')).OpenFeature.isolated;
+      const isolatedProviderTwo = new MockProvider({ name: 'isolated-provider-two' });
+      isolatedInstanceTwo.setProvider(isolatedProviderTwo);
 
-      expect(firstIsolatedInstance).not.toBe(secondIsolatedInstance);
+      expect(isolatedInstanceOne.getProvider()).toBe(isolatedProviderOne);
+      expect(isolatedInstanceTwo.getProvider()).toBe(isolatedProviderTwo);
     });
   });
 });