أنواع Intersection في TypeScript: دمج الأنواع باستخدام &

نوع intersection، ويُكتب A & B، يصف قيمة هي A وB في الوقت نفسه. في أنواع الكائنات يعني ذلك أن القيمة تملك كل خصائص الاثنين. وهكذا تدمج أنواعًا موجودة دون كتابة خصائصها من جديد.

type Person = { name: string; email: string };
type Employee = { employeeId: number; team: string };

type Staff = Person & Employee; // has all four properties

const ada: Staff = { name: "Ada", email: "ada@example.com", employeeId: 7, team: "compilers" };

function badge(s: Staff): string {
  return `${s.name} (#${s.employeeId}, ${s.team})`;
}

console.log(badge(ada)); // Ada (#7, compilers)

// @ts-expect-error: Type '{ name: string; email: string; employeeId: number; }' is not assignable to type 'Staff'.
const partial: Staff = { name: "Alan", email: "alan@example.com", employeeId: 8 };

يترك الكائن الثاني team، فيكون خطأ الترجمة TS2322، ويقول السطر التالي من الرسالة Property 'team' is missing ... but required in type 'Employee'. ويمكن تمرير قيمة Staff في أي مكان يُتوقع فيه Person أو Employee.

دمج أنواع الكائنات

يعمل & مع أي مزيج من type aliases والواجهات وأنواع الكائنات المضمّنة، ومع معاملات الأنواع العامة. والحالة الأخيرة هي حيث يصعب استبداله: الدالة التي تضيف خصائص إلى أي كائن تستقبله يمكنها أن تقول ذلك بدقة.

function withMeta<T extends object>(obj: T, author: string): T & { author: string; savedAt: string } {
  return { ...obj, author, savedAt: "2024-03-15T10:30:00.000Z" };
}

const note = withMeta({ title: "Draft", words: 120 }, "ada");
// type: { title: string; words: number } & { author: string; savedAt: string }

console.log(note.title, note.words, note.author); // Draft 120 ada
console.log(note.savedAt);                         // 2024-03-15T10:30:00.000Z

يحتفظ المستدعي بالنوع الدقيق لما مرره (title وwords) إضافة إلى الخاصيتين المضافتين. لا يستطيع interface ... extends التعبير عن «أيًا كان T، مع هذه الخصائص»، لأن الواجهة لا تستطيع توسيع معامل نوع.

الخصائص المتعارضة تصبح never

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

// This does not compile: id cannot be a string and a number at once
type WithStringId = { id: string; name: string };
type WithNumberId = { id: number };

type Account = WithStringId & WithNumberId; // no error on this line

const r: Account = { id: "u1", name: "Ada" };
console.log(r);

index.ts(7,22): error TS2322: Type 'string' is not assignable to type 'never'.

يشير الخطأ إلى الكائن، لا إلى النوع الذي تسبب فيه، ما يجعل تتبع هذه الأخطاء بطيئًا. وتمرير المؤشر فوق r.id في المحرر يُظهر نوعها: never. وعندما تكون الخاصية المتعارضة وسمًا حرفيًا، كما في type Shape = { kind: "circle" } & { kind: "square" }، تذهب TypeScript أبعد وتختزل الـ intersection كله إلى never. عندها تشرح قراءة خاصية من قيمة كهذه السبب: Property 'kind' does not exist on type 'never'. The intersection 'Shape' was reduced to 'never' because property 'kind' has conflicting types in some constituents.

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

التداخل المتوافق يضيّق الخاصية

إذا كان نوعا الخاصية يتداخلان فعلًا، يكون الناتج هو التداخل. هذا مفيد وليس خطأ:

type Editable = { id: string | number; tags: string[] };
type Stored = { id: string; createdAt: string };

type Doc = Editable & Stored; // id: (string | number) & string, which is string

const doc: Doc = { id: "d1", tags: ["draft"], createdAt: "2024-03-15" };
console.log(doc.id.toUpperCase()); // D1: id is a string, so string methods are allowed

type Letters = "a" | "b" | "c";
type Later = "b" | "c" | "d";
type Both = Letters & Later; // "b" | "c": what the two unions have in common

const shared: Both[] = ["b", "c"];
console.log(shared); // [ 'b', 'c' ]

يُظهر النصف الثاني ما يفعله & بأنواع union: يحتفظ بالأعضاء المشتركة بين الطرفين. التفكير في الأنواع كمجموعات من القيم يجعل هذا متوقعًا. A | B اتحاد المجموعتين، وA & B تقاطعهما، والتقاطع الخالي هو never.

Intersection مقابل Union

الاسمان مأخوذان من نظرية المجموعات، ويبدوان معكوسين عند تطبيقهما على خصائص الكائنات:

يملك intersection أنواع الكائنات خصائص أكثر لأنه تحديدًا يسمح بقيم أقل: الكائنات التي تملك كل شيء فقط.

Intersection مقابل extends

لدمج بضعة type aliases لأنواع كائنات، يكون & أسلوبًا مألوفًا ومناسبًا. ولنوع مبني من أجزاء كثيرة، أو لنوع في واجهة برمجية عامة، يعطي extends أخطاء أبكر وفحص أنواع أقل تكلفة.

Intersection مع الأنواع البدائية: الوسم (Branding)

تقاطع نوع بدائي مع نوع كائن لا ينتج never: string & { readonly __brand: "UserId" } نص يحمل علامة إضافية موجودة وقت الترجمة فقط. لا يملك أي نص حقيقي تلك الخاصية، وهذا تحديدًا هو المقصود: لا يستطيع إنشاء قيمة كهذه إلا كود يؤكد الوسم عمدًا، فلا يعود ممكنًا تمرير string عادي أو OrderId حيث يُتوقع UserId. ولهذه التقنية صفحتها الخاصة، branded types.