io-ts TypeScript: الطرق، الأمثلة، التثبيت

ما هو io-ts ولماذا هو مطلوب؟

\nio-ts هي مكتبة لـ TypeScript تحل واحدة من أكثر المشاكل إيلامًا في التطوير بهذه اللغة: التناقض بين الأنواع الثابتة (أثناء التجميع) والبيانات الفعلية (أثناء التنفيذ). TypeScript أداة رائعة، لكن نظام الأنواع الخاص بها يعمل فقط في مرحلة التطوير. عندما يتم تشغيل تطبيقك، يتم مسح جميع الأنواع. إذا كنت تتلقى بيانات من API خارجي، أو من نموذج على موقع ويب، أو من localStorage، أو من أي مصدر آخر لا يتحكم فيه المترجم الخاص بك، فلا يمكنك التأكد من أن البيانات تتطابق مع الأنواع المعلنة.\n

\nهنا يأتي دور التحقق من الصحة في وقت التشغيل. يتيح لك io-ts تعريف مخطط بيانات مرة واحدة، ثم استخدامه لغرضين:\n

الكتابة الثابتة (وقت التجميع): يستنتج TypeScript الأنواع بناءً على المخطط الخاص بك، مما يضمن أمان الكود أثناء الكتابة.
التحقق من الصحة في وقت التشغيل: يتحقق io-ts مما إذا كانت البيانات الفعلية تتطابق مع المخطط الخاص بك، ويعيد إما نتيجة ناجحة أو خطأ مفصلاً.

\nتعتمد المكتبة على مفهوم التشفير/فك التشفير (codecs). الكوديك هو كائن يعرف كيفية فك التشفير (التحقق والتحويل) للبيانات الأولية إلى نوع TypeScript وكيفية تشفير (تسلسل) هذا النوع مرة أخرى. وهذا يجعل io-ts أداة قوية ليس فقط للتحقق من الصحة، ولكن أيضًا للتسلسل/إلغاء التسلسل الآمن للبيانات.\n

\n\n

التثبيت

\nio-ts هي مكتبة للنظام البيئي Node.js والمتصفحات، لذلك يتم تثبيتها عبر npm (أو yarn). لاحظ أن io-ts يتطلب fp-ts كاعتماد نظير (peer dependency)، لأنه يستخدم مفاهيم وظيفية مثل Either و Option.\n

npm install io-ts fp-ts

\nأو، إذا كنت تستخدم yarn:\n

yarn add io-ts fp-ts

\nبعد التثبيت، يمكنك استيراد المكتبة إلى مشروعك:\n

import * as t from 'io-ts';\nimport { isRight, isLeft } from 'fp-ts/Either';

\n\n

بداية سريعة: المثال الأول

\nلنبدأ بمثال بسيط. لنفترض أننا نتوقع كائن مستخدم يحتوي على حقلي name (سلسلة نصية) و age (رقم). دعنا نحدد المخطط باستخدام io-ts ونحاول التحقق من صحة بعض البيانات.\n

import * as t from 'io-ts';\nimport { isRight, isLeft } from 'fp-ts/Either';\n\n// 1. تعريف المخطط (codec)\nconst User = t.type({\n    name: t.string,\n    age: t.number,\n});\n\n// 2. دالة للحصول على النوع بأمان\ntype User = t.TypeOf<typeof User>;\n\n// 3. بيانات للتحقق\nconst validData = { name: 'Alice', age: 30 };\nconst invalidData = { name: 'Bob', age: 'عشرون' }; // age عبارة عن سلسلة نصية وليس رقمًا\n\n// 4. التحقق من الصحة\nconst result1 = User.decode(validData);\nconst result2 = User.decode(invalidData);\n\nconsole.log(isRight(result1)); // true\nconsole.log(isLeft(result2));  // true\n\n// 5. استخراج البيانات (إذا نجح التحقق)\nif (isRight(result1)) {\n    const user: User = result1.right;\n    console.log(user.name); // Alice\n}\n\n// 6. معالجة الخطأ\nif (isLeft(result2)) {\n    console.error('خطأ في التحقق:', result2.left);\n    // سيطبع قائمة بالأخطاء، على سبيل المثال:\n    // [ { value: 'عشرون', context: [...], message: 'Invalid value "عشرون" supplied to : { name: string, age: number }/age: number' } ]\n}\n

\nفي هذا المثال، نرى النمط الأساسي: decode يعيد Either<Errors, A> من مكتبة fp-ts. Either هو حاوية يمكنها أن تحتوي إما على خطأ (النوع الأيسر) أو قيمة ناجحة (النوع الأيمن). نتحقق من النتيجة باستخدام الدالتين isRight و isLeft.\n

\n\n