Vextra Cooperation Module

A collaborative editing module based on CRDT (Conflict-Free Replicated Data Types), specifically designed for the Vextra design tool ecosystem. Supports real-time collaborative editing, conflict resolution, and version management.

🚀 Features

• Real-time Collaborative Editing: Based on CRDT algorithms, supports multi-user simultaneous editing
• Automatic Conflict Resolution: Automatically handles concurrent editing conflicts without manual merging
• Version Management: Complete operation history and version control
• Undo/Redo: Supports local and collaborative undo/redo operations
• Network Synchronization: Configurable network layer supporting various collaboration scenarios
• Type Safety: Fully written in TypeScript with complete type definitions

📦 Installation

npm install @kcaitech/vextra-coop

🔧 Quick Start

Basic Usage

import { CoopRepository } from '@kcaitech/vextra-coop';
import { Document, TransactDataGuard } from '@kcaitech/vextra-core';

// Create collaborative repository
const document = new Document();
const repo = new TransactDataGuard();
const coopRepo = new CoopRepository(document, repo);

// Start editing operation
const operator = coopRepo.start('Add text');
// ... perform editing operations
coopRepo.commit();

Network Collaboration Setup

import { INet } from '@kcaitech/vextra-coop';

class CustomNetwork implements INet {
    hasConnected(): boolean {
        return true;
    }
    
    async pullCmds(from: number, to?: number): Promise<Cmd[]> {
        // Implement logic to pull commands from server
        return [];
    }
    
    async postCmds(cmds: Cmd[], serial: (cmds: Cmd[]) => string): Promise<boolean> {
        // Implement logic to push commands to server
        return true;
    }
    
    watchCmds(watcher: (cmds: Cmd[]) => void) {
        // Implement logic to watch remote commands
        return () => {};
    }
    
    watchError(watcher: (errorInfo: any) => void): void {
        // Implement error watching logic
    }
}

// Set up network layer
const network = new CustomNetwork();
coopRepo.setNet(network);

🏗️ Architecture Design

Core Components

• CoopRepository: Main collaborative repository class managing all collaborative operations
• CmdMgr: Command manager handling command synchronization and conflict resolution
• CRDT Algorithms: Conflict resolution algorithms based on array and tree structures
• Network Layer: Pluggable network interface supporting various collaboration protocols

Data Flow

User Operation → Local Command → Command Merging → Network Sync → Remote Application
    ↓
Undo/Redo ← Version Management ← Conflict Resolution ← Remote Commands

📚 API Documentation

CoopRepository

Main collaborative repository class providing complete collaborative editing functionality.

Methods

• start(description: string, selectionupdater?: Function): Start editing operation
• commit(mergetype?: CmdMergeType): Commit current editing
• undo(): Undo operation
• redo(): Redo operation
• canUndo(): Check if undo is possible
• canRedo(): Check if redo is possible
• setNet(net: INet): Set network layer
• receive(cmds: Cmd[]): Receive remote commands

INet Interface

Network layer interface for implementing custom network communication.

Required Methods

• hasConnected(): Check network connection status
• pullCmds(from: number, to?: number): Pull commands
• postCmds(cmds: Cmd[], serial: Function): Push commands
• watchCmds(watcher: Function): Watch remote commands
• watchError(watcher: Function): Watch for errors

Operation Types

• OpType.Array: Array operations
• OpType.Idset: Set operations
• OpType.CrdtArr: CRDT array operations
• OpType.CrdtTree: CRDT tree operations

🧪 Testing

Run test suite:

npm test

Run in development mode (watch file changes):

npm run dev

🏗️ Build

Build production version:

npm run build

📄 License

This project is licensed under the AGPL-3.0 License.

🤝 Contributing

Issues and Pull Requests are welcome! Please ensure:

1. Code follows project coding standards
2. New features include corresponding tests
3. Update relevant documentation

📖 Related Documentation

• Vextra Core - Core design tool library
• CRDT Algorithm Introduction
• Collaborative Editing Best Practices

🔗 Links

• Official Website
• GitHub Repository
• NPM Package

KCai Technology - Making Design Collaboration Simpler