feat: Support for providing custom contexts (#313)

**Requirements**

- [X] I have added test coverage for new or changed functionality
- [X] I have followed the repository's [pull request submission
guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)
- [ ] I have validated my changes against all supported platform
versions

_How do I validate my changes against all supported platform versions?_

**Related issues**

#127 

**Describe the solution you've provided**

This PR enables developers to provide a custom React Context to the
React SDK along-side a pre-initialized LDClient object. This allows
applications to create one client per environment and/or project and
create a unique React Context that corresponds with each client.

Also, in a microfrontend situation where multiple independent React
applications are loaded on the same page, this custom React Context
feature would allow a parent application to create the client and
associated React Context. Then any child application loaded on the page
could leverage those existing client and context objects.

Here's an example of how the React Contexts can be used together:
```javascript
      <LDProvider1>
        <LDProvider2>
          <CustomContext1.Consumer>
            {({ flags }) => {
              return (
                <>
                  <span>consumer 1, flag 1 is {safeValue(flags.context1TestFlag)}</span>
                  <span>consumer 1, flag 2 is {safeValue(flags.context2TestFlag)}</span>
                </>
              );
            }}
          </CustomContext1.Consumer>
          <CustomContext2.Consumer>
            {({ flags }) => {
              return (
                <>
                  <span>consumer 2, flag 1 is {safeValue(flags.context1TestFlag)}</span>
                  <span>consumer 2, flag 2 is {safeValue(flags.context2TestFlag)}</span>
                </>
              );
            }}
          </CustomContext2.Consumer>
        </LDProvider2>
      </LDProvider1>
```

**Describe alternatives you've considered**

I am unaware of alternatives to providing a custom React context into
the library because this library creates its own context at runtime.

**Additional context**

Co-authored-by: Ryan Lamb <[email protected]>

Author: drewpc

src/asyncWithLDProvider.test.tsx

@@ -2,14 +2,13 @@ import React from 'react';
 import '@testing-library/dom';
 import '@testing-library/jest-dom';
 import { render } from '@testing-library/react';
-import { initialize, LDContext, LDFlagChangeset, LDOptions } from 'launchdarkly-js-client-sdk';
+import { initialize, LDClient, LDContext, LDFlagChangeset, LDOptions } from 'launchdarkly-js-client-sdk';
 import { AsyncProviderConfig, LDReactOptions } from './types';
-import { Consumer } from './context';
+import { Consumer, reactSdkContextFactory } from './context';
 import asyncWithLDProvider from './asyncWithLDProvider';
 import wrapperOptions from './wrapperOptions';
 import { fetchFlags } from './utils';
 
-
 jest.mock('launchdarkly-js-client-sdk', () => {
   const actual = jest.requireActual('launchdarkly-js-client-sdk');
 
@@ -351,4 +350,120 @@ describe('asyncWithLDProvider', () => {
 
     expect(receivedNode).toHaveTextContent('{"testFlag":false}');
   });
+
+  test('custom context is provided to consumer', async () => {
+    const CustomContext = reactSdkContextFactory();
+    const customLDClient = {
+      on: jest.fn((_: string, cb: () => void) => {
+        cb();
+      }),
+      off: jest.fn(),
+      allFlags: jest.fn().mockReturnValue({ 'context-test-flag': true }),
+      variation: jest.fn((_: string, v) => v),
+      waitForInitialization: jest.fn(),
+    };
+    const config: AsyncProviderConfig = {
+      clientSideID,
+      ldClient: customLDClient as unknown as LDClient,
+      reactOptions: {
+        reactContext: CustomContext,
+      },
+    };
+    const originalUtilsModule = jest.requireActual('./utils');
+    mockFetchFlags.mockImplementation(originalUtilsModule.fetchFlags);
+
+    const LDProvider = await asyncWithLDProvider(config);
+    const LaunchDarklyApp = (
+      <LDProvider>
+        <CustomContext.Consumer>
+          {({ flags }) => {
+            return (
+              <span>
+                flag is {flags.contextTestFlag === undefined ? 'undefined' : JSON.stringify(flags.contextTestFlag)}
+              </span>
+            );
+          }}
+        </CustomContext.Consumer>
+      </LDProvider>
+    );
+
+    const { findByText } = render(LaunchDarklyApp);
+    expect(await findByText('flag is true')).not.toBeNull();
+
+    const receivedNode = await renderWithConfig({ clientSideID });
+    expect(receivedNode).not.toHaveTextContent('{"contextTestFlag":true}');
+  });
+
+  test('multiple providers', async () => {
+    const customLDClient1 = {
+      on: jest.fn((_: string, cb: () => void) => {
+        cb();
+      }),
+      off: jest.fn(),
+      allFlags: jest.fn().mockReturnValue({ 'context1-test-flag': true }),
+      variation: jest.fn((_: string, v) => v),
+      waitForInitialization: jest.fn(),
+    };
+    const customLDClient2 = {
+      on: jest.fn((_: string, cb: () => void) => {
+        cb();
+      }),
+      off: jest.fn(),
+      allFlags: jest.fn().mockReturnValue({ 'context2-test-flag': true }),
+      variation: jest.fn((_: string, v) => v),
+      waitForInitialization: jest.fn(),
+    };
+    const originalUtilsModule = jest.requireActual('./utils');
+    mockFetchFlags.mockImplementation(originalUtilsModule.fetchFlags);
+
+    const CustomContext1 = reactSdkContextFactory();
+    const LDProvider1 = await asyncWithLDProvider({
+      clientSideID,
+      ldClient: customLDClient1 as unknown as LDClient,
+      reactOptions: {
+        reactContext: CustomContext1,
+      },
+    });
+    const CustomContext2 = reactSdkContextFactory();
+    const LDProvider2 = await asyncWithLDProvider({
+      clientSideID,
+      ldClient: customLDClient2 as unknown as LDClient,
+      reactOptions: {
+        reactContext: CustomContext2,
+      },
+    });
+    const safeValue = (val?: boolean) => (val === undefined ? 'undefined' : JSON.stringify(val));
+    const LaunchDarklyApp = (
+      <LDProvider1>
+        <LDProvider2>
+          <CustomContext1.Consumer>
+            {({ flags }) => {
+              return (
+                <>
+                  <span>consumer 1, flag 1 is {safeValue(flags.context1TestFlag)}</span>
+                  <span>consumer 1, flag 2 is {safeValue(flags.context2TestFlag)}</span>
+                </>
+              );
+            }}
+          </CustomContext1.Consumer>
+          <CustomContext2.Consumer>
+            {({ flags }) => {
+              return (
+                <>
+                  <span>consumer 2, flag 1 is {safeValue(flags.context1TestFlag)}</span>
+                  <span>consumer 2, flag 2 is {safeValue(flags.context2TestFlag)}</span>
+                </>
+              );
+            }}
+          </CustomContext2.Consumer>
+        </LDProvider2>
+      </LDProvider1>
+    );
+
+    const { findByText } = render(LaunchDarklyApp);
+    expect(await findByText('consumer 1, flag 1 is true')).not.toBeNull();
+    expect(await findByText('consumer 1, flag 2 is undefined')).not.toBeNull();
+    expect(await findByText('consumer 2, flag 1 is undefined')).not.toBeNull();
+    expect(await findByText('consumer 2, flag 2 is true')).not.toBeNull();
+  });
 });

src/asyncWithLDProvider.tsx

@@ -1,7 +1,6 @@
 import React, { useState, useEffect, ReactNode } from 'react';
 import { initialize, LDFlagChangeset } from 'launchdarkly-js-client-sdk';
 import { AsyncProviderConfig, defaultReactOptions } from './types';
-import { Provider } from './context';
 import { fetchFlags, getContextOrUser, getFlattenedFlagsFromChangeset } from './utils';
 import getFlagsProxy from './getFlagsProxy';
 import wrapperOptions from './wrapperOptions';
@@ -104,7 +103,9 @@ export default async function asyncWithLDProvider(config: AsyncProviderConfig) {
     // unproxiedFlags is for internal use only. Exclude it from context.
     const { unproxiedFlags: _, ...rest } = ldData;
 
-    return <Provider value={rest}>{children}</Provider>;
+    const { reactContext } = reactOptions;
+
+    return <reactContext.Provider value={rest}>{children}</reactContext.Provider>;
   };
 
   return LDProvider;

src/context.ts

@@ -1,41 +1,17 @@
 import { createContext } from 'react';
-import { LDClient, LDFlagSet } from 'launchdarkly-js-client-sdk';
-import { LDFlagKeyMap } from './types';
+import { ReactSdkContext } from './types';
 
 /**
- * The sdk context stored in the Provider state and passed to consumers.
+ * `reactSdkContextFactory` is a function useful for creating a React context for use with
+ * all the providers and consumers in this library.
+ *
+ * @return a React Context
  */
-interface ReactSdkContext {
-  /**
-   * JavaScript proxy that will trigger a LDClient#variation call on flag read in order
-   * to register a flag evaluation event in LaunchDarkly. Empty {} initially
-   * until flags are fetched from the LaunchDarkly servers.
-   */
-  flags: LDFlagSet;
-
-  /**
-   * Map of camelized flag keys to their original unmodified form. Empty if useCamelCaseFlagKeys option is false.
-   */
-  flagKeyMap: LDFlagKeyMap;
-
-  /**
-   * An instance of `LDClient` from the LaunchDarkly JS SDK (`launchdarkly-js-client-sdk`).
-   * This will be be undefined initially until initialization is complete.
-   *
-   * @see https://docs.launchdarkly.com/sdk/client-side/javascript
-   */
-  ldClient?: LDClient;
-
-  /**
-   * LaunchDarkly client initialization error, if there was one.
-   */
-  error?: Error;
-}
-
+const reactSdkContextFactory = () => createContext<ReactSdkContext>({ flags: {}, flagKeyMap: {}, ldClient: undefined });
 /**
  * @ignore
  */
-const context = createContext<ReactSdkContext>({ flags: {}, flagKeyMap: {}, ldClient: undefined });
+const context = reactSdkContextFactory();
 const {
   /**
    * @ignore
@@ -47,5 +23,5 @@ const {
   Consumer,
 } = context;
 
-export { Provider, Consumer, ReactSdkContext };
+export { Provider, Consumer, ReactSdkContext, reactSdkContextFactory };
 export default context;

src/getFlagsProxy.test.ts

@@ -13,7 +13,7 @@ const camelizedFlags: LDFlagSet = {
 };
 
 // cast as unknown first to be able to partially mock ldClient
-const ldClient = ({ variation: jest.fn((flagKey) => rawFlags[flagKey] as string) } as unknown) as LDClient;
+const ldClient = { variation: jest.fn((flagKey) => rawFlags[flagKey] as string) } as unknown as LDClient;
 
 beforeEach(jest.clearAllMocks);
 

src/index.ts

@@ -6,13 +6,15 @@ import useFlags from './useFlags';
 import useLDClient from './useLDClient';
 import useLDClientError from './useLDClientError';
 import { camelCaseKeys } from './utils';
+import { reactSdkContextFactory } from './context';
 
 export * from './types';
 
 export {
   LDProvider,
   asyncWithLDProvider,
   camelCaseKeys,
+  reactSdkContextFactory,
   useFlags,
   useLDClient,
   useLDClientError,

src/provider.test.tsx

@@ -16,13 +16,21 @@ jest.mock('./utils', () => {
     fetchFlags: jest.fn(),
   };
 });
-jest.mock('./context', () => ({ Provider: 'Provider' }));
+jest.mock('./context', () => {
+  const originalModule = jest.requireActual('./context');
+
+  return {
+    ...originalModule,
+    Provider: 'Provider',
+  };
+});
 
 import React, { Component } from 'react';
+import { render } from '@testing-library/react';
 import { create } from 'react-test-renderer';
 import { initialize, LDClient, LDContext, LDFlagChangeset, LDOptions } from 'launchdarkly-js-client-sdk';
 import { LDReactOptions, EnhancedComponent, ProviderConfig } from './types';
-import { ReactSdkContext as HocState } from './context';
+import { ReactSdkContext as HocState, reactSdkContextFactory } from './context';
 import LDProvider from './provider';
 import { fetchFlags } from './utils';
 import wrapperOptions from './wrapperOptions';
@@ -126,7 +134,7 @@ describe('LDProvider', () => {
 
   test('ld client is used if passed in', async () => {
     options = { ...options, bootstrap: {} };
-    const ldClient = (mockLDClient as unknown) as LDClient;
+    const ldClient = mockLDClient as unknown as LDClient;
     mockInitialize.mockClear();
     const props: ProviderConfig = { clientSideID, ldClient };
     const LaunchDarklyApp = (
@@ -144,7 +152,7 @@ describe('LDProvider', () => {
     const context2: LDContext = { key: 'launch', kind: 'user', name: 'darkly' };
     options = { ...options, bootstrap: {} };
     const ldClient = new Promise<LDClient>((resolve) => {
-      resolve((mockLDClient as unknown) as LDClient);
+      resolve(mockLDClient as unknown as LDClient);
 
       return;
     });
@@ -537,4 +545,43 @@ describe('LDProvider', () => {
       flagKeyMap: { testFlag: 'test-flag' },
     });
   });
+
+  test('custom context is provided to consumer', async () => {
+    const CustomContext = reactSdkContextFactory();
+    const customLDClient = {
+      on: jest.fn((_: string, cb: () => void) => {
+        cb();
+      }),
+      off: jest.fn(),
+      allFlags: jest.fn().mockReturnValue({ 'context-test-flag': true }),
+      variation: jest.fn((_: string, v) => v),
+      waitForInitialization: jest.fn(),
+    };
+    const props: ProviderConfig = {
+      clientSideID,
+      ldClient: customLDClient as unknown as LDClient,
+      reactOptions: {
+        reactContext: CustomContext,
+      },
+    };
+    const originalUtilsModule = jest.requireActual('./utils');
+    mockFetchFlags.mockImplementation(originalUtilsModule.fetchFlags);
+
+    const LaunchDarklyApp = (
+      <LDProvider {...props}>
+        <CustomContext.Consumer>
+          {({ flags }) => {
+            return (
+              <span>
+                flag is {flags.contextTestFlag === undefined ? 'undefined' : JSON.stringify(flags.contextTestFlag)}
+              </span>
+            );
+          }}
+        </CustomContext.Consumer>
+      </LDProvider>
+    );
+
+    const { findByText } = render(LaunchDarklyApp);
+    expect(await findByText('flag is true')).not.toBeNull();
+  });
 });

src/provider.tsx

@@ -1,7 +1,6 @@
 import React, { Component, PropsWithChildren } from 'react';
 import { initialize, LDClient, LDFlagChangeset, LDFlagSet } from 'launchdarkly-js-client-sdk';
 import { EnhancedComponent, ProviderConfig, defaultReactOptions, LDReactOptions } from './types';
-import { Provider } from './context';
 import { camelCaseKeys, fetchFlags, getContextOrUser, getFlattenedFlagsFromChangeset } from './utils';
 import getFlagsProxy from './getFlagsProxy';
 import wrapperOptions from './wrapperOptions';
@@ -144,7 +143,13 @@ class LDProvider extends Component<PropsWithChildren<ProviderConfig>, ProviderSt
   render() {
     const { flags, flagKeyMap, ldClient, error } = this.state;
 
-    return <Provider value={{ flags, flagKeyMap, ldClient, error }}>{this.props.children}</Provider>;
+    const { reactContext } = this.getReactOptions();
+
+    return (
+      <reactContext.Provider value={{ flags, flagKeyMap, ldClient, error }}>
+        {this.props.children}
+      </reactContext.Provider>
+    );
   }
 }