@aitianyu.cn/types 0.1.2 → 0.1.3

package/doc/zh/README.md

@@ -0,0 +1,372 @@
+# @aitianyu.cn/types — 中文文档
+
+> aitianyu 生态系统的通用基础模块（类型、函数、类）。
+> 同时支持 Node.js 和浏览器运行环境。
+
+---
+
+## 目录
+
+- [项目简介](#项目简介)
+- [项目结构](#项目结构)
+- [安装](#安装)
+- [使用说明](#使用说明)
+  - [核心工具](#核心工具)
+  - [对象帮助工具](#对象帮助工具)
+  - [安全模块](#安全模块)
+  - [类型定义](#类型定义)
+- [构建与测试](#构建与测试)
+
+---
+
+## 项目简介
+
+`@aitianyu.cn/types` 是 aitianyu Node.js 生态系统的基础工具包，提供以下功能：
+
+- **强类型基础定义** — 供所有 aitianyu 包共享的接口、枚举和泛型帮助类型。
+- **核心运行时工具** — 结构化日志、运行环境检测、类型转换及自定义异常。
+- **对象操作帮助工具** — 深度克隆、深度比较、字符串格式化、字节操作和 JSON 工具。
+- **安全工具** — TOTP（RFC 6238）、Base32 编解码、UUID/GUID 生成、SHA 哈希、RSA 加密及二维码生成。
+- **路径处理** — 跨平台文件/目录路径解析与校验。
+
+本库以 CommonJS 格式发布，并附带完整的 TypeScript 声明文件，可直接用于 TypeScript 或 JavaScript 项目。
+
+---
+
+## 项目结构
+
+```
+tianyu-types/
+├── src/                        # TypeScript 源代码
+│   ├── index.ts                # 主导出入口
+│   ├── coding/                 # 路径编码与错误类型
+│   │   ├── Error.ts            # 路径相关异常
+│   │   └── Path.ts             # Path 类及 PathTargetType 枚举
+│   ├── core/                   # 核心运行时工具
+│   │   ├── Environment.ts      # 运行环境检测（node / browser）
+│   │   ├── Errors.ts           # 自定义异常类
+│   │   ├── Language.ts         # 区域码 / 语言环境帮助函数
+│   │   ├── Log.ts              # 结构化日志与性能跟踪
+│   │   ├── TypeConvertion.ts   # 类型转换帮助函数（如 getBoolean）
+│   │   ├── interface/
+│   │   │   ├── ITJSON.ts       # JSON 类型接口
+│   │   │   └── ITianyuType.ts  # aitianyu 基础类型接口
+│   │   ├── object/             # 对象 / 数据结构帮助工具
+│   │   │   ├── ArrayHelper.ts  # 数组工具
+│   │   │   ├── Bytes.ts        # 随机字节缓冲区生成
+│   │   │   ├── Calculater.ts   # 数学计算
+│   │   │   ├── DataView.ts     # 二进制 DataView 工具
+│   │   │   ├── Integer.ts      # 位运算 / 随机整数帮助函数
+│   │   │   ├── Json.ts         # JSON 处理工具
+│   │   │   ├── ObjectHelper.ts # 深度克隆、比较、校验
+│   │   │   └── StringHelper.ts # 字符串格式化与序列化
+│   │   └── type/               # 类型包装类
+│   │       ├── TArray.ts
+│   │       ├── TBoolean.ts
+│   │       ├── TJSON.ts
+│   │       ├── TNumber.ts
+│   │       ├── TObject.ts
+│   │       └── TString.ts
+│   ├── security/               # 安全与密码学工具
+│   │   ├── Base32.ts           # Base32 编解码（RFC3548、RFC4648、Crockford）
+│   │   ├── Guid.ts             # UUID v4 生成
+│   │   ├── Hash.ts             # 通用哈希操作
+│   │   ├── QRCode.ts           # 二维码图片生成（base64）
+│   │   ├── RSA.ts              # RSA 加密 / 解密
+│   │   ├── SHA.ts              # SHA 哈希函数
+│   │   └── TOTP.ts             # 基于时间的一次性密码（RFC 6238）
+│   └── types/                  # 纯类型定义与接口
+│       ├── AreaCode.ts         # 国际区域码枚举（200+ 语言环境）
+│       ├── Exception.ts        # 基础 Exception 类
+│       ├── Logs.ts             # LogLevel 枚举与日志接口
+│       ├── Object.ts           # 对象差异追踪类型
+│       ├── PathBase.ts         # 抽象路径基类
+│       ├── Security.ts         # EncryptOption 枚举与 ICipher 接口
+│       ├── TMap.ts             # 泛型 TMap 数据结构
+│       ├── Types.ts            # 通用泛型类型与接口
+│       └── index.ts            # 类型桶形导出
+├── test/                       # Jest 测试套件（目录结构镜像 src/）
+├── dist/                       # 编译输出（自动生成，不提交）
+│   ├── lib/                    # CommonJS JavaScript 文件
+│   └── types/                  # TypeScript 声明文件
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+└── eslint.config.ts
+```
+
+---
+
+## 安装
+
+```bash
+npm install @aitianyu.cn/types
+```
+
+运行要求：Node.js ≥ 14 或现代浏览器环境。
+
+---
+
+## 使用说明
+
+### 核心工具
+
+#### 日志
+
+```typescript
+import { Log, Performance } from "@aitianyu.cn/types";
+
+Log.info("服务器已在 3000 端口启动");
+Log.warn("调用了已废弃的 API");
+Log.error("未处理的异常", err);
+Log.debug("配置已加载", config);
+
+// 性能跟踪
+const perf = Performance.startPerf("db-query");
+// ... 执行操作 ...
+Performance.endPerf(perf);
+```
+
+可用日志级别：`DEBUG`、`INFO`、`WARNING`、`ERROR`、`FATAL`、`LOG`
+
+#### 运行环境检测
+
+```typescript
+import { Environment } from "@aitianyu.cn/types";
+
+const env = Environment.runtimeEnv(); // "node" | "browser"
+```
+
+#### 类型转换
+
+```typescript
+import { getBoolean } from "@aitianyu.cn/types";
+
+getBoolean(1);        // true
+getBoolean("false");  // false
+getBoolean(null);     // false
+```
+
+#### 自定义异常
+
+```typescript
+import { ArgumentNullOrEmptyException, Exception } from "@aitianyu.cn/types";
+
+throw new ArgumentNullOrEmptyException("userId");
+```
+
+可用异常类：
+- `ArgumentNullOrEmptyException` — 参数为空或 null
+- `ObjectCloneFunctionNotSupportException` — 对象不支持克隆函数
+- `ObjectMergeStatusCheckFailedException` — 对象合并状态校验失败
+- `ObjectDiffApplyInvalidStatusException` — 差异应用状态无效
+- `ObjectDiffMergeFailedException` — 差异合并失败
+- `PathProcessorSourceLostException` — 路径处理器源丢失
+- `PathDirectoryValidationFailException` — 路径目录校验失败
+
+---
+
+### 对象帮助工具
+
+#### 字符串格式化
+
+```typescript
+import { StringHelper } from "@aitianyu.cn/types";
+
+// 位置占位符（类似 C# String.Format）
+StringHelper.format("你好，{0}！你有 {1} 条消息。", "Alice", 5);
+// => "你好，Alice！你有 5 条消息。"
+
+// 安全序列化（循环引用时返回 ""）
+StringHelper.stringifySafe(someObject);
+```
+
+#### 深度对象操作
+
+```typescript
+import { ObjectHelper } from "@aitianyu.cn/types";
+
+// 深度克隆
+const copy = ObjectHelper.clone(original);
+
+// 多对象深度相等性比较
+const equal = ObjectHelper.compareObjects(obj1, obj2, obj3);
+
+// 检测原始类型
+ObjectHelper.isSimpleDataType(42);      // true
+ObjectHelper.isSimpleDataType({});      // false
+
+// 校验 JSON 可序列化性
+ObjectHelper.validateSerializable(data);
+```
+
+#### 整数与字节工具
+
+```typescript
+import { Integer, Bytes } from "@aitianyu.cn/types";
+
+const n = Integer.random(0, 100);       // 生成 [0, 100] 范围内的随机整数
+const buf = Bytes.random(16);           // 生成 16 字节的随机 Buffer
+
+// 位运算帮助函数
+Integer.left(value, bits);              // 左移
+Integer.right(value, bits);             // 右移（有符号）
+Integer.xor(a, b);                      // 异或
+```
+
+#### 数组帮助工具
+
+```typescript
+import { ArrayHelper } from "@aitianyu.cn/types";
+
+// 数组操作工具方法
+```
+
+---
+
+### 安全模块
+
+#### UUID / GUID 生成
+
+```typescript
+import { guid } from "@aitianyu.cn/types";
+
+guid();            // "550e8400-e29b-41d4-a716-446655440000"
+guid("no-dash");   // "550e8400e29b41d4a716446655440000"
+```
+
+#### TOTP（基于时间的一次性密码）
+
+```typescript
+import { TOTP } from "@aitianyu.cn/types";
+
+// 生成新的 TOTP 密钥
+const secret = TOTP.generate();
+
+// 获取当前 30 秒时间窗口内的 6 位验证码
+const code = TOTP.code(secret);
+
+// 生成 otpauth:// URI（用于认证器应用 / 二维码扫描）
+const uri = TOTP.getUrl("MyApp", "user@example.com", secret);
+```
+
+#### Base32 编解码
+
+```typescript
+import { Base32 } from "@aitianyu.cn/types";
+
+const encoded = Base32.encode(buffer);                   // 默认使用 RFC4648
+const decoded = Base32.decode(encoded);
+const rand    = Base32.random(16);                       // 生成 16 字符随机 Base32 字符串
+
+// 支持的格式："RFC3548" | "RFC4648" | "RFC4648-HEX" | "Crockford"
+Base32.encode(buffer, "Crockford");
+```
+
+#### SHA 哈希
+
+```typescript
+import { SHA } from "@aitianyu.cn/types";
+
+SHA.sha256("输入数据");
+SHA.hmac("密钥", "消息");
+```
+
+#### RSA 加密
+
+```typescript
+import { RSA } from "@aitianyu.cn/types";
+
+const { publicKey, privateKey } = RSA.generateKeyPair();
+const encrypted = RSA.encrypt(publicKey, "敏感文本");
+const decrypted = RSA.decrypt(privateKey, encrypted);
+```
+
+#### 二维码生成
+
+```typescript
+import { QRCode } from "@aitianyu.cn/types";
+
+// 返回 base64 编码的 PNG data URL
+const dataUrl = await QRCode.getURL("https://example.com");
+```
+
+---
+
+### 类型定义
+
+#### 通用泛型类型
+
+```typescript
+import {
+    MapOfString,
+    MapOfStrings,
+    MapOfBoolean,
+    MapOfType,
+    KeyValuePair,
+    CallbackAction,
+    CallbackActionT,
+    IComparable,
+} from "@aitianyu.cn/types";
+
+const map: MapOfString    = { key: "value" };
+const flags: MapOfBoolean = { enabled: true };
+
+const pair: KeyValuePair<string, number> = { key: "age", value: 30 };
+
+const cb: CallbackActionT<string> = (value) => console.log(value);
+```
+
+#### 区域码
+
+```typescript
+import { AreaCode, parseAreaCode, parseAreaString } from "@aitianyu.cn/types";
+
+const code = AreaCode.zh_CN;                      // 简体中文
+const str  = parseAreaString(AreaCode.en_US);     // "en-US"
+```
+
+#### 路径工具
+
+```typescript
+import { Path, PathTargetType } from "@aitianyu.cn/types";
+
+const p = new Path("/usr/local/bin/node", PathTargetType.File);
+p.directory;   // "/usr/local/bin"
+p.fileName;    // "node"
+```
+
+#### TMap
+
+```typescript
+import { TMap } from "@aitianyu.cn/types";
+
+const map = new TMap<string, number>();
+map.set("a", 1);
+map.get("a");   // 1
+```
+
+---
+
+## 构建与测试
+
+```bash
+# 安装依赖
+npm install
+
+# 编译 TypeScript，生成 dist/
+npm run build
+
+# 运行测试
+npm test
+
+# 运行测试并生成覆盖率报告
+npm run test-all
+
+# 代码检查
+npm run eslint
+```
+
+构建输出目录 `dist/`：
+- `dist/lib/` — CommonJS JavaScript 文件
+- `dist/types/` — TypeScript 声明文件（`.d.ts`）

package/package.json

@@ -1,12 +1,13 @@
 {
     "name": "@aitianyu.cn/types",
-    "version": "0.1.2",
+    "version": "0.1.3",
     "private": false,
     "description": "Common modules (types, functions, classes) for aitianyu",
     "main": "./dist/lib/index.js",
     "types": "./dist/types/index.d.ts",
     "files": [
-        "dist"
+        "dist",
+        "doc"
     ],
     "type": "commonjs",
     "keywords": [