@featbit/js-client-sdk 2.0.1 → 3.0.0

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@featbit/js-client-sdk",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "https://github.com/featbit/featbit-js-client-sdk",
-  "main": "esm/index.js",
+  "main": "./dist/esm/index.js",
+  "module": "./dist/esm/index.js",
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
-    "watch-esm": "rimraf esm && tsc --watch",
-    "watch-umd": "rimraf umd && webpack --watch --mode development",
-    "build": "rimraf umd && rimraf esm && tsc && webpack --mode production",
-    "prepublishOnly": "npm run build",
-    "lint": "gts lint",
-    "clean": "gts clean",
-    "compile": "tsc",
-    "fix": "gts fix"
+    "prebuild": "node -p \"'export const version = \\\"' + require('./package.json').version + '\\\"; export const name = \\\"' + require('./package.json').name + '\\\";'\" > src/version.ts",
+    "build": "rimraf dist && tsc -p tsconfig.json && webpack --mode production",
+    "test": "npx jest --ci",
+    "test-coverage": "npx jest --ci --coverage",
+    "prepublishOnly": "npm run build"
   },
   "repository": {
     "type": "git",
@@ -19,30 +21,26 @@
   },
   "keywords": [
     "featbit",
+    "client sdk",
     "feature flags",
     "feature management"
   ],
   "author": "featbit.co",
-  "license": "ISC",
+  "license": "MIT",
   "bugs": {
     "url": "https://github.com/featbit/featbit-js-client-sdk/issues"
   },
   "homepage": "https://github.com/featbit/featbit-js-client-sdk#readme",
-  "files": [
-    "/esm",
-    "/umd",
-    "/src"
-  ],
   "devDependencies": {
-    "gts": "^5.2.0",
-    "rimraf": "^3.0.2",
+    "@types/jest": "^29.5.11",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "rimraf": "^5.0.5",
     "string-replace-loader": "^3.1.0",
-    "ts-loader": "^9.2.6",
-    "tslint": "^6.1.3",
+    "ts-jest": "^29.1.1",
+    "ts-loader": "^9.5.1",
     "typescript": "^5.2.2",
-    "webpack": "^5.67.0",
-    "webpack-cli": "^4.9.2"
-  },
-  "dependencies": {
+    "webpack": "^5.91.0",
+    "webpack-cli": "^5.1.4"
   }
 }

package/src/Configuration.ts

@@ -0,0 +1,234 @@
+import { IOptions } from "./options/IOptions";
+import { ILogger } from "./logging/ILogger";
+import { IValidatedOptions } from "./options/IValidatedOptions";
+import { NumberWithMinimum, TypeValidator, TypeValidators, UserValidator } from "./options/Validators";
+import OptionMessages from "./options/OptionMessages";
+import { IStore } from "./platform/IStore";
+import { IClientContext } from "./options/IClientContext";
+import { IDataSynchronizer } from "./data-sync/IDataSynchronizer";
+import { IDataSourceUpdates } from "./store/IDataSourceUpdates";
+import InMemoryStore from "./store/InMemoryStore";
+import { VoidFunction } from "./utils/VoidFunction";
+import { isNullOrUndefined } from "./utils/isNullOrUndefined";
+import { canonicalizeUri } from "./utils/canonicalizeUri";
+import { IBootstrapProvider } from "./bootstrap/IBootstrapProvider";
+import { NullBootstrapProvider } from "./bootstrap/NullBootstrapProvider";
+import { EmptyString } from "./constants";
+import { DataSyncModeEnum } from "./data-sync/DataSyncMode";
+import { IUser } from "./options/IUser";
+import LocalStorageStore from "./platform/browser/LocalStorageStore";
+import { JsonBootstrapProvider } from "./bootstrap";
+
+// Once things are internal to the implementation of the SDK we can depend on
+// types. Calls to the SDK could contain anything without any regard to typing.
+// So, data we take from external sources must be normalized into something
+// that can be trusted.
+
+/**
+ * These perform cursory validations. Complex objects are implemented with classes
+ * and these should allow for conditional construction.
+ */
+const validations: Record<string, TypeValidator> = {
+  startWaitTime: TypeValidators.Number,
+  sdkKey: TypeValidators.String,
+  pollingUri: TypeValidators.String,
+  streamingUri: TypeValidators.String,
+  eventsUri: TypeValidators.String,
+  webSocketPingInterval: TypeValidators.Number,
+  logger: TypeValidators.Object,
+  store: TypeValidators.ObjectOrFactory,
+  dataSynchronizer: TypeValidators.ObjectOrFactory,
+  flushInterval: TypeValidators.Number,
+  maxEventsInQueue: TypeValidators.Number,
+  pollingInterval: TypeValidators.Number,
+  offline: TypeValidators.Boolean,
+  dataSyncMode: TypeValidators.String,
+  bootstrap: TypeValidators.Bootstrap,
+  user: TypeValidators.User
+};
+
+/**
+ * @internal
+ */
+export const defaultValues: IValidatedOptions = {
+  startWaitTime: 5000,
+  sdkKey: '',
+  pollingUri: '',
+  streamingUri: '',
+  eventsUri: '',
+  dataSyncMode: DataSyncModeEnum.STREAMING,
+  sendEvents: true,
+  webSocketPingInterval: 18 * 1000,
+  flushInterval: 2000,
+  maxEventsInQueue: 10000,
+  pollingInterval: 30000,
+  offline: false,
+  store: (options: IOptions) => new LocalStorageStore(options),
+  bootstrap: undefined,
+  user: undefined,
+};
+
+function validateTypesAndNames(options: IOptions): {
+  errors: string[];
+  validatedOptions: IValidatedOptions;
+} {
+  let errors: string[] = [];
+  const validatedOptions: IValidatedOptions = {...defaultValues};
+  Object.keys(options).forEach((optionName) => {
+    // We need to tell typescript it doesn't actually know what options are.
+    // If we don't then it complains we are doing crazy things with it.
+    const optionValue = (options as unknown as any)[optionName];
+    const validator = validations[optionName];
+    if (validator) {
+      if (!validator.is(optionValue)) {
+        if (validator.getType() === 'boolean') {
+          errors.push(OptionMessages.wrongOptionTypeBoolean(optionName, typeof optionValue));
+          validatedOptions[optionName] = !!optionValue;
+        } else if (
+          validator instanceof NumberWithMinimum &&
+          TypeValidators.Number.is(optionValue)
+        ) {
+          const {min} = validator as NumberWithMinimum;
+          errors.push(OptionMessages.optionBelowMinimum(optionName, optionValue, min));
+          validatedOptions[optionName] = min;
+        } else if (validator instanceof UserValidator) {
+          errors = [...errors, ...validator.messages];
+          validatedOptions[optionName] = defaultValues[optionName];
+        } else {
+          errors.push(
+            OptionMessages.wrongOptionType(optionName, validator.getType(), typeof optionValue),
+          );
+          validatedOptions[optionName] = defaultValues[optionName];
+        }
+      } else {
+        validatedOptions[optionName] = optionValue;
+      }
+    } else {
+      options.logger?.warn(OptionMessages.unknownOption(optionName));
+    }
+  });
+  return {errors, validatedOptions};
+}
+
+function validateEndpoints(options: IOptions, validatedOptions: IValidatedOptions) {
+  const {streamingUri, pollingUri, eventsUri} = options;
+  const streamingUriMissing = isNullOrUndefined(streamingUri) || streamingUri === EmptyString;
+  const pollingUriMissing = isNullOrUndefined(pollingUri) || pollingUri === EmptyString;
+  const eventsUriMissing = isNullOrUndefined(eventsUri) || eventsUri === EmptyString;
+
+  if (!validatedOptions.offline && (eventsUriMissing || (streamingUriMissing && pollingUriMissing))) {
+    if (eventsUriMissing) {
+      validatedOptions.logger?.error(OptionMessages.partialEndpoint('eventsUri'));
+    }
+
+    if (validatedOptions.dataSyncMode === DataSyncModeEnum.STREAMING && streamingUriMissing) {
+      validatedOptions.logger?.error(OptionMessages.partialEndpoint('streamingUri'));
+    }
+
+    if (validatedOptions.dataSyncMode === DataSyncModeEnum.POLLING && pollingUriMissing) {
+      validatedOptions.logger?.error(OptionMessages.partialEndpoint('pollingUri'));
+    }
+  }
+}
+
+export default class Configuration {
+  public readonly startWaitTime: number;
+
+  public readonly sdkKey: string;
+
+  public readonly streamingUri: string;
+
+  public readonly pollingUri: string;
+
+  public readonly eventsUri: string;
+
+  public readonly webSocketPingInterval: number;
+
+  public readonly logger?: ILogger;
+
+  public readonly flushInterval: number;
+
+  public readonly maxEventsInQueue: number;
+
+  public readonly pollingInterval: number;
+
+  public readonly offline: boolean;
+
+  public readonly dataSyncMode: DataSyncModeEnum;
+
+  public readonly bootstrapProvider: IBootstrapProvider = new NullBootstrapProvider();
+
+  public readonly user: IUser;
+
+  public readonly storeFactory: (clientContext: IClientContext) => IStore;
+
+  public readonly dataSynchronizerFactory?: (
+    clientContext: IClientContext,
+    store: IStore,
+    dataSourceUpdates: IDataSourceUpdates,
+    initSuccessHandler: VoidFunction,
+    errorHandler?: (e: Error) => void,
+  ) => IDataSynchronizer;
+
+  constructor(options: IOptions = {}) {
+    // The default will handle undefined, but not null.
+    // Because we can be called from JS we need to be extra defensive.
+    options = options || {};
+    // If there isn't a valid logger from the platform, then logs would go nowhere.
+    this.logger = options.logger;
+
+    const {errors, validatedOptions} = validateTypesAndNames(options);
+    errors.forEach((error) => {
+      this.logger?.warn(error);
+    });
+
+    this.user = options.user!;
+
+    validateEndpoints(options, validatedOptions);
+    this.streamingUri = `${ canonicalizeUri(validatedOptions.streamingUri) }/streaming`;
+    this.pollingUri = `${ canonicalizeUri(validatedOptions.pollingUri) }/api/public/sdk/client/latest-all`;
+    this.eventsUri = `${ canonicalizeUri(validatedOptions.eventsUri) }/api/public/insight/track`;
+
+    this.startWaitTime = validatedOptions.startWaitTime;
+
+    this.sdkKey = validatedOptions.sdkKey;
+    this.webSocketPingInterval = validatedOptions.webSocketPingInterval!;
+
+    this.flushInterval = validatedOptions.flushInterval;
+    this.maxEventsInQueue = validatedOptions.maxEventsInQueue;
+    this.pollingInterval = validatedOptions.pollingInterval;
+
+    this.offline = validatedOptions.offline;
+    if (validatedOptions.bootstrap && validatedOptions.bootstrap.length > 0) {
+      try {
+        this.bootstrapProvider = new JsonBootstrapProvider(validatedOptions.bootstrap);
+      } catch (_) {
+        this.logger?.error('Failed to parse bootstrap JSON, use NullBootstrapProvider.');
+      }
+    }
+
+    if (this.offline) {
+      this.logger?.info('Offline mode enabled. No data synchronization with the FeatBit server will occur.');
+    }
+
+    this.dataSyncMode = validatedOptions.dataSyncMode;
+
+    if (TypeValidators.Function.is(validatedOptions.dataSynchronizer)) {
+      // @ts-ignore
+      this.dataSynchronizerFactory = validatedOptions.dataSynchronizer;
+    } else {
+      // The processor is already created, just have the method return it.
+      // @ts-ignore
+      this.dataSynchronizerFactory = () => validatedOptions.dataSynchronizer;
+    }
+
+    if (TypeValidators.Function.is(validatedOptions.store)) {
+      // @ts-ignore
+      this.storeFactory = validatedOptions.store;
+    } else {
+      // The store is already created, just have the method return it.
+      // @ts-ignore
+      this.storeFactory = () => validatedOptions.store;
+    }
+  }
+}

package/src/Context.ts

@@ -0,0 +1,62 @@
+import { IUser } from "./options/IUser";
+
+export default class Context {
+  private _user?: IUser;
+  /**
+   * Is this a valid context. If a valid context cannot be created, then this flag will be true.
+   * The validity of a context should be tested before it is used.
+   */
+  public readonly valid: boolean;
+
+  public readonly message?: string;
+
+  /**
+   * Contexts should be created using the static factory method {@link Context.fromUser}.
+   *
+   * The factory methods are static functions within the class because they access private
+   * implementation details, so they cannot be free functions.
+   */
+  private constructor(valid: boolean, message?: string) {
+    this.valid = valid;
+    this.message = message;
+  }
+
+  public static fromUser(user: IUser): Context {
+    if (!user) {
+      return Context.contextForError('No user specified');
+    }
+
+    const {keyId, name} = user;
+
+    if (keyId === undefined || keyId === null || keyId.trim() === '') {
+      return Context.contextForError('key is mandatory');
+    }
+
+    const context = new Context(true);
+    context._user = user;
+
+    return context;
+  }
+
+  get user(): IUser {
+    return this._user!;
+  }
+
+  get keyId(): string {
+    return this._user!.keyId;
+  }
+
+  value(property: string): any {
+    if (property === 'keyId') {
+      return this._user?.keyId;
+    } else if (property === 'name') {
+      return this._user?.name;
+    } else {
+      return this._user?.customizedProperties?.find(x => x.name === property)?.value;
+    }
+  }
+
+  private static contextForError(message: string) {
+    return new Context(false, message);
+  }
+}

package/src/FbClientBuilder.ts

@@ -0,0 +1,161 @@
+import { IFbClient } from "./IFbClient";
+import { IOptions } from "./options/IOptions";
+import FbClient from "./platform/browser/FbClient";
+import { IDataSynchronizer } from "./data-sync/IDataSynchronizer";
+import { IClientContext } from "./options/IClientContext";
+import { IDataSourceUpdates } from "./store/IDataSourceUpdates";
+import { VoidFunction } from "./utils/VoidFunction";
+import { ILogger } from "./logging/ILogger";
+import { DataSyncModeEnum } from "./data-sync/DataSyncMode";
+import { IUser } from "./options/IUser";
+import { IFlagBase } from "./evaluation";
+
+/**
+ * Creates an instance of the FeatBit client.
+ *
+ * Applications should instantiate a single instance for the lifetime of the application.
+ * The client will begin attempting to connect to FeatBit as soon as it is created. To
+ * determine when it is ready to use, call {@link IFbClient.waitForInitialization}, or register an
+ * event listener for the `"ready"` event using {@link IFbClient.on}.
+ *
+ * **Important:** Do **not** try to instantiate `FbClient` with its constructor
+ * (`new FbClientNode()`); the SDK does not currently support
+ * this.
+ *
+ * @return
+ *   The new {@link IFbClient} instance.
+ */
+export class FbClientBuilder {
+  private _options: IOptions;
+
+  constructor(options?: IOptions) {
+    this._options = options ?? {};
+  }
+
+  /**
+   * Creates a new instance of the FeatBit client.
+   */
+  build(): IFbClient {
+    return new FbClient(this._options);
+  }
+
+  /**
+   * Refer to {@link IOptions.startWaitTime}.
+   */
+  startWaitTime(startWaitTime: number): FbClientBuilder {
+    this._options.startWaitTime = startWaitTime;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.sdkKey}.
+   */
+  sdkKey(sdkKey: string): FbClientBuilder {
+    this._options.sdkKey = sdkKey;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.user}.
+   */
+  user(user: IUser): FbClientBuilder {
+    this._options.user = user;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.streamingUri}.
+   */
+  streamingUri(streamingUri: string): FbClientBuilder {
+    this._options.streamingUri = streamingUri;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.pollingUri}.
+   */
+  pollingUri(pollingUri: string): FbClientBuilder {
+    this._options.pollingUri = pollingUri;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.eventsUri}.
+   */
+  eventsUri(eventsUri: string): FbClientBuilder {
+    this._options.eventsUri = eventsUri;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.dataSyncMode}.
+   */
+  dataSyncMode(mode: DataSyncModeEnum): FbClientBuilder {
+    this._options.dataSyncMode = mode;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.pollingInterval}.
+   */
+  pollingInterval(pollingInterval: number): FbClientBuilder {
+    this._options.pollingInterval = pollingInterval;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.flushInterval}.
+   */
+  flushInterval(flushInterval: number): FbClientBuilder {
+    this._options.flushInterval = flushInterval;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.maxEventsInQueue}.
+   */
+  maxEventsInQueue(maxEventsInQueue: number): FbClientBuilder {
+    this._options.maxEventsInQueue = maxEventsInQueue;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.logger}.
+   */
+  logger(logger: ILogger): FbClientBuilder {
+    this._options.logger = logger;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.offline}.
+   */
+  offline(offline: boolean): FbClientBuilder {
+    this._options.offline = offline;
+    return this;
+  }
+
+  /**
+   * Use the JsonBootstrapProvider.
+   */
+  bootstrap(flags: IFlagBase[]): FbClientBuilder {
+    this._options.bootstrap = flags;
+    return this;
+  }
+
+  /**
+   * Refer to {@link IOptions.dataSynchronizer}.
+   */
+  dataSynchronizer(
+    dataSynchronizer: IDataSynchronizer |
+    ((
+      clientContext: IClientContext,
+      dataSourceUpdates: IDataSourceUpdates,
+      initSuccessHandler: VoidFunction,
+      errorHandler?: (e: Error) => void,
+    ) => IDataSynchronizer)
+  ): FbClientBuilder {
+    this._options.dataSynchronizer = dataSynchronizer;
+    return this;
+  }
+}