@featbit/react-client-sdk 1.0.0

package/src/getFlagsProxy.ts

@@ -0,0 +1,82 @@
+import { defaultReactOptions, FbReactOptions, FlagKeyMap, IFlagSet } from "./types";
+import { IFbClient } from "@featbit/js-client-sdk";
+import camelCase from "lodash.camelcase";
+
+export default function getFlagsProxy(
+  fbClient: IFbClient,
+  bootstrapFlags: IFlagSet,
+  fetchedFlags: IFlagSet,
+  reactOptions: FbReactOptions = defaultReactOptions
+): { flags: IFlagSet; flagKeyMap: FlagKeyMap } {
+  const { useCamelCaseFlagKeys = false, sendEventsOnFlagRead = true } = reactOptions;
+  const [flags, flagKeyMap = {}] = useCamelCaseFlagKeys ? getCamelizedKeysAndFlagMap(fetchedFlags) : [fetchedFlags];
+
+  return {
+    flags: toFlagsProxy(fbClient, bootstrapFlags, flags, flagKeyMap, fetchedFlags, useCamelCaseFlagKeys, sendEventsOnFlagRead),
+    flagKeyMap,
+  };
+}
+
+function getCamelizedKeysAndFlagMap(rawFlags: IFlagSet) {
+  const flags: IFlagSet = {};
+  const flagKeyMap: FlagKeyMap = {};
+  for (const rawFlagKey in rawFlags) {
+    // Exclude system keys
+    if (rawFlagKey.indexOf('$') === 0) {
+      continue;
+    }
+    const camelKey = camelCase(rawFlagKey);
+    flags[camelKey] = rawFlags[rawFlagKey];
+    flagKeyMap[camelKey] = rawFlagKey;
+  }
+
+  return [flags, flagKeyMap];
+}
+
+function hasFlag(flags: IFlagSet, flagKey: string) {
+  return Object.prototype.hasOwnProperty.call(flags, flagKey);
+}
+
+function toFlagsProxy(
+  fbClient: IFbClient,
+  bootstrapFlags: IFlagSet,
+  flags: IFlagSet,
+  flagKeyMap: FlagKeyMap,
+  flagsWithRawFlagKeys: IFlagSet,
+  useCamelCaseFlagKeys: boolean,
+  sendEventsOnFlagRead: boolean
+): IFlagSet {
+  return new Proxy(flags, {
+    get: (target, prop, receiver) => {
+      const currentValue = Reflect.get(target, prop, receiver) || flagsWithRawFlagKeys[prop as string]
+
+      // check if flag key exists as camelCase or original case
+      const validFlagKey =
+        hasFlag(flagKeyMap, prop as string) || hasFlag(target, prop as string) || hasFlag(flagsWithRawFlagKeys, prop as string);
+
+      if (!validFlagKey && hasFlag(bootstrapFlags, prop as string)) {
+        return bootstrapFlags[prop as string];
+      }
+
+      // only process flag keys and ignore symbols and native Object functions
+      if (typeof prop === 'symbol' || !validFlagKey) {
+        return currentValue;
+      }
+
+      if (useCamelCaseFlagKeys && prop !== camelCase(prop as string)) {
+        console.warn(`You're attempting to access a flag with its original keyId: ${prop as string}, even though useCamelCaseFlagKeys is set to true.`);
+      }
+
+      if (currentValue === undefined) {
+        return undefined;
+      }
+
+      if (!sendEventsOnFlagRead) {
+        return currentValue;
+      }
+
+      const pristineFlagKey = useCamelCaseFlagKeys ? (flagKeyMap[prop] || prop) : prop;
+      return fbClient.variation(pristineFlagKey, currentValue);
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+import asyncWithFbProvider from './asyncWithFbProvider';
+import context from './context';
+import FbProvider from './provider';
+import useFlags from './useFlags';
+import useFbClient from './useFbClient';
+import { camelCaseKeys } from './utils';
+import withFbConsumer from './withFbConsumer';
+import withFbProvider from './withFbProvider';
+
+export * from './types';
+
+export {
+  FbProvider,
+  context,
+  asyncWithFbProvider,
+  camelCaseKeys,
+  useFlags,
+  useFbClient,
+  withFbProvider,
+  withFbConsumer
+};

package/src/initClient.ts

@@ -0,0 +1,26 @@
+import { AllFlagsFbClient, defaultReactOptions, FbReactOptions } from './types';
+import { FbClientBuilder, IOptions } from '@featbit/js-client-sdk';
+import { fetchFlags } from "./utils";
+
+/**
+ * Internal function to initialize the `@featbit/js-client-sdk`.
+ *
+ * @param reactOptions Initialization options for the FeatBit React SDK
+ * @param options @featbit/js-client-sdk initialization options
+ *
+ * @see `ProviderConfig` for more details about the parameters
+ * @return An initialized client and flags
+ */
+export const initClient = async (
+  reactOptions: FbReactOptions = defaultReactOptions,
+  options: IOptions = {}
+): Promise<AllFlagsFbClient> => {
+  const fbClient = new FbClientBuilder({...options}).build();
+
+  return new Promise<AllFlagsFbClient>((resolve) => {
+    fbClient.on('ready', async () => {
+      const flags = await fetchFlags(fbClient);
+      resolve({flags, fbClient});
+    });
+  });
+};

package/src/provider.tsx

@@ -0,0 +1,136 @@
+import React from "react";
+import { EnhancedComponent, ProviderConfig, defaultReactOptions, IFlagSet } from './types';
+import { Provider, FbContext } from './context';
+import { camelCaseKeys, fetchFlags } from "./utils";
+import { initClient } from './initClient';
+import { IFbClient } from '@featbit/js-client-sdk';
+import getFlagsProxy from "./getFlagsProxy";
+
+interface FbHocState extends FbContext {
+  unproxiedFlags: IFlagSet;
+}
+
+/**
+ * The `FbProvider` is a component which accepts a config object which is used to
+ * initialize `@featbit/js-client-sdk`.
+ *
+ * This Provider does three things:
+ * - It initializes the FeatBit instance by calling `@featbit/js-client-sdk` init on `componentDidMount`
+ * - It saves all flags and the FeatBit instance in the context API
+ * - It subscribes to flag changes and propagate them through the context API
+ *
+ * Because the `@featbit/js-client-sdk` is only initialized on `componentDidMount`, your flags and the
+ * FeatBit are only available after your app has mounted. This can result in a flicker due to flag changes at
+ * startup time.
+ *
+ * This component can be used as a standalone provider. However, be mindful to only include the component once
+ * within your application. This provider is used inside the `withFbProviderHOC` and can be used instead to initialize
+ * the `@featbit/js-client-sdk`. For async initialization, check out the `asyncWithFbProvider` function
+ */
+class FbProvider extends React.Component<ProviderConfig, FbHocState> implements EnhancedComponent {
+  readonly state: Readonly<FbHocState>;
+  bootstrapFlags: IFlagSet;
+
+  constructor(props: ProviderConfig) {
+    super(props);
+
+    const {options} = props;
+    this.bootstrapFlags = (options?.bootstrap || []).reduce((acc: {[key: string]: string}, flag: any) => {
+      acc[flag.id] = flag.variation;
+      return acc;
+    }, {} as {[key: string]: string});;
+
+    this.state = {
+      flags: {},
+      unproxiedFlags: {},
+      flagKeyMap: {},
+      fbClient: undefined,
+    };
+
+    if (options?.bootstrap && options?.bootstrap.length > 0) {
+      const {useCamelCaseFlagKeys} = this.getReactOptions();
+      const flags = useCamelCaseFlagKeys ? camelCaseKeys(this.bootstrapFlags) : this.bootstrapFlags;
+      this.state = {
+        flags,
+        unproxiedFlags: flags,
+        flagKeyMap: {},
+        fbClient: undefined,
+      };
+    }
+  }
+
+  getReactOptions = () => ({...defaultReactOptions, ...this.props.reactOptions});
+
+  subscribeToChanges = (fbClient: IFbClient) => {
+    fbClient.on('update', (changedKeys: string[]) => {
+      const updates: IFlagSet = changedKeys.reduce((acc, key) => {
+        acc[key] = fbClient.variation(key, '');
+        return acc;
+      }, {} as IFlagSet);
+
+      const unproxiedFlags = {
+        ...this.state.unproxiedFlags,
+        ...updates,
+      };
+
+      if (Object.keys(updates).length > 0) {
+        this.setState({
+          unproxiedFlags,
+          ...getFlagsProxy(fbClient, this.bootstrapFlags, unproxiedFlags, this.getReactOptions())
+        })
+      }
+    });
+  };
+
+  init = async () => {
+    const {options} = this.props;
+    let client: IFbClient = this.props.fbClient!;
+    const reactOptions = this.getReactOptions();
+    let unproxiedFlags;
+    if (client) {
+      unproxiedFlags = await fetchFlags(client);
+    } else {
+      const initialisedOutput = await initClient(reactOptions, options);
+      unproxiedFlags = initialisedOutput.flags;
+      client = initialisedOutput.fbClient!;
+    }
+
+    this.setState({
+      unproxiedFlags,
+      ...getFlagsProxy(client, this.bootstrapFlags, unproxiedFlags, reactOptions),
+      fbClient: client
+    });
+
+    this.subscribeToChanges(client);
+  };
+
+  async componentDidMount() {
+    const {options, deferInitialization} = this.props;
+    if (deferInitialization && !options) {
+      return;
+    }
+
+    await this.init();
+  }
+
+  async componentDidUpdate(prevProps: ProviderConfig) {
+    const {options, deferInitialization} = this.props;
+    const userJustLoaded = !prevProps.options?.user && options?.user;
+    if (deferInitialization && userJustLoaded) {
+      await this.init();
+    }
+  }
+
+  render() {
+    const {flags, flagKeyMap, fbClient} = this.state;
+
+    // Conditional rendering when fbClient is null
+    if (fbClient === undefined) {
+      return null; // or Loading Indicator or any other placeholder
+    }
+
+    return <Provider value={{ flags, flagKeyMap, fbClient }}>{ this.props.children }</Provider>;
+  }
+}
+
+export default FbProvider;

package/src/types.ts

@@ -0,0 +1,103 @@
+import { IFbClient, IOptions, FlagValue } from '@featbit/js-client-sdk';
+
+export interface IFlagSet {
+  [key: string]: FlagValue;
+}
+
+/**
+ * Initialization options for the FeatBit React SDK. These are in addition to the options exposed
+ * by [[IOption]] which are common to both the JavaScript and React SDKs.
+ */
+export interface FbReactOptions {
+  /**
+   * Whether the React SDK should transform flag keys into camel-cased format.
+   * Using camel-cased flag keys allow for easier use as prop values, however,
+   * these keys won't directly match the flag keys as known to LaunchDarkly.
+   * Consequently, flag key collisions may be possible and the Code References feature
+   * will not function properly.
+   *
+   * This is false by default, if set to true, keys will automatically be converted to camel-case.
+   */
+  useCamelCaseFlagKeys?: boolean;
+
+  /**
+   * Whether to send flag evaluation events when a flag is read from the `flags` object
+   * returned by the `useFlags` hook. This is true by default, meaning flag evaluation
+   * events will be sent by default.
+   */
+  sendEventsOnFlagRead?: boolean;
+}
+
+/**
+ * Contains default values for the `reactOptions` object.
+ */
+export const defaultReactOptions = {useCamelCaseFlagKeys: false, sendEventsOnFlagRead: true};
+
+/**
+ * Configuration object used to initialise FeatBit's JS client.
+ */
+export interface ProviderConfig {
+  /**
+   * If set to true, the FeatBit will not be initialized until the option prop has been defined.
+   */
+  deferInitialization?: boolean;
+
+  /**
+   * FeatBit initialization options. These options are common between FeatBit's JavaScript and React SDKs.
+   */
+  options?: IOptions;
+
+  /**
+   * Additional initialization options specific to the React SDK.
+   *
+   * @see options
+   */
+  reactOptions?: FbReactOptions;
+
+  /**
+   * Optionally, the FB can be initialised outside the provider
+   * and passed in, instead of being initialised by the provider.
+   * Note: it should only be passed in when it has emitted the 'ready'
+   * event, to ensure that the flags are properly set.
+   */
+  fbClient?: IFbClient;
+}
+
+/**
+ * The return type of withFbProvider HOC. Exported for testing purposes only.
+ *
+ * @ignore
+ */
+export interface EnhancedComponent extends React.Component {
+  subscribeToChanges(fbClient: IFbClient): void;
+
+  // tslint:disable-next-line:invalid-void
+  componentDidMount(): Promise<void>;
+
+  // tslint:disable-next-line:invalid-void
+  componentDidUpdate(prevProps: ProviderConfig): Promise<void>;
+}
+
+/**
+ * Return type of `initClient`.
+ */
+export interface AllFlagsFbClient {
+  /**
+   * Contains all flags from FeatBit.
+   */
+  flags: IFlagSet;
+
+  /**
+   * An instance of `FB` from the FeatBit JS SDK.
+   */
+  fbClient: IFbClient;
+}
+
+/**
+ * Map of camelized flag keys to original unmodified flag keys.
+ */
+export interface FlagKeyMap {
+  [camelCasedKey: string]: string;
+}
+
+export * from '@featbit/js-client-sdk';

package/src/useFbClient.ts

@@ -0,0 +1,21 @@
+import { useContext } from 'react';
+import context, { FbContext } from './context';
+import { IFbClient } from "@featbit/js-client-sdk";
+
+// tslint:disable:max-line-length
+/**
+ * `useFbClient` is a custom hook which returns the underlying [FeatBit JavaScript SDK client object](https://github.com/featbit/featbit-js-client-sdk).
+ * Like the `useFlags` custom hook, `useFbClient` also uses the `useContext` primitive to access the FeatBit
+ * context set up by `withFbProvider`. You will still need to use the `withFbProvider` HOC
+ * to initialise the react sdk to use this custom hook.
+ *
+ * @return The `@featbit/js-client-sdk` `FB` object
+ */
+// tslint:enable:max-line-length
+const useFbClient = (): IFbClient => {
+  const { fbClient} = useContext<FbContext>(context);
+
+  return fbClient!;
+};
+
+export default useFbClient;

package/src/useFlags.ts

@@ -0,0 +1,19 @@
+import { useContext } from 'react';
+import context, { FbContext } from './context';
+import { IFlagSet } from "./types";
+
+/**
+ * `useFlags` is a custom hook which returns all feature flags. It uses the `useContext` primitive
+ * to access the FeatBit context set up by `withFbProvider`. As such you will still need to
+ * use the `withFbProvider` HOC at the root of your app to initialize the React SDK and populate the
+ * context with `fbClient` and your flags.
+ *
+ * @return All the feature flags configured in FeatBit
+ */
+const useFlags = <T extends IFlagSet = IFlagSet>(): T => {
+  const {flags} = useContext<FbContext>(context);
+
+  return flags as T;
+};
+
+export default useFlags;

package/src/utils.ts

@@ -0,0 +1,39 @@
+import { IEvalDetail, IFbClient } from '@featbit/js-client-sdk';
+import camelCase from 'lodash.camelcase';
+import { IFlagSet } from "./types";
+
+/**
+ * Transforms a set of flags so that their keys are camelCased. This function ignores
+ * flag keys which start with `$`.
+ *
+ * @param rawFlags A mapping of flag keys and their values
+ * @return A transformed `IFeatureFlagSet` with camelCased flag keys
+ */
+export const camelCaseKeys = (rawFlags: IFlagSet) => {
+  const flags: IFlagSet = {};
+  for (const rawFlag in rawFlags) {
+    // Exclude system keys
+    if (rawFlag.indexOf('$') !== 0) {
+      flags[camelCase(rawFlag)] = rawFlags[rawFlag]; // tslint:disable-line:no-unsafe-any
+    }
+  }
+
+  return flags;
+};
+
+/**
+ * Retrieves flag values.
+ *
+ * @param fbClient FeatBit client
+ *
+ * @returns an `IFeatureFlagSet` with the current flag values from FeatBit
+ */
+export const fetchFlags = async (
+  fbClient: IFbClient
+) => {
+  const evalDetails: IEvalDetail<string>[] = await fbClient.getAllVariations();
+
+  return evalDetails.map(({flagKey, value}) => ({[flagKey]: value}));
+};
+
+export default {camelCaseKeys, fetchFlags};

package/src/withFbConsumer.tsx

@@ -0,0 +1,58 @@
+import * as React from 'react';
+import { Consumer, FbContext } from './context';
+import { IFbClient } from '@featbit/js-client-sdk';
+import { IFlagSet } from "./types";
+
+/**
+ * Controls the props the wrapped component receives from the `FbConsumer` HOC.
+ */
+export interface ConsumerOptions {
+  /**
+   * If true then the wrapped component only receives the `fbClient` instance
+   * and nothing else.
+   */
+  clientOnly: boolean;
+}
+
+/**
+ * The possible props the wrapped component can receive from the `FbConsumer` HOC.
+ */
+export interface FbProps {
+  /**
+   * A map of feature flags from their keys to their values.
+   * Keys are camelCased using `lodash.camelcase`.
+   */
+  flags?: IFlagSet;
+
+  /**
+   * An instance of `FB` from the FeatBit JS Client SDK (`@featbit/js-client-sdk`)
+   */
+  fbClient?: IFbClient;
+}
+
+/**
+ * withFbConsumer is a function which accepts an optional options object and returns a function
+ * which accepts your React component. This function returns a HOC with flags
+ * and the FB instance injected via props.
+ *
+ * @param options - If you need only the `fbClient` instance and not flags, then set `{ clientOnly: true }`
+ * to only pass the fbClient prop to your component. Defaults to `{ clientOnly: false }`.
+ * @return A HOC with flags and the `fbClient` instance injected via props
+ */
+function withFbConsumer(options: ConsumerOptions = {clientOnly: false}) {
+  return function withFbConsumerHoc<P>(WrappedComponent: React.ComponentType<P & FbProps>) {
+    return (props: P) => (
+      <Consumer>
+        { ({flags, fbClient}: FbContext) => {
+          if (options.clientOnly) {
+            return <WrappedComponent fbClient={ fbClient } { ...props } />;
+          }
+
+          return <WrappedComponent flags={ flags } fbClient={ fbClient } { ...props } />;
+        } }
+      </Consumer>
+    );
+  };
+}
+
+export default withFbConsumer;

package/src/withFbProvider.tsx

@@ -0,0 +1,49 @@
+import * as React from 'react';
+import { defaultReactOptions, ProviderConfig } from './types';
+import FbProvider from './provider';
+import hoistNonReactStatics from 'hoist-non-react-statics';
+import IntrinsicAttributes = React.JSX.IntrinsicAttributes;
+
+/**
+ * `withFbProvider` is a function which accepts a config object which is used to
+ * initialize `@featbit/js-client-sdk`.
+ *
+ * This HOC handles passing configuration to the `FbProvider`, which does the following:
+ * - It initializes the fbClient instance by calling `@featbit/js-client-sdk` init on `componentDidMount`
+ * - It saves all flags and the fbClient instance in the context API
+ * - It subscribes to flag changes and propagate them through the context API
+ *
+ * The difference between `withFbProvider` and `asyncWithFbProvider` is that `withFbProvider` initializes
+ * `@featbit/js-client-sdk` at `componentDidMount`. This means your flags and the fbClient are only available after
+ * your app has mounted. This can result in a flicker due to flag changes at startup time.
+ *
+ * `asyncWithFbProvider` initializes `@featbit/js-client-sdk` at the entry point of your app prior to render.
+ * This means that your flags and the fbClient are ready at the beginning of your app. This ensures your app does not
+ * flicker due to flag changes at startup time.
+ *
+ * @param config - The configuration used to initialize FeatBit JS Client SDK
+ * @return A function which accepts your root React component and returns a HOC
+ */
+export function withFbProvider<T extends IntrinsicAttributes = {}>(
+  config: ProviderConfig,
+): (WrappedComponent: React.ComponentType<T>) => any {
+  return function withFbProviderHoc(WrappedComponent: React.ComponentType<T>): any {
+    const {reactOptions: userReactOptions} = config;
+    const reactOptions = {...defaultReactOptions, ...userReactOptions};
+    const providerProps = {...config, reactOptions};
+
+    function HoistedComponent(props: T) {
+      return (
+        <FbProvider { ...providerProps }>
+          <WrappedComponent { ...props } />
+        </FbProvider>
+      );
+    }
+
+    hoistNonReactStatics(HoistedComponent, WrappedComponent);
+
+    return HoistedComponent;
+  };
+}
+
+export default withFbProvider;