@fast-china/utils 1.0.38 → 2.0.2

package/docs/API.zh-CN.md

@@ -0,0 +1,112 @@
+# Fast.Utils API
+
+Fast.Utils 是面向浏览器的 ES2022 工具包；包管理器使用 ESM 入口，CDN 使用单独压缩的 IIFE 入口。应用环境包括现代浏览器、WebView、Vue 3 和 uni-app。
+
+## 导入
+
+包只提供一个公开根入口，包含普通工具和 Vue Helper 在内的全部 API 均使用具名导出。
+
+```ts
+import { chunk, configureStorage, installationIdentity, Local } from "@fast-china/utils";
+```
+
+内部 Helper 不提供公共子路径。库不再导出工具聚合对象，调用方应直接导入具名函数，以便 Tree Shaking。
+
+## Storage
+
+`Local` 和 `Session` 会以旧版兼容的 `fast__` 前缀、JSON Codec 与 `Date.now` 延迟初始化。除非需要覆盖默认值，否则无需调用 `configureStorage`。
+
+```ts
+import { Local, Session } from "@fast-china/utils";
+
+Local.set("profile", { name: "Ada" }, { ttlMs: 3_600_000 });
+Session.set("draft", { step: 2 });
+```
+
+`Local` 和 `Session` 提供 `get`、`set`、`has`、`remove`、`removeByPrefix`、`keys`、`pruneExpired` 和仅清理当前命名空间的 `clear`。键缺失或过期时返回 `undefined`。TTL 非法、Prefix 为空、存储包络损坏、平台 Storage 不可用或重复配置发生冲突时抛出错误；浏览器配额与隐私策略错误直接向上传播。自定义选项必须在首次 Storage 操作前配置。
+
+uni-app 中，首次 Storage 操作或显式调用 `configureStorage` 会自动检测全局 `uni` 并使用其同步 Storage API。uni-app 没有独立 Session 后端，因此该模式调用 `Session` 会明确抛错。
+
+```ts
+import { Local } from "@fast-china/utils";
+
+Local.set("token", "value");
+```
+
+`configureStorage({ prefix: "admin:", crypto: true })` 恢复了旧版全局前缀与 Base64 混淆选项。`crypto: true` 和 `base64StorageCodec` 都只是可逆编码，不是加密，不能保护敏感数据。可以使用自定义 `codec` 替代 `crypto`。
+
+`encodeSecureBase64` 与 `decodeSecureBase64` 保留旧字典兼容载荷，并使用 Web Crypto 生成安全随机前缀。给定相同的默认 6 字符前缀时，有效旧载荷保持逐字符兼容；旧字典在 Base64 长度 101–124 时会引用越界，当前实现使用单字符回退，旧删除字典流程仍可解码。旧自定义长度参数始终生成 6 个随机字符，当前 API 已按 `prefixLength` 正确生成。自定义 `prefixLength` 必须在编码和解码时保持一致；传入 `0` 会同时关闭随机前缀与字典插入。该格式仍是可逆编码，不等同于加密。
+
+## Identity
+
+`installationIdentity` 是全局安装标识门面。可在程序入口、首次使用前调用 `configureInstallationIdentity` 覆盖默认缓存键 `identity:installation-id`。`getOrCreateInstallationId(installationId?)` 会通过 `Local` 读取、生成或替换 UUID v4；未显式配置 Storage 时使用其默认值。UUID 生成依赖 Web Crypto，不会回退到 `Math.random()`。
+
+```ts
+import { configureInstallationIdentity, configureStorage, getOrCreateInstallationId, installationIdentity } from "@fast-china/utils";
+
+configureStorage({ prefix: "app:" });
+configureInstallationIdentity({ cacheKey: "account:installation-id" });
+getOrCreateInstallationId();
+installationIdentity.read();
+installationIdentity.clear();
+```
+
+这个 ID 只标识当前存储空间中的安装实例，不是硬件标识、认证凭证、秘密或反欺诈信号。
+
+## Logger
+
+Logger 作用域属于每条日志，不保存在可变 Logger 或 Child 实例中：
+
+```ts
+import { logger } from "@fast-china/utils";
+
+logger.info("storage", "profile loaded", { userId: 1 });
+logger.error("network", "request failed", error);
+```
+
+`createLogger` 只配置最低级别、品牌前缀、Sink 和可选的 uni-app App-Plus 拆分输出。作用域必须是无外围空白的非空字符串。
+
+## Crypto
+
+TypeScript Crypto 公共 API 与 .NET `CryptoUtil` 的公开方法及算法名称大小写保持一致：
+
+| 能力                     | 两端统一的方法名                                                                                                                     |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| 安全随机与字节比较       | `GenerateRandomBytes`、`FixedTimeEquals`                                                                                             |
+| MD5、SHA-1 与 SHA-2 摘要 | `MD5Encrypt`、`SHA1Encrypt`、`SHA256Encrypt`、`SHA256Bytes`、`SHA384Encrypt`、`SHA384Bytes`、`SHA512Encrypt`、`SHA512Bytes`          |
+| HMAC                     | `HMACSHA256Encrypt`、`HMACSHA384Encrypt`、`HMACSHA512Encrypt`                                                                        |
+| 密码派生与密码哈希       | `PBKDF2SHA256`、`HashPasswordPBKDF2SHA256`、`VerifyPasswordPBKDF2SHA256`                                                             |
+| HKDF                     | `HKDFSHA256`                                                                                                                         |
+| AES                      | `AESEncrypt`、`AESDecrypt`、`AESEncryptAuthenticated`、`AESDecryptAuthenticated`、`AESEncryptWithPassword`、`AESDecryptWithPassword` |
+| RSA                      | `GenerateRSAKeyPair`、`RSAEncryptOAEP`、`RSADecryptOAEP`、`RSASignPSS`、`RSAVerifyPSS`                                               |
+| 椭圆曲线                 | `GenerateECDSAKeyPair`、`ECDSASign`、`ECDSAVerify`、`GenerateECDHKeyPair`、`DeriveECDHSecret`、`DeriveECDHKeySHA256`                 |
+
+`AESEncryptAuthenticated` 的 Base64 v1 载荷、`AESEncryptWithPassword` 的 `FAST-AES-256-GCM-V2` 载荷、PBKDF2 密码哈希以及 PKCS#8/SPKI PEM 密钥均可与 .NET 双向使用。MD5 与 HMAC 输出小写十六进制；SHA-1/256/384/512 输出大写十六进制，与 .NET 保持一致。
+
+密码存储使用 `HashPasswordPBKDF2SHA256` 和 `VerifyPasswordPBKDF2SHA256`；该哈希不可解密。需要同时保证机密性和完整性的文本使用 AES-GCM 入口。HMAC 用于共享密钥认证，SHA-2 用于摘要，HKDF/PBKDF2 用于密钥派生。MD5、SHA-1、AES-CBC 和 AES-ECB 不提供现代密码存储或认证加密保证。
+
+## 模块
+
+- `array`：分块、压缩、去重、分组、分区、差集、交集和一致性判断。
+- `async`：支持取消的 Sleep、超时、重试、受限并发映射、防抖和节流。
+- `base64`：严格 UTF-8 Base64/Base64URL 字节与文本函数，以及 Latin-1 和 SecureBase64 兼容函数。
+- `color`：颜色解析、格式化、混合、明暗、亮度和对比度。
+- `crypto`：安全随机、摘要、HMAC、PBKDF2、HKDF、AES、RSA-OAEP/PSS、ECDSA 和 ECDH。
+- `date`：日期校验、加减、日范围、相对时间，以及七个历史日期功能的具名函数。
+- `dom`：CSS 单位和 Style 序列化。
+- `env`：能力与 User-Agent 检测；检测函数不扩大运行时支持范围。
+- `logger`：隔离的可配置 Logger 和默认 `logger`。
+- `number`：范围、舍入、聚合、插值、字节格式化和安全随机整数。
+- `object`：防原型污染的选择、比较、映射和 Query 序列化；Style 序列化由 `dom` 模块提供。
+- `string`：Query 解析、大小写、字素截断、UUID、安全随机文本、转义和空白规范化。
+- `vue`：Vue 3 的 Composition API、类型、Render 和 `app.use()` 注册 Helper。
+
+## 安全与限制
+
+AES-GCM 提供机密性和完整性；AES-CBC/ECB 不提供认证。MD5、SHA-1 和历史 Base64 字典不能用于密码存储、签名或受保护数据。Crypto API 按算法限制参数和载荷大小，并在需要时强制要求 Web Crypto。
+
+Query 与 Object API 拒绝原型污染键，URL 解码有最大深度，Storage 清理只作用于配置的命名空间。浏览器全局对象只在调用 API 时解析，模块导入阶段不会访问。
+
+## 错误与兼容性
+
+除明确说明返回空值的函数外，编程错误、非法输入、平台能力缺失和受保护数据损坏均抛出原生错误。

package/docs/DEVELOPMENT_RELEASE.zh-CN.md

@@ -0,0 +1,65 @@
+# Fast.Utils 开发与发布
+
+## 基线
+
+- Node.js：`^22.18.0 || ^24.18.0`。
+- pnpm：`^11.0.0`，不固定补丁版本。
+- TypeScript 6、tsdown、ESLint 10 Flat Config、Prettier 3。
+- 发布格式：包管理器使用 ESM、`.mjs` 与 `.d.mts`，CDN 使用压缩 IIFE；两类 JavaScript 产物均提供 Source Map。
+- 根目录是唯一 npm 发布单元，根 `dist/` 是唯一产物目录。
+
+应用环境包括现代浏览器、WebView、Vue 3 和 uni-app。
+
+## 安装与命令
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+```
+
+| 命令                | 用途                                                                   |
+| ------------------- | ---------------------------------------------------------------------- |
+| `pnpm dev`          | 使用 tsdown 监听源码并增量构建                                         |
+| `pnpm build`        | 使用 tsdown 构建 ESM 模块与压缩 IIFE                                   |
+| `pnpm typecheck`    | 检查源码与构建配置类型                                                 |
+| `pnpm lint`         | 运行零警告 ESLint                                                      |
+| `pnpm format:check` | 检查 Prettier                                                          |
+| `pnpm test:types`   | 验证公开消费者类型                                                     |
+| `pnpm test:runtime` | 运行单元、平台与 Vue Runtime 测试                                      |
+| `pnpm test:package` | 验证 Tarball、公开入口、声明、Source Map、Tree Shaking、体积与 Publint |
+| `pnpm check`        | 运行统一质量门禁                                                       |
+
+## 修改公共模块
+
+新增公共模块时必须同步：
+
+1. 在 `src/<module>/index.ts` 定义具名 API 和 TSDoc。
+2. 在 `src/index.ts` 统一重新导出公共 API。
+3. 不为模块增加 `package.json#exports` 子路径或独立构建入口。
+4. 增加源码类型、消费者类型、单元和真实包测试。
+5. 更新双语 README、API 和 Changelog。
+
+禁止在导入阶段访问浏览器或 uni-app 全局对象。平台能力应在调用阶段解析；`configureStorage` 在调用时自动检测全局 `uni`。
+
+## 依赖与锁文件
+
+- Runtime Dependency 必须证明无法由平台能力或小型实现替代。
+- Vue 3.3+ 是必须安装的 Peer Dependency；ESM 与 IIFE 均保持外部引用，不打包进发布产物。
+- 依赖升级后使用当前 pnpm 11 更新 Lockfile，并通过 Frozen Lockfile 安装验证。
+- 不混用 npm、Yarn 或不同 pnpm 主版本改写 Lockfile。
+
+## CI
+
+CI 在 Node 22 与 24 上运行，使用 Frozen Lockfile，并执行 `pnpm check` 与 Pack Dry Run。不得通过关闭类型、Lint、测试或包验证来修复门禁。
+
+## 发布
+
+仓库只采用人工发布流程，不声明或配置 OIDC Trusted Publishing：
+
+1. 更新 SemVer 与 `CHANGELOG.md` 日期。
+2. 执行 `pnpm install --frozen-lockfile`。
+3. 执行 `pnpm check`。
+4. 人工检查 `pnpm --config.ignore-scripts=true pack --dry-run` 清单。
+5. 由维护者在可信环境执行 npm Publish，并创建对应 `v<version>` Tag。
+
+未经明确授权，不执行 Publish、Push、Tag 或 Release。npm 已发布版本不可覆盖；发布后缺陷必须通过新 Patch 或 Pre-release 修复。

package/docs/RUNTIME_CONTRACT.md

@@ -0,0 +1,37 @@
+# Fast.Utils runtime contract / 运行时契约
+
+## Runtime and package contract
+
+- Runtime platforms: ES2022 modern browsers, WebViews, Vue 3 applications, and uni-app.
+- Package format: one public named-export ESM entry for package managers and one separately minified IIFE entry for CDN use; CommonJS and UMD are not shipped.
+- Framework boundary: Vue remains external to the package-manager build and is a required peer in `^3.3.0`.
+- uni-app boundary: the first Storage operation, or an earlier `configureStorage({ prefix })` call, detects global `uni` and uses its synchronous Storage API.
+- Browser storage: applications import `Local` and `Session` directly; `configureStorage()` is needed only to override defaults before the first operation.
+- Stateful browser defaults: Storage and Identity configuration are page-global by design. Conflicting reconfiguration throws.
+- Security: secure random APIs require Web Crypto and never fall back to `Math.random()`.
+- Publishing: the repository root is the only package, `dist/` is the only build output, and `package.json#exports` is the complete public path whitelist.
+
+Importing a module does not itself read `window`, browser Storage, or `uni`, so unsupported platform capabilities fail only when the corresponding API is called.
+
+## Public API policy
+
+- Stateless Array, Date, String, Number, Object, Base64, Color, DOM, Env, Async, and Crypto capabilities use named exports.
+- The public API uses named functions instead of mutable aggregate utility objects.
+- Stateful browser capabilities use cohesive package-owned objects: `Local`, `Session`, `installationIdentity`, and logger instances. Logger scope is supplied to each severity method rather than stored in child instances.
+- Internal adapters and client factories are implementation details and are not public export paths.
+- Removing a named function, changing Storage/ciphertext formats, raising the browser syntax target, or changing the Vue peer range requires an explicit major-version Breaking Change.
+
+## 运行时与包契约
+
+- 运行平台：ES2022 现代浏览器、WebView、Vue 3 应用和 uni-app。
+- 包格式：包管理器使用单一公开具名导出 ESM 入口，CDN 使用单独压缩的 IIFE；不发布 CommonJS 或 UMD。
+- Vue 边界：Vue 不会打进包管理器使用的构建产物，是 `^3.3.0` 的必需 Peer。
+- uni-app：首次 Storage 操作或更早的 `configureStorage({ prefix })` 调用会检测全局 `uni`，并使用其同步 Storage API。
+- Storage：直接从包导入 `Local` 和 `Session` 即可；只有覆盖默认值时才需在首次操作前调用 `configureStorage()`。
+- 状态：Storage 与 Identity 配置按浏览器页面全局共享；冲突配置明确抛错。
+- 安全随机：要求 Web Crypto，禁止回退 `Math.random()`。
+- 发布：根目录是唯一 npm 包，`dist/` 是唯一构建输出，`exports` 是完整公共路径白名单。
+
+模块导入本身不读取 `window`、浏览器 Storage 或 `uni`，不具备对应平台能力时只在调用相关 API 时明确失败。
+
+无状态能力统一使用具名导出。有状态浏览器能力使用 `Local`、`Session`、`installationIdentity` 和 Logger 实例；Logger 作用域随每次级别方法调用传入，不创建 Child Logger。

package/package.json

@@ -1,104 +1,94 @@
 {
 	"name": "@fast-china/utils",
-	"version": "1.0.38",
-	"description": "Fast 工具库.",
+	"version": "2.0.2",
+	"description": "Typed utilities for modern browsers, WebViews, Vue 3, and uni-app applications.",
 	"type": "module",
 	"keywords": [
-		"fast-china",
 		"fast",
+		"fast-china",
 		"typescript",
 		"utils"
 	],
 	"license": "Apache-2.0",
 	"homepage": "https://fastdotnet.com",
 	"bugs": {
-		"url": "https://gitee.com/FastDotnet/Fast.Utils/issues"
+		"url": "https://gitee.com/FastDotnet/fast.utils/issues"
 	},
 	"repository": {
 		"type": "git",
-		"url": "https://gitee.com/FastDotnet/Fast.Utils"
+		"url": "https://gitee.com/FastDotnet/fast.utils"
 	},
 	"author": "小方",
 	"files": [
-		"./Fast.png",
-		"./LICENSE",
-		"./README.md",
-		"./README.zh.md",
-		"./dist",
-		"./es",
-		"./lib"
+		"CHANGELOG.md",
+		"CONTRIBUTING.md",
+		"Fast.png",
+		"LICENSE",
+		"README.md",
+		"README.zh.md",
+		"SECURITY.md",
+		"dist",
+		"docs"
 	],
-	"main": "lib/index.js",
-	"module": "es/index.mjs",
-	"types": "es/index.d.ts",
+	"main": "./dist/index.mjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
 	"exports": {
 		".": {
-			"types": "./es/index.d.ts",
-			"require": "./lib/index.js",
-			"import": "./es/index.mjs"
-		},
-		"./es": {
-			"types": "./es/index.d.ts",
-			"import": "./es/index.mjs"
-		},
-		"./lib": {
-			"types": "./lib/index.d.ts",
-			"require": "./lib/index.js"
-		},
-		"./es/*.mjs": {
-			"types": "./es/*.d.ts",
-			"import": "./es/*.mjs"
-		},
-		"./es/*": {
-			"types": [
-				"./es/*.d.ts",
-				"./es/*/index.d.ts"
-			],
-			"import": "./es/*.mjs"
-		},
-		"./lib/*.js": {
-			"types": "./lib/*.d.ts",
-			"require": "./lib/*.js"
-		},
-		"./lib/*": {
-			"types": [
-				"./lib/*.d.ts",
-				"./lib/*/index.d.ts"
-			],
-			"require": "./lib/*.js"
-		},
-		"./*": "./*"
+			"types": "./dist/index.d.mts",
+			"import": "./dist/index.mjs",
+			"default": "./dist/index.mjs"
+		}
 	},
-	"unpkg": "dist/index.global.min.js",
-	"jsdelivr": "dist/index.global.min.js",
+	"sideEffects": false,
+	"unpkg": "./dist/index.global.min.js",
+	"jsdelivr": "./dist/index.global.min.js",
 	"publishConfig": {
 		"access": "public"
 	},
+	"scripts": {
+		"dev": "tsdown --watch",
+		"build": "tsdown",
+		"typecheck": "tsc --noEmit",
+		"lint": "eslint . --max-warnings 0",
+		"lint:fix": "eslint . --fix",
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"test": "pnpm run build && pnpm run test:types && pnpm run test:runtime && pnpm run test:package",
+		"test:types": "tsc --noEmit --project tests/tsconfig.json",
+		"test:runtime": "node --import tsx --test tests/async.test.ts tests/core.test.ts tests/storage-crypto.test.ts tests/storage-default.test.ts tests/storage-uni.test.ts tests/vue.test.ts",
+		"test:package": "node --test tests/package.test.mjs && publint --strict --pack npm",
+		"check": "pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run format:check",
+		"prepack": "pnpm run check"
+	},
 	"peerDependencies": {
-		"vue": "^2 || ^3"
+		"vue": "^3.3.0"
 	},
 	"dependencies": {
-		"@types/crypto-js": "^4.2",
-		"@types/lodash": "^4.17",
-		"@types/lodash-es": "^4.17",
-		"crypto-js": "^4.2",
-		"lodash": "^4.17",
-		"lodash-es": "^4.17",
-		"lodash-unified": "^1"
+		"crypto-js": "^4.2.0"
 	},
 	"devDependencies": {
-		"@dcloudio/types": "^3",
-		"@fast-china/eslint-config": "^1",
-		"@rollup/plugin-terser": "^0.4",
-		"@types/node": "^24",
-		"@vue/tsconfig": "^0.8",
-		"eslint": "^9",
-		"prettier": "^3",
-		"terser": "^5",
-		"typescript": "^5",
-		"vite": "^7",
-		"vite-plugin-dts": "^4",
-		"vue": "^2 || ^3",
-		"vue-tsc": "^3"
+		"@eslint/js": "^10.0.1",
+		"@eslint/markdown": "^8.0.3",
+		"@types/crypto-js": "^4.2.2",
+		"@types/node": "^24.13.3",
+		"eslint": "^10.8.0",
+		"eslint-config-flat-gitignore": "^2.3.0",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-import-x": "^4.17.1",
+		"eslint-plugin-jsonc": "^3.3.0",
+		"eslint-plugin-regexp": "^3.1.1",
+		"globals": "^17.8.0",
+		"prettier": "^3.9.6",
+		"publint": "^0.3.22",
+		"tsdown": "^0.22.14",
+		"tsx": "^4.23.1",
+		"typescript": "^6.0.3",
+		"typescript-eslint": "^8.65.0",
+		"vue": "^3.5.40"
+	},
+	"engines": {
+		"node": "^22.18.0 || ^24.18.0",
+		"pnpm": "^11.0.0"
 	}
 }