Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
gulf - npm Package Compare versions
Comparing version 4.0.3 to 4.0.4
@@ -425,3 +425,3 @@ /** | ||
| missed.forEach(function(oldSnapshot) { | ||
| fromLink.send('edit', oldSnapshot.edit.pack()) | ||
| fromLink.send('edit', oldSnapshot.edit) | ||
| }) | ||
@@ -428,0 +428,0 @@ } |
| { | ||
| "name": "gulf", | ||
| "version": "4.0.3", | ||
| "version": "4.0.4", | ||
| "description": "transport-agnostic operational transformation control layer", | ||
@@ -5,0 +5,0 @@ "repository": { |
@@ -60,5 +60,5 @@ # Gulf [](https://travis-ci.org/marcelklehr/gulf) | ||
| * [contenteditable](https://github.com/marcelklehr/gulf-contenteditable) | ||
| * [textarea/textinput](https://github.com/marcelklehr/gulf-textarea) | ||
| * [codemirror](https://github.com/marcelklehr/gulf-codemirror) | ||
| * [contenteditable](https://github.com/marcelklehr/gulf-contenteditable) (using DOM OT) | ||
| * [textarea/textinput](https://github.com/marcelklehr/gulf-textarea) (using text OT) | ||
| * [codemirror](https://github.com/marcelklehr/gulf-codemirror) (using text OT) | ||
@@ -71,7 +71,7 @@ ### Above and Beyond | ||
| ## Documents | ||
| A document may contain arbitrary data (as long as you provide an ottype that can handle that kind of data, but we're getting ahead of ourselves). The content of a document is available in `myDocument.content` (which is read-only for you!) and that's basically all a document can do. | ||
| A document may contain arbitrary data. The content of a document is available in `myDocument.content` (which is read-only!). | ||
| Now, how do I change this document if `Document#content` is untouchable? Well, thankfully there's also EditableDocuments. | ||
| Editable documents can be updated via the `update(cs)` method. The `cs` stands for changeset. A changeset contains the changes to a document. (There are many ways you can create such a changeset, right now we use the simple method of imagination: *bling* -- there it is, see it?) | ||
| Editable documents can be updated via the `update(cs)` method. The `cs` is short for changeset. A changeset contains the changes to a document. (There are quite a few ways you can create such a changeset, all specific to the OT implementation you're using, right now we use the simple method of imagination: *bling* -- there it is, see it?) | ||
@@ -81,12 +81,10 @@ Ok, now we update our editable document and we notice that it keeps a record of all revisions -- all documents remember every change ever done. Nice. | ||
| ## Linking documents | ||
| Now, Alice and Bob each have a document, actually it's "the same" document. At least it should be, oh -- wait: Bob has made some changes to his version, and Alice of course couldn't resist to write some introductory paragraph again. | ||
| Now, Alice and Bob each have a document and want to sync them. For this, we need some kind of mediator document that takes care of the syncing process to keep things sane. In gulf this mediator is called the master document. It has the final say in which edit is accepted and how the edits are ordered. | ||
| Now it's not the same document anymore -- but if we connect the two, they'll always be in sync, right? We just need some kind of mediator that takes care of the syncing process to keep things sane (imagine, if David had changed his document, too!). | ||
| Now, somehow Alice and Bob need to link their documents to that master document in order to send it the changes they make. | ||
| This mediator is also in possession of, surprise, a Document. It's doesn't need to be editable, though. Now, somehow Alice and Bob need to link their documents to that master document and send it the changes they make. | ||
| Well, Links we have. If Alice wants to connect to the master document, she creates a master link to it. The master document attaches Alice's link as a slave link. | ||
| Well, Links we have. If Alice wants to connect to the master document, she creates a Link to it and attaches it to her document as a master link. The master document attaches Alice's link as a slave link. | ||
| A document can have many slaves, but only one master link (EditableDocuments have no slave links). | ||
| A document can have many slave links, but only one master link ( EditableDocuments have no slave links, but you can always put another document in front of them). | ||
| Now that we've connected all documents, every time Alice or Bob make a change the edits will just flow to the other documents. | ||
@@ -98,7 +96,11 @@ | ||
| ```js | ||
| masterDoc = new gulf.Document(adapter, ot) | ||
| socket.pipe(masterDoc.slaveLink()).pipe(socket) | ||
| gulf.Document.create(adapter, ot, initialContents, (er, masterDoc) => { | ||
| net.createserver((socket) => { | ||
| socket.pipe(masterDoc.slaveLink()).pipe(socket) // for each socket | ||
| }).listen(1234) | ||
| }) | ||
| ``` | ||
| The master doc has the final say in whether an edit is accepted, and so it always holds what you can consider the actual document contents, the *absolute truth* if you will. Thus you must initialize it with the initial document contents, otherwise no one will know where to start from. | ||
| ```js | ||
@@ -134,3 +136,3 @@ slaveDoc = new gulf.Document(adapter, ot) | ||
| Before anything can happen, the document is initialized wwith `_setContents`. | ||
| Before anything can happen, the editable document is initialized wwith `_setContents`. | ||
@@ -170,2 +172,10 @@ Everytime the document is changed by an incoming edit `_change` is called with the changeset. | ||
| ## Examples | ||
| It's probably easiest to observe gulf in action. So, have a look at these examples. | ||
| * https://gist.github.com/marcelklehr/0430be7e3fb45a83189b -- a small html page with two contenteditables that are synced. | ||
| * https://github.com/marcelklehr/warp -- a complete web server serving a collaborative editor, driven by CKeditor, sockJS and gulf-contenteditable | ||
| **Additions wanted:** If you have the perfect example show-casing gulf or its related libraries leave me a note via email or [the issues](https://github.com/marcelklehr/gulf/issues). | ||
| ## API | ||
@@ -242,4 +252,4 @@ | ||
| #### gulf.Document.load(adapter, ottype, cb) | ||
| Loads a document from the storage. Since there's one instance of a storage adapter per document, you need to pass the information *which* document to load to the adapter instance. `cb` will be called with `(er, doc)`. | ||
| #### gulf.Document.load(adapter, ottype, documentId, cb) | ||
| Loads a document from the storage. `cb` will be called with `(er, doc)`. | ||
@@ -246,0 +256,0 @@ #### gulf.Document#slaveLink(opts:Object) : Link |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by0.37%
103774
- Number of lines in readme file
- increased by2.83%
363
No dependency changes