open-index/open-npm huggingface dataset:
npm package: @spike.hmc/h-logger
Description: Standardized logging SDK
Latest version: 1.0.0

# @spike.hmc/h-logger

标准化日志 SDK，基于 [Winston](https://github.com/winstonjs/winston) 开发。

## 特性

- 🚀 **零配置**: 开箱即用，包含合理的默认设置。
- 🎨 **美化打印**: 为开发环境提供美观、带颜色的控制台输出。
- 📂 **日志轮转**: 每日自动轮转日志文件，并支持自动清理旧文件。
- 🔄 **Pino 兼容**: 同时支持 `log.info(msg, meta)` 和 `log.info(meta, msg)` 两种调用方式。
- 🧵 **异步上下文**: 使用 `AsyncLocalStorage` 自动注入 `taskId` 等上下文元数据。
- 📊 **丰富格式化**: 内置表格、树形结构和任务进度格式化工具。
- 🛡️ **类型安全**: 完全使用 TypeScript 编写。

## 安装

```bash
npm install @spike.hmc/h-logger
```

## 快速上手

### 基础日志记录

```typescript
import { log } from '@spike.hmc/h-logger';

// 标准记录
log.info('应用已启动');
log.warn('内存占用较高', { usage: '85%' });
log.error('处理请求失败', new Error('数据库连接超时'));

// Pino 风格记录 (元数据在前)
log.info({ userId: 123 }, '用户已登录');
```

### 初始化配置

你可以在应用启动时自定义日志行为：

```typescript
import { log } from '@spike.hmc/h-logger';

log.init({
  serviceName: 'my-service',
  level: 'debug',
  pretty: true,        // 是否开启美化打印 (默认: true)
  toFile: true,        // 是否写入文件 (默认: true)
  logsDir: './my-logs' // 日志保存目录 (默认: './logs')
});
```

## 进阶用法

### 异步上下文管理

使用 `withContext` 或 `withContextAsync` 在特定的执行范围内自动注入元数据。

```typescript
import { log } from '@spike.hmc/h-logger';

async function handleRequest(requestId: string) {
  await log.withContextAsync({ taskId: requestId }, async () => {
    // 该代码块内的所有日志都会自动包含 taskId
    log.info('正在处理请求'); // 输出: [INFO] [requestId] 正在处理请求
    
    await someAsyncOperation();
    
    log.info('请求处理完成');
  });
}
```

### 丰富的格式化工具

SDK 提供了专门的格式化工具，用于处理常见的日志展示场景。

#### 表格和树形结构

```typescript
import { createFormatters, log } from '@spike.hmc/h-logger';

const formatters = createFormatters(true); // true 表示开启颜色

// 1. 表格格式化
const headers = ['ID', '名称', '状态'];
const rows = [
  ['1', 'Bitcoin', 'Active'],
  ['2', 'Ethereum', 'Pending']
];
const tableLines = formatters.table.format(headers, rows);
tableLines.forEach(line => log.raw.info(line));

// 2. 树形/步骤格式化
const tree = formatters.tree;
log.info(tree.formatStep(1, 3, '验证输入'));
log.info(tree.formatStep(2, 3, '获取数据'));
log.info(tree.formatChildNode('子任务: 检查缓存'));
log.info(tree.formatStep(3, 3, '完成处理'));

// 3. 任务状态区块
formatters.tree.formatTaskStart('TRANSACTION_001', { chainId: 1 }).forEach(l => log.raw.info(l));
// ... 执行任务 ...
formatters.tree.formatTaskComplete('TRANSACTION_001', 1250).forEach(l => log.raw.info(l));
```

### 原始日志记录

如果你想绕过标准格式化或上下文注入：

```typescript
log.raw.info('一条不带上下文或额外格式化的原始消息');
```

## 配置项说明

| 选项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `serviceName` | `string` | 取自 `package.json` | 服务的名称 |
| `level` | `string` | `'info'` | 最低显示的日志级别 |
| `pretty` | `boolean` | `true` | 使用人性化且带颜色的输出 |
| `toFile` | `boolean` | `true` | 是否将日志写入轮转文件 |
| `logsDir` | `string` | `'./logs'` | 日志文件的保存目录 |

## 日志级别

支持的级别（按优先级排序）：
- `fatal` (映射至 error)
- `error`
- `warn`
- `info`
- `debug`
- `trace` (映射至 silly)

## 许可

MIT