Compare commits

..

41 Commits

Author SHA1 Message Date
Kevin Jahns
658081566b Deploy 10.0.2 2016-03-23 14:42:23 +01:00
Kevin Jahns
ffe0ec5a38 Deploy 10.0.1 2016-03-23 14:41:04 +01:00
Kevin Jahns
5cfe209688 added xml example 2016-03-14 19:45:50 +01:00
Kevin Jahns
51c8d3bdc6 Deploy 9.0.4 2016-02-24 12:00:45 +01:00
Kevin Jahns
0f86b71f78 add readme? 2016-02-24 12:00:02 +01:00
Kevin Jahns
fafda2726f Deploy 9.0.3 2016-02-23 15:50:16 +01:00
Kevin Jahns
116770fbce fix gitignore, fix Examples/bower.json 2016-02-23 15:47:53 +01:00
Kevin Jahns
5286f507c8 Deploy 9.0.2 2016-02-23 15:42:09 +01:00
Kevin Jahns
2f7349b712 fixed bower & added dependencies & cleanup 2016-02-23 15:41:22 +01:00
Kevin Jahns
54529ab1e7 Deploy 9.0.1 2016-02-23 11:58:10 +01:00
Kevin Jahns
e165c5ee2a added peer dependencies, upgraded version to major (new versioning scheme) 2016-02-23 11:57:27 +01:00
Kevin Jahns
7b3693aff3 Deploy 0.8.28 2016-02-23 11:27:26 +01:00
Kevin Jahns
f75f47646b Deploy 0.8.27 2016-02-22 13:08:01 +01:00
Kevin Jahns
64044123e3 Deploy 0.8.26 2016-02-22 13:06:11 +01:00
Kevin Jahns
a286162ace Deploy 0.8.25 2016-02-22 13:04:32 +01:00
Kevin Jahns
f739f3b5d7 Deploy 0.8.23 2016-02-22 12:40:21 +01:00
Kevin Jahns
f2052f95f8 Deploy 0.8.22 2016-02-22 12:38:21 +01:00
Kevin Jahns
81324dc7d4 Deploy 0.8.21 2016-02-18 16:57:27 +01:00
Kevin Jahns
6599cb20b4 Deploy 0.8.20 2016-02-16 16:08:50 +01:00
Kevin Jahns
74ed9e4107 Deploy 0.8.18 2016-02-15 15:22:51 +01:00
Kevin Jahns
ef6d63c19a Deploy 0.8.17 2016-02-04 23:13:47 +01:00
Kevin Jahns
941dd36e74 Deploy 0.8.16 2016-02-04 23:12:49 +01:00
Kevin Jahns
e74c22f0a9 Deploy 0.8.15 2016-02-04 23:11:07 +01:00
Kevin Jahns
98085b2807 Deploy 0.8.14 2016-02-04 15:26:28 +01:00
Kevin Jahns
e48608a7d4 update ace example 2016-02-04 12:53:27 +01:00
Kevin Jahns
ddbe19d78e Deploy 0.8.13 2016-02-04 12:47:05 +01:00
Kevin Jahns
f9a9edcc26 Deploy 0.8.12 2016-02-04 12:12:53 +01:00
Kevin Jahns
4340f028b5 cleanup 2016-02-04 12:05:47 +01:00
Kevin Jahns
6a4aabe69c Deploy 0.8.11 2016-02-04 10:52:55 +01:00
Kevin Jahns
6904e6018d added ace example 2016-02-03 11:37:10 +01:00
Kevin Jahns
5e295b80d7 Deploy 0.8.9 2016-01-18 16:45:40 +01:00
Kevin Jahns
e58f633115 Deploy 0.8.8 2016-01-18 15:40:31 +01:00
Kevin Jahns
65ea42481e Deploy 0.8.7 2016-01-16 01:45:53 +01:00
Kevin Jahns
a220b06ad9 Deploy 0.8.6 2016-01-16 01:41:55 +01:00
Kevin Jahns
2650338b4b Deploy 0.8.5 2016-01-15 18:09:41 +01:00
Kevin Jahns
919dfb5e16 Deploy 0.8.4 2016-01-15 17:58:01 +01:00
Kevin Jahns
3b8e148d8f Deploy 0.8.3 2016-01-15 03:46:51 +01:00
Kevin Jahns
a77eb39218 Deploy 0.8.2 2016-01-15 03:10:52 +01:00
Kevin Jahns
9902da470b Deploy 0.8.1 2016-01-15 00:03:37 +01:00
Kevin Jahns
0ec83aa431 Deploy 0.8.0 2016-01-15 00:01:56 +01:00
Kevin Jahns
ff006c92d7 Deploy 0.7.6 2016-01-11 15:48:06 +01:00
17 changed files with 1157 additions and 416 deletions

9
.gitignore vendored
View File

@@ -1,8 +1 @@
node_modules
Examples/bower_components
.directory
.codio
.settings
.jshintignore
.jshintrc
.validate.json
bower_components

32
Examples/Ace/index.html Normal file
View File

@@ -0,0 +1,32 @@
<!DOCTYPE html>
<html>
<head>
<style type="text/css" media="screen">
#ace {
position: absolute;
top: 0;
right: 0;
bottom: 0;
left: 0;
}
.inserted {
position:absolute;
z-index:20;
background-color: #FFC107;
}
.deleted {
position:absolute;
z-index:20;
background-color: #FFC107;
}
</style>
</head>
<body>
<div id="ace"></div>
<script src="../bower_components/yjs/y.es6"></script>
<script src="../bower_components/ace-builds/src/ace.js"></script>
<script src="./index.js"></script>
</body>
</html>

25
Examples/Ace/index.js Normal file
View File

@@ -0,0 +1,25 @@
/* global Y, ace */
// initialize a shared object. This function call returns a promise!
Y({
db: {
name: 'memory'
},
connector: {
name: 'websockets-client',
room: 'ace-example'
},
sourceDir: '/bower_components',
share: {
ace: 'Text' // y.share.textarea is of type Y.Text
}
}).then(function (y) {
window.yAce = y
// bind the textarea to a shared text element
var editor = ace.edit('ace')
editor.setTheme('ace/theme/chrome')
editor.getSession().setMode('ace/mode/javascript')
y.share.ace.bindAce(editor)
})

View File

@@ -9,15 +9,13 @@ Y({
connector: {
name: 'websockets-client',
room: 'chat-example'
// debug: true,
// url: 'http://127.0.0.1:2345'
},
sourceDir: '/bower_components',
share: {
chat: 'Array'
}
}).then(function (y) {
window.y = y
window.yChat = y
// This functions inserts a message at the specified position in the DOM
function appendMessage(message, position) {
var p = document.createElement('p')

View File

@@ -8,9 +8,7 @@ Y({
},
connector: {
name: 'websockets-client',
room: 'Puzzle-example2'
// debug: true,
// url: 'http://127.0.0.1:2345'
room: 'Puzzle-example'
},
sourceDir: '/bower_components',
share: {
@@ -20,6 +18,7 @@ Y({
piece4: 'Map'
}
}).then(function (y) {
window.yJigsaw = y
var origin // mouse start position - translation of piece
var drag = d3.behavior.drag()
.on('dragstart', function (params) {

View File

@@ -8,16 +8,15 @@ Y({
},
connector: {
name: 'websockets-client',
room: 'richtext-example18',
debug: true
//url: 'http://127.0.0.1:2345'
room: 'richtext-example'
// url: 'http://127.0.0.1:1234'
},
sourceDir: '/bower_components',
share: {
richtext: 'Richtext' // y.share.richtext is of type Y.Richtext
}
}).then(function (y) {
window.yquill = y
window.yQuill = y
// create quill element
window.quill = new Quill('#editor', {
@@ -30,3 +29,4 @@ Y({
// bind quill to richtext type
y.share.richtext.bind(window.quill)
})

View File

@@ -2,7 +2,7 @@
<html>
<body>
<textarea style="width:80%;" rows=40 id="textfield" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"></textarea>
<script src="../bower_components/yjs/y.js"></script>
<script src="../bower_components/yjs/y.es6"></script>
<script src="./index.js"></script>
</body>
</html>

View File

@@ -7,16 +7,14 @@ Y({
},
connector: {
name: 'websockets-client',
room: 'Textarea-example-dev'
// debug: true
// url: 'http://127.0.0.1:2345'
room: 'Textarea-example'
},
sourceDir: '/bower_components',
share: {
textarea: 'Text' // y.share.textarea is of type Y.Text
}
}).then(function (y) {
window.y = y
window.yTextarea = y
// bind the textarea to a shared text element
y.share.textarea.bind(document.getElementById('textfield'))

8
Examples/Xml/index.html Normal file
View File

@@ -0,0 +1,8 @@
<!DOCTYPE html>
<html>
<body>
<script src="../bower_components/yjs/y.es6"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.0.0-beta1/jquery.min.js"></script>
<script src="./index.js"></script>
</body>
</html>

24
Examples/Xml/index.js Normal file
View File

@@ -0,0 +1,24 @@
/* global Y */
// initialize a shared object. This function call returns a promise!
Y({
db: {
name: 'memory'
},
connector: {
name: 'websockets-client',
// url: 'http://127.0.0.1:1234',
room: 'Xml-example'
},
sourceDir: '/bower_components',
share: {
xml: 'Xml("p")' // y.share.xml is of type Y.Xml with tagname "p"
}
}).then(function (y) {
window.yXml = y
// bind xml type to a dom, and put it in body
y.share.xml.getDom().then(function (dom) {
window.sharedDom = dom
document.body.appendChild(dom)
})
})

View File

@@ -9,7 +9,17 @@
"license": "MIT",
"ignore": [],
"dependencies": {
"yjs": "../",
"y-webrtc": "~0.6.4"
"yjs": "latest",
"y-array": "latest",
"y-map": "latest",
"y-memory": "latest",
"y-richtext": "latest",
"y-webrtc": "latest",
"y-websockets-client": "latest",
"y-text": "latest",
"y-indexeddb": "latest",
"quill": "~0.20.1",
"ace": "~1.2.3",
"ace-builds": "~1.2.3"
}
}

201
README.md
View File

@@ -1,49 +1,55 @@
# ![Yjs](http://y-js.org/images/yjs.png)
Yjs is a framework for optimistic concurrency control and automatic conflict resolution on shared data types. The framework implements a new OT-like concurrency algorithm and provides similar functionality as [ShareJs] and [OpenCoweb]. Yjs was designed to handle concurrent actions on arbitrary complex data types like Text, Json, and XML. We provide a tutorial and some applications for this framework on our [homepage](http://y-js.org/).
Yjs is a framework for optimistic concurrency control and automatic conflict resolution on shared data. The framework provides similar functionality as [ShareJs] and [OpenCoweb], but supports peer-to-peer communication protocols by default. Yjs was designed to handle concurrent actions on arbitrary data like Text, Json, and XML. We also provide support for storing and manipulating your shared data offline. For more information and demo applications visit our [homepage](http://y-js.org/).
**NOTE** This project is currently migrating. So there may exist some information that is not true anymore..
You can create you own shared types easily. Therefore, you can take matters into your own hand by defining the meaning of the shared types and ensure that it is valid, while Yjs ensures data consistency (everyone will eventually end up with the same data). We already provide data types for
You can create you own shared types easily.
Therefore, you can design the sturcture of your custom type,
and ensure data validity, while Yjs ensures data consistency (everyone will eventually end up with the same data).
We already provide abstract data types for
| Name | Description |
|----------|-------------------|
|[map](https://github.com/y-js/y-map) | Add, update, and remove properties of an object. Included in Yjs|
|[array](https://github.com/y-js/y-array) | A shared linked list implementation |
|[selections](https://github.com/y-js/y-selections) | Manages selections on types that use linear structures (e.g. the y-array type). Select a range of elements, and assign meaning to them.|
|[xml](https://github.com/y-js/y-xml) | An implementation of the DOM. You can create a two way binding to Browser DOM objects|
|[text](https://github.com/y-js/y-text) | Collaborate on text. Supports two way binding to textareas, input elements, or HTML elements (e.g. *h1*, or *p*)|
|[richtext](https://github.com/y-js/y-richtext) | Collaborate on rich text. Supports two way binding to several editors|
|[map](https://github.com/y-js/y-map) | A shared Map implementation. Maps from text to any stringify-able object |
|[array](https://github.com/y-js/y-array) | A shared Array implementation |
|[xml](https://github.com/y-js/y-xml) | An implementation of the DOM. You can create a two way binding to Browser DOM objects |
|[text](https://github.com/y-js/y-text) | Collaborate on text. Supports two way binding to textareas, input elements, or HTML elements (e.g. <*h1*>, or <*p*>). Also supports the [Ace Editor](https://ace.c9.io) |
|[richtext](https://github.com/y-js/y-richtext) | Collaborate on rich text. Supports two way binding to the [Quill Rich Text Editor](http://quilljs.com/)|
Unlike other frameworks, Yjs supports P2P message propagation and is not bound to a specific communication protocol. Therefore, Yjs is extremely scalable and can be used in a wide range of application scenarios.
Yjs supports P2P message propagation, and is not bound to a specific communication protocol. Therefore, Yjs is extremely scalable and can be used in a wide range of application scenarios.
We support several communication protocols as so called *Connectors*. You can create your own connector too - read [this wiki page](https://github.com/y-js/yjs/wiki/Custom-Connectors). Currently, we support the following communication protocols:
We support several communication protocols as so called *Connectors*.
You can create your own connector too - read [this wiki page](https://github.com/y-js/yjs/wiki/Custom-Connectors).
Currently, we support the following communication protocols:
|Name | Description |
|----------------|-----------------------------------|
|[xmpp](https://github.com/y-js/y-xmpp) | Propagate updates in a XMPP multi-user-chat room ([XEP-0045](http://xmpp.org/extensions/xep-0045.html))|
|[webrtc](https://github.com/y-js/y-webrtc) | Propagate updates Browser2Browser via WebRTC|
|[websockets](https://github.com/y-js/y-websockets-client) | Exchange updates efficiently in the classical client-server model |
|[test](https://github.com/y-js/y-test) | A Connector for testing purposes. It is designed to simulate delays that happen in worst case scenarios|
You are not limited to use a specific database to store the shared data. We provide the following database adapters:
|Name | Description |
|----------------|-----------------------------------|
|[memory](https://github.com/y-js/y-memory) | In-memory storage. |
|[indexeddb](https://github.com/y-js/y-indexeddb) | Offline storage for the browser |
You can use Yjs client-, and server- side. You can get it as via npm, and bower. We even provide polymer elements for Yjs!
The advantages over similar frameworks are support for
* .. P2P message propagation and arbitrary communication protocols
* .. arbitrary complex data types
* .. offline editing: Changes are stored persistently and only relevant changes are propagated on rejoin
* .. AnyUndo: Undo *any* action that was executed in constant time (coming..)
* .. share any type of data. The types provide a convenient interface
* .. offline support: Changes are stored persistently and only relevant changes are propagated on rejoin
* .. Intention Preservation: When working on Text, the intention of your changes are preserved. This is particularily important when working offline. Every type has a notion on how we define Intention Preservation on it.
## Use it!
You can find a tutorial, and examples on the [website](http://y-js.org). Furthermore, the [github wiki](https://github.com/y-js/yjs/wiki) offers more information about how you can use Yjs in your application.
Either clone this git repository, install it with [bower](http://bower.io/), or install it with [npm](https://www.npmjs.org/package/yjs).
Install yjs and its modules with [bower](http://bower.io/), or with [npm](https://www.npmjs.org/package/yjs).
### Bower
```
bower install y-js/yjs
bower install yjs --save
```
Then you include the libraries directly from the installation folder.
```
@@ -60,69 +66,130 @@ And use it like this with *npm*:
Y = require("yjs");
```
# Y()
In order to create an instance of Y, you need to have a connection object (instance of a Connector). Then, you can create a shared data type like this:
# Text editing example
```
var y = new Y(connector);
Y({
db: {
name: 'memory' // store in memory.
// name: 'indexeddb'
},
connector: {
name: 'websockets-client', // choose the websockets connector
// name: 'webrtc'
// name: 'xmpp'
room: 'Textarea-example-dev'
},
sourceDir: '/bower_components', // location of the y-* modules
share: {
textarea: 'Text' // y.share.textarea is of type Y.Text
}
// types: ['Richtext', 'Array'] // optional list of types you want to import
}).then(function (y) {
// bind the textarea to a shared text element
y.share.textarea.bind(document.getElementById('textfield'))
}
```
# Api
# Y.Map
Yjs includes only one type by default - the Y.Map type. It mimics the behaviour of a javascript Object. You can create, update, and remove properies on the Y.Map type. Furthermore, you can observe changes on this type as you can observe changes on Javascript Objects with [Object.observe](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/observe) - an ECMAScript 7 proposal which is likely to become accepted by the committee. Until then, we have our own implementation.
##### Reference
* Create
### Y(options)
* options.db
* Will be forwarded to the database adapter. Specify the database adaper on `options.db.name`.
* Have a look at the used database adapter repository to see all available options.
* options.connector
* Will be forwarded to the connector adapter. Specify the connector adaper on `options.connector.name`.
* All our connectors implement a `room` property. Clients that specify the same room share the same data.
* All of our connectors specify an `url` property that defines the connection endpoint of the used connector.
* All of our connectors also have a default connection endpoint that you can use for development.
* Have a look at the used connector repository to see all available options.
* options.sourceDir
* Path where all y-* modules are stored.
* Defaults to `/bower_components`
* Not required when running on `nodejs` / `iojs`
* When using browserify you can specify all used modules like this:
```
var map = y.set("new_map", Y.Map).then(function(map){
map // is my map type
});
```
* Every instance of Y is an Y.Map
```
var y = new Y(options);
```
* .get(name)
* Retrieve the value of a property. If the value is a type, `.get(name)` returns a promise
* .set(name, value)
* Set/update a property. `value` may be a primitive type, or a custom type definition (e.g. `Y.Map`)
* .delete(name)
* Delete a property
* .observe(observer)
* The `observer` is called whenever something on this object changes. Throws *add*, *update*, and *delete* events
* .observePath(path, observer)
* `path` is an array of property names. `observer` is called when the property under `path` is set, deleted, or updated
* .unobserve(f)
* Delete an observer
var Y = require('yjs')
// you need to require the db, connector, and *all* types you use!
require('y-memory')(Y)
require('y-webrtc')(Y)
require('y-map')(Y)
// ..
```
* options.share
* Specify on `options.share[arbitraryName]` types that are shared among all users.
* E.g. Specify `options.share[arbitraryName] = 'Array'` to require y-array and create an Y.Array type on `y.share[arbitraryName]`.
* If userA doesn't specify `options.share[arbitraryName]`, it won't be available for userA.
* If userB specifies `options.share[arbitraryName]`, it still won't be available for userA. But all the updates are send from userB to userA.
* In contrast to Y.Map, types on `y.share.*` cannot be overwritten or deleted. Instead, they are merged among all users. This feature is only available on `y.share.*`
* Weird behavior: It is supported that two users specify different types with the same property name.
E.g. userA specifies `options.share.x = 'Array'`, and userB specifies `options.share.x = 'Text'`. But they'll only share data if they specified the same type with the same property name
* options.type
* Array of modules that Yjs needs to require, before instantiating a shared type.
* By default Yjs requires the specified database adapter, the specified connector, and all modules that are used in `options.share.*`
* Put all types here that you intend to use, but are not used in y.share.*
# A note on intention preservation
When users create/update/delete the same property concurrently, only one change will prevail. Changes on different properties do not conflict with each other.
### Instantiated Y object (y)
`Y(options)` returns a promise that is fulfilled when..
# A note on time complexities
* .get(name)
* O(1)
* .set(name, value)
* O(1)
* .delete(name)
* O(1)
* Apply a delete operation from another user
* O(1)
* Apply an update operation from another user (set/update a property)
* Yjs does not transform against operations that do not conflict with each other.
* An operation conflicts with another operation if it changes the same property.
* Overall worst case complexety: O(|conflicts|!)
* All modules are loaded
* The specified database adapter is loaded
* The specified connector is loaded
* All types are included
* The connector is initialized, and a unique user id is set (received from the server)
* Note: When using y-indexeddb, a retrieved user id is stored on `localStorage`
# Status
Yjs is a work in progress. Different versions of the *y-* repositories may not work together. Just drop me a line if you run into troubles.
The promise returns an instance of Y. We denote it with a lower case `y`.
* y.share.*
* Instances of the types you specified on options.share.*
* y.share.* can only be defined once when you instantiate Y!
* y.connector is an instance of Y.AbstractConnector
* y.connector.onUserEvent(function (event) {..})
* Observe user events (event.action is either 'userLeft' or 'userJoined')
* y.connector.whenSynced(listener)
* `listener` is executed when y synced with at least one user.
* `listener` is not called when no other user is in the same room.
* y-websockets-client aways waits to sync with the server
* y.connector.disconnect()
* Force to disconnect this instance from the other instances
* y.connector.reconnect()
* Try to reconnect to the other instances (needs to be supported by the connector)
* Not supported by y-xmpp
* y.destroy()
* Destroy this object.
* Destroys all types (they will throw weird errors if you still use them)
* Disconnects from the other instances (via connector)
* Removes all data from the database
* y.db.stopGarbageCollector()
* Stop the garbage collector. Call y.db.garbageCollect() to continue garbage collection
* y.db.gcTimeout :: Number (defaults to 50000 ms)
* Time interval between two garbage collect cycles
* It is required that all instances exchanged all messages after two garbage collect cycles (after 100000 ms per default)
* y.db.userId :: String
* The used user id for this client. **Never overwrite this**
## Get help
There are some friendly people on [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/y-js/yjs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) who may help you with your problem, and answer your questions.
Please report _any_ issues to the [Github issue page](https://github.com/y-js/yjs/issues)! I try to fix them very soon, if possible.
If you want to see an issue fixed, please subscribe to the thread (or remind me via gitter).
## Changelog
### 1.0.0
This is a complete rewrite of the 0.5 version of Yjs. Since Yjs 1.0 it is possible to work asynchronously on a persistent database, which enables offline support.
### 10.0.0
* Support for more complex types (a type can be a composition of several types)
* Fixes several memory leaks
### 9.0.0
There were several rolling updates from 0.6 to 0.8. We consider Yjs stable since a long time,
and intend to continue stable releases. From this release forward y-* modules will implement peer-dependencies for npm, and dependencies for bower.
Furthermore, incompatible yjs instances will now throw errors when syncing - this feature was influenced by #48. The versioning jump was influenced by react (see [here](https://facebook.github.io/react/blog/2016/02/19/new-versioning-scheme.html))
### 0.6.0
This is a complete rewrite of the 0.5 version of Yjs. Since Yjs 0.6.0 it is possible to work asynchronously on a persistent database, which enables offline support.
* Switched to semver versioning
* Requires a promise implementation in environment (es6 promises suffice, included in all the major browsers). Otherwise you have to include a polyfill
* Y.Object has been renamed to Y.Map

View File

@@ -1,19 +1,21 @@
{
"name": "yjs",
"version": "0.7.6",
"version": "10.0.2",
"homepage": "y-js.org",
"authors": [
"Kevin Jahns <kevin.jahns@rwth-aachen.de>"
],
"description": "A Framework that enables Real-Time collaboration on arbitrary data structures.",
"main": "y.js",
"description": "A Framework for shared editing on any data",
"main": "./y.js",
"keywords": [
"Yjs",
"OT",
"collaboration",
"synchronization",
"sharejs",
"coweb",
"concurrency"
"Collaboration",
"Synchronization",
"ShareJS",
"Coweb",
"Concurrency"
],
"license": "MIT"
"license": "MIT",
"ignore": []
}

1204
y.es6

File diff suppressed because it is too large Load Diff

File diff suppressed because one or more lines are too long

7
y.js

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long