@featbit/js-client-sdk 2.0.2 → 3.0.1

package/src/IFbClientCore.ts

@@ -0,0 +1,291 @@
+import { IEvalDetail } from "./evaluation/IEvalDetail";
+import { IConvertResult } from "./utils/ValueConverters";
+import { IUser } from "./options";
+
+/**
+ * The FeatBit SDK client object.
+ *
+ * Create this object with {@link FbClientBuilder}. Applications should configure the client at startup time
+ * and continue to use it throughout the lifetime of the application, rather than creating instances
+ * on the fly.
+ *
+ */
+export interface IFbClientCore {
+  /**
+   * Set the current user of the client.
+   *
+   * @param user
+   *   The current user. The actual type of this parameter is
+   *   {@link IUser}.
+   */
+  identify(user: IUser): void;
+
+  /**
+   * Indicates whether the client is ready to be used.
+   *
+   * @returns true if the client is ready to be used, false otherwise.
+   */
+  initialized(): boolean;
+
+  /**
+   * Wait until the client is initialized. The promise resolves when the client has finished initializing successfully.
+   * If the client fails to initialize, the promise will be rejected.
+   *
+   * @returns A promise.
+   */
+  waitForInitialization(): Promise<IFbClientCore>;
+
+  /**
+   * Calculates the boolean value of a feature flag for a given user.
+   *
+   * If the flag variation does not have a boolean value, {@link defaultValue} is returned.
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param key
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   *
+   *  @returns the variation for the given user, or {@link defaultValue} if the flag cannot be evaluated
+   */
+  boolVariation(
+    key: string,
+    defaultValue: boolean
+  ): boolean;
+
+  /**
+   * Calculates the boolean value of a feature flag for a given user, and returns an object that
+   * describes the way the value was determined.
+   *
+   * If the flag variation does not have a boolean value, {@link defaultValue} is returned.
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param key
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   *
+   *  @returns {@link IEvalDetail} object describing the way the value was determined.
+   */
+  boolVariationDetail(
+    key: string,
+    defaultValue: boolean
+  ): IEvalDetail<boolean>;
+
+  /**
+   * Calculates the number value of a feature flag for a given user.
+   *
+   * If the flag variation does not have a number value, {@link defaultValue} is returned.
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param key
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   *
+   *  @returns the variation for the given user, or {@link defaultValue} if the flag cannot be evaluated
+   */
+  numberVariation(
+    key: string,
+    defaultValue: number
+  ): number;
+
+  /**
+   * Calculates the number value of a feature flag for a given user, and returns an object that
+   * describes the way the value was determined.
+   *
+   * If the flag variation does not have a number value, {@link defaultValue} is returned.
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param key
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   *
+   *  @returns {@link IEvalDetail} object describing the way the value was determined.
+   */
+  numberVariationDetail(
+    key: string,
+    defaultValue: number
+  ): IEvalDetail<number>;
+
+  /**
+   * Calculates the string value of a feature flag for a given user.
+   *
+   * If the flag variation does not have a string value, {@link defaultValue} is returned.
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param key
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   *
+   *  @returns the variation for the given user, or {@link defaultValue} if the flag cannot be evaluated
+   */
+  stringVariation(
+    key: string,
+    defaultValue: string
+  ): string;
+
+  /**
+   * Calculates the string value of a feature flag for a given user, and returns an object that
+   * describes the way the value was determined.
+   *
+   * If the flag variation does not have a string value, {@link defaultValue} is returned.
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param key
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   *
+   *  @returns {@link IEvalDetail} object describing the way the value was determined.
+   */
+  stringVariationDetail(
+    key: string,
+    defaultValue: string
+  ): IEvalDetail<string>;
+
+  /**
+   * Calculates the JSON value of a feature flag for a given user.
+   *
+   * If the flag variation does not have a JSON value, {@link defaultValue} is returned.
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param key
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   *
+   *  @returns the variation for the given user, or {@link defaultValue} if the flag cannot be evaluated
+   */
+  jsonVariation(
+    key: string,
+    defaultValue: any
+  ): any;
+
+  /**
+   * Calculates the JSON value of a feature flag for a given user, and returns an object that
+   * describes the way the value was determined.
+   *
+   * If the flag variation does not have a JSON value, {@link defaultValue} is returned.
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param key
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   *
+   *  @returns {@link IEvalDetail} object describing the way the value was determined.
+   */
+  jsonVariationDetail(
+    key: string,
+    defaultValue: any
+  ): IEvalDetail<any>;
+
+  /**
+   * Calculates the string value of a feature flag for a given user.
+   *
+   * If the flag variation does not have a string value, {@link defaultValue} is returned.
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param key
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   *
+   *  @returns the variation for the given user, or {@link defaultValue} if the flag cannot be evaluated
+   */
+  variation(
+    key: string,
+    defaultValue: string
+  ): string;
+
+  /**
+   * Calculates the string value of a feature flag for a given user, and returns an object that
+   * describes the way the value was determined.
+   *
+   * If the flag variation does not have a string value, {@link defaultValue} is returned.
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param key
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   *
+   *  @returns {@link IEvalDetail} object describing the way the value was determined.
+   */
+  variationDetail(
+    key: string,
+    defaultValue: string
+  ): IEvalDetail<string>;
+
+  /**
+   * This method is exposed only for testing purpose, please DO NOT USE IT
+   *
+   * Calculates the value of a feature flag for a given user, and returns a {@link IEvalDetail} object that
+   * describes the way the value was determined.
+   *
+   * If an error makes it impossible to evaluate the flag (for instance, the feature flag key
+   * does not match any existing flag), {@link defaultValue} is returned.
+   *
+   * @param flagKey
+   *  The unique key of the feature flag.
+   * @param defaultValue
+   *  The default value to return if the flag cannot be evaluated.
+   * @param typeConverter
+   *  the function to convert result.
+   *
+   *  @returns {@link IEvalDetail} object describing the way the value was determined.
+   */
+  evaluateCore<TValue>(
+    flagKey: string,
+    defaultValue: TValue,
+    typeConverter: (value: string) => IConvertResult<TValue>
+  ): IEvalDetail<TValue>;
+
+  /**
+   * Returns the variation with  of all feature flags for a given user, and returns an object that
+   * describes the way the value was determined for each flag.
+   *
+   *  @returns A list of {@link IEvalDetail} objects describing the way the values were determined.
+   */
+  getAllVariations(): Promise<IEvalDetail<string>[]>;
+
+  /**
+   * Shuts down the client and releases any resources it is using.
+   *
+   * @returns A promise that resolves when the client has been shut down.
+   */
+  close(): Promise<void>;
+
+  /**
+   * Tracks that an application-defined event occurred, and provides an additional numeric value for custom metrics.
+   *
+   * @param eventName
+   *  the name of the event.
+   * @param metricValue
+   *  a numeric value used by the FeatBit experimentation feature in custom numeric metrics, the default value is 1 if not provided.
+   */
+  track(eventName: string, metricValue?: number | undefined): void
+
+  /**
+   * Tells the client that all pending events (if any) should be delivered as soon as possible.
+   *
+   * @param callback
+   *  Will be called when the flush operation is complete. If the flush fails, the callback will be called with false.
+   *
+   * @returns A promise that resolves when the client has been shut down.
+   */
+  flush(callback?: (res: boolean) => void): Promise<boolean>;
+}

package/src/IVersionedData.ts

@@ -0,0 +1,18 @@
+/**
+ * Used internally to describe the basic properties of stored data such as feature flags or user
+ * segments.
+ *
+ * This is the actual type of parameters and return values in `IStore` methods that refer
+ * to a flag or segment item. Those methods still use the `object` type for backward compatibility.
+ */
+export interface IVersionedData {
+  /**
+   * The item's unique key, such as a feature flag key.
+   */
+  key: string;
+
+  /**
+   * A version number that FeatBit will increment each time this item is changed.
+   */
+  version: number;
+}

package/src/bootstrap/IBootstrapProvider.ts

@@ -0,0 +1,5 @@
+import { IDataSourceUpdates } from "../store/IDataSourceUpdates";
+
+export interface IBootstrapProvider {
+  populate(userKeyId: string, dataSourceUpdates: IDataSourceUpdates, callback?: () => void): Promise<void>
+}

package/src/bootstrap/JsonBootstrapProvider.ts

@@ -0,0 +1,35 @@
+import { IBootstrapProvider } from "./IBootstrapProvider";
+import { deserializeAll } from "../store/serialization";
+import { IDataSourceUpdates } from "../store/IDataSourceUpdates";
+import { IStoreDataStorage } from "../store/store";
+import { isNullOrUndefined } from "../utils/isNullOrUndefined";
+import { IFlag, IFlagBase } from "../evaluation/data/IFlag";
+
+export class JsonBootstrapProvider implements IBootstrapProvider {
+  private dataSet?: IStoreDataStorage;
+
+  constructor(bootstrap: IFlagBase[]) {
+    const flags: IFlag[] = (bootstrap || []).map((flag: IFlagBase) => ({...flag, variationOptions: flag.variationOptions || [{id: null, variation: flag.variation}]})) as IFlag[];
+
+    const data = deserializeAll(flags);
+    this.dataSet = {
+      flags: data.flags,
+      version: 0
+    };
+  }
+
+  populate(userKeyId: string, dataSourceUpdates: IDataSourceUpdates, callback?: () => void): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (isNullOrUndefined(this.dataSet)) {
+        return resolve();
+      }
+
+      const internalCallback = () => {
+        resolve();
+        callback?.();
+      }
+
+      dataSourceUpdates.init(userKeyId, this.dataSet!, internalCallback);
+    });
+  }
+}

package/src/bootstrap/NullBootstrapProvider.ts

@@ -0,0 +1,21 @@
+import { IBootstrapProvider } from "./IBootstrapProvider";
+import { IDataSourceUpdates } from "../store/IDataSourceUpdates";
+import { IStoreDataStorage } from "../store/store";
+
+export class NullBootstrapProvider implements IBootstrapProvider {
+  private dataSet?: IStoreDataStorage;
+
+  constructor() {
+    this.dataSet = {
+      flags: {},
+      version: 0
+    };
+  }
+
+  populate(userKeyId: string, dataSourceUpdates: IDataSourceUpdates, callback?: () => void): Promise<void> {
+    return new Promise((resolve, reject) => {
+      resolve();
+      callback?.();
+    });
+  }
+}

package/src/bootstrap/index.ts

@@ -0,0 +1,3 @@
+export * from './IBootstrapProvider';
+export * from './JsonBootstrapProvider';
+export * from './NullBootstrapProvider';

package/src/constants.ts

@@ -1,6 +1,2 @@
-export const insightsFlushTopic = 'insights.flush';
-export const featureFlagEvaluatedTopic = 'featureflag.evaluated.topic';
-export const featureFlagEvaluatedBufferTopic = 'featureflag.evaluated.buffer.topic';
-export const websocketReconnectTopic = 'network.websocket.reconnect';
-export const insightsTopic = 'insights.topic';
-export const currentUserStorageKey = 'fb-user';
+export const EmptyString = '';
+export const MinInt: number = 0x80000000;

package/src/data-sources/DataSourceUpdates.ts

@@ -0,0 +1,89 @@
+import { IDataSourceUpdates } from "../store/IDataSourceUpdates";
+import {
+  IStoreDataStorage,
+  IStoreItem,
+  IKeyedStoreItem
+} from "../store/store";
+import { IStore } from "../platform/IStore";
+import { IDataKind } from "../IDataKind";
+import DataKinds from "../store/DataKinds";
+
+/**
+ * @internal
+ */
+export default class DataSourceUpdates implements IDataSourceUpdates {
+
+  constructor(
+    private readonly store: IStore,
+    private readonly hasEventListeners: () => boolean,
+    private readonly onChange: (keys: string[]) => void,
+  ) {
+  }
+
+  init(userKeyId: string, allData: IStoreDataStorage, callback?: () => void): void {
+    if (userKeyId !== this.store.user.keyId) {
+      callback?.();
+      return;
+    }
+
+    const checkForChanges = this.hasEventListeners();
+    const doInit = async (oldData?: IStoreDataStorage) => {
+      await this.store.init(allData);
+      Promise.resolve().then(() => {
+        if (checkForChanges) {
+          const updatedKeys = Object.keys(allData)
+            .flatMap((namespace) => {
+              const oldDataForKind = oldData?.[namespace] || {};
+              const newDataForKind = allData[namespace];
+              const mergedData = {...oldDataForKind, ...newDataForKind};
+              return Object.keys(mergedData)
+                .filter((key: string) => this.isUpdated(oldDataForKind && oldDataForKind[key], newDataForKind && newDataForKind[key]));
+            });
+          updatedKeys.length > 0 && this.onChange(updatedKeys);
+        }
+      });
+      callback?.();
+    };
+
+    if (checkForChanges) {
+      const [flags, version] = this.store.all(DataKinds.Flags);
+      const oldData = {
+        flags,
+        version
+      };
+      doInit(oldData);
+    } else {
+      doInit();
+    }
+  }
+
+  upsert(userKeyId: string, kind: IDataKind, data: IKeyedStoreItem, callback: () => void): void {
+    if (userKeyId !== this.store.user.keyId) {
+      callback?.();
+      return;
+    }
+
+    const {key} = data;
+    const checkForChanges = this.hasEventListeners();
+    const doUpsert = async (oldItem?: IStoreItem) => {
+      await this.store.upsert(kind, data);
+      Promise.resolve().then(() => {
+        if (checkForChanges && this.isUpdated(oldItem, data[key])) {
+          this.onChange([key]);
+        }
+      });
+
+      callback?.();
+    };
+    if (checkForChanges) {
+      const item = this.store.get(kind, key);
+      doUpsert(item || undefined);
+    } else {
+      doUpsert();
+    }
+  }
+
+  private isUpdated(oldData?: IStoreItem, newData?: IStoreItem): boolean {
+    return !oldData || !newData || newData.version > oldData.version
+  }
+}

package/src/data-sources/createStreamListeners.ts

@@ -0,0 +1,66 @@
+import { IDataSourceUpdates } from "../store/IDataSourceUpdates";
+import { ILogger } from "../logging/ILogger";
+import { VoidFunction } from "../utils/VoidFunction";
+import {
+  deserializeAll,
+  deserializePatch,
+  IPatchData,
+  Flags
+} from "../store/serialization";
+import DataKinds from "../store/DataKinds";
+import { IStoreDataStorage } from "../store/store";
+import { EventName, ProcessStreamResponse } from "../data-sync/types";
+
+export const createPutListener = (
+  dataSourceUpdates: IDataSourceUpdates,
+  logger?: ILogger,
+  onPutCompleteHandler: VoidFunction = () => {
+  },
+) => ({
+  deserializeData: deserializeAll,
+  processJson: async (userKeyId: string, {flags}: Flags) => {
+    const initData: IStoreDataStorage = {
+      flags: flags,
+      version: 0
+    };
+
+    logger?.debug('Initializing all data');
+    dataSourceUpdates.init(userKeyId, initData, onPutCompleteHandler);
+  },
+});
+
+export const createPatchListener = (
+  dataSourceUpdates: IDataSourceUpdates,
+  logger?: ILogger,
+  onPatchCompleteHandler: VoidFunction = () => {
+  },
+) => ({
+  deserializeData: deserializePatch,
+  processJson: async (userKeyId: string, data: IPatchData[]) => {
+    if (data?.length === 0) {
+      onPatchCompleteHandler?.();
+      return;
+    }
+
+    data?.forEach(item => {
+      logger?.debug(`Updating ${ item.data.key } in ${ item.kind.namespace }`);
+      dataSourceUpdates.upsert(userKeyId, item.kind, item.data, onPatchCompleteHandler);
+    })
+  },
+});
+
+
+export const createStreamListeners = (
+  dataSourceUpdates: IDataSourceUpdates,
+  logger?: ILogger,
+  onCompleteHandlers?: {
+    put?: VoidFunction;
+    patch?: VoidFunction;
+    delete?: VoidFunction;
+  },
+) => {
+  const listeners = new Map<EventName, ProcessStreamResponse>();
+  listeners.set('put', createPutListener(dataSourceUpdates, logger, onCompleteHandlers?.put));
+  listeners.set('patch', createPatchListener(dataSourceUpdates, logger, onCompleteHandlers?.patch));
+  return listeners;
+};

package/src/data-sources/index.ts

@@ -0,0 +1,2 @@
+export * from './createStreamListeners';
+export * from './DataSourceUpdates';

package/src/data-sync/DataSyncMode.ts

@@ -0,0 +1,4 @@
+export enum DataSyncModeEnum {
+  POLLING = 'polling',
+  STREAMING = 'streaming'
+}

package/src/data-sync/IDataSynchronizer.ts

@@ -0,0 +1,15 @@
+import { IUser } from "../options/IUser";
+
+/**
+ * The client data synchronizer
+ *
+ * The client uses this internally to retrieve updates from the FeatBit server.
+ *
+ * @ignore
+ */
+export interface IDataSynchronizer {
+  start: () => void;
+  stop: () => void;
+  close: () => void;
+  identify: (user: IUser) => void;
+}

package/src/data-sync/IRequestor.ts

@@ -0,0 +1,10 @@
+/**
+ * The FeatBit client feature flag requestor
+ *
+ * The client uses this internally to retrieve feature flags from FeatBit.
+ *
+ * @ignore
+ */
+export interface IRequestor {
+  requestData: (timestamp: number, payload: any, cb: (err: any, body: any) => void) => void;
+}

package/src/data-sync/NullDataSynchronizer.ts

@@ -0,0 +1,15 @@
+import { IDataSynchronizer } from "./IDataSynchronizer";
+
+export class NullDataSynchronizer implements IDataSynchronizer {
+  close(): void {
+  }
+
+  start(): void {
+  }
+
+  stop(): void {
+  }
+
+  identify(): void {
+  }
+}