@vuer-ai/vuer-rtc 0.0.1

package/src/operations/dispatcher.ts

@@ -0,0 +1,127 @@
+/**
+ * Operation Dispatcher
+ *
+ * Applies CRDTMessage operations to a SceneGraph using immer.
+ * Each operation is dispatched to its corresponding "apply" function.
+ */
+
+import { produce, enableMapSet } from 'immer';
+import type { SceneGraph, CRDTMessage, Operation } from './OperationTypes.js';
+import type { OpMeta } from './apply/types.js';
+import * as registry from './apply/index.js';
+
+// Enable immer support for Map and Set
+enableMapSet();
+
+/**
+ * Handler map: otype -> apply function
+ */
+const handlers: Record<string, (draft: SceneGraph, op: Operation, meta: OpMeta) => void> = {
+  // Number operations
+  'number.set': registry.NumberSet as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'number.add': registry.NumberAdd as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'number.multiply': registry.NumberMultiply as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'number.min': registry.NumberMin as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'number.max': registry.NumberMax as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+
+  // String operations
+  'string.set': registry.StringSet as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'string.concat': registry.StringConcat as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+
+  // Boolean operations
+  'boolean.set': registry.BooleanSet as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'boolean.or': registry.BooleanOr as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'boolean.and': registry.BooleanAnd as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+
+  // Vector3 operations
+  'vector3.set': registry.Vector3Set as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'vector3.add': registry.Vector3Add as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'vector3.multiply': registry.Vector3Multiply as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+
+  // Quaternion operations
+  'quaternion.set': registry.QuaternionSet as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'quaternion.multiply': registry.QuaternionMultiply as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+
+  // Color operations
+  'color.set': registry.ColorSet as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'color.blend': registry.ColorBlend as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+
+  // Array operations
+  'array.set': registry.ArraySet as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'array.push': registry.ArrayPush as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'array.remove': registry.ArrayRemove as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'array.union': registry.ArrayUnion as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+
+  // Object operations
+  'object.set': registry.ObjectSet as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'object.merge': registry.ObjectMerge as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+
+  // Node operations
+  'node.insert': registry.NodeInsert as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+  'node.remove': registry.NodeRemove as (draft: SceneGraph, op: Operation, meta: OpMeta) => void,
+};
+
+/**
+ * Apply a single operation to a SceneGraph draft
+ */
+export function applyOperation(
+  draft: SceneGraph,
+  op: Operation,
+  meta: OpMeta
+): void {
+  const handler = handlers[op.otype];
+  if (handler) {
+    handler(draft, op, meta);
+  } else {
+    console.warn(`Unknown otype: ${op.otype}`);
+  }
+}
+
+/**
+ * Apply a CRDTMessage to a SceneGraph (immutable)
+ *
+ * Uses immer to produce a new state without mutating the original.
+ *
+ * @param graph - Current scene graph state
+ * @param msg - CRDT message containing operations
+ * @returns New scene graph state with operations applied
+ */
+export function applyMessage(graph: SceneGraph, msg: CRDTMessage): SceneGraph {
+  return produce(graph, (draft) => {
+    const meta: OpMeta = {
+      sessionId: msg.sessionId,
+      clock: msg.clock,
+      lamportTime: msg.lamportTime,
+      timestamp: msg.timestamp,
+    };
+
+    for (const op of msg.ops) {
+      applyOperation(draft, op, meta);
+    }
+  });
+}
+
+/**
+ * Apply multiple CRDTMessages to a SceneGraph (immutable)
+ *
+ * @param graph - Current scene graph state
+ * @param messages - Array of CRDT messages to apply
+ * @returns New scene graph state with all operations applied
+ */
+export function applyMessages(graph: SceneGraph, messages: CRDTMessage[]): SceneGraph {
+  let current = graph;
+  for (const msg of messages) {
+    current = applyMessage(current, msg);
+  }
+  return current;
+}
+
+/**
+ * Create an empty scene graph
+ */
+export function createEmptyGraph(): SceneGraph {
+  return {
+    nodes: {},
+    rootKey: '',
+  };
+}

package/src/operations/index.ts

@@ -0,0 +1,80 @@
+/**
+ * Operations module exports
+ */
+
+// ============================================
+// Operation Types
+// ============================================
+
+export type {
+  CRDTMessage,
+  BaseOp,
+  // Number ops
+  NumberSetOp,
+  NumberAddOp,
+  NumberMultiplyOp,
+  NumberMinOp,
+  NumberMaxOp,
+  // String ops
+  StringSetOp,
+  StringConcatOp,
+  // Boolean ops
+  BooleanSetOp,
+  BooleanOrOp,
+  BooleanAndOp,
+  // Vector3 ops
+  Vector3SetOp,
+  Vector3AddOp,
+  Vector3MultiplyOp,
+  // Quaternion ops
+  QuaternionSetOp,
+  QuaternionMultiplyOp,
+  // Color ops
+  ColorSetOp,
+  ColorBlendOp,
+  // Array ops
+  ArraySetOp,
+  ArrayPushOp,
+  ArrayUnionOp,
+  ArrayRemoveOp,
+  // Object ops
+  ObjectSetOp,
+  ObjectMergeOp,
+  // Scene graph ops
+  NodeInsertOp,
+  NodeRemoveOp,
+  // Meta ops (undo/redo)
+  MetaUndoOp,
+  MetaRedoOp,
+  // Union
+  Operation,
+  // Scene graph types
+  SceneNode,
+  SceneGraph,
+} from './OperationTypes.js';
+
+// ============================================
+// Validation
+// ============================================
+
+export { OperationValidator, type ValidationResult } from './OperationValidator.js';
+
+// ============================================
+// Apply Registry (individual apply functions)
+// ============================================
+
+import * as registry from './apply/index.js';
+export { registry };
+
+export type { OpMeta, ApplyFn } from './apply/types.js';
+
+// ============================================
+// Dispatcher (high-level API)
+// ============================================
+
+export {
+  applyMessage,
+  applyMessages,
+  applyOperation,
+  createEmptyGraph,
+} from './dispatcher.js';

package/src/state/ConflictResolver.ts

@@ -0,0 +1,205 @@
+/**
+ * ConflictResolver - Schema-based property conflict resolution
+ *
+ * Merges concurrent property updates based on:
+ * - Property schema (dtype + operation)
+ * - DType merge functions
+ */
+
+import { DType, type ValueWithMeta } from './DType.js';
+import { getPropertySchema, isImmutable } from './Schema.js';
+
+export class ConflictResolver {
+  /**
+   * Merge a single property from multiple concurrent updates
+   *
+   * @param propertyName - Name of the property being merged
+   * @param values - Array of values with metadata
+   * @param operationHint - Optional operation override from UPDATE operation
+   * @returns Merged value
+   */
+  mergeProperty<T = any>(
+    propertyName: string,
+    values: ValueWithMeta<T>[],
+    operationHint?: string
+  ): T {
+    if (values.length === 0) {
+      throw new Error(`Cannot merge empty values for property: ${propertyName}`);
+    }
+
+    if (values.length === 1) {
+      return values[0].value;
+    }
+
+    // Get schema for this property
+    const schema = getPropertySchema(propertyName);
+
+    // Immutable properties: return earliest value
+    if (isImmutable(propertyName)) {
+      const sorted = [...values].sort((a, b) => a.lamportTime - b.lamportTime);
+      return sorted[0].value;
+    }
+
+    // Use operation hint if provided, otherwise use schema
+    const operation = operationHint || schema.operation;
+
+    // Get merge function based on dtype and operation
+    const mergeFn = this.getMergeFunction(schema.dtype, operation);
+
+    if (!mergeFn) {
+      console.warn(
+        `No merge function for dtype=${schema.dtype} operation=${operation}, defaulting to LWW`
+      );
+      return DType.string.set(values as any) as any;
+    }
+
+    return mergeFn(values);
+  }
+
+  /**
+   * Merge multiple properties from concurrent updates
+   *
+   * @param updates - Array of property updates with metadata and operation hints
+   * @returns Merged properties
+   */
+  mergeProperties(
+    updates: Array<{
+      properties: Record<string, any>;
+      operations?: Record<string, string>; // Operation hints per property
+      lamportTime: number;
+      sessionId: string;
+    }>
+  ): Record<string, any> {
+    // Group values by property name
+    const valuesByProperty = new Map<string, ValueWithMeta[]>();
+    const operationHints = new Map<string, string>();
+
+    for (const update of updates) {
+      for (const [key, value] of Object.entries(update.properties)) {
+        if (key === 'operations') continue; // Skip operations field
+
+        if (!valuesByProperty.has(key)) {
+          valuesByProperty.set(key, []);
+        }
+
+        valuesByProperty.get(key)!.push({
+          value,
+          lamportTime: update.lamportTime,
+          sessionId: update.sessionId,
+        });
+
+        // Store operation hint if provided
+        if (update.operations?.[key]) {
+          operationHints.set(key, update.operations[key]);
+        }
+      }
+    }
+
+    // Merge each property
+    const result: Record<string, any> = {};
+
+    for (const [propertyName, values] of valuesByProperty.entries()) {
+      const operationHint = operationHints.get(propertyName);
+      result[propertyName] = this.mergeProperty(propertyName, values, operationHint);
+    }
+
+    return result;
+  }
+
+  /**
+   * Get merge function for dtype and operation
+   */
+  private getMergeFunction(dtype: string, operation: string): ((values: ValueWithMeta[]) => any) | null {
+    switch (dtype) {
+      case 'number':
+        switch (operation) {
+          case 'set':
+            return DType.number.set;
+          case 'add':
+            return DType.number.add;
+          case 'multiply':
+            return DType.number.multiply;
+          case 'min':
+            return DType.number.min;
+          case 'max':
+            return DType.number.max;
+        }
+        break;
+
+      case 'string':
+        switch (operation) {
+          case 'set':
+            return DType.string.set;
+          case 'concat':
+            return DType.string.concat as any;
+        }
+        break;
+
+      case 'boolean':
+        switch (operation) {
+          case 'set':
+            return DType.boolean.set;
+          case 'or':
+            return DType.boolean.or;
+          case 'and':
+            return DType.boolean.and;
+        }
+        break;
+
+      case 'vector3':
+        switch (operation) {
+          case 'set':
+            return DType.vector3.set;
+          case 'add':
+            return DType.vector3.add;
+          case 'multiply':
+            return DType.vector3.multiply;
+        }
+        break;
+
+      case 'quaternion':
+        switch (operation) {
+          case 'set':
+            return DType.quaternion.set;
+          case 'multiply':
+            return DType.quaternion.multiply;
+        }
+        break;
+
+      case 'color':
+        switch (operation) {
+          case 'set':
+            return DType.color.set;
+          case 'blend':
+            return DType.color.blend;
+        }
+        break;
+
+      case 'array':
+        switch (operation) {
+          case 'set':
+            return DType.array.set;
+          case 'union':
+            return DType.array.union;
+          case 'append':
+            return DType.array.append;
+        }
+        break;
+
+      case 'object':
+        switch (operation) {
+          case 'set':
+            return DType.object.set;
+          case 'lww-per-key':
+            return DType.object.lwwPerKey;
+        }
+        break;
+
+      case 'any':
+        // Default to LWW for 'any' type
+        return DType.string.set as any;
+    }
+
+    return null;
+  }
+}