ساخت یک کتابخانه اعتبارسنجی؛ آموخته‌هایی از valiend

چرا valiend را ساختم

اعتبارسنجی از آن مسئله‌هایی است که هر توسعه‌دهنده بارها حل می‌کند. پس از نوشتن چندباره ابزارهای isEmail و isRequired در سه پروژه متفاوت، تصمیم گرفتم آن‌ها را به یک پکیج مستقل تبدیل کنم.

چیزی که به‌عنوان ابزاری کوچک آغاز شد، به محصولی تبدیل شد که واقعاً به آن افتخار می‌کنم. در ادامه آموخته‌های این مسیر را می‌خوانید.

ابتدا API را طراحی کنید

پیش از نوشتن حتی یک خط از پیاده‌سازی، نوشتم که دوست دارم چگونه از کتابخانه استفاده کنم:

import { validate } from 'valiend';

const result = validate(userInput, {
  email: ['required', 'email'],
  age: ['required', 'min:18', 'max:120'],
  username: ['required', 'min:3', 'max:20', 'alphanumeric'],
});

if (!result.valid) {
  console.log(result.errors); // { email: ['Must be a valid email'] }
}

نوشتن مثال‌های استفاده پیش از پیاده‌سازی یکی از بهترین روش‌های طراحی API است؛ چون شما را وادار می‌کند از دید مصرف‌کننده فکر کنید.

بخش‌های دشوار

حذف کدهای استفاده‌نشده (Tree-shaking)

یکی از نخستین بازخوردها این بود که حجم باندل زیاد است. کاربران تنها به دو یا سه اعتبارسنج نیاز داشتند، اما کل کتابخانه را دریافت می‌کردند.

راه‌حل روشن بود: اعتبارسنج‌ها را جداگانه خروجی بدهیم تا باندلر بتواند کدهای بدون استفاده را حذف کند:

// قبل
import { validate } from 'valiend';

// بعد — فقط چیزی را وارد کنید که نیاز دارید
import { required, email, minLength } from 'valiend/validators';

شخصی‌سازی پیام خطا

پیام‌های خطای ثابت یک دام هستند. پروژه‌ها، زبان‌ها و لحن‌ها با هم فرق دارند. برای حل این مسئله الگوی کارخانه پیام را اضافه کردم:

validate(data, rules, {
  messages: {
    required: (field) => `${field} cannot be empty`,
    email: () => 'Please enter a valid email address',
  }
});

ایمنی نوع‌ها

افزودن نوع‌های TypeScript در مراحل پایانی دردسرساز بود. درس این تجربه روشن است: حتی اگر JavaScript می‌نویسید، نوع‌ها را از ابتدا در نظر بگیرید. اگر هنوز آماده مهاجرت کامل به TypeScript نیستید، JSDoc هم انتخاب مناسبی است.

نکته‌های پایانی

انتشار یک محصول ناقص، بی‌نهایت ارزشمندتر از منتشر نکردن یک محصول بی‌نقص است.

1. طراحی API همان طراحی محصول است. تجربه توسعه‌دهنده به‌اندازه عملکرد زمان اجرا اهمیت دارد.
2. مستندات نیمی از محصول است. کتابخانه‌ای که کسی آن را نفهمد، استفاده نخواهد شد.
3. نسخه‌بندی معنایی مهم است. یک تغییر ناخواسته و ناسازگار در نسخه اصلاحی به من آموخت که در نسخه‌بندی دقیق باشم.
4. آزمون‌ها قرارداد شما هستند. مجموعه آزمون کامل اجازه می‌دهد با اطمینان بازآرایی کنید.

می‌توانید valiend را در valiend.com ببینید یا کد منبع آن را در GitHub بررسی کنید.