feat (ai/core): export callback types (#4800)

.changeset/lucky-scissors-fix.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+feat (ai/core): export callback types

content/docs/07-reference/01-ai-sdk-core/01-generate-text.mdx

@@ -564,12 +564,12 @@ To see `generateText` in action, check out [these examples](#examples).
     },
     {
       name: 'onStepFinish',
-      type: '(result: onStepFinishResult) => Promise<void> | void',
+      type: '(result: OnStepFinishResult) => Promise<void> | void',
       isOptional: true,
       description: 'Callback that is called when a step is finished.',
       properties: [
         {
-          type: 'onStepFinishResult',
+          type: 'OnStepFinishResult',
           parameters: [
             {
               name: 'stepType',

packages/ai/core/generate-object/index.ts

@@ -1,6 +1,7 @@
 export { generateObject } from './generate-object';
 export type { GenerateObjectResult } from './generate-object-result';
 export { streamObject } from './stream-object';
+export type { StreamObjectOnFinishCallback } from './stream-object';
 export type {
   ObjectStreamPart,
   StreamObjectResult,

packages/ai/core/generate-object/stream-object.ts

@@ -56,7 +56,7 @@ import { validateObjectGenerationInput } from './validate-object-generation-inpu
 
 const originalGenerateId = createIdGenerator({ prefix: 'aiobj', size: 24 });
 
-type OnFinishCallback<RESULT> = (event: {
+export type StreamObjectOnFinishCallback<RESULT> = (event: {
   /**
 The token usage of the generated response.
 */
@@ -167,7 +167,7 @@ functionality that can be fully encapsulated in the provider.
       /**
 Callback that is called when the LLM response and the final object validation are finished.
      */
-      onFinish?: OnFinishCallback<OBJECT>;
+      onFinish?: StreamObjectOnFinishCallback<OBJECT>;
 
       /**
        * Internal. For test use only. May change without notice.
@@ -251,7 +251,7 @@ functionality that can be fully encapsulated in the provider.
       /**
 Callback that is called when the LLM response and the final object validation are finished.
      */
-      onFinish?: OnFinishCallback<Array<ELEMENT>>;
+      onFinish?: StreamObjectOnFinishCallback<Array<ELEMENT>>;
 
       /**
        * Internal. For test use only. May change without notice.
@@ -310,7 +310,7 @@ functionality that can be fully encapsulated in the provider.
       /**
 Callback that is called when the LLM response and the final object validation are finished.
      */
-      onFinish?: OnFinishCallback<JSONValue>;
+      onFinish?: StreamObjectOnFinishCallback<JSONValue>;
 
       /**
        * Internal. For test use only. May change without notice.
@@ -366,7 +366,7 @@ export function streamObject<SCHEMA, PARTIAL, RESULT, ELEMENT_STREAM>({
     experimental_telemetry?: TelemetrySettings;
     providerOptions?: ProviderOptions;
     experimental_providerMetadata?: ProviderMetadata;
-    onFinish?: OnFinishCallback<RESULT>;
+    onFinish?: StreamObjectOnFinishCallback<RESULT>;
     _internal?: {
       generateId?: () => string;
       currentDate?: () => Date;
@@ -469,7 +469,7 @@ class DefaultStreamObjectResult<PARTIAL, RESULT, ELEMENT_STREAM>
     schemaDescription: string | undefined;
     providerOptions: ProviderOptions | undefined;
     mode: 'auto' | 'json' | 'tool' | undefined;
-    onFinish: OnFinishCallback<RESULT> | undefined;
+    onFinish: StreamObjectOnFinishCallback<RESULT> | undefined;
     generateId: () => string;
     currentDate: () => Date;
     now: () => number;

packages/ai/core/generate-text/generate-text.ts

@@ -45,6 +45,15 @@ const originalGenerateMessageId = createIdGenerator({
   size: 24,
 });
 
+/**
+Callback that is set using the `onStepFinish` option.
+
+@param stepResult - The result of the step.
+ */
+export type GenerateTextOnStepFinishCallback<TOOLS extends ToolSet> = (
+  stepResult: StepResult<TOOLS>,
+) => Promise<void> | void;
+
 /**
 Generate a text and call tools for a given prompt using a language model.
 
@@ -195,7 +204,7 @@ A function that attempts to repair a tool call that failed to parse.
     /**
     Callback that is called when each step (LLM call) is finished, including intermediate steps.
     */
-    onStepFinish?: (event: StepResult<TOOLS>) => Promise<void> | void;
+    onStepFinish?: GenerateTextOnStepFinishCallback<TOOLS>;
 
     /**
      * Internal. For test use only. May change without notice.

packages/ai/core/generate-text/index.ts

@@ -1,19 +1,25 @@
 export { generateText } from './generate-text';
+export type { GenerateTextOnStepFinishCallback } from './generate-text';
 export type { GenerateTextResult } from './generate-text-result';
 export * as Output from './output';
 export { smoothStream } from './smooth-stream';
 export type { StepResult } from './step-result';
 export { streamText } from './stream-text';
-export type { StreamTextTransform } from './stream-text';
+export type {
+  StreamTextOnChunkCallback,
+  StreamTextOnErrorCallback,
+  StreamTextOnFinishCallback,
+  StreamTextOnStepFinishCallback,
+  StreamTextTransform,
+} from './stream-text';
 export type { StreamTextResult, TextStreamPart } from './stream-text-result';
-export type { ToolCallRepairFunction } from './tool-call-repair';
-
 export type {
   CoreToolCall,
   CoreToolCallUnion,
   ToolCall,
   ToolCallUnion,
 } from './tool-call';
+export type { ToolCallRepairFunction } from './tool-call-repair';
 export type {
   CoreToolResult,
   CoreToolResultUnion,

packages/ai/core/generate-text/stream-text.ts

@@ -77,6 +77,59 @@ export type StreamTextTransform<TOOLS extends ToolSet> = (options: {
   stopStream: () => void;
 }) => TransformStream<TextStreamPart<TOOLS>, TextStreamPart<TOOLS>>;
 
+/**
+Callback that is set using the `onError` option.
+
+@param event - The event that is passed to the callback.
+ */
+export type StreamTextOnErrorCallback = (event: {
+  error: unknown;
+}) => Promise<void> | void;
+
+/**
+Callback that is set using the `onStepFinish` option.
+
+@param stepResult - The result of the step.
+ */
+export type StreamTextOnStepFinishCallback<TOOLS extends ToolSet> = (
+  stepResult: StepResult<TOOLS>,
+) => Promise<void> | void;
+
+/**
+Callback that is set using the `onChunk` option.
+
+@param event - The event that is passed to the callback.
+ */
+export type StreamTextOnChunkCallback<TOOLS extends ToolSet> = (event: {
+  chunk: Extract<
+    TextStreamPart<TOOLS>,
+    {
+      type:
+        | 'text-delta'
+        | 'reasoning'
+        | 'source'
+        | 'tool-call'
+        | 'tool-call-streaming-start'
+        | 'tool-call-delta'
+        | 'tool-result';
+    }
+  >;
+}) => Promise<void> | void;
+
+/**
+Callback that is set using the `onFinish` option.
+
+@param event - The event that is passed to the callback.
+ */
+export type StreamTextOnFinishCallback<TOOLS extends ToolSet> = (
+  event: Omit<StepResult<TOOLS>, 'stepType' | 'isContinued'> & {
+    /**
+Details for all steps.
+   */
+    readonly steps: StepResult<TOOLS>[];
+  },
+) => Promise<void> | void;
+
 /**
 Generate a text and call tools for a given prompt using a language model.
 
@@ -253,48 +306,30 @@ The stream transformations must maintain the stream structure for streamText to
       | Array<StreamTextTransform<TOOLS>>;
 
     /**
-Callback that is called for each chunk of the stream. The stream processing will pause until the callback promise is resolved.
+Callback that is called for each chunk of the stream.
+The stream processing will pause until the callback promise is resolved.
      */
-    onChunk?: (event: {
-      chunk: Extract<
-        TextStreamPart<TOOLS>,
-        {
-          type:
-            | 'text-delta'
-            | 'reasoning'
-            | 'source'
-            | 'tool-call'
-            | 'tool-call-streaming-start'
-            | 'tool-call-delta'
-            | 'tool-result';
-        }
-      >;
-    }) => Promise<void> | void;
+    onChunk?: StreamTextOnChunkCallback<TOOLS>;
 
     /**
-Callback that is invoked when an error occurs during streaming. You can use it to log errors.
+Callback that is invoked when an error occurs during streaming.
+You can use it to log errors.
+The stream processing will pause until the callback promise is resolved.
      */
-    onError?: (event: { error: unknown }) => Promise<void> | void;
+    onError?: StreamTextOnErrorCallback;
 
     /**
 Callback that is called when the LLM response and all request tool executions
 (for tools that have an `execute` function) are finished.
 
 The usage is the combined usage of all steps.
      */
-    onFinish?: (
-      event: Omit<StepResult<TOOLS>, 'stepType' | 'isContinued'> & {
-        /**
-Details for all steps.
-       */
-        readonly steps: StepResult<TOOLS>[];
-      },
-    ) => Promise<void> | void;
+    onFinish?: StreamTextOnFinishCallback<TOOLS>;
 
     /**
 Callback that is called when each step (LLM call) is finished, including intermediate steps.
     */
-    onStepFinish?: (event: StepResult<TOOLS>) => Promise<void> | void;
+    onStepFinish?: StreamTextOnStepFinishCallback<TOOLS>;
 
     /**
 Internal. For test use only. May change without notice.
@@ -490,14 +525,14 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT, PARTIAL_OUTPUT>
     output,
     continueSteps,
     providerOptions,
-    onChunk,
-    onError,
-    onFinish,
-    onStepFinish,
     now,
     currentDate,
     generateId,
     generateMessageId,
+    onChunk,
+    onError,
+    onFinish,
+    onStepFinish,
   }: {
     model: LanguageModel;
     telemetry: TelemetrySettings | undefined;
@@ -518,38 +553,16 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT, PARTIAL_OUTPUT>
     output: Output<OUTPUT, PARTIAL_OUTPUT> | undefined;
     continueSteps: boolean;
     providerOptions: ProviderOptions | undefined;
-    onChunk:
-      | undefined
-      | ((event: {
-          chunk: Extract<
-            TextStreamPart<TOOLS>,
-            {
-              type:
-                | 'text-delta'
-                | 'reasoning'
-                | 'source'
-                | 'tool-call'
-                | 'tool-call-streaming-start'
-                | 'tool-call-delta'
-                | 'tool-result';
-            }
-          >;
-        }) => Promise<void> | void);
-    onError: undefined | ((event: { error: unknown }) => Promise<void> | void);
-    onFinish:
-      | undefined
-      | ((
-          event: Omit<StepResult<TOOLS>, 'stepType' | 'isContinued'> & {
-            readonly steps: StepResult<TOOLS>[];
-          },
-        ) => Promise<void> | void);
-    onStepFinish:
-      | undefined
-      | ((event: StepResult<TOOLS>) => Promise<void> | void);
     now: () => number;
     currentDate: () => Date;
     generateId: () => string;
     generateMessageId: () => string;
+
+    // callbacks:
+    onChunk: undefined | StreamTextOnChunkCallback<TOOLS>;
+    onError: undefined | StreamTextOnErrorCallback;
+    onFinish: undefined | StreamTextOnFinishCallback<TOOLS>;
+    onStepFinish: undefined | StreamTextOnStepFinishCallback<TOOLS>;
   }) {
     if (maxSteps < 1) {
       throw new InvalidArgumentError({