العلامات الاسمية في TypeScript: تعريفات الأنواع المعتمة لتعزيز سلامة الأنواع

بينما يقدم TypeScript كتابة ثابتة، فإنه يستخدم في الأساس الكتابة الهيكلية. هذا يعني أن الأنواع تُعتبر متوافقة إذا كان لها نفس الشكل، بغض النظر عن أسمائها المعلنة. وبينما تتيح هذه المرونة، يمكن أن تؤدي أحيانًا إلى استبدالات غير مقصودة للأنواع وتقليل سلامة الأنواع. تقدم العلامات الاسمية، المعروفة أيضًا بتعريفات الأنواع المعتمة، طريقة لتحقيق نظام أنواع أكثر قوة، أقرب إلى الكتابة الاسمية، داخل TypeScript. يستخدم هذا النهج تقنيات ذكية لجعل الأنواع تتصرف كما لو كانت تحمل أسماء فريدة، مما يمنع الاختلاط العرضي ويضمن صحة الكود.

فهم الكتابة الهيكلية مقابل الكتابة الاسمية

قبل الخوض في العلامات الاسمية، من الضروري فهم الفرق بين الكتابة الهيكلية والاسمية.

الكتابة الهيكلية

في الكتابة الهيكلية، يُعتبر نوعان متوافقين إذا كان لهما نفس البنية (أي، نفس الخصائص بنفس الأنواع). لننظر إلى مثال TypeScript هذا:

interface Kilogram { value: number; }
interface Gram { value: number; }

const kg: Kilogram = { value: 10 };
const g: Gram = { value: 10000 };

// TypeScript allows this because both types have the same structure
const kg2: Kilogram = g;

console.log(kg2);

على الرغم من أن `Kilogram` و `Gram` يمثلان وحدات قياس مختلفة، يسمح TypeScript بتعيين كائن `Gram` لمتغير `Kilogram` لأنهما يمتلكان كلاهما خاصية `value` من النوع `number`. هذا يمكن أن يؤدي إلى أخطاء منطقية في الكود الخاص بك.

الكتابة الاسمية

على النقيض، تعتبر الكتابة الاسمية نوعين متوافقين فقط إذا كان لهما نفس الاسم أو إذا كان أحدهما مشتقًا صراحةً من الآخر. تستخدم لغات مثل Java و C# بشكل أساسي الكتابة الاسمية. إذا استخدمت TypeScript الكتابة الاسمية، فإن المثال أعلاه سينتج عنه خطأ في النوع.

الحاجة إلى العلامات الاسمية في TypeScript

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

لنأخذ بعين الاعتبار هذه السيناريوهات:

• معالجة العملات: التمييز بين مبالغ `USD` و `EUR` لمنع الخلط العرضي للعملات.
• معرفات قواعد البيانات: التأكد من عدم استخدام `UserID` عن طريق الخطأ حيث يتوقع `ProductID`.
• وحدات القياس: التمييز بين `Meters` و `Feet` لتجنب الحسابات غير الصحيحة.
• البيانات الآمنة: التمييز بين `Password` (نص عادي) و `PasswordHash` (كلمة مرور مشفرة) لمنع الكشف العرضي عن المعلومات الحساسة.

في كل من هذه الحالات، يمكن أن تؤدي الكتابة الهيكلية إلى أخطاء لأن التمثيل الأساسي (مثل رقم أو سلسلة نصية) هو نفسه لكلا النوعين. تساعدك العلامات الاسمية في فرض سلامة الأنواع عن طريق جعل هذه الأنواع مميزة.

تطبيق العلامات الاسمية في TypeScript

هناك عدة طرق لتطبيق العلامات الاسمية في TypeScript. سنستكشف تقنية شائعة وفعالة باستخدام تقاطعات الرموز الفريدة (intersections and unique symbols).

استخدام تقاطعات الرموز الفريدة (Intersections and Unique Symbols)

تتضمن هذه التقنية إنشاء رمز فريد وربطه بالنوع الأساسي. يعمل الرمز الفريد كـ "علامة تجارية" تميز النوع عن غيره من الأنواع ذات البنية المتشابهة.

// Define a unique symbol for the Kilogram brand
const kilogramBrand: unique symbol = Symbol();

// Define a Kilogram type branded with the unique symbol
type Kilogram = number & { readonly [kilogramBrand]: true };

// Define a unique symbol for the Gram brand
const gramBrand: unique symbol = Symbol();

// Define a Gram type branded with the unique symbol
type Gram = number & { readonly [gramBrand]: true };

// Helper function to create Kilogram values
const Kilogram = (value: number) => value as Kilogram;

// Helper function to create Gram values
const Gram = (value: number) => value as Gram;

const kg: Kilogram = Kilogram(10);
const g: Gram = Gram(10000);

// This will now cause a TypeScript error
// const kg2: Kilogram = g; // Type 'Gram' is not assignable to type 'Kilogram'.

console.log(kg, g);

شرح:

• نقوم بتعريف رمز فريد باستخدام `Symbol()`. كل استدعاء لـ `Symbol()` ينشئ قيمة فريدة، مما يضمن تميز علاماتنا التجارية.
• نقوم بتعريف نوعي `Kilogram` و `Gram` كتقاطعات لـ `number` وكائن يحتوي على الرمز الفريد كمفتاح بقيمة `true`. يضمن المعدّل `readonly` عدم إمكانية تعديل العلامة التجارية بعد الإنشاء.
• نستخدم وظائف مساعدة (`Kilogram` و `Gram`) مع تأكيدات النوع (`as Kilogram` و `as Gram`) لإنشاء قيم من الأنواع ذات العلامات التجارية. وهذا ضروري لأن TypeScript لا يمكنه استنتاج النوع ذي العلامة التجارية تلقائيًا.

الآن، يقوم TypeScript بالإبلاغ عن خطأ بشكل صحيح عندما تحاول تعيين قيمة `Gram` إلى متغير `Kilogram`. هذا يفرض سلامة الأنواع ويمنع الخلط العرضي.

العلامات الاسمية العامة لإعادة الاستخدام

لتجنب تكرار نمط العلامات لكل نوع، يمكنك إنشاء نوع مساعد عام:

type Brand<K, T> = K & { readonly __brand: unique symbol; };

// Define Kilogram using the generic Brand type
type Kilogram = Brand<number, 'Kilogram'>;

// Define Gram using the generic Brand type
type Gram = Brand<number, 'Gram'>;

// Helper function to create Kilogram values
const Kilogram = (value: number) => value as Kilogram;

// Helper function to create Gram values
const Gram = (value: number) => value as Gram;

const kg: Kilogram = Kilogram(10);
const g: Gram = Gram(10000);

// This will still cause a TypeScript error
// const kg2: Kilogram = g; // Type 'Gram' is not assignable to type 'Kilogram'.

console.log(kg, g);

يبسط هذا النهج بناء الجملة ويجعل من السهل تعريف الأنواع ذات العلامات التجارية بشكل متسق.

حالات الاستخدام المتقدمة والاعتبارات

وسم الكائنات (Branding Objects)

يمكن أيضًا تطبيق العلامات الاسمية على أنواع الكائنات، وليس فقط الأنواع البدائية مثل الأرقام أو السلاسل النصية.

interface User {
  id: number;
  name: string;
}

const UserIDBrand: unique symbol = Symbol();
type UserID = number & { readonly [UserIDBrand]: true };

interface Product {
  id: number;
  name: string;
}

const ProductIDBrand: unique symbol = Symbol();
type ProductID = number & { readonly [ProductIDBrand]: true };

// Function expecting UserID
function getUser(id: UserID): User {
  // ... implementation to fetch user by ID
  return {id: id, name: "Example User"};
}

const userID = 123 as UserID;
const productID = 456 as ProductID;

const user = getUser(userID);

// This would cause an error if uncommented
// const user2 = getUser(productID); // Argument of type 'ProductID' is not assignable to parameter of type 'UserID'.

console.log(user);

هذا يمنع تمرير `ProductID` عن طريق الخطأ حيث يتوقع `UserID`، على الرغم من أن كلاهما ممثل في النهاية كأرقام.

العمل مع المكتبات والأنواع الخارجية

عند العمل مع المكتبات الخارجية أو واجهات برمجة التطبيقات (APIs) التي لا توفر أنواعًا مُعلّمة (branded types)، يمكنك استخدام تأكيدات النوع (type assertions) لإنشاء أنواع مُعلّمة من القيم الموجودة. ومع ذلك، كن حذرًا عند القيام بذلك، لأنك تؤكد أساسًا أن القيمة تتوافق مع النوع المُعلّم، وتحتاج إلى التأكد من أن هذا هو الحال بالفعل.

// Assume you receive a number from an API that represents a UserID
const rawUserID = 789; // Number from an external source

// Create a branded UserID from the raw number
const userIDFromAPI = rawUserID as UserID;

اعتبارات وقت التشغيل

من المهم أن نتذكر أن العلامات الاسمية في TypeScript هي بناء وقت تجميع بحت. يتم مسح العلامات (الرموز الفريدة) أثناء التجميع، لذلك لا توجد تكلفة إضافية في وقت التشغيل. ومع ذلك، هذا يعني أيضًا أنه لا يمكنك الاعتماد على العلامات لفحص الأنواع في وقت التشغيل. إذا كنت بحاجة إلى فحص الأنواع في وقت التشغيل، فستحتاج إلى تنفيذ آليات إضافية، مثل حراس الأنواع المخصصة.

حراس الأنواع للتحقق في وقت التشغيل

لإجراء التحقق في وقت التشغيل للأنواع المُعلّمة، يمكنك إنشاء حراس أنواع مخصصة:

function isKilogram(value: number): value is Kilogram {
  // In a real-world scenario, you might add additional checks here,
  // such as ensuring the value is within a valid range for kilograms.
  return typeof value === 'number';
}

const someValue: any = 15;

if (isKilogram(someValue)) {
  const kg: Kilogram = someValue;
  console.log("Value is a Kilogram:", kg);
} else {
  console.log("Value is not a Kilogram");
}

يتيح لك هذا تضييق نوع القيمة بأمان في وقت التشغيل، مما يضمن توافقها مع النوع المُعلّم قبل استخدامها.

فوائد العلامات الاسمية

• تعزيز سلامة الأنواع: يمنع استبدالات الأنواع غير المقصودة ويقلل من خطر الأخطاء المنطقية.
• تحسين وضوح الكود: يجعل الكود أكثر قابلية للقراءة وأسهل في الفهم من خلال التمييز الصريح بين الأنواع المختلفة ذات التمثيل الأساسي نفسه.
• تقليل وقت التصحيح: يكتشف الأخطاء المتعلقة بالأنواع في وقت التجميع، مما يوفر الوقت والجهد أثناء التصحيح.
• زيادة الثقة في الكود: يوفر ثقة أكبر في صحة الكود الخاص بك من خلال فرض قيود أكثر صرامة على الأنواع.

قيود العلامات الاسمية

• وقت التجميع فقط: يتم مسح العلامات أثناء التجميع، لذا فهي لا توفر فحصًا للأنواع في وقت التشغيل.
• يتطلب تأكيدات النوع: يتطلب إنشاء أنواع مُعلّمة غالبًا تأكيدات للنوع، والتي يمكن أن تتجاوز فحص النوع إذا استخدمت بشكل غير صحيح.
• زيادة الشيفرة المتكررة (Boilerplate): يمكن أن تضيف تعريفات واستخدامات الأنواع المُعلّمة بعض الشيفرة المتكررة إلى الكود الخاص بك، على الرغم من أنه يمكن التخفيف من ذلك باستخدام أنواع المساعدة العامة.

أفضل الممارسات لاستخدام العلامات الاسمية

• استخدم العلامات الاسمية العامة: أنشئ أنواع مساعدة عامة لتقليل الشيفرة المتكررة وضمان الاتساق.
• استخدم حراس الأنواع: نفّذ حراس أنواع مخصصة للتحقق في وقت التشغيل عند الضرورة.
• طبق العلامات الاسمية بحكمة: لا تفرط في استخدام العلامات الاسمية. طبقها فقط عندما تحتاج إلى فرض فحص أكثر صرامة للأنواع لمنع الأخطاء المنطقية.
• وثق العلامات الاسمية بوضوح: وثّق بوضوح الغرض والاستخدام لكل نوع مُعلّم.
• اعتبارات الأداء: على الرغم من أن التكلفة في وقت التشغيل ضئيلة، إلا أن وقت التجميع يمكن أن يزداد مع الاستخدام المفرط. قم بتحليل الأداء والتحسين عند الحاجة.

أمثلة عبر مختلف الصناعات والتطبيقات

تجد العلامات الاسمية تطبيقات عبر مجالات مختلفة:

• الأنظمة المالية: التمييز بين العملات المختلفة (USD, EUR, GBP) وأنواع الحسابات (التوفير، الجاري) لمنع المعاملات والحسابات غير الصحيحة. على سبيل المثال، قد يستخدم تطبيق مصرفي أنواعًا اسمية لضمان أن حسابات الفائدة تُجرى فقط على حسابات التوفير وأن تحويلات العملة تُطبق بشكل صحيح عند تحويل الأموال بين الحسابات بعملات مختلفة.
• منصات التجارة الإلكترونية: التمييز بين معرفات المنتجات، معرفات العملاء، ومعرفات الطلبات لتجنب تلف البيانات والثغرات الأمنية. تخيل أن يتم عن طريق الخطأ ربط معلومات بطاقة ائتمان العميل بمنتج – يمكن للأنواع الاسمية أن تساعد في منع مثل هذه الأخطاء الكارثية.
• تطبيقات الرعاية الصحية: الفصل بين معرفات المرضى، معرفات الأطباء، ومعرفات المواعيد لضمان ارتباط البيانات الصحيح ومنع الخلط العرضي لسجلات المرضى. هذا أمر بالغ الأهمية للحفاظ على خصوصية المريض وسلامة البيانات.
• إدارة سلسلة التوريد: التمييز بين معرفات المستودعات، معرفات الشحنات، ومعرفات المنتجات لتتبع البضائع بدقة ومنع الأخطاء اللوجستية. على سبيل المثال، التأكد من تسليم الشحنة إلى المستودع الصحيح وأن المنتجات في الشحنة تتطابق مع الطلب.
• أنظمة إنترنت الأشياء (IoT): التمييز بين معرفات الحساسات، معرفات الأجهزة، ومعرفات المستخدمين لضمان جمع البيانات والتحكم فيها بشكل صحيح. هذا مهم بشكل خاص في السيناريوهات التي تكون فيها الأمان والموثوقية ذات أهمية قصوى، مثل التشغيل الآلي للمنزل الذكي أو أنظمة التحكم الصناعية.
• الألعاب: التمييز بين معرفات الأسلحة، معرفات الشخصيات، ومعرفات العناصر لتعزيز منطق اللعبة ومنع الاستغلالات. قد يؤدي خطأ بسيط إلى السماح للاعب بتجهيز عنصر مخصص فقط للشخصيات غير القابلة للعب (NPCs)، مما يخل بتوازن اللعبة.

بدائل العلامات الاسمية

بينما تعد العلامات الاسمية تقنية قوية، يمكن لنهج أخرى تحقيق نتائج مماثلة في بعض الحالات:

• الفئات (Classes): يمكن أن يوفر استخدام الفئات ذات الخصائص الخاصة (private properties) درجة معينة من الكتابة الاسمية، حيث أن مثيلات الفئات المختلفة تكون مميزة بطبيعتها. ومع ذلك، يمكن أن يكون هذا النهج أكثر إطالة من العلامات الاسمية وقد لا يكون مناسبًا لجميع الحالات.
• التعدادات (Enum): يوفر استخدام تعدادات TypeScript درجة معينة من الكتابة الاسمية في وقت التشغيل لمجموعة محددة ومحدودة من القيم الممكنة.
• الأنواع الحرفية (Literal Types): يمكن أن يؤدي استخدام الأنواع الحرفية للنص أو الأرقام إلى تقييد القيم الممكنة للمتغير، لكن هذا النهج لا يوفر نفس مستوى سلامة الأنواع مثل العلامات الاسمية.
• المكتبات الخارجية: توفر مكتبات مثل `io-ts` إمكانات فحص الأنواع والتحقق منها في وقت التشغيل، والتي يمكن استخدامها لفرض قيود أكثر صرامة على الأنواع. ومع ذلك، تضيف هذه المكتبات تبعية في وقت التشغيل وقد لا تكون ضرورية لجميع الحالات.

الخلاصة

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

تذكر أن تأخذ في الاعتبار المقايضات بين سلامة الأنواع، تعقيد الكود، والتكلفة الإضافية لوقت التشغيل عند اتخاذ قرار بشأن استخدام العلامات الاسمية في مشاريعك.

من خلال دمج أفضل الممارسات والنظر بعناية في البدائل، يمكنك الاستفادة من العلامات الاسمية لكتابة كود TypeScript أنظف، وأكثر قابلية للصيانة، وأكثر قوة. احتضن قوة سلامة الأنواع، وابنِ برمجيات أفضل!