Provide a local singleton of OpenFeatureAPI

Signed-off-by: MattIPv4 <[email protected]>

Author: MattIPv4

packages/web/src/open-feature.ts

@@ -28,6 +28,7 @@ type DomainRecord = {
 };
 
 const _globalThis = globalThis as OpenFeatureGlobal;
+const _localThis = {} as OpenFeatureGlobal;
 
 export class OpenFeatureAPI
   extends OpenFeatureCommonAPI<ClientProviderStatus, Provider, Hook>
@@ -50,16 +51,19 @@ export class OpenFeatureAPI
   /**
    * Gets a singleton instance of the OpenFeature API.
    * @ignore
+   * @param {boolean} global Whether to get the global (window) singleton instance or a package-local singleton instance.
    * @returns {OpenFeatureAPI} OpenFeature API
    */
-  static getInstance(): OpenFeatureAPI {
-    const globalApi = _globalThis[GLOBAL_OPENFEATURE_API_KEY];
+  static getInstance(global = true): OpenFeatureAPI {
+    const store = global ? _globalThis : _localThis;
+
+    const globalApi = store[GLOBAL_OPENFEATURE_API_KEY];
     if (globalApi) {
       return globalApi;
     }
 
     const instance = new OpenFeatureAPI();
-    _globalThis[GLOBAL_OPENFEATURE_API_KEY] = instance;
+    store[GLOBAL_OPENFEATURE_API_KEY] = instance;
     return instance;
   }
 
@@ -430,8 +434,60 @@ export class OpenFeatureAPI
   }
 }
 
+interface OpenFeatureAPIWithIsolated extends OpenFeatureAPI {
+  /**
+   * An package-local singleton instance of the OpenFeature API.
+   *
+   * By default, the OpenFeature API is exposed as a global singleton (stored on `window` in browsers) instance.
+   * 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.
+   * This allows different parts of an application to have their own isolated OpenFeature API instances,
+   * avoiding potential conflicts and ensuring they're using the expected version of the SDK.
+   *
+   * HOWEVER, the `isolated` instance is *isolated* to the package, and so will not share domains, providers, etc., with
+   * the global singleton instance. As it is still a singleton within the package though, it will share state with other
+   * uses of the `isolated` instance imported from the same package within the same micro-frontend.
+   * @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
+   *
+   * // In the same micro-frontend, in a different file ...
+   * 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(); // Uses MyIsolatedProvider, the provider for the default domain on the 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
+   */
+  readonly isolated: OpenFeatureAPI;
+}
+
+const createOpenFeatureAPI = (): OpenFeatureAPIWithIsolated => {
+  const globalInstance = OpenFeatureAPI.getInstance();
+  const localInstance = OpenFeatureAPI.getInstance(false);
+
+  return Object.assign(globalInstance, {
+    get isolated() {
+      return localInstance;
+    },
+  });
+};
+
 /**
  * A singleton instance of the OpenFeature API.
- * @returns {OpenFeatureAPI} OpenFeature API
+ * @returns {OpenFeatureAPIWithIsolated} OpenFeature API
  */
-export const OpenFeature = OpenFeatureAPI.getInstance();
+export const OpenFeature = createOpenFeatureAPI();