streamObject() - core-ai

Overview

The streamObject() function streams structured objects from chat models in real-time. It emits the raw JSON text as it arrives, then the final object. With a Standard Schema, such as a Zod 4.2+ schema, core-ai validates the final object. This is ideal for displaying partial results as they’re being generated.

Function signature

export async function streamObject<TSchema extends SchemaInput>(
    params: StreamObjectParams<TSchema>
): Promise<ObjectStream<TSchema>>

export type StreamObjectParams<TSchema extends SchemaInput> =
    StreamObjectOptions<TSchema> & {
        model: ChatModel;
    };

Parameters

ChatModel

required

The chat model instance to use for streaming.

Message[]

required

Array of messages in the conversation. Must not be empty.

SchemaInput

required

Schema of the object to generate: a Standard Schema with JSON Schema support, such as a Zod 4.2+ schema, or plain JSON Schema. See Schemas for the supported libraries.

string

Optional name for the schema.

string

Optional description of the schema.

number

Sampling temperature (0-2).

number

Total output allowance for the response, covering reasoning tokens and the visible answer. When omitted, the model’s output ceiling applies. If the value cannot hold the reasoning budget of the requested effort, the call throws a ValidationError. See maxTokens.

number

Nucleus sampling parameter (0-1).

ReasoningConfig

Configuration for extended thinking/reasoning capabilities.

GenerateProviderOptions

Provider-specific options, namespaced by provider name.

AbortSignal

AbortSignal for cancelling the stream.

Return value

Returns a Promise<ObjectStream<TSchema>>. ObjectStream is an async iterable of ObjectStreamEvent objects with two additional properties:

type ObjectStream<TSchema extends SchemaInput> = AsyncIterable<
    ObjectStreamEvent<TSchema>
> & {
    readonly result: Promise<GenerateObjectResult<TSchema>>;
    readonly events: Promise<readonly ObjectStreamEvent<TSchema>[]>;
};

Promise<GenerateObjectResult<TSchema>>

Resolves with the final object result when the stream completes. Rejects on abort, upstream failure, or a structured output error.

Promise<readonly ObjectStreamEvent<TSchema>[]>

Resolves with all observed events, including abort and failure cases.

The HTTP request starts as soon as you create the stream. You do not need to iterate before the model begins responding.

ObjectStreamEvent types

{ type: 'object-delta'; text: string }

Emitted for each chunk of the JSON object being generated. The text is raw and unvalidated.

{ type: 'object'; object: InferSchemaOutput<TSchema> }

Emitted once with the final object. For a Standard Schema, object is the validated output of the schema. For plain JSON Schema, it is the parsed JSON, typed unknown and not validated.

{ type: 'finish'; finishReason: FinishReason; usage: ChatUsage }

Emitted when streaming completes with final metadata.

Examples

Basic streaming object

import { streamObject } from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';
import { z } from 'zod';

const openai = createOpenAI();
const model = openai.chatModel('gpt-5-mini');

const schema = z.object({
  name: z.string(),
  age: z.number(),
  bio: z.string()
});

const objectStream = await streamObject({
  model,
  messages: [
    { role: 'user', content: 'Generate a character profile' }
  ],
  schema
});

for await (const event of objectStream) {
  if (event.type === 'object-delta') {
    process.stdout.write(event.text);
  } else if (event.type === 'object') {
    console.log('\n\nComplete object:', event.object);
  }
}

Progressive UI updates

const schema = z.object({
  tasks: z.array(
    z.object({
      title: z.string(),
      description: z.string(),
      priority: z.enum(['low', 'medium', 'high'])
    })
  )
});

const objectStream = await streamObject({
  model,
  messages: [
    { role: 'user', content: 'Create a project task list' }
  ],
  schema
});

let partialJson = '';

for await (const event of objectStream) {
  switch (event.type) {
    case 'object-delta':
      partialJson += event.text;
      updatePreview(partialJson);
      break;
    
    case 'object':
      displayTasks(event.object.tasks);
      break;
    
    case 'finish':
      console.log('Tokens used:', event.usage.outputTokens);
      break;
  }
}

Using .result

const objectStream = await streamObject({
  model,
  messages: [
    { role: 'user', content: 'Generate a user profile' }
  ],
  schema: z.object({
    username: z.string(),
    email: z.string().email()
  })
});

const finalResult = await objectStream.result;
console.log(finalResult.object);
console.log('Usage:', finalResult.usage);

Using .events

const objectStream = await streamObject({
  model,
  messages: [{ role: 'user', content: 'Generate a user profile' }],
  schema
});

const events = await objectStream.events;
console.log(events.map((event) => event.type));

ObjectStream follows the same lifecycle semantics as ChatStream: .result settles independently of iteration, .events keeps the observed history, and iteration is replayable.

Cancellation

const controller = new AbortController();

const objectStream = await streamObject({
  model,
  messages: [
    { role: 'user', content: 'Generate a large dataset' }
  ],
  schema: z.object({
    data: z.array(z.object({
      id: z.number(),
      value: z.string()
    }))
  }),
  signal: controller.signal
});

setTimeout(() => controller.abort(), 5000);

try {
  for await (const event of objectStream) {
    if (event.type === 'object-delta') {
      process.stdout.write(event.text);
    }
  }
} catch (error) {
  console.log('\nStream cancelled');
}

Important notes

ObjectStream is replayable: iterating after events have already arrived replays the buffered event history.

The object event is emitted once with the complete object. core-ai validates only this final object, never the deltas. Use object-delta events to show progressive updates while the JSON payload is still streaming.

Error handling

Throws ValidationError if:

Messages array is empty
The schema cannot be converted to JSON Schema

May also throw:

CoreAIError if the stream completes without generating an object
ProviderError if the provider returns an error during streaming

May also throw structured output errors:

StructuredOutputValidationError if the final object does not match a Standard Schema
StructuredOutputParseError if the output is not valid JSON
StructuredOutputNoObjectGeneratedError if the model returns no object

import { 
  ValidationError,
  StructuredOutputValidationError 
} from '@core-ai/core-ai';

try {
  const objectStream = await streamObject({
    model,
    messages: [{ role: 'user', content: 'Generate data' }],
    schema: z.object({ name: z.string() })
  });
  
  for await (const event of objectStream) {
    // Process events
  }
} catch (error) {
  if (error instanceof StructuredOutputValidationError) {
    console.error('Validation failed:', error.issues);
  } else if (error instanceof ValidationError) {
    console.error('Stream failed:', error.message);
  }
}

​Overview

​Function signature

​Parameters

​Return value

​ObjectStreamEvent types

​Examples

​Basic streaming object

​Progressive UI updates

​Using .result

​Using .events

​Cancellation

​Important notes

​Error handling

Overview

Function signature

Parameters

Return value

ObjectStreamEvent types

Examples

Basic streaming object

Progressive UI updates

Using .result

Using .events

Cancellation

Important notes

Error handling