HeliumTS is under active development and may have bugs or breaking changes. Report issues on GitHub.
OpenAI Streaming
Stream OpenAI responses through an async-generator defineMethod and render the text with useStreaming. The hook manages the HTTP request, incremental output, cancellation, and component state.
Try the deterministic streaming demo without an API key or provider account.
Install and configure OpenAI
%npm install openai
Set OPENAI_API_KEY in your server environment. Optionally set OPENAI_MODEL to a model available to your project; the example defaults to gpt-6-astra. Keep these variables server-only.
%# .env — server only%OPENAI_API_KEY=your-openai-api-key%OPENAI_MODEL=gpt-6-astra
Define a streaming server method
Keep the implementation in src/server/assistant.ts. Creating the SDK client inside the handler lets method discovery and builds run without an API key. maxRetries: 0 disables SDK retries, so starting another generation is an explicit application action.
1// src/server/assistant.ts2import { defineMethod, PublicError } from "heliumts/server";3import OpenAI from "openai";45export const streamAssistant = defineMethod(async function* (6 { prompt }: { prompt: string }, ctx7) {8 if (typeof prompt !== "string" || !prompt.trim()) {9 throw new PublicError("Enter a prompt.");10 }1112 const openai = new OpenAI({ maxRetries: 0 });13 const stream = await openai.responses.create(14 {15 model: process.env.OPENAI_MODEL || "gpt-6-astra",16 input: prompt.trim(),17 stream: true,18 },19 { signal: ctx.signal },20 );2122 let completed = false;23 try {24 for await (const event of stream) {25 if (event.type === "response.output_text.delta" ||26 event.type === "response.refusal.delta") {27 yield event.delta;28 } else if (event.type === "response.completed") {29 completed = true;30 } else if (event.type === "error" ||31 event.type === "response.failed" ||32 event.type === "response.incomplete") {33 throw new PublicError("The response could not be completed. Try again.");34 }35 }36 if (!completed && !ctx.signal.aborted) {37 throw new PublicError("The response ended before completion. Try again.");38 }39 } finally {40 stream.controller.abort();41 }42});
The generator yields text deltas, including refusal text, and reports failed, incomplete, or prematurely ended responses as safe public errors. It closes the upstream stream in finally. The same pattern works with any provider that exposes an async iterable.
Render the stream with useStreaming
Import the method reference from src/rpc.generated.ts using HeliumTS 0.11.0. The OpenAI SDK and API key stay on the server. The hook infers the prompt argument and string chunk type from the method.
1// src/pages/assistant.tsx2import { useState } from "react";3import { useStreaming } from "heliumts/client";4import { streamAssistant } from "../rpc.generated";56export default function Assistant() {7 const [prompt, setPrompt] = useState("");8 const { text, error, isStreaming, start, cancel, reset } =9 useStreaming(streamAssistant);1011 return (12 <form onSubmit={(event) => {13 event.preventDefault();14 void start({ prompt });15 }}>16 <label htmlFor="assistant-prompt">Prompt</label>17 <input id="assistant-prompt" value={prompt}18 onChange={(event) => setPrompt(event.target.value)} />19 <button type="submit" disabled={!prompt.trim()}>20 {isStreaming ? "Restart" : "Send"}21 </button>22 <button type="button" disabled={!isStreaming} onClick={cancel}>23 Cancel24 </button>25 <button type="button" onClick={reset}>Reset</button>26 <output aria-live="polite" style={{ whiteSpace: "pre-wrap" }}>{text}</output>27 {error && <p role="alert">{error}</p>}28 </form>29 );30}
Cancellation and partial failures
Cancel, restart, and unmount abort the active request. Passing ctx.signal to the OpenAI SDK lets that cancellation stop upstream work. Received text remains visible after cancellation or failure; render the hook's error separately. Restart clears the old reply, and reset cancels and clears all output.
Apply application authentication and quotas in method middleware before exposing a provider-backed method. Use a positive timeoutMs to change the idle limit, and configure hosting proxies to flush chunks as they arrive.
See the useStreaming reference for fields, callbacks, and lifecycle behavior, and the official OpenAI streaming documentation for provider event types.