# luckdog

**Repository Path**: liushuku/luckdog

## Basic Information

- **Project Name**: luckdog
- **Description**: npm 工具包  luckdog~
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 0
- **Created**: 2025-04-13
- **Last Updated**: 2025-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LuckDog 工具库

一个现代化的JavaScript/TypeScript实用工具库

## 特性

- 📦 使用Rollup打包，同时支持ESM和CommonJS
- 🔑 完整的TypeScript类型定义
- 🧪 Jest单元测试保障
- 📝 详细的API文档
- 🔍 支持Tree-shaking，按需导入

## 安装

```bash
# 使用npm
npm install luckdog

# 使用yarn
yarn add luckdog

# 使用pnpm
pnpm add luckdog
```

## 使用方法

LuckDog 支持多种使用方式，可以在不同的环境中使用：

### 在 Node.js 中使用

#### ESM 方式 (推荐)

```javascript
// 方式1: 导入特定工具命名空间
import { strUtil, arrUtil, validUtil } from 'luckdog';

// 通过命名空间调用相应工具函数
const shortText = strUtil.truncate('这是一个很长的文本', 5);
const uniqueArray = arrUtil.unique([1, 2, 2, 3]);
const isValidMail = validUtil.isValidEmail('example@domain.com');

// 方式2: 导入全部工具
import * as LuckDog from 'luckdog';
const shortText = LuckDog.strUtil.truncate('这是一个很长的文本', 5);
```

#### CommonJS 方式

```javascript
// 方式1: 导入特定工具命名空间
const { strUtil, arrUtil, validUtil } = require('luckdog');

// 通过命名空间调用相应工具函数
const shortText = strUtil.truncate('这是一个很长的文本', 5);
const uniqueArray = arrUtil.unique([1, 2, 2, 3]);
const isValidMail = validUtil.isValidEmail('example@domain.com');

// 方式2: 导入全部工具
const LuckDog = require('luckdog');
const shortText = LuckDog.strUtil.truncate('这是一个很长的文本', 5);
```

### 在浏览器中使用

#### 使用 ES Modules (推荐)

```html
<script type="module">
  import { strUtil, arrUtil, validUtil } from 'https://cdn.jsdelivr.net/npm/luckdog/dist/luckdog.esm.js';
  
  const text = strUtil.truncate('这是一个很长的文本', 10);
  console.log(text);
</script>
```

#### 使用 UMD 方式 (通过 CDN)

```html
<!-- 通过 jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/luckdog/dist/luckdog.umd.js"></script>

<!-- 或通过 unpkg -->
<script src="https://unpkg.com/luckdog/dist/luckdog.umd.js"></script>

<script>
  // 通过全局变量 luckdog 使用所有工具
  const text = luckdog.strUtil.truncate('这是一个很长的文本', 10);
  console.log(text);
</script>
```

### 在 Vue 项目中使用

```javascript
// 在组件中
<script>
import { strUtil, arrUtil } from 'luckdog';

export default {
  data() {
    return {
      originalText: '这是一个很长的文本，需要被截断',
      shortText: ''
    }
  },
  mounted() {
    this.shortText = strUtil.truncate(this.originalText, 10);
  }
}
</script>
```

### 在小程序中使用

首先安装:

```bash
# 进入小程序项目目录
cd your-miniprogram
# 安装依赖
npm install luckdog
```

在构建npm后，可以直接在小程序中使用:

```javascript
// 在页面或组件的 js 文件中
import { strUtil, arrUtil } from 'luckdog';

Page({
  data: {
    shortText: ''
  },
  onLoad() {
    this.setData({
      shortText: strUtil.truncate('这是一个很长的文本', 10)
    });
  }
})
```

### 在 React 项目中使用

```jsx
import React, { useState, useEffect } from 'react';
import { strUtil, validUtil } from 'luckdog';

function ExampleComponent() {
  const [shortText, setShortText] = useState('');
  
  useEffect(() => {
    setShortText(strUtil.truncate('这是一个很长的文本，需要被截断', 10));
  }, []);
  
  return (
    <div>
      <p>截断后的文本: {shortText}</p>
    </div>
  );
}
```

## 功能分类

LuckDog工具库将工具函数按功能分为三大类：

### 字符串工具 (String)

```javascript
import { strUtil } from 'luckdog';

// 使用strUtil命名空间调用，避免命名冲突
strUtil.truncate('这是一个很长的字符串', 4); // '这是一个...'
strUtil.hasBlank(''); // true
strUtil.hasBlank('hello', null, ''); // true
strUtil.hasBlank('hello', 'world'); // false
```

- `strUtil.hasBlank(...strs)`: 判断字符串是否为空白
- `strUtil.truncate(str, maxLength, suffix)`: 截断字符串到指定长度
- `strUtil.capitalize(str)`: 首字母大写
- `strUtil.camelToKebab(str)`: 驼峰命名转连字符命名
- `strUtil.kebabToCamel(str)`: 连字符命名转驼峰命名
- `strUtil.escapeHtml(html)`: 转义HTML特殊字符

### 数组工具 (Array)

```javascript
import { arrUtil } from 'luckdog';

// 使用arrUtil命名空间调用，避免命名冲突
arrUtil.unique([1, 2, 2, 3]); // [1, 2, 3]
arrUtil.groupBy([{age: 20}, {age: 30}, {age: 20}], item => item.age);
// {20: [{age: 20}, {age: 20}], 30: [{age: 30}]}
```

- `arrUtil.unique(arr)`: 数组去重
- `arrUtil.groupBy(arr, keySelector)`: 数组分组
- `arrUtil.flatten(arr)`: 数组扁平化（一维化）
- `arrUtil.random(arr)`: 获取数组中的随机元素
- `arrUtil.shuffle(arr)`: 数组洗牌（随机排序）

### 验证工具 (Validation)

```javascript
import { validUtil } from 'luckdog';

// 使用validUtil命名空间调用，避免命名冲突
validUtil.isEmpty(''); // true
validUtil.isValidEmail('test@example.com'); // true
validUtil.isValidMobile('13800138000'); // true
```

- `validUtil.isEmpty(value)`: 判断是否为空值
- `validUtil.isValidEmail(email)`: 验证邮箱格式
- `validUtil.isValidMobile(mobile)`: 验证手机号格式（中国大陆）
- `validUtil.isValidUrl(url)`: 验证URL格式
- `validUtil.isValidIDCard(idCard)`: 验证身份证号（中国大陆18位）

## 项目结构

```
luckdog/
├── config/               # 配置文件目录
│   ├── .eslintrc.json    # ESLint配置
│   ├── .prettierrc       # Prettier配置
│   ├── jest.config.mjs   # Jest测试配置
│   ├── rollup.config.mjs # Rollup打包配置
│   └── tsconfig.json     # TypeScript配置
├── dist/                 # 构建输出目录
├── examples/             # 示例代码目录
│   └── quickstart.mjs    # 快速入门示例
├── luckdog.bat           # 工具箱主菜单脚本
├── src/                  # 源代码目录
├── test/                 # 测试目录
├── CHANGELOG.md          # 版本更新日志
├── CODE_OF_CONDUCT.md    # 行为准则
├── CONTRIBUTING.md       # 贡献指南
├── LICENSE               # 许可证文件
├── NPM_PUBLISH_GUIDE.md  # NPM发布指南
├── package.json          # 项目配置
└── tsconfig.json         # TypeScript配置
```

## 开发

### 通用命令 (适用于所有操作系统)

```bash
# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建生产版本
npm run build

# 运行测试
npm test

# 生成测试覆盖率报告
npm run test:coverage

# 生成测试覆盖率报告并更新README
npm run test:update-readme

# 代码检查
npm run lint

# 代码格式化
npm run format
```

### Windows用户工具库管理系统

为方便Windows用户使用，我们提供了一个综合管理菜单系统：

只需双击根目录下的 `luckdog.bat` 文件，即可打开管理菜单，包含以下功能：

1. **构建相关**
   - 构建项目
   - 开发模式（监听文件变化）

2. **测试相关**
   - 运行测试
   - 生成测试覆盖率报告
   - 生成测试覆盖率并自动更新README

3. **发布相关**
   - 增加版本号并发布到NPM
   - 直接发布到NPM（不变更版本号）

4. **Git相关**
   - 提交并推送变更
   - 创建并推送版本标签

系统实现结构：
- 根目录 `luckdog.bat`: 入口文件
- `scripts/menu.bat`: 主菜单
- `scripts/build/`: 构建相关脚本
- `scripts/test/`: 测试相关脚本
- `scripts/npm/`: 发布相关脚本
- `scripts/git/`: Git相关脚本

通过这种模块化的方式，所有功能都被拆分到不同模块中，便于维护和扩展。

## 示例

可以在`examples`目录下找到使用示例：

- `quickstart.js`: 演示了基本的使用方法

运行示例（需要先构建项目）：

```bash
# 先构建项目
npm run build

# 然后运行示例
node examples/quickstart.js
```

## 发布与贡献

### NPM发布

我们已经为您准备了多种方式发布LuckDog至NPM：

1. 使用工具库管理系统(推荐):
   ```bash
   # Windows环境下双击，打开菜单系统
   luckdog.bat
   
   # 然后选择选项5来增加版本号并发布
   # 或选择选项6直接发布（不增加版本号）
   ```

2. 使用命令行方式:
   ```bash
   # 选择版本号类型
   npm run release:major  # 增加主版本号 (x.0.0)
   npm run release:minor  # 增加次版本号 (x.y.0)
   npm run release:patch  # 增加补丁版本号 (x.y.z)
   
   # 直接使用脚本，传入版本类型参数
   node scripts/npm/publish.js major  # 增加主版本号 (x.0.0)
   node scripts/npm/publish.js minor  # 增加次版本号 (x.y.0)
   node scripts/npm/publish.js patch  # 增加补丁版本号 (x.y.z)
   ```
   
   版本号规则 (遵循语义化版本):
   - **主版本号(x.0.0)**: 不兼容的API变更
   - **次版本号(x.y.0)**: 向下兼容的功能性新增
   - **补丁版本号(x.y.z)**: 向下兼容的问题修正
   
   脚本会自动执行测试、更新版本号、构建项目并发布。

3. 手动发布:
   ```bash
   # 安装依赖
   npm install
   
   # 运行测试
   npm test
   
   # 构建项目
   npm run build
   
   # 发布到NPM
   npm publish
   ```

### Git操作

使用工具库管理系统可以轻松管理代码变更：

1. 提交并推送变更:
   - 运行 `luckdog.bat` 并选择选项7
   - 输入提交信息
   
2. 为当前版本创建标签:
   - 运行 `luckdog.bat` 并选择选项8
   - 确认创建标签

详细的发布指南请参阅 [NPM_PUBLISH_GUIDE.md](./NPM_PUBLISH_GUIDE.md)。

### 贡献代码

我们欢迎您为LuckDog贡献代码，请参考 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解详情。

## 许可证

本项目采用 [MIT 许可证](./LICENSE)。

## 测试覆盖率

```
--------------|---------|----------|---------|---------|-------------------
File          | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
--------------|---------|----------|---------|---------|-------------------
All files     |   98.94 |    98.14 |     100 |   98.57 |                   
 arrutil.ts   |     100 |      100 |     100 |     100 |                   
 strutil.ts   |     100 |      100 |     100 |     100 |                   
 validutil.ts |   97.67 |    95.65 |     100 |   96.96 | 80                
--------------|---------|----------|---------|---------|-------------------
```

- **测试用例总数**: 48
- **测试套件数**: 3
- **覆盖率统计**:
  - 语句覆盖率: 98.94%
  - 分支覆盖率: 98.14%
  - 函数覆盖率: 100%
  - 行覆盖率: 98.57%