@featbit/js-client-sdk 2.0.1 → 3.0.0

package/src/options/IValidatedOptions.ts

@@ -0,0 +1,30 @@
+import { ILogger } from "../logging/ILogger";
+import { IStore } from "../platform/IStore";
+import { IOptions } from "./IOptions";
+import { IDataSynchronizer } from "../data-sync/IDataSynchronizer";
+import { DataSyncModeEnum } from "../data-sync/DataSyncMode";
+import { IUser } from "./IUser";
+import { IBootstrapProvider } from "../bootstrap";
+import { IFlagBase } from "../evaluation";
+
+export interface IValidatedOptions {
+  startWaitTime: number;
+  sdkKey: string;
+  pollingUri: string;
+  streamingUri: string;
+  eventsUri: string;
+  dataSyncMode: DataSyncModeEnum;
+  webSocketPingInterval?: number;
+  flushInterval: number;
+  maxEventsInQueue: number;
+  pollingInterval: number;
+  offline: boolean;
+  store: IStore | ((options: IOptions) => IStore);
+  dataSynchronizer?: IDataSynchronizer;
+  logger?: ILogger;
+  user?: IUser;
+  bootstrap?: IFlagBase[];
+
+  // Allow indexing this by a string for the validation step.
+  [index: string]: any;
+}

package/src/options/OptionMessages.ts

@@ -0,0 +1,36 @@
+/**
+ * Messages for issues which can be encountered from processing the configuration options.
+ */
+export default class OptionMessages {
+  static optionBelowMinimum(name: string, value: number, min: number): string {
+    return `Config option "${ name }" had invalid value of ${ value }, using minimum of ${ min } instead`;
+  }
+
+  static unknownOption(name: string): string {
+    return `Ignoring unknown config option "${ name }"`;
+  }
+
+  static wrongOptionType(name: string, expectedType: string, actualType: string): string {
+    return `Config option "${ name }" should be of type ${ expectedType }, got ${ actualType }, using default value`;
+  }
+
+  static wrongOptionTypeBoolean(name: string, actualType: string): string {
+    return `Config option "${ name }" should be a boolean, got ${ actualType }, converting to boolean`;
+  }
+
+  static partialEndpoint(name: string): string {
+    return `You have set custom uris without specifying the ${ name } URI; connections may not work properly`;
+  }
+
+  static mandatory(name: string): string {
+    return `${ name } is mandatory`;
+  }
+
+  static invalidOptionValue(name: string): string {
+    return `Invalid option value: ${ name }`;
+  }
+
+  static missingKeyInBootstrapValue(key: string): string {
+    return `Missing key "${ key }" in bootstrap value`;
+  }
+}

package/src/options/UserBuilder.ts

@@ -0,0 +1,36 @@
+import { IUser } from "./IUser";
+import {IContextProperty} from "../IContextProperty";
+
+/**
+ * Creates an instance of the FeatBit user.
+ *
+ * @return
+ *   The new {@link IUser} instance.
+ */
+export class UserBuilder {
+  private _keyId: string = '';
+  private _name: string = '';
+  private _custom: IContextProperty[] = [];
+
+  constructor(keyId: string) {
+    this._keyId = keyId;
+  }
+
+  name(name: string): UserBuilder {
+    this._name = name;
+    return this;
+  }
+
+  custom(propertyName: string, value: string): UserBuilder {
+    this._custom?.push({ name: propertyName, value: value });
+    return this;
+  }
+
+  build(): IUser {
+    return {
+      name: this._name,
+      keyId: this._keyId,
+      customizedProperties: this._custom
+    };
+  }
+}

package/src/options/Validators.ts

@@ -0,0 +1,301 @@
+/* eslint-disable class-methods-use-this */
+/* eslint-disable max-classes-per-file */
+
+// The classes here are static, but needs to be instantiated to
+// support the generic functionality. Which is why we do not care about using
+// `this`
+
+// These validators are also of trivial complexity, so we are allowing more than
+// one per file.
+
+import OptionMessages from "./OptionMessages";
+import { IFlagBase } from "../evaluation";
+
+/**
+ * Interface for type validation.
+ */
+export interface TypeValidator {
+  // holding validation error messages
+  messages?: string[];
+
+  is(u: unknown): boolean;
+
+  getType(): string;
+}
+
+/**
+ * Validate a factory or instance.
+ */
+export class FactoryOrInstance implements TypeValidator {
+  is(factoryOrInstance: unknown) {
+    if (Array.isArray(factoryOrInstance)) {
+      return false;
+    }
+    const anyFactory = factoryOrInstance as any;
+    const typeOfFactory = typeof anyFactory;
+    return typeOfFactory === 'function' || typeOfFactory === 'object';
+  }
+
+  getType(): string {
+    return 'factory method or object';
+  }
+}
+
+/**
+ * Validate a basic type.
+ */
+export class Type<T> implements TypeValidator {
+  private typeName: string;
+
+  protected typeOf: string;
+
+  constructor(typeName: string, example: T) {
+    this.typeName = typeName;
+    this.typeOf = typeof example;
+  }
+
+  is(u: unknown): u is T {
+    if (Array.isArray(u)) {
+      return false;
+    }
+    return typeof u === this.typeOf;
+  }
+
+  getType(): string {
+    return this.typeName;
+  }
+}
+
+/**
+ * Validate an array of the specified type.
+ *
+ * This does not validate instances of types. All class instances
+ * of classes will simply objects.
+ */
+export class TypeArray<T> implements TypeValidator {
+  private typeName: string;
+
+  protected typeOf: string;
+
+  constructor(typeName: string, example: T) {
+    this.typeName = typeName;
+    this.typeOf = typeof example;
+  }
+
+  is(u: unknown): u is T {
+    if (Array.isArray(u)) {
+      if (u.length > 0) {
+        return u.every((val) => typeof val === this.typeOf);
+      }
+      return true;
+    }
+    return false;
+  }
+
+  getType(): string {
+    return this.typeName;
+  }
+}
+
+/**
+ * Validate a value is a number and is greater or eval than a minimum.
+ */
+export class NumberWithMinimum extends Type<number> {
+  readonly min: number;
+
+  constructor(min: number) {
+    super(`number with minimum value of ${ min }`, 0);
+    this.min = min;
+  }
+
+  override is(u: unknown): u is number {
+    return typeof u === this.typeOf && (u as number) >= this.min;
+  }
+}
+
+/**
+ * Validate a value is a string and it matches the given expression.
+ */
+export class StringMatchingRegex extends Type<string> {
+  readonly expression: RegExp;
+
+  constructor(expression: RegExp) {
+    super(`string matching ${ expression }`, '');
+    this.expression = expression;
+  }
+
+  override is(u: unknown): u is string {
+    return !!(u as string).match(this.expression);
+  }
+}
+
+/**
+ * Validate a value is a function.
+ */
+export class Function implements TypeValidator {
+  is(u: unknown): u is (...args: any[]) => void {
+    // We cannot inspect the parameters and there isn't really
+    // a generic function type we can instantiate.
+    // So the type guard is here just to make TS comfortable
+    // calling something after using this guard.
+    return typeof u === 'function';
+  }
+
+  getType(): string {
+    return 'function';
+  }
+}
+
+export class NullableBoolean implements TypeValidator {
+  is(u: unknown): boolean {
+    return typeof u === 'boolean' || typeof u === 'undefined' || u === null;
+  }
+
+  getType(): string {
+    return 'boolean | undefined | null';
+  }
+}
+
+export class BootstrapValidator implements TypeValidator {
+  messages: string[] = [];
+
+  is(u: unknown): boolean {
+    if (typeof u !== 'object' || u === null) {
+      this.messages.push(OptionMessages.invalidOptionValue('bootstrap'));
+      return false;
+    }
+
+    try {
+      const bootstrap = u as IFlagBase[];
+      for (let flag of bootstrap) {
+        const hasMandatoryKeys = ['id', 'variation'].every((key) => Object.keys(flag).includes(key));
+        const keys = Object.keys(flag);
+
+        if (keys.includes('id')) {
+          this.messages.push(OptionMessages.missingKeyInBootstrapValue('id'));
+        }
+
+        if (keys.includes('variation')) {
+          this.messages.push(OptionMessages.missingKeyInBootstrapValue('variation'));
+        }
+
+        if (this.messages.length > 0) {
+          return false;
+        }
+      }
+    } catch (_) {
+      this.messages.push(OptionMessages.wrongOptionType('bootstrap', this.getType(), typeof u));
+      return false;
+    }
+
+    return true;
+  }
+
+  getType(): string {
+    return 'IFlagBase[]';
+  }
+}
+
+export class UserValidator implements TypeValidator {
+  messages: string[] = [];
+
+  is(u: unknown): boolean {
+    if (typeof u !== 'object' || u === null) {
+      this.messages.push(OptionMessages.mandatory('user'));
+      return false;
+    }
+
+    const user = u as any;
+
+    if (typeof user.keyId !== 'string' || user.keyId.trim() === '') {
+      this.messages.push(OptionMessages.mandatory('user.keyId'));
+      return false;
+    }
+
+    if (typeof user.name !== 'string' || user.name.trim() === '') {
+      this.messages.push(OptionMessages.mandatory('user.name'));
+      return false;
+    }
+
+    return true;
+  }
+
+  getType(): string {
+    return 'user';
+  }
+}
+
+// Our reference SDK, Go, parses date/time strings with the time.RFC3339Nano format.
+// This regex should match strings that are valid in that format, and no others.
+// Acceptable:
+//   2019-10-31T23:59:59Z, 2019-10-31T23:59:59.100Z,
+//   2019-10-31T23:59:59-07, 2019-10-31T23:59:59-07:00, etc.
+// Unacceptable: no "T", no time zone designation
+const DATE_REGEX = /^\d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d\d*)?(Z|[-+]\d\d(:\d\d)?)/;
+
+/**
+ * Validate a value is a date. Values which are numbers are treated as dates and any string
+ * which if compliant with `time.RFC3339Nano` is a date.
+ */
+export class DateValidator implements TypeValidator {
+  is(u: unknown): boolean {
+    return typeof u === 'number' || (typeof u === 'string' && DATE_REGEX.test(u));
+  }
+
+  getType(): string {
+    return 'date';
+  }
+}
+
+/**
+ * Validates that a string is a valid kind.
+ */
+export class KindValidator extends StringMatchingRegex {
+  constructor() {
+    super(/^(\w|\.|-)+$/);
+  }
+
+  override is(u: unknown): u is string {
+    return super.is(u) && u !== 'kind';
+  }
+}
+
+/**
+ * A set of standard type validators.
+ */
+export class TypeValidators {
+  static readonly String = new Type<string>('string', '');
+
+  static readonly Number = new Type<number>('number', 0);
+
+  static readonly ObjectOrFactory = new FactoryOrInstance();
+
+  static readonly Object = new Type<object>('object', {});
+
+  static readonly StringArray = new TypeArray<string>('string[]', '');
+
+  static readonly Boolean = new Type<boolean>('boolean', true);
+
+  static readonly User = new Type<object>('object', {});
+
+  static readonly Bootstrap = new Type<object>('object', {});
+
+  static readonly Function = new Function();
+
+  static createTypeArray<T>(typeName: string, example: T) {
+    return new TypeArray<T>(typeName, example);
+  }
+
+  static numberWithMin(min: number): NumberWithMinimum {
+    return new NumberWithMinimum(min);
+  }
+
+  static stringMatchingRegex(expression: RegExp): StringMatchingRegex {
+    return new StringMatchingRegex(expression);
+  }
+
+  static readonly Date = new DateValidator();
+
+  static readonly Kind = new KindValidator();
+  static readonly NullableBoolean = new NullableBoolean();
+}

package/src/options/index.ts

@@ -0,0 +1,8 @@
+export * from './ClientContext';
+export * from './IClientContext';
+export * from './IOptions';
+export * from './IUser';
+export * from './IValidatedOptions';
+export * from './OptionMessages';
+export * from './UserBuilder';
+export * from './Validators';

package/src/platform/IInfo.ts

@@ -0,0 +1,82 @@
+/**
+ * Information about the platform of the SDK and the environment it is executing.
+ */
+export interface IPlatformData {
+  /**
+   * Information about the OS on which the SDK is running. Should be populated
+   * when available. Not all platforms will make this data accessible.
+   */
+  os?: {
+    /**
+     * The architecture. Ideally at runtime, but may be build time if that is
+     * a constraint.
+     */
+    arch?: string;
+    /**
+     * The name of the OS. "MacOS", "Windows", or "Linux". If not one of those,
+     * then use the value provided by the OS.
+     */
+    name?: string;
+
+    /** The version of the OS. */
+    version?: string;
+  };
+
+  /**
+   * The name of the platform the SDK is running on. For instance 'Node'.
+   */
+  name?: string;
+
+  /**
+   * Any additional attributes associated with the platform.
+   */
+  additional?: Record<string, string>;
+}
+
+export interface ISdkData {
+  /**
+   * The name of the SDK. e.g. "browser-server-sdk"
+   */
+  name?: string;
+
+  /**
+   * The version of the SDK.
+   */
+  version?: string;
+
+  /**
+   * If this is a top-level (not a wrapper) SDK this will be used to create the user agent string.
+   * It will take the form 'userAgentBase/version`.
+   */
+  userAgentBase?: string;
+
+  /**
+   * Name of the wrapper SDK if present.
+   */
+  wrapperName?: string;
+  /**
+   * Version of the wrapper if present.
+   */
+  wrapperVersion?: string;
+}
+
+/**
+ * Interface for getting information about the SDK or the environment it is
+ * executing in.
+ */
+export interface IInfo {
+  /**
+   * Get the app type
+   */
+  get appType(): string;
+
+  /**
+   * Get information about the platform.
+   */
+  platformData(): IPlatformData;
+
+  /**
+   * Get information about the SDK implementation.
+   */
+  sdkData(): ISdkData;
+}

package/src/platform/IPlatform.ts

@@ -0,0 +1,21 @@
+import { IRequests } from "./requests";
+import { IInfo } from "./IInfo";
+import { IWebSocketWithEvents } from "./IWebSocket";
+
+export interface IPlatform {
+  /**
+   * The interface for getting information about the platform and the execution
+   * environment.
+   */
+  info: IInfo;
+
+  /**
+   * The interface for performing http/https requests.
+   */
+  requests: IRequests;
+
+  /**
+   * The interface for performing websocket connections.
+   */
+  webSocket: IWebSocketWithEvents;
+}

package/src/platform/IStore.ts

@@ -0,0 +1,119 @@
+import { IDataKind } from "../IDataKind";
+import { IKeyedStoreItem, IStoreDataStorage, IStoreItem, IStoreKindData } from "../store/store";
+import { IUser } from "../options/IUser";
+
+/**
+ * Interface for a feature store component.
+ *
+ * The feature store is what the client uses to store feature flag data that has been received
+ * from FeatBit. By default, it uses an in-memory implementation; database integrations are
+ * also available. Read the [SDK features guide](xxx).
+ * You will not need to use this interface unless you are writing your own implementation.
+ *
+ * Feature store methods can and should call their callbacks directly whenever possible, rather
+ * than deferring them with setImmediate() or process.nextTick(). This means that if for any
+ * reason you are updating or querying a feature store directly in your application code (which
+ * is not part of normal use of the SDK) you should be aware that the callback may be executed
+ * immediately.
+ */
+export interface IStore {
+  /**
+   * Set the current user of the store.
+   *
+   * @param user
+   *   The current user. The actual type of this parameter is
+   *   {@link IUser}.
+   */
+  identify(user: IUser): void;
+
+  /**
+   * Get the current user of the store.
+   */
+  user: IUser;
+
+  /**
+   * Get an entity from the store.
+   *
+   * The store should treat any entity with the property `deleted: true` as "not found".
+   *
+   * @param kind
+   *   The type of data to be accessed. The store should not make any assumptions about the format
+   *   of the data, but just return a JSON object. The actual type of this parameter is
+   *   {@link DataKind}.
+   *
+   * @param key
+   *   The unique key of the entity within the specified collection.
+   */
+  get(kind: IDataKind, key: string): IStoreItem | null
+
+  /**
+   * Get all entities from a collection.
+   *
+   * The store should filter out any entities with the property `deleted: true`.
+   *
+   * @param kind
+   *   The type of data to be accessed. The store should not make any assumptions about the format
+   *   of the data, but just return an object in which each key is the `key` property of an entity
+   *   and the value is the entity. The actual type of this parameter is
+   *   {@link IDataKind}.
+   */
+  all(kind: IDataKind): [IStoreKindData, number];
+
+  /**
+   * Initialize the store, overwriting any existing data.
+   *
+   * @param allData
+   *   An object in which each key is the "namespace" of a collection (e.g. `"features"`) and
+   *   the value is an object that maps keys to entities. The actual type of this parameter is
+   *   `interfaces.FullDataSet<VersionedData>`.
+   *
+   * @param callback
+   *   Will be called when the store has been initialized.
+   */
+  init(allData: IStoreDataStorage, callback: () => void): void;
+
+  /**
+   * Add an entity or update an existing entity.
+   *
+   * @param kind
+   *   The type of data to be accessed. The actual type of this parameter is
+   *   {@link IDataKind}.
+   *
+   * @param data
+   *   The contents of the entity, as an object that can be converted to JSON. The store
+   *   should check the `version` property of this object, and should *not* overwrite any
+   *   existing data if the existing `version` is greater than or equal to that value.
+   *   The actual type of this parameter is {@link IKeyedStoreItem}.
+   *
+   * @param callback
+   *   Will be called after the upsert operation is complete.
+   */
+  upsert(kind: IDataKind, data: IKeyedStoreItem, callback: () => void): void;
+
+  /**
+   * Tests whether the store is initialized.
+   *
+   * "Initialized" means that the store has been populated with data, either by the client
+   * having called `init()` within this process, or by another process (if this is a shared
+   * database).
+   *
+   * @param callback
+   *   Will be called back with the boolean result.
+   */
+  initialized(): boolean;
+
+  /**
+   * Releases any resources being used by the feature store.
+   */
+  close(): void;
+
+  /**
+   * Get a description of the store.
+   */
+  getDescription?(): string;
+
+  /**
+   * The current version of the store.
+   */
+  version: number;
+}

package/src/platform/IWebSocket.ts

@@ -0,0 +1,23 @@
+import { IEventEmitter } from "../utils/IEventEmitter";
+import { ILogger } from "../logging/ILogger";
+import { IUser } from "../options/IUser";
+
+export interface IWebSocketConfig {
+  sdkKey: string;
+  streamingUri: string;
+  pingInterval: number;
+  user: IUser;
+  logger: ILogger;
+  getStoreTimestamp: () => number,
+  emitter?: IEventEmitter;
+}
+
+export interface IWebSocket {
+  connect: () => void;
+  close: () => void;
+  config: (param: IWebSocketConfig) => void;
+  identify: (user: IUser) => void;
+}
+
+export interface IWebSocketWithEvents extends IWebSocket, IEventEmitter {
+}

package/src/platform/browser/BrowserInfo.ts

@@ -0,0 +1,25 @@
+import { IInfo, IPlatformData, ISdkData } from "../IInfo";
+import { name, version } from '../../version';
+
+
+export default class BrowserInfo implements IInfo {
+  get appType(): string {
+    return 'Browser-Client-SDK';
+  }
+
+  platformData(): IPlatformData {
+    return {
+      os: {},
+      name: 'Browser',
+      additional: {},
+    };
+  }
+
+  sdkData(): ISdkData {
+    return {
+      name: name,
+      version: version,
+      userAgentBase: this.appType
+    };
+  }
+}