@featurevisor/sdk 0.8.0 → 0.10.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,8 @@ 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
+  interceptAttributes?: (attributes: Attributes) => Attributes; // @TODO: move it to FeaturevisorInstance in next breaking semver
 }
 
 type FieldType = VariationType | VariableType;
@@ -68,6 +70,8 @@ export class FeaturevisorSDK {
   private onActivation?: ActivationCallback;
   private datafileReader: DatafileReader;
   private configureBucketValue?: ConfigureBucketValue;
+  private logger: Logger;
+  private interceptAttributes?: (attributes: Attributes) => Attributes;
 
   constructor(options: SdkOptions) {
     if (options.onActivation) {
@@ -78,6 +82,12 @@ export class FeaturevisorSDK {
       this.configureBucketValue = options.configureBucketValue;
     }
 
+    this.logger = options.logger || createLogger();
+
+    if (options.interceptAttributes) {
+      this.interceptAttributes = options.interceptAttributes;
+    }
+
     this.setDatafile(options.datafile);
   }
 
@@ -87,8 +97,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 +144,49 @@ 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);
+      const finalAttributes = this.interceptAttributes
+        ? this.interceptAttributes(attributes)
+        : attributes;
+
+      const forcedVariation = getForcedVariation(feature, finalAttributes, this.datafileReader);
 
       if (forcedVariation) {
+        this.logger.debug("forced variation found", {
+          featureKey,
+          variation: forcedVariation.value,
+        });
+
         return forcedVariation.value;
       }
 
-      const bucketValue = this.getBucketValue(feature, attributes);
+      const bucketValue = this.getBucketValue(feature, finalAttributes);
 
-      const variation = getBucketedVariation(feature, attributes, bucketValue, this.datafileReader);
+      const variation = getBucketedVariation(
+        feature,
+        finalAttributes,
+        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,11 +235,15 @@ export class FeaturevisorSDK {
     try {
       const variationValue = this.getVariation(featureKey, attributes);
 
-      if (!variationValue) {
+      if (typeof variationValue === "undefined") {
         return undefined;
       }
 
       if (this.onActivation) {
+        const finalAttributes = this.interceptAttributes
+          ? this.interceptAttributes(attributes)
+          : attributes;
+
         const captureAttributes: Attributes = {};
 
         const attributesForCapturing = this.datafileReader
@@ -215,17 +251,17 @@ export class FeaturevisorSDK {
           .filter((a) => a.capture === true);
 
         attributesForCapturing.forEach((a) => {
-          if (typeof attributes[a.key] !== "undefined") {
+          if (typeof finalAttributes[a.key] !== "undefined") {
             captureAttributes[a.key] = attributes[a.key];
           }
         });
 
-        this.onActivation(featureKey, variationValue, attributes, captureAttributes);
+        this.onActivation(featureKey, variationValue, finalAttributes, captureAttributes);
       }
 
       return variationValue;
     } catch (e) {
-      console.error("[Featurevisor]", e);
+      this.logger.error("activate", { featureKey, error: e });
 
       return undefined;
     }
@@ -268,6 +304,8 @@ export class FeaturevisorSDK {
       const feature = this.getFeature(featureKey);
 
       if (!feature) {
+        this.logger.warn("feature not found in datafile", { featureKey, variableKey });
+
         return undefined;
       }
 
@@ -276,31 +314,40 @@ export class FeaturevisorSDK {
         : undefined;
 
       if (!variableSchema) {
+        this.logger.warn("variable schema not found", { featureKey, variableKey });
+
         return undefined;
       }
 
+      const finalAttributes = this.interceptAttributes
+        ? this.interceptAttributes(attributes)
+        : attributes;
+
       const forcedVariableValue = getForcedVariableValue(
         feature,
         variableSchema,
-        attributes,
+        finalAttributes,
         this.datafileReader,
       );
 
       if (typeof forcedVariableValue !== "undefined") {
+        this.logger.debug("forced variable value found", { featureKey, variableKey });
+
         return forcedVariableValue;
       }
 
-      const bucketValue = this.getBucketValue(feature, attributes);
+      const bucketValue = this.getBucketValue(feature, finalAttributes);
 
       return getBucketedVariableValue(
         feature,
         variableSchema,
-        attributes,
+        finalAttributes,
         bucketValue,
         this.datafileReader,
+        this.logger,
       );
     } catch (e) {
-      console.error("[Featurevisor]", e);
+      this.logger.error("getVariable", { featureKey, variableKey, error: e });
 
       return undefined;
     }

package/src/createInstance.spec.ts

@@ -0,0 +1,70 @@
+import { createInstance } from "./createInstance";
+
+describe("sdk: createInstance", function () {
+  it("should be a function", function () {
+    expect(typeof createInstance).toEqual("function");
+  });
+
+  it("should create instance with datafile content", function () {
+    const sdk = createInstance({
+      datafile: {
+        schemaVersion: "1",
+        revision: "1.0",
+        features: [],
+        attributes: [],
+        segments: [],
+      },
+    });
+
+    expect(typeof sdk.getVariation).toEqual("function");
+  });
+
+  it("should intercept attributes", function () {
+    let intercepted = false;
+
+    const sdk = createInstance({
+      datafile: {
+        schemaVersion: "1",
+        revision: "1.0",
+        features: [
+          {
+            key: "test",
+            defaultVariation: false,
+            bucketBy: "userId",
+            variations: [
+              { type: "boolean", value: true },
+              { type: "boolean", value: false },
+            ],
+            traffic: [
+              {
+                key: "1",
+                segments: "*",
+                percentage: 100000,
+                allocation: [
+                  { variation: true, percentage: 100000 },
+                  { variation: false, percentage: 0 },
+                ],
+              },
+            ],
+          },
+        ],
+        attributes: [],
+        segments: [],
+      },
+      interceptAttributes: function (attributes) {
+        intercepted = true;
+
+        return {
+          ...attributes,
+        };
+      },
+    });
+
+    const variation = sdk.getVariation("test", {
+      userId: "123",
+    });
+
+    expect(variation).toEqual(true);
+    expect(intercepted).toEqual(true);
+  });
+});

package/src/createInstance.ts

@@ -1,5 +1,6 @@
-import { DatafileContent } from "@featurevisor/types";
+import { DatafileContent, Attributes } from "@featurevisor/types";
 import { FeaturevisorSDK, ConfigureBucketValue, ActivationCallback } from "./client";
+import { createLogger, Logger } from "./logger";
 
 export type ReadyCallback = () => void;
 
@@ -13,6 +14,8 @@ export interface InstanceOptions {
   datafileUrl?: string;
   onReady?: ReadyCallback;
   handleDatafileFetch?: (datafileUrl: string) => Promise<DatafileContent>;
+  logger?: Logger;
+  interceptAttributes?: (attributes: Attributes) => Attributes;
 }
 
 // @TODO: consider renaming it to FeaturevisorSDK in next breaking semver
@@ -106,16 +109,20 @@ 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,
+      interceptAttributes: options.interceptAttributes,
     });
 
     if (typeof options.onReady === "function") {
@@ -134,6 +141,8 @@ export function createInstance(options: InstanceOptions) {
     datafile: emptyDatafile,
     onActivation: options.onActivation,
     configureBucketValue: options.configureBucketValue,
+    logger,
+    interceptAttributes: options.interceptAttributes,
   });
 
   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 });
+}