@uniformdev/context 20.8.1 → 20.8.2-alpha.21

package/dist/index.js

@@ -53,7 +53,9 @@ __export(src_exports, {
   PAIR_SEP: () => PAIR_SEP,
   QUIRK_SEP: () => QUIRK_SEP,
   SERVER_STATE_ID: () => SERVER_STATE_ID,
+  STRONGEST_SCORE_PERSONALIZATION_ALGORITHM: () => STRONGEST_SCORE_PERSONALIZATION_ALGORITHM,
   ScriptType: () => ScriptType,
+  TOP_DOWN_CRITERIA_PERSONALIZATION_ALGORITHM: () => TOP_DOWN_CRITERIA_PERSONALIZATION_ALGORITHM,
   TYPE_SEP: () => TYPE_SEP,
   TransitionDataStore: () => TransitionDataStore,
   UNIFORM_DEFAULT_COOKIE_NAME: () => UNIFORM_DEFAULT_COOKIE_NAME,
@@ -95,7 +97,9 @@ __export(src_exports, {
   serializePersonalizeVariants: () => serializePersonalizeVariants,
   serializeQuickConnect: () => serializeQuickConnect,
   serializeQuirks: () => serializeQuirks,
-  testVariations: () => testVariations
+  strongestScorePersonalizationSelectionAlgorithm: () => strongestScorePersonalizationSelectionAlgorithm,
+  testVariations: () => testVariations,
+  topDownCriteriaPersonalizationSelectionAlgorithm: () => topDownCriteriaPersonalizationSelectionAlgorithm
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -605,7 +609,7 @@ var GroupCriteriaEvaluator = class {
 _evaluators = new WeakMap();
 
 // src/placement/criteria/evaluateVariantMatch.ts
-function evaluateVariantMatch(variantId, match, vec, onLogMessage) {
+function evaluateVariantMatch(variantId, match, vec, onLogMessage, quirks) {
   onLogMessage == null ? void 0 : onLogMessage(["info", 301, "GROUP", { id: variantId, op: match == null ? void 0 : match.op }]);
   let result;
   try {
@@ -613,9 +617,9 @@ function evaluateVariantMatch(variantId, match, vec, onLogMessage) {
       onLogMessage == null ? void 0 : onLogMessage(["info", 302, { matched: true, description: "default variation" }]);
       result = true;
     } else if (!match.op || match.op === "&") {
-      result = match.crit.every((c) => evaluateDimensionMatch(c, vec, onLogMessage));
+      result = match.crit.every((c) => evaluateMatch(c, vec, quirks != null ? quirks : {}, onLogMessage));
     } else {
-      result = match.crit.some((c) => evaluateDimensionMatch(c, vec, onLogMessage));
+      result = match.crit.some((c) => evaluateMatch(c, vec, quirks != null ? quirks : {}, onLogMessage));
     }
     onLogMessage == null ? void 0 : onLogMessage(["info", 303, result]);
   } finally {
@@ -623,9 +627,16 @@ function evaluateVariantMatch(variantId, match, vec, onLogMessage) {
   }
   return result;
 }
+function evaluateMatch(crit, vec, quirks, onLogMessage) {
+  if ("t" in crit && crit.t === "q") {
+    return evaluateQuirkMatch(crit, quirks, onLogMessage);
+  } else {
+    return evaluateDimensionMatch(crit, vec, onLogMessage);
+  }
+}
 function evaluateDimensionMatch(crit, vec, onLogMessage) {
   var _a, _b;
-  const { op, l: lhs } = crit;
+  const { l: lhs, op } = crit;
   const lhsScore = (_a = vec[lhs]) != null ? _a : 0;
   if (op === "^") {
     const [cat] = lhs.split(ENR_SEPARATOR);
@@ -692,33 +703,65 @@ function evaluateDimensionMatch(crit, vec, onLogMessage) {
   }
   if (op === ">") {
     const result = lhsScore > rhsScore;
-    explain(onLogMessage, result, crit, lhsScore, rhsScore);
+    explainScore(onLogMessage, result, crit, lhsScore, rhsScore);
     return result;
   } else if (op === ">=") {
     const result = lhsScore >= rhsScore;
-    explain(onLogMessage, result, crit, lhsScore, rhsScore);
+    explainScore(onLogMessage, result, crit, lhsScore, rhsScore);
     return result;
   } else if (op === "<") {
     const result = lhsScore < rhsScore;
-    explain(onLogMessage, result, crit, lhsScore, rhsScore);
+    explainScore(onLogMessage, result, crit, lhsScore, rhsScore);
     return result;
   } else if (op === "<=") {
     const result = lhsScore <= rhsScore;
-    explain(onLogMessage, result, crit, lhsScore, rhsScore);
+    explainScore(onLogMessage, result, crit, lhsScore, rhsScore);
     return result;
   } else if (op === "=") {
     const result = lhsScore === rhsScore;
-    explain(onLogMessage, result, crit, lhsScore, rhsScore);
+    explainScore(onLogMessage, result, crit, lhsScore, rhsScore);
     return result;
   } else if (op === "!=") {
     const result = lhsScore !== rhsScore;
-    explain(onLogMessage, result, crit, lhsScore, rhsScore);
+    explainScore(onLogMessage, result, crit, lhsScore, rhsScore);
+    return result;
+  } else {
+    onLogMessage == null ? void 0 : onLogMessage([
+      "error",
+      302,
+      {
+        matched: false,
+        description: `${crit.l} ${crit.op} ${crit.rDim ? `${crit.rDim}` : crit.r}: Unknown op ${crit.op}.`
+      }
+    ]);
+    return false;
+  }
+}
+function evaluateQuirkMatch(crit, quirks, onLogMessage) {
+  var _a;
+  const { l: targetQuirk, op, r: targetValue } = crit;
+  const targetQuirkValue = (_a = quirks[targetQuirk]) != null ? _a : "";
+  if (op === "=") {
+    const result = targetQuirkValue === targetValue;
+    explainQuirk(onLogMessage, result, crit, targetQuirkValue);
+    return result;
+  } else if (op === "!=") {
+    const result = targetQuirkValue !== targetValue;
+    explainQuirk(onLogMessage, result, crit, targetQuirkValue);
     return result;
   } else {
-    throw new Error(`Unknown op: ${op}`);
+    onLogMessage == null ? void 0 : onLogMessage([
+      "error",
+      302,
+      {
+        matched: false,
+        description: `Quirk ${crit.l} ${crit.op} ${crit.r}: Unknown quirk op ${crit.op}.`
+      }
+    ]);
+    return false;
   }
 }
-function explain(onLogMessage, result, crit, lhsScore, rhsScore) {
+function explainScore(onLogMessage, result, crit, lhsScore, rhsScore) {
   onLogMessage == null ? void 0 : onLogMessage([
     "info",
     302,
@@ -728,9 +771,20 @@ function explain(onLogMessage, result, crit, lhsScore, rhsScore) {
     }
   ]);
 }
+function explainQuirk(onLogMessage, result, crit, lhs) {
+  onLogMessage == null ? void 0 : onLogMessage([
+    "info",
+    302,
+    {
+      matched: result,
+      description: `Quirk ${crit.l}[${lhs}] ${crit.op} ${crit.r}`
+    }
+  ]);
+}
 
-// src/placement/personalize.ts
-function personalizeVariations({
+// src/placement/topDownCriteriaPersonalizationSelectionAlgorithm.ts
+var TOP_DOWN_CRITERIA_PERSONALIZATION_ALGORITHM = "default";
+function topDownCriteriaPersonalizationSelectionAlgorithm({
   name,
   context,
   variations,
@@ -740,27 +794,35 @@ function personalizeVariations({
   var _a, _b, _c;
   onLogMessage == null ? void 0 : onLogMessage(["info", 300, "GROUP", { name, take }]);
   try {
-    const variantMatches = [];
-    const defaultVariants = [];
-    const needsConsent = context.requireConsentForPersonalization;
-    const canEvaluate = !needsConsent || context.storage.data.consent;
-    for (const variant of variations) {
-      if ((_a = variant.pz) == null ? void 0 : _a.crit.length) {
-        if (canEvaluate && variantMatches.length !== take && evaluateVariantMatch(variant.id, variant.pz, context.scores, onLogMessage)) {
-          variantMatches.push(variant);
+    const variationMatches = [];
+    const defaultVariations = [];
+    const needsConsentToPersonalize = context.requireConsentForPersonalization;
+    const personalizationAllowed = !needsConsentToPersonalize || context.storage.data.consent;
+    for (const variation of variations) {
+      const isInvalidFormat = variation.pz && (typeof variation.pz !== "object" || variation.pz === null || !("crit" in variation.pz && Array.isArray(variation.pz.crit)));
+      let validVariation;
+      if (isInvalidFormat) {
+        const { pz, ...validParts } = variation;
+        validVariation = validParts;
+      } else {
+        validVariation = variation;
+      }
+      if ((_a = validVariation.pz) == null ? void 0 : _a.crit.length) {
+        if (personalizationAllowed && variationMatches.length !== take && evaluateVariantMatch(variation.id, validVariation.pz, context.scores, onLogMessage, context.quirks)) {
+          variationMatches.push(validVariation);
         }
       } else {
-        defaultVariants.push(variant);
+        defaultVariations.push(validVariation);
       }
     }
     const result = [];
-    for (let i = 0; i < variantMatches.length; i++) {
+    for (let i = 0; i < variationMatches.length; i++) {
       let isControl = (_b = context.storage.data.controlGroup) != null ? _b : false;
-      const variant = variantMatches[i];
-      if (!isControl && typeof ((_c = variant.pz) == null ? void 0 : _c.control) === "number") {
+      const variation = variationMatches[i];
+      if (!isControl && typeof ((_c = variation.pz) == null ? void 0 : _c.control) === "number") {
         isControl = context.getPersonalizeVariantControl(name, i);
         if (typeof isControl === "undefined") {
-          isControl = rollForControlGroup(variant.pz.control);
+          isControl = rollForControlGroup(variation.pz.control);
           context.storage.updateData([
             {
               type: "setpersonalizecontrol",
@@ -773,13 +835,13 @@ function personalizeVariations({
           ]);
         }
       }
-      let variantToAdd = variant;
+      let variantToAdd = variation;
       if (isControl) {
-        const defaultReplacement = defaultVariants.shift();
+        const defaultReplacement = defaultVariations.shift();
         if (defaultReplacement) {
           variantToAdd = {
             ...defaultReplacement,
-            id: variant.id
+            id: variation.id
           };
         } else {
           variantToAdd = void 0;
@@ -789,8 +851,8 @@ function personalizeVariations({
         result.push({ ...variantToAdd, control: isControl });
       }
     }
-    while (result.length < take && defaultVariants.length) {
-      result.push({ ...defaultVariants.shift(), control: false });
+    while (result.length < take && defaultVariations.length) {
+      result.push({ ...defaultVariations.shift(), control: false });
     }
     const personalized = result.some((v) => {
       var _a2;
@@ -805,7 +867,94 @@ function personalizeVariations({
   }
 }
 
-// src/placement/test.ts
+// src/placement/personalizeVariations.ts
+function personalizeVariations(options) {
+  return topDownCriteriaPersonalizationSelectionAlgorithm(options);
+}
+
+// src/placement/strongestScorePersonalizationSelectionAlgorithm.ts
+var STRONGEST_SCORE_PERSONALIZATION_ALGORITHM = "ssc";
+function strongestScorePersonalizationSelectionAlgorithm({
+  name,
+  context,
+  variations,
+  take = 1,
+  onLogMessage
+}) {
+  var _a, _b;
+  onLogMessage == null ? void 0 : onLogMessage(["info", 300, "GROUP", { name, take }]);
+  try {
+    const variationMatches = [];
+    const defaultVariations = [];
+    const needsConsentToPersonalize = context.requireConsentForPersonalization;
+    const isInGlobalControlGroup = (_a = context.storage.data.controlGroup) != null ? _a : false;
+    const personalizationAllowed = !needsConsentToPersonalize || context.storage.data.consent;
+    let originalIndex = 0;
+    for (const variation of variations) {
+      const isInvalidFormat = variation.pz && typeof variation.pz !== "object";
+      let validVariation;
+      if (isInvalidFormat) {
+        const { pz, ...validParts } = variation;
+        validVariation = validParts;
+      } else {
+        validVariation = variation;
+      }
+      if ((_b = validVariation.pz) == null ? void 0 : _b.dim) {
+        if (!personalizationAllowed) {
+          continue;
+        }
+        const score = context.scores[validVariation.pz.dim];
+        if (score === void 0 || score <= 0) {
+          continue;
+        }
+        variationMatches.push({ variation: validVariation, score, originalIndex });
+        originalIndex++;
+      } else {
+        defaultVariations.push(validVariation);
+      }
+    }
+    variationMatches.sort((a, b) => {
+      const scoreComparison = b.score - a.score;
+      if (scoreComparison === 0) {
+        return a.originalIndex - b.originalIndex;
+      }
+      return scoreComparison;
+    });
+    const result = [];
+    for (let i = 0; i < variationMatches.length; i++) {
+      const variationMatch = variationMatches[i];
+      let variantToAdd = variationMatch.variation;
+      if (i >= take) {
+        continue;
+      }
+      if (isInGlobalControlGroup) {
+        const defaultReplacement = defaultVariations.shift();
+        if (defaultReplacement) {
+          variantToAdd = {
+            ...defaultReplacement,
+            id: variationMatch.variation.id
+          };
+        } else {
+          variantToAdd = void 0;
+        }
+      }
+      if (variantToAdd) {
+        result.push({ ...variantToAdd, control: isInGlobalControlGroup });
+      }
+    }
+    while (result.length < take && defaultVariations.length) {
+      result.push({ ...defaultVariations.shift(), control: false });
+    }
+    return {
+      personalized: variationMatches.length > 0 && !isInGlobalControlGroup,
+      variations: result
+    };
+  } finally {
+    onLogMessage == null ? void 0 : onLogMessage(["info", 300, "ENDGROUP"]);
+  }
+}
+
+// src/placement/normalizeVariationDistributions.ts
 var normalizeVariationDistributions = (variations) => {
   const { values, total, missingDistribution } = variations.reduce(
     (previous, current) => {
@@ -824,7 +973,12 @@ var normalizeVariationDistributions = (variations) => {
     }
   );
   if (total > 100) {
-    throw new Error(`Total distribution ${total} is over the maximum 100.`);
+    const autoScaleFactor = 100 / total;
+    values.forEach((value, index) => {
+      if (typeof value === "number") {
+        values[index] = value * autoScaleFactor;
+      }
+    });
   } else if (total < 100) {
     const remainder = 100 - total;
     const missingSlice = remainder / missingDistribution;
@@ -836,6 +990,8 @@ var normalizeVariationDistributions = (variations) => {
   }
   return values;
 };
+
+// src/placement/testVariations.ts
 var testVariations = ({
   name,
   context,
@@ -1602,11 +1758,12 @@ var import_lite5 = require("dequal/lite");
 var import_mitt3 = __toESM(require("mitt"));
 var CONTEXTUAL_EDITING_TEST_NAME = "contextual_editing_test";
 var CONTEXTUAL_EDITING_TEST_SELECTED_VARIANT_ID = "contextual_editing_test_selected_variant";
-var _serverTransitionState, _scores, _state, _pzCache, _plugins, _commands, _requireConsentForPersonalization, _mitt3, _Context_instances, emitTest_fn, updateGoals_fn, updateComputedScores_fn, calculateScores_fn;
+var _personalizationSelectionAlgorithms, _serverTransitionState, _scores, _state, _pzCache, _plugins, _commands, _requireConsentForPersonalization, _mitt3, _Context_instances, emitTest_fn, updateGoals_fn, updateComputedScores_fn, calculateScores_fn;
 var Context = class {
   constructor(options) {
     __privateAdd(this, _Context_instances);
     __publicField(this, "manifest");
+    __privateAdd(this, _personalizationSelectionAlgorithms);
     __privateAdd(this, _serverTransitionState);
     __privateAdd(this, _scores, {});
     __privateAdd(this, _state);
@@ -1623,7 +1780,7 @@ var Context = class {
       off: __privateGet(this, _mitt3).off
     });
     __publicField(this, "storage");
-    var _a, _b;
+    var _a, _b, _c;
     const { manifest, ...storageOptions } = options;
     __privateSet(this, _state, {});
     __privateSet(this, _plugins, options.plugins);
@@ -1631,7 +1788,20 @@ var Context = class {
     if (typeof options.transitionStore !== "undefined") {
       __privateSet(this, _commands, []);
     }
+    __privateSet(this, _personalizationSelectionAlgorithms, {
+      [TOP_DOWN_CRITERIA_PERSONALIZATION_ALGORITHM]: topDownCriteriaPersonalizationSelectionAlgorithm,
+      [STRONGEST_SCORE_PERSONALIZATION_ALGORITHM]: strongestScorePersonalizationSelectionAlgorithm
+    });
     (_a = __privateGet(this, _plugins)) == null ? void 0 : _a.forEach((plugin) => {
+      if (!plugin.personalizationSelectionAlgorithms) {
+        return;
+      }
+      __privateSet(this, _personalizationSelectionAlgorithms, {
+        ...__privateGet(this, _personalizationSelectionAlgorithms),
+        ...plugin.personalizationSelectionAlgorithms
+      });
+    });
+    (_b = __privateGet(this, _plugins)) == null ? void 0 : _b.forEach((plugin) => {
       if (!plugin.logDrain) {
         return;
       }
@@ -1682,7 +1852,7 @@ var Context = class {
         __privateGet(this, _mitt3).emit("quirksUpdated", quirks.quirks);
         __privateGet(this, _mitt3).emit("log", ["info", 4, quirks.quirks]);
       });
-      (_b = __privateGet(this, _plugins)) == null ? void 0 : _b.forEach((plugin) => {
+      (_c = __privateGet(this, _plugins)) == null ? void 0 : _c.forEach((plugin) => {
         if (!plugin.init) {
           return;
         }
@@ -1932,7 +2102,17 @@ var Context = class {
   }
   /** Executes a personalized placement with a given set of variants */
   personalize(options) {
-    const value = personalizeVariations({
+    var _a;
+    const algorithmName = (_a = options.algorithm) != null ? _a : TOP_DOWN_CRITERIA_PERSONALIZATION_ALGORITHM;
+    const algorithm = __privateGet(this, _personalizationSelectionAlgorithms)[algorithmName];
+    if (!algorithm) {
+      __privateGet(this, _mitt3).emit("log", ["warn", 304, { algorithm: algorithmName }]);
+      return {
+        personalized: false,
+        variations: []
+      };
+    }
+    const value = algorithm({
       ...options,
       context: this,
       onLogMessage: (message) => __privateGet(this, _mitt3).emit("log", message)
@@ -2006,6 +2186,7 @@ var Context = class {
     __privateGet(this, _mitt3).emit("personalizationResult", event);
   }
 };
+_personalizationSelectionAlgorithms = new WeakMap();
 _serverTransitionState = new WeakMap();
 _scores = new WeakMap();
 _state = new WeakMap();
@@ -2601,6 +2782,10 @@ var messageContent = {
   301: ({ id, op }) => ["personalization", `testing variation ${id} (${op === "|" ? "OR" : "AND"})`],
   302: ({ matched, description }) => ["personalization", `${description} is ${matched}`],
   303: (selected) => ["personalization", selected ? "selected variation" : "did not select variation"],
+  304: ({ algorithm }) => [
+    "personalization",
+    `personalization selection algorithm '${algorithm}' not found. Hiding placement.`
+  ],
   // TESTING
   400: (name) => ["testing", `executing A/B test '${name}'`],
   401: (testName) => ["testing", `${testName} is not registered in the manifest; it will not be run.`],
@@ -2706,7 +2891,9 @@ function parseQuickConnect(serialized) {
   PAIR_SEP,
   QUIRK_SEP,
   SERVER_STATE_ID,
+  STRONGEST_SCORE_PERSONALIZATION_ALGORITHM,
   ScriptType,
+  TOP_DOWN_CRITERIA_PERSONALIZATION_ALGORITHM,
   TYPE_SEP,
   TransitionDataStore,
   UNIFORM_DEFAULT_COOKIE_NAME,
@@ -2748,5 +2935,7 @@ function parseQuickConnect(serialized) {
   serializePersonalizeVariants,
   serializeQuickConnect,
   serializeQuirks,
-  testVariations
+  strongestScorePersonalizationSelectionAlgorithm,
+  testVariations,
+  topDownCriteriaPersonalizationSelectionAlgorithm
 });