@fast-china/utils 1.0.38 → 2.0.0

package/dist/vue/install.d.mts

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

package/dist/vue/install.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.mts","names":[],"sources":["../../src/vue/install.ts"],"mappings":";;UACiB;;;;;;;;EAQhB,YAAY,cAAc;;;;;;;;EAQ1B,YAAY,cAAc;;;KAIf,gCAAgC;;KAGhC,YAAY,SAAS;;;;;EAKhC,UAAU;;;KAIC,eAAe,SAAS,YAAY;;;;;;;;;;;;iBA0EhC,YAAY,aAAa,iBAAiB,eAAe,eAAe,mBAAmB,sBAC1G,MAAM,MACN,SAAS,SACP,YAAY,QAAQ;;;;;;;;;;iBAyCP,gBAAgB,cAAc,iBAAiB,WAAW,QAAQ,eAAe;;;;;;;;;;;;iBAkBjF,qBAAqB,cAAc,iBAAiB,WAAW,OAAO,eAAe,YAAY"}

package/dist/vue/install.mjs

@@ -0,0 +1,123 @@
+//#region src/vue/install.ts
+/**
+* 校验 Vue 插件安装目标。
+*
+* @param value - Vue 2.7 构造器或 Vue 3 App 实例。
+* @returns 只包含组件和指令注册能力的结构化目标。
+* @throws `TypeError` 当目标缺少 `component` 或 `directive` 方法。
+*/
+const assertTarget = (value) => {
+	if (typeof value !== "object" && typeof value !== "function" || value === null) throw new TypeError("Vue plugin installation requires a Vue constructor or App.");
+	const target = value;
+	if (typeof target.component !== "function" || typeof target.directive !== "function") throw new TypeError("Vue plugin installation requires component() and directive() registration methods.");
+	return target;
+};
+/**
+* 提取组件的全局注册名称。
+*
+* @param component - 待注册组件。
+* @returns 去除外围空白后的显式名称。
+* @throws `TypeError` 当组件没有非空字符串名称。
+*/
+const getComponentName = (component) => {
+	const name = component.name;
+	if (typeof name !== "string" || name.length === 0 || /\s/u.test(name)) throw new TypeError("Installable Vue components must expose a non-empty name without whitespace.");
+	return name;
+};
+/**
+* 预检单个组件注册。
+*
+* @remarks 先读取同名组件并完成冲突判断，再返回延迟执行动作；调用方可以在所有组件预检通过后统一提交。
+* @param target - 已校验的 Vue 注册目标。
+* @param component - 待注册组件。
+* @returns 已校验的组件引用、名称和目标中是否已经存在同一引用。
+* @throws `Error` 当同名位置已由其他组件占用。
+*/
+const prepareComponentRegistration = (target, component) => {
+	const name = getComponentName(component);
+	const existing = target.component(name);
+	if (existing !== void 0 && existing !== component) throw new Error(`Vue component name "${name}" is already registered by another component.`);
+	return {
+		component,
+		name,
+		registered: existing === component
+	};
+};
+/**
+* 为主组件附加 Vue 2.7 `Vue.use()` 与 Vue 3 `app.use()` 安装能力。
+*
+* @remarks 函数会直接为 `main` 定义附属组件属性和 `install`。所有组件名称、附属属性
+* 冲突会在修改 `main` 前完成校验；安装到 App 时也会先预检全部全局名称，再统一注册。
+* @param main - 具有非空 `name` 的组件。
+* @param extras - 同时注册并以可枚举属性挂到主组件的附属组件映射。
+* @returns 原始 `main` 引用，并附加类型化的 `install` 与 `extras` 属性。
+* @throws `TypeError` 当组件缺少合法名称、已有 `install`、附属键或名称发生冲突。
+* @throws `Error` 当安装目标中同名位置已经注册其他组件。
+*/
+function withInstall(main, extras) {
+	const componentNames = /* @__PURE__ */ new Set([getComponentName(main)]);
+	if ("install" in Object(main)) throw new TypeError("The Vue component already defines an install property.");
+	const extraEntries = Object.entries(extras ?? {});
+	if (extras !== void 0 && Object.getOwnPropertySymbols(extras).some((key) => Object.prototype.propertyIsEnumerable.call(extras, key))) throw new TypeError("Vue component extras must use string property names.");
+	for (const [key, component] of extraEntries) {
+		const componentName = getComponentName(component);
+		if (componentNames.has(componentName)) throw new TypeError(`Vue component name "${componentName}" is registered more than once.`);
+		componentNames.add(componentName);
+		if (key === "install" || key in Object(main)) throw new TypeError(`Vue component extra "${key}" would overwrite a property on the main component.`);
+	}
+	const installable = main;
+	for (const [key, component] of extraEntries) Object.defineProperty(installable, key, {
+		configurable: true,
+		enumerable: true,
+		value: component,
+		writable: true
+	});
+	installable.install = (value) => {
+		const target = assertTarget(value);
+		const registrations = [main, ...extraEntries.map(([, component]) => component)].map((component) => prepareComponentRegistration(target, component));
+		for (const registration of registrations) if (!registration.registered) target.component(registration.name, registration.component);
+	};
+	return installable;
+}
+/**
+* 为不需要单独注册的附属组件附加空安装函数。
+*
+* @remarks 适用于只能作为主组件附属属性使用、但仍需满足 Vue Plugin 类型的组件。
+* 函数直接修改并返回传入组件，不会向 Vue 全局组件表注册内容。
+* @param component - 尚未定义或继承 `install` 属性的组件。
+* @returns 原组件引用及无副作用的 `install` 方法。
+* @throws `TypeError` 当组件自身或原型链已经存在 `install`。
+*/
+function withNoopInstall(component) {
+	if ("install" in Object(component)) throw new TypeError("The Vue component already defines an install property.");
+	const installable = component;
+	installable.install = () => void 0;
+	return installable;
+}
+/**
+* 为 Vue 2.7/3 指令附加插件安装能力。
+*
+* @remarks 函数直接修改并返回指令。安装时重复注册同一引用保持幂等，不会覆盖同名的
+* 其他指令。名称只传给 `directive()`，不得包含 `v-` 前缀。
+* @param directive - 尚未定义或继承 `install` 属性的 Vue 指令对象。
+* @param name - 非空、无空白且不以 `v-` 开头的全局指令名。
+* @returns 原指令引用及 Vue Plugin `install` 方法。
+* @throws `TypeError` 当名称非法、指令已有 `install`，或安装目标无效。
+* @throws `Error` 当安装目标中同名位置已经注册其他指令。
+*/
+function withInstallDirective(directive, name) {
+	if (name.length === 0 || /\s/u.test(name) || name.startsWith("v-")) throw new TypeError("Installable Vue directives require a name without whitespace or a v- prefix.");
+	if ("install" in Object(directive)) throw new TypeError("The Vue directive already defines an install property.");
+	const installable = directive;
+	installable.install = (value) => {
+		const target = assertTarget(value);
+		const existing = target.directive(name);
+		if (existing !== void 0 && existing !== directive) throw new Error(`Vue directive name "${name}" is already registered by another directive.`);
+		if (existing !== directive) target.directive(name, directive);
+	};
+	return installable;
+}
+//#endregion
+export { withInstall, withInstallDirective, withNoopInstall };
+
+//# sourceMappingURL=install.mjs.map

package/dist/vue/install.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.mjs","names":[],"sources":["../../src/vue/install.ts"],"sourcesContent":["/** Vue 2.7 构造器与 Vue 3 App 共有的组件、指令注册能力。 */\nexport interface VueRegistrationTarget {\n\t/**\n\t * 读取或注册全局组件。\n\t *\n\t * @param name - 全局组件名。\n\t * @param component - 注册时传入的组件；省略时读取现有组件。\n\t * @returns Vue 平台返回的现有组件、注册结果或目标自身。\n\t */\n\tcomponent: (name: string, component?: unknown) => unknown;\n\t/**\n\t * 读取或注册全局指令。\n\t *\n\t * @param name - 不带 `v-` 的全局指令名。\n\t * @param directive - 注册时传入的指令；省略时读取现有指令。\n\t * @returns Vue 平台返回的现有指令、注册结果或目标自身。\n\t */\n\tdirective: (name: string, directive?: unknown) => unknown;\n}\n\n/** Vue 组件对象、函数组件或指令对象可接受的最小结构类型。 */\nexport type VueInstallValue = object | ((...arguments_: never[]) => unknown);\n\n/** 为 Vue 组件或指令附加供 Vue 2.7 `Vue.use()` 与 Vue 3 `app.use()` 调用的安装能力。 */\nexport type Installable<Value> = Value & {\n\t/**\n\t * 把当前组件或指令安装到 Vue 2.7 构造器或 Vue 3 App。\n\t * @param target - Vue 2.7 构造器或 Vue 3 App 实例。\n\t */\n\tinstall: (target: unknown) => void;\n};\n\n/** TSX 组件安装类型；与 {@link Installable} 保持同一运行时契约。 */\nexport type TSXWithInstall<Value> = Installable<Value>;\n\n/**\n * 校验 Vue 插件安装目标。\n *\n * @param value - Vue 2.7 构造器或 Vue 3 App 实例。\n * @returns 只包含组件和指令注册能力的结构化目标。\n * @throws `TypeError` 当目标缺少 `component` 或 `directive` 方法。\n */\nconst assertTarget = (value: unknown): VueRegistrationTarget => {\n\tif ((typeof value !== \"object\" && typeof value !== \"function\") || value === null) {\n\t\tthrow new TypeError(\"Vue plugin installation requires a Vue constructor or App.\");\n\t}\n\tconst target = value as Partial<VueRegistrationTarget>;\n\tif (typeof target.component !== \"function\" || typeof target.directive !== \"function\") {\n\t\tthrow new TypeError(\"Vue plugin installation requires component() and directive() registration methods.\");\n\t}\n\treturn target as VueRegistrationTarget;\n};\n\n/**\n * 提取组件的全局注册名称。\n *\n * @param component - 待注册组件。\n * @returns 去除外围空白后的显式名称。\n * @throws `TypeError` 当组件没有非空字符串名称。\n */\nconst getComponentName = (component: VueInstallValue): string => {\n\tconst name = (component as { name?: unknown }).name;\n\tif (typeof name !== \"string\" || name.length === 0 || /\\s/u.test(name)) {\n\t\tthrow new TypeError(\"Installable Vue components must expose a non-empty name without whitespace.\");\n\t}\n\treturn name;\n};\n\n/** 预检完成、可以无失败注册的组件动作。 */\ninterface ComponentRegistration {\n\t/** 已校验的组件引用。 */\n\tcomponent: VueInstallValue;\n\t/** 已校验的组件名称。 */\n\tname: string;\n\t/** 目标中是否已经注册了完全相同的组件引用。 */\n\tregistered: boolean;\n}\n\n/**\n * 预检单个组件注册。\n *\n * @remarks 先读取同名组件并完成冲突判断，再返回延迟执行动作；调用方可以在所有组件预检通过后统一提交。\n * @param target - 已校验的 Vue 注册目标。\n * @param component - 待注册组件。\n * @returns 已校验的组件引用、名称和目标中是否已经存在同一引用。\n * @throws `Error` 当同名位置已由其他组件占用。\n */\nconst prepareComponentRegistration = (target: VueRegistrationTarget, component: VueInstallValue): ComponentRegistration => {\n\tconst name = getComponentName(component);\n\tconst existing = target.component(name);\n\tif (existing !== undefined && existing !== component) {\n\t\tthrow new Error(`Vue component name \"${name}\" is already registered by another component.`);\n\t}\n\treturn { component, name, registered: existing === component };\n};\n\n/**\n * 为主组件附加 Vue 2.7 `Vue.use()` 与 Vue 3 `app.use()` 安装能力。\n *\n * @remarks 函数会直接为 `main` 定义附属组件属性和 `install`。所有组件名称、附属属性\n * 冲突会在修改 `main` 前完成校验；安装到 App 时也会先预检全部全局名称，再统一注册。\n * @param main - 具有非空 `name` 的组件。\n * @param extras - 同时注册并以可枚举属性挂到主组件的附属组件映射。\n * @returns 原始 `main` 引用，并附加类型化的 `install` 与 `extras` 属性。\n * @throws `TypeError` 当组件缺少合法名称、已有 `install`、附属键或名称发生冲突。\n * @throws `Error` 当安装目标中同名位置已经注册其他组件。\n */\nexport function withInstall<Main extends VueInstallValue, Extras extends Record<string, VueInstallValue> = Record<never, never>>(\n\tmain: Main,\n\textras?: Extras\n): Installable<Main> & Extras {\n\tconst componentNames = new Set([getComponentName(main)]);\n\tif (\"install\" in Object(main)) throw new TypeError(\"The Vue component already defines an install property.\");\n\tconst extraEntries = Object.entries(extras ?? {});\n\tif (extras !== undefined && Object.getOwnPropertySymbols(extras).some((key) => Object.prototype.propertyIsEnumerable.call(extras, key))) {\n\t\tthrow new TypeError(\"Vue component extras must use string property names.\");\n\t}\n\tfor (const [key, component] of extraEntries) {\n\t\tconst componentName = getComponentName(component);\n\t\tif (componentNames.has(componentName)) throw new TypeError(`Vue component name \"${componentName}\" is registered more than once.`);\n\t\tcomponentNames.add(componentName);\n\t\tif (key === \"install\" || key in Object(main)) {\n\t\t\tthrow new TypeError(`Vue component extra \"${key}\" would overwrite a property on the main component.`);\n\t\t}\n\t}\n\tconst installable = main as Installable<Main> & Extras;\n\tfor (const [key, component] of extraEntries) {\n\t\tObject.defineProperty(installable, key, { configurable: true, enumerable: true, value: component, writable: true });\n\t}\n\tinstallable.install = (value: unknown): void => {\n\t\tconst target = assertTarget(value);\n\t\t// 先完成全部冲突检查，再统一注册，避免安装到一半留下部分全局组件。\n\t\tconst registrations = [main, ...extraEntries.map(([, component]) => component)].map((component) =>\n\t\t\tprepareComponentRegistration(target, component)\n\t\t);\n\t\tfor (const registration of registrations) {\n\t\t\tif (!registration.registered) target.component(registration.name, registration.component);\n\t\t}\n\t};\n\treturn installable;\n}\n\n/**\n * 为不需要单独注册的附属组件附加空安装函数。\n *\n * @remarks 适用于只能作为主组件附属属性使用、但仍需满足 Vue Plugin 类型的组件。\n * 函数直接修改并返回传入组件，不会向 Vue 全局组件表注册内容。\n * @param component - 尚未定义或继承 `install` 属性的组件。\n * @returns 原组件引用及无副作用的 `install` 方法。\n * @throws `TypeError` 当组件自身或原型链已经存在 `install`。\n */\nexport function withNoopInstall<Value extends VueInstallValue>(component: Value): TSXWithInstall<Value> {\n\tif (\"install\" in Object(component)) throw new TypeError(\"The Vue component already defines an install property.\");\n\tconst installable = component as TSXWithInstall<Value>;\n\tinstallable.install = (): void => undefined;\n\treturn installable;\n}\n\n/**\n * 为 Vue 2.7/3 指令附加插件安装能力。\n *\n * @remarks 函数直接修改并返回指令。安装时重复注册同一引用保持幂等，不会覆盖同名的\n * 其他指令。名称只传给 `directive()`，不得包含 `v-` 前缀。\n * @param directive - 尚未定义或继承 `install` 属性的 Vue 指令对象。\n * @param name - 非空、无空白且不以 `v-` 开头的全局指令名。\n * @returns 原指令引用及 Vue Plugin `install` 方法。\n * @throws `TypeError` 当名称非法、指令已有 `install`，或安装目标无效。\n * @throws `Error` 当安装目标中同名位置已经注册其他指令。\n */\nexport function withInstallDirective<Value extends VueInstallValue>(directive: Value, name: string): Installable<Value> {\n\tif (name.length === 0 || /\\s/u.test(name) || name.startsWith(\"v-\")) {\n\t\tthrow new TypeError(\"Installable Vue directives require a name without whitespace or a v- prefix.\");\n\t}\n\tif (\"install\" in Object(directive)) throw new TypeError(\"The Vue directive already defines an install property.\");\n\tconst installable = directive as Installable<Value>;\n\tinstallable.install = (value: unknown): void => {\n\t\tconst target = assertTarget(value);\n\t\tconst existing = target.directive(name);\n\t\tif (existing !== undefined && existing !== directive) {\n\t\t\tthrow new Error(`Vue directive name \"${name}\" is already registered by another directive.`);\n\t\t}\n\t\tif (existing !== directive) target.directive(name, directive);\n\t};\n\treturn installable;\n}\n"],"mappings":";;;;;;;;AA0CA,MAAM,gBAAgB,UAA0C;CAC/D,IAAK,OAAO,UAAU,YAAY,OAAO,UAAU,cAAe,UAAU,MAC3E,MAAM,IAAI,UAAU,4DAA4D;CAEjF,MAAM,SAAS;CACf,IAAI,OAAO,OAAO,cAAc,cAAc,OAAO,OAAO,cAAc,YACzE,MAAM,IAAI,UAAU,oFAAoF;CAEzG,OAAO;AACR;;;;;;;;AASA,MAAM,oBAAoB,cAAuC;CAChE,MAAM,OAAQ,UAAiC;CAC/C,IAAI,OAAO,SAAS,YAAY,KAAK,WAAW,KAAK,MAAM,KAAK,IAAI,GACnE,MAAM,IAAI,UAAU,6EAA6E;CAElG,OAAO;AACR;;;;;;;;;;AAqBA,MAAM,gCAAgC,QAA+B,cAAsD;CAC1H,MAAM,OAAO,iBAAiB,SAAS;CACvC,MAAM,WAAW,OAAO,UAAU,IAAI;CACtC,IAAI,aAAa,KAAA,KAAa,aAAa,WAC1C,MAAM,IAAI,MAAM,uBAAuB,KAAK,8CAA8C;CAE3F,OAAO;EAAE;EAAW;EAAM,YAAY,aAAa;CAAU;AAC9D;;;;;;;;;;;;AAaA,SAAgB,YACf,MACA,QAC6B;CAC7B,MAAM,iCAAiB,IAAI,IAAI,CAAC,iBAAiB,IAAI,CAAC,CAAC;CACvD,IAAI,aAAa,OAAO,IAAI,GAAG,MAAM,IAAI,UAAU,wDAAwD;CAC3G,MAAM,eAAe,OAAO,QAAQ,UAAU,CAAC,CAAC;CAChD,IAAI,WAAW,KAAA,KAAa,OAAO,sBAAsB,MAAM,CAAC,CAAC,MAAM,QAAQ,OAAO,UAAU,qBAAqB,KAAK,QAAQ,GAAG,CAAC,GACrI,MAAM,IAAI,UAAU,sDAAsD;CAE3E,KAAK,MAAM,CAAC,KAAK,cAAc,cAAc;EAC5C,MAAM,gBAAgB,iBAAiB,SAAS;EAChD,IAAI,eAAe,IAAI,aAAa,GAAG,MAAM,IAAI,UAAU,uBAAuB,cAAc,gCAAgC;EAChI,eAAe,IAAI,aAAa;EAChC,IAAI,QAAQ,aAAa,OAAO,OAAO,IAAI,GAC1C,MAAM,IAAI,UAAU,wBAAwB,IAAI,oDAAoD;CAEtG;CACA,MAAM,cAAc;CACpB,KAAK,MAAM,CAAC,KAAK,cAAc,cAC9B,OAAO,eAAe,aAAa,KAAK;EAAE,cAAc;EAAM,YAAY;EAAM,OAAO;EAAW,UAAU;CAAK,CAAC;CAEnH,YAAY,WAAW,UAAyB;EAC/C,MAAM,SAAS,aAAa,KAAK;EAEjC,MAAM,gBAAgB,CAAC,MAAM,GAAG,aAAa,KAAK,GAAG,eAAe,SAAS,CAAC,CAAC,CAAC,KAAK,cACpF,6BAA6B,QAAQ,SAAS,CAC/C;EACA,KAAK,MAAM,gBAAgB,eAC1B,IAAI,CAAC,aAAa,YAAY,OAAO,UAAU,aAAa,MAAM,aAAa,SAAS;CAE1F;CACA,OAAO;AACR;;;;;;;;;;AAWA,SAAgB,gBAA+C,WAAyC;CACvG,IAAI,aAAa,OAAO,SAAS,GAAG,MAAM,IAAI,UAAU,wDAAwD;CAChH,MAAM,cAAc;CACpB,YAAY,gBAAsB,KAAA;CAClC,OAAO;AACR;;;;;;;;;;;;AAaA,SAAgB,qBAAoD,WAAkB,MAAkC;CACvH,IAAI,KAAK,WAAW,KAAK,MAAM,KAAK,IAAI,KAAK,KAAK,WAAW,IAAI,GAChE,MAAM,IAAI,UAAU,8EAA8E;CAEnG,IAAI,aAAa,OAAO,SAAS,GAAG,MAAM,IAAI,UAAU,wDAAwD;CAChH,MAAM,cAAc;CACpB,YAAY,WAAW,UAAyB;EAC/C,MAAM,SAAS,aAAa,KAAK;EACjC,MAAM,WAAW,OAAO,UAAU,IAAI;EACtC,IAAI,aAAa,KAAA,KAAa,aAAa,WAC1C,MAAM,IAAI,MAAM,uBAAuB,KAAK,8CAA8C;EAE3F,IAAI,aAAa,WAAW,OAAO,UAAU,MAAM,SAAS;CAC7D;CACA,OAAO;AACR"}

package/dist/vue/props.d.mts

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

package/dist/vue/props.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.d.mts","names":[],"sources":["../../src/vue/props.ts"],"mappings":";;;;;;;;;;iBAYgB,eAAe,OAAO,uBAAuB,SAAS;;;;;;;;;iBAYtD,SAAS,sBAAsB,yBAC9C,OAAO,OACP,UAAU,UACV,+BAA8B,cAC5B,YAAY,KAAK,OAAO,cAAc,aAAa"}

package/dist/vue/props.mjs

@@ -0,0 +1,41 @@
+import { computed } from "vue";
+//#region src/vue/props.ts
+/**
+* 为 Vue 运行时 Props 构造器附加泛型类型。
+*
+* @remarks 该函数只帮助 TypeScript 建模，不验证运行时值与 `Value` 一致；调用方仍应
+* 传入 Vue 支持的构造器或构造器数组。
+* @param runtimeType - Vue 支持的运行时构造器或构造器数组。
+* @returns 同一引用，仅在类型层收窄为 `PropType<Value>`。
+*/
+function definePropType(runtimeType) {
+	return runtimeType;
+}
+/**
+* 构建需要透传给子组件的响应式 Props。
+*
+* @param props - Vue `setup` 接收的只读响应式 Props 对象。
+* @param rawProps - 子组件的运行时 Props 配置。
+* @param ignoredProps - 不需要透传的 Props 名称。
+* @returns 只包含 `rawProps` 声明键且随 Props 更新的 ComputedRef。
+*/
+function useProps(props, rawProps, ignoredProps = []) {
+	const ignored = new Set(ignoredProps);
+	return computed(() => {
+		const result = {};
+		for (const key of Reflect.ownKeys(rawProps)) {
+			if (ignored.has(key) || !Object.hasOwn(props, key)) continue;
+			Object.defineProperty(result, key, {
+				configurable: true,
+				enumerable: true,
+				value: Reflect.get(props, key),
+				writable: true
+			});
+		}
+		return result;
+	});
+}
+//#endregion
+export { definePropType, useProps };
+
+//# sourceMappingURL=props.mjs.map

package/dist/vue/props.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.mjs","names":[],"sources":["../../src/vue/props.ts"],"sourcesContent":["import { computed } from \"vue\";\n\nimport type { ComputedRef, PropType } from \"vue\";\n\n/**\n * 为 Vue 运行时 Props 构造器附加泛型类型。\n *\n * @remarks 该函数只帮助 TypeScript 建模，不验证运行时值与 `Value` 一致；调用方仍应\n * 传入 Vue 支持的构造器或构造器数组。\n * @param runtimeType - Vue 支持的运行时构造器或构造器数组。\n * @returns 同一引用，仅在类型层收窄为 `PropType<Value>`。\n */\nexport function definePropType<Value>(runtimeType: unknown): PropType<Value> {\n\treturn runtimeType as PropType<Value>;\n}\n\n/**\n * 构建需要透传给子组件的响应式 Props。\n *\n * @param props - Vue `setup` 接收的只读响应式 Props 对象。\n * @param rawProps - 子组件的运行时 Props 配置。\n * @param ignoredProps - 不需要透传的 Props 名称。\n * @returns 只包含 `rawProps` 声明键且随 Props 更新的 ComputedRef。\n */\nexport function useProps<Props extends object, RawProps extends object>(\n\tprops: Props,\n\trawProps: RawProps,\n\tignoredProps: readonly (keyof RawProps)[] = []\n): ComputedRef<Pick<Props, Extract<keyof Props, keyof RawProps>>> {\n\tconst ignored = new Set<PropertyKey>(ignoredProps);\n\treturn computed<Pick<Props, Extract<keyof Props, keyof RawProps>>>(() => {\n\t\tconst result = {} as Pick<Props, Extract<keyof Props, keyof RawProps>>;\n\t\tfor (const key of Reflect.ownKeys(rawProps)) {\n\t\t\tif (ignored.has(key) || !Object.hasOwn(props, key)) continue;\n\t\t\tObject.defineProperty(result, key, { configurable: true, enumerable: true, value: Reflect.get(props, key), writable: true });\n\t\t}\n\t\treturn result;\n\t});\n}\n"],"mappings":";;;;;;;;;;AAYA,SAAgB,eAAsB,aAAuC;CAC5E,OAAO;AACR;;;;;;;;;AAUA,SAAgB,SACf,OACA,UACA,eAA4C,CAAC,GACoB;CACjE,MAAM,UAAU,IAAI,IAAiB,YAAY;CACjD,OAAO,eAAkE;EACxE,MAAM,SAAS,CAAC;EAChB,KAAK,MAAM,OAAO,QAAQ,QAAQ,QAAQ,GAAG;GAC5C,IAAI,QAAQ,IAAI,GAAG,KAAK,CAAC,OAAO,OAAO,OAAO,GAAG,GAAG;GACpD,OAAO,eAAe,QAAQ,KAAK;IAAE,cAAc;IAAM,YAAY;IAAM,OAAO,QAAQ,IAAI,OAAO,GAAG;IAAG,UAAU;GAAK,CAAC;EAC5H;EACA,OAAO;CACR,CAAC;AACF"}

package/dist/vue/render.d.mts

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

package/dist/vue/render.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.mts","names":[],"sources":["../../src/vue/render.ts"],"mappings":";;;;;;;;;iBA+BgB,UAAU,cAAc"}

package/dist/vue/render.mjs

@@ -0,0 +1,23 @@
+import { getCurrentInstance } from "vue";
+//#region src/vue/render.ts
+/**
+* 在当前 Vue 2.7/3 组件实例上安装 TSX 渲染函数。
+*
+* @remarks 组件的 `setup` 可以继续返回状态对象，因此状态能够显示在 Vue Devtools 中。
+* @param render - 当前组件的渲染函数。
+* @throws 不在组件 `setup` 调用栈中使用时抛出 `Error`。
+*/
+function useRender(render) {
+	const instance = getCurrentInstance();
+	if (instance === null) throw new Error("useRender must be called from inside a setup function.");
+	const compatible = instance;
+	if (compatible.proxy?.$options !== void 0 && !("render" in compatible)) {
+		compatible.proxy.$options.render = render;
+		return;
+	}
+	compatible.render = render;
+}
+//#endregion
+export { useRender };
+
+//# sourceMappingURL=render.mjs.map

package/dist/vue/render.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.mjs","names":[],"sources":["../../src/vue/render.ts"],"sourcesContent":["import { getCurrentInstance } from \"vue\";\n\nimport type { VNode } from \"vue\";\n\n/** Vue 2.7 与 Vue 3 组件实例中渲染函数可能出现的位置。 */\ninterface CompatibleVueInstance {\n\t/** Vue 2.7 兼容实例上的公共代理。 */\n\tproxy?: CompatibleVueProxy;\n\t/** Vue 3 内部组件实例直接持有的渲染函数。 */\n\trender?: () => VNode;\n}\n\n/** Vue 2.7 公共代理中允许写入渲染函数的最小结构。 */\ninterface CompatibleVueProxy {\n\t/** 当前组件的可变 Options API 配置。 */\n\t$options?: CompatibleVueOptions;\n}\n\n/** TSX Helper 需要写入的最小组件选项。 */\ninterface CompatibleVueOptions {\n\t/** 当前组件渲染函数；调用 {@link useRender} 后替换为传入函数。 */\n\trender?: () => VNode;\n}\n\n/**\n * 在当前 Vue 2.7/3 组件实例上安装 TSX 渲染函数。\n *\n * @remarks 组件的 `setup` 可以继续返回状态对象，因此状态能够显示在 Vue Devtools 中。\n * @param render - 当前组件的渲染函数。\n * @throws 不在组件 `setup` 调用栈中使用时抛出 `Error`。\n */\nexport function useRender(render: () => VNode): void {\n\tconst instance = getCurrentInstance();\n\tif (instance === null) throw new Error(\"useRender must be called from inside a setup function.\");\n\tconst compatible = instance as unknown as CompatibleVueInstance;\n\tif (compatible.proxy?.$options !== undefined && !(\"render\" in compatible)) {\n\t\tcompatible.proxy.$options.render = render;\n\t\treturn;\n\t}\n\tcompatible.render = render;\n}\n"],"mappings":";;;;;;;;;AA+BA,SAAgB,UAAU,QAA2B;CACpD,MAAM,WAAW,mBAAmB;CACpC,IAAI,aAAa,MAAM,MAAM,IAAI,MAAM,wDAAwD;CAC/F,MAAM,aAAa;CACnB,IAAI,WAAW,OAAO,aAAa,KAAA,KAAa,EAAE,YAAY,aAAa;EAC1E,WAAW,MAAM,SAAS,SAAS;EACnC;CACD;CACA,WAAW,SAAS;AACrB"}

package/dist/vue/slots.d.mts

@@ -0,0 +1,19 @@
+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 函数。 */
+type TypedSlots<Slots extends RawSlots> = { [Name in keyof Slots]: VueSlot<Slots[Name]>; };
+/** Vue 3 `slots` 选项接受的运行时声明与官方静态类型标记。 */
+type TypedSlotsDeclaration<Slots extends RawSlots> = SlotsType<Partial<TypedSlots<Slots>>>;
+/**
+ * 为 Options API 的 `slots` 选项创建带作用域参数的类型声明。
+ *
+ * @returns 运行时 `Object` 构造器，并携带仅供 TypeScript 使用的 Slot 类型标记。
+ */
+declare function makeSlots<Slots extends RawSlots>(): TypedSlotsDeclaration<Slots>;
+//#endregion
+export { TypedSlots, TypedSlotsDeclaration, makeSlots };
+//# sourceMappingURL=slots.d.mts.map

package/dist/vue/slots.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.mts","names":[],"sources":["../../src/vue/slots.ts"],"mappings":";;;KAGK,WAAW;;KAEX,QAAQ,eAAe,oCAAoC,WAAW,YAAY,eAAe;;KAG1F,WAAW,cAAc,eACnC,cAAc,QAAQ,QAAQ,MAAM;;KAI1B,sBAAsB,cAAc,YAAY,UAAU,QAAQ,WAAW;;;;;;iBAOzE,UAAU,cAAc,aAAa,sBAAsB"}

package/dist/vue/slots.mjs

@@ -0,0 +1,13 @@
+//#region src/vue/slots.ts
+/**
+* 为 Options API 的 `slots` 选项创建带作用域参数的类型声明。
+*
+* @returns 运行时 `Object` 构造器，并携带仅供 TypeScript 使用的 Slot 类型标记。
+*/
+function makeSlots() {
+	return Object;
+}
+//#endregion
+export { makeSlots };
+
+//# sourceMappingURL=slots.mjs.map

package/dist/vue/slots.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.mjs","names":[],"sources":["../../src/vue/slots.ts"],"sourcesContent":["import type { SlotsType, VNode } from \"vue\";\n\n/** Slot 名到 Props 类型的内部声明映射。 */\ntype RawSlots = Record<string, unknown>;\n/** 根据 Slot Props 是否为 never 生成无参数或有参数的 Slot 签名。 */\ntype VueSlot<Properties> = [Properties] extends [never] ? () => VNode[] : (properties: Properties) => VNode[];\n\n/** 把 Slot 名称与作用域参数映射为 Vue 3 Slot 函数。 */\nexport type TypedSlots<Slots extends RawSlots> = {\n\t[Name in keyof Slots]: VueSlot<Slots[Name]>;\n};\n\n/** Vue 3 `slots` 选项接受的运行时声明与官方静态类型标记。 */\nexport type TypedSlotsDeclaration<Slots extends RawSlots> = SlotsType<Partial<TypedSlots<Slots>>>;\n\n/**\n * 为 Options API 的 `slots` 选项创建带作用域参数的类型声明。\n *\n * @returns 运行时 `Object` 构造器，并携带仅供 TypeScript 使用的 Slot 类型标记。\n */\nexport function makeSlots<Slots extends RawSlots>(): TypedSlotsDeclaration<Slots> {\n\treturn Object as TypedSlotsDeclaration<Slots>;\n}\n"],"mappings":";;;;;;AAoBA,SAAgB,YAAkE;CACjF,OAAO;AACR"}

package/dist/vue/with.d.mts

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

package/dist/vue/with.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with.d.mts","names":[],"sources":["../../src/vue/with.ts"],"mappings":";;;;;;;;iBAOgB,eAAe,OAAO,OAAO,QAAQ"}

package/dist/vue/with.mjs

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

package/dist/vue/with.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"with.mjs","names":[],"sources":["../../src/vue/with.ts"],"sourcesContent":["/**\n * 保留传入值并显式指定其 TypeScript 类型。\n *\n * @remarks 未传值时运行时结果为 `undefined`，仅适合为 reactive 对象的初始字段提供类型。\n * @param data - 可选的原始值。\n * @returns 传入值本身；省略时返回类型化的 `undefined`。\n */\nexport function withDefineType<Value>(data?: Value): Value {\n\treturn data as Value;\n}\n"],"mappings":";;;;;;;;AAOA,SAAgB,eAAsB,MAAqB;CAC1D,OAAO;AACR"}

package/docs/API.md

@@ -0,0 +1,96 @@
+# Fast.Utils API
+
+Fast.Utils is a browser-first, pure ESM utility package targeting ES2022. Its application environments are modern browsers, WebViews, Vue 2.7/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
+
+Call `configureStorage` once in the application entry, then import `Local` or `Session` directly wherever needed.
+
+```ts
+import { configureStorage, Local, Session } from "@fast-china/utils";
+
+configureStorage({ prefix: "admin:" });
+
+Local.set("profile", { name: "Ada" }, { ttlMs: 3_600_000 });
+Session.set("draft", { step: 2 });
+```
+
+`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.
+
+For uni-app, `configureStorage` automatically 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 { configureStorage, Local } from "@fast-china/utils";
+
+configureStorage({ prefix: "mini:" });
+Local.set("token", "value");
+```
+
+Custom codecs may be supplied with `codec`. `base64StorageCodec` is reversible obfuscation, not encryption.
+
+`encodeSecureBase64` and `decodeSecureBase64` preserve the legacy dictionary payload while using a Web Crypto random prefix. 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 configured `Local` storage. Call `configureStorage` first. UUID generation requires Web Crypto and never falls back to `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();
+```
+
+The identifier is an installation-scoped value, not a hardware identifier, authentication credential, secret, or anti-fraud signal.
+
+## Logger
+
+Logger scope belongs to each message rather than a mutable logger or child instance:
+
+```ts
+import { logger } from "@fast-china/utils";
+
+logger.info("storage", "profile loaded", { userId: 1 });
+logger.error("network", "request failed", error);
+```
+
+`createLogger` configures the minimum level, brand prefix, sink, and optional uni-app App-Plus split output. Scope must be a non-empty string without surrounding whitespace.
+
+## Modules
+
+- `array`: `chunk`, `removeNullishValues`, `unique`, `uniqueBy`, `groupBy`, `partition`, `difference`, `intersection`, `hasDuplicatesBy`, and `allEqualBy`.
+- `async`: abort-aware `sleep`, timeout, retry, bounded concurrent mapping, debounce, and throttle primitives.
+- `base64`: strict UTF-8 Base64/Base64URL byte and text functions plus the historical Latin-1 and dictionary-obfuscation functions.
+- `color`: Hex parsing/formatting/mixing, explicit black/white mixing, luminance, and contrast helpers.
+- `crypto`: secure randomness, hashes, AES compatibility helpers, authenticated password encryption, RSA-OAEP, ECDSA, and ECDH helpers.
+- `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.
+- `logger`: isolated configurable loggers and the default `logger`.
+- `number`: ranges, rounding, aggregation, interpolation, byte formatting, and secure integer generation.
+- `object`: prototype-safe selection, comparison, mapping, and query serialization. Style serialization is provided by the `dom` module.
+- `string`: query parsing, casing, grapheme-aware truncation, UUID, secure random strings, escaping, and whitespace normalization.
+- `vue`: Composition API, type, render, and registration helpers for Vue 2.7/3. `makeSlots` is Vue 3-only because it uses Vue's official `SlotsType`.
+
+## Security and limits
+
+Use authenticated password encryption for new protected payloads. AES-CBC/ECB, MD5, SHA-1, and the historical Base64 dictionary exist for protocol compatibility and must not be presented as modern authenticated encryption. 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.

package/docs/API.zh-CN.md

@@ -0,0 +1,96 @@
+# Fast.Utils API
+
+Fast.Utils 是面向浏览器的纯 ESM 工具包，语法目标为 ES2022，应用环境包括现代浏览器、WebView、Vue 2.7/3 和 uni-app。
+
+## 导入
+
+包只提供一个公开根入口，包含普通工具和 Vue Helper 在内的全部 API 均使用具名导出。
+
+```ts
+import { chunk, configureStorage, installationIdentity, Local } from "@fast-china/utils";
+```
+
+内部 Helper 不提供公共子路径。库不再导出工具聚合对象，调用方应直接导入具名函数，以便 Tree Shaking。
+
+## Storage
+
+在程序入口调用一次 `configureStorage`，其余业务文件直接从包中导入 `Local` 或 `Session`。
+
+```ts
+import { configureStorage, Local, Session } from "@fast-china/utils";
+
+configureStorage({ prefix: "admin:" });
+
+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 不可用或重复配置发生冲突时抛出错误；浏览器配额与隐私策略错误直接向上传播。
+
+uni-app 中，`configureStorage` 会自动检测全局 `uni` 并使用其同步 Storage API。uni-app 没有独立 Session 后端，因此该模式调用 `Session` 会明确抛错。
+
+```ts
+import { configureStorage, Local } from "@fast-china/utils";
+
+configureStorage({ prefix: "mini:" });
+Local.set("token", "value");
+```
+
+可以通过 `codec` 注入自定义 Codec。`base64StorageCodec` 只是可逆混淆，不是加密。
+
+`encodeSecureBase64` 与 `decodeSecureBase64` 保留旧字典兼容载荷，并使用 Web Crypto 生成安全随机前缀。给定相同的默认 6 字符前缀时，有效旧载荷保持逐字符兼容；旧字典在 Base64 长度 101–124 时会引用越界，当前实现使用单字符回退，旧删除字典流程仍可解码。旧自定义长度参数始终生成 6 个随机字符，当前 API 已按 `prefixLength` 正确生成。自定义 `prefixLength` 必须在编码和解码时保持一致；传入 `0` 会同时关闭随机前缀与字典插入。该格式仍是可逆编码，不等同于加密。
+
+## Identity
+
+`installationIdentity` 是全局安装标识门面。可在程序入口、首次使用前调用 `configureInstallationIdentity` 覆盖默认缓存键 `identity:installation-id`。`getOrCreateInstallationId(installationId?)` 会通过已配置的 `Local` 读取、生成或替换 UUID v4。必须先调用 `configureStorage`。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 拆分输出。作用域必须是无外围空白的非空字符串。
+
+## 模块
+
+- `array`：分块、压缩、去重、分组、分区、差集、交集和一致性判断。
+- `async`：支持取消的 Sleep、超时、重试、受限并发映射、防抖和节流。
+- `base64`：严格 UTF-8 Base64/Base64URL 字节与文本函数，以及 Latin-1 和 SecureBase64 兼容函数。
+- `color`：颜色解析、格式化、混合、明暗、亮度和对比度。
+- `crypto`：安全随机、哈希、AES 兼容函数、认证密码加密、RSA-OAEP、ECDSA 和 ECDH。
+- `date`：日期校验、加减、日范围、相对时间，以及七个历史日期功能的具名函数。
+- `dom`：CSS 单位和 Style 序列化。
+- `env`：能力与 User-Agent 检测；检测函数不扩大运行时支持范围。
+- `logger`：隔离的可配置 Logger 和默认 `logger`。
+- `number`：范围、舍入、聚合、插值、字节格式化和安全随机整数。
+- `object`：防原型污染的选择、比较、映射和 Query 序列化；Style 序列化由 `dom` 模块提供。
+- `string`：Query 解析、大小写、字素截断、UUID、安全随机文本、转义和空白规范化。
+- `vue`：Vue 2.7/3 的 Composition API、类型、Render 和注册 Helper；使用官方 `SlotsType` 的 `makeSlots` 仅供 Vue 3 使用。
+
+## 安全与限制
+
+新受保护载荷应使用认证密码加密。AES-CBC/ECB、MD5、SHA-1 和历史 Base64 字典仅用于协议兼容，不能描述为现代认证加密。Crypto API 按算法限制参数和载荷大小，并在需要时强制要求 Web Crypto。
+
+Query 与 Object API 拒绝原型污染键，URL 解码有最大深度，Storage 清理只作用于配置的命名空间。浏览器全局对象只在调用 API 时解析，模块导入阶段不会访问。
+
+## 错误与兼容性
+
+除明确说明返回空值的函数外，编程错误、非法输入、平台能力缺失和受保护数据损坏均抛出原生错误。