xsAI SDK v0.4.x Quick Reference

xsAI is an extra-small AI SDK with OpenAI-compatible API interface, similar to Vercel AI SDK but much smaller.

Project packages: @xsai/generate-text, @xsai/stream-text, @xsai/model

Core APIs

streamText (sync call, returns StreamTextResult)

typescript

import { streamText } from "@xsai/stream-text"

// NOTE: streamText is SYNCHRONOUS (not async) in 0.4.x
const { textStream } = streamText({
  apiKey: "...",
  baseURL: "https://api.openai.com/v1/",
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello" },
  ],
  streamOptions: { includeUsage: true },
})

// textStream is a ReadableStream<string>, supports async iteration
for await (const textPart of textStream) {
  console.log(textPart)
}

Types:

typescript

interface StreamTextResult {
  textStream: ReadableStream<string>
  fullStream: ReadableStream<StreamTextEvent>
  reasoningTextStream: ReadableStream<string>
  messages: Promise<Message[]>
  steps: Promise<CompletionStep[]>
  usage: Promise<undefined | Usage>
  totalUsage: Promise<undefined | Usage>
}

interface StreamTextOptions extends ChatOptions {
  maxSteps?: number  // default: 1
  onEvent?: (event: StreamTextEvent) => Promise<unknown> | unknown
  onFinish?: (step?: CompletionStep) => Promise<unknown> | unknown
  onStepFinish?: (step: CompletionStep) => Promise<unknown> | unknown
  streamOptions?: { includeUsage?: boolean }
}

// StreamTextEvent replaces the old StreamTextChunkResult
type StreamTextEvent = /* union of stream event types */

generateText (async call)

typescript

import { generateText } from "@xsai/generate-text"

const { text, usage } = await generateText({
  apiKey: "...",
  baseURL: "https://api.openai.com/v1/",
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Why is the sky blue?" },
  ],
})

Types:

typescript

interface GenerateTextResult {
  text?: string  // NOTE: optional in 0.4.x (was required in 0.2.x)
  usage: Usage
  finishReason: FinishReason
  messages: Message[]
  steps: CompletionStep<true>[]
  toolCalls: CompletionToolCall[]
  toolResults: CompletionToolResult[]
  reasoningText?: string
}

listModels (async call)

typescript

import { listModels } from "@xsai/model"

const models = await listModels({
  apiKey: "...",
  baseURL: "https://api.openai.com/v1/",
})
// Returns Model[] with { id, object, created, owned_by }

Shared Types

typescript

// From @xsai/shared-chat
interface ChatOptions {
  apiKey?: string
  baseURL: string
  model: string
  messages: Message[]
  // ... other OpenAI-compatible options
}

interface Usage {
  prompt_tokens: number
  completion_tokens: number
  total_tokens: number
}

type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage | DeveloperMessage

Breaking Changes from 0.2.0-beta.3

Change	0.2.0-beta.3	0.4.x
`streamText` call	`await streamText()` (async)	`streamText()` (sync)
`StreamTextResult`	`{ textStream, chunkStream }`	`{ textStream, fullStream, usage: Promise, ... }`
Usage retrieval	Iterate `chunkStream` chunks	`await result.usage`
`StreamTextChunkResult`	Exists	Removed, replaced by `StreamTextEvent`
`textStream` type	Required `as unknown as AsyncIterable` cast	Native `ReadableStream`, supports `for await` and `pipeThrough()`
`generateText` result `.text`	`string`	`string \| undefined`

Utils

smoothStream (from @xsai/utils-stream)

typescript

import { smoothStream } from "@xsai/utils-stream"

const smoothed = textStream.pipeThrough(smoothStream({
  delay: 20,
  chunking: "line",
}))

toAsyncIterator (polyfill for Safari)

typescript

import { toAsyncIterator } from "@xsai/utils-stream"

// For browsers that don't support ReadableStream async iteration
const iterableStream = toAsyncIterator(textStream)

Reference Documentation

•references/index.md - Full documentation index with all examples
•references/docs/ - Individual package documentation (27 files with complete code examples)
•references/type-defs/ - Deno Doc type definitions from esm.sh