@fast-china/utils 2.1.6 → 2.1.7

package/dist/vue/element-size.d.mts

@@ -1,25 +0,0 @@
-import { ResizeObserverTarget } from "./resize-observer.mjs";
-import { ShallowRef } from "vue";
-//#region src/vue/element-size.d.ts
-/** 元素的二维尺寸。 */
-export interface ElementSize {
-  readonly width: number;
-  readonly height: number;
-}
-/** `useElementSize` 返回的响应式尺寸和停止函数。 */
-export interface UseElementSizeReturn {
-  readonly width: Readonly<ShallowRef<number>>;
-  readonly height: Readonly<ShallowRef<number>>;
-  readonly stop: () => void;
-}
-/**
- * 响应式读取元素 Content Rect 尺寸。
- *
- * @param target - 原生元素、Ref 或 Getter。
- * @param initialSize - 收到首次观察结果前的尺寸，默认均为 `0`。
- * @param options - 原生元素观察选项。
- * @returns 只读宽度、高度和手动停止函数。
- */
-export declare function useElementSize(target: ResizeObserverTarget, initialSize?: ElementSize, options?: ResizeObserverOptions): UseElementSizeReturn;
-//#endregion
-//# sourceMappingURL=element-size.d.mts.map

package/dist/vue/emits.d.mts

@@ -1,23 +0,0 @@
-import { ComputedRef } from "vue";
-//#region src/vue/emits.d.ts
-/** Vue Emits 对象中允许的校验器形状。 */
-type EmitValidator = ((...arguments_: never[]) => unknown) | null;
-/** 事件名到可选参数校验器的内部映射。 */
-type EmitsOptions = Record<string, EmitValidator>;
-/** 从校验器中提取事件参数；无校验器时保留未知参数。 */
-type EventArguments<Validator> = Validator extends ((...arguments_: infer Arguments) => unknown) ? Arguments : unknown[];
-/** 在类型层递归把 kebab-case 事件名转换为 PascalCase。 */
-type PascalEventName<Value extends string> = Value extends `${infer Head}-${infer Tail}` ? `${Capitalize<Head>}${PascalEventName<Tail>}` : Capitalize<Value>;
-/** 把事件配置映射为 Vue `onXxx` 属性。 */
-export type EmitHandlers<Emits extends EmitsOptions> = { [Name in keyof Emits as Name extends string ? `on${PascalEventName<Name>}` : never]: (...arguments_: EventArguments<Emits[Name]>) => void; };
-/**
- * 构建响应式 Vue 事件处理器。
- *
- * @param emits - Vue emits 配置对象。
- * @param emit - `setup` 上下文提供的 emit 函数。
- * @param ignoredEvents - 不需要向子组件透传的事件名。
- * @returns 随配置重新计算的事件处理器对象。
- */
-export declare function useEmits<Emits extends EmitsOptions>(emits: Emits, emit: (...arguments_: never[]) => unknown, ignoredEvents?: readonly (keyof Emits)[]): ComputedRef<Partial<EmitHandlers<Emits>>>;
-//#endregion
-//# sourceMappingURL=emits.d.mts.map

package/dist/vue/event-listener.d.mts

@@ -1,16 +0,0 @@
-import { MaybeRefOrGetter } from "vue";
-//#region src/vue/event-listener.d.ts
-/** `useEventListener` 接受的原生事件目标或响应式事件目标。 */
-export type EventTargetSource = MaybeRefOrGetter<EventTarget | null | undefined>;
-/**
- * 注册原生事件监听器，并在目标变化或 Vue 作用域销毁时自动移除。
- *
- * @param target - 原生事件目标、Ref 或 Getter。
- * @param event - 原生事件名称。
- * @param listener - 事件回调。
- * @param options - 原生事件监听选项。
- * @returns 可提前移除监听器的停止函数。
- */
-export declare function useEventListener<EventType extends Event = Event>(target: EventTargetSource, event: string, listener: (event: EventType) => void, options?: boolean | AddEventListenerOptions): () => void;
-//#endregion
-//# sourceMappingURL=event-listener.d.mts.map

package/dist/vue/expose.d.mts

@@ -1,11 +0,0 @@
-//#region src/vue/expose.d.ts
-/**
- * 同时暴露组件实例能力并返回同一个对象，便于 `setup` 返回状态供 Vue Devtools 查看。
- *
- * @param expose - `setup` 上下文提供的 expose 函数。
- * @param exposed - 需要暴露的状态和方法。
- * @returns 原始 exposed 对象。
- */
-export declare function useExpose<Exposed extends object>(expose: (exposed?: Exposed) => void, exposed: Exposed): Exposed;
-//#endregion
-//# sourceMappingURL=expose.d.mts.map

package/dist/vue/func.d.mts

@@ -1,13 +0,0 @@
-//#region src/vue/func.d.ts
-/** 可同步或异步返回结果的函数。 */
-export type AwaitableFunction<Arguments extends readonly unknown[], Result> = (...arguments_: Arguments) => Result | PromiseLike<Result>;
-/**
- * 统一执行同步或异步函数，异常保持原样向调用方传播。
- *
- * @param function_ - 可选的待执行函数。
- * @param arguments_ - 原样传入函数的参数。
- * @returns 函数结果；未传函数时返回 `undefined`。
- */
-export declare function callOptionalFunction<Arguments extends readonly unknown[], Result>(function_: AwaitableFunction<Arguments, Result> | null | undefined, ...arguments_: Arguments): Promise<Awaited<Result> | undefined>;
-//#endregion
-//# sourceMappingURL=func.d.mts.map

package/dist/vue/index.d.mts

@@ -1,15 +0,0 @@
-import { Breakpoints, UseBreakpointsReturn, useBreakpoints } from "./breakpoints.mjs";
-import { ResizeObserverTarget, useResizeObserver } from "./resize-observer.mjs";
-import { ElementSize, UseElementSizeReturn, useElementSize } from "./element-size.mjs";
-import { EmitHandlers, useEmits } from "./emits.mjs";
-import { EventTargetSource, useEventListener } from "./event-listener.mjs";
-import { useExpose } from "./expose.mjs";
-import { AwaitableFunction, callOptionalFunction } from "./func.mjs";
-import { Installable, TSXWithInstall, VueInstallValue, withInstall, withInstallDirective, withNoopInstall } from "./install.mjs";
-import { useNow } from "./now.mjs";
-import { definePropType, useProps } from "./props.mjs";
-import { useRender } from "./render.mjs";
-import { TypedSlots, TypedSlotsDeclaration, makeSlots } from "./slots.mjs";
-import { UseWindowSizeReturn, useWindowSize } from "./window-size.mjs";
-import { withDefineType } from "./with.mjs";
-export { AwaitableFunction, Breakpoints, ElementSize, EmitHandlers, EventTargetSource, Installable, ResizeObserverTarget, TSXWithInstall, TypedSlots, TypedSlotsDeclaration, UseBreakpointsReturn, UseElementSizeReturn, UseWindowSizeReturn, VueInstallValue, callOptionalFunction, definePropType, makeSlots, useBreakpoints, useElementSize, useEmits, useEventListener, useExpose, useNow, useProps, useRender, useResizeObserver, useWindowSize, withDefineType, withInstall, withInstallDirective, withNoopInstall };

package/dist/vue/install.d.mts

@@ -1,50 +0,0 @@
-import { App } from "vue";
-//#region src/vue/install.d.ts
-/** Vue 组件对象、函数组件或指令对象可接受的最小结构类型。 */
-export type VueInstallValue = object | ((...arguments_: never[]) => unknown);
-/** 为 Vue 组件或指令附加供 Vue 3 `app.use()` 调用的安装能力。 */
-export type Installable<Value> = Value & {
-  /**
-   * 把当前组件或指令安装到 Vue 3 App。
-   * @param app - Vue 3 App 实例。
-   */
-  install: (app: App) => void;
-};
-/** TSX 组件安装类型；与 {@link Installable} 保持同一运行时契约。 */
-export type TSXWithInstall<Value> = Installable<Value>;
-/**
- * 为主组件附加 Vue 3 `app.use()` 安装能力。
- *
- * @remarks 函数会直接为 `main` 定义附属组件属性和 `install`。所有组件名称、附属属性
- * 冲突会在修改 `main` 前完成校验；安装到 App 时也会先预检全部全局名称，再统一注册。
- * @param main - 具有非空 `name` 的组件。
- * @param extras - 同时注册并以可枚举属性挂到主组件的附属组件映射。
- * @returns 原始 `main` 引用，并附加类型化的 `install` 与 `extras` 属性。
- * @throws `TypeError` 当组件缺少合法名称、已有 `install`、附属键或名称发生冲突。
- * @throws `Error` 当 App 中同名位置已经注册其他组件。
- */
-export declare function withInstall<Main extends VueInstallValue, Extras extends Record<string, VueInstallValue> = Record<never, never>>(main: Main, extras?: Extras): Installable<Main> & Extras;
-/**
- * 为不需要单独注册的附属组件附加空安装函数。
- *
- * @remarks 适用于只能作为主组件附属属性使用、但仍需满足 Vue Plugin 类型的组件。
- * 函数直接修改并返回传入组件，不会向 Vue 3 App 注册内容。
- * @param component - 尚未定义或继承 `install` 属性的组件。
- * @returns 原组件引用及无副作用的 `install` 方法。
- * @throws `TypeError` 当组件自身或原型链已经存在 `install`。
- */
-export declare function withNoopInstall<Value extends VueInstallValue>(component: Value): TSXWithInstall<Value>;
-/**
- * 为 Vue 3 指令附加插件安装能力。
- *
- * @remarks 函数直接修改并返回指令。安装时重复注册同一引用保持幂等，不会覆盖同名的
- * 其他指令。名称只传给 `directive()`，不得包含 `v-` 前缀。
- * @param directive - 尚未定义或继承 `install` 属性的 Vue 指令对象。
- * @param name - 非空、无空白且不以 `v-` 开头的全局指令名。
- * @returns 原指令引用及 Vue Plugin `install` 方法。
- * @throws `TypeError` 当名称非法、指令已有 `install`，或安装目标无效。
- * @throws `Error` 当 App 中同名位置已经注册其他指令。
- */
-export declare function withInstallDirective<Value extends VueInstallValue>(directive: Value, name: string): Installable<Value>;
-//#endregion
-//# sourceMappingURL=install.d.mts.map

package/dist/vue/now.d.mts

@@ -1,13 +0,0 @@
-import { ShallowRef } from "vue";
-//#region src/vue/now.d.ts
-/**
- * 按固定间隔提供响应式当前时间。
- *
- * @param intervalMilliseconds - 更新时间间隔，默认 `1000` 毫秒。
- * @returns 当前 Date 的只读 ShallowRef；SSR 环境只返回调用时的时间。
- * @throws `Error` 当浏览器或 uni-app 环境中不存在可用于自动清理的 Vue 响应式作用域。
- * @throws `RangeError` 当间隔不是平台计时器支持的非负有限整数。
- */
-export declare function useNow(intervalMilliseconds?: number): Readonly<ShallowRef<Date>>;
-//#endregion
-//# sourceMappingURL=now.d.mts.map

package/dist/vue/props.d.mts

@@ -1,22 +0,0 @@
-import { ComputedRef, PropType } from "vue";
-//#region src/vue/props.d.ts
-/**
- * 为 Vue 运行时 Props 构造器附加泛型类型。
- *
- * @remarks 该函数只帮助 TypeScript 建模，不验证运行时值与 `Value` 一致；调用方仍应
- * 传入 Vue 支持的构造器或构造器数组。
- * @param runtimeType - Vue 支持的运行时构造器或构造器数组。
- * @returns 同一引用，仅在类型层收窄为 `PropType<Value>`。
- */
-export declare function definePropType<Value>(runtimeType: unknown): PropType<Value>;
-/**
- * 构建需要透传给子组件的响应式 Props。
- *
- * @param props - Vue `setup` 接收的只读响应式 Props 对象。
- * @param rawProps - 子组件的运行时 Props 配置。
- * @param ignoredProps - 不需要透传的 Props 名称。
- * @returns 只包含 `rawProps` 声明键且随 Props 更新的 ComputedRef。
- */
-export declare function useProps<Props extends object, RawProps extends object, IgnoredProp extends keyof RawProps = never>(props: Props, rawProps: RawProps, ignoredProps?: readonly IgnoredProp[]): ComputedRef<Omit<Pick<Props, Extract<keyof Props, keyof RawProps>>, Extract<IgnoredProp, keyof Props>>>;
-//#endregion
-//# sourceMappingURL=props.d.mts.map

package/dist/vue/render.d.mts

@@ -1,11 +0,0 @@
-import { VNode } from "vue";
-//#region src/vue/render.d.ts
-/**
- * 在当前 Vue 3 组件实例上安装 TSX 渲染函数。
- * @remarks `setup` 仍可返回状态对象，因此状态能够显示在 Vue Devtools 中。
- * @param render - 当前组件的渲染函数。
- * @throws 不在组件 `setup` 调用栈中使用时抛出 `Error`。
- */
-export declare function useRender(render: () => VNode): void;
-//#endregion
-//# sourceMappingURL=render.d.mts.map

package/dist/vue/resize-observer.d.mts

@@ -1,15 +0,0 @@
-import { MaybeRefOrGetter } from "vue";
-//#region src/vue/resize-observer.d.ts
-/** `useResizeObserver` 接受的元素或响应式元素。 */
-export type ResizeObserverTarget = MaybeRefOrGetter<Element | null | undefined>;
-/**
- * 监听元素尺寸变化，并随响应式目标切换和 Vue 作用域销毁自动断开。
- *
- * @param target - 原生元素、Ref 或 Getter。
- * @param callback - 原生 ResizeObserver 回调。
- * @param options - 原生元素观察选项。
- * @returns 可提前断开观察的停止函数；运行时不支持 ResizeObserver 时为空操作。
- */
-export declare function useResizeObserver(target: ResizeObserverTarget, callback: ResizeObserverCallback, options?: ResizeObserverOptions): () => void;
-//#endregion
-//# sourceMappingURL=resize-observer.d.mts.map

package/dist/vue/slots.d.mts

@@ -1,18 +0,0 @@
-import { SlotsType, VNode } from "vue";
-//#region src/vue/slots.d.ts
-/** Slot 名到 Props 类型的内部声明映射。 */
-type RawSlots = Record<string, unknown>;
-/** 根据 Slot Props 是否为 never 生成无参数或有参数的 Slot 签名。 */
-type VueSlot<Properties> = [Properties] extends [never] ? () => VNode[] : (properties: Properties) => VNode[];
-/** 把 Slot 名称与作用域参数映射为 Vue 3 Slot 函数。 */
-export type TypedSlots<Slots extends RawSlots> = { [Name in keyof Slots]: VueSlot<Slots[Name]>; };
-/** Vue 3 `slots` 选项接受的运行时声明与官方静态类型标记。 */
-export type TypedSlotsDeclaration<Slots extends RawSlots> = SlotsType<Partial<TypedSlots<Slots>>>;
-/**
- * 为 Options API 的 `slots` 选项创建带作用域参数的类型声明。
- *
- * @returns 运行时 `Object` 构造器，并携带仅供 TypeScript 使用的 Slot 类型标记。
- */
-export declare function makeSlots<Slots extends RawSlots>(): TypedSlotsDeclaration<Slots>;
-//#endregion
-//# sourceMappingURL=slots.d.mts.map

package/dist/vue/window-size.d.mts

@@ -1,16 +0,0 @@
-import { ShallowRef } from "vue";
-//#region src/vue/window-size.d.ts
-/** `useWindowSize` 返回的只读窗口尺寸。 */
-export interface UseWindowSizeReturn {
-  readonly width: Readonly<ShallowRef<number>>;
-  readonly height: Readonly<ShallowRef<number>>;
-}
-/**
- * 响应式读取浏览器窗口内部尺寸。
- *
- * @returns 随原生 `resize` 事件更新的只读宽度和高度；非浏览器环境均为 `0`。
- * @throws `Error` 当浏览器环境中不存在可用于自动清理的 Vue 响应式作用域。
- */
-export declare function useWindowSize(): UseWindowSizeReturn;
-//#endregion
-//# sourceMappingURL=window-size.d.mts.map

package/dist/vue/with.d.mts

@@ -1,11 +0,0 @@
-//#region src/vue/with.d.ts
-/**
- * 保留传入值并显式指定其 TypeScript 类型。
- *
- * @remarks 未传值时运行时结果为 `undefined`，仅适合为 reactive 对象的初始字段提供类型。
- * @param data - 可选的原始值。
- * @returns 传入值本身；省略时返回类型化的 `undefined`。
- */
-export declare function withDefineType<Value>(data?: Value): Value;
-//#endregion
-//# sourceMappingURL=with.d.mts.map

package/docs/API.md

@@ -1,155 +0,0 @@
-# Fast.Utils API
-
-Fast.Utils is a browser-first utility package targeting ES2022. Package managers use its ESM entry, while CDNs use the separately minified IIFE entry. Its application environments are modern browsers, WebViews, Vue 3, and uni-app.
-
-## Imports
-
-The package has one public root entry. Every utility, including the Vue helpers, is exposed as a named export.
-
-```ts
-import { chunk, configureStorage, installationIdentity, Local } from "@fast-china/utils";
-```
-
-Internal helpers are not public subpaths. Aggregate utility objects are not exported; import named functions so bundlers can remove unused code.
-
-## Storage
-
-`Local` and `Session` initialize lazily with the legacy-compatible `fast__` prefix, JSON codec, and `Date.now`. Calling `configureStorage` is optional unless the defaults must be overridden.
-
-```ts
-import { Local, Session } from "@fast-china/utils";
-
-Local.set("profile", { name: "Ada" }, { ttlMs: 3_600_000 });
-Session.set("draft", { step: 2 });
-
-Local.set("private-profile", { name: "Ada" }, { crypto: true });
-Local.get<{ name: string }>("private-profile", { crypto: true });
-```
-
-`Local` and `Session` provide `get`, `set`, `has`, `remove`, `removeByPrefix`, `keys`, `pruneExpired`, and namespace-scoped `clear`. Missing and expired values return `undefined`. Invalid TTL values, empty prefixes, malformed stored envelopes, unavailable platform storage, and conflicting repeated configuration throw errors. Native storage quota and privacy errors are propagated. Custom options must be configured before the first Storage operation.
-
-`get<Value = string>()` has the static return type `string | undefined` when its generic is omitted, so string entries can be read directly. The codec still restores the original JSON value at runtime and does not convert objects, arrays, or other non-string values to strings; pass an explicit generic when accurate type information is required.
-
-For uni-app, the first Storage operation or an explicit `configureStorage` call detects the global `uni` object and uses its synchronous Storage API. uni-app has no separate session backend, so `Session` throws when called in this mode.
-
-```ts
-import { Local } from "@fast-china/utils";
-
-Local.set("token", "value");
-```
-
-`configureStorage({ prefix: "admin:", crypto: true })` restores the old global prefix and Base64-obfuscation options. `Local` and `Session` `set/get` also accept a per-operation `{ crypto: boolean }`: `true` selects the Base64 codec, `false` selects the JSON codec, and omission uses the global codec. An operation override does not mutate global configuration. The current v3 envelope does not record its codec, so writes and reads of the same entry must use matching options; a mismatch throws a decoding error.
-
-`crypto: true` and `base64StorageCodec` are reversible encoding rather than encryption and must not protect secrets. A custom `codec` may be supplied instead of global `crypto`.
-
-`decodeBase64`, `decodeBase64Url`, `decodeLatin1Base64`, and `decodeSecureBase64` return the primitive-string `DecodedText` type. It is directly assignable to `string` and supports strict equality; an explicit `.parseJson<T = any>()` call attempts JSON parsing and returns the unchanged source string when its syntax is invalid. The first text decode lazily installs a non-enumerable `String.prototype.parseJson`; a foreign property with the same name causes a `TypeError` instead of being overwritten. The generic type describes the expected shape but neither validates it nor guarantees an object result at runtime. Storage codecs do not use this fallback and continue to reject invalid JSON strictly.
-
-`encodeSecureBase64` and `decodeSecureBase64` preserve the legacy dictionary payload. The random prefix prefers Web Crypto and falls back to `Math.random()` when unavailable; it does not provide a security property. Given the same default six-character prefix, valid legacy payloads remain byte-for-byte compatible. The old dictionary references an unavailable character for Base64 lengths 101–124, so the current implementation inserts a one-character fallback that the legacy removal flow can decode. The old custom-length argument always generated six random characters; the current API correctly generates `prefixLength` characters. Custom lengths must match during encoding and decoding; `0` disables both the prefix and dictionary insertion. The format remains reversible encoding rather than encryption.
-
-## Identity
-
-`installationIdentity` is the global installation identifier facade. Call `configureInstallationIdentity` in the application entry before first use to override its `identity:installation-id` cache key. `getOrCreateInstallationId(installationId?)` loads, creates, or replaces its UUID v4 value in `Local` storage. Storage uses its defaults when no explicit configuration was supplied. UUID generation prefers Web Crypto and falls back to `Math.random()` when unavailable.
-
-```ts
-import { configureInstallationIdentity, configureStorage, getOrCreateInstallationId, installationIdentity } from "@fast-china/utils";
-
-configureStorage({ prefix: "app:" });
-configureInstallationIdentity({ cacheKey: "account:installation-id" });
-getOrCreateInstallationId();
-installationIdentity.read();
-installationIdentity.clear();
-```
-
-The identifier is an installation-scoped value, not a hardware identifier, authentication credential, secret, or anti-fraud signal.
-
-## Logger
-
-Logger scope belongs to each entry rather than a logger or child instance. The default `logger` works without construction and has a minimum level of `debug`. Configure it once
-at application startup when uni-app App-Plus needs split object output:
-
-```ts
-import { configureLogger, logger } from "@fast-china/utils";
-
-configureLogger({ uniAppPlusSplit: true });
-logger.log("Launch", { code: 200, data: { id: 1 } });
-logger.log("storage", "profile loaded", { userId: 1 });
-logger.error("network", "request failed", error);
-```
-
-Log content is optional and may directly contain objects, arrays, `Error` instances, or other values. Non-string values are passed unchanged to
-the Sink in normal runtimes. With App-Plus splitting enabled, the heading is emitted separately and each additional value is converted to readable
-text because HBuilderX does not reliably display objects.
-
-`configureLogger` replaces the complete configuration of the default `logger`; previously retained `logger` references immediately observe the new
-configuration. Calling it without options restores all defaults. `createLogger` creates an isolated instance unaffected by global configuration.
-Logger's `debug`, `log`, `warn`, and `error` methods call the matching Sink methods; the default Sink maps them to `console.debug`, `console.log`, `console.warn`, and `console.error`. Both support a minimum level, brand prefix, Sink, and optional App-Plus split output. Scope must be a non-empty string without surrounding whitespace.
-
-## Clipboard
-
-`copy(value)` restores the V1 text-copy capability and returns `Promise<void>`. uni-app uses `setClipboardData`; browsers prefer the Clipboard API and fall back to `document.execCommand("copy")` when it is unavailable. Missing capabilities, denied permission, and copy failures throw errors.
-
-```ts
-import { copy } from "@fast-china/utils";
-
-await copy("Fast utilities");
-```
-
-## Crypto
-
-The TypeScript Crypto public API mirrors the public methods and algorithm casing of .NET `CryptoUtil`:
-
-| Capability                       | Shared method names                                                                                                                  |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| Random bytes and byte comparison | `GenerateRandomBytes`, `FixedTimeEquals`                                                                                             |
-| MD5, SHA-1, and SHA-2 digests    | `MD5Encrypt`, `SHA1Encrypt`, `SHA256Encrypt`, `SHA256Bytes`, `SHA384Encrypt`, `SHA384Bytes`, `SHA512Encrypt`, `SHA512Bytes`          |
-| HMAC                             | `HMACSHA256Encrypt`, `HMACSHA384Encrypt`, `HMACSHA512Encrypt`                                                                        |
-| Password derivation and hashing  | `PBKDF2SHA256`, `HashPasswordPBKDF2SHA256`, `VerifyPasswordPBKDF2SHA256`                                                             |
-| HKDF                             | `HKDFSHA256`                                                                                                                         |
-| AES                              | `AESEncrypt`, `AESDecrypt`, `AESEncryptAuthenticated`, `AESDecryptAuthenticated`, `AESEncryptWithPassword`, `AESDecryptWithPassword` |
-| RSA                              | `GenerateRSAKeyPair`, `RSAEncryptOAEP`, `RSADecryptOAEP`, `RSASignPSS`, `RSAVerifyPSS`                                               |
-| Elliptic curves                  | `GenerateECDSAKeyPair`, `ECDSASign`, `ECDSAVerify`, `GenerateECDHKeyPair`, `DeriveECDHSecret`, `DeriveECDHKeySHA256`                 |
-
-The Base64 v1 payload produced by `AESEncryptAuthenticated`, the `FAST-AES-256-GCM-V1` password payload, PBKDF2 password hashes, and PKCS#8/SPKI PEM keys interoperate with .NET in both directions. MD5 and HMAC output lowercase hexadecimal; SHA-1/256/384/512 output uppercase hexadecimal, matching .NET.
-
-`AESDecrypt`, `AESDecryptAuthenticated`, `AESDecryptWithPassword`, and `RSADecryptOAEP` return the primitive-string `DecodedText` type (wrapped in a Promise for asynchronous APIs). Use the result directly as plaintext or call `.parseJson<T = any>()` explicitly:
-
-```ts
-const plaintext = await AESDecryptWithPassword(payload, password);
-const raw: string = plaintext;
-const result = plaintext.parseJson<{ id: number }>();
-```
-
-Store passwords with `HashPasswordPBKDF2SHA256` and `VerifyPasswordPBKDF2SHA256`; the result is not decryptable. AES-GCM provides confidentiality and integrity, HMAC authenticates with a shared key, SHA-2 computes digests, and HKDF/PBKDF2 derive keys. MD5, SHA-1, AES-CBC, and AES-ECB do not provide modern password-storage or authenticated-encryption guarantees.
-
-## Modules
-
-- `array`: `chunk`, `removeNullishValues`, `unique`, `uniqueBy`, `groupBy`, `partition`, `difference`, `intersection`, `symmetricDifference`, `hasDuplicatesBy`, and `allEqualBy`.
-- `async`: abort-aware `sleep`, timeout, retry, bounded concurrent mapping, debounce, and throttle primitives.
-- `base64`: strict UTF-8 Base64/Base64URL byte functions and chainable text results plus the historical Latin-1 and dictionary-obfuscation functions.
-- `color`: Hex parsing/formatting/mixing, explicit black/white mixing, luminance, and contrast helpers.
-- `crypto`: random bytes, digests, HMAC, PBKDF2, HKDF, AES, RSA-OAEP/PSS, ECDSA, and ECDH.
-- `date`: date validation and arithmetic, day ranges, relative formatting, and the seven historical date helpers as named functions.
-- `dom`: CSS unit and style serialization helpers.
-- `env`: capability and user-agent detection. Detection does not expand the supported runtime contract.
-- `function`: `once` execution with cached return, Promise identity, and synchronous-error behavior.
-- `logger`: isolated configurable loggers and the default `logger`.
-- `number`: ranges, rounding, aggregation, interpolation, byte formatting, and Web Crypto-preferred `randomInt`.
-- `object`: deep cloning and equality, prototype-safe key and predicate selection, mapping, and query serialization. Style serialization is provided by the `dom` module.
-- `string`: query parsing, casing, grapheme-aware truncation, clipboard copying, UUID, Web Crypto-preferred `randomString`, escaping, and whitespace normalization.
-- `vue`: Vue 3 helpers plus native-backed `useEventListener`, `useWindowSize`, `useResizeObserver`, `useElementSize`, `useNow`, and `useBreakpoints` composables. They intentionally cover common browser use rather than the full VueUse option surface.
-
-## Security and limits
-
-AES-GCM provides confidentiality and integrity; AES-CBC/ECB do not authenticate ciphertexts. MD5, SHA-1, and the historical Base64 dictionary must not protect passwords, signatures, or sensitive data. Cryptographic helpers enforce algorithm-specific parameter and payload limits and require Web Crypto where applicable.
-
-Query and object helpers reject prototype-polluting keys. URL decoders are bounded. Storage cleanup is always restricted to the configured namespace. Browser globals are resolved only when an API is called, never during module import.
-
-## Errors and compatibility
-
-Programming errors, invalid inputs, unsupported platform capabilities, and malformed protected data throw native errors unless a function explicitly documents a nullable result.
-
-Since Fast.Utils 2.1.1, built-in validation and runtime failure messages are Chinese. Consumers must branch on native error types instead of matching message text.
-
-`randomInt`, `randomString`, `generateUuidV4`, and `GenerateRandomBytes` all prefer Web Crypto and fall back to `Math.random()` when unavailable.
-
-Fast.Utils 2.1.0 removes `secureRandomInt` and `secureRandomString`. This is a breaking change; consumers must migrate to `randomInt` and `randomString`, respectively.

package/docs/API.zh-CN.md

@@ -1,154 +0,0 @@
-# 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.set("private-profile", { name: "Ada" }, { crypto: true });
-Local.get<{ name: string }>("private-profile", { crypto: true });
-```
-
-`Local` 和 `Session` 提供 `get`、`set`、`has`、`remove`、`removeByPrefix`、`keys`、`pruneExpired` 和仅清理当前命名空间的 `clear`。键缺失或过期时返回 `undefined`。TTL 非法、Prefix 为空、存储包络损坏、平台 Storage 不可用或重复配置发生冲突时抛出错误；浏览器配额与隐私策略错误直接向上传播。自定义选项必须在首次 Storage 操作前配置。
-
-`get<Value = string>()` 在未传泛型时的静态返回类型为 `string | undefined`，可以直接读取字符串条目。Codec 在运行时仍通过 JSON 反序列化恢复原值，因此对象、数组或其他非字符串值不会被转换成字符串；需要准确类型提示时显式传入对应泛型。
-
-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 混淆选项。`Local` 与 `Session` 的 `set/get` 也接受单次 `{ crypto: boolean }`：`true` 使用 Base64 Codec，`false` 使用 JSON Codec，省略时沿用全局 Codec。单次设置不会修改全局配置；当前 v3 包络不记录 Codec，读写同一条目时必须传入一致选项，错误配置会明确抛出解码错误。
-
-`crypto: true` 和 `base64StorageCodec` 都只是可逆编码，不是加密，不能保护敏感数据。可以使用自定义 `codec` 替代全局 `crypto`。
-
-`decodeBase64`、`decodeBase64Url`、`decodeLatin1Base64` 与 `decodeSecureBase64` 返回原始字符串类型 `DecodedText`，可以直接赋值给 `string` 或参与严格比较；显式调用 `.parseJson<T = any>()` 才尝试解析 JSON，语法无效时返回未经修改的原始字符串。首次文本解码会按需安装不可枚举的 `String.prototype.parseJson`；若同名属性已被其他实现占用则抛出 `TypeError`，不会覆盖。泛型只描述期望类型，不执行运行时结构校验，也不保证结果一定是对象。Storage Codec 不使用该容错行为，仍会严格拒绝非法 JSON。
-
-`encodeSecureBase64` 与 `decodeSecureBase64` 保留旧字典兼容载荷。随机前缀优先使用 Web Crypto，能力缺失时回退到 `Math.random()`；它不承担安全用途。给定相同的默认 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 实例中。默认 `logger` 无需创建即可使用，最低输出级别为 `debug`；uni-app App-Plus
-需要拆分对象输出时，在应用入口配置一次：
-
-```ts
-import { configureLogger, logger } from "@fast-china/utils";
-
-configureLogger({ uniAppPlusSplit: true });
-logger.log("Launch", { code: 200, data: { id: 1 } });
-logger.log("storage", "profile loaded", { userId: 1 });
-logger.error("network", "request failed", error);
-```
-
-日志内容可省略，也可以直接传入对象、数组、`Error` 等任意值。普通环境会把非字符串值原样传给 Sink；启用 App-Plus
-拆分输出后，为解决 HBuilderX 无法正确显示对象的问题，标题单独输出，附加值逐条转换为可读文本。
-
-`configureLogger` 会替换默认 `logger` 的完整配置，已经保存的 `logger` 引用也会立即使用新配置；无参数调用会恢复默认值。
-`createLogger` 用于创建不受全局配置影响的独立实例。Logger 的 `debug`、`log`、`warn`、`error` 分别调用 Sink 的同名方法，默认 Sink 对应 `console.debug`、`console.log`、`console.warn`、`console.error`。两者均支持最低级别、品牌前缀、Sink 和可选的 App-Plus 拆分输出。
-作用域必须是无外围空白的非空字符串。
-
-## 剪贴板
-
-`copy(value)` 恢复 V1 的文本复制能力，并返回 `Promise<void>`。uni-app 使用 `setClipboardData`；浏览器优先使用 Clipboard API，不可用时回退到 `document.execCommand("copy")`。平台能力缺失、权限被拒绝或复制失败时会抛出错误。
-
-```ts
-import { copy } from "@fast-china/utils";
-
-await copy("Fast 工具库");
-```
-
-## 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-V1` 载荷、PBKDF2 密码哈希以及 PKCS#8/SPKI PEM 密钥均可与 .NET 双向使用。MD5 与 HMAC 输出小写十六进制；SHA-1/256/384/512 输出大写十六进制，与 .NET 保持一致。
-
-`AESDecrypt`、`AESDecryptAuthenticated`、`AESDecryptWithPassword` 与 `RSADecryptOAEP` 返回原始字符串类型 `DecodedText`（异步入口返回其 Promise）。返回值可直接作为明文字符串使用，也可通过 `.parseJson<T = any>()` 显式解析 JSON：
-
-```ts
-const plaintext = await AESDecryptWithPassword(payload, password);
-const raw: string = plaintext;
-const result = plaintext.parseJson<{ id: number }>();
-```
-
-密码存储使用 `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 检测；检测函数不扩大运行时支持范围。
-- `function`：最多执行一次并缓存返回值、Promise 引用或同步错误的 `once`。
-- `logger`：隔离的可配置 Logger 和默认 `logger`。
-- `number`：范围、舍入、聚合、插值、字节格式化，以及优先使用 Web Crypto 的 `randomInt`。
-- `object`：深复制、深度比较、防原型污染的键和条件筛选、映射及 Query 序列化；Style 序列化由 `dom` 模块提供。
-- `string`：Query 解析、大小写、字素截断、剪贴板复制、UUID、优先使用 Web Crypto 的 `randomString`、转义和空白规范化。
-- `vue`：Vue 3 Helper，以及基于原生能力的 `useEventListener`、`useWindowSize`、`useResizeObserver`、`useElementSize`、`useNow` 和 `useBreakpoints`。这些 Composable 面向常用浏览器场景，不提供 VueUse 的完整选项面。
-
-## 安全与限制
-
-AES-GCM 提供机密性和完整性；AES-CBC/ECB 不提供认证。MD5、SHA-1 和历史 Base64 字典不能用于密码存储、签名或受保护数据。Crypto API 按算法限制参数和载荷大小，并在需要时强制要求 Web Crypto。
-
-Query 与 Object API 拒绝原型污染键，URL 解码有最大深度，Storage 清理只作用于配置的命名空间。浏览器全局对象只在调用 API 时解析，模块导入阶段不会访问。
-
-## 错误与兼容性
-
-除明确说明返回空值的函数外，编程错误、非法输入、平台能力缺失和受保护数据损坏均抛出原生错误。
-
-自 Fast.Utils 2.1.1 起，内置校验与运行时失败消息统一使用中文；调用方应依据原生错误类型分支，不应匹配消息文本。
-
-`randomInt`、`randomString`、`generateUuidV4` 与 `GenerateRandomBytes` 默认都优先使用 Web Crypto，能力缺失时回退到 `Math.random()`。
-
-Fast.Utils 2.1.0 已删除 `secureRandomInt` 与 `secureRandomString`，这是破坏性修改；调用方应分别改用 `randomInt` 与 `randomString`。