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.ts
2import { defineMethod, PublicError } from "heliumts/server";
3import OpenAI from "openai";
4
5export const streamAssistant = defineMethod(async function* (
6 { prompt }: { prompt: string }, ctx
7) {
8 if (typeof prompt !== "string" || !prompt.trim()) {
9 throw new PublicError("Enter a prompt.");
10 }
11
12 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 );
21
22 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.tsx
2import { useState } from "react";
3import { useStreaming } from "heliumts/client";
4import { streamAssistant } from "../rpc.generated";
5
6export default function Assistant() {
7 const [prompt, setPrompt] = useState("");
8 const { text, error, isStreaming, start, cancel, reset } =
9 useStreaming(streamAssistant);
10
11 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 Cancel
24 </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.