@qubit-ltd/logging 1.4.4 → 1.4.6

package/README.zh_CN.md

@@ -9,6 +9,16 @@
 [@qubit-ltd/logging] 是一个 JavaScript 库，通过装饰器为类方法和属性提供强大的日志记录功能。
 该库旨在与[Vue.js 类组件]无缝集成，为处理 JavaScript 项目中的日志记录提供了优雅的解决方案。
 
+## 特性
+
+- 📝 简单灵活的日志接口，支持不同的日志级别
+- 🔍 支持带占位符的格式化日志消息
+- 🎯 自动方法日志记录和类日志集成的装饰器
+- 🔄 与Vue.js类组件无缝集成
+- 🎛️ 可配置的日志级别和输出器
+- 🌐 全局和单独的日志记录器管理
+- 📋 支持浏览器控制台和自定义输出器
+
 ## 安装
 
 使用 npm 或 yarn 安装该库：
@@ -34,6 +44,28 @@ yarn add @qubit-ltd/logging
     - `level: string`：定义日志记录级别（`TRACE`、`DEBUG`、`INFO`、`WARN`、`ERROR`、`NONE`）。不区分大小写。
       如果省略，将使用 logger 的现有日志级别，或者为新创建的 logger 分配默认日志级别。
 
+示例：
+
+```javascript
+import Logger from '@qubit-ltd/logging';
+
+// 创建一个使用默认设置的logger
+const logger1 = Logger.getLogger('MyLogger');
+
+// 创建一个自定义日志级别的logger
+const logger2 = Logger.getLogger('DebugLogger', { level: 'DEBUG' });
+
+// 创建一个带自定义输出器的logger
+const customAppender = {
+  trace: (message, ...args) => { /* 自定义trace实现 */ },
+  debug: (message, ...args) => { /* 自定义debug实现 */ },
+  info: (message, ...args) => { /* 自定义info实现 */ },
+  warn: (message, ...args) => { /* 自定义warn实现 */ },
+  error: (message, ...args) => { /* 自定义error实现 */ },
+};
+const logger3 = Logger.getLogger('CustomLogger', { appender: customAppender, level: 'INFO' });
+```
+
 ### 记录日志消息
 
 - `logger.trace(message, ...args)`：记录一个 trace 级别的消息。
@@ -70,7 +102,33 @@ logger.log(level, 'This is an %s message with argument %s and argument %o', leve
 
 使用 `logger.setLevel(level)` 调整 logger 的日志级别。
 
-可用的日志级别有：`TRACE`、`DEBUG`、`INFO`、`WARN`、`ERROR`、`NONE`（不区分大小写）。
+可用的日志级别（从最详细到最简略）：
+- `TRACE`：用于调试目的的最详细信息
+- `DEBUG`：一般调试信息
+- `INFO`：关于应用程序进度的一般信息
+- `WARN`：可能需要注意的警告情况
+- `ERROR`：需要处理的错误条件
+- `NONE`：完全禁用日志记录
+
+所有级别名称不区分大小写。
+
+示例：
+
+```javascript
+const logger = Logger.getLogger('MyClass');
+
+// 将级别更改为只显示警告和错误
+logger.setLevel('WARN');
+
+// 这些不会显示，因为它们低于WARN级别
+logger.trace('这条跟踪消息不会显示');
+logger.debug('这条调试消息不会显示');
+logger.info('这条信息消息不会显示');
+
+// 这些会显示
+logger.warn('这条警告消息会显示');
+logger.error('这条错误消息会显示');
+```
 
 ### 设置日志 Appender
 
@@ -85,7 +143,17 @@ logger.log(level, 'This is an %s message with argument %s and argument %o', leve
 
 ```javascript
 const logger = Logger.getLogger('MyClass');
-logger.setAppender(console);    // Outputs log messages to the console.
+logger.setAppender(console);    // 将日志消息输出到控制台
+
+// 或者创建一个为所有日志添加时间戳的自定义输出器
+const timestampAppender = {
+  trace: (message, ...args) => console.trace(`[${new Date().toISOString()}] ${message}`, ...args),
+  debug: (message, ...args) => console.debug(`[${new Date().toISOString()}] ${message}`, ...args),
+  info: (message, ...args) => console.info(`[${new Date().toISOString()}] ${message}`, ...args),
+  warn: (message, ...args) => console.warn(`[${new Date().toISOString()}] ${message}`, ...args),
+  error: (message, ...args) => console.error(`[${new Date().toISOString()}] ${message}`, ...args),
+};
+logger.setAppender(timestampAppender);
 ```
 
 ### 启用或禁用日志记录
@@ -94,12 +162,50 @@ logger.setAppender(console);    // Outputs log messages to the console.
 - `logger.disable()`：禁用日志记录。
 - `logger.setEnabled(enabled)`：动态控制日志记录的启用与禁用。
 
+示例：
+
+```javascript
+const logger = Logger.getLogger('MyClass');
+
+// 暂时禁用所有日志
+logger.disable();
+logger.info('此消息不会被记录');
+
+// 重新启用日志
+logger.enable();
+logger.info('此消息会被记录');
+
+// 使用条件控制日志记录
+const debugMode = process.env.NODE_ENV === 'development';
+logger.setEnabled(debugMode);
+```
+
 ### 管理日志记录器
 
 - `Logger.clearAllLoggers()`：清除所有已注册的日志记录器。
 - `Logger.getLevel(name)`：获取特定日志记录器的日志级别。
 - `Logger.setLevel(name, level)`：设置特定日志记录器的日志级别。
 
+示例：
+
+```javascript
+// 创建多个日志记录器
+const apiLogger = Logger.getLogger('API');
+const uiLogger = Logger.getLogger('UI');
+const dbLogger = Logger.getLogger('Database');
+
+// 在不访问实例的情况下更改特定日志记录器的级别
+Logger.setLevel('API', 'DEBUG');
+Logger.setLevel('Database', 'ERROR');
+
+// 获取日志记录器的当前级别
+const uiLevel = Logger.getLevel('UI');
+console.log(`UI Logger级别: ${uiLevel}`);
+
+// 关闭应用程序时清除所有日志记录器
+Logger.clearAllLoggers();
+```
+
 ### 默认级别和 Appender
 
 当创建一个新日志记录器时，如果没有指定级别或 appender，将使用默认的日志级别和 appender。
@@ -111,6 +217,23 @@ logger.setAppender(console);    // Outputs log messages to the console.
 - `Logger.setDefaultAppender(appender)`：设置默认日志 appender。
 - `Logger.resetDefaultAppender()`：将默认日志 appender 重置为出厂值。
 
+示例：
+
+```javascript
+// 获取当前默认级别
+const defaultLevel = Logger.getDefaultLevel();
+console.log(`默认日志级别: ${defaultLevel}`);
+
+// 为所有新的日志记录器更改默认级别
+Logger.setDefaultLevel('DEBUG');
+
+// 所有新的日志记录器现在默认将具有DEBUG级别
+const logger = Logger.getLogger('NewLogger'); // 将具有DEBUG级别
+
+// 重置为原始的工厂默认级别
+Logger.resetDefaultLevel();
+```
+
 ### 全局日志管理
 
 - `Logger.setAllLevels(level)`：将指定日志级别应用于所有现有日志记录器。
@@ -118,10 +241,42 @@ logger.setAppender(console);    // Outputs log messages to the console.
 - `Logger.setAllAppenders(appender)`：将指定日志 appender 应用于所有现有日志记录器。
 - `Logger.resetAllAppenders()`：将所有现有日志记录器的日志 appender 重置为默认 appender。
 
+示例：
+
+```javascript
+// 创建几个具有不同级别的日志记录器
+const logger1 = Logger.getLogger('Logger1', { level: 'TRACE' });
+const logger2 = Logger.getLogger('Logger2', { level: 'INFO' });
+const logger3 = Logger.getLogger('Logger3', { level: 'ERROR' });
+
+// 一次将所有日志记录器更改为WARN级别
+Logger.setAllLevels('WARN');
+
+// 现在所有日志记录器将只显示WARN和ERROR消息
+logger1.info('这不会显示');
+logger2.warn('这会显示');
+logger3.error('这会显示');
+
+// 将所有日志记录器重置为使用默认级别
+Logger.resetAllLevels();
+
+// 将自定义输出器应用于所有现有的日志记录器
+const fileAppender = { /* ... 记录到文件的实现 ... */ };
+Logger.setAllAppenders(fileAppender);
+```
+
 ### 重置日志记录器
 
 - `Logger.reset()`：将日志记录器重置为出厂状态。这将清除所有已注册的日志记录器、重置默认日志级别和默认日志 appender。
 
+示例：
+
+```javascript
+// 在对日志记录器和默认设置进行多次修改后
+// 这一个调用将一切重置为工厂设置
+Logger.reset();
+```
+
 ## `@Log` 装饰器
 
 `@Log` 装饰器会自动记录方法签名，包括类名、方法名和参数。
@@ -134,13 +289,25 @@ import { Log } from '@qubit-ltd/logging';
 class Person {
   @Log
   eat(meal) {
-    // method implementation
+    // 方法实现
+    return `正在吃${meal.name}`;
+  }
+  
+  // Log装饰器的自定义选项
+  @Log({ level: 'INFO', withResult: true })
+  calculateCalories(food, amount) {
+    const calories = food.caloriesPerUnit * amount;
+    return calories;
   }
 }
 
 const person = new Person();
-const meal = new Meal();
-person.eat(meal); // The log will print the method calling signature
+const meal = { name: '早餐', type: '健康' };
+person.eat(meal); 
+// 记录: "Person.eat({"name":"早餐","type":"健康"})"
+
+const calories = person.calculateCalories({ caloriesPerUnit: 50 }, 4);
+// 记录: "Person.calculateCalories({"caloriesPerUnit":50}, 4) => 200"
 ```
 
 ## `@HasLogger` 装饰器
@@ -155,9 +322,22 @@ import { HasLogger } from '@qubit-ltd/logging';
 @HasLogger
 class MyClass {
   foo() {
-    this.logger.debug('This is MyClass.foo()');
+    this.logger.debug('这是MyClass.foo()');
+  }
+  
+  bar(param) {
+    this.logger.info('使用参数处理: %o', param);
+    // 使用param做一些事情
+    if (param.value < 0) {
+      this.logger.warn('检测到负值: %d', param.value);
+    }
+    return param.value * 2;
   }
 }
+
+const instance = new MyClass();
+instance.foo();
+instance.bar({ value: -5 });
 ```
 
 ## 与 Vue.js 类组件一起使用
@@ -178,7 +358,22 @@ class MyComponent {
   
   @Log
   foo() {
-    this.logger.debug('This is MyComponent.foo()');
+    this.logger.debug('这是MyComponent.foo()');
+    this.message = '点击于 ' + new Date().toLocaleTimeString();
+  }
+  
+  @Log({ level: 'INFO' })
+  async fetchData() {
+    try {
+      this.logger.info('从API获取数据...');
+      const response = await fetch('/api/data');
+      const data = await response.json();
+      this.logger.info('接收到数据: %o', data);
+      return data;
+    } catch (error) {
+      this.logger.error('获取数据失败: %o', error);
+      throw error;
+    }
   }
 }
 
@@ -187,10 +382,76 @@ export default toVue(MyComponent);
 
 **注意**：`@HasLogger` 装饰器必须放在 `@Component` 装饰器的**后面**。
 
+## 高级用法
+
+### 创建自定义输出器
+
+你可以创建自定义输出器将日志定向到不同的目的地：
+
+```javascript
+// 文件日志输出器（Node.js示例）
+import fs from 'fs';
+
+const fileAppender = {
+  _writeToFile(level, message, ...args) {
+    const formattedArgs = args.map(arg => 
+      typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
+    );
+    const logEntry = `[${new Date().toISOString()}] [${level}] ${message} ${formattedArgs.join(' ')}\n`;
+    fs.appendFileSync('application.log', logEntry);
+  },
+  trace: function(message, ...args) { this._writeToFile('TRACE', message, ...args); },
+  debug: function(message, ...args) { this._writeToFile('DEBUG', message, ...args); },
+  info: function(message, ...args) { this._writeToFile('INFO', message, ...args); },
+  warn: function(message, ...args) { this._writeToFile('WARN', message, ...args); },
+  error: function(message, ...args) { this._writeToFile('ERROR', message, ...args); }
+};
+
+// 使用自定义输出器
+const logger = Logger.getLogger('AppLogger', { appender: fileAppender });
+```
+
+### 条件日志记录
+
+```javascript
+import Logger from '@qubit-ltd/logging';
+
+function processData(data, options = {}) {
+  const logger = Logger.getLogger('DataProcessor');
+  
+  // 仅在明确请求时启用调试日志
+  if (options.debug) {
+    logger.setLevel('DEBUG');
+  } else {
+    logger.setLevel('INFO');
+  }
+  
+  logger.debug('使用选项处理数据: %o', options);
+  // 函数的其余部分
+}
+```
+
 ## <span id="contributing">贡献</span>
 
 如果您发现任何问题或有改进建议，请随时在[GitHub 仓库]上提交 issue 或 pull request。
 
+### 开发设置
+
+```bash
+# 克隆仓库
+git clone https://github.com/Haixing-Hu/js-logging.git
+cd js-logging
+
+# 安装依赖
+yarn install
+
+# 运行测试
+yarn test
+
+# 构建库
+yarn build
+```
+
 ## <span id="license">许可证</span>
 
 [@qubit-ltd/logging] 根据 Apache 2.0 许可证分发。详情请参阅 [LICENSE](LICENSE) 文件。

package/dist/logging.cjs

@@ -35,12 +35,12 @@ function toPropertyKey(t) {
 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);
+    o.enumerable = o.enumerable || false, o.configurable = true, "value" in o && (o.writable = true), 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
+  return r && _defineProperties(e.prototype, r), t && _defineProperties(e, t), Object.defineProperty(e, "prototype", {
+    writable: false
   }), e;
 }
 
@@ -465,7 +465,7 @@ function bindLoggingMethods(logger, level, appender) {
   }
 }
 
-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 _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: true } : { done: false, 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 = true, u = false; 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 = true, 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; }