resources/src/mediawiki/mediawiki.experiments.js

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