resources/src/mediawiki.base/log.js

   1 // This file extends the mw.log skeleton defined in startup/mediawiki.js.
   2 // Code that is not needed by mw.loader is placed here.
   3
   4 /* eslint-disable no-console */
   5
   6 /**
   7  * Log debug messages and developer warnings to the browser console.
   8  *
   9  * See [mw.log()]{@link mw.log(2)} for verbose debug logging.
  10  *
  11  * @namespace mw.log
  12  */
  13
  14 /**
  15  * Create a function that returns true for the first call from any particular call stack.
  16  *
  17  * @private
  18  * @return {Function}
  19  * @return {boolean|undefined} return.return True if the caller was not seen before.
  20  */
  21 function stackSet() {
  22         // Optimisation: Don't create or compute anything for the common case
  23         // where deprecations are not triggered.
  24         let stacks;
  25
  26         return function isFirst() {
  27                 if ( !stacks ) {
  28                         stacks = new Set();
  29                 }
  30                 const stack = new Error().stack;
  31                 if ( !stacks.has( stack ) ) {
  32                         stacks.add( stack );
  33                         return true;
  34                 }
  35         };
  36 }
  37
  38 /**
  39  * Write a message to the browser console's error channel.
  40  *
  41  * Most browsers also print a stacktrace when calling this method if the
  42  * argument is an Error object.
  43  *
  44  * @since 1.26
  45  * @method
  46  * @param {...Mixed} msg Messages to output to console
  47  */
  48 mw.log.error = Function.prototype.bind.call( console.error, console );
  49
  50 /**
  51  * Create a function that logs a deprecation warning when called.
  52  *
  53  * @example
  54  * var deprecatedNoB = mw.log.makeDeprecated( 'hello_without_b', 'Use of hello without b is deprecated.' );
  55  *
  56  * function hello( a, b ) {
  57  *   if ( b === undefined ) {
  58  *     deprecatedNoB();
  59  *     b = 0;
  60  *   }
  61  *   return a + b;
  62  * }
  63  *
  64  * hello( 1 );
  65  *
  66  * @since 1.38
  67  * @param {string|null} key Name of the feature for deprecation tracker,
  68  *  or null for a console-only deprecation.
  69  * @param {string} msg Deprecation warning.
  70  * @return {Function}
  71  */
  72 mw.log.makeDeprecated = function ( key, msg ) {
  73         const isFirst = stackSet();
  74         return function maybeLog() {
  75                 if ( isFirst() ) {
  76                         if ( key ) {
  77                                 mw.track( 'mw.deprecate', key );
  78                         }
  79                         mw.log.warn( msg );
  80                 }
  81         };
  82 };
  83
  84 /**
  85  * Create a property on a host object that, when accessed, will log
  86  * a deprecation warning to the console.
  87  *
  88  * @example
  89  * mw.log.deprecate( window, 'myGlobalFn', myGlobalFn );
  90  *
  91  * @example
  92  * mw.log.deprecate( Thing, 'old', old, 'Use Other.thing instead', 'Thing.old'  );
  93  *
  94  * @param {Object} obj Host object of deprecated property
  95  * @param {string} key Name of property to create in `obj`
  96  * @param {any} val The value this property should return when accessed
  97  * @param {string} [msg] Optional extra text to add to the deprecation warning
  98  * @param {string} [logName] Name of the feature for deprecation tracker.
  99  *  Tracking is disabled by default, except for global variables on `window`.
 100  */
 101 mw.log.deprecate = function ( obj, key, val, msg, logName ) {
 102         const maybeLog = mw.log.makeDeprecated(
 103                 logName || ( obj === window ? key : null ),
 104                 'Use of "' + ( logName || key ) + '" is deprecated.' + ( msg ? ' ' + msg : '' )
 105         );
 106         Object.defineProperty( obj, key, {
 107                 configurable: true,
 108                 enumerable: true,
 109                 get: function () {
 110                         maybeLog();
 111                         return val;
 112                 },
 113                 set: function ( newVal ) {
 114                         maybeLog();
 115                         val = newVal;
 116                 }
 117         } );
 118 };