File: source/skylink-debug.js

  1. /**
  2.  * Stores the log message starting header string.
  3.  * E.g. "<header> - <the log message>".
  4.  * @attribute _LOG_KEY
  5.  * @type String
  6.  * @private
  7.  * @scoped true
  8.  * @for Skylink
  9.  * @since 0.5.4
  10.  */
  11. var _LOG_KEY = 'SkylinkJS';
  12.  
  13. /**
  14.  * Stores the list of available SDK log levels.
  15.  * @attribute _LOG_LEVELS
  16.  * @type Array
  17.  * @private
  18.  * @scoped true
  19.  * @for Skylink
  20.  * @since 0.5.5
  21.  */
  22. var _LOG_LEVELS = ['error', 'warn', 'info', 'log', 'debug'];
  23.  
  24. /**
  25.  * Stores the current SDK log level.
  26.  * Default is ERROR (<code>0</code>).
  27.  * @attribute _logLevel
  28.  * @type String
  29.  * @default 0
  30.  * @private
  31.  * @scoped true
  32.  * @for Skylink
  33.  * @since 0.5.4
  34.  */
  35. var _logLevel = 0;
  36.  
  37. /**
  38.  * Stores the flag if debugging mode is enabled.
  39.  * This manipulates the SkylinkLogs interface.
  40.  * @attribute _enableDebugMode
  41.  * @type Boolean
  42.  * @default false
  43.  * @private
  44.  * @scoped true
  45.  * @for Skylink
  46.  * @since 0.5.4
  47.  */
  48. var _enableDebugMode = false;
  49.  
  50. /**
  51.  * Stores the flag if logs should be stored in SkylinkLogs interface.
  52.  * @attribute _enableDebugStack
  53.  * @type Boolean
  54.  * @default false
  55.  * @private
  56.  * @scoped true
  57.  * @for Skylink
  58.  * @since 0.5.5
  59.  */
  60. var _enableDebugStack = false;
  61.  
  62. /**
  63.  * Stores the flag if logs should trace if available.
  64.  * This uses the <code>console.trace</code> API.
  65.  * @attribute _enableDebugTrace
  66.  * @type Boolean
  67.  * @default false
  68.  * @private
  69.  * @scoped true
  70.  * @for Skylink
  71.  * @since 0.5.5
  72.  */
  73. var _enableDebugTrace = false;
  74.  
  75. /**
  76.  * Stores the flag if logs should print timestamp.
  77.  * @attribute _printTimestamp
  78.  * @type Boolean
  79.  * @default false
  80.  * @private
  81.  * @scoped true
  82.  * @for Skylink
  83.  * @since 0.6.26
  84.  */
  85. var _printTimestamp = false;
  86.  
  87. /**
  88.  * Stores the logs used for SkylinkLogs object.
  89.  * @attribute _storedLogs
  90.  * @type Array
  91.  * @private
  92.  * @scoped true
  93.  * @for Skylink
  94.  * @since 0.5.5
  95.  */
  96. var _storedLogs = [];
  97.  
  98. /**
  99.  * Function that gets the stored logs.
  100.  * @method _getStoredLogsFn
  101.  * @private
  102.  * @scoped true
  103.  * @for Skylink
  104.  * @since 0.5.5
  105.  */
  106. var _getStoredLogsFn = function (logLevel) {
  107.   if (typeof logLevel === 'undefined') {
  108.     return _storedLogs;
  109.   }
  110.   var returnLogs = [];
  111.   for (var i = 0; i < _storedLogs.length; i++) {
  112.     if (_storedLogs[i][1] === _LOG_LEVELS[logLevel]) {
  113.       returnLogs.push(_storedLogs[i]);
  114.     }
  115.   }
  116.   return returnLogs;
  117. };
  118.  
  119. /**
  120.  * Function that clears the stored logs.
  121.  * @method _clearAllStoredLogsFn
  122.  * @private
  123.  * @scoped true
  124.  * @for Skylink
  125.  * @since 0.5.5
  126.  */
  127. var _clearAllStoredLogsFn = function () {
  128.   _storedLogs = [];
  129. };
  130.  
  131. /**
  132.  * Function that prints in the Web Console interface the stored logs.
  133.  * @method _printAllStoredLogsFn
  134.  * @private
  135.  * @scoped true
  136.  * @for Skylink
  137.  * @since 0.5.5
  138.  */
  139. var _printAllStoredLogsFn = function () {
  140.   for (var i = 0; i < _storedLogs.length; i++) {
  141.     var timestamp = _storedLogs[i][0];
  142.     var log = (console[_storedLogs[i][1]] !== 'undefined') ?
  143.       _storedLogs[i][1] : 'log';
  144.     var message = _storedLogs[i][2];
  145.     var debugObject = _storedLogs[i][3];
  146.  
  147.     if (typeof debugObject !== 'undefined') {
  148.       console[log](message, debugObject, timestamp);
  149.     } else {
  150.       console[log](message, timestamp);
  151.     }
  152.   }
  153. };
  154.  
  155. /**
  156.  * <blockquote class="info">
  157.  *   To utilise and enable the <code>SkylinkLogs</code> API functionalities, the
  158.  *   <a href="#method_setDebugMode"><code>setDebugMode()</code> method</a>
  159.  *   <code>options.storeLogs</code> parameter has to be enabled.
  160.  * </blockquote>
  161.  * The object interface to manage the SDK <a href="https://developer.mozilla.org/en/docs/Web/API/console">
  162.  * Javascript Web Console</a> logs.
  163.  * @property SkylinkLogs
  164.  * @type JSON
  165.  * @global true
  166.  * @for Skylink
  167.  * @since 0.5.5
  168.  */
  169. var SkylinkLogs = {
  170.   /**
  171.    * Function that gets the current stored SDK <code>console</code> logs.
  172.    * @property SkylinkLogs.getLogs
  173.    * @param {Number} [logLevel] The specific log level of logs to return.
  174.    * - When not provided or that the level does not exists, it will return all logs of all levels.
  175.    *  [Rel: Skylink.LOG_LEVEL]
  176.    * @return {Array} The array of stored logs.<ul>
  177.    *   <li><code><#index></code><var><b>{</b>Array<b>}</b></var><p>The stored log item.</p><ul>
  178.    *   <li><code>0</code><var><b>{</b>Date<b>}</b></var><p>The DateTime of when the log was stored.</p></li>
  179.    *   <li><code>1</code><var><b>{</b>String<b>}</b></var><p>The log level. [Rel: Skylink.LOG_LEVEL]</p></li>
  180.    *   <li><code>2</code><var><b>{</b>String<b>}</b></var><p>The log message.</p></li>
  181.    *   <li><code>3</code><var><b>{</b>Any<b>}</b></var><span class="label">Optional</span><p>The log message object.
  182.    *   </p></li></ul></li></ul>
  183.    * @example
  184.    *  // Example 1: Get logs of specific level
  185.    *  var debugLogs = SkylinkLogs.getLogs(skylinkDemo.LOG_LEVEL.DEBUG);
  186.    *
  187.    *  // Example 2: Get all the logs
  188.    *  var allLogs = SkylinkLogs.getLogs();
  189.    * @type Function
  190.    * @global true
  191.    * @triggerForPropHackNone true
  192.    * @for Skylink
  193.    * @since 0.5.5
  194.    */
  195.   getLogs: _getStoredLogsFn,
  196.  
  197.   /**
  198.    * Function that clears all the current stored SDK <code>console</code> logs.
  199.    * @property SkylinkLogs.clearAllLogs
  200.    * @type Function
  201.    * @example
  202.    *   // Example 1: Clear all the logs
  203.    *   SkylinkLogs.clearAllLogs();
  204.    * @global true
  205.    * @triggerForPropHackNone true
  206.    * @for Skylink
  207.    * @since 0.5.5
  208.    */
  209.   clearAllLogs: _clearAllStoredLogsFn,
  210.  
  211.   /**
  212.    * Function that prints all the current stored SDK <code>console</code> logs into the
  213.    * <a href="https://developer.mozilla.org/en/docs/Web/API/console">Javascript Web Console</a>.
  214.    * @property SkylinkLogs.printAllLogs
  215.    * @type Function
  216.    * @example
  217.    *   // Example 1: Print all the logs
  218.    *   SkylinkLogs.printAllLogs();
  219.    * @global true
  220.    * @triggerForPropHackNone true
  221.    * @for Skylink
  222.    * @since 0.5.5
  223.    */
  224.   printAllLogs: _printAllStoredLogsFn
  225. };
  226.  
  227. /**
  228.  * Function that handles the logs received and prints in the Web Console interface according to the log level set.
  229.  * @method _logFn
  230.  * @private
  231.  * @required
  232.  * @scoped true
  233.  * @for Skylink
  234.  * @since 0.5.5
  235.  */
  236. var _logFn = function(logLevel, message, debugObject) {
  237.   var outputLog = '';
  238.   var datetime = (new Date());
  239.  
  240.   if (typeof message === 'object') {
  241.     outputLog += (message[0]) ? ' [' + message[0] + '] -' : ' -';
  242.     outputLog += (message[1]) ? ' <<' + message[1] + '>>' : '';
  243.     if (message[2]) {
  244.       outputLog += ' ';
  245.       if (typeof message[2] === 'object') {
  246.         for (var i = 0; i < message[2].length; i++) {
  247.           outputLog += '(' + message[2][i] + ')';
  248.         }
  249.       } else {
  250.         outputLog += '(' + message[2] + ')';
  251.       }
  252.     }
  253.     outputLog += ' ' + message[3];
  254.   } else {
  255.     outputLog += ' - ' + message;
  256.   }
  257.  
  258.   if (_enableDebugMode && _enableDebugStack) {
  259.     // store the logs
  260.     var logItem = [datetime, _LOG_LEVELS[logLevel], outputLog];
  261.  
  262.     if (typeof debugObject !== 'undefined') {
  263.       logItem.push(debugObject);
  264.     }
  265.     _storedLogs.push(logItem);
  266.   }
  267.  
  268.   outputLog = _LOG_KEY + (_printTimestamp ? ' :: ' + datetime.toISOString() : '') + outputLog;
  269.  
  270.   if (_logLevel >= logLevel) {
  271.     // Fallback to log if failure
  272.     logLevel = (typeof console[_LOG_LEVELS[logLevel]] === 'undefined') ? 3 : logLevel;
  273.  
  274.     if (_enableDebugMode && _enableDebugTrace) {
  275.       var logConsole = (typeof console.trace === 'undefined') ? logLevel[3] : 'trace';
  276.       if (typeof debugObject !== 'undefined') {
  277.         console[_LOG_LEVELS[logLevel]](outputLog, debugObject);
  278.         // output if supported
  279.         if (typeof console.trace !== 'undefined') {
  280.           console.trace('');
  281.         }
  282.       } else {
  283.         console[_LOG_LEVELS[logLevel]](outputLog);
  284.         // output if supported
  285.         if (typeof console.trace !== 'undefined') {
  286.           console.trace('');
  287.         }
  288.       }
  289.     } else {
  290.       if (typeof debugObject !== 'undefined') {
  291.         console[_LOG_LEVELS[logLevel]](outputLog, debugObject);
  292.       } else {
  293.         console[_LOG_LEVELS[logLevel]](outputLog);
  294.       }
  295.     }
  296.   }
  297. };
  298.  
  299. /**
  300.  * Stores the logging functions.
  301.  * @attribute log
  302.  * @param {Function} debug The function that handles the DEBUG level logs.
  303.  * @param {Function} log The function that handles the LOG level logs.
  304.  * @param {Function} info The function that handles the INFO level logs.
  305.  * @param {Function} warn The function that handles the WARN level logs.
  306.  * @param {Function} error The function that handles the ERROR level logs.
  307.  * @type JSON
  308.  * @private
  309.  * @scoped true
  310.  * @for Skylink
  311.  * @since 0.5.4
  312.  */
  313. var log = {
  314.   debug: function (message, object) {
  315.     _logFn(4, message, object);
  316.   },
  317.  
  318.   log: function (message, object) {
  319.     _logFn(3, message, object);
  320.   },
  321.  
  322.   info: function (message, object) {
  323.     _logFn(2, message, object);
  324.   },
  325.  
  326.   warn: function (message, object) {
  327.     _logFn(1, message, object);
  328.   },
  329.  
  330.   error: function (message, object) {
  331.     _logFn(0, message, object);
  332.   }
  333. };
  334.  
  335. /**
  336.  * Function that configures the level of <code>console</code> API logs to be printed in the
  337.  * <a href="https://developer.mozilla.org/en/docs/Web/API/console">Javascript Web Console</a>.
  338.  * @method setLogLevel
  339.  * @param {Number} [logLevel] The specific log level of logs to return.
  340.  * - When not provided or that the level does not exists, it will not overwrite the current log level.
  341.  *   <small>By default, the initial log level is <code>ERROR</code>.</small>
  342.  *   [Rel: Skylink.LOG_LEVEL]
  343.  * @example
  344.  *   // Example 1: Print all of the console.debug, console.log, console.info, console.warn and console.error logs.
  345.  *   skylinkDemo.setLogLevel(skylinkDemo.LOG_LEVEL.DEBUG);
  346.  *
  347.  *   // Example 2: Print only the console.log, console.info, console.warn and console.error logs.
  348.  *   skylinkDemo.setLogLevel(skylinkDemo.LOG_LEVEL.LOG);
  349.  *
  350.  *   // Example 3: Print only the console.info, console.warn and console.error logs.
  351.  *   skylinkDemo.setLogLevel(skylinkDemo.LOG_LEVEL.INFO);
  352.  *
  353.  *   // Example 4: Print only the console.warn and console.error logs.
  354.  *   skylinkDemo.setLogLevel(skylinkDemo.LOG_LEVEL.WARN);
  355.  *
  356.  *   // Example 5: Print only the console.error logs. This is done by default.
  357.  *   skylinkDemo.setLogLevel(skylinkDemo.LOG_LEVEL.ERROR);
  358.  * @for Skylink
  359.  * @since 0.5.5
  360.  */
  361. Skylink.prototype.setLogLevel = function(logLevel) {
  362.   for (var level in this.LOG_LEVEL) {
  363.     if (this.LOG_LEVEL[level] === logLevel) {
  364.       _logLevel = logLevel;
  365.       log.log([null, 'Log', level, 'Log level exists. Level is set']);
  366.       return;
  367.     }
  368.   }
  369.   log.error([null, 'Log', level, 'Log level does not exist. Level is not set']);
  370. };
  371.  
  372. /**
  373.  * Function that configures the debugging mode of the SDK.
  374.  * @method setDebugMode
  375.  * @param {Boolean|JSON} [options=false] The debugging options.
  376.  * - When provided as a boolean, this sets both <code>options.trace</code>
  377.  *   and <code>options.storeLogs</code> to its boolean value.
  378.  * @param {Boolean} [options.trace=false] The flag if SDK <code>console</code> logs
  379.  *   should output as <code>console.trace()</code> logs for tracing the <code>Function</code> call stack.
  380.  *   <small>Note that the <code>console.trace()</code> output logs is determined by the log level set
  381.  *   <a href="#method_setLogLevel"><code>setLogLevel()</code> method</a>.</small>
  382.  *   <small>If <code>console.trace()</code> API is not supported, <code>setDebugMode()</code>
  383.  *   will fallback to use <code>console.log()</code> API.</small>
  384.  * @param {Boolean} [options.storeLogs=false] The flag if SDK should store the <code>console</code> logs.
  385.  *   <small>This is required to be enabled for <a href="#prop_SkylinkLogs"><code>SkylinkLogs</code> API</a>.</small>
  386.  * @param {Boolean} [options.printTimestamp=false] The flag if SDK should print the timestamp of the <code>console</code> logs.
  387.  * @example
  388.  *   // Example 1: Enable both options.storeLogs and options.trace
  389.  *   skylinkDemo.setDebugMode(true);
  390.  *
  391.  *   // Example 2: Enable only options.storeLogs
  392.  *   skylinkDemo.setDebugMode({ storeLogs: true });
  393.  *
  394.  *   // Example 3: Disable debugging mode
  395.  *   skylinkDemo.setDebugMode();
  396.  * @for Skylink
  397.  * @since 0.5.2
  398.  */
  399. Skylink.prototype.setDebugMode = function(isDebugMode) {
  400.   // setDebugMode({})
  401.   if (isDebugMode && typeof isDebugMode === 'object') {
  402.     _enableDebugMode = true;
  403.     _enableDebugTrace = isDebugMode.trace === true;
  404.     _enableDebugStack = isDebugMode.storeLogs === true;
  405.     _printTimestamp = isDebugMode.printTimestamp === true;
  406.   // setDebugMode(true)
  407.   } else if (isDebugMode === true) {
  408.     _enableDebugMode = true;
  409.     _enableDebugTrace = true;
  410.     _enableDebugStack = true;
  411.     _printTimestamp = false;
  412.   // setDebugMode()
  413.   } else {
  414.     _enableDebugMode = false;
  415.     _enableDebugTrace = false;
  416.     _enableDebugStack = false;
  417.     _printTimestamp = false;
  418.   }
  419. };
  420.