diff --git a/README.v13.md b/README.v13.md index 3ae9ae1f..77a59ec8 100644 --- a/README.v13.md +++ b/README.v13.md @@ -1,13 +1,13 @@ # ![Yjs](https://user-images.githubusercontent.com/5553757/48975307-61efb100-f06d-11e8-9177-ee895e5916e5.png) -> The shared editing library +> A CRDT framework with a powerful abstraction of shared data -Yjs is a library for automatic conflict resolution on shared state. It implements an [operation-based CRDT](#Yjs-CRDT-Algorithm) and exposes its internal model as shared types. Shared types are common data types like `Map` or `Array` with superpowers: changes are automatically distributed to other peers and merged without merge conflicts. +Yjs is a [CRDT implementation](#Yjs-CRDT-Algorithm) that exposes its internal data structure as *shared types*. Shared types are common data types like `Map` or `Array` with superpowers: changes are automatically distributed to other peers and merged without merge conflicts. -Yjs is **network agnostic** (p2p!), supports many existing **rich text editors**, **offline editing**, **version snapshots**, **shared cursors**, and encodes update messages using **binary protocol encoding**. +Yjs is **network agnostic** (p2p!), supports many existing **rich text editors**, **offline editing**, **version snapshots**, **undo/redo** and **shared cursors**. It scales well with an unlimited number of users and is well suited for even large documents. * Chat: [https://gitter.im/y-js/yjs](https://gitter.im/y-js/yjs) * Demos: [https://github.com/y-js/yjs-demos](https://github.com/y-js/yjs-demos) -* API Docs: [https://yjs.website/](https://yjs.website/) +* Benchmarks: [https://github.com/dmonad/crdt-benchmarks](https://github.com/dmonad/crdt-benchmarks) # Table of Contents @@ -16,18 +16,15 @@ Yjs is **network agnostic** (p2p!), supports many existing **rich text editors** * [Providers](#Providers) * [Getting Started](#Getting-Started) * [API](#API) -* [Transaction](#Transaction) -* [Offline Editing](#Offline-Editing) -* [Awareness](#Awareness) -* [Working with Yjs](#Working-with-Yjs) + * [Shared Types](#Shared-Types) + * [Y.Doc](#Y.Doc) + * [Document Updates](#Document-Updates) + * [Relative Positions](#Relative-Positions) +* [Miscellaneous](#Miscellaneous) * [Typescript Declarations](#Typescript-Declarations) -* [Binary Protocols](#Binary-Protocols) - * [Sync Protocol](#Sync-Protocols) - * [Awareness Protocol](#Awareness-Protocols) - * [Auth Protocol](#Auth-Protocol) * [Yjs CRDT Algorithm](#Yjs-CRDT-Algorithm) * [Evaluation](#Evaluation) - * [Existing shared editing libraries](#Exisisting-Javascript-Products) + * [Existing shared editing libraries](#Exisisting-Javascript-Libraries) * [CRDT Algorithms](#CRDT-Algorithms) * [Comparison of CRDT with OT](#Comparing-CRDT-with-OT) * [Comparison of CRDT Algorithms](#Comparing-CRDT-Algorithms) @@ -52,7 +49,7 @@ This repository contains a collection of shared types that can be observed for c ### Providers -Setting up the communication between clients, managing awareness information, and storing shared data for offline usage is quite a hassle. **Providers** manage all that for you and are a good off-the-shelf solution. +Setting up the communication between clients, managing awareness information, and storing shared data for offline usage is quite a hassle. **Providers** manage all that for you and are the perfect starting point for your collaborative app.
y-websocket
@@ -60,15 +57,15 @@ Setting up the communication between clients, managing awareness information, an
y-mesh
[WIP] Creates a connected graph of webrtc connections with a high strength. It requires a signalling server that connects a client to the first peer. But after that the network manages itself. It is well suited for large and small networks.
y-dat
-
[WIP] Writes updates effinciently in the dat network using multifeed. Each client has an append-only log of CRDT local updates (hypercore). Multifeed manages and sync hypercores and y-dat listens to changes and applies them to the Yjs document.
+
[WIP] Write document updates effinciently to the dat network using multifeed. Each client has an append-only log of CRDT local updates (hypercore). Multifeed manages and sync hypercores and y-dat listens to changes and applies them to the Yjs document.
## Getting Started -Install Yjs and a provider with your favorite package manager. In this section we are going to bind a YText to a DOM textarea. +Install Yjs and a provider with your favorite package manager. ```sh -npm i yjs@13.0.0-80 y-websocket@1.0.0-1 y-textarea +npm i yjs@13.0.0-81 y-websocket@1.0.0-2 y-textarea ``` **Start the y-websocket server** @@ -77,7 +74,9 @@ npm i yjs@13.0.0-80 y-websocket@1.0.0-1 y-textarea PORT=1234 node ./node_modules/y-websocket/bin/server.js ``` -**Textarea Binding Example** +**Example: Textarea Binding** + +This is a complete example on how to create a connection to a [y-websocket](https://github.com/y-js/y-websocket) server instance, sync the shared document to all clients in a *room*, and bind a Y.Text type to a dom textarea. All changes to the textarea are automatically shared with everyone in the same room. ```js import * as Y from 'yjs' @@ -85,15 +84,39 @@ import { WebsocketProvider } from 'y-websocket' import { TextareaBinding } from 'y-textarea' const provider = new WebsocketProvider('http://localhost:1234') -const sharedDocument = provider.get('my-favourites') +const doc = provider.get('roomname') // Define a shared type on the document. -const ytext = sharedDocument.getText('my resume') +const ytext = doc.getText('my resume') -// bind to a textarea +// use data bindings to bind types to editors const binding = new TextareaBinding(ytext, document.querySelector('textarea')) ``` +**Example: Observe types** + +```js +const yarray = doc.getArray('my-array') +yarray.observe(event => { + console.log('yarray was modified') +}) +// every time a local or remote client modifies yarray, the observer is called +yarray.insert(0, ['val']) // => "yarray was modified" +``` + +**Example: Nest types** + +Remember, shared types are just plain old data types. The only limitation is that a shared type must exist only once in the shared document. + +```js +const ymap = doc.getMap('map') +const foodArray = new Y.Array() +foodArray.insert(0, ['apple', 'banana']) +ymap.set('food', foodArray) +ymap.get('food') === foodArray // => true +ymap.set('fruit', foodArray) // => Error! foodArray is already defined on the shared document +``` + Now you understand how types are defined on a shared document. Next you can jump to the [demo repository](https://github.com/y-js/yjs-demos) or continue reading the API docs. ## API @@ -102,6 +125,8 @@ Now you understand how types are defined on a shared document. Next you can jump import * as Y from 'yjs' ``` +### Shared Types +
Y.Array
@@ -110,11 +135,11 @@ import * as Y from 'yjs' 

const yarray = new Y.Array()
- insert(index:number, content:Array<object|string|number|Y.Type>) + insert(index:number, content:Array<object|string|number|Uint8Array|Y.Type>)
Insert content at index. Note that content is an array of elements. I.e. array.insert(0, [1] splices the list and inserts 1 at position 0.
- push(Array<Object|Array|string|number|Y.Type>) + push(Array<Object|Array|string|number|Uint8Array|Y.Type>)
delete(index:number, length:number)
@@ -124,7 +149,7 @@ import * as Y from 'yjs'
map(function(T, number, YArray):M):Array<M>
- toArray():Array<Object|Array|string|number|Y.Type> + toArray():Array<Object|Array|string|number|Uint8Array|Y.Type>
Copies the content of this YArray to a new Array.
toJSON():Array<Object|Array|string|number>
Copies the content of this YArray to a new Array. It transforms all child types to JSON using their toJSON method.
@@ -159,9 +184,9 @@ import * as Y from 'yjs' 

const ymap = new Y.Map()
- get(key:string):object|string|number|Y.Type + get(key:string):object|string|number|Uint8Array|Y.Type
- set(key:string, value:object|string|number|Y.Type) + set(key:string, value:object|string|number|Uint8Array|Y.Type)
delete(key:string)
@@ -350,38 +375,148 @@ import * as Y from 'yjs'
-### Custom Types +### Y.Doc -## Bindings +```js +const doc = new Y.Doc() +``` -## Transaction +
+ clientID +
A unique id that identifies this client. (readonly)
+ transact(function(Transaction):void [, origin:any]) +
Every change on the shared document happens in a transaction. Observer calls and the update event are called after each transaction. You should bundle changes into a single transaction to reduce the amount of event calls. I.e. doc.transact(() => { yarray.insert(..); ymap.set(..) }) triggers a single change event.
You can specify an optional origin parameter that is stored on transaction.origin and on('update', (update, origin) => ..).
+ get(string, Y.[TypeClass]):[Type] +
Define a shared type.
+ getArray(string):Y.Array +
Define a shared Y.Array type. Is equivalent to y.get(string, Y.Array).
+ getMap(string):Y.Map +
Define a shared Y.Map type. Is equivalent to y.get(string, Y.Map).
+ getXmlFragment(string):Y.XmlFragment +
Define a shared Y.XmlFragment type. Is equivalent to y.get(string, Y.XmlFragment).
+ on(string, function) +
Register an event listener on the shared type
+ off(string, function) +
Unregister an event listener from the shared type
+
-## Binary Encoding Protocols -### Sync Protocol +#### Y.Doc Events +
+ on('update', function(updateMessage:Uint8Array, origin:any, Y.Doc):void) +
Listen to document updates. Document updates must be transmitted to all other peers. You can apply document updates in any order and multiple times.
+ on('beforeTransaction', function(Y.Transaction, Y.Doc):void) +
Emitted before each transaction.
+ on('afterTransaction', function(Y.Transaction, Y.Doc):void) +
Emitted after each transaction.
+
-Sync steps +### Document Updates -### Awareness Protocol +Changes on the shared document are encoded into *document updates*. Document updates are *commutative* and *idempotent*. This means that they can be applied in any order and multiple times. -### Auth Protocol +**Example: Listen to update events and apply them on remote client** +```js +const doc1 = new Y.Doc() +const doc2 = new Y.Doc() -## Offline Editing +doc1.on('update', update => { + Y.applyUpdate(doc2, update) +}) -It is trivial with Yjs to persist the local state to indexeddb, so it is always available when working offline. But there are two non-trivial questions that need to answered when implementing a professional offline editing app: +doc2.on('update', update => { + Y.applyUpdate(doc1, update) +}) -1. How does a client sync down all rooms that were modified while offline? -2. How does a client sync up all rooms that were modified while offline? +// All changes are also applied to the other document +doc1.getArray('myarray').insert(0, ['Hello doc2, you got this?']) +doc2.getArray('myarray').get(0) // => 'Hello doc2, you got this?' +``` -Assuming 5000 documents are stored on each client for offline usage. How do we sync up/down each of those documents after a client comes online? It would be inefficient to sync each of those rooms separately. The only provider that currently supports syncing many rooms efficiently is Ydb, because its database layer is optimized to sync many rooms with each client. +Yjs internally maintains a [State Vector](#State-Vector) that denotes the next expected clock from each client. In a different interpretation it holds the number of structs created by each client. When two clients sync, you can either exchange the complete document structure or only the differences by sending the state vector to compute the differences. -If you do not care about 1. and 2. you can use `/persistences/indexeddb.js` to mirror the local state to indexeddb. +**Example: Sync two clients by exchanging the complete document structure** -## Working with Yjs +```js +const state1 = Y.encodeStateAsUpdate(ydoc1) +const state2 = Y.encodeStateAsUpdate(ydoc2) +Y.applyUpdate(ydoc1, state2) +Y.applyUpdate(ydoc2, state1) +``` + +**Example: Sync two clients by computing the differences** + +This example shows how to sync two clients with the minimal amount of exchanged data by computing only the differences using the state vector of the remote client. Syncing clients using the state vector requires another roundtrip, but can safe a lot of bandwidth. + +```js +const stateVector1 = Y.encodeDocumentStateVector(ydoc1) +const stateVector2 = Y.encodeDocumentStateVector(ydoc2) +const diff1 = Y.encodeStateAsUpdate(ydoc1, stateVector2) +const diff2 = Y.encodeStateAsUpdate(ydoc2, stateVector1) +Y.applyUpdate(ydoc1, diff2) +Y.applyUpdate(ydoc2, diff1) +``` + +
+ Y.applyUpdate(Y.Doc, update:Uint8Array, [transactionOrigin:any]) +
Apply a document update on the shared document. Optionally you can specify transactionOrigin that will be stored on transaction.origin and ydoc.on('update', (update, origin) => ..).
+ Y.encodeStateAsUpdate(Y.Doc, [encodedTargetStateVector:Uint8Array]):Uint8Array +
Encode the document state as a single update message that can be applied on the remote document. Optionally specify the target state vector to only write the differences to the update message.
+ Y.encodeDocumentStateVector(Y.Doc):Uint8Array +
Computes the state vector and encodes it into an Uint8Array.
+
+ +### Relative Positions +> This API is not stable yet + +This feature is intended for managing selections / cursors. When working with other users that manipulate the shared document, you can't trust that an index position (an integer) will stay at the intended location. A *relative position* is fixated to an element in the shared document and is not affected by remote changes. I.e. given the document `"a|c"`, the relative position is attached to `c`. When a remote user modifies the document by inserting a character before the cursor, the cursor will stay attached to the character `c`. `insert(1, 'x')("a|c") = "ax|c"`. When the *relative position* is set to the end of the document, it will stay attached to the end of the document. + +**Example: Transform to RelativePosition and back** +```js +const relPos = Y.createRelativePositionFromTypeIndex(ytext, 2) +const pos = Y.createAbsolutePositionFromRelativePosition(relPos, doc) +pos.type === ytext // => true +pos.index === 2 // => true +``` + +**Example: Send relative position to remote client (json)** +```js +const relPos = Y.createRelativePositionFromTypeIndex(ytext, 2) +const encodedRelPos = JSON.stringify(relPos) +// send encodedRelPos to remote client.. +const parsedRelPos = JSON.parse(encodedRelPos) +const pos = Y.createAbsolutePositionFromRelativePosition(parsedRelPos, remoteDoc) +pos.type === remoteytext // => true +pos.index === 2 // => true +``` + +**Example: Send relative position to remote client (Uint8Array)** +```js +const relPos = Y.createRelativePositionFromTypeIndex(ytext, 2) +const encodedRelPos = Y.encodeRelativePosition(relPos) +// send encodedRelPos to remote client.. +const parsedRelPos = Y.decodeRelativePosition(encodedRelPos) +const pos = Y.createAbsolutePositionFromRelativePosition(parsedRelPos, remoteDoc) +pos.type === remoteytext // => true +pos.index === 2 // => true +``` + +
+ Y.createRelativePositionFromTypeIndex(Uint8Array|Y.Type, number) +
+ Y.createAbsolutePositionFromRelativePosition(RelativePosition, Y.Doc) +
+ Y.encodeRelativePosition(RelativePosition):Uint8Array +
+ Y.decodeRelativePosition(Uint8Array):RelativePosition +
+
+ +## Miscellaneous ### Typescript Declarations -Until [this](https://github.com/Microsoft/TypeScript/issues/7546) is fixed, the only way to get type declarations is by adding Yjs to the list of checked files: +Yjs has type descriptions. But until [this ticket](https://github.com/Microsoft/TypeScript/issues/7546) is fixed, this is how you can make use of Yjs type declarations. ```json { @@ -395,10 +530,26 @@ Until [this](https://github.com/Microsoft/TypeScript/issues/7546) is fixed, the ## Yjs CRDT Algorithm +*Conflict-free replicated data types* (CRDT) for collaborative editing are an alternative approach to *operational transformation* (OT). A very simple differenciation between the two approaches is that OT attempts to transform index positions to ensure convergence (all clients end up with the same content), while CRDTs use models that usually do not involve index transformations, like linked lists. OT is currently the de-facto standard for shared editing on text. OT approaches that support shared editing without a central source of truth (a central server) require too much bookkeeping to be viable in practice. CRDTs are better suited for distributed systems, provide additional guarantees that the document can be synced with remote clients, and do not require a central source of truth / central source of failure. + +Yjs implements a modified version of the algorithm described in [this paper](https://www.researchgate.net/publication/310212186_Near_Real-Time_Peer-to-Peer_Shared_Editing_on_Extensible_Data_Types). I will eventually publish a paper that describes the new approach. Note: Since operations make up the document structure, we prefer the term *struct* now. + +CRDTs suitable for shared text editing suffer from the fact that they only grow in size. There are CRDTs that do not grow in size, but they do not have the characteristics that are benificial for shared text editing (like intention preservation). Yjs implements many improvements to the original algorithm that diminish the trade-off that the document only grows in size. We can't garbage collect deleted structs (tombstones) while ensuring a unique order of the structs. But we can 1. merge preceeding structs into a single struct to reduce the amount of meta information, 2. we can delete content from the struct if it is deleted, and 3. we can garbage collect tombstones if we don't care about the order of the structs anymore (e.g. if the parent was deleted). + +**Examples:** +1. If a user inserts elements in sequence, the struct will be merged into a single struct. E.g. `array.insert(0, ['a']), array.insert(0, ['b']);` is first represented as two structs (`[{id: {client, clock: 0}, content: 'a'}, {id: {client, clock: 1}, content: 'b'}`) and then merged into a single struct: `[{id: {client, clock: 0}, content: 'ab'}]`. +2. When a struct that contains content (e.g. `ItemString`) is deleted, the struct will be replaced with an `ItemDeleted` that does not contain content anymore. +3. When a type is deleted, all child elements are transformed to `GC` structs. A `GC` struct only denotes the existence of a struct and that it is deleted. `GC` structs can always be merged with other `GC` structs if the id's are adjacent. + +Especially when working on structured content (e.g. shared editing on ProseMirror), these improvements yield very good results when [benchmarking](#Benchmarks) random document edits. In practice they show even better results, because users usually edit text in sequence, resulting in structs that can easily be merged. The benchmarks showt that even in the worst case scenario that a user edits text from right to left, Yjs achieves good performance even for huge documents. + +#### State Vector +Yjs has the ability to exchange only the differences when syncing two clients. We use lamport timestamps to identify structs and to track in which order a client created them. Each struct has an `struct.id = { client: number, clock: number}` that uniquely identifies a struct. We define the next expected `clock` by each client as the *state vector*. This data structure is similar to the [version vectors](https://en.wikipedia.org/wiki/Version_vector) data structure. But we use state vectors only to describe the state of the local document, so we can compute the missing struct of the remote client. We do not use it to track causality. + ## License and Author Yjs and all related projects are [**MIT licensed**](./LICENSE). -Yjs is based on the research I did as a student at the [RWTH i5](http://dbis.rwth-aachen.de/). Now I am working on Yjs in my spare time. +Yjs is based on my research as a student at the [RWTH i5](http://dbis.rwth-aachen.de/). Now I am working on Yjs in my spare time. -Support me on [Patreon](https://www.patreon.com/dmonad) to fund this project or hire [me](https://github.com/dmonad) for professional support. +Fund this project by donating on [Patreon](https://www.patreon.com/dmonad) or hiring [me](https://github.com/dmonad) for professional support. diff --git a/examples/prosemirror-history.js b/examples/prosemirror-history.js index d84f3fbf..48a45cf7 100644 --- a/examples/prosemirror-history.js +++ b/examples/prosemirror-history.js @@ -154,6 +154,6 @@ class NoteHistoryPlugin { const encoder = encoding.createEncoder() historyProtocol.writeHistorySnapshot(encoder, y, updatedUserMap) encoding.writeUint32(encoder, Math.floor(Date.now() / 1000)) - history.push([encoding.toBuffer(encoder)]) + history.push([encoding.toUint8Array(encoder)]) } } diff --git a/package-lock.json b/package-lock.json index 06a53285..ee3bdcca 100644 --- a/package-lock.json +++ b/package-lock.json @@ -3036,9 +3036,9 @@ } }, "lib0": { - "version": "0.0.2", - "resolved": "https://registry.npmjs.org/lib0/-/lib0-0.0.2.tgz", - "integrity": "sha512-7bJgV2emHGRO5kpj66Gdc9SQKVfhDBLx0UIS/aU5P8R0179nRFHKDTYGvLlNloWbeUUARlqk3ndFIO4JbUy7Sw==" + "version": "0.0.4", + "resolved": "https://registry.npmjs.org/lib0/-/lib0-0.0.4.tgz", + "integrity": "sha512-osSGIxFM0mUuVAclVOQAio4lq0YYk1xFfj6J+1i3u5az8rXAQKDil2skA19aiiG0sfAdasOtr8Mk+9Mrw10cfQ==" }, "live-server": { "version": "1.2.1", @@ -5579,10 +5579,13 @@ "dev": true }, "y-protocols": { - "version": "0.0.3", - "resolved": "https://registry.npmjs.org/y-protocols/-/y-protocols-0.0.3.tgz", - "integrity": "sha512-b6yUR4KuRN9ehf2b0/YyaxxO2bxk7ti5DDTg5Jm/FEtPf0Vk6s4ez5wIhkV1nA7bloz/NDmVpoCDPFX1zZORhg==", - "dev": true + "version": "0.0.4", + "resolved": "https://registry.npmjs.org/y-protocols/-/y-protocols-0.0.4.tgz", + "integrity": "sha512-a7F8t16y6rVPYGvwsbfeN5EauHFBo+SIsYadvaONdp6jCyhcKokDK8u30BQOJCOxwd1FkuAhMs14m6CtJbfRqg==", + "dev": true, + "requires": { + "lib0": "0.0.4" + } }, "yallist": { "version": "2.1.2", diff --git a/package.json b/package.json index 6b70b4d3..a574d425 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,7 @@ "lint": "standard && tsc", "docs": "rm -rf docs; jsdoc --configure ./.jsdoc.json --verbose --readme ./README.v13.md --package ./package.json || true", "serve-docs": "npm run docs && serve ./docs/", - "preversion": "PRODUCTION=1 npm run dist && node ./dist/tests.js --repitition-time 1000", + "preversion": "PRODUCTION=1 npm run dist && npm run docs && node ./dist/tests.js --repitition-time 1000", "postversion": "git push && git push --tags", "debug": "concurrently 'live-server --port=3443 --entry-file=test.html' 'npm run watch'", "trace-deopt": "clear && rollup -c && node --trace-deopt dist/test.js", @@ -54,10 +54,10 @@ }, "homepage": "http://y-js.org", "dependencies": { - "lib0": "0.0.2" + "lib0": "0.0.4" }, "devDependencies": { - "y-protocols": "0.0.3", + "y-protocols": "0.0.4", "codemirror": "^5.42.0", "concurrently": "^3.6.1", "jsdoc": "^3.5.5", diff --git a/src/index.js b/src/index.js index 9f2d3e38..2a4fa55a 100644 --- a/src/index.js +++ b/src/index.js @@ -1,6 +1,6 @@ export { - Y, + Doc, Transaction, YArray as Array, YMap as Map, @@ -24,25 +24,23 @@ export { ItemString, ItemType, AbstractType, - compareCursors, - Cursor, - createCursorFromTypeOffset, - createCursorFromJSON, - createAbsolutePositionFromCursor, - writeCursor, - readCursor, + RelativePosition, + createRelativePositionFromTypeIndex, + createRelativePositionFromJSON, + createAbsolutePositionFromRelativePosition, + compareRelativePositions, + writeRelativePosition, + readRelativePosition, ID, createID, compareIDs, getState, - getStates, - readStatesAsMap, - writeStates, - writeModel, - readModel, Snapshot, findRootTypeKey, - typeArrayToArraySnapshot, + typeListToArraySnapshot, typeMapGetSnapshot, - iterateDeletedStructs + iterateDeletedStructs, + applyUpdate, + encodeStateAsUpdate, + encodeDocumentStateVector } from './internals.js' diff --git a/src/internals.js b/src/internals.js index 56eb25e1..ed0cced1 100644 --- a/src/internals.js +++ b/src/internals.js @@ -2,12 +2,12 @@ export * from './utils/DeleteSet.js' export * from './utils/EventHandler.js' export * from './utils/ID.js' export * from './utils/isParentOf.js' -export * from './utils/cursor.js' +export * from './utils/RelativePosition.js' export * from './utils/Snapshot.js' export * from './utils/StructStore.js' export * from './utils/Transaction.js' // export * from './utils/UndoManager.js' -export * from './utils/Y.js' +export * from './utils/Doc.js' export * from './utils/YEvent.js' export * from './types/AbstractType.js' diff --git a/src/structs/AbstractItem.js b/src/structs/AbstractItem.js index a27b0de7..16a3d8ea 100644 --- a/src/structs/AbstractItem.js +++ b/src/structs/AbstractItem.js @@ -17,7 +17,7 @@ import { getItemType, getItemCleanEnd, getItemCleanStart, - YEvent, StructStore, ID, AbstractType, Y, Transaction // eslint-disable-line + YEvent, StructStore, ID, AbstractType, Transaction // eslint-disable-line } from '../internals.js' import * as error from 'lib0/error.js' @@ -153,7 +153,7 @@ export class AbstractItem extends AbstractStruct { * @private */ integrate (transaction) { - const store = transaction.y.store + const store = transaction.doc.store const id = this.id const parent = this.parent const parentSub = this.parentSub @@ -415,23 +415,19 @@ export class AbstractItem extends AbstractStruct { } /** - * @param {Transaction} transaction * @param {StructStore} store * * @private */ - gcChildren (transaction, store) { } + gcChildren (store) { } /** - * @todo remove transaction param - * - * @param {Transaction} transaction * @param {StructStore} store * @param {boolean} parentGCd * * @private */ - gc (transaction, store, parentGCd) { + gc (store, parentGCd) { if (!this.deleted) { throw error.unexpectedCase() } @@ -619,12 +615,16 @@ export const computeItemParams = (transaction, store, leftid, rightid, parentid, case GC: break default: + // Edge case: toStruct is called with an offset > 0. In this case left is defined. + // Depending in which order structs arrive, left may be GC'd and the parent not + // deleted. This is why we check if left is GC'd. Strictly we probably don't have + // to check if right is GC'd, but we will in case we run into future issues if (!parentItem.deleted && (left === null || left.constructor !== GC) && (right === null || right.constructor !== GC)) { parent = parentItem.type } } } else if (parentYKey !== null) { - parent = transaction.y.get(parentYKey) + parent = transaction.doc.get(parentYKey) } else if (left !== null) { if (left.constructor !== GC) { parent = left.parent diff --git a/src/structs/AbstractStruct.js b/src/structs/AbstractStruct.js index 2b576d85..3572b44d 100644 --- a/src/structs/AbstractStruct.js +++ b/src/structs/AbstractStruct.js @@ -1,6 +1,6 @@ import { - Y, StructStore, ID, Transaction // eslint-disable-line + StructStore, ID, Transaction // eslint-disable-line } from '../internals.js' import * as encoding from 'lib0/encoding.js' // eslint-disable-line diff --git a/src/structs/GC.js b/src/structs/GC.js index 4431dc53..a35a8334 100644 --- a/src/structs/GC.js +++ b/src/structs/GC.js @@ -4,7 +4,7 @@ import { AbstractStruct, createID, addStruct, - Y, StructStore, Transaction, ID // eslint-disable-line + StructStore, Transaction, ID // eslint-disable-line } from '../internals.js' import * as decoding from 'lib0/decoding.js' @@ -48,7 +48,7 @@ export class GC extends AbstractStruct { * @param {Transaction} transaction */ integrate (transaction) { - addStruct(transaction.y.store, this) + addStruct(transaction.doc.store, this) } /** diff --git a/src/structs/ItemBinary.js b/src/structs/ItemBinary.js index 917db5c4..3640d9b7 100644 --- a/src/structs/ItemBinary.js +++ b/src/structs/ItemBinary.js @@ -9,6 +9,7 @@ import { import * as encoding from 'lib0/encoding.js' import * as decoding from 'lib0/decoding.js' +import * as buffer from 'lib0/buffer.js' /** * @private @@ -27,7 +28,7 @@ export class ItemBinary extends AbstractItem { * @param {ID | null} rightOrigin * @param {AbstractType} parent * @param {string | null} parentSub - * @param {ArrayBuffer} content + * @param {Uint8Array} content */ constructor (id, left, origin, right, rightOrigin, parent, parentSub, content) { super(id, left, origin, right, rightOrigin, parent, parentSub) @@ -54,7 +55,7 @@ export class ItemBinary extends AbstractItem { */ write (encoder, offset) { super.write(encoder, offset, structBinaryRefNumber) - encoding.writePayload(encoder, this.content) + encoding.writeVarUint8Array(encoder, this.content) } } @@ -70,9 +71,9 @@ export class ItemBinaryRef extends AbstractItemRef { constructor (decoder, id, info) { super(decoder, id, info) /** - * @type {ArrayBuffer} + * @type {Uint8Array} */ - this.content = decoding.readPayload(decoder) + this.content = buffer.copyUint8Array(decoding.readVarUint8Array(decoder)) } /** * @param {Transaction} transaction diff --git a/src/structs/ItemDeleted.js b/src/structs/ItemDeleted.js index c2f803e8..71497137 100644 --- a/src/structs/ItemDeleted.js +++ b/src/structs/ItemDeleted.js @@ -8,7 +8,7 @@ import { splitItem, addToDeleteSet, mergeItemWith, - Y, StructStore, Transaction, ID, AbstractType // eslint-disable-line + StructStore, Transaction, ID, AbstractType // eslint-disable-line } from '../internals.js' import * as encoding from 'lib0/encoding.js' @@ -87,15 +87,14 @@ export class ItemDeleted extends AbstractItem { } /** - * @param {Transaction} transaction * @param {StructStore} store * @param {boolean} parentGCd * * @private */ - gc (transaction, store, parentGCd) { + gc (store, parentGCd) { if (parentGCd) { - super.gc(transaction, store, parentGCd) + super.gc(store, parentGCd) } } /** diff --git a/src/structs/ItemEmbed.js b/src/structs/ItemEmbed.js index a317dc4f..e30fb426 100644 --- a/src/structs/ItemEmbed.js +++ b/src/structs/ItemEmbed.js @@ -67,7 +67,7 @@ export class ItemEmbedRef extends AbstractItemRef { constructor (decoder, id, info) { super(decoder, id, info) /** - * @type {ArrayBuffer} + * @type {Object} */ this.embed = JSON.parse(decoding.readVarString(decoder)) } diff --git a/src/structs/ItemJSON.js b/src/structs/ItemJSON.js index 1b69a90e..837ff401 100644 --- a/src/structs/ItemJSON.js +++ b/src/structs/ItemJSON.js @@ -7,7 +7,7 @@ import { changeItemRefOffset, GC, mergeItemWith, - Transaction, StructStore, Y, ID, AbstractType // eslint-disable-line + Transaction, StructStore, ID, AbstractType // eslint-disable-line } from '../internals.js' import * as encoding from 'lib0/encoding.js' diff --git a/src/structs/ItemString.js b/src/structs/ItemString.js index 8409c9f7..bbaee867 100644 --- a/src/structs/ItemString.js +++ b/src/structs/ItemString.js @@ -7,7 +7,7 @@ import { changeItemRefOffset, GC, mergeItemWith, - Transaction, StructStore, Y, ID, AbstractType // eslint-disable-line + Transaction, StructStore, ID, AbstractType // eslint-disable-line } from '../internals.js' import * as encoding from 'lib0/encoding.js' diff --git a/src/structs/ItemType.js b/src/structs/ItemType.js index bdf648b0..61ecf5df 100644 --- a/src/structs/ItemType.js +++ b/src/structs/ItemType.js @@ -10,7 +10,7 @@ import { readYXmlFragment, readYXmlHook, readYXmlText, - StructStore, Y, GC, Transaction, ID, AbstractType // eslint-disable-line + StructStore, GC, Transaction, ID, AbstractType // eslint-disable-line } from '../internals.js' import * as encoding from 'lib0/encoding.js' // eslint-disable-line @@ -83,7 +83,7 @@ export class ItemType extends AbstractItem { */ integrate (transaction) { super.integrate(transaction) - this.type._integrate(transaction.y, this) + this.type._integrate(transaction.doc, this) } /** * @param {encoding.Encoder} encoder @@ -129,19 +129,18 @@ export class ItemType extends AbstractItem { } /** - * @param {Transaction} transaction * @param {StructStore} store */ - gcChildren (transaction, store) { + gcChildren (store) { let item = this.type._start while (item !== null) { - item.gc(transaction, store, true) + item.gc(store, true) item = item.right } this.type._start = null this.type._map.forEach(item => { while (item !== null) { - item.gc(transaction, store, true) + item.gc(store, true) // @ts-ignore item = item.left } @@ -150,13 +149,12 @@ export class ItemType extends AbstractItem { } /** - * @param {Transaction} transaction * @param {StructStore} store * @param {boolean} parentGCd */ - gc (transaction, store, parentGCd) { - this.gcChildren(transaction, store) - super.gc(transaction, store, parentGCd) + gc (store, parentGCd) { + this.gcChildren(store) + super.gc(store, parentGCd) } } diff --git a/src/types/AbstractType.js b/src/types/AbstractType.js index ab9bd7c6..ae3f1e33 100644 --- a/src/types/AbstractType.js +++ b/src/types/AbstractType.js @@ -11,7 +11,7 @@ import { ItemBinary, createID, getItemCleanStart, - Y, Snapshot, Transaction, EventHandler, YEvent, AbstractItem, // eslint-disable-line + Doc, Snapshot, Transaction, EventHandler, YEvent, AbstractItem, // eslint-disable-line } from '../internals.js' import * as map from 'lib0/map.js' @@ -64,9 +64,9 @@ export class AbstractType { this._start = null /** * @private - * @type {Y|null} + * @type {Doc|null} */ - this._y = null + this.doc = null this._length = 0 /** * Event handlers @@ -87,12 +87,12 @@ export class AbstractType { * * This type is sent to other client * * Observer functions are fired * - * @param {Y} y The Yjs instance + * @param {Doc} y The Yjs instance * @param {ItemType|null} item * @private */ _integrate (y, item) { - this._y = y + this.doc = y this._item = item } @@ -182,7 +182,7 @@ export class AbstractType { * @private * @function */ -export const typeArrayToArray = type => { +export const typeListToArray = type => { const cs = [] let n = type._start while (n !== null) { @@ -205,7 +205,7 @@ export const typeArrayToArray = type => { * @private * @function */ -export const typeArrayToArraySnapshot = (type, snapshot) => { +export const typeListToArraySnapshot = (type, snapshot) => { const cs = [] let n = type._start while (n !== null) { @@ -229,7 +229,7 @@ export const typeArrayToArraySnapshot = (type, snapshot) => { * @private * @function */ -export const typeArrayForEach = (type, f) => { +export const typeListForEach = (type, f) => { let index = 0 let n = type._start while (n !== null) { @@ -252,12 +252,12 @@ export const typeArrayForEach = (type, f) => { * @private * @function */ -export const typeArrayMap = (type, f) => { +export const typeListMap = (type, f) => { /** * @type {Array} */ const result = [] - typeArrayForEach(type, (c, i) => { + typeListForEach(type, (c, i) => { result.push(f(c, i, type)) }) return result @@ -270,7 +270,7 @@ export const typeArrayMap = (type, f) => { * @private * @function */ -export const typeArrayCreateIterator = type => { +export const typeListCreateIterator = type => { let n = type._start /** * @type {Array|null} @@ -326,7 +326,7 @@ export const typeArrayCreateIterator = type => { * @private * @function */ -export const typeArrayForEachSnapshot = (type, f, snapshot) => { +export const typeListForEachSnapshot = (type, f, snapshot) => { let index = 0 let n = type._start while (n !== null) { @@ -348,7 +348,7 @@ export const typeArrayForEachSnapshot = (type, f, snapshot) => { * @private * @function */ -export const typeArrayGet = (type, index) => { +export const typeListGet = (type, index) => { for (let n = type._start; n !== null; n = n.right) { if (!n.deleted && n.countable) { if (index < n.length) { @@ -363,12 +363,12 @@ export const typeArrayGet = (type, index) => { * @param {Transaction} transaction * @param {AbstractType} parent * @param {AbstractItem?} referenceItem - * @param {Array|Array|number|string|ArrayBuffer>} content + * @param {Array|Array|number|string|Uint8Array>} content * * @private * @function */ -export const typeArrayInsertGenericsAfter = (transaction, parent, referenceItem, content) => { +export const typeListInsertGenericsAfter = (transaction, parent, referenceItem, content) => { let left = referenceItem const right = referenceItem === null ? parent._start : referenceItem.right /** @@ -393,10 +393,9 @@ export const typeArrayInsertGenericsAfter = (transaction, parent, referenceItem, default: packJsonContent() switch (c.constructor) { + case Uint8Array: case ArrayBuffer: - // @ts-ignore c is definitely an ArrayBuffer - left = new ItemBinary(nextID(transaction), left, left === null ? null : left.lastId, right, right === null ? null : right.id, parent, null, c) - // @ts-ignore + left = new ItemBinary(nextID(transaction), left, left === null ? null : left.lastId, right, right === null ? null : right.id, parent, null, new Uint8Array(/** @type {Uint8Array} */ (c))) left.integrate(transaction) break default: @@ -416,14 +415,14 @@ export const typeArrayInsertGenericsAfter = (transaction, parent, referenceItem, * @param {Transaction} transaction * @param {AbstractType} parent * @param {number} index - * @param {Array|Array|number|string|ArrayBuffer>} content + * @param {Array|Array|number|string|Uint8Array>} content * * @private * @function */ -export const typeArrayInsertGenerics = (transaction, parent, index, content) => { +export const typeListInsertGenerics = (transaction, parent, index, content) => { if (index === 0) { - return typeArrayInsertGenericsAfter(transaction, parent, null, content) + return typeListInsertGenericsAfter(transaction, parent, null, content) } let n = parent._start for (; n !== null; n = n.right) { @@ -431,14 +430,14 @@ export const typeArrayInsertGenerics = (transaction, parent, index, content) => if (index <= n.length) { if (index < n.length) { // insert in-between - getItemCleanStart(transaction, transaction.y.store, createID(n.id.client, n.id.clock + index)) + getItemCleanStart(transaction, transaction.doc.store, createID(n.id.client, n.id.clock + index)) } break } index -= n.length } } - return typeArrayInsertGenericsAfter(transaction, parent, n, content) + return typeListInsertGenericsAfter(transaction, parent, n, content) } /** @@ -450,14 +449,14 @@ export const typeArrayInsertGenerics = (transaction, parent, index, content) => * @private * @function */ -export const typeArrayDelete = (transaction, parent, index, length) => { +export const typeListDelete = (transaction, parent, index, length) => { if (length === 0) { return } let n = parent._start // compute the first item to be deleted for (; n !== null && index > 0; n = n.right) { if (!n.deleted && n.countable) { if (index < n.length) { - getItemCleanStart(transaction, transaction.y.store, createID(n.id.client, n.id.clock + index)) + getItemCleanStart(transaction, transaction.doc.store, createID(n.id.client, n.id.clock + index)) } index -= n.length } @@ -466,7 +465,7 @@ export const typeArrayDelete = (transaction, parent, index, length) => { while (length > 0 && n !== null) { if (!n.deleted) { if (length < n.length) { - getItemCleanStart(transaction, transaction.y.store, createID(n.id.client, n.id.clock + length)) + getItemCleanStart(transaction, transaction.doc.store, createID(n.id.client, n.id.clock + length)) } n.delete(transaction) length -= n.length @@ -497,7 +496,7 @@ export const typeMapDelete = (transaction, parent, key) => { * @param {Transaction} transaction * @param {AbstractType} parent * @param {string} key - * @param {Object|number|Array|string|ArrayBuffer|AbstractType} value + * @param {Object|number|Array|string|Uint8Array|AbstractType} value * * @private * @function @@ -515,7 +514,7 @@ export const typeMapSet = (transaction, parent, key, value) => { case String: new ItemJSON(nextID(transaction), left, left === null ? null : left.lastId, null, null, parent, key, [value]).integrate(transaction) break - case ArrayBuffer: + case Uint8Array: new ItemBinary(nextID(transaction), left, left === null ? null : left.lastId, null, null, parent, key, value).integrate(transaction) break default: @@ -530,7 +529,7 @@ export const typeMapSet = (transaction, parent, key, value) => { /** * @param {AbstractType} parent * @param {string} key - * @return {Object|number|Array|string|ArrayBuffer|AbstractType|undefined} + * @return {Object|number|Array|string|Uint8Array|AbstractType|undefined} * * @private * @function @@ -542,7 +541,7 @@ export const typeMapGet = (parent, key) => { /** * @param {AbstractType} parent - * @return {Object|number|Array|string|ArrayBuffer|AbstractType|undefined>} + * @return {Object|number|Array|string|Uint8Array|AbstractType|undefined>} * * @private * @function @@ -577,7 +576,7 @@ export const typeMapHas = (parent, key) => { * @param {AbstractType} parent * @param {string} key * @param {Snapshot} snapshot - * @return {Object|number|Array|string|ArrayBuffer|AbstractType|undefined} + * @return {Object|number|Array|string|Uint8Array|AbstractType|undefined} * * @private * @function diff --git a/src/types/YArray.js b/src/types/YArray.js index e2986859..38dfeb02 100644 --- a/src/types/YArray.js +++ b/src/types/YArray.js @@ -5,17 +5,17 @@ import { YEvent, AbstractType, - typeArrayGet, - typeArrayToArray, - typeArrayForEach, - typeArrayCreateIterator, - typeArrayInsertGenerics, - typeArrayDelete, - typeArrayMap, + typeListGet, + typeListToArray, + typeListForEach, + typeListCreateIterator, + typeListInsertGenerics, + typeListDelete, + typeListMap, YArrayRefID, callTypeObservers, transact, - Y, Transaction, ItemType, // eslint-disable-line + Doc, Transaction, ItemType, // eslint-disable-line } from '../internals.js' import * as decoding from 'lib0/decoding.js' // eslint-disable-line @@ -58,7 +58,7 @@ export class YArray extends AbstractType { * * This type is sent to other client * * Observer functions are fired * - * @param {Y} y The Yjs instance + * @param {Doc} y The Yjs instance * @param {ItemType} item * * @private @@ -101,9 +101,9 @@ export class YArray extends AbstractType { * @param {Array} content The array of content */ insert (index, content) { - if (this._y !== null) { - transact(this._y, transaction => { - typeArrayInsertGenerics(transaction, this, index, content) + if (this.doc !== null) { + transact(this.doc, transaction => { + typeListInsertGenerics(transaction, this, index, content) }) } else { // @ts-ignore _prelimContent is defined because this is not yet integrated @@ -127,9 +127,9 @@ export class YArray extends AbstractType { * @param {number} length The number of elements to remove. Defaults to 1. */ delete (index, length = 1) { - if (this._y !== null) { - transact(this._y, transaction => { - typeArrayDelete(transaction, this, index, length) + if (this.doc !== null) { + transact(this.doc, transaction => { + typeListDelete(transaction, this, index, length) }) } else { // @ts-ignore _prelimContent is defined because this is not yet integrated @@ -144,7 +144,7 @@ export class YArray extends AbstractType { * @return {T} */ get (index) { - return typeArrayGet(this, index) + return typeListGet(this, index) } /** @@ -153,7 +153,7 @@ export class YArray extends AbstractType { * @return {Array} */ toArray () { - return typeArrayToArray(this) + return typeListToArray(this) } /** @@ -176,7 +176,7 @@ export class YArray extends AbstractType { */ map (f) { // @ts-ignore - return typeArrayMap(this, f) + return typeListMap(this, f) } /** @@ -185,14 +185,14 @@ export class YArray extends AbstractType { * @param {function(T,number,YArray):void} f A function to execute on every element of this YArray. */ forEach (f) { - typeArrayForEach(this, f) + typeListForEach(this, f) } /** * @return {IterableIterator} */ [Symbol.iterator] () { - return typeArrayCreateIterator(this) + return typeListCreateIterator(this) } /** diff --git a/src/types/YMap.js b/src/types/YMap.js index 2df44d97..34efbe03 100644 --- a/src/types/YMap.js +++ b/src/types/YMap.js @@ -14,7 +14,7 @@ import { YMapRefID, callTypeObservers, transact, - Y, Transaction, ItemType, // eslint-disable-line + Doc, Transaction, ItemType, // eslint-disable-line } from '../internals.js' import * as encoding from 'lib0/encoding.js' @@ -38,7 +38,7 @@ export class YMapEvent extends YEvent { } /** - * @template T number|string|Object|Array|ArrayBuffer + * @template T number|string|Object|Array|Uint8Array * A shared Map implementation. * * @extends AbstractType> @@ -60,7 +60,7 @@ export class YMap extends AbstractType { * * This type is sent to other client * * Observer functions are fired * - * @param {Y} y The Yjs instance + * @param {Doc} y The Yjs instance * @param {ItemType} item * * @private @@ -144,8 +144,8 @@ export class YMap extends AbstractType { * @param {string} key The key of the element to remove. */ delete (key) { - if (this._y !== null) { - transact(this._y, transaction => { + if (this.doc !== null) { + transact(this.doc, transaction => { typeMapDelete(transaction, this, key) }) } else { @@ -161,8 +161,8 @@ export class YMap extends AbstractType { * @param {T} value The value of the element to add */ set (key, value) { - if (this._y !== null) { - transact(this._y, transaction => { + if (this.doc !== null) { + transact(this.doc, transaction => { typeMapSet(transaction, this, key, value) }) } else { diff --git a/src/types/YText.js b/src/types/YText.js index 539760f2..27665ca7 100644 --- a/src/types/YText.js +++ b/src/types/YText.js @@ -16,7 +16,7 @@ import { YTextRefID, callTypeObservers, transact, - Y, ItemType, AbstractItem, Snapshot, StructStore, Transaction // eslint-disable-line + Doc, ItemType, AbstractItem, Snapshot, StructStore, Transaction // eslint-disable-line } from '../internals.js' import * as decoding from 'lib0/decoding.js' // eslint-disable-line @@ -303,7 +303,7 @@ const formatText = (transaction, parent, left, right, currentAttributes, length, case ItemEmbed: case ItemString: if (length < right.length) { - getItemCleanStart(transaction, transaction.y.store, createID(right.id.client, right.id.clock + length)) + getItemCleanStart(transaction, transaction.doc.store, createID(right.id.client, right.id.clock + length)) } length -= right.length break @@ -337,7 +337,7 @@ const deleteText = (transaction, left, right, currentAttributes, length) => { case ItemEmbed: case ItemString: if (length < right.length) { - getItemCleanStart(transaction, transaction.y.store, createID(right.id.client, right.id.clock + length)) + getItemCleanStart(transaction, transaction.doc.store, createID(right.id.client, right.id.clock + length)) } length -= right.length right.delete(transaction) @@ -411,7 +411,7 @@ class YTextEvent extends YEvent { */ get delta () { if (this._delta === null) { - const y = this.target._y + const y = this.target.doc // @ts-ignore transact(y, transaction => { /** @@ -629,7 +629,7 @@ export class YText extends AbstractType { } /** - * @param {Y} y + * @param {Doc} y * @param {ItemType} item * * @private @@ -686,8 +686,8 @@ export class YText extends AbstractType { * @public */ applyDelta (delta) { - if (this._y !== null) { - transact(this._y, transaction => { + if (this.doc !== null) { + transact(this.doc, transaction => { /** * @type {ItemListPosition} */ @@ -803,7 +803,7 @@ export class YText extends AbstractType { if (text.length <= 0) { return } - const y = this._y + const y = this.doc if (y !== null) { transact(y, transaction => { const { left, right, currentAttributes } = findPosition(transaction, y.store, this, index) @@ -829,7 +829,7 @@ export class YText extends AbstractType { if (embed.constructor !== Object) { throw new Error('Embed must be an Object') } - const y = this._y + const y = this.doc if (y !== null) { transact(y, transaction => { const { left, right, currentAttributes } = findPosition(transaction, y.store, this, index) @@ -853,7 +853,7 @@ export class YText extends AbstractType { if (length === 0) { return } - const y = this._y + const y = this.doc if (y !== null) { transact(y, transaction => { const { left, right, currentAttributes } = findPosition(transaction, y.store, this, index) @@ -876,7 +876,7 @@ export class YText extends AbstractType { * @public */ format (index, length, attributes) { - const y = this._y + const y = this.doc if (y !== null) { transact(y, transaction => { let { left, right, currentAttributes } = findPosition(transaction, y.store, this, index) diff --git a/src/types/YXmlElement.js b/src/types/YXmlElement.js index b2fbc2f2..a70ec1e2 100644 --- a/src/types/YXmlElement.js +++ b/src/types/YXmlElement.js @@ -6,9 +6,9 @@ import { typeMapSet, typeMapGet, typeMapGetAll, - typeArrayForEach, + typeListForEach, YXmlElementRefID, - Snapshot, Y, ItemType // eslint-disable-line + Snapshot, Doc, ItemType // eslint-disable-line } from '../internals.js' import * as encoding from 'lib0/encoding.js' @@ -39,7 +39,7 @@ export class YXmlElement extends YXmlFragment { * * This type is sent to other client * * Observer functions are fired * - * @param {Y} y The Yjs instance + * @param {Doc} y The Yjs instance * @param {ItemType} item * @private */ @@ -100,8 +100,8 @@ export class YXmlElement extends YXmlFragment { * @public */ removeAttribute (attributeName) { - if (this._y !== null) { - transact(this._y, transaction => { + if (this.doc !== null) { + transact(this.doc, transaction => { typeMapDelete(transaction, this, attributeName) }) } else { @@ -119,8 +119,8 @@ export class YXmlElement extends YXmlFragment { * @public */ setAttribute (attributeName, attributeValue) { - if (this._y !== null) { - transact(this._y, transaction => { + if (this.doc !== null) { + transact(this.doc, transaction => { typeMapSet(transaction, this, attributeName, attributeValue) }) } else { @@ -176,7 +176,7 @@ export class YXmlElement extends YXmlFragment { for (let key in attrs) { dom.setAttribute(key, attrs[key]) } - typeArrayForEach(this, yxml => { + typeListForEach(this, yxml => { dom.appendChild(yxml.toDOM(_document, hooks, binding)) }) if (binding !== undefined) { diff --git a/src/types/YXmlFragment.js b/src/types/YXmlFragment.js index 998ebb26..a49e5b6f 100644 --- a/src/types/YXmlFragment.js +++ b/src/types/YXmlFragment.js @@ -6,11 +6,11 @@ import { YXmlEvent, YXmlElement, AbstractType, - typeArrayMap, - typeArrayForEach, - typeArrayInsertGenerics, - typeArrayDelete, - typeArrayToArray, + typeListMap, + typeListForEach, + typeListInsertGenerics, + typeListDelete, + typeListToArray, YXmlFragmentRefID, callTypeObservers, transact, @@ -211,7 +211,7 @@ export class YXmlFragment extends AbstractType { * @return {string} The string representation of all children. */ toString () { - return typeArrayMap(this, xml => xml.toString()).join('') + return typeListMap(this, xml => xml.toString()).join('') } toJSON () { @@ -238,7 +238,7 @@ export class YXmlFragment extends AbstractType { if (binding !== undefined) { binding._createAssociation(fragment, this) } - typeArrayForEach(this, xmlType => { + typeListForEach(this, xmlType => { fragment.insertBefore(xmlType.toDOM(_document, hooks, binding), null) }) return fragment @@ -255,9 +255,9 @@ export class YXmlFragment extends AbstractType { * @param {Array} content The array of content */ insert (index, content) { - if (this._y !== null) { - transact(this._y, transaction => { - typeArrayInsertGenerics(transaction, this, index, content) + if (this.doc !== null) { + transact(this.doc, transaction => { + typeListInsertGenerics(transaction, this, index, content) }) } else { // @ts-ignore _prelimContent is defined because this is not yet integrated @@ -272,9 +272,9 @@ export class YXmlFragment extends AbstractType { * @param {number} [length=1] The number of elements to remove. Defaults to 1. */ delete (index, length = 1) { - if (this._y !== null) { - transact(this._y, transaction => { - typeArrayDelete(transaction, this, index, length) + if (this.doc !== null) { + transact(this.doc, transaction => { + typeListDelete(transaction, this, index, length) }) } else { // @ts-ignore _prelimContent is defined because this is not yet integrated @@ -287,7 +287,7 @@ export class YXmlFragment extends AbstractType { * @return {Array} */ toArray () { - return typeArrayToArray(this) + return typeListToArray(this) } /** * Transform the properties of this type to binary and write it to an diff --git a/src/utils/DeleteSet.js b/src/utils/DeleteSet.js index fa71454e..95db50f3 100644 --- a/src/utils/DeleteSet.js +++ b/src/utils/DeleteSet.js @@ -48,7 +48,7 @@ export class DeleteSet { /** * Iterate over all structs that were deleted. * - * This function expects that the deletes structs are not deleted. Hence, you can + * This function expects that the deletes structs are not merged. Hence, you can * probably only use it in type observes and `afterTransaction` events. But not * in `afterTransactionCleanup`. * @@ -266,6 +266,6 @@ export const readDeleteSet = (decoder, transaction, store) => { if (unappliedDS.clients.size > 0) { const unappliedDSEncoder = encoding.createEncoder() writeDeleteSet(unappliedDSEncoder, unappliedDS) - store.pendingDeleteReaders.push(decoding.createDecoder(encoding.toBuffer(unappliedDSEncoder))) + store.pendingDeleteReaders.push(decoding.createDecoder(encoding.toUint8Array(unappliedDSEncoder))) } } diff --git a/src/utils/Y.js b/src/utils/Doc.js similarity index 89% rename from src/utils/Y.js rename to src/utils/Doc.js index 1d1522e3..cc45af19 100644 --- a/src/utils/Y.js +++ b/src/utils/Doc.js @@ -10,26 +10,23 @@ import { YMap, YXmlFragment, transact, - Transaction, YEvent // eslint-disable-line + AbstractItem, Transaction, YEvent // eslint-disable-line } from '../internals.js' import { Observable } from 'lib0/observable.js' import * as random from 'lib0/random.js' import * as map from 'lib0/map.js' -// @todo rename to shared document - /** * A Yjs instance handles the state of shared data. * @extends Observable */ -export class Y extends Observable { +export class Doc extends Observable { /** * @param {Object|undefined} conf configuration */ constructor (conf = {}) { super() - // todo: change to clientId this.clientID = random.uint32() /** * @type {Map>} @@ -82,7 +79,7 @@ export class Y extends Observable { * } * * @param {string} name - * @param {Function} TypeConstructor The constructor of the type definition + * @param {Function} TypeConstructor The constructor of the type definition. E.g. Y.Text, Y.Array, Y.Map, ... * @return {AbstractType} The created type. Constructed with TypeConstructor * * @public @@ -97,9 +94,18 @@ export class Y extends Observable { const Constr = type.constructor if (TypeConstructor !== AbstractType && Constr !== TypeConstructor) { if (Constr === AbstractType) { - const t = new Constr() + // @ts-ignore + const t = new TypeConstructor() t._map = type._map + type._map.forEach(/** @param {AbstractItem?} n */ n => { + for (; n !== null; n = n.left) { + n.parent = t + } + }) t._start = type._start + for (let n = t._start; n !== null; n = n.right) { + n.parent = t + } t._length = type._length this.share.set(name, t) t._integrate(this, null) diff --git a/src/utils/ID.js b/src/utils/ID.js index 76f0cd28..81860f2c 100644 --- a/src/utils/ID.js +++ b/src/utils/ID.js @@ -22,16 +22,6 @@ export class ID { */ this.clock = clock } - /** - * @deprecated - * @todo remove and adapt relative position implementation - */ - toJSON () { - return { - client: this.client, - clock: this.clock - } - } } /** @@ -91,7 +81,7 @@ export const readID = decoder => */ export const findRootTypeKey = type => { // @ts-ignore _y must be defined, otherwise unexpected case - for (let [key, value] of type._y.share) { + for (let [key, value] of type.doc.share) { if (value === type) { return key } diff --git a/src/utils/cursor.js b/src/utils/RelativePosition.js similarity index 57% rename from src/utils/cursor.js rename to src/utils/RelativePosition.js index a9e4d24d..25522078 100644 --- a/src/utils/cursor.js +++ b/src/utils/RelativePosition.js @@ -1,6 +1,3 @@ -/** - * @module Cursors - */ import { getItem, @@ -13,7 +10,7 @@ import { findRootTypeKey, AbstractItem, ItemType, - ID, StructStore, Y, AbstractType // eslint-disable-line + ID, StructStore, Doc, AbstractType // eslint-disable-line } from '../internals.js' import * as encoding from 'lib0/encoding.js' @@ -21,29 +18,30 @@ import * as decoding from 'lib0/decoding.js' import * as error from 'lib0/error.js' /** - * A Cursor is a relative position that is based on the Yjs model. In contrast to an - * absolute position (position by index), the Cursor can be - * recomputed when remote changes are received. For example: + * A relative position is based on the Yjs model and is not affected by document changes. + * E.g. If you place a relative position before a certain character, it will always point to this character. + * If you place a relative position at the end of a type, it will always point to the end of the type. * - * ```Insert(0, 'x')('a|bc') = 'xa|bc'``` Where | is the cursor position. + * A numeric position is often unsuited for user selections, because it does not change when content is inserted + * before or after. * - * A relative cursor position can be obtained with the function + * ```Insert(0, 'x')('a|bc') = 'xa|bc'``` Where | is the relative position. * * One of the properties must be defined. * * @example * // Current cursor position is at position 10 - * const relativePosition = createCursorFromOffset(yText, 10) + * const relativePosition = createRelativePositionFromIndex(yText, 10) * // modify yText * yText.insert(0, 'abc') * yText.delete(3, 10) * // Compute the cursor position - * const absolutePosition = toAbsolutePosition(y, relativePosition) + * const absolutePosition = createAbsolutePositionFromRelativePosition(y, relativePosition) * absolutePosition.type === yText // => true - * console.log('cursor location is ' + absolutePosition.offset) // => cursor location is 3 + * console.log('cursor location is ' + absolutePosition.index) // => cursor location is 3 * */ -export class Cursor { +export class RelativePosition { /** * @param {ID|null} type * @param {string|null} tname @@ -63,35 +61,22 @@ export class Cursor { */ this.item = item } - toJSON () { - const json = {} - if (this.type !== null) { - json.type = this.type.toJSON() - } - if (this.tname !== null) { - json.tname = this.tname - } - if (this.item !== null) { - json.item = this.item.toJSON() - } - return json - } } /** * @param {Object} json - * @return {Cursor} + * @return {RelativePosition} * * @function */ -export const createCursorFromJSON = json => new Cursor(json.type == null ? null : createID(json.type.client, json.type.clock), json.tname || null, json.item == null ? null : createID(json.item.client, json.item.clock)) +export const createRelativePositionFromJSON = json => new RelativePosition(json.type == null ? null : createID(json.type.client, json.type.clock), json.tname || null, json.item == null ? null : createID(json.item.client, json.item.clock)) export class AbsolutePosition { /** * @param {AbstractType} type - * @param {number} offset + * @param {number} index */ - constructor (type, offset) { + constructor (type, index) { /** * @type {AbstractType} */ @@ -99,17 +84,17 @@ export class AbsolutePosition { /** * @type {number} */ - this.offset = offset + this.index = index } } /** * @param {AbstractType} type - * @param {number} offset + * @param {number} index * * @function */ -export const createAbsolutePosition = (type, offset) => new AbsolutePosition(type, offset) +export const createAbsolutePosition = (type, index) => new AbsolutePosition(type, index) /** * @param {AbstractType} type @@ -117,7 +102,7 @@ export const createAbsolutePosition = (type, offset) => new AbsolutePosition(typ * * @function */ -export const createCursor = (type, item) => { +export const createRelativePosition = (type, item) => { let typeid = null let tname = null if (type._item === null) { @@ -125,40 +110,40 @@ export const createCursor = (type, item) => { } else { typeid = type._item.id } - return new Cursor(typeid, tname, item) + return new RelativePosition(typeid, tname, item) } /** * Create a relativePosition based on a absolute position. * * @param {AbstractType} type The base type (e.g. YText or YArray). - * @param {number} offset The absolute position. - * @return {Cursor} + * @param {number} index The absolute position. + * @return {RelativePosition} * * @function */ -export const createCursorFromTypeOffset = (type, offset) => { +export const createRelativePositionFromTypeIndex = (type, index) => { let t = type._start while (t !== null) { if (!t.deleted && t.countable) { - if (t.length > offset) { + if (t.length > index) { // case 1: found position somewhere in the linked list - return createCursor(type, createID(t.id.client, t.id.clock + offset)) + return createRelativePosition(type, createID(t.id.client, t.id.clock + index)) } - offset -= t.length + index -= t.length } t = t.right } - return createCursor(type, null) + return createRelativePosition(type, null) } /** * @param {encoding.Encoder} encoder - * @param {Cursor} rpos + * @param {RelativePosition} rpos * * @function */ -export const writeCursor = (encoder, rpos) => { +export const writeRelativePosition = (encoder, rpos) => { const { type, tname, item } = rpos if (item !== null) { encoding.writeVarUint(encoder, 0) @@ -177,15 +162,23 @@ export const writeCursor = (encoder, rpos) => { return encoder } +/** + * @param {RelativePosition} rpos + * @return {Uint8Array} + */ +export const encodeRelativePosition = rpos => { + const encoder = encoding.createEncoder() + writeRelativePosition(encoder, rpos) + return encoding.toUint8Array(encoder) +} + /** * @param {decoding.Decoder} decoder - * @param {Y} y - * @param {StructStore} store - * @return {Cursor|null} + * @return {RelativePosition|null} * * @function */ -export const readCursor = (decoder, y, store) => { +export const readRelativePosition = decoder => { let type = null let tname = null let itemID = null @@ -203,23 +196,29 @@ export const readCursor = (decoder, y, store) => { type = readID(decoder) } } - return new Cursor(type, tname, itemID) + return new RelativePosition(type, tname, itemID) } /** - * @param {Cursor} cursor - * @param {Y} y + * @param {Uint8Array} uint8Array + * @return {RelativePosition|null} + */ +export const decodeRelativePosition = uint8Array => readRelativePosition(decoding.createDecoder(uint8Array)) + +/** + * @param {RelativePosition} rpos + * @param {Doc} doc * @return {AbsolutePosition|null} * * @function */ -export const createAbsolutePositionFromCursor = (cursor, y) => { - const store = y.store - const rightID = cursor.item - const typeID = cursor.type - const tname = cursor.tname +export const createAbsolutePositionFromRelativePosition = (rpos, doc) => { + const store = doc.store + const rightID = rpos.item + const typeID = rpos.type + const tname = rpos.tname let type = null - let offset = 0 + let index = 0 if (rightID !== null) { if (getState(store, rightID.client) <= rightID.clock) { return null @@ -228,18 +227,18 @@ export const createAbsolutePositionFromCursor = (cursor, y) => { if (!(right instanceof AbstractItem)) { return null } - offset = right.deleted || !right.countable ? 0 : rightID.clock - right.id.clock + index = right.deleted || !right.countable ? 0 : rightID.clock - right.id.clock let n = right.left while (n !== null) { if (!n.deleted && n.countable) { - offset += n.length + index += n.length } n = n.left } type = right.parent } else { if (tname !== null) { - type = y.get(tname) + type = doc.get(tname) } else if (typeID !== null) { if (getState(store, typeID.client) <= typeID.clock) { // type does not exist yet @@ -255,20 +254,20 @@ export const createAbsolutePositionFromCursor = (cursor, y) => { } else { throw error.unexpectedCase() } - offset = type._length + index = type._length } if (type._item !== null && type._item.deleted) { return null } - return createAbsolutePosition(type, offset) + return createAbsolutePosition(type, index) } /** - * @param {Cursor|null} a - * @param {Cursor|null} b + * @param {RelativePosition|null} a + * @param {RelativePosition|null} b * * @function */ -export const compareCursors = (a, b) => a === b || ( +export const compareRelativePositions = (a, b) => a === b || ( a !== null && b !== null && a.tname === b.tname && compareIDs(a.item, b.item) && compareIDs(a.type, b.type) ) diff --git a/src/utils/Snapshot.js b/src/utils/Snapshot.js index bfc4fbd4..92e2f0ec 100644 --- a/src/utils/Snapshot.js +++ b/src/utils/Snapshot.js @@ -6,12 +6,10 @@ import { export class Snapshot { /** - * @param {DeleteSet} ds delete store + * @param {DeleteSet} ds * @param {Map} sm state map - * @param {Map} userMap - * @private */ - constructor (ds, sm, userMap) { + constructor (ds, sm) { /** * @type {DeleteSet} * @private @@ -23,14 +21,15 @@ export class Snapshot { * @private */ this.sm = sm - /** - * @type {Map} - * @private - */ - this.userMap = userMap } } +/** + * @param {DeleteSet} ds + * @param {Map} sm + */ +export const createSnapshot = (ds, sm) => new Snapshot(ds, sm) + /** * @param {AbstractItem} item * @param {Snapshot|undefined} snapshot diff --git a/src/utils/StructStore.js b/src/utils/StructStore.js index 20a38078..2a9bb27d 100644 --- a/src/utils/StructStore.js +++ b/src/utils/StructStore.js @@ -6,8 +6,7 @@ import { import * as math from 'lib0/math.js' import * as error from 'lib0/error.js' -import * as encoding from 'lib0/encoding.js' -import * as decoding from 'lib0/decoding.js' +import * as decoding from 'lib0/decoding.js' // eslint-disable-line export class StructStore { constructor () { @@ -51,7 +50,7 @@ export class StructStore { * @public * @function */ -export const getStates = store => { +export const getStateVector = store => { const sm = new Map() store.clients.forEach((structs, client) => { const struct = structs[structs.length - 1] @@ -262,42 +261,3 @@ export const replaceStruct = (store, struct, newStruct) => { const structs = store.clients.get(struct.id.client) structs[findIndexSS(structs, struct.id.clock)] = newStruct } - -/** - * Read StateMap from Decoder and return as Map - * - * @param {decoding.Decoder} decoder - * @return {Map} - * - * @private - * @function - */ -export const readStatesAsMap = decoder => { - const ss = new Map() - const ssLength = decoding.readVarUint(decoder) - for (let i = 0; i < ssLength; i++) { - const client = decoding.readVarUint(decoder) - const clock = decoding.readVarUint(decoder) - ss.set(client, clock) - } - return ss -} - -/** - * Write StateMap to Encoder - * - * @param {encoding.Encoder} encoder - * @param {StructStore} store - * - * @private - * @function - */ -export const writeStates = (encoder, store) => { - encoding.writeVarUint(encoder, store.clients.size) - store.clients.forEach((structs, client) => { - const id = structs[structs.length - 1].id - encoding.writeVarUint(encoder, id.client) - encoding.writeVarUint(encoder, id.clock) - }) - return encoder -} diff --git a/src/utils/Transaction.js b/src/utils/Transaction.js index 41c9cb87..d8ae1c80 100644 --- a/src/utils/Transaction.js +++ b/src/utils/Transaction.js @@ -6,11 +6,11 @@ import { writeDeleteSet, DeleteSet, sortAndMergeDeleteSet, - getStates, + getStateVector, findIndexSS, callEventHandlerListeners, AbstractItem, - ID, AbstractType, AbstractStruct, YEvent, Y // eslint-disable-line + ID, AbstractType, AbstractStruct, YEvent, Doc // eslint-disable-line } from '../internals.js' import * as encoding from 'lib0/encoding.js' @@ -43,15 +43,15 @@ import * as math from 'lib0/math.js' */ export class Transaction { /** - * @param {Y} y + * @param {Doc} doc * @param {any} origin */ - constructor (y, origin) { + constructor (doc, origin) { /** * The Yjs instance. - * @type {Y} + * @type {Doc} */ - this.y = y + this.doc = doc /** * Describes the set of deleted items by ids * @type {DeleteSet} @@ -61,7 +61,7 @@ export class Transaction { * Holds the state before the transaction started. * @type {Map} */ - this.beforeState = getStates(y.store) + this.beforeState = getStateVector(doc.store) /** * Holds the state after the transaction. * @type {Map} @@ -80,11 +80,6 @@ export class Transaction { * @type {Map,Array>} */ this.changedParentTypes = new Map() - /** - * @type {encoding.Encoder|null} - * @private - */ - this._updateMessage = null /** * @type {Set} * @private @@ -95,21 +90,20 @@ export class Transaction { */ this.origin = origin } - /** - * @type {encoding.Encoder|null} - * @public - */ - get updateMessage () { - // only create if content was added in transaction (state or ds changed) - if (this._updateMessage === null && (this.deleteSet.clients.size > 0 || map.any(this.afterState, (clock, client) => this.beforeState.get(client) !== clock))) { - const encoder = encoding.createEncoder() - sortAndMergeDeleteSet(this.deleteSet) - writeStructsFromTransaction(encoder, this) - writeDeleteSet(encoder, this.deleteSet) - this._updateMessage = encoder - } - return this._updateMessage +} + +/** + * @param {Transaction} transaction + */ +export const computeUpdateMessageFromTransaction = transaction => { + if (transaction.deleteSet.clients.size === 0 && !map.any(transaction.afterState, (clock, client) => transaction.beforeState.get(client) !== clock)) { + return null } + const encoder = encoding.createEncoder() + sortAndMergeDeleteSet(transaction.deleteSet) + writeStructsFromTransaction(encoder, transaction) + writeDeleteSet(encoder, transaction.deleteSet) + return encoder } /** @@ -119,45 +113,44 @@ export class Transaction { * @function */ export const nextID = transaction => { - const y = transaction.y + const y = transaction.doc return createID(y.clientID, getState(y.store, y.clientID)) } /** * Implements the functionality of `y.transact(()=>{..})` * - * @param {Y} y + * @param {Doc} doc * @param {function(Transaction):void} f * @param {any} [origin] * * @private * @function */ -export const transact = (y, f, origin = null) => { - const transactionCleanups = y._transactionCleanups +export const transact = (doc, f, origin = null) => { + const transactionCleanups = doc._transactionCleanups let initialCall = false - if (y._transaction === null) { + if (doc._transaction === null) { initialCall = true - y._transaction = new Transaction(y, origin) - transactionCleanups.push(y._transaction) - y.emit('beforeTransaction', [y._transaction, y]) + doc._transaction = new Transaction(doc, origin) + transactionCleanups.push(doc._transaction) + doc.emit('beforeTransaction', [doc._transaction, doc]) } try { - f(y._transaction) + f(doc._transaction) } finally { - // @todo set after state here - if (initialCall && transactionCleanups[0] === y._transaction) { + if (initialCall && transactionCleanups[0] === doc._transaction) { // The first transaction ended, now process observer calls. // Observer call may create new transactions for which we need to call the observers and do cleanup. // We don't want to nest these calls, so we execute these calls one after another for (let i = 0; i < transactionCleanups.length; i++) { const transaction = transactionCleanups[i] - const store = transaction.y.store + const store = transaction.doc.store const ds = transaction.deleteSet sortAndMergeDeleteSet(ds) - transaction.afterState = getStates(transaction.y.store) - y._transaction = null - y.emit('beforeObserverCalls', [transaction, y]) + transaction.afterState = getStateVector(transaction.doc.store) + doc._transaction = null + doc.emit('beforeObserverCalls', [transaction, doc]) // emit change events on changed types transaction.changed.forEach((subs, itemtype) => { itemtype._callObserver(transaction, subs) @@ -175,7 +168,7 @@ export const transact = (y, f, origin = null) => { // because we know it has at least one element callEventHandlerListeners(type._dEH, events, transaction) }) - y.emit('afterTransaction', [transaction, y]) + doc.emit('afterTransaction', [transaction, doc]) /** * @param {Array} structs * @param {number} pos @@ -213,7 +206,7 @@ export const transact = (y, f, origin = null) => { break } if (struct.deleted && struct instanceof AbstractItem) { - struct.gc(transaction, store, false) + struct.gc(store, false) } } } @@ -276,10 +269,15 @@ export const transact = (y, f, origin = null) => { } } // @todo Merge all the transactions into one and provide send the data as a single update message - // @todo implement a dedicatet event that we can use to send updates to other peer - y.emit('afterTransactionCleanup', [transaction, y]) + doc.emit('afterTransactionCleanup', [transaction, doc]) + if (doc._observers.has('update')) { + const updateMessage = computeUpdateMessageFromTransaction(transaction) + if (updateMessage !== null) { + doc.emit('update', [encoding.toUint8Array(updateMessage), transaction.origin, doc]) + } + } } - y._transactionCleanups = [] + doc._transactionCleanups = [] } } } diff --git a/src/utils/UndoManager.js b/src/utils/UndoManager.js index ed3f4ace..d2e19797 100644 --- a/src/utils/UndoManager.js +++ b/src/utils/UndoManager.js @@ -116,10 +116,10 @@ export class UndoManager { this._undoing = false this._redoing = false this._lastTransactionWasUndo = false - const y = scope._y - this.y = y + const doc = scope.doc + this.y = doc let bindingInfos - y.on('beforeTransaction', (y, transaction, remote) => { + doc.on('beforeTransaction', (y, transaction, remote) => { if (!remote) { // Store binding information before transaction is executed // By restoring the binding information, we can make sure that the state @@ -130,7 +130,7 @@ export class UndoManager { }) } }) - y.on('afterTransaction', (y, transaction, remote) => { + doc.on('afterTransaction', (y, transaction, remote) => { if (!remote && transaction.changedParentTypes.has(scope)) { let reverseOperation = new ReverseOperation(y, transaction, bindingInfos) if (!this._undoing) { @@ -200,3 +200,4 @@ export class UndoManager { return performedRedo } } +} diff --git a/src/utils/encoding.js b/src/utils/encoding.js index 1eb39ed9..80f52042 100644 --- a/src/utils/encoding.js +++ b/src/utils/encoding.js @@ -17,11 +17,11 @@ import { createID, readID, getState, - getStates, + getStateVector, readDeleteSet, writeDeleteSet, createDeleteSetFromStructStore, - Transaction, AbstractStruct, AbstractStructRef, StructStore, ID // eslint-disable-line + Doc, Transaction, AbstractStruct, AbstractStructRef, StructStore, ID // eslint-disable-line } from '../internals.js' import * as encoding from 'lib0/encoding.js' @@ -104,7 +104,7 @@ export const writeClientsStructs = (encoder, store, _sm) => { sm.set(client, clock) } }) - getStates(store).forEach((clock, client) => { + getStateVector(store).forEach((clock, client) => { if (!_sm.has(client)) { sm.set(client, 0) } @@ -250,7 +250,7 @@ export const tryResumePendingDeleteReaders = (transaction, store) => { * @private * @function */ -export const writeStructsFromTransaction = (encoder, transaction) => writeClientsStructs(encoder, transaction.y.store, transaction.beforeState) +export const writeStructsFromTransaction = (encoder, transaction) => writeClientsStructs(encoder, transaction.doc.store, transaction.beforeState) /** * @param {StructStore} store @@ -297,25 +297,127 @@ export const readStructs = (decoder, transaction, store) => { } /** + * Read and apply a document update. + * + * This function has the same effect as `applyUpdate` but accepts an decoder. + * * @param {decoding.Decoder} decoder - * @param {Transaction} transaction - * @param {StructStore} store + * @param {Doc} ydoc + * @param {any} [transactionOrigin] This will be stored on `transaction.origin` and `.on('update', (update, origin))` * * @function */ -export const readModel = (decoder, transaction, store) => { - readStructs(decoder, transaction, store) - readDeleteSet(decoder, transaction, store) +export const readUpdate = (decoder, ydoc, transactionOrigin) => + ydoc.transact(transaction => { + readStructs(decoder, transaction, ydoc.store) + readDeleteSet(decoder, transaction, ydoc.store) + }, transactionOrigin) + +/** + * Apply a document update created by, for example, `y.on('update', update => ..)` or `update = encodeStateAsUpdate()`. + * + * This function has the same effect as `readUpdate` but accepts an Uint8Array instead of a Decoder. + * + * @param {Doc} ydoc + * @param {Uint8Array} update + * @param {any} [transactionOrigin] This will be stored on `transaction.origin` and `.on('update', (update, origin))` + * + * @function + */ +export const applyUpdate = (ydoc, update, transactionOrigin) => + readUpdate(decoding.createDecoder(update), ydoc, transactionOrigin) + +/** + * Write all the document as a single update message. If you specify the state of the remote client (`targetStateVector`) it will + * only write the operations that are missing. + * + * @param {encoding.Encoder} encoder + * @param {Doc} doc + * @param {Map} [targetStateVector] The state of the target that receives the update. Leave empty to write all known structs + * + * @function + */ +export const writeStateAsUpdate = (encoder, doc, targetStateVector = new Map()) => { + writeClientsStructs(encoder, doc.store, targetStateVector) + writeDeleteSet(encoder, createDeleteSetFromStructStore(doc.store)) } /** - * @param {encoding.Encoder} encoder - * @param {StructStore} store - * @param {Map} [targetState] The state of the target that receives the update. Leave empty to write all known structs + * Write all the document as a single update message that can be applied on the remote document. If you specify the state of the remote client (`targetState`) it will + * only write the operations that are missing. + * + * Use `writeStateAsUpdate` instead if you are working with lib0/encoding.js#Encoder + * + * @param {Doc} doc + * @param {Uint8Array} [encodedTargetStateVector] The state of the target that receives the update. Leave empty to write all known structs + * @return {Uint8Array} * * @function */ -export const writeModel = (encoder, store, targetState = new Map()) => { - writeClientsStructs(encoder, store, targetState) - writeDeleteSet(encoder, createDeleteSetFromStructStore(store)) +export const encodeStateAsUpdate = (doc, encodedTargetStateVector) => { + const encoder = encoding.createEncoder() + const targetStateVector = encodedTargetStateVector == null ? new Map() : decodeStateVector(encodedTargetStateVector) + writeStateAsUpdate(encoder, doc, targetStateVector) + return encoding.toUint8Array(encoder) +} + +/** + * Read state vector from Decoder and return as Map + * + * @param {decoding.Decoder} decoder + * @return {Map} Maps `client` to the number next expected `clock` from that client. + * + * @function + */ +export const readStateVector = decoder => { + const ss = new Map() + const ssLength = decoding.readVarUint(decoder) + for (let i = 0; i < ssLength; i++) { + const client = decoding.readVarUint(decoder) + const clock = decoding.readVarUint(decoder) + ss.set(client, clock) + } + return ss +} + +/** + * Read decodedState and return State as Map. + * + * @param {Uint8Array} decodedState + * @return {Map} Maps `client` to the number next expected `clock` from that client. + * + * @function + */ +export const decodeStateVector = decodedState => readStateVector(decoding.createDecoder(decodedState)) + +/** + * Write State Vector to `lib0/encoding.js#Encoder`. + * + * @param {encoding.Encoder} encoder + * @param {Doc} doc + * + * @function + */ +export const writeDocumentStateVector = (encoder, doc) => { + encoding.writeVarUint(encoder, doc.store.clients.size) + doc.store.clients.forEach((structs, client) => { + const id = structs[structs.length - 1].id + encoding.writeVarUint(encoder, id.client) + encoding.writeVarUint(encoder, id.clock) + }) + return encoder +} + +/** + * Encode State as Uint8Array. + * + * @param {Doc} doc + * @return {Uint8Array} + * + * @function + */ +export const encodeDocumentStateVector = doc => { + const encoder = encoding.createEncoder() + writeDocumentStateVector(encoder, doc) + return encoding.toUint8Array(encoder) } diff --git a/tests/testHelper.js b/tests/testHelper.js index 3ea840da..41fbc07b 100644 --- a/tests/testHelper.js +++ b/tests/testHelper.js @@ -2,9 +2,9 @@ import * as Y from '../src/index.js' import { createDeleteSetFromStructStore, - getStates, + getStateVector, AbstractItem, - DeleteSet, StructStore // eslint-disable-line + DeleteSet, StructStore, Doc // eslint-disable-line } from '../src/internals.js' import * as t from 'lib0/testing.js' @@ -13,24 +13,9 @@ import * as encoding from 'lib0/encoding.js' import * as decoding from 'lib0/decoding.js' import * as syncProtocol from 'y-protocols/sync.js' -/** - * @param {Y.Transaction} transaction - * @param {TestYInstance} y - */ -const afterTransaction = (transaction, y) => { - if (transaction.origin !== y.tc) { - const m = transaction.updateMessage - if (m !== null) { - const encoder = encoding.createEncoder() - syncProtocol.writeUpdate(encoder, m) - broadcastMessage(y, encoding.toBuffer(encoder)) - } - } -} - /** * @param {TestYInstance} y // publish message created by `y` to all other online clients - * @param {ArrayBuffer} m + * @param {Uint8Array} m */ const broadcastMessage = (y, m) => { if (y.tc.onlineConns.has(y)) { @@ -42,7 +27,7 @@ const broadcastMessage = (y, m) => { } } -export class TestYInstance extends Y.Y { +export class TestYInstance extends Doc { /** * @param {TestConnector} testConnector * @param {number} clientID @@ -55,12 +40,18 @@ export class TestYInstance extends Y.Y { */ this.tc = testConnector /** - * @type {Map>} + * @type {Map>} */ this.receiving = new Map() testConnector.allConns.add(this) // set up observe on local model - this.on('afterTransactionCleanup', afterTransaction) + this.on('update', /** @param {Uint8Array} update @param {any} origin */ (update, origin) => { + if (origin !== testConnector) { + const encoder = encoding.createEncoder() + syncProtocol.writeUpdate(encoder, update) + broadcastMessage(this, encoding.toUint8Array(encoder)) + } + }) this.connect() } /** @@ -78,15 +69,15 @@ export class TestYInstance extends Y.Y { if (!this.tc.onlineConns.has(this)) { this.tc.onlineConns.add(this) const encoder = encoding.createEncoder() - syncProtocol.writeSyncStep1(encoder, this.store) + syncProtocol.writeSyncStep1(encoder, this) // publish SyncStep1 - broadcastMessage(this, encoding.toBuffer(encoder)) + broadcastMessage(this, encoding.toUint8Array(encoder)) this.tc.onlineConns.forEach(remoteYInstance => { if (remoteYInstance !== this) { // remote instance sends instance to this instance const encoder = encoding.createEncoder() - syncProtocol.writeSyncStep1(encoder, remoteYInstance.store) - this._receive(encoding.toBuffer(encoder), remoteYInstance) + syncProtocol.writeSyncStep1(encoder, remoteYInstance) + this._receive(encoding.toUint8Array(encoder), remoteYInstance) } }) } @@ -95,7 +86,7 @@ export class TestYInstance extends Y.Y { * Receive a message from another client. This message is only appended to the list of receiving messages. * TestConnector decides when this client actually reads this message. * - * @param {ArrayBuffer} message + * @param {Uint8Array} message * @param {TestYInstance} remoteClient */ _receive (message, remoteClient) { @@ -164,7 +155,7 @@ export class TestConnector { syncProtocol.readSyncMessage(decoding.createDecoder(m), encoder, receiver, receiver.tc) if (encoding.length(encoder) > 0) { // send reply message - sender._receive(encoding.toBuffer(encoder), receiver) + sender._receive(encoding.toUint8Array(encoder), receiver) } return true } @@ -282,7 +273,7 @@ export const compare = users => { // @ts-ignore t.compare(userTextValues[i].map(a => a.insert).join('').length, users[i].getText('text').length) t.compare(userTextValues[i], userTextValues[i + 1]) - t.compare(getStates(users[i].store), getStates(users[i + 1].store)) + t.compare(getStateVector(users[i].store), getStateVector(users[i + 1].store)) compareDS(createDeleteSetFromStructStore(users[i].store), createDeleteSetFromStructStore(users[i + 1].store)) compareStructStores(users[i].store, users[i + 1].store) } diff --git a/tests/y-array.tests.js b/tests/y-array.tests.js index ffa595f8..0c508477 100644 --- a/tests/y-array.tests.js +++ b/tests/y-array.tests.js @@ -263,7 +263,7 @@ export const testEventTargetIsSetCorrectlyOnRemote = tc => { * @param {t.TestCase} tc */ export const testIteratingArrayContainingTypes = tc => { - const y = new Y.Y() + const y = new Y.Doc() const arr = y.getArray('arr') const numItems = 10 for (let i = 0; i < numItems; i++) { diff --git a/tsconfig.json b/tsconfig.json index bd1640d7..ab9813e6 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -54,7 +54,7 @@ /* Experimental Options */ // "experimentalDecorators": true, /* Enables experimental support for ES7 decorators. */ // "emitDecoratorMetadata": true, /* Enables experimental support for emitting type metadata for decorators. */ - "maxNodeModuleJsDepth": 1, + "maxNodeModuleJsDepth": 5, // "types": ["./src/utils/typedefs.js"] }, "include": ["./src/**/*", "./tests/**/*"],