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)

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:

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)

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:

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)

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

// 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

streamText

await streamText()

streamText()

StreamTextResult

{ textStream, chunkStream }

{ textStream, fullStream, usage: Promise, ... }

chunkStream

await result.usage

StreamTextChunkResult

StreamTextEvent

textStream

as unknown as AsyncIterable

ReadableStream

for await

pipeThrough()

generateText

.text

string

string | undefined

Utils

smoothStream (from @xsai/utils-stream)

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

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

toAsyncIterator (polyfill for Safari)

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