@gaias/client_node 1.0.6 → 1.0.7

package/CONFIG.md

@@ -0,0 +1,608 @@
+# 项目配置文件详解
+
+本文档详细说明 `@gaias/client_node` 项目中所有配置文件的用途和配置项。
+
+## 📦 目录
+
+- [package.json - 项目元数据与依赖管理](#packagejson)
+- [tsconfig.json - TypeScript 编译配置](#tsconfigjson)
+- [eslint.config.js - 代码质量检查配置](#eslintconfigjs)
+- [jest.config.js - 测试框架配置](#jestconfigjs)
+- [.prettierrc.json - 代码格式化配置](#prettierrrcjson)
+- [.ctirc - 索引文件自动生成配置](#ctirc)
+
+---
+
+## package.json
+
+### 基本信息
+
+```json
+{
+  "name": "@gaias/client_node",
+  "version": "1.0.6",
+  "description": "store data in cookie and localstorage",
+  "main": "dist/single/index.js",
+  "types": "dist/single/index.d.ts",
+  "license": "UNLICENSED"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `name` | NPM 包名，使用 `@gaias` 命名空间 |
+| `version` | 当前版本号，遵循语义化版本 (Semver) |
+| `description` | 包描述 |
+| `main` | CommonJS 入口文件 |
+| `types` | TypeScript 类型定义文件入口 |
+| `license` | 许可证类型 |
+
+### 发布配置
+
+```json
+{
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}
+```
+
+- `access`: `public` - 公开发布包
+- `registry`: NPM 官方仓库地址
+
+### 关键词
+
+```json
+{
+  "keywords": [
+    "restclient",
+    "globalstorage",
+    "messageclient",
+    "configclient"
+  ]
+}
+```
+
+用于 NPM 搜索的关键词，提高包的可发现性。
+
+### 引擎要求
+
+```json
+{
+  "engines": {
+    "node": ">=18.0.0",
+    "yarn": ">=1.22.x"
+  }
+}
+```
+
+指定项目运行所需的最低 Node.js 和 Yarn 版本。
+
+### NPM Scripts
+
+#### 构建相关
+
+| Script | 命令 | 说明 |
+|--------|------|------|
+| `ncc:build` | `ncc build ./src/index.ts -m -o ./dist/single -e sqlite3 --no-source-map-register && ncc cache clean` | 使用 `@vercel/ncc` 将代码打包成单文件，排除 sqlite3 依赖 |
+| `prepub` | `rimraf dist && mkdir dist && tsc && mv temp/* dist/ && rimraf temp` | 发布前准备：清理构建目录、运行 TypeScript 编译、移动产物 |
+
+**prepub 命令详解**:
+1. `rimraf dist` - 删除现有的 dist 目录
+2. `mkdir dist` - 创建新的 dist 目录
+3. `tsc` - 使用 TypeScript 编译器编译（输出到 temp 目录）
+4. `mv temp/* dist/` - 将编译产物从 temp 移动到 dist
+5. `rimraf temp` - 删除临时目录
+
+#### 开发相关
+
+| Script | 命令 | 说明 |
+|--------|------|------|
+| `dev` | `http-server` | 启动本地开发服务器 |
+| `upver` | `ncu -u && yarn install` | 更新所有依赖到最新版本 |
+| `gen:idx` | `cti create ./src` | 自动生成 src 目录的 index.ts 文件 |
+
+#### 测试相关
+
+| Script | 命令 | 说明 |
+|--------|------|------|
+| `test` | `jest` | 运行 Jest 测试套件 |
+
+#### 代码质量
+
+| Script | 命令 | 说明 |
+|--------|------|------|
+| `lint` | `tsc --noEmit && eslint . --ext .ts` | 运行类型检查和 ESLint 检查 |
+| `lint:fix` | `eslint . --ext .ts --fix` | 自动修复 ESLint 问题 |
+| `precommit` | `yarn lint` | 提交前运行 lint 检查 |
+
+#### 安全审计
+
+| Script | 命令 | 说明 |
+|--------|------|------|
+| `security` | `yarn audit` | 运行完整的依赖安全审计 |
+| `security:summary` | `yarn audit --summary` | 显示安全审计摘要 |
+| `security:json` | `yarn audit --json` | 以 JSON 格式输出审计结果 |
+| `security:check` | `node tools/security-check.js` | 自定义安全检查脚本 |
+
+### 依赖说明
+
+#### 核心运行时依赖
+
+| 依赖 | 版本 | 说明 |
+|------|------|------|
+| `axios` | ^1.12.2 | HTTP 客户端 |
+| `cls-hooked` | ^4.2.2 | 异步上下文管理 |
+| `dot-object` | ^2.1.5 | 对象路径操作工具 |
+| `eventemitter3` | ^5.0.1 | 事件发射器 |
+| `ioredis` | ^5.8.2 | Redis 客户端 |
+| `js-cookie` | ^3.0.5 | Cookie 操作库 |
+| `js-yaml` | ^4.1.0 | YAML 解析器 |
+| `jsonata` | ^2.1.0 | JSON 查询和转换 |
+| `lodash` | ^4.17.21 | 工具函数库 |
+| `mustache` | ^4.2.0 | 模板引擎 |
+| `storage-manager-js` | ^4.2.6 | 存储管理 |
+| `store2` | ^2.14.4 | 本地存储封装 |
+| `typedi` | ^0.10.0 | 依赖注入容器 |
+| `whatwg-url` | ^15.1.0 | URL 解析 |
+
+#### 开发依赖
+
+主要包括：
+- TypeScript 相关工具链
+- ESLint 及插件
+- Jest 测试框架
+- Prettier 代码格式化
+- @vercel/ncc 打包工具
+
+---
+
+## tsconfig.json
+
+TypeScript 编译器配置文件。
+
+### 编译选项
+
+```json
+{
+  "compilerOptions": {
+    "outDir": "temp",
+    "target": "ES2021",
+    "module": "CommonJS"
+  }
+}
+```
+
+#### 基础配置
+
+| 选项 | 值 | 说明 |
+|------|-----|------|
+| `outDir` | `"temp"` | 编译输出目录（由 prepub 脚本移动到 dist） |
+| `target` | `"ES2021"` | 编译目标 JavaScript 版本 |
+| `module` | `"CommonJS"` | 模块系统类型 |
+| `lib` | `["ES2021"]` | 可用的库文件 |
+| `moduleResolution` | `"node"` | Node.js 风格的模块解析 |
+
+#### 严格模式选项
+
+| 选项 | 值 | 说明 |
+|------|-----|------|
+| `strict` | `true` | 启用所有严格类型检查选项 |
+| `noImplicitAny` | `true` | 禁止隐式 any 类型 |
+| `strictPropertyInitialization` | `false` | 关闭类属性必须初始化的检查 |
+| `forceConsistentCasingInFileNames` | `true` | 强制文件名大小写一致 |
+
+#### 互操作性选项
+
+| 选项 | 值 | 说明 |
+|------|-----|------|
+| `esModuleInterop` | `true` | 允许 CommonJS 和 ES 模块互操作 |
+| `allowSyntheticDefaultImports` | `true` | 允许从没有默认导出的模块导入默认值 |
+| `resolveJsonModule` | `true` | 允许导入 JSON 文件 |
+
+#### 装饰器支持
+
+| 选项 | 值 | 说明 |
+|------|-----|------|
+| `experimentalDecorators` | `true` | 启用实验性装饰器语法 |
+| `emitDecoratorMetadata` | `true` | 为装饰器生成元数据（TypeDI 需要） |
+
+#### 类型声明
+
+| 选项 | 值 | 说明 |
+|------|-----|------|
+| `declaration` | `true` | 生成 .d.ts 类型声明文件 |
+| `declarationMap` | `true` | 生成声明文件的 source map |
+
+#### 调试与优化
+
+| 选项 | 值 | 说明 |
+|------|-----|------|
+| `sourceMap` | `true` | 生成 source map 文件 |
+| `removeComments` | `true` | 移除编译后的注释 |
+| `skipLibCheck` | `true` | 跳过声明文件的类型检查（加快编译） |
+
+#### 路径映射
+
+```json
+{
+  "paths": {
+    "@/*": ["src/*"]
+  },
+  "baseUrl": "."
+}
+```
+
+允许使用 `@/` 作为 `src/` 的别名。
+
+#### 类型声明
+
+```json
+{
+  "types": ["node", "jest"]
+}
+```
+
+包含 Node.js 和 Jest 的类型定义。
+
+### 包含与排除
+
+```json
+{
+  "include": [
+    "src/**/*",
+    "example/**/*",
+    "tools/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "temp",
+    "dist",
+    "**/*.spec.ts",
+    "**/*.test.ts"
+  ]
+}
+```
+
+- **include**: 编译 src、example 和 tools 目录
+- **exclude**: 排除 node_modules、构建产物和测试文件
+
+---
+
+## eslint.config.js
+
+ESLint 9.x 新版扁平化配置格式。
+
+### 配置结构
+
+项目使用多配置策略，针对不同目录应用不同的规则：
+
+#### 1. 忽略文件
+
+```javascript
+{
+  ignores: [
+    '**/node_modules/**',
+    '**/temp/**',
+    '**/dist/**',
+    '**/*.js',
+    '**/*.d.ts',
+  ]
+}
+```
+
+排除不需要检查的文件和目录。
+
+#### 2. src/ 和 example/ 目录配置
+
+**特点**: 启用类型感知的 lint 规则
+
+```javascript
+{
+  files: ['src/**/*.ts', 'example/**/*.ts'],
+  languageOptions: {
+    parser: tsParser,
+    parserOptions: {
+      project: './tsconfig.json'  // 使用项目配置进行类型检查
+    }
+  }
+}
+```
+
+**启用的类型感知规则**:
+- `@typescript-eslint/no-floating-promises`: 'warn' - 警告未处理的 Promise
+- `@typescript-eslint/await-thenable`: 'warn' - 避免 await 非 thenable 对象
+- `@typescript-eslint/no-misused-promises`: 'warn' - Promise 误用检查
+
+#### 3. tools/ 目录配置
+
+**特点**: 不启用类型检查（提高性能）
+
+```javascript
+{
+  files: ['tools/**/*.ts'],
+  languageOptions: {
+    parserOptions: {
+      // ✅ 不使用 project，避免解析错误
+    }
+  }
+}
+```
+
+#### 4. __tests__ 目录配置
+
+**特点**: 测试文件专用配置
+
+### 通用规则设置
+
+| 规则 | 设置 | 说明 |
+|------|------|------|
+| `@typescript-eslint/no-require-imports` | off | 允许使用 require() |
+| `@typescript-eslint/no-var-requires` | off | 允许 require 赋值给变量 |
+| `@typescript-eslint/explicit-function-return-type` | off | 不强制函数返回类型声明 |
+| `@typescript-eslint/no-explicit-any` | off | 允许使用 any 类型 |
+| `@typescript-eslint/no-unused-vars` | off | 不检查未使用变量 |
+| `no-console` | off | 允许使用 console |
+| `lines-between-class-members` | warn | 类成员之间需要空行 |
+
+---
+
+## jest.config.js
+
+Jest 测试框架配置。
+
+```javascript
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    setupFiles: ['reflect-metadata'],
+};
+```
+
+### 配置说明
+
+| 选项 | 值 | 说明 |
+|------|-----|------|
+| `preset` | `'ts-jest'` | 使用 ts-jest 预设，支持 TypeScript |
+| `testEnvironment` | `'node'` | 在 Node.js 环境中运行测试 |
+| `setupFiles` | `['reflect-metadata']` | 测试前加载 reflect-metadata（装饰器元数据支持） |
+
+### 使用方式
+
+```bash
+# 运行所有测试
+yarn test
+
+# 运行特定测试文件
+yarn test path/to/test.spec.ts
+```
+
+---
+
+## .prettierrc.json
+
+Prettier 代码格式化配置。
+
+```json
+{
+    "semi": true,
+    "trailingComma": "all",
+    "singleQuote": true,
+    "printWidth": 220,
+    "tabWidth": 4,
+    "arrowParens": "always"
+}
+```
+
+### 配置说明
+
+| 选项 | 值 | 说明 |
+|------|-----|------|
+| `semi` | `true` | 语句末尾添加分号 |
+| `trailingComma` | `"all"` | 在所有可能的地方添加尾随逗号 |
+| `singleQuote` | `true` | 使用单引号而非双引号 |
+| `printWidth` | `220` | 单行最大字符数（较宽） |
+| `tabWidth` | `4` | 缩进宽度为 4 个空格 |
+| `arrowParens` | `"always"` | 箭头函数参数始终使用括号 |
+
+### 格式化示例
+
+**Before:**
+```typescript
+const foo = (x) => {return x + 1}
+const obj = {a: 1, b: 2}
+```
+
+**After:**
+```typescript
+const foo = (x) => {
+    return x + 1;
+};
+const obj = { a: 1, b: 2 };
+```
+
+---
+
+## .ctirc
+
+`create-ts-index` (cti) 工具配置，用于自动生成 TypeScript 索引文件。
+
+### 配置说明
+
+```json
+{
+  "fileFirst": false,
+  "addNewline": true,
+  "useSemicolon": true,
+  "useTimestamp": false,
+  "includeCWD": true,
+  "excludes": ["__test__", "__tests__", "node_modules", "tools"],
+  "fileExcludePatterns": ["*excludeme.ts"],
+  "targetExts": ["ts", "tsx"],
+  "withoutBackupFile": true,
+  "quote": "'",
+  "verbose": false
+}
+```
+
+| 选项 | 值 | 说明 |
+|------|-----|------|
+| `fileFirst` | `false` | 不优先导出文件 |
+| `addNewline` | `true` | 文件末尾添加换行符 |
+| `useSemicolon` | `true` | 导出语句添加分号 |
+| `useTimestamp` | `false` | 不在注释中添加时间戳 |
+| `includeCWD` | `true` | 包含当前工作目录 |
+| `excludes` | `[...]` | 排除的目录 |
+| `targetExts` | `["ts", "tsx"]` | 目标文件扩展名 |
+| `withoutBackupFile` | `true` | 不创建备份文件 |
+| `quote` | `"'"` | 使用单引号 |
+| `verbose` | `false` | 不显示详细日志 |
+
+### 使用方式
+
+```bash
+# 生成 src 目录的 index.ts
+yarn gen:idx
+```
+
+### 生成示例
+
+对于目录结构：
+```
+src/
+  ├── foo.ts
+  ├── bar.ts
+  └── utils/
+      └── helper.ts
+```
+
+生成的 `src/index.ts`:
+```typescript
+export * from './foo';
+export * from './bar';
+export * from './utils/helper';
+```
+
+---
+
+## 构建流程
+
+### 完整发布流程
+
+1. **清理旧构建**:   `rimraf dist`
+2. **创建目录**:     `mkdir dist`
+3. **TypeScript 编译**: `tsc` (输出到 temp)
+4. **移动产物**: `mv temp/* dist/`
+5. **清理临时文件**: `rimraf temp`
+6. **单文件打包**: `yarn ncc:build` (可选)
+
+### 输出结构
+
+```
+dist/
+  ├── index.js          # CommonJS 主入口
+  ├── index.d.ts        # 类型定义
+  ├── index.d.ts.map    # 类型定义 source map
+  └── ...               # 其他编译产物
+
+dist/single/
+  └── index.js          # NCC 打包的单文件 (包含所有依赖)
+```
+
+---
+
+## 最佳实践
+
+### 开发工作流
+
+1. **启动开发**: `yarn dev`
+2. **自动生成索引**: `yarn gen:idx`
+3. **代码检查**: `yarn lint`
+4. **运行测试**: `yarn test`
+5. **发布前构建**: `yarn prepub`
+
+### 版本发布
+
+```bash
+# 1. 更新版本号
+npm version patch  # 或 minor/major
+
+# 2. 构建
+yarn prepub
+
+# 3. 发布到 NPM
+npm publish --access public
+
+# 4. 推送标签
+git push origin main --follow-tags
+```
+
+详细发布流程请参考 [PUBLISHING.md](./PUBLISHING.md)。
+
+### 依赖更新
+
+```bash
+# 检查可更新的依赖
+ncu
+
+# 更新所有依赖
+yarn upver
+
+# 安全审计
+yarn security
+```
+
+---
+
+## 故障排除
+
+### TypeScript 编译错误
+
+```bash
+# 只进行类型检查，不生成文件
+yarn lint
+
+# 查看详细错误信息
+tsc --noEmit
+```
+
+### ESLint 配置问题
+
+- **错误**: "Parsing error: Cannot read file 'tsconfig.json'"
+  - **解决**: 确保 `tsconfig.json` 在项目根目录
+  - **说明**: tools 和 __tests__ 目录不需要 project 配置
+
+### 构建产物问题
+
+```bash
+# 清理所有构建产物
+rimraf dist temp
+
+# 重新构建
+yarn prepub
+```
+
+### Jest 测试失败
+
+- **错误**: "Cannot find module 'reflect-metadata'"
+  - **解决**: 确保 `setupFiles` 包含 'reflect-metadata'
+  - **说明**: TypeDI 装饰器需要元数据反射支持
+
+---
+
+## 相关文档
+
+- [发布指南](./PUBLISHING.md)
+- [TypeScript 官方文档](https://www.typescriptlang.org/tsconfig)
+- [ESLint 配置文档](https://eslint.org/docs/latest/use/configure/)
+- [Jest 配置文档](https://jestjs.io/docs/configuration)
+- [Prettier 配置文档](https://prettier.io/docs/en/options.html)
+
+---
+
+## 更新日志
+
+| 日期 | 版本 | 说明 |
+|------|------|------|
+| 2025-10-23 | 1.0.0 | 初始版本 |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gaias/client_node",
-    "version": "1.0.6",
+    "version": "1.0.7",
     "description": "store data in cookie and localstorage",
     "main": "dist/single/index.js",
     "types": "dist/single/index.d.ts",