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

inject-generation.ts

278 lines9.8 KB

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