@featurevisor/sdk 1.35.2 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featurevisor/sdk",
-  "version": "1.35.2",
+  "version": "2.0.0",
   "description": "Featurevisor SDK for Node.js and the browser",
   "main": "dist/index.cjs.js",
   "module": "dist/index.mjs",
@@ -49,9 +49,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@featurevisor/types": "1.35.0",
-    "compare-versions": "^6.0.0-rc.1",
-    "murmurhash": "^2.0.1"
+    "@featurevisor/types": "2.0.0"
   },
-  "gitHead": "95d85e35b937d59f533e9e6f398315453a188bd4"
+  "gitHead": "9817e05a07735294c750ee921991509b67015afd"
 }

package/src/bucketer.spec.ts

@@ -0,0 +1,165 @@
+import { getBucketedNumber, MAX_BUCKETED_NUMBER, getBucketKey } from "./bucketer";
+import { createLogger } from "./logger";
+
+describe("sdk: Bucket", function () {
+  describe("getBucketedNumber", function () {
+    it("should be a function", function () {
+      expect(typeof getBucketedNumber).toEqual("function");
+    });
+
+    it("should return a number between 0 and 100000", function () {
+      const keys = ["foo", "bar", "baz", "123adshlk348-93asdlk"];
+
+      keys.forEach((key) => {
+        const n = getBucketedNumber(key);
+
+        expect(n >= 0).toEqual(true);
+        expect(n <= MAX_BUCKETED_NUMBER).toEqual(true);
+      });
+    });
+
+    // these assertions will be copied to unit tests of SDKs ported to other languages,
+    // so we can keep consistent bucketing across all SDKs
+    it("should return expected number for known keys", function () {
+      const expectedResults = {
+        foo: 20602,
+        bar: 89144,
+        "123.foo": 3151,
+        "123.bar": 9710,
+        "123.456.foo": 14432,
+        "123.456.bar": 1982,
+      };
+
+      Object.keys(expectedResults).forEach((key) => {
+        const n = getBucketedNumber(key);
+
+        expect(n).toEqual(expectedResults[key]);
+      });
+    });
+  });
+
+  describe("getBucketKey", function () {
+    const logger = createLogger({
+      level: "warn",
+    });
+
+    it("should be a function", function () {
+      expect(typeof getBucketKey).toEqual("function");
+    });
+
+    it("plain: should return a bucket key for a plain bucketBy", function () {
+      const featureKey = "test-feature";
+      const bucketBy = "userId";
+      const context = { userId: "123", browser: "chrome" };
+
+      const bucketKey = getBucketKey({
+        featureKey,
+        bucketBy,
+        context,
+        logger,
+      });
+
+      expect(bucketKey).toEqual("123.test-feature");
+    });
+
+    it("plain: should return a bucket key with feature key only if value is missing in context", function () {
+      const featureKey = "test-feature";
+      const bucketBy = "userId";
+      const context = { browser: "chrome" };
+
+      const bucketKey = getBucketKey({
+        featureKey,
+        bucketBy,
+        context,
+        logger,
+      });
+
+      expect(bucketKey).toEqual("test-feature");
+    });
+
+    it("and: should combine multiple field values together if present", function () {
+      const featureKey = "test-feature";
+      const bucketBy = ["organizationId", "userId"];
+      const context = { organizationId: "123", userId: "234", browser: "chrome" };
+
+      const bucketKey = getBucketKey({
+        featureKey,
+        bucketBy,
+        context,
+        logger,
+      });
+
+      expect(bucketKey).toEqual("123.234.test-feature");
+    });
+
+    it("and: should combine only available field values together if present", function () {
+      const featureKey = "test-feature";
+      const bucketBy = ["organizationId", "userId"];
+      const context = { organizationId: "123", browser: "chrome" };
+
+      const bucketKey = getBucketKey({
+        featureKey,
+        bucketBy,
+        context,
+        logger,
+      });
+
+      expect(bucketKey).toEqual("123.test-feature");
+    });
+
+    it("and: should combine all available fields, with dot separated paths", function () {
+      const featureKey = "test-feature";
+      const bucketBy = ["organizationId", "user.id"];
+      const context = {
+        organizationId: "123",
+        user: {
+          id: "234",
+        },
+        browser: "chrome",
+      };
+
+      const bucketKey = getBucketKey({
+        featureKey,
+        bucketBy,
+        context,
+        logger,
+      });
+
+      expect(bucketKey).toEqual("123.234.test-feature");
+    });
+
+    it("or: should take first available field value", function () {
+      const featureKey = "test-feature";
+      const bucketBy = {
+        or: ["userId", "deviceId"],
+      };
+      const context = { deviceId: "deviceIdHere", userId: "234", browser: "chrome" };
+
+      const bucketKey = getBucketKey({
+        featureKey,
+        bucketBy,
+        context,
+        logger,
+      });
+
+      expect(bucketKey).toEqual("234.test-feature");
+    });
+
+    it("or: should take first available field value", function () {
+      const featureKey = "test-feature";
+      const bucketBy = {
+        or: ["userId", "deviceId"],
+      };
+      const context = { deviceId: "deviceIdHere", browser: "chrome" };
+
+      const bucketKey = getBucketKey({
+        featureKey,
+        bucketBy,
+        context,
+        logger,
+      });
+
+      expect(bucketKey).toEqual("deviceIdHere.test-feature");
+    });
+  });
+});

package/src/bucketer.ts

@@ -0,0 +1,84 @@
+import type { BucketKey, Context, AttributeValue, FeatureKey, BucketBy } from "@featurevisor/types";
+
+import { Logger } from "./logger";
+import { getValueFromContext } from "./conditions";
+import { MurmurHashV3 } from "./murmurhash";
+
+/**
+ * Generic hashing
+ */
+const HASH_SEED = 1;
+const MAX_HASH_VALUE = Math.pow(2, 32);
+
+export const MAX_BUCKETED_NUMBER = 100000; // 100% * 1000 to include three decimal places in the same integer value
+
+export function getBucketedNumber(bucketKey: string): number {
+  const hashValue = MurmurHashV3(bucketKey, HASH_SEED);
+  const ratio = hashValue / MAX_HASH_VALUE;
+
+  return Math.floor(ratio * MAX_BUCKETED_NUMBER);
+}
+
+/**
+ * Bucket key
+ */
+const DEFAULT_BUCKET_KEY_SEPARATOR = ".";
+
+export interface GetBucketKeyOptions {
+  featureKey: FeatureKey;
+  bucketBy: BucketBy;
+  context: Context;
+
+  logger: Logger;
+}
+
+export function getBucketKey(options: GetBucketKeyOptions): BucketKey {
+  const {
+    featureKey,
+    bucketBy,
+    context,
+
+    logger,
+  } = options;
+
+  let type;
+  let attributeKeys;
+
+  if (typeof bucketBy === "string") {
+    type = "plain";
+    attributeKeys = [bucketBy];
+  } else if (Array.isArray(bucketBy)) {
+    type = "and";
+    attributeKeys = bucketBy;
+  } else if (typeof bucketBy === "object" && Array.isArray(bucketBy.or)) {
+    type = "or";
+    attributeKeys = bucketBy.or;
+  } else {
+    logger.error("invalid bucketBy", { featureKey, bucketBy });
+
+    throw new Error("invalid bucketBy");
+  }
+
+  const bucketKey: AttributeValue[] = [];
+
+  attributeKeys.forEach((attributeKey) => {
+    const attributeValue = getValueFromContext(context, attributeKey);
+
+    if (typeof attributeValue === "undefined") {
+      return;
+    }
+
+    if (type === "plain" || type === "and") {
+      bucketKey.push(attributeValue);
+    } else {
+      // or
+      if (bucketKey.length === 0) {
+        bucketKey.push(attributeValue);
+      }
+    }
+  });
+
+  bucketKey.push(featureKey);
+
+  return bucketKey.join(DEFAULT_BUCKET_KEY_SEPARATOR);
+}

package/src/child.spec.ts

@@ -0,0 +1,267 @@
+import { createInstance } from "./instance";
+
+describe("sdk: child", function () {
+  it("should create a child instance", function () {
+    const f = createInstance({
+      datafile: {
+        schemaVersion: "2",
+        revision: "1.0",
+        features: {
+          test: {
+            key: "test",
+            bucketBy: "userId",
+            variablesSchema: {
+              color: {
+                key: "color",
+                type: "string",
+                defaultValue: "red",
+              },
+              showSidebar: {
+                key: "showSidebar",
+                type: "boolean",
+                defaultValue: false,
+              },
+              sidebarTitle: {
+                key: "sidebarTitle",
+                type: "string",
+                defaultValue: "sidebar title",
+              },
+              count: {
+                key: "count",
+                type: "integer",
+                defaultValue: 0,
+              },
+              price: {
+                key: "price",
+                type: "double",
+                defaultValue: 9.99,
+              },
+              paymentMethods: {
+                key: "paymentMethods",
+                type: "array",
+                defaultValue: ["paypal", "creditcard"],
+              },
+              flatConfig: {
+                key: "flatConfig",
+                type: "object",
+                defaultValue: {
+                  key: "value",
+                },
+              },
+              nestedConfig: {
+                key: "nestedConfig",
+                type: "json",
+                defaultValue: JSON.stringify({
+                  key: {
+                    nested: "value",
+                  },
+                }),
+              },
+            },
+            variations: [
+              { value: "control" },
+              {
+                value: "treatment",
+                variables: {
+                  showSidebar: true,
+                  sidebarTitle: "sidebar title from variation",
+                },
+                variableOverrides: {
+                  showSidebar: [
+                    {
+                      segments: ["netherlands"],
+                      value: false,
+                    },
+                    {
+                      conditions: [
+                        {
+                          attribute: "country",
+                          operator: "equals",
+                          value: "de",
+                        },
+                      ],
+                      value: false,
+                    },
+                  ],
+                  sidebarTitle: [
+                    {
+                      segments: ["netherlands"],
+                      value: "Dutch title",
+                    },
+                    {
+                      conditions: [
+                        {
+                          attribute: "country",
+                          operator: "equals",
+                          value: "de",
+                        },
+                      ],
+                      value: "German title",
+                    },
+                  ],
+                },
+              },
+            ],
+            force: [
+              {
+                conditions: [{ attribute: "userId", operator: "equals", value: "user-ch" }],
+                enabled: true,
+                variation: "control",
+                variables: {
+                  color: "red and white",
+                },
+              },
+              {
+                conditions: [{ attribute: "userId", operator: "equals", value: "user-gb" }],
+                enabled: false,
+              },
+              {
+                conditions: [
+                  { attribute: "userId", operator: "equals", value: "user-forced-variation" },
+                ],
+                enabled: true,
+                variation: "treatment",
+              },
+            ],
+            traffic: [
+              // belgium
+              {
+                key: "2",
+                segments: ["belgium"],
+                percentage: 100000,
+                allocation: [
+                  { variation: "control", range: [0, 0] },
+                  {
+                    variation: "treatment",
+                    range: [0, 100000],
+                  },
+                ],
+                variation: "control",
+                variables: {
+                  color: "black",
+                },
+              },
+
+              // everyone
+              {
+                key: "1",
+                segments: "*",
+                percentage: 100000,
+                allocation: [
+                  { variation: "control", range: [0, 0] },
+                  {
+                    variation: "treatment",
+                    range: [0, 100000],
+                  },
+                ],
+              },
+            ],
+          },
+          anotherTest: {
+            key: "test",
+            bucketBy: "userId",
+            traffic: [
+              // everyone
+              {
+                key: "1",
+                segments: "*",
+                percentage: 100000,
+              },
+            ],
+          },
+        },
+        segments: {
+          netherlands: {
+            key: "netherlands",
+            conditions: JSON.stringify([
+              {
+                attribute: "country",
+                operator: "equals",
+                value: "nl",
+              },
+            ]),
+          },
+          belgium: {
+            key: "belgium",
+            conditions: JSON.stringify([
+              {
+                attribute: "country",
+                operator: "equals",
+                value: "be",
+              },
+            ]),
+          },
+        },
+      },
+      context: {
+        appVersion: "1.0.0",
+      },
+    });
+
+    expect(f).toBeDefined();
+    expect(f.getContext()).toEqual({ appVersion: "1.0.0" });
+
+    const childF = f.spawn({
+      userId: "123",
+      country: "nl",
+    });
+
+    expect(childF).toBeDefined();
+    expect(childF.getContext()).toEqual({ appVersion: "1.0.0", userId: "123", country: "nl" });
+
+    let contextUpdated = false;
+    const unsubscribeContext = childF.on("context_set", () => {
+      contextUpdated = true;
+    });
+
+    childF.setContext({ country: "be" });
+    expect(childF.getContext()).toEqual({ appVersion: "1.0.0", userId: "123", country: "be" });
+
+    expect(childF.isEnabled("test")).toBe(true);
+    expect(childF.getVariation("test")).toEqual("control");
+
+    expect(childF.getVariable("test", "color")).toEqual("black");
+    expect(childF.getVariableString("test", "color")).toEqual("black");
+
+    expect(childF.getVariable("test", "showSidebar")).toEqual(false);
+    expect(childF.getVariableBoolean("test", "showSidebar")).toEqual(false);
+
+    expect(childF.getVariable("test", "sidebarTitle")).toEqual("sidebar title");
+    expect(childF.getVariableString("test", "sidebarTitle")).toEqual("sidebar title");
+
+    expect(childF.getVariable("test", "count")).toEqual(0);
+    expect(childF.getVariableInteger("test", "count")).toEqual(0);
+
+    expect(childF.getVariable("test", "price")).toEqual(9.99);
+    expect(childF.getVariableDouble("test", "price")).toEqual(9.99);
+
+    expect(childF.getVariable("test", "paymentMethods")).toEqual(["paypal", "creditcard"]);
+    expect(childF.getVariableArray("test", "paymentMethods")).toEqual(["paypal", "creditcard"]);
+
+    expect(childF.getVariable("test", "flatConfig")).toEqual({ key: "value" });
+    expect(childF.getVariableObject("test", "flatConfig")).toEqual({ key: "value" });
+
+    expect(childF.getVariable("test", "nestedConfig")).toEqual({
+      key: { nested: "value" },
+    });
+    expect(childF.getVariableJSON("test", "nestedConfig")).toEqual({
+      key: { nested: "value" },
+    });
+
+    expect(contextUpdated).toBe(true);
+    unsubscribeContext();
+
+    expect(childF.isEnabled("newFeature")).toEqual(false);
+    childF.setSticky({
+      newFeature: {
+        enabled: true,
+      },
+    });
+    expect(childF.isEnabled("newFeature")).toEqual(true);
+
+    const allEvaluations = childF.getAllEvaluations();
+    expect(Object.keys(allEvaluations)).toEqual(["test", "anotherTest"]);
+
+    childF.close();
+  });
+});