OT_Types

js-collaboration-ot support multi-user collaborative editing through Operational Transformation (OT). OT Type define the transform and apply logic for operations (Ops), register to both the client and server sides. OT Type are responsible for handling operation conflicts and application, ensuring that multi-user operations can be synchronized correctly. This document introduces the definition and usage of OT Type.

OT_Type must be registered on both server and client.

Prerequisity

Before reading the subsequent sections, it is recommended to first read the following article to understand conflicts and Transform: Conflicts and Transform.

Definition

The general OT_Type interface includes the following methods, register to both the client and server sides:

/**
 * The interface of ot type, user can customize the ot behavior of the collaboration.
 * @template S The type of snapshot.
 * @template T The type of op.
 */
export interface OT_Type<S = unknown, T = unknown> {
    /**
     * The type uri of the document.
     */
    uri: string;
    /**
     * Create a snapshot from init data.
     * @param data - snapshot
     * @returns snapshot
     */
    create?(data: any): S;
    /**
     * Transform op1, to handling conflicts.
     * @param op1 The op to be transformed.
     * @param op2 The basis of the operation being transformed (op1 is transformed based on op2).
     * @param side Indicates which parameter's corresponding op arrives at the server later.
     * @returns The transformed op1.
     */
    transform(op1: T, op2: T, side: 'left' | 'right'): T;
    /**
     * Apply op to snapshot.
     * @param snapshot - snapshot
     * @param op - op
     * @returns snapshot
     */
    apply(snapshot: S, op: T): S;
}

This document only describes the basic capabilities of OT Types. For additional extended capabilities, please refer to the following link: Fragment.

Example: Simple Text OT Type

The following is a simplified text OT Type example, supporting only text insertion operations, but not operations like text deletion.

The operations (Ops) in the following example are simplified for demonstration purposes. In real-world scenarios, the structure and content of Ops may vary depending on the document type, operation complexity and implementation.

type ISnapshot = string;
interface IOp {
    pos: number;
    text: string;
};

const textType: OT_Type<ISnapshot, IOp> = {
    uri: 'rich-text-ot-type',
    create: (data) => data || '', // Initialize as an empty string
    transform: (op1, op2, side) => {
        if (op1.pos > op2.pos || (op1.pos === op2.pos && side === 'left')) {
            return { pos: op1.pos + op2.text.length, text: op1.text };
        }
        return op1;
    },
    apply: (snapshot, op) => {
        return snapshot.slice(0, op.pos) + op.text + snapshot.slice(op.pos);
    }
};

Registration

Client-Side Registration

import { TypesManager } from '@mescius/js-collaboration-ot-client';

// Register the OT Type
TypesManager.register(textType);

Server-Side Registration

import { TypesManager } from '@mescius/js-collaboration-ot';

// Register the OT Type
TypesManager.register(textType);

OT_Types

Prerequisity

Definition

Example: Simple Text OT Type

Registration

Next Steps