resources/src/mediawiki.experiments.js

   1 /*!
   2  * @author Ori Livneh <ori@wikimedia.org>
   3  */
   4 ( function () {
   5         /**
   6          * Provides an API for bucketing users in experiments.
   7          *
   8          * @namespace mw.experiments
   9          * @singleton
  10          */
  11
  12         const CONTROL_BUCKET = 'control',
  13                 MAX_INT32_UNSIGNED = 4294967295;
  14
  15         /**
  16          * An implementation of Jenkins' one-at-a-time hash.
  17          *
  18          * See <https://en.wikipedia.org/wiki/Jenkins_hash_function>.
  19          *
  20          * @private
  21          * @param {string} string String to hash
  22          * @return {number} The hash as a 32-bit unsigned integer
  23          */
  24         function hashString( string ) {
  25                 /* eslint-disable no-bitwise */
  26                 let hash = 0,
  27                         i = string.length;
  28
  29                 while ( i-- ) {
  30                         hash += string.charCodeAt( i );
  31                         hash += ( hash << 10 );
  32                         hash ^= ( hash >> 6 );
  33                 }
  34                 hash += ( hash << 3 );
  35                 hash ^= ( hash >> 11 );
  36                 hash += ( hash << 15 );
  37
  38                 return hash >>> 0;
  39                 /* eslint-enable no-bitwise */
  40         }
  41
  42         mw.experiments = {
  43
  44                 /**
  45                  * Gets the bucket for the experiment given the token.
  46                  *
  47                  * The name of the experiment and the token are hashed. The hash is converted
  48                  * to a number which is then used to get a bucket.
  49                  *
  50                  * @example
  51                  * // The experiment has three buckets: control, A, and B. The user has a 50% chance of
  52                  * // being assigned to the control bucket, and a 25% chance of being assigned to either
  53                  * // the A or B bucket. If the experiment were disabled, then the user would always be
  54                  * // assigned to the control bucket.
  55                  * {
  56                  *   name: 'My first experiment',
  57                  *   enabled: true,
  58                  *   buckets: {
  59                  *     control: 0.5
  60                  *     A: 0.25,
  61                  *     B: 0.25
  62                  *   }
  63                  * }
  64                  *
  65                  * @param {Object} experiment
  66                  * @param {string} experiment.name The name of the experiment
  67                  * @param {boolean} experiment.enabled Whether or not the experiment is
  68                  *  enabled. If the experiment is disabled, then the user is always assigned
  69                  *  to the control bucket
  70                  * @param {Object} experiment.buckets A map of bucket name to probability
  71                  *  that the user will be assigned to that bucket
  72                  * @param {string} token A token that uniquely identifies the user for the
  73                  *  duration of the experiment
  74                  * @return {string|undefined} The bucket
  75                  */
  76                 getBucket: function ( experiment, token ) {
  77                         const buckets = experiment.buckets;
  78                         let range = 0,
  79                                 acc = 0;
  80
  81                         if ( !experiment.enabled || !Object.keys( experiment.buckets ).length ) {
  82                                 return CONTROL_BUCKET;
  83                         }
  84
  85                         for ( const key in buckets ) {
  86                                 range += buckets[ key ];
  87                         }
  88
  89                         const hash = hashString( experiment.name + ':' + token );
  90                         const max = ( hash / MAX_INT32_UNSIGNED ) * range;
  91
  92                         for ( const key in buckets ) {
  93                                 acc += buckets[ key ];
  94
  95                                 if ( max <= acc ) {
  96                                         return key;
  97                                 }
  98                         }
  99                 }
 100         };
 101
 102 }() );