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

big documentation update - all public functions and classes are documented now

Browse Source
This commit is contained in:
Kevin Jahns
2018-03-05 03:03:40 +01:00
parent dc22a79ac4
commit a9b610479d
33 changed files with 2426 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
src/Struct/Delete.js
View File

@@ -3,6 +3,7 @@ import ID from '../Util/ID.js'
import { logID } from '../MessageHandler/messageToString.js'
/**
* @private
* Delete all items in an ID-range
* TODO: implement getItemCleanStartNode for better performance (only one lookup)
*/
@@ -35,13 +36,26 @@ export function deleteItemRange (y, user, clock, range) {
}
/**
* Delete is not a real struct. It will not be saved in OS
* @private
* A Delete change is not a real Item, but it provides the same interface as an
* Item. The only difference is that it will not be saved in the ItemStore
* (OperationStore), but instead it is safed in the DeleteStore.
*/
export default class Delete {
constructor () {
this._target = null
this._length = null
}
/**
* @private
* Read the next Item in a Decoder and fill this Item with the read data.
*
* This is called when data is received from a remote peer.
*
* @param {Y} y The Yjs instance that this Item belongs to.
* @param {BinaryDecoder} decoder The decoder object to read data from.
*/
_fromBinary (y, decoder) {
// TODO: set target, and add it to missing if not found
// There is an edge case in p2p networks!
@@ -54,15 +68,32 @@ export default class Delete {
return []
}
}
/**
* @private
* Transform the properties of this type to binary and write it to an
* BinaryEncoder.
*
* This is called when this Item is sent to a remote peer.
*
* @param {BinaryEncoder} encoder The encoder to write data to.
*/
_toBinary (encoder) {
encoder.writeUint8(getReference(this.constructor))
encoder.writeID(this._targetID)
encoder.writeVarUint(this._length)
}
/**
* - If created remotely (a remote user deleted something),
* @private
* Integrates this Item into the shared structure.
*
* This method actually applies the change to the Yjs instance. In the case of
* Delete it marks the delete target as deleted.
*
* * If created remotely (a remote user deleted something),
* this Delete is applied to all structs in id-range.
* - If created lokally (e.g. when y-array deletes a range of elements),
* * If created lokally (e.g. when y-array deletes a range of elements),
* this struct is broadcasted only (it is already executed)
*/
_integrate (y, locallyCreated = false) {
@@ -78,6 +109,12 @@ export default class Delete {
y.persistence.saveStruct(y, this)
}
}
/**
* @private
* Transform this Delete to a readable format.
* Useful for logging as all Items implement this method.
*/
_logString () {
return `Delete - target: ${logID(this._targetID)}, len: ${this._length}`
}

101
src/Struct/Item.js
View File

@@ -5,11 +5,12 @@ import Delete from './Delete.js'
import { transactionTypeChanged } from '../Transaction.js'
/**
* Helper utility to split an Item (see _splitAt)
* - copy all properties from a to b
* - connect a to b
* @private
* Helper utility to split an Item (see {@link Item#_splitAt})
* - copies all properties from a to b
* - connects a to b
* - assigns the correct _id
* - save b to os
* - saves b to os
*/
export function splitHelper (y, a, b, diff) {
const aID = a._id
@@ -46,6 +47,10 @@ export function splitHelper (y, a, b, diff) {
}
}
/**
* @private
* Abstract class that represents any content.
*/
export default class Item {
constructor () {
this._id = null
@@ -58,14 +63,18 @@ export default class Item {
this._deleted = false
this._redone = null
}
/**
* Create a operation with the same effect (without position effect)
* @private
* Creates an Item with the same effect as this Item (without position effect)
*/
_copy () {
return new this.constructor()
}
/**
* Redo the effect of this operation.
* @private
* Redoes the effect of this operation.
*/
_redo (y) {
if (this._redone !== null) {
@@ -106,27 +115,43 @@ export default class Item {
return struct
}
/**
* @private
* Computes the last content address of this Item.
*/
get _lastId () {
return new ID(this._id.user, this._id.clock + this._length - 1)
}
/**
* @private
* Computes the length of this Item.
*/
get _length () {
return 1
}
/**
* Some elements are not supposed to be addressable. For example, an
* ItemFormat should not be retrievable via yarray.get(pos)
* @private
* Should return false if this Item is some kind of meta information
* (e.g. format information).
*
* * Whether this Item should be addressable via `yarray.get(i)`
* * Whether this Item should be counted when computing yarray.length
*/
get _countable () {
return true
}
/**
* Splits this struct so that another struct can be inserted in-between.
* @private
* Splits this Item so that another Items can be inserted in-between.
* This must be overwritten if _length > 1
* Returns right part after split
* - diff === 0 => this
* - diff === length => this._right
* - otherwise => split _content and return right part of split
* (see ItemJSON/ItemString for implementation)
* * diff === 0 => this
* * diff === length => this._right
* * otherwise => split _content and return right part of split
* (see {@link ItemJSON}/{@link ItemString} for implementation)
*/
_splitAt (y, diff) {
if (diff === 0) {
@@ -134,6 +159,15 @@ export default class Item {
}
return this._right
}
/**
* @private
* Mark this Item as deleted.
*
* @param {Y} y The Yjs instance
* @param {boolean} createDelete Whether to propagate a message that this
* Type was deleted.
*/
_delete (y, createDelete = true) {
if (!this._deleted) {
this._deleted = true
@@ -152,17 +186,27 @@ export default class Item {
y._transaction.deletedStructs.add(this)
}
}
/**
* This is called right before this struct receives any children.
* @private
* This is called right before this Item receives any children.
* It can be overwritten to apply pending changes before applying remote changes
*/
_beforeChange () {
// nop
}
/*
* - Integrate the struct so that other types/structs can see it
* - Add this struct to y.os
* - Check if this is struct deleted
/**
* @private
* Integrates this Item into the shared structure.
*
* This method actually applies the change to the Yjs instance. In case of
* Item it connects _left and _right to this Item and calls the
* {@link Item#beforeChange} method.
*
* * Integrate the struct so that other types/structs can see it
* * Add this struct to y.os
* * Check if this is struct deleted
*/
_integrate (y) {
y._transaction.newTypes.add(this)
@@ -188,6 +232,7 @@ export default class Item {
// or this types is new
this._parent._beforeChange()
}
/*
# $this has to find a unique position between origin and the next known character
# case 1: $origin equals $o.origin: the $creator parameter decides if left or right
@@ -280,6 +325,16 @@ export default class Item {
}
}
}
/**
* @private
* Transform the properties of this type to binary and write it to an
* BinaryEncoder.
*
* This is called when this Item is sent to a remote peer.
*
* @param {BinaryEncoder} encoder The encoder to write data to.
*/
_toBinary (encoder) {
encoder.writeUint8(getReference(this.constructor))
let info = 0
@@ -320,6 +375,16 @@ export default class Item {
encoder.writeVarString(JSON.stringify(this._parentSub))
}
}
/**
* @private
* Read the next Item in a Decoder and fill this Item with the read data.
*
* This is called when data is received from a remote peer.
*
* @param {Y} y The Yjs instance that this Item belongs to.
* @param {BinaryDecoder} decoder The decoder object to read data from.
*/
_fromBinary (y, decoder) {
let missing = []
const info = decoder.readUint8()

75
src/Struct/Type.js
View File

@@ -30,6 +30,9 @@ export function getListItemIDByPosition (type, i) {
}
}
/**
* Abstract Yjs Type class
*/
export default class Type extends Item {
constructor () {
super()
@@ -39,6 +42,20 @@ export default class Type extends Item {
this._eventHandler = new EventHandler()
this._deepEventHandler = new EventHandler()
}
/**
* Compute the path from this type to the specified target.
*
* @example
* It should be accessible via `this.get(result[0]).get(result[1])..``
* const path = type.getPathTo(child)
* // assuming `type instanceof YArray`
* console.log(path) // might look like => [2, 'key1']
* child === type.get(path[0]).get(path[1])
*
* @param {YType} type Type target
* @return {Array<string>} Path to the target
*/
getPathTo (type) {
if (type === this) {
return []
@@ -65,6 +82,12 @@ export default class Type extends Item {
}
return path
}
/**
* @private
* Call event listeners with an event. This will also add an event to all
* parents (for `.observeDeep` handlers).
*/
_callEventHandler (transaction, event) {
const changedParentTypes = transaction.changedParentTypes
this._eventHandler.callEventListeners(transaction, event)
@@ -79,6 +102,14 @@ export default class Type extends Item {
type = type._parent
}
}
/**
* @private
* Helper method to transact if the y instance is available.
*
* TODO: Currently event handlers are not thrown when a type is not registered
* with a Yjs instance.
*/
_transact (f) {
const y = this._y
if (y !== null) {
@@ -87,18 +118,53 @@ export default class Type extends Item {
f(y)
}
}
/**
* Observe all events that are created on this type.
*
* @param {Function} f Observer function
*/
observe (f) {
this._eventHandler.addEventListener(f)
}
/**
* Observe all events that are created by this type and its children.
*
* @param {Function} f Observer function
*/
observeDeep (f) {
this._deepEventHandler.addEventListener(f)
}
/**
* Unregister an observer function.
*
* @param {Function} f Observer function
*/
unobserve (f) {
this._eventHandler.removeEventListener(f)
}
/**
* Unregister an observer function.
*
* @param {Function} f Observer function
*/
unobserveDeep (f) {
this._deepEventHandler.removeEventListener(f)
}
/**
* @private
* Integrate this type into the Yjs instance.
*
* * Save this struct in the os
* * This type is sent to other client
* * Observer functions are fired
*
* @param {Y} y The Yjs instance
*/
_integrate (y) {
super._integrate(y)
this._y = y
@@ -117,6 +183,15 @@ export default class Type extends Item {
integrateChildren(y, t)
}
}
/**
* @private
* Mark this Item as deleted.
*
* @param {Y} y The Yjs instance
* @param {boolean} createDelete Whether to propagate a message that this
* Type was deleted.
*/
_delete (y, createDelete) {
super._delete(y, createDelete)
y._transaction.changedTypes.delete(this)