يحجز نظام الدفع في Cartwheel المخزون قبل الخصم من البطاقة، ثم يحرّر الحجز إن فشل أي شيء. النسخة الأولى من ذلك الكود بدت هكذا:
\nfunction placeOrder(skus: string[]) {\n const reservations = skus.map((sku) => reserve(sku));\n chargeCard(); // throws on a declined card\n reservations.forEach((r) => r.release());\n}البطاقة المرفوضة تتخطّى السطر الأخير، فيبقى المخزون مقفلًا حتى تلاحظه مهمة ليلية. الإصلاح التقليدي هو try/finally، متداخلة مرة لكل مورد. هذا الدرس يغطّي جواب اللغة المدمج، ثم ميزة حديثة ثانية تُبقي الكود العابر للأجزاء مثل إعادة المحاولة خارج منطق العمل: الـ decorators القياسية.
تصريح using مثل const، مع إضافة واحدة: حين تنتهي الكتلة التي يعيش فيها، بـ return أو بالوصول إلى نهايتها أو بـ throw، تستدعي JavaScript الـ method المسمّاة [Symbol.dispose]() على القيمة.
function reserve(sku: string): Disposable {\n log(`reserve ${sku}`);\n return { [Symbol.dispose]: () => log(`release ${sku}`) };\n}\n\nfunction placeOrder() {\n using tent = reserve('TENT-2P');\n using mug = reserve('MUG-SET');\n chargeCard(); // even if this throws…\n} // …both are released here: MUG-SET first, then TENT-2Pتصريحات using المتعددة تُحرَّر بترتيب معكوس، تمامًا مثل كتل finally المتداخلة، فيُحرَّر المورد دائمًا قبل الموارد التي أُنشئ بعدها. وإن رمى التحرير نفسه خطأً بينما خطأ آخر قيد الانتشار، يُحفظ الاثنان في SuppressedError بدل أن يحلّ أحدهما محلّ الآخر بصمت.
للتنظيف غير المتزامن، مثل إغلاق معاملة قاعدة بيانات، استخدم await using مع كائن فيه [Symbol.asyncDispose]() تُعيد promise. وحين يكون عدد الموارد ديناميكيًا، اجمعها في DisposableStack (أو AsyncDisposableStack)، وهي نفسها قابلة للتحرير:
function placeOrder(skus: string[]) {\n using stack = new DisposableStack();\n for (const sku of skus) stack.use(reserve(sku));\n chargeCard();\n} // every reservation released, in reverse orderوصلت using في TypeScript 5.2. وهي تعمل أصليًا في Node 24 وفي Chrome وEdge منذ الإصدار 134 وFirefox منذ 141، لكن Safari لا يدعمها بعد (حتى أواخر 2026)، فهي ليست Baseline. وللكود الذي يصل إلى المتصفّحات، دع TypeScript أو الـ bundler يحوّل الصياغة إلى صيغة أقدم، وتأكّد من وجود Symbol.dispose في بيئة التشغيل (يوفّره polyfill حيث يغيب). والأنواع موجودة في الـ lib المسمّاة esnext.disposable (المضمّنة في "lib": ["esnext"]). بيئة تجربة التمارين تستخدم الـ lib الخاصة بـ ES2022، فيعلن كود البداية هاتين القطعتين بنفسه، وهي معاينة لدمج التصريحات الذي ستتعلّمه في الدرس القادم.
تؤتي using أكبر ثمارها حين تُعيد الـ APIs الخاصة بك قيمًا قابلة للتحرير. الـ emitter من باعثات أحداث وبنّاؤون آمنون من حيث النوع أعاد دالة off؛ وإعادة كائن فيه [Symbol.dispose] أيضًا تتيح للمستدعين حصر الاشتراك في كتلة:
function subscribe<K extends keyof CheckoutEvents>(event: K, handler: (p: CheckoutEvents[K]) => void): Disposable {\n const off = bus.on(event, handler);\n return { [Symbol.dispose]: off };\n}\n\nasync function waitForShipment(orderId: number) {\n using _ = subscribe('order.shipped', (e) => { if (e.orderId === orderId) notify(e); });\n await pollUntilShipped(orderId);\n} // listener removed here, however the function endsالمرشّحون الجيدون كل ما له “تراجع” مقابل: الأقفال والحجوزات، واشتراكات الأحداث، والمؤقّتات، والملفات المؤقتة، ومعاملات قواعد البيانات (مع await using). إن وجدت نفسك تكتب try/finally فقط لاستدعاء method تنظيف، فذلك المورد يريد [Symbol.dispose].
الـ decorator (المُزخرِف) دالة تُطبَّق بـ @ على صنف أو عضو في صنف. نفّذ TypeScript 5.0 الـ decorators القياسية (TC39)، ويترجمها TypeScript إلى استدعاءات دوال عادية، فتعمل في أي بيئة تشغيل. يتلقّى method decorator الـ method الأصلية وكائن context، ويمكنه إعادة بديل:
function logged<This, Args extends unknown[], Return>(\n method: (this: This, ...args: Args) => Return,\n context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,\n) {\n const name = String(context.name);\n return function (this: This, ...args: Args): Return {\n console.log(`→ ${name}`, args);\n return method.call(this, ...args);\n };\n}\n\nclass PaymentGateway {\n @logged\n charge(amountCents: number, currency: string) { /* … */ }\n}الـ generics تجعل الـ decorator يعمل على أي method دون any: تُستنتج This وArgs وReturn من الـ method التي يزخرفها، ويحتفظ البديل بالتوقيع نفسه. والـ decorators التي تأخذ خيارات هي مصانع decorators (decorator factories)، أي دوال تُعيد الـ decorator:
function retry(times: number) {\n return function <This, Args extends unknown[], Return>(\n method: (this: This, ...args: Args) => Return,\n _context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,\n ) {\n return function (this: This, ...args: Args): Return {\n for (let attempt = 1; ; attempt++) {\n try {\n return method.call(this, ...args);\n } catch (e) {\n if (attempt >= times) throw e;\n }\n }\n };\n };\n}\n\nclass PaymentGateway {\n @retry(3)\n charge(amountCents: number, currency: string) { /* … */ }\n}الـ decorators المكدّسة تُطبَّق من الأسفل إلى الأعلى. مع @logged فوق @retry(3)، يُطبَّق غلاف إعادة المحاولة على charge أولًا ثم يغلّف logged النتيجة، فتحصل على سطر تسجيل واحد لكل استدعاء لا لكل محاولة. بدّلهما فتسجّل كل محاولة. لا أحد منهما خاطئ، لكن الترتيب سلوك، فاختره عن قصد.
ويقدّم context أيضًا context.name وcontext.static وcontext.private وcontext.addInitializer(fn)، التي تنفّذ كودًا حين تُنشأ نسخة (وهي الطريقة المعتادة لكتابة decorator مثل @bound يربط method بنسختها).
في التمرين ستحرّر حجوزات المخزون بـ using وتضيف @retry محدَّد النوع إلى بوابة الدفع في Cartwheel. الدرس القادم: وصف كود لم تكتبه، بملفات التصريحات.
using يستدعي [Symbol.dispose]() على القيمة حين تنتهي الكتلة المحيطة، سواء عادت بشكل طبيعي أو رمت خطأً.","تصريحات using المتعددة في كتلة واحدة تُحرَّر بترتيب معكوس، مثل كتل try/finally المتداخلة.","await using وSymbol.asyncDispose يفعلان الشيء نفسه للتنظيف الذي يُعيد promise.","الـ decorators القياسية (منذ TypeScript 5.0) دوال بالشكل (value, context) يمكنها إعادة بديل؛ وهي ليست نفسها experimentalDecorators الأقدم.","حدّد نوع method decorator بـ ClassMethodDecoratorContext ومعاملات generic هي This وArgs وReturn كي يعمل على أي method دون any."],"further":[{"title":"using declarations (TypeScript 5.2 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html"},{"title":"Decorators (TypeScript 5.0 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html"},{"title":"using (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using"}],"quiz":[{"q":"ماذا يطبع هذا؟
\nfunction checkout() {\n using a = reserve('TENT-2P'); // logs \"reserve TENT-2P\", disposes with \"release TENT-2P\"\n using b = reserve('MUG-SET'); // logs \"reserve MUG-SET\", disposes with \"release MUG-SET\"\n throw new Error('card declined');\n}\ntry { checkout(); } catch {}finally المتداخلة، فيُحرَّر b قبل a."},{"text":"reserve TENT-2P, reserve MUG-SET (لا شيء يُحرَّر لأن الدالة رمت خطأً)","why":"التحرير عند كل مسار خروج، بما فيه الرمي، هو الغاية كلها من using."},{"text":"لا شيء؛ لا يمكن الجمع بين using وthrow في الكتلة نفسها.","why":"لا يوجد قيد كهذا؛ الرمي أحد مسارات الخروج التي صُمّمت using لأجلها."}],"answer":0},{"q":"أيّ قيمة يمكن ربطها بـ using؟
close().","why":"using لا تبحث عن close()؛ بل تستدعي الـ method المخزّنة تحت Symbol.dispose."},{"text":"كائن فيه method باسم [Symbol.dispose]()، أو null/undefined.","why":"صحيح. يجب أن تكون القيمة قابلة للتحرير؛ وnull وundefined مسموحتان وتُتخطّيان ببساطة."},{"text":"نُسخ DisposableStack فقط.","why":"DisposableStack أداة مساعدة لجمع القيم القابلة للتحرير، لا شرط."}],"answer":1},{"q":"كيف يتلقّى method decorator القياسي الـ method التي يزخرفها؟
","options":[{"text":"بالشكل(target, propertyKey, descriptor)، ويعدّل الـ descriptor.","why":"هذا توقيع experimentalDecorators القديم. الـ decorators القياسية تتلقّى (value, context)."},{"text":"كاسم نصي، ويبحث عن الـ method على this.","why":"الـ method نفسها تُمرَّر كوسيط أول؛ والاسم متاح في context.name."},{"text":"بالشكل (value, context)، حيث value هي الـ method ويمكن للـ decorator أن يُعيد دالة بديلة.","why":"صحيح. إعادة دالة جديدة تستبدل الـ method، وهكذا تعمل decorators التسجيل وإعادة المحاولة."}],"answer":2},{"q":"تستخدم قاعدة الكود عندك parameter decorators على طريقة NestJS مثل constructor(@Inject(TOKEN) svc). ماذا يعني ذلك لـ tsconfig الخاص بك؟
"experimentalDecorators": true، الذي يحوّل المشروع كله إلى دلالات الـ decorators القديمة.","why":"صحيح. لا يمكن خلط النظامين في ترجمة واحدة؛ والأطر المبنية على النموذج القديم تحتاج هذا الخيار."},{"text":"يجب ضبط "target": "esnext" كي تتعامل بيئة التشغيل معها.","why":"الـ target لا يغيّر نظام الـ decorators الذي يستخدمه TypeScript؛ الخيار هو من يغيّره."},{"text":"يجب تفعيل emitDecoratorMetadata وحده.","why":"هذا الخيار لا يعمل إلا مع experimentalDecorators؛ ووحده لا يفعل شيئًا للـ parameter decorators."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"// ---- Playground shim (do not edit) ----\n// The playground's lib is ES2022. These lines add what lib.esnext.disposable\n// would declare, and make sure Symbol.dispose exists at runtime.\ninterface SymbolConstructor { readonly dispose: unique symbol; }\ninterface Disposable { [Symbol.dispose](): void; }\n(Symbol as { dispose?: symbol }).dispose ??= Symbol.for('Symbol.dispose');\n// ----------------------------------------\n\nconst events: string[] = [];\n\nfunction reserve(sku: string) {\n events.push(`reserve ${sku}`);\n return { sku, release: () => events.push(`release ${sku}`) };\n}\n\nclass PaymentGateway {\n calls = 0;\n failuresLeft: number;\n\n constructor(failures: number) {\n this.failuresLeft = failures;\n }\n\n // Should be retried up to 3 times in total.\n charge(amountCents: number): string {\n this.calls++;\n if (this.failuresLeft > 0) {\n this.failuresLeft--;\n throw new Error('Gateway timeout');\n }\n events.push(`charge ${amountCents}`);\n return `receipt-${amountCents}`;\n }\n}\n\nfunction placeOrder(skus: string[], gateway: PaymentGateway): string {\n const reservations = skus.map((sku) => reserve(sku));\n const receipt = gateway.charge(skus.length * 1000);\n reservations.forEach((r) => r.release());\n return receipt;\n}\n\n// ---- Type tests (do not edit) ----\ntype T1 = Expectإصلاحان لنظام الدفع في Cartwheel:
\nreserve تُعيد قيمة قابلة للتحرير (فيها method باسم [Symbol.dispose] تطبع release <sku> بدل method باسم release)، وأعِد كتابة placeOrder باستخدام using بحيث يُحرَّر كل حجز حين تنتهي الدالة، بترتيب معكوس، حتى حين يرمي الخصم من البطاقة خطأً.retry(times) وطبّق @retry(3) على PaymentGateway.charge، بحيث يُحاوَل الخصم من البطاقة الذي يرمي خطأً حتى 3 مرات إجمالًا قبل أن ينتشر الخطأ. أبقِ توقيع charge سليمًا.أعلى الملف يعلن Symbol.dispose وDisposable، لأن بيئة التجربة تستخدم الـ lib الخاصة بـ ES2022. DisposableStack غير متاحة هنا؛ إن احتجت إليها، فاكتب صنفًا صغيرًا خاصًا بك.
using r = reserve('A'); تحرّر r عند نهاية الكتلة. لقائمة ديناميكية من رموز المنتجات، اجمع القيم القابلة للتحرير في صنف صغير فيه method باسم use(item) و[Symbol.dispose]() تحرّرها بترتيب معكوس.","الـ method decorator القياسي شكله (method, context: ClassMethodDecoratorContext<This, …>) => replacementFunction. والمصنع دالة تُعيد واحدًا: function retry(times: number) { return function <This, Args extends unknown[], Return>(method, context) { … } }.","داخل البديل، كرّر: try { return method.call(this, ...args); } catch (e) { if (attempt >= times) throw e; }."],"explanation":"تربط using عمر المورد بكتلة: أيًّا كانت طريقة خروج placeOrder، تُحرَّر الحاوية، وهي تحرّر الحجوزات بترتيب “الداخل أخيرًا يخرج أولًا”، فيزول تسرّب كود البداية عند رفض الخصم من البطاقة. يلتقط مصنع الـ decorator قيمة times ويُعيد method decorator قياسيًا؛ وتُستنتج This وArgs وReturn الـ generic من charge، فيحتفظ البديل بتوقيعها بالضبط (اختبار T2) ويستدعي الأصل بـ method.call(this, ...args). ومنطق إعادة المحاولة يعيش الآن في مكان واحد قابل لإعادة الاستخدام بدل أن يكون داخل كود الدفع.
charge في المحاولة الثالثة بعد إخفاقين","gives-up":"يستسلم charge ويعيد رمي الخطأ بعد 3 محاولات"}},"words":655,"readMinutes":4}