otter-js v0.3.0

Otter

Otter is a library to support collaborative realtime editing using Operational Transformation. This repository contains the JavaScript-implementation for use both in a browser and in a Node-based server.

A Java-implementation is also available.

Using Otter

Install via NPM:

npm install --save otter-js

Otter consists of three parts, the operations library, the editing engine and a high level model. The high level model is what you usually want to use unless you are implementing something special.

Operations

The lowest level of Otter is the operational transformation algorithms. Otter supports transformations on maps, lists and strings. There is also a combined type that can be used to combine several other types based on unique identifiers. All of these transformations are used together to create the higher level model.

Engine

The engine contains editing control. It provides support for creating editors on top of any supported operational transformation.

const string = require('otter-js/operations/string');
const Editor = require('otter-js/engine/editor');

const sync = new YourOperationSync(string.newType(), ...);
const editor = new Editor(sync);

// Connect and do something with the current version
editor.connect()
	.then(() => {
		editor.current.apply(...);
		editor.on('change', function(e) {
			// This will receive all operations that occur on the editor
		});
	});


// Perform an operation
editor.apply(string.delta()
	.retain(currentStringLength)
	.insert('abc')
	.done()
);

Editors require a synchronization helper for sending and receiving operations from a server. There is intentionally no default implementation of such a sync as different applications will have different requirements here.

In the end all operations performed by an editor will end up being handled by an instance of EditorControl.

const EditorControl = require('otter-js/engine/editor-control');

const control = new EditorControl(historyStorage);

control.latest()
	.then(latestVersion => {
		// Do something with the latest version
	});


// When an operation is received from a client it needs to be stored and
// the result needs to be sent back to all clients
control.store(taggedOperation)
	.then(op => {
		// Op should be sent back to all clients
	});

Model

This is the high level API that makes it easier to work with shared editing. The model provides shared objects of different types that are synchronized between all editors of the model.

Here is a tiny example of working with the model:

const combined = require('otter-js/operations/combined');
const Editor = require('otter-js/engine/editor');
const Model = require('otter-js/model');

const sync = new YourOperationSync(combined.newType(), ...);
const editor = new Editor(sync);
const model = new Model(editor);

model.open()
	.then(function() {
		// Create a new string and store it in the root map
		const title = model.newString();
		title.set('Cookies are tasty');
		model.set('title', title);

		// Set a primitive value in the map
		model.set('priority', 10);
	});