feat(json-rpc): add defineJsonRpc and improve types

Author: sandros94

src/index.ts

@@ -204,10 +204,9 @@ export type {
   JsonRpcRequest,
   JsonRpcResponse,
   JsonRpcError,
-  JsonRpcMethodHandler,
-  JsonRpcMethodMap,
+  JsonRpcMethod,
 } from "./utils/json-rpc.ts";
-export { defineJsonRpcHandler } from "./utils/json-rpc.ts";
+export { defineJsonRpcHandler, defineJsonRpc } from "./utils/json-rpc.ts";
 
 // ---- Deprecated ----
 

src/utils/json-rpc.ts

@@ -51,15 +51,15 @@ export type JsonRpcResponse<O = unknown> =
  * A function that handles a JSON-RPC method call.
  * It receives the parameters from the request and the original H3Event.
  */
-export type JsonRpcMethodHandler<
+export type JsonRpcMethod<
   O = unknown,
   I extends JsonRpcParams | undefined = JsonRpcParams | undefined,
 > = (data: JsonRpcRequest<I>, event: H3Event) => O | Promise<O>;
 
 /**
- * A map of method names to their corresponding handler functions.
+ * A map of method names to their corresponding functions.
  */
-export type JsonRpcMethodMap = Record<string, JsonRpcMethodHandler>;
+type JsonRpcMethodMap = Record<string, JsonRpcMethod>;
 
 // Official JSON-RPC 2.0 error codes.
 /**
@@ -114,6 +114,24 @@ const SERVER_ERROR_RATE_LIMITED = -32_029;
  */
 const SERVER_ERROR = -32_000;
 
+/**
+ * Define a JSON-RPC method.
+ *
+ * @param method The method implementation function.
+ * @returns The method function, unmodified.
+ *
+ * @example
+ * const add = defineJsonRpc(({ params }) => {
+ *   return params.a + params.b;
+ * });
+ */
+export function defineJsonRpc<
+  O = unknown,
+  I extends JsonRpcParams | undefined = JsonRpcParams | undefined,
+>(method: JsonRpcMethod<O, I>): JsonRpcMethod<O, I> {
+  return method;
+}
+
 /**
  * Creates an H3 event handler that implements the JSON-RPC 2.0 specification.
  *
@@ -140,7 +158,7 @@ export function defineJsonRpcHandler<RequestT extends EventHandlerRequest = Even
    * This ensures that method names like "__proto__", "constructor", "toString",
    * "hasOwnProperty", etc. cannot resolve to inherited Object.prototype properties.
    */
-  const methodMap: Record<string, JsonRpcMethodHandler> = Object.create(null);
+  const methodMap: Record<string, JsonRpcMethod> = Object.create(null);
   for (const key of Object.keys(methods)) {
     methodMap[key] = methods[key];
   }

test/json-rpc.test.ts

@@ -1,25 +1,28 @@
-import { defineJsonRpcHandler, HTTPError } from "../src/index.ts";
+import { defineJsonRpcHandler, defineJsonRpc, HTTPError } from "../src/index.ts";
 import { describeMatrix } from "./_setup.ts";
 
 describeMatrix("json-rpc", (t, { describe, it, expect }) => {
+  const echo = defineJsonRpc(({ params }, event) => {
+    const message = Array.isArray(params) ? params[0] : params?.message;
+    return `Received ${message} on path ${event.url.pathname}`;
+  });
+  const sum = defineJsonRpc(({ params }) => {
+    if (
+      !params ||
+      typeof params !== "object" ||
+      !("a" in params) ||
+      typeof params.a !== "number" ||
+      !("b" in params) ||
+      typeof params.b !== "number"
+    ) {
+      throw new Error("Invalid parameters for sum");
+    }
+    return params.a + params.b;
+  });
+
   const eventHandler = defineJsonRpcHandler({
-    echo: ({ params }, event) => {
-      const message = Array.isArray(params) ? params[0] : params?.message;
-      return `Received ${message} on path ${event.url.pathname}`;
-    },
-    sum: ({ params }) => {
-      if (
-        !params ||
-        typeof params !== "object" ||
-        !("a" in params) ||
-        typeof params.a !== "number" ||
-        !("b" in params) ||
-        typeof params.b !== "number"
-      ) {
-        throw new Error("Invalid parameters for sum");
-      }
-      return params.a + params.b;
-    },
+    echo,
+    sum,
     error: () => {
       throw new Error("Handler error");
     },

test/unit/package.test.ts

@@ -31,6 +31,7 @@ describe("h3 package", () => {
         "defaultContentType",
         "defineEventHandler",
         "defineHandler",
+        "defineJsonRpc",
         "defineJsonRpcHandler",
         "defineLazyEventHandler",
         "defineMiddleware",