@qubit-ltd/logging 1.4.4

package/dist/logging.mjs

@@ -0,0 +1,1330 @@
+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.
+//
+////////////////////////////////////////////////////////////////////////////////
+
+export { HasLogger, Log, Logger, Logger as default };
+//# sourceMappingURL=logging.mjs.map