‏TanStack AI: استریم خروجی ساختاریافته با یک پراپ

وقتی از یه مدل زبانی (LLM) می‌خوای یه آبجکت JSON ساختاریافته بگیری، کاربر باید صبر کنه تا کل خروجی تولید بشه — و این تجربه کاربری بدیه. راه‌حل «استریم کردن» روی کاغذ سادست، ولی در عمل تا حالا یعنی نوشتن یه دسته کد glue: یه onChunk handler، یه useState، یه parsePartialJSON دستی، و cast کردن تایپ‌ها به امید اینکه درست باشن. این آپدیت از TanStack AI همه این کدهای تکراری رو حذف می‌کنه.

روش قدیمی این بود که خودت باید string buffer جمع می‌کردی، parsePartialJSON رو صدا می‌زدی، و نتیجه رو به تایپ موردنظرت cast می‌کردی — بدون هیچ تضمینی که واقعاً با schema مطابقت داشته باشه. این کارها رو هم باید توی هر کامپوننتی که می‌خواست پیش‌نمایش live داشته باشه تکرار می‌کردی.

روش جدید فقط یه پراپ اضافه‌ست:

const { partial, final, status } = useChat({
  connection: fetchServerSentEvents('/api/extract'),
  outputSchema: PersonSchema,
})

• partial از نوع DeepPartial هست و با هر تکه‌ای که از مدل می‌رسه آپدیت می‌شه.
• final از نوع Person | null هست و وقتی مدل خروجی کامل رو emit می‌کنه، به یه Person تایپ‌دار تبدیل می‌شه.
• دیگه نه parsePartialJSON، نه onChunk، نه useState اضافه، و نه cast دستی لازم نیست.

برای تعریف schema کافیه یه بار با zod بنویسیش و هم سمت سرور و هم سمت کلاینت ازش استفاده کنی:

export const PersonSchema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email(),
})

تغییرات زیرساختی این آپدیت فراتر از هوک هست. chat({ outputSchema, stream: true }) حالا یه StructuredOutputStream برمی‌گردونه که یه discriminated union واقعیه — دیگه با any دست‌وپنجه نرم نمی‌کنی. رویدادهای ApprovalRequestedEvent و ToolInputAvailableEvent هم tagged shape مخصوص خودشون رو گرفتن. پوشش provider هم کامله: OpenAI، OpenRouter، Grok، Groq و Ollama همه از همین pipeline عبور می‌کنن.

نکته طراحی جالب اینه که به جای ساختن یه هوک جداگانه مثل useStructuredChat، تیم TanStack تصمیم گرفت outputSchema رو به همون useChat اضافه کنه. این یعنی migration از «چت معمولی» به «چت با خروجی تایپ‌دار استریمی» واقعاً یه پراپ بیشتر نیست — همه چیز دیگه‌ای مثل tool wiring، approval prompts و transcript state دست‌نخورده باقی می‌مونن.

نکات کلیدی:

• useChat({ outputSchema }) حالا partial و final تایپ‌دار مستقیم برمی‌گردونه
• دیگه نیازی به کد glue برای پارس JSON جزئی نیست
• در React، Vue، Solid و Svelte یکسان کار می‌کنه
• پشتیبانی از OpenAI، OpenRouter، Grok، Groq و Ollama
• schema یه بار با zod تعریف می‌شه و هم سرور هم کلاینت ازش استفاده می‌کنن