إليك بلاغ خطأ قدّمه كل فريق TypeScript مرة على الأقل: “أمرّر النص الصحيح بالضبط ويقول لي Type 'string' is not assignable to type 'OrderStatus'.”
type OrderStatus = 'processing' | 'shipped' | 'delivered' | 'cancelled' | 'returned';\ntype Order = { id: number; status: OrderStatus };\nfunction save(order: Order) {}\n\nconst draft = { id: 1001, status: 'processing' };\nsave(draft);\n// Error: Argument of type '{ id: number; status: string; }' is not assignable\n// to parameter of type 'Order'.النص هو 'processing' فعلًا. لكن TypeScript لم يستنتج له 'processing'، بل استنتج string. هذا هو الاتساع (widening)، وفهمه يشرح ثلاث أدوات ستستخدمها كل أسبوع: الـ literal types (الأنواع الحرفية)، وas const، وsatisfies.
يستنتج TypeScript النوع الذي يُرجَّح أن تحمله القيمة طوال حياتها، لا القيمة التي تبدأ بها فقط. الـ const لا يمكن أن يتغيّر أبدًا، فيحتفظ بالقيمة الحرفية. أما let أو خاصية الكائن فيمكن إعادة الإسناد إليهما، فيوسّعهما TypeScript:
const a = 'processing'; // 'processing'\nlet b = 'processing'; // string\nconst c = { status: 'processing' }; // { status: string }الأخيرة هي المفاجأة. const c تمنعك من إعادة الإسناد إلى c، لكن c.status = 'anything' ما زالت JavaScript مشروعة، فتتّسع الخاصية إلى string.
هناك ثلاثة إصلاحات جيدة، مرتّبة حسب الأفضلية. اكتب القيمة الحرفية حيث يكون النوع معروفًا أصلًا (save({ id: 1001, status: 'processing' }))، فتُفحص مقابل Order مباشرة. أو علّق المتغيّر بنوعه (const draft: Order = …) حين تبنيه مسبقًا. أو استخدم as const، وهي موضوعنا التالي.
as const تطلب من TypeScript أن يستنتج أضيق نوع ممكن: كل قيمة حرفية تبقى حرفية، وكل مصفوفة تصبح tuple للقراءة فقط، وكل خاصية تصبح readonly:
const COUNTRIES = ['EG', 'AE', 'SA', 'JO', 'GB', 'DE', 'US', 'CA'] as const;\n// readonly ['EG', 'AE', 'SA', 'JO', 'GB', 'DE', 'US', 'CA']\n\ntype Country = (typeof COUNTRIES)[number];\n// 'EG' | 'AE' | 'SA' | 'JO' | 'GB' | 'DE' | 'US' | 'CA'ذلك السطر الثاني من أنفع الأنماط في TypeScript اليومية. typeof COUNTRIES تحوّل القيمة إلى نوعها، و[number] تسأل “ما النوع الذي أحصل عليه حين أفهرس هذا بأي رقم؟” (ستتعرّف على هذين العاملين (operators) كما ينبغي في keyof و typeof وأنواع الوصول بالفهرس). والنتيجة union مشتقّ من مصفوفة وقت التشغيل. تحصل على مصدر حقيقة واحد: المصفوفة موجودة وقت التشغيل للقوائم المنسدلة والتحقّق، والنوع يتبعها تلقائيًا.
function isCountry(value: string): value is Country {\n return (COUNTRIES as readonly string[]).includes(value);\n}التحويل الموسِّع داخل isCountry ضروري لأن includes على tuple من القيم الحرفية لا تقبل إلا تلك القيم، وهذا يُفسد الغاية من فحص نص اعتباطي.
كوبونات Cartwheel موجودة في كائن إعداد. الطريقة البديهية لتحديد نوعه هي التعليق النوعي:
\ntype Coupon = { kind: 'percent'; percentOff: number } | { kind: 'free-shipping' };\n\nconst coupons: Record<string, Coupon> = {\n WELCOME10: { kind: 'percent', percentOff: 10 },\n FREESHIP: { kind: 'free-shipping' },\n};\n\ncoupons.WELCOME10.percentOff; // Error: Property 'percentOff' does not exist on type 'Coupon'.\ncoupons.SPRNG15; // compiles, undefined at runtimeالتعليق النوعي يستبدل ما كان TypeScript يعرفه. كتبت WELCOME10 ككوبون نسبة مئوية، لكن نوعه صار مجرّد Coupon، والكائن يقبل أي مفتاح على الإطلاق، بما فيها الأخطاء الإملائية.
أما satisfies فتتحقّق من القيمة مقابل نوع دون أن تستبدل النوع المستنتَج:
const coupons = {\n WELCOME10: { kind: 'percent', percentOff: 10 },\n FREESHIP: { kind: 'free-shipping' },\n} satisfies Record<string, Coupon>;\n\ncoupons.WELCOME10.percentOff; // number\ncoupons.SPRNG15; // Error: Property 'SPRNG15' does not exist on type …ما زلت تحصل على التحقّق: percentof المكتوبة خطأً أو kind: 'bogo' تُعلَّم مباشرة في الكائن الحرفي. وتحتفظ بالمفاتيح والأشكال الدقيقة. كما أن satisfies تحدّد نوع القيم الحرفية من السياق، فيبقى kind بقيمة 'percent' بدل أن يتّسع إلى string، دون الحاجة إلى as const.
استخدم التركيبة as const satisfies T حين تريد الأمرين: قيمًا حرفية للقراءة فقط بعمق، وفحصًا مقابل شكل. تُقرأ من اليسار إلى اليمين هكذا: “جمّد هذا، ثم تأكّد أنه مناسب”.
قاعدة افتراضية بسيطة: علّق معاملات الدوال وأنواع الإرجاع والمتغيّرات التي يجب أن يكون نوعها هو النوع العام (let current: Order). استخدم satisfies لكائنات الإعداد وجداول البحث وكل ما تهمّ فيه المفاتيح والقيم المحدّدة لاحقًا. واستخدم as const للقوائم الثابتة التي تريدها union. الثلاثة كلها وقت الترجمة فقط؛ لا يغيّر أيٌّ منها بايتًا واحدًا من JavaScript الناتجة.
في التمرين ستشتقّ Country من قائمة دول Cartwheel، وتحدّد نوع جدول العملات بحيث يرفض الدول المجهولة ويتذكّر العملات بدقة. بهذا تكتمل أدوات التصميم في هذا القسم؛ وبعده تنتقل إلى الـ generics، بدءًا بالعلاقات التي تعبّر عنها.
let وخصائص الكائنات توسّع القيم الحرفية إلى string أو number؛ أما متغيّرات const فتحتفظ بالقيمة الحرفية.","as const تجعل القيمة للقراءة فقط بعمق وتحتفظ بكل قيمة حرفية، ما يتيح لك اشتقاق نوع union من مصفوفة وقت التشغيل.","التعليق النوعي (annotation) يستبدل النوع المستنتَج بالنوع المكتوب؛ أما satisfies فتتحقّق مقابل نوع وتحتفظ بالنوع المستنتَج.","تأكيدات as تتخطّى فحوصًا مثل الخصائص الناقصة، لذا استخدم satisfies حين تريد تحقّقًا لا ثقة عمياء."],"further":[{"title":"The satisfies operator (TypeScript 4.9 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html"},{"title":"Literal types","url":"https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types"},{"title":"const assertions (TypeScript 3.4 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html"}],"quiz":[{"q":"لماذا تفشل save(draft) حين يكون Order['status'] هو 'processing' | 'shipped'؟
const draft = { id: 1001, status: 'processing' };\nsave(draft);const تجعل الكائن كله للقراءة فقط، وsave تتوقّع كائنًا قابلًا للتعديل.","why":"const تمنع فقط إعادة الإسناد إلى draft. أما خصائصه فتبقى قابلة للتعديل، ولهذا بالضبط تتّسع."},{"text":"لأن draft.status يُستنتج على أنه string؛ خصائص الكائنات تتّسع لأنه قد يُعاد الإسناد إليها لاحقًا.","why":"صحيح. اكتب القيمة الحرفية حيث يكون النوع معروفًا (save({ … }))، أو علّق draft بالنوع Order، أو استخدم as const."},{"text":"لأن draft ليس فيه customerId.","why":"الـ Order في السؤال لا يحتاج إلا id وstatus. الفشل سببه status المتّسع."}],"answer":1},{"q":"ما هو Country هنا؟
const COUNTRIES = ['EG', 'AE', 'GB'] as const;\ntype Country = (typeof COUNTRIES)[number];string","why":"هذه ستكون النتيجة دون as const، حيث تُستنتج المصفوفة على أنها string[]."},{"text":"readonly ['EG', 'AE', 'GB']","why":"هذا هو typeof COUNTRIES. وفهرسته بـ [number] تعطي نوع عناصره."},{"text":"'EG' | 'AE' | 'GB'","why":"صحيح. as const تحتفظ بالقيم الحرفية، و[number] تطلب نوع أي عنصر في الـ tuple."}],"answer":2},{"q":"عُرّف coupons مع satisfies Record<string, Coupon>. أيّ سطر يُعدّ خطأً؟
type Coupon = { kind: 'percent'; percentOff: number } | { kind: 'free-shipping' };\nconst coupons = {\n WELCOME10: { kind: 'percent', percentOff: 10 },\n FREESHIP: { kind: 'free-shipping' },\n} satisfies Record<string, Coupon>;coupons.WELCOME10.percentOff","why":"satisfies تحتفظ بالنوع المستنتَج، فيعرف TypeScript أن WELCOME10 هو شكل النسبة المئوية وأن percentOff موجودة."},{"text":"coupons.FREESHIP.kind === 'free-shipping'","why":"النوع المستنتَج لـ kind هو القيمة الحرفية 'free-shipping'، فهذه المقارنة صالحة (وصادقة دائمًا)."},{"text":"coupons.SPRING15","why":"صحيح. النوع المستنتَج لا يحتوي إلا المفتاحين اللذين كتبتهما، فقراءة مفتاح مجهول خطأ، بخلاف التعليق النوعي Record<string, Coupon>."}],"answer":2},{"q":"يكتب زميل const config = { retries: 3 } as CheckoutConfig;، وCheckoutConfig يتطلّب أيضًا timeoutMs. ماذا يحدث؟
timeoutMs الناقصة.","why":"صحيح. as تطلب من الـ compiler أن يثق بك. استخدم satisfies CheckoutConfig أو تعليقًا نوعيًا لتحصل على خطأ الخاصية الناقصة."},{"text":"يفشل مع “Property ‘timeoutMs’ is missing”.","why":"هذا الخطأ يأتي من التعليقات النوعية ومن satisfies. أما التأكيد فلا يرفض إلا الأنواع التي لا تتداخل إطلاقًا."},{"text":"يضيف timeoutMs: undefined إلى الكائن وقت التشغيل.","why":"تأكيدات الأنواع تُمحى كليًا؛ لا تضيف قيمًا ولا تغيّرها أبدًا."}],"answer":0}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type Currency = 'EGP' | 'AED' | 'SAR' | 'JOD' | 'GBP' | 'EUR' | 'USD' | 'CAD';\ntype Coupon = { kind: 'percent'; percentOff: number } | { kind: 'free-shipping' };\n\nconst COUNTRIES = ['EG', 'AE', 'SA', 'JO', 'GB', 'DE', 'US', 'CA'];\ntype Country = string; // derive this from COUNTRIES\n\nconst currencyByCountry: Recordاجعل جداول البحث في Cartwheel دقيقة دون أن تكرّر نفسك:
\nCountry من المصفوفة COUNTRIES، بحيث يكون الـ union 'EG' | 'AE' | … | 'CA'.currencyByCountry بحيث يجب أن يحتوي مدخلًا واحدًا لكل Country، وبحيث يكون نوع currencyByCountry.DE هو 'EUR' بالضبط.coupons بحيث تُفحص كل قيمة مقابل Coupon، لكن لا يحتوي الكائن إلا المفاتيح الثلاثة التي كتبتها، ويُعرف أن SPRING15 كوبون نسبة مئوية.أبقِ isCountry تعمل وقت التشغيل مع أي نص.
as const على المصفوفة تحتفظ بقيمها الحرفية؛ و(typeof COUNTRIES)[number] تحوّلها إلى union.","استبدل التعليقات النوعية على الكائنين بـ satisfies: { … } satisfies Record<Country, Currency>. ولأن Currency هو union من قيم حرفية، تُبقي satisfies وحدها 'EUR' حرفية؛ وإضافة as const قبلها تجعل الجدول للقراءة فقط أيضًا.","حين تصير COUNTRIES tuple للقراءة فقط، لا تقبل includes إلا الدول. وسّعها من أجل الفحص: (COUNTRIES as readonly string[]).includes(value)."],"explanation":"as const تجمّد المصفوفة في tuple للقراءة فقط من القيم الحرفية، وفهرسة نوعها بـ [number] تعطي الـ union من عناصرها: قائمة واحدة تقود فحص وقت التشغيل والنوع معًا. التعليقات النوعية على الجدولين استبدلت أنواعهما المستنتَجة بأنواع عامة (أي مفتاح نصي، وقيم Currency، وأشكال Coupon). أما satisfies فتحتفظ بالفحص (دولة ناقصة، أو percentOff مكتوبة خطأً، أو عملة مجهولة ستُعلَّم كلها) مع الحفاظ على المفاتيح والقيم الدقيقة. ولأن النوع السياقي Currency هو union من قيم حرفية، تبقى 'EUR' حرفية بدل أن تتّسع إلى string؛ أما as const satisfies … فتجعل الجدول فوق ذلك للقراءة فقط.
isCountry تقبل دول Cartwheel وترفض غيرها وقت التشغيل","currency":"currencyFor تُعيد العملة الصحيحة"}},"words":633,"readMinutes":4}