@yuhere/js-jsonrpc2 2.1.2 → 2.1.4

package/htdoc/assets/{index-CQr-lnlD.js → index-sVQlhxjI.js}

@@ -8129,7 +8129,7 @@ var THEME_OPTIONS = [
 		label: "暗"
 	}
 ];
-function Toolbar({ transport, onTransportChange, onRefresh, loading, error }) {
+function Toolbar({ transport, onTransportChange, onRefresh, loading, error, onGenerateDocs, generatingDocs }) {
 	const { mode, setMode } = useTheme();
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("header", {
 		className: "toolbar",
@@ -8156,6 +8156,12 @@ function Toolbar({ transport, onTransportChange, onRefresh, loading, error }) {
 				disabled: loading,
 				children: loading ? "刷新中…" : "刷新方法列表"
 			}),
+			/* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", {
+				onClick: onGenerateDocs,
+				disabled: generatingDocs || loading || loading,
+				title: "拉取所有方法的帮助与签名，生成 Markdown 文档并下载",
+				children: generatingDocs ? "生成中…" : "生成文档 ⬇"
+			}),
 			error && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", {
 				className: "error",
 				children: error
@@ -8446,7 +8452,7 @@ function MethodDetail({ method, detail }) {
 //#endregion
 //#region webui/src/api/paramForm.ts
 /** 判断是否为合法 schema 描述（kind 为字符串） */
-function isSchema(v) {
+function isSchema$1(v) {
 	return !!v && typeof v === "object" && typeof v.kind === "string";
 }
 /**
@@ -8470,20 +8476,20 @@ function sampleFromSchema(schema) {
 			const values = schema.constraints?.values;
 			return Array.isArray(values) && values.length > 0 ? values[0] : "";
 		}
-		case "nullable": return isSchema(c.inner) ? sampleFromSchema(c.inner) : null;
-		case "array": return [isSchema(c.items) ? sampleFromSchema(c.items) : null];
-		case "tuple": return (Array.isArray(c.items) ? c.items : []).map((it) => isSchema(it) ? sampleFromSchema(it) : null);
+		case "nullable": return isSchema$1(c.inner) ? sampleFromSchema(c.inner) : null;
+		case "array": return [isSchema$1(c.items) ? sampleFromSchema(c.items) : null];
+		case "tuple": return (Array.isArray(c.items) ? c.items : []).map((it) => isSchema$1(it) ? sampleFromSchema(it) : null);
 		case "union": {
 			const options = Array.isArray(c.options) ? c.options : [];
-			return options.length > 0 && isSchema(options[0]) ? sampleFromSchema(options[0]) : null;
+			return options.length > 0 && isSchema$1(options[0]) ? sampleFromSchema(options[0]) : null;
 		}
 		case "object": {
 			const props = c.properties ?? {};
 			const out = {};
-			for (const [k, v] of Object.entries(props)) if (isSchema(v)) out[k] = sampleFromSchema(v);
+			for (const [k, v] of Object.entries(props)) if (isSchema$1(v)) out[k] = sampleFromSchema(v);
 			return out;
 		}
-		case "record": return { key: isSchema(c.values) ? sampleFromSchema(c.values) : null };
+		case "record": return { key: isSchema$1(c.values) ? sampleFromSchema(c.values) : null };
 		default: return null;
 	}
 }
@@ -8531,7 +8537,7 @@ function SchemaField({ schema, value, onChange, label, depth = 0, defaultOpen =
 	const [open, setOpen] = (0, import_react.useState)(defaultOpen);
 	const kind = schema.kind;
 	if (kind === "nullable") {
-		const inner = schema.children && isSchema(schema.children.inner) ? schema.children.inner : void 0;
+		const inner = schema.children && isSchema$1(schema.children.inner) ? schema.children.inner : void 0;
 		if (!inner) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(UnknownLeaf, {
 			schema,
 			value,
@@ -8556,10 +8562,6 @@ function SchemaField({ schema, value, onChange, label, depth = 0, defaultOpen =
 						style: { color: colorOf("nullable") },
 						children: "nullable"
 					}),
-					/* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", {
-						className: "sf-nullable",
-						children: "| null"
-					}),
 					!isNull && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", {
 						type: "button",
 						className: "tiny",
@@ -8623,7 +8625,7 @@ function SchemaField({ schema, value, onChange, label, depth = 0, defaultOpen =
 		})]
 	});
 	if (kind === "union") {
-		const options = Array.isArray(schema.children?.options) ? schema.children.options.filter(isSchema) : [];
+		const options = Array.isArray(schema.children?.options) ? schema.children.options.filter(isSchema$1) : [];
 		return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 			className: "sf-node sf-row",
 			style: { paddingLeft: depth * 14 },
@@ -8799,7 +8801,7 @@ function UnionField({ options, value, onChange, depth, disabled }) {
 function ContainerChildren({ schema, value, onChange, depth, disabled }) {
 	const c = schema.children ?? {};
 	if (schema.kind === "array") {
-		const itemSchema = isSchema(c.items) ? c.items : void 0;
+		const itemSchema = isSchema$1(c.items) ? c.items : void 0;
 		if (!itemSchema) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", {
 			className: "hint",
 			children: "（数组无 item schema）"
@@ -8835,7 +8837,7 @@ function ContainerChildren({ schema, value, onChange, depth, disabled }) {
 		})] });
 	}
 	if (schema.kind === "tuple") {
-		const items = Array.isArray(c.items) ? c.items.filter(isSchema) : [];
+		const items = Array.isArray(c.items) ? c.items.filter(isSchema$1) : [];
 		const arr = Array.isArray(value) ? value : [];
 		return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { children: items.map((itemSchema, i) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SchemaField, {
 			schema: itemSchema,
@@ -8856,7 +8858,7 @@ function ContainerChildren({ schema, value, onChange, depth, disabled }) {
 		const obj = value && typeof value === "object" && !Array.isArray(value) ? value : {};
 		const strict = Boolean(schema.constraints?.strict);
 		return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { children: [Object.entries(props).map(([key, prop]) => {
-			if (!isSchema(prop)) return null;
+			if (!isSchema$1(prop)) return null;
 			return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SchemaField, {
 				schema: prop,
 				value: obj[key],
@@ -8881,7 +8883,7 @@ function ContainerChildren({ schema, value, onChange, depth, disabled }) {
 		})] });
 	}
 	if (schema.kind === "record") {
-		const valueSchema = isSchema(c.values) ? c.values : void 0;
+		const valueSchema = isSchema$1(c.values) ? c.values : void 0;
 		if (!valueSchema) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", {
 			className: "hint",
 			children: "（record 无 value schema）"
@@ -9009,11 +9011,17 @@ var COPY_OPTIONS = [{
 	value: "fetch",
 	label: "复制 fetch"
 }];
+/** 格式化耗时：<1s 用 ms，否则用 s */
+function formatElapsed(ms) {
+	if (ms < 1e3) return `${ms.toFixed(0)} ms`;
+	return `${(ms / 1e3).toFixed(2)} s`;
+}
 function TestPanel({ method, detail, rpc, transport, endpoint }) {
 	const paramSchemas = (0, import_react.useMemo)(() => detail.signature.slice(1), [detail.signature]);
 	const isStreamReturn = detail.signature[0]?.kind === "stream";
 	const [values, setValues] = (0, import_react.useState)([]);
 	const [output, setOutput] = (0, import_react.useState)("");
+	const [elapsed, setElapsed] = (0, import_react.useState)(null);
 	const [running, setRunning] = (0, import_react.useState)(false);
 	const [copyKind, setCopyKind] = (0, import_react.useState)("curl");
 	const [copied, setCopied] = (0, import_react.useState)(false);
@@ -9025,6 +9033,7 @@ function TestPanel({ method, detail, rpc, transport, endpoint }) {
 		if (!method) return;
 		setValues(paramSchemas.map(sampleFromSchema));
 		setOutput("");
+		setElapsed(null);
 	}, [method, paramSchemas]);
 	(0, import_react.useEffect)(() => {
 		setCopied(false);
@@ -9050,25 +9059,37 @@ function TestPanel({ method, detail, rpc, transport, endpoint }) {
 		if (!method) return;
 		setRunning(true);
 		setOutput("");
+		setElapsed(null);
+		const startedAt = performance.now();
 		try {
 			const result = await rpc.call(method, ...values);
+			const firstFrameAt = performance.now() - startedAt;
 			if (isStreamResult(result)) {
 				let idx = 0;
 				const lines = [];
 				for await (const value of result) {
-					lines.push(`[${idx}] ${JSON.stringify(value, null, 2)}`);
+					const now = performance.now() - startedAt;
+					lines.push(`[${idx}] (+${formatElapsed(now)}) ${JSON.stringify(value, null, 2)}`);
 					idx++;
 					setOutput(lines.join("\n"));
 				}
-				if (idx === 0) setOutput("（流已结束，无数据）");
-				else lines.push(`（流已结束，共 ${idx} 帧）`), setOutput(lines.join("\n"));
-			} else setOutput(JSON.stringify(result, null, 2));
-			if (isStreamReturn) {} else {
-				const result = await rpc.call(method, ...values);
+				const totalAt = performance.now() - startedAt;
+				if (idx === 0) lines.push(`（流已结束，无数据，总耗时 ${formatElapsed(totalAt)}）`);
+				else lines.push(`（流已结束，共 ${idx} 帧，总耗时 ${formatElapsed(totalAt)}）`);
+				setOutput(lines.join("\n"));
+				setElapsed({
+					total: totalAt,
+					firstFrame: firstFrameAt
+				});
+			} else {
+				const totalAt = performance.now() - startedAt;
 				setOutput(JSON.stringify(result, null, 2));
+				setElapsed({ total: totalAt });
 			}
 		} catch (e) {
+			const totalAt = performance.now() - startedAt;
 			setOutput(formatError(e));
+			setElapsed({ total: totalAt });
 		} finally {
 			setRunning(false);
 			requestAnimationFrame(() => outRef.current?.scrollIntoView({ block: "nearest" }));
@@ -9180,16 +9201,38 @@ function TestPanel({ method, detail, rpc, transport, endpoint }) {
 						children: "重置为示例"
 					}),
 					/* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", {
-						onClick: () => setOutput(""),
-						disabled: !output,
+						onClick: () => {
+							setOutput("");
+							setElapsed(null);
+						},
+						disabled: !output && !elapsed,
 						children: "清空输出"
 					})
 				]
 			}),
-			/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("h3", { children: ["结果", isStreamReturn && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", {
-				className: "hint",
-				children: "（流式）"
-			})] }),
+			/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("h3", { children: [
+				"结果",
+				isStreamReturn && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", {
+					className: "hint",
+					children: "（流式）"
+				}),
+				elapsed && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", {
+					className: "elapsed-badge",
+					children: [
+						" ",
+						"⏱ ",
+						formatElapsed(elapsed.total),
+						elapsed.firstFrame !== void 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", {
+							className: "hint",
+							children: [
+								" ",
+								"· 首帧 ",
+								formatElapsed(elapsed.firstFrame)
+							]
+						})
+					]
+				})
+			] }),
 			/* @__PURE__ */ (0, import_jsx_runtime.jsx)("pre", {
 				className: "output",
 				ref: outRef,
@@ -9232,11 +9275,142 @@ function formatError(e) {
 	return `Error: ${e instanceof Error ? e.message : String(e)}`;
 }
 //#endregion
+//#region webui/src/api/docGen.ts
+function isSchema(v) {
+	return !!v && typeof v === "object" && typeof v.kind === "string";
+}
+/** 逐个方法拉取 help + signature */
+async function collectApiDoc(rpc, methods, onProgress) {
+	const out = [];
+	for (let i = 0; i < methods.length; i++) {
+		const name = methods[i];
+		try {
+			const [help, sig] = await Promise.all([rpc.call("system.methodHelp", name).catch(() => ""), rpc.call("system.methodSignature", name).catch(() => [])]);
+			out.push({
+				name,
+				help: typeof help === "string" ? help : "",
+				signature: Array.isArray(sig) ? sig.filter(isSchema) : []
+			});
+		} catch (e) {
+			out.push({
+				name,
+				help: "",
+				signature: [],
+				error: e instanceof Error ? e.message : String(e)
+			});
+		}
+		onProgress?.(i + 1, methods.length);
+	}
+	return {
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		methods: out
+	};
+}
+function renderSchemaTree(schema, indent = 0) {
+	const pad = "  ".repeat(indent);
+	const lines = [];
+	let head = `${pad}- \`${schema.kind}\``;
+	if (schema.nullable) head += " _(nullable)_";
+	if (schema.description) head += ` — ${schema.description}`;
+	const c = schema.constraints;
+	if (c && Object.keys(c).length > 0) {
+		const parts = Object.entries(c).filter(([, v]) => v !== void 0).map(([k, v]) => `${k}=${JSON.stringify(v)}`);
+		if (parts.length) head += ` \`{ ${parts.join(", ")} }\``;
+	}
+	lines.push(head);
+	const ch = schema.children ?? {};
+	const pushChild = (label, child) => {
+		const sub = renderSchemaTree(child, indent + 1);
+		if (sub.length) {
+			sub[0] = `${"  ".repeat(indent + 1)}- **${label}**: ${sub[0].trim().replace(/^- /, "")}`;
+			lines.push(...sub);
+		}
+	};
+	if (isSchema(ch.inner)) pushChild("inner", ch.inner);
+	if (Array.isArray(ch.items)) ch.items.forEach((it, i) => {
+		if (isSchema(it)) pushChild(`[${i}]`, it);
+	});
+	else if (isSchema(ch.items)) pushChild("items", ch.items);
+	if (Array.isArray(ch.options)) ch.options.forEach((opt, i) => {
+		if (isSchema(opt)) pushChild(`option[${i}]`, opt);
+	});
+	if (ch.properties && typeof ch.properties === "object") {
+		for (const [k, v] of Object.entries(ch.properties)) if (isSchema(v)) pushChild(k, v);
+	}
+	if (isSchema(ch.values)) pushChild("values", ch.values);
+	return lines;
+}
+function renderMarkdown(doc) {
+	const lines = [];
+	lines.push("# JSON-RPC API 文档");
+	lines.push("");
+	lines.push(`> 生成时间：${doc.generatedAt}`);
+	lines.push(`> 方法总数：${doc.methods.length}`);
+	lines.push("");
+	lines.push("## 目录");
+	lines.push("");
+	for (const m of doc.methods) {
+		const anchor = m.name.toLowerCase().replace(/[^\w]+/g, "-");
+		lines.push(`- [\`${m.name}\`](#${anchor})`);
+	}
+	lines.push("");
+	for (const m of doc.methods) {
+		lines.push(`## \`${m.name}\``);
+		lines.push("");
+		if (m.error) {
+			lines.push(`> ⚠️ 获取失败：${m.error}`);
+			lines.push("");
+			continue;
+		}
+		lines.push("**帮助**");
+		lines.push("");
+		lines.push(m.help ? m.help : "_（无帮助信息）_");
+		lines.push("");
+		if (m.signature.length === 0) {
+			lines.push("**签名**：_（无）_");
+			lines.push("");
+			continue;
+		}
+		const [ret, ...params] = m.signature;
+		lines.push("**返回类型**");
+		lines.push("");
+		lines.push(...renderSchemaTree(ret, 0));
+		lines.push("");
+		lines.push(`**参数**（${params.length} 个）`);
+		lines.push("");
+		if (params.length === 0) lines.push("_（无参数）_");
+		else params.forEach((p, i) => {
+			const sub = renderSchemaTree(p, 0);
+			if (sub.length) {
+				sub[0] = `- **参数 [${i}]**: ${sub[0].trim().replace(/^- /, "")}`;
+				lines.push(...sub);
+			}
+		});
+		lines.push("");
+		lines.push("---");
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+/** 触发浏览器下载 */
+function downloadText(filename, text, mime = "text/plain") {
+	const blob = new Blob([text], { type: `${mime};charset=utf-8` });
+	const url = URL.createObjectURL(blob);
+	const a = document.createElement("a");
+	a.href = url;
+	a.download = filename;
+	document.body.appendChild(a);
+	a.click();
+	document.body.removeChild(a);
+	setTimeout(() => URL.revokeObjectURL(url), 1e3);
+}
+//#endregion
 //#region webui/src/App.tsx
 var ENDPOINT = "";
 function App() {
 	const [transport, setTransport] = (0, import_react.useState)("http");
 	const [selected, setSelected] = (0, import_react.useState)("");
+	const [generatingDocs, setGeneratingDocs] = (0, import_react.useState)(false);
 	const rpc = (0, import_react.useMemo)(() => {
 		return createRpc({
 			transport,
@@ -9248,6 +9422,21 @@ function App() {
 	}, [rpc]);
 	const { methods, loading, error, refresh } = useMethods(rpc);
 	const detail = useMethodDetail(rpc, selected);
+	const generateDocs = (0, import_react.useCallback)(async () => {
+		if (methods.length === 0) {
+			alert("方法列表为空，请先刷新方法列表。");
+			return;
+		}
+		setGeneratingDocs(true);
+		try {
+			const md = renderMarkdown(await collectApiDoc(rpc, methods));
+			downloadText(`jsonrpc-api-doc-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)}.md`, md, "text/markdown");
+		} catch (e) {
+			alert(`生成文档失败：${e instanceof Error ? e.message : String(e)}`);
+		} finally {
+			setGeneratingDocs(false);
+		}
+	}, [rpc, methods]);
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 		className: "app",
 		children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Toolbar, {
@@ -9255,7 +9444,9 @@ function App() {
 			onTransportChange: setTransport,
 			onRefresh: refresh,
 			loading,
-			error
+			error,
+			onGenerateDocs: generateDocs,
+			generatingDocs
 		}), /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("main", { children: [/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("aside", {
 			className: "sidebar",
 			children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)("h2", { children: "Methods" }), /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MethodTree, {
@@ -9283,4 +9474,4 @@ function App() {
 import_client.createRoot(document.getElementById("root")).render(/* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react.StrictMode, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ThemeProvider, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(App, {}) }) }));
 //#endregion
 
-//# sourceMappingURL=index-CQr-lnlD.js.map
+//# sourceMappingURL=index-sVQlhxjI.js.map