@tanstack/ai-angular 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,5 @@
1
1
  import { injectGeneration } from './inject-generation'
2
+ import { reconstructAudioResult } from '@tanstack/ai-client'
2
3
  import type { AudioGenerationResult, StreamChunk } from '@tanstack/ai'
3
4
  import type {
4
5
  AIDevtoolsDisplayOptions,
@@ -6,22 +7,34 @@ import type {
6
7
  ConnectConnectionAdapter,
7
8
  GenerationClientState,
8
9
  GenerationFetcher,
10
+ GenerationPersistenceOptions,
9
11
  InferGenerationOutputFromReturn,
10
12
  } from '@tanstack/ai-client'
11
13
  import type { Signal } from '@angular/core'
12
14
  import type { ReactiveOption } from './internal/to-reactive'
15
+ import type {
16
+ InjectGenerationOptions,
17
+ InjectGenerationResult,
18
+ } from './inject-generation'
13
19
 
14
20
  /**
15
21
  * Options for the injectGenerateAudio injectable.
16
22
  *
17
23
  * @template TOutput - The output type after optional transform (defaults to AudioGenerationResult)
18
24
  */
19
- export interface InjectGenerateAudioOptions<TOutput = AudioGenerationResult> {
25
+ export interface InjectGenerateAudioOptions<
26
+ TOutput = AudioGenerationResult,
27
+ > extends Pick<
28
+ InjectGenerationOptions<AudioGenerateInput, AudioGenerationResult, TOutput>,
29
+ 'persistence' | 'threadId' | 'hydrateGeneration' | 'joinRun'
30
+ > {
20
31
  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
21
32
  connection?: ConnectConnectionAdapter
22
33
  /** Direct async function for audio generation */
23
34
  fetcher?: GenerationFetcher<AudioGenerateInput, AudioGenerationResult>
24
- /** Unique identifier for this generation instance */
35
+ /**
36
+ * @deprecated Prefer `threadId`. Only allowed when `threadId` is omitted (see `GenerationPersistenceOptions`).
37
+ */
25
38
  id?: string
26
39
  /** Additional body parameters to send with connect-based adapter requests. Reactive. */
27
40
  body?: ReactiveOption<Record<string, any>>
@@ -48,7 +61,9 @@ export interface InjectGenerateAudioOptions<TOutput = AudioGenerationResult> {
48
61
  *
49
62
  * @template TOutput - The output type (after optional transform)
50
63
  */
51
- export interface InjectGenerateAudioResult<TOutput = AudioGenerationResult> {
64
+ export interface InjectGenerateAudioResult<
65
+ TOutput = AudioGenerationResult,
66
+ > extends Omit<InjectGenerationResult<TOutput>, 'generate'> {
52
67
  /** Trigger audio generation */
53
68
  generate: (input: AudioGenerateInput) => Promise<void>
54
69
  /** The generation result containing audio, or null */
@@ -59,10 +74,6 @@ export interface InjectGenerateAudioResult<TOutput = AudioGenerationResult> {
59
74
  error: Signal<Error | undefined>
60
75
  /** Current state of the generation */
61
76
  status: Signal<GenerationClientState>
62
- /** Abort the current generation */
63
- stop: () => void
64
- /** Clear result, error, and return to idle */
65
- reset: () => void
66
77
  }
67
78
 
68
79
  /**
@@ -97,9 +108,12 @@ export interface InjectGenerateAudioResult<TOutput = AudioGenerationResult> {
97
108
  * ```
98
109
  */
99
110
  export function injectGenerateAudio<TTransformed = void>(
100
- options: Omit<InjectGenerateAudioOptions, 'onResult'> & {
111
+ options: Omit<
112
+ InjectGenerateAudioOptions,
113
+ 'onResult' | 'persistence' | 'threadId' | 'id'
114
+ > & {
101
115
  onResult?: (result: AudioGenerationResult) => TTransformed
102
- },
116
+ } & GenerationPersistenceOptions,
103
117
  ): InjectGenerateAudioResult<
104
118
  InferGenerationOutputFromReturn<AudioGenerationResult, TTransformed>
105
119
  > {
@@ -109,19 +123,15 @@ export function injectGenerateAudio<TTransformed = void>(
109
123
  hookName: 'injectGenerateAudio',
110
124
  outputKind: 'audio' as const,
111
125
  }
112
- const { generate, result, isLoading, error, status, stop, reset } =
113
- injectGeneration<AudioGenerateInput, AudioGenerationResult, TTransformed>({
114
- ...options,
115
- devtools,
116
- })
126
+ const generation = injectGeneration<
127
+ AudioGenerateInput,
128
+ AudioGenerationResult,
129
+ TTransformed
130
+ >({
131
+ ...options,
132
+ devtools,
133
+ reconstructResult: reconstructAudioResult,
134
+ })
117
135
 
118
- return {
119
- generate: generate as (input: AudioGenerateInput) => Promise<void>,
120
- result,
121
- isLoading,
122
- error,
123
- status,
124
- stop,
125
- reset,
126
- }
136
+ return generation
127
137
  }
@@ -1,34 +1,42 @@
1
1
  import { injectGeneration } from './inject-generation'
2
+ import { reconstructImageResult } from '@tanstack/ai-client'
2
3
  import type { Signal } from '@angular/core'
3
4
  import type { ImageGenerationResult } from '@tanstack/ai'
4
5
  import type {
5
6
  GenerationClientState,
7
+ GenerationPersistenceOptions,
6
8
  ImageGenerateInput,
7
9
  InferGenerationOutputFromReturn,
8
10
  } from '@tanstack/ai-client'
9
- import type { InjectGenerationOptions } from './inject-generation'
11
+ import type {
12
+ InjectGenerationOptions,
13
+ InjectGenerationResult,
14
+ } from './inject-generation'
10
15
 
11
16
  export type InjectGenerateImageOptions<TOutput = ImageGenerationResult> = Omit<
12
17
  InjectGenerationOptions<ImageGenerateInput, ImageGenerationResult, TOutput>,
13
- 'onResult'
18
+ 'onResult' | 'reconstructResult'
14
19
  > & {
15
20
  onResult?: (result: ImageGenerationResult) => TOutput | null | void
16
21
  }
17
22
 
18
- export interface InjectGenerateImageResult<TOutput = ImageGenerationResult> {
23
+ export interface InjectGenerateImageResult<
24
+ TOutput = ImageGenerationResult,
25
+ > extends Omit<InjectGenerationResult<TOutput>, 'generate'> {
19
26
  generate: (input: ImageGenerateInput) => Promise<void>
20
27
  result: Signal<TOutput | null>
21
28
  isLoading: Signal<boolean>
22
29
  error: Signal<Error | undefined>
23
30
  status: Signal<GenerationClientState>
24
- stop: () => void
25
- reset: () => void
26
31
  }
27
32
 
28
33
  export function injectGenerateImage<TTransformed = void>(
29
- options: Omit<InjectGenerateImageOptions, 'onResult'> & {
34
+ options: Omit<
35
+ InjectGenerateImageOptions,
36
+ 'onResult' | 'persistence' | 'threadId' | 'id'
37
+ > & {
30
38
  onResult?: (result: ImageGenerationResult) => TTransformed
31
- },
39
+ } & GenerationPersistenceOptions,
32
40
  ): InjectGenerateImageResult<
33
41
  InferGenerationOutputFromReturn<ImageGenerationResult, TTransformed>
34
42
  > {
@@ -38,18 +46,14 @@ export function injectGenerateImage<TTransformed = void>(
38
46
  hookName: 'injectGenerateImage',
39
47
  outputKind: 'image' as const,
40
48
  }
41
- const { generate, result, isLoading, error, status, stop, reset } =
42
- injectGeneration<ImageGenerateInput, ImageGenerationResult, TTransformed>({
43
- ...options,
44
- devtools,
45
- })
46
- return {
47
- generate: generate as (input: ImageGenerateInput) => Promise<void>,
48
- result,
49
- isLoading,
50
- error,
51
- status,
52
- stop,
53
- reset,
54
- }
49
+ const generation = injectGeneration<
50
+ ImageGenerateInput,
51
+ ImageGenerationResult,
52
+ TTransformed
53
+ >({
54
+ ...options,
55
+ devtools,
56
+ reconstructResult: reconstructImageResult,
57
+ })
58
+ return generation
55
59
  }
@@ -1,34 +1,43 @@
1
1
  import { injectGeneration } from './inject-generation'
2
+ import { reconstructSpeechResult } from '@tanstack/ai-client'
2
3
  import type { Signal } from '@angular/core'
3
4
  import type { TTSResult } from '@tanstack/ai'
4
5
  import type {
5
6
  GenerationClientState,
7
+ GenerationPersistenceOptions,
6
8
  InferGenerationOutputFromReturn,
7
9
  SpeechGenerateInput,
8
10
  } from '@tanstack/ai-client'
9
- import type { InjectGenerationOptions } from './inject-generation'
11
+ import type {
12
+ InjectGenerationOptions,
13
+ InjectGenerationResult,
14
+ } from './inject-generation'
10
15
 
11
16
  export type InjectGenerateSpeechOptions<TOutput = TTSResult> = Omit<
12
17
  InjectGenerationOptions<SpeechGenerateInput, TTSResult, TOutput>,
13
- 'onResult'
18
+ 'onResult' | 'reconstructResult'
14
19
  > & {
15
20
  onResult?: (result: TTSResult) => TOutput | null | void
16
21
  }
17
22
 
18
- export interface InjectGenerateSpeechResult<TOutput = TTSResult> {
23
+ export interface InjectGenerateSpeechResult<TOutput = TTSResult> extends Omit<
24
+ InjectGenerationResult<TOutput>,
25
+ 'generate'
26
+ > {
19
27
  generate: (input: SpeechGenerateInput) => Promise<void>
20
28
  result: Signal<TOutput | null>
21
29
  isLoading: Signal<boolean>
22
30
  error: Signal<Error | undefined>
23
31
  status: Signal<GenerationClientState>
24
- stop: () => void
25
- reset: () => void
26
32
  }
27
33
 
28
34
  export function injectGenerateSpeech<TTransformed = void>(
29
- options: Omit<InjectGenerateSpeechOptions, 'onResult'> & {
35
+ options: Omit<
36
+ InjectGenerateSpeechOptions,
37
+ 'onResult' | 'persistence' | 'threadId' | 'id'
38
+ > & {
30
39
  onResult?: (result: TTSResult) => TTransformed
31
- },
40
+ } & GenerationPersistenceOptions,
32
41
  ): InjectGenerateSpeechResult<
33
42
  InferGenerationOutputFromReturn<TTSResult, TTransformed>
34
43
  > {
@@ -38,18 +47,14 @@ export function injectGenerateSpeech<TTransformed = void>(
38
47
  hookName: 'injectGenerateSpeech',
39
48
  outputKind: 'audio' as const,
40
49
  }
41
- const { generate, result, isLoading, error, status, stop, reset } =
42
- injectGeneration<SpeechGenerateInput, TTSResult, TTransformed>({
43
- ...options,
44
- devtools,
45
- })
46
- return {
47
- generate: generate as (input: SpeechGenerateInput) => Promise<void>,
48
- result,
49
- isLoading,
50
- error,
51
- status,
52
- stop,
53
- reset,
54
- }
50
+ const generation = injectGeneration<
51
+ SpeechGenerateInput,
52
+ TTSResult,
53
+ TTransformed
54
+ >({
55
+ ...options,
56
+ devtools,
57
+ reconstructResult: reconstructSpeechResult,
58
+ })
59
+ return generation
55
60
  }
@@ -17,6 +17,7 @@ import type {
17
17
  ConnectConnectionAdapter,
18
18
  GenerationClientState,
19
19
  GenerationFetcher,
20
+ GenerationPersistenceOptions,
20
21
  InferGenerationOutputFromReturn,
21
22
  VideoGenerateInput,
22
23
  VideoGenerateResult,
@@ -32,6 +33,43 @@ export interface InjectGenerateVideoOptions<TOutput = VideoGenerateResult> {
32
33
  id?: string
33
34
  body?: ReactiveOption<Record<string, any>>
34
35
  devtools?: AIDevtoolsDisplayOptions
36
+ /**
37
+ * How this generation persists across reloads.
38
+ * - Omit / `false`: ephemeral, in-memory only.
39
+ * - `true`: server-driven — on mount the client hydrates the last generation
40
+ * for its `threadId` from the server (needs a connection with a
41
+ * `hydrateGeneration` handler) and repaints it; it never auto-starts a run.
42
+ */
43
+ persistence?: boolean
44
+ /**
45
+ * The **scope** this generation belongs to: a stable, app-chosen name for the
46
+ * slot successive runs fill — not a link to a chat conversation.
47
+ *
48
+ * The hook starts empty and produces many runs over its life; each gets its
49
+ * own `runId`, but all belong to one scope. Persistence keys on this, so
50
+ * derive it from your own domain and keep it identical across reloads (e.g.
51
+ * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread
52
+ * id on the wire, which the protocol requires.
53
+ *
54
+ * **Required whenever `persistence` is set** — an app that cannot name the
55
+ * scope has nothing to restore to. Optional for ephemeral generations, where
56
+ * it falls back to `id` purely to satisfy the wire.
57
+ */
58
+ threadId?: string
59
+ /**
60
+ * Server-driven hydration handler for `persistence: true` when the
61
+ * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /
62
+ * `rpcStream()` adapter built without handlers) — typically a one-line
63
+ * server-function call. The connection's own handler takes precedence.
64
+ */
65
+ hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']
66
+ /**
67
+ * Re-attach handler that replays a run still generating to completion on
68
+ * mount, when the connection doesn't carry one. Without it, a restored
69
+ * `running` snapshot surfaces as an (interrupted) error. The connection's
70
+ * own handler takes precedence.
71
+ */
72
+ joinRun?: ConnectConnectionAdapter['joinRun']
35
73
  onResult?: (result: VideoGenerateResult) => TOutput | null | void
36
74
  onError?: (error: Error) => void
37
75
  onProgress?: (progress: number, message?: string) => void
@@ -50,15 +88,25 @@ export interface InjectGenerateVideoResult<TOutput = VideoGenerateResult> {
50
88
  status: Signal<GenerationClientState>
51
89
  stop: () => void
52
90
  reset: () => void
91
+ /**
92
+ * The id of the generation job currently running, or `null` when nothing is in
93
+ * flight. Each call to `generate` is one job with its own id. Pass it to your
94
+ * own endpoint to cancel or poll the provider job — `stop()` only aborts the
95
+ * local stream, it does not stop work already running on the provider.
96
+ */
97
+ runId: Signal<string | null>
53
98
  }
54
99
 
55
100
  // `TTransformed` infers from the `onResult` return position so the callback
56
101
  // parameter is typed as `VideoGenerateResult` and `result` narrows to the
57
102
  // transform's return. See issue #848.
58
103
  export function injectGenerateVideo<TTransformed = void>(
59
- options: Omit<InjectGenerateVideoOptions, 'onResult'> & {
104
+ options: Omit<
105
+ InjectGenerateVideoOptions,
106
+ 'onResult' | 'persistence' | 'threadId' | 'id'
107
+ > & {
60
108
  onResult?: (result: VideoGenerateResult) => TTransformed
61
- },
109
+ } & GenerationPersistenceOptions,
62
110
  ): InjectGenerateVideoResult<
63
111
  InferGenerationOutputFromReturn<VideoGenerateResult, TTransformed>
64
112
  > {
@@ -71,7 +119,6 @@ export function injectGenerateVideo<TTransformed = void>(
71
119
 
72
120
  const destroyRef = inject(DestroyRef)
73
121
  const injector = inject(Injector)
74
- const clientId = options.id || `injectGenerateVideo-${nextId++}`
75
122
 
76
123
  const result = signal<TOutput | null>(null)
77
124
  const jobId = signal<string | null>(null)
@@ -79,13 +126,25 @@ export function injectGenerateVideo<TTransformed = void>(
79
126
  const isLoading = signal(false)
80
127
  const error = signal<Error | undefined>(undefined)
81
128
  const status = signal<GenerationClientState>('idle')
129
+ const runId = signal<string | null>(null)
130
+ let disposed = false
82
131
 
83
132
  const bodySource =
84
133
  options.body !== undefined ? toReactive(options.body) : undefined
85
134
 
135
+ // Identity: pass `threadId` alone when set (never also pass deprecated `id`).
86
136
  const baseOptions = {
87
- id: clientId,
88
137
  ...(bodySource !== undefined && { body: bodySource() }),
138
+ ...(options.threadId !== undefined
139
+ ? { threadId: options.threadId }
140
+ : { id: options.id ?? `injectGenerateVideo-${nextId++}` }),
141
+ ...(options.persistence !== undefined && {
142
+ persistence: options.persistence,
143
+ }),
144
+ ...(options.hydrateGeneration !== undefined && {
145
+ hydrateGeneration: options.hydrateGeneration,
146
+ }),
147
+ ...(options.joinRun !== undefined && { joinRun: options.joinRun }),
89
148
  devtoolsBridgeFactory: createVideoDevtoolsBridge,
90
149
  devtools: {
91
150
  ...options.devtools,
@@ -99,17 +158,42 @@ export function injectGenerateVideo<TTransformed = void>(
99
158
  onResult: ((r: VideoGenerateResult) => options.onResult?.(r)) as (
100
159
  result: VideoGenerateResult,
101
160
  ) => TOutput | null | void,
102
- onError: (e: Error) => options.onError?.(e),
103
- onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
104
- onChunk: (c: StreamChunk) => options.onChunk?.(c),
105
- onJobCreated: (id: string) => options.onJobCreated?.(id),
106
- onStatusUpdate: (s: VideoStatusInfo) => options.onStatusUpdate?.(s),
107
- onResultChange: (r: TOutput | null) => result.set(r),
108
- onLoadingChange: (l: boolean) => isLoading.set(l),
109
- onErrorChange: (e: Error | undefined) => error.set(e),
110
- onStatusChange: (s: GenerationClientState) => status.set(s),
111
- onJobIdChange: (id: string | null) => jobId.set(id),
112
- onVideoStatusChange: (s: VideoStatusInfo | null) => videoStatus.set(s),
161
+ onError: (e: Error) => {
162
+ if (!disposed) options.onError?.(e)
163
+ },
164
+ onProgress: (p: number, m?: string) => {
165
+ if (!disposed) options.onProgress?.(p, m)
166
+ },
167
+ onChunk: (c: StreamChunk) => {
168
+ if (!disposed) options.onChunk?.(c)
169
+ },
170
+ onJobCreated: (id: string) => {
171
+ if (!disposed) options.onJobCreated?.(id)
172
+ },
173
+ onStatusUpdate: (s: VideoStatusInfo) => {
174
+ if (!disposed) options.onStatusUpdate?.(s)
175
+ },
176
+ onResultChange: (r: TOutput | null) => {
177
+ if (!disposed) result.set(r)
178
+ },
179
+ onLoadingChange: (l: boolean) => {
180
+ if (!disposed) isLoading.set(l)
181
+ },
182
+ onErrorChange: (e: Error | undefined) => {
183
+ if (!disposed) error.set(e)
184
+ },
185
+ onStatusChange: (s: GenerationClientState) => {
186
+ if (!disposed) status.set(s)
187
+ },
188
+ onJobIdChange: (id: string | null) => {
189
+ if (!disposed) jobId.set(id)
190
+ },
191
+ onVideoStatusChange: (s: VideoStatusInfo | null) => {
192
+ if (!disposed) videoStatus.set(s)
193
+ },
194
+ onResumeStateChange: (rs: { runId: string } | null) => {
195
+ if (!disposed) runId.set(rs?.runId ?? null)
196
+ },
113
197
  }
114
198
 
115
199
  let client: VideoGenerationClient<TOutput>
@@ -132,14 +216,26 @@ export function injectGenerateVideo<TTransformed = void>(
132
216
  if (bodySource) {
133
217
  effect(
134
218
  () => {
135
- client.updateOptions({ body: bodySource() })
219
+ client.updateOptions({
220
+ body: bodySource(),
221
+ })
136
222
  },
137
223
  { injector },
138
224
  )
139
225
  }
140
226
 
141
- afterNextRender(() => client.mountDevtools(), { injector })
142
- destroyRef.onDestroy(() => client.dispose())
227
+ // Mount devtools only. Generation runs are never auto-started after render —
228
+ // persisted state is read-only for display.
229
+ afterNextRender(
230
+ () => {
231
+ client.mountDevtools()
232
+ },
233
+ { injector },
234
+ )
235
+ destroyRef.onDestroy(() => {
236
+ disposed = true
237
+ client.dispose()
238
+ })
143
239
 
144
240
  return {
145
241
  generate: (input: VideoGenerateInput) => client.generate(input),
@@ -151,5 +247,6 @@ export function injectGenerateVideo<TTransformed = void>(
151
247
  status: status.asReadonly(),
152
248
  stop: () => client.stop(),
153
249
  reset: () => client.reset(),
250
+ runId: runId.asReadonly(),
154
251
  }
155
252
  }