في تصميم عميل API بأنواع دقيقة، انتهى العميل بـ return result as Routes[R]['output']. ذلك التحويل كان وعدًا بشأن الخادم. وهذا الدرس عن إبقاء ذلك الوعد صادقًا.
لكل برنامج حدود (boundary): المواضع التي تأتي منها البيانات من مكان لا يستطيع الـ compiler رؤيته. استجابات HTTP، وJSON.parse، ومعاملات الروابط، وlocalStorage، وحقول النماذج، والرسائل من نوافذ أخرى، ومتغيّرات البيئة. داخل الحدود، تصف الأنواع قيمًا أنشأها كودك. وعند الحدود، الأنواع مجرّد آمال. وللنمط الذي يتعامل مع ذلك شعار معروف: حلّل، لا تتحقّق فقط (parse, don’t validate). حوّل البيانات غير المحدَّدة الأنواع إلى بيانات محدَّدة الأنواع مرة واحدة، عند الحافة، ودع بقية البرنامج يثق بالأنواع.
JSON.parse تُعيد any، وكذلك Response.json(). وany معدية: أسندها إلى متغيّر نوعه Order فيصدّقك TypeScript. الخطوة الأولى أن ترفض هذه الهدية:
const raw: unknown = await res.json();\nraw.status;\n// Error: 'raw' is of type 'unknown'.unknown هو النوع الصادق للبيانات التي لم تفحصها. يمكنك تمريرها، لكن لا يمكنك استخدامها حتى تضيّقها. والتضييق هو ما يفعله المحلّل.
يأخذ المحلّل unknown ويُعيد إمّا قيمة محدَّدة النوع أو وصفًا لما كان خاطئًا. مع نوع Result من الدرس السابق:
const STATUSES = ['processing', 'shipped', 'delivered', 'cancelled', 'returned'] as const;\ntype OrderStatus = (typeof STATUSES)[number];\ntype Order = { id: number; status: OrderStatus; totalCents: number; couponCode: string | null };\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction isOrderStatus(value: unknown): value is OrderStatus {\n return typeof value === 'string' && (STATUSES as readonly string[]).includes(value);\n}\n\nfunction parseOrder(input: unknown): Result<Order, string> {\n if (!isRecord(input)) return err('order: expected an object');\n const { id, status, totalCents, couponCode } = input;\n if (typeof id !== 'number' || !Number.isInteger(id)) return err('id: expected an integer');\n if (!isOrderStatus(status)) return err(`status: unknown value ${JSON.stringify(status)}`);\n if (typeof totalCents !== 'number') return err('totalCents: expected a number');\n if (couponCode !== null && typeof couponCode !== 'string') return err('couponCode: expected a string or null');\n return ok({ id, status, totalCents, couponCode });\n}انظر إلى السطر الأخير: لا يوجد تحويل. كل فحص ضيّق متغيّرًا واحدًا، وفي النهاية يستطيع TypeScript التحقّق من أن الكائن الحرفي يطابق Order. وإن اكتسب النوع حقلًا ونسيه المحلّل، يفشل سطر ok(…) في الترجمة. وهذا أيضًا هو المكان الذي تسِم فيه القيم، باستدعاء toOrderId(id) من الـ Branded Types والفحوص الشاملة.
عودةً إلى العميل، إصلاح ذلك التحويل الأخير هو جدول من المحلّلات، واحد لكل مسار، يُفحص مقابل خريطة المسارات بـ mapped type وsatisfies:
const parsers = {\n 'GET /orders/:id': parseOrder,\n 'GET /orders': parseOrderPage,\n 'POST /orders/:id/cancel': parseCancelledOrder,\n} satisfies { [R in keyof Routes]: (input: unknown) => Result<Routes[R]['output'], string> };انسَ مسارًا فتبلّغ satisfies عن المفتاح الناقص؛ وأعِد النوع الخاطئ من محلّل فتبلّغ عن ذلك أيضًا. داخل call، تمرّ الاستجابة الآن عبر parsers[route] قبل إعادتها. لا يستطيع TypeScript ربط الـ R العام بالصف المطابق في الجدول، فيبقى تعليق نوعي واحد هناك، لكنه يقع الآن على بيانات فُحصت فعلًا: أنواع مخرجات العميل مكتسَبة لا مُدّعاة.
isRecord وisOrderStatus هما type predicates (دوال حارسة للنوع): دوال نوع إرجاعها value is T. حين تُعيد إحداها true، يضيّق TypeScript الوسيط في موضع الاستدعاء. ومنذ TypeScript 5.5، تُستنتج البسيطة منها مثل (x) => x !== null، كما رأيت في القسم 1، لكن أي شيء فيه منطق حقيقي يحتاج إلى التعليق النوعي.
أحيانًا تريد التضييق والتوقّف إن كانت البيانات سيئة، دون if في كل موضع استدعاء. دالة التأكيد (assertion function) لا تُعيد شيئًا وترمي خطأً عند الفشل، ونوع إرجاعها asserts يضيّق كل ما يلي الاستدعاء:
function assertIsOrder(input: unknown): asserts input is Order {\n const parsed = parseOrder(input);\n if (!parsed.ok) throw new Error(`Invalid order: ${parsed.error}`);\n}\n\nconst raw: unknown = JSON.parse(cachedJson);\nassertIsOrder(raw);\nraw.status; // OrderStatusتناسب دوال التأكيد الأماكن التي تكون فيها البيانات السيئة خطأً برمجيًا لا حالة متوقَّعة: دوال الاختبار المساعدة، والبيانات التي عرضها خادمك في الصفحة، والثوابت. أما لاستجابات HTTP، ففضّل محلّلًا يُعيد Result، كي ينتج تغيّر الـ API خطأً مُعالَجًا لا انهيارًا. وهناك غرابة واحدة: يجب أن تُستدعى دالة التأكيد عبر اسم له نوع صريح، فـ const assertIsOrder = (x: unknown): asserts x is Order => … تحتاج إلى تعليق نوعي على الـ const نفسه، وإلا يبلّغ TypeScript عن “Assertions require every name in the call target to be declared with an explicit type annotation”.
في التمرين ستكتب محلّل الطلبات في Cartwheel وpredicate ودالة تأكيد، وتستبدل تحويلًا ظل يكذب منذ اليوم الأول. والدرس القادم يبني باعثات أحداث وبنّائين محدَّدي الأنواع فوق كل ما في هذا القسم.
\n","toc":[{"id":"sec-1","text":"ابدأ من unknown","level":2},{"id":"sec-2","text":"محلّل مكتوب يدويًا","level":2},{"id":"sec-3","text":"سدّ الفجوة في عميل الـ API","level":3},{"id":"sec-4","text":"الـ type predicates","level":2},{"id":"sec-5","text":"دوال التأكيد","level":2}],"takeaways":["JSON.parse وresponse.json() وlocalStorage تعطيك any؛ علّق نتائجها بـ unknown كي يجبرك الـ compiler على الفحص.","المحلّل يأخذ unknown ويُعيد قيمة محدَّدة النوع أو خطأً، فلا يرى بقية الكود إلا بيانات فُحصت.","الـ type predicate (value is T) يضيّق النوع في موضع الاستدعاء، لكن TypeScript يثق بجسمه، فالـ predicate الخاطئ تحويل غير مفحوص.","دالة التأكيد (asserts value is T) تضيّق كل ما يلي الاستدعاء، ويجب أن ترمي خطأً حين يفشل الفحص.","مكتبات المخطّطات تعلن الفحص مرة واحدة وتشتقّ النوع منه، فتُزيل خطر التباعد بين المحلّل والنوع."],"further":[{"title":"Using type predicates","url":"https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates"},{"title":"Assertion functions (TypeScript 3.7 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html"},{"title":"JSON.parse() (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse"}],"quiz":[{"q":"const data = await res.json(); ما نوع data، وماذا يجب أن تفعل حياله؟
unknown؛ ضيّقه قبل الاستخدام.","why":"Response.json() معلَنة على أنها تُعيد Promise<any>، لا unknown، فلا شيء يجبرك على التضييق ما لم تعلّقها بنوع."},{"text":"Order، مستنتَجًا من رابط الـ endpoint.","why":"لا يستطيع TypeScript معرفة ما يُعيده الخادم؛ الرابط بالنسبة إليه مجرّد نص."},{"text":"object؛ حوّله بـ as Order.","why":"النوع any، والتحويل يتخطّى الفحص الذي كان سيلتقط تغيّر الـ API."},{"text":"any؛ علّقه بـ unknown ومرّره عبر محلّل.","why":"صحيح. any تُطفئ الفحص في كل استخدام؛ وunknown تجبر كل استخدام على أن يُثبَت أولًا."}],"answer":3},{"q":"ما الخطأ في هذا الـ predicate؟
\nfunction isOrder(value: unknown): value is Order {\n return typeof value === 'object' && value !== null && 'id' in value;\n}id يكفي لإثبات أن القيمة Order.","why":"سجلّ العميل فيه id أيضًا. الـ predicate يدّعي أكثر بكثير مما يفحص."},{"text":"يدّعي أن القيمة Order كامل لكنه لا يفحص إلا id، ويثق TypeScript بالادّعاء دون التحقّق منه.","why":"صحيح. جسم الـ predicate لا يُفحص مقابل نوع إرجاعه، فالفحص الضعيف تحويل غير مفحوص."},{"text":"الـ predicates لا يمكنها استخدام المعامل in.","why":"in فحص تضييق عادي ويعمل جيدًا داخل الـ predicates."}],"answer":1},{"q":"كيف تختلف دالة التأكيد عن الـ type predicate؟
","options":[{"text":"دالة التأكيد تُعيدboolean؛ والـ predicate يُعيد void.","why":"العكس هو الصحيح. الـ predicate يُعيد boolean؛ ودالة التأكيد لا تُعيد شيئًا وترمي خطأً عند الفشل."},{"text":"دالة التأكيد تضيّق القيمة لبقية النطاق بعد الاستدعاء، وترمي خطأً إن فشل الفحص.","why":"صحيح. assertIsOrder(x); x.id تعمل، لأن العودة الطبيعية تثبت التأكيد."},{"text":"دوال التأكيد لا تعمل إلا على الأنواع الأولية.","why":"تعمل على أي نوع، بما فيه الكائنات والـ unions."}],"answer":1},{"q":"أين يجب تحليل القيمة القادمة من localStorage.getItem('cart')؟
استبدل التحويل الكاذب في parseOrder بمحلّل حقيقي، وأعطِ الدوال المساعدة أنواعًا حقيقية:
isRecord وisOrderStatus من نوع type predicates.parseOrder(input: unknown) القيمة ok(order) فقط حين يكون id عددًا صحيحًا، وstatus حالة معروفة، وtotalCents عددًا صحيحًا، وcouponCode نصًا أو null. وإلا فإنها تُعيد err(message)، حيث تبدأ الرسالة باسم الحقل الخاطئ (مثلًا status: …). ويجب ألّا يحتوي الطلب المُعاد إلا هذه الحقول الأربعة.assertIsOrder دالة تأكيد تضيّق وسيطها إلى Order وترمي Error تحتوي رسالته Invalid order حين يفشل التحليل.بلا تحويلات as في parseOrder.
value is Record<string, unknown> وvalue is OrderStatus.","في parseOrder، افحص isRecord(input) أولًا، وفكّك الحقول الأربعة، وافحص كلًّا منها بـ typeof أو بالـ predicate الخاص بك، مُعيدًا err('field: …') عند أول فشل.","ابنِ النتيجة من المتغيّرات المضيَّقة، ok({ id, status, totalCents, couponCode })، كي يتحقّق منها TypeScript وتُسقط الحقول الإضافية. وفي التأكيد، نوع الإرجاع هو asserts input is Order."],"explanation":"كان input as Order القديم يسمح بمرور أي شيء، بما في ذلك حالة لا فرع لها في الواجهة. الآن يُضيَّق كل حقل بفحص عادي، ويُبنى الكائن الحرفي الأخير من المتغيّرات المضيَّقة، فيتحقّق الـ compiler من مطابقته لـ Order دون تحويل، ولا تعبر الحقول غير المتوقَّعة مثل cardNumber الحدود أبدًا. والـ predicates الاثنان صغيران بما يكفي ليكونا صحيحين بوضوح. وتعيد assertIsOrder استخدام المحلّل وتحوّل الفشل إلى خطأ مرمي، وتوقيعها asserts يضيّق متغيّر المستدعي لبقية النطاق.
status","rejects-types":"تُرفض أنواع الحقول الخاطئة والمصفوفات وnull برسائل تسمّي الحقل","only-known-fields":"لا تُنسخ الحقول غير المتوقَّعة إلى الطلب المحلَّل","asserts":"assertIsOrder ترمي ‘Invalid order…’ مع البيانات السيئة"}},"words":661,"readMinutes":4}