إليك توقيع الدالة التي في قلب نظام الدفع في Cartwheel:
\nasync function placeOrder(cart: Cart, payment: PaymentMethod): Promise<Order> { /* … */ }يمكن أن تفشل بخمس طرق على الأقل يتوقّعها العمل كل يوم: البطاقة مرفوضة، أو منتج نفد من المخزون، أو الكوبون منتهي الصلاحية، أو العنوان لا يمكن التوصيل إليه، أو مزوّد الدفع يطلب 3-D Secure. التوقيع لا يذكر أيًّا منها. إنها استثناءات تُرمى من مكان ما في الداخل، وليس في TypeScript جملة throws. المستدعي الذي ينسى try/catch يمرّ في الترجمة بلا مشكلة، والعميل يرى شاشة فارغة.
الإصلاح أن تُعيد الإخفاقات المتوقَّعة بدل رميها، باستخدام discriminated union تعرف كتابته أصلًا:
\ntype Result<T, E> = { ok: true; value: T } | { ok: false; error: E };\n\nconst ok = <T>(value: T): { ok: true; value: T } => ({ ok: true, value });\nconst err = <E>(error: E): { ok: false; error: E } => ({ ok: false, error });ok هو المميِّز. لا يستطيع المستدعي قراءة value دون أن يثبت أولًا أن الاستدعاء نجح، لأن value لا توجد إلا في عضو واحد:
const result = await placeOrder(cart, payment);\nshowConfirmation(result.value);\n// Error: Property 'value' does not exist on type 'Result<Order, CheckoutError>'.\n// Property 'value' does not exist on type '{ ok: false; error: CheckoutError; }'.\n\nif (result.ok) showConfirmation(result.value); // fineيمكن أن يكون E نصًا، لكن النص في الأخطاء هو نظير status: string في الحالات. نمذج الإخفاقات كـ discriminated union، كلٌّ منها بالبيانات اللازمة لمعالجته:
type CheckoutError =\n | { type: 'card-declined'; declineCode: string }\n | { type: 'out-of-stock'; sku: string; available: number }\n | { type: 'coupon-expired'; code: string; expiredOn: string };\n\nfunction errorMessage(e: CheckoutError): string {\n switch (e.type) {\n case 'card-declined': return `Your card was declined (${e.declineCode}).`;\n case 'out-of-stock': return `Only ${e.available} of ${e.sku} left.`;\n case 'coupon-expired': return `${e.code} expired on ${e.expiredOn}.`;\n }\n}نوع الإرجاع : string يجعل هذا شاملًا، كما رأيت في القسم 1. وحين يضيف فريق المدفوعات 'requires-3ds' إلى الـ union، تُعلَّم كل دالة رسائل وكل فرع في الواجهة يتفرّع على type.
الدفع تسلسل: تحقّق من السلة، ثم طبّق الكوبون، ثم اخصم من البطاقة. كل خطوة يمكن أن تفشل بأخطائها الخاصة. والعودة المبكرة تركّبها دون تداخل:
\ntype CartError = { type: 'out-of-stock'; sku: string; available: number };\ntype CouponError = { type: 'coupon-expired'; code: string; expiredOn: string };\n\nasync function checkout(input: CheckoutInput): Promise<Result<Order, CartError | CouponError | PaymentError>> {\n const cart = validateCart(input.lines);\n if (!cart.ok) return cart;\n\n const priced = applyCoupon(cart.value, input.coupon);\n if (!priced.ok) return priced;\n\n const charge = await chargeCard(priced.value.total, input.payment);\n if (!charge.ok) return charge;\n\n return ok(createOrder(priced.value, charge.value));\n}بعد if (!cart.ok)، يضيق cart إلى { ok: false; error: CartError }، وهو قابل للإسناد إلى نوع الإخفاق الأوسع للدالة، فيمكن إعادته كما هو. ومسار النجاح يُقرأ من الأعلى إلى الأسفل، ونوع الإرجاع يوثّق كل إخفاق على المستدعي معالجته. وإن أضاف أحدهم لاحقًا خطوة رابعة بنوع خطأ جديد ونسي توسيع نوع الإرجاع، فإن return لإخفاق تلك الخطوة يكون خطأ ترجمة، فلا يمكن لقائمة الإخفاقات أن تتقادم بصمت.
سترى مكتبات تقدّم methods مثل map وandThen لسلسلة النتائج بدلًا من ذلك. لا بأس بها، لكن في TypeScript يكون أسلوب العودة المبكرة عادةً أسهل قراءة ولا يحتاج إلى مكتبة: الـ narrowing يقوم بالعمل.
معظم الإخفاقات في نظام الدفع تبدأ حياتها كاستثناءات في كود شخص آخر: الـ SDK الخاص بالدفع يرمي CardError، وfetch تُرفض حين تنقطع الشبكة. حوّلها مرة واحدة، عند الحافة، إلى الـ Result الذي يتحدّثه كودك:
type PaymentError = { type: 'card-declined'; declineCode: string };\n\nasync function chargeCard(amount: Money, payment: PaymentMethod): Promise<Result<Receipt, PaymentError>> {\n try {\n return ok(await paymentSdk.charge(amount, payment));\n } catch (e: unknown) {\n if (e instanceof CardError) return err({ type: 'card-declined', declineCode: e.code });\n throw e; // not a failure we understand: let it propagate\n }\n}ثلاثة أمور تستحق التقليد. متغيّر catch من نوع unknown، كما هو دائمًا تحت strict، فتضيّقه بـ instanceof قبل قراءة code. ولا يتحوّل إلى قيمة إلا الإخفاق الوحيد الذي يتوقّعه العمل؛ وكل ما عداه يُعاد رميه دون مساس، مع الـ stack trace كاملًا. ونوع إرجاع الدالة صار الآن قائمة صادقة بما يمكن أن يسوء، يراها كل مستدعٍ في التلميح.
النتائج غير المتزامنة تتداخل بالطريقة البديهية، Promise<Result<T, E>>. الـ promise المرفوض ما زال يعني “حدث شيء غير متوقَّع”، و{ ok: false } المحلول يعني “العمل قال لا”. وإبقاء هاتين القناتين منفصلتين هو الغاية كلها.
Result للإخفاقات التي يتوقّعها العمل ويستطيع المستدعي التصرّف بناءً عليها. إنه ليس بديلًا عن كل throw:
null حيث تقول الأنواع إنه لا يمكن وجوده، أو عضو union غير مُعالَج يصل إلى assertNever) يجب أن ترمي استثناءً. لا يوجد ما هو معقول ليفعله المستدعي، وأنت تريد الـ stack trace.err(…) ويُعاد رمي الباقي.في التمرين ستبني خطوة الكوبون في Cartwheel بـ Result، وتركّبها في دالة دفع، وتكتب رسائل الأخطاء الشاملة. والدرس القادم يتناول البيانات التي تبدأ منها تلك الخطوات: المدخلات غير الموثوقة.
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E } هو discriminated union، فعلى المستدعين فحص ok قبل أن يستطيعوا قراءة value.","نمذج الأخطاء أيضًا كـ discriminated union، كي يحمل كل إخفاق بياناته الخاصة وتستطيع الواجهة معالجة كل حالة بشمول.","ركّب النتائج بالعودة المبكرة (if (!r.ok) return r;)؛ فالإخفاق المضيَّق قابل للإسناد إلى union الأخطاء الأوسع لدى المستدعي.","استخدم Result للإخفاقات التي يتوقّعها العمل؛ واحتفظ بـ throw للأخطاء البرمجية والثوابت المكسورة وأعطال البنية التحتية التي لا يمكنك معالجتها محليًا."],"further":[{"title":"Discriminated unions (Narrowing)","url":"https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions"},{"title":"Control flow and error handling (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling"}],"quiz":[{"q":"يمكن أن تفشل placeOrder(cart): Promise<Order> ببطاقة مرفوضة. ماذا يقول توقيعها للمستدعي عن ذلك؟
throws في TypeScript، ولهذا تنتمي الإخفاقات المتوقَّعة إلى نوع الإرجاع."},{"text":"أنها تُرفض بـ Error، لأن كل promise يمكن أن يُرفض.","why":"أي promise يمكن أن يُرفض بأي قيمة. التوقيع لا يقول أيّ الإخفاقات متوقَّعة ولا ما البيانات التي تحملها."},{"text":"أن على المستدعي تغليفها بـ try/catch، وهذا ما يفرضه strict.","why":"لا يوجد خيار في الـ compiler يفرض try/catch؛ ونسيانها يمرّ في الترجمة بلا مشكلة."},{"text":"أنها قد ترمي CardDeclinedError، مستنتَجًا من التنفيذ.","why":"الأنواع المرمية لا تُستنتج ولا تُتتبّع أبدًا، حتى مع تفعيل كل الخيارات الصارمة."}],"answer":0},{"q":"لماذا يفشل السطر الأخير في الترجمة؟
\ntype Result<T, E> = { ok: true; value: T } | { ok: false; error: E };\ndeclare const r: Result<Order, CheckoutError>;\nconsole.log(r.value.id);value اختيارية في Result.","why":"value إلزامية في عضو النجاح. المشكلة أنها غير موجودة إطلاقًا في عضو الإخفاق."},{"text":"لأنه يجب انتظار Result بـ await أولًا.","why":"r ليست promise في هذا المقطع؛ لا شيء يحتاج إلى انتظار."},{"text":"لأن value لا توجد إلا في العضو ok: true، ولم يُضيَّق r بعد.","why":"صحيح. فحص if (r.ok) يضيّق r إلى عضو النجاح، حيث تكون value متاحة."}],"answer":2},{"q":"أيّ إخفاق يناسب Result بدل الاستثناء؟
null إلى دالة تقول أنواعها إنها لا يمكن أن تكون null.","why":"هذا ثابت مكسور، أي خطأ برمجي. ارمِ استثناءً، وأصلح الكود الذي سمح بحدوثه."},{"text":"نفاد مجمّع الاتصالات بقاعدة البيانات.","why":"عطل في البنية التحتية لا يستطيع نظام الدفع معالجته محليًا؛ دعه ينتشر إلى حدّ الأخطاء أو طبقة إعادة المحاولة."},{"text":"انتهاء صلاحية رمز الكوبون الذي كتبه العميل.","why":"صحيح. إنه متوقَّع، ويستطيع المستدعي فعل شيء مفيد (عرض رسالة)، ويحمل بيانات (الرمز وتاريخ انتهائه)."}],"answer":2},{"q":"تُعيد validateCart النوع Result<Cart, CartError> وتُعيد checkout النوع Result<Order, CartError | PaymentError>. هل يمرّ هذا في الترجمة؟
const cart = validateCart(input);\nif (!cart.ok) return cart;Result<Cart, CartError> ليس Result<Order, …>.","why":"بعد الفحص، يكون cart عضو الإخفاق فقط، { ok: false; error: CartError }، وليس فيه Cart."},{"text":"لا، يجب إعادة بناء الإخفاق بـ err(cart.error).","why":"إعادة البناء تعمل، لكنها غير ضرورية؛ الإخفاق المضيَّق مناسب أصلًا."},{"text":"فقط مع تحويل as.","why":"لا حاجة إلى تحويل؛ قابلية الإسناد تتكفّل بذلك."},{"text":"نعم، لأن { ok: false; error: CartError } المضيَّق قابل للإسناد إلى عضو الإخفاق الأوسع.","why":"صحيح. CartError جزء من CartError | PaymentError، فيمكن إعادة الإخفاق كما هو."}],"answer":3}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"type Coupon = { code: string; percentOff: number; expiresOn: string };\ntype Cart = { lines: { sku: string; quantity: number; unitPriceCents: number }[] };\ntype PricedCart = Cart & { totalCents: number };\n\nconst COUPONS: Coupon[] = [\n { code: 'WELCOME10', percentOff: 10, expiresOn: '2099-12-31' },\n { code: 'SPRING15', percentOff: 15, expiresOn: '2025-05-31' },\n];\nconst STOCK: Recordحوّل خطوة الكوبون في Cartwheel إلى إخفاقات متوقَّعة محدَّدة الأنواع:
\nResult<T, E> كـ discriminated union على ok، مع الدالتين المساعدتين ok(value) وerr(error).findCoupon تُعيد Result<Coupon, CouponError>: coupon-unknown حين لا يوجد الرمز، وcoupon-expired (مع expiredOn) حين يكون expiresOn قبل today.checkout تُعيد Result<PricedCart, CheckoutError>: افحص المخزون أولًا، ثم الكوبون (حين لا يكون couponCode هو null)، ثم أعِد السلة مع totalCents (المجموع الفرعي ناقص نسبة الكوبون، مقرّبًا).errorMessage تُعيد رسالة لكل نوع خطأ تتضمّن بياناته (الرمز، أو تاريخ الانتهاء، أو رمز المنتج SKU).type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }; وconst ok = <T>(value: T): { ok: true; value: T } => ({ ok: true, value });.","في checkout، استخدم العودة المبكرة: const stocked = checkStock(cart); if (!stocked.ok) return stocked;. الإخفاق المضيَّق يناسب الـ union الأوسع CheckoutError.","علّق نوع إرجاع checkout صراحة، وتفرّع على e.type في errorMessage مع نوع إرجاع : string كي تكون الحالة المنسيّة خطأ ترجمة."],"explanation":"حين يكون Result هو discriminated union، فإن value ببساطة غير موجودة حتى يفحص المستدعي ok، وهذا ما يثبته سطر @ts-expect-error. صارت findCoupon تعلن إخفاقَيها المتوقَّعين في توقيعها بدل إخفائهما في throw. والعودة المبكرة تُبقي checkout مسطّحة: كل إخفاق مضيَّق قابل للإسناد إلى CheckoutError، فيُعاد دون تغيير. ولأن الأخطاء union بمميِّز type، تستطيع errorMessage استخدام بيانات كل إخفاق، وإضافة نوع خطأ جديد لاحقًا تعلّم هذه الدالة تلقائيًا.
coupon-expired مع تاريخ انتهائه","stock-first":"يُفحص المخزون قبل الكوبون","messages":"errorMessage تتضمّن بيانات كل إخفاق"}},"words":632,"readMinutes":4}