ArkType لـ TypeScript: دليل شامل

1. ما هو ArkType ولماذا تحتاجه

ArkType هي مكتبة حديثة للتحقق من صحة البيانات في TypeScript تعمل على مستوى الأنواع. على عكس أدوات التحقق التقليدية (مثل Zod و Yup)، تستخدم ArkType نهجًا فريدًا: فهي تحول تعريفات الأنواع إلى محللات ومتحققين محسنين في مرحلة الترجمة. هذا يتيح أداءً عاليًا وتكاملًا كاملًا مع نظام الأنواع في TypeScript.

لماذا تحتاج ArkType؟ في تطبيقات الويب الحديثة، غالبًا ما تأتي البيانات من مصادر خارجية: API، نماذج، localStorage، WebSocket. بدون التحقق من الصحة، قد تواجه أخطاء وقت التشغيل التي يصعب اكتشافها. تحل ArkType هذه المشكلة من خلال توفير طريقة تعريفية لوصف مخططات البيانات والتوليد التلقائي لأنواع TypeScript من هذه المخططات. المكتبة مفيدة بشكل خاص عند العمل مع REST API و GraphQL والنماذج وأي بيانات خارجية.

الميزة الرئيسية لـ ArkType هي السرعة. بفضل الترجمة الثابتة للمخططات، يتم التحقق من الصحة بشكل أسرع بمقدار 10-100 مرة مقارنة بالنظائر. بالإضافة إلى ذلك، تدعم ArkType الأنواع المتكررة، والمراجع الدائرية، والفحوصات الصارمة، والعديد من الأنواع المضمنة. هذا يجعلها الخيار الأمثل للتطبيقات عالية التحميل والخدمات المصغرة.

2. التثبيت

يتم تثبيت ArkType عبر مدير الحزم npm (أو yarn/pnpm). المكتبة مكتوبة بلغة TypeScript وتأتي مع دعم كامل للأنواع.

npm install arktype

لا يتطلب العمل مع TypeScript أي إعدادات إضافية — المكتبة تلتقط تلقائيًا إعدادات tsconfig.json. الحد الأدنى لإصدار TypeScript هو 5.0.

# إذا كنت تستخدم yarn
yarn add arktype

# إذا كنت تستخدم pnpm
pnpm add arktype

3. البداية السريعة

مثال بسيط لاستخدام ArkType — إنشاء مخطط للتحقق من صحة كائن مستخدم:

import { type } from 'arktype';

// تعريف المخطط
const User = type({
    name: 'string',
    age: 'number',
    email: 'string.email'
});

// التحقق من صحة البيانات
const result = User({
    name: 'أحمد',
    age: 25,
    email: 'ahmed@example.com'
});

if (result instanceof type.errors) {
    console.error('خطأ في التحقق:', result.summary);
} else {
    console.log('البيانات صحيحة:', result);
    // result له تلقائيًا النوع { name: string; age: number; email: string }
}

في هذا المثال، أنشأنا مخطط User الذي يتحقق من ثلاثة حقول. إذا لم تمر البيانات التحقق، يتم إرجاع كائن خطأ مع وصف تفصيلي. إذا كان كل شيء صحيحًا، يتم إرجاع البيانات مع تحديد الأنواع.

4. أهم الطرق والدوال

توفر ArkType واجهة برمجة تطبيقات غنية لإنشاء المخططات ودمجها وتحويلها. دعنا نستعرض 8 طرق رئيسية.

4.1. type() — إنشاء مخطط

التوقيع: type(schema: TypeSchema): Type

الوصف: الطريقة الأساسية لإنشاء مخطط التحقق. تأخذ كائنًا أو سلسلة نصية مع تعريف النوع.

import { type } from 'arktype';

// مخطط بسيط
const StringType = type('string');
const NumberType = type('number');

// مخطط كائن
const Person = type({
    name: 'string',
    age: 'number',
    isActive: 'boolean'
});

// التحقق
console.log(StringType('مرحبا')); // 'مرحبا'
console.log(StringType(123)); // خطأ: Expected string, got number