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";23function 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}1213export const getTasks = defineMethod(() => [14 { id: 1, name: "Ship the app" },15]);1617export 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";34export default function TasksPage() {5 const { data, isLoading, error, refetch } = useFetch(getTasks);6 const save = useCall(createTask, { invalidate: [getTasks] });78 async function addTask() {9 const result = await save.submit({ name: "New Task" });10 if (result.status === "success") console.log(result.data.id);11 }1213 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.ts2import { callMethod } from "heliumts/client";3import { getTasks } from "../rpc.generated";45const { 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";23export 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 }89 return createTaskInDb(args);10});