@fast-china/utils 1.0.38 → 2.0.2

package/dist/env/index.mjs

@@ -0,0 +1,97 @@
+//#region src/env/index.ts
+const runtimeGlobals = globalThis;
+/**
+* 延迟读取当前 User-Agent。
+*
+* @returns Navigator 不存在或字段类型异常时返回空字符串。
+*/
+const currentUserAgent = () => typeof runtimeGlobals.navigator?.userAgent === "string" ? runtimeGlobals.navigator.userAgent : "";
+/**
+* 延迟读取当前设备报告的最大触点数。
+*
+* @returns Navigator 不存在或字段类型异常时返回 `0`。
+*/
+const currentTouchPoints = () => typeof runtimeGlobals.navigator?.maxTouchPoints === "number" ? runtimeGlobals.navigator.maxTouchPoints : 0;
+/**
+* 判断当前运行时是否具有浏览器 `window` 与 `document`。
+*
+* @returns 两项能力均存在时返回 `true`；不读取 DOM 内容。
+*/
+function isBrowser() {
+	const window = runtimeGlobals.window;
+	return window !== void 0 && window !== null && window.document !== null && typeof window.document === "object";
+}
+/**
+* 判断当前运行时是否像 Web Worker 且不是 Window。
+*
+* @remarks 经典、模块、Shared 与 Service Worker 全局通常都暴露 `importScripts`；模块
+* Worker 中调用它可能抛错，本检测只检查能力存在，不会执行。
+* @returns 具有 `importScripts` 且不是浏览器 Window 时返回 `true`。
+*/
+function isWebWorker() {
+	return !isBrowser() && typeof runtimeGlobals.importScripts === "function";
+}
+/**
+* 判断当前运行时是否暴露 Node.js 版本标记。
+*
+* @returns `process.versions.node` 为字符串时返回 `true`。
+*/
+function isNode() {
+	return typeof runtimeGlobals.process?.versions?.node === "string";
+}
+/**
+* 判断当前运行时是否暴露 uni-app 的 `uni` 全局对象。
+*
+* @returns 全局属性存在且不为 `undefined` 时返回 `true`；不调用任何平台 API。
+*/
+function isUniApp() {
+	return runtimeGlobals.uni !== void 0;
+}
+/**
+* 判断当前运行时是否具备本库完整加密 API 所需的 Web Crypto 能力。
+*
+* @remarks 只具有 `getRandomValues` 的平台仍可调用随机数与随机字符串 API，但本函数
+* 会返回 `false`，因为摘要、PBKDF2、AES-GCM、RSA 与 ECC 还需要完整的 `SubtleCrypto` 方法集。
+* @returns 同时提供本库 Web Crypto 功能所需方法时返回 `true`。
+*/
+function hasWebCrypto() {
+	const crypto = runtimeGlobals.crypto;
+	const subtle = crypto?.subtle;
+	return typeof crypto?.getRandomValues === "function" && typeof subtle?.decrypt === "function" && typeof subtle.deriveBits === "function" && typeof subtle.deriveKey === "function" && typeof subtle.digest === "function" && typeof subtle.encrypt === "function" && typeof subtle.exportKey === "function" && typeof subtle.generateKey === "function" && typeof subtle.importKey === "function" && typeof subtle.sign === "function" && typeof subtle.verify === "function";
+}
+/**
+* 返回当前主要运行环境。
+*
+* @remarks 在使用 DOM 模拟器的 Node.js 进程中优先报告 `browser`，因为可观察能力比宿主进程名称更有用。
+* @returns `browser`、`worker`、`node` 或无法识别时的 `unknown`。
+*/
+function detectRuntime() {
+	if (isBrowser()) return "browser";
+	if (isWebWorker()) return "worker";
+	if (isNode()) return "node";
+	return "unknown";
+}
+/**
+* 基于 User-Agent 启发式判断手机设备。
+*
+* @param userAgent - 默认读取当前 `navigator.userAgent`；平台对象不存在时使用空字符串。
+* @remarks User-Agent 可以被伪造，不得用于鉴权、安全策略或永久功能分流。
+* @returns 命中手机特征时返回 `true`。
+*/
+function isMobileUserAgent(userAgent = currentUserAgent()) {
+	return /Mobile|iPhone|Android.*Mobile|Windows Phone/iu.test(userAgent);
+}
+/**
+* 基于 User-Agent 与触点数量启发式判断平板设备。
+*
+* @param userAgent - 默认读取当前 User-Agent。
+* @param maxTouchPoints - 用于识别桌面 User-Agent 模式下的 iPadOS，默认读取当前触点数。
+* @returns 命中平板特征时返回 `true`。
+*/
+function isTabletUserAgent(userAgent = currentUserAgent(), maxTouchPoints = currentTouchPoints()) {
+	return /iPad|Android(?!.*Mobile)|Tablet/iu.test(userAgent) || /Macintosh/iu.test(userAgent) && maxTouchPoints > 1;
+}
+//#endregion
+export { detectRuntime, hasWebCrypto, isBrowser, isMobileUserAgent, isNode, isTabletUserAgent, isUniApp, isWebWorker };
+
+//# sourceMappingURL=index.mjs.map

package/dist/env/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/env/index.ts"],"sourcesContent":["/** 可识别的主要 JavaScript 运行环境。 */\nexport type RuntimeKind = \"browser\" | \"node\" | \"unknown\" | \"worker\";\n\n/** 环境检测需要逐项确认的 SubtleCrypto 最小能力集合。 */\ntype RuntimeSubtleCrypto = Partial<\n\tPick<SubtleCrypto, \"decrypt\" | \"deriveBits\" | \"deriveKey\" | \"digest\" | \"encrypt\" | \"exportKey\" | \"generateKey\" | \"importKey\" | \"sign\" | \"verify\">\n>;\n\n/** 环境检测读取的 Web Crypto 最小视图。 */\ninterface RuntimeEnvironmentCrypto extends Partial<Pick<Crypto, \"getRandomValues\">> {\n\t/** 可选 SubtleCrypto 能力；只有所需方法全部存在时才视为完整 Web Crypto。 */\n\tsubtle?: RuntimeSubtleCrypto;\n}\n\n/** 环境检测读取的最小 Navigator 视图。 */\ninterface RuntimeNavigator {\n\t/** 平台报告的最大同时触点数；类型异常时按 `0` 处理。 */\n\tmaxTouchPoints?: unknown;\n\t/** 平台报告的 User-Agent；类型异常时按空字符串处理。 */\n\tuserAgent?: unknown;\n}\n\n/** 环境检测读取的最小 Node 进程视图。 */\ninterface RuntimeProcess {\n\t/** 可选运行时版本表。 */\n\tversions?: RuntimeVersions;\n}\n\n/** 环境检测读取的最小运行时版本表。 */\ninterface RuntimeVersions {\n\t/** Node.js 版本文本；存在字符串值时识别为 Node 环境。 */\n\tnode?: unknown;\n}\n\n/** 环境检测读取的最小 Window 视图。 */\ninterface RuntimeWindow {\n\t/** DOM 文档标记；只检查是否为非空对象。 */\n\tdocument?: unknown;\n}\n\n/** 可选平台全局对象的结构化视图，避免导入 Node 或 uni-app 全局类型。 */\ninterface RuntimeGlobals {\n\t/** 可选 Web Crypto 能力；所有方法都在调用前逐项检查，不因对象存在而假定完整实现。 */\n\tcrypto?: RuntimeEnvironmentCrypto;\n\t/** Web Worker 中通常存在的脚本导入函数；只检查其类型，不会在检测阶段调用。 */\n\timportScripts?: unknown;\n\t/** 浏览器或 WebView 暴露的最小 Navigator 字段；未知类型会被能力读取函数视为缺失。 */\n\tnavigator?: RuntimeNavigator;\n\t/** 工具或测试环境可能暴露的 Node 版本标记；仅用于检测，不代表 Node 属于应用运行时契约。 */\n\tprocess?: RuntimeProcess;\n\t/** uni-app 平台标记；Storage 会在调用 `configureStorage` 时读取并校验该全局对象。 */\n\tuni?: unknown;\n\t/** 浏览器 Window 的最小结构；`document` 只用于能力判定，不在模块导入阶段读取 DOM 内容。 */\n\twindow?: RuntimeWindow | null;\n}\n\nconst runtimeGlobals = globalThis as unknown as RuntimeGlobals;\n\n/**\n * 延迟读取当前 User-Agent。\n *\n * @returns Navigator 不存在或字段类型异常时返回空字符串。\n */\nconst currentUserAgent = (): string => (typeof runtimeGlobals.navigator?.userAgent === \"string\" ? runtimeGlobals.navigator.userAgent : \"\");\n/**\n * 延迟读取当前设备报告的最大触点数。\n *\n * @returns Navigator 不存在或字段类型异常时返回 `0`。\n */\nconst currentTouchPoints = (): number => (typeof runtimeGlobals.navigator?.maxTouchPoints === \"number\" ? runtimeGlobals.navigator.maxTouchPoints : 0);\n\n/**\n * 判断当前运行时是否具有浏览器 `window` 与 `document`。\n *\n * @returns 两项能力均存在时返回 `true`；不读取 DOM 内容。\n */\nexport function isBrowser(): boolean {\n\tconst window = runtimeGlobals.window;\n\treturn window !== undefined && window !== null && window.document !== null && typeof window.document === \"object\";\n}\n\n/**\n * 判断当前运行时是否像 Web Worker 且不是 Window。\n *\n * @remarks 经典、模块、Shared 与 Service Worker 全局通常都暴露 `importScripts`；模块\n * Worker 中调用它可能抛错，本检测只检查能力存在，不会执行。\n * @returns 具有 `importScripts` 且不是浏览器 Window 时返回 `true`。\n */\nexport function isWebWorker(): boolean {\n\treturn !isBrowser() && typeof runtimeGlobals.importScripts === \"function\";\n}\n\n/**\n * 判断当前运行时是否暴露 Node.js 版本标记。\n *\n * @returns `process.versions.node` 为字符串时返回 `true`。\n */\nexport function isNode(): boolean {\n\treturn typeof runtimeGlobals.process?.versions?.node === \"string\";\n}\n\n/**\n * 判断当前运行时是否暴露 uni-app 的 `uni` 全局对象。\n *\n * @returns 全局属性存在且不为 `undefined` 时返回 `true`；不调用任何平台 API。\n */\nexport function isUniApp(): boolean {\n\treturn runtimeGlobals.uni !== undefined;\n}\n\n/**\n * 判断当前运行时是否具备本库完整加密 API 所需的 Web Crypto 能力。\n *\n * @remarks 只具有 `getRandomValues` 的平台仍可调用随机数与随机字符串 API，但本函数\n * 会返回 `false`，因为摘要、PBKDF2、AES-GCM、RSA 与 ECC 还需要完整的 `SubtleCrypto` 方法集。\n * @returns 同时提供本库 Web Crypto 功能所需方法时返回 `true`。\n */\nexport function hasWebCrypto(): boolean {\n\tconst crypto = runtimeGlobals.crypto;\n\tconst subtle = crypto?.subtle;\n\treturn (\n\t\ttypeof crypto?.getRandomValues === \"function\" &&\n\t\ttypeof subtle?.decrypt === \"function\" &&\n\t\ttypeof subtle.deriveBits === \"function\" &&\n\t\ttypeof subtle.deriveKey === \"function\" &&\n\t\ttypeof subtle.digest === \"function\" &&\n\t\ttypeof subtle.encrypt === \"function\" &&\n\t\ttypeof subtle.exportKey === \"function\" &&\n\t\ttypeof subtle.generateKey === \"function\" &&\n\t\ttypeof subtle.importKey === \"function\" &&\n\t\ttypeof subtle.sign === \"function\" &&\n\t\ttypeof subtle.verify === \"function\"\n\t);\n}\n\n/**\n * 返回当前主要运行环境。\n *\n * @remarks 在使用 DOM 模拟器的 Node.js 进程中优先报告 `browser`，因为可观察能力比宿主进程名称更有用。\n * @returns `browser`、`worker`、`node` 或无法识别时的 `unknown`。\n */\nexport function detectRuntime(): RuntimeKind {\n\tif (isBrowser()) return \"browser\";\n\tif (isWebWorker()) return \"worker\";\n\tif (isNode()) return \"node\";\n\treturn \"unknown\";\n}\n\n/**\n * 基于 User-Agent 启发式判断手机设备。\n *\n * @param userAgent - 默认读取当前 `navigator.userAgent`；平台对象不存在时使用空字符串。\n * @remarks User-Agent 可以被伪造，不得用于鉴权、安全策略或永久功能分流。\n * @returns 命中手机特征时返回 `true`。\n */\nexport function isMobileUserAgent(userAgent: string = currentUserAgent()): boolean {\n\treturn /Mobile|iPhone|Android.*Mobile|Windows Phone/iu.test(userAgent);\n}\n\n/**\n * 基于 User-Agent 与触点数量启发式判断平板设备。\n *\n * @param userAgent - 默认读取当前 User-Agent。\n * @param maxTouchPoints - 用于识别桌面 User-Agent 模式下的 iPadOS，默认读取当前触点数。\n * @returns 命中平板特征时返回 `true`。\n */\nexport function isTabletUserAgent(userAgent: string = currentUserAgent(), maxTouchPoints: number = currentTouchPoints()): boolean {\n\treturn /iPad|Android(?!.*Mobile)|Tablet/iu.test(userAgent) || (/Macintosh/iu.test(userAgent) && maxTouchPoints > 1);\n}\n"],"mappings":";AAwDA,MAAM,iBAAiB;;;;;;AAOvB,MAAM,yBAAkC,OAAO,eAAe,WAAW,cAAc,WAAW,eAAe,UAAU,YAAY;;;;;;AAMvI,MAAM,2BAAoC,OAAO,eAAe,WAAW,mBAAmB,WAAW,eAAe,UAAU,iBAAiB;;;;;;AAOnJ,SAAgB,YAAqB;CACpC,MAAM,SAAS,eAAe;CAC9B,OAAO,WAAW,KAAA,KAAa,WAAW,QAAQ,OAAO,aAAa,QAAQ,OAAO,OAAO,aAAa;AAC1G;;;;;;;;AASA,SAAgB,cAAuB;CACtC,OAAO,CAAC,UAAU,KAAK,OAAO,eAAe,kBAAkB;AAChE;;;;;;AAOA,SAAgB,SAAkB;CACjC,OAAO,OAAO,eAAe,SAAS,UAAU,SAAS;AAC1D;;;;;;AAOA,SAAgB,WAAoB;CACnC,OAAO,eAAe,QAAQ,KAAA;AAC/B;;;;;;;;AASA,SAAgB,eAAwB;CACvC,MAAM,SAAS,eAAe;CAC9B,MAAM,SAAS,QAAQ;CACvB,OACC,OAAO,QAAQ,oBAAoB,cACnC,OAAO,QAAQ,YAAY,cAC3B,OAAO,OAAO,eAAe,cAC7B,OAAO,OAAO,cAAc,cAC5B,OAAO,OAAO,WAAW,cACzB,OAAO,OAAO,YAAY,cAC1B,OAAO,OAAO,cAAc,cAC5B,OAAO,OAAO,gBAAgB,cAC9B,OAAO,OAAO,cAAc,cAC5B,OAAO,OAAO,SAAS,cACvB,OAAO,OAAO,WAAW;AAE3B;;;;;;;AAQA,SAAgB,gBAA6B;CAC5C,IAAI,UAAU,GAAG,OAAO;CACxB,IAAI,YAAY,GAAG,OAAO;CAC1B,IAAI,OAAO,GAAG,OAAO;CACrB,OAAO;AACR;;;;;;;;AASA,SAAgB,kBAAkB,YAAoB,iBAAiB,GAAY;CAClF,OAAO,gDAAgD,KAAK,SAAS;AACtE;;;;;;;;AASA,SAAgB,kBAAkB,YAAoB,iBAAiB,GAAG,iBAAyB,mBAAmB,GAAY;CACjI,OAAO,oCAAoC,KAAK,SAAS,KAAM,cAAc,KAAK,SAAS,KAAK,iBAAiB;AAClH"}

package/dist/identity/index.d.mts

@@ -0,0 +1,78 @@
+//#region src/identity/index.d.ts
+/** {@link configureInstallationIdentity} 接收的安装标识配置。 */
+interface InstallationIdentityConfiguration {
+  /**
+   * `Local` 中使用的业务键，默认 `identity:installation-id`。
+   *
+   * @remarks 必须是无外围空白的非空字符串，并在首次访问 Identity API 前配置；物理键仍会叠加 Storage 全局前缀。
+   */
+  cacheKey?: string;
+}
+/** 浏览器或 uni-app 当前安装实例标识。 */
+interface InstallationIdentity {
+  /**
+   * `Local` 中使用的业务键。
+   *
+   * @remarks 首次读取会锁定默认配置；之后不能再切换为其他业务键。
+   */
+  readonly cacheKey: string;
+  /**
+   * 当前内存中的安装标识；尚未取得标识或调用 {@link InstallationIdentity.clear clear} 后为空字符串。
+   *
+   * @remarks 直接赋值只改变内存，不会校验或持久化；通常应调用 {@link InstallationIdentity.getOrCreate getOrCreate}。
+   */
+  deviceId: string;
+  /**
+   * 删除当前 `cacheKey` 对应的持久化标识，并把 `deviceId` 重置为空字符串。
+   *
+   * @throws `Error` 当当前平台存储不可用。
+   */
+  clear: () => void;
+  /**
+   * 按“显式参数、当前内存、持久化值、安全生成值”的优先级取得安装标识。
+   *
+   * @param installationId - 可选 UUID v4；传入时覆盖内存值和当前持久化值。
+   * @returns 已校验并同时写入 `deviceId` 与 `Local` 的 UUID v4。
+   * @throws `TypeError` 当显式参数、内存值或持久化值不是 UUID v4。
+   * @throws `Error` 当当前平台存储不可用，或生成新值时平台缺少 Web Crypto。
+   */
+  getOrCreate: (installationId?: string) => string;
+  /**
+   * 读取并校验当前 `cacheKey` 对应的持久化标识。
+   *
+   * @remarks 该方法不修改 `deviceId`，只负责读取；过期记录由 Storage 视为缺失。
+   * @returns 已持久化的 UUID v4；键缺失或过期时返回 `undefined`。
+   * @throws `TypeError` 当持久化值不是字符串或不是 UUID v4。
+   * @throws `Error` 当当前平台存储不可用。
+   */
+  read: () => string | undefined;
+}
+/**
+ * 在应用入口配置安装标识使用的 Storage 业务键。
+ *
+ * @remarks 必须在首次读取 `installationIdentity.cacheKey` 或调用其他安装标识 API 前执行。相同配置
+ * 可以幂等重复调用；切换到不同键会抛错，避免同一页面产生分裂状态。
+ * @param options - 安装标识配置；省略 `cacheKey` 时使用 `identity:installation-id`。
+ * @throws `TypeError` 当 `cacheKey` 不是非空字符串或包含外围空白。
+ * @throws `Error` 当安装标识已经使用另一个业务键初始化。
+ */
+declare function configureInstallationIdentity(options?: InstallationIdentityConfiguration): void;
+/**
+ * 全局安装标识状态。
+ *
+ * @remarks Storage 未显式配置时会使用其默认值。默认随机源只使用 Web Crypto，
+ * 能力缺失时明确抛错，不回退到 `Math.random()`。该值不是硬件标识、认证凭证或安全边界。
+ */
+declare const installationIdentity: InstallationIdentity;
+/**
+ * 返回已有安装标识，否则创建并持久化一个安全 UUID v4。
+ *
+ * @param installationId - 可选的显式安装标识；传入时会校验并覆盖当前持久化值。
+ * @returns 显式值、内存值、持久化值或新生成值中的最终安装标识。
+ * @throws `TypeError` 当显式值或持久化值不是 UUID v4。
+ * @throws `Error` 当当前平台存储不可用或缺少 Web Crypto。
+ */
+declare function getOrCreateInstallationId(installationId?: string): string;
+//#endregion
+export { InstallationIdentity, InstallationIdentityConfiguration, configureInstallationIdentity, getOrCreateInstallationId, installationIdentity };
+//# sourceMappingURL=index.d.mts.map

package/dist/identity/index.mjs

@@ -0,0 +1,87 @@
+import { Local } from "../storage/index.mjs";
+import { generateUuidV4, isUuidV4 } from "../string/index.mjs";
+//#region src/identity/index.ts
+const defaultInstallationIdentityStorageKey = "identity:installation-id";
+/**
+* 校验安装标识格式。
+*
+* @param value - 外部传入或从 Storage 读取的候选值。
+* @throws `TypeError` 当值不是 RFC 4122 UUID v4。
+*/
+const assertInstallationId = (value) => {
+	if (!isUuidV4(value)) throw new TypeError("Installation Identity values must be RFC 4122 version 4 UUIDs.");
+};
+let activeStorageKey;
+/**
+* 取得已经锁定的安装标识业务键。
+*
+* @remarks 首次读取会锁定默认值，防止标识已经写入后再切换键而产生两个安装标识。
+* @returns 应用于后续全部 Identity 操作的业务键。
+*/
+const getInstallationIdentityStorageKey = () => {
+	activeStorageKey ??= defaultInstallationIdentityStorageKey;
+	return activeStorageKey;
+};
+/**
+* 在应用入口配置安装标识使用的 Storage 业务键。
+*
+* @remarks 必须在首次读取 `installationIdentity.cacheKey` 或调用其他安装标识 API 前执行。相同配置
+* 可以幂等重复调用；切换到不同键会抛错，避免同一页面产生分裂状态。
+* @param options - 安装标识配置；省略 `cacheKey` 时使用 `identity:installation-id`。
+* @throws `TypeError` 当 `cacheKey` 不是非空字符串或包含外围空白。
+* @throws `Error` 当安装标识已经使用另一个业务键初始化。
+*/
+function configureInstallationIdentity(options = {}) {
+	const cacheKey = options.cacheKey ?? defaultInstallationIdentityStorageKey;
+	if (typeof cacheKey !== "string" || cacheKey.length === 0 || cacheKey.trim() !== cacheKey) throw new TypeError("Installation Identity cacheKey must be a non-empty string without surrounding whitespace.");
+	if (activeStorageKey === void 0) {
+		activeStorageKey = cacheKey;
+		return;
+	}
+	if (activeStorageKey !== cacheKey) throw new Error("Installation Identity has already been configured with a different cacheKey.");
+}
+/**
+* 全局安装标识状态。
+*
+* @remarks Storage 未显式配置时会使用其默认值。默认随机源只使用 Web Crypto，
+* 能力缺失时明确抛错，不回退到 `Math.random()`。该值不是硬件标识、认证凭证或安全边界。
+*/
+const installationIdentity = {
+	get cacheKey() {
+		return getInstallationIdentityStorageKey();
+	},
+	deviceId: "",
+	clear() {
+		Local.remove(installationIdentity.cacheKey);
+		installationIdentity.deviceId = "";
+	},
+	getOrCreate(installationId) {
+		const candidate = installationId ?? (installationIdentity.deviceId.length > 0 ? installationIdentity.deviceId : installationIdentity.read()) ?? generateUuidV4();
+		assertInstallationId(candidate);
+		Local.set(installationIdentity.cacheKey, candidate);
+		installationIdentity.deviceId = candidate;
+		return candidate;
+	},
+	read() {
+		const stored = Local.get(installationIdentity.cacheKey);
+		if (stored === void 0) return void 0;
+		if (typeof stored !== "string") throw new TypeError("The stored identity is corrupted.");
+		assertInstallationId(stored);
+		return stored;
+	}
+};
+/**
+* 返回已有安装标识，否则创建并持久化一个安全 UUID v4。
+*
+* @param installationId - 可选的显式安装标识；传入时会校验并覆盖当前持久化值。
+* @returns 显式值、内存值、持久化值或新生成值中的最终安装标识。
+* @throws `TypeError` 当显式值或持久化值不是 UUID v4。
+* @throws `Error` 当当前平台存储不可用或缺少 Web Crypto。
+*/
+function getOrCreateInstallationId(installationId) {
+	return installationIdentity.getOrCreate(installationId);
+}
+//#endregion
+export { configureInstallationIdentity, getOrCreateInstallationId, installationIdentity };
+
+//# sourceMappingURL=index.mjs.map

package/dist/identity/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/identity/index.ts"],"sourcesContent":["import { Local } from \"../storage/index\";\nimport { generateUuidV4, isUuidV4 } from \"../string/index\";\n\nconst defaultInstallationIdentityStorageKey = \"identity:installation-id\";\n\n/** {@link configureInstallationIdentity} 接收的安装标识配置。 */\nexport interface InstallationIdentityConfiguration {\n\t/**\n\t * `Local` 中使用的业务键，默认 `identity:installation-id`。\n\t *\n\t * @remarks 必须是无外围空白的非空字符串，并在首次访问 Identity API 前配置；物理键仍会叠加 Storage 全局前缀。\n\t */\n\tcacheKey?: string;\n}\n\n/** 浏览器或 uni-app 当前安装实例标识。 */\nexport interface InstallationIdentity {\n\t/**\n\t * `Local` 中使用的业务键。\n\t *\n\t * @remarks 首次读取会锁定默认配置；之后不能再切换为其他业务键。\n\t */\n\treadonly cacheKey: string;\n\t/**\n\t * 当前内存中的安装标识；尚未取得标识或调用 {@link InstallationIdentity.clear clear} 后为空字符串。\n\t *\n\t * @remarks 直接赋值只改变内存，不会校验或持久化；通常应调用 {@link InstallationIdentity.getOrCreate getOrCreate}。\n\t */\n\tdeviceId: string;\n\t/**\n\t * 删除当前 `cacheKey` 对应的持久化标识，并把 `deviceId` 重置为空字符串。\n\t *\n\t * @throws `Error` 当当前平台存储不可用。\n\t */\n\tclear: () => void;\n\t/**\n\t * 按“显式参数、当前内存、持久化值、安全生成值”的优先级取得安装标识。\n\t *\n\t * @param installationId - 可选 UUID v4；传入时覆盖内存值和当前持久化值。\n\t * @returns 已校验并同时写入 `deviceId` 与 `Local` 的 UUID v4。\n\t * @throws `TypeError` 当显式参数、内存值或持久化值不是 UUID v4。\n\t * @throws `Error` 当当前平台存储不可用，或生成新值时平台缺少 Web Crypto。\n\t */\n\tgetOrCreate: (installationId?: string) => string;\n\t/**\n\t * 读取并校验当前 `cacheKey` 对应的持久化标识。\n\t *\n\t * @remarks 该方法不修改 `deviceId`，只负责读取；过期记录由 Storage 视为缺失。\n\t * @returns 已持久化的 UUID v4；键缺失或过期时返回 `undefined`。\n\t * @throws `TypeError` 当持久化值不是字符串或不是 UUID v4。\n\t * @throws `Error` 当当前平台存储不可用。\n\t */\n\tread: () => string | undefined;\n}\n\n/**\n * 校验安装标识格式。\n *\n * @param value - 外部传入或从 Storage 读取的候选值。\n * @throws `TypeError` 当值不是 RFC 4122 UUID v4。\n */\nconst assertInstallationId = (value: string): void => {\n\tif (!isUuidV4(value)) throw new TypeError(\"Installation Identity values must be RFC 4122 version 4 UUIDs.\");\n};\n\nlet activeStorageKey: string | undefined;\n\n/**\n * 取得已经锁定的安装标识业务键。\n *\n * @remarks 首次读取会锁定默认值，防止标识已经写入后再切换键而产生两个安装标识。\n * @returns 应用于后续全部 Identity 操作的业务键。\n */\nconst getInstallationIdentityStorageKey = (): string => {\n\tactiveStorageKey ??= defaultInstallationIdentityStorageKey;\n\treturn activeStorageKey;\n};\n\n/**\n * 在应用入口配置安装标识使用的 Storage 业务键。\n *\n * @remarks 必须在首次读取 `installationIdentity.cacheKey` 或调用其他安装标识 API 前执行。相同配置\n * 可以幂等重复调用；切换到不同键会抛错，避免同一页面产生分裂状态。\n * @param options - 安装标识配置；省略 `cacheKey` 时使用 `identity:installation-id`。\n * @throws `TypeError` 当 `cacheKey` 不是非空字符串或包含外围空白。\n * @throws `Error` 当安装标识已经使用另一个业务键初始化。\n */\nexport function configureInstallationIdentity(options: InstallationIdentityConfiguration = {}): void {\n\tconst cacheKey = options.cacheKey ?? defaultInstallationIdentityStorageKey;\n\tif (typeof cacheKey !== \"string\" || cacheKey.length === 0 || cacheKey.trim() !== cacheKey) {\n\t\tthrow new TypeError(\"Installation Identity cacheKey must be a non-empty string without surrounding whitespace.\");\n\t}\n\tif (activeStorageKey === undefined) {\n\t\tactiveStorageKey = cacheKey;\n\t\treturn;\n\t}\n\tif (activeStorageKey !== cacheKey) throw new Error(\"Installation Identity has already been configured with a different cacheKey.\");\n}\n\n/**\n * 全局安装标识状态。\n *\n * @remarks Storage 未显式配置时会使用其默认值。默认随机源只使用 Web Crypto，\n * 能力缺失时明确抛错，不回退到 `Math.random()`。该值不是硬件标识、认证凭证或安全边界。\n */\nexport const installationIdentity: InstallationIdentity = {\n\tget cacheKey(): string {\n\t\treturn getInstallationIdentityStorageKey();\n\t},\n\tdeviceId: \"\",\n\tclear(): void {\n\t\tLocal.remove(installationIdentity.cacheKey);\n\t\tinstallationIdentity.deviceId = \"\";\n\t},\n\tgetOrCreate(installationId?: string): string {\n\t\tconst candidate =\n\t\t\tinstallationId ??\n\t\t\t(installationIdentity.deviceId.length > 0 ? installationIdentity.deviceId : installationIdentity.read()) ??\n\t\t\tgenerateUuidV4();\n\t\tassertInstallationId(candidate);\n\t\tLocal.set(installationIdentity.cacheKey, candidate);\n\t\tinstallationIdentity.deviceId = candidate;\n\t\treturn candidate;\n\t},\n\tread(): string | undefined {\n\t\tconst stored = Local.get(installationIdentity.cacheKey);\n\t\tif (stored === undefined) return undefined;\n\t\tif (typeof stored !== \"string\") throw new TypeError(\"The stored identity is corrupted.\");\n\t\tassertInstallationId(stored);\n\t\treturn stored;\n\t},\n};\n\n/**\n * 返回已有安装标识，否则创建并持久化一个安全 UUID v4。\n *\n * @param installationId - 可选的显式安装标识；传入时会校验并覆盖当前持久化值。\n * @returns 显式值、内存值、持久化值或新生成值中的最终安装标识。\n * @throws `TypeError` 当显式值或持久化值不是 UUID v4。\n * @throws `Error` 当当前平台存储不可用或缺少 Web Crypto。\n */\nexport function getOrCreateInstallationId(installationId?: string): string {\n\treturn installationIdentity.getOrCreate(installationId);\n}\n"],"mappings":";;;AAGA,MAAM,wCAAwC;;;;;;;AA0D9C,MAAM,wBAAwB,UAAwB;CACrD,IAAI,CAAC,SAAS,KAAK,GAAG,MAAM,IAAI,UAAU,gEAAgE;AAC3G;AAEA,IAAI;;;;;;;AAQJ,MAAM,0CAAkD;CACvD,qBAAqB;CACrB,OAAO;AACR;;;;;;;;;;AAWA,SAAgB,8BAA8B,UAA6C,CAAC,GAAS;CACpG,MAAM,WAAW,QAAQ,YAAY;CACrC,IAAI,OAAO,aAAa,YAAY,SAAS,WAAW,KAAK,SAAS,KAAK,MAAM,UAChF,MAAM,IAAI,UAAU,2FAA2F;CAEhH,IAAI,qBAAqB,KAAA,GAAW;EACnC,mBAAmB;EACnB;CACD;CACA,IAAI,qBAAqB,UAAU,MAAM,IAAI,MAAM,8EAA8E;AAClI;;;;;;;AAQA,MAAa,uBAA6C;CACzD,IAAI,WAAmB;EACtB,OAAO,kCAAkC;CAC1C;CACA,UAAU;CACV,QAAc;EACb,MAAM,OAAO,qBAAqB,QAAQ;EAC1C,qBAAqB,WAAW;CACjC;CACA,YAAY,gBAAiC;EAC5C,MAAM,YACL,mBACC,qBAAqB,SAAS,SAAS,IAAI,qBAAqB,WAAW,qBAAqB,KAAK,MACtG,eAAe;EAChB,qBAAqB,SAAS;EAC9B,MAAM,IAAI,qBAAqB,UAAU,SAAS;EAClD,qBAAqB,WAAW;EAChC,OAAO;CACR;CACA,OAA2B;EAC1B,MAAM,SAAS,MAAM,IAAI,qBAAqB,QAAQ;EACtD,IAAI,WAAW,KAAA,GAAW,OAAO,KAAA;EACjC,IAAI,OAAO,WAAW,UAAU,MAAM,IAAI,UAAU,mCAAmC;EACvF,qBAAqB,MAAM;EAC3B,OAAO;CACR;AACD;;;;;;;;;AAUA,SAAgB,0BAA0B,gBAAiC;CAC1E,OAAO,qBAAqB,YAAY,cAAc;AACvD"}

package/dist/index.d.mts

@@ -0,0 +1,24 @@
+import { KeySelector, allEqualBy, chunk, difference, groupBy, hasDuplicatesBy, intersection, partition, removeNullishValues, unique, uniqueBy } from "./array/index.mjs";
+import { AbortOptions, ConcurrentMapOptions, DebouncedFunction, RetryContext, RetryOptions, ThrottledFunction, TimeoutOptions, debounce, mapConcurrent, retry, sleep, throttle, withTimeout } from "./async/index.mjs";
+import { decodeBase64, decodeBase64Bytes, decodeBase64Url, decodeBase64UrlBytes, decodeLatin1Base64, decodeSecureBase64, encodeBase64, encodeBase64Bytes, encodeBase64Url, encodeBase64UrlBytes, encodeLatin1Base64, encodeSecureBase64 } from "./base64/index.mjs";
+import { RgbColor, RgbaColor, contrastRatio, formatHexColor, mixHexColorWithBlack, mixHexColorWithWhite, mixHexColors, parseHexColor, pickHigherContrastColor, relativeLuminance } from "./color/index.mjs";
+import { AESDecrypt, AESDecryptAuthenticated, AESDecryptWithPassword, AESEncrypt, AESEncryptAuthenticated, AESEncryptWithPassword, AesCipherMode, AesPaddingMode, DeriveECDHKeySHA256, DeriveECDHSecret, ECDSASign, ECDSAVerify, EcNamedCurve, FixedTimeEquals, GenerateECDHKeyPair, GenerateECDSAKeyPair, GenerateRSAKeyPair, GenerateRandomBytes, HKDFSHA256, HMACSHA256Encrypt, HMACSHA384Encrypt, HMACSHA512Encrypt, HashPasswordPBKDF2SHA256, MD5Encrypt, PBKDF2SHA256, PemKeyPair, RSADecryptOAEP, RSAEncryptOAEP, RSASignPSS, RSAVerifyPSS, SHA1Encrypt, SHA256Bytes, SHA256Encrypt, SHA384Bytes, SHA384Encrypt, SHA512Bytes, SHA512Encrypt, VerifyPasswordPBKDF2SHA256 } from "./crypto/index.mjs";
+import { DateInput, DateRangeShortcut, DateShortcut, RelativeTimeOptions, addDays, addMonths, addYears, createDateRangeShortcuts, createDateShortcuts, createOneMonthRangeFromToday, endOfDay, formatChineseRelativeTime, formatRelativeTime, getLocalDayBounds, getLocalTimeGreeting, getStartOfToday, isDateAfterNow, isFuture, isSameDay, isValidDate, isWithinInterval, startOfDay, toDate } from "./date/index.mjs";
+import { StyleInput, StyleObject, StyleValue, addCssUnit, serializeStyle } from "./dom/style.mjs";
+import { RuntimeKind, detectRuntime, hasWebCrypto, isBrowser, isMobileUserAgent, isNode, isTabletUserAgent, isUniApp, isWebWorker } from "./env/index.mjs";
+import { InstallationIdentity, InstallationIdentityConfiguration, configureInstallationIdentity, getOrCreateInstallationId, installationIdentity } from "./identity/index.mjs";
+import { LogLevel, Logger, LoggerOptions, LoggerSink, createLogger, logger } from "./logger/index.mjs";
+import { FormatBytesOptions, average, clamp, formatBytes, inRange, lerp, roundTo, secureRandomInt, sum } from "./number/index.mjs";
+import { QueryPrimitive, QueryStringOptions, QueryValue, hasOwn, isPlainObject, mapValues, omit, pick, shallowEqual, toQueryString } from "./object/index.mjs";
+import { Local, Session, StorageArea, StorageCodec, StorageConfiguration, StorageWriteOptions, base64StorageCodec, configureStorage, isStorageConfigured } from "./storage/index.mjs";
+import { ParsedQueryParameters, StringLocale, camelCase, decodeURIComponentRepeatedly, escapeHtml, generateUuidV4, isUuidV4, isValidJson, kebabCase, lowerFirst, normalizeWhitespace, parseQueryString, pascalCase, secureRandomString, splitWords, truncateGraphemes, upperFirst } from "./string/index.mjs";
+import { EmitHandlers, useEmits } from "./vue/emits.mjs";
+import { useExpose } from "./vue/expose.mjs";
+import { AwaitableFunction, callOptionalFunction } from "./vue/func.mjs";
+import { Installable, TSXWithInstall, VueInstallValue, withInstall, withInstallDirective, withNoopInstall } from "./vue/install.mjs";
+import { definePropType, useProps } from "./vue/props.mjs";
+import { useRender } from "./vue/render.mjs";
+import { TypedSlots, TypedSlotsDeclaration, makeSlots } from "./vue/slots.mjs";
+import { withDefineType } from "./vue/with.mjs";
+import "./vue/index.mjs";
+export { AESDecrypt, AESDecryptAuthenticated, AESDecryptWithPassword, AESEncrypt, AESEncryptAuthenticated, AESEncryptWithPassword, AbortOptions, AesCipherMode, AesPaddingMode, AwaitableFunction, ConcurrentMapOptions, DateInput, DateRangeShortcut, DateShortcut, DebouncedFunction, DeriveECDHKeySHA256, DeriveECDHSecret, ECDSASign, ECDSAVerify, EcNamedCurve, EmitHandlers, FixedTimeEquals, FormatBytesOptions, GenerateECDHKeyPair, GenerateECDSAKeyPair, GenerateRSAKeyPair, GenerateRandomBytes, HKDFSHA256, HMACSHA256Encrypt, HMACSHA384Encrypt, HMACSHA512Encrypt, HashPasswordPBKDF2SHA256, Installable, InstallationIdentity, InstallationIdentityConfiguration, KeySelector, Local, LogLevel, Logger, LoggerOptions, LoggerSink, MD5Encrypt, PBKDF2SHA256, ParsedQueryParameters, PemKeyPair, QueryPrimitive, QueryStringOptions, QueryValue, RSADecryptOAEP, RSAEncryptOAEP, RSASignPSS, RSAVerifyPSS, RelativeTimeOptions, RetryContext, RetryOptions, RgbColor, RgbaColor, RuntimeKind, SHA1Encrypt, SHA256Bytes, SHA256Encrypt, SHA384Bytes, SHA384Encrypt, SHA512Bytes, SHA512Encrypt, Session, StorageArea, StorageCodec, StorageConfiguration, StorageWriteOptions, StringLocale, StyleInput, StyleObject, StyleValue, TSXWithInstall, ThrottledFunction, TimeoutOptions, TypedSlots, TypedSlotsDeclaration, VerifyPasswordPBKDF2SHA256, VueInstallValue, addCssUnit, addDays, addMonths, addYears, allEqualBy, average, base64StorageCodec, callOptionalFunction, camelCase, chunk, clamp, configureInstallationIdentity, configureStorage, contrastRatio, createDateRangeShortcuts, createDateShortcuts, createLogger, createOneMonthRangeFromToday, debounce, decodeBase64, decodeBase64Bytes, decodeBase64Url, decodeBase64UrlBytes, decodeLatin1Base64, decodeSecureBase64, decodeURIComponentRepeatedly, definePropType, detectRuntime, difference, encodeBase64, encodeBase64Bytes, encodeBase64Url, encodeBase64UrlBytes, encodeLatin1Base64, encodeSecureBase64, endOfDay, escapeHtml, formatBytes, formatChineseRelativeTime, formatHexColor, formatRelativeTime, generateUuidV4, getLocalDayBounds, getLocalTimeGreeting, getOrCreateInstallationId, getStartOfToday, groupBy, hasDuplicatesBy, hasOwn, hasWebCrypto, inRange, installationIdentity, intersection, isBrowser, isDateAfterNow, isFuture, isMobileUserAgent, isNode, isPlainObject, isSameDay, isStorageConfigured, isTabletUserAgent, isUniApp, isUuidV4, isValidDate, isValidJson, isWebWorker, isWithinInterval, kebabCase, lerp, logger, lowerFirst, makeSlots, mapConcurrent, mapValues, mixHexColorWithBlack, mixHexColorWithWhite, mixHexColors, normalizeWhitespace, omit, parseHexColor, parseQueryString, partition, pascalCase, pick, pickHigherContrastColor, relativeLuminance, removeNullishValues, retry, roundTo, secureRandomInt, secureRandomString, serializeStyle, shallowEqual, sleep, splitWords, startOfDay, sum, throttle, toDate, toQueryString, truncateGraphemes, unique, uniqueBy, upperFirst, useEmits, useExpose, useProps, useRender, withDefineType, withInstall, withInstallDirective, withNoopInstall, withTimeout };