@neosjs/timer-logger/README.md

A timer logger for NeosJS

<div align="center">

# @neosjs/timer-logger

</div>

<div align="center">

![Npm Version][npm-version-image] ![Npm Week Downloads][npm-downloads-image-week] ![Npm Month Downloads][npm-downloads-image-month] ![Minzip][minzip] ![License][license-image] ![Timer Logger][timer-logger] ![Githu Ci][githu-ci]

</div>

一个高性能、类型安全的计时器日志记录库，支持浏览器和 Node.js 环境。

## ✨ 特性

- 🚀 **高性能**: 使用高精度时间 API，提供纳秒级精度
- 🌐 **跨平台**: 支持浏览器和 Node.js 环境
- 📝 **类型安全**: 完整的 TypeScript 类型定义
- 🎯 **灵活配置**: 支持自定义格式化选项
- 🔧 **易于使用**: 简洁的 API 设计
- 📦 **轻量级**: 仅 2.7KB (gzipped)

## 安装

```bash
pnpm add @neosjs/timer-logger

npm install @neosjs/timer-logger

yarn add @neosjs/timer-logger
```

## 快速开始

### 基本用法

```typescript
import timerLogger from '@neosjs/timer-logger'

// 启用计时器
timerLogger.setEnabled(true)

// 开始计时
const timer = timerLogger.start('my-task')
// ... 执行一些操作
timer?.end('任务完成')

// 或者使用标签方式
timerLogger.start('another-task')
// ... 执行一些操作
timerLogger.end('another-task', '另一个任务完成')
```

### 高级用法

```typescript
import { createTimerLogger } from '@neosjs/timer-logger'

// 创建自定义实例
const customLogger = createTimerLogger({
  enabled: true
})

customLogger.start('custom-task')
// ... 执行操作
customLogger.end('custom-task', '自定义任务')
```

### 获取总时间

```typescript
import timerLogger from '@neosjs/timer-logger'

timerLogger.setEnabled(true)

// 开始多个计时器
timerLogger.start('task1')
timerLogger.start('task2')
timerLogger.start('task3')

// ... 执行操作

// 获取各个计时器的时间
console.log('task1 时间:', timerLogger.getLabelTime('task1'), 'ms')
console.log('task2 时间:', timerLogger.getLabelTime('task2'), 'ms')

// 获取所有计时器的总时间
const totalTime = timerLogger.getTotalTime()
console.log('总时间:', totalTime, 'ms')
```

## API 参考

### TimerLogger (默认实例)

#### 方法

- `setEnabled(enabled: boolean)`: 启用或禁用计时器
- `isEnabled(): boolean`: 检查是否启用
- `start(label?: string): BaseTimerLogger | undefined`: 开始计时
- `end(label: string, overrideLabel?: string, options?: TimeFormatOptions): void`: 结束计时
- `get(label: string, options?: TimeFormatOptions): string | undefined`: 获取计时结果
- `getLabelTime(label: string): number | undefined`: 获取原始毫秒数
- `getTotalTime(): number`: 获取所有活跃计时器的总时间
- `clear(label: string): boolean`: 清除指定标签的计时器
- `reset(): void`: 重置计时器

### 类型定义

```typescript
interface TimerLoggerOptions {
  enabled?: boolean
}

type HrTime = readonly [number, number] // [秒, 纳秒]
```

## 环境支持

- **浏览器**: 使用 `performance.now()` API
- **Node.js**: 使用 `process.hrtime()` API
- **其他环境**: 降级使用 `Date.now()`

## License

[MIT](./LICENSE) License © 2021-PRESENT [NeosJS](https://docs.neosjs.com)

<!-- Badges -->

[npm-version-image]: https://img.shields.io/npm/v/@neosjs/timer-logger?style=flat&colorA=2d333b&colorB=1fa669
[npm-downloads-image-week]: https://img.shields.io/npm/dw/@neosjs/timer-logger?style=flat&colorA=2d333b&colorB=1fa669
[npm-downloads-image-month]: https://img.shields.io/npm/dm/@neosjs/timer-logger?style=flat&colorA=2d333b&colorB=1fa669
[license-image]: https://img.shields.io/npm/l/@neosjs/timer-logger?style=flat&colorA=2d333b&colorB=1fa669
[minzip]: https://img.shields.io/bundlephobia/minzip/%40neosjs%2Ftimer-logger?style=flat&colorA=2d333b&colorB=1fa669
[timer-logger]: https://img.shields.io/badge/NeosJS-timer--logger-1fa669?style=flat&colorA=2d333b&colorB=1fa669
[githu-ci]: https://github.com/neosjs/starter-ts/workflows/CI/badge.svg