prepare 2.27.0 release (#150)

Added:

- useFlags hook is now generically typed, allowing you to assert what type your flag set will be.
- useLDClientError hook for exposing client initialization failures.

Changed:

- sendEventsOnlyForVariation is now set to true by default to prevent a flag evaluation event being generated for every flag on load.
- flags object (that is either injected via props using LDConsumer or returned from the useFlags hook) will generate a - flag evaluation event on flag read (using a JavaScript proxy). This can be disabled by setting reactOptions.sendEventsOnFlagRead: false.
- upgraded from ES5 to ES6.

Author: LaunchDarklyReleaseBot

.github/pull_request_template.md

@@ -1,7 +1,7 @@
 **Requirements**
 
 - [ ] I have added test coverage for new or changed functionality
-- [ ] I have followed the repository's [pull request submission guidelines](../blob/master/CONTRIBUTING.md#submitting-pull-requests)
+- [ ] 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
 
 **Related issues**

.ldrelease/config.yml

@@ -1,3 +1,5 @@
+version: 2
+
 repo:
   public: react-client-sdk
   private: react-client-sdk-private
@@ -6,11 +8,14 @@ publications:
   - url: https://www.npmjs.com/package/launchdarkly-react-client-sdk
     description: npm
 
-template:
-  name: npm
+jobs:
+  - docker:
+      image: node:16-buster
+    template:
+      name: npm
 
 documentation:
-  githubPages: true
+  gitHubPages: true
   title: LaunchDarkly React SDK
 
 sdk:

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change log
 
-All notable changes to the LaunchDarkly Client-side SDK for React will be documented in this file. For the source code for versions 2.13.0 and earlier, see the corresponding tags in the [js-client-sdk](https://github.com/launchdarkly/js-client-sdk) repository; this code was previously in a monorepo package there. See also the [JavaScript SDK changelog](https://github.com/launchdarkly/js-client-sdk/blob/master/CHANGELOG.md), since the React SDK inherits all of the underlying functionality of the JavaScript SDK; this file covers only changes that are specific to the React interface. This project adheres to [Semantic Versioning](http://semver.org).
+All notable changes to the LaunchDarkly Client-side SDK for React will be documented in this file. For the source code for versions 2.13.0 and earlier, see the corresponding tags in the [js-client-sdk](https://github.com/launchdarkly/js-client-sdk) repository; this code was previously in a monorepo package there. See also the [JavaScript SDK changelog](https://github.com/launchdarkly/js-client-sdk/blob/main/CHANGELOG.md), since the React SDK inherits all of the underlying functionality of the JavaScript SDK; this file covers only changes that are specific to the React interface. This project adheres to [Semantic Versioning](http://semver.org).
 
 ## [2.26.0] - 2022-04-27
 ### Added:

README.md

@@ -1,6 +1,6 @@
 # LaunchDarkly Client-side SDK for React
 
-[![Circle CI](https://circleci.com/gh/launchdarkly/react-client-sdk/tree/master.svg?style=svg)](https://circleci.com/gh/launchdarkly/react-client-sdk/tree/master)
+[![Circle CI](https://circleci.com/gh/launchdarkly/react-client-sdk/tree/main.svg?style=svg)](https://circleci.com/gh/launchdarkly/react-client-sdk/tree/main)
 
 ## LaunchDarkly overview
 
@@ -24,7 +24,7 @@ Please note that the React SDK has two special requirements in terms of your Lau
 
 Check out our [documentation](https://docs.launchdarkly.com) for in-depth instructions on configuring and using LaunchDarkly. You can also head straight to the [complete reference guide for this SDK](https://docs.launchdarkly.com/docs/react-sdk-reference) or our [code-generated API documentation](https://launchdarkly.github.io/react-client-sdk/).
 
-This SDK builds upon the [JavaScript SDK](https://github.com/launchdarkly/js-client-sdk), supporting all of the same functionality, but using React's Context API to provide additional conveniences. While using this SDK you may need to directly interact with the underlying JavaScript SDK. For more information on how to use the JavaScript SDK and its characteristics, see the [SDK's README](https://github.com/launchdarkly/js-client-sdk/blob/master/README.md).
+This SDK builds upon the [JavaScript SDK](https://github.com/launchdarkly/js-client-sdk), supporting all of the same functionality, but using React's Context API to provide additional conveniences. While using this SDK you may need to directly interact with the underlying JavaScript SDK. For more information on how to use the JavaScript SDK and its characteristics, see the [SDK's README](https://github.com/launchdarkly/js-client-sdk/blob/main/README.md).
 
 ## Testing
 

examples/async-provider/package.json

@@ -23,7 +23,7 @@
   ],
   "author": "LaunchDarkly <[email protected]>",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/launchdarkly/js-client-sdk/tree/master/packages/launchdarkly-react-client-sdk",
+  "homepage": "https://github.com/launchdarkly/js-client-sdk/tree/main/packages/launchdarkly-react-client-sdk",
   "dependencies": {
     "@babel/polyfill": "^7.2.5",
     "express": "^4.16.4",

examples/hoc/package.json

@@ -23,7 +23,7 @@
   ],
   "author": "LaunchDarkly <[email protected]>",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/launchdarkly/js-client-sdk/tree/master/packages/launchdarkly-react-client-sdk",
+  "homepage": "https://github.com/launchdarkly/js-client-sdk/tree/main/packages/launchdarkly-react-client-sdk",
   "dependencies": {
     "@babel/polyfill": "^7.2.5",
     "express": "^4.16.4",

package.json

@@ -46,8 +46,8 @@
     "@types/react": "^18.0.3",
     "@types/react-dom": "^18.0.0",
     "@types/react-test-renderer": "^18.0.0",
-    "@types/uuid": "^3.4.5",
     "jest": "^27.4.4",
+    "jest-environment-jsdom": "^27.4.4",
     "jest-environment-jsdom-global": "^3.0.0",
     "jest-junit": "^13.0.0",
     "prettier": "^1.18.2",
@@ -65,8 +65,7 @@
   "dependencies": {
     "hoist-non-react-statics": "^3.3.2",
     "launchdarkly-js-client-sdk": "2.22.1",
-    "lodash.camelcase": "^4.3.0",
-    "uuid": "^3.3.2"
+    "lodash.camelcase": "^4.3.0"
   },
   "peerDependencies": {
     "react": "^16.6.3 || ^17.0.0 || ^18.0.0",

src/__snapshots__/provider.test.tsx.snap

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

src/__snapshots__/withLDProvider.test.tsx.snap

@@ -4,6 +4,8 @@ exports[`withLDProvider render app 1`] = `
 <Provider
   value={
     Object {
+      "error": undefined,
+      "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, error } = 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, error }}>{children}</Provider>;
   };
 
   return LDProvider;

src/context.ts

@@ -1,29 +1,41 @@
 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.
    *
    * @see https://docs.launchdarkly.com/sdk/client-side/javascript
    */
   ldClient?: LDClient;
+
+  /**
+   * LaunchDarkly client initialization error, if there was one.
+   */
+  error?: Error;
 }
 
 /**
  * @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();
+});