@nym.sh/jrpc 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# @nym.sh/jrpc
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.14. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+import type { JrpcChannel } from "./transport";
+type JsonRpcHandler = (...params: any[]) => any;
+type JsonRpcMethod<Schema> = Extract<keyof Schema, string>;
+export declare class JsonRpcClient<Schema extends Record<keyof Schema, JsonRpcHandler>> {
+    private dispatcher;
+    constructor(channel: JrpcChannel);
+    call<M extends JsonRpcMethod<Schema>>(method: M, ...params: Parameters<Schema[M]>): Promise<Awaited<ReturnType<Schema[M]>>>;
+}
+export {};

package/dist/error.d.ts

@@ -0,0 +1,20 @@
+export declare const JsonRpcErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+    readonly ServerError: -32000;
+};
+export type JsonRpcErrorCode = (typeof JsonRpcErrorCode)[keyof typeof JsonRpcErrorCode];
+export interface JsonRpcErrorObject {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export declare class JsonRpcRemoteError extends Error {
+    code: number;
+    data?: unknown;
+    constructor(error: JsonRpcErrorObject);
+}
+export declare function toJsonRpcError(error: unknown): JsonRpcErrorObject;

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { JsonRpcErrorCode as JsonRpcErrorCodeValue } from "./error";
+export { JsonRpcClient } from "./client";
+export { JsonRpcRemoteError } from "./error";
+export { JsonRpcServer } from "./server";
+export declare const JsonRpcErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+    readonly ServerError: -32000;
+};
+export type JsonRpcErrorCode = JsonRpcErrorCodeValue;
+export type { JsonRpcErrorObject } from "./error";
+export type { JrpcChannel, JrpcMessage, JsonRpcErrorResponse, JsonRpcMessage, JsonRpcRequest, JsonRpcResponse, JsonRpcSuccessResponse, JsonRpcTransport, } from "./transport";
+export interface TestSchema {
+    sendMessage(content: string): void;
+    test(a: number, b: string): void;
+}

package/dist/index.js

@@ -0,0 +1,283 @@
+// error.ts
+var JsonRpcErrorCode = {
+  ParseError: -32700,
+  InvalidRequest: -32600,
+  MethodNotFound: -32601,
+  InvalidParams: -32602,
+  InternalError: -32603,
+  ServerError: -32000
+};
+
+class JsonRpcRemoteError extends Error {
+  code;
+  data;
+  constructor(error) {
+    super(error.message);
+    this.name = "JsonRpcRemoteError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+}
+function toJsonRpcError(error) {
+  if (error instanceof Error) {
+    return {
+      code: JsonRpcErrorCode.ServerError,
+      message: error.message
+    };
+  }
+  return {
+    code: JsonRpcErrorCode.ServerError,
+    message: String(error)
+  };
+}
+
+// transport.ts
+var dispatchers = new WeakMap;
+
+class JsonRpcDispatcher {
+  channel;
+  activeRequests = new Set;
+  fatalHandlerError;
+  hasFatalHandlerError = false;
+  unresolvedIds = new Set;
+  pending = new Map;
+  requestHandler;
+  running;
+  isClosed = false;
+  closeReason;
+  constructor(channel) {
+    this.channel = channel;
+  }
+  setRequestHandler(handler) {
+    if (this.requestHandler) {
+      throw new Error("JSON-RPC channel already has a request handler.");
+    }
+    this.requestHandler = handler;
+  }
+  send(msg) {
+    return this.channel.send(msg);
+  }
+  start() {
+    if (!this.running) {
+      this.running = this.listen();
+      this.running.catch(() => {
+        return;
+      });
+    }
+    return this.running;
+  }
+  async call(method, params) {
+    if (this.isClosed) {
+      throw this.closeReason;
+    }
+    const id = this.createId();
+    const response = new Promise((resolve, reject) => {
+      this.pending.set(id, {
+        resolve,
+        reject
+      });
+    });
+    this.start();
+    try {
+      await this.channel.send({
+        jsonrpc: "2.0",
+        id,
+        method,
+        params
+      });
+    } catch (error) {
+      this.pending.delete(id);
+      this.unresolvedIds.delete(id);
+      throw error;
+    }
+    return response;
+  }
+  createId() {
+    let id;
+    do {
+      id = randomJsonRpcId();
+    } while (this.unresolvedIds.has(id));
+    this.unresolvedIds.add(id);
+    return id;
+  }
+  async listen() {
+    let listenerError;
+    let hasListenerError = false;
+    try {
+      for await (const msg of this.channel) {
+        if (isJsonRpcRequest(msg)) {
+          this.handleRequestInBackground(msg);
+          continue;
+        }
+        if (isJsonRpcResponse(msg)) {
+          this.handleResponse(msg);
+        }
+      }
+    } catch (error) {
+      hasListenerError = true;
+      listenerError = error;
+      this.close(error);
+    } finally {
+      this.close(new Error("JSON-RPC channel closed."));
+      await this.waitForActiveRequests();
+    }
+    if (hasListenerError) {
+      throw listenerError;
+    }
+    if (this.hasFatalHandlerError) {
+      throw this.fatalHandlerError;
+    }
+  }
+  handleRequestInBackground(msg) {
+    const request = this.handleRequest(msg);
+    this.activeRequests.add(request);
+    request.catch((error) => {
+      this.hasFatalHandlerError = true;
+      this.fatalHandlerError = error;
+      this.close(error);
+      this.channel.return(undefined).catch(() => {
+        return;
+      });
+    }).finally(() => {
+      this.activeRequests.delete(request);
+    });
+  }
+  async waitForActiveRequests() {
+    while (this.activeRequests.size > 0) {
+      await Promise.allSettled(this.activeRequests);
+    }
+  }
+  handleResponse(msg) {
+    const pending = this.pending.get(msg.id);
+    if (!pending) {
+      return;
+    }
+    this.pending.delete(msg.id);
+    this.unresolvedIds.delete(msg.id);
+    if (isJsonRpcErrorResponse(msg)) {
+      pending.reject(new JsonRpcRemoteError(msg.error));
+      return;
+    }
+    pending.resolve(msg.result);
+  }
+  async handleRequest(msg) {
+    if (this.requestHandler) {
+      await this.requestHandler(msg);
+      return;
+    }
+    await this.channel.send({
+      jsonrpc: "2.0",
+      id: msg.id,
+      error: {
+        code: JsonRpcErrorCode.MethodNotFound,
+        message: `Method not found: ${msg.method}`
+      }
+    });
+  }
+  close(reason) {
+    if (this.isClosed) {
+      return;
+    }
+    this.isClosed = true;
+    this.closeReason = reason;
+    for (const pending of this.pending.values()) {
+      pending.reject(reason);
+    }
+    this.pending.clear();
+    this.unresolvedIds.clear();
+  }
+}
+function getDispatcher(channel) {
+  let dispatcher = dispatchers.get(channel);
+  if (!dispatcher) {
+    dispatcher = new JsonRpcDispatcher(channel);
+    dispatchers.set(channel, dispatcher);
+  }
+  return dispatcher;
+}
+function isJsonRpcRequest(msg) {
+  return Object.hasOwn(msg, "method");
+}
+function isJsonRpcResponse(msg) {
+  return Object.hasOwn(msg, "result") || Object.hasOwn(msg, "error");
+}
+function isJsonRpcErrorResponse(msg) {
+  return Object.hasOwn(msg, "error");
+}
+function randomJsonRpcId() {
+  const [id = 0] = crypto.getRandomValues(new Uint32Array(1));
+  return id;
+}
+
+// client.ts
+class JsonRpcClient {
+  dispatcher;
+  constructor(channel) {
+    this.dispatcher = getDispatcher(channel);
+  }
+  async call(method, ...params) {
+    return this.dispatcher.call(method, params);
+  }
+}
+// server.ts
+class JsonRpcServer {
+  handlers;
+  dispatcher;
+  constructor(handlers, channel) {
+    this.handlers = handlers;
+    this.dispatcher = getDispatcher(channel);
+    this.dispatcher.setRequestHandler((msg) => this.handle(msg));
+  }
+  start() {
+    return this.dispatcher.start();
+  }
+  async handle(msg) {
+    if (!Object.hasOwn(this.handlers, msg.method)) {
+      await this.dispatcher.send({
+        jsonrpc: "2.0",
+        id: msg.id,
+        error: {
+          code: JsonRpcErrorCode.MethodNotFound,
+          message: `Method not found: ${msg.method}`
+        }
+      });
+      return;
+    }
+    const handler = this.handlers[msg.method];
+    const params = msg.params ?? [];
+    if (!Array.isArray(params)) {
+      await this.dispatcher.send({
+        jsonrpc: "2.0",
+        id: msg.id,
+        error: {
+          code: JsonRpcErrorCode.InvalidParams,
+          message: "Params must be an array."
+        }
+      });
+      return;
+    }
+    try {
+      const result = await handler(...params);
+      await this.dispatcher.send({
+        jsonrpc: "2.0",
+        id: msg.id,
+        result: result ?? null
+      });
+    } catch (error) {
+      await this.dispatcher.send({
+        jsonrpc: "2.0",
+        id: msg.id,
+        error: toJsonRpcError(error)
+      });
+    }
+  }
+}
+
+// index.ts
+var JsonRpcErrorCode2 = JsonRpcErrorCode;
+export {
+  JsonRpcServer,
+  JsonRpcRemoteError,
+  JsonRpcErrorCode2 as JsonRpcErrorCode,
+  JsonRpcClient
+};

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import type { JrpcChannel } from "./transport";
+type JsonRpcHandler = (...params: any[]) => any;
+export declare class JsonRpcServer<Schema extends Record<keyof Schema, JsonRpcHandler>> {
+    private handlers;
+    private dispatcher;
+    constructor(handlers: Schema, channel: JrpcChannel);
+    start(): Promise<void>;
+    private handle;
+}
+export {};

package/dist/transport.d.ts

@@ -0,0 +1,31 @@
+import type { JsonRpcErrorObject } from "./error";
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: number;
+    method: string;
+    params?: unknown[];
+}
+export interface JsonRpcSuccessResponse {
+    jsonrpc: "2.0";
+    id: number;
+    result: unknown;
+}
+export interface JsonRpcErrorResponse {
+    jsonrpc: "2.0";
+    id: number;
+    error: JsonRpcErrorObject;
+}
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse;
+export type JrpcMessage = JsonRpcMessage;
+export interface JrpcChannel extends AsyncGenerator<JrpcMessage, void, unknown> {
+    send(msg: JsonRpcMessage): Promise<void>;
+}
+export type RequestHandler = (msg: JsonRpcRequest) => Promise<void>;
+export interface JsonRpcTransport {
+    call(method: string, params: unknown[]): Promise<unknown>;
+    send(msg: JsonRpcMessage): Promise<void>;
+    setRequestHandler(handler: RequestHandler): void;
+    start(): Promise<void>;
+}
+export declare function getDispatcher(channel: JrpcChannel): JsonRpcTransport;

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@nym.sh/jrpc",
+	"version": "0.1.0",
+	"description": "Typed JSON-RPC over async channels.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/kennethnym/jrpc"
+	},
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "rm -rf dist && bun build index.ts --outdir=dist --target=node --format=esm && tsc -p tsconfig.build.json",
+		"fmt": "oxfmt",
+		"fmt:check": "oxfmt --check",
+		"lint": "oxlint",
+		"lint:fix": "oxlint --fix",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"oxfmt": "^0.55.0",
+		"oxlint": "^1.70.0",
+		"typescript": "^6.0.3"
+	}
+}