@yuhere/js-jsonrpc2 2.1.2 → 2.1.4

package/htdoc/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>JSON-RPC 2.0</title>
-    <script type="module" crossorigin src="./assets/index-CQr-lnlD.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-hcP2-9jw.css">
+    <script type="module" crossorigin src="./assets/index-sVQlhxjI.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BAZmvr5x.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuhere/js-jsonrpc2",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "A TypeScript JSON-RPC 2.0 server library with schema validation, authorization, dependency injection, and multiple transports.",
   "homepage": "https://github.com/yuhere/js-jsonrpc2#readme",
   "license": "MIT",
@@ -40,8 +40,8 @@
     "js-jsonrpc2": "./dist/cli.js"
   },
   "scripts": {
-    "build": "npm run build:lib && npm run build:webui",
-    "build:lib": "tsc -p tsconfig.build.json",
+    "build": "clean && npm run build:lib && npm run build:webui",
+    "build:lib": "tsc -p tsconfig.build.json && tsc-esm-fix",
     "build:webui": "tsc -p webui//tsconfig.json && vite build --config webui/vite.config.ts",
     "dev": "run-p dev:lib dev:webui",
     "dev:lib": "tsx src/cli/express.ts",
@@ -78,6 +78,7 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "supertest": "^7.3.1",
+    "tsc-esm-fix": "^3.1.2",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
     "vite": "^8.3.5",
@@ -89,4 +90,4 @@
     "ws": "^8.22.0",
     "zod": "^4.6.7"
   }
-}
+}

package/webui/src/App.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import { createRpc, type TransportKind } from './api/rpc';
 import { useMethods } from './hooks/useMethods';
 import { useMethodDetail } from './hooks/useMethodDetail';
@@ -6,14 +6,18 @@ import { Toolbar } from './components/Toolbar';
 import { MethodTree } from './components/MethodTree';
 import { MethodDetail } from './components/MethodDetail';
 import { TestPanel } from './components/TestPanel';
+import {
+    collectApiDoc,
+    downloadText,
+    renderMarkdown,
+} from './api/docGen';
 
 const ENDPOINT = '';
-// 如需强制指定 WS 地址，可改为例如 'ws://localhost:3000/'
-// 默认由 wsTransport 从 window.location 推导。
 
 export default function App() {
     const [transport, setTransport] = useState<TransportKind>('http');
     const [selected, setSelected] = useState('');
+    const [generatingDocs, setGeneratingDocs] = useState(false);
 
     const rpc = useMemo(() => {
         return createRpc({ transport, endpoint: ENDPOINT });
@@ -26,6 +30,27 @@ export default function App() {
     const { methods, loading, error, refresh } = useMethods(rpc);
     const detail = useMethodDetail(rpc, selected);
 
+    const generateDocs = useCallback(async () => {
+        if (methods.length === 0) {
+            alert('方法列表为空，请先刷新方法列表。');
+            return;
+        }
+        setGeneratingDocs(true);
+        try {
+            const doc = await collectApiDoc(rpc, methods);
+            const md = renderMarkdown(doc);
+            const ts = new Date()
+                .toISOString()
+                .replace(/[:.]/g, '-')
+                .slice(0, 19);
+            downloadText(`jsonrpc-api-doc-${ts}.md`, md, 'text/markdown');
+        } catch (e) {
+            alert(`生成文档失败：${e instanceof Error ? e.message : String(e)}`);
+        } finally {
+            setGeneratingDocs(false);
+        }
+    }, [rpc, methods]);
+
     return (
         <div className="app">
             <Toolbar
@@ -34,6 +59,8 @@ export default function App() {
                 onRefresh={refresh}
                 loading={loading}
                 error={error}
+                onGenerateDocs={generateDocs}
+                generatingDocs={generatingDocs}
             />
             <main>
                 <aside className="sidebar">

package/webui/src/api/docGen.ts

@@ -0,0 +1,188 @@
+import type { RpcClient } from './rpc';
+import type { SchemaDescription } from './schema';
+
+export interface MethodDoc {
+    name: string;
+    help: string;
+    signature: SchemaDescription[];
+    error?: string;
+}
+
+export interface ApiDoc {
+    generatedAt: string;
+    methods: MethodDoc[];
+}
+
+function isSchema(v: unknown): v is SchemaDescription {
+    return !!v && typeof v === 'object' && typeof (v as SchemaDescription).kind === 'string';
+}
+
+/** 逐个方法拉取 help + signature */
+export async function collectApiDoc(
+    rpc: RpcClient,
+    methods: string[],
+    onProgress?: (done: number, total: number) => void,
+): Promise<ApiDoc> {
+    const out: MethodDoc[] = [];
+    for (let i = 0; i < methods.length; i++) {
+        const name = methods[i];
+        try {
+            const [help, sig] = await Promise.all([
+                rpc.call<string>('system.methodHelp', name).catch(() => ''),
+                rpc.call<unknown[]>('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: new Date().toISOString(), methods: out };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Markdown 渲染
+// ─────────────────────────────────────────────────────────────
+
+function renderSchema(schema: SchemaDescription): string {
+    // 简单的单行描述：kind + constraints + nullable
+    let s = schema.kind;
+    if (schema.nullable) s += ' | null';
+    const c = schema.constraints;
+    if (c && Object.keys(c).length > 0) {
+        const parts = Object.entries(c)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => `${k}=${JSON.stringify(v)}`);
+        if (parts.length) s += ` { ${parts.join(', ')} }`;
+    }
+    return s;
+}
+
+function renderSchemaTree(schema: SchemaDescription, indent = 0): string[] {
+    const pad = '  '.repeat(indent);
+    const lines: string[] = [];
+    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 !== undefined)
+            .map(([k, v]) => `${k}=${JSON.stringify(v)}`);
+        if (parts.length) head += ` \`{ ${parts.join(', ')} }\``;
+    }
+    lines.push(head);
+
+    const ch = schema.children ?? {};
+    const pushChild = (label: string, child: SchemaDescription) => {
+        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 as unknown[]).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 as unknown[]).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;
+}
+
+export function renderMarkdown(doc: ApiDoc): string {
+    const lines: string[] = [];
+    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');
+}
+
+/** 触发浏览器下载 */
+export function downloadText(filename: string, text: string, 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), 1000);
+}

package/webui/src/components/SchemaForm.tsx

@@ -120,7 +120,6 @@ function SchemaField({
                     <span className="sf-kind" style={{ color: colorOf('nullable') }}>
                         nullable
                     </span>
-                    <span className="sf-nullable">| null</span>
                     {!isNull && (
                         <button
                             type="button"

package/webui/src/components/TestPanel.tsx

@@ -20,6 +20,12 @@ const COPY_OPTIONS: { value: CopyKind; label: string }[] = [
     { value: 'fetch', label: '复制 fetch' },
 ];
 
+/** 格式化耗时：<1s 用 ms，否则用 s */
+function formatElapsed(ms: number): string {
+    if (ms < 1000) return `${ms.toFixed(0)} ms`;
+    return `${(ms / 1000).toFixed(2)} s`;
+}
+
 export function TestPanel({
     method,
     detail,
@@ -32,6 +38,7 @@ export function TestPanel({
 
     const [values, setValues] = useState<unknown[]>([]);
     const [output, setOutput] = useState('');
+    const [elapsed, setElapsed] = useState<{ total: number; firstFrame?: number } | null>(null);
     const [running, setRunning] = useState(false);
     const [copyKind, setCopyKind] = useState<CopyKind>('curl');
     const [copied, setCopied] = useState(false);
@@ -44,6 +51,7 @@ export function TestPanel({
         if (!method) return;
         setValues(paramSchemas.map(sampleFromSchema));
         setOutput('');
+        setElapsed(null);
     }, [method, paramSchemas]);
 
     useEffect(() => {
@@ -76,29 +84,46 @@ export function TestPanel({
         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: string[] = [];
+
+                // 每帧记录到达时间
                 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) {
+                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 result = await rpc.call(method, ...values);
+                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(() =>
@@ -211,12 +236,30 @@ export function TestPanel({
                 >
                     重置为示例
                 </button>
-                <button onClick={() => setOutput('')} disabled={!output}>
+                <button
+                    onClick={() => {
+                        setOutput('');
+                        setElapsed(null);
+                    }}
+                    disabled={!output && !elapsed}
+                >
                     清空输出
                 </button>
             </div>
 
-            <h3>结果{isStreamReturn && <span className="hint">（流式）</span>}</h3>
+            <h3>
+                结果{isStreamReturn && <span className="hint">（流式）</span>}
+                {elapsed && (
+                    <span className="elapsed-badge">
+                        {' '}⏱ {formatElapsed(elapsed.total)}
+                        {elapsed.firstFrame !== undefined && (
+                            <span className="hint">
+                                {' '}· 首帧 {formatElapsed(elapsed.firstFrame)}
+                            </span>
+                        )}
+                    </span>
+                )}
+            </h3>
             <pre className="output" ref={outRef}>
                 {output || '（尚未执行）'}
             </pre>

package/webui/src/components/Toolbar.tsx

@@ -7,6 +7,9 @@ interface ToolbarProps {
     onRefresh: () => void;
     loading: boolean;
     error: string | null;
+    /** 新增：生成文档 */
+    onGenerateDocs: () => void;
+    generatingDocs: boolean;
 }
 
 const THEME_OPTIONS: { value: ThemeMode; label: string }[] = [
@@ -21,6 +24,8 @@ export function Toolbar({
     onRefresh,
     loading,
     error,
+    onGenerateDocs,
+    generatingDocs,
 }: ToolbarProps) {
     const { mode, setMode } = useTheme();
 
@@ -49,9 +54,16 @@ export function Toolbar({
                 {loading ? '刷新中…' : '刷新方法列表'}
             </button>
 
+            <button
+                onClick={onGenerateDocs}
+                disabled={generatingDocs || loading || loading /* methods 空时由 App 拦截 */}
+                title="拉取所有方法的帮助与签名，生成 Markdown 文档并下载"
+            >
+                {generatingDocs ? '生成中…' : '生成文档 ⬇'}
+            </button>
+
             {error && <span className="error">{error}</span>}
 
-            {/* 主题下拉，放右上角 */}
             <label className="theme-select" title="主题">
                 <span className="theme-select-label">主题</span>
                 <select

package/webui/src/styles/geek.css

@@ -726,4 +726,17 @@ textarea:focus {
     .split-button {
         display: inline-flex;
     }
+}
+
+/* ---- 耗时徽章（TestPanel 结果区） ---- */
+.elapsed-badge {
+    color: var(--syn-number);
+    font-size: 12px;
+    font-weight: normal;
+    letter-spacing: 0;
+    text-transform: none;
+}
+
+.elapsed-badge .hint {
+    font-size: 11px;
 }

package/dist/schema/index.d.ts

@@ -1,4 +0,0 @@
-export * from './primitives';
-export * from './rpc';
-export { z } from 'zod';
-//# sourceMappingURL=index.d.ts.map

package/dist/schema/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,OAAO,CAAC;AACtB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC"}

package/dist/schema/index.js

@@ -1,4 +0,0 @@
-export * from './primitives';
-export * from './rpc';
-export { z } from 'zod';
-//# sourceMappingURL=index.js.map

package/dist/schema/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,OAAO,CAAC;AACtB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC"}

package/dist/schema/primitives.d.ts

@@ -1,25 +0,0 @@
-import type { ParamSchema } from '../types';
-export interface ParamMeta {
-    kind?: 'void' | 'any' | 'array' | 'boolean' | 'function' | 'number' | 'object' | 'string' | 'symbol' | 'arrayOf' | 'objectOf' | 'shape' | 'oneOf' | 'oneOfType' | 'instanceOf' | 'injectable';
-    naming?: string;
-    required?: 'none' | 'isRequired' | 'isRequiredNotNull';
-    injectable?: string;
-    of?: unknown;
-}
-export declare function getMeta(schema: ParamSchema): ParamMeta;
-export declare function setJSONString(schema: ParamSchema, description: string): ParamSchema;
-export declare function toJSONString(schema: ParamSchema): string;
-export declare function voidSchema(): ParamSchema;
-export declare function anySchema(): ParamSchema;
-export declare function injectableSchema(name: string): ParamSchema;
-export declare function named(schema: ParamSchema, naming: string): ParamSchema;
-export declare function required(schema: ParamSchema): ParamSchema;
-export declare function requiredNotNull(schema: ParamSchema): ParamSchema;
-export declare function primitiveSchema(kind: 'void' | 'string' | 'number' | 'boolean' | 'function' | 'object' | 'symbol' | 'array'): ParamSchema;
-export declare function arrayOf(schema: ParamSchema): ParamSchema;
-export declare function objectOf(schema: ParamSchema): ParamSchema;
-export declare function oneOf<T extends readonly [string, ...string[]]>(values: T): ParamSchema;
-export declare function oneOfType(schemas: ParamSchema[]): ParamSchema;
-export declare function shape<T extends Record<string, ParamSchema>>(shapeMap: T): ParamSchema;
-export declare function instanceOf<T extends abstract new (...args: any[]) => any>(cls: T): ParamSchema;
-//# sourceMappingURL=primitives.d.ts.map

package/dist/schema/primitives.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/schema/primitives.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EACH,MAAM,GACN,KAAK,GACL,OAAO,GACP,SAAS,GACT,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,UAAU,GACV,OAAO,GACP,OAAO,GACP,WAAW,GACX,YAAY,GACZ,YAAY,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,mBAAmB,CAAC;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,EAAE,CAAC,EAAE,OAAO,CAAC;CACd;AAOD,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAEtD;AA8BD,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW,CAInF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAMxD;AAED,wBAAgB,UAAU,IAAI,WAAW,CAIxC;AAED,wBAAgB,SAAS,IAAI,WAAW,CAIvC;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAI1D;AAED,wBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAKtE;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAKzD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAKhE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAC1F,WAAW,CA8Bb;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAKxD;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAKzD;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,WAAW,CAKtF;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,CAa7D;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,WAAW,CAOrF;AAED,wBAAgB,UAAU,CAAC,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,WAAW,CAO9F"}