ai 6.0.31 → 6.0.32

package/docs/07-reference/03-ai-sdk-rsc/02-create-ai.mdx

@@ -0,0 +1,90 @@
+---
+title: createAI
+description: Reference for the createAI function from the AI SDK RSC
+---
+
+# `createAI`
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+Creates a client-server context provider that can be used to wrap parts of your application tree to easily manage both UI and AI states of your application.
+
+## Import
+
+<Snippet text={`import { createAI } from "@ai-sdk/rsc"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'actions',
+      type: 'Record<string, Action>',
+      description: 'Server side actions that can be called from the client.',
+    },
+    {
+      name: 'initialAIState',
+      type: 'any',
+      description: 'Initial AI state to be used in the client.',
+    },
+    {
+      name: 'initialUIState',
+      type: 'any',
+      description: 'Initial UI state to be used in the client.',
+    },
+    {
+      name: 'onGetUIState',
+      type: '() => UIState',
+      description: 'is called during SSR to compare and update UI state.',
+    },
+    {
+      name: 'onSetAIState',
+      type: '(Event) => void',
+      description:
+        'is triggered whenever an update() or done() is called by the mutable AI state in your action, so you can safely store your AI state in the database.',
+      properties: [
+        {
+          type: 'Event',
+          parameters: [
+            {
+              name: 'state',
+              type: 'AIState',
+              description: 'The resulting AI state after the update.',
+            },
+            {
+              name: 'done',
+              type: 'boolean',
+              description:
+                'Whether the AI state updates have been finalized or not.',
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+### Returns
+
+It returns an `<AI/>` context provider.
+
+## Examples
+
+<ExampleLinks
+  examples={[
+    {
+      title: 'Learn to manage AI and UI states in Next.js',
+      link: '/examples/next-app/state-management/ai-ui-states',
+    },
+    {
+      title: 'Learn to persist and restore states UI/AI states in Next.js',
+      link: '/examples/next-app/state-management/save-and-restore-states',
+    },
+  ]}
+/>

package/docs/07-reference/03-ai-sdk-rsc/03-create-streamable-ui.mdx

@@ -0,0 +1,91 @@
+---
+title: createStreamableUI
+description: Reference for the createStreamableUI function from the AI SDK RSC
+---
+
+# `createStreamableUI`
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+Create a stream that sends UI from the server to the client. On the client side, it can be rendered as a normal React node.
+
+## Import
+
+<Snippet
+  text={`import { createStreamableUI } from "@ai-sdk/rsc"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'initialValue',
+      type: 'ReactNode',
+      isOptional: true,
+      description: 'The initial value of the streamable UI.',
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'value',
+      type: 'ReactNode',
+      description:
+        'The value of the streamable UI. This can be returned from a Server Action and received by the client.',
+    },
+  ]}
+/>
+
+### Methods
+
+<PropertiesTable
+  content={[
+    {
+      name: 'update',
+      type: '(ReactNode) => void',
+      description:
+        'Updates the current UI node. It takes a new UI node and replaces the old one.',
+    },
+    {
+      name: 'append',
+      type: '(ReactNode) => void',
+      description:
+        'Appends a new UI node to the end of the old one. Once appended a new UI node, the previous UI node cannot be updated anymore.',
+    },
+    {
+      name: 'done',
+      type: '(ReactNode | null) => void',
+      description:
+        'Marks the UI node as finalized and closes the stream. Once called, the UI node cannot be updated or appended anymore. This method is always required to be called, otherwise the response will be stuck in a loading state.',
+    },
+    {
+      name: 'error',
+      type: '(Error) => void',
+      description:
+        'Signals that there is an error in the UI stream. It will be thrown on the client side and caught by the nearest error boundary component.',
+    },
+  ]}
+/>
+
+## Examples
+
+<ExampleLinks
+  examples={[
+    {
+      title: 'Render a React component during a tool call',
+      link: '/examples/next-app/tools/render-interface-during-tool-call',
+    },
+  ]}
+/>

package/docs/07-reference/03-ai-sdk-rsc/04-create-streamable-value.mdx

@@ -0,0 +1,48 @@
+---
+title: createStreamableValue
+description: Reference for the createStreamableValue function from the AI SDK RSC
+---
+
+# `createStreamableValue`
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+Create a stream that sends values from the server to the client. The value can be any serializable data.
+
+## Import
+
+<Snippet
+  text={`import { createStreamableValue } from "@ai-sdk/rsc"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'value',
+      type: 'any',
+      description: 'Any data that RSC supports. Example, JSON.',
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'value',
+      type: 'streamable',
+      description:
+        'This creates a special value that can be returned from Actions to the client. It holds the data inside and can be updated via the update method.',
+    },
+  ]}
+/>

package/docs/07-reference/03-ai-sdk-rsc/05-read-streamable-value.mdx

@@ -0,0 +1,78 @@
+---
+title: readStreamableValue
+description: Reference for the readStreamableValue function from the AI SDK RSC
+---
+
+# `readStreamableValue`
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+It is a function that helps you read the streamable value from the client that was originally created using [`createStreamableValue`](/docs/reference/ai-sdk-rsc/create-streamable-value) on the server.
+
+## Import
+
+<Snippet
+  text={`import { readStreamableValue } from "@ai-sdk/rsc"`}
+  prompt={false}
+/>
+
+## Example
+
+```ts filename="app/actions.ts"
+async function generate() {
+  'use server';
+  const streamable = createStreamableValue();
+
+  streamable.update(1);
+  streamable.update(2);
+  streamable.done(3);
+
+  return streamable.value;
+}
+```
+
+```tsx filename="app/page.tsx" highlight="12"
+import { readStreamableValue } from '@ai-sdk/rsc';
+
+export default function Page() {
+  const [generation, setGeneration] = useState('');
+
+  return (
+    <div>
+      <button
+        onClick={async () => {
+          const stream = await generate();
+
+          for await (const delta of readStreamableValue(stream)) {
+            setGeneration(generation => generation + delta);
+          }
+        }}
+      >
+        Generate
+      </button>
+    </div>
+  );
+}
+```
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'stream',
+      type: 'StreamableValue',
+      description: 'The streamable value to read from.',
+    },
+  ]}
+/>
+
+### Returns
+
+It returns an async iterator that contains the values emitted by the streamable value.

package/docs/07-reference/03-ai-sdk-rsc/06-get-ai-state.mdx

@@ -0,0 +1,50 @@
+---
+title: getAIState
+description: Reference for the getAIState function from the AI SDK RSC
+---
+
+# `getAIState`
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+Get the current AI state.
+
+## Import
+
+<Snippet text={`import { getAIState } from "@ai-sdk/rsc"`} prompt={false} />
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'key',
+      type: 'string',
+      isOptional: true,
+      description:
+        "Returns the value of the specified key in the AI state, if it's an object.",
+    },
+  ]}
+/>
+
+### Returns
+
+The AI state.
+
+## Examples
+
+<ExampleLinks
+  examples={[
+    {
+      title:
+        'Learn to render a React component during a tool call made by a language model in Next.js',
+      link: '/examples/next-app/tools/render-interface-during-tool-call',
+    },
+  ]}
+/>

package/docs/07-reference/03-ai-sdk-rsc/07-get-mutable-ai-state.mdx

@@ -0,0 +1,70 @@
+---
+title: getMutableAIState
+description: Reference for the getMutableAIState function from the AI SDK RSC
+---
+
+# `getMutableAIState`
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+Get a mutable copy of the AI state. You can use this to update the state in the server.
+
+## Import
+
+<Snippet
+  text={`import { getMutableAIState } from "@ai-sdk/rsc"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'key',
+      isOptional: true,
+      type: 'string',
+      description:
+        "Returns the value of the specified key in the AI state, if it's an object.",
+    },
+  ]}
+/>
+
+### Returns
+
+The mutable AI state.
+
+### Methods
+
+<PropertiesTable
+  content={[
+    {
+      name: 'update',
+      type: '(newState: any) => void',
+      description: 'Updates the AI state with the new state.',
+    },
+    {
+      name: 'done',
+      type: '(newState: any) => void',
+      description:
+        'Updates the AI state with the new state, marks it as finalized and closes the stream.',
+    },
+  ]}
+/>
+
+## Examples
+
+<ExampleLinks
+  examples={[
+    {
+      title: 'Learn to persist and restore states AI and UI states in Next.js',
+      link: '/examples/next-app/state-management/save-and-restore-states',
+    },
+  ]}
+/>

package/docs/07-reference/03-ai-sdk-rsc/08-use-ai-state.mdx

@@ -0,0 +1,26 @@
+---
+title: useAIState
+description: Reference for the useAIState function from the AI SDK RSC
+---
+
+# `useAIState`
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+It is a hook that enables you to read and update the AI state. The AI state is shared globally between all `useAIState` hooks under the same `<AI/>` provider.
+
+The AI state is intended to contain context and information shared with the AI model, such as system messages, function responses, and other relevant data.
+
+## Import
+
+<Snippet text={`import { useAIState } from "@ai-sdk/rsc"`} prompt={false} />
+
+## API Signature
+
+### Returns
+
+A single element array where the first element is the current AI state.

package/docs/07-reference/03-ai-sdk-rsc/09-use-actions.mdx

@@ -0,0 +1,42 @@
+---
+title: useActions
+description: Reference for the useActions function from the AI SDK RSC
+---
+
+# `useActions`
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+It is a hook to help you access your Server Actions from the client. This is particularly useful for building interfaces that require user interactions with the server.
+
+It is required to access these server actions via this hook because they are patched when passed through the context. Accessing them directly may result in a [Cannot find Client Component error](/docs/troubleshooting/common-issues/server-actions-in-client-components).
+
+## Import
+
+<Snippet text={`import { useActions } from "@ai-sdk/rsc"`} prompt={false} />
+
+## API Signature
+
+### Returns
+
+`Record<string, Action>`, a dictionary of server actions.
+
+## Examples
+
+<ExampleLinks
+  examples={[
+    {
+      title: 'Learn to manage AI and UI states in Next.js',
+      link: '/examples/next-app/state-management/ai-ui-states',
+    },
+    {
+      title:
+        'Learn to route React components using a language model in Next.js',
+      link: '/examples/next-app/interface/route-components',
+    },
+  ]}
+/>

package/docs/07-reference/03-ai-sdk-rsc/10-use-ui-state.mdx

@@ -0,0 +1,35 @@
+---
+title: useUIState
+description: Reference for the useUIState function from the AI SDK RSC
+---
+
+# `useUIState`
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+It is a hook that enables you to read and update the UI State. The state is client-side and can contain functions, React nodes, and other data. UIState is the visual representation of the AI state.
+
+## Import
+
+<Snippet text={`import { useUIState } from "@ai-sdk/rsc"`} prompt={false} />
+
+## API Signature
+
+### Returns
+
+Similar to useState, it is an array, where the first element is the current UI state and the second element is the function that updates the state.
+
+## Examples
+
+<ExampleLinks
+  examples={[
+    {
+      title: 'Learn to manage AI and UI states in Next.js',
+      link: '/examples/next-app/state-management/ai-ui-states',
+    },
+  ]}
+/>

package/docs/07-reference/03-ai-sdk-rsc/11-use-streamable-value.mdx

@@ -0,0 +1,46 @@
+---
+title: useStreamableValue
+description: Reference for the useStreamableValue function from the AI SDK RSC
+---
+
+# `useStreamableValue`
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+It is a React hook that takes a streamable value created using [`createStreamableValue`](/docs/reference/ai-sdk-rsc/create-streamable-value) and returns the current value, error, and pending state.
+
+## Import
+
+<Snippet
+  text={`import { useStreamableValue } from "@ai-sdk/rsc"`}
+  prompt={false}
+/>
+
+## Example
+
+This is useful for consuming streamable values received from a component's props.
+
+```tsx
+function MyComponent({ streamableValue }) {
+  const [data, error, pending] = useStreamableValue(streamableValue);
+
+  if (pending) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <div>Data: {data}</div>;
+}
+```
+
+## API Signature
+
+### Parameters
+
+It accepts a streamable value created using `createStreamableValue`.
+
+### Returns
+
+It is an array, where the first element contains the data, the second element contains an error if it is thrown anytime during the stream, and the third is a boolean indicating if the value is pending.