Merge pull request #79 from launchdarkly/christie/sc-166224/react-sdk-flag-evaluation-events-on-flag

Flag evaluation events on flag read

Author: XieX

src/__snapshots__/provider.test.tsx.snap

@@ -4,6 +4,7 @@ exports[`LDProvider render app 1`] = `
 <Provider
   value={
     Object {
+      "flagKeyMap": Object {},
       "flags": Object {},
       "ldClient": undefined,
     }

src/__snapshots__/withLDProvider.test.tsx.snap

@@ -4,6 +4,7 @@ exports[`withLDProvider render app 1`] = `
 <Provider
   value={
     Object {
+      "flagKeyMap": Object {},
       "flags": Object {},
       "ldClient": undefined,
     }

src/asyncWithLDProvider.test.tsx

@@ -12,18 +12,16 @@ import React from 'react';
 import { render } from '@testing-library/react';
 import { LDFlagChangeset, LDOptions, LDUser } from 'launchdarkly-js-client-sdk';
 import initLDClient from './initLDClient';
-import { fetchFlags } from './utils';
-import { AsyncProviderConfig, defaultReactOptions, LDReactOptions } from './types';
+import { AsyncProviderConfig, LDReactOptions } from './types';
 import { Consumer } from './context';
 import asyncWithLDProvider from './asyncWithLDProvider';
 
 const clientSideID = 'deadbeef';
 const user: LDUser = { key: 'yus', name: 'yus ng' };
 const App = () => <>My App</>;
 const mockInitLDClient = initLDClient as jest.Mock;
-const mockFetchFlags = fetchFlags as jest.Mock;
-const mockFlags = { testFlag: true, anotherTestFlag: true };
-let mockLDClient: { on: jest.Mock };
+const rawFlags = { 'test-flag': true, 'another-test-flag': true };
+let mockLDClient: { on: jest.Mock; off: jest.Mock; variation: jest.Mock };
 
 const renderWithConfig = async (config: AsyncProviderConfig) => {
   const LDProvider = await asyncWithLDProvider(config);
@@ -43,13 +41,15 @@ describe('asyncWithLDProvider', () => {
       on: jest.fn((e: string, cb: () => void) => {
         cb();
       }),
+      off: jest.fn(),
+      // tslint:disable-next-line: no-unsafe-any
+      variation: jest.fn((_: string, v) => v),
     };
 
     mockInitLDClient.mockImplementation(() => ({
       ldClient: mockLDClient,
+      flags: rawFlags,
     }));
-
-    mockFetchFlags.mockReturnValue(mockFlags);
   });
 
   afterEach(() => {
@@ -72,7 +72,7 @@ describe('asyncWithLDProvider', () => {
     const reactOptions: LDReactOptions = { useCamelCaseFlagKeys: false };
     await asyncWithLDProvider({ clientSideID, user, options, reactOptions });
 
-    expect(mockInitLDClient).toHaveBeenCalledWith(clientSideID, user, reactOptions, options, undefined);
+    expect(mockInitLDClient).toHaveBeenCalledWith(clientSideID, user, options, undefined);
   });
 
   test('subscribe to changes on mount', async () => {
@@ -97,17 +97,17 @@ describe('asyncWithLDProvider', () => {
   });
 
   test('subscribe to changes with kebab-case', async () => {
-    mockFetchFlags.mockReturnValue({ 'another-test-flag': true, 'test-flag': true });
     mockInitLDClient.mockImplementation(() => ({
       ldClient: mockLDClient,
+      flags: rawFlags,
     }));
     mockLDClient.on.mockImplementation((e: string, cb: (c: LDFlagChangeset) => void) => {
       cb({ 'another-test-flag': { current: false, previous: true }, 'test-flag': { current: false, previous: true } });
     });
     const receivedNode = await renderWithConfig({ clientSideID, reactOptions: { useCamelCaseFlagKeys: false } });
 
     expect(mockLDClient.on).toHaveBeenNthCalledWith(1, 'change', expect.any(Function));
-    expect(receivedNode).toHaveTextContent('{"another-test-flag":false,"test-flag":false}');
+    expect(receivedNode).toHaveTextContent('{"test-flag":false,"another-test-flag":false}');
   });
 
   test('consecutive flag changes gets stored in context correctly', async () => {
@@ -180,31 +180,31 @@ describe('asyncWithLDProvider', () => {
   });
 
   test('ldClient is initialised correctly with target flags', async () => {
-    mockFetchFlags.mockReturnValue({ devTestFlag: true, launchDoggly: true });
     mockInitLDClient.mockImplementation(() => ({
       ldClient: mockLDClient,
+      flags: rawFlags,
     }));
 
     const options: LDOptions = {};
-    const flags = { 'dev-test-flag': false, 'launch-doggly': false };
+    const flags = { 'test-flag': false };
     const receivedNode = await renderWithConfig({ clientSideID, user, options, flags });
 
-    expect(mockInitLDClient).toHaveBeenCalledWith(clientSideID, user, defaultReactOptions, options, flags);
-    expect(receivedNode).toHaveTextContent('{"devTestFlag":true,"launchDoggly":true}');
+    expect(mockInitLDClient).toHaveBeenCalledWith(clientSideID, user, options, flags);
+    expect(receivedNode).toHaveTextContent('{"testFlag":true}');
   });
 
   test('only updates to subscribed flags are pushed to the Provider', async () => {
-    mockFetchFlags.mockReturnValue({ testFlag: 2 });
     mockInitLDClient.mockImplementation(() => ({
       ldClient: mockLDClient,
+      flags: rawFlags,
     }));
     mockLDClient.on.mockImplementation((e: string, cb: (c: LDFlagChangeset) => void) => {
-      cb({ 'test-flag': { current: 3, previous: 2 }, 'another-test-flag': { current: false, previous: true } });
+      cb({ 'test-flag': { current: false, previous: true }, 'another-test-flag': { current: false, previous: true } });
     });
     const options: LDOptions = {};
-    const subscribedFlags = { 'test-flag': 1 };
+    const subscribedFlags = { 'test-flag': true };
     const receivedNode = await renderWithConfig({ clientSideID, user, options, flags: subscribedFlags });
 
-    expect(receivedNode).toHaveTextContent('{"testFlag":3}');
+    expect(receivedNode).toHaveTextContent('{"testFlag":false}');
   });
 });

src/asyncWithLDProvider.tsx

@@ -1,9 +1,10 @@
 import React, { useState, useEffect, ReactNode } from 'react';
-import { LDFlagSet, LDFlagChangeset } from 'launchdarkly-js-client-sdk';
+import { LDFlagChangeset, LDFlagSet } from 'launchdarkly-js-client-sdk';
 import { AsyncProviderConfig, defaultReactOptions } from './types';
 import { Provider } from './context';
 import initLDClient from './initLDClient';
-import { camelCaseKeys, fetchFlags, getFlattenedFlagsFromChangeset } from './utils';
+import { getFlattenedFlagsFromChangeset } from './utils';
+import getFlagsProxy from './getFlagsProxy';
 
 /**
  * This is an async function which initializes LaunchDarkly's JS SDK (`launchdarkly-js-client-sdk`)
@@ -32,32 +33,43 @@ import { camelCaseKeys, fetchFlags, getFlattenedFlagsFromChangeset } from './uti
 export default async function asyncWithLDProvider(config: AsyncProviderConfig) {
   const { clientSideID, user, flags: targetFlags, options, reactOptions: userReactOptions } = config;
   const reactOptions = { ...defaultReactOptions, ...userReactOptions };
-  const { ldClient } = await initLDClient(clientSideID, user, reactOptions, options, targetFlags);
+  const { ldClient, flags: fetchedFlags } = await initLDClient(clientSideID, user, options, targetFlags);
 
   const LDProvider = ({ children }: { children: ReactNode }) => {
     const [ldData, setLDData] = useState({
-      flags: fetchFlags(ldClient, reactOptions, targetFlags),
-      ldClient,
+      flags: {},
+      unproxiedFlags: {},
+      flagKeyMap: {},
     });
 
     useEffect(() => {
-      if (options) {
-        const { bootstrap } = options;
-        if (bootstrap && bootstrap !== 'localStorage') {
-          const bootstrappedFlags = reactOptions.useCamelCaseFlagKeys ? camelCaseKeys(bootstrap) : bootstrap;
-          setLDData((prev) => ({ ...prev, flags: bootstrappedFlags }));
+      const initialFlags =
+        options?.bootstrap && options.bootstrap !== 'localStorage' ? options.bootstrap : fetchedFlags;
+      setLDData({ unproxiedFlags: initialFlags, ...getFlagsProxy(ldClient, initialFlags, reactOptions, targetFlags) });
+
+      function onChange(changes: LDFlagChangeset) {
+        const updates = getFlattenedFlagsFromChangeset(changes, targetFlags);
+        if (Object.keys(updates).length > 0) {
+          setLDData(({ unproxiedFlags }) => {
+            const updatedUnproxiedFlags = { ...unproxiedFlags, ...updates };
+
+            return {
+              unproxiedFlags: updatedUnproxiedFlags,
+              ...getFlagsProxy(ldClient, updatedUnproxiedFlags, reactOptions, targetFlags),
+            };
+          });
         }
       }
+      ldClient.on('change', onChange);
 
-      ldClient.on('change', (changes: LDFlagChangeset) => {
-        const flattened: LDFlagSet = getFlattenedFlagsFromChangeset(changes, targetFlags, reactOptions);
-        if (Object.keys(flattened).length > 0) {
-          setLDData((prev) => ({ ...prev, flags: { ...prev.flags, ...flattened } }));
-        }
-      });
+      return function cleanup() {
+        ldClient.off('change', onChange);
+      };
     }, []);
 
-    return <Provider value={ldData}>{children}</Provider>;
+    const { flags, flagKeyMap } = ldData;
+
+    return <Provider value={{ flags, flagKeyMap, ldClient }}>{children}</Provider>;
   };
 
   return LDProvider;

src/context.ts

@@ -1,16 +1,23 @@
 import { createContext } from 'react';
 import { LDClient, LDFlagSet } from 'launchdarkly-js-client-sdk';
+import { LDFlagKeyMap } from './types';
 
 /**
  * The LaunchDarkly context stored in the Provider state and passed to consumers.
  */
 interface LDContext {
   /**
-   * Contains all flags from LaunchDarkly. This object will always exist but will be empty {} initially
+   * 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.
@@ -23,7 +30,7 @@ interface LDContext {
 /**
  * @ignore
  */
-const context = createContext<LDContext>({ flags: {}, ldClient: undefined });
+const context = createContext<LDContext>({ flags: {}, flagKeyMap: {}, ldClient: undefined });
 const {
   /**
    * @ignore

src/getFlagsProxy.test.ts

@@ -0,0 +1,60 @@
+import { LDClient, LDFlagSet } from 'launchdarkly-js-client-sdk';
+import getFlagsProxy from './getFlagsProxy';
+import { defaultReactOptions } from './types';
+
+// tslint:disable-next-line: no-unsafe-any
+const variation = jest.fn((k: string): string | undefined => rawFlags[k]);
+
+const ldClient = ({ variation } as unknown) as LDClient;
+
+const rawFlags: LDFlagSet = {
+  'foo-bar': 'foobar',
+  'baz-qux': 'bazqux',
+};
+
+const camelizedFlags: LDFlagSet = {
+  fooBar: 'foobar',
+  bazQux: 'bazqux',
+};
+
+beforeEach(jest.clearAllMocks);
+
+test('camel cases keys', () => {
+  const { flags } = getFlagsProxy(ldClient, rawFlags);
+
+  expect(flags).toEqual(camelizedFlags);
+});
+
+test('does not camel cases keys', () => {
+  const { flags } = getFlagsProxy(ldClient, rawFlags, { useCamelCaseFlagKeys: false });
+
+  expect(flags).toEqual(rawFlags);
+});
+
+test('proxy calls variation on flag read', () => {
+  const { flags } = getFlagsProxy(ldClient, rawFlags);
+
+  expect(flags.fooBar).toBe('foobar');
+
+  expect(variation).toHaveBeenCalledWith('foo-bar', 'foobar');
+});
+
+test('returns flag key map', () => {
+  const { flagKeyMap } = getFlagsProxy(ldClient, rawFlags);
+
+  expect(flagKeyMap).toEqual({ fooBar: 'foo-bar', bazQux: 'baz-qux' });
+});
+
+test('filters to target flags', () => {
+  const { flags } = getFlagsProxy(ldClient, rawFlags, defaultReactOptions, { 'foo-bar': 'mr-toot' });
+
+  expect(flags).toEqual({ fooBar: 'foobar' });
+});
+
+test('does not use proxy if option is false', () => {
+  const { flags } = getFlagsProxy(ldClient, rawFlags, { sendEventsOnFlagRead: false });
+
+  expect(flags['foo-bar']).toBe('foobar');
+
+  expect(variation).not.toHaveBeenCalled();
+});

src/getFlagsProxy.ts

@@ -0,0 +1,79 @@
+import { LDFlagSet, LDClient } from 'launchdarkly-js-client-sdk';
+import camelCase from 'lodash.camelcase';
+import { defaultReactOptions, LDFlagKeyMap, LDReactOptions } from './types';
+
+export default function getFlagsProxy(
+  ldClient: LDClient,
+  rawFlags: LDFlagSet,
+  reactOptions: LDReactOptions = defaultReactOptions,
+  targetFlags?: LDFlagSet,
+): { flags: LDFlagSet; flagKeyMap: LDFlagKeyMap } {
+  const filteredFlags = filterFlags(rawFlags, targetFlags);
+  const [flags, flagKeyMap = {}] = reactOptions.useCamelCaseFlagKeys
+    ? getCamelizedKeysAndFlagMap(filteredFlags)
+    : [filteredFlags];
+
+  return {
+    flags: reactOptions.sendEventsOnFlagRead ? toFlagsProxy(ldClient, flags, flagKeyMap) : flags,
+    flagKeyMap,
+  };
+}
+
+function filterFlags(flags: LDFlagSet, targetFlags?: LDFlagSet): LDFlagSet {
+  if (targetFlags === undefined) {
+    return flags;
+  }
+
+  return Object.keys(targetFlags).reduce<LDFlagSet>((acc, key) => {
+    if (hasFlag(flags, key)) {
+      acc[key] = flags[key];
+    }
+
+    return acc;
+  }, {});
+}
+
+function getCamelizedKeysAndFlagMap(rawFlags: LDFlagSet) {
+  const flags: LDFlagSet = {};
+  const flagKeyMap: LDFlagKeyMap = {};
+  for (const rawFlag in rawFlags) {
+    // Exclude system keys
+    if (rawFlag.indexOf('$') === 0) {
+      continue;
+    }
+    const camelKey = camelCase(rawFlag);
+    flags[camelKey] = rawFlags[rawFlag];
+    flagKeyMap[camelKey] = rawFlag;
+  }
+
+  return [flags, flagKeyMap];
+}
+
+function hasFlag(flags: LDFlagSet, flagKey: string) {
+  return Object.prototype.hasOwnProperty.call(flags, flagKey);
+}
+
+function toFlagsProxy(ldClient: LDClient, flags: LDFlagSet, flagKeyMap: LDFlagKeyMap): LDFlagSet {
+  return new Proxy(flags, {
+    // trap for reading a flag value using `LDClient#variation` to trigger an evaluation event
+    get(target, prop, receiver) {
+      const currentValue = Reflect.get(target, prop, receiver);
+      if (typeof prop === 'symbol') {
+        return currentValue;
+      }
+      if (currentValue === undefined) {
+        return;
+      }
+      const originalFlagKey = hasFlag(flagKeyMap, prop) ? flagKeyMap[prop] : prop;
+      const nextValue = ldClient.variation(originalFlagKey, currentValue);
+
+      return nextValue;
+    },
+    // disable all mutation functions to make proxy readonly
+    setPrototypeOf: () => false,
+    set: () => false,
+    defineProperty: () => false,
+    deleteProperty: () => false,
+    preventExtensions: () => false,
+  });
+}