yonote/yjs
23
0
Fork 0
Code Pull Requests 1 Releases Activity

improve jsdoc comments

Browse Source
This commit is contained in:
Kevin Jahns 2019-04-11 13:18:35 +02:00
parent ed3b31e58f
commit 31ff7ac78c
32 changed files with 477 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.v13.md
View File

@ -74,9 +74,7 @@ Yjs does not hava any dependencies. Install this package with your favorite pack
npm i yjs
```
##### Tutorial
In this *short* tutorial I will give an overview of the basic concepts in Yjs.
##### Quickstart
Yjs itself only knows how to do conflict resolution. You need to choose a provider, that handles how document updates are distributed over the network.
@ -140,6 +138,8 @@ food.toJSON() // => { pancake: 10 }
Now you understand how types are defined on a shared document. Next you can jump to one of the [tutorials on our website](https://yjs.website/tutorial-prosemirror.html) or continue reading about [Providers](#Providers), [Shared Types](#Shared-Types), and [Bindings](#Bindings).
## API
## Providers
In Yjs, a provider handles the communication channel to *authenticate*, *authorize*, and *exchange document updates*. Yjs ships with some existing providers.

2
src/internals.js
View File

@ -30,4 +30,4 @@ export * from './structs/ItemJSON.js'
export * from './structs/ItemString.js'
export * from './structs/ItemType.js'
export * from './utils/structEncoding.js'
export * from './utils/encoding.js'

25
src/structs/AbstractItem.js
View File

@ -33,6 +33,8 @@ import * as binary from 'lib0/binary.js'
* @param {AbstractItem} leftItem
* @param {number} diff
* @return {AbstractItem}
* @function
* @private
*/
export const splitItem = (transaction, leftItem, diff) => {
const id = leftItem.id
@ -127,6 +129,7 @@ export class AbstractItem extends AbstractStruct {
/**
* @param {Transaction} transaction
* @private
*/
integrate (transaction) {
const store = transaction.y.store
@ -257,6 +260,8 @@ export class AbstractItem extends AbstractStruct {
* @param {AbstractType<any>} parent
* @param {string | null} parentSub
* @return {AbstractItem}
*
* @private
*/
copy (id, left, origin, right, rightOrigin, parent, parentSub) {
throw new Error('unimplemented')
@ -363,6 +368,8 @@ export class AbstractItem extends AbstractStruct {
* @param {Transaction} transaction
* @param {number} diff
* @return {AbstractItem}
*
* @private
*/
splitAt (transaction, diff) {
throw new Error('unimplemented')
@ -371,6 +378,8 @@ export class AbstractItem extends AbstractStruct {
/**
* @param {AbstractItem} right
* @return {boolean}
*
* @private
*/
mergeWith (right) {
if (compareIDs(right.origin, this.lastId) && this.right === right && compareIDs(this.rightOrigin, right.rightOrigin)) {
@ -386,8 +395,6 @@ export class AbstractItem extends AbstractStruct {
* Mark this Item as deleted.
*
* @param {Transaction} transaction
*
* @private
*/
delete (transaction) {
if (!this.deleted) {
@ -405,12 +412,16 @@ export class AbstractItem extends AbstractStruct {
/**
* @param {Transaction} transaction
* @param {StructStore} store
*
* @private
*/
gcChildren (transaction, store) { }
/**
* @param {Transaction} transaction
* @param {StructStore} store
*
* @private
*/
gc (transaction, store) {
let r
@ -449,6 +460,7 @@ export class AbstractItem extends AbstractStruct {
* @param {encoding.Encoder} encoder The encoder to write data to.
* @param {number} offset
* @param {number} encodingRef
*
* @private
*/
write (encoder, offset, encodingRef) {
@ -487,6 +499,9 @@ export class AbstractItem extends AbstractStruct {
}
}
/**
* @private
*/
export class AbstractItemRef extends AbstractStructRef {
/**
* @param {decoding.Decoder} decoder
@ -543,6 +558,9 @@ export class AbstractItemRef extends AbstractStructRef {
/**
* @param {AbstractItemRef} item
* @param {number} offset
*
* @function
* @private
*/
export const changeItemRefOffset = (item, offset) => {
item.id = createID(item.id.client, item.id.clock + offset)
@ -561,6 +579,9 @@ export const changeItemRefOffset = (item, offset) => {
* @param {string|null} parentSub
* @param {string|null} parentYKey
* @return {{left:AbstractItem?,right:AbstractItem?,parent:AbstractType<YEvent>?,parentSub:string?}}
*
* @private
* @function
*/
export const computeItemParams = (transaction, store, leftid, rightid, parentid, parentSub, parentYKey) => {
const left = leftid === null ? null : getItemCleanEnd(transaction, store, leftid)

7
src/structs/AbstractStruct.js
View File

@ -6,7 +6,9 @@ import {
import * as encoding from 'lib0/encoding.js' // eslint-disable-line
import * as error from 'lib0/error.js'
// eslint-disable-next-line
/**
* @private
*/
export class AbstractStruct {
/**
* @param {ID} id
@ -53,6 +55,9 @@ export class AbstractStruct {
}
}
/**
* @private
*/
export class AbstractStructRef {
/**
* @param {ID} id

10
src/structs/GC.js
View File

@ -1,6 +1,4 @@
/**
* @module structs
*/
import {
AbstractStructRef,
AbstractStruct,
@ -14,6 +12,9 @@ import * as encoding from 'lib0/encoding.js'
export const structGCRefNumber = 0
/**
* @private
*/
export class GC extends AbstractStruct {
/**
* @param {ID} id
@ -60,6 +61,9 @@ export class GC extends AbstractStruct {
}
}
/**
* @private
*/
export class GCRef extends AbstractStructRef {
/**
* @param {decoding.Decoder} decoder

12
src/structs/ItemBinary.js
View File

@ -1,6 +1,3 @@
/**
* @module structs
*/
import {
AbstractItem,
@ -13,8 +10,14 @@ import {
import * as encoding from 'lib0/encoding.js'
import * as decoding from 'lib0/decoding.js'
/**
* @private
*/
export const structBinaryRefNumber = 1
/**
* @private
*/
export class ItemBinary extends AbstractItem {
/**
* @param {ID} id
@ -55,6 +58,9 @@ export class ItemBinary extends AbstractItem {
}
}
/**
* @private
*/
export class ItemBinaryRef extends AbstractItemRef {
/**
* @param {decoding.Decoder} decoder

12
src/structs/ItemDeleted.js
View File

@ -1,6 +1,3 @@
/**
* @module structs
*/
import {
AbstractItem,
@ -16,8 +13,14 @@ import {
import * as encoding from 'lib0/encoding.js'
import * as decoding from 'lib0/decoding.js'
/**
* @private
*/
export const structDeletedRefNumber = 2
/**
* @private
*/
export class ItemDeleted extends AbstractItem {
/**
* @param {ID} id
@ -91,6 +94,9 @@ export class ItemDeleted extends AbstractItem {
}
}
/**
* @private
*/
export class ItemDeletedRef extends AbstractItemRef {
/**
* @param {decoding.Decoder} decoder

12
src/structs/ItemEmbed.js
View File

@ -1,6 +1,3 @@
/**
* @module structs
*/
import {
AbstractItem,
@ -13,8 +10,14 @@ import {
import * as encoding from 'lib0/encoding.js'
import * as decoding from 'lib0/decoding.js'
/**
* @private
*/
export const structEmbedRefNumber = 3
/**
* @private
*/
export class ItemEmbed extends AbstractItem {
/**
* @param {ID} id
@ -52,6 +55,9 @@ export class ItemEmbed extends AbstractItem {
}
}
/**
* @private
*/
export class ItemEmbedRef extends AbstractItemRef {
/**
* @param {decoding.Decoder} decoder

12
src/structs/ItemFormat.js
View File

@ -1,6 +1,3 @@
/**
* @module structs
*/
import {
AbstractItem,
@ -13,8 +10,14 @@ import {
import * as encoding from 'lib0/encoding.js'
import * as decoding from 'lib0/decoding.js'
/**
* @private
*/
export const structFormatRefNumber = 4
/**
* @private
*/
export class ItemFormat extends AbstractItem {
/**
* @param {ID} id
@ -58,6 +61,9 @@ export class ItemFormat extends AbstractItem {
}
}
/**
* @private
*/
export class ItemFormatRef extends AbstractItemRef {
/**
* @param {decoding.Decoder} decoder

12
src/structs/ItemJSON.js
View File

@ -1,6 +1,3 @@
/**
* @module structs
*/
import {
AbstractItem,
@ -15,8 +12,14 @@ import {
import * as encoding from 'lib0/encoding.js'
import * as decoding from 'lib0/decoding.js'
/**
* @private
*/
export const structJSONRefNumber = 5
/**
* @private
*/
export class ItemJSON extends AbstractItem {
/**
* @param {ID} id
@ -92,6 +95,9 @@ export class ItemJSON extends AbstractItem {
}
}
/**
* @private
*/
export class ItemJSONRef extends AbstractItemRef {
/**
* @param {decoding.Decoder} decoder

10
src/structs/ItemString.js
View File

@ -1,6 +1,4 @@
/**
* @module structs
*/
import {
AbstractItem,
AbstractItemRef,
@ -16,6 +14,9 @@ import * as decoding from 'lib0/decoding.js'
export const structStringRefNumber = 6
/**
* @private
*/
export class ItemString extends AbstractItem {
/**
* @param {ID} id
@ -88,6 +89,9 @@ export class ItemString extends AbstractItem {
}
}
/**
* @private
*/
export class ItemStringRef extends AbstractItemRef {
/**
* @param {decoding.Decoder} decoder

13
src/structs/ItemType.js
View File

@ -1,6 +1,3 @@
/**
* @module structs
*/
import {
AbstractItem,
@ -19,10 +16,14 @@ import {
import * as encoding from 'lib0/encoding.js' // eslint-disable-line
import * as decoding from 'lib0/decoding.js'
/**
* @private
*/
export const structTypeRefNumber = 7
/**
* @type {Array<function(decoding.Decoder):AbstractType<any>>}
* @private
*/
export const typeRefs = [
readYArray,
@ -42,6 +43,9 @@ export const YXmlFragmentRefID = 4
export const YXmlHookRefID = 5
export const YXmlTextRefID = 6
/**
* @private
*/
export class ItemType extends AbstractItem {
/**
* @param {ID} id
@ -133,6 +137,9 @@ export class ItemType extends AbstractItem {
}
}
/**
* @private
*/
export class ItemTypeRef extends AbstractItemRef {
/**
* @param {decoding.Decoder} decoder

61
src/types/AbstractType.js
View File

@ -1,6 +1,3 @@
/**
* @module structs
*/
import {
removeEventHandlerListener,
@ -101,6 +98,7 @@ export class AbstractType {
/**
* @return {AbstractType<EventType>}
* @private
*/
_copy () {
throw new Error('unimplemented')
@ -108,6 +106,7 @@ export class AbstractType {
/**
* @param {encoding.Encoder} encoder
* @private
*/
_write (encoder) { }
@ -125,10 +124,11 @@ export class AbstractType {
/**
* Creates YEvent and calls all type observers.
* Must be implemented by each type.
* @private
*
* @param {Transaction} transaction
* @param {Set<null|string>} parentSubs Keys changed on this type. `null` if list was modified.
*
* @private
*/
_callObserver (transaction, parentSubs) { /* skip if no type is specified */ }
@ -178,6 +178,9 @@ export class AbstractType {
/**
* @param {AbstractType<any>} type
* @return {Array<any>}
*
* @private
* @function
*/
export const typeArrayToArray = type => {
const cs = []
@ -199,6 +202,9 @@ export const typeArrayToArray = type => {
*
* @param {AbstractType<any>} type
* @param {function(any,number,AbstractType<any>):void} f A function to execute on every element of this YArray.
*
* @private
* @function
*/
export const typeArrayForEach = (type, f) => {
let index = 0
@ -219,6 +225,9 @@ export const typeArrayForEach = (type, f) => {
* @param {AbstractType<any>} type
* @param {function(C,number,AbstractType<any>):R} f
* @return {Array<R>}
*
* @private
* @function
*/
export const typeArrayMap = (type, f) => {
/**
@ -233,7 +242,10 @@ export const typeArrayMap = (type, f) => {
/**
* @param {AbstractType<any>} type
* @return {{next:function():{done:boolean,value:any|undefined}}}
* @return {IterableIterator<any>}
*
* @private
* @function
*/
export const typeArrayCreateIterator = type => {
let n = type._start
@ -243,6 +255,9 @@ export const typeArrayCreateIterator = type => {
let currentContent = null
let currentContentIndex = 0
return {
[Symbol.iterator] () {
return this
},
next: () => {
// find some content
if (currentContent === null) {
@ -284,6 +299,9 @@ export const typeArrayCreateIterator = type => {
* @param {AbstractType<any>} type
* @param {function(any,number,AbstractType<any>):void} f A function to execute on every element of this YArray.
* @param {Snapshot} snapshot
*
* @private
* @function
*/
export const typeArrayForEachSnapshot = (type, f, snapshot) => {
let index = 0
@ -303,6 +321,9 @@ export const typeArrayForEachSnapshot = (type, f, snapshot) => {
* @param {AbstractType<any>} type
* @param {number} index
* @return {any}
*
* @private
* @function
*/
export const typeArrayGet = (type, index) => {
for (let n = type._start; n !== null; n = n.right) {
@ -320,6 +341,9 @@ export const typeArrayGet = (type, index) => {
* @param {AbstractType<any>} parent
* @param {AbstractItem?} referenceItem
* @param {Array<Object<string,any>|Array<any>|number|string|ArrayBuffer>} content
*
* @private
* @function
*/
export const typeArrayInsertGenericsAfter = (transaction, parent, referenceItem, content) => {
let left = referenceItem
@ -370,6 +394,9 @@ export const typeArrayInsertGenericsAfter = (transaction, parent, referenceItem,
* @param {AbstractType<any>} parent
* @param {number} index
* @param {Array<Object<string,any>|Array<any>|number|string|ArrayBuffer>} content
*
* @private
* @function
*/
export const typeArrayInsertGenerics = (transaction, parent, index, content) => {
if (index === 0) {
@ -396,6 +423,9 @@ export const typeArrayInsertGenerics = (transaction, parent, index, content) =>
* @param {AbstractType<any>} parent
* @param {number} index
* @param {number} length
*
* @private
* @function
*/
export const typeArrayDelete = (transaction, parent, index, length) => {
if (length === 0) { return }
@ -432,6 +462,9 @@ export const typeArrayDelete = (transaction, parent, index, length) => {
* @param {Transaction} transaction
* @param {AbstractType<any>} parent
* @param {string} key
*
* @private
* @function
*/
export const typeMapDelete = (transaction, parent, key) => {
const c = parent._map.get(key)
@ -445,6 +478,9 @@ export const typeMapDelete = (transaction, parent, key) => {
* @param {AbstractType<any>} parent
* @param {string} key
* @param {Object|number|Array<any>|string|ArrayBuffer|AbstractType<any>} value
*
* @private
* @function
*/
export const typeMapSet = (transaction, parent, key, value) => {
const left = parent._map.get(key) || null
@ -475,6 +511,9 @@ export const typeMapSet = (transaction, parent, key, value) => {
* @param {AbstractType<any>} parent
* @param {string} key
* @return {Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|undefined}
*
* @private
* @function
*/
export const typeMapGet = (parent, key) => {
const val = parent._map.get(key)
@ -484,6 +523,9 @@ export const typeMapGet = (parent, key) => {
/**
* @param {AbstractType<any>} parent
* @return {Object<string,Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|undefined>}
*
* @private
* @function
*/
export const typeMapGetAll = (parent) => {
/**
@ -502,6 +544,9 @@ export const typeMapGetAll = (parent) => {
* @param {AbstractType<any>} parent
* @param {string} key
* @return {boolean}
*
* @private
* @function
*/
export const typeMapHas = (parent, key) => {
const val = parent._map.get(key)
@ -513,6 +558,9 @@ export const typeMapHas = (parent, key) => {
* @param {string} key
* @param {Snapshot} snapshot
* @return {Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|undefined}
*
* @private
* @function
*/
export const typeMapGetSnapshot = (parent, key, snapshot) => {
let v = parent._map.get(key) || null
@ -525,5 +573,8 @@ export const typeMapGetSnapshot = (parent, key, snapshot) => {
/**
* @param {Map<string,AbstractItem>} map
* @return {Iterator<[string,AbstractItem]>}
*
* @private
* @function
*/
export const createMapIterator = map => iterator.iteratorFilter(map.entries(), entry => !entry[1].deleted)

15
src/types/YArray.js
View File

@ -1,5 +1,5 @@
/**
* @module types
* @module YArray
*/
import {
@ -40,12 +40,14 @@ export class YArrayEvent extends YEvent {
* A shared Array implementation.
* @template T
* @extends AbstractType<YArrayEvent<T>>
* @implements {IterableIterator<T>}
*/
export class YArray extends AbstractType {
constructor () {
super()
/**
* @type {Array<any>?}
* @private
*/
this._prelimContent = []
}
@ -58,6 +60,7 @@ export class YArray extends AbstractType {
*
* @param {Y} y The Yjs instance
* @param {ItemType} item
*
* @private
*/
_integrate (y, item) {
@ -71,10 +74,11 @@ export class YArray extends AbstractType {
}
/**
* Creates YArrayEvent and calls observers.
* @private
*
* @param {Transaction} transaction
* @param {Set<null|string>} parentSubs Keys changed on this type. `null` if list was modified.
*
* @private
*/
_callObserver (transaction, parentSubs) {
callTypeObservers(this, transaction, new YArrayEvent(this, transaction))
@ -131,6 +135,9 @@ export class YArray extends AbstractType {
typeArrayForEach(this, f)
}
/**
* @return {IterableIterator<T>}
*/
[Symbol.iterator] () {
return typeArrayCreateIterator(this)
}
@ -190,6 +197,7 @@ export class YArray extends AbstractType {
/**
* @param {encoding.Encoder} encoder
* @private
*/
_write (encoder) {
encoding.writeVarUint(encoder, YArrayRefID)
@ -198,5 +206,8 @@ export class YArray extends AbstractType {
/**
* @param {decoding.Decoder} decoder
*
* @private
* @function
*/
export const readYArray = decoder => new YArray()

19
src/types/YMap.js
View File

@ -1,5 +1,6 @@
/**
* @module types
* @module YMap
*/
import {
@ -41,12 +42,14 @@ export class YMapEvent extends YEvent {
* A shared Map implementation.
*
* @extends AbstractType<YMapEvent<T>>
* @implements {IterableIterator}
*/
export class YMap extends AbstractType {
constructor () {
super()
/**
* @type {Map<string,any>?}
* @private
*/
this._prelimContent = new Map()
}
@ -59,6 +62,7 @@ export class YMap extends AbstractType {
*
* @param {Y} y The Yjs instance
* @param {ItemType} item
*
* @private
*/
_integrate (y, item) {
@ -71,10 +75,11 @@ export class YMap extends AbstractType {
}
/**
* Creates YMapEvent and calls observers.
* @private
*
* @param {Transaction} transaction
* @param {Set<null|string>} parentSubs Keys changed on this type. `null` if list was modified.
*
* @private
*/
_callObserver (transaction, parentSubs) {
callTypeObservers(this, transaction, new YMapEvent(this, transaction, parentSubs))
@ -110,12 +115,15 @@ export class YMap extends AbstractType {
/**
* Returns the value for each element in the YMap Type.
*
* @return {Iterator<T>}
* @return {IterableIterator<T>}
*/
entries () {
return iterator.iteratorMap(createMapIterator(this._map), v => v[1].getContent()[0])
}
/**
* @return {IterableIterator<T>}
*/
[Symbol.iterator] () {
return this.entries()
}
@ -177,6 +185,8 @@ export class YMap extends AbstractType {
/**
* @param {encoding.Encoder} encoder
*
* @private
*/
_write (encoder) {
encoding.writeVarUint(encoder, YMapRefID)
@ -185,5 +195,8 @@ export class YMap extends AbstractType {
/**
* @param {decoding.Decoder} decoder
*
* @private
* @function
*/
export const readYMap = decoder => new YMap()

53
src/types/YText.js
View File

@ -1,5 +1,6 @@
/**
* @module types
* @module YText
*/
import {
@ -22,7 +23,6 @@ import * as decoding from 'lib0/decoding.js' // eslint-disable-line
import * as encoding from 'lib0/encoding.js'
/**
* @private
* @param {Transaction} transaction
* @param {StructStore} store
* @param {Map<string,any>} currentAttributes
@ -30,6 +30,9 @@ import * as encoding from 'lib0/encoding.js'
* @param {AbstractItem|null} right
* @param {number} count
* @return {{left:AbstractItem|null,right:AbstractItem|null,currentAttributes:Map<string,any>}}
*
* @private
* @function
*/
const findNextPosition = (transaction, store, currentAttributes, left, right, count) => {
while (right !== null && count > 0) {
@ -58,12 +61,14 @@ const findNextPosition = (transaction, store, currentAttributes, left, right, co
}
/**
* @private
* @param {Transaction} transaction
* @param {StructStore} store
* @param {AbstractType<any>} parent
* @param {number} index
* @return {{left:AbstractItem|null,right:AbstractItem|null,currentAttributes:Map<string,any>}}
*
* @private
* @function
*/
const findPosition = (transaction, store, parent, index) => {
let currentAttributes = new Map()
@ -75,13 +80,15 @@ const findPosition = (transaction, store, parent, index) => {
/**
* Negate applied formats
*
* @private
* @param {Transaction} transaction
* @param {AbstractType<any>} parent
* @param {AbstractItem|null} left
* @param {AbstractItem|null} right
* @param {Map<string,any>} negatedAttributes
* @return {{left:AbstractItem|null,right:AbstractItem|null}}
*
* @private
* @function
*/
const insertNegatedAttributes = (transaction, parent, left, right, negatedAttributes) => {
// check if we really need to remove attributes
@ -109,9 +116,11 @@ const insertNegatedAttributes = (transaction, parent, left, right, negatedAttrib
}
/**
* @private
* @param {Map<string,any>} currentAttributes
* @param {ItemFormat} item
*
* @private
* @function
*/
const updateCurrentAttributes = (currentAttributes, item) => {
const value = item.value
@ -124,12 +133,14 @@ const updateCurrentAttributes = (currentAttributes, item) => {
}
/**
* @private
* @param {AbstractItem|null} left
* @param {AbstractItem|null} right
* @param {Map<string,any>} currentAttributes
* @param {Object<string,any>} attributes
* @return {{left:AbstractItem|null,right:AbstractItem|null}}
*
* @private
* @function
*/
const minimizeAttributeChanges = (left, right, currentAttributes, attributes) => {
// go right while attributes[right.key] === right.value (or right is deleted)
@ -153,7 +164,6 @@ const minimizeAttributeChanges = (left, right, currentAttributes, attributes) =>
}
/**
* @private
* @param {Transaction} transaction
* @param {AbstractType<any>} parent
* @param {AbstractItem|null} left
@ -161,6 +171,9 @@ const minimizeAttributeChanges = (left, right, currentAttributes, attributes) =>
* @param {Map<string,any>} currentAttributes
* @param {Object<string,any>} attributes
* @return {{left:AbstractItem|null,right:AbstractItem|null,negatedAttributes:Map<string,any>}}
*
* @private
* @function
**/
const insertAttributes = (transaction, parent, left, right, currentAttributes, attributes) => {
const negatedAttributes = new Map()
@ -179,7 +192,6 @@ const insertAttributes = (transaction, parent, left, right, currentAttributes, a
}
/**
* @private
* @param {Transaction} transaction
* @param {AbstractType<any>} parent
* @param {AbstractItem|null} left
@ -188,6 +200,9 @@ const insertAttributes = (transaction, parent, left, right, currentAttributes, a
* @param {string} text
* @param {Object<string,any>} attributes
* @return {{left:AbstractItem|null,right:AbstractItem|null}}
*
* @private
* @function
**/
const insertText = (transaction, parent, left, right, currentAttributes, text, attributes) => {
for (let [key] of currentAttributes) {
@ -210,7 +225,6 @@ const insertText = (transaction, parent, left, right, currentAttributes, text, a
}
/**
* @private
* @param {Transaction} transaction
* @param {AbstractType<any>} parent
* @param {AbstractItem|null} left
@ -219,6 +233,9 @@ const insertText = (transaction, parent, left, right, currentAttributes, text, a
* @param {number} length
* @param {Object<string,any>} attributes
* @return {{left:AbstractItem|null,right:AbstractItem|null}}
*
* @private
* @function
*/
const formatText = (transaction, parent, left, right, currentAttributes, length, attributes) => {
const minPos = minimizeAttributeChanges(left, right, currentAttributes, attributes)
@ -264,7 +281,6 @@ const formatText = (transaction, parent, left, right, currentAttributes, length,
}
/**
* @private
* @param {Transaction} transaction
* @param {AbstractType<any>} parent
* @param {AbstractItem|null} left
@ -272,6 +288,9 @@ const formatText = (transaction, parent, left, right, currentAttributes, length,
* @param {Map<string,any>} currentAttributes
* @param {number} length
* @return {{left:AbstractItem|null,right:AbstractItem|null}}
*
* @private
* @function
*/
const deleteText = (transaction, parent, left, right, currentAttributes, length) => {
while (length > 0 && right !== null) {
@ -326,8 +345,6 @@ const deleteText = (transaction, parent, left, right, currentAttributes, length)
/**
* Event that describes the changes on a YText type.
*
* @private
*/
class YTextEvent extends YEvent {
/**
@ -337,6 +354,7 @@ class YTextEvent extends YEvent {
constructor (ytext, transaction) {
super(ytext, transaction)
/**
* @private
* @type {Array<{delete:number|undefined,retain:number|undefined,insert:string|undefined,attributes:Object<string,any>}>|null}
*/
this._delta = null
@ -558,6 +576,7 @@ export class YText extends AbstractType {
super()
/**
* @type {Array<string>?}
* @private
*/
this._prelimContent = string !== undefined ? [string] : []
}
@ -569,6 +588,8 @@ export class YText extends AbstractType {
/**
* @param {Y} y
* @param {ItemType} item
*
* @private
*/
_integrate (y, item) {
super._integrate(y, item)
@ -579,10 +600,11 @@ export class YText extends AbstractType {
/**
* Creates YTextEvent and calls observers.
* @private
*
* @param {Transaction} transaction
* @param {Set<null|string>} parentSubs Keys changed on this type. `null` if list was modified.
*
* @private
*/
_callObserver (transaction, parentSubs) {
callTypeObservers(this, transaction, new YTextEvent(this, transaction))
@ -847,6 +869,8 @@ export class YText extends AbstractType {
/**
* @param {encoding.Encoder} encoder
*
* @private
*/
_write (encoder) {
encoding.writeVarUint(encoder, YTextRefID)
@ -856,5 +880,8 @@ export class YText extends AbstractType {
/**
* @param {decoding.Decoder} decoder
* @return {YText}
*
* @private
* @function
*/
export const readYText = decoder => new YText()

12
src/types/YXmlElement.js
View File

@ -1,5 +1,5 @@
/**
* @module types
* @module YXml
*/
import {
@ -50,6 +50,7 @@ import * as decoding from 'lib0/decoding.js'
* Can be created with {@link YXmlFragment#createTreeWalker}
*
* @public
* @implements {IterableIterator}
*/
export class YXmlTreeWalker {
/**
@ -66,6 +67,7 @@ export class YXmlTreeWalker {
this._currentNode = root._start
this._firstCall = true
}
[Symbol.iterator] () {
return this
}
@ -250,10 +252,12 @@ export class YXmlElement extends YXmlFragment {
this.nodeName = nodeName.toUpperCase()
/**
* @type {Array<any>|null}
* @private
*/
this._prelimContent = []
/**
* @type {Map<string, any>|null}
* @private
*/
this._prelimAttrs = new Map()
}
@ -471,10 +475,16 @@ export class YXmlElement extends YXmlFragment {
/**
* @param {decoding.Decoder} decoder
* @return {YXmlElement}
*
* @private
* @function
*/
export const readYXmlElement = decoder => new YXmlElement(decoding.readVarString(decoder))
/**
* @param {decoding.Decoder} decoder
* @return {YXmlFragment}
*
* @private
* @function
*/
export const readYXmlFragment = decoder => new YXmlFragment()

11
src/types/YXmlEvent.js
View File

@ -1,6 +1,3 @@
/**
* @module types
*/
import {
YEvent,
@ -9,8 +6,6 @@ import {
/**
* An Event that describes changes on a YXml Element or Yxml Fragment
*
* @protected
*/
export class YXmlEvent extends YEvent {
/**
@ -22,14 +17,10 @@ export class YXmlEvent extends YEvent {
*/
constructor (target, subs, transaction) {
super(target, transaction)
/**
* The transaction instance for the computed change.
* @type {Transaction}
*/
this._transaction = transaction
/**
* Whether the children changed.
* @type {Boolean}
* @private
*/
this.childListChanged = false
/**

9
src/types/YXmlHook.js
View File

@ -1,6 +1,3 @@
/**
* @module types
*/
import {
YMap,
@ -20,6 +17,9 @@ export class YXmlHook extends YMap {
*/
constructor (hookName) {
super()
/**
* @type {string}
*/
this.hookName = hookName
}
@ -82,6 +82,9 @@ export class YXmlHook extends YMap {
/**
* @param {decoding.Decoder} decoder
* @return {YXmlHook}
*
* @private
* @function
*/
export const readYXmlHook = decoder =>
new YXmlHook(decoding.readVarString(decoder))

8
src/types/YXmlText.js
View File

@ -1,6 +1,3 @@
/**
* @module types
*/
import { YText, YXmlTextRefID } from '../internals.js'
@ -36,6 +33,8 @@ export class YXmlText extends YText {
}
/**
* @param {encoding.Encoder} encoder
*
* @private
*/
_write (encoder) {
encoding.writeVarUint(encoder, YXmlTextRefID)
@ -45,5 +44,8 @@ export class YXmlText extends YText {
/**
* @param {decoding.Decoder} decoder
* @return {YXmlText}
*
* @private
* @function
*/
export const readYXmlText = decoder => new YXmlText()

26
src/utils/DeleteSet.js
View File

@ -11,6 +11,9 @@ import * as map from 'lib0/map.js'
import * as encoding from 'lib0/encoding.js'
import * as decoding from 'lib0/decoding.js'
/**
* @private
*/
class DeleteItem {
/**
* @param {number} clock
@ -35,11 +38,13 @@ class DeleteItem {
* - We do not create a DeleteSet when we send a sync message. The DeleteSet message is created directly from StructStore
* - We read a DeleteSet as part of a sync/update message. In this case the DeleteSet is already sorted and merged.
*
* @private
*/
export class DeleteSet {
constructor () {
/**
* @type {Map<number,Array<DeleteItem>>}
* @private
*/
this.clients = new Map()
}
@ -49,6 +54,9 @@ export class DeleteSet {
* @param {Array<DeleteItem>} dis
* @param {number} clock
* @return {number|null}
*
* @private
* @function
*/
export const findIndexDS = (dis, clock) => {
let left = 0
@ -73,6 +81,9 @@ export const findIndexDS = (dis, clock) => {
* @param {DeleteSet} ds
* @param {ID} id
* @return {boolean}
*
* @private
* @function
*/
export const isDeleted = (ds, id) => {
const dis = ds.clients.get(id.client)
@ -81,6 +92,9 @@ export const isDeleted = (ds, id) => {
/**
* @param {DeleteSet} ds
*
* @private
* @function
*/
export const sortAndMergeDeleteSet = ds => {
ds.clients.forEach(dels => {
@ -110,6 +124,9 @@ export const sortAndMergeDeleteSet = ds => {
* @param {DeleteSet} ds
* @param {ID} id
* @param {number} length
*
* @private
* @function
*/
export const addToDeleteSet = (ds, id, length) => {
map.setIfUndefined(ds.clients, id.client, () => []).push(new DeleteItem(id.clock, length))
@ -118,6 +135,9 @@ export const addToDeleteSet = (ds, id, length) => {
/**
* @param {StructStore} ss
* @return {DeleteSet} Merged and sorted DeleteSet
*
* @private
* @function
*/
export const createDeleteSetFromStructStore = ss => {
const ds = new DeleteSet()
@ -149,6 +169,9 @@ export const createDeleteSetFromStructStore = ss => {
/**
* @param {encoding.Encoder} encoder
* @param {DeleteSet} ds
*
* @private
* @function
*/
export const writeDeleteSet = (encoder, ds) => {
encoding.writeVarUint(encoder, ds.clients.size)
@ -168,6 +191,9 @@ export const writeDeleteSet = (encoder, ds) => {
* @param {decoding.Decoder} decoder
* @param {Transaction} transaction
* @param {StructStore} store
*
* @private
* @function
*/
export const readDeleteSet = (decoder, transaction, store) => {
const unappliedDS = new DeleteSet()

17
src/utils/EventHandler.js
View File

@ -4,6 +4,8 @@ import * as f from 'lib0/function.js'
* General event handler implementation.
*
* @template ARG0, ARG1
*
* @private
*/
export class EventHandler {
constructor () {
@ -17,6 +19,9 @@ export class EventHandler {
/**
* @template ARG0,ARG1
* @returns {EventHandler<ARG0,ARG1>}
*
* @private
* @function
*/
export const createEventHandler = () => new EventHandler()
@ -27,6 +32,9 @@ export const createEventHandler = () => new EventHandler()
* @template ARG0,ARG1
* @param {EventHandler<ARG0,ARG1>} eventHandler
* @param {function(ARG0,ARG1):void} f The event handler.
*
* @private
* @function
*/
export const addEventHandlerListener = (eventHandler, f) =>
eventHandler.l.push(f)
@ -38,6 +46,9 @@ export const addEventHandlerListener = (eventHandler, f) =>
* @param {EventHandler<ARG0,ARG1>} eventHandler
* @param {function(ARG0,ARG1):void} f The event handler that was added with
* {@link EventHandler#addEventListener}
*
* @private
* @function
*/
export const removeEventHandlerListener = (eventHandler, f) => {
eventHandler.l = eventHandler.l.filter(g => f !== g)
@ -47,6 +58,9 @@ export const removeEventHandlerListener = (eventHandler, f) => {
* Removes all event listeners.
* @template ARG0,ARG1
* @param {EventHandler<ARG0,ARG1>} eventHandler
*
* @private
* @function
*/
export const removeAllEventHandlerListeners = eventHandler => {
eventHandler.l.length = 0
@ -59,6 +73,9 @@ export const removeAllEventHandlerListeners = eventHandler => {
* @template ARG0,ARG1
* @param {EventHandler<ARG0,ARG1>} eventHandler
* @param {[ARG0,ARG1]} args
*
* @private
* @function
*/
export const callEventHandlerListeners = (eventHandler, args) =>
f.callAll(eventHandler.l, args)

17
src/utils/ID.js
View File

@ -1,6 +1,3 @@
/**
* @module utils
*/
import { AbstractType } from '../internals' // eslint-disable-line
@ -41,18 +38,26 @@ export class ID {
* @param {ID | null} a
* @param {ID | null} b
* @return {boolean}
*
* @function
*/
export const compareIDs = (a, b) => a === b || (a !== null && b !== null && a.client === b.client && a.clock === b.clock)
/**
* @param {number} client
* @param {number} clock
*
* @private
* @function
*/
export const createID = (client, clock) => new ID(client, clock)
/**
* @param {encoding.Encoder} encoder
* @param {ID} id
*
* @private
* @function
*/
export const writeID = (encoder, id) => {
encoding.writeVarUint(encoder, id.client)
@ -66,6 +71,9 @@ export const writeID = (encoder, id) => {
*
* @param {decoding.Decoder} decoder
* @return {ID}
*
* @private
* @function
*/
export const readID = decoder =>
createID(decoding.readVarUint(decoder), decoding.readVarUint(decoder))
@ -77,6 +85,9 @@ export const readID = decoder =>
*
* @param {AbstractType<any>} type
* @return {string}
*
* @private
* @function
*/
export const findRootTypeKey = type => {
// @ts-ignore _y must be defined, otherwise unexpected case

19
src/utils/Snapshot.js
View File

@ -10,17 +10,34 @@ export class Snapshot {
* @param {DeleteSet} ds delete store
* @param {Map<number,number>} sm state map
* @param {Map<number,string>} userMap
* @private
*/
constructor (ds, sm, userMap) {
/**
* @type {DeleteSet}
* @private
*/
this.ds = new DeleteSet()
/**
* State Map
* @type {Map<number,number>}
* @private
*/
this.sm = sm
/**
* @type {Map<number,string>}
* @private
*/
this.userMap = userMap
}
}
/**
* @param {AbstractItem} item
* @param {Snapshot} [snapshot]
* @param {Snapshot|undefined} snapshot
*
* @protected
* @function
*/
export const isVisible = (item, snapshot) => snapshot === undefined ? !item.deleted : (
snapshot.sm.has(item.id.client) && (snapshot.sm.get(item.id.client) || 0) > item.id.clock && !isDeleted(snapshot.ds, item.id)

41
src/utils/StructStore.js
View File

@ -13,6 +13,7 @@ export class StructStore {
constructor () {
/**
* @type {Map<number,Array<AbstractStruct>>}
* @private
*/
this.clients = new Map()
/**
@ -22,16 +23,19 @@ export class StructStore {
* slow in Chrome for arrays with more than 100k elements
* @see tryResumePendingStructRefs
* @type {Map<number,{i:number,refs:Array<AbstractStructRef>}>}
* @private
*/
this.pendingClientsStructRefs = new Map()
/**
* Stack of pending structs waiting for struct dependencies
* Maximum length of stack is structReaders.size
* @type {Array<AbstractStructRef>}
* @private
*/
this.pendingStack = []
/**
* @type {Array<decoding.Decoder>}
* @private
*/
this.pendingDeleteReaders = []
}
@ -43,6 +47,9 @@ export class StructStore {
*
* @param {StructStore} store
* @return {Map<number,number>}
*
* @public
* @function
*/
export const getStates = store => {
const sm = new Map()
@ -56,6 +63,10 @@ export const getStates = store => {
/**
* @param {StructStore} store
* @param {number} client
* @return {number}
*
* @public
* @function
*/
export const getState = (store, client) => {
const structs = store.clients.get(client)
@ -68,6 +79,9 @@ export const getState = (store, client) => {
/**
* @param {StructStore} store
*
* @private
* @function
*/
export const integretyCheck = store => {
store.clients.forEach(structs => {
@ -84,6 +98,9 @@ export const integretyCheck = store => {
/**
* @param {StructStore} store
* @param {AbstractStruct} struct
*
* @private
* @function
*/
export const addStruct = (store, struct) => {
let structs = store.clients.get(struct.id.client)
@ -104,7 +121,9 @@ export const addStruct = (store, struct) => {
* @param {Array<any>} structs
* @param {number} clock
* @return {number}
*
* @private
* @function
*/
export const findIndexSS = (structs, clock) => {
let left = 0
@ -133,7 +152,9 @@ export const findIndexSS = (structs, clock) => {
* @param {StructStore} store
* @param {ID} id
* @return {AbstractStruct}
*
* @private
* @function
*/
export const find = (store, id) => {
/**
@ -150,6 +171,9 @@ export const find = (store, id) => {
* @param {StructStore} store
* @param {ID} id
* @return {AbstractItem}
*
* @private
* @function
*/
// @ts-ignore
export const getItem = (store, id) => find(store, id)
@ -160,6 +184,9 @@ export const getItem = (store, id) => find(store, id)
* @param {StructStore} store
* @param {ID} id
* @return {ItemType}
*
* @private
* @function
*/
// @ts-ignore
export const getItemType = (store, id) => find(store, id)
@ -173,6 +200,7 @@ export const getItemType = (store, id) => find(store, id)
* @return {AbstractItem}
*
* @private
* @function
*/
export const getItemCleanStart = (transaction, store, id) => {
/**
@ -201,6 +229,7 @@ export const getItemCleanStart = (transaction, store, id) => {
* @return {AbstractItem}
*
* @private
* @function
*/
export const getItemCleanEnd = (transaction, store, id) => {
/**
@ -221,6 +250,9 @@ export const getItemCleanEnd = (transaction, store, id) => {
* @param {StructStore} store
* @param {AbstractStruct} struct
* @param {AbstractStruct} newStruct
*
* @private
* @function
*/
export const replaceStruct = (store, struct, newStruct) => {
/**
@ -235,6 +267,9 @@ export const replaceStruct = (store, struct, newStruct) => {
* @param {StructStore} store
* @param {ID} id
* @return {boolean}
*
* @private
* @function
*/
export const exists = (store, id) => id.clock < getState(store, id.client)
@ -243,6 +278,9 @@ export const exists = (store, id) => id.clock < getState(store, id.client)
*
* @param {decoding.Decoder} decoder
* @return {Map<number,number>}
*
* @private
* @function
*/
export const readStatesAsMap = decoder => {
const ss = new Map()
@ -260,6 +298,9 @@ export const readStatesAsMap = decoder => {
*
* @param {encoding.Encoder} encoder
* @param {StructStore} store
*
* @private
* @function
*/
export const writeStates = (encoder, store) => {
encoding.writeVarUint(encoder, store.clients.size)

13
src/utils/Transaction.js
View File

@ -1,6 +1,3 @@
/**
* @module utils
*/
import {
getState,
@ -43,6 +40,7 @@ import * as math from 'lib0/math.js'
* map.set('b', 1)
* }) // => "change triggered"
*
* @public
*/
export class Transaction {
/**
@ -84,15 +82,18 @@ export class Transaction {
this.changedParentTypes = new Map()
/**
* @type {encoding.Encoder|null}
* @private
*/
this._updateMessage = null
/**
* @type {Set<ID>}
* @private
*/
this._mergeStructs = new Set()
}
/**
* @type {encoding.Encoder|null}
* @public
*/
get updateMessage () {
// only create if content was added in transaction (state or ds changed)
@ -109,6 +110,9 @@ export class Transaction {
/**
* @param {Transaction} transaction
*
* @private
* @function
*/
export const nextID = transaction => {
const y = transaction.y
@ -120,6 +124,9 @@ export const nextID = transaction => {
*
* @param {Y} y
* @param {function(Transaction):void} f
*
* @private
* @function
*/
export const transact = (y, f) => {
let initialCall = false

19
src/utils/UndoManager.js
View File

@ -6,6 +6,9 @@ import {
transact
} from '../internals.js'
/**
* @private
*/
class ReverseOperation {
constructor (y, transaction, bindingInfos) {
this.created = new Date()
@ -31,6 +34,10 @@ class ReverseOperation {
}
}
/**
* @private
* @function
*/
function applyReverseOperation (y, scope, reverseBuffer) {
let performedUndo = false
let undoOp = null
@ -90,6 +97,9 @@ function applyReverseOperation (y, scope, reverseBuffer) {
/**
* Saves a history of locally applied operations. The UndoManager handles the
* undoing and redoing of locally created changes.
*
* @private
* @function
*/
export class UndoManager {
/**
@ -156,6 +166,9 @@ export class UndoManager {
/**
* Enforce that the next change is created as a separate item in the undo stack
*
* @private
* @function
*/
flushChanges () {
this._lastTransactionWasUndo = true
@ -163,6 +176,9 @@ export class UndoManager {
/**
* Undo the last locally created change.
*
* @private
* @function
*/
undo () {
this._undoing = true
@ -173,6 +189,9 @@ export class UndoManager {
/**
* Redo the last locally created change.
*
* @private
* @function
*/
redo () {
this._redoing = true

35
src/utils/Y.js
View File

@ -1,3 +1,7 @@
/**
* @module Y
*/
import {
StructStore,
AbstractType,
@ -10,7 +14,6 @@ import {
} from '../internals.js'
import { Observable } from 'lib0/observable.js'
import * as error from 'lib0/error.js'
import * as random from 'lib0/random.js'
import * as map from 'lib0/map.js'
@ -20,11 +23,10 @@ import * as map from 'lib0/map.js'
*/
export class Y extends Observable {
/**
* @param {Object} [conf] configuration
* @param {Object|undefined} conf configuration
*/
constructor (conf = {}) {
super()
this.gcEnabled = conf.gc || false
this.clientID = random.uint32()
/**
* @type {Map<string, AbstractType<YEvent>>}
@ -33,19 +35,10 @@ export class Y extends Observable {
this.store = new StructStore()
/**
* @type {Transaction | null}
* @private
*/
this._transaction = null
}
/**
* @type {Transaction}
*/
get transaction () {
const t = this._transaction
if (t === null) {
throw error.create('All changes must happen inside a transaction')
}
return t
}
/**
* Changes that happen inside of a transaction are bundled. This means that
* the observer fires _after_ the transaction is finished and that all changes
@ -53,6 +46,8 @@ export class Y extends Observable {
* other peers.
*
* @param {function(Transaction):void} f The function that should be executed as a transaction
*
* @public
*/
transact (f) {
transact(this, f)
@ -80,6 +75,8 @@ export class Y extends Observable {
* @param {string} name
* @param {Function} TypeConstructor The constructor of the type definition
* @return {AbstractType<any>} The created type. Constructed with TypeConstructor
*
* @public
*/
get (name, TypeConstructor = AbstractType) {
const type = map.setIfUndefined(this.share, name, () => {
@ -108,6 +105,8 @@ export class Y extends Observable {
* @template T
* @param {string} name
* @return {YArray<T>}
*
* @public
*/
getArray (name) {
// @ts-ignore
@ -116,6 +115,8 @@ export class Y extends Observable {
/**
* @param {string} name
* @return {YText}
*
* @public
*/
getText (name) {
// @ts-ignore
@ -124,6 +125,8 @@ export class Y extends Observable {
/**
* @param {string} name
* @return {YMap<any>}
*
* @public
*/
getMap (name) {
// @ts-ignore
@ -132,13 +135,17 @@ export class Y extends Observable {
/**
* @param {string} name
* @return {YXmlFragment}
*
* @public
*/
getXmlFragment (name) {
// @ts-ignore
return this.get(name, YXmlFragment)
}
/**
* Disconnect from the room, and destroy all traces of this Yjs instance.
* Emit `destroy` event and unregister all event handlers.
*
* @protected
*/
destroy () {
this.emit('destroyed', [true])

9
src/utils/YEvent.js
View File

@ -1,13 +1,9 @@
import {
isDeleted,
AbstractItem, AbstractType, Transaction, AbstractStruct // eslint-disable-line
AbstractType, Transaction, AbstractStruct // eslint-disable-line
} from '../internals.js'
/**
* @module utils
*/
/**
* YEvent describes the changes on a YType.
*/
@ -84,6 +80,9 @@ export class YEvent {
* @param {AbstractType<any>} parent
* @param {AbstractType<any>} child target
* @return {Array<string|number>} Path to the target
*
* @private
* @function
*/
const getPathTo = (parent, child) => {
const path = []

47
src/utils/structEncoding.js → src/utils/encoding.js
View File

@ -1,4 +1,8 @@
/**
* @module encoding
*/
import {
findIndexSS,
exists,
@ -26,9 +30,8 @@ import * as decoding from 'lib0/decoding.js'
import * as binary from 'lib0/binary.js'
/**
* @typedef {Map<number, number>} StateMap
* @private
*/
export const structRefs = [
GCRef,
ItemBinaryRef,
@ -45,6 +48,8 @@ export const structRefs = [
* @param {Array<AbstractStruct>} structs All structs by `client`
* @param {number} client
* @param {number} clock write structs starting with `ID(client,clock)`
*
* @function
*/
const writeStructs = (encoder, structs, client, clock) => {
// write first id
@ -65,6 +70,9 @@ const writeStructs = (encoder, structs, client, clock) => {
* @param {number} numOfStructs
* @param {ID} nextID
* @return {Array<AbstractStructRef>}
*
* @private
* @function
*/
const readStructRefs = (decoder, numOfStructs, nextID) => {
/**
@ -83,7 +91,10 @@ const readStructRefs = (decoder, numOfStructs, nextID) => {
/**
* @param {encoding.Encoder} encoder
* @param {StructStore} store
* @param {StateMap} _sm
* @param {Map<number,number>} _sm
*
* @private
* @function
*/
export const writeClientsStructs = (encoder, store, _sm) => {
// we filter all valid _sm entries into sm
@ -110,6 +121,9 @@ export const writeClientsStructs = (encoder, store, _sm) => {
/**
* @param {decoding.Decoder} decoder The decoder object to read data from.
* @return {Map<number,Array<AbstractStructRef>>}
*
* @private
* @function
*/
export const readClientsStructRefs = decoder => {
/**
@ -148,6 +162,8 @@ export const readClientsStructRefs = decoder => {
* @param {Transaction} transaction
* @param {StructStore} store
*
* @private
* @function
*/
const resumeStructIntegration = (transaction, store) => {
const stack = store.pendingStack
@ -216,6 +232,9 @@ const resumeStructIntegration = (transaction, store) => {
/**
* @param {Transaction} transaction
* @param {StructStore} store
*
* @private
* @function
*/
export const tryResumePendingDeleteReaders = (transaction, store) => {
const pendingReaders = store.pendingDeleteReaders
@ -225,31 +244,28 @@ export const tryResumePendingDeleteReaders = (transaction, store) => {
}
}
/**
* @param {Map<number,{refs:Array<AbstractStructRef>,i:number}>} pendingClientsStructRefs
* @param {number} client
* @param {Array<AbstractStructRef>} refs
*/
const setPendingClientsStructRefs = (pendingClientsStructRefs, client, refs) => {
pendingClientsStructRefs.set(client, { refs, i: 0 })
}
/**
* @param {encoding.Encoder} encoder
* @param {Transaction} transaction
*
* @private
* @function
*/
export const writeStructsFromTransaction = (encoder, transaction) => writeClientsStructs(encoder, transaction.y.store, transaction.beforeState)
/**
* @param {StructStore} store
* @param {Map<number, Array<AbstractStructRef>>} clientsStructsRefs
*
* @private
* @function
*/
const mergeReadStructsIntoPendingReads = (store, clientsStructsRefs) => {
const pendingClientsStructRefs = store.pendingClientsStructRefs
for (const [client, structRefs] of clientsStructsRefs) {
const pendingStructRefs = pendingClientsStructRefs.get(client)
if (pendingStructRefs === undefined) {
setPendingClientsStructRefs(pendingClientsStructRefs, client, structRefs)
pendingClientsStructRefs.set(client, { refs: structRefs, i: 0 })
} else {
// merge into existing structRefs
const merged = pendingStructRefs.i > 0 ? pendingStructRefs.refs.slice(pendingStructRefs.i) : pendingStructRefs.refs
@ -272,6 +288,7 @@ const mergeReadStructsIntoPendingReads = (store, clientsStructsRefs) => {
* @param {StructStore} store
*
* @private
* @function
*/
export const readStructs = (decoder, transaction, store) => {
const clientsStructRefs = readClientsStructRefs(decoder)
@ -284,6 +301,8 @@ export const readStructs = (decoder, transaction, store) => {
* @param {decoding.Decoder} decoder
* @param {Transaction} transaction
* @param {StructStore} store
*
* @function
*/
export const readModel = (decoder, transaction, store) => {
readStructs(decoder, transaction, store)
@ -294,6 +313,8 @@ export const readModel = (decoder, transaction, store) => {
* @param {encoding.Encoder} encoder
* @param {StructStore} store
* @param {Map<number,number>} [targetState] The state of the target that receives the update. Leave empty to write all known structs
*
* @function
*/
export const writeModel = (encoder, store, targetState = new Map()) => {
writeClientsStructs(encoder, store, targetState)

6
src/utils/isParentOf.js
View File

@ -1,6 +1,3 @@
/**
* @module utils
*/
import { AbstractType } from '../internals.js' // eslint-disable-line
@ -11,7 +8,8 @@ import { AbstractType } from '../internals.js' // eslint-disable-line
* @param {AbstractType<any>} child
* @return {Boolean} Whether `parent` is a parent of `child`.
*
* @public
* @private
* @function
*/
export const isParentOf = (parent, child) => {
while (child._item !== null) {

21
src/utils/relativePosition.js
View File

@ -1,3 +1,6 @@
/**
* @module RelativePosition
*/
import {
find,
@ -79,6 +82,8 @@ export class RelativePosition {
/**
* @param {Object} json
* @return {RelativePosition}
*
* @function
*/
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))
@ -102,12 +107,16 @@ export class AbsolutePosition {
/**
* @param {AbstractType<any>} type
* @param {number} offset
*
* @function
*/
export const createAbsolutePosition = (type, offset) => new AbsolutePosition(type, offset)
/**
* @param {AbstractType<any>} type
* @param {ID|null} item
*
* @function
*/
export const createRelativePosition = (type, item) => {
let typeid = null
@ -126,6 +135,8 @@ export const createRelativePosition = (type, item) => {
* @param {AbstractType<any>} type The base type (e.g. YText or YArray).
* @param {number} offset The absolute position.
* @return {RelativePosition}
*
* @function
*/
export const createRelativePositionByOffset = (type, offset) => {
let t = type._start
@ -145,6 +156,8 @@ export const createRelativePositionByOffset = (type, offset) => {
/**
* @param {encoding.Encoder} encoder
* @param {RelativePosition} rpos
*
* @function
*/
export const writeRelativePosition = (encoder, rpos) => {
const { type, tname, item } = rpos
@ -170,6 +183,8 @@ export const writeRelativePosition = (encoder, rpos) => {
* @param {Y} y
* @param {StructStore} store
* @return {RelativePosition|null}
*
* @function
*/
export const readRelativePosition = (decoder, y, store) => {
let type = null
@ -196,6 +211,8 @@ export const readRelativePosition = (decoder, y, store) => {
* @param {RelativePosition} rpos
* @param {Y} y
* @return {AbsolutePosition|null}
*
* @function
*/
export const toAbsolutePosition = (rpos, y) => {
const store = y.store
@ -244,6 +261,8 @@ export const toAbsolutePosition = (rpos, y) => {
* @param {Y} y The Yjs instance in which to query for the absolute position.
* @return {RelativePosition} The absolute position in the Yjs model
* (type + offset).
*
* @function
*/
export const toRelativePosition = (apos, y) => {
const type = apos.type
@ -268,6 +287,8 @@ export const toRelativePosition = (apos, y) => {
/**
* @param {RelativePosition|null} a
* @param {RelativePosition|null} b
*
* @function
*/
export const compareRelativePositions = (a, b) => a === b || (
a !== null && b !== null && a.tname === b.tname && (