RPC Docs.
Prim+RPC Tools
Prim+RPC includes additional (and optional) tooling that can make working with Prim+RPC even easier.
Table of Contents
Prevent Import Utility
Since Prim+RPC allows you to import type definitions from your server, there's the possibility (although unlikely) that some developer makes the mistake of importing a function from the server. Generally these errors can be caught fairly quickly because many server-side tools will throw errors on the client however when you're using isomorphic/universal tools that work on both server and client this may be harder to catch.
The Prevent Import Utility is very simple plugin for the build tool of your choice (using unplugin) that just prevents imports of a specified directory or file, like those from the server. You can use it like so (we'll use Vite as an example but you could use Webpack or others):
import path from "node:path"import { defineConfig } from "vite"import preventImport from "@doseofted/prim-rpc-tooling/build"const preventServerImport = preventImport.vite({ name: path.join(__dirname, "server"),})export default defineConfig({ plugins: [preventServerImport],})
In this example we assume that server-related code is located in the same directory as the Vite config (./server).
Now if we try to import a function directly from the server (the code itself, not the types as used with Prim+RPC) that
function call will fail because the plugin replaces all server imports with an empty export (export {}).
Documentation Generator
The Documentation Generator is a tool that reads TypeDoc documentation and creates a simpler RPC-specific documentation for your code.
This RPC documentation process is intended become more streamlined in the future.
First, it's suggested that you document your code using TypeDoc's format. Next, you can generate TypeDoc with its CLI
(this is not Prim+RPC related). We'll pretend your code lives at src/index.ts.
npx typedoc src/index.ts --json dist/docs.json
Now we can use this generated dist/docs.json file to generate RPC-specific documentation.
Below is a simple script that creates the documentation.
import preventImport from "@doseofted/prim-rpc-tooling/docs"import typeDoc from "./dist/docs.json"const rpcDocs = createDocsForModule(typeDoc)
In the future, basic JavaScript types will be turned into JSON Schema for typed usage outside of TypeScript. It's not planned to support all TypeScript types in RPC documentation since it doesn't make sense to use them outside of TypeScript but basic JSON Schema support could be useful for using Prim+RPC outside of JavaScript environments.
The resulting documentation is a simpler version of the TypeDoc that relates to RPC. This output could be used for a documentation website or fed to another tool like HTTPsnippet to generate requests for other clients outside of JavaScript.
Command Line Tool
Documentation in Progress
