@fast-china/utils 2.1.6 → 2.1.7

package/docs/DEVELOPMENT_RELEASE.zh-CN.md

@@ -1,65 +0,0 @@
-# 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

@@ -1,44 +0,0 @@
-# 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.5.11`.
-- Vue browser composables: event and observer helpers use native platform APIs, return manual stop handles where exposed, and clean up automatically with the current Vue scope. Window size and breakpoints use `0`/`false` outside browsers; `useNow` returns a non-updating initial Date during SSR.
-- 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.
-- Storage operation overrides: `set/get({ crypto })` select JSON or Base64 for one operation without mutating global configuration. The v3 envelope does not identify its codec, so callers must use matching options for the same entry.
-- Storage read typing: `get<Value = string>()` defaults to `string | undefined` when no generic is supplied; codecs still restore the original runtime JSON value.
-- Stateful browser defaults: Storage, Identity, and default Logger configuration are page-global by design. Storage and Identity reject conflicting reconfiguration; `configureLogger` replaces the default Logger configuration while preserving the exported facade reference.
-- Randomness: every random generation entry prefers Web Crypto and falls back to `Math.random()` when unavailable.
-- 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.
-- Base64 and Crypto text decoders return primitive strings typed as `DecodedText`. They can be used directly as strings; an explicit `.parseJson<T = any>()` call attempts JSON parsing and falls back to the original string for invalid JSON. The first text decode lazily installs a non-enumerable `String.prototype.parseJson` and rejects a foreign same-name property instead of overwriting it. Storage codecs continue to parse JSON automatically and strictly.
-- Stateful browser capabilities use cohesive package-owned objects: `Local`, `Session`, `installationIdentity`, and Logger instances. Logger exposes the matching `debug`, `log`, `warn`, and `error` levels, defaults to the `debug` minimum, and receives scope on each method rather than storing it in child instances. `createLogger` returns isolated instances, while `configureLogger` only changes the default `logger` facade.
-- 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.5.11` 的必需 Peer。
-- Vue 浏览器 Composable：事件和观察器 Helper 直接使用原生平台 API，在公开停止函数时支持手动清理，并随当前 Vue 作用域自动清理。非浏览器环境下窗口尺寸和断点状态分别使用 `0` 与 `false`，`useNow` 在 SSR 时只返回调用时的静态 Date。
-- uni-app：首次 Storage 操作或更早的 `configureStorage({ prefix })` 调用会检测全局 `uni`，并使用其同步 Storage API。
-- Storage：直接从包导入 `Local` 和 `Session` 即可；只有覆盖默认值时才需在首次操作前调用 `configureStorage()`。
-- Storage 单次覆盖：`set/get({ crypto })` 只为当前操作选择 JSON 或 Base64，不修改全局配置。v3 包络不记录 Codec，调用方必须对同一条目使用匹配的读写选项。
-- Storage 读取类型：`get<Value = string>()` 未传泛型时默认推断为 `string | undefined`，Codec 在运行时仍恢复原始 JSON 值。
-- 状态：Storage、Identity 与默认 Logger 配置按浏览器页面全局共享。Storage 和 Identity 的冲突配置明确抛错；`configureLogger` 替换默认 Logger 的配置，同时保持导出的门面引用稳定。
-- 随机数：所有随机生成入口都优先使用 Web Crypto，缺失时回退到 `Math.random()`。
-- 发布：根目录是唯一 npm 包，`dist/` 是唯一构建输出，`exports` 是完整公共路径白名单。
-
-模块导入本身不读取 `window`、浏览器 Storage 或 `uni`，不具备对应平台能力时只在调用相关 API 时明确失败。
-
-无状态能力统一使用具名导出。Base64 与 Crypto 文本解码入口返回原始字符串类型 `DecodedText`，可以直接作为字符串使用；`.parseJson<T = any>()` 只在显式调用时尝试解析 JSON，非法 JSON 回退为原始字符串。首次文本解码会按需安装不可枚举的 `String.prototype.parseJson`，若同名属性已被其他实现占用则拒绝覆盖并抛错。Storage Codec 继续严格自动解析 JSON。有状态浏览器能力使用 `Local`、`Session`、`installationIdentity` 和 Logger 实例；Logger 提供与 Sink 同名的 `debug`、`log`、`warn`、`error` 级别，默认最低级别为 `debug`，作用域随每次调用传入，不创建 Child Logger。`createLogger` 返回隔离实例，`configureLogger` 只修改默认 `logger` 门面。