@yuhere/js-jsonrpc2 0.0.0-stage → 2.1.1

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "@yuhere/js-jsonrpc2",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.1.1",
+  "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",
+  "engines": {
+    "node": ">=20"
+  },
+  "author": {
+    "name": "yuhere@gmail.com"
+  },
+  "bugs": {
+    "url": "https://github.com/yuhere/js-jsonrpc2/issues"
+  },
+  "files": [
+    "dist",
+    "htdoc",
+    "webui",
+    "dev",
+    "SKILL.md",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yuhere/js-jsonrpc2.git"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "js-jsonrpc2": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "npm run build:lib && npm run build:webui",
+    "build:lib": "tsc -p tsconfig.build.json",
+    "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",
+    "dev:webui": "vite build --config webui/vite.config.ts --watch --mode development",
+    "typecheck": "npm run typecheck:lib && npm run typecheck:webui",
+    "typecheck:lib": "tsc --noEmit",
+    "typecheck:webui": "tsc -p webui/tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist htdoc/assets htdoc/index.html"
+  },
+  "keywords": [
+    "json-rpc",
+    "jsonrpc",
+    "jsonrpc2",
+    "express",
+    "middleware",
+    "typescript",
+    "zod"
+  ],
+  "devDependencies": {
+    "@types/body-parser": "^1.19.6",
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.6.5",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@types/supertest": "^7.2.1",
+    "@types/type-is": "^1.6.7",
+    "@types/ws": "^8.18.2",
+    "@vitejs/plugin-react": "^6.1.2",
+    "@vitest/coverage-v8": "^5.0.5",
+    "express": "^5.3.0",
+    "npm-run-all": "^4.1.5",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "supertest": "^7.3.1",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
+    "ws": "^8.22.0"
+  },
+  "dependencies": {
+    "body-parser": "^2.3.0",
+    "zod": "^4.6.7"
+  }
 }

package/webui/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>JSON-RPC 2.0</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/webui/src/App.tsx

@@ -0,0 +1,56 @@
+import { useEffect, useMemo, useState } from 'react';
+import { createRpc, type TransportKind } from './api/rpc';
+import { useMethods } from './hooks/useMethods';
+import { useMethodDetail } from './hooks/useMethodDetail';
+import { Toolbar } from './components/Toolbar';
+import { MethodTree } from './components/MethodTree';
+import { MethodDetail } from './components/MethodDetail';
+import { TestPanel } from './components/TestPanel';
+
+const ENDPOINT = '';
+// 如需强制指定 WS 地址，可改为例如 'ws://localhost:3000/'
+// 默认由 wsTransport 从 window.location 推导。
+
+export default function App() {
+    const [transport, setTransport] = useState<TransportKind>('http');
+    const [selected, setSelected] = useState('');
+
+    const rpc = useMemo(() => {
+        return createRpc({ transport, endpoint: ENDPOINT });
+    }, [transport]);
+
+    useEffect(() => {
+        return () => rpc.close();
+    }, [rpc]);
+
+    const { methods, loading, error, refresh } = useMethods(rpc);
+    const detail = useMethodDetail(rpc, selected);
+
+    return (
+        <div className="app">
+            <Toolbar
+                transport={transport}
+                onTransportChange={setTransport}
+                onRefresh={refresh}
+                loading={loading}
+                error={error}
+            />
+            <main>
+                <aside className="sidebar">
+                    <h2>Methods</h2>
+                    <MethodTree methods={methods} selected={selected} onSelect={setSelected} />
+                </aside>
+                <div className="content">
+                    <MethodDetail method={selected} detail={detail} />
+                    <TestPanel
+                        method={selected}
+                        detail={detail}
+                        rpc={rpc}
+                        transport={transport}
+                        endpoint={ENDPOINT}
+                    />
+                </div>
+            </main>
+        </div>
+    );
+}

package/webui/src/api/httpTransport.ts

@@ -0,0 +1,148 @@
+import type { RpcResponse } from './types';
+import {
+    RPCError,
+    type CallResult,
+    type RpcClient,
+} from './rpc';
+
+export interface HttpRpcOptions {
+    endpoint?: string;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}
+
+let idCounter = 0;
+
+interface StreamFrame {
+    jsonrpc: '2.0';
+    id: number | string;
+    done: boolean;
+    index?: number;
+    value?: unknown;
+    error?: { code: number; message: string };
+}
+
+async function readLine(
+    reader: ReadableStreamDefaultReader<Uint8Array>,
+    decoder: TextDecoder,
+    state: { buf: string },
+): Promise<string | undefined> {
+    while (true) {
+        const nl = state.buf.indexOf('\n');
+        if (nl >= 0) {
+            const line = state.buf.slice(0, nl).trim();
+            state.buf = state.buf.slice(nl + 1);
+            if (line) return line;
+            continue;
+        }
+        const { done, value } = await reader.read();
+        if (done) {
+            const trailing = state.buf.trim();
+            state.buf = '';
+            return trailing.length > 0 ? trailing : undefined;
+        }
+        state.buf += decoder.decode(value, { stream: true });
+    }
+}
+
+function isStreamFrame(v: unknown): v is StreamFrame {
+    return !!v && typeof v === 'object' && typeof (v as StreamFrame).done === 'boolean';
+}
+
+export function createHttpRpc(options: HttpRpcOptions = {}): RpcClient {
+    const {
+        endpoint = '',
+        headers = {},
+        fetchImpl = fetch,
+    } = options;
+
+    function call<T = unknown>(method: string, ...params: unknown[]): CallResult<T> {
+        const id = ++idCounter;
+        const body = { jsonrpc: '2.0', method, params, id };
+
+        return (async () => {
+            const res = await fetchImpl(endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/x-ndjson',
+                    ...headers,
+                },
+                body: JSON.stringify(body),
+            });
+
+            if (!res.ok) {
+                throw new Error(`HTTP ${res.status} ${res.statusText}`);
+            }
+
+            if (!res.body) {
+                const payload = (await res.json()) as RpcResponse<T>;
+                if (payload.error) throw new RPCError(payload.error);
+                return payload.result as T;
+            }
+
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            const state = { buf: '' };
+
+            const firstLine = await readLine(reader, decoder, state);
+            if (firstLine === undefined) {
+                await reader.cancel().catch(() => { /* ignore */ });
+                throw new Error(`Empty response for ${method}`);
+            }
+
+            let first: StreamFrame | RpcResponse<T>;
+            try {
+                first = JSON.parse(firstLine);
+            } catch (e) {
+                await reader.cancel().catch(() => { /* ignore */ });
+                throw new Error(
+                    `Invalid JSON response for ${method}: ${e instanceof Error ? e.message : String(e)}`,
+                );
+            }
+
+            if (!isStreamFrame(first)) {
+                const payload = first as RpcResponse<T>;
+                await reader.cancel().catch(() => { /* ignore */ });
+                if (payload.error) throw new RPCError(payload.error);
+                return payload.result as T;
+            }
+
+            return (async function* (): AsyncGenerator<T, void, unknown> {
+                let drained = false;
+                try {
+                    let chunk = first;
+                    while (true) {
+                        if (chunk.error) throw new RPCError(chunk.error);
+                        if (chunk.done) { drained = true; return; }
+                        if (chunk.value !== undefined) yield chunk.value as T;
+                        const line = await readLine(reader, decoder, state);
+                        if (line === undefined) {
+                            throw new Error('Stream ended without terminal frame');
+                        }
+                        chunk = JSON.parse(line);
+                    }
+                } finally {
+                    if (!drained) {
+                        await reader.cancel().catch(() => { /* ignore */ });
+                    }
+                }
+            })();
+        })();
+    }
+
+    return {
+        call,
+        close() {
+        },
+    };
+}
+
+export function absoluteEndpoint(endpoint?: string): string {
+    const raw = endpoint && endpoint.trim().length > 0 ? endpoint : '/';
+    try {
+        return new URL(raw, window.location.href).toString();
+    } catch {
+        return raw;
+    }
+}

package/webui/src/api/paramForm.ts

@@ -0,0 +1,79 @@
+import type { SchemaDescription } from './schema';
+
+/** 判断是否为合法 schema 描述（kind 为字符串） */
+export function isSchema(v: unknown): v is SchemaDescription {
+    return !!v && typeof v === 'object' && typeof (v as SchemaDescription).kind === 'string';
+}
+
+/**
+ * 根据 schema 生成一个合理的示例值。
+ * - 原始类型返回零值（''、0、false）
+ * - literal 返回固定值
+ * - enum 返回第一个枚举值
+ * - nullable 返回 null
+ * - 容器类型递归展开
+ * - unknown 返回 null
+ */
+export function sampleFromSchema(schema: SchemaDescription): unknown {
+    if (schema.nullable) return null;
+    const c = schema.children ?? {};
+    switch (schema.kind) {
+        case 'string':
+            return '';
+        case 'number':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'literal':
+            return schema.constraints?.value ?? null;
+        case 'enum': {
+            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': {
+            const item = isSchema(c.items) ? sampleFromSchema(c.items) : null;
+            return [item];
+        }
+        case 'tuple': {
+            const items = Array.isArray(c.items) ? c.items : [];
+            return items.map((it) => (isSchema(it) ? sampleFromSchema(it) : null));
+        }
+        case 'union': {
+            const options = Array.isArray(c.options) ? c.options : [];
+            return options.length > 0 && isSchema(options[0])
+                ? sampleFromSchema(options[0] as SchemaDescription)
+                : null;
+        }
+        case 'object': {
+            const props = (c.properties ?? {}) as Record<string, unknown>;
+            const out: Record<string, unknown> = {};
+            for (const [k, v] of Object.entries(props)) {
+                if (isSchema(v)) out[k] = sampleFromSchema(v);
+            }
+            return out;
+        }
+        case 'record': {
+            const val = isSchema(c.values) ? sampleFromSchema(c.values) : null;
+            return { key: val };
+        }
+        default:
+            return null;
+    }
+}
+
+/** 是否用原生 input 编辑（否则走 JSON textarea / 递归容器） */
+export function isScalarSchema(schema: SchemaDescription): boolean {
+    if (schema.nullable) return true;
+    switch (schema.kind) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+        case 'enum':
+        case 'literal':
+            return true;
+        default:
+            return false;
+    }
+}

package/webui/src/api/rpc.ts

@@ -0,0 +1,57 @@
+import type { RPCErrorPayload } from './types';
+import { createHttpRpc, type HttpRpcOptions } from './httpTransport';
+import { createWsRpc, type WsRpcOptions } from './wsTransport';
+
+export type TransportKind = 'http' | 'ws';
+
+export type CallResult<T> = Promise<T> | AsyncGenerator<T, void, unknown>;
+
+export interface RpcClient {
+  call<T = unknown>(method: string, ...params: unknown[]): CallResult<T>;
+  close(): void;
+}
+
+export interface RpcOptions {
+  transport: TransportKind;
+  endpoint?: string;
+  headers?: Record<string, string>;
+  fetchImpl?: typeof fetch;
+  connectTimeoutMs?: number;
+  callTimeoutMs?: number;
+}
+
+export class RPCError extends Error {
+  constructor(public payload: RPCErrorPayload) {
+    super(payload.message);
+    this.name = 'RPCError';
+  }
+
+  get code(): number { return this.payload.code; }
+  get data(): unknown { return this.payload.data; }
+}
+
+export function isStreamResult<T>(v: CallResult<T>): v is AsyncGenerator<T, void, unknown> {
+  return (
+    !!v &&
+    typeof v === 'object' &&
+    typeof (v as AsyncGenerator<T>)[Symbol.asyncIterator] === 'function'
+  );
+}
+
+export function createRpc(options: RpcOptions): RpcClient {
+  if (options.transport === 'ws') {
+    const wsOpts: WsRpcOptions = {
+      endpoint: options.endpoint,
+      connectTimeoutMs: options.connectTimeoutMs,
+      callTimeoutMs: options.callTimeoutMs,
+    };
+    return createWsRpc(wsOpts);
+  }
+
+  const httpOpts: HttpRpcOptions = {
+    endpoint: options.endpoint,
+    headers: options.headers,
+    fetchImpl: options.fetchImpl,
+  };
+  return createHttpRpc(httpOpts);
+}

package/webui/src/api/schema.ts

@@ -0,0 +1,12 @@
+export type JSONPrimitive = string | number | boolean | null;
+export type JSONValue = JSONPrimitive | JSONValue[] | { [key: string]: JSONValue };
+
+export type SchemaKind = string;
+
+export interface SchemaDescription {
+  kind: SchemaKind;
+  description?: string;
+  nullable?: boolean;
+  constraints?: Record<string, unknown>;
+  children?: Record<string, unknown>;
+}

package/webui/src/api/types.ts

@@ -0,0 +1,16 @@
+export interface RPCErrorPayload {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+export interface RpcResponse<T = unknown> {
+  jsonrpc: '2.0';
+  id: number | string | null;
+  result?: T;
+  error?: RPCErrorPayload;
+}
+
+export interface Signature {
+  [index: number]: string | string[];
+}