@featbit/js-client-sdk 2.0.2 → 3.0.0

package/src/logging/BasicLogger.ts

@@ -0,0 +1,108 @@
+import format from './format';
+import { ILogger } from "./ILogger";
+import { IBasicLoggerOptions } from "./IBasicLoggerOptions";
+
+const LogPriority = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  none: 4,
+};
+
+const LevelNames = ['debug', 'info', 'warn', 'error', 'none'];
+
+/**
+ * A basic logger which handles filtering by level.
+ *
+ * With the default options it will write to `console.error`
+ * and it will use the formatting provided by `console.error`.
+ * If the destination is overwritten, then it will use an included
+ * formatter similar to `util.format`.
+ *
+ * If a formatter is available, then that should be overridden
+ * as well for performance.
+ */
+export class BasicLogger implements ILogger {
+  private logLevel: number;
+
+  private name: string;
+
+  private destination?: (line: string) => void;
+
+  private formatter?: (...args: any[]) => string;
+
+  /**
+   * This should only be used as a default fallback and not as a convenient
+   * solution. In most cases you should construct a new instance with the
+   * appropriate options for your specific needs.
+   */
+  static get() {
+    return new BasicLogger({});
+  }
+
+  constructor(options: IBasicLoggerOptions) {
+    this.logLevel = LogPriority[options.level ?? 'info'] ?? LogPriority.info;
+    this.name = options.name ?? 'FeatBit';
+    // eslint-disable-next-line no-console
+    this.destination = options.destination;
+    this.formatter = options.formatter;
+  }
+
+  private tryFormat(...args: any[]): string {
+    try {
+      if (this.formatter) {
+        // In case the provided formatter fails.
+        return this.formatter?.(...args);
+      }
+      return format(...args);
+    } catch {
+      return format(...args);
+    }
+  }
+
+  private tryWrite(msg: string) {
+    try {
+      this.destination!(msg);
+    } catch {
+      // eslint-disable-next-line no-console
+      console.error(msg);
+    }
+  }
+
+  private log(level: number, args: any[]) {
+    if (level >= this.logLevel) {
+      const prefix = `${ LevelNames[level] }: [${ this.name }]`;
+      try {
+        if (this.destination) {
+          this.tryWrite(`${ prefix } ${ this.tryFormat(...args) }`);
+        } else {
+          // `console.error` has its own formatter.
+          // So we don't need to do anything.
+          // eslint-disable-next-line no-console
+          console.error(...args);
+        }
+      } catch {
+        // If all else fails do not break.
+        // eslint-disable-next-line no-console
+        console.error(...args);
+      }
+    }
+  }
+
+  error(...args: any[]): void {
+    this.log(LogPriority.error, args);
+  }
+
+  warn(...args: any[]): void {
+    this.log(LogPriority.warn, args);
+  }
+
+  info(...args: any[]): void {
+    this.log(LogPriority.info, args);
+  }
+
+  debug(...args: any[]): void {
+    this.log(LogPriority.debug, args);
+  }
+}

package/src/logging/IBasicLoggerOptions.ts

@@ -0,0 +1,46 @@
+import { ILogLevel } from './LogLevel';
+
+/**
+ * Configuration for {@link basicLogger}.
+ */
+export interface IBasicLoggerOptions {
+  /**
+   * The lowest level of log message to enable.
+   *
+   * See {@link ILogLevel} for a list of possible levels. Setting a level here causes
+   * all lower-importance levels to be disabled: for instance, if you specify
+   * `'warn'`, then `'debug'` and `'info'` are disabled.
+   *
+   * If not specified, the default is `'info'` (meaning that `'debug'` is disabled).
+   */
+  level?: ILogLevel;
+
+  /**
+   * Name to use for the log entires. The default name is `FeatBit`.
+   */
+  name?: string;
+
+  /**
+   * An optional function to use to print each log line.
+   *
+   * If this is specified, `basicLogger` calls it to write each line of output. The
+   * argument is a fully formatted log line, not including a linefeed. The function
+   * is only called for log levels that are enabled.
+   *
+   * If not specified, the default is `console.error`.
+   *
+   * Setting this property to anything other than a function will cause SDK
+   * initialization to fail.
+   */
+  destination?: (line: string) => void;
+
+  /**
+   * An optional formatter to use. The formatter should be compatible
+   * with browser-style format strings like those used with `util.format`.
+   *
+   * If not specified, then a default implementation will be used.
+   * But using a browser-specific implementation, for instance, would
+   * have performance and quality benefits.
+   */
+  formatter?: (...args: any[]) => string;
+}

package/src/logging/ILogger.ts

@@ -0,0 +1,49 @@
+/**
+ * The FeatBit client logger interface.
+ *
+ * The {@link IOptions.logger} property accepts any object that conforms to this
+ * interface. The SDK only uses four logging levels: `error`, `warn`, `info`, and
+ * `debug`. It will call the corresponding method of the `ILogger` either with a
+ * single string argument, or with a format string and variable arguments in the
+ * format used by Node's `util.format()`.
+ *
+ * The [Winston](https://github.com/winstonjs/winston) logging package provides a
+ * logger that conforms to this interface, so if you have created a logger with
+ * Winston, you can simply put it into the {@link IOptions.logger} property.
+ *
+ * If you do not provide a logger object, the SDK uses the {@link basicLogger}
+ * implementation with a minimum level of `info`.
+ */
+export interface ILogger {
+  /**
+   * The error logger.
+   *
+   * @param args
+   *   A sequence of any JavaScript values.
+   */
+  error(...args: any[]): void;
+
+  /**
+   * The warning logger.
+   *
+   * @param args
+   *   A sequence of any JavaScript values.
+   */
+  warn(...args: any[]): void;
+
+  /**
+   * The info logger.
+   *
+   * @param args
+   *   A sequence of any JavaScript values.
+   */
+  info(...args: any[]): void;
+
+  /**
+   * The debug logger.
+   *
+   * @param args
+   *   A sequence of any JavaScript values.
+   */
+  debug(...args: any[]): void;
+}

package/src/logging/LogLevel.ts

@@ -0,0 +1,9 @@
+/**
+ * Logging levels that can be used with {@link basicLogger}.
+ *
+ * Set {@link BasicLoggerOptions.level} to one of these values to control what levels
+ * of log messages are enabled. Going from lowest importance (and most verbose)
+ * to most importance, the levels are `'debug'`, `'info'`, `'warn'`, and `'error'`.
+ * You can also specify `'none'` instead to disable all logging.
+ */
+export type ILogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';

package/src/logging/SafeLogger.ts

@@ -0,0 +1,70 @@
+import { ILogger } from "./ILogger";
+import { TypeValidators } from "../options/Validators";
+
+const loggerRequirements = {
+  error: TypeValidators.Function,
+  warn: TypeValidators.Function,
+  info: TypeValidators.Function,
+  debug: TypeValidators.Function,
+};
+
+/**
+ * The safeLogger logic exists because we allow the application to pass in a custom logger, but
+ * there is no guarantee that the logger works correctly and if it ever throws exceptions there
+ * could be serious consequences (e.g. an uncaught exception within an error event handler, due
+ * to the SDK trying to log the error, can terminate the application). An exception could result
+ * from faulty logic in the logger implementation, or it could be that this is not a logger at
+ * all but some other kind of object; the former is handled by a catch block that logs an error
+ * message to the SDK's default logger, and we can at least partly guard against the latter by
+ * checking for the presence of required methods at configuration time.
+ */
+export default class SafeLogger implements ILogger {
+  private logger: ILogger;
+
+  private fallback: ILogger;
+
+  /**
+   * Construct a safe logger with the specified logger.
+   * @param logger The logger to use.
+   * @param fallback A fallback logger to use in case an issue is  encountered using
+   * the provided logger.
+   */
+  constructor(logger: ILogger, fallback: ILogger) {
+    Object.entries(loggerRequirements).forEach(([level, validator]) => {
+      if (!validator.is((logger as any)[level])) {
+        throw new Error(`Provided logger instance must support logger.${ level }(...) method`);
+        // Note that the SDK normally does not throw exceptions to the application, but that rule
+        // does not apply to FbClientNode.init() which will throw an exception if the parameters are so
+        // invalid that we cannot proceed with creating the client. An invalid logger meets those
+        // criteria since the SDK calls the logger during nearly all of its operations.
+      }
+    });
+    this.logger = logger;
+    this.fallback = fallback;
+  }
+
+  private log(level: 'error' | 'warn' | 'info' | 'debug', args: any[]) {
+    try {
+      this.logger[level](...args);
+    } catch {
+      // If all else fails do not break.
+      this.fallback[level](...args);
+    }
+  }
+
+  error(...args: any[]): void {
+    this.log('error', args);
+  }
+
+  warn(...args: any[]): void {
+    this.log('warn', args);
+  }
+
+  info(...args: any[]): void {
+    this.log('info', args);
+  }
+
+  debug(...args: any[]): void {
+    this.log('debug', args);
+  }
+}

package/src/logging/format.ts

@@ -0,0 +1,154 @@
+import { TypeValidators } from "../options/Validators";
+
+
+/**
+ * Attempt to produce a string representation of a value.
+ * The format should be roughly comparable to `util.format`
+ * aside from object which will be JSON versus the `util.inspect`
+ * format.
+ * @param val
+ * @returns A string representation of the value if possible.
+ */
+function tryStringify(val: any) {
+  if (typeof val === 'string') {
+    return val;
+  }
+  if (val === undefined) {
+    return 'undefined';
+  }
+  if (val === null) {
+    return 'null';
+  }
+  if (Object.prototype.hasOwnProperty.call(val, 'toString')) {
+    try {
+      return val.toString();
+    } catch {
+      /* Keep going */
+    }
+  }
+
+  if (typeof val === 'bigint') {
+    return `${ val }n`;
+  }
+  try {
+    return JSON.stringify(val);
+  } catch (error) {
+    if (error instanceof TypeError && error.message.indexOf('circular') >= 0) {
+      return '[Circular]';
+    }
+    return '[Not Stringifiable]';
+  }
+}
+
+/**
+ * Attempt to produce a numeric representation.
+ * BigInts have an `n` suffix.
+ * @param val
+ * @returns The numeric representation or 'NaN' if not numeric.
+ */
+function toNumber(val: any): string {
+  // Symbol has to be treated special because it will
+  // throw an exception if an attempt is made to convert it.
+  if (typeof val === 'symbol') {
+    return 'NaN';
+  }
+  if (typeof val === 'bigint') {
+    return `${ val }n`;
+  }
+  return String(Number(val));
+}
+
+/**
+ * Attempt to produce an integer representation.
+ * BigInts have an `n` suffix.
+ * @param val
+ * @returns The integer representation or 'NaN' if not numeric.
+ */
+function toInt(val: any): string {
+  if (typeof val === 'symbol') {
+    return 'NaN';
+  }
+  if (typeof val === 'bigint') {
+    return `${ val }n`;
+  }
+  return String(parseInt(val, 10));
+}
+
+/**
+ * Attempt to produce a float representation.
+ * BigInts have an `n` suffix.
+ * @param val
+ * @returns The integer representation or 'NaN' if not numeric.
+ */
+function toFloat(val: any): string {
+  if (typeof val === 'symbol') {
+    return 'NaN';
+  }
+  return String(parseFloat(val));
+}
+
+// Based on:
+// https://nodejs.org/api/util.html#utilformatformat-args
+// The result will not match browser exactly, but it should get the
+// right information through.
+const escapes: Record<string, (val: any) => string> = {
+  s: (val: any) => tryStringify(val),
+  d: (val: any) => toNumber(val),
+  i: (val: any) => toInt(val),
+  f: (val: any) => toFloat(val),
+  j: (val: any) => tryStringify(val),
+  o: (val: any) => tryStringify(val),
+  O: (val: any) => tryStringify(val),
+  c: () => '',
+};
+
+/**
+ * A basic formatted for use where `util.format` is not available.
+ * This will not be as performant, but it will produce formatted
+ * messages.
+ *
+ * @internal
+ *
+ * @param args
+ * @returns Formatted string.
+ */
+export default function format(...args: any[]): string {
+  const formatString = args.shift();
+  if (TypeValidators.String.is(formatString)) {
+    let out = '';
+    let i = 0;
+    while (i < formatString.length) {
+      const char = formatString.charAt(i);
+      if (char === '%') {
+        const nextIndex = i + 1;
+        if (nextIndex < formatString.length) {
+          const nextChar = formatString.charAt(i + 1);
+          if (nextChar in escapes && args.length) {
+            const value = args.shift();
+            // This rule is for math.
+            // eslint-disable-next-line no-unsafe-optional-chaining
+            out += escapes[nextChar]?.(value);
+          } else if (nextChar === '%') {
+            out += '%';
+          } else {
+            out += `%${ nextChar }`;
+          }
+          i += 2;
+        }
+      } else {
+        out += char;
+        i += 1;
+      }
+    }
+    // If there are any args left after we exhaust the format string
+    // then just stick those on the end.
+    if (args.length) {
+      if (out.length) {
+        out += ' ';
+      }
+      out += args.map(tryStringify).join(' ');
+    }
+    return out;
+  }
+  return args.map(tryStringify).join(' ');
+}

package/src/logging/index.ts

@@ -0,0 +1,6 @@
+export * from './BasicLogger';
+export * from './format';
+export * from './IBasicLoggerOptions';
+export * from './ILogger';
+export * from './LogLevel';
+export * from './SafeLogger';

package/src/options/ClientContext.ts

@@ -0,0 +1,40 @@
+import { ILogger } from "../logging/ILogger";
+import { IPlatform } from "../platform/IPlatform";
+import { IClientContext } from "./IClientContext";
+import { IUser } from "./IUser";
+
+/**
+ * The client context provides basic configuration and platform support which are required
+ * when building SDK components.
+ */
+export default class ClientContext implements IClientContext {
+  flushInterval: number;
+  maxEventsInQueue: number;
+  offline: boolean;
+  logger: ILogger;
+  eventsUri: string;
+  pollingUri: string;
+  streamingUri: string;
+
+  constructor(
+    public readonly sdkKey: string,
+    configuration: {
+      logger?: ILogger;
+      offline?: boolean;
+      flushInterval: number;
+      maxEventsInQueue: number;
+      streamingUri: string;
+      pollingUri: string;
+      eventsUri: string;
+    },
+    public readonly platform: IPlatform,
+  ) {
+    this.logger = configuration.logger!;
+    this.offline = configuration.offline!;
+    this.flushInterval = configuration.flushInterval;
+    this.maxEventsInQueue = configuration.maxEventsInQueue;
+    this.streamingUri = configuration.streamingUri;
+    this.pollingUri = configuration.pollingUri;
+    this.eventsUri = configuration.eventsUri;
+  }
+}

package/src/options/IClientContext.ts

@@ -0,0 +1,54 @@
+import { ILogger } from "../logging/ILogger";
+import { IPlatform } from "../platform/IPlatform";
+
+/**
+ * Factory methods receive this class as a parameter.
+ *
+ * Its public properties provide information about the SDK configuration and environment. The SDK
+ * may also include non-public properties that are relevant only when creating one of the built-in
+ * component types and are not accessible to custom components.
+ */
+export interface IClientContext {
+
+  logger?: ILogger;
+
+  /**
+   * True if the SDK was configured to be completely offline.
+   */
+  offline?: boolean;
+
+  /**
+   * The configured SDK key.
+   */
+  sdkKey: string;
+
+  /**
+   * The base URI of the data-sync service
+   */
+  streamingUri: string;
+
+  /**
+   * The base URI of the polling service
+   */
+  pollingUri: string;
+
+  /**
+   * The base URI of the event service
+   */
+  eventsUri: string;
+
+  /**
+   * The interval in between flushes of events queue, in milliseconds.
+   */
+  flushInterval: number;
+
+  /**
+   * The max number of events in the events queue.
+   */
+  maxEventsInQueue: number;
+
+  /**
+   * Interfaces providing platform specific information and functionality.
+   */
+  platform: IPlatform;
+}

package/src/options/IOptions.ts

@@ -0,0 +1,124 @@
+import { ILogger } from "../logging/ILogger";
+import { IDataSynchronizer } from "../data-sync/IDataSynchronizer";
+import { IClientContext } from "./IClientContext";
+import { IDataSourceUpdates } from "../store/IDataSourceUpdates";
+import { VoidFunction } from "../utils/VoidFunction";
+import { IStore } from "../platform/IStore";
+import { DataSyncModeEnum } from "../data-sync/DataSyncMode";
+import { IUser } from "./IUser";
+import { IFlagBase } from "../evaluation";
+
+export interface IOptions {
+  /**
+   * The user for whom you are evaluating feature flags.
+   */
+  user?: IUser;
+
+  /**
+   * How long the client constructor will block awaiting a successful connection to FeatBit, in milliseconds.
+   *
+   * Defaults to 5000 milliseconds.
+   */
+  startWaitTime?: number;
+
+  /**
+   * The SDK key for your FeatBit environment.
+   */
+  sdkKey?: string;
+
+  /**
+   * The mode to sync flag end segment data with the FeatBit server. See {@link DataSyncModeEnum} for possible values.
+   *
+   * Defaults to {@link DataSyncModeEnum.STREAMING}.
+   */
+  dataSyncMode?: DataSyncModeEnum;
+
+  /**
+   * The base URI of the data-sync service, mandatory if the {@link dataSyncMode} is set to {@link DataSyncModeEnum.STREAMING}.
+   */
+  streamingUri?: string;
+
+  /**
+   * The base URI of the polling service, mandatory if the {@link dataSyncMode} option is set to {@link DataSyncModeEnum.POLLING}.
+   */
+  pollingUri?: string;
+
+  /**
+   * The base URI of the event service
+   */
+  eventsUri?: string;
+
+  /**
+   * Whether this client is offline. If true, no calls to FeatBit will be made.
+   *
+   * Defaults to false
+   */
+  offline?: boolean;
+
+  /**
+   * The time between polling requests, in milliseconds. Ignored in data-sync mode.
+   *
+   * Defaults to 30 000 milliseconds.
+   */
+  pollingInterval?: number;
+
+  /**
+   * The interval in between flushes of events queue, in milliseconds.
+   *
+   * The default value is 2 000 milliseconds.
+   */
+  flushInterval?: number;
+
+  /**
+   * The max number of events in the events queue.
+   * defaults to 10 000
+   */
+  maxEventsInQueue?: number;
+
+  /**
+   * Configures a logger for warnings and errors generated by the SDK.
+   *
+   * The logger can be any object that conforms to the {@link ILogger} interface.
+   * For a simple implementation that lets you filter by log level, see
+   * {@link BasicLogger}. You can also use an instance of `winston.Logger` from
+   * the Winston logging package.
+   *
+   * If you do not set this property, the SDK uses {@link BasicLogger} with a
+   * minimum level of `info`.
+   */
+  logger?: ILogger;
+
+  /**
+   * The interval in between sending WebSocket ping messages to evaluation server, in milliseconds.
+
+   * Defaults to 18 000 milliseconds.
+   */
+  webSocketPingInterval?: number;
+
+  /**
+   * The flags to bootstrap the client, which should be the string representation of type {@link IFlagBase[]}.
+   */
+  bootstrap?: IFlagBase[];
+
+  /**
+   * The store to use for caching feature flag data.
+   *
+   * Defaults to {@link InMemoryStore}.
+   */
+  store?: IStore | ((options: IOptions) => IStore);
+
+  /**
+   * A component that obtains feature flag data and puts it in the store.
+   *
+   * Defaults to {@link WebSocketDataSynchronizer}.
+   */
+  dataSynchronizer?:
+    | object
+    | ((
+    clientContext: IClientContext,
+    store: IStore,
+    dataSourceUpdates: IDataSourceUpdates,
+    initSuccessHandler: VoidFunction,
+    errorHandler?: (e: Error) => void,
+  ) => IDataSynchronizer);
+}

package/src/options/IUser.ts

@@ -0,0 +1,7 @@
+import { IContextProperty } from "../IContextProperty";
+
+export interface IUser {
+  keyId: string;
+  name?: string;
+  customizedProperties?: IContextProperty[];
+}