Source: randomization.js

  1. /**
  2.  * This module enables running measurements and interventions with randomization,
  3.  * such as A/B tests, multivariate tests, and randomized controlled trials.
  4.  * 
  5.  * @module randomization
  6.  */
  8. import * as permissions from "./permissions.js";
  10. /**
  11.  * A condition for a measurement or intervention that can be randomly selected.
  12.  * @typedef {Object} Condition
  13.  * @property {string} name - A name that uniquely identifies the condition within
  14.  * the set of conditions.
  15.  * @property {number} weight - The positive weight to give this condition when randomly
  16.  * selecting a condition from a set.
  17.  */
  19. /**
  20.  * @typedef {Object} ConditionSet
  21.  * @property {string} name - A name that uniquely identifies the set of conditions.
  22.  * @property {Condition[]} conditions - The conditions in the set.
  23.  */
  25. /**
  26.  * A map of condition set names to condition names. Maintaining a cache avoids
  27.  * storage race conditions. The cache is an Object rather than a Map so it can
  28.  * be easily stored in extension local storage.
  29.  * @type {Object|null}
  30.  * @private
  31.  */
  32. let conditionCache = null;
  34. /**
  35.  * A unique key for storing selected conditions in extension local storage.
  36.  * @constant {string}
  37.  * @private
  38.  */
  39. const storageKey = "webScience.randomization.conditions";
  41. /**
  42.  * Selects a condition from a set of conditions. If a condition has previously
  43.  * been selected from the set, that same condition will be returned. If not,
  44.  * a condition will be randomly selected according to the provided weights.
  45.  * @param {ConditionSet} conditionSet - The set of conditions.
  46.  * @returns {string} - The name of the selected condition in the condition set.
  47.  * @example
  48.  * // on first run, returns "red" with 0.5 probability and "blue" with 0.5 probability
  49.  * // on subsequent runs, returns the same value as before
  50.  * randomization.selectCondition({
  51.  *   name: "color",
  52.  *   conditions: [
  53.  *     {
  54.  *       name: "red",
  55.  *       weight: 1
  56.  *     },
  57.  *     {
  58.  *       name: "blue",
  59.  *       weight: 1
  60.  *     }
  61.  *   ]
  62.  * });
  63.  */
  64. export async function selectCondition(conditionSet) {
  65.     permissions.check({
  66.         module: "webScience.linkExposure",
  67.         requiredPermissions: [ "storage" ],
  68.         suggestedPermissions: [ "unlimitedStorage" ]
  69.     });
  70.     
  71.     // Initialize the cache of selected conditions
  72.     if(conditionCache === null) {
  73.         const retrievedConditions = await browser.storage.local.get(storageKey);
  74.         // Check the cache once more, to avoid a race condition
  75.         if(conditionCache === null) {
  76.             if(storageKey in retrievedConditions)
  77.                 conditionCache = retrievedConditions[storageKey];
  78.             else
  79.                 conditionCache = { };
  80.         }
  81.     }
  83.     // Try to load the selected condition from the cache
  84.     if(conditionSet.name in conditionCache)
  85.         return conditionCache[conditionSet.name];
  87.     // If there isn't a previously selected condition, select a condition,
  88.     // save it to the cache and extension local storage, and return it 
  89.     let totalWeight = 0;
  90.     const conditionNames = new Set();
  91.     if(!Array.isArray(conditionSet.conditions) || conditionSet.length === 0)
  92.         throw "The condition set must include an array with at least one condition."
  93.     for(const condition of conditionSet.conditions) {
  94.         if(condition.weight <= 0)
  95.             throw "Condition weights must be positive values."
  96.         totalWeight += condition.weight;
  97.         if(conditionNames.has(condition.name))
  98.             throw "Conditions must have unique names."
  99.         conditionNames.add(condition.name);
  100.     }
  101.     let randomValue = Math.random();
  102.     let selectedCondition = "";
  103.     for(const condition of conditionSet.conditions) {
  104.         randomValue -= (condition.weight / totalWeight);
  105.         if(randomValue <= 0) {
  106.             selectedCondition = condition.name;
  107.             break;
  108.         }
  109.     }
  110.     conditionCache[conditionSet.name] = selectedCondition;
  111.     // No need to wait for storage to complete
  112.     browser.storage.local.set({ [storageKey]: conditionCache });
  113.     return selectedCondition.repeat(1);
  114. }