@vuer-ai/vuer-rtc-server 0.2.0 → 0.2.2

package/tests/journal/rle-compression.test.ts

@@ -0,0 +1,526 @@
+/**
+ * Unit tests for RLE Compression
+ *
+ * Tests:
+ * 1. RLE encode/decode roundtrip with various message patterns
+ * 2. CRDT semantics preservation (operations remain unchanged)
+ * 3. Compression ratio calculation
+ * 4. Edge cases (empty, single message, alternating sessions)
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import type { CRDTMessage, NumberSetOp } from '@vuer-ai/vuer-rtc';
+import {
+  encodeRLE,
+  decodeRLE,
+  encodeRLEWithMetadata,
+  decodeRLEWithMetadata,
+  calculateCompressionRatio,
+} from '../../src/journal/RLECompression';
+
+describe('RLE Compression', () => {
+  // Helper to create test messages
+  function createMessage(
+    id: string,
+    sessionId: string,
+    lamportTime: number,
+    opsCount: number = 1
+  ): CRDTMessage {
+    const ops: NumberSetOp[] = Array.from({ length: opsCount }, (_, i) => ({
+      otype: 'number.set',
+      key: `key-${lamportTime}`,
+      path: `properties/prop-${i}`,
+      value: Math.random() * 100,
+    }));
+
+    return {
+      id,
+      sessionId,
+      clock: { [sessionId]: lamportTime },
+      lamportTime,
+      timestamp: Date.now() / 1000,
+      ops,
+    };
+  }
+
+  describe('encodeRLE', () => {
+    it('should encode empty list', () => {
+      const result = encodeRLE([]);
+      expect(result).toEqual([]);
+    });
+
+    it('should encode single message', () => {
+      const msg = createMessage('msg-1', 'session-a', 1, 2);
+      const result = encodeRLE([msg]);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toMatchObject({
+        sessionId: 'session-a',
+        count: 1,
+        lamportTime: 1,
+        endLamportTime: 1,
+        ops: msg.ops,
+      });
+    });
+
+    it('should encode consecutive messages from same session', () => {
+      const msgs = [
+        createMessage('msg-1', 'session-a', 1, 1),
+        createMessage('msg-2', 'session-a', 2, 1),
+        createMessage('msg-3', 'session-a', 3, 1),
+      ];
+
+      const result = encodeRLE(msgs);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toMatchObject({
+        sessionId: 'session-a',
+        count: 3,
+        lamportTime: 1,
+        endLamportTime: 3,
+      });
+      // All ops should be flattened
+      expect(result[0].ops).toHaveLength(3);
+    });
+
+    it('should encode alternating sessions as separate runs', () => {
+      const msgs = [
+        createMessage('msg-1', 'session-a', 1, 1),
+        createMessage('msg-2', 'session-b', 2, 1),
+        createMessage('msg-3', 'session-a', 3, 1),
+      ];
+
+      const result = encodeRLE(msgs);
+
+      expect(result).toHaveLength(3);
+      expect(result[0].sessionId).toBe('session-a');
+      expect(result[0].count).toBe(1);
+      expect(result[1].sessionId).toBe('session-b');
+      expect(result[1].count).toBe(1);
+      expect(result[2].sessionId).toBe('session-a');
+      expect(result[2].count).toBe(1);
+    });
+
+    it('should encode mixed multi-operation messages', () => {
+      const msgs = [
+        createMessage('msg-1', 'session-a', 1, 3), // 3 ops
+        createMessage('msg-2', 'session-a', 2, 2), // 2 ops
+        createMessage('msg-3', 'session-a', 3, 1), // 1 op
+      ];
+
+      const result = encodeRLE(msgs);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].count).toBe(3);
+      expect(result[0].ops).toHaveLength(6); // 3 + 2 + 1
+    });
+
+    it('should preserve operation details', () => {
+      const msg = createMessage('msg-1', 'session-a', 1, 2);
+      const result = encodeRLE([msg]);
+
+      expect(result[0].ops).toEqual(msg.ops);
+      expect(result[0].ops[0].key).toBe(msg.ops[0].key);
+      expect(result[0].ops[1].otype).toBe(msg.ops[1].otype);
+    });
+  });
+
+  describe('decodeRLE', () => {
+    it('should decode single run to single message', () => {
+      const encoded = [
+        {
+          sessionId: 'session-a',
+          count: 1,
+          lamportTime: 1,
+          endLamportTime: 1,
+          ops: [{ otype: 'number.set', key: 'k1', path: 'p1', value: 10 }],
+          timestamp: 1000,
+        },
+      ];
+      const opCounts = [1];
+
+      const result = decodeRLE(encoded, opCounts);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].sessionId).toBe('session-a');
+      expect(result[0].lamportTime).toBe(1);
+      expect(result[0].ops).toHaveLength(1);
+    });
+
+    it('should decode run with multiple messages', () => {
+      const encoded = [
+        {
+          sessionId: 'session-a',
+          count: 3,
+          lamportTime: 1,
+          endLamportTime: 3,
+          ops: [
+            { otype: 'number.set', key: 'k1', path: 'p1', value: 1 },
+            { otype: 'number.set', key: 'k2', path: 'p2', value: 2 },
+            { otype: 'number.set', key: 'k3', path: 'p3', value: 3 },
+          ],
+          timestamp: 1000,
+        },
+      ];
+      const opCounts = [1, 1, 1];
+
+      const result = decodeRLE(encoded, opCounts);
+
+      expect(result).toHaveLength(3);
+      expect(result[0].lamportTime).toBe(1);
+      expect(result[1].lamportTime).toBe(2);
+      expect(result[2].lamportTime).toBe(3);
+      // Each should have one op
+      result.forEach((msg) => {
+        expect(msg.ops).toHaveLength(1);
+      });
+    });
+
+    it('should handle multi-op messages during decode', () => {
+      const encoded = [
+        {
+          sessionId: 'session-a',
+          count: 2,
+          lamportTime: 1,
+          endLamportTime: 2,
+          ops: [
+            { otype: 'number.set', key: 'k1a', path: 'p1a', value: 10 },
+            { otype: 'number.set', key: 'k1b', path: 'p1b', value: 20 },
+            { otype: 'number.set', key: 'k2a', path: 'p2a', value: 30 },
+          ],
+          timestamp: 1000,
+        },
+      ];
+      const opCounts = [2, 1]; // First msg has 2 ops, second has 1
+
+      const result = decodeRLE(encoded, opCounts);
+
+      expect(result).toHaveLength(2);
+      expect(result[0].ops).toHaveLength(2);
+      expect(result[1].ops).toHaveLength(1);
+    });
+  });
+
+  describe('Roundtrip: encode → decode', () => {
+    it('should preserve single message through roundtrip', () => {
+      const original = [createMessage('msg-1', 'session-a', 1, 1)];
+      const opCounts = original.map((m) => m.ops.length);
+
+      const encoded = encodeRLE(original);
+      const decoded = decodeRLE(encoded, opCounts);
+
+      // Check counts
+      expect(decoded).toHaveLength(original.length);
+      expect(decoded[0].sessionId).toBe(original[0].sessionId);
+      expect(decoded[0].lamportTime).toBe(original[0].lamportTime);
+      expect(decoded[0].ops).toEqual(original[0].ops);
+    });
+
+    it('should preserve multiple consecutive messages from same session', () => {
+      const original = [
+        createMessage('msg-1', 'session-a', 1, 1),
+        createMessage('msg-2', 'session-a', 2, 1),
+        createMessage('msg-3', 'session-a', 3, 1),
+      ];
+      const opCounts = original.map((m) => m.ops.length);
+
+      const encoded = encodeRLE(original);
+      const decoded = decodeRLE(encoded, opCounts);
+
+      expect(decoded).toHaveLength(original.length);
+      for (let i = 0; i < original.length; i++) {
+        expect(decoded[i].sessionId).toBe(original[i].sessionId);
+        expect(decoded[i].lamportTime).toBe(original[i].lamportTime);
+        expect(decoded[i].ops).toEqual(original[i].ops);
+      }
+    });
+
+    it('should preserve alternating sessions through roundtrip', () => {
+      const original = [
+        createMessage('msg-1', 'session-a', 1, 1),
+        createMessage('msg-2', 'session-b', 2, 1),
+        createMessage('msg-3', 'session-c', 3, 1),
+      ];
+      const opCounts = original.map((m) => m.ops.length);
+
+      const encoded = encodeRLE(original);
+      const decoded = decodeRLE(encoded, opCounts);
+
+      expect(decoded).toHaveLength(original.length);
+      for (let i = 0; i < original.length; i++) {
+        expect(decoded[i].sessionId).toBe(original[i].sessionId);
+        expect(decoded[i].lamportTime).toBe(original[i].lamportTime);
+      }
+    });
+
+    it('should preserve complex multi-operation messages', () => {
+      const original = [
+        createMessage('msg-1', 'session-a', 1, 3),
+        createMessage('msg-2', 'session-a', 2, 2),
+        createMessage('msg-3', 'session-b', 3, 4),
+        createMessage('msg-4', 'session-b', 4, 1),
+      ];
+      const opCounts = original.map((m) => m.ops.length);
+
+      const encoded = encodeRLE(original);
+      const decoded = decodeRLE(encoded, opCounts);
+
+      expect(decoded).toHaveLength(original.length);
+      for (let i = 0; i < original.length; i++) {
+        expect(decoded[i].ops).toHaveLength(original[i].ops.length);
+        expect(decoded[i].sessionId).toBe(original[i].sessionId);
+      }
+    });
+  });
+
+  describe('encodeRLEWithMetadata & decodeRLEWithMetadata', () => {
+    it('should preserve all message metadata through roundtrip', () => {
+      const original = [
+        createMessage('msg-1', 'session-a', 1, 2),
+        createMessage('msg-2', 'session-a', 2, 1),
+        createMessage('msg-3', 'session-b', 3, 3),
+      ];
+
+      const encoded = encodeRLEWithMetadata(original);
+      const decoded = decodeRLEWithMetadata(encoded);
+
+      expect(decoded).toHaveLength(original.length);
+      for (let i = 0; i < original.length; i++) {
+        expect(decoded[i].id).toBe(original[i].id);
+        expect(decoded[i].sessionId).toBe(original[i].sessionId);
+        expect(decoded[i].clock).toEqual(original[i].clock);
+        expect(decoded[i].lamportTime).toBe(original[i].lamportTime);
+        expect(decoded[i].ops).toEqual(original[i].ops);
+      }
+    });
+
+    it('should recover message IDs correctly', () => {
+      const original = [
+        createMessage('unique-id-1', 'session-a', 1, 1),
+        createMessage('unique-id-2', 'session-a', 2, 1),
+      ];
+
+      const encoded = encodeRLEWithMetadata(original);
+      const decoded = decodeRLEWithMetadata(encoded);
+
+      expect(decoded[0].id).toBe('unique-id-1');
+      expect(decoded[1].id).toBe('unique-id-2');
+    });
+
+    it('should preserve vector clocks', () => {
+      const msg1: CRDTMessage = {
+        id: 'msg-1',
+        sessionId: 'session-a',
+        clock: { 'session-a': 5, 'session-b': 3 },
+        lamportTime: 1,
+        timestamp: 1000,
+        ops: [{ otype: 'number.set', key: 'k', path: 'p', value: 10 }],
+      };
+      const msg2: CRDTMessage = {
+        id: 'msg-2',
+        sessionId: 'session-a',
+        clock: { 'session-a': 6, 'session-b': 4 },
+        lamportTime: 2,
+        timestamp: 1001,
+        ops: [{ otype: 'number.set', key: 'k', path: 'p', value: 20 }],
+      };
+
+      const encoded = encodeRLEWithMetadata([msg1, msg2]);
+      const decoded = decodeRLEWithMetadata(encoded);
+
+      expect(decoded[0].clock).toEqual({ 'session-a': 5, 'session-b': 3 });
+      expect(decoded[1].clock).toEqual({ 'session-a': 6, 'session-b': 4 });
+    });
+  });
+
+  describe('CRDT Semantics Preservation', () => {
+    it('should not lose any operations', () => {
+      const original = [
+        createMessage('msg-1', 'session-a', 1, 5),
+        createMessage('msg-2', 'session-a', 2, 3),
+        createMessage('msg-3', 'session-b', 3, 7),
+      ];
+
+      const encoded = encodeRLEWithMetadata(original);
+      const decoded = decodeRLEWithMetadata(encoded);
+
+      let totalOriginalOps = 0;
+      let totalDecodedOps = 0;
+
+      for (const msg of original) {
+        totalOriginalOps += msg.ops.length;
+      }
+      for (const msg of decoded) {
+        totalDecodedOps += msg.ops.length;
+      }
+
+      expect(totalDecodedOps).toBe(totalOriginalOps);
+    });
+
+    it('should maintain operation order within messages', () => {
+      const ops: NumberSetOp[] = [
+        { otype: 'number.set', key: 'k1', path: 'p1', value: 1 },
+        { otype: 'number.set', key: 'k2', path: 'p2', value: 2 },
+        { otype: 'number.set', key: 'k3', path: 'p3', value: 3 },
+      ];
+
+      const msg: CRDTMessage = {
+        id: 'msg-1',
+        sessionId: 'session-a',
+        clock: { 'session-a': 1 },
+        lamportTime: 1,
+        timestamp: 1000,
+        ops,
+      };
+
+      const encoded = encodeRLEWithMetadata([msg]);
+      const decoded = decodeRLEWithMetadata(encoded);
+
+      expect(decoded[0].ops).toEqual(ops);
+    });
+
+    it('should maintain lamport timestamps', () => {
+      const original = [
+        createMessage('msg-1', 'session-a', 100, 1),
+        createMessage('msg-2', 'session-a', 101, 1),
+        createMessage('msg-3', 'session-b', 102, 1),
+      ];
+
+      const encoded = encodeRLEWithMetadata(original);
+      const decoded = decodeRLEWithMetadata(encoded);
+
+      for (let i = 0; i < original.length; i++) {
+        expect(decoded[i].lamportTime).toBe(original[i].lamportTime);
+      }
+    });
+  });
+
+  describe('Compression Ratio', () => {
+    it('should calculate compression for small set', () => {
+      const msgs = [
+        createMessage('msg-1', 'session-a', 1, 1),
+        createMessage('msg-2', 'session-a', 2, 1),
+      ];
+      const encoded = encodeRLE(msgs);
+
+      const { original, encoded: encodedSize, ratio } = calculateCompressionRatio(
+        msgs,
+        encoded
+      );
+
+      expect(original).toBeGreaterThan(0);
+      expect(encodedSize).toBeGreaterThan(0);
+      expect(ratio).toBeGreaterThanOrEqual(-1);
+      expect(ratio).toBeLessThanOrEqual(1);
+    });
+
+    it('should show positive compression for repetitive data', () => {
+      // Create many messages from same session
+      const msgs = Array.from({ length: 50 }, (_, i) =>
+        createMessage(`msg-${i}`, 'session-a', i + 1, 1)
+      );
+      const encoded = encodeRLE(msgs);
+
+      const { ratio } = calculateCompressionRatio(msgs, encoded);
+
+      // With many runs of same session, should get good compression
+      expect(ratio).toBeGreaterThan(0);
+    });
+
+    it('should show little compression for highly alternating sessions', () => {
+      // Create messages alternating between sessions
+      const msgs = Array.from({ length: 20 }, (_, i) =>
+        createMessage(`msg-${i}`, i % 2 === 0 ? 'session-a' : 'session-b', i + 1, 1)
+      );
+      const encoded = encodeRLE(msgs);
+
+      const { original, encoded: encodedSize } = calculateCompressionRatio(msgs, encoded);
+
+      // Alternating sessions means many runs, less compression
+      // But should still not be larger
+      expect(encodedSize).toBeLessThanOrEqual(original * 1.1);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle very large lamport times', () => {
+      const msg: CRDTMessage = {
+        id: 'msg-huge',
+        sessionId: 'session-a',
+        clock: { 'session-a': 999999999 },
+        lamportTime: 999999999,
+        timestamp: 1000,
+        ops: [{ otype: 'number.set', key: 'k', path: 'p', value: 10 }],
+      };
+
+      const encoded = encodeRLEWithMetadata([msg]);
+      const decoded = decodeRLEWithMetadata(encoded);
+
+      expect(decoded[0].lamportTime).toBe(999999999);
+    });
+
+    it('should handle empty operations array', () => {
+      const msg: CRDTMessage = {
+        id: 'msg-1',
+        sessionId: 'session-a',
+        clock: { 'session-a': 1 },
+        lamportTime: 1,
+        timestamp: 1000,
+        ops: [],
+      };
+
+      const encoded = encodeRLEWithMetadata([msg]);
+      const decoded = decodeRLEWithMetadata(encoded);
+
+      expect(decoded[0].ops).toEqual([]);
+    });
+
+    it('should handle very long operation lists', () => {
+      const ops: NumberSetOp[] = Array.from({ length: 1000 }, (_, i) => ({
+        otype: 'number.set',
+        key: `k-${i}`,
+        path: `p-${i}`,
+        value: i,
+      }));
+
+      const msg: CRDTMessage = {
+        id: 'msg-huge-ops',
+        sessionId: 'session-a',
+        clock: { 'session-a': 1 },
+        lamportTime: 1,
+        timestamp: 1000,
+        ops,
+      };
+
+      const encoded = encodeRLEWithMetadata([msg]);
+      const decoded = decodeRLEWithMetadata(encoded);
+
+      expect(decoded[0].ops).toHaveLength(1000);
+      expect(decoded[0].ops).toEqual(ops);
+    });
+  });
+
+  describe('CRDT Semantics Preservation - Operation Details', () => {
+    it('should maintain operation order and properties', () => {
+      const ops: NumberSetOp[] = [
+        { otype: 'number.set', key: 'k1', path: 'p1', value: 1 },
+        { otype: 'number.set', key: 'k2', path: 'p2', value: 2 },
+        { otype: 'number.set', key: 'k3', path: 'p3', value: 3 },
+      ];
+
+      const msg: CRDTMessage = {
+        id: 'msg-1',
+        sessionId: 'session-a',
+        clock: { 'session-a': 1 },
+        lamportTime: 1,
+        timestamp: 1000,
+        ops,
+      };
+
+      const encoded = encodeRLEWithMetadata([msg]);
+      const decoded = decodeRLEWithMetadata(encoded);
+
+      expect(decoded[0].ops).toEqual(ops);
+    });
+  });
+});