uss-sync: Universal State Synchronization

uss-sync هي مكتبة JavaScript قوية مصممة لمزامنة الحالة في الوقت الفعلي وبدون تعارض بين المستخدمين والأجهزة. تم بناء المكتبة على أساس CRDTs (Conflict-free Replicated Data Types)، وتستفيد من WebSockets و WebRTC لتقديم حلول تعاونية مرنة وقابلة للتطوير.

المميزات الرئيسية

• مزامنة الحالة في الوقت الفعلي: حافظ على تحديث البيانات عبر جميع العملاء المتصلين فورًا.
• CRDTs مدمجة: تستخدم أنواع البيانات المنسوخة الخالية من التعارض لضمان دمج التعديلات بشكل صحيح دون الحاجة إلى خادم مركزي لحل التعارضات.
  • LWW-Register: آخر كتابة تفوز للقيم الفردية.
  • LWW-Map: آخر كتابة تفوز للخرائط (الكائنات) مع حل التعارضات لكل مفتاح.
  • OR-Set: مجموعة إضافة-إزالة (Observed-Remove Set) التي تدعم الإضافة والإزالة دون تعارضات.
  • G-Counter: عداد نمو فقط (Grow-only counter).
  • PN-Counter: عداد زيادة-نقصان (Positive-Negative counter).
  • RGA (Replicated Growable Array): مصفوفة قابلة للنمو المنسوخة، مثالية للتحرير التعاوني للنصوص والقوائم المرتبة.
• نقل مرن للبيانات: تدعم WebSockets للاتصال من العميل إلى الخادم و WebRTC للاتصال من نظير إلى نظير (P2P)، مع دعم الوضع الهجين الذي يجمع بينهما.
• العمل دون اتصال بالإنترنت أولاً: مصممة للعمل بسلاسة في بيئات متقطعة الاتصال، مع قائمة انتظار للعمليات غير المتصلة بالإنترنت.
• حل التعارضات تلقائيًا: تضمن CRDTs أن جميع النسخ تتقارب إلى نفس الحالة النهائية، حتى مع التعديلات المتزامنة.
• نظام التواجد (Presence): تتبع المستخدمين المتصلين وحالتهم (متصل، بعيد، غير متصل)، مع دعم مؤشرات الكتابة والمؤشرات البصرية (cursors).
• الاشتراكات التفاعلية: اشترك في تغييرات حقول معينة في المخزن وتلقى تحديثات فورية.
• سجل العمليات (Operation Log): تتبع جميع التعديلات التي تتم على الحالة.
• المزامنة الجزئية والكاملة: تدعم مزامنة الدلتا (التغييرات فقط) والمزامنة الكاملة (لقطات الحالة).
• مكافحة الانتروبيا (Anti-Entropy): آليات لضمان اتساق الحالة بمرور الوقت.

التثبيت

يمكنك تثبيت uss-sync عبر npm:

npm install uss-sync

الاستخدام السريع

مثال 1: محرر نصوص تعاوني (WebSocket)

import USS from 'uss-sync';

const doc = new USS({
  roomId: 'my-document-id',
  transport: { type: 'websocket', url: 'wss://your-sync-server.com' },
  schema: { title: 'lww-register', body: 'rga', tags: 'or-set' },
  initialState: { title: 'Untitled Document', body: [], tags: [] },
  presence: { name: 'Alice', color: '#4F46E5' }
});

await doc.connect();

// تحديث العنوان
doc.set('title', 'My Collaborative Document');

// تعديل النص باستخدام RGA
const bodyRGA = doc.crdt('body');
bodyRGA.insert('H', null); // إدراج 'H' في البداية
bodyRGA.insert('e', bodyRGA.elements[0].id); // إدراج 'e' بعد 'H'

// قراءة الحالة
console.log(doc.get('title')); // 'My Collaborative Document'
console.log(doc.get('body').join('')); // 'He'

// الاشتراك في التغييرات
doc.subscribe('title', (newTitle) => {
  document.title = newTitle;
});

// تحديث مؤشر التواجد
doc.presence.setCursor({ line: 1, col: 5 });
doc.presence.subscribe(peers => {
  console.log('Peers online:', peers);
  // عرض مؤشرات الزملاء على الواجهة
});

// عند الانتهاء
doc.disconnect();

مثال 2: لعبة متعددة اللاعبين (WebRTC)

import USS from 'uss-sync';

const game = new USS({
  roomId: 'game-room-123',
  transport: {
    type: 'webrtc',
    signalingUrl: 'wss://your-signaling-server.com',
    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
  },
  schema: { score: 'pn-counter', players: 'or-set', chat: 'rga' },
  presence: { name: 'Player1', avatar: 'url-to-avatar.png' }
});

await game.connect();

// زيادة النتيجة
game.crdt('score').increment(10);

// إضافة لاعب
game.crdt('players').add('Player2');

// قراءة النتيجة
console.log('Current score:', game.get('score'));
console.log('Players:', game.get('players'));

// التبديل إلى غرفة أخرى
await game.switchRoom('game-room-456');

البنية الأساسية للمكتبة

تتكون uss-sync من عدة وحدات مترابطة:

• Core: الواجهة الرئيسية التي ي взаимодей معها المطورون. تقوم بتوصيل Store و Transport و SyncEngine و Presence.
• Store: حاوية حالة تفاعلية مدعومة بـ CRDTs. تدعم الحصول على القيم وتعيينها والاشتراك في التغييرات، وتوفر وصولاً مباشرًا إلى مثيلات CRDT الأساسية.
• CRDT: تنفيذ لأنواع البيانات المنسوخة الخالية من التعارض (LWW-Register, LWW-Map, OR-Set, G-Counter, PN-Counter, RGA).
• Transport: طبقة النقل التي تتعامل مع الاتصال الشبكي. تدعم WebSocketTransport و WebRTCTransport.
• SyncEngine: محرك المزامنة الذي ينسق تدفق البيانات بين Store و Transport، ويتعامل مع مزامنة الدلتا، والمزامنة الكاملة، ومكافحة الانتروبيا، وقائمة انتظار العمليات غير المتصلة بالإنترنت.
• Presence: يدير معلومات التواجد للمستخدمين الآخرين في الغرفة، ويدعم تحديثات التواجد المحلية والاشتراكات في تغييرات الزملاء.
• Utils: مجموعة من الأدوات المساعدة مثل EventEmitter، HybridLogicalClock، generateUUID، deepClone، debounce، throttle.

واجهة برمجة التطبيقات (API) الرئيسية

new USS(config)

ينشئ مثيل USS جديدًا.

config الكائن:

• roomId (سلسلة): معرف فريد لغرفة المزامنة (المستند، القناة، إلخ).
• nodeId (سلسلة، اختياري): معرف فريد لهذا العميل (يتم إنشاؤه تلقائيًا إذا لم يتم توفيره).
• transport (كائن): تكوين النقل.
  • type (سلسلة): 'websocket', 'webrtc', أو 'hybrid'.
  • url (سلسلة، لـ websocket و hybrid): عنوان URL لخادم WebSocket.
  • signalingUrl (سلسلة، لـ webrtc و hybrid): عنوان URL لخادم إشارات WebRTC.
  • iceServers (مصفوفة، لـ webrtc و hybrid): خوادم ICE لتكوين WebRTC.
• schema (كائن، اختياري): يحدد نوع CRDT لكل حقل في المخزن (مثال: { title: 'lww-register', body: 'rga' }).
• initialState (كائن، اختياري): القيم الأولية للحالة.
• presence (كائن، اختياري): بيانات التواجد المحلية (مثال: { name: 'Alice', color: '#FF0000' }).
• sync (كائن، اختياري): خيارات محرك المزامنة (مثال: { antiEntropyInterval: 30000 }).
• reconnect (كائن، اختياري): خيارات إعادة الاتصال للنقل.
• enablePresence (منطقي، افتراضي: true): تمكين/تعطيل ميزة التواجد.
• enableMetrics (منطقي، افتراضي: true): تمكين/تعطيل جمع المقاييس.

uss.connect()

يتصل بالخادم/الزملاء ويبدأ المزامنة. يعيد Promise.

uss.disconnect()

يفصل الاتصال وينظف الموارد.

uss.get(path)

يحصل على قيمة من المخزن باستخدام مسار نقطي (مثال: 'user.profile.name').

uss.set(path, value)

يحدد قيمة في المخزن باستخدام مسار نقطي ويقوم ببث التغيير.

uss.subscribe(path, callback)

يشترك في التغييرات على مسار معين. callback يتلقى (newValue, oldValue, path).

uss.crdt(field)

يحصل على مثيل CRDT الأساسي لحقل معين، مما يسمح بالعمليات الدقيقة (مثال: rga.insert(), orSet.add()).

uss.batch(mutationFn)

يجمع عدة تعديلات في عملية واحدة، مما يؤدي إلى بث دلتا مجمعة واحدة فقط.

uss.switchRoom(newRoomId)

يتبديل إلى غرفة مزامنة مختلفة. يفصل من الغرفة الحالية ويعيد مزامنة الغرفة الجديدة.

uss.export()

يصدر الحالة الكاملة القابلة للتسلسل (للتخزين المحلي، IndexedDB، إلخ).

uss.import(exportedState)

يستورد حالة تم تصديرها مسبقًا.

uss.presence (كائن)

يدير معلومات التواجد.

• presence.setLocal(metadata): يحدد بيانات التواجد المحلية (مثال: { cursor: { line: 1, col: 10 } }).
• presence.subscribe(callback): يشترك في تغييرات التواجد للزملاء.
• presence.getAll(): يحصل على خريطة بجميع الزملاء المتصلين وبيانات تواجدهم.
• presence.getRemoteCursors(): يحصل على مؤشرات الزملاء المتصلين (مفيد للمحررات التعاونية).

المساهمة والترخيص

المكتبة مرخصة بموجب ترخيص MIT. نرحب بالمساهمات! يرجى زيارة مستودع GitHub للإبلاغ عن المشكلات أو تقديم طلبات السحب.

المؤلف: محمد أشرف