ai 5.0.0-canary.3 → 5.0.0-canary.4

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,813 +0,0 @@
1
- import { LanguageModelV2FinishReason, LanguageModelV2CallWarning, LanguageModelV2ProviderMetadata, LanguageModelV2 } from '@ai-sdk/provider';
2
- import { ReactNode } from 'react';
3
- import { z } from 'zod';
4
- import { Message } from '@ai-sdk/ui-utils';
5
-
6
- type AIAction<T = any, R = any> = (...args: T[]) => Promise<R>;
7
- type AIActions<T = any, R = any> = Record<string, AIAction<T, R>>;
8
- type AIProviderProps<AIState = any, UIState = any, Actions = any> = {
9
- children: React.ReactNode;
10
- initialAIState?: AIState;
11
- initialUIState?: UIState;
12
- /** $ActionTypes is only added for type inference and is never used at runtime **/
13
- $ActionTypes?: Actions;
14
- };
15
- type AIProvider<AIState = any, UIState = any, Actions = any> = (props: AIProviderProps<AIState, UIState, Actions>) => Promise<React.ReactElement>;
16
- type InferAIState<T, Fallback> = T extends AIProvider<infer AIState, any, any> ? AIState : Fallback;
17
- type InferUIState<T, Fallback> = T extends AIProvider<any, infer UIState, any> ? UIState : Fallback;
18
- type InferActions<T, Fallback> = T extends AIProvider<any, any, infer Actions> ? Actions : Fallback;
19
- type OnSetAIState<S> = ({ key, state, done, }: {
20
- key: string | number | symbol | undefined;
21
- state: S;
22
- done: boolean;
23
- }) => void | Promise<void>;
24
- type OnGetUIState<S> = AIAction<void, S | undefined>;
25
- type ValueOrUpdater<T> = T | ((current: T) => T);
26
- type MutableAIState<AIState> = {
27
- get: () => AIState;
28
- update: (newState: ValueOrUpdater<AIState>) => void;
29
- done: ((newState: AIState) => void) | (() => void);
30
- };
31
-
32
- /**
33
- * Get the current AI state.
34
- * If `key` is provided, it will return the value of the specified key in the
35
- * AI state, if it's an object. If it's not an object, it will throw an error.
36
- *
37
- * @example const state = getAIState() // Get the entire AI state
38
- * @example const field = getAIState('key') // Get the value of the key
39
- */
40
- declare function getAIState<AI extends AIProvider = any>(): Readonly<InferAIState<AI, any>>;
41
- declare function getAIState<AI extends AIProvider = any>(key: keyof InferAIState<AI, any>): Readonly<InferAIState<AI, any>[typeof key]>;
42
- /**
43
- * Get the mutable AI state. Note that you must call `.done()` when finishing
44
- * updating the AI state.
45
- *
46
- * @example
47
- * ```tsx
48
- * const state = getMutableAIState()
49
- * state.update({ ...state.get(), key: 'value' })
50
- * state.update((currentState) => ({ ...currentState, key: 'value' }))
51
- * state.done()
52
- * ```
53
- *
54
- * @example
55
- * ```tsx
56
- * const state = getMutableAIState()
57
- * state.done({ ...state.get(), key: 'value' }) // Done with a new state
58
- * ```
59
- */
60
- declare function getMutableAIState<AI extends AIProvider = any>(): MutableAIState<InferAIState<AI, any>>;
61
- declare function getMutableAIState<AI extends AIProvider = any>(key: keyof InferAIState<AI, any>): MutableAIState<InferAIState<AI, any>[typeof key]>;
62
-
63
- declare function createAI<AIState = any, UIState = any, Actions extends AIActions = {}>({ actions, initialAIState, initialUIState, onSetAIState, onGetUIState, }: {
64
- actions: Actions;
65
- initialAIState?: AIState;
66
- initialUIState?: UIState;
67
- /**
68
- * This function is called whenever the AI state is updated by an Action.
69
- * You can use this to persist the AI state to a database, or to send it to a
70
- * logging service.
71
- */
72
- onSetAIState?: OnSetAIState<AIState>;
73
- /**
74
- * This function is used to retrieve the UI state based on the AI state.
75
- * For example, to render the initial UI state based on a given AI state, or
76
- * to sync the UI state when the application is already loaded.
77
- *
78
- * If returning `undefined`, the client side UI state will not be updated.
79
- *
80
- * This function must be annotated with the `"use server"` directive.
81
- *
82
- * @example
83
- * ```tsx
84
- * onGetUIState: async () => {
85
- * 'use server';
86
- *
87
- * const currentAIState = getAIState();
88
- * const externalAIState = await loadAIStateFromDatabase();
89
- *
90
- * if (currentAIState === externalAIState) return undefined;
91
- *
92
- * // Update current AI state and return the new UI state
93
- * const state = getMutableAIState()
94
- * state.done(externalAIState)
95
- *
96
- * return <div>...</div>;
97
- * }
98
- * ```
99
- */
100
- onGetUIState?: OnGetUIState<UIState>;
101
- }): AIProvider<AIState, UIState, Actions>;
102
-
103
- type CallSettings = {
104
- /**
105
- Maximum number of tokens to generate.
106
- */
107
- maxTokens?: number;
108
- /**
109
- Temperature setting. This is a number between 0 (almost no randomness) and
110
- 1 (very random).
111
-
112
- It is recommended to set either `temperature` or `topP`, but not both.
113
-
114
- @default 0
115
- */
116
- temperature?: number;
117
- /**
118
- Nucleus sampling. This is a number between 0 and 1.
119
-
120
- E.g. 0.1 would mean that only tokens with the top 10% probability mass
121
- are considered.
122
-
123
- It is recommended to set either `temperature` or `topP`, but not both.
124
- */
125
- topP?: number;
126
- /**
127
- Only sample from the top K options for each subsequent token.
128
-
129
- Used to remove "long tail" low probability responses.
130
- Recommended for advanced use cases only. You usually only need to use temperature.
131
- */
132
- topK?: number;
133
- /**
134
- Presence penalty setting. It affects the likelihood of the model to
135
- repeat information that is already in the prompt.
136
-
137
- The presence penalty is a number between -1 (increase repetition)
138
- and 1 (maximum penalty, decrease repetition). 0 means no penalty.
139
- */
140
- presencePenalty?: number;
141
- /**
142
- Frequency penalty setting. It affects the likelihood of the model
143
- to repeatedly use the same words or phrases.
144
-
145
- The frequency penalty is a number between -1 (increase repetition)
146
- and 1 (maximum penalty, decrease repetition). 0 means no penalty.
147
- */
148
- frequencyPenalty?: number;
149
- /**
150
- Stop sequences.
151
- If set, the model will stop generating text when one of the stop sequences is generated.
152
- Providers may have limits on the number of stop sequences.
153
- */
154
- stopSequences?: string[];
155
- /**
156
- The seed (integer) to use for random sampling. If set and supported
157
- by the model, calls will generate deterministic results.
158
- */
159
- seed?: number;
160
- /**
161
- Maximum number of retries. Set to 0 to disable retries.
162
-
163
- @default 2
164
- */
165
- maxRetries?: number;
166
- /**
167
- Abort signal.
168
- */
169
- abortSignal?: AbortSignal;
170
- /**
171
- Additional HTTP headers to be sent with the request.
172
- Only applicable for HTTP-based providers.
173
- */
174
- headers?: Record<string, string | undefined>;
175
- };
176
-
177
- /**
178
- Reason why a language model finished generating a response.
179
-
180
- Can be one of the following:
181
- - `stop`: model generated stop sequence
182
- - `length`: model generated maximum number of tokens
183
- - `content-filter`: content filter violation stopped the model
184
- - `tool-calls`: model triggered tool calls
185
- - `error`: model stopped because of an error
186
- - `other`: model stopped for other reasons
187
- */
188
- type FinishReason = LanguageModelV2FinishReason;
189
- /**
190
- Warning from the model provider for this call. The call will proceed, but e.g.
191
- some settings might not be supported, which can lead to suboptimal results.
192
- */
193
- type CallWarning = LanguageModelV2CallWarning;
194
- /**
195
- Tool choice for the generation. It supports the following settings:
196
-
197
- - `auto` (default): the model can choose whether and which tools to call.
198
- - `required`: the model must call a tool. It can choose which tool to call.
199
- - `none`: the model must not call tools
200
- - `{ type: 'tool', toolName: string (typed) }`: the model must call the specified tool
201
- */
202
- type ToolChoice<TOOLS extends Record<string, unknown>> = 'auto' | 'none' | 'required' | {
203
- type: 'tool';
204
- toolName: keyof TOOLS;
205
- };
206
-
207
- /**
208
- Additional provider-specific metadata that is returned from the provider.
209
-
210
- This is needed to enable provider-specific functionality that can be
211
- fully encapsulated in the provider.
212
- */
213
- type ProviderMetadata = LanguageModelV2ProviderMetadata;
214
- /**
215
- Additional provider-specific options.
216
-
217
- They are passed through to the provider from the AI SDK and enable
218
- provider-specific functionality that can be fully encapsulated in the provider.
219
- */
220
- type ProviderOptions = LanguageModelV2ProviderMetadata;
221
-
222
- /**
223
- Represents the number of tokens used in a prompt and completion.
224
- */
225
- type LanguageModelUsage = {
226
- /**
227
- The number of tokens used in the prompt.
228
- */
229
- promptTokens: number;
230
- /**
231
- The number of tokens used in the completion.
232
- */
233
- completionTokens: number;
234
- /**
235
- The total number of tokens used (promptTokens + completionTokens).
236
- */
237
- totalTokens: number;
238
- };
239
-
240
- /**
241
- Data content. Can either be a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer.
242
- */
243
- type DataContent = string | Uint8Array | ArrayBuffer | Buffer;
244
-
245
- type ToolResultContent = Array<{
246
- type: 'text';
247
- text: string;
248
- } | {
249
- type: 'image';
250
- data: string;
251
- mimeType?: string;
252
- }>;
253
-
254
- /**
255
- Text content part of a prompt. It contains a string of text.
256
- */
257
- interface TextPart {
258
- type: 'text';
259
- /**
260
- The text content.
261
- */
262
- text: string;
263
- /**
264
- Additional provider-specific metadata. They are passed through
265
- to the provider from the AI SDK and enable provider-specific
266
- functionality that can be fully encapsulated in the provider.
267
- */
268
- providerOptions?: ProviderOptions;
269
- /**
270
- @deprecated Use `providerOptions` instead.
271
- */
272
- experimental_providerMetadata?: ProviderMetadata;
273
- }
274
- /**
275
- Image content part of a prompt. It contains an image.
276
- */
277
- interface ImagePart {
278
- type: 'image';
279
- /**
280
- Image data. Can either be:
281
-
282
- - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
283
- - URL: a URL that points to the image
284
- */
285
- image: DataContent | URL;
286
- /**
287
- Optional mime type of the image.
288
- */
289
- mimeType?: string;
290
- /**
291
- Additional provider-specific metadata. They are passed through
292
- to the provider from the AI SDK and enable provider-specific
293
- functionality that can be fully encapsulated in the provider.
294
- */
295
- providerOptions?: ProviderOptions;
296
- /**
297
- @deprecated Use `providerOptions` instead.
298
- */
299
- experimental_providerMetadata?: ProviderMetadata;
300
- }
301
- /**
302
- File content part of a prompt. It contains a file.
303
- */
304
- interface FilePart {
305
- type: 'file';
306
- /**
307
- File data. Can either be:
308
-
309
- - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
310
- - URL: a URL that points to the image
311
- */
312
- data: DataContent | URL;
313
- /**
314
- Optional filename of the file.
315
- */
316
- filename?: string;
317
- /**
318
- Mime type of the file.
319
- */
320
- mimeType: string;
321
- /**
322
- Additional provider-specific metadata. They are passed through
323
- to the provider from the AI SDK and enable provider-specific
324
- functionality that can be fully encapsulated in the provider.
325
- */
326
- providerOptions?: ProviderOptions;
327
- /**
328
- @deprecated Use `providerOptions` instead.
329
- */
330
- experimental_providerMetadata?: ProviderMetadata;
331
- }
332
- /**
333
- * Reasoning content part of a prompt. It contains a reasoning.
334
- */
335
- interface ReasoningPart {
336
- type: 'reasoning';
337
- /**
338
- The reasoning text.
339
- */
340
- text: string;
341
- /**
342
- An optional signature for verifying that the reasoning originated from the model.
343
- */
344
- signature?: string;
345
- /**
346
- Additional provider-specific metadata. They are passed through
347
- to the provider from the AI SDK and enable provider-specific
348
- functionality that can be fully encapsulated in the provider.
349
- */
350
- providerOptions?: ProviderOptions;
351
- /**
352
- @deprecated Use `providerOptions` instead.
353
- */
354
- experimental_providerMetadata?: ProviderMetadata;
355
- }
356
- /**
357
- Redacted reasoning content part of a prompt.
358
- */
359
- interface RedactedReasoningPart {
360
- type: 'redacted-reasoning';
361
- /**
362
- Redacted reasoning data.
363
- */
364
- data: string;
365
- /**
366
- Additional provider-specific metadata. They are passed through
367
- to the provider from the AI SDK and enable provider-specific
368
- functionality that can be fully encapsulated in the provider.
369
- */
370
- providerOptions?: ProviderOptions;
371
- /**
372
- @deprecated Use `providerOptions` instead.
373
- */
374
- experimental_providerMetadata?: ProviderMetadata;
375
- }
376
- /**
377
- Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).
378
- */
379
- interface ToolCallPart {
380
- type: 'tool-call';
381
- /**
382
- ID of the tool call. This ID is used to match the tool call with the tool result.
383
- */
384
- toolCallId: string;
385
- /**
386
- Name of the tool that is being called.
387
- */
388
- toolName: string;
389
- /**
390
- Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
391
- */
392
- args: unknown;
393
- /**
394
- Additional provider-specific metadata. They are passed through
395
- to the provider from the AI SDK and enable provider-specific
396
- functionality that can be fully encapsulated in the provider.
397
- */
398
- providerOptions?: ProviderOptions;
399
- /**
400
- @deprecated Use `providerOptions` instead.
401
- */
402
- experimental_providerMetadata?: ProviderMetadata;
403
- }
404
- /**
405
- Tool result content part of a prompt. It contains the result of the tool call with the matching ID.
406
- */
407
- interface ToolResultPart {
408
- type: 'tool-result';
409
- /**
410
- ID of the tool call that this result is associated with.
411
- */
412
- toolCallId: string;
413
- /**
414
- Name of the tool that generated this result.
415
- */
416
- toolName: string;
417
- /**
418
- Result of the tool call. This is a JSON-serializable object.
419
- */
420
- result: unknown;
421
- /**
422
- Multi-part content of the tool result. Only for tools that support multipart results.
423
- */
424
- experimental_content?: ToolResultContent;
425
- /**
426
- Optional flag if the result is an error or an error message.
427
- */
428
- isError?: boolean;
429
- /**
430
- Additional provider-specific metadata. They are passed through
431
- to the provider from the AI SDK and enable provider-specific
432
- functionality that can be fully encapsulated in the provider.
433
- */
434
- providerOptions?: ProviderOptions;
435
- /**
436
- @deprecated Use `providerOptions` instead.
437
- */
438
- experimental_providerMetadata?: ProviderMetadata;
439
- }
440
-
441
- /**
442
- A system message. It can contain system information.
443
-
444
- Note: using the "system" part of the prompt is strongly preferred
445
- to increase the resilience against prompt injection attacks,
446
- and because not all providers support several system messages.
447
- */
448
- type CoreSystemMessage = {
449
- role: 'system';
450
- content: string;
451
- /**
452
- Additional provider-specific metadata. They are passed through
453
- to the provider from the AI SDK and enable provider-specific
454
- functionality that can be fully encapsulated in the provider.
455
- */
456
- providerOptions?: ProviderOptions;
457
- /**
458
- @deprecated Use `providerOptions` instead.
459
- */
460
- experimental_providerMetadata?: ProviderMetadata;
461
- };
462
- /**
463
- A user message. It can contain text or a combination of text and images.
464
- */
465
- type CoreUserMessage = {
466
- role: 'user';
467
- content: UserContent;
468
- /**
469
- Additional provider-specific metadata. They are passed through
470
- to the provider from the AI SDK and enable provider-specific
471
- functionality that can be fully encapsulated in the provider.
472
- */
473
- providerOptions?: ProviderOptions;
474
- /**
475
- @deprecated Use `providerOptions` instead.
476
- */
477
- experimental_providerMetadata?: ProviderMetadata;
478
- };
479
- /**
480
- Content of a user message. It can be a string or an array of text and image parts.
481
- */
482
- type UserContent = string | Array<TextPart | ImagePart | FilePart>;
483
- /**
484
- An assistant message. It can contain text, tool calls, or a combination of text and tool calls.
485
- */
486
- type CoreAssistantMessage = {
487
- role: 'assistant';
488
- content: AssistantContent;
489
- /**
490
- Additional provider-specific metadata. They are passed through
491
- to the provider from the AI SDK and enable provider-specific
492
- functionality that can be fully encapsulated in the provider.
493
- */
494
- providerOptions?: ProviderOptions;
495
- /**
496
- @deprecated Use `providerOptions` instead.
497
- */
498
- experimental_providerMetadata?: ProviderMetadata;
499
- };
500
- /**
501
- Content of an assistant message.
502
- It can be a string or an array of text, image, reasoning, redacted reasoning, and tool call parts.
503
- */
504
- type AssistantContent = string | Array<TextPart | FilePart | ReasoningPart | RedactedReasoningPart | ToolCallPart>;
505
- /**
506
- A tool message. It contains the result of one or more tool calls.
507
- */
508
- type CoreToolMessage = {
509
- role: 'tool';
510
- content: ToolContent;
511
- /**
512
- Additional provider-specific metadata. They are passed through
513
- to the provider from the AI SDK and enable provider-specific
514
- functionality that can be fully encapsulated in the provider.
515
- */
516
- providerOptions?: ProviderOptions;
517
- /**
518
- @deprecated Use `providerOptions` instead.
519
- */
520
- experimental_providerMetadata?: ProviderMetadata;
521
- };
522
- /**
523
- Content of a tool message. It is an array of tool result parts.
524
- */
525
- type ToolContent = Array<ToolResultPart>;
526
- /**
527
- A message that can be used in the `messages` field of a prompt.
528
- It can be a user message, an assistant message, or a tool message.
529
- */
530
- type CoreMessage = CoreSystemMessage | CoreUserMessage | CoreAssistantMessage | CoreToolMessage;
531
-
532
- /**
533
- Prompt part of the AI function options.
534
- It contains a system message, a simple text prompt, or a list of messages.
535
- */
536
- type Prompt = {
537
- /**
538
- System message to include in the prompt. Can be used with `prompt` or `messages`.
539
- */
540
- system?: string;
541
- /**
542
- A simple text prompt. You can either use `prompt` or `messages` but not both.
543
- */
544
- prompt?: string;
545
- /**
546
- A list of messages. You can either use `prompt` or `messages` but not both.
547
- */
548
- messages?: Array<CoreMessage> | Array<Omit<Message, 'id'>>;
549
- };
550
-
551
- type Streamable = ReactNode | Promise<ReactNode>;
552
- type Renderer<T extends Array<any>> = (...args: T) => Streamable | Generator<Streamable, Streamable, void> | AsyncGenerator<Streamable, Streamable, void>;
553
- type RenderTool<PARAMETERS extends z.ZodTypeAny = any> = {
554
- description?: string;
555
- parameters: PARAMETERS;
556
- generate?: Renderer<[
557
- z.infer<PARAMETERS>,
558
- {
559
- toolName: string;
560
- toolCallId: string;
561
- }
562
- ]>;
563
- };
564
- type RenderText = Renderer<[
565
- {
566
- /**
567
- * The full text content from the model so far.
568
- */
569
- content: string;
570
- /**
571
- * The new appended text content from the model since the last `text` call.
572
- */
573
- delta: string;
574
- /**
575
- * Whether the model is done generating text.
576
- * If `true`, the `content` will be the final output and this call will be the last.
577
- */
578
- done: boolean;
579
- }
580
- ]>;
581
- type RenderResult = {
582
- value: ReactNode;
583
- } & Awaited<ReturnType<LanguageModelV2['doStream']>>;
584
- /**
585
- * `streamUI` is a helper function to create a streamable UI from LLMs.
586
- */
587
- declare function streamUI<TOOLS extends {
588
- [name: string]: z.ZodTypeAny;
589
- } = {}>({ model, tools, toolChoice, system, prompt, messages, maxRetries, abortSignal, headers, initial, text, experimental_providerMetadata, providerOptions, onFinish, ...settings }: CallSettings & Prompt & {
590
- /**
591
- * The language model to use.
592
- */
593
- model: LanguageModelV2;
594
- /**
595
- * The tools that the model can call. The model needs to support calling tools.
596
- */
597
- tools?: {
598
- [name in keyof TOOLS]: RenderTool<TOOLS[name]>;
599
- };
600
- /**
601
- * The tool choice strategy. Default: 'auto'.
602
- */
603
- toolChoice?: ToolChoice<TOOLS>;
604
- text?: RenderText;
605
- initial?: ReactNode;
606
- /**
607
- Additional provider-specific options. They are passed through
608
- to the provider from the AI SDK and enable provider-specific
609
- functionality that can be fully encapsulated in the provider.
610
- */
611
- providerOptions?: ProviderOptions;
612
- /**
613
- @deprecated Use `providerOptions` instead.
614
- */
615
- experimental_providerMetadata?: ProviderMetadata;
616
- /**
617
- * Callback that is called when the LLM response and the final object validation are finished.
618
- */
619
- onFinish?: (event: {
620
- /**
621
- * The reason why the generation finished.
622
- */
623
- finishReason: FinishReason;
624
- /**
625
- * The token usage of the generated response.
626
- */
627
- usage: LanguageModelUsage;
628
- /**
629
- * The final ui node that was generated.
630
- */
631
- value: ReactNode;
632
- /**
633
- * Warnings from the model provider (e.g. unsupported settings)
634
- */
635
- warnings?: CallWarning[];
636
- /**
637
- * Optional raw response data.
638
- */
639
- rawResponse?: {
640
- /**
641
- * Response headers.
642
- */
643
- headers?: Record<string, string>;
644
- };
645
- }) => Promise<void> | void;
646
- }): Promise<RenderResult>;
647
-
648
- type StreamableUIWrapper = {
649
- /**
650
- * The value of the streamable UI. This can be returned from a Server Action and received by the client.
651
- */
652
- readonly value: React.ReactNode;
653
- /**
654
- * This method updates the current UI node. It takes a new UI node and replaces the old one.
655
- */
656
- update(value: React.ReactNode): StreamableUIWrapper;
657
- /**
658
- * This method is used to append a new UI node to the end of the old one.
659
- * Once appended a new UI node, the previous UI node cannot be updated anymore.
660
- *
661
- * @example
662
- * ```jsx
663
- * const ui = createStreamableUI(<div>hello</div>)
664
- * ui.append(<div>world</div>)
665
- *
666
- * // The UI node will be:
667
- * // <>
668
- * // <div>hello</div>
669
- * // <div>world</div>
670
- * // </>
671
- * ```
672
- */
673
- append(value: React.ReactNode): StreamableUIWrapper;
674
- /**
675
- * This method is used to signal that there is an error in the UI stream.
676
- * It will be thrown on the client side and caught by the nearest error boundary component.
677
- */
678
- error(error: any): StreamableUIWrapper;
679
- /**
680
- * This method marks the UI node as finalized. You can either call it without any parameters or with a new UI node as the final state.
681
- * Once called, the UI node cannot be updated or appended anymore.
682
- *
683
- * This method is always **required** to be called, otherwise the response will be stuck in a loading state.
684
- */
685
- done(...args: [React.ReactNode] | []): StreamableUIWrapper;
686
- };
687
- /**
688
- * Create a piece of changeable UI that can be streamed to the client.
689
- * On the client side, it can be rendered as a normal React node.
690
- */
691
- declare function createStreamableUI(initialValue?: React.ReactNode): StreamableUIWrapper;
692
-
693
- declare const __internal_curr: unique symbol;
694
- declare const __internal_error: unique symbol;
695
- /**
696
- * StreamableValue is a value that can be streamed over the network via AI Actions.
697
- * To read the streamed values, use the `readStreamableValue` or `useStreamableValue` APIs.
698
- */
699
- type StreamableValue<T = any, E = any> = {
700
- [__internal_curr]?: T;
701
- [__internal_error]?: E;
702
- };
703
-
704
- /**
705
- * Create a wrapped, changeable value that can be streamed to the client.
706
- * On the client side, the value can be accessed via the readStreamableValue() API.
707
- */
708
- declare function createStreamableValue<T = any, E = any>(initialValue?: T | ReadableStream<T>): StreamableValueWrapper<T, E>;
709
- type StreamableValueWrapper<T, E> = {
710
- /**
711
- * The value of the streamable. This can be returned from a Server Action and
712
- * received by the client. To read the streamed values, use the
713
- * `readStreamableValue` or `useStreamableValue` APIs.
714
- */
715
- readonly value: StreamableValue<T, E>;
716
- /**
717
- * This method updates the current value with a new one.
718
- */
719
- update(value: T): StreamableValueWrapper<T, E>;
720
- /**
721
- * This method is used to append a delta string to the current value. It
722
- * requires the current value of the streamable to be a string.
723
- *
724
- * @example
725
- * ```jsx
726
- * const streamable = createStreamableValue('hello');
727
- * streamable.append(' world');
728
- *
729
- * // The value will be 'hello world'
730
- * ```
731
- */
732
- append(value: T): StreamableValueWrapper<T, E>;
733
- /**
734
- * This method is used to signal that there is an error in the value stream.
735
- * It will be thrown on the client side when consumed via
736
- * `readStreamableValue` or `useStreamableValue`.
737
- */
738
- error(error: any): StreamableValueWrapper<T, E>;
739
- /**
740
- * This method marks the value as finalized. You can either call it without
741
- * any parameters or with a new value as the final state.
742
- * Once called, the value cannot be updated or appended anymore.
743
- *
744
- * This method is always **required** to be called, otherwise the response
745
- * will be stuck in a loading state.
746
- */
747
- done(...args: [T] | []): StreamableValueWrapper<T, E>;
748
- };
749
-
750
- /**
751
- * `readStreamableValue` takes a streamable value created via the `createStreamableValue().value` API,
752
- * and returns an async iterator.
753
- *
754
- * ```js
755
- * // Inside your AI action:
756
- *
757
- * async function action() {
758
- * 'use server'
759
- * const streamable = createStreamableValue();
760
- *
761
- * streamable.update(1);
762
- * streamable.update(2);
763
- * streamable.done(3);
764
- * // ...
765
- * return streamable.value;
766
- * }
767
- * ```
768
- *
769
- * And to read the value:
770
- *
771
- * ```js
772
- * const streamableValue = await action()
773
- * for await (const v of readStreamableValue(streamableValue)) {
774
- * console.log(v)
775
- * }
776
- * ```
777
- *
778
- * This logs out 1, 2, 3 on console.
779
- */
780
- declare function readStreamableValue<T = unknown>(streamableValue: StreamableValue<T>): AsyncIterable<T | undefined>;
781
-
782
- /**
783
- * `useStreamableValue` is a React hook that takes a streamable value created via the `createStreamableValue().value` API,
784
- * and returns the current value, error, and pending state.
785
- *
786
- * This is useful for consuming streamable values received from a component's props. For example:
787
- *
788
- * ```js
789
- * function MyComponent({ streamableValue }) {
790
- * const [data, error, pending] = useStreamableValue(streamableValue);
791
- *
792
- * if (pending) return <div>Loading...</div>;
793
- * if (error) return <div>Error: {error.message}</div>;
794
- *
795
- * return <div>Data: {data}</div>;
796
- * }
797
- * ```
798
- */
799
- declare function useStreamableValue<T = unknown, Error = unknown>(streamableValue?: StreamableValue<T>): [data: T | undefined, error: Error | undefined, pending: boolean];
800
-
801
- declare function useUIState<AI extends AIProvider = any>(): [InferUIState<AI, any>, (v: InferUIState<AI, any> | ((v_: InferUIState<AI, any>) => InferUIState<AI, any>)) => void];
802
- declare function useAIState<AI extends AIProvider = any>(): [
803
- InferAIState<AI, any>,
804
- (newState: ValueOrUpdater<InferAIState<AI, any>>) => void
805
- ];
806
- declare function useAIState<AI extends AIProvider = any>(key: keyof InferAIState<AI, any>): [
807
- InferAIState<AI, any>[typeof key],
808
- (newState: ValueOrUpdater<InferAIState<AI, any>[typeof key]>) => void
809
- ];
810
- declare function useActions<AI extends AIProvider = any>(): InferActions<AI, any>;
811
- declare function useSyncUIState(): () => Promise<void>;
812
-
813
- export { StreamableValue, createAI, createStreamableUI, createStreamableValue, getAIState, getMutableAIState, readStreamableValue, streamUI, useAIState, useActions, useStreamableValue, useSyncUIState, useUIState };