Note:

HeliumTS is under pre-beta and active development. Expect bugs and breaking changes. If you find any issues, please report them in our GitHub

A stable release is planned for early December 2025.

Data Fetching

HeliumTS provides the useFetch hook for data fetching. It communicates with the server over WebSocket RPC, providing real-time, type-safe data operations.

useFetch

The useFetch hook automatically fetches data from a server method and caches the result. It's designed for reading/querying data.

Basic Usage

1import { useFetch } from "heliumts/client";
2import { getTasks } from "heliumts/server";
3
4function TaskList() {
5    const { data, isLoading, error } = useFetch(getTasks, { status: "open" });
6
7    if (isLoading) return <div>Loading...</div>;
8    if (error) return <div>Error: {error}</div>;
9
10    return (
11        <ul>
12            {data?.map((task) => (
13                <li key={task.id}>{task.name}</li>
14            ))}
15        </ul>
16    );
17}

Return Values

Property	Type	Description
`data`	`TResult \| undefined`	The fetched data (typed based on server method return type)
`isLoading`	`boolean`	Whether a fetch is in progress
`error`	`string \| null`	Error message if the fetch failed
`stats`	`RpcStats \| null`	RPC statistics (timing, etc.)
`refetch`	`(showLoader?: boolean) => Promise<TResult \| undefined>`	Function to manually trigger a refetch

Options

The useFetch hook accepts an optional third parameter for controlling caching and refetch behavior:

1const { data, isLoading } = useFetch(method, args, {
2    ttl: 30000,
3    refetchOnWindowFocus: true,
4    showLoaderOnRefocus: false,
5    enabled: true,
6});

Option	Type	Default	Description
`ttl`	`number`	`300000` (5 min)	Time-to-live for cached data in milliseconds. After TTL expires, data is automatically refetched.
`refetchOnWindowFocus`	`boolean`	`true`	Automatically refetch when the browser tab becomes visible or window regains focus.
`showLoaderOnRefocus`	`boolean`	`false`	Whether to show loading state during focus-triggered refetches. When `false`, data updates silently in the background without showing a loader.
`enabled`	`boolean`	`true`	Set to `false` to disable automatic fetching. Useful for conditional fetching when a required value isn't available yet.