ts-toolkit لـ TypeScript: دليل شامل

1. ما هي هذه المكتبة ولماذا تحتاجها؟

ts-toolkit هي مكتبة أدوات قوية مكتوبة بلغة TypeScript، صُممت لتبسيط المهام اليومية للمطور. توفر مجموعة من الدوال والأنواع والكلاسات الجاهزة التي تساعدك في التعامل مع الكائنات (objects)، المصفوفات (arrays)، النصوص (strings)، الدوال (functions)، وأنواع البيانات (data types) بكفاءة وأمان أعلى. على عكس المكتبة القياسية للغة JavaScript، تقدم ts-toolkit حلولاً مقيدة بشكل صارم بالأنواع (strictly typed)، ومتوافقة تماماً مع نظام الأنواع في TypeScript.

لماذا تحتاج هذه المكتبة؟ في تطوير TypeScript الحديث، غالباً ما تحتاج لتنفيذ عمليات روتينية مثل: النسخ العميق للكائنات (deep cloning)، التنقل الآمن عبر الهياكل المتداخلة (safe navigation)، التحقق من الأنواع أثناء التشغيل (runtime type checking)، والتعامل مع أنماط Option/Result (وهي عبارة عن حاويات لمعالجة الأخطاء). ts-toolkit تتولى تنفيذ هذه الأنماط نيابة عنك، مما يتيح لك التركيز على منطق الأعمال. المكتبة مفيدة بشكل خاص في المشاريع التي تتطلب موثوقية عالية وكتابة أنواع صارمة.

الميزة الأساسية لـ ts-toolkit هي أمان الأنواع (type safety). كل دالة صُممت لاستخدام إمكانيات TypeScript إلى أقصى حد: الأنواع الشرطية (conditional types)، أنواع الخرائط (mapped types)، الاستدلال (infer)، وغيرها من التركيبات المتقدمة. هذا يعني أن العديد من الأخطاء التي قد تظهر فقط أثناء التشغيل (runtime) سيتم اكتشافها في مرحلة الترجمة (compile time).

2. التثبيت

يتم تثبيت المكتبة عبر مدير الحزم npm:

npm install @tool-belt/ts-toolkit

أو عبر yarn:

yarn add @tool-belt/ts-toolkit

بعد التثبيت، قم باستيراد الدوال التي تحتاجها في مشروعك:

import { deepClone, safeGet, pipe } from '@tool-belt/ts-toolkit';

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

مثال عملي بسيط يوضح الإمكانيات الأساسية للمكتبة:

import { deepClone, isObject, pipe } from '@tool-belt/ts-toolkit';

// مثال 1: النسخ العميق
const original = { a: 1, b: { c: 2 } };
const cloned = deepClone(original);
cloned.b.c = 42;
console.log(original.b.c); // 2 (الأصلي لم يتغير)

// مثال 2: التحقق من النوع
console.log(isObject({}));   // true
console.log(isObject(null)); // false

// مثال 3: تركيب الدوال (Function Composition)
const addOne = (x: number) => x + 1;
const double = (x: number) => x * 2;
const addOneThenDouble = pipe(addOne, double);
console.log(addOneThenDouble(5)); // 12

4. الدوال والوظائف الرئيسية

4.1. `deepClone`

التوقيع (Signature): function deepClone<T>(value: T): T

الوصف: تقوم بنسخ أي قيمة بشكل عميق، بما في ذلك الكائنات المتداخلة، المصفوفات، التواريخ (Date)، الخرائط (Map)، المجموعات (Set)، والهياكل الأخرى. تدعم المراجع الدائرية (circular references).

import { deepClone } from '@tool-belt/ts-toolkit';

const user = {
  name: 'Alice',
  address: { city: 'NYC', zip: 10001 },
  hobbies: ['reading', 'coding']
};

const clonedUser = deepClone(user);
clonedUser.address.city = 'LA';
console.log(user.address.city); // 'NYC'

4.2. `safeGet`

التوقيع (Signature): function safeGet<T, K extends keyof T>(obj: T, key: K): T[K] | undefined

الوصف: تحصل بأمان على قيمة خاصية من كائن. ترجع undefined إذا كانت الخاصية غير موجودة أو إذا كان الكائن يساوي null أو undefined، بدلاً من إلقاء خطأ.

import { safeGet } from '@tool-belt/ts-toolkit';

const data = { user: { name: 'Bob' } };
const name = safeGet(data, 'user')?.name; // 'Bob'
const missing = safeGet(null, 'anything'); // undefined