mm_logger 0.0.0-stage → 1.0.0

package/.gitattributes

@@ -0,0 +1,5 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+*.js linguist-language=JavaScript
+*.css linguist-language=JavaScript
+*.html linguist-language=JavaScript

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024, 邱文武
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,326 @@
-# Temporary Holding Version
+# mm_logger
+
+高性能 Node.js 日志模块，支持多级别日志、文件轮转、事件钩子和灵活配置。
+
+## 特性
+
+- 📝 **多级别日志**: debug, info, success, warn, error, fatal
+- 💾 **文件轮转**: 按大小自动分割日志文件
+- 🎨 **双格式输出**: 支持 JSON 和文本格式
+- 🖥️ **双路输出**: 同时输出到控制台和文件
+- 🌐 **HTTP 日志**: 单独记录 HTTP 请求日志
+- 🔍 **日志查询**: 支持按日期、时间、关键词查询
+- 🎯 **事件钩子**: 支持日志记录前后的事件监听
+- ⚡ **异步处理**: 非阻塞日志写入，提高应用性能
+- 🧹 **自动清理**: 自动管理日志文件数量
+- 🌈 **ANSI 着色工具**: 内置 `colors`，按终端能力自动启用 / 禁用颜色
+- 🧩 **轻量日志器**: `ConsoleLogger` 提供零依赖的彩色控制台输出
+
+## 安装
+
+```bash
+npm install mm_logger
+```
+
+## 快速开始
+
+```javascript
+const { Logger } = require('mm_logger');
+
+// 创建日志实例
+const logger = new Logger({
+    level: 'debug',
+    dir: './logs',
+    console: true,
+    file: true
+});
+
+// 记录日志
+logger.debug('调试信息');
+logger.info('普通信息');
+logger.success('成功信息');
+logger.warn('警告信息');
+logger.error('错误信息');
+logger.fatal('致命错误');
+
+// 记录带参数的日志
+logger.info('用户登录', { username: 'admin', ip: '127.0.0.1' });
+
+// 记录 HTTP 日志
+logger.http('info', 'API 请求', { method: 'GET', url: '/api/users' });
+```
+
+## 示例代码
+
+仓库提供可直接运行的示例，位于 `examples/` 目录：
+
+- `examples/basic.js`：基础用法，演示各级别日志、带参数日志和动态更新配置
+- `examples/http.js`：HTTP 请求日志的记录与查询
+- `examples/query.js`：日志查询、读取、清空与删除
+
+```bash
+node examples/basic.js
+node examples/http.js
+node examples/query.js
+```
+
+## 配置选项
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|-------|------|-------|------|
+| `level` | string | `'debug'` | 日志级别 |
+| `dir` | string | `'./log'` | 日志文件目录 |
+| `console` | boolean | `true` | 是否输出到控制台 |
+| `file` | boolean | `true` | 是否输出到文件 |
+| `max_size` | number | `3145728` (3MB) | 单个日志文件最大大小（字节） |
+| `max_files` | number | `7` | 保留的日志文件最大数量 |
+| `date_pattern` | string | `'_yyyy-MM-dd'` | 日期格式 |
+| `content_pattern` | string | `'%d{hh:mm:ss.SSS} [%p] - %m'` | 日志内容格式 |
+| `file_name_pattern` | string | `'{type}_{date}_{index}'` | 文件名格式 |
+| `is_json` | boolean | `false` | 是否使用 JSON 格式输出 |
+
+## 日志级别
+
+日志级别从低到高排序：
+
+- `debug`: 调试信息，开发环境使用
+- `info`: 普通信息，记录程序运行状态
+- `success`: 成功信息，记录操作成功
+- `warn`: 警告信息，需要关注但不影响运行
+- `error`: 错误信息，功能异常但程序仍可运行
+- `fatal`: 致命错误，程序无法继续运行
+
+## 高级用法
+
+### 批量记录日志
+
+```javascript
+logger.batch([
+    { level: 'info', message: '用户登录', args: [{ username: 'admin' }] },
+    { level: 'warn', message: '密码错误', args: [{ username: 'user123' }] }
+]);
+```
+
+### 重新配置
+
+```javascript
+// 动态更新配置
+logger.reconfig({
+    level: 'info',
+    is_json: true,
+    max_size: 5 * 1024 * 1024 // 5MB
+});
+```
+
+### 日志查询
+
+```javascript
+const result = logger.find({
+    date: '2023-12-01',      // 查询日期
+    start_time: '09:00:00',  // 起始时间
+    end_time: '18:00:00',    // 结束时间
+    keyword: 'error',        // 关键词
+    page: 1,                 // 页码
+    size: 50                 // 每页大小
+});
+
+console.log(result.logs);          // 日志列表
+console.log(result.pagination);    // 分页信息
+```
+
+### 事件监听
+
+```javascript
+// 日志记录前
+logger.on('before_log', (data) => {
+    // 可以在这里处理敏感信息脱敏
+    console.log('准备记录日志:', data);
+});
+
+// 日志记录后
+logger.on('record:after', (result) => {
+    // 可以在这里进行性能监控
+    console.log('日志记录完成:', result);
+});
+
+// 日志记录错误
+logger.on('record:error', (error) => {
+    console.error('日志记录出错:', error);
+});
+
+// 查询错误
+logger.on('find:error', (error) => {
+    console.error('日志查询出错:', error);
+});
+```
+
+### 刷新与销毁
+
+```javascript
+// 刷新日志缓存到磁盘
+logger.flush().then(() => {
+    console.log('日志已刷新');
+});
+
+// 销毁日志实例
+logger.destroy().then(() => {
+    console.log('日志实例已销毁');
+});
+```
+
+## 日志文件
+
+模块自动创建三种类型的日志文件：
+
+- `debug_{date}_{index}.log`: 记录 debug、info、success 级别
+- `error_{date}_{index}.log`: 记录 warn、error、fatal 级别
+- `http_{date}_{index}.log`: 记录 HTTP 相关日志
+
+当文件大小超过 `max_size` 时，自动创建新文件（索引递增）。
+
+## 最佳实践
+
+### 1. 全局日志实例
+
+```javascript
+// logger.js
+const { Log } = require('mm_logger');
+
+const logger = new Log({
+    level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
+    dir: './logs',
+    console: true,
+    file: true,
+    is_json: process.env.NODE_ENV === 'production'
+});
+
+module.exports = logger;
+```
+
+### 2. Express 集成
+
+```javascript
+const express = require('express');
+const logger = require('./logger');
+const app = express();
+
+// HTTP 请求日志中间件
+app.use((req, res, next) => {
+    const startTime = Date.now();
+    const originalSend = res.send;
+    
+    res.send = function(body) {
+        const duration = Date.now() - startTime;
+        const logData = {
+            method: req.method,
+            url: req.url,
+            status: res.statusCode,
+            duration: duration,
+            ip: req.ip
+        };
+        
+        // 根据状态码记录不同级别
+        if (res.statusCode >= 500) {
+            logger.http('error', 'HTTP 错误', logData);
+        } else if (res.statusCode >= 400) {
+            logger.http('warn', 'HTTP 警告', logData);
+        } else {
+            logger.http('info', 'HTTP 请求', logData);
+        }
+        
+        return originalSend.call(this, body);
+    };
+    
+    next();
+});
+
+app.get('/', (req, res) => {
+    logger.debug('处理请求', { path: req.path });
+    res.send('Hello World');
+});
+
+app.listen(3000);
+```
+
+### 3. 错误处理
+
+```javascript
+// error-handler.js
+const logger = require('./logger');
+
+function handleError(err, req, res, next) {
+    logger.error('应用错误', {
+        message: err.message,
+        stack: process.env.NODE_ENV === 'production' ? '' : err.stack,
+        path: req.path,
+        method: req.method
+    });
+    
+    res.status(500).json({
+        error: process.env.NODE_ENV === 'production' ? 'Internal Server Error' : err.message
+    });
+}
+
+module.exports = handleError;
+```
+
+## 颜色工具与轻量日志器
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`colors` 与轻量日志器 `ConsoleLogger` 已自 `mm_corejs` 迁移至此模块，`mm_logger` 不再依赖 `mm_corejs`。
+
+### colors
+
+```javascript
+const { colors: lib } = require('mm_logger');
+const c = lib.colors;
+
+console.log(c.red('错误'));
+console.log(c.style('bold underline cyan')('组合样式'));
+console.log(c.rgb(255, 128, 0)('真彩色'));
+```
+
+| 导出 | 说明 |
+| --- | --- |
+| `colors` | 已按 `process.stdout` 检测好可用性的着色器实例 |
+| `createColors(enabled)` | 按指定开关创建着色器 |
+| `forStream(stream)` | 针对指定流检测并创建着色器 |
+| `supportsColor(stream)` | 判断流是否应启用颜色 |
+| `windowsSupportsVT()` | 判断 Windows 终端是否支持 ANSI/VT |
+| `STYLES` | ANSI 样式表（名称 -> `[开启码, 关闭码]`） |
+
+颜色开关遵循 `NO_COLOR`（禁用）、`FORCE_COLOR`（强制，`0` / `false` 表示禁用）、`TERM=dumb`、非 TTY 以及 CI 环境等常见约定。
+
+### ConsoleLogger
+
+轻量控制台日志器，按级别着色后输出到原生 `console`；`error` / `warn` 走 stderr，其余走 stdout，各自按对应流的 TTY 能力检测颜色。
+
+```javascript
+const { ConsoleLogger } = require('mm_logger');
+const logger = new ConsoleLogger();
+
+logger.info('普通信息');
+logger.success('成功信息');
+logger.warn('警告信息');
+logger.error('错误信息');
+```
+
+## 测试
+
+```bash
+npm run test:unit   # Jest 单元测试（含覆盖率阈值）
+```
+
+## 兼容性
+
+支持 Node.js 12.x 及以上版本。
+
+## 性能
+
+- 使用流式写入，避免阻塞主线程
+- 异步日志处理，提高应用响应速度
+- 自动轮转和清理，保持文件系统整洁
+- 优化的文件 I/O，减少磁盘操作开销
+
+## 许可证
+
+MIT License

package/eslint.config.js

@@ -0,0 +1,68 @@
+const jsdoc = require('eslint-plugin-jsdoc');
+
+module.exports = [
+  {
+    files: ['index.js','lib/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'script'
+    },
+    plugins: {
+      jsdoc: jsdoc
+    },
+    rules: {
+      // JSDoc相关规则 - 设置为error级别强制要求
+      'jsdoc/require-jsdoc': ['error', {
+        require: {
+          FunctionDeclaration: true,
+          MethodDefinition: true,
+          ClassDeclaration: true,
+          ArrowFunctionExpression: true
+        }
+      }],
+      'jsdoc/check-param-names': 'off',
+      'jsdoc/check-tag-names': 'off',
+      'jsdoc/check-types': 'off',
+      'jsdoc/require-param': 'off',
+      'jsdoc/require-param-description': 'off',
+      'jsdoc/require-returns': 'off',
+      'jsdoc/require-returns-description': 'off',
+      
+      // 基础语法规则
+      'no-unused-vars': ['error', { args: 'none', vars: 'all' }],
+      'no-console': 'warn',
+      
+      // 代码风格规则
+      'indent': ['error', 2],
+      'quotes': ['error', 'single'],
+      'semi': ['error', 'always'],
+      'comma-dangle': ['error', 'never'],
+      'no-trailing-spaces': 'error',
+      'eol-last': 'error',
+      'max-len': ['error', { code: 100 }],
+      'max-lines-per-function': ['error', { max: 40 }],
+      'complexity': ['error', 12],
+      'max-depth': ['error', 4],
+      'max-params': ['error', 4],
+      
+      // 命名规则
+      'id-length': ['error', {
+        min: 1,
+        max: 20,
+        properties: 'always'
+      }]
+    }
+  },
+  {
+    files: ['test/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'script'
+    },
+    rules: {
+      // 测试文件中允许使用console
+      'no-console': 'off',
+      'no-unused-vars': 'off'
+    }
+  }
+];

package/examples/basic.js

@@ -0,0 +1,70 @@
+/**
+ * @description 基础用法示例：创建日志实例、记录各级别日志、动态更新配置
+ * @example 运行方式：node examples/basic.js
+ */
+
+const { Logger, getLogger, LEVEL } = require('../index');
+
+/**
+ * 创建日志实例
+ * @returns {Logger} - 日志实例
+ */
+function createLogger() {
+  return new Logger({
+    level: 'debug',
+    dir: './logs',
+    console: true,
+    file: true
+  });
+}
+
+/**
+ * 记录各级别日志
+ * @param {Logger} logger - 日志实例
+ */
+function logAllLevels(logger) {
+  logger.debug('调试信息');
+  logger.info('普通信息');
+  logger.success('成功信息');
+  logger.warn('警告信息');
+  logger.error('错误信息');
+  logger.fatal('致命错误');
+}
+
+/**
+ * 记录带附加参数的日志
+ * @param {Logger} logger - 日志实例
+ */
+function logWithArgs(logger) {
+  logger.info('用户登录成功', { username: 'admin', ip: '127.0.0.1' });
+  logger.log('warn', '自定义级别日志', { code: 1001, retry: 3 });
+}
+
+/**
+ * 动态更新配置
+ * @param {Logger} logger - 日志实例
+ */
+function updateConfig(logger) {
+  logger.setConfig({
+    level: 'info',
+    console_format: '{time} [{level}] {msg}'
+  });
+  logger.info('配置已更新为 info 级别');
+}
+
+// 直接创建 Logger 实例
+const logger = createLogger();
+
+// 记录日志
+logAllLevels(logger);
+logWithArgs(logger);
+
+// 动态更新配置
+updateConfig(logger);
+
+// 查看日志级别枚举
+console.log('日志级别枚举:', LEVEL);
+
+// 使用 getLogger 获取全局单例（file: false，避免与上面的实例产生文件冲突）
+const global_logger = getLogger({ level: 'info', dir: './logs', file: false });
+global_logger.info('全局单例日志');

package/examples/http.js

@@ -0,0 +1,71 @@
+/**
+ * @description HTTP 日志示例：模拟 HTTP 请求日志的记录与查询
+ * @example 运行方式：node examples/http.js
+ */
+
+const { Logger } = require('../index');
+
+/**
+ * 创建日志实例
+ * @returns {Logger} - 日志实例
+ */
+function createLogger() {
+  return new Logger({
+    level: 'debug',
+    dir: './logs',
+    console: true,
+    file: true
+  });
+}
+
+/**
+ * 模拟处理一次 HTTP 请求
+ * @param {Logger} logger - 日志实例
+ * @param {string} method - 请求方法
+ * @param {string} url - 请求路径
+ * @param {number} status - 响应状态码
+ * @param {number} duration - 请求耗时（毫秒）
+ */
+function handleRequest(logger, method, url, status, duration) {
+  const log_data = {
+    method,
+    url,
+    status,
+    duration,
+    ip: '127.0.0.1'
+  };
+
+  if (status >= 500) {
+    logger.http('error', 'HTTP 服务器错误', log_data);
+  } else if (status >= 400) {
+    logger.http('warn', 'HTTP 客户端错误', log_data);
+  } else {
+    logger.http('info', 'HTTP 请求', log_data);
+  }
+}
+
+/**
+ * 查询 HTTP 日志
+ * @param {Logger} logger - 日志实例
+ */
+function findHttpLogs(logger) {
+  const result = logger.find({
+    keyword: 'HTTP',
+    level: 'info',
+    page_now: 1,
+    page_size: 10
+  });
+  console.log('HTTP 日志查询结果:', result);
+}
+
+const logger = createLogger();
+
+// 模拟若干 HTTP 请求
+handleRequest(logger, 'GET', '/api/users', 200, 12);
+handleRequest(logger, 'POST', '/api/users', 400, 5);
+handleRequest(logger, 'GET', '/api/orders', 500, 100);
+
+// 等待日志写入完成后查询
+setTimeout(() => {
+  findHttpLogs(logger);
+}, 500);

package/examples/query.js

@@ -0,0 +1,84 @@
+/**
+ * @description 日志查询与管理示例：find、read、clear、remove
+ * @example 运行方式：node examples/query.js
+ */
+
+const { Logger } = require('../index');
+
+/**
+ * 创建日志实例
+ * @returns {Logger} - 日志实例
+ */
+function createLogger() {
+  return new Logger({
+    level: 'debug',
+    dir: './logs',
+    console: true,
+    file: true
+  });
+}
+
+/**
+ * 写入示例日志
+ * @param {Logger} logger - 日志实例
+ */
+function writeLogs(logger) {
+  logger.info('用户创建成功', { user_id: 1 });
+  logger.info('用户更新成功', { user_id: 2 });
+  logger.warn('密码重试次数过多', { user_id: 1 });
+  logger.error('数据库连接失败', { host: '127.0.0.1' });
+}
+
+/**
+ * 按条件查询日志
+ * @param {Logger} logger - 日志实例
+ */
+function findLogs(logger) {
+  const result = logger.find({
+    keyword: '用户',
+    level: 'info',
+    page_now: 1,
+    page_size: 10
+  });
+  console.log('find 查询结果:', result);
+}
+
+/**
+ * 读取日志内容
+ * @param {Logger} logger - 日志实例
+ */
+function readLogs(logger) {
+  const logs = logger.read('debug', '用户');
+  console.log('read 读取结果:', logs);
+}
+
+/**
+ * 按关键词清空日志
+ * @param {Logger} logger - 日志实例
+ */
+function clearLogs(logger) {
+  const result = logger.clear('debug', '数据库');
+  console.log('clear 清空结果:', result);
+}
+
+/**
+ * 删除指定类型日志文件
+ * @param {Logger} logger - 日志实例
+ */
+function removeLogs(logger) {
+  const result = logger.remove('debug');
+  console.log('remove 删除结果:', result);
+}
+
+const logger = createLogger();
+
+// 写入示例日志
+writeLogs(logger);
+
+// 等待日志写入完成后执行查询与管理操作
+setTimeout(() => {
+  findLogs(logger);
+  readLogs(logger);
+  clearLogs(logger);
+  removeLogs(logger);
+}, 500);

package/index.js

@@ -0,0 +1,27 @@
+const Logger = require('./lib/logger');
+const ConsoleLogger = require('./lib/console_logger');
+const Admin = require('mm_corejs').Admin;
+
+let admin = new Admin();
+admin.setClass(Logger);
+
+module.exports = {
+  LEVEL: require('./lib/level'),
+  Logger,
+  // 轻量控制台日志器（自 mm_corejs 迁移，类名避免与 Logger 冲突）
+  ConsoleLogger,
+  // 颜色工具（自 mm_corejs 迁移），结构与 mm_corejs.colors 保持一致
+  colors: require('./lib/colors'),
+  admin,
+  // 获取日志记录器实例（<模块>Admin 范式）
+  loggerAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  },
+  // 兼容旧调用名
+  getLogger() {
+    return admin.get('os');
+  }
+};

package/jest.config.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/**
+ * Jest 测试配置
+ */
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['<rootDir>/test/**/*.test.js'],
+  collectCoverageFrom: ['lib/colors.js', 'lib/console_logger.js'],
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100
+    }
+  }
+};