jinbi-utils 1.0.19 → 1.0.21

package/.babelrc

@@ -0,0 +1,19 @@
+{
+  "presets": [
+    [
+      "@babel/preset-env",
+      {
+        "modules": false,
+        "targets": {
+          "node": "current"
+        }
+      }
+    ],
+    "@babel/preset-typescript"
+  ],
+  "env": {
+    "test": {
+      "plugins": ["@babel/plugin-transform-modules-commonjs"]
+    }
+  }
+}

package/.cz-config.js

@@ -0,0 +1,55 @@
+'use strict';
+
+module.exports = {
+
+  types: [
+    {value: 'feat',     name: 'feat:     新特性或功能'},
+    {value: 'fix',      name: 'fix:      修复Bug'},
+    {value: 'docs',     name: 'docs:     文档的变更'},
+    {value: 'style',    name: 'style:    不影响代码运行的风格更改(空白、格式、缺少分号等)'},
+    {value: 'refactor', name: 'refactor: 代码重构, 注意和feat、fix区分'},
+    {value: 'perf',     name: 'perf:     提高性能'},
+    {value: 'test',     name: 'test:     添加测试'},
+    {value: 'chore',    name: 'chore:    开发工具(构建、脚手架工具等)和库（如文档生成）的更改'},
+    {value: 'revert',   name: 'revert:   代码回滚'},
+    {value: 'WIP',      name: 'WIP:      进行中开发'}
+  ],
+
+  // list of Function Modules
+  scopes: [
+    {name: '模块1'},
+    {name: '模块2'},
+  ],
+
+  // it needs to match the value for field type. Eg.: 'fix'
+  /*
+  scopeOverrides: {
+    fix: [
+      {name: 'merge'},
+      {name: 'style'},
+      {name: 'e2eTest'},
+      {name: 'unitTest'}
+    ]
+  },
+  */
+  // override the messages, defaults are as follows
+  messages: {
+    type: '选择一种提交类型:',
+    scope: '选择一个scope (可选):',
+    // used if allowCustomScopes is true
+    customScope: 'Denote the SCOPE of this change:',
+    subject: '简短说明:\n',
+    body: '长说明，使用"|"换行(可选)：\n',
+    breaking: '非兼容性说明 (可选):\n',
+    footer: '关联关闭的issue，例如：#31, #34(可选):\n',
+    confirmCommit: '确定提交说明?'
+  },
+
+
+  allowCustomScopes: true,
+  allowBreakingChanges: ['feat', 'fix'],
+
+  // limit subject length
+  subjectLimit: 100
+
+};

package/.dockerignore

@@ -0,0 +1,3 @@
+ .git
+ node_modules
+ npm-debug.log

package/.editorconfig

@@ -0,0 +1,12 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.eslintignore

@@ -0,0 +1,8 @@
+/.git
+/.vscode
+node_modules
+dist
+test
+rollup.config.js
+types
+*

package/.eslintrc.js

@@ -0,0 +1,54 @@
+module.exports = {
+  "env": {
+    "browser": true,
+    "commonjs": true,
+    "es6": true,
+    "node": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "parserOptions": {
+    "ecmaVersion": 2015,
+    "sourceType": "module",
+    "project": "./tsconfig.json"
+  },
+  "rules": {
+    'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'off',
+    'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
+    'prefer-promise-reject-errors': 'off', // 要求使用 Error 对象作为 Promise 拒绝的原因
+    'linebreak-style': 'off', // 回车换行风格
+    'no-trailing-spaces': 1, // 允许在空行、在注释块中使用空白符
+    'import/prefer-default-export': 'off', // 
+    'object-curly-newline': 'off', // 不强制花括号内换行
+    'import/named': 'off', // 停用 import/named 校验
+    'no-underscore-dangle': 'off', // 禁止标识符中有悬空下划线
+    'import/order': 'off',
+    'prefer-object-spread': 1, // 禁止使用以对象字面量作为第一个参数的 Object.assign，优先使用对象扩展。
+    'arrow-parens': [2, "as-needed", { "requireForBlockBody": true }], // 要求箭头函数的参数使用圆括号
+    "comma-dangle": ["error", "always-multiline"], // 要求或禁止使用拖尾逗号
+    "semi": 2, // 要求或禁止使用分号代替 ASI
+    "keyword-spacing": 2, // 强制关键字周围空格的一致性
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/interface-name-prefix": "off",
+    "@typescript-eslint/no-empty-function": "off",
+    "@typescript-eslint/no-inferrable-types": "off",
+    "@typescript-eslint/no-empty-interface": "off",
+    "@typescript-eslint/no-non-null-assertion": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/member-delimiter-style": ["error", {
+      "multiline": {
+        "delimiter": "semi",
+        "requireLast": true
+      },
+      "singleline": {
+        "delimiter": "semi",
+        "requireLast": true
+      }
+    }]
+  }
+};

package/.versionrc.json

@@ -0,0 +1,9 @@
+{
+  "types": [
+    { "type": "feat", "section": "✨ Features" },
+    { "type": "fix", "section": "🐞 Bug Fixes" },
+    { "type": "docs", "section": "📖 Documentation" },
+    { "type": "style", "section": "🎨 Style" }
+  ],
+  "releaseCommitMessageFormat": "chore(release): 发布版本 v{{currentTag}}"
+}

package/CHUNK_OPTIMIZER_USAGE.md

@@ -0,0 +1,132 @@
+# Chunk Optimizer 使用说明
+
+## 问题说明
+
+`chunk-optimizer` 是一个**构建时工具**，它依赖 Node.js 内置模块（`fs` 和 `path`），只能在 Node.js 环境中运行（如 `vite.config.ts`）。
+
+从 v1.0.9 版本开始，`chunk-optimizer` 已从主入口文件中移除，以避免将 Node.js 模块打包到浏览器端的 bundle 中。
+
+## 正确的使用方式
+
+### 在消费项目中使用
+
+**方式一：通过单独的导出路径（推荐）**
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { createChunkOptimizer } from 'jinbi-utils/chunk-optimizer'
+
+const optimizer = createChunkOptimizer({
+  framework: 'vue',
+  debug: true
+})
+
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: optimizer.generate()
+      }
+    }
+  }
+})
+```
+
+**方式二：直接从源码导入**
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { createChunkOptimizer } from 'jinbi-utils/src/build/chunk-optimizer'
+
+// 使用方式同上
+```
+
+### 在浏览器代码中使用其他工具函数
+
+浏览器代码中可以正常导入其他工具函数，不会受到影响：
+
+```typescript
+// 在 .vue 或 .ts 文件中
+import { formatTime, formatPhone, isEmpty } from 'jinbi-utils'
+
+// 正常使用
+const time = formatTime(Date.now())
+```
+
+## 版本升级指南
+
+如果你的项目之前使用的是 v1.0.8 或更早版本，并且遇到了以下错误：
+
+```
+error during build:
+"resolve" is not exported by "__vite-browser-external"
+```
+
+请按照以下步骤升级：
+
+### 步骤 1: 更新包版本
+
+```bash
+npm install jinbi-utils@latest
+# 或
+pnpm update jinbi-utils
+```
+
+### 步骤 2: 修改 vite.config.ts 中的导入
+
+**修改前：**
+```typescript
+import { createChunkOptimizer } from 'jinbi-utils'
+```
+
+**修改后：**
+```typescript
+import { createChunkOptimizer } from 'jinbi-utils/chunk-optimizer'
+```
+
+### 步骤 3: 重新构建
+
+```bash
+npm run build
+```
+
+## 技术细节
+
+### 为什么要这样做？
+
+1. **chunk-optimizer 依赖 Node.js 模块**：它需要读取 `package.json` 文件来分析依赖
+2. **浏览器环境不支持 Node.js 模块**：`fs` 和 `path` 无法在浏览器中运行
+3. **Vite 的处理方式**：当浏览器代码导入包含 Node.js 模块的文件时，Vite 会尝试用 polyfill 替换，但这会导致错误
+
+### 解决方案的原理
+
+通过将 `chunk-optimizer` 从主入口移除，并提供单独的导出路径：
+
+- **浏览器代码**导入 `jinbi-utils` 时，只会加载不包含 Node.js 模块的代码
+- **构建配置**导入 `jinbi-utils/chunk-optimizer` 时，可以正常使用 Node.js 模块
+
+## 常见问题
+
+### Q: 我的项目没有使用 chunk-optimizer，也遇到了这个错误？
+
+A: 如果你的项目代码中导入了 `jinbi-utils`，但没有使用 `chunk-optimizer`，升级到最新版本即可解决。
+
+### Q: 我可以在浏览器代码中使用 chunk-optimizer 吗？
+
+A: 不可以。`chunk-optimizer` 是构建时工具，只能在 Node.js 环境（如 `vite.config.ts`）中使用。
+
+### Q: 升级后，其他工具函数还能正常使用吗？
+
+A: 可以。其他所有工具函数（如 `formatTime`、`formatPhone` 等）都不受影响，可以在浏览器代码中正常使用。
+
+## 联系支持
+
+如果遇到问题，请提供以下信息：
+
+1. `jinbi-utils` 版本号
+2. 错误信息截图
+3. `vite.config.ts` 中的相关配置
+4. Node.js 和 npm/pnpm 版本
+

package/Dockerfile

@@ -0,0 +1,3 @@
+FROM nginx
+
+COPY docs /usr/share/nginx/html/

package/QUICK_RELEASE.md

@@ -0,0 +1,85 @@
+# 🚀 快速发布参考
+
+## 一键发布命令
+
+```bash
+# 🔧 修复 bug（1.0.8 -> 1.0.9）
+npm run release
+
+# 或明确指定
+npm run release:patch
+
+# ✨ 新功能（1.0.8 -> 1.1.0）
+npm run release:minor
+
+# 💥 破坏性更新（1.0.8 -> 2.0.0）
+npm run release:major
+
+# 🧪 测试版本（1.0.8 -> 1.0.9-beta.0）
+npm run release:beta
+```
+
+## 发布前准备
+
+1. **提交所有更改**
+   ```bash
+   git add .
+   git commit -m "feat: 添加新功能"
+   ```
+
+2. **确保在正确的分支**
+   ```bash
+   git checkout main
+   ```
+
+3. **拉取最新代码**
+   ```bash
+   git pull origin main
+   ```
+
+## Commit 规范速查
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `feat` | 新功能 | `feat: 添加文件上传功能` |
+| `fix` | 修复 bug | `fix: 修复日期格式化问题` |
+| `docs` | 文档 | `docs: 更新 API 文档` |
+| `style` | 格式 | `style: 格式化代码` |
+| `refactor` | 重构 | `refactor: 重构用户模块` |
+| `perf` | 性能 | `perf: 优化列表渲染` |
+| `test` | 测试 | `test: 添加单元测试` |
+| `chore` | 构建 | `chore: 更新依赖` |
+
+## 自动化流程
+
+运行 `npm run release` 会自动：
+
+1. ✅ 运行构建
+2. 📝 更新版本号
+3. 📄 生成 CHANGELOG
+4. 🏷️ 创建 Git Tag
+5. 💾 提交更改
+6. 📤 发布到 npm
+7. ⬆️ 推送到 Git
+
+## 常见问题
+
+**Q: 如何撤销发布？**
+```bash
+npm unpublish jinbi-utils@版本号
+```
+
+**Q: 如何查看当前版本？**
+```bash
+npm view jinbi-utils version
+```
+
+**Q: 发布失败怎么办？**
+- 检查是否已登录：`npm whoami`
+- 检查网络连接
+- 查看错误信息
+
+## 详细文档
+
+查看 [RELEASE_GUIDE.md](./RELEASE_GUIDE.md) 了解完整的发布流程。
+

package/RELEASE_GUIDE.md

@@ -0,0 +1,243 @@
+# 📦 发布指南
+
+本文档说明如何使用自动化命令发布新版本。
+
+## 🚀 快速开始
+
+### 一键发布（推荐）
+
+```bash
+# 发布 patch 版本（默认，如 1.0.8 -> 1.0.9）
+npm run release
+
+# 或者明确指定
+npm run release:patch
+```
+
+### 指定版本类型发布
+
+```bash
+# 发布 patch 版本（修复 bug）：1.0.8 -> 1.0.9
+npm run release:patch
+
+# 发布 minor 版本（新功能）：1.0.8 -> 1.1.0
+npm run release:minor
+
+# 发布 major 版本（破坏性更新）：1.0.8 -> 2.0.0
+npm run release:major
+
+# 发布 beta 版本（测试版）：1.0.8 -> 1.0.9-beta.0
+npm run release:beta
+```
+
+## 📋 发布流程说明
+
+当你运行 `npm run release:patch` 时，会自动执行以下步骤：
+
+1. ✅ **运行构建**：`npm run build`
+2. 📝 **更新版本号**：自动修改 `package.json` 中的版本号
+3. 📄 **生成 CHANGELOG**：根据 git commit 自动生成更新日志
+4. 🏷️ **创建 Git Tag**：创建版本标签（如 `v1.0.9`）
+5. 💾 **提交更改**：自动提交版本号和 CHANGELOG 的更改
+6. 📤 **发布到 npm**：执行 `npm publish`
+7. ⬆️ **推送到远程**：推送代码和标签到 Git 仓库
+
+## 🔍 发布前检查
+
+在发布前，建议手动运行检查脚本：
+
+```bash
+./scripts/pre-release-check.sh
+```
+
+这个脚本会检查：
+- ✅ Git 状态（是否有未提交的更改）
+- ✅ 当前分支（是否在 main/master）
+- ✅ 代码检查（ESLint）
+- ✅ 测试（如果有）
+- ✅ 构建
+
+## 📝 Commit 规范
+
+为了自动生成正确的 CHANGELOG，请遵循以下 commit 规范：
+
+### Commit 类型
+
+- `feat`: 新功能
+- `fix`: 修复 bug
+- `docs`: 文档更新
+- `style`: 代码格式（不影响代码运行）
+- `refactor`: 重构
+- `perf`: 性能优化
+- `test`: 测试相关
+- `chore`: 构建工具或辅助工具的变动
+
+### Commit 格式
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### 示例
+
+```bash
+# 新功能
+git commit -m "feat: 添加文件大小格式化函数"
+git commit -m "feat(array): 添加数组去重方法"
+
+# 修复 bug
+git commit -m "fix: 修复日期格式化在 Safari 中的问题"
+git commit -m "fix(http): 修复请求超时配置无效的问题"
+
+# 破坏性更新（会触发 major 版本）
+git commit -m "feat: 重构 API 接口
+
+BREAKING CHANGE: 移除了旧的 formatDate 方法，请使用 formatTime 代替"
+```
+
+## 🎯 版本号规则
+
+遵循 [语义化版本](https://semver.org/lang/zh-CN/)：
+
+- **MAJOR（主版本号）**：不兼容的 API 修改
+- **MINOR（次版本号）**：向下兼容的功能性新增
+- **PATCH（修订号）**：向下兼容的问题修正
+
+### 何时升级版本？
+
+| 变更类型 | 版本类型 | 示例 |
+|---------|---------|------|
+| 修复 bug | patch | 1.0.8 -> 1.0.9 |
+| 新增功能（向下兼容） | minor | 1.0.8 -> 1.1.0 |
+| 破坏性更新 | major | 1.0.8 -> 2.0.0 |
+| 测试版本 | beta | 1.0.8 -> 1.0.9-beta.0 |
+
+## 🔧 手动发布（不推荐）
+
+如果需要手动控制每一步：
+
+```bash
+# 1. 运行构建
+npm run build
+
+# 2. 更新版本号和生成 CHANGELOG
+npm run standard-version -- --release-as patch
+
+# 3. 发布到 npm
+npm publish
+
+# 4. 推送到 Git
+git push --follow-tags
+```
+
+## 📦 发布到特定 registry
+
+如果需要发布到私有 npm registry：
+
+```bash
+# 设置 registry
+npm config set registry https://your-registry.com
+
+# 或者在发布时指定
+npm publish --registry https://your-registry.com
+```
+
+## 🔐 npm 认证
+
+首次发布需要登录 npm：
+
+```bash
+npm login
+```
+
+或者使用 token：
+
+```bash
+npm config set //registry.npmjs.org/:_authToken YOUR_TOKEN
+```
+
+## ⚠️ 注意事项
+
+1. **确保在正确的分支**：通常应该在 `main` 或 `master` 分支发布
+2. **确保代码已提交**：不要有未提交的更改
+3. **确保测试通过**：运行 `npm test` 确保所有测试通过
+4. **确保构建成功**：运行 `npm run build` 确保构建无错误
+5. **检查 .npmignore**：确保不会发布不必要的文件
+
+## 🔄 回滚版本
+
+如果发布了错误的版本：
+
+```bash
+# 1. 从 npm 撤回版本（24小时内）
+npm unpublish jinbi-utils@1.0.9
+
+# 2. 删除本地 tag
+git tag -d v1.0.9
+
+# 3. 删除远程 tag
+git push origin :refs/tags/v1.0.9
+
+# 4. 回退 commit
+git reset --hard HEAD~1
+git push -f origin main
+```
+
+## 📊 查看发布历史
+
+```bash
+# 查看所有版本
+npm view jinbi-utils versions
+
+# 查看最新版本
+npm view jinbi-utils version
+
+# 查看 Git tags
+git tag -l
+```
+
+## 🆘 常见问题
+
+### Q: 发布失败，提示 "You do not have permission to publish"
+
+A: 检查是否已登录 npm，或者是否有发布权限：
+```bash
+npm whoami
+npm owner ls jinbi-utils
+```
+
+### Q: 如何发布 beta 版本？
+
+A: 使用 `npm run release:beta`，这会创建类似 `1.0.9-beta.0` 的版本
+
+### Q: 如何跳过某个步骤？
+
+A: 可以手动执行命令，例如只更新版本号不发布：
+```bash
+npm run build
+standard-version --release-as patch
+# 不执行 npm publish
+```
+
+### Q: CHANGELOG 没有正确生成？
+
+A: 确保 commit 信息遵循规范，使用 `feat:`、`fix:` 等前缀
+
+## 📚 相关资源
+
+- [语义化版本规范](https://semver.org/lang/zh-CN/)
+- [Conventional Commits](https://www.conventionalcommits.org/zh-hans/)
+- [standard-version 文档](https://github.com/conventional-changelog/standard-version)
+- [npm 发布文档](https://docs.npmjs.com/cli/v8/commands/npm-publish)
+
+## 🎉 发布成功后
+
+1. ✅ 检查 npm 上的版本：https://www.npmjs.com/package/jinbi-utils
+2. ✅ 检查 CHANGELOG.md 是否正确生成
+3. ✅ 通知团队成员更新依赖
+4. ✅ 更新相关文档（如果需要）
+

package/api-extractor.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "./types/index.d.ts",
+  "bundledPackages": [ ],
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "./types/index.d.ts"
+  },
+  "docModel": {
+    "enabled": true
+  },
+  "apiReport": {
+    "enabled": true
+  }
+}

package/commitlint.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+};

package/jest.config.js

@@ -0,0 +1,15 @@
+module.exports = {
+  testEnvironment: 'jsdom',
+  testEnvironmentOptions: {
+    url: 'http://localhost'
+  },
+  preset: 'ts-jest',
+  rootDir: './',
+  collectCoverage: false,
+  transformIgnorePatterns: ["/node_modules/"],
+  moduleFileExtensions: ["js", "ts", "tsx"],
+  transform: {
+    '^.+\\.js$': 'babel-jest',
+    '.*\\.(ts)$': 'ts-jest',
+  },
+}