إليك دالة من عميل الدفع في Cartwheel، واستدعاءً يفاجئ القادمين من Java أو C#:
\ntype Money = { amountCents: number; currency: string };\n\nfunction formatMoney(m: Money): string {\n return `${(m.amountCents / 100).toFixed(2)} ${m.currency}`;\n}\n\nconst tent = { sku: 'TENT-2P', name: 'Two-person tent', amountCents: 18900, currency: 'USD' };\nformatMoney(tent); // compiles: \"189.00 USD\"لم يُعرَّف tent أبدًا على أنه Money؛ إنه منتج. ومع ذلك يقبله TypeScript، لأنه لا يسأل عن اسم الشيء، بل يسأل إن كان له الشكل الصحيح. هذا هو الـ structural typing (التنميط البنيوي)، وحين تراه بوضوح تختفي معظم لحظات “لماذا يمرّ هذا الكود؟”.
هذا أنفع نموذج ذهني في الدورة كلها: الـ type مجموعة من القيم. string هو مجموعة كل النصوص. 'USD' مجموعة فيها قيمة واحدة. و'USD' | 'EUR' فيها قيمتان.
قابلية الإسناد (assignability) هي علاقة الاحتواء. يمكن وضع قيمة من النوع A حيث يُنتظر B حين تكون كل A هي أيضًا B. كل 'USD' نصٌّ، لذا 'USD' قابل للإسناد إلى string. وليس كل نص هو 'USD'، لذا يحتاج العكس إلى فحص.
أنواع الكائنات تعمل بالطريقة نفسها، مع لمسة تُربك الناس. { id: number } هو مجموعة كل القيم التي لها id رقمي. و{ id: number; status: string } يضيف شرطًا ثانيًا، فتقلّ القيم المؤهَّلة. خصائص أكثر تعني مجموعة أصغر. لهذا يمكن تمرير Order كامل حيث يُنتظر { id: number }: إنه في المجموعة الأصغر، فهو إذن في الأكبر أيضًا.
يقف نوعان خاصّان عند الأطراف. unknown هو مجموعة كل القيم: كل شيء قابل للإسناد إليه، وعليك أن تفحص قبل استخدامه. وnever هو المجموعة الفارغة: قابل للإسناد إلى كل شيء (فالمجموعة الفارغة جزء من كل مجموعة)، ولا شيء قابل للإسناد إليه. ستعتمد على الاثنين لاحقًا في الدورة. أما any فليس مجموعة أصلًا؛ إنه يُطفئ الفحص في الاتجاهين، ولهذا يستطيع any واحد شارد أن يسمّم بهدوء كل ما يلمسه.
إن كانت الخصائص الإضافية مقبولة، فلماذا يفشل هذا؟
\ntype Order = { id: number; status: string };\nfunction save(order: Order) {}\n\nsave({ id: 1001, stauts: 'processing' });\n// Error: Object literal may only specify known properties, but 'stauts'\n// does not exist in type 'Order'. Did you mean to write 'status'?هذا فحص الخصائص الزائدة (excess property check)، وهو قاعدة تقديرية مقصودة فوق التنميط البنيوي. حين تكتب كائنًا حرفيًا مباشرة حيث يُنتظر نوع، يكون الكائن “طازجًا”: لا شيء آخر يمكن أن يراه، فالخاصية الإضافية لا يمكن أن تكون إلا خطأً إملائيًا. لذلك يعلّمها TypeScript.
\nولا ينطبق الفحص إلا على الكائنات الحرفية الطازجة:
\nconst draft = { id: 1001, status: 'processing', stauts: 'oops' };\nsave(draft); // compiles: draft is not freshفي الدوال، تتبع أنواع القيم المُعادة القاعدة المعتادة، لكن المعاملات تسير في الاتجاه الآخر. الـ handler الذي يقبل أي CheckoutEvent يمكن أن يحلّ محلّ handler لا يحتاج إلا PaymentFailed. والعكس غير آمن: handler لا يفهم إلا PaymentFailed سينهار أمام حدث shipped. تحت strict (وتحديدًا strictFunctionTypes)، يرفضه TypeScript:
type PaymentFailed = { type: 'payment-failed'; reason: string };\ntype OrderShipped = { type: 'order-shipped'; carrier: string };\ntype CheckoutEvent = PaymentFailed | OrderShipped;\n\ntype Listener = { onEvent: (e: CheckoutEvent) => void };\n\nconst failuresOnly = { onEvent: (e: PaymentFailed) => console.log(e.reason.toUpperCase()) };\nconst l: Listener = failuresOnly;\n// Error: Type '{ onEvent: (e: PaymentFailed) => void; }' is not assignable to type 'Listener'.\n// Types of property 'onEvent' are incompatible.المعاملات الأقل مقبولة أيضًا: (e) => {} و() => {} كلتاهما تناسبان (e: CheckoutEvent, at: Date) => void، لأن الدالة مسموح لها بتجاهل الوسائط. ولهذا تعمل orders.forEach((o) => …) رغم أن forEach تمرّر ثلاثة وسائط.
اكتب الآن النوع نفسه بصيغة الـ method:
\ninterface Listener {\n onEvent(e: CheckoutEvent): void; // method syntax\n}\nconst l: Listener = failuresOnly; // compiles!معاملات الـ methods المعرَّفة بهذه الطريقة تُفحص فحصًا ثنائي التغاير (bivariant)، حتى تحت strict. يُبقي TypeScript هذا عن قصد كي تبقى الأنماط اليومية تعمل، مثل معاملة Array<Dog> على أنها Array<Animal>. والثمن أن الـ listener غير الآمن أعلاه يُقبَل.
أحيانًا يكون التنميط البنيوي كريمًا أكثر من اللازم. OrderId وCustomerId كلاهما number، فلا شيء يمنعك من تبديلهما. الحل أن تجعل الشكلين مختلفين، وهذا ما تفعله الـ branded types في الـ Branded Types والفحوص الشاملة. أما الآن فتكفيك القاعدة العامة: إن كان لشيئين الشكل نفسه، يعتبرهما TypeScript الشيء نفسه.
التمرين أدناه يسدّ ثغرة الـ listener في ناقل الأحداث في Cartwheel. وبعده سترى كيف يضيّق TypeScript نوعًا واسعًا داخل الدالة، النصف الآخر من العمل مع المجموعات.
\n","toc":[{"id":"sec-1","text":"الأنواع مجموعات من القيم","level":2},{"id":"sec-2","text":"فحوص الخصائص الزائدة: الاستثناء الوحيد","level":2},{"id":"sec-3","text":"الدوال: المعاملات تقلب الاتجاه","level":2},{"id":"sec-4","text":"ثغرة صيغة الـ method","level":3},{"id":"sec-5","text":"حين تريد أن تكون للأسماء قيمة","level":2}],"takeaways":["يقارن TypeScript الأشكال لا الأسماء؛ أي قيمة تملك الخصائص المطلوبة قابلة للإسناد، أيًّا كان اسم نوعها.","اقرأ الـ type على أنه مجموعة القيم التي يسمح بها؛ نوع الكائن الذي فيه خصائص مطلوبة أكثر يصف مجموعة أصغر.","فحوص الخصائص الزائدة لا تنطبق إلا على الكائنات الحرفية الطازجة، ولهذا يمرّ تمرير متغيّر فيه حقل إضافي.","تُفحص معاملات الدوال في الاتجاه المعاكس، لكن الـ methods المعرَّفة بصيغة الـ method تُفحص فحصًا ثنائي التغاير (bivariant)، لذا فضّل صيغة الخاصية للـ callbacks."],"further":[{"title":"Type Compatibility","url":"https://www.typescriptlang.org/docs/handbook/type-compatibility.html"},{"title":"strictFunctionTypes","url":"https://www.typescriptlang.org/tsconfig/strictFunctionTypes.html"}],"quiz":[{"q":"هل يمرّ هذا الكود في الترجمة؟
\ntype Money = { amountCents: number; currency: string };\nconst product = { sku: 'TENT-2P', amountCents: 18900, currency: 'USD' };\nconst price: Money = product;product يملك كل خاصية يتطلّبها Money، والخصائص الإضافية مسموحة في القيمة غير الطازجة.","why":"صحيح. product متغيّر وليس كائنًا حرفيًا طازجًا، لذا لا يُفحص الحقل الزائد sku؛ والشكل مطابق."},{"text":"لا، لأن product لم يُعرَّف أبدًا على أنه Money.","why":"TypeScript بنيوي؛ لا يسأل أبدًا بماذا عُرّفت القيمة، بل يسأل فقط إن كان شكلها مناسبًا."},{"text":"لا، لأن sku خاصية زائدة.","why":"فحوص الخصائص الزائدة لا تعمل إلا على الكائنات الحرفية المكتوبة مباشرة حيث يُنتظر النوع. عبر متغيّر، الحقول الإضافية مقبولة."}],"answer":0},{"q":"إذا فكّرت في الأنواع على أنها مجموعات من القيم، فأيّ العبارات صحيحة؟
","options":[{"text":"{ id: number; status: string } مجموعة أكبر من { id: number }.","why":"كل خاصية مطلوبة شرطٌ إضافي على القيمة أن تحقّقه، فإضافة خاصية تُصغّر المجموعة لا تكبّرها."},{"text":"never يحتوي كل القيم، ولهذا هو قابل للإسناد إلى كل شيء.","why":"never هو المجموعة الفارغة. وهو قابل للإسناد إلى كل شيء لأن المجموعة الفارغة جزء من كل مجموعة."},{"text":"'EUR' مجموعة جزئية من string، فالقيمة 'EUR' قابلة للإسناد إلى string والعكس غير صحيح.","why":"صحيح. قابلية الإسناد هي علاقة الاحتواء؛ المجموعة الأوسع لا تتدفّق إلى الأضيق دون فحص."},{"text":"unknown وany كلاهما المجموعة الفارغة.","why":"unknown هو مجموعة كل القيم. وany ليس مجموعة أصلًا؛ إنه يُطفئ الفحص في الاتجاهين."}],"answer":2},{"q":"لماذا يمرّ هذا الكود في الترجمة تحت strict؟
type CheckoutEvent = { type: 'paid' } | { type: 'shipped'; carrier: string };\ninterface Listener { onEvent(e: CheckoutEvent): void }\nconst l: Listener = { onEvent: (e: { type: 'shipped'; carrier: string }) => {} };onEvent."},{"text":"لأن onEvent تستخدم صيغة الـ method، ومعاملات الـ methods تُفحص فحصًا ثنائي التغاير حتى مع strictFunctionTypes.","why":"صحيح. كتابة onEvent: (e: CheckoutEvent) => void بدلًا منها تجعل فحص المعامل صارمًا وترفض هذا الـ listener."},{"text":"لأن المعامل من نوع union يقبل أيًّا من أعضائه.","why":"على الـ listener أن يتعامل مع كل أعضاء الـ union. قبول عضو واحد فقط غير آمن، والفحص الصارم كان سيلتقطه."}],"answer":1},{"q":"أيّ استدعاء يرفضه فحص الخصائص الزائدة؟
","options":[{"text":"ship(order) حيث order متغيّر فيه حقل إضافي notes","why":"المتغيّرات ليست طازجة، فلا تُفحص خصائصها الإضافية."},{"text":"ship({ ...order, notes: 'gift' }) حيث لا يحتوي Order حقلًا اسمه notes","why":"صحيح. الكائن الحرفي الذي فيه spread يبقى كائنًا حرفيًا طازجًا، وnotes مكتوب فيه مباشرة، فيُعلَّم. (أما الحقول الإضافية القادمة عبر ...order نفسه فلا تُفحص.)"},{"text":"ship(order as Order) حيث order فيه حقل إضافي notes","why":"تأكيد النوع يطلب من الـ compiler أن يثق بك، فيتخطّى فحص الخصائص الزائدة كليًا."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type PaymentFailed = { type: 'payment-failed'; orderId: number; reason: string };\ntype OrderShipped = { type: 'order-shipped'; orderId: number; carrier: string };\ntype CheckoutEvent = PaymentFailed | OrderShipped;\n\n// Cartwheel's checkout event bus.\ninterface CheckoutListener {\n onEvent(event: CheckoutEvent): void;\n}\n\nconst listeners: CheckoutListener[] = [];\nconst seen: string[] = [];\n\nfunction subscribe(listener: CheckoutListener): void {\n listeners.push(listener);\n}\n\nfunction emit(event: CheckoutEvent): void {\n for (const l of listeners) l.onEvent(event);\n}\n\n// Handles every event: must keep compiling.\nsubscribe({ onEvent: (e) => { seen.push(`${e.type}:${e.orderId}`); } });\n\n// A listener that takes no arguments at all: must keep compiling too.\nsubscribe({ onEvent: () => { seen.push('ping'); } });\n\n// ---- Type tests (do not edit) ----\n// This listener only understands PaymentFailed; an OrderShipped event would\n// crash it (e.reason is undefined). Subscribing it must be a type error.\nconst failuresOnly = { onEvent: (e: PaymentFailed) => { seen.push(e.reason.toUpperCase()); } };\n// @ts-expect-error: a PaymentFailed-only listener cannot receive every CheckoutEvent\nconst unsafe: CheckoutListener = failuresOnly;\n\nemit({ type: 'order-shipped', orderId: 1042, carrier: 'DHL' });\nconsole.log(seen);\n"},"solution":{"ts":"type PaymentFailed = { type: 'payment-failed'; orderId: number; reason: string };\ntype OrderShipped = { type: 'order-shipped'; orderId: number; carrier: string };\ntype CheckoutEvent = PaymentFailed | OrderShipped;\n\n// Cartwheel's checkout event bus.\n// Property syntax: the parameter is checked strictly (contravariantly).\ninterface CheckoutListener {\n onEvent: (event: CheckoutEvent) => void;\n}\n\nconst listeners: CheckoutListener[] = [];\nconst seen: string[] = [];\n\nfunction subscribe(listener: CheckoutListener): void {\n listeners.push(listener);\n}\n\nfunction emit(event: CheckoutEvent): void {\n for (const l of listeners) l.onEvent(event);\n}\n\n// Handles every event: must keep compiling.\nsubscribe({ onEvent: (e) => { seen.push(`${e.type}:${e.orderId}`); } });\n\n// A listener that takes no arguments at all: must keep compiling too.\nsubscribe({ onEvent: () => { seen.push('ping'); } });\n\n// ---- Type tests (do not edit) ----\n// This listener only understands PaymentFailed; an OrderShipped event would\n// crash it (e.reason is undefined). Subscribing it must be a type error.\nconst failuresOnly = { onEvent: (e: PaymentFailed) => { seen.push(e.reason.toUpperCase()); } };\n// @ts-expect-error: a PaymentFailed-only listener cannot receive every CheckoutEvent\nconst unsafe: CheckoutListener = failuresOnly;\n\nemit({ type: 'order-shipped', orderId: 1042, carrier: 'DHL' });\nconsole.log(seen);\n"},"checks":[{"id":"types","typecheck":true},{"id":"still-delivers","test":"return seen.includes('order-shipped:1042') && seen.includes('ping');"}],"title":"سُدّ ثغرة الـ listener","prompt":"يعرّف CheckoutListener الدالة onEvent بصيغة الـ method، فيفحص TypeScript معاملها فحصًا ثنائي التغاير (bivariant) ويقبل بلا تردّد failuresOnly، وهو listener سينهار أمام حدث OrderShipped. غيّر طريقة تعريف onEvent (لا نوع معاملها) بحيث يصبح إسناد failuresOnly إلى CheckoutListener خطأ نوع، مع بقاء استدعاءَي subscribe الموجودين يمرّان في الترجمة ووصول حدث الشحن إليهما.
name(arg: T): void. وصيغة الخاصية هي name: (arg: T) => void.","اكتب onEvent: (event: CheckoutEvent) => void;."],"explanation":"مع صيغة الـ method لا ينطبق strictFunctionTypes، فيمرّ listener لا يقبل إلا PaymentFailed على أنه listener يقبل كل CheckoutEvent. وحين تُعرَّف كخاصية من نوع دالة، يُفحص المعامل بتغاير معاكس: على الـ listener أن يقبل على الأقل كل ما يمكن أن يرسله الناقل. أما (e) => … فتأخذ نوع معاملها من السياق، و() => … تتجاهل الوسيط، فتبقى كلتاهما تمرّان. وصار لسطر @ts-expect-error خطأ حقيقي يتوقّعه.