Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

use-generation.ts

309 lines11.2 KB

1import { GenerationClient } from '@tanstack/ai-client'
2import { createGenerationDevtoolsBridge } from '@tanstack/ai-client/devtools'
3import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
4import type { StreamChunk } from '@tanstack/ai'
5import type {
6 AIDevtoolsDisplayOptions,
7 ConnectConnectionAdapter,
8 GenerationClientOptions,
9 GenerationClientState,
10 GenerationFetcher,
11 GenerationPersistenceOptions,
12 GenerationRestoredResult,
13 InferGenerationOutputFromReturn,
14} from '@tanstack/ai-client'
15​
16/**
17 * Options for the useGeneration hook.
18 *
19 * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).
20 *
21 * @template TInput - The input type for the generation request
22 * @template TResult - The result type returned by the generation
23 * @template TOutput - The output type after optional transform (defaults to TResult)
24 */
25export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
26 /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
27 connection?: ConnectConnectionAdapter
28 /** Direct async function for one-shot generation (no streaming protocol needed) */
29 fetcher?: GenerationFetcher<TInput, TResult>
30 /**
31 * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
32 */
33 id?: string
34 /** Additional body parameters to send with connect-based adapter requests */
35 body?: Record<string, any>
36 /** Display options for TanStack AI Devtools. */
37 devtools?: AIDevtoolsDisplayOptions
38 /**
39 * How this generation persists across reloads.
40 * - Omit / `false`: ephemeral, in-memory only.
41 * - `true`: server-driven — on mount the client hydrates the last generation
42 * for its `threadId` from the server (needs a connection with a
43 * `hydrateGeneration` handler) and repaints it; it never auto-starts a run.
44 */
45 persistence?: boolean
46 /**
47 * The **scope** this generation belongs to: a stable, app-chosen name for the
48 * slot successive runs fill — not a link to a chat conversation.
49 *
50 * The hook starts empty and produces many runs over its life; each gets its
51 * own `runId`, but all belong to one scope. Persistence keys on this, so
52 * derive it from your own domain and keep it identical across reloads (e.g.
53 * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread
54 * id on the wire, which the protocol requires.
55 *
56 * **Required whenever `persistence` is set** — an app that cannot name the
57 * scope has nothing to restore to. Optional for ephemeral generations, where
58 * it falls back to `id` purely to satisfy the wire.
59 */
60 threadId?: string
61 /**
62 * Server-driven hydration handler for `persistence: true` when the
63 * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /
64 * `rpcStream()` adapter built without handlers) — typically a one-line
65 * server-function call. The connection's own handler takes precedence.
66 */
67 hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']
68 /**
69 * Re-attach handler that replays a run still generating to completion on
70 * mount, when the connection doesn't carry one. Without it, a restored
71 * `running` snapshot surfaces as an (interrupted) error. The connection's
72 * own handler takes precedence.
73 */
74 joinRun?: ConnectConnectionAdapter['joinRun']
75 /**
76 * Callback when a result is received. Can optionally return a transformed value.
77 *
78 * - Return a non-null value to transform and store it as the result
79 * - Return `null` to keep the previous result unchanged
80 * - Return nothing (`void`) to store the raw result as-is
81 */
82 onResult?: (result: TResult) => TOutput | null | void
83 /** Callback when an error occurs */
84 onError?: (error: Error) => void
85 /** Callback when progress is reported (0-100) */
86 onProgress?: (progress: number, message?: string) => void
87 /** Callback for each stream chunk (connect-based adapter mode only) */
88 onChunk?: (chunk: StreamChunk) => void
89 /**
90 * @internal Rebuild a typed result from a restored snapshot, injected by each
91 * specialized hook (image / speech / audio / transcription / summarize).
92 * Forwarded to the client so a server-hydrate restore repaints `result`.
93 */
94 reconstructResult?: (restored: GenerationRestoredResult) => TResult | null
96​
97/**
98 * Return type for the useGeneration hook.
99 *
100 * @template TOutput - The output type (after optional transform)
101 * @template TInput - The input type accepted by `generate` (defaults to any object)
102 */
103export interface UseGenerationReturn<
104 TOutput,
105 TInput extends Record<string, any> = Record<string, any>,
106> {
107 /** Trigger a generation request */
108 generate: (input: TInput) => Promise<void>
109 /** The generation result, or null if not yet generated */
110 result: TOutput | null
111 /** Whether a generation is currently in progress */
112 isLoading: boolean
113 /** Current error, if any */
114 error: Error | undefined
115 /** Current state of the generation client */
116 status: GenerationClientState
117 /** Abort the current generation */
118 stop: () => void
119 /** Clear result, error, and return to idle */
120 reset: () => void
121 /**
122 * The id of the generation job currently running, or `null` when nothing is in
123 * flight. Each call to `generate` is one job with its own id. Pass it to your
124 * own endpoint to cancel or poll the provider job — `stop()` only aborts the
125 * local stream, it does not stop work already running on the provider.
126 */
127 runId: string | null
129​
130/**
131 * Generic React hook for one-shot generation tasks.
132 *
133 * This is the base hook used by `useGenerateImage`, `useGenerateSpeech`,
134 * `useTranscription`, and `useSummarize`. You can also use it directly
135 * for custom generation types.
136 *
137 * @template TInput - The input type for the generation request
138 * @template TResult - The result type returned by the generation
139 *
140 * @example
141 * ```tsx
142 * const { generate, result, isLoading } = useGeneration<MyInput, MyResult>({
143 * connection: fetchServerSentEvents('/api/generate/custom'),
144 * })
145 *
146 * await generate({ prompt: 'Hello' })
147 * ```
148 */
149// `TTransformed` infers from the `onResult` return position (a covariant
150// inference site that works even for an optional nested property), which types
151// the callback parameter as `TResult` and narrows `result`. Inferring the
152// whole callback as a defaulted type parameter instead collapses to the
153// default, leaving the parameter `any` — a hard error under `strict`. See
154// issue #848.
155export function useGeneration<
156 TInput extends Record<string, any>,
157 TResult,
158 TTransformed = void,
159>(
160 options: Omit<
161 UseGenerationOptions<TInput, TResult>,
162 'onResult' | 'persistence' | 'threadId' | 'id'
163 > & {
164 onResult?: (result: TResult) => TTransformed
165 } & GenerationPersistenceOptions,
166): UseGenerationReturn<
167 InferGenerationOutputFromReturn<TResult, TTransformed>,
168 TInput
169> {
170 type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>
171 const hookId = useId()
172 // Single identity: prefer `threadId`; deprecated `id` only when no threadId.
173 const clientIdentity = options.threadId ?? options.id ?? hookId
174​
175 const [result, setResult] = useState<TOutput | null>(null)
176 const [isLoading, setIsLoading] = useState(false)
177 const [error, setError] = useState<Error | undefined>(undefined)
178 const [status, setStatus] = useState<GenerationClientState>('idle')
179 const [runId, setRunId] = useState<string | null>(null)
180​
181 const optionsRef = useRef(options)
182 optionsRef.current = options
183 const disposedRef = useRef(false)
184​
185 const client = useMemo(() => {
186 const opts = optionsRef.current
187​
188 // Conditional spread for `body` (strict-optional in target;
189 // local source is `Record<string, any> | undefined`). Callbacks
190 // wrap optional ones in non-returning bodies so `?.()`'s
191 // implicit `undefined` doesn't pollute the function return type.
192 // Identity: pass `threadId` alone when set (never also pass deprecated `id`).
193 const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
194 body: opts.body,
195 ...(opts.threadId !== undefined
196 ? { threadId: opts.threadId }
197 : { id: opts.id ?? hookId }),
198 ...(opts.persistence !== undefined && { persistence: opts.persistence }),
199 ...(opts.hydrateGeneration !== undefined && {
200 hydrateGeneration: opts.hydrateGeneration,
201 }),
202 ...(opts.joinRun !== undefined && { joinRun: opts.joinRun }),
203 ...(opts.reconstructResult
204 ? { reconstructResult: opts.reconstructResult }
205 : {}),
206 devtoolsBridgeFactory: createGenerationDevtoolsBridge,
207 devtools: {
208 hookName: 'useGeneration',
209 framework: 'react',
210 ...opts.devtools,
211 },
212 // The transform's raw return type (`TTransformed`) and the stored output
213 // (`TOutput`, with null/void/undefined stripped) are identical at runtime;
214 // the cast bridges the relationship that the conditional type hides.
215 onResult: ((r: TResult) => optionsRef.current.onResult?.(r)) as (
216 result: TResult,
217 ) => TOutput | null | void,
218 onError: (e: Error) => {
219 if (!disposedRef.current) optionsRef.current.onError?.(e)
220 },
221 onProgress: (p: number, m?: string) => {
222 if (!disposedRef.current) optionsRef.current.onProgress?.(p, m)
223 },
224 onChunk: (c: StreamChunk) => {
225 if (!disposedRef.current) optionsRef.current.onChunk?.(c)
226 },
227 onResultChange: (r) => {
228 if (!disposedRef.current) setResult(r)
229 },
230 onLoadingChange: (l) => {
231 if (!disposedRef.current) setIsLoading(l)
232 },
233 onErrorChange: (e) => {
234 if (!disposedRef.current) setError(e)
235 },
236 onStatusChange: (s) => {
237 if (!disposedRef.current) setStatus(s)
238 },
239 onResumeStateChange: (rs) => {
240 if (!disposedRef.current) setRunId(rs?.runId ?? null)
241 },
242 }
243​
244 if (opts.connection) {
245 return new GenerationClient<TInput, TResult, TOutput>({
246 ...clientOptions,
247 connection: opts.connection,
248 })
249 }
250​
251 if (opts.fetcher) {
252 return new GenerationClient<TInput, TResult, TOutput>({
253 ...clientOptions,
254 fetcher: opts.fetcher,
255 })
256 }
257​
258 throw new Error(
259 'useGeneration requires either a connection or fetcher option',
260 )
261 }, [clientIdentity, hookId])
262​
263 // Sync body changes without recreating client
264 useEffect(() => {
265 // Conditional spread: target uses strict-optional `body?: T`.
266 client.updateOptions({
267 ...(options.body !== undefined && { body: options.body }),
268 })
269 }, [client, options.body])
270​
271 // Mount devtools and clean up on unmount. Generation runs are never
272 // auto-started on mount — persisted state is only displayed. Mounting
273 // revives the client after a StrictMode dispose → remount replay.
274 useEffect(() => {
275 disposedRef.current = false
276 client.mountDevtools()
277​
278 return () => {
279 disposedRef.current = true
280 client.dispose()
281 }
282 }, [client])
283​
284 const generate = useCallback(
285 async (input: TInput) => {
286 await client.generate(input)
287 },
288 [client],
289 )
290​
291 const stop = useCallback(() => {
292 client.stop()
293 }, [client])
294​
295 const reset = useCallback(() => {
296 client.reset()
297 }, [client])
298​
299 return {
300 generate,
301 result,
302 isLoading,
303 error,
304 status,
305 stop,
306 reset,
307 runId,
308 }