feat (Hooks): Add useFeature hook (#28)

## Summary

This PR adds a React Hook called `useFeature`, enabling feature usage (with variables) via the hooks interface.

The API designed here is intended to be feature complete with the `<OptimizelyFeature>` component.

### Justification - Why add hooks?

Despite just being the new hotness in the React world, there are a couple good reasons to supporting the hooks paradigm in this SDK:

- Easy use of features/variables outside the context of JSX markup
- Allow consumers to avoid using class components (mostly in the interest of bundle size)
  - This could also be done by rewriting `<OptimizelyFeature>` as a functional component that itself leverages built in React hooks for state management

#### TODO

- [x] Update hook to return a third argument, `clientReady`, which will indicate whether or not the client is ready.
- [x] Add more tests for usage of the options and overrides

### Example Usage

_Directly from the README update:_

*arguments*
* `feature : string` Key of the feature
* `options : Object`
  * `autoUpdate : boolean` (optional) If true, this component will re-render in response to datafile or user changes. Default: `false`.
  * `timeout : number` (optional) Rendering timeout as described in the `OptimizelyProvider` section. Overrides any timeout set on the ancestor `OptimizelyProvider`. 
* `overrides : Object`
  * `overrideUserId : string` (optional) Override the userId for calls to `isFeatureEnabled` for this hook.
  * `overrideAttributes : optimizely.UserAttributes` (optional) Override the user attributes for calls to `isFeatureEnabled` for this hook.

```jsx
import { useEffect } from 'react';
import { useFeature } from '@optimizely/react-sdk';

function LoginComponent() {
  const [isEnabled, variables] = useFeature('feature1', { autoUpdate: true }, { /* (Optional) User overrides */ });
  useEffect(() => {
    document.title = isEnabled ? 'login1' : 'login2';
  }, [isEnabled]);

  return (
    <p>
      <a href={isEnabled ? "/login" : "/login2"}>
        {variables.loginText}
      </a>
    </p>
  )
}
```

### AutoUpdate

A utility was added to help manage auto updates of the feature and it's variables in `autoUpdate.ts`. Eventually, this utility can be used in a `useExperiment` hook.

Additionally, the `useFeature` and `useExperiment` hooks could then handle all the state management and auto update logic for `<OptimizelyFeature>` and `<OptimizelyExperiment>`, allowing those to just be thin wrapper components.


## Test Plan

Minimal unit tests have been added to test the base case(s) here. Additional testing of the optional parameters will be added once this overall approach is agreed upon.

_Note: Until we upgrade to React 16.9, there will be errors in the `hooks.spec.tsx` unit tests about not wrapping state setting test actions in `act()`. React 16.9 introduces async support for `act()`, which will allow us to wrap our invocation of `await client.onReady()`_ 

## Issues

Addresses #6

Author: James Fox

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### New Features
+
+- Added `useFeature` hook
+  - Can be used to retrieve the status of a feature flag and its variables. See [#28](https://github.com/optimizely/react-sdk/pull/28) for more details.
+
+### Enhancements
+
+- Exposed the entire context object used by 
+  - Enables support for using APIs which require passing reference to a context object, like `useContext`. [#27](https://github.com/optimizely/react-sdk/pull/27) for more details.
+
+
 ## [1.2.0-alpha.1] - March 5th, 2020
 
 ### New Features

README.md

@@ -98,7 +98,7 @@ The `ReactSDKClient` client created via `createInstance` is the programmatic API
   - [JavaScript: Update datafiles](https://docs.developers.optimizely.com/full-stack/docs/javascript-update-datafiles)
 
 *returns*
-- A `ReactSDKClient` instance.
+* A `ReactSDKClient` instance.
 
 ```jsx
 import { OptimizelyProvider, createInstance } from '@optimizely/react-sdk'
@@ -301,6 +301,53 @@ function FeatureComponent() {
 }
 ```
 
+
+## `useFeature` Hook
+
+A [React Hook](https://reactjs.org/docs/hooks-intro.html) to retrieve the status of a feature flag and its variables. This can be useful as an alternative to the `<OptimizelyFeature>` component or to use features & variables inside code that is not explicitly rendered.
+
+*arguments*
+* `feature : string` Key of the feature
+* `options : Object`
+  * `autoUpdate : boolean` (optional) If true, this hook will update the feature and it's variables in response to datafile or user changes. Default: `false`.
+  * `timeout : number` (optional) Client timeout as described in the `OptimizelyProvider` section. Overrides any timeout set on the ancestor `OptimizelyProvider`. 
+* `overrides : Object`
+  * `overrideUserId : string` (optional) Override the userId for calls to `isFeatureEnabled` for this hook.
+  * `overrideAttributes : optimizely.UserAttributes` (optional) Override the user attributes for calls to `isFeatureEnabled` for this hook.
+
+*returns*
+
+* `Array` of:
+  * `isFeatureEnabled : boolean` - The `isFeatureEnabled` value for the `feature` provided.
+  * `variables : VariableValuesObject` - The variable values for the `feature` provided
+  * `clientReady : boolean` - Whether or not the underlying `ReactSDKClient` instance is ready or not.
+  * `didTimeout : boolean` - Whether or not the underlying `ReactSDKClient` became ready within the allowed `timeout` range.
+
+  _Note: `clientReady` can be true even if `didTimeout` is also true. This indicates that the client became ready *after* the timeout period._
+
+### Render something if feature is enabled
+
+```jsx
+import { useEffect } from 'react';
+import { useFeature } from '@optimizely/react-sdk';
+
+function LoginComponent() {
+  const [isEnabled, variables] = useFeature('feature1', { autoUpdate: true }, { /* (Optional) User overrides */ });
+  useEffect(() => {
+    document.title = isEnabled ? 'login1' : 'login2';
+  }, [isEnabled]);
+
+  return (
+    <p>
+      <a href={isEnabled ? "/login" : "/login2"}>
+        {variables.loginText}
+      </a>
+    </p>
+  )
+}
+```
+
+
 ## `withOptimizely`
 
 Any component under the `<OptimizelyProvider>` can access the Optimizely `ReactSDKClient` via the higher-order component (HoC) `withOptimizely`.
@@ -377,7 +424,7 @@ The following type definitions are used in the `ReactSDKClient` interface:
 
 `ReactSDKClient` instances have the methods/properties listed below. Note that in general, the API largely matches that of the core `@optimizely/optimizely-sdk` client instance, which is documented on the [Optimizely X Full Stack developer docs site](https://docs.developers.optimizely.com/full-stack/docs). The major exception is that, for most methods, user id & attributes are ***optional*** arguments. `ReactSDKClient` has a current user. This user's id & attributes are automatically applied to all method calls, and overrides can be provided as arguments to these method calls if desired.
 
-* `onReady(opts?: { timeout?: number }): Promise` Returns a Promise that fulfills with an object representing the initialization process. The instance is ready when it has fetched a datafile and a user is available (via `setUser` being called with an object, or a Promise passed to `setUser` becoming fulfilled).
+* `onReady(opts?: { timeout?: number }): Promise<onReadyResult>` Returns a Promise that fulfills with an `onReadyResult` object representing the initialization process. The instance is ready when it has fetched a datafile and a user is available (via `setUser` being called with an object, or a Promise passed to `setUser` becoming fulfilled). If the `timeout` period happens before the client instance is ready, the `onReadyResult` object will contain an additional key, `dataReadyPromise`, which can be used to determine when, if ever, the instance does become ready.
 * `user: User` The current user associated with this client instance
 * `setUser(userInfo: User | Promise<User>): void` Call this to update the current user
 * `onUserUpdate(handler: (userInfo: User) => void): () => void` Subscribe a callback to be called when this instance's current user changes. Returns a function that will unsubscribe the callback.
@@ -406,7 +453,7 @@ Right now server side rendering is possible with a few caveats.
 
 1. You must download the datafile manually and pass in via the `datafile` option.  Can not use `sdkKey` to automatically download.
 
-2. Rendering of components must be completely synchronous (this is true for all server side rendering)
+2. Rendering of components must be completely synchronous (this is true for all server side rendering), thus the Optimizely SDK assumes that the optimizely client has been instantiated and fired it's `onReady` event already.
 
 ### Setting up `<OptimizelyProvider>`
 

package.json

@@ -29,12 +29,13 @@
   "dependencies": {
     "@optimizely/js-sdk-logging": "^0.1.0",
     "@optimizely/optimizely-sdk": "3.6.0-alpha.1",
+    "@types/react-dom": "^16.9.5",
     "hoist-non-react-statics": "^3.3.0",
     "prop-types": "^15.6.2",
     "utility-types": "^2.1.0"
   },
   "peerDependencies": {
-    "react": ">=16.3.0"
+    "react": ">=16.8.0"
   },
   "devDependencies": {
     "@types/enzyme": "^3.1.15",
@@ -46,8 +47,8 @@
     "enzyme": "^3.8.0",
     "enzyme-adapter-react-16": "^1.7.1",
     "jest": "^23.6.0",
-    "react": "^16.7.0",
-    "react-dom": "^16.7.0",
+    "react": "^16.8.0",
+    "react-dom": "^16.8.0",
     "rollup": "^1.1.0",
     "rollup-plugin-commonjs": "^9.2.0",
     "rollup-plugin-node-resolve": "^4.0.0",

src/Experiment.tsx

@@ -52,7 +52,7 @@ export class Experiment extends React.Component<ExperimentProps, ExperimentState
     this.autoUpdate = !!autoUpdate
 
     if (isServerSide) {
-      if (optimizely === null) {
+      if (!optimizely) {
         throw new Error('optimizely prop must be supplied')
       }
       const variation = optimizely.activate(experiment)

src/Feature.tsx

@@ -74,7 +74,7 @@ class FeatureComponent extends React.Component<FeatureProps, FeatureState> {
       isServerSide,
       timeout,
     } = this.props
-    if (optimizely === null) {
+    if (!optimizely) {
       throw new Error('optimizely prop must be supplied')
     }
 

src/autoUpdate.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright 2020, Optimizely
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { enums } from '@optimizely/optimizely-sdk';
+import { LoggerFacade } from '@optimizely/js-sdk-logging';
+
+import { ReactSDKClient } from './client';
+
+interface AutoUpdate {
+  (
+    optimizely: ReactSDKClient,
+    type: 'feature' | 'experiment',
+    value: string,
+    logger: LoggerFacade,
+    callback: () => void
+  ) : () => void
+}
+
+/**
+ * Utility to setup listeners for changes to the datafile or user attributes and invoke the provided callback.
+ * Returns an unListen function
+ */
+export const setupAutoUpdateListeners : AutoUpdate = (optimizely, type, value, logger, callback) => {
+  const loggerSuffix = `re-evaluating ${type}="${value}" for user="${optimizely.user.id}"`;
+  const optimizelyNotificationId = optimizely.notificationCenter.addNotificationListener(
+    enums.NOTIFICATION_TYPES.OPTIMIZELY_CONFIG_UPDATE,
+    () => {
+      logger.info(`${enums.NOTIFICATION_TYPES.OPTIMIZELY_CONFIG_UPDATE}, ${loggerSuffix}`);
+      callback();
+    },
+  );
+  const unregisterConfigUpdateListener = () => optimizely.notificationCenter.removeNotificationListener(optimizelyNotificationId);
+
+  const unregisterUserListener = optimizely.onUserUpdate(() => {
+    logger.info(`User update, ${loggerSuffix}`);
+    callback();
+  });
+
+  return () => {
+    unregisterConfigUpdateListener();
+    unregisterUserListener();
+  };
+}

src/client.ts

@@ -30,6 +30,7 @@ type OnUserUpdateHandler = (userInfo: UserContext) => void
 export type OnReadyResult = {
   success: boolean
   reason?: string
+  dataReadyPromise?: Promise<any>
 }
 
 const REACT_SDK_CLIENT_ENGINE = 'react-sdk'
@@ -183,6 +184,7 @@ class OptimizelyReactSDKClient implements ReactSDKClient {
           success: false,
           reason:
             'failed to initialize onReady before timeout, either the datafile or user info was not set before the timeout',
+          dataReadyPromise: this.dataReadyPromise
         })
       }, timeout) as any
     })