@featurevisor/sdk 0.8.0 → 0.9.0

package/src/client.ts

@@ -18,7 +18,7 @@ import {
   getForcedVariableValue,
 } from "./feature";
 import { getBucketedNumber } from "./bucket";
-import { VariableSchema } from "@featurevisor/types/src";
+import { createLogger, Logger } from "./logger";
 
 export type ActivationCallback = (
   featureName: string,
@@ -33,6 +33,7 @@ export interface SdkOptions {
   datafile: DatafileContent | string;
   onActivation?: ActivationCallback; // @TODO: move it to FeaturevisorInstance in next breaking semver
   configureBucketValue?: ConfigureBucketValue;
+  logger?: Logger; // TODO: keep it in FeaturevisorInstance only in next breaking semver
 }
 
 type FieldType = VariationType | VariableType;
@@ -68,6 +69,7 @@ export class FeaturevisorSDK {
   private onActivation?: ActivationCallback;
   private datafileReader: DatafileReader;
   private configureBucketValue?: ConfigureBucketValue;
+  private logger: Logger;
 
   constructor(options: SdkOptions) {
     if (options.onActivation) {
@@ -78,6 +80,8 @@ export class FeaturevisorSDK {
       this.configureBucketValue = options.configureBucketValue;
     }
 
+    this.logger = options.logger || createLogger();
+
     this.setDatafile(options.datafile);
   }
 
@@ -87,8 +91,7 @@ export class FeaturevisorSDK {
         typeof datafile === "string" ? JSON.parse(datafile) : datafile,
       );
     } catch (e) {
-      console.error(`Featurevisor could not parse the datafile`);
-      console.error(e);
+      this.logger.error("could not parse datafile", { error: e });
     }
   }
 
@@ -135,26 +138,45 @@ export class FeaturevisorSDK {
       const feature = this.getFeature(featureKey);
 
       if (!feature) {
+        this.logger.warn("feature not found in datafile", { featureKey });
+
         return undefined;
       }
 
       const forcedVariation = getForcedVariation(feature, attributes, this.datafileReader);
 
       if (forcedVariation) {
+        this.logger.debug("forced variation found", {
+          featureKey,
+          variation: forcedVariation.value,
+        });
+
         return forcedVariation.value;
       }
 
       const bucketValue = this.getBucketValue(feature, attributes);
 
-      const variation = getBucketedVariation(feature, attributes, bucketValue, this.datafileReader);
+      const variation = getBucketedVariation(
+        feature,
+        attributes,
+        bucketValue,
+        this.datafileReader,
+        this.logger,
+      );
 
       if (!variation) {
+        this.logger.debug("using default variation", {
+          featureKey,
+          bucketValue,
+          variation: feature.defaultVariation,
+        });
+
         return feature.defaultVariation;
       }
 
       return variation.value;
     } catch (e) {
-      console.error("[Featurevisor]", e);
+      this.logger.error("getVariation", { featureKey, error: e });
 
       return undefined;
     }
@@ -203,7 +225,7 @@ export class FeaturevisorSDK {
     try {
       const variationValue = this.getVariation(featureKey, attributes);
 
-      if (!variationValue) {
+      if (typeof variationValue === "undefined") {
         return undefined;
       }
 
@@ -225,7 +247,7 @@ export class FeaturevisorSDK {
 
       return variationValue;
     } catch (e) {
-      console.error("[Featurevisor]", e);
+      this.logger.error("activate", { featureKey, error: e });
 
       return undefined;
     }
@@ -268,6 +290,8 @@ export class FeaturevisorSDK {
       const feature = this.getFeature(featureKey);
 
       if (!feature) {
+        this.logger.warn("feature not found in datafile", { featureKey, variableKey });
+
         return undefined;
       }
 
@@ -276,6 +300,8 @@ export class FeaturevisorSDK {
         : undefined;
 
       if (!variableSchema) {
+        this.logger.warn("variable schema not found", { featureKey, variableKey });
+
         return undefined;
       }
 
@@ -287,6 +313,8 @@ export class FeaturevisorSDK {
       );
 
       if (typeof forcedVariableValue !== "undefined") {
+        this.logger.debug("forced variable value found", { featureKey, variableKey });
+
         return forcedVariableValue;
       }
 
@@ -298,9 +326,10 @@ export class FeaturevisorSDK {
         attributes,
         bucketValue,
         this.datafileReader,
+        this.logger,
       );
     } catch (e) {
-      console.error("[Featurevisor]", e);
+      this.logger.error("getVariable", { featureKey, variableKey, error: e });
 
       return undefined;
     }

package/src/createInstance.ts

@@ -1,5 +1,6 @@
 import { DatafileContent } from "@featurevisor/types";
 import { FeaturevisorSDK, ConfigureBucketValue, ActivationCallback } from "./client";
+import { createLogger, Logger } from "./logger";
 
 export type ReadyCallback = () => void;
 
@@ -13,6 +14,7 @@ export interface InstanceOptions {
   datafileUrl?: string;
   onReady?: ReadyCallback;
   handleDatafileFetch?: (datafileUrl: string) => Promise<DatafileContent>;
+  logger?: Logger;
 }
 
 // @TODO: consider renaming it to FeaturevisorSDK in next breaking semver
@@ -106,16 +108,19 @@ function fetchDatafileContent(datafileUrl, options: InstanceOptions): Promise<Da
 export function createInstance(options: InstanceOptions) {
   if (!options.datafile && !options.datafileUrl) {
     throw new Error(
-      "Featurevisor SDK instance cannot be created without `datafile` or `datafileUrl` option",
+      "Featurevisor SDK instance cannot be created without both `datafile` and `datafileUrl` options",
     );
   }
 
+  const logger = options.logger || createLogger();
+
   // datafile content is already provided
   if (options.datafile) {
     const sdk = new FeaturevisorSDK({
       datafile: options.datafile,
       onActivation: options.onActivation,
       configureBucketValue: options.configureBucketValue,
+      logger,
     });
 
     if (typeof options.onReady === "function") {
@@ -134,6 +139,7 @@ export function createInstance(options: InstanceOptions) {
     datafile: emptyDatafile,
     onActivation: options.onActivation,
     configureBucketValue: options.configureBucketValue,
+    logger,
   });
 
   if (options.datafileUrl) {

package/src/feature.ts

@@ -11,12 +11,14 @@ import { DatafileReader } from "./datafileReader";
 import { allGroupSegmentsAreMatched } from "./segments";
 import { allConditionsAreMatched } from "./conditions";
 import { VariableSchema } from "@featurevisor/types/src";
+import { Logger } from "./logger";
 
 export function getMatchedTraffic(
   traffic: Traffic[],
   attributes: Attributes,
   bucketValue: number,
   datafileReader: DatafileReader,
+  logger: Logger,
 ): Traffic | undefined {
   return traffic.find((traffic) => {
     if (bucketValue > traffic.percentage) {
@@ -36,6 +38,10 @@ export function getMatchedTraffic(
       return false;
     }
 
+    logger.debug("matched rule", {
+      ruleKey: traffic.key,
+    });
+
     return true;
   });
 }
@@ -99,21 +105,33 @@ export function getBucketedVariation(
   attributes: Attributes,
   bucketValue: number,
   datafileReader: DatafileReader,
+  logger: Logger,
 ): Variation | undefined {
   const matchedTraffic = getMatchedTraffic(
     feature.traffic,
     attributes,
     bucketValue,
     datafileReader,
+    logger,
   );
 
   if (!matchedTraffic) {
+    logger.debug("no matched rule found", {
+      featureKey: feature.key,
+      bucketValue,
+    });
+
     return undefined;
   }
 
   const allocation = getMatchedAllocation(matchedTraffic, bucketValue);
 
   if (!allocation) {
+    logger.debug("no matched allocation found", {
+      featureKey: feature.key,
+      bucketValue,
+    });
+
     return undefined;
   }
 
@@ -124,9 +142,22 @@ export function getBucketedVariation(
   });
 
   if (!variation) {
+    // this should never happen
+    logger.debug("no matched variation found", {
+      featureKey: feature.key,
+      variation: variationValue,
+      bucketValue,
+    });
+
     return undefined;
   }
 
+  logger.debug("matched variation", {
+    featureKey: feature.key,
+    variation: variation.value,
+    bucketValue,
+  });
+
   return variation;
 }
 
@@ -157,6 +188,7 @@ export function getBucketedVariableValue(
   attributes: Attributes,
   bucketValue: number,
   datafileReader: DatafileReader,
+  logger: Logger,
 ): VariableValue | undefined {
   // get traffic
   const matchedTraffic = getMatchedTraffic(
@@ -164,9 +196,16 @@ export function getBucketedVariableValue(
     attributes,
     bucketValue,
     datafileReader,
+    logger,
   );
 
   if (!matchedTraffic) {
+    logger.debug("no matched rule found", {
+      featureKey: feature.key,
+      variableKey: variableSchema.key,
+      bucketValue,
+    });
+
     return undefined;
   }
 
@@ -174,12 +213,24 @@ export function getBucketedVariableValue(
 
   // see if variable is set at traffic/rule level
   if (matchedTraffic.variables && typeof matchedTraffic.variables[variableKey] !== "undefined") {
+    logger.debug("using variable from rule", {
+      featureKey: feature.key,
+      variableKey,
+      bucketValue,
+    });
+
     return matchedTraffic.variables[variableKey];
   }
 
   const allocation = getMatchedAllocation(matchedTraffic, bucketValue);
 
   if (!allocation) {
+    logger.debug("no matched allocation found", {
+      featureKey: feature.key,
+      variableKey,
+      bucketValue,
+    });
+
     return undefined;
   }
 
@@ -190,6 +241,14 @@ export function getBucketedVariableValue(
   });
 
   if (!variation) {
+    // this should never happen
+    logger.debug("no matched variation found", {
+      feature: feature.key,
+      variableKey,
+      variation: variationValue,
+      bucketValue,
+    });
+
     return undefined;
   }
 
@@ -198,6 +257,13 @@ export function getBucketedVariableValue(
   });
 
   if (!variableFromVariation) {
+    logger.debug("using default value as variation has no variable", {
+      featureKey: feature.key,
+      variableKey,
+      variation: variationValue,
+      bucketValue,
+    });
+
     if (variableSchema.type === "json") {
       return JSON.parse(variableSchema.defaultValue as string);
     }
@@ -228,6 +294,13 @@ export function getBucketedVariableValue(
     });
 
     if (override) {
+      logger.debug("using override value from variation", {
+        feature: feature.key,
+        variableKey,
+        variation: variationValue,
+        bucketValue,
+      });
+
       if (variableSchema.type === "json") {
         return JSON.parse(override.value as string);
       }
@@ -236,6 +309,13 @@ export function getBucketedVariableValue(
     }
   }
 
+  logger.debug("using value from variation", {
+    feature: feature.key,
+    variableKey,
+    variation: variationValue,
+    bucketValue,
+  });
+
   if (variableSchema.type === "json") {
     return JSON.parse(variableFromVariation.value as string);
   }

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from "./bucket";
 export * from "./client";
 export * from "./createInstance";
+export * from "./logger";

package/src/logger.ts

@@ -0,0 +1,86 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export type LogMessage = string;
+
+export interface LogDetails {
+  [key: string]: any;
+}
+
+export type LogHandler = (level: LogLevel, message: LogMessage, details?: LogDetails) => void;
+
+export interface CreateLoggerOptions {
+  levels?: LogLevel[];
+  handler?: LogHandler;
+}
+
+export const loggerPrefix = "[Featurevisor]";
+
+export const defaultLogLevels: LogLevel[] = [
+  // supported, but not enabled by default
+  // "debug",
+  // "info",
+
+  // enabled by default
+  "warn",
+  "error",
+];
+
+export const defaultLogHandler: LogHandler = function defaultLogHandler(
+  level,
+  message,
+  details = {},
+) {
+  switch (level) {
+    case "debug":
+      console.log(loggerPrefix, message, details);
+    case "info":
+      console.info(loggerPrefix, message, details);
+    case "warn":
+      console.warn(loggerPrefix, message, details);
+    case "error":
+      console.error(loggerPrefix, message, details);
+  }
+};
+
+export class Logger {
+  private levels: LogLevel[];
+  private handle: LogHandler;
+
+  constructor(options: CreateLoggerOptions) {
+    this.levels = options.levels as LogLevel[];
+    this.handle = options.handler as LogHandler;
+  }
+
+  setLevels(levels: LogLevel[]) {
+    this.levels = levels;
+  }
+
+  log(level: LogLevel, message: LogMessage, details?: LogDetails) {
+    if (this.levels.indexOf(level) !== -1) {
+      this.handle(level, message, details);
+    }
+  }
+
+  debug(message: LogMessage, details?: LogDetails) {
+    this.log("debug", message, details);
+  }
+
+  info(message: LogMessage, details?: LogDetails) {
+    this.log("info", message, details);
+  }
+
+  warn(message: LogMessage, details?: LogDetails) {
+    this.log("warn", message, details);
+  }
+
+  error(message: LogMessage, details?: LogDetails) {
+    this.log("error", message, details);
+  }
+}
+
+export function createLogger(options: CreateLoggerOptions = {}): Logger {
+  const levels = options.levels || defaultLogLevels;
+  const logHandler = options.handler || defaultLogHandler;
+
+  return new Logger({ levels, handler: logHandler });
+}