@atom-forge/rpc · Communication
Call the server. Keep the types.
Client and server already agree on your domain. Let them share an API type, too. AtomForge RPC models remote work as asynchronous function calls, with a place for validation, authentication and file uploads.
What it is
Remote functions with explicit intent.
rpc.query(...) describes reads; rpc.command(...) describes operations that change state, send messages or upload files. The distinction helps communicate intent, but your implementation must still preserve read-only query behaviour.
The client consumes a shared API type rather than generated client code. The transport builds on Web Request and Response APIs, while payload schemas and middleware handle concerns that compile-time types cannot enforce.
Why choose RPC?
One API contract
Share the server API type with the TypeScript client so parameter and return-type changes are visible during development. Import the type, not the server implementation.
Files belong in the payload
The source design supports FormData and File values, making uploads part of the API rather than a separate hand-written transport.
Validate at the boundary
Zod schemas can validate incoming payloads before business logic runs. Types alone do not establish that a request is trustworthy.
Middleware on both sides
Server middleware can build authentication context; client middleware can attach credentials and centralize response handling. Authorization remains your application’s responsibility.
How it works
-
Describe the server API
Group queries and commands around your domain and define schemas where untrusted input enters.
-
Connect the HTTP boundary
Integrate the handler with your framework’s Request/Response flow and add the authentication and logging middleware you need.
-
Create the typed client
Import the API type and construct the RPC client. Calls are asynchronous network operations: handle errors, latency and mutation retries explicitly.
An honest fit check
Trade-offs, not fine print
Best for a shared TypeScript ecosystem
A public API serving Python, Java or independent mobile clients may be better served by REST and an explicit language-neutral contract. The source does not promise OpenAPI or Swagger generation.
Protocol-aware debugging
Requests still use HTTP, but their payloads follow the RPC protocol. Ad hoc calls from Postman can be less convenient than a conventional REST endpoint.
Not a progressively enhanced form
Browser RPC calls require JavaScript. Use native framework form actions when no-JavaScript submission is a requirement.
In practice
A command that accepts a file
Adapted from the official RPC documentation. Storage, authorization and endpoint registration are omitted; a File schema alone is not a complete upload security policy.
import { rpc } from '@atom-forge/rpc';
import { z } from 'zod';
export const api = {
uploadAvatar: rpc.zod({ avatar: z.instanceof(File) })
.command(async ({ avatar }) => ({ name: avatar.name })),
};
export type AppApi = typeof api;Share only the type with the client
An illustrative client-side counterpart. The /api/rpc endpoint must be configured by your application, and avatar must come from a user-selected File.
import { createClient } from '@atom-forge/rpc';
import type { AppApi } from '../server/api';
const [client] = createClient<AppApi>('/api/rpc');
export async function upload(avatar: File) {
return client.uploadAvatar.$command({ avatar });
}