logger/lib/loggers/Logger.js

  1. import process from "node:process";
  2. import {inspect} from "node:util";
  4. // Module name must not contain any other characters than alphanumerical and some specials
  5. const rIllegalModuleNameChars = /[^0-9a-zA-Z-_:@./]/i;
  7. /**
  8.  * Standard logging module for UI5 Tooling and extensions.
  9.  * <br><br>
  10.  * Emits <code>ui5.log</code> events on the [<code>process</code>]{@link https://nodejs.org/api/process.html} object,
  11.  * which can be handled by dedicated writers,
  12.  * like [@ui5/logger/writers/Console]{@link @ui5/logger/writers/Console}.
  13.  * <br><br>
  14.  * If no listener is attached to an event, messages are written directly to the <code>process.stderr</code> stream.
  15.  *
  16.  * @public
  17.  * @class
  18.  * @alias @ui5/logger/Logger
  19.  */
  20. class Logger {
  21. 	/**
  22. 	 * Available log levels, ordered by priority:
  23. 	 * <br>
  24. 	 * <ol>
  25. 	 *   <li>silly</li>
  26. 	 *   <li>verbose</li>
  27. 	 *   <li>perf</li>
  28. 	 *   <li>info <i>(default)</i></li>
  29. 	 *   <li>warn</li>
  30. 	 *   <li>error</li>
  31. 	 *   <li>silent</li>
  32. 	 * </ol>
  33. 	 *
  34. 	 * Log level <code>silent</code> is special in the sense that no messages can be submitted with that level.
  35. 	 * It can be used to suppress all logging.
  36. 	 *
  37. 	 * @member {string[]}
  38. 	 * @public
  39. 	*/
  40. 	static LOG_LEVELS = ["silly", "verbose", "perf", "info", "warn", "error", "silent"];
  42. 	/**
  43. 	 * Event name used for emitting new log-message event on the
  44. 	 * [<code>process</code>]{@link https://nodejs.org/api/process.html} object
  45. 	 *
  46. 	 * @member {string}
  47. 	 * @public
  48. 	*/
  49. 	static LOG_EVENT_NAME = "ui5.log";
  51. 	/**
  52. 	 * Sets the standard log level.
  53. 	 * <br>
  54. 	 * <b>Example:</b> Setting it to <code>perf</code> would suppress all <code>silly</code> and <code>verbose</code>
  55. 	 * logging, and only show <code>perf</code>, <code>info</code>, <code>warn</code> and <code>error</code> logs.
  56. 	 *
  57. 	 * @public
  58. 	 * @param {string} levelName New log level
  59. 	 */
  60. 	static setLevel(levelName) {
  61. 		process.env.UI5_LOG_LVL = levelName;
  62. 	}
  64. 	/**
  65. 	 * Gets the current log level
  66. 	 *
  67. 	 * @public
  68. 	 * @returns {string} The current log level. Defaults to <code>info</code>
  69. 	 */
  70. 	static getLevel() {
  71. 		if (process.env.UI5_LOG_LVL) {
  72. 			// Check whether set log level is valid
  73. 			const levelName = process.env.UI5_LOG_LVL;
  74. 			if (!Logger.LOG_LEVELS.includes(levelName)) {
  75. 				throw new Error(
  76. 					`UI5 Logger: Environment variable UI5_LOG_LVL is set to an unknown log level "${levelName}". ` +
  77. 					`Valid levels are ${Logger.LOG_LEVELS.join(", ")}`);
  78. 			}
  79. 			return levelName;
  80. 		} else {
  81. 			return "info";
  82. 		}
  83. 	}
  85. 	/**
  86. 	 * Tests whether the provided log level is enabled by the current log level
  87. 	 *
  88. 	 * @public
  89. 	 * @param {string} levelName Log level to test
  90. 	 * @returns {boolean} True if the provided level is enabled
  91. 	 */
  92. 	static isLevelEnabled(levelName) {
  93. 		const currIdx = Logger.LOG_LEVELS.indexOf(Logger.getLevel());
  94. 		const reqIdx = Logger.LOG_LEVELS.indexOf(levelName);
  95. 		if (reqIdx === -1) {
  96. 			throw new Error(`Unknown log level "${levelName}"`);
  97. 		}
  98. 		return reqIdx >= currIdx;
  99. 	}
  101. 	/**
  102. 	 * Formats a given parameter into a string
  103. 	 *
  104. 	 * @param {any} message Single log message parameter passed by a program
  105. 	 * @returns {string} String representation for the given message
  106. 	 */
  107. 	static _formatMessage(message) {
  108. 		if (typeof message === "string" || message instanceof String) {
  109. 			return message;
  110. 		}
  111. 		return inspect(message, {
  112. 			depth: 3,
  113. 			compact: 2,
  114. 		});
  115. 	}
  117. 	#moduleName;
  119. 	/**
  120. 	 *
  121. 	 *
  122. 	 * @public
  123. 	 * @param {string} moduleName Identifier for messages created by this logger.
  124. 	 * Example: <code>module:submodule:Class</code>
  125. 	 */
  126. 	constructor(moduleName) {
  127. 		if (!moduleName) {
  128. 			throw new Error("Logger: Missing moduleName parameter");
  129. 		}
  130. 		if (rIllegalModuleNameChars.test(moduleName)) {
  131. 			throw new Error(`Logger: Invalid module name: ${moduleName}`);
  132. 		}
  133. 		this.#moduleName = moduleName;
  134. 	}
  136. 	/**
  137. 	 * Tests whether the provided log level is enabled by the current log level
  138. 	 *
  139. 	 * @public
  140. 	 * @param {string} levelName Log level to test
  141. 	 * @returns {boolean} True if the provided level is enabled
  142. 	 */
  143. 	isLevelEnabled(levelName) {
  144. 		return Logger.isLevelEnabled(levelName);
  145. 	}
  147. 	_emit(eventName, payload) {
  148. 		return process.emit(eventName, payload);
  149. 	}
  151. 	_log(level, message) {
  152. 		if (this.isLevelEnabled(level)) {
  153. 			process.stderr.write(`[${level}] ${message}\n`);
  154. 		}
  155. 	}
  157. 	_emitOrLog(level, message) {
  158. 		const hasListeners = this._emit(Logger.LOG_EVENT_NAME, {
  159. 			level,
  160. 			message,
  161. 			moduleName: this.#moduleName,
  162. 		});
  163. 		if (!hasListeners) {
  164. 			this._log(level, `${this.#moduleName}: ${message}`);
  165. 		}
  166. 	}
  167. }
  169. /**
  170.  * Create a log entry with the <code>silly</code> level
  171.  *
  172.  * @public
  173.  * @name @ui5/logger/Logger#silly
  174.  * @function
  175.  * @memberof @ui5/logger/Logger
  176.  * @param {...any} message Messages to log. An automatic string conversion is applied if necessary
  177.  */
  179. /**
  180.  * Create a log entry with the <code>verbose</code> level
  181.  *
  182.  * @public
  183.  * @name @ui5/logger/Logger#verbose
  184.  * @function
  185.  * @memberof @ui5/logger/Logger
  186.  * @param {...any} message Messages to log. An automatic string conversion is applied if necessary
  187.  */
  189. /**
  190.  * Create a log entry with the <code>perf</code> level
  191.  *
  192.  * @public
  193.  * @name @ui5/logger/Logger#perf
  194.  * @function
  195.  * @memberof @ui5/logger/Logger
  196.  * @param {...any} message Messages to log. An automatic string conversion is applied if necessary
  197.  */
  199. /**
  200.  * Create a log entry with the <code>info</code> level
  201.  *
  202.  * @public
  203.  * @name @ui5/logger/Logger#info
  204.  * @function
  205.  * @memberof @ui5/logger/Logger
  206.  * @param {...any} message Messages to log. An automatic string conversion is applied if necessary
  207.  */
  209. /**
  210.  * Create a log entry with the <code>warn</code> level
  211.  *
  212.  * @public
  213.  * @name @ui5/logger/Logger#warn
  214.  * @function
  215.  * @memberof @ui5/logger/Logger
  216.  * @param {...any} message Messages to log. An automatic string conversion is applied if necessary
  217.  */
  219. /**
  220.  * Create a log entry with the <code>error</code> level
  221.  *
  222.  * @public
  223.  * @name @ui5/logger/Logger#error
  224.  * @function
  225.  * @memberof @ui5/logger/Logger
  226.  * @param {...any} message Messages to log. An automatic string conversion is applied if necessary
  227.  */
  229. Logger.LOG_LEVELS.forEach((logLevel) => {
  230. 	if (logLevel === "silent") {
  231. 		// This level is to suppress any logging. Hence we do not provide a dedicated log-function
  232. 		return;
  233. 	}
  234. 	Logger.prototype[logLevel] = function(...args) {
  235. 		const message = args.map(Logger._formatMessage).join(" ");
  236. 		this._emitOrLog(logLevel, message);
  237. 	};
  238. });
  240. export default Logger;