@vuer-ai/vuer-rtc 0.4.2 → 0.5.0

package/src/client/coalescence/textInserts.ts

@@ -0,0 +1,128 @@
+/**
+ * Text Insert Coalescence Utility
+ *
+ * Merges consecutive text insert operations to reduce network traffic.
+ * Uses CRDT comparison logic: seq → ts → id.
+ *
+ * Merge conditions:
+ * 1. Same agent (from ID)
+ * 2. Same target (key + path)
+ * 3. Sequential IDs (ID seq numbers are consecutive)
+ * 4. Within time threshold (ts difference)
+ * 5. Compatible YATA structure (forms a chain)
+ */
+
+import type { Operation } from '../../operations/OperationTypes.js';
+import { parseItemId } from '../../crdt/Rope.js';
+
+export interface TextInsertOp {
+  otype: 'text.insert';
+  key: string;
+  path: string;
+  id: string;
+  content: string;
+  parentId: string | null;
+  seq: number;
+  ts: number;
+}
+
+export interface CoalesceOptions {
+  /** Time threshold in milliseconds (default: 1000ms = 1 second) */
+  thresholdMs?: number;
+}
+
+/**
+ * Check if an operation is a text insert with CRDT metadata
+ */
+export function isTextInsertOp(op: Operation): op is TextInsertOp {
+  return (
+    op.otype === 'text.insert' &&
+    typeof (op as any).id === 'string' &&
+    typeof (op as any).content === 'string' &&
+    typeof (op as any).seq === 'number' &&
+    typeof (op as any).ts === 'number'
+  );
+}
+
+/**
+ * Coalesce consecutive text insert operations.
+ *
+ * Example:
+ * Input:  [insert(id:"alice:1", "h"), insert(id:"alice:2", "e"), insert(id:"alice:3", "l")]
+ * Output: [insert(id:"alice:1", "hel")]
+ *
+ * @param ops - Array of text insert operations
+ * @param options - Coalescence options
+ * @returns New array with coalesced operations
+ */
+export function coalesceTextInserts(
+  ops: TextInsertOp[],
+  options: CoalesceOptions = {}
+): TextInsertOp[] {
+  const { thresholdMs = 1000 } = options;
+
+  if (ops.length === 0) return ops;
+
+  const result: TextInsertOp[] = [];
+  let pending: TextInsertOp | null = null;
+
+  for (const op of ops) {
+    if (pending === null) {
+      // Start new pending insert
+      pending = { ...op };
+    } else {
+      // Parse IDs to extract agent and local sequence numbers
+      const prevId = parseItemId(pending.id);
+      const currId = parseItemId(op.id);
+
+      // Check merge conditions
+      const sameAgent = prevId.agent === currId.agent;
+      const sameTarget = pending.key === op.key && pending.path === op.path;
+
+      // IDs must be sequential: next ID = prev ID + prev content length
+      // Example: prev="alice:5" content="hel"(3 chars) → next="alice:8"
+      const sequentialIds = currId.seq === prevId.seq + pending.content.length;
+
+      // Time threshold: operations must be close in time (ts is in seconds)
+      const timeDiffMs = (op.ts - pending.ts) * 1000;
+      const withinThreshold = timeDiffMs <= thresholdMs;
+
+      // YATA structure: check if operations form a valid chain
+      // Current op's parent should be the last character ID in the merged content
+      // (not the first ID, which is what pending.id contains after merging)
+      // OR both should have the same parent (inserting at same position)
+      const prevLastId = (pending as any)._lastCharId || pending.id;
+      const formsChain =
+        op.parentId === prevLastId ||
+        (pending.parentId === op.parentId && pending.parentId !== null);
+
+      if (sameAgent && sameTarget && sequentialIds && withinThreshold && formsChain) {
+        // Merge operations
+        const merged: TextInsertOp = {
+          otype: 'text.insert',
+          key: pending.key,
+          path: pending.path,
+          id: pending.id, // Keep first ID (anchor point)
+          content: pending.content + op.content, // Concatenate content
+          parentId: pending.parentId, // Keep first parentId
+          seq: Math.max(pending.seq, op.seq), // Use max Lamport clock for ordering
+          ts: pending.ts, // Keep first timestamp (when sequence started)
+          // Track the last character ID for chain validation in next merge
+          _lastCharId: op.id,
+        } as any;
+        pending = merged;
+      } else {
+        // Can't merge - flush pending and start new
+        result.push(pending);
+        pending = { ...op };
+      }
+    }
+  }
+
+  // Flush any remaining pending insert
+  if (pending !== null) {
+    result.push(pending);
+  }
+
+  return result;
+}

package/src/client/createGraph.ts

@@ -40,6 +40,7 @@ export function createGraph(options: CreateGraphOptions): GraphStore {
   let coalescingTimer: ReturnType<typeof setTimeout> | null = null;
   let coalescingEnabled = options.coalescingEnabled ?? false;
   let coalescingDelayMs = options.coalescingDelayMs ?? 300;
+  let coalescingThresholdMs = options.coalescingThresholdMs ?? 1000;
 
   function dispatch(fn: (s: ClientState) => ClientState): void {
     state = fn(state);
@@ -59,7 +60,7 @@ export function createGraph(options: CreateGraphOptions): GraphStore {
     coalescingTimer = setTimeout(() => {
       coalescingTimer = null;
       if (state.edits.ops.length > 0) {
-        const result = commitEdits(state, 'coalesced commit');
+        const result = commitEdits(state, 'coalesced commit', coalescingThresholdMs);
         dispatch(() => result.state);
         if (result.msg) {
           options.onSend?.(result.msg);
@@ -92,7 +93,9 @@ export function createGraph(options: CreateGraphOptions): GraphStore {
       // Clear pending coalescing timer when explicitly committing
       clearCoalescingTimer();
 
-      const result = commitEdits(state, _description);
+      // Pass threshold if coalescence is enabled
+      const threshold = coalescingEnabled ? coalescingThresholdMs : undefined;
+      const result = commitEdits(state, _description, threshold);
       dispatch(() => result.state);
       if (result.msg) {
         options.onSend?.(result.msg);
@@ -113,10 +116,16 @@ export function createGraph(options: CreateGraphOptions): GraphStore {
       coalescingDelayMs = delayMs;
     },
 
+    setCoalescingThreshold: (thresholdMs: number) => {
+      coalescingThresholdMs = thresholdMs;
+    },
+
     getCoalescingEnabled: () => coalescingEnabled,
 
     getCoalescingDelay: () => coalescingDelayMs,
 
+    getCoalescingThreshold: () => coalescingThresholdMs,
+
     // Server communication
     receive: (msg: CRDTMessage) => {
       dispatch(s => onRemoteMessage(s, msg));

package/src/client/createTextDocument.ts

@@ -62,7 +62,8 @@ export function createTextDocument(options: CreateTextDocumentOptions): TextDocu
     coalescingTimer = setTimeout(() => {
       coalescingTimer = null;
       if (state.edits.ops.length > 0) {
-        const result = commitTextEdits(state, 'coalesced commit');
+        // Pass coalescingDelayMs as threshold for operation merging
+        const result = commitTextEdits(state, 'coalesced commit', coalescingDelayMs);
         dispatch(() => result.state);
         if (result.msg) {
           options.onSend?.(result.msg);

package/src/client/index.ts

@@ -39,6 +39,17 @@ export {
 // Edit buffer utilities
 export { isAdditiveOp, mergeValues, EditBufferImpl, coalesceTextOps } from './EditBuffer.js';
 
+// Coalescence utilities
+export { coalesceGraphOps } from './coalesceGraphOps.js';
+export {
+  coalesceOperations,
+  registerCoalescer,
+  coalesceTextInserts,
+  coalesceTextDeletes,
+  type CoalesceHandler,
+  type TypeGuard,
+} from './coalescence/index.js';
+
 // Sound utilities
 export { playWhoosh, createMessageSentSound } from './sounds.js';
 
@@ -80,3 +91,6 @@ export {
   redoText,
   initTextFromServer,
 } from './textActions.js';
+
+export { coalesceTextOperations, compareTextOps } from './coalesceTextOperations.js';
+export type { CoalesceOptions } from './coalesceTextOperations.js';

package/src/client/textActions.ts

@@ -24,6 +24,7 @@ import type {
   TextSnapshot,
 } from './textTypes.js';
 import { VectorClockManager, type VectorClock } from '../state/VectorClock.js';
+import { coalesceTextOperations } from './coalesceTextOperations.js';
 
 const clockManager = new VectorClockManager();
 
@@ -95,12 +96,18 @@ export function onTextEdit(
  */
 export function commitTextEdits(
   state: TextDocumentState,
-  description?: string
+  description?: string,
+  coalescingThresholdMs?: number
 ): { state: TextDocumentState; msg: TextMessage | null } {
   if (state.edits.ops.length === 0) {
     return { state, msg: null };
   }
 
+  // Coalesce operations before sending (if threshold provided)
+  const operations = coalescingThresholdMs !== undefined
+    ? coalesceTextOperations(state.edits.ops, { thresholdMs: coalescingThresholdMs })
+    : state.edits.ops;
+
   const msgId = `${state.sessionId}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
   const vectorClock = clockManager.increment(state.vectorClock, state.sessionId);
   const lamportTime = state.lamportTime + 1;
@@ -108,7 +115,7 @@ export function commitTextEdits(
   const msg: TextMessage = {
     msgId,
     sessionId: state.sessionId,
-    operations: state.edits.ops,
+    operations,
     vectorClock,
     lamportTime,
     timestamp: Date.now(),

package/src/client/types.ts

@@ -70,7 +70,8 @@ export interface CreateGraphOptions {
   onStateChange?: (state: ClientState) => void;
   onMessageSent?: (msg: CRDTMessage) => void;  // Called after each message sent (for sound, analytics, etc)
   coalescingEnabled?: boolean;
-  coalescingDelayMs?: number;
+  coalescingDelayMs?: number;      // Time to wait before auto-committing (batching delay)
+  coalescingThresholdMs?: number;  // Time window for merging operations (merge threshold)
 }
 
 /**
@@ -101,6 +102,8 @@ export interface GraphStore {
   // Coalescing control
   setCoalescingEnabled: (enabled: boolean) => void;
   setCoalescingDelay: (delayMs: number) => void;
+  setCoalescingThreshold: (thresholdMs: number) => void;
   getCoalescingEnabled: () => boolean;
   getCoalescingDelay: () => number;
+  getCoalescingThreshold: () => number;
 }

package/src/crdt/GraphTextCRDT.ts

@@ -36,11 +36,6 @@ import {
 // Types
 // ============================================
 
-export interface ItemId {
-  agent: string;
-  seq: number;
-}
-
 /**
  * Graph-level CRDT coordinator
  *