@fast-china/utils 1.0.37 → 2.0.0

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、ES2022、`.mjs`、`.d.mts` 和 Source Map。
+- 根目录是唯一 npm 发布单元，根 `dist/` 是唯一产物目录。
+
+应用环境包括现代浏览器、WebView、Vue 2.7/3 和 uni-app。
+
+## 安装与命令
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+```
+
+| 命令                | 用途                                                                   |
+| ------------------- | ---------------------------------------------------------------------- |
+| `pnpm dev`          | 使用 tsdown 监听源码并增量构建                                         |
+| `pnpm build`        | 使用 tsdown 构建统一公开入口与内部模块                                 |
+| `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 保持 Optional Peer Dependency，不得打包进发布产物。
+- 依赖升级后使用当前 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 2.7/3 applications, and uni-app.
+- Package format: pure ESM with one public named-export entry; CommonJS, UMD, and IIFE are not shipped.
+- Framework boundary: Vue remains external to the package build and is an optional peer in `^2.7.0 || ^3.3.0`.
+- uni-app boundary: `configureStorage({ prefix })` detects global `uni` at call time and uses its synchronous Storage API.
+- Browser storage: applications call `configureStorage()` once, then import `Local` and `Session` directly from the package.
+- 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 2.7/3 应用和 uni-app。
+- 包格式：仅纯 ESM 和单一公开具名导出入口，不发布 CommonJS、UMD 或 IIFE。
+- Vue 边界：Vue 不会打进本包产物，是 `^2.7.0 || ^3.3.0` 的可选 Peer。
+- uni-app：`configureStorage({ prefix })` 在调用阶段自动检测全局 `uni` 并使用其同步 Storage API。
+- Storage：程序入口配置一次，其他文件直接从包导入 `Local` 和 `Session`。
+- 状态：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,96 @@
 {
 	"name": "@fast-china/utils",
-	"version": "1.0.37",
-	"description": "Fast 工具库.",
+	"version": "2.0.0",
+	"description": "Typed utilities for modern browsers, WebViews, Vue 2.7/3, and uni-app applications.",
 	"type": "module",
 	"keywords": [
 		"fast-china",
-		"fast",
 		"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",
+		"LICENSE",
+		"README.md",
+		"README.zh.md",
+		"SECURITY.md",
+		"dist",
+		"docs",
+		"src"
 	],
-	"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,
 	"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-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": "^2.7.0 || ^3.3.0"
+	},
+	"peerDependenciesMeta": {
+		"vue": {
+			"optional": true
+		}
 	},
 	"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"
 	}
 }

package/src/array/index.ts

@@ -0,0 +1,173 @@
+/** 从数组项中提取可比较键的函数。 */
+export type KeySelector<Item, Key> = (item: Item, index: number) => Key;
+
+/**
+ * 将只读数组按固定大小分组。
+ *
+ * @typeParam Item - 数组项类型。
+ * @param items - 不会被修改的输入数组。
+ * @param size - 每组最多包含的项目数，必须是正安全整数。
+ * @returns 新建的二维数组；最后一组可能小于 `size`。
+ * @throws `RangeError` 当 `size` 不是正安全整数。
+ */
+export function chunk<Item>(items: readonly Item[], size: number): Item[][] {
+	if (!Number.isSafeInteger(size) || size <= 0) {
+		throw new RangeError("size must be a positive safe integer.");
+	}
+
+	const result: Item[][] = [];
+	for (let index = 0; index < items.length; index += size) {
+		result.push(items.slice(index, index + size));
+	}
+	return result;
+}
+
+/**
+ * 删除数组中的 `null` 与 `undefined`，保留 `false`、`0` 和空字符串。
+ *
+ * @param items - 可包含空值的只读数组。
+ * @returns 保持原顺序的新数组。
+ */
+export function removeNullishValues<Item>(items: readonly (Item | null | undefined)[]): Item[] {
+	return items.filter((item): item is Item => item !== null && item !== undefined);
+}
+
+/**
+ * 使用 JavaScript `Set` 的 SameValueZero 语义去重。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @returns 保留每个值首次出现顺序的新数组；稀疏数组空位被忽略。
+ */
+export function unique<Item>(items: readonly Item[]): Item[] {
+	const result: Item[] = [];
+	const seen = new Set<Item>();
+	for (let index = 0; index < items.length; index += 1) {
+		if (!(index in items)) continue;
+		const item = items[index] as Item;
+		if (seen.has(item)) continue;
+		seen.add(item);
+		result.push(item);
+	}
+	return result;
+}
+
+/**
+ * 按选择器返回的键去重。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 接收项目与索引并返回去重键的函数。
+ * @returns 保留每个键首次出现项目的新数组；稀疏数组空位被忽略。
+ */
+export function uniqueBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): Item[] {
+	const seen = new Set<Key>();
+	const result: Item[] = [];
+	for (let index = 0; index < items.length; index += 1) {
+		const item = items[index];
+		if (item === undefined && !(index in items)) continue;
+		const key = selectKey(item as Item, index);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		result.push(item as Item);
+	}
+	return result;
+}
+
+/**
+ * 按选择器结果分组。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 返回任意 `Map` 键的函数。
+ * @returns 按键首次出现顺序排列的 `Map`；每个分组保持输入顺序，稀疏空位被忽略。
+ */
+export function groupBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): Map<Key, Item[]> {
+	const groups = new Map<Key, Item[]>();
+	items.forEach((item, index) => {
+		const key = selectKey(item, index);
+		const group = groups.get(key);
+		if (group === undefined) groups.set(key, [item]);
+		else group.push(item);
+	});
+	return groups;
+}
+
+/**
+ * 按谓词把数组拆分为匹配项和非匹配项。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param predicate - 接收项目与索引的判断函数。
+ * @returns 二元组：第一项匹配谓词，第二项不匹配；两组都保持原顺序并忽略稀疏空位。
+ */
+export function partition<Item>(items: readonly Item[], predicate: (item: Item, index: number) => boolean): [matched: Item[], unmatched: Item[]] {
+	const matched: Item[] = [];
+	const unmatched: Item[] = [];
+	items.forEach((item, index) => (predicate(item, index) ? matched : unmatched).push(item));
+	return [matched, unmatched];
+}
+
+/**
+ * 返回只出现在左侧数组中的不同值。
+ *
+ * @param left - 主输入数组。
+ * @param right - 需要排除的值。
+ * @returns 保留左侧首次出现顺序的去重结果；两侧稀疏空位都被忽略。
+ */
+export function difference<Item>(left: readonly Item[], right: readonly Item[]): Item[] {
+	const excluded = new Set(unique(right));
+	return unique(left).filter((item) => !excluded.has(item));
+}
+
+/**
+ * 返回两个数组共有的不同值。
+ *
+ * @param left - 决定结果顺序的数组。
+ * @param right - 用于成员判断的数组。
+ * @returns 保留左侧首次出现顺序的去重结果；两侧稀疏空位都被忽略。
+ */
+export function intersection<Item>(left: readonly Item[], right: readonly Item[]): Item[] {
+	const included = new Set(unique(right));
+	return unique(left).filter((item) => included.has(item));
+}
+
+/**
+ * 判断选择器产生的键是否重复。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 返回比较键的函数；键使用 SameValueZero 语义比较。
+ * @returns 存在至少一个重复键时返回 `true`。
+ */
+export function hasDuplicatesBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): boolean {
+	const seen = new Set<Key>();
+	for (let index = 0; index < items.length; index += 1) {
+		const item = items[index];
+		if (item === undefined && !(index in items)) continue;
+		const key = selectKey(item as Item, index);
+		if (seen.has(key)) return true;
+		seen.add(key);
+	}
+	return false;
+}
+
+/**
+ * 判断所有项目是否具有相同的选择器结果。
+ *
+ * @remarks 空数组、只有稀疏空位的数组和单项数组按数学惯例返回 `true`；空位不会调用选择器。
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 返回比较键的函数。
+ * @returns 所有键都满足 SameValueZero 相等时返回 `true`。
+ */
+export function allEqualBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): boolean {
+	let first: Key | undefined;
+	let hasFirst = false;
+	for (let index = 0; index < items.length; index += 1) {
+		const item = items[index];
+		if (item === undefined && !(index in items)) continue;
+		const current = selectKey(item as Item, index);
+		if (!hasFirst) {
+			first = current;
+			hasFirst = true;
+			continue;
+		}
+		if (!(first === current || (Number.isNaN(first) && Number.isNaN(current)))) return false;
+	}
+	return true;
+}