@atcute/xrpc-server

a small web framework for handling XRPC operations.

quick start

this framework relies on schemas generated by @atcute/lex-cli, you'd need to follow its quick start guide on how to set it up.

for this example, we'll define a very simple query operation, one that returns a message greeting the name that's provided to it:

// file: lexicons/com/example/greet.json
{
    "lexicon": 1,
    "id": "com.example.greet",
    "defs": {
        "main": {
            "type": "query",
            "parameters": {
                "type": "params",
                "required": ["name"],
                "properties": {
                    "name": {
                        "type": "string"
                    }
                }
            },
            "output": {
                "encoding": "application/json",
                "schema": {
                    "type": "object",
                    "required": ["message"],
                    "properties": {
                        "message": {
                            "type": "string"
                        }
                    }
                }
            }
        }
    }
}

now we can build a server using the TypeScript schemas:

// file: src/index.js
import { XRPCRouter, json } from '@atcute/xrpc-server';
import { cors } from '@atucte/xrpc-server/middlewares/cors';

import { ComExampleGreet } from './lexicons/index.js';

const router = new XRPCRouter({ middlewares: [cors()] });

router.add(ComExampleGreet.mainSchema, {
    async handler({ params: { name } }) {
        return json({ message: `hello ${name}!` });
    },
});

export default router;

on Deno, Bun or Cloudflare Workers, you can export the router directly and expect it to work out of the box.

but for Node.js, you'll need the @hono/node-server adapter as the router works with standard Web Request/Response:

// file: src/index.js
import { XRPCRouter } from '@atcute/xrpc-server';
import { serve } from '@hono/node-server';

const router = new XRPCRouter();

// ... handler code ...

serve(
    {
        fetch: router.fetch,
        port: 3000,
    },
    (info) => {
        console.log(`listening on port ${info.port}`);
    },
);

internal calls

you can make typed calls to your own endpoints using @atcute/client:

import { Client, ok } from '@atcute/client';

const client = new Client({
    handler(pathname, init) {
        return router.fetch(new Request(new URL(pathname, 'http://localhost'), init));
    },
});

const data = await ok(
    client.get('com.example.greet', {
        params: { name: 'world' },
    }),
);

console.log(data.message); // fully typed!