@wtheff/rpc

A TypeScript library for generating type-safe Remote Procedure Calls (RPCs) with built-in schema validation using Suretype or TypeBox.

Features

• Create type-safe query and mutation RPCs
• Built-in schema validation using Suretype/TypeBox
• Runtime validation of arguments
• Generated JSON-Schema for RPCs

Installation

npm install @wtheff/rpc

Usage

Basic Example

import { RPCGenerator } from '@wtheff/rpc';
import { v } from 'suretype';

const { RegisterRPC } = RPCGenerator();

// Register a query RPC
const { getUserInfo } = RegisterRPC.query(
  'getUserInfo',
  {
    schema: {
      args: v.object({ userId: v.string().required() }),
      data: v.object({
        name: v.string().required(),
        email: v.string()
      })
    }
  },
  async (ctx, args) => {
    // Handle the RPC call
    return {
      name: 'John Doe',
      email: '[email protected]'
    };
  }
);

// Call the RPC
const userInfo = await getUserInfo({ userId: '123' });

With Custom Context

interface CustomContext {
  authToken: string;
}

const { RegisterRPC } = RPCGenerator<CustomContext>({
  // RPC handler registration callback
  onRegisterRPC: ({ handler, name }) => {
    httpRouter.post(`/rpc/${name}`, async (req) => {
      return handler({ authToken: req.headers.authorization }, req.body);
    });
  }
});

const { CheckIsAuthenticated } = RegisterRPC.query(
  'CheckIsAuthenticated',
  {
    context: async (ctx) => {
      if (validateAuthToken(ctx.authToken)) {
        const user = await getUserFromToken(ctx.authToken);

        return { user }
      }

      throw new RPCError('Invalid auth token');
    },

    schema: {
      data: v.string(),
    }
  },
  async (ctx, args) => {
    // Access context in handler with type-safety
    console.log(ctx.user);
    return 'User authentication is valid';
  }
);

// Call the RPC
CheckIsAuthenticated({authToken:'valid-token'}, {}); // Returns 'User authentication is valid'
CheckIsAuthenticated({authToken:'no-token'}, {}); // Throws 'RPCContextError: Invalid auth token'

Retrieving Registered RPCs

const { RegisterRPC, getRegisteredRPCs } = RPCGenerator();

// Later in your code
const registeredProcedures = getRegisteredRPCs();
const userInfoProcedure = registeredProcedures.get('getUserInfo');

Generated JSON-Schema

const { RegisterRPC, getRegisteredRPCs } = RPCGenerator();

const { getUserInfo, getUserInfoSchema } = RegisterRPC.query(
  'getUserInfo',
  {
    schema: {
      args: v.object({ userId: v.string().required() }),
      data: v.object({
        name: v.string().required(),
        email: v.string()
      })
    }
  },
  async (ctx, args) => {
    // Handle the RPC call
    return {
      name: 'John Doe',
      email: ''
    };
    }
);

console.log(getUserInfoSchema); // { args: JSON-schema; data: JSON-schema }
// or
console.log(getRegisteredRPCs().get('getUserInfo').config.schema); // { args: JSON-schema; data: JSON-schema }

API Reference

RPCGenerator(options?)

Creates a new RPC generator instance.

Options

• onRegisterRPC: Callback function called when a new RPC is registered
  • handler: The RPC handler function
  • config: Configuration object containing schema and local RPC context handler
  • name: Name of the RPC procedure

RegisterRPC

Object containing methods to register new RPCs.

Methods

• query(name, options, handler): Register a query RPC
• mutation(name, options, handler): Register a mutation RPC

Note: query and mutation methods are identical, except for the type of RPC registered. These RPC "type"'s are used in client implementation to differentiate between query and mutation RPCs. This helps clients support caching calls appropriately if using a cache layer. For example, you can cache
query RPCs but should not cache mutation RPCs.

Options

• schema:
  • args: Suretype/TypeBox validation schema for arguments
  • data: Suretype/TypeBox validation schema for return data
• context: Function that returns additional context local to the RPC call

Error Handling

The library includes built-in validation error handling through the RPCValidationError class.

If the RPC config.args schema exists, the args are validated before the RPC handler is called. If the validation fails, an RPCValidationError is thrown with the validation error message.

Acknowledgements

• @sinclair/typebox - For providing a great library for generating JSON schema with TypeScript.
• @suretype/suretype - For providing a great library for runtime type validation.
• @typeschema - For providing inspiration for the RPC schema resolver between Suretype or TypeBox.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.