Zod مدت‌هاست که یکی از محبوب‌ترین کتابخانه‌ها برای اعتبارسنجی Schema در تایپ اسکریپت می‌باشد. دلیل این محبوبیت، سادگی و یکپارچگی قدرتمند آن با محیط تایپ اسکریپت است. با انتشار نسخه جدید یعنی نسخه Zod 4، این کتابخانه جهشی بزرگ به سمت جلو برداشته و با ارائه بهبودهای چشمگیر در عملکرد، افزودن ویژگی‌های جدید و کاربرپسند و پشتیبانی بهتر از وب اپلیکیشن‌های مدرن، موجی از هیجان در جامعه تایپ اسکریت ایجاد کرده است.

در این مقاله به بررسی ویژگی‌های جدید نسخه Zod 4، اهمیت آن‌ها و تأثیری که می‌توانند بر روند کاری ما داشته باشند می‌پردازیم.

مرور کوتاه تأثیر Zod 4 بر توسعه‌دهندگان فرانت‌اند

پیش از ورود به جزئیات، نگاهی کوتاه به نتایج و مزایایی داشته باشیم که توسعه‌دهندگان از نسخه Zod 4 تجربه می‌کنند:

ویژگی‌های جدید در نسخه 4 Zod

بهبود عملکرد

Zod 4 با بهینه‌سازی‌های داخلی عمیق، سرعت پردازش Schemaها را تا ۳ برابر افزایش می‌دهد و هم‌زمان مصرف حافظه را کاهش می‌دهد؛ بنابراین پروژه‌هایی با Schemaهای پیچیده و تودرتو عملکرد بهتری تجربه می‌کنند.

تیم توسعه در نسخه ۴ هسته Zod را حدود ۵۷٪ کوچک‌تر کرده است. این ویژگی آن را برای پروژه‌های فرانت‌اند که عملکرد و زمان بارگذاری اهمیت زیادی دارند، بسیار مناسب می‌سازد. چه یک اپلیکیشن سبک‌وزن ایجاد کنیم و چه یک داشبورد سازمانی پیچیده، این ساختار کم‌حجم‌تر تضمین می‌کند اپلیکیشن ما همیشه سریع و کارآمد عمل کند.

در نسخه‌های قبلی، ابزارهای تایپ اسکریپت گاهی دچار کندی می‌شدند، به‌خصوص در پروژه‌هایی با Schemaهای بزرگ یا Monorepoها. نسخه Zod 4 این مشکل را با ۲۰ برابر کاهش در تعداد Compiler Instantiationها برطرف کرده است؛ نتیجه آن Type-checking سریع‌تر، عملکرد روان‌تر IDE و Buildهای کوتاه‌تر می‌باشد.

معرفی Zod Mini

یکی از جذاب‌ترین قابلیت‌های نسخه Zod 4 معرفی پکیج جدیدی به نام @zod/mini است. توسعه‌دهندگان این نسخه سبک و تابع‌محور را با هدف کاهش حجم باندل طراحی کرده‌اند و آن را به‌طور خاص برای محیط‌هایی مانند Edge Functionها، پلتفرم‌های Serverless یا اپلیکیشن‌های فرانت‌اند حساس به عملکرد بهینه ساخته‌اند.

در این نسخه، به‌جای متدهایی مانند .min() یا .trim()، از توابع مستقل استفاده می‌کنیم که داخل .check() پاس داده می‌شوند. این تغییر باعث بهبود Tree-shaking و کاهش حجم باندل خواهد شد.

اگرچه @zod/mini نسبت به نسخه کامل این کتابخانه API محدودتری دارد، اما همچنان متدهای ضروری مانند .parse()، safeParse() و نسخه‌های Async آن‌ها را پشتیبانی می‌کند. علاوه بر این، کاملاً با Schemaهای Zod سازگار است. بنابراین می‌توانیم بدون از دست دادن Type-safety یا تجربه توسعه‌دهنده، در زمان Production از نسخه @zod/mini استفاده کنیم.

تبدیل مستقیم به JSON Schema

در نسخه‌های قبلی، برای تبدیل Schemaهای Zod به JSON Schema نیاز داشتیم از کتابخانه‌های third-party مانند zod-to-json-schema استفاده کنیم؛ امری که فرآیند را پیچیده‌تر و زمان‌برتر می‌کرد.

اما در نسخه Zod 4، تیم توسعه این قابلیت را به‌طور داخلی اضافه کرده است. تنها با چند خط کد می‌توانیم Schemaهای Zod را به JSON Schema تبدیل کنیم و آن‌ها را در ابزارها یا سیستم‌هایی که به این استاندارد نیاز دارند (مانند APIها یا Form Builderها) ادغام نماییم.

import { z } from "zod";
const userSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1),
  email: z.string().email(),
  age: z.number().int().positive().optional(),
  isAdmin: z.boolean().default(false),
});
const jsonSchema = userSchema.toJSON();
console.log(JSON.stringify(jsonSchema, null, 2));

کد بالا، JSON Schema زیر را خروجی می‌دهد:

{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "number" },
    "isAdmin": { "type": "boolean", "default": false }
  },
  "required": ["id", "name", "email"]
}

Zod Global Registry

یکی از قابلیت‌های مهم در نسخه Zod 4، معرفی Global Registry (با z.globalRegistry) است. این سیستم مرکزی امکان مدیریت و استفاده مجدد از Schemaها و Metadataهای مربوط به آن‌ها (مانند id، title، description و examples) را فراهم می‌کند.

با استفاده از متدهایی مانند .meta() یا .register() می‌توان Schemaها را ثبت کرد و هنگام سریال‌سازی با .toJSON()، Zod آن‌ها را به‌طور خودکار به بخش $defs اضافه می‌کند تا به‌سادگی از طریق $ref-based به آن‌ها ارجاع داده شود.

این قابلیت به‌ویژه در پروژه‌های بزرگ که نیاز به اعتبارسنجی یکپارچه دارند یا در زمان تولید API Specificationها بسیار ارزشمند است.

import { z } from "zod";
const userSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  email: z.string().email(),
}).meta({
  id: "User",
  title: "User",
  description: "A registered user in the system",
});
userSchema.register(z.globalRegistry);
const postSchema = z.object({
  title: z.string(),
  author: userSchema,
}).meta({ id: "Post" });
const definitions: Record<string, any> = {};
const jsonSchema = postSchema.toJSON({ target: "jsonSchema7", definitions });
console.log("Post Schema:", JSON.stringify(jsonSchema, null, 2));
console.log("Definitions:", JSON.stringify(definitions, null, 2));

مدیریت بهتر خطاهای Type

نسخه Zod 4 قابلیتی جدید به نام Error Pretty-printing معرفی کرده است که پیام‌های خطای اعتبارسنجی را بسیار خواناتر و قابل‌درک‌تر می‌سازد.

با این ویژگی، خطاهای ZodError به یک رشته چندخطی و خوش‌فرمت تبدیل می‌شوند و فرآیند دیباگ ساده‌تر می‌شود. در نتیجه توسعه‌دهندگان می‌توانند مشکلات را سریع‌تر شناسایی و رفع کنند. در مثال زیر مشاهده می‌کنیم که تابع z.prettifyError چگونه خطاها را مدیریت می‌کند:

import { z } from "zod";
const userSchema = z.object({
  username: z.string().min(5),
  age: z.number().positive(),
});
const invalidData = {
  username: "abc",
  age: -5,
};
const result = userSchema.safeParse(invalidData);
if (!result.success) {
  console.log(z.prettifyError(result.error));
}

خطاهای تایپ در کد بالا یک خروجی خوانا و قابل‌فهم ایجاد می‌کنند:

✖ Invalid input: expected string, received string
  → at username
✖ Invalid input: expected number, received number
  → at age

بهبود اعتبارسنجی فایل

در نسخه‌های قبلی Zod، اعتبارسنجی فایل‌ها معمولاً با استفاده از z.instanceof(File) و Refinementهای سفارشی انجام می‌شد. این روش هم کد اضافی زیادی تولید می‌کرد و هم پیچیدگی بالایی داشت.

اما در Zod 4، یک API جدید به نام z.file() معرفی شده است که فرآیند اعتبارسنجی فایل‌ها را ساده‌تر و قدرتمندتر می‌کند. با این متد می‌توانیم به‌راحتی محدودیت‌هایی مانند حداقل و حداکثر حجم فایل (بر حسب بایت) یا نوع MIME را با استفاده از.min()، .max() و .type() اعمال کنیم.

این قابلیت مدیریت آپلود فایل در اپلیکیشن‌های تحت مرورگر را به شکل چشمگیری ساده‌تر می‌سازد.

import { z } from "zod";
const fileSchema = z
  .file()
  .min(10_000, { message: "File is too small (min 10KB)." })
  .max(1_000_000, { message: "File is too large (max 1MB)." })
  .type("image/png", { message: "Only PNG files are allowed." });
function handleFileUpload(file: File) {
  const result = fileSchema.safeParse(file);
  if (!result.success) {
    console.error("File validation failed:", result.error.format());
    alert("Invalid file: " + result.error.errors[0].message);
    return;
  }
  console.log("Valid file:", result.data);
}

ارتقا به نسخه Zod 4

هرچند نسخه Zod 4 هنوز در مرحله بتا قرار دارد، اما تغییرات و بهبودهای چشمگیری را ارائه کرده است؛ از جمله افزایش عملکرد، افزودن ویژگی‌های جدید و اصلاحاتی که روند کاری توسعه‌دهندگان را ساده‌تر می‌سازد. برای ارتقا به این نسخه کافی است در ترمینال دستور زیر را اجرا نماییم:

npm upgrade zod@next

پس از ارتقا، لازم است کدهای پروژه با ساختار Schemaهای جدید در Zod 4 هماهنگ شوند. برخی از Schemaها و متدها در این نسخه منسوخ یا جایگزین شده‌اند که عبارت‌اند از:

جمع‌بندی

نسخه Zod 4 صرفاً یک به‌روزرسانی ساده نیست؛ بلکه یک جهش بزرگ در اعتبارسنجی Schema در تایپ اسکریپت است که واقعاً شایسته این میزان توجه می‌باشد.

با بهبودهای چشمگیر در عملکرد، قابلیت داخلی برای تبدیل به JSON Schema، معرفی نسخه سبک‌تر @zod/mini، گزارش خطاهای خواناتر و پشتیبانی native از اعتبارسنجی فایل، Zod 4 مجموعه‌ای قدرتمند از امکانات را در اختیار ما قرار می‌دهد که فرآیند اعتبارسنجی را ساده‌تر و کارآمدتر می‌کند.

فرقی نمی‌کند ما یک فرانت‌اند سبک بسازیم یا یک سیستم پیچیده سمت سرور؛ Zod 4 در هر سطحی از توسعه، روند اعتبارسنجی را روان‌تر و سریع‌تر می‌کند.