‏TanStack Form v2 با بازنویسی کامل به آلفا رسید

تیم TanStack نسخهٔ آلفای Form v2 رو منتشر کرد. تو این پست اومده که v1 بیشتر از یه سال بیرون بوده و همین فرصت داده ببینن کاربرها کجا گیر می‌کنن؛ نتیجه‌ش چند ماه بازنویسی هستهٔ کتابخونه از پایه‌ست. سینتکس پایه شبیه v1 مونده، ولی سرعت اجرا بالاتر رفته، تایپ‌ها امن‌تر شدن و همون بخش‌هایی از API که بیشترین دردسر رو داشتن دوباره طراحی شدن.

بزرگ‌ترین تغییر مال ولیدیتورهاست. تو v1 ولیدیتورها تو یه آبجکت می‌نشستن که کلیدش اسم رویداد بود (onChange، onBlur)، پس اگه یه ولیدیتور رو هم موقع تغییر مقدار و هم موقع از دست دادن فوکوس می‌خواستی، باید دوبار ثبتش می‌کردی و بعد خطاهای تکراری رو خودت از UI پاک می‌کردی. v2 به‌جاش pipeline داره — یعنی ولیدیتورها یه لیستن و هر کدوم خودش تریگرهاشو اعلام می‌کنه:

const form = useForm({
  defaultValues: { name: '' },
  validators: [
    { run: mySchema, triggers: ['change', 'blur'] },
  ],
})

حالت برعکس هم حل شده: چند ولیدیتور می‌تونن یه تریگر مشترک داشته باشن و جدا از هم بمونن، و bailIfInvalid: true می‌گه دومی فقط وقتی اجرا شه که اولی پاس شده باشه — همون کاری که تو v1 با یه early return دستی انجام می‌دادی. شرط‌ها هم از دل ولیدیتور اومدن بیرون: هر تریگر می‌تونه یه when داشته باشه، مثلاً تریگر change فقط بعد از اولین تلاش برای submit فعال شه. لیسنرها هم دقیقاً به همین مدل منتقل شدن.

سمت تایپ‌ها، v1 نوع فرم رو از defaultValues استنتاج می‌کرد؛ دردسر جایی بود که حالت اولیهٔ فرم با schema نهایی یکی نیست — مثل فرم نوبت‌دهی که schema یه Date می‌خواد ولی فرم با null شروع می‌شه چون نمی‌خوای تاریخی از قبل انتخاب شده باشه. v2 دو حالت اضافه کرده: formOptions.strictSchema که schema رو منبع حقیقت می‌کنه، و formOptions.looseSchema که null و undefined رو همون‌جایی که تو دیفالت‌ها هستن قبول می‌کنه و تایپ رو Date | null درمی‌آره.

تو Form Composition هم حالا می‌شه کامپوننت‌ها رو به تایپ مقداری که پشتیبانی می‌کنن برند کرد، پس یه فیلد رشته‌ای مثل email دیگه NumberInput رو تو API خودش نداره و خطای تایپ قبل از رسیدن به مرورگر درمیاد. سمت SSR هم ولیدیتور سرور رفته داخل همون formOpts مشترک؛ serverValidate دیگه خطا throw نمی‌کنه بلکه نتیجه برمی‌گردونه و کلاینت serverState رو مستقیم می‌ده به useForm، بدون useTransform و mergeForm دستی.

نکات کلیدی:

• ولیدیتورها و لیسنرها تو v2 به مدل pipeline رفتن: هر ولیدیتور با فیلد triggers چند رویداد رو پوشش می‌ده.
• bailIfInvalid: true جلوی اجرای ولیدیتور بعدی رو می‌گیره تا وقتی قبلی پاس نشده.
• formOptions.strictSchema و formOptions.looseSchema تعیین می‌کنن تایپ فرم از schema بیاد یا null تو دیفالت‌ها مجاز باشه.
• کامپوننت‌های composition رو می‌شه برند کرد تا فقط روی فیلدهای هم‌تایپ در دسترس باشن.
• آلفا هنوز persistence داخلی، Form Composition خارج از React و submit meta رو نداره؛ آداپترهای Vue، Solid، Angular و Lit مهاجرت کردن ولی composition‌شون منتقل نشده.