A typesafe RPC framework with compile-time error checking.
🤔 Why is this useful?
You can think of magic-rpc as a way to write APIs quickly and [typed]
safely. It avoids the clunkiness of REST and the boilerplate/complexity of
GraphQL.
👩🏼🏫 I want more boring details!
Motivation:
It helps to have correctness guarantees from your compiler when writing your programs. This is applicable when writing client-server applications, but requires some tooling to achieve.
To this end, we can use an RPC client that is aware of the return type of the server response. We will encode the data type and error type into the return type of an RPC method. The client will infer the type of the RPC method enabling the compiler to know about data and error types. The compiler will enforce appropriate error handling on the client: providing us strongly-typed client-server code.
Inspiration:
This project is loosely based on JSON RPC.
Our error propagation is inspired by
Rust's Result type, which returns a
tuple of Result<T, E> from a function. Here T is your data type and E is
your error type.
npm i magic-rpc
⚠️ IMPORTANT: You must enable `strictNullChecks` in your `tsconfig.json`.
Typescript currently has a
bug, making type
narrowing only work when strictNullChecks is turned on.
// tsconfig.json
{
// ...
"compilerOptions": {
// ...
"strictNullChecks": true
}
}Invoke methods in your client code with type guarantees but without strange
import paths.
No code generation is required, speeding up your iteration! Minimal boilerplate and intuitive syntax. Looks just like method invocations. Tiny library footprint.
See stack traces from server code in development
Can be gradually deployed into your project. Designed to be agnostic to front-end framework choice.
Invoking an RPC method from your client looks like calling a function defined on your server.
const quotient = await math.divide(10, 2);Create a client that is aware of the return types of your methods.
// client.ts
import { createClient } from 'magic-rpc';
import fetch from 'cross-fetch';
import type { Services } from './server';
export async function main() {
// Create an RPC Client
const { math } = createClient<Services>(`http://localhost:8080/rpc`, fetch);
// Invoke method on RPC client (crosses network boundary)
const response = await math.divide(10, 2); // TS is aware of types
console.log(response);
}Finally, this is what configuring your server looks like.
// server.ts
import { createRpcHandler, Request } from 'magic-rpc';
import express from 'express';
// Define some services
const services = {
math: {
divide(_: Request, x: number, y: number) {
return x / y;
},
},
};
// Client will import these for the RpcClient
export type Services = typeof services;
// Configure server
export const app = express();
app.use(express.json());
app.post('/rpc', createRpcHandler(services));What does a `curl` command look like?
$ curl localhost:8080/rpc \
--header "Content-Type: application/json" \
--request POST \
--data '{
"service": "math",
"method": "divide",
"params": [99, 3]
}'
{"result":{"ok":true,"err":false,"val":33}}