مناطق الشحن في Cartwheel موجودة في كائن إعداد. النسخة الأولى من الكود وصفتها مرتين: مرة كبيانات، ومرة كأنواع.
\nconst SHIPPING_ZONES = {\n domestic: { countries: ['US', 'CA'], feeCents: 499 },\n gulf: { countries: ['AE', 'SA'], feeCents: 1299 },\n europe: { countries: ['GB', 'DE'], feeCents: 999 },\n};\n\ntype Zone = 'domestic' | 'gulf' | 'europe'; // written by handبعد ستة أشهر أضاف أحدهم منطقة levant إلى الكائن ونسي النوع. لم يفشل شيء في الترجمة؛ كل ما في الأمر أن المنطقة الجديدة لم يكن ممكنًا اختيارها في أي مكان. كل نسخة مكتوبة يدويًا من حقيقةٍ ما هي نسخة قابلة للتباعد. هذا الدرس يغطّي عوامل الأنواع (type operators) الثلاثة التي تتيح لك كتابة الحقيقة مرة واحدة واشتقاق الباقي.
في موضع النوع، تأخذ typeof قيمة وتعطيك النوع الذي استنتجه TypeScript لها. إنها ليست العامل typeof في JavaScript (الذي يُعيد نصوصًا مثل 'object' وقت التشغيل)؛ إنها لا توجد إلا وقت الترجمة.
const SHIPPING_ZONES = {\n domestic: { countries: ['US', 'CA'], feeCents: 499 },\n gulf: { countries: ['AE', 'SA'], feeCents: 1299 },\n europe: { countries: ['GB', 'DE'], feeCents: 999 },\n} as const;\n\ntype ShippingZones = typeof SHIPPING_ZONES;\n// { readonly domestic: { readonly countries: readonly ['US', 'CA']; readonly feeCents: 499 }; … }as const مهمة هنا، كما كانت في الـ Literal Types و as const و satisfies. دونها سيكون countries من نوع string[] وfeeCents من نوع number، وستفقد التفاصيل الجديرة بالاشتقاق.
تعمل typeof مع الدوال أيضًا: typeof formatPrice هو التوقيع الكامل للدالة، ويمكنك تمريره إلى utility types (أنواع مساعدة) مثل ReturnType<typeof formatPrice>. ستبني ReturnType بنفسك بعد درسين.
متى يجب أن تكون القيمة هي المصدر والنوع مشتقًا، لا العكس؟ استخدم typeof حين تكون البيانات هي التعريف: جداول البحث، وإعدادات المناطق، وقوائم الخيارات التي تُعرض أيضًا في الواجهة. واكتب النوع أولًا حين يكون الشكل عقدًا مع طرف آخر، مثل حمولة API، وافحص القيم مقابله.
keyof T هو الـ union من أسماء خصائص T:
type Zone = keyof typeof SHIPPING_ZONES; // 'domestic' | 'gulf' | 'europe'أضف levant إلى الكائن فيتحدّث Zone من تلقاء نفسه. وهذا هو المقصود كله.
تفصيلان يستحقان المعرفة. أولًا، مع نوع فيه index signature مثل Record<string, number>، تعطي keyof النوع string (وstring | number مع { [k: string]: … }، لأن JavaScript تحوّل المفاتيح الرقمية إلى نصوص). ثانيًا، keyof على union تعطي فقط المفاتيح التي يملكها كل عضو. keyof (ShippedOrder | CancelledOrder) هو 'id' | 'status'، لأن قراءة trackingNumber من شيء قد يكون طلبًا ملغى ليست آمنة.
T[K] تبحث عن نوع الخاصية K في T، بصياغة الأقواس المربّعة نفسها المستخدمة للوصول إلى الخصائص وقت التشغيل:
type GulfZone = ShippingZones['gulf']; // { readonly countries: …; readonly feeCents: 1299 }\ntype GulfFee = ShippingZones['gulf']['feeCents']; // 1299\ntype ZoneConfig = ShippingZones[Zone]; // union of all three configs\ntype FeeCents = ShippingZones[Zone]['feeCents']; // 499 | 1299 | 999\ntype ShippingCountry = ShippingZones[Zone]['countries'][number]; // 'US' | 'CA' | 'AE' | …الفهرسة بـ union تعطي union من النتائج، فيكون ShippingZones[Zone] هو “نوع قيمة أي منطقة”. والتعبير (typeof X)[keyof typeof X] هو طريقتك للحصول على الـ union من قيم الكائن، ويتكرّر بما يكفي لأن تسمّيه قواعد كود كثيرة ValueOf<T>.
المصفوفات والـ tuples تُفهرس بـ number: T[number] هو نوع العنصر. هذا هو (typeof COUNTRIES)[number] الذي استخدمته في القسم 1، وهو أيضًا السطر الأخير أعلاه، الذي يحفر عبر مستويين من الكائنات ومصفوفة واحدة ليجمع كل دولة في كل منطقة.
الحيلة نفسها تعمل على أنواع API لم تكتبها أنت. إن أعطاك عميل مولَّد نوعًا كبيرًا اسمه CheckoutResponse، يمكنك تسمية نوع البند بـ CheckoutResponse['lines'][number] بدل نسخ حقوله.
عاجلًا أو آجلًا ستكتب هذا وتنزعج:
\nfor (const zone of Object.keys(SHIPPING_ZONES)) {\n SHIPPING_ZONES[zone]; // Error: 'string' can't be used to index type …\n}تُعيد Object.keys النوع string[]، لا Zone[]، وهذا مقصود. تذكّر التنميط البنيوي: القيمة التي نوعها { a: number } قد تكون كائنًا فيه عشر خصائص أخرى وقت التشغيل. لو وعدت Object.keys بـ (keyof T)[]، لكانت تكذب بشأن تلك العشر.
مع كائن const عرّفته بنفسك، لا سبيل لتسلّل مفاتيح إضافية إليه، يكون التحويل المحلّي معقولًا وصادقًا: Object.keys(SHIPPING_ZONES) as Zone[]. أما مع الكائنات القادمة من مكان آخر، فأبقِ string وافحص كل مفتاح.
في التمرين ستشتقّ خمسة أنواع من إعدادات الشحن في Cartwheel ومن استجابة الـ API. والدرس القادم يذهب خطوة أبعد: بدل قراءة الخصائص من نوع، ستـحوّل كل خصائص النوع دفعة واحدة.
\n","toc":[{"id":"sec-1","text":"typeof: من القيم إلى الأنواع","level":2},{"id":"sec-2","text":"keyof: أسماء الخصائص","level":2},{"id":"sec-3","text":"الوصول بالفهرس: نوع الخاصية","level":2},{"id":"sec-4","text":"لماذا تُعيد Object.keys النوع string[]","level":2}],"takeaways":["في موضع النوع، تعطيtypeof value النوع الذي استنتجه TypeScript لتلك القيمة، فتكون جسرًا من كود وقت التشغيل إلى نظام الأنواع.","keyof T هو الـ union من أسماء خصائص T، وT[K] هو نوع الخاصية (أو الخصائص) التي يسمّيها K.","(typeof CONFIG)[keyof typeof CONFIG] يعطي الـ union من أنواع قيم الكائن، وT[number] يعطي نوع عنصر المصفوفة.","تُعيد Object.keys النوع string[] عن قصد: التنميط البنيوي يعني أن الكائن قد يحمل مفاتيح أكثر مما يسرده نوعه."],"further":[{"title":"Keyof Type Operator","url":"https://www.typescriptlang.org/docs/handbook/2/keyof-types.html"},{"title":"Typeof Type Operator","url":"https://www.typescriptlang.org/docs/handbook/2/typeof-types.html"},{"title":"Indexed Access Types","url":"https://www.typescriptlang.org/docs/handbook/2/indexed-access-types.html"}],"quiz":[{"q":"ما هو Zone؟
const SHIPPING_ZONES = {\n domestic: { feeCents: 499 },\n gulf: { feeCents: 1299 },\n} as const;\ntype Zone = keyof typeof SHIPPING_ZONES;'domestic' | 'gulf'","why":"صحيح. typeof تحوّل القيمة إلى نوعها، وkeyof تأخذ الـ union من أسماء خصائصها."},{"text":"string","why":"keyof على نوع كائن بخصائص معروفة يعطي تلك الأسماء بالضبط، لا string. لا تحصل على string إلا من index signature."},{"text":"{ feeCents: 499 } | { feeCents: 1299 }","why":"هذا هو الـ union من القيم، وتحصل عليه بـ (typeof SHIPPING_ZONES)[Zone]."},{"text":"خطأ، لأن keyof تحتاج نوعًا لا قيمة.","why":"typeof في موضع النوع تحوّل القيمة أولًا، فتتلقّى keyof نوعًا فعلًا."}],"answer":0},{"q":"type CheckoutResponse = { lines: { sku: string; qty: number }[] }. أيّ نوع يساوي { sku: string; qty: number }؟
CheckoutResponse.lines[0]","why":"الوصول بالنقطة غير موجود في مواضع الأنواع؛ يقرأ TypeScript CheckoutResponse.lines كبحث في namespace فيفشل."},{"text":"CheckoutResponse['lines']","why":"هذا نوع المصفوفة كاملة، { sku: string; qty: number }[]، لا عنصر واحد."},{"text":"keyof CheckoutResponse['lines']","why":"هذا يعطي مفاتيح المصفوفة (number و'length' و'map' …)، لا عناصرها."},{"text":"CheckoutResponse['lines'][number]","why":"صحيح. فهرسة نوع مصفوفة بـ number تعطي نوع عنصرها."}],"answer":3},{"q":"ما هو keyof (ShippedOrder | CancelledOrder) حين يملك كلاهما id وstatus، ولا يملك trackingNumber إلا ShippedOrder، ولا يملك cancelReason إلا CancelledOrder؟
'id' | 'status' | 'trackingNumber' | 'cancelReason'","why":"هذا سيتيح لك قراءة trackingNumber من قيمة قد تكون طلبًا ملغى، وهذا غير آمن."},{"text":"'id' | 'status'","why":"صحيح. مفتاح الـ union يجب أن يكون مفتاحًا في كل عضو، فلا يبقى إلا الخصائص المشتركة."},{"text":"never، لأن النوعين مختلفان","why":"العضوان يشتركان في id وstatus، فتنجو تلك المفاتيح."}],"answer":1},{"q":"لماذا تُعيد Object.keys(order) النوع string[] بدل (keyof Order)[]؟
keyof غير متاحة في ملفات الـ lib.","why":"ملفات الـ lib تستخدم keyof في كل مكان؛ هذا ليس قيدًا تقنيًا."},{"text":"لأن القيمة من نوع Order قد تحمل خصائص إضافية وقت التشغيل لا يسردها النوع.","why":"صحيح. التنميط البنيوي يسمح لـ DetailedOrder بالمرور كـ Order، فتظهر مفاتيحه الإضافية وقت التشغيل."}],"answer":2}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"const SHIPPING_ZONES = {\n domestic: { countries: ['US', 'CA'], feeCents: 499 },\n gulf: { countries: ['AE', 'SA'], feeCents: 1299 },\n levant: { countries: ['EG', 'JO'], feeCents: 899 },\n europe: { countries: ['GB', 'DE'], feeCents: 999 },\n} as const;\n\n// Shape of the checkout API response (generated from the backend's schema).\ntype CheckoutResponse = {\n order: { id: number; status: 'processing' | 'shipped'; totalCents: number };\n lines: { sku: string; quantity: number; unitPriceCents: number }[];\n};\n\ntype Zone = string;\ntype ShippingCountry = string;\ntype FeeCents = number;\ntype LineItem = unknown;\ntype CheckoutStatus = string;\n\nfunction zoneFor(country: ShippingCountry): Zone {\n for (const [zone, config] of Object.entries(SHIPPING_ZONES)) {\n if ((config.countries as readonly string[]).includes(country)) return zone;\n }\n throw new Error(`No shipping zone for ${country}`);\n}\n\nfunction feeFor(country: ShippingCountry): FeeCents {\n return SHIPPING_ZONES[zoneFor(country)].feeCents;\n}\n\n// ---- Type tests (do not edit) ----\ntype T1 = Expectاستبدل الأنواع الخمسة المكتوبة يدويًا بأنواع مشتقّة من SHIPPING_ZONES وCheckoutResponse، بحيث تتحدّث تلقائيًا عند إضافة منطقة أو تغيير نوع الـ API:
Zone: أسماء المناطق.ShippingCountry: كل دولة في كل منطقة.FeeCents: رسوم كل منطقة، كأرقام حرفية.LineItem: عنصر واحد من CheckoutResponse['lines'].CheckoutStatus: نوع status في الطلب.ثم اجعل zoneFor وfeeFor تمرّان في الترجمة بالأنواع الجديدة (بلا any).
typeof SHIPPING_ZONES؛ وkeyof عليه تعطي أسماء المناطق.","افهرس بالـ union من أسماء المناطق لتصل إلى كل الإعدادات دفعة واحدة: ShippingZones[Zone]['feeCents']. والمصفوفات تُفهرس بـ number.","Object.entries وObject.keys تعطيانك مفاتيح من نوع string. ولأن SHIPPING_ZONES كائنك الخاص المعرَّف بـ as const، فإن Object.keys(SHIPPING_ZONES) as Zone[] تحويل محلّي صادق."],"explanation":"تُدخل typeof كائن الإعداد إلى عالم الأنواع، وتسرد keyof أسماء مناطقه، والوصول بالفهرس بالـ union المسمّى Zone يصل إلى كل المناطق دفعة واحدة، فيجمع ShippingZones[Zone]['countries'][number] كل الدول. ويسمّي CheckoutResponse['lines'][number] نوع البند دون نسخ حقوله. تُعيد Object.keys النوع string[] لأن الكائنات قد تحمل مفاتيح إضافية وقت التشغيل؛ أما مع كائن const عرّفته أنت، فالتحويل إلى Zone[] آمن، ويجلس التحويل بجوار تعليق يشرح السبب.
zoneFor تجد المنطقة الصحيحة لدولة ما","fee":"feeFor تُعيد رسوم المنطقة"}},"words":651,"readMinutes":4}