toolkit/modules/Deprecated.sys.mjs

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 const PREF_DEPRECATION_WARNINGS = "devtools.errorconsole.deprecation_warnings";
   6
   7 // A flag that indicates whether deprecation warnings should be logged.
   8 var logWarnings = Services.prefs.getBoolPref(PREF_DEPRECATION_WARNINGS);
   9
  10 Services.prefs.addObserver(
  11   PREF_DEPRECATION_WARNINGS,
  12   function (aSubject, aTopic, aData) {
  13     logWarnings = Services.prefs.getBoolPref(PREF_DEPRECATION_WARNINGS);
  14   }
  15 );
  16
  17 /**
  18  * Build a callstack log message.
  19  *
  20  * @param nsIStackFrame aStack
  21  *        A callstack to be converted into a string log message.
  22  */
  23 function stringifyCallstack(aStack) {
  24   // If aStack is invalid, use Components.stack (ignoring the last frame).
  25   if (!aStack || !(aStack instanceof Ci.nsIStackFrame)) {
  26     aStack = Components.stack.caller;
  27   }
  28
  29   let frame = aStack.caller;
  30   let msg = "";
  31   // Get every frame in the callstack.
  32   while (frame) {
  33     if (frame.filename || frame.lineNumber || frame.name) {
  34       msg += frame.filename + " " + frame.lineNumber + " " + frame.name + "\n";
  35     }
  36     frame = frame.caller;
  37   }
  38   return msg;
  39 }
  40
  41 export var Deprecated = {
  42   /**
  43    * Log a deprecation warning.
  44    *
  45    * @param string aText
  46    *        Deprecation warning text.
  47    * @param string aUrl
  48    *        A URL pointing to documentation describing deprecation
  49    *        and the way to address it.
  50    * @param nsIStackFrame aStack
  51    *        An optional callstack. If it is not provided a
  52    *        snapshot of the current JavaScript callstack will be
  53    *        logged.
  54    */
  55   warning(aText, aUrl, aStack) {
  56     if (!logWarnings) {
  57       return;
  58     }
  59
  60     // If URL is not provided, report an error.
  61     if (!aUrl) {
  62       console.error(
  63         "Error in Deprecated.warning: warnings must " +
  64           "provide a URL documenting this deprecation."
  65       );
  66       return;
  67     }
  68
  69     let textMessage =
  70       "DEPRECATION WARNING: " +
  71       aText +
  72       "\nYou may find more details about this deprecation at: " +
  73       aUrl +
  74       "\n" +
  75       // Append a callstack part to the deprecation message.
  76       stringifyCallstack(aStack);
  77
  78     // Report deprecation warning.
  79     console.error(textMessage);
  80   },
  81 };