@planarcat/js-toolkit

一个现代化的 JavaScript/TypeScript 实用工具库，提供类型安全、高性能的常用函数。

特性

• 🚀 类型安全: 完整的 TypeScript 支持，提供完整的类型定义
• 📦 轻量级: 零依赖，体积小巧
• 🎯 高性能: 优化的算法实现
• 🔧 现代化: 使用最新的 JavaScript/TypeScript 特性
• 📚 学习性质: 代码清晰，适合学习和参考

安装

# 使用 npm
npm install @planarcat/js-toolkit

# 使用 yarn
yarn add @planarcat/js-toolkit

# 使用 pnpm
pnpm add @planarcat/js-toolkit

快速开始

日期格式化

import { formatDate } from '@planarcat/js-toolkit';

// 基本使用
console.log(formatDate(new Date()));
// 输出: "2023-12-25 14:30:45"

// 自定义格式
console.log(formatDate('2023-12-25', 'YYYY年MM月DD日'));
// 输出: "2023年12月25日"

// 使用 dd 标记显示周几
console.log(formatDate(new Date(), 'dd HH:mm'));
// 输出: "周一 14:30"

// 英文环境
console.log(formatDate(new Date(), 'dd HH:mm', { locale: 'en-US' }));
// 输出: "Monday 14:30"

函数防抖

import { debounce } from '@planarcat/js-toolkit';

// 创建防抖函数
const debouncedFn = debounce(
  () => {
    console.log('函数执行了！');
  },
  { delay: 500 },
);

// 多次调用，只会执行最后一次
debouncedFn();
debouncedFn();
debouncedFn();
// 500ms 后执行一次

数字格式化

import {
  toFormattedNumber,
  toFormattedNumberString,
  DecimalPlacesOptions,
} from '@planarcat/js-toolkit';

// 基本使用
console.log(toFormattedNumber(1234.5678));
// 输出: 1234.5678

// 保留两位小数
console.log(toFormattedNumber(1234.5678, { decimalPlaces: 2 }));
// 输出: 1234.57

// 使用 RETAIN_ALL 常量保留所有小数位
console.log(
  toFormattedNumber(1234.5678, {
    decimalPlaces: DecimalPlacesOptions.RETAIN_ALL,
  }),
);
// 输出: 1234.5678

// 处理字符串
console.log(toFormattedNumber('123.45abc'));
// 输出: 123.45

// 处理数组
console.log(toFormattedNumber([123.456, '456.789']));
// 输出: [123.456, 456.789]

// 处理深层数组
console.log(
  toFormattedNumber([
    [1, '1.23'],
    ['45.67', [89.01, 'abc']],
  ]),
);
// 输出: [[1, 1.23], [45.67, [89.01, NaN]]]

// 数字转格式化字符串
console.log(toFormattedNumberString(1234.5678, { decimalPlaces: 2 }));
// 输出: "1234.57"

// 使用 RETAIN_ALL 常量保留所有小数位
console.log(
  toFormattedNumberString(1234.5678, {
    decimalPlaces: DecimalPlacesOptions.RETAIN_ALL,
  }),
);
// 输出: "1234.5678"

// 保留两位小数，不够时补0
console.log(toFormattedNumberString(123.4, { decimalPlaces: 2 }));
// 输出: "123.40"

// 带前缀后缀
console.log(
  toFormattedNumberString(1234.5678, { prefix: '$', suffix: ' USD' }),
);
// 输出: "$1234.5678 USD"

// 本地化格式
console.log(toFormattedNumberString(1234567.89, { localized: true }));
// 输出: "1,234,567.89"

// 自定义NaN和0显示
console.log(toFormattedNumberString(null, { nanValue: 'N/A' }));
// 输出: "N/A"
console.log(toFormattedNumberString(0, { zeroValue: '-' }));
// 输出: "-"

// 预处理函数
console.log(
  toFormattedNumberString(0.1234, {
    preProcessor: (original, num) => num * 100,
    suffix: '%',
  }),
);
// 输出: "12.34%"

// 函数类型前缀
console.log(
  toFormattedNumberString(123.456, {
    prefix: (original, num, formatted) => `$${Math.floor(num)}`,
  }),
);
// 输出: "$123123.456"

// 函数类型后缀
console.log(
  toFormattedNumberString(123.456, {
    suffix: (original, num, formatted) => `/${num.toFixed(0)}`,
  }),
);
// 输出: "123.456/123"

// 处理数组
console.log(
  toFormattedNumberString([123.456, '789.012'], { decimalPlaces: 2 }),
);
// 输出: ["123.46", "789.01"]

API 文档

详细的 API 文档请查看 docs/ 目录下的模块文档：

• 日期格式化
• 函数防抖
• 数字格式化
• 类型定义

生成文档

# 生成 API 文档
pnpm run docs

# 监听模式生成文档
pnpm run docs:watch

开发

项目结构

src/
├── date/
│   └── formatDate.ts      # 日期格式化函数
├── function/
│   └── debounce.ts        # 函数防抖功能
├── object/
│   ├── toFormattedNumber.ts  # 数字格式化函数
│   └── toFormattedNumberString.ts  # 格式化数字字符串函数
├── types/
│   ├── date.ts            # 日期相关类型定义
│   ├── function.ts        # 防抖相关类型定义
│   ├── object.ts          # 数字格式化相关类型定义
│   └── index.ts           # 类型导出
├── utils/
│   └── constants.ts       # 常量定义
└── index.ts               # 主入口文件

开发命令

# 安装依赖
pnpm install

# 构建项目
pnpm run build

# 运行测试
pnpm test

# 运行测试（监听模式）
pnpm run test:watch

# 代码检查
pnpm run lint

# 代码格式化
pnpm run format

# 清理构建文件
pnpm run clean

测试

项目使用 Jest 进行单元测试，测试文件位于 __tests__/ 目录。

# 运行所有测试
pnpm test

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

发布

项目使用 GitHub Actions 和 Trusted Publishing 进行自动发布。

发布流程

1. 更新版本号：使用 bump-version.js 脚本更新版本号

   # 可选参数：patch (默认), minor, major, prerelease
   pnpm run bump:patch

2. 推送代码和标签：

   git push && git push --tags

3. 自动发布：GitHub Actions 将自动触发发布流程：

   • 执行质量检查
   • 构建项目
   • 使用 Trusted Publishing 发布到 npm
   • 创建 GitHub Release

发布配置

• Trusted Publishing：通过 OIDC 令牌进行身份验证，无需持久化的 npm 令牌
• 自动触发：仅在标签推送时触发发布
• 安全可靠：使用 GitHub Actions 安全上下文

贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

许可证

本项目基于 MIT 许可证开源 - 查看 LICENSE 文件了解详情。

作者

• planarcat - GitHub

更新日志

v1.7.13

• ✨ 重构了 decimalPlaces 参数类型，使用 DecimalPlacesOptions 联合类型
• ✨ 新增 DecimalPlacesOptions 对象，包含 RETAIN_ALL 常量用于保留所有小数位
• ✨ 优化了类型定义，提高了类型安全性
• ✨ 更新了文档，添加了 DecimalPlacesOptions 的使用示例

v1.7.12

• ✨ 修复了构建错误，解决了合并声明问题

v1.7.1

• ✨ 修复了 formatDate 函数中 Unix 时间戳计算问题，确保基于 UTC 时间
• ✨ 统一了 regular 和 compile 两种模式下的时间戳计算逻辑
• ✨ 修复了测试用例中的时间戳期望值，确保跨时区测试通过
• ✨ 优化了项目依赖管理，迁移到 pnpm 包管理器
• ✨ 新增了自动化发布流程，支持 GitHub Actions 自动发布到 npm
• ✨ 添加了 API 文档自动部署到 GitHub Pages 的功能

v1.7.0

• ✨ 优化日期格式化功能，移除了 dddd 和 ddd 标记
• ✨ 使用 dd 标记显示完整星期名称（周一、Monday）
• ✨ 新增自定义周名称映射功能，支持：
  • 数组格式：['星期日', '星期一', ...]
  • 完整映射：{ zh: ['周日', ...], en: ['Sun', ...] }
• ✨ 支持自动模式检测，根据调用频率自动切换普通/编译模式
• ✨ 优化编译模式性能，使用 LRU 缓存存储编译后的格式化函数
• ✨ 修复了模板字符串嵌套错误和类型安全问题

v1.6.0

• ✨ 增强了日期格式化功能，支持更多格式化标记
• ✨ 新增月份相关标记：MMMM（完整月份名称）、MMM（月份缩写）
• ✨ 新增日期相关标记：DDD（一年中的第几天）、Do（带序数词的日期）
• ✨ 新增时间相关标记：S（单个毫秒）
• ✨ 新增星期相关标记：dddd（完整星期名称）、ddd（星期缩写）
• ✨ 新增时间戳相关标记：X（Unix时间戳秒）、x（Unix时间戳毫秒）
• ✨ 优化了文档结构，添加了完整的格式化标记参考
• ✨ 完善了测试用例，覆盖所有新功能

v1.5.6

• ✨ 优化了 toFormattedNumberString 函数的内部实现，将内部函数提取到外部
• ✨ 统一了变量命名规范，根据转化进度命名：converted、preProcessed、formatted
• ✨ 新增测试用例，验证预处理函数和后缀函数的组合使用
• ✨ 提高了代码的可读性和可维护性

v1.5.5

• ✨ 修复了测试文件中的未使用变量警告
• ✨ 优化了代码注释，删除了重复的不必要说明
• ✨ 提高了代码的简洁性和可维护性

v1.5.3

• ✨ 增强了 toFormattedNumberString 函数，为 preProcessor、prefix 和 suffix 函数更新了参数顺序
• ✨ preProcessor 现在接收两个参数：原始对象和转化后的 number
• ✨ prefix 如果是函数，现在接收三个参数：原始对象、转化后的 number、格式化后的字符串
• ✨ suffix 如果是函数，现在接收三个参数：原始对象、转化后的 number、格式化后的字符串
• ✨ 增强了测试用例，验证新功能
• ✨ 更新了文档，明确说明每个函数参数的用途

v1.5.2

• ✨ 更新了函数返回值类型说明，明确区分数组和非数组输入的返回值
• ✨ 生成了最新的 API 文档

v1.5.1

• ✨ 更新了 README 文档，修复了参数名称
• ✨ 生成了最新的 API 文档

v1.5.0

• ✨ 为 toFormattedNumberString 函数的前缀后缀添加函数类型支持
• ✨ 修复 0 值、NaN 值和无数字字符串的前缀后缀处理问题
• ✨ 完善文档和测试用例，确保覆盖所有功能
• ✨ 优化项目规则文件结构，采用分层管理

v1.4.0

• ✨ 优化数字格式化功能，无数字字符串返回 0 而不是 NaN
• ✨ 改进 toFormattedNumberString 函数，无数字字符串直接返回 zeroValue
• ✨ 完善文档和测试用例
• ✨ 优化深层数组处理逻辑

v1.3.0

• ✨ 添加数字格式化功能 toFormattedNumber
• ✨ 支持处理任意输入类型（number、string、array、deep array）
• ✨ 支持自定义小数位数和 NaN 显示
• ✨ 支持深层数组递归处理
• ✨ 完善的类型定义和 JSDoc 注释
• ✨ 新增 object 分类目录结构

v1.2.0

• ✨ 优化日期格式化功能，支持使用 dd 标记直接显示周几
• ✨ 改进文档系统，使用 TypeDoc 自动生成模块化文档
• ✨ 优化代码结构和类型定义

v1.1.0

• ✨ 添加函数防抖功能 debounce
• ✨ 支持防抖取消功能 cancel
• ✨ 完善类型定义
• ✨ 添加防抖函数测试用例

v1.0.0

• ✨ 初始版本发布
• ✨ 实现日期格式化功能 formatDate
• ✨ 完整的 TypeScript 类型支持
• ✨ 单元测试覆盖
• ✨ 构建和发布配置