@qubit-ltd/logging 1.4.4

package/dist/logging.iife.js

@@ -0,0 +1,1342 @@
+var Logging = (function (exports) {
+  'use strict';
+
+  function _classCallCheck(a, n) {
+    if (!(a instanceof n)) throw new TypeError("Cannot call a class as a function");
+  }
+
+  function _typeof(o) {
+    "@babel/helpers - typeof";
+
+    return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) {
+      return typeof o;
+    } : function (o) {
+      return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+    }, _typeof(o);
+  }
+
+  function toPrimitive(t, r) {
+    if ("object" != _typeof(t) || !t) return t;
+    var e = t[Symbol.toPrimitive];
+    if (void 0 !== e) {
+      var i = e.call(t, r);
+      if ("object" != _typeof(i)) return i;
+      throw new TypeError("@@toPrimitive must return a primitive value.");
+    }
+    return (String )(t);
+  }
+
+  function toPropertyKey(t) {
+    var i = toPrimitive(t, "string");
+    return "symbol" == _typeof(i) ? i : i + "";
+  }
+
+  function _defineProperties(e, r) {
+    for (var t = 0; t < r.length; t++) {
+      var o = r[t];
+      o.enumerable = o.enumerable || !1, o.configurable = !0, "value" in o && (o.writable = !0), Object.defineProperty(e, toPropertyKey(o.key), o);
+    }
+  }
+  function _createClass(e, r, t) {
+    return _defineProperties(e.prototype, r), _defineProperties(e, t), Object.defineProperty(e, "prototype", {
+      writable: !1
+    }), e;
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2023.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * Predefined logging levels.
+   *
+   * @author Haixing Hu
+   */
+  var LOGGING_LEVELS = {
+    TRACE: 0,
+    DEBUG: 1,
+    INFO: 2,
+    WARN: 3,
+    ERROR: 4,
+    NONE: 5
+  };
+
+  /**
+   * Checks the validity of an appender.
+   *
+   * @param {Object} appender
+   *     The appender to be checked. If it is invalid, an `Error` will be thrown.
+   * @author Haixing Hu
+   * @private
+   */
+  function checkAppender(appender) {
+    if (appender === null || _typeof(appender) !== 'object') {
+      throw new TypeError('The appender for a logger must be a non-null object.');
+    }
+    for (var level in LOGGING_LEVELS) {
+      // NOTE: do NOT use Object.hasOwn() because it has a lot of compatibility problems
+      if (Object.prototype.hasOwnProperty.call(LOGGING_LEVELS, level) && level !== 'NONE') {
+        var methodName = level.toLowerCase();
+        var method = appender[methodName];
+        if (typeof method !== 'function') {
+          throw new Error("The appender of this logger has no ".concat(methodName, "() method."));
+        }
+      }
+    }
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2023.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * Checks the validity of a logging level.
+   *
+   * @param {String} level
+   *     The logging level to be checked. If it is invalid, an `Error` will be
+   *     thrown.
+   * @private
+   */
+  function checkLoggingLevel(level) {
+    if (typeof level !== 'string') {
+      throw new TypeError('The logging level must be a string.');
+    }
+    if (LOGGING_LEVELS[level] === undefined) {
+      throw new RangeError("Unknown logging level \"".concat(level, "\". ") + "Possible values are\uFF1A".concat(JSON.stringify(Object.keys(LOGGING_LEVELS)), "."));
+    }
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2023.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * Convert a string to uppercase.
+   *
+   * @param {any} value
+   *     The value to be converted. If it is not a string, it will be returned directly.
+   * @return {any|string}
+   *     The converted string, or the original value if it is not a string.
+   * @author Haixing Hu
+   * @private
+   */
+  function upperCaseString(value) {
+    if (typeof value !== 'string' && !(value instanceof String)) {
+      return value;
+    }
+    return value.toUpperCase();
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2024.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * Determines whether a value is a string.
+   *
+   * A value is a string if it is a string or a `String` object.
+   *
+   * @param {any} value
+   *     The value to be checked.
+   * @return {boolean}
+   *     `true` if the value is a string; `false` otherwise.
+   * @author Haixing Hu
+   * @private
+   */
+  function isString(value) {
+    return typeof value === 'string' || value instanceof String;
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2024.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * Gets the engine name of the current browser.
+   *
+   * @return {string}
+   *     The engine name of the current browser.
+   * @author Haixing Hu
+   * @private
+   */
+  function getBrowserEngine() {
+    var userAgent = window.navigator.userAgent;
+    if (/Gecko\/\d/i.test(userAgent) && !/like Gecko/i.test(userAgent)) {
+      return 'Gecko'; // Firefox and other Gecko-based browsers
+    } else if (/Chrome|Chromium|Edg/i.test(userAgent)) {
+      return 'Blink'; // Chrome, Edge and other Blink-based browsers
+    } else if (/(Apple)?WebKit/i.test(userAgent) && !/Chrome/i.test(userAgent)) {
+      return 'WebKit'; // Safari and other WebKit-based browsers
+    } else if (/Trident/i.test(userAgent)) {
+      return 'Trident'; // Internet Explorer and other Trident-based browsers
+    } else if (/Presto/i.test(userAgent)) {
+      return 'Presto'; // Opera and other Presto-based browsers
+    } else {
+      return 'Unknown';
+    }
+  }
+
+  function _arrayLikeToArray$1(r, a) {
+    (null == a || a > r.length) && (a = r.length);
+    for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e];
+    return n;
+  }
+
+  function _arrayWithoutHoles(r) {
+    if (Array.isArray(r)) return _arrayLikeToArray$1(r);
+  }
+
+  function _iterableToArray(r) {
+    if ("undefined" != typeof Symbol && null != r[Symbol.iterator] || null != r["@@iterator"]) return Array.from(r);
+  }
+
+  function _unsupportedIterableToArray$1(r, a) {
+    if (r) {
+      if ("string" == typeof r) return _arrayLikeToArray$1(r, a);
+      var t = {}.toString.call(r).slice(8, -1);
+      return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray$1(r, a) : void 0;
+    }
+  }
+
+  function _nonIterableSpread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+  }
+
+  function _toConsumableArray(r) {
+    return _arrayWithoutHoles(r) || _iterableToArray(r) || _unsupportedIterableToArray$1(r) || _nonIterableSpread();
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2024.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * Gets the logging prefix for a logger.
+   *
+   * @param {Logger} logger
+   *     The logger object.
+   * @param {string} level
+   *     The logging level.
+   * @return {string}
+   *     The logging prefix.
+   * @author Haixing Hu
+   * @private
+   */
+  function getLoggingPrefix(logger, level) {
+    var prefix = "[".concat(level, "] ");
+    if (logger._name) {
+      prefix += "".concat(logger._name, " - ");
+    }
+    return prefix;
+  }
+
+  function fixFirstArgument(prefix, args) {
+    if (args.length === 0) {
+      return [prefix];
+    } else if (isString(args[0])) {
+      args[0] = prefix + args[0];
+      return args;
+    } else {
+      return [prefix].concat(_toConsumableArray(args));
+    }
+  }
+
+  /**
+   * Binds a logging method of a logger with an array function.
+   *
+   * We use the simple arrow function to preserve the actual source code location
+   * where the logging method is called.
+   *
+   * This works for the Safari browser.
+   *
+   * @param {Logger} logger
+   *     The logger object whose method to be bound.
+   * @param {string} method
+   *     The name of the logging method to be bound.
+   * @param {string} level
+   *     The logging level of the method.
+   * @param {object} appender
+   *     The appender object which provides underlying logging operation.
+   * @author Haixing Hu
+   * @private
+   */
+  function bindWithArrowFunction(logger, method, level, appender) {
+    // Add a prefix to the message, which contains the logging level
+    // and the name of the logger. Since the prefix use the recursive
+    // string substitution pattern '%s', only some browsers support it.
+    var prefix = getLoggingPrefix(logger, level);
+    // For Safari, the recursive string substitution pattern '%s' is not
+    // supported. So we add the prefix to the first argument of the message
+    // manually. We use the arrow function to preserve the actual source
+    // code location where the logging method is called.
+    logger[method] = function () {
+      for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+        args[_key] = arguments[_key];
+      }
+      return appender[method].apply(appender, _toConsumableArray(fixFirstArgument(prefix, args)));
+    };
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2024.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * Binds a logging method of a logger with the stack of an `Error` object
+   * with logging prefix.
+   *
+   * We use the `Function.prototype.bind` to preserve the actual source code
+   * location where the logging method is called.
+   *
+   * See: https://stackoverflow.com/questions/13815640/a-proper-wrapper-for-console-log-with-correct-line-number
+   *
+   * Some browsers do not support the recursive string substitution pattern '%s'
+   * in the `console` object. For those browsers, we have no way to add a prefix
+   * to the logging message.
+   *
+   * @param {Logger} logger
+   *     The logger object whose method to be bound.
+   * @param {string} method
+   *     The name of the logging method to be bound.
+   * @param {string} level
+   *     The logging level of the method.
+   * @param {object} appender
+   *     The appender object which provides underlying logging operation.
+   * @author Haixing Hu
+   * @private
+   */
+  function bindWithoutPrefix(logger, method, level, appender) {
+    logger[method] = Function.prototype.bind.call(appender[method], appender);
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2024.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * Binds a logging method of a logger with the stack of an `Error` object.
+   *
+   * We use the `Function.prototype.bind` to preserve the actual source code
+   * location where the logging method is called.
+   *
+   * See: https://stackoverflow.com/questions/13815640/a-proper-wrapper-for-console-log-with-correct-line-number
+   *
+   * @param {Logger} logger
+   *     The logger object whose method to be bound.
+   * @param {string} method
+   *     The name of the logging method to be bound.
+   * @param {string} level
+   *     The logging level of the method.
+   * @param {object} appender
+   *     The appender object which provides underlying logging operation.
+   * @author Haixing Hu
+   * @private
+   */
+  function bindWithFunctionBind(logger, method, level, appender) {
+    // Add a prefix to the message, which contains the logging level
+    // and the name of the logger. Since the prefix use the recursive
+    // string substitution pattern '%s', only some browsers support it.
+    var prefix = getLoggingPrefix(logger, level);
+    // Note that we add a string substitution pattern '%s' to the end of
+    // the prefix, since according to the specification of the `console`,
+    // the string substitution is taken on the first argument **recursively**.
+    // See: https://stackoverflow.com/questions/75160241/what-order-does-console-log-with-multiple-arguments-and-multiple-s-substitu#answer-75167070
+    //      https://console.spec.whatwg.org/#logger
+    //      https://console.spec.whatwg.org/#formatter
+    //
+    // But the `console` object of the Node.js does not support the recursive
+    // string substitution.
+    // See: https://nodejs.org/api/console.html#console_console_log_data_args
+    //  and https://nodejs.org/api/util.html#utilformatformat-args
+    logger[method] = Function.prototype.bind.call(appender[method], appender, "".concat(prefix, "%s"));
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2023.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+
+  /**
+   * A no-operation function.
+   *
+   * @author Haixing Hu
+   * @private
+   */
+  var NOOP = function NOOP() {};
+
+  /**
+   * Rebinds all logging implementation methods to the corresponding logging
+   * methods of the appender.
+   *
+   * @param {Logger} logger
+   *     The logger whose logging methods will be rebind to the corresponding
+   *     logging methods of the appender.
+   * @param {string} level
+   *     The target logging level. All logging methods belows this target logging
+   *     level will be bind to a no-op function, while all logging methods above
+   *     or equal to this target logging level will be bind to the corresponding
+   *     logging methods of the appender. This argument should be a valid
+   *     logging level. The function do not check the validity of this argument.
+   * @param {object} appender
+   *     The appender whose logging methods will be bound to the corresponding
+   *     logging methods of this logger. This argument should be a valid appender.
+   *     The function do not check the validity of this argument.
+   * @author Haixing Hu
+   * @private
+   */
+  function bindLoggingMethods(logger, level, appender) {
+    var target = LOGGING_LEVELS[level];
+    for (var _level in LOGGING_LEVELS) {
+      // NOTE: do NOT use Object.hasOwn() because it has a lot of compatibility problems
+      if (Object.prototype.hasOwnProperty.call(LOGGING_LEVELS, _level) && _level !== 'NONE') {
+        var m = _level.toLowerCase();
+        if (LOGGING_LEVELS[_level] < target) {
+          // binds the private logging method of this object to no-op
+          logger[m] = NOOP;
+        } else {
+          // binds the private logging method of this object to the
+          // corresponding logging method of this.appender.
+          var engine = getBrowserEngine();
+          switch (engine) {
+            case 'Blink':
+              // Chrome, Edge and other Blink-based browsers
+              bindWithFunctionBind(logger, m, _level, appender);
+              break;
+            case 'WebKit':
+              // Safari and other WebKit-based browsers
+              bindWithArrowFunction(logger, m, _level, appender);
+              break;
+            case 'Gecko': // Firefox and other Gecko-based browsers
+            case 'Trident': // Internet Explorer and other Trident-based browsers
+            case 'Presto': // Opera and other Presto-based browsers
+            default:
+              bindWithoutPrefix(logger, m, _level, appender);
+              // bindWithErrorStack(logger, m, level, appender);
+              // bindWithProxy(logger, m, level, appender);
+              break;
+          }
+        }
+      }
+    }
+  }
+
+  function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t["return"] || t["return"](); } finally { if (u) throw o; } } }; }
+  function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+  function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+
+  /**
+   * The factory value of the Logger class's default logging level,
+   * which is `DEBUG`.
+   *
+   * @type {string}
+   */
+  var FACTORY_DEFAULT_LEVEL = 'DEBUG';
+
+  /**
+   * The factory value of the Logger class's default log appender, which is
+   * the standard output pipe of the console.
+   *
+   * @type {Console}
+   */
+  var FACTORY_DEFAULT_APPENDER = console;
+
+  /**
+   * The default logging level of all `Logger` instances, which is `DEBUG`.
+   *
+   * @private
+   * @author Haixing Hu
+   */
+  var __defaultLevel = FACTORY_DEFAULT_LEVEL;
+
+  /**
+   * The default log appender of all `Logger` instances, which is the standard
+   * output pipe of the console.
+   *
+   * @private
+   * @author Haixing Hu
+   */
+  var __defaultAppender = FACTORY_DEFAULT_APPENDER;
+
+  /**
+   * The map of all `Logger` instances.
+   *
+   * This value maps the name of a `Logger` instance to its instance.
+   *
+   * @type {Map<String, Logger>}
+   * @private
+   * @author Haixing Hu
+   */
+  var __loggerMap = new Map();
+
+  /**
+   * The map of all logging levels.
+   *
+   * This value maps the name of a `Logger` instance to its logging level.
+   *
+   * @type {Map<String, String>}
+   * @private
+   * @author Haixing Hu
+   */
+  var __levelMap = new Map();
+
+  /**
+   * Indicates whether the `Logger` instance is under internal constructing.
+   *
+   * Many other languages include the capability to mark a constructor as private,
+   * which prevents the class from being instantiated outside the class itself,
+   * such taht you can only use static factory methods that create instances, or
+   * not be able to create instances at all. JavaScript does not have a native way
+   * to do this, but it can be accomplished by using a private static flag.
+   *
+   * @type {boolean}
+   * @private
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields#simulating_private_constructors
+   * @author Haixing Hu
+   */
+  var __isInternalConstructing = false;
+
+  /**
+   * A simple logging class.
+   *
+   * A `Logger` object provides the following logging methods:
+   *
+   * - `Logger.trace(message, arg1, arg2, ...)`: Outputs a log message with the `TRACE` level.
+   * - `Logger.debug(message, arg1, arg2, ...)`: Outputs a log message with the `DEBUG` level.
+   * - `Logger.info(message, arg1, arg2, ...)`: Outputs a log message with the `INFO` level.
+   * - `Logger.warn(message, arg1, arg2, ...)`: Outputs a log message with the `WARN` level.
+   * - `Logger.error(message, arg1, arg2, ...)`: Outputs a log message with the `ERROR` level.
+   * - `Logger.log(level, message, arg1, arg2, ...)`: Outputs a log message with the specified level.
+   *
+   * The message argument of those logging methods supports the following
+   * substitution patterns:
+   *
+   * - `%o` or `%O`: Outputs a JavaScript object. Clicking the object name opens
+   *    more information about it in the inspector.
+   * - `%d` or `%i`: Outputs an integer. Number formatting is supported, for
+   *   example `logger.info('Foo %.2d', 1.1)` will output the number as two
+   *   significant figures with a leading 0: `Foo 01`.
+   * - `%s`: Outputs a string.
+   * - `%f`: Outputs a floating-point value. Formatting is supported, for example
+   *   `logger.debug("Foo %.2f", 1.1)` will output the number to 2 decimal
+   *   places: `Foo 1.10`.
+   *
+   * @author Haixing Hu
+   */
+  var Logger = /*#__PURE__*/function () {
+    /**
+     * Construct a log object.
+     *
+     * **NOTE**: Do NOT call this constructor directly. Use the static method
+     * `Logger.getLogger()` instead.
+     *
+     * @param {string} name
+     *     The optional name of this logger. The default value of this argument
+     *     is an empty string.
+     * @param {object} appender
+     *     Optional, indicating the content output pipe of the log. This object
+     *     must provide `trace`, `debug`, `info`, `warn` and `error` methods.
+     *     The default value of this argument is `Logger.getDefaultAppender()`.
+     * @param {string} level
+     *     Optional, indicating the log level of this object. The default value
+     *     of this argument is `Logger.getDefaultLevel()`.
+     * @see Logger.getLogger
+     */
+    function Logger(name, appender, level) {
+      _classCallCheck(this, Logger);
+      if (!__isInternalConstructing) {
+        throw new Error('The `Logger` instance can only be constructed by the ' + 'static method `Logger.getLogger()`.');
+      }
+      if (appender === undefined) {
+        appender = __defaultAppender;
+      } else {
+        checkAppender(appender);
+      }
+      if (level === undefined) {
+        var _levelMap$get;
+        level = (_levelMap$get = __levelMap.get(name)) !== null && _levelMap$get !== void 0 ? _levelMap$get : __defaultLevel;
+      } else {
+        level = upperCaseString(level);
+        checkLoggingLevel(level);
+      }
+      this._name = name;
+      this._level = level;
+      this._appender = appender;
+      bindLoggingMethods(this, level, appender);
+      __levelMap.set(name, level);
+    }
+
+    /**
+     * Get the name of this logger.
+     *
+     * @returns {string}
+     *     The name of this logger.
+     */
+    return _createClass(Logger, [{
+      key: "getName",
+      value: function getName() {
+        return this._name;
+      }
+
+      /**
+       * Get the appender of this logger.
+       *
+       * @return {object}
+       *     The appender of this logger.
+       */
+    }, {
+      key: "getAppender",
+      value: function getAppender() {
+        return this._appender;
+      }
+
+      /**
+       * Set up a new Appender.
+       *
+       * @param {object} appender
+       *     The new Appender serves as the content output pipeline of the log.
+       *     This object must provide `trace`, `debug`, `info`, `warn` and `error`
+       *     methods.
+       */
+    }, {
+      key: "setAppender",
+      value: function setAppender(appender) {
+        checkAppender(appender);
+        bindLoggingMethods(this, this._level, appender);
+        this._appender = appender;
+      }
+
+      /**
+       * Get the logging level of this logger.
+       *
+       * @return {string}
+       *     The logging level of this logger. Possible return values are `TRACE`,
+       *     `DEBUG`, `INFO`, `WARN`, `ERROR`, and `NONE`.
+       */
+    }, {
+      key: "getLevel",
+      value: function getLevel() {
+        return this._level;
+      }
+
+      /**
+       * Set the logging level of this logger.
+       *
+       * @param {string} level
+       *     The new logging level. The allowed levels are `TRACE`, `DEBUG`, `INFO`,
+       *     `WARN`, `ERROR`, and `NONE`. Lowercase letters are also allowed.
+       */
+    }, {
+      key: "setLevel",
+      value: function setLevel(level) {
+        level = upperCaseString(level);
+        checkLoggingLevel(level);
+        bindLoggingMethods(this, level, this._appender);
+        this._level = level;
+      }
+
+      /**
+       * Disable this logging object.
+       */
+    }, {
+      key: "disable",
+      value: function disable() {
+        bindLoggingMethods(this, 'NONE', this._appender);
+      }
+
+      /**
+       * Enable this logging object.
+       */
+    }, {
+      key: "enable",
+      value: function enable() {
+        bindLoggingMethods(this, this._level, this._appender);
+      }
+
+      /**
+       * Enable or disable this log object.
+       *
+       * @param {boolean} enabled
+       *    Whether to enable this log object.
+       */
+    }, {
+      key: "setEnabled",
+      value: function setEnabled(enabled) {
+        if (enabled) {
+          this.enable();
+        } else {
+          this.disable();
+        }
+      }
+
+      /**
+       * Logs a message in the specified logging level.
+       *
+       * @param {string} level
+       *     the logging level.
+       * @param {string} message
+       *     the message or message template, which may contain zero or more
+       *     substitution patterns, e.g., '%o', '%s', '%d', '%f', ..., etc.
+       * @param {array} args
+       *     the array of arguments used to format the message.
+       */
+    }, {
+      key: "log",
+      value: function log(level, message) {
+        var levelName = upperCaseString(level);
+        if (LOGGING_LEVELS[levelName] !== undefined && LOGGING_LEVELS[levelName] >= LOGGING_LEVELS[this._level]) {
+          var method = levelName.toLowerCase();
+          for (var _len = arguments.length, args = new Array(_len > 2 ? _len - 2 : 0), _key = 2; _key < _len; _key++) {
+            args[_key - 2] = arguments[_key];
+          }
+          this[method].apply(this, [message].concat(args));
+        }
+      }
+
+      /**
+       * Logs a message in the `TRACE` level.
+       *
+       * @param {string} message
+       *     the message or message template, which may contain zero or more
+       *     substitution patterns, e.g., '%o', '%s', '%d', '%f', ..., etc.
+       * @param {array} args
+       *     the array of arguments used to format the message.
+       * @private
+       */
+      // eslint-disable-next-line no-unused-vars
+    }, {
+      key: "trace",
+      value: function trace(message) {}
+
+      /**
+       * Logs a message in the `DEBUG` level.
+       *
+       * @param {string} message
+       *     the message or message template, which may contain zero or more
+       *     substitution patterns, e.g., '%o', '%s', '%d', '%f', ..., etc.
+       * @param {array} args
+       *     the array of arguments used to format the message.
+       * @private
+       */
+      // eslint-disable-next-line no-unused-vars
+    }, {
+      key: "debug",
+      value: function debug(message) {}
+
+      /**
+       * Logs a message in the `INFO` level.
+       *
+       * @param {string} message
+       *     the message or message template, which may contain zero or more
+       *     substitution patterns, e.g., '%o', '%s', '%d', '%f', ..., etc.
+       * @param {array} args
+       *     the array of arguments used to format the message.
+       * @private
+       */
+      // eslint-disable-next-line no-unused-vars
+    }, {
+      key: "info",
+      value: function info(message) {}
+
+      /**
+       * Logs a message in the `WARN` level.
+       *
+       * @param {string} message
+       *     the message or message template, which may contain zero or more
+       *     substitution patterns, e.g., '%o', '%s', '%d', '%f', ..., etc.
+       * @param {array} args
+       *     the array of arguments used to format the message.
+       * @private
+       */
+      // eslint-disable-next-line no-unused-vars
+    }, {
+      key: "warn",
+      value: function warn(message) {}
+
+      /**
+       * Logs a message in the `ERROR` level.
+       *
+       * @param {string} message
+       *     the message or message template, which may contain zero or more
+       *     substitution patterns, e.g., '%o', '%s', '%d', '%f', ..., etc.
+       * @param {array} args
+       *     the array of arguments used to format the message.
+       * @private
+       */
+      // eslint-disable-next-line no-unused-vars
+    }, {
+      key: "error",
+      value: function error(message) {}
+    }], [{
+      key: "getLogger",
+      value:
+      /**
+       * Gets the `Logger` instance of the specified name, or constructs a new
+       * `Logger` instance if it does not exist.
+       *
+       * @param {string} name
+       *     The name of the `Logger` instance to be retrieved.
+       * @param {Object} options
+       *     The optional options of the `Logger` instance to be retrieved. This
+       *     option object may have the following properties:
+       *     - `appender: object`: the specified content output pipe of the log.
+       *       This object must provide `trace`, `debug`, `info`, `warn` and `error`
+       *       methods. If this option is not provided, the appender of the existing
+       *       `Logger` instance will not be changed, and the default appender
+       *       will be used to construct a new `Logger` instance if it does not exist.
+       *     - `level: string`: the logging level of the `Logger` instance to be
+       *       retrieved. The allowed levels are `TRACE`, `DEBUG`, `INFO`, `WARN`,
+       *       `ERROR`, and `NONE`. Lowercase letters are also allowed. If this
+       *       option is not provided, the logging level of the existing `Logger`
+       *       instance will not be changed, and the default logging level will be
+       *       used to construct a new `Logger` instance if it does not exist.
+       * @return {Logger}
+       *       The `Logger` instance of the specified name, which either be the
+       *       existing one or a newly constructed one.
+       */
+      function getLogger() {
+        var name = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '';
+        var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+        if (!isString(name)) {
+          throw new TypeError('The name of a logger must be a string, and empty string is allowed.');
+        }
+        var theName = String(name); // make sure the name is a primitive string
+        var logger = __loggerMap.get(theName);
+        if (logger === undefined) {
+          // sets the internally constructing flag before constructing a instance
+          __isInternalConstructing = true;
+          logger = new Logger(theName, options.appender, options.level);
+          // clear the internally constructing flag after constructing the new instance
+          __isInternalConstructing = false;
+          __loggerMap.set(theName, logger);
+        } else {
+          if (options.appender !== undefined) {
+            logger.setAppender(options.appender);
+          }
+          if (options.level !== undefined) {
+            logger.setLevel(options.level);
+          }
+        }
+        return logger;
+      }
+
+      /**
+       * Clears all existing `Logger` instances.
+       */
+    }, {
+      key: "clearAllLoggers",
+      value: function clearAllLoggers() {
+        __loggerMap.clear();
+        __levelMap.clear();
+      }
+
+      /**
+       * Gets the logging level of the `Logger` instance of the specified name.
+       *
+       * @param name
+       *     The name of the `Logger` instance.
+       * @returns {string}
+       *     The logging level of the `Logger` instance of the specified name. If the
+       *     `Logger` instance of the specified name does not exist, the default
+       *     logging level will be returned.
+       */
+    }, {
+      key: "getLoggerLevel",
+      value: function getLoggerLevel(name) {
+        var level = __levelMap.get(name);
+        return level !== null && level !== void 0 ? level : __defaultLevel;
+      }
+
+      /**
+       * Sets the logging level of the `Logger` instance of the specified name.
+       *
+       * @param name
+       *     The name of the `Logger` instance.
+       * @param level
+       *     The new logging level of the `Logger` instance of the specified name.
+       *     The allowed levels are `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`,
+       *     and `NONE`. Lowercase letters are also allowed.
+       */
+    }, {
+      key: "setLoggerLevel",
+      value: function setLoggerLevel(name, level) {
+        level = upperCaseString(level);
+        checkLoggingLevel(level);
+        __levelMap.set(name, level);
+        var logger = __loggerMap.get(name);
+        if (logger !== undefined) {
+          logger.setLevel(level);
+        }
+      }
+
+      /**
+       * Gets the default logging level.
+       *
+       * The default logging level is used to construct a new `Logger` instance if
+       * the logging level of the new instance is not specified.
+       *
+       * @return {string}
+       *     The global default logging level.
+       * @see Logger.setDefaultLevel
+       * @see Logger.setAllLevels
+       * @see Logger.resetAllLevels
+       */
+    }, {
+      key: "getDefaultLevel",
+      value: function getDefaultLevel() {
+        return __defaultLevel;
+      }
+
+      /**
+       * Sets the default logging level.
+       *
+       * The default logging level is used to construct a new `Logger` instance if
+       * the logging level of the new instance is not specified.
+       *
+       * @param {string} level
+       *     The new default logging level. The allowed levels are `TRACE`, `DEBUG`,
+       *     `INFO`, `WARN`, `ERROR`, and `NONE`. Lowercase letters are also allowed.
+       * @see Logger.getDefaultLevel
+       * @see Logger.setAllLevels
+       * @see Logger.resetAllLevels
+       */
+    }, {
+      key: "setDefaultLevel",
+      value: function setDefaultLevel(level) {
+        level = upperCaseString(level);
+        checkLoggingLevel(level);
+        __defaultLevel = level;
+      }
+
+      /**
+       * Resets the default logging level to the factory value.
+       *
+       * The default logging level is used to construct a new `Logger` instance if
+       * the logging level of the new instance is not specified.
+       */
+    }, {
+      key: "resetDefaultLevel",
+      value: function resetDefaultLevel() {
+        __defaultLevel = FACTORY_DEFAULT_LEVEL;
+      }
+
+      /**
+       * Sets the logging level of all existing `Logger` instants.
+       *
+       * @param {string} level
+       *    The new logging level of all existing `Logger` instants. The allowed
+       *    levels are `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, and `NONE`.
+       *    Lowercase letters are also allowed.
+       * @see Logger.getDefaultLevel
+       * @see Logger.setDefaultLevel
+       * @see Logger.resetAllLevels
+       */
+    }, {
+      key: "setAllLevels",
+      value: function setAllLevels(level) {
+        level = upperCaseString(level);
+        checkLoggingLevel(level);
+        var _iterator = _createForOfIteratorHelper(__loggerMap.values()),
+          _step;
+        try {
+          for (_iterator.s(); !(_step = _iterator.n()).done;) {
+            var logger = _step.value;
+            logger.setLevel(level);
+          }
+        } catch (err) {
+          _iterator.e(err);
+        } finally {
+          _iterator.f();
+        }
+      }
+
+      /**
+       * Sets the logging level of all `Logger` instants to the default logging level.
+       *
+       * @see Logger.getDefaultLevel
+       * @see Logger.setDefaultLevel
+       * @see Logger.setAllLevels
+       */
+    }, {
+      key: "resetAllLevels",
+      value: function resetAllLevels() {
+        Logger.setAllLevels(__defaultLevel);
+      }
+
+      /**
+       * Gets the default logging appender.
+       *
+       * The default logging appender is used to construct a new `Logger` instance
+       * if the logging appender of the new instance is not specified.
+       *
+       * @return {Object}
+       *     The default logging appender.
+       * @see Logger.setDefaultAppender
+       * @see Logger.setAllAppenders
+       * @see Logger.resetAllAppenders
+       */
+    }, {
+      key: "getDefaultAppender",
+      value: function getDefaultAppender() {
+        return __defaultAppender;
+      }
+
+      /**
+       * Sets the default logging appender.
+       *
+       * The default logging appender is used to construct a new `Logger` instance
+       * if the logging appender of the new instance is not specified.
+       *
+       * @param {object} appender
+       *     The new default logging appender.
+       * @see Logger.getDefaultAppender
+       * @see Logger.setAllAppenders
+       * @see Logger.resetAllAppenders
+       */
+    }, {
+      key: "setDefaultAppender",
+      value: function setDefaultAppender(appender) {
+        checkAppender(appender);
+        __defaultAppender = appender;
+      }
+
+      /**
+       * Resets the default logging appender to the factory value.
+       *
+       * The default logging appender is used to construct a new `Logger` instance
+       * if the logging appender of the new instance is not specified.
+       *
+       * @see Logger.getDefaultAppender
+       */
+    }, {
+      key: "resetDefaultAppender",
+      value: function resetDefaultAppender() {
+        __defaultAppender = FACTORY_DEFAULT_APPENDER;
+      }
+
+      /**
+       * Sets the appender of all `Logger` instants.
+       *
+       * @param {object} appender
+       *     The new appender to be set, indicating the content output pipe of the
+       *     log. This object must provide `trace`, `debug`, `info`, `warn` and
+       *     `error` methods.
+       * @see Logger.getDefaultAppender
+       * @see Logger.setDefaultAppender
+       * @see Logger.resetAllAppenders
+       */
+    }, {
+      key: "setAllAppenders",
+      value: function setAllAppenders(appender) {
+        checkAppender(appender);
+        var _iterator2 = _createForOfIteratorHelper(__loggerMap.values()),
+          _step2;
+        try {
+          for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+            var logger = _step2.value;
+            logger.setAppender(appender);
+          }
+        } catch (err) {
+          _iterator2.e(err);
+        } finally {
+          _iterator2.f();
+        }
+      }
+
+      /**
+       * Sets the appender of all `Logger` instants to the default appender.
+       *
+       * @see Logger.getDefaultAppender
+       * @see Logger.setDefaultAppender
+       * @see Logger.setAllAppenders
+       */
+    }, {
+      key: "resetAllAppenders",
+      value: function resetAllAppenders() {
+        Logger.setAllAppenders(__defaultAppender);
+      }
+
+      /**
+       * Resets all configurations of the `Logger` class to the factory values.
+       *
+       * This method is equivalent to calling the following methods in sequence:
+       * - `Logger.clearAllLoggers()`
+       * - `Logger.resetDefaultLevel()`
+       * - `Logger.resetDefaultAppender()`
+       */
+    }, {
+      key: "reset",
+      value: function reset() {
+        Logger.clearAllLoggers();
+        Logger.resetDefaultLevel();
+        Logger.resetDefaultAppender();
+      }
+    }]);
+  }();
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2023.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+  var VUE3_CLASS_COMPONENT_DECORATORS_KEY = '__vue3_class_component_decorators__';
+
+  /**
+   * The names of special functions of Vue components.
+   *
+   * @type {string[]}
+   * @private
+   * @author Haixing Hu
+   */
+  var VUE_FUNCTIONS = [
+  // The names of lifecycle hooks of Vue components.
+  'beforeCreate', 'created', 'beforeMount', 'mounted', 'beforeUpdate', 'updated', 'beforeUnmount', 'unmounted', 'errorCaptured', 'renderTracked',
+  // Dev only
+  'renderTriggered',
+  // Dev only
+  'activated', 'deactivated', 'serverPrefetch',
+  // SSR only
+  // The names of special functions in the options API Vue components.
+  'render'];
+
+  /**
+   * Print tracing logs for class methods.
+   *
+   * @param {string} className
+   *     The name of the class the decorated method belongs to.
+   * @param {string} methodName
+   *     The name of the decorated method..
+   * @param {array} args
+   *     The calling arguments of the decorated method.
+   * @author Haixing Hu
+   * @private
+   */
+  function printMethodLog(className, methodName, args) {
+    var logger = Logger.getLogger(className);
+    if (args.length === 0) {
+      logger.trace('%s.%s.', className, methodName);
+    } else {
+      logger.trace.apply(logger, ['%s.%s:', className, methodName].concat(_toConsumableArray(args)));
+    }
+  }
+
+  /**
+   * A decorator function that meets the requirements of the `createDecorator()`
+   * function of `vue-class-component`.
+   *
+   * @param {Object} options
+   *     Options object used to create Vue components.
+   * @param {String} key
+   *     The name of the property or method to which this decorator applies.
+   * @param {Function} originalMethod
+   *     The original method to be called.
+   * @author Haixing Hu
+   * @private
+   */
+  function vueLogDecorator(options, key, originalMethod) {
+    // If the method decorated by the decorator is a Vue's life cycle hook function,
+    // Then `col` is `options`; otherwise `col` is `options.methods`
+    var col = VUE_FUNCTIONS.includes(key) ? options : options.methods;
+    col[key] = function logWrapperMethod() {
+      for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+        args[_key] = arguments[_key];
+      }
+      printMethodLog(options.name, key, args);
+      return originalMethod.apply(this, args);
+    };
+  }
+
+  /**
+   * Defines a class method decorator that modifies the target method and prints
+   * its calling signature in the log, including class name, method name and
+   * parameters.
+   *
+   * Note that only non-constructor class method can be decorated by this decorator.
+   * The global function and class constructor CANNOT be decorated by this decorator.
+   *
+   * Usage example:
+   * ```js
+   * import { Log } from '@haixing_hu/logging';
+   *
+   * class Person {
+   *   &#064;Log
+   *   eat(meal) {
+   *     ...
+   *   }
+   * }
+   *
+   * const person = new Person();
+   * const meal = new Meal();
+   * person.eat(meal);   // 日志中将会打印此方法调用的签名
+   * ```
+   *
+   * @param {function} target
+   *     The method being decorated.
+   * @param {object} context
+   *     the context object containing information about the method to be decorated.
+   * @return {function}
+   *     The decorated method.
+   * @author Haixing Hu
+   */
+  function Log(target, context) {
+    var _metadata$VUE3_CLASS_;
+    if (context === null || _typeof(context) !== 'object') {
+      throw new TypeError('The context of `@Log` decorator must be an object.');
+    }
+    if (typeof target !== 'function' || context.kind !== 'method') {
+      throw new TypeError('The `@Log` can only decorate a class method.');
+    }
+    // decorate the class-style Vue component
+    // see the `createDecorator()` function in `@haixing_hu/vue3-class-component`
+    var metadata = context.metadata;
+    (_metadata$VUE3_CLASS_ = metadata[VUE3_CLASS_COMPONENT_DECORATORS_KEY]) !== null && _metadata$VUE3_CLASS_ !== void 0 ? _metadata$VUE3_CLASS_ : metadata[VUE3_CLASS_COMPONENT_DECORATORS_KEY] = [];
+    metadata[VUE3_CLASS_COMPONENT_DECORATORS_KEY].push(function (Class, instance, options) {
+      return vueLogDecorator(options, context.name, target);
+    });
+    // decorate the original method
+    function decoratedMethod() {
+      var prototype = Object.getPrototypeOf(this);
+      var Class = prototype.constructor;
+      var className = Class.name;
+      for (var _len2 = arguments.length, args = new Array(_len2), _key2 = 0; _key2 < _len2; _key2++) {
+        args[_key2] = arguments[_key2];
+      }
+      printMethodLog(className, context.name, args);
+      return target.apply(this, args);
+    }
+    return decoratedMethod;
+  }
+
+  /**
+   * A decorator to add a named logger to a class.
+   *
+   * This decorator will add a named logger to the class, which can be accessed
+   * via the `logger` property of the class.
+   *
+   * Example usage:
+   * ```js
+   * import { HasLogger } from '@haixing_hu/logging';
+   *
+   * &#064;HasLogger
+   * class MyClass {
+   *    foo() {
+   *      this.logger.debug('This is MyClass.foo()');
+   *    }
+   * }
+   * ```
+   *
+   * The following is another example usage with the class component of Vue.js:
+   * ```js
+   * import { Component, toVue } from '@haixing_hu/vue3-class-component';
+   * import { HasLogger, Log } from '@haixing_hu/logging';
+   *
+   * &#064;Component({
+   *   template: '<p &#064;click="foo">{{ message }}</p>',
+   * })
+   * &#064;HasLogger
+   * class MyComponent {
+   *    &#064;Log
+   *    foo() {
+   *      this.logger.debug('This is MyComponent.foo()');
+   *    }
+   * }
+   *
+   * export default toVue(MyComponent);
+   * ```
+   *
+   * **NOTE**: the order of the decorators is IMPORTANT. The `@HasLogger` decorator
+   * must be placed **AFTER** the `@Component` decorator.
+   *
+   * @param {function} Class
+   *     the target class to be decorated.
+   * @param {object} context
+   *     the context object containing information about the class to be decorated.
+   * @return {function}
+   *     the new constructor of the decorated class.
+   * @author Haixing Hu
+   */
+  function HasLogger(Class, context) {
+    if (context === null || _typeof(context) !== 'object') {
+      throw new TypeError('The context must be an object.');
+    }
+    if (typeof Class !== 'function' || context.kind !== 'class') {
+      throw new TypeError('The `@HasLogger` can only decorate a class.');
+    }
+    if (Class.prototype.logger) {
+      throw new Error('The @HasLogger decorator can only be used once on a class.');
+    }
+    var instance = new Class();
+    if (instance.logger !== undefined) {
+      throw new Error('The @HasLogger cannot be decorated on the class with a `logger` field.');
+    }
+    // add the logger to the class prototype
+    Class.prototype.logger = Logger.getLogger(context.name);
+    return Class;
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  //
+  //    Copyright (c) 2022 - 2023.
+  //    Haixing Hu, Qubit Co. Ltd.
+  //
+  //    All rights reserved.
+  //
+  ////////////////////////////////////////////////////////////////////////////////
+
+  exports.HasLogger = HasLogger;
+  exports.Log = Log;
+  exports.Logger = Logger;
+  exports.default = Logger;
+
+  Object.defineProperty(exports, '__esModule', { value: true });
+
+  return exports;
+
+})({});
+//# sourceMappingURL=logging.iife.js.map