# glogjs

**Repository Path**: alamhubb/glogjs

## Basic Information

- **Project Name**: glogjs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-17
- **Last Updated**: 2026-01-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# glogjs

> Global Singleton Logger - 全局单例日志库

[![npm version](https://img.shields.io/npm/v/glogjs.svg)](https://www.npmjs.com/package/glogjs)
[![license](https://img.shields.io/npm/l/glogjs.svg)](https://github.com/alamhubb/glogjs/blob/main/LICENSE)

✅ **跨包共享** - 无需传递，自动共享配置  
✅ **静态 API** - `Glog.info()`，无需实例化  
✅ **零配置** - 开箱即用，可选配置  
✅ **文件输出** - 内置文件写入，异步不阻塞  
✅ **自动根目录** - 智能查找项目根目录  
✅ **双文件策略** - 时间戳日志 + 包名日志

## 痛点与解决方案

### 痛点：跨包日志需要传递实例

即使你的项目和所有依赖包都用同一个日志库（比如 winston），你仍然需要：

```typescript
// 入口文件
const logger = winston.createLogger({ level: 'debug', ... })

// 每个依赖包都需要暴露 init 接口
import packageA from 'package-a'
import packageB from 'package-b'

packageA.init({ logger })  // 需要传递
packageB.init({ logger })  // 需要传递
```

**问题**：
- 每个依赖包必须暴露 `init` 接口接收 logger
- 调用方需要手动传递 logger 实例
- 忘记传递就没有日志
- 包的作者和使用者都需要额外工作

### 解决方案：真正的全局单例

glogjs 使用 `Symbol.for` + `globalThis` 实现**无需传递**的全局单例：

```typescript
// 入口文件：只需配置一次
import Glog from 'glogjs'
Glog.init({ level: 'debug' })

// 依赖包：直接使用，自动共享配置
// package-a/index.ts
import Glog from 'glogjs'
Glog.info('自动使用入口的配置')  // ✅ 无需传递

// package-b/index.ts  
import Glog from 'glogjs'
Glog.debug('也是共享的')  // ✅ 无需传递
```

**零侵入、零传递、自动共享！**

## 使用场景

### 适合使用 glogjs 的场景

1. **Monorepo 多包项目** - 统一日志配置
2. **npm 包开发** - 让使用者控制日志级别
3. **VSCode/Volar 插件** - 多个依赖包共享日志
4. **调试复杂依赖链** - 所有日志输出到同一个文件

### 不太需要 glogjs 的场景

- 单文件脚本（直接用 console 即可）
- 需要复杂日志分析（考虑 pino + ELK）

## 安装

```bash
npm install glogjs
```

## 快速开始

```typescript
import Glog from 'glogjs'

// 直接使用（自动初始化）
Glog.info('Hello World')
Glog.debug('Debug info')
Glog.warn('Warning')
Glog.error('Error')
```

## 特性

- ✅ **全局单例** - 整个 npm 依赖链共享同一实例
- ✅ **零配置** - 开箱即用，可选配置
- ✅ **静态 API** - `Glog.info()`，无需实例化
- ✅ **双文件输出** - 时间戳日志 + 包名日志
- ✅ **自动项目根发现** - 智能查找日志目录
- ✅ **浏览器兼容** - 自动禁用文件写入
- ✅ **TypeScript** - 完整类型支持

## 日志格式

```
2026-01-17 21:16:42 +08 [DEBUG] [my-project] 这是调试日志
│                   │    │       │           └─ 消息
│                   │    │       └─ 项目名（自动获取）
│                   │    └─ 日志级别
│                   └─ 时区
└─ 本地时间
```

## 日志文件

日志存储在项目根目录的 `.glog/` 文件夹：

```
.glog/
├── 2026-01-17-21.log   # 时间戳日志（追加模式）
└── my-project.log      # 包名日志（每次 init 清空）
```

## 配置（可选）

```typescript
import Glog from 'glogjs'

// 在入口文件配置一次，所有依赖包共享
Glog.init({
    level: 'debug',      // 'debug' | 'info' | 'warn' | 'error' | 'silent'
    logRoot: '/path',    // 日志目录（默认自动查找）
    console: true,       // 是否输出到控制台
    writeFile: true,     // 是否写入文件
    timestamp: true,     // 是否包含时间戳
    useUtcTime: false,   // 使用 UTC 时间
})
```

## 全局单例原理

```typescript
// package-a/index.ts（入口包）
import Glog from 'glogjs'
Glog.init({ level: 'debug' })

// package-b/index.ts（依赖包）
import Glog from 'glogjs'
Glog.info('使用 package-a 的配置')  // ✅ 自动共享

// package-c/index.ts（依赖包）
import Glog from 'glogjs'
Glog.debug('也是共享的')  // ✅ 自动共享
```

## 与其他日志库对比

| 特性 | glogjs | winston | pino | consola | debug |
|------|--------|---------|------|---------|-------|
| 跨包共享 | ✅ 自动 | ❌ 需传递 | ❌ 需传递 | ⚠️ 版本隔离 | ❌ |
| 静态 API | ✅ | ⚠️ | ❌ | ✅ | ❌ |
| 零配置 | ✅ | ❌ | ❌ | ✅ | ✅ |
| 文件输出 | ✅ 内置 | ✅ 内置 | ✅ stream | ❌ | ❌ |
| 自动项目根 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 双文件策略 | ✅ | ❌ 需配置 | ❌ 需配置 | ❌ | ❌ |

**核心差异**：其他库需要传递 logger 实例，glogjs 自动跨包共享。

### 传统方式 vs glogjs

**传统方式（依赖注入）：**
```typescript
// 需要手动传递 logger
const logger = new Logger()
packageA.init({ logger })
packageB.init({ logger })
packageC.init({ logger })
```

**glogjs 方式：**
```typescript
// 只需配置一次
Glog.init({ level: 'debug' })
// 所有依赖包自动共享，无需传递
```

## API

### 日志方法

```typescript
Glog.log(message, level?)  // 通用日志，默认 info
Glog.debug(message)        // 调试日志
Glog.info(message)         // 信息日志
Glog.warn(message)         // 警告日志
Glog.error(message)        // 错误日志
```

### 动态配置

```typescript
Glog.level = 'debug'       // 修改日志级别
Glog.console = false       // 禁用控制台输出
Glog.writeFile = false     // 禁用文件写入
```

### 获取配置

```typescript
const config = Glog.getConfig()
console.log(config.level)  // 当前日志级别
```

## 贡献

欢迎提交 Issue 和 PR！

GitHub: https://github.com/alamhubb/glogjs

## License

MIT