@danscan/zod-jsonrpc
v2.1.0
Published
Create JSON-RPC 2.0-compliant clients and servers that use Zod to validate requests and responses.
Downloads
594
Maintainers
Readme
@danscan/zod-jsonrpc
Create JSON-RPC 2.0-compliant clients and servers that use Zod to validate requests and responses.
Just define your methods with Zod schemas and handlers, and zod-jsonrpc will handle the rest.
Features
- JSON-RPC 2.0-compliant
- Transport-agnostic (supports HTTP, WebSockets, and more)
- Automatically handles batch requests, notification requests, and errors
- Rich documentation comments referencing the JSON-RPC 2.0 specification
- Exports Zod schemas and types for JSON-RPC requests, responses, errors and notifications
- Automatic type safety for requests and responses
- No dependencies; just one peer dependency:
zod
Installation
bun add @danscan/zod-jsonrpc
yarn add @danscan/zod-jsonrpc
npm add @danscan/zod-jsonrpc
Usage
Creating a Server
import { createServer, method, JSONRPC2Error } from '@danscan/zod-jsonrpc';
import { z } from 'zod';
const server = createServer({
greet: method({
paramsSchema: z.object({ name: z.string() }),
resultSchema: z.string(),
}, ({ name }) => `Hello, ${name}!`),
mustBeOdd: method({
paramsSchema: z.object({ number: z.number() }),
resultSchema: z.boolean(),
}, ({ number }) => {
const isOdd = number % 2 === 1;
// Just throw a JSONRPC2Error to return an error response
if (!isOdd) {
throw new JSONRPC2Error.InvalidParams({
message: 'Number must be odd',
data: { number },
});
}
return true;
}),
});
// Handles single requests
const result = await server.request({
id: 1,
method: 'greet',
params: { name: 'danscan' },
jsonrpc: '2.0',
});
/*
{
id: 1,
result: 'Hello, danscan!',
jsonrpc: '2.0',
}
*/
// Handles batch requests
const result = await server.request([
{ id: 1, method: 'greet', params: { name: 'danscan' }, jsonrpc: '2.0' },
{ id: 2, method: 'greet', params: { name: 'user' }, jsonrpc: '2.0' },
{ id: 3, method: 'mustBeOdd', params: { number: 4 }, jsonrpc: '2.0' },
]);
/*
[
{ id: 1, result: 'Hello, danscan!', jsonrpc: '2.0' },
{ id: 2, result: 'Hello, user!', jsonrpc: '2.0' },
// Throwing a JSON-RPC 2.0 error returns a correct JSON-RPC 2.0 error response
{ id: 3, error: { code: -32602, message: 'Invalid params: Number must be odd', data: { number: 4 } }, jsonrpc: '2.0' },
]
*/
Usage with an HTTP Server
const jsonRpcServer = createServer({ /* methods */ });
// Simple Bun HTTP server
Bun.serve({
fetch: async (req) => {
const jsonRpcRequest = await req.json();
const jsonRpcResponse = await jsonRpcServer.request(jsonRpcRequest);
return Response.json(jsonRpcResponse);
}
});
Creating a Client
import { createClient } from '@danscan/zod-jsonrpc';
import { z } from 'zod';
// Define a function that sends a JSON-RPC request to the server
const sendRequest = async (request: JSONRPCRequest) => {
const response = await fetch('/jsonrpc', {
method: 'POST',
body: JSON.stringify(request),
});
return response.json();
};
// Create the client with the methods you want to call, and pass in the request function
const client = createClient({
greet: method({
paramsSchema: z.object({ name: z.string() }),
resultSchema: z.string(),
}),
}, sendRequest);
// Send a single request
const result = await client.greet({ name: 'danscan' });
// 'Hello, danscan!'
// Send a batch request, setting a convenient key for each request so you can easily match them up in the response
const result = await client.batch((ctx) => ({
dan: ctx.greet({ name: 'Dan' }),
drea: ctx.greet({ name: 'Drea' }),
}));
/*
{
dan: { ok: true, value: 'Hello, Dan!' },
drea: { ok: true, value: 'Hello, Drea!' },
}
*/
If you already have a server defined, you can create a client from it using the server.createClient
method.
const client = server.createClient(async (request) => {
// TODO: send the request to the server and return the result
});