حجم الحزمة وتنسيقات الوحدات

يوفّر SDK بنية CommonJS وبنية ESM، ويُبقي اعتماديتيه الثقيلتين، Zod وsocket.io-client، خارج رسم الاستيراد حتى تُستخدما. المشروع الذي يستدعي طريقة واحدة، ويترك التحقق معطلًا ولا يفتح أي مقبس يحمّل نحو 49 kB مصغّرة (10.9 kB gzip)، بعد أن كانت 706 kB (141 kB gzip) في الإصدار 1.0.158.

ما تتضمنه الحزمة

الحقل	القيمة	يستخدمه
main	dist/index.js	Node وأي مستهلك CommonJS
module	esm/index.js	المجمّعات (webpack, Vite, Rollup, esbuild)
types	dist/index.d.ts	TypeScript
sideEffects	false	المجمّعات، لإسقاط الوحدات غير المستخدمة
exports	., ./types, ./dist/*, ./esm/*, ./package.json	Node والمجمّعات التي تقرأ خريطة exports

توجّه خريطة exports الأمر import إلى بنية ESM والأمر require إلى بنية CommonJS، لكل من الجذر وoneentry/types. كما تكشف ./dist/* و./esm/*، فتستمر الاستيرادات العميقة الحالية (oneentry/dist/<module>/<module>Interfaces وغيرها) في العمل، ولا يحتاج إعدادك الحالي إلى تغيير.

تخبر sideEffects: false المجمّع بأن استيراد وحدة SDK ليس له آثار جانبية. وهذا ما يجعل tree-shaking يعمل: تُسقط الوحدات التي لا تستخدمها من المخرجات.

يُحمَّل Zod فقط عند تشغيل التحقق

التحقق من استجابات API معطل افتراضيًا. تُحمَّل المخططات ودوال التحقق المساعدة عند الطلب، في أول مرة تحتاج فيها استجابة إلى التحقق. (كانت الإصدارات السابقة تستورد المخططات بشكل ثابت في كل وحدة، مما كان يضع Zod في كل حزمة حتى عندما لا يجري أي تحقق.)

• مع validation.enabled: false (الافتراضي)، ينتهي Zod ومخططات الوحدات (~400 kB) في أجزاء لا تُطلب أبدًا.
• مع validation.enabled: true، يعمل التحقق كما كان؛ وتُجلب المخططات في أول مرة تُحتاج فيها.
• في Node، لم يعد require('oneentry') يحمّل Zod عند البدء.

تفترض هذه الأرقام مُجمِّعًا يقسّم الشيفرة (code splitting)، وهو الوضع الافتراضي في webpack وVite وRollup. الحزمة المُجبرة على ملف واحد تصغر أيضًا، لكن إلى ~447 kB فقط، لأن Zod يُضمَّن فيها رغم أنه لا يعمل أبدًا.

الواجهة العامة هي نفسها. أصبحت الدالة المساعدة الداخلية _validateResponse الآن async، وهذا يهم فقط إذا وسّعت الأصناف الأساسية لـ SDK بنفسك.

يُحمَّل socket.io فقط عند فتح مقبس

لا تزال WS.connect() متزامنة وتُعيد Socket من socket.io، لكن socket.io-client (~43 kB) يُستورد في أول مرة تُستدعى فيها connect().

إلى أن يُحمَّل الجزء، يضع الكائن المُعاد كل استدعاء تجريه عليه (on، emit، disconnect) في قائمة انتظار ويعيد تشغيلها على المقبس الحقيقي في الدورة نفسها التي يُنشأ فيها المقبس، قبل أن يتمكن الاتصال من إيصال أي شيء. لا يضيع أي حدث:

// Nothing changes in normal use — handlers registered here always fire.
// Requires an access token: call AuthProvider.auth() first. With only auth.refreshToken
// in the config, make an authorized call (for example Users.getUser()) before connect()
// so the SDK refreshes the token.
const socket = WS.connect();

socket.on('connect', () => console.log('WebSocket connected'));
socket.on('my_event', (payload) => console.log(payload));

تظل قراءة حالة الاتصال مبكرًا دقيقة، لأن المقبس المُنشأ حديثًا غير متصل أيضًا: id يساوي undefined وconnected يساوي false، كما كان.

الفرق الوحيد: الطريقة التي يجب أن تُعيد شيئًا (مثل listeners()) لا يمكنها الإجابة قبل وصول الجزء، والكائنات المتداخلة مثل socket.io لا يمكن الوصول إليها إلا بعد تحميله. أما تسجيل المعالجات والإرسال، وهو الاستخدام المعتاد، فلا يتأثران.

حجم الحزمة في لمحة

السيناريو	مصغّرة	Gzip
قبل (1.0.158، لكل مستهلك)	706 kB	141 kB
التحقق معطل، بلا مقبس	49 kB	10.9 kB
التحقق معطل، مع فتح مقبس	~92 kB	~24 kB
حزمة ملف واحد، بلا تقسيم للكود	~447 kB	~94 kB

القياس على الإصدار 1.0.173 (والإصدار 1.0.158 للصف الأول) باستخدام esbuild 0.24.2: مخرجات ESM، و--bundle --splitting --minify، ومنصة browser، وتطبيق يستدعي Pages.getPageByUrl مرة واحدة (مع WS.connect() لصف المقبس)؛ وgzip بالمستوى 9. تعطي المجمّعات الأخرى أرقامًا مختلفة قليلًا.

الحصول على أصغر بنية

• اترك التحقق معطلًا في الإنتاج. فعّله أثناء التطوير لاكتشاف عدم اتساق البيانات، ثم عطّله مجددًا، لتبقى المخططات خارج الكود المحمّل.
• دع المجمّع يقسّم الكود. تقسيم الكود مفعّل افتراضيًا في webpack وVite وRollup. تعطيله يضمّن الأجزاء الكسولة ويُفقد معظم التوفير.
• استورد الأنواع باستخدام import type. تُحذف عمليات استيراد الأنواع عند الترجمة البرمجية؛ انظر استيراد الأنواع.
• فكّك فقط الوحدات التي تستخدمها. مع sideEffects: false وبنية ESM، تُسقط الوحدات غير المستخدمة من المخرجات.

---

ذات صلة

• استيراد الأنواع: نقطتا الدخول oneentry وoneentry/types
• التحقق من استجابات API: تفعيل التحقق عبر Zod وإعداده
• وحدة WS: فتح اتصال في الوقت الفعلي

---