@vuer-ai/vuer-rtc-server 0.1.1

package/tests/unit/operations.test.ts

@@ -0,0 +1,310 @@
+/**
+ * Tests for operation application on server side
+ * Tests all operation types using shared fixtures
+ */
+
+import { describe, it, expect, beforeEach } from '@jest/globals';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import type { SceneGraph, CRDTMessage, Operation } from '@vuer-ai/vuer-rtc';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+interface OpFixture {
+  name: string;
+  op: Operation;
+}
+
+function loadOps(filename: string): OpFixture[] {
+  const filepath = join(__dirname, '../fixtures', filename);
+  const content = readFileSync(filepath, 'utf-8');
+  return content
+    .trim()
+    .split('\n')
+    .map((line) => JSON.parse(line));
+}
+
+function createMsg(op: Operation, lamport = 1): CRDTMessage {
+  return {
+    id: `msg-${Math.random().toString(36).slice(2)}`,
+    sessionId: 'test-session',
+    clock: { 'test-session': lamport },
+    lamportTime: lamport,
+    timestamp: Date.now() / 1000,
+    ops: [op],
+  };
+}
+
+async function createNodeWithProps(
+  graph: SceneGraph,
+  key: string,
+  props: Record<string, unknown>
+): Promise<SceneGraph> {
+  const { applyMessage } = await import('@vuer-ai/vuer-rtc');
+  const nodeOp: Operation = {
+    key: '',
+    otype: 'node.insert',
+    path: 'children',
+    value: {
+      key,
+      id: `uuid-${key}`,
+      tag: 'Mesh',
+      name: key,
+      ...props,
+    },
+  };
+  return applyMessage(graph, createMsg(nodeOp, 0));
+}
+
+describe('Server Operation Tests', () => {
+  describe('Number Operations', () => {
+    let numberOps: OpFixture[];
+
+    beforeEach(() => {
+      numberOps = loadOps('number-ops.jsonl');
+    });
+
+    it('should apply number.set operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { opacity: 1 });
+
+      const op = numberOps.find((f) => f.name === 'number_set')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].opacity).toBe(0.5);
+    });
+
+    it('should apply number.add operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { score: 50 });
+
+      const op = numberOps.find((f) => f.name === 'number_add')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].score).toBe(60);
+    });
+
+    it('should apply number.multiply operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { scale: 3 });
+
+      const op = numberOps.find((f) => f.name === 'number_multiply')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].scale).toBe(6);
+    });
+
+    it('should apply number.min operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { health: 100 });
+
+      const op = numberOps.find((f) => f.name === 'number_min')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].health).toBe(50);
+    });
+
+    it('should apply number.max operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { damage: 10 });
+
+      const op = numberOps.find((f) => f.name === 'number_max')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].damage).toBe(25);
+    });
+  });
+
+  describe('Vector3 Operations', () => {
+    let vectorOps: OpFixture[];
+
+    beforeEach(() => {
+      vectorOps = loadOps('vector-ops.jsonl');
+    });
+
+    it('should apply vector3.set operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { position: [0, 0, 0] });
+
+      const op = vectorOps.find((f) => f.name === 'vector3_set')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].position).toEqual([1, 2, 3]);
+    });
+
+    it('should apply vector3.add operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { position: [1, 1, 1] });
+
+      const op = vectorOps.find((f) => f.name === 'vector3_add')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].position).toEqual([1.5, 1.5, 1.5]);
+    });
+
+    it('should apply vector3.multiply operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { scale: [2, 2, 2] });
+
+      const op = vectorOps.find((f) => f.name === 'vector3_multiply')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].scale).toEqual([4, 4, 4]);
+    });
+  });
+
+  describe('Boolean Operations', () => {
+    let boolOps: OpFixture[];
+
+    beforeEach(() => {
+      boolOps = loadOps('boolean-ops.jsonl');
+    });
+
+    it('should apply boolean.set true', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { visible: false });
+
+      const op = boolOps.find((f) => f.name === 'boolean_set_true')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].visible).toBe(true);
+    });
+
+    it('should apply boolean.or operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { enabled: false });
+
+      const op = boolOps.find((f) => f.name === 'boolean_or_true')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].enabled).toBe(true);
+    });
+
+    it('should apply boolean.and operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { active: true });
+
+      const op = boolOps.find((f) => f.name === 'boolean_and_false')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].active).toBe(false);
+    });
+  });
+
+  describe('Array Operations', () => {
+    let arrayOps: OpFixture[];
+
+    beforeEach(() => {
+      arrayOps = loadOps('array-ops.jsonl');
+    });
+
+    it('should apply array.set operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { tags: [] });
+
+      const op = arrayOps.find((f) => f.name === 'array_set')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].tags).toEqual(['enemy', 'active']);
+    });
+
+    it('should apply array.push operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { tags: ['initial'] });
+
+      const op = arrayOps.find((f) => f.name === 'array_push')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].tags).toEqual(['initial', 'new-tag']);
+    });
+
+    it('should apply array.union operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { tags: ['initial'] });
+
+      const op = arrayOps.find((f) => f.name === 'array_union')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].tags).toContain('initial');
+      expect(result.nodes['node-1'].tags).toContain('tag-a');
+      expect(result.nodes['node-1'].tags).toContain('tag-b');
+    });
+
+    it('should apply array.remove operation', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+      graph = await createNodeWithProps(graph, 'node-1', { tags: ['friend', 'enemy'] });
+
+      const op = arrayOps.find((f) => f.name === 'array_remove')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.nodes['node-1'].tags).toEqual(['friend']);
+    });
+  });
+
+  describe('Node Operations', () => {
+    let nodeOps: OpFixture[];
+
+    beforeEach(() => {
+      nodeOps = loadOps('node-ops.jsonl');
+    });
+
+    it('should insert root node', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      const graph = createEmptyGraph();
+
+      const op = nodeOps.find((f) => f.name === 'node_insert_root')!.op;
+      const result = applyMessage(graph, createMsg(op));
+
+      expect(result.rootKey).toBe('scene');
+      expect(result.nodes['scene']).toBeDefined();
+      expect(result.nodes['scene'].tag).toBe('Scene');
+    });
+
+    it('should insert child under parent', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+
+      const rootOp = nodeOps.find((f) => f.name === 'node_insert_root')!.op;
+      graph = applyMessage(graph, createMsg(rootOp, 1));
+
+      const meshOp = nodeOps.find((f) => f.name === 'node_insert_mesh')!.op;
+      const result = applyMessage(graph, createMsg(meshOp, 2));
+
+      expect(result.nodes['cube-1']).toBeDefined();
+      expect(result.nodes['scene'].children).toContain('cube-1');
+    });
+
+    it('should remove node (tombstone)', async () => {
+      const { createEmptyGraph, applyMessage } = await import('@vuer-ai/vuer-rtc');
+      let graph = createEmptyGraph();
+
+      const rootOp = nodeOps.find((f) => f.name === 'node_insert_root')!.op;
+      graph = applyMessage(graph, createMsg(rootOp, 1));
+
+      const meshOp = nodeOps.find((f) => f.name === 'node_insert_mesh')!.op;
+      graph = applyMessage(graph, createMsg(meshOp, 2));
+
+      const removeOp = nodeOps.find((f) => f.name === 'node_remove')!.op;
+      const result = applyMessage(graph, createMsg(removeOp, 3));
+
+      expect(result.nodes['scene'].children).not.toContain('cube-1');
+      expect(result.nodes['cube-1']._crdt?.deletedAt).toBeDefined();
+    });
+  });
+});

package/tests/unit/vectorClock.test.ts

@@ -0,0 +1,281 @@
+import { describe, it, expect, beforeEach } from '@jest/globals';
+
+// Import types that we'll implement
+type VectorClock = Record<string, number>;
+
+interface IVectorClockManager {
+  create(sessionId: string): VectorClock;
+  increment(clock: VectorClock, sessionId: string): VectorClock;
+  merge(clock1: VectorClock, clock2: VectorClock): VectorClock;
+  compare(clock1: VectorClock, clock2: VectorClock): number;
+}
+
+// We'll implement this later
+let VectorClockManager: new () => IVectorClockManager;
+
+try {
+  const module = await import('@vuer-ai/vuer-rtc');
+  VectorClockManager = module.VectorClockManager;
+} catch {
+  // Implementation doesn't exist yet - tests will fail until we implement
+  VectorClockManager = class {
+    create() { throw new Error('Not implemented'); }
+    increment() { throw new Error('Not implemented'); }
+    merge() { throw new Error('Not implemented'); }
+    compare() { throw new Error('Not implemented'); }
+  } as any;
+}
+
+describe('VectorClockManager', () => {
+  let manager: IVectorClockManager;
+
+  beforeEach(() => {
+    manager = new VectorClockManager();
+  });
+
+  describe('create', () => {
+    it('should create a new vector clock for a session', () => {
+      const clock = manager.create('session-1');
+
+      expect(clock).toBeDefined();
+      expect(clock['session-1']).toBe(0);
+    });
+
+    it('should create an empty clock for new session', () => {
+      const clock = manager.create('session-abc');
+
+      expect(Object.keys(clock)).toHaveLength(1);
+      expect(clock['session-abc']).toBe(0);
+    });
+  });
+
+  describe('increment', () => {
+    it('should increment the counter for a session', () => {
+      const clock = { 'session-1': 5 };
+      const newClock = manager.increment(clock, 'session-1');
+
+      expect(newClock['session-1']).toBe(6);
+    });
+
+    it('should not mutate the original clock', () => {
+      const clock = { 'session-1': 5 };
+      const newClock = manager.increment(clock, 'session-1');
+
+      expect(clock['session-1']).toBe(5); // Original unchanged
+      expect(newClock['session-1']).toBe(6);
+    });
+
+    it('should initialize counter to 1 if session not in clock', () => {
+      const clock = { 'session-1': 5 };
+      const newClock = manager.increment(clock, 'session-2');
+
+      expect(newClock['session-1']).toBe(5);
+      expect(newClock['session-2']).toBe(1);
+    });
+
+    it('should handle incrementing from 0', () => {
+      const clock = { 'session-1': 0 };
+      const newClock = manager.increment(clock, 'session-1');
+
+      expect(newClock['session-1']).toBe(1);
+    });
+  });
+
+  describe('merge', () => {
+    it('should take the maximum value for each session', () => {
+      const clock1 = { 'session-1': 5, 'session-2': 3 };
+      const clock2 = { 'session-1': 3, 'session-2': 7 };
+
+      const merged = manager.merge(clock1, clock2);
+
+      expect(merged['session-1']).toBe(5); // max(5, 3)
+      expect(merged['session-2']).toBe(7); // max(3, 7)
+    });
+
+    it('should include sessions only in first clock', () => {
+      const clock1 = { 'session-1': 5, 'session-2': 3 };
+      const clock2 = { 'session-1': 3 };
+
+      const merged = manager.merge(clock1, clock2);
+
+      expect(merged['session-1']).toBe(5);
+      expect(merged['session-2']).toBe(3);
+    });
+
+    it('should include sessions only in second clock', () => {
+      const clock1 = { 'session-1': 5 };
+      const clock2 = { 'session-1': 3, 'session-2': 7 };
+
+      const merged = manager.merge(clock1, clock2);
+
+      expect(merged['session-1']).toBe(5);
+      expect(merged['session-2']).toBe(7);
+    });
+
+    it('should not mutate either input clock', () => {
+      const clock1 = { 'session-1': 5 };
+      const clock2 = { 'session-1': 3 };
+
+      manager.merge(clock1, clock2);
+
+      expect(clock1['session-1']).toBe(5); // Unchanged
+      expect(clock2['session-1']).toBe(3); // Unchanged
+    });
+
+    it('should handle empty clocks', () => {
+      const clock1 = {};
+      const clock2 = { 'session-1': 5 };
+
+      const merged = manager.merge(clock1, clock2);
+
+      expect(merged['session-1']).toBe(5);
+    });
+
+    it('should handle both empty clocks', () => {
+      const clock1 = {};
+      const clock2 = {};
+
+      const merged = manager.merge(clock1, clock2);
+
+      expect(Object.keys(merged)).toHaveLength(0);
+    });
+  });
+
+  describe('compare', () => {
+    it('should return 1 when clock1 > clock2 (causally after)', () => {
+      const clock1 = { 'session-1': 5, 'session-2': 3 };
+      const clock2 = { 'session-1': 3, 'session-2': 2 };
+
+      const result = manager.compare(clock1, clock2);
+
+      expect(result).toBe(1);
+    });
+
+    it('should return -1 when clock1 < clock2 (causally before)', () => {
+      const clock1 = { 'session-1': 3, 'session-2': 2 };
+      const clock2 = { 'session-1': 5, 'session-2': 3 };
+
+      const result = manager.compare(clock1, clock2);
+
+      expect(result).toBe(-1);
+    });
+
+    it('should return 0 when clocks are concurrent', () => {
+      const clock1 = { 'session-1': 5, 'session-2': 2 };
+      const clock2 = { 'session-1': 3, 'session-2': 4 };
+
+      const result = manager.compare(clock1, clock2);
+
+      expect(result).toBe(0); // Concurrent
+    });
+
+    it('should return 0 for identical clocks', () => {
+      const clock1 = { 'session-1': 5, 'session-2': 3 };
+      const clock2 = { 'session-1': 5, 'session-2': 3 };
+
+      const result = manager.compare(clock1, clock2);
+
+      expect(result).toBe(0);
+    });
+
+    it('should handle missing sessions in clock1', () => {
+      const clock1 = { 'session-1': 5 };
+      const clock2 = { 'session-1': 3, 'session-2': 2 };
+
+      const result = manager.compare(clock1, clock2);
+
+      expect(result).toBe(0); // Concurrent (5>3 but 0<2)
+    });
+
+    it('should handle missing sessions in clock2', () => {
+      const clock1 = { 'session-1': 3, 'session-2': 2 };
+      const clock2 = { 'session-1': 5 };
+
+      const result = manager.compare(clock1, clock2);
+
+      expect(result).toBe(0); // Concurrent (3<5 but 2>0)
+    });
+
+    it('should treat missing entries as 0', () => {
+      const clock1 = { 'session-1': 5 };
+      const clock2 = { 'session-2': 3 };
+
+      const result = manager.compare(clock1, clock2);
+
+      expect(result).toBe(0); // Concurrent
+    });
+  });
+
+  describe('concurrency detection', () => {
+    it('should detect concurrent operations', () => {
+      // Session 1 does operation A: {s1: 1, s2: 0}
+      const clockA = { 'session-1': 1, 'session-2': 0 };
+
+      // Session 2 does operation B: {s1: 0, s2: 1}
+      const clockB = { 'session-1': 0, 'session-2': 1 };
+
+      // Neither causally precedes the other
+      expect(manager.compare(clockA, clockB)).toBe(0);
+      expect(manager.compare(clockB, clockA)).toBe(0);
+    });
+
+    it('should detect causal ordering', () => {
+      // Session 1 does operation A: {s1: 1}
+      const clockA = { 'session-1': 1 };
+
+      // Session 1 does operation B after A: {s1: 2}
+      const clockB = { 'session-1': 2 };
+
+      // B causally follows A
+      expect(manager.compare(clockA, clockB)).toBe(-1);
+      expect(manager.compare(clockB, clockA)).toBe(1);
+    });
+
+    it('should detect concurrent edits to same object', () => {
+      // Both sessions have seen initial state
+      const baseClock = { 'session-1': 5, 'session-2': 3 };
+
+      // Session 1 makes an edit
+      const clock1 = manager.increment(baseClock, 'session-1');
+
+      // Session 2 makes concurrent edit (hasn't seen session 1's edit)
+      const clock2 = manager.increment(baseClock, 'session-2');
+
+      // These are concurrent
+      expect(manager.compare(clock1, clock2)).toBe(0);
+    });
+  });
+
+  describe('real-world scenarios', () => {
+    it('should handle multi-session collaboration', async () => {
+      // Three sessions editing concurrently
+      const sessions = ['s1', 's2', 's3'];
+      const clocks: Record<string, VectorClock> = {};
+
+      // Each session starts
+      sessions.forEach(sid => {
+        clocks[sid] = manager.create(sid);
+      });
+
+      // s1 makes first edit
+      clocks.s1 = manager.increment(clocks.s1, 's1');
+      expect(clocks.s1).toEqual({ 's1': 1 });
+
+      // s2 receives s1's edit and makes own edit
+      clocks.s2 = manager.merge(clocks.s2, clocks.s1);
+      clocks.s2 = manager.increment(clocks.s2, 's2');
+      expect(clocks.s2).toEqual({ 's1': 1, 's2': 1 });
+
+      // s2's edit causally follows s1's
+      expect(manager.compare(clocks.s1, clocks.s2)).toBe(-1);
+
+      // s3 makes concurrent edit (hasn't seen s1 or s2)
+      clocks.s3 = manager.increment(clocks.s3, 's3');
+      expect(clocks.s3).toEqual({ 's3': 1 });
+
+      // s3's edit is concurrent with both s1 and s2
+      expect(manager.compare(clocks.s1, clocks.s3)).toBe(0);
+      expect(manager.compare(clocks.s2, clocks.s3)).toBe(0);
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true
+  },
+  "include": ["src", "tests"]
+}