HeliumTS is under active development and may have bugs or breaking changes. Report issues on GitHub.

RPC (Remote Procedure Calls)

Define server-side functions using defineMethod and call them from the client using useCall or useFetch.

The client examples use src/rpc.generated.ts from the 0.11.0 release. The dev server and production build generate it automatically. Run npx helium typegen to generate it on demand.

HTTP RPC

Helium handles HTTP requests, MessagePack serialization, batching, and typed responses. Use useFetch for cached reads, useCall for mutations, and callMethod for promises outside hooks. For incremental replies, define an async generator and use useStreaming.

Server

src/server/tasks.ts

1import { defineMethod } from "heliumts/server";
2
3function taskInput(value: unknown): { name: string } {
4 if (!value || typeof value !== "object" ||
5 !("name" in value) || typeof value.name !== "string") {
6 throw new Error("Expected a task name");
7 }
8 const name = value.name.trim();
9 if (!name || name.length > 120) throw new Error("Invalid name");
10 return { name };
11}
12
13export const getTasks = defineMethod(() => [
14 { id: 1, name: "Ship the app" },
15]);
16
17export const createTask = defineMethod(
18 async ({ name }: { name: string }) => {
19 // Enforce authorization and persist with your own database here.
20 return { id: 2, name };
21 },
22 { input: taskInput }
23);

The parser receives unknown network input, validates it and returns the handler arguments. TypeScript types alone do not validate requests. Keep authentication and ownership checks in the handler or middleware; parser errors are returned safely without exposing submitted values.

Client

src/pages/tasks.tsx

1import { useFetch, useCall } from "heliumts/client";
2import { getTasks, createTask } from "../rpc.generated";
3
4export default function TasksPage() {
5 const { data, isLoading, error, refetch } = useFetch(getTasks);
6 const save = useCall(createTask, { invalidate: [getTasks] });
7
8 async function addTask() {
9 const result = await save.submit({ name: "New Task" });
10 if (result.status === "success") console.log(result.data.id);
11 }
12
13 if (isLoading) return <p role="status">Loading...</p>;
14 if (error) return <p role="alert">{error}</p>;
15 return (
16 <div>
17 <button onClick={() => void refetch()}>Refresh</button>
18 <button onClick={() => void addTask()} disabled={save.isCalling}>
19 {save.isCalling ? "Adding..." : "Add Task"}
20 </button>
21 {save.error && <p role="alert">{save.error}</p>}
22 {data?.map(task => <div key={task.id}>{task.name}</div>)}
23 </div>
24 );
25}

Calling Without a Hook

Use callMethod in event handlers or client utilities when you want a promise without hook state. Arguments and results are inferred from the method reference. The response includes data and rate-limit stats.

1// src/components/loadTasks.ts
2import { callMethod } from "heliumts/client";
3import { getTasks } from "../rpc.generated";
4
5const { data, stats } = await callMethod(getTasks);
6// Arguments and data are inferred from getTasks. No hook state is updated.

Unlike useCall, this function does not update hook state or invalidate cached queries. Handle those updates yourself when needed.

Retries and Mutation Safety

Network failures and server errors are not automatically replayed. An expired request token may be refreshed after an authorization rejection before retrying. If you choose to retry a mutation yourself after a lost response, use an idempotency key or database constraint for operations such as payments and order creation. Streams are never replayed automatically.

Public errors in production

In production, server errors are redacted to a generic Server error message by default. If you want to expose a safe message to clients, throw aPublicError or an error-like object with { public: true } from your RPC method.

1import { defineMethod, PublicError } from "heliumts/server";
2
3export const createTask = defineMethod(async (args) => {
4 if (!args.name?.trim()) {
5 throw new PublicError("Task name is required");
6 // Or: throw { public: true, message: "Task name is required" };
7 }
8
9 return createTaskInDb(args);
10});