@ai-sdk/langchain 2.0.87 → 2.0.88

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ai-sdk/langchain
 
+## 2.0.88
+
+### Patch Changes
+
+- 2b29f7a: Add `onFinish`, `onError`, and `onAbort` callbacks to `StreamCallbacks` for `toUIMessageStream`.
+
+  - `onFinish(state)`: Called on successful completion with final LangGraph state (or `undefined` for other stream types)
+  - `onError(error)`: Called when stream encounters an error
+  - `onAbort()`: Called when stream is aborted
+
+  Also adds `parseLangGraphEvent` helper for parsing LangGraph event tuples.
+
 ## 2.0.87
 
 ### Patch Changes

package/README.md

@@ -56,6 +56,30 @@ return createUIMessageStreamResponse({
 });
 ```
 
+### Streaming with Callbacks
+
+Use callbacks to access the final LangGraph state, handle errors, or detect aborts:
+
+```ts
+const langchainStream = await graph.stream(
+  { messages: langchainMessages },
+  { streamMode: ['values', 'messages'] },
+);
+
+return createUIMessageStreamResponse({
+  stream: toUIMessageStream<MyGraphState>(langchainStream, {
+    onFinish: async finalState => {
+      if (finalState) {
+        await saveConversation(finalState.messages);
+        await sendAnalytics(finalState);
+      }
+    },
+    onError: error => console.error('Stream failed:', error),
+    onAbort: () => console.log('Client disconnected'),
+  }),
+});
+```
+
 ### Streaming with `streamEvents`
 
 You can also use `toUIMessageStream` with `streamEvents()` for more granular event handling:
@@ -195,13 +219,21 @@ Converts AI SDK `ModelMessage` objects to LangChain `BaseMessage` objects.
 
 **Returns:** `BaseMessage[]`
 
-### `toUIMessageStream(stream)`
+### `toUIMessageStream(stream, callbacks?)`
 
 Converts a LangChain/LangGraph stream to an AI SDK `UIMessageStream`.
 
 **Parameters:**
 
 - `stream`: `AsyncIterable | ReadableStream` - A stream from LangChain `model.stream()`, LangGraph `graph.stream()`, or `streamEvents()`
+- `callbacks?`: `StreamCallbacks<TState>` - Optional lifecycle callbacks:
+  - `onStart()` - Called when stream initializes
+  - `onToken(token)` - Called for each token
+  - `onText(text)` - Called for each text chunk
+  - `onFinal(text)` - Called with aggregated text (on success, error, or abort)
+  - `onFinish(state)` - Called on success with LangGraph state (or `undefined` for other streams)
+  - `onError(error)` - Called when stream errors
+  - `onAbort()` - Called when stream is aborted
 
 **Returns:** `ReadableStream<UIMessageChunk>`
 

package/dist/index.d.mts

@@ -3,17 +3,26 @@ import { UIMessage, UIMessageChunk, ModelMessage, ChatTransport, ChatRequestOpti
 import { RemoteGraph, RemoteGraphParams } from '@langchain/langgraph/remote';
 
 /**
- * Configuration options and helper callback methods for stream lifecycle events.
+ * Callback options for stream lifecycle events.
  */
-interface StreamCallbacks {
-    /** `onStart`: Called once when the stream is initialized. */
+interface StreamCallbacks<TState = unknown> {
+    /** Called once when the stream is initialized. */
     onStart?: () => Promise<void> | void;
-    /** `onFinal`: Called once when the stream is closed with the final completion message. */
-    onFinal?: (completion: string) => Promise<void> | void;
-    /** `onToken`: Called for each tokenized message. */
+    /** Called for each tokenized message. */
     onToken?: (token: string) => Promise<void> | void;
-    /** `onText`: Called for each text chunk. */
+    /** Called for each text chunk. */
     onText?: (text: string) => Promise<void> | void;
+    /** Called with aggregated text when stream ends (success, error, or abort). */
+    onFinal?: (completion: string) => Promise<void> | void;
+    /**
+     * Called on successful completion. Receives final graph state for LangGraph
+     * streams (from last "values" event), undefined for other stream types.
+     */
+    onFinish?: (finalState: TState | undefined) => Promise<void> | void;
+    /** Called when the stream encounters an error. */
+    onError?: (error: Error) => Promise<void> | void;
+    /** Called when the stream is aborted. */
+    onAbort?: () => Promise<void> | void;
 }
 
 /**
@@ -81,9 +90,26 @@ declare function convertModelMessages(modelMessages: ModelMessage[]): BaseMessag
  * return createUIMessageStreamResponse({
  *   stream: toUIMessageStream(streamEvents),
  * });
+ *
+ * // With callbacks for LangGraph state
+ * const graphStream = await graph.stream(
+ *   { messages },
+ *   { streamMode: ['values', 'messages'] }
+ * );
+ * return createUIMessageStreamResponse({
+ *   stream: toUIMessageStream<MyStateType>(graphStream, {
+ *     onFinish: async (finalState) => {
+ *       if (finalState) {
+ *         await saveToDatabase(finalState);
+ *       }
+ *     },
+ *     onError: (error) => console.error('Stream failed:', error),
+ *     onAbort: () => console.log('Stream aborted'),
+ *   }),
+ * });
  * ```
  */
-declare function toUIMessageStream(stream: AsyncIterable<AIMessageChunk> | ReadableStream, callbacks?: StreamCallbacks): ReadableStream<UIMessageChunk>;
+declare function toUIMessageStream<TState = unknown>(stream: AsyncIterable<AIMessageChunk> | ReadableStream, callbacks?: StreamCallbacks<TState>): ReadableStream<UIMessageChunk>;
 
 /**
  * Options for configuring a LangSmith deployment transport.

package/dist/index.d.ts

@@ -3,17 +3,26 @@ import { UIMessage, UIMessageChunk, ModelMessage, ChatTransport, ChatRequestOpti
 import { RemoteGraph, RemoteGraphParams } from '@langchain/langgraph/remote';
 
 /**
- * Configuration options and helper callback methods for stream lifecycle events.
+ * Callback options for stream lifecycle events.
  */
-interface StreamCallbacks {
-    /** `onStart`: Called once when the stream is initialized. */
+interface StreamCallbacks<TState = unknown> {
+    /** Called once when the stream is initialized. */
     onStart?: () => Promise<void> | void;
-    /** `onFinal`: Called once when the stream is closed with the final completion message. */
-    onFinal?: (completion: string) => Promise<void> | void;
-    /** `onToken`: Called for each tokenized message. */
+    /** Called for each tokenized message. */
     onToken?: (token: string) => Promise<void> | void;
-    /** `onText`: Called for each text chunk. */
+    /** Called for each text chunk. */
     onText?: (text: string) => Promise<void> | void;
+    /** Called with aggregated text when stream ends (success, error, or abort). */
+    onFinal?: (completion: string) => Promise<void> | void;
+    /**
+     * Called on successful completion. Receives final graph state for LangGraph
+     * streams (from last "values" event), undefined for other stream types.
+     */
+    onFinish?: (finalState: TState | undefined) => Promise<void> | void;
+    /** Called when the stream encounters an error. */
+    onError?: (error: Error) => Promise<void> | void;
+    /** Called when the stream is aborted. */
+    onAbort?: () => Promise<void> | void;
 }
 
 /**
@@ -81,9 +90,26 @@ declare function convertModelMessages(modelMessages: ModelMessage[]): BaseMessag
  * return createUIMessageStreamResponse({
  *   stream: toUIMessageStream(streamEvents),
  * });
+ *
+ * // With callbacks for LangGraph state
+ * const graphStream = await graph.stream(
+ *   { messages },
+ *   { streamMode: ['values', 'messages'] }
+ * );
+ * return createUIMessageStreamResponse({
+ *   stream: toUIMessageStream<MyStateType>(graphStream, {
+ *     onFinish: async (finalState) => {
+ *       if (finalState) {
+ *         await saveToDatabase(finalState);
+ *       }
+ *     },
+ *     onError: (error) => console.error('Stream failed:', error),
+ *     onAbort: () => console.log('Stream aborted'),
+ *   }),
+ * });
  * ```
  */
-declare function toUIMessageStream(stream: AsyncIterable<AIMessageChunk> | ReadableStream, callbacks?: StreamCallbacks): ReadableStream<UIMessageChunk>;
+declare function toUIMessageStream<TState = unknown>(stream: AsyncIterable<AIMessageChunk> | ReadableStream, callbacks?: StreamCallbacks<TState>): ReadableStream<UIMessageChunk>;
 
 /**
  * Options for configuring a LangSmith deployment transport.

package/dist/index.js

@@ -33,6 +33,9 @@ var import_ai = require("ai");
 
 // src/utils.ts
 var import_messages = require("@langchain/core/messages");
+function parseLangGraphEvent(event) {
+  return event.length === 3 ? [event[1], event[2]] : [event[0], event[1]];
+}
 function convertToolResultPart(block) {
   const content = (() => {
     if (block.output.type === "text" || block.output.type === "error-text") {
@@ -462,7 +465,7 @@ function processLangGraphEvent(event, state, controller) {
     toolCallInfoByIndex,
     emittedToolCallsByKey
   } = state;
-  const [type, data] = event.length === 3 ? event.slice(1) : event;
+  const [type, data] = parseLangGraphEvent(event);
   switch (type) {
     case "custom": {
       let customTypeName = "custom";
@@ -922,8 +925,15 @@ function processStreamEventsEvent(event, state, controller) {
     }
   }
 }
+function isAbortError(error) {
+  if (error instanceof Error) {
+    return error.name === "AbortError" || error instanceof DOMException && error.name === "AbortError";
+  }
+  return false;
+}
 function toUIMessageStream(stream, callbacks) {
   const textChunks = [];
+  let lastValuesData;
   const modelState = {
     started: false,
     messageId: "langchain-msg-1",
@@ -979,7 +989,7 @@ function toUIMessageStream(stream, callbacks) {
   };
   return new ReadableStream({
     async start(controller) {
-      var _a, _b, _c, _d;
+      var _a, _b, _c, _d, _e, _f, _g, _h;
       await ((_a = callbacks == null ? void 0 : callbacks.onStart) == null ? void 0 : _a.call(callbacks));
       const wrappedController = createCallbackController(controller);
       controller.enqueue({ type: "start" });
@@ -1009,8 +1019,13 @@ function toUIMessageStream(stream, callbacks) {
               wrappedController
             );
           } else {
+            const eventArray = value;
+            const [type, data] = parseLangGraphEvent(eventArray);
+            if (type === "values") {
+              lastValuesData = data;
+            }
             processLangGraphEvent(
-              value,
+              eventArray,
               langGraphState,
               wrappedController
             );
@@ -1037,10 +1052,18 @@ function toUIMessageStream(stream, callbacks) {
           controller.enqueue({ type: "finish" });
         }
         await ((_d = callbacks == null ? void 0 : callbacks.onFinal) == null ? void 0 : _d.call(callbacks, textChunks.join("")));
+        await ((_e = callbacks == null ? void 0 : callbacks.onFinish) == null ? void 0 : _e.call(callbacks, lastValuesData));
       } catch (error) {
+        const errorObj = error instanceof Error ? error : new Error(String(error));
+        await ((_f = callbacks == null ? void 0 : callbacks.onFinal) == null ? void 0 : _f.call(callbacks, textChunks.join("")));
+        if (isAbortError(error)) {
+          await ((_g = callbacks == null ? void 0 : callbacks.onAbort) == null ? void 0 : _g.call(callbacks));
+        } else {
+          await ((_h = callbacks == null ? void 0 : callbacks.onError) == null ? void 0 : _h.call(callbacks, errorObj));
+        }
         controller.enqueue({
           type: "error",
-          errorText: error instanceof Error ? error.message : "Unknown error"
+          errorText: errorObj.message
         });
       } finally {
         controller.close();