zod-json-rpc

zod-json-rpc lets you rapidly build typesafe JSON-RPC servers and clients in TypeScript. Not only that, it is self-describing via its advanced introspection API, which can output JSON Schema or source code in multiple languages.

Why JSON-RPC?

It's super simple to use, easy to understand, and client libraries are widely available. When combined with a strong type system like TypeScript or JSON Schema it's a very nice way to build web apps.

Getting started

npm install zod-json-rpc

Creating a server

The following creates a server with one method named "hello" with introspection enabled.

// methods.ts

import { z } from "zod";
// You can import directly from zod-json-rpc/lib/server to avoid importing client-side
// dependencies
import { withIntrospection, method } from "zod-json-rpc";

export default withIntrospection({
  hello: method()
    .arg({ name: z.string() })
    .returns({ message: z.string() })
    .impl(({ name }) => {
      return { message: `hello, ${name}!` };
    }),
});

You can serve your app via the API:

import { createZodJsonRpcServer } from "zod-json-rpc";
import methods from "./methods";

const expressApp = createZodJsonRpcServer(methods);
expressApp.listen(8000);

Or just use the CLI:

npx zod-json-rpc --transpile --module ./methods

You can remove the --transpile flag if you are precompiling your TypeScript ahead of time and aren't importing a .ts file directly.

Calling the API via curl

$ curl -XPOST -H'Content-type: application/json' http://localhost:2288/rpc -d'{"id": "1", "jsonrpc":"2.0", "method": "hello", "params": {"name": "Pete"}}'

{"jsonrpc":"2.0","id":"1","result":{"message":"hello, Pete!"}}

Calling the API via jsonrpc2.0-cli

$ npx jsonrpc2.0-cli --url http://localhost:2288/rpc --method hello --arg '{name: "pete"}' --pretty
{
  "message": "hello, pete!"
}

Calling the API via the typesafe TypeScript client

import type methods from "./methods";
import { createZodJsonRpcClient } from "zod-json-rpc/lib/client";

const request = createZodJsonRpcClient<typeof methods>(
  `http://localhost:2288/rpc`
);
const response = await request("hello", { name: "pete" });
console.log(response.message);

Built-in JSON Schema introspection

$ curl http://localhost:2288/rpc/schema

{    "$schema": "http://json-schema.org/draft-06/schema#",
    "definitions": {
        "HelloArg": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "name": {
                    "type": "string"
                }
            },
            "required": [
                "name"
            ],
            "title": "HelloArg"
        },
        "HelloRet": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "message": {
                    "type": "string"
                }
            },
            "required": [
                "message"
            ],
            "title": "HelloRet"
        },
        "ServerGetSchemaArg": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "lang": {
                    "type": "string"
                },
                "pattern": {
                    "type": "string"
                }
            },
            "required": [],
            "title": "ServerGetSchemaArg"
        },
        "ServerGetSchemaRet": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "source": {
                    "type": "string"
                }
            },
            "required": [
                "source"
            ],
            "title": "ServerGetSchemaRet"
        }
    }
}

This data is also available via JSON-RPC by calling the server.getSchema method. You can filter which methods are returned by passing a glob pattern:

$ curl http://localhost:2288/rpc/schema?pattern=hello
{
    "$schema": "http://json-schema.org/draft-06/schema#",
    "definitions": {
        "HelloArg": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "name": {
                    "type": "string"
                }
            },
            "required": [
                "name"
            ],
            "title": "HelloArg"
        },
        "HelloRet": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "message": {
                    "type": "string"
                }
            },
            "required": [
                "message"
            ],
            "title": "HelloRet"
        }
    }
}

You can also pass a lang parameter to generate types in your favorite programming language:

$ curl 'http://localhost:2288/rpc/schema?pattern=hello&lang=rust'
// Example code that deserializes and serializes the model.
// extern crate serde;
// #[macro_use]
// extern crate serde_derive;
// extern crate serde_json;
//
// use generated_module::[object Object];
//
// fn main() {
//     let json = r#"{"answer": 42}"#;
//     let model: [object Object] = serde_json::from_str(&json).unwrap();
// }

extern crate serde_derive;

#[derive(Serialize, Deserialize)]
pub struct HelloArg {
    #[serde(rename = "name")]
    name: String,
}

#[derive(Serialize, Deserialize)]
pub struct HelloRet {
    #[serde(rename = "message")]
    message: String,
}

Running a server in a unit test

await withTestServer(createZodJsonRpcServer(methods), async (port) => {
    const request = createZodJsonRpcClient<typeof methods>(
      `http://localhost:${port}/rpc`
    );
    const response = await request("hello", { name: "pete" });
    expect(response.message).toBe("hello, pete!");
});

Future work

• Ideally, this should be split into separate packages for the client and server to minimize the number of dependencies that need to be installed.
• Support multiple lazy loaded namespaces / apps in a single server.
• The server CLI should integrate with ts-node-dev for automatic reloading