@vuer-ai/vuer-rtc-server 0.1.1

package/tests/test-data/datatypes.ts

@@ -0,0 +1,677 @@
+/**
+ * Data Type Definitions - Complete operation sets for all data types
+ *
+ * This file defines:
+ * 1. What operations each data type supports
+ * 2. How those operations work
+ * 3. Conflict resolution semantics
+ *
+ * See docs/TYPE_BEHAVIORS.md for detailed behavior descriptions.
+ */
+
+// ============================================
+// PRIMITIVE DATA TYPES
+// ============================================
+
+/**
+ * Number Data Type
+ *
+ * dtype: 'number'
+ * Supported operations: set, add, multiply, min, max
+ */
+export const NumberType = {
+  dtype: 'number',
+  operations: {
+    /**
+     * SET - Replace value (LWW)
+     * Usage: Absolute values, IDs, measurements
+     */
+    set: {
+      behavior: 'lww',
+      merge: (ops: Array<{ value: number; lamportTime: number }>) => {
+        // Last-Write-Wins by lamport time
+        const sorted = ops.sort((a, b) => b.lamportTime - a.lamportTime);
+        return sorted[0].value;
+      },
+      example: {
+        ops: [
+          { value: 42, lamportTime: 100 },
+          { value: 99, lamportTime: 101 },
+        ],
+        result: 99,
+      },
+    },
+
+    /**
+     * ADD - Accumulate values
+     * Usage: Counters, scores, deltas
+     */
+    add: {
+      behavior: 'additive',
+      merge: (ops: Array<{ value: number; lamportTime: number }>) => {
+        // Sum all concurrent operations
+        return ops.reduce((sum, op) => sum + op.value, 0);
+      },
+      example: {
+        ops: [
+          { value: 10, lamportTime: 100 },
+          { value: 5, lamportTime: 101 },
+        ],
+        result: 15,
+      },
+    },
+
+    /**
+     * MULTIPLY - Multiply values
+     * Usage: Scale factors, percentages
+     */
+    multiply: {
+      behavior: 'multiplicative',
+      merge: (ops: Array<{ value: number; lamportTime: number }>) => {
+        return ops.reduce((product, op) => product * op.value, 1);
+      },
+      example: {
+        ops: [
+          { value: 2, lamportTime: 100 },
+          { value: 3, lamportTime: 101 },
+        ],
+        result: 6,
+      },
+    },
+
+    /**
+     * MIN - Take minimum value
+     * Usage: Lower bounds, quality settings
+     */
+    min: {
+      behavior: 'min',
+      merge: (ops: Array<{ value: number; lamportTime: number }>) => {
+        return Math.min(...ops.map((op) => op.value));
+      },
+      example: {
+        ops: [
+          { value: 720, lamportTime: 100 },
+          { value: 1080, lamportTime: 101 },
+        ],
+        result: 720,
+      },
+    },
+
+    /**
+     * MAX - Take maximum value
+     * Usage: Upper bounds, quality settings
+     */
+    max: {
+      behavior: 'max',
+      merge: (ops: Array<{ value: number; lamportTime: number }>) => {
+        return Math.max(...ops.map((op) => op.value));
+      },
+      example: {
+        ops: [
+          { value: 720, lamportTime: 100 },
+          { value: 1080, lamportTime: 101 },
+        ],
+        result: 1080,
+      },
+    },
+  },
+};
+
+/**
+ * String Data Type
+ *
+ * dtype: 'string'
+ * Supported operations: set, concat
+ */
+export const StringType = {
+  dtype: 'string',
+  operations: {
+    /**
+     * SET - Replace value (LWW)
+     * Usage: Names, labels, single values
+     */
+    set: {
+      behavior: 'lww',
+      merge: (ops: Array<{ value: string; lamportTime: number }>) => {
+        const sorted = ops.sort((a, b) => b.lamportTime - a.lamportTime);
+        return sorted[0].value;
+      },
+      example: {
+        ops: [
+          { value: 'Cube', lamportTime: 100 },
+          { value: 'Sphere', lamportTime: 101 },
+        ],
+        result: 'Sphere',
+      },
+    },
+
+    /**
+     * CONCAT - Concatenate values
+     * Usage: Logs, append-only strings
+     */
+    concat: {
+      behavior: 'append',
+      merge: (ops: Array<{ value: string; lamportTime: number }>, separator = '\n') => {
+        const sorted = ops.sort((a, b) => a.lamportTime - b.lamportTime);
+        return sorted.map((op) => op.value).join(separator);
+      },
+      example: {
+        ops: [
+          { value: 'User A edited', lamportTime: 100 },
+          { value: 'User B edited', lamportTime: 101 },
+        ],
+        result: 'User A edited\nUser B edited',
+      },
+    },
+  },
+};
+
+/**
+ * Boolean Data Type
+ *
+ * dtype: 'boolean'
+ * Supported operations: set, or, and
+ */
+export const BooleanType = {
+  dtype: 'boolean',
+  operations: {
+    /**
+     * SET - Replace value (LWW)
+     * Usage: Flags, toggles
+     */
+    set: {
+      behavior: 'lww',
+      merge: (ops: Array<{ value: boolean; lamportTime: number }>) => {
+        const sorted = ops.sort((a, b) => b.lamportTime - a.lamportTime);
+        return sorted[0].value;
+      },
+      example: {
+        ops: [
+          { value: true, lamportTime: 100 },
+          { value: false, lamportTime: 101 },
+        ],
+        result: false,
+      },
+    },
+
+    /**
+     * OR - Logical OR (enable wins)
+     * Usage: Feature flags where enabling takes precedence
+     */
+    or: {
+      behavior: 'or',
+      merge: (ops: Array<{ value: boolean; lamportTime: number }>) => {
+        return ops.some((op) => op.value === true);
+      },
+      example: {
+        ops: [
+          { value: true, lamportTime: 100 },
+          { value: false, lamportTime: 101 },
+        ],
+        result: true,
+      },
+    },
+
+    /**
+     * AND - Logical AND (disable wins)
+     * Usage: Permissions where disabling takes precedence
+     */
+    and: {
+      behavior: 'and',
+      merge: (ops: Array<{ value: boolean; lamportTime: number }>) => {
+        return ops.every((op) => op.value === true);
+      },
+      example: {
+        ops: [
+          { value: true, lamportTime: 100 },
+          { value: false, lamportTime: 101 },
+        ],
+        result: false,
+      },
+    },
+  },
+};
+
+// ============================================
+// COMPOUND DATA TYPES (3D GRAPHICS)
+// ============================================
+
+/**
+ * Vector3 Data Type - [x, y, z]
+ *
+ * dtype: 'vector3'
+ * Supported operations: set, add, multiply, lww-per-component
+ * Used for: position, scale, velocity
+ */
+export const Vector3Type = {
+  dtype: 'vector3',
+  operations: {
+    /**
+     * SET - Replace entire vector (LWW)
+     * Usage: Absolute position/scale
+     * Important: Preserves user intent by replacing whole vector
+     */
+    set: {
+      behavior: 'lww',
+      merge: (ops: Array<{ value: [number, number, number]; lamportTime: number }>) => {
+        const sorted = ops.sort((a, b) => b.lamportTime - a.lamportTime);
+        return sorted[0].value;
+      },
+      example: {
+        ops: [
+          { value: [5, 0, 0], lamportTime: 100 },
+          { value: [0, 5, 0], lamportTime: 101 },
+        ],
+        result: [0, 5, 0],
+        // NOT [5, 5, 0] - that would violate user intent!
+      },
+    },
+
+    /**
+     * ADD - Component-wise addition
+     * Usage: Velocity, forces, deltas
+     */
+    add: {
+      behavior: 'additive',
+      merge: (ops: Array<{ value: [number, number, number]; lamportTime: number }>) => {
+        const sum: [number, number, number] = [0, 0, 0];
+        for (const op of ops) {
+          sum[0] += op.value[0];
+          sum[1] += op.value[1];
+          sum[2] += op.value[2];
+        }
+        return sum;
+      },
+      example: {
+        ops: [
+          { value: [1, 0, 0], lamportTime: 100 },
+          { value: [0, 1, 0], lamportTime: 101 },
+        ],
+        result: [1, 1, 0],
+      },
+    },
+
+    /**
+     * MULTIPLY - Component-wise multiplication
+     * Usage: Scale composition
+     */
+    multiply: {
+      behavior: 'multiplicative',
+      merge: (ops: Array<{ value: [number, number, number]; lamportTime: number }>) => {
+        const product: [number, number, number] = [1, 1, 1];
+        for (const op of ops) {
+          product[0] *= op.value[0];
+          product[1] *= op.value[1];
+          product[2] *= op.value[2];
+        }
+        return product;
+      },
+      example: {
+        ops: [
+          { value: [2, 1, 1], lamportTime: 100 },
+          { value: [1, 3, 1], lamportTime: 101 },
+        ],
+        result: [2, 3, 1],
+      },
+    },
+
+    /**
+     * LWW_PER_COMPONENT - LWW per x/y/z
+     * Usage: Mixed semantics (rare)
+     */
+    lwwPerComponent: {
+      behavior: 'lww-per-component',
+      merge: (
+        ops: Array<{
+          value: Partial<{ x: number; y: number; z: number }>;
+          lamportTime: number;
+        }>
+      ) => {
+        const result = { x: 0, y: 0, z: 0 };
+        const latest = { x: -1, y: -1, z: -1 };
+
+        for (const op of ops) {
+          if (op.value.x !== undefined && op.lamportTime > latest.x) {
+            result.x = op.value.x;
+            latest.x = op.lamportTime;
+          }
+          if (op.value.y !== undefined && op.lamportTime > latest.y) {
+            result.y = op.value.y;
+            latest.y = op.lamportTime;
+          }
+          if (op.value.z !== undefined && op.lamportTime > latest.z) {
+            result.z = op.value.z;
+            latest.z = op.lamportTime;
+          }
+        }
+
+        return [result.x, result.y, result.z] as [number, number, number];
+      },
+      example: {
+        ops: [
+          { value: { x: 5 }, lamportTime: 100 },
+          { value: { y: 3 }, lamportTime: 101 },
+        ],
+        result: [5, 3, 0],
+      },
+    },
+  },
+};
+
+/**
+ * Quaternion Data Type - [x, y, z, w]
+ *
+ * dtype: 'quaternion'
+ * Supported operations: set, multiply
+ * Used for: rotation
+ */
+export const QuaternionType = {
+  dtype: 'quaternion',
+  operations: {
+    /**
+     * SET - Replace entire quaternion (LWW)
+     * Usage: Absolute rotation (most common)
+     */
+    set: {
+      behavior: 'lww',
+      merge: (ops: Array<{ value: [number, number, number, number]; lamportTime: number }>) => {
+        const sorted = ops.sort((a, b) => b.lamportTime - a.lamportTime);
+        return sorted[0].value;
+      },
+      example: {
+        ops: [
+          { value: [0, 0, 0, 1], lamportTime: 100 }, // No rotation
+          { value: [0, 0.707, 0, 0.707], lamportTime: 101 }, // 90° around Y
+        ],
+        result: [0, 0.707, 0, 0.707],
+      },
+    },
+
+    /**
+     * MULTIPLY - Quaternion multiplication (composition)
+     * Usage: Rotation composition (advanced)
+     * Warning: Order matters! Result may be unpredictable for users
+     */
+    multiply: {
+      behavior: 'multiplicative',
+      merge: (ops: Array<{ value: [number, number, number, number]; lamportTime: number }>) => {
+        // Sort by lamport time to get deterministic order
+        const sorted = ops.sort((a, b) => a.lamportTime - b.lamportTime);
+
+        // Multiply quaternions in order
+        let result = sorted[0].value;
+        for (let i = 1; i < sorted.length; i++) {
+          result = multiplyQuaternions(result, sorted[i].value);
+        }
+        return result;
+      },
+      example: {
+        ops: [
+          { value: [0, 0.707, 0, 0.707], lamportTime: 100 }, // 90° Y
+          { value: [0.707, 0, 0, 0.707], lamportTime: 101 }, // 90° X
+        ],
+        result: [0.5, 0.5, 0.5, 0.5], // Combined rotation
+      },
+    },
+  },
+};
+
+/**
+ * Helper: Quaternion multiplication
+ */
+function multiplyQuaternions(
+  a: [number, number, number, number],
+  b: [number, number, number, number]
+): [number, number, number, number] {
+  const [ax, ay, az, aw] = a;
+  const [bx, by, bz, bw] = b;
+
+  return [
+    aw * bx + ax * bw + ay * bz - az * by,
+    aw * by - ax * bz + ay * bw + az * bx,
+    aw * bz + ax * by - ay * bx + az * bw,
+    aw * bw - ax * bx - ay * by - az * bz,
+  ];
+}
+
+/**
+ * Color Data Type - RGB hex string or object
+ *
+ * dtype: 'color'
+ * Supported operations: set, blend
+ */
+export const ColorType = {
+  dtype: 'color',
+  operations: {
+    /**
+     * SET - Replace color (LWW)
+     * Usage: Object colors (most common)
+     */
+    set: {
+      behavior: 'lww',
+      merge: (ops: Array<{ value: string; lamportTime: number }>) => {
+        const sorted = ops.sort((a, b) => b.lamportTime - a.lamportTime);
+        return sorted[0].value;
+      },
+      example: {
+        ops: [
+          { value: '#ff0000', lamportTime: 100 },
+          { value: '#0000ff', lamportTime: 101 },
+        ],
+        result: '#0000ff',
+      },
+    },
+
+    /**
+     * BLEND - Average colors
+     * Usage: Lighting (advanced)
+     */
+    blend: {
+      behavior: 'blend',
+      merge: (ops: Array<{ value: string; lamportTime: number }>) => {
+        // Convert hex to RGB, average, convert back
+        const rgbs = ops.map((op) => hexToRgb(op.value));
+        const avgR = Math.round(rgbs.reduce((sum, rgb) => sum + rgb.r, 0) / rgbs.length);
+        const avgG = Math.round(rgbs.reduce((sum, rgb) => sum + rgb.g, 0) / rgbs.length);
+        const avgB = Math.round(rgbs.reduce((sum, rgb) => sum + rgb.b, 0) / rgbs.length);
+        return rgbToHex(avgR, avgG, avgB);
+      },
+      example: {
+        ops: [
+          { value: '#ff0000', lamportTime: 100 }, // Red
+          { value: '#0000ff', lamportTime: 101 }, // Blue
+        ],
+        result: '#7f007f', // Purple
+      },
+    },
+  },
+};
+
+/**
+ * Helper: Hex to RGB
+ */
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result
+    ? {
+        r: parseInt(result[1], 16),
+        g: parseInt(result[2], 16),
+        b: parseInt(result[3], 16),
+      }
+    : { r: 0, g: 0, b: 0 };
+}
+
+/**
+ * Helper: RGB to Hex
+ */
+function rgbToHex(r: number, g: number, b: number): string {
+  return '#' + [r, g, b].map((x) => x.toString(16).padStart(2, '0')).join('');
+}
+
+// ============================================
+// COLLECTION DATA TYPES
+// ============================================
+
+/**
+ * Array Data Type
+ *
+ * dtype: 'array'
+ * Supported operations: set, union, append, rga
+ */
+export const ArrayType = {
+  dtype: 'array',
+  operations: {
+    /**
+     * SET - Replace entire array (LWW)
+     * Usage: Replace whole list
+     */
+    set: {
+      behavior: 'lww',
+      merge: (ops: Array<{ value: any[]; lamportTime: number }>) => {
+        const sorted = ops.sort((a, b) => b.lamportTime - a.lamportTime);
+        return sorted[0].value;
+      },
+      example: {
+        ops: [
+          { value: ['a', 'b'], lamportTime: 100 },
+          { value: ['c', 'd'], lamportTime: 101 },
+        ],
+        result: ['c', 'd'],
+      },
+    },
+
+    /**
+     * UNION - Merge all unique elements
+     * Usage: Tags, sets
+     */
+    union: {
+      behavior: 'union',
+      merge: (ops: Array<{ value: any[]; lamportTime: number }>) => {
+        const allElements = ops.flatMap((op) => op.value);
+        return [...new Set(allElements)];
+      },
+      example: {
+        ops: [
+          { value: ['a', 'b'], lamportTime: 100 },
+          { value: ['b', 'c'], lamportTime: 101 },
+        ],
+        result: ['a', 'b', 'c'],
+      },
+    },
+
+    /**
+     * APPEND - Append all (ordered by lamport)
+     * Usage: Logs, history
+     */
+    append: {
+      behavior: 'append',
+      merge: (ops: Array<{ value: any[]; lamportTime: number }>) => {
+        const sorted = ops.sort((a, b) => a.lamportTime - b.lamportTime);
+        return sorted.flatMap((op) => op.value);
+      },
+      example: {
+        ops: [
+          { value: ['edit1'], lamportTime: 100 },
+          { value: ['edit2'], lamportTime: 101 },
+        ],
+        result: ['edit1', 'edit2'],
+      },
+    },
+
+    /**
+     * RGA - Replicated Growable Array (CRDT)
+     * Usage: Text editing, ordered lists (Phase 3)
+     */
+    rga: {
+      behavior: 'rga',
+      merge: (
+        ops: Array<{ action: 'insert' | 'delete'; index: number; value?: any; lamportTime: number }>
+      ) => {
+        // Simplified RGA - real implementation needs tombstones and references
+        const sorted = ops.sort((a, b) => a.lamportTime - b.lamportTime);
+        const result: any[] = [];
+
+        for (const op of sorted) {
+          if (op.action === 'insert') {
+            result.splice(op.index, 0, op.value);
+          } else if (op.action === 'delete') {
+            result.splice(op.index, 1);
+          }
+        }
+
+        return result;
+      },
+      example: {
+        ops: [
+          { action: 'insert', index: 0, value: 'a', lamportTime: 100 },
+          { action: 'insert', index: 1, value: 'b', lamportTime: 101 },
+          { action: 'insert', index: 1, value: 'X', lamportTime: 102 },
+        ],
+        result: ['a', 'X', 'b'],
+      },
+    },
+  },
+};
+
+/**
+ * Object/Map Data Type
+ *
+ * dtype: 'object'
+ * Supported operations: set, lww-per-key
+ */
+export const ObjectType = {
+  dtype: 'object',
+  operations: {
+    /**
+     * SET - Replace entire object (LWW)
+     * Usage: Replace whole map
+     */
+    set: {
+      behavior: 'lww',
+      merge: (ops: Array<{ value: Record<string, any>; lamportTime: number }>) => {
+        const sorted = ops.sort((a, b) => b.lamportTime - a.lamportTime);
+        return sorted[0].value;
+      },
+      example: {
+        ops: [
+          { value: { a: 1 }, lamportTime: 100 },
+          { value: { b: 2 }, lamportTime: 101 },
+        ],
+        result: { b: 2 },
+      },
+    },
+
+    /**
+     * LWW_PER_KEY - LWW per object key
+     * Usage: Properties (most common)
+     */
+    lwwPerKey: {
+      behavior: 'lww-per-key',
+      merge: (
+        ops: Array<{ value: Record<string, any>; lamportTime: number; perKeyLamport?: Record<string, number> }>
+      ) => {
+        const result: Record<string, any> = {};
+        const latestTimes: Record<string, number> = {};
+
+        for (const op of ops) {
+          for (const [key, value] of Object.entries(op.value)) {
+            const keyLamport = op.perKeyLamport?.[key] ?? op.lamportTime;
+            if (!latestTimes[key] || keyLamport > latestTimes[key]) {
+              result[key] = value;
+              latestTimes[key] = keyLamport;
+            }
+          }
+        }
+
+        return result;
+      },
+      example: {
+        ops: [
+          { value: { color: 'red', size: 10 }, lamportTime: 100 },
+          { value: { color: 'blue', opacity: 0.5 }, lamportTime: 101 },
+        ],
+        result: { color: 'blue', size: 10, opacity: 0.5 },
+      },
+    },
+  },
+};