@fast-china/utils 1.0.37 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to Fast.Utils are documented in this file.
+
+## [2.0.0] - 2026-08-03
+
+### Added
+
+- Named utilities for arrays, asynchronous control flow, Base64, colors, cryptography, dates, DOM styles, environment detection, identity, logging, numbers, objects, storage, and strings.
+- Promise-aware cancellation, timeout, retry, bounded concurrency, debounce, and throttle primitives.
+- Strict Base64/Base64URL, secure random generation, authenticated password encryption, RSA-OAEP, ECDSA, ECDH, and protocol-compatibility hash/AES functions.
+- Browser and automatically detected uni-app Storage with TTL, codecs, namespace isolation, and cleanup.
+- Optional Vue 2.7/3 entry with Composition API, typed emits/props/slots, render, and install helpers.
+- Pure ESM ES2022 publishing with exact public subpaths, one root package, and one root `dist/` directory.
+- Runtime, type-consumer, package-contract, Source Map, Tree Shaking, package-size, Publint, and CI validation.
+
+### Security
+
+- Added authenticated ciphertext validation, bounded crypto parameters and payloads, unbiased Web Crypto randomness, prototype-safe query/object transforms, and namespace-scoped Storage cleanup.
+
+[2.0.0]: https://github.com/China-xiaoFang/Fast.Utils/releases/tag/v2.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to Fast.Utils
+
+Thank you for improving Fast.Utils. Contributions should make behavior more predictable, types more truthful, or supported workflows easier to verify.
+
+## Requirements
+
+- Node.js `^22.18.0 || ^24.18.0`
+- pnpm `^11.0.0` through Corepack
+- Git with LF line endings
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm check
+```
+
+Use `pnpm dev` when a long-running tsdown watch build is useful during implementation.
+
+## Design rules
+
+- Prefer small named functions with explicit semantics over mutable utility singletons.
+- Do not introduce global configuration, import-time platform access, or hidden logging.
+- Keep the framework-neutral root independent from Vue.
+- Do not add a production dependency when the platform or a small reviewed implementation is sufficient.
+- Do not add ambiguous deep merge, string-path access, unbounded cache, or automatic retry behavior without a concrete contract and bounded risk.
+- Treat serialized data, cryptographic formats, storage namespaces, package exports, runtime requirements, and peer ranges as public design decisions.
+- Reject invalid input early. Do not silently return raw or partially parsed data after corruption.
+
+## Public API checklist
+
+Every new public function, type, interface, class, method, or option must include TSDoc covering the applicable items:
+
+- purpose and non-obvious design rationale;
+- type parameters, parameters, defaults, units, and accepted ranges;
+- return value, ordering, mutation, allocation, and empty-input behavior;
+- native error classes, `name`, `cause`, and failure semantics;
+- cancellation, concurrency, cleanup, and ownership semantics;
+- browser, Vue, or uni-app runtime restrictions;
+- security boundaries and common misuse risks;
+- a focused example when the signature alone is insufficient.
+
+Comments should explain why a choice exists. Do not repeat obvious syntax or add comments only to increase volume.
+
+## Tests
+
+- Add a regression test for every defect.
+- Test successful calls, invalid input, empty input, boundary values, and relevant cancellation or platform branches.
+- Add compile-only cases to `tests/public-api.test.ts` for inference and rejected calls.
+- Avoid tests that execute code without asserting meaningful behavior.
+- Keep tests deterministic; inject clocks, storage, sinks, identifiers, and signals where supported.
+
+Run the narrowest relevant command during development, then run the full set before opening a pull request:
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm test:types
+pnpm lint
+pnpm format:check
+pnpm build
+pnpm test:package
+```
+
+## Dependencies
+
+Development tools use reviewed caret ranges and are resolved exactly by `pnpm-lock.yaml`. Before changing a tool version:
+
+1. verify Node.js and peer requirements;
+2. review release notes and security advisories;
+3. regenerate only the lock file with the pinned pnpm version;
+4. run type, lint, test, build, package-consumer, audit, and dry-run checks;
+5. avoid unrelated upgrades in the same pull request.
+
+This repository intentionally defines its own ESLint Flat Config and must not depend on `@fast-china/eslint-config`.
+
+## Pull requests
+
+- Keep the diff focused and avoid repository-wide formatting unrelated to the change.
+- Update English and Chinese docs for user-visible behavior.
+- Add a dated `CHANGELOG.md` entry only when preparing a release.
+- Describe API, runtime, package-entry, type, security, and size impact.
+- Never include credentials, private endpoints, connection strings, or production data.
+- Do not publish, tag, push, or deploy from a contribution workflow.
+
+## Security reports
+
+Do not open a public issue for a suspected vulnerability. Follow [SECURITY.md](./SECURITY.md).

package/README.md

@@ -1,83 +1,144 @@
-[中](https://gitee.com/FastDotnet/Fast.Utils) | **En**
-
-<h1 align="center">Fast.Utils</h1>
-
-<p align="center">
-  <code>Fast</code> platform An util library built based on <code>TypeScript</code>.
+<p align="left">
+	<a href="./README.zh.md">简体中文</a> | <strong>English</strong>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@fast-china/utils">
-    <img src="https://img.shields.io/npm/v/@fast-china/utils?color=orange&label=" alt="version" />
-  </a>
-  <a href="https://gitee.com/FastDotnet/Fast.Utils/blob/master/LICENSE">
-    <img src="https://img.shields.io/npm/l/@fast-china/utils" alt="license" />
-  </a>
+	<img src="./Fast.png" alt="logo" width="160" />
 </p>
 
-## Install
+# @fast-china/utils
+
+Browser-first TypeScript utilities for modern browsers, WebViews, Vue 2.7/3, and uni-app.
 
-#### Using a Package Manager
+[![npm version](https://img.shields.io/npm/v/@fast-china/utils?color=orange)](https://www.npmjs.com/package/@fast-china/utils) [![node](https://img.shields.io/badge/node-%5E22.18%20%7C%7C%20%5E24.18-brightgreen)](https://nodejs.org/) [![vue](https://img.shields.io/badge/vue-%5E2.7%20%7C%7C%20%5E3.3-42b883)](https://vuejs.org/) [![license](https://img.shields.io/npm/l/@fast-china/utils)](./LICENSE)
 
-```sh
-# Choose a package manager of your choice
+## Highlights
 
-# NPM
-npm install @fast-china/utils
+- Typed, side-effect-free utilities with one named-export entry for effective Tree Shaking.
+- Browser, WebView, Vue 2.7/3, and uni-app contracts without import-time platform access.
+- Explicit security boundaries for storage, identity, encoding, random generation, and cryptography.
+- TypeScript 6 strict checks, ESLint, runtime tests, consumer type tests, package validation, and Publint.
+
+## Install
+
+```bash
+pnpm add @fast-china/utils
+```
 
-# Yarn
-yarn add @fast-china/utils
+Install the optional Vue peer only when using Vue helpers:
 
-# pnpm (recommend)
-pnpm install @fast-china/utils
+```bash
+pnpm add vue
 ```
 
-## Update log
+Supported peer range: Vue `^2.7.0 || ^3.3.0`. Vue 2.6 and Vue 3.0-3.2 are outside the declared range.
 
-Update log [Click to view](https://gitee.com/FastDotnet/Fast.Utils/commits/master)
+## Storage
 
-## Protocol
+Configure storage exactly once from the browser application entry:
 
-[Fast.Utils](https://gitee.com/FastDotnet/Fast.Utils) complies with the [Apache-2.0](https://gitee.com/FastDotnet/Fast.Utils/blob/master/LICENSE) open source agreement. Welcome to submit `PR` or `Issue`.
+```ts
+import { configureStorage } from "@fast-china/utils";
 
+configureStorage({
+	prefix: "my-app:",
+});
 ```
-Apache Open Source License
 
-Copyright © 2018-Now xiaoFang
+Every other module imports the stable package exports directly:
 
-License:
-This Agreement grants any individual or organization that obtains a copy of this software and its related documentation (hereinafter referred to as the "Software").
-Subject to the terms of this Agreement, you have the right to use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the Software:
-1.All copies or major parts of the Software must retain this Copyright Notice and this License Agreement.
-2.The use, copying, modification, or distribution of the Software shall not violate applicable laws or infringe upon the legitimate rights and interests of others.
-3.Modified or derivative works must clearly indicate the original author and the source of the original Software.
+```ts
+import { Local, Session } from "@fast-china/utils";
 
-Special Statement:
-- This Software is provided "as is" without any express or implied warranty of any kind, including but not limited to the warranty of merchantability, fitness for purpose, and non-infringement.
-- In no event shall the author or copyright holder be liable for any direct or indirect loss caused by the use or inability to use this Software.
-- Including but not limited to data loss, business interruption, etc.
+Local.set("user", { id: 1 }, { ttlMs: 30 * 60 * 1000 });
+const user = Local.get<{ id: number }>("user");
 
-Disclaimer:
-It is prohibited to use this software to engage in illegal activities such as endangering national security, disrupting social order, or infringing on the legitimate rights and interests of others.
-The author does not assume any responsibility for any legal disputes and liabilities caused by the secondary development of this software.
+Session.set("redirect", "/home");
 ```
 
-## Disclaimer
+The configuration is immutable after the first call. Repeating the same configuration is idempotent; a conflicting configuration throws.
 
+In uni-app, the same configuration automatically uses the global `uni` synchronous Storage API:
+
+```ts
+import { configureStorage } from "@fast-china/utils";
+
+configureStorage({
+	prefix: "my-app:",
+});
 ```
-Please do not use it for projects that violate our country's laws
+
+uni-app uses `Local`; `Session` throws because uni-app has no sessionStorage equivalent. `clear()` removes only keys inside the configured prefix. The optional `base64StorageCodec` is reversible obfuscation, not encryption.
+
+## Base64
+
+Prefer the UTF-8 or Base64URL APIs in new code:
+
+```ts
+import { decodeBase64, encodeBase64, encodeBase64Url } from "@fast-china/utils";
+
+const encoded = encodeBase64("Fast utilities");
+decodeBase64(encoded);
+encodeBase64Url("path/value");
 ```
 
-## Contributors
+`encodeSecureBase64` and `decodeSecureBase64` exist only for the legacy dictionary format. Given the same default six-character prefix, valid legacy payloads remain byte-for-byte identical. A historical Base64-length 101–124 dictionary gap uses a one-character fallback that the legacy removal flow understands. This format is not encryption and must not protect passwords, tokens, or other secrets.
+
+## Identity
 
-Thank you for all their contributions!
+```ts
+import { configureInstallationIdentity, getOrCreateInstallationId } from "@fast-china/utils";
 
-<a href="https://github.com/China-xiaoFang/Fast.Utils/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=China-xiaoFang/Fast.Utils" />
-</a>
+configureInstallationIdentity({ cacheKey: "account:installation-id" });
 
-## Supplementary instructions
+const installationId = getOrCreateInstallationId();
+```
+
+Call `configureInstallationIdentity` in the application entry before first use. The default business key is `identity:installation-id`; repeated identical configuration is idempotent and conflicting configuration throws. Installation Identity uses the configured `Local` storage and Web Crypto UUID v4 generation. It never falls back to `Math.random()`.
+
+## Vue 2.7 and Vue 3
 
+```ts
+import { useEmits, useProps, withInstall } from "@fast-china/utils";
 ```
-If it is helpful to you, you can click ⭐Star in the upper right corner to collect it and get the latest updates. Thank you!
+
+The package provides structural plugin registration compatible with Vue 2.7 `Vue.use()` and Vue 3 `app.use()`, Composition API helpers, typed props/emits/slots, and TSX rendering. Vue remains external to the bundle and is declared as an optional peer dependency. `makeSlots` uses Vue 3's official `SlotsType` and is intended for Vue 3 components.
+
+## Modules
+
+`@fast-china/utils` is the only public entry and exposes every API as a named export. Source modules remain separate in `dist/` so modern bundlers can remove unused exports; those internal files are not public package subpaths.
+
+Historical aggregate objects are not public. Their behavior is available through named functions, improving auto-imports and Tree Shaking.
+
+## Runtime contract
+
+- Pure ESM; no CommonJS, UMD, or IIFE.
+- ES2022 modern browsers and WebViews.
+- Vue 2.7 or Vue 3 through an optional peer.
+- uni-app through automatic global `uni` detection when Storage is configured.
+- No import-time access to `window`, Storage, or `uni`; unsupported calls fail explicitly.
+- Web Crypto, URL, Intl, TextEncoder, and related platform capabilities are not polyfilled.
+
+## Documentation
+
+- [API reference](./docs/API.md)
+- [Runtime contract](./docs/RUNTIME_CONTRACT.md)
+- [Development and release guide (Chinese)](./docs/DEVELOPMENT_RELEASE.zh-CN.md)
+- [Security policy](./SECURITY.md)
+- [Contributing guide](./CONTRIBUTING.md)
+- [Changelog](./CHANGELOG.md)
+
+## Development
+
+Development requires Node.js `^22.18.0 || ^24.18.0` and pnpm `^11.0.0`.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
 ```
+
+Use `pnpm dev` for a long-running tsdown watch build while editing source files.
+
+## License
+
+[Apache-2.0](./LICENSE)

package/README.zh.md

@@ -1,83 +1,144 @@
-**中** | [En](https://github.com/China-xiaoFang/fast.utils)
-
-<h1 align="center">Fast.Utils</h1>
-
-<p align="center">
-  <code>Fast</code> 平台下基于 <code>TypeScript</code> 构建的工具库。
+<p align="left">
+	<strong>简体中文</strong> | <a href="./README.md">English</a>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@fast-china/utils">
-    <img src="https://img.shields.io/npm/v/@fast-china/utils?color=orange&label=" alt="version" />
-  </a>
-  <a href="https://gitee.com/FastDotnet/Fast.Utils/blob/master/LICENSE">
-    <img src="https://img.shields.io/npm/l/@fast-china/utils" alt="license" />
-  </a>
+	<img src="./Fast.png" alt="logo" width="160" />
 </p>
 
-## 安装
+# @fast-china/utils
+
+面向现代浏览器、WebView、Vue 2.7/3 与 uni-app 的 TypeScript 前端工具库。
 
-#### 使用包管理器
+[![npm 版本](https://img.shields.io/npm/v/@fast-china/utils?color=orange)](https://www.npmjs.com/package/@fast-china/utils) [![node](https://img.shields.io/badge/node-%5E22.18%20%7C%7C%20%5E24.18-brightgreen)](https://nodejs.org/) [![Vue](https://img.shields.io/badge/vue-%5E2.7%20%7C%7C%20%5E3.3-42b883)](https://vuejs.org/) [![开源协议](https://img.shields.io/npm/l/@fast-china/utils)](./LICENSE)
 
-```sh
-# 选择一个你喜欢的包管理器
+## 特性
 
-# NPM
-npm install @fast-china/utils
+- 提供完整类型、无副作用实现和统一具名导出入口，便于 Tree Shaking。
+- 明确支持浏览器、WebView、Vue 2.7/3 与 uni-app，导入阶段不访问平台全局对象。
+- 为 Storage、安装标识、编码、安全随机数与密码学能力划定清晰的安全边界。
+- 使用 TypeScript 6 严格检查、ESLint、运行时测试、消费者类型测试、包契约与 Publint 共同验证。
+
+## 安装
+
+```bash
+pnpm add @fast-china/utils
+```
 
-# Yarn
-yarn add @fast-china/utils
+使用 Vue 工具时由应用安装 Vue：
 
-# pnpm（推荐）
-pnpm install @fast-china/utils
+```bash
+pnpm add vue
 ```
 
-## 更新日志
+Peer 范围为 Vue `^2.7.0 || ^3.3.0`。Vue 2.6 与 Vue 3.0-3.2 不在声明范围内。
 
-更新日志 [点击查看](https://gitee.com/FastDotnet/Fast.Utils/commits/master)
+## Storage
 
-## 协议
+只在浏览器程序入口配置一次：
 
-[Fast.Utils](https://gitee.com/FastDotnet/Fast.Utils) 遵循 [Apache-2.0](https://gitee.com/FastDotnet/Fast.Utils/blob/master/LICENSE) 开源协议，欢迎大家提交 `PR` 或 `Issue`。
+```ts
+import { configureStorage } from "@fast-china/utils";
 
+configureStorage({
+	prefix: "my-app:",
+});
 ```
-Apache开源许可证
 
-版权所有 © 2018-Now 小方
+其他业务文件直接引用包：
 
-许可授权：
-本协议授予任何获得本软件及其相关文档（以下简称“软件”）副本的个人或组织。
-在遵守本协议条款的前提下，享有使用、复制、修改、合并、发布、分发、再许可、销售软件副本的权利：
-1.所有软件副本或主要部分必须保留本版权声明及本许可协议。
-2.软件的使用、复制、修改或分发不得违反适用法律或侵犯他人合法权益。
-3.修改或衍生作品须明确标注原作者及原软件出处。
+```ts
+import { Local, Session } from "@fast-china/utils";
 
-特别声明：
-- 本软件按“原样”提供，不提供任何形式的明示或暗示的保证，包括但不限于对适销性、适用性和非侵权的保证。
-- 在任何情况下，作者或版权持有人均不对因使用或无法使用本软件导致的任何直接或间接损失的责任。
-- 包括但不限于数据丢失、业务中断等情况。
+Local.set("user", { id: 1 }, { ttlMs: 30 * 60 * 1000 });
+const user = Local.get<{ id: number }>("user");
 
-免责条款：
-禁止利用本软件从事危害国家安全、扰乱社会秩序或侵犯他人合法权益等违法活动。
-对于基于本软件二次开发所引发的任何法律纠纷及责任，作者不承担任何责任。
+Session.set("redirect", "/home");
 ```
 
-## 免责申明
+首次配置后不可变；相同配置重复调用保持幂等，不同配置会抛错。
 
+在 uni-app 中，同一配置会自动使用全局 `uni` 的同步 Storage API：
+
+```ts
+import { configureStorage } from "@fast-china/utils";
+
+configureStorage({
+	prefix: "my-app:",
+});
 ```
-请勿用于违反我国法律的项目上
+
+uni-app 使用 `Local`；由于不存在等价的 sessionStorage，调用 `Session` 会明确抛错。`clear()` 只清理当前前缀。可选的 `base64StorageCodec` 只是可逆混淆，不是加密。
+
+## Base64
+
+新代码优先使用 UTF-8 或 Base64URL API：
+
+```ts
+import { decodeBase64, encodeBase64, encodeBase64Url } from "@fast-china/utils";
+
+const encoded = encodeBase64("Fast 工具库");
+decodeBase64(encoded);
+encodeBase64Url("path/参数");
 ```
 
-## 贡献者
+`encodeSecureBase64` / `decodeSecureBase64` 仅用于兼容旧字典格式。给定相同的默认 6 字符前缀时，有效旧载荷保持逐字符一致；历史字典无法自解码的 101–124 字符 Base64 区间使用旧删除流程可识别的单字符回退。它不是加密，不应用于密码、Token 或其他秘密。
+
+## 安装实例标识
 
-感谢他们的所做的一切贡献！
+```ts
+import { configureInstallationIdentity, getOrCreateInstallationId } from "@fast-china/utils";
 
-<a href="https://github.com/China-xiaoFang/Fast.Utils/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=China-xiaoFang/Fast.Utils" />
-</a>
+configureInstallationIdentity({ cacheKey: "account:installation-id" });
 
-## 补充说明
+const installationId = getOrCreateInstallationId();
+```
+
+在程序入口、首次使用安装标识前调用 `configureInstallationIdentity`。默认业务键是 `identity:installation-id`；相同配置可幂等重复调用，不同配置会抛错。安装标识使用已配置的 `Local` 和 Web Crypto UUID v4，不回退 `Math.random()`。它不是硬件 ID、认证凭证或风控信号。
+
+## Vue 2.7 与 Vue 3
 
+```ts
+import { useEmits, useProps, withInstall } from "@fast-china/utils";
 ```
-如果对您有帮助，您可以点右上角 ⭐Star 收藏一下 ，获取第一时间更新，谢谢！
+
+包内提供结构化插件注册，同时兼容 Vue 2.7 `Vue.use()` 与 Vue 3 `app.use()`，并提供 Composition API、Props/Emits/Slots 类型和 TSX 渲染。Vue 不会打进本包产物，并声明为可选 Peer Dependency。`makeSlots` 使用 Vue 3 官方 `SlotsType`，仅供 Vue 3 组件使用。
+
+## 模块
+
+`@fast-china/utils` 是唯一公开入口，全部 API 都通过具名导出提供。源码模块仍会在 `dist/` 中独立保留，便于现代打包器移除未使用代码，但这些内部文件不是公开子路径。
+
+历史聚合对象不再公开，其功能全部通过具名函数提供，便于自动导入与 Tree Shaking。
+
+## 运行时契约
+
+- 仅纯 ESM，不提供 CommonJS、UMD 或 IIFE。
+- 面向 ES2022 现代浏览器与 WebView。
+- Vue 2.7 或 Vue 3 通过可选 Peer 接入。
+- 配置 Storage 时自动检测全局 `uni` 并接入 uni-app。
+- 导入阶段不访问 `window`、Storage 或 `uni`；不支持的调用明确失败。
+- 不注入 Web Crypto、URL、Intl、TextEncoder 等 Polyfill。
+
+## 文档
+
+- [API 文档](./docs/API.zh-CN.md)
+- [运行时契约](./docs/RUNTIME_CONTRACT.md)
+- [开发与发布](./docs/DEVELOPMENT_RELEASE.zh-CN.md)
+- [安全策略](./SECURITY.md)
+- [贡献指南](./CONTRIBUTING.md)
+- [更新日志](./CHANGELOG.md)
+
+## 开发
+
+开发工具链要求 Node.js `^22.18.0 || ^24.18.0` 与 pnpm `^11.0.0`。
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
 ```
+
+修改源码时可使用 `pnpm dev` 启动长期运行的 tsdown 监听构建。
+
+## 许可证
+
+[Apache-2.0](./LICENSE)

package/SECURITY.md

@@ -0,0 +1,46 @@
+# Security Policy
+
+## Supported releases
+
+Security fixes are provided for the latest stable release. Pre-release builds and unsupported runtime combinations receive best-effort investigation only.
+
+## Reporting a vulnerability
+
+Use the repository's private GitHub Security Advisory reporting flow. Do not disclose the issue publicly until a fix and coordinated disclosure plan are available.
+
+Include:
+
+- affected package version and public API;
+- runtime, browser, framework, and platform;
+- minimal reproduction without real credentials or user data;
+- expected and observed impact;
+- whether untrusted input, authentication, storage, or cryptography is involved.
+
+Maintainers should acknowledge a complete report within five business days. Timelines depend on severity, reproducibility, affected platforms, and release coordination.
+
+## Security boundaries
+
+Fast.Utils is a utility library, not a complete security system.
+
+- `encryptText` provides authenticated encryption for caller-owned text up to 8 MiB of UTF-8 with a caller-owned password. It does not provide KMS, key rotation, account recovery, rate limiting, or protocol negotiation.
+- `sha256` is a fast digest and must not be used directly for password storage.
+- `timingSafeEqual` avoids explicit early exit, but JavaScript engines cannot guarantee strict constant-time execution.
+- Base64 and Base64URL are encodings, not encryption.
+- Web Storage is readable by same-origin script and must not contain passwords, private keys, or long-lived credentials.
+- Installation IDs are local convenience identifiers, not authentication, hardware identity, or fraud signals.
+- User-Agent detection is heuristic and must not drive authorization or trust decisions.
+- `escapeHtml` is limited to HTML text context and is not a general sanitizer.
+- `serializeStyle` converts trusted structures and does not sanitize untrusted CSS.
+- Logger calls must not receive passwords, tokens, keys, connection strings, or complete personal data.
+
+## Supply chain and release controls
+
+- The runtime package allows only the reviewed `crypto-js` production dependency; package checks enforce this allowlist.
+- Development dependencies are exact and locked.
+- CI runs frozen installation, lint, strict type checks, tests, build, package consumers, and package inspection.
+- The release gate validates package metadata, changelog/version consistency, build output, consumers, and the npm archive before publication.
+- Release workflows use pinned action commits and do not persist checkout credentials.
+
+## Handling secrets
+
+No secret is required to build or test the repository. Never commit npm tokens, GitHub tokens, signing keys, private registry credentials, `.env` files, production logs, or encrypted data whose password is available in the same repository.

package/dist/array/index.d.mts

@@ -0,0 +1,87 @@
+//#region src/array/index.d.ts
+/** 从数组项中提取可比较键的函数。 */
+type KeySelector<Item, Key> = (item: Item, index: number) => Key;
+/**
+ * 将只读数组按固定大小分组。
+ *
+ * @typeParam Item - 数组项类型。
+ * @param items - 不会被修改的输入数组。
+ * @param size - 每组最多包含的项目数，必须是正安全整数。
+ * @returns 新建的二维数组；最后一组可能小于 `size`。
+ * @throws `RangeError` 当 `size` 不是正安全整数。
+ */
+declare function chunk<Item>(items: readonly Item[], size: number): Item[][];
+/**
+ * 删除数组中的 `null` 与 `undefined`，保留 `false`、`0` 和空字符串。
+ *
+ * @param items - 可包含空值的只读数组。
+ * @returns 保持原顺序的新数组。
+ */
+declare function removeNullishValues<Item>(items: readonly (Item | null | undefined)[]): Item[];
+/**
+ * 使用 JavaScript `Set` 的 SameValueZero 语义去重。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @returns 保留每个值首次出现顺序的新数组；稀疏数组空位被忽略。
+ */
+declare function unique<Item>(items: readonly Item[]): Item[];
+/**
+ * 按选择器返回的键去重。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 接收项目与索引并返回去重键的函数。
+ * @returns 保留每个键首次出现项目的新数组；稀疏数组空位被忽略。
+ */
+declare function uniqueBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): Item[];
+/**
+ * 按选择器结果分组。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 返回任意 `Map` 键的函数。
+ * @returns 按键首次出现顺序排列的 `Map`；每个分组保持输入顺序，稀疏空位被忽略。
+ */
+declare function groupBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): Map<Key, Item[]>;
+/**
+ * 按谓词把数组拆分为匹配项和非匹配项。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param predicate - 接收项目与索引的判断函数。
+ * @returns 二元组：第一项匹配谓词，第二项不匹配；两组都保持原顺序并忽略稀疏空位。
+ */
+declare function partition<Item>(items: readonly Item[], predicate: (item: Item, index: number) => boolean): [matched: Item[], unmatched: Item[]];
+/**
+ * 返回只出现在左侧数组中的不同值。
+ *
+ * @param left - 主输入数组。
+ * @param right - 需要排除的值。
+ * @returns 保留左侧首次出现顺序的去重结果；两侧稀疏空位都被忽略。
+ */
+declare function difference<Item>(left: readonly Item[], right: readonly Item[]): Item[];
+/**
+ * 返回两个数组共有的不同值。
+ *
+ * @param left - 决定结果顺序的数组。
+ * @param right - 用于成员判断的数组。
+ * @returns 保留左侧首次出现顺序的去重结果；两侧稀疏空位都被忽略。
+ */
+declare function intersection<Item>(left: readonly Item[], right: readonly Item[]): Item[];
+/**
+ * 判断选择器产生的键是否重复。
+ *
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 返回比较键的函数；键使用 SameValueZero 语义比较。
+ * @returns 存在至少一个重复键时返回 `true`。
+ */
+declare function hasDuplicatesBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): boolean;
+/**
+ * 判断所有项目是否具有相同的选择器结果。
+ *
+ * @remarks 空数组、只有稀疏空位的数组和单项数组按数学惯例返回 `true`；空位不会调用选择器。
+ * @param items - 不会被修改的输入数组。
+ * @param selectKey - 返回比较键的函数。
+ * @returns 所有键都满足 SameValueZero 相等时返回 `true`。
+ */
+declare function allEqualBy<Item, Key>(items: readonly Item[], selectKey: KeySelector<Item, Key>): boolean;
+//#endregion
+export { KeySelector, allEqualBy, chunk, difference, groupBy, hasDuplicatesBy, intersection, partition, removeNullishValues, unique, uniqueBy };
+//# sourceMappingURL=index.d.mts.map

package/dist/array/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/array/index.ts"],"mappings":";;KACY,YAAY,MAAM,QAAQ,MAAM,MAAM,kBAAkB;;;;;;;;;;iBAWpD,MAAM,MAAM,gBAAgB,QAAQ,eAAe;;;;;;;iBAkBnD,oBAAoB,MAAM,iBAAiB,6BAA6B;;;;;;;iBAUxE,OAAO,MAAM,gBAAgB,SAAS;;;;;;;;iBAoBtC,SAAS,MAAM,KAAK,gBAAgB,QAAQ,WAAW,YAAY,MAAM,OAAO;;;;;;;;iBAqBhF,QAAQ,MAAM,KAAK,gBAAgB,QAAQ,WAAW,YAAY,MAAM,OAAO,IAAI,KAAK;;;;;;;;iBAkBxF,UAAU,MAAM,gBAAgB,QAAQ,YAAY,MAAM,MAAM,6BAA6B,SAAS,QAAQ,WAAW;;;;;;;;iBAczH,WAAW,MAAM,eAAe,QAAQ,gBAAgB,SAAS;;;;;;;;iBAYjE,aAAa,MAAM,eAAe,QAAQ,gBAAgB,SAAS;;;;;;;;iBAYnE,gBAAgB,MAAM,KAAK,gBAAgB,QAAQ,WAAW,YAAY,MAAM;;;;;;;;;iBAoBhF,WAAW,MAAM,KAAK,gBAAgB,QAAQ,WAAW,YAAY,MAAM"}