@fast-china/utils 1.0.37 → 2.0.0

package/dist/string/index.d.mts

@@ -0,0 +1,130 @@
+//#region src/string/index.d.ts
+/** 查询字符串解析结果；重复键保留为数组，不存在的键读取为 `undefined`。 */
+type ParsedQueryParameters = Record<string, string | string[] | undefined>;
+/** 大小写与字素分割可接受的显式语言；省略时固定使用 `en-US` 以保持输出稳定。 */
+type StringLocale = string | readonly string[] | undefined;
+/**
+ * 重复执行 URI 组件解码，直到值稳定或达到深度上限。
+ *
+ * @param value - 不包含 URI 路径语义的编码组件。
+ * @param maxDepth - 最大解码次数，默认 `10`。
+ * @returns 解码稳定或达到上限后的组件文本。
+ * @throws `URIError` 当任一层包含非法百分号序列；深度非法时抛出 `RangeError`。
+ */
+declare function decodeURIComponentRepeatedly(value: string, maxDepth?: number): string;
+/**
+ * 解析带 `://` 的绝对 URL、`?query` 或纯查询字符串。
+ *
+ * @remarks 纯查询字符串值中的未编码 `?` 会作为值内容保留；片段标识及其后内容被忽略。
+ * @param input - 完整 URL、带前导问号或不带前导问号的查询文本。
+ * @returns 重复键对应字符串数组，空值保留为空字符串。
+ */
+declare function parseQueryString(input: string): ParsedQueryParameters;
+/**
+ * 判断文本是否为任意合法 JSON 值，包括标量与 `null`。
+ *
+ * @param value - 待解析文本；纯空白不视为 JSON。
+ * @returns `JSON.parse` 能完整解析时返回 `true`。
+ */
+declare function isValidJson(value: string): boolean;
+/**
+ * 按大小写边界、连字符、下划线与空白切分单词。
+ *
+ * @example `XMLHttp_request` 返回 `["XML", "Http", "request"]`。
+ * @param value - 待拆分文本。
+ * @returns 删除空项、保持输入顺序的单词数组。
+ */
+declare function splitWords(value: string): string[];
+/**
+ * 将首个 Unicode 码点转为大写。
+ *
+ * @param value - 输入文本；空字符串保持为空。
+ * @param locale - 显式语言，默认固定为 `en-US`。
+ * @returns 首个 Unicode 码点转换后的文本。
+ */
+declare function upperFirst(value: string, locale?: StringLocale): string;
+/**
+ * 将首个 Unicode 码点转为小写。
+ *
+ * @param value - 输入文本；空字符串保持为空。
+ * @param locale - 显式语言，默认固定为 `en-US`。
+ * @returns 首个 Unicode 码点转换后的文本。
+ */
+declare function lowerFirst(value: string, locale?: StringLocale): string;
+/**
+ * 将文本转换为 camelCase。
+ *
+ * @param value - 由大小写、连字符、下划线或空白分隔的文本。
+ * @param locale - 大小写转换使用的语言，默认固定为 `en-US`。
+ * @returns camelCase 文本。
+ */
+declare function camelCase(value: string, locale?: StringLocale): string;
+/**
+ * 将文本转换为 PascalCase。
+ *
+ * @param value - 参数语义与 {@link camelCase} 一致。
+ * @param locale - 大小写转换使用的显式语言。
+ * @returns PascalCase 文本。
+ */
+declare function pascalCase(value: string, locale?: StringLocale): string;
+/**
+ * 将文本转换为 kebab-case。
+ *
+ * @param value - 参数语义与 {@link camelCase} 一致。
+ * @param locale - 大小写转换使用的显式语言。
+ * @returns kebab-case 文本。
+ */
+declare function kebabCase(value: string, locale?: StringLocale): string;
+/**
+ * 按 Unicode 字素簇截断文本，避免拆开 emoji、组合音标或代理对。
+ *
+ * @param value - 输入文本。
+ * @param maxLength - 保留的最大字素簇数量。
+ * @param suffix - 被截断时追加的文本，默认单字符省略号 `…`；不计入上限。
+ * @param locale - 字素分割语言，默认固定为 `en-US`。
+ * @returns 未超限时返回原字符串，否则返回截断内容与后缀。
+ * @throws `RangeError` 当 `maxLength` 不是非负安全整数或 Locale 无效；缺少
+ * `Intl.Segmenter` 时抛出 `Error`。
+ */
+declare function truncateGraphemes(value: string, maxLength: number, suffix?: string, locale?: StringLocale): string;
+/**
+ * 使用无偏 Web Crypto 随机数生成字符串。
+ *
+ * @param length - 字符数量，必须是 0 至 1,000,000 的安全整数。
+ * @param alphabet - 不得为空、包含重复字符或超过 2^32 个 Unicode 码点。
+ * @returns 由 `alphabet` 中 Unicode 码点组成的随机文本。
+ * @throws `RangeError` 当长度或字母表非法；缺少 Web Crypto 时抛出 `Error`。
+ */
+declare function secureRandomString(length: number, alphabet?: string): string;
+/**
+ * 使用 Web Crypto 生成 RFC 4122 version 4 UUID。
+ *
+ * @returns 小写、带连字符的 UUID v4。
+ * @throws 缺少 Web Crypto 时抛出 `Error`。
+ */
+declare function generateUuidV4(): string;
+/**
+ * 判断字符串是否为 RFC 4122 version 4 UUID。
+ *
+ * @param value - 待验证文本；十六进制字母大小写均可。
+ * @returns 版本位与 Variant 位均正确时返回 `true`。
+ */
+declare function isUuidV4(value: string): boolean;
+/**
+ * 转义 HTML 文本上下文中的五个特殊字符。
+ *
+ * @remarks 这不是 HTML 清洗器，不能让不可信文本安全进入 URL、CSS、脚本或属性名上下文。
+ * @param value - 将作为 HTML 文本节点内容的字符串。
+ * @returns 转义 `&`、`<`、`>`、双引号与单引号后的文本。
+ */
+declare function escapeHtml(value: string): string;
+/**
+ * 把连续 Unicode 空白折叠为单个空格并删除两端空白。
+ *
+ * @param value - 输入文本。
+ * @returns 规范化后的文本；全空白输入返回空字符串。
+ */
+declare function normalizeWhitespace(value: string): string;
+//#endregion
+export { ParsedQueryParameters, StringLocale, camelCase, decodeURIComponentRepeatedly, escapeHtml, generateUuidV4, isUuidV4, isValidJson, kebabCase, lowerFirst, normalizeWhitespace, parseQueryString, pascalCase, secureRandomString, splitWords, truncateGraphemes, upperFirst };
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/string/index.ts"],"mappings":";;KA0BY,wBAAwB;;KAGxB;;;;;;;;;iBAsDI,6BAA6B,eAAe;;;;;;;;iBAkB5C,iBAAiB,gBAAgB;;;;;;;iBAyBjC,YAAY;;;;;;;;iBAiBZ,WAAW;;;;;;;;iBAgBX,WAAW,eAAe,SAAS;;;;;;;;iBAanC,WAAW,eAAe,SAAS;;;;;;;;iBAanC,UAAU,eAAe,SAAS;;;;;;;;iBAgBlC,WAAW,eAAe,SAAS;;;;;;;;iBAWnC,UAAU,eAAe,SAAS;;;;;;;;;;;;iBAiBlC,kBAAkB,eAAe,mBAAmB,iBAAc,SAAS;;;;;;;;;iBAc3E,mBAAmB,gBAAgB;;;;;;;iBAoCnC;;;;;;;iBAYA,SAAS;;;;;;;;iBAWT,WAAW;;;;;;;iBAuBX,oBAAoB"}

package/dist/string/index.mjs

@@ -0,0 +1,275 @@
+//#region src/string/index.ts
+const defaultRandomAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const defaultStringLocale = "en-US";
+const maximumRandomStringLength = 1e6;
+const maximumRandomValuesPerBatch = 16384;
+const uuidV4Pattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const runtimeGlobals = globalThis;
+/**
+* 获取字符串随机 API 所需的 Web Crypto 能力。
+*
+* @returns 具有 `getRandomValues` 的当前 Crypto 对象。
+* @throws `Error` 当平台没有安全随机能力；绝不回退到 `Math.random()`。
+*/
+const requireWebCrypto = () => {
+	const crypto = runtimeGlobals.crypto;
+	if (typeof crypto?.getRandomValues !== "function") throw new Error("Web Crypto random generation is unavailable in the current runtime.");
+	return crypto;
+};
+/**
+* 从随机字节创建 UUID v4。
+*
+* @param bytes - 长度至少为 16 的随机字节；Version 与 Variant 位会被原地修改。
+* @returns 小写、带连字符的 RFC 4122 UUID v4。
+*/
+const createUuidV4FromBytes = (bytes) => {
+	bytes[6] = (bytes[6] ?? 0) & 15 | 64;
+	bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+	const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+};
+/**
+* 按用户可见字素切分文本。
+*
+* @param value - 待切分字符串。
+* @param locale - Segmenter 使用的显式语言；省略时使用固定默认值。
+* @returns 保留组合 Emoji、变音符号和连接序列的字素数组。
+* @throws `Error` 当平台缺少 `Intl.Segmenter`。
+*/
+const splitGraphemes = (value, locale) => {
+	const Segmenter = runtimeGlobals.Intl?.Segmenter;
+	if (typeof Segmenter !== "function") throw new Error("Intl.Segmenter is unavailable in the current runtime.");
+	const segmenter = new Segmenter(locale ?? defaultStringLocale, { granularity: "grapheme" });
+	return Array.from(segmenter.segment(value), ({ segment }) => segment);
+};
+/**
+* 重复执行 URI 组件解码，直到值稳定或达到深度上限。
+*
+* @param value - 不包含 URI 路径语义的编码组件。
+* @param maxDepth - 最大解码次数，默认 `10`。
+* @returns 解码稳定或达到上限后的组件文本。
+* @throws `URIError` 当任一层包含非法百分号序列；深度非法时抛出 `RangeError`。
+*/
+function decodeURIComponentRepeatedly(value, maxDepth = 10) {
+	if (!Number.isSafeInteger(maxDepth) || maxDepth < 0) throw new RangeError("maxDepth must be a non-negative safe integer.");
+	let decoded = value;
+	for (let index = 0; index < maxDepth; index += 1) {
+		const next = decodeURIComponent(decoded);
+		if (next === decoded) break;
+		decoded = next;
+	}
+	return decoded;
+}
+/**
+* 解析带 `://` 的绝对 URL、`?query` 或纯查询字符串。
+*
+* @remarks 纯查询字符串值中的未编码 `?` 会作为值内容保留；片段标识及其后内容被忽略。
+* @param input - 完整 URL、带前导问号或不带前导问号的查询文本。
+* @returns 重复键对应字符串数组，空值保留为空字符串。
+*/
+function parseQueryString(input) {
+	const fragmentStart = input.indexOf("#");
+	const withoutFragment = fragmentStart < 0 ? input : input.slice(0, fragmentStart);
+	const isAbsoluteUrl = /^[a-z][a-z\d+.-]*:\/\//iu.test(withoutFragment);
+	const queryStart = withoutFragment.indexOf("?");
+	if (isAbsoluteUrl && queryStart < 0) return {};
+	const query = isAbsoluteUrl ? withoutFragment.slice(queryStart + 1) : withoutFragment.replace(/^\?/u, "");
+	const result = {};
+	for (const [key, value] of new URLSearchParams(query)) {
+		const existing = Object.hasOwn(result, key) ? result[key] : void 0;
+		if (existing === void 0) Object.defineProperty(result, key, {
+			configurable: true,
+			enumerable: true,
+			value,
+			writable: true
+		});
+		else if (Array.isArray(existing)) existing.push(value);
+		else Object.defineProperty(result, key, {
+			configurable: true,
+			enumerable: true,
+			value: [existing, value],
+			writable: true
+		});
+	}
+	return result;
+}
+/**
+* 判断文本是否为任意合法 JSON 值，包括标量与 `null`。
+*
+* @param value - 待解析文本；纯空白不视为 JSON。
+* @returns `JSON.parse` 能完整解析时返回 `true`。
+*/
+function isValidJson(value) {
+	if (value.trim().length === 0) return false;
+	try {
+		JSON.parse(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* 按大小写边界、连字符、下划线与空白切分单词。
+*
+* @example `XMLHttp_request` 返回 `["XML", "Http", "request"]`。
+* @param value - 待拆分文本。
+* @returns 删除空项、保持输入顺序的单词数组。
+*/
+function splitWords(value) {
+	return value.trim().replace(/(\p{Ll}|\p{N})(\p{Lu})/gu, "$1 $2").replace(/(\p{Lu})(\p{Lu}\p{Ll})/gu, "$1 $2").split(/[\s_-]+/u).filter((part) => part.length > 0);
+}
+/**
+* 将首个 Unicode 码点转为大写。
+*
+* @param value - 输入文本；空字符串保持为空。
+* @param locale - 显式语言，默认固定为 `en-US`。
+* @returns 首个 Unicode 码点转换后的文本。
+*/
+function upperFirst(value, locale) {
+	const characters = Array.from(value);
+	const first = characters.shift();
+	return first === void 0 ? "" : first.toLocaleUpperCase(locale ?? defaultStringLocale) + characters.join("");
+}
+/**
+* 将首个 Unicode 码点转为小写。
+*
+* @param value - 输入文本；空字符串保持为空。
+* @param locale - 显式语言，默认固定为 `en-US`。
+* @returns 首个 Unicode 码点转换后的文本。
+*/
+function lowerFirst(value, locale) {
+	const characters = Array.from(value);
+	const first = characters.shift();
+	return first === void 0 ? "" : first.toLocaleLowerCase(locale ?? defaultStringLocale) + characters.join("");
+}
+/**
+* 将文本转换为 camelCase。
+*
+* @param value - 由大小写、连字符、下划线或空白分隔的文本。
+* @param locale - 大小写转换使用的语言，默认固定为 `en-US`。
+* @returns camelCase 文本。
+*/
+function camelCase(value, locale) {
+	return splitWords(value).map((part, index) => {
+		const normalized = part.toLocaleLowerCase(locale ?? defaultStringLocale);
+		return index === 0 ? normalized : upperFirst(normalized, locale);
+	}).join("");
+}
+/**
+* 将文本转换为 PascalCase。
+*
+* @param value - 参数语义与 {@link camelCase} 一致。
+* @param locale - 大小写转换使用的显式语言。
+* @returns PascalCase 文本。
+*/
+function pascalCase(value, locale) {
+	return upperFirst(camelCase(value, locale), locale);
+}
+/**
+* 将文本转换为 kebab-case。
+*
+* @param value - 参数语义与 {@link camelCase} 一致。
+* @param locale - 大小写转换使用的显式语言。
+* @returns kebab-case 文本。
+*/
+function kebabCase(value, locale) {
+	return splitWords(value).map((part) => part.toLocaleLowerCase(locale ?? defaultStringLocale)).join("-");
+}
+/**
+* 按 Unicode 字素簇截断文本，避免拆开 emoji、组合音标或代理对。
+*
+* @param value - 输入文本。
+* @param maxLength - 保留的最大字素簇数量。
+* @param suffix - 被截断时追加的文本，默认单字符省略号 `…`；不计入上限。
+* @param locale - 字素分割语言，默认固定为 `en-US`。
+* @returns 未超限时返回原字符串，否则返回截断内容与后缀。
+* @throws `RangeError` 当 `maxLength` 不是非负安全整数或 Locale 无效；缺少
+* `Intl.Segmenter` 时抛出 `Error`。
+*/
+function truncateGraphemes(value, maxLength, suffix = "…", locale) {
+	if (!Number.isSafeInteger(maxLength) || maxLength < 0) throw new RangeError("maxLength must be a non-negative safe integer.");
+	const segments = splitGraphemes(value, locale);
+	return segments.length > maxLength ? segments.slice(0, maxLength).join("") + suffix : value;
+}
+/**
+* 使用无偏 Web Crypto 随机数生成字符串。
+*
+* @param length - 字符数量，必须是 0 至 1,000,000 的安全整数。
+* @param alphabet - 不得为空、包含重复字符或超过 2^32 个 Unicode 码点。
+* @returns 由 `alphabet` 中 Unicode 码点组成的随机文本。
+* @throws `RangeError` 当长度或字母表非法；缺少 Web Crypto 时抛出 `Error`。
+*/
+function secureRandomString(length, alphabet = defaultRandomAlphabet) {
+	if (!Number.isSafeInteger(length) || length < 0 || length > maximumRandomStringLength) throw new RangeError(`length must be a safe integer from 0 through ${maximumRandomStringLength}.`);
+	const characters = Array.from(alphabet);
+	if (characters.length === 0) throw new RangeError("alphabet cannot be empty.");
+	if (new Set(characters).size !== characters.length) throw new RangeError("alphabet cannot contain duplicate characters.");
+	if (characters.length > 4294967296) throw new RangeError("alphabet cannot contain more than 2^32 characters.");
+	if (length === 0) return "";
+	const crypto = requireWebCrypto();
+	const acceptanceLimit = Math.floor(4294967296 / characters.length) * characters.length;
+	const result = [];
+	while (result.length < length) {
+		const remaining = length - result.length;
+		const samples = crypto.getRandomValues(new Uint32Array(Math.min(remaining, maximumRandomValuesPerBatch)));
+		for (const sample of samples) {
+			if (sample >= acceptanceLimit) continue;
+			const character = characters[sample % characters.length];
+			if (character === void 0) continue;
+			result.push(character);
+			if (result.length === length) break;
+		}
+	}
+	return result.join("");
+}
+/**
+* 使用 Web Crypto 生成 RFC 4122 version 4 UUID。
+*
+* @returns 小写、带连字符的 UUID v4。
+* @throws 缺少 Web Crypto 时抛出 `Error`。
+*/
+function generateUuidV4() {
+	const crypto = requireWebCrypto();
+	if (typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	return createUuidV4FromBytes(crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16)));
+}
+/**
+* 判断字符串是否为 RFC 4122 version 4 UUID。
+*
+* @param value - 待验证文本；十六进制字母大小写均可。
+* @returns 版本位与 Variant 位均正确时返回 `true`。
+*/
+function isUuidV4(value) {
+	return uuidV4Pattern.test(value);
+}
+/**
+* 转义 HTML 文本上下文中的五个特殊字符。
+*
+* @remarks 这不是 HTML 清洗器，不能让不可信文本安全进入 URL、CSS、脚本或属性名上下文。
+* @param value - 将作为 HTML 文本节点内容的字符串。
+* @returns 转义 `&`、`<`、`>`、双引号与单引号后的文本。
+*/
+function escapeHtml(value) {
+	return value.replace(/[&<>"']/gu, (character) => {
+		switch (character) {
+			case "&": return "&amp;";
+			case "<": return "&lt;";
+			case ">": return "&gt;";
+			case "\"": return "&quot;";
+			default: return "&#39;";
+		}
+	});
+}
+/**
+* 把连续 Unicode 空白折叠为单个空格并删除两端空白。
+*
+* @param value - 输入文本。
+* @returns 规范化后的文本；全空白输入返回空字符串。
+*/
+function normalizeWhitespace(value) {
+	return value.trim().replace(/\s+/gu, " ");
+}
+//#endregion
+export { camelCase, decodeURIComponentRepeatedly, escapeHtml, generateUuidV4, isUuidV4, isValidJson, kebabCase, lowerFirst, normalizeWhitespace, parseQueryString, pascalCase, secureRandomString, splitWords, truncateGraphemes, upperFirst };
+
+//# sourceMappingURL=index.mjs.map

package/dist/string/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/string/index.ts"],"sourcesContent":["const defaultRandomAlphabet = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\";\nconst defaultStringLocale = \"en-US\";\nconst maximumRandomStringLength = 1_000_000;\nconst maximumRandomValuesPerBatch = 16_384;\nconst uuidV4Pattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;\n\n/** 字符串随机 API 需要的 Web Crypto 最小能力。 */\ntype RuntimeStringCrypto = Partial<Pick<Crypto, \"getRandomValues\" | \"randomUUID\">>;\n\n/** 字素分割需要的可选 Intl 能力。 */\ninterface RuntimeStringIntl {\n\t/** 可选 Segmenter 构造器；缺失时字素 API 使用内部兼容路径。 */\n\tSegmenter?: typeof Intl.Segmenter;\n}\n\n/** 字符串工具延迟访问的平台全局对象最小视图。 */\ninterface RuntimeStringGlobals {\n\t/** 安全随机字符串与 UUID 所需的可选 Web Crypto 能力。 */\n\tcrypto?: RuntimeStringCrypto;\n\t/** 字素分割所需的可选 Intl 能力。 */\n\tIntl?: RuntimeStringIntl;\n}\n\nconst runtimeGlobals = globalThis as unknown as RuntimeStringGlobals;\n\n/** 查询字符串解析结果；重复键保留为数组，不存在的键读取为 `undefined`。 */\nexport type ParsedQueryParameters = Record<string, string | string[] | undefined>;\n\n/** 大小写与字素分割可接受的显式语言；省略时固定使用 `en-US` 以保持输出稳定。 */\nexport type StringLocale = string | readonly string[] | undefined;\n\n/**\n * 获取字符串随机 API 所需的 Web Crypto 能力。\n *\n * @returns 具有 `getRandomValues` 的当前 Crypto 对象。\n * @throws `Error` 当平台没有安全随机能力；绝不回退到 `Math.random()`。\n */\nconst requireWebCrypto = (): Crypto => {\n\tconst crypto = runtimeGlobals.crypto;\n\tif (typeof crypto?.getRandomValues !== \"function\") {\n\t\tthrow new Error(\"Web Crypto random generation is unavailable in the current runtime.\");\n\t}\n\treturn crypto as Crypto;\n};\n\n/**\n * 从随机字节创建 UUID v4。\n *\n * @param bytes - 长度至少为 16 的随机字节；Version 与 Variant 位会被原地修改。\n * @returns 小写、带连字符的 RFC 4122 UUID v4。\n */\nconst createUuidV4FromBytes = (bytes: Uint8Array): string => {\n\tbytes[6] = ((bytes[6] ?? 0) & 15) | 64;\n\tbytes[8] = ((bytes[8] ?? 0) & 63) | 128;\n\tconst hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, \"0\")).join(\"\");\n\treturn `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;\n};\n\n/**\n * 按用户可见字素切分文本。\n *\n * @param value - 待切分字符串。\n * @param locale - Segmenter 使用的显式语言；省略时使用固定默认值。\n * @returns 保留组合 Emoji、变音符号和连接序列的字素数组。\n * @throws `Error` 当平台缺少 `Intl.Segmenter`。\n */\nconst splitGraphemes = (value: string, locale: StringLocale): string[] => {\n\tconst Segmenter = runtimeGlobals.Intl?.Segmenter;\n\tif (typeof Segmenter !== \"function\") {\n\t\tthrow new Error(\"Intl.Segmenter is unavailable in the current runtime.\");\n\t}\n\tconst segmenter = new Segmenter(locale ?? defaultStringLocale, { granularity: \"grapheme\" });\n\treturn Array.from(segmenter.segment(value), ({ segment }) => segment);\n};\n\n/**\n * 重复执行 URI 组件解码，直到值稳定或达到深度上限。\n *\n * @param value - 不包含 URI 路径语义的编码组件。\n * @param maxDepth - 最大解码次数，默认 `10`。\n * @returns 解码稳定或达到上限后的组件文本。\n * @throws `URIError` 当任一层包含非法百分号序列；深度非法时抛出 `RangeError`。\n */\nexport function decodeURIComponentRepeatedly(value: string, maxDepth = 10): string {\n\tif (!Number.isSafeInteger(maxDepth) || maxDepth < 0) throw new RangeError(\"maxDepth must be a non-negative safe integer.\");\n\tlet decoded = value;\n\tfor (let index = 0; index < maxDepth; index += 1) {\n\t\tconst next = decodeURIComponent(decoded);\n\t\tif (next === decoded) break;\n\t\tdecoded = next;\n\t}\n\treturn decoded;\n}\n\n/**\n * 解析带 `://` 的绝对 URL、`?query` 或纯查询字符串。\n *\n * @remarks 纯查询字符串值中的未编码 `?` 会作为值内容保留；片段标识及其后内容被忽略。\n * @param input - 完整 URL、带前导问号或不带前导问号的查询文本。\n * @returns 重复键对应字符串数组，空值保留为空字符串。\n */\nexport function parseQueryString(input: string): ParsedQueryParameters {\n\tconst fragmentStart = input.indexOf(\"#\");\n\tconst withoutFragment = fragmentStart < 0 ? input : input.slice(0, fragmentStart);\n\tconst isAbsoluteUrl = /^[a-z][a-z\\d+.-]*:\\/\\//iu.test(withoutFragment);\n\tconst queryStart = withoutFragment.indexOf(\"?\");\n\tif (isAbsoluteUrl && queryStart < 0) return {};\n\tconst query = isAbsoluteUrl ? withoutFragment.slice(queryStart + 1) : withoutFragment.replace(/^\\?/u, \"\");\n\tconst result: ParsedQueryParameters = {};\n\tfor (const [key, value] of new URLSearchParams(query)) {\n\t\tconst existing = Object.hasOwn(result, key) ? result[key] : undefined;\n\t\tif (existing === undefined) {\n\t\t\t// defineProperty 让 `__proto__` 成为普通自有键，不触发 Object.prototype Setter。\n\t\t\tObject.defineProperty(result, key, { configurable: true, enumerable: true, value, writable: true });\n\t\t} else if (Array.isArray(existing)) existing.push(value);\n\t\telse Object.defineProperty(result, key, { configurable: true, enumerable: true, value: [existing, value], writable: true });\n\t}\n\treturn result;\n}\n\n/**\n * 判断文本是否为任意合法 JSON 值，包括标量与 `null`。\n *\n * @param value - 待解析文本；纯空白不视为 JSON。\n * @returns `JSON.parse` 能完整解析时返回 `true`。\n */\nexport function isValidJson(value: string): boolean {\n\tif (value.trim().length === 0) return false;\n\ttry {\n\t\tJSON.parse(value);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * 按大小写边界、连字符、下划线与空白切分单词。\n *\n * @example `XMLHttp_request` 返回 `[\"XML\", \"Http\", \"request\"]`。\n * @param value - 待拆分文本。\n * @returns 删除空项、保持输入顺序的单词数组。\n */\nexport function splitWords(value: string): string[] {\n\treturn value\n\t\t.trim()\n\t\t.replace(/(\\p{Ll}|\\p{N})(\\p{Lu})/gu, \"$1 $2\")\n\t\t.replace(/(\\p{Lu})(\\p{Lu}\\p{Ll})/gu, \"$1 $2\")\n\t\t.split(/[\\s_-]+/u)\n\t\t.filter((part) => part.length > 0);\n}\n\n/**\n * 将首个 Unicode 码点转为大写。\n *\n * @param value - 输入文本；空字符串保持为空。\n * @param locale - 显式语言，默认固定为 `en-US`。\n * @returns 首个 Unicode 码点转换后的文本。\n */\nexport function upperFirst(value: string, locale?: StringLocale): string {\n\tconst characters = Array.from(value);\n\tconst first = characters.shift();\n\treturn first === undefined ? \"\" : first.toLocaleUpperCase(locale ?? defaultStringLocale) + characters.join(\"\");\n}\n\n/**\n * 将首个 Unicode 码点转为小写。\n *\n * @param value - 输入文本；空字符串保持为空。\n * @param locale - 显式语言，默认固定为 `en-US`。\n * @returns 首个 Unicode 码点转换后的文本。\n */\nexport function lowerFirst(value: string, locale?: StringLocale): string {\n\tconst characters = Array.from(value);\n\tconst first = characters.shift();\n\treturn first === undefined ? \"\" : first.toLocaleLowerCase(locale ?? defaultStringLocale) + characters.join(\"\");\n}\n\n/**\n * 将文本转换为 camelCase。\n *\n * @param value - 由大小写、连字符、下划线或空白分隔的文本。\n * @param locale - 大小写转换使用的语言，默认固定为 `en-US`。\n * @returns camelCase 文本。\n */\nexport function camelCase(value: string, locale?: StringLocale): string {\n\treturn splitWords(value)\n\t\t.map((part, index) => {\n\t\t\tconst normalized = part.toLocaleLowerCase(locale ?? defaultStringLocale);\n\t\t\treturn index === 0 ? normalized : upperFirst(normalized, locale);\n\t\t})\n\t\t.join(\"\");\n}\n\n/**\n * 将文本转换为 PascalCase。\n *\n * @param value - 参数语义与 {@link camelCase} 一致。\n * @param locale - 大小写转换使用的显式语言。\n * @returns PascalCase 文本。\n */\nexport function pascalCase(value: string, locale?: StringLocale): string {\n\treturn upperFirst(camelCase(value, locale), locale);\n}\n\n/**\n * 将文本转换为 kebab-case。\n *\n * @param value - 参数语义与 {@link camelCase} 一致。\n * @param locale - 大小写转换使用的显式语言。\n * @returns kebab-case 文本。\n */\nexport function kebabCase(value: string, locale?: StringLocale): string {\n\treturn splitWords(value)\n\t\t.map((part) => part.toLocaleLowerCase(locale ?? defaultStringLocale))\n\t\t.join(\"-\");\n}\n\n/**\n * 按 Unicode 字素簇截断文本，避免拆开 emoji、组合音标或代理对。\n *\n * @param value - 输入文本。\n * @param maxLength - 保留的最大字素簇数量。\n * @param suffix - 被截断时追加的文本，默认单字符省略号 `…`；不计入上限。\n * @param locale - 字素分割语言，默认固定为 `en-US`。\n * @returns 未超限时返回原字符串，否则返回截断内容与后缀。\n * @throws `RangeError` 当 `maxLength` 不是非负安全整数或 Locale 无效；缺少\n * `Intl.Segmenter` 时抛出 `Error`。\n */\nexport function truncateGraphemes(value: string, maxLength: number, suffix = \"…\", locale?: StringLocale): string {\n\tif (!Number.isSafeInteger(maxLength) || maxLength < 0) throw new RangeError(\"maxLength must be a non-negative safe integer.\");\n\tconst segments = splitGraphemes(value, locale);\n\treturn segments.length > maxLength ? segments.slice(0, maxLength).join(\"\") + suffix : value;\n}\n\n/**\n * 使用无偏 Web Crypto 随机数生成字符串。\n *\n * @param length - 字符数量，必须是 0 至 1,000,000 的安全整数。\n * @param alphabet - 不得为空、包含重复字符或超过 2^32 个 Unicode 码点。\n * @returns 由 `alphabet` 中 Unicode 码点组成的随机文本。\n * @throws `RangeError` 当长度或字母表非法；缺少 Web Crypto 时抛出 `Error`。\n */\nexport function secureRandomString(length: number, alphabet: string = defaultRandomAlphabet): string {\n\tif (!Number.isSafeInteger(length) || length < 0 || length > maximumRandomStringLength) {\n\t\tthrow new RangeError(`length must be a safe integer from 0 through ${maximumRandomStringLength}.`);\n\t}\n\tconst characters = Array.from(alphabet);\n\tif (characters.length === 0) throw new RangeError(\"alphabet cannot be empty.\");\n\tif (new Set(characters).size !== characters.length) throw new RangeError(\"alphabet cannot contain duplicate characters.\");\n\tif (characters.length > 0x1_0000_0000) throw new RangeError(\"alphabet cannot contain more than 2^32 characters.\");\n\tif (length === 0) return \"\";\n\n\tconst crypto = requireWebCrypto();\n\tconst uint32Range = 0x1_0000_0000;\n\t// 丢弃不能平均映射到字母表的尾部区间，避免 `%` 造成前部字符概率偏高。\n\tconst acceptanceLimit = Math.floor(uint32Range / characters.length) * characters.length;\n\tconst result: string[] = [];\n\twhile (result.length < length) {\n\t\tconst remaining = length - result.length;\n\t\t// 分批请求可控制临时内存，并避开 Web Crypto 单次随机数组大小限制。\n\t\tconst samples = crypto.getRandomValues(new Uint32Array(Math.min(remaining, maximumRandomValuesPerBatch)));\n\t\tfor (const sample of samples) {\n\t\t\tif (sample >= acceptanceLimit) continue;\n\t\t\tconst character = characters[sample % characters.length];\n\t\t\tif (character === undefined) continue;\n\t\t\tresult.push(character);\n\t\t\tif (result.length === length) break;\n\t\t}\n\t}\n\treturn result.join(\"\");\n}\n\n/**\n * 使用 Web Crypto 生成 RFC 4122 version 4 UUID。\n *\n * @returns 小写、带连字符的 UUID v4。\n * @throws 缺少 Web Crypto 时抛出 `Error`。\n */\nexport function generateUuidV4(): string {\n\tconst crypto = requireWebCrypto();\n\tif (typeof crypto.randomUUID === \"function\") return crypto.randomUUID();\n\treturn createUuidV4FromBytes(crypto.getRandomValues(new Uint8Array(16)));\n}\n\n/**\n * 判断字符串是否为 RFC 4122 version 4 UUID。\n *\n * @param value - 待验证文本；十六进制字母大小写均可。\n * @returns 版本位与 Variant 位均正确时返回 `true`。\n */\nexport function isUuidV4(value: string): boolean {\n\treturn uuidV4Pattern.test(value);\n}\n\n/**\n * 转义 HTML 文本上下文中的五个特殊字符。\n *\n * @remarks 这不是 HTML 清洗器，不能让不可信文本安全进入 URL、CSS、脚本或属性名上下文。\n * @param value - 将作为 HTML 文本节点内容的字符串。\n * @returns 转义 `&`、`<`、`>`、双引号与单引号后的文本。\n */\nexport function escapeHtml(value: string): string {\n\treturn value.replace(/[&<>\"']/gu, (character) => {\n\t\tswitch (character) {\n\t\t\tcase \"&\":\n\t\t\t\treturn \"&amp;\";\n\t\t\tcase \"<\":\n\t\t\t\treturn \"&lt;\";\n\t\t\tcase \">\":\n\t\t\t\treturn \"&gt;\";\n\t\t\tcase '\"':\n\t\t\t\treturn \"&quot;\";\n\t\t\tdefault:\n\t\t\t\treturn \"&#39;\";\n\t\t}\n\t});\n}\n\n/**\n * 把连续 Unicode 空白折叠为单个空格并删除两端空白。\n *\n * @param value - 输入文本。\n * @returns 规范化后的文本；全空白输入返回空字符串。\n */\nexport function normalizeWhitespace(value: string): string {\n\treturn value.trim().replace(/\\s+/gu, \" \");\n}\n"],"mappings":"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"}

package/dist/vue/emits.d.mts

@@ -0,0 +1,24 @@
+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` 属性。 */
+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 随配置重新计算的事件处理器对象。
+ */
+declare function useEmits<Emits extends EmitsOptions>(emits: Emits, emit: (...arguments_: never[]) => unknown, ignoredEvents?: readonly (keyof Emits)[]): ComputedRef<Partial<EmitHandlers<Emits>>>;
+//#endregion
+export { EmitHandlers, useEmits };
+//# sourceMappingURL=emits.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emits.d.mts","names":[],"sources":["../../src/vue/emits.ts"],"mappings":";;;KAKK,qBAAqB;;KAErB,eAAe,eAAe;;KAE9B,eAAe,aAAa,uBAAsB,kBAAkB,yBAAwB;;KAE5F,gBAAgB,wBAAwB,uBAAuB,cAAc,YAC5E,WAAW,QAAQ,gBAAgB,UACtC,WAAW;;KAGF,aAAa,cAAc,mBACrC,cAAc,SAAS,2BAA2B,gBAAgB,sBAAsB,YAAY,eAAe,MAAM;;;;;;;;;iBAyB3G,SAAS,cAAc,cACtC,OAAO,OACP,UAAU,iCACV,gCAA+B,WAC7B,YAAY,QAAQ,aAAa"}

package/dist/vue/emits.mjs

@@ -0,0 +1,47 @@
+import { computed } from "vue";
+//#region src/vue/emits.ts
+/**
+* 把事件名转换为 Vue Handler Prop 名称。
+*
+* @param eventName - Emits 对象中的原始事件名，可使用 kebab-case。
+* @returns `onPascalCase` 形式的属性名。
+* @throws `TypeError` 当事件名包含空片段或无法生成有效 Handler 名称。
+*/
+const toHandlerName = (eventName) => {
+	return `on${eventName.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("")}`;
+};
+/**
+* 构建响应式 Vue 事件处理器。
+*
+* @param emits - Vue emits 配置对象。
+* @param emit - `setup` 上下文提供的 emit 函数。
+* @param ignoredEvents - 不需要向子组件透传的事件名。
+* @returns 随配置重新计算的事件处理器对象。
+*/
+function useEmits(emits, emit, ignoredEvents = []) {
+	const ignored = new Set(ignoredEvents);
+	const emitEvent = emit;
+	return computed(() => {
+		const handlers = {};
+		const handlerNames = /* @__PURE__ */ new Set();
+		for (const eventName of Object.keys(emits)) {
+			if (ignored.has(eventName)) continue;
+			if (eventName.length === 0 || /\s/u.test(eventName)) throw new TypeError(`Invalid Vue event name: "${eventName}".`);
+			const handlerName = toHandlerName(eventName);
+			if (handlerNames.has(handlerName)) throw new TypeError(`Vue events map to the same handler property: "${handlerName}".`);
+			handlerNames.add(handlerName);
+			Object.defineProperty(handlers, handlerName, {
+				enumerable: true,
+				value: (...arguments_) => {
+					emitEvent(eventName, ...arguments_);
+				},
+				writable: true
+			});
+		}
+		return handlers;
+	});
+}
+//#endregion
+export { useEmits };
+
+//# sourceMappingURL=emits.mjs.map

package/dist/vue/emits.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"emits.mjs","names":[],"sources":["../../src/vue/emits.ts"],"sourcesContent":["import { computed } from \"vue\";\n\nimport type { ComputedRef } from \"vue\";\n\n/** Vue Emits 对象中允许的校验器形状。 */\ntype EmitValidator = ((...arguments_: never[]) => unknown) | null;\n/** 事件名到可选参数校验器的内部映射。 */\ntype EmitsOptions = Record<string, EmitValidator>;\n/** 从校验器中提取事件参数；无校验器时保留未知参数。 */\ntype EventArguments<Validator> = Validator extends (...arguments_: infer Arguments) => unknown ? Arguments : unknown[];\n/** 在类型层递归把 kebab-case 事件名转换为 PascalCase。 */\ntype PascalEventName<Value extends string> = Value extends `${infer Head}-${infer Tail}`\n\t? `${Capitalize<Head>}${PascalEventName<Tail>}`\n\t: Capitalize<Value>;\n\n/** 把事件配置映射为 Vue `onXxx` 属性。 */\nexport type EmitHandlers<Emits extends EmitsOptions> = {\n\t[Name in keyof Emits as Name extends string ? `on${PascalEventName<Name>}` : never]: (...arguments_: EventArguments<Emits[Name]>) => void;\n};\n\n/**\n * 把事件名转换为 Vue Handler Prop 名称。\n *\n * @param eventName - Emits 对象中的原始事件名，可使用 kebab-case。\n * @returns `onPascalCase` 形式的属性名。\n * @throws `TypeError` 当事件名包含空片段或无法生成有效 Handler 名称。\n */\nconst toHandlerName = (eventName: string): string => {\n\treturn `on${eventName\n\t\t.split(\"-\")\n\t\t.map((part) => part.charAt(0).toUpperCase() + part.slice(1))\n\t\t.join(\"\")}`;\n};\n\n/**\n * 构建响应式 Vue 事件处理器。\n *\n * @param emits - Vue emits 配置对象。\n * @param emit - `setup` 上下文提供的 emit 函数。\n * @param ignoredEvents - 不需要向子组件透传的事件名。\n * @returns 随配置重新计算的事件处理器对象。\n */\nexport function useEmits<Emits extends EmitsOptions>(\n\temits: Emits,\n\temit: (...arguments_: never[]) => unknown,\n\tignoredEvents: readonly (keyof Emits)[] = []\n): ComputedRef<Partial<EmitHandlers<Emits>>> {\n\tconst ignored = new Set<PropertyKey>(ignoredEvents);\n\tconst emitEvent = emit as unknown as (eventName: string, ...arguments_: unknown[]) => void;\n\treturn computed<Partial<EmitHandlers<Emits>>>(() => {\n\t\tconst handlers = {} as Partial<EmitHandlers<Emits>>;\n\t\tconst handlerNames = new Set<string>();\n\t\tfor (const eventName of Object.keys(emits)) {\n\t\t\tif (ignored.has(eventName)) continue;\n\t\t\tif (eventName.length === 0 || /\\s/u.test(eventName)) throw new TypeError(`Invalid Vue event name: \"${eventName}\".`);\n\t\t\tconst handlerName = toHandlerName(eventName);\n\t\t\tif (handlerNames.has(handlerName)) {\n\t\t\t\tthrow new TypeError(`Vue events map to the same handler property: \"${handlerName}\".`);\n\t\t\t}\n\t\t\thandlerNames.add(handlerName);\n\t\t\tObject.defineProperty(handlers, handlerName, {\n\t\t\t\tenumerable: true,\n\t\t\t\tvalue: (...arguments_: unknown[]): void => {\n\t\t\t\t\temitEvent(eventName, ...arguments_);\n\t\t\t\t},\n\t\t\t\twritable: true,\n\t\t\t});\n\t\t}\n\t\treturn handlers;\n\t});\n}\n"],"mappings":";;;;;;;;;AA2BA,MAAM,iBAAiB,cAA8B;CACpD,OAAO,KAAK,UACV,MAAM,GAAG,CAAC,CACV,KAAK,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,YAAY,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAC3D,KAAK,EAAE;AACV;;;;;;;;;AAUA,SAAgB,SACf,OACA,MACA,gBAA0C,CAAC,GACC;CAC5C,MAAM,UAAU,IAAI,IAAiB,aAAa;CAClD,MAAM,YAAY;CAClB,OAAO,eAA6C;EACnD,MAAM,WAAW,CAAC;EAClB,MAAM,+BAAe,IAAI,IAAY;EACrC,KAAK,MAAM,aAAa,OAAO,KAAK,KAAK,GAAG;GAC3C,IAAI,QAAQ,IAAI,SAAS,GAAG;GAC5B,IAAI,UAAU,WAAW,KAAK,MAAM,KAAK,SAAS,GAAG,MAAM,IAAI,UAAU,4BAA4B,UAAU,GAAG;GAClH,MAAM,cAAc,cAAc,SAAS;GAC3C,IAAI,aAAa,IAAI,WAAW,GAC/B,MAAM,IAAI,UAAU,iDAAiD,YAAY,GAAG;GAErF,aAAa,IAAI,WAAW;GAC5B,OAAO,eAAe,UAAU,aAAa;IAC5C,YAAY;IACZ,QAAQ,GAAG,eAAgC;KAC1C,UAAU,WAAW,GAAG,UAAU;IACnC;IACA,UAAU;GACX,CAAC;EACF;EACA,OAAO;CACR,CAAC;AACF"}

package/dist/vue/expose.d.mts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"expose.d.mts","names":[],"sources":["../../src/vue/expose.ts"],"mappings":";;;;;;;;iBAOgB,UAAU,wBAAwB,SAAS,UAAU,kBAAkB,SAAS,UAAU"}

package/dist/vue/expose.mjs

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

package/dist/vue/expose.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"expose.mjs","names":[],"sources":["../../src/vue/expose.ts"],"sourcesContent":["/**\n * 同时暴露组件实例能力并返回同一个对象，便于 `setup` 返回状态供 Vue Devtools 查看。\n *\n * @param expose - `setup` 上下文提供的 expose 函数。\n * @param exposed - 需要暴露的状态和方法。\n * @returns 原始 exposed 对象。\n */\nexport function useExpose<Exposed extends object>(expose: (exposed?: Exposed) => void, exposed: Exposed): Exposed {\n\texpose(exposed);\n\treturn exposed;\n}\n"],"mappings":";;;;;;;;AAOA,SAAgB,UAAkC,QAAqC,SAA2B;CACjH,OAAO,OAAO;CACd,OAAO;AACR"}

package/dist/vue/func.d.mts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"func.d.mts","names":[],"sources":["../../src/vue/func.ts"],"mappings":";;KACY,kBAAkB,sCAAsC,cAAc,YAAY,cAAc,SAAS,YAAY;;;;;;;;iBAS3G,qBAAqB,sCAAsC,QAChF,WAAW,kBAAkB,WAAW,+BACrC,YAAY,YACb,QAAQ,QAAQ"}

package/dist/vue/func.mjs

@@ -0,0 +1,16 @@
+//#region src/vue/func.ts
+/**
+* 统一执行同步或异步函数，异常保持原样向调用方传播。
+*
+* @param function_ - 可选的待执行函数。
+* @param arguments_ - 原样传入函数的参数。
+* @returns 函数结果；未传函数时返回 `undefined`。
+*/
+async function callOptionalFunction(function_, ...arguments_) {
+	if (function_ === null || function_ === void 0) return void 0;
+	return await function_(...arguments_);
+}
+//#endregion
+export { callOptionalFunction };
+
+//# sourceMappingURL=func.mjs.map

package/dist/vue/func.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"func.mjs","names":[],"sources":["../../src/vue/func.ts"],"sourcesContent":["/** 可同步或异步返回结果的函数。 */\nexport type AwaitableFunction<Arguments extends readonly unknown[], Result> = (...arguments_: Arguments) => Result | PromiseLike<Result>;\n\n/**\n * 统一执行同步或异步函数，异常保持原样向调用方传播。\n *\n * @param function_ - 可选的待执行函数。\n * @param arguments_ - 原样传入函数的参数。\n * @returns 函数结果；未传函数时返回 `undefined`。\n */\nexport async function callOptionalFunction<Arguments extends readonly unknown[], Result>(\n\tfunction_: AwaitableFunction<Arguments, Result> | null | undefined,\n\t...arguments_: Arguments\n): Promise<Awaited<Result> | undefined> {\n\tif (function_ === null || function_ === undefined) return undefined;\n\treturn await function_(...arguments_);\n}\n"],"mappings":";;;;;;;;AAUA,eAAsB,qBACrB,WACA,GAAG,YACoC;CACvC,IAAI,cAAc,QAAQ,cAAc,KAAA,GAAW,OAAO,KAAA;CAC1D,OAAO,MAAM,UAAU,GAAG,UAAU;AACrC"}

package/dist/vue/index.d.mts

@@ -0,0 +1,9 @@
+import { EmitHandlers, useEmits } from "./emits.mjs";
+import { useExpose } from "./expose.mjs";
+import { AwaitableFunction, callOptionalFunction } from "./func.mjs";
+import { Installable, TSXWithInstall, VueInstallValue, VueRegistrationTarget, withInstall, withInstallDirective, withNoopInstall } from "./install.mjs";
+import { definePropType, useProps } from "./props.mjs";
+import { useRender } from "./render.mjs";
+import { TypedSlots, TypedSlotsDeclaration, makeSlots } from "./slots.mjs";
+import { withDefineType } from "./with.mjs";
+export { AwaitableFunction, EmitHandlers, Installable, TSXWithInstall, TypedSlots, TypedSlotsDeclaration, VueInstallValue, VueRegistrationTarget, callOptionalFunction, definePropType, makeSlots, useEmits, useExpose, useProps, useRender, withDefineType, withInstall, withInstallDirective, withNoopInstall };