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

v13 api docs

Browse Source
This commit is contained in:
Kevin Jahns
2019-04-28 02:37:39 +02:00
parent 1417470156
commit c9dda245bf
11 changed files with 391 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/types/AbstractType.js
View File

@@ -224,7 +224,7 @@ export const typeArrayToArraySnapshot = (type, snapshot) => {
* Executes a provided function on once on overy element of this YArray.
*
* @param {AbstractType<any>} type
* @param {function(any,number,AbstractType<any>):void} f A function to execute on every element of this YArray.
* @param {function(any,number,any):void} f A function to execute on every element of this YArray.
*
* @private
* @function
@@ -597,4 +597,4 @@ export const typeMapGetSnapshot = (parent, key, snapshot) => {
* @private
* @function
*/
export const createMapIterator = map => iterator.iteratorFilter(map.entries(), entry => !entry[1].deleted)
export const createMapIterator = map => iterator.iteratorFilter(map.entries(), /** @param {any} entry */ entry => !entry[1].deleted)

108
src/types/YArray.js
View File

@@ -84,6 +84,59 @@ export class YArray extends AbstractType {
callTypeObservers(this, transaction, new YArrayEvent(this, transaction))
}
/**
* Inserts new content at an index.
*
* Important: This function expects an array of content. Not just a content
* object. The reason for this "weirdness" is that inserting several elements
* is very efficient when it is done as a single operation.
*
* @example
* // Insert character 'a' at position 0
* yarray.insert(0, ['a'])
* // Insert numbers 1, 2 at position 1
* yarray.insert(1, [1, 2])
*
* @param {number} index The index to insert content at.
* @param {Array<T>} content The array of content
*/
insert (index, content) {
if (this._y !== null) {
transact(this._y, transaction => {
typeArrayInsertGenerics(transaction, this, index, content)
})
} else {
// @ts-ignore _prelimContent is defined because this is not yet integrated
this._prelimContent.splice(index, 0, ...content)
}
}
/**
* Appends content to this YArray.
*
* @param {Array<T>} content Array of content to append.
*/
push (content) {
this.insert(this.length, content)
}
/**
* Deletes elements starting from an index.
*
* @param {number} index Index at which to start deleting elements
* @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)
})
} else {
// @ts-ignore _prelimContent is defined because this is not yet integrated
this._prelimContent.splice(index, length)
}
}
/**
* Returns the i-th element from a YArray.
*
@@ -129,7 +182,7 @@ export class YArray extends AbstractType {
/**
* Executes a provided function on once on overy element of this YArray.
*
* @param {function(T,number):void} f A function to execute on every element of this YArray.
* @param {function(T,number,YArray<T>):void} f A function to execute on every element of this YArray.
*/
forEach (f) {
typeArrayForEach(this, f)
@@ -142,59 +195,6 @@ export class YArray extends AbstractType {
return typeArrayCreateIterator(this)
}
/**
* Deletes elements starting from an index.
*
* @param {number} index Index at which to start deleting elements
* @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)
})
} else {
// @ts-ignore _prelimContent is defined because this is not yet integrated
this._prelimContent.splice(index, length)
}
}
/**
* Inserts new content at an index.
*
* Important: This function expects an array of content. Not just a content
* object. The reason for this "weirdness" is that inserting several elements
* is very efficient when it is done as a single operation.
*
* @example
* // Insert character 'a' at position 0
* yarray.insert(0, ['a'])
* // Insert numbers 1, 2 at position 1
* yarray.insert(1, [1, 2])
*
* @param {number} index The index to insert content at.
* @param {Array<T>} content The array of content
*/
insert (index, content) {
if (this._y !== null) {
transact(this._y, transaction => {
typeArrayInsertGenerics(transaction, this, index, content)
})
} else {
// @ts-ignore _prelimContent is defined because this is not yet integrated
this._prelimContent.splice(index, 0, ...content)
}
}
/**
* Appends content to this YArray.
*
* @param {Array<T>} content Array of content to append.
*/
push (content) {
this.insert(this.length, content)
}
/**
* @param {encoding.Encoder} encoder
* @private

18
src/types/YMap.js
View File

@@ -110,15 +110,25 @@ export class YMap extends AbstractType {
* @return {Iterator<string>}
*/
keys () {
return iterator.iteratorMap(createMapIterator(this._map), v => v[0])
return iterator.iteratorMap(createMapIterator(this._map), /** @param {any} v */ v => v[0])
}
/**
* Returns the value for each element in the YMap Type.
* Returns the keys for each element in the YMap Type.
*
* @return {IterableIterator<T>}
* @return {Iterator<string>}
*/
values () {
return iterator.iteratorMap(createMapIterator(this._map), /** @param {any} v */ v => v[1].getContent()[v[1].length - 1])
}
/**
* Returns an Iterator of [key, value] pairs
*
* @return {IterableIterator<any>}
*/
entries () {
return iterator.iteratorMap(createMapIterator(this._map), v => v[1].getContent()[0])
return iterator.iteratorMap(createMapIterator(this._map), /** @param {any} v */ v => [v[0], v[1].getContent()[v[1].length - 1]])
}
/**

16
src/types/YXmlElement.js
View File

@@ -65,20 +65,16 @@ export class YXmlElement extends YXmlFragment {
return new YXmlElement(this.nodeName)
}
toString () {
return this.toDomString()
}
/**
* Returns the string representation of this YXmlElement.
* Returns the XML serialization of this YXmlElement.
* The attributes are ordered by attribute-name, so you can easily use this
* method to compare YXmlElements
*
* @return {String} The string representation of this type.
* @return {string} The string representation of this type.
*
* @public
*/
toDomString () {
toString () {
const attrs = this.getAttributes()
const stringBuilder = []
const keys = []
@@ -93,7 +89,7 @@ export class YXmlElement extends YXmlFragment {
}
const nodeName = this.nodeName.toLocaleLowerCase()
const attrsString = stringBuilder.length > 0 ? ' ' + stringBuilder.join(' ') : ''
return `<${nodeName}${attrsString}>${super.toDomString()}</${nodeName}>`
return `<${nodeName}${attrsString}>${super.toString()}</${nodeName}>`
}
/**
@@ -174,14 +170,14 @@ export class YXmlElement extends YXmlFragment {
*
* @public
*/
toDom (_document = document, hooks = {}, binding) {
toDOM (_document = document, hooks = {}, binding) {
const dom = _document.createElement(this.nodeName)
let attrs = this.getAttributes()
for (let key in attrs) {
dom.setAttribute(key, attrs[key])
}
typeArrayForEach(this, yxml => {
dom.appendChild(yxml.toDom(_document, hooks, binding))
dom.appendChild(yxml.toDOM(_document, hooks, binding))
})
if (binding !== undefined) {
binding._createAssociation(dom, this)

16
src/types/YXmlFragment.js
View File

@@ -205,17 +205,17 @@ export class YXmlFragment extends AbstractType {
callTypeObservers(this, transaction, new YXmlEvent(this, parentSubs, transaction))
}
toString () {
return this.toDomString()
}
/**
* Get the string representation of all the children of this YXmlFragment.
*
* @return {string} The string representation of all children.
*/
toDomString () {
return typeArrayMap(this, xml => xml.toDomString()).join('')
toString () {
return typeArrayMap(this, xml => xml.toString()).join('')
}
toJSON () {
return this.toString()
}
/**
@@ -233,13 +233,13 @@ export class YXmlFragment extends AbstractType {
*
* @public
*/
toDom (_document = document, hooks = {}, binding) {
toDOM (_document = document, hooks = {}, binding) {
const fragment = _document.createDocumentFragment()
if (binding !== undefined) {
binding._createAssociation(fragment, this)
}
typeArrayForEach(this, xmlType => {
fragment.insertBefore(xmlType.toDom(_document, hooks, binding), null)
fragment.insertBefore(xmlType.toDOM(_document, hooks, binding), null)
})
return fragment
}

2
src/types/YXmlHook.js
View File

@@ -47,7 +47,7 @@ export class YXmlHook extends YMap {
*
* @public
*/
toDom (_document = document, hooks = {}, binding) {
toDOM (_document = document, hooks = {}, binding) {
const hook = hooks[this.hookName]
let dom
if (hook !== undefined) {

8
src/types/YXmlText.js
View File

@@ -24,7 +24,7 @@ export class YXmlText extends YText {
*
* @public
*/
toDom (_document = document, hooks, binding) {
toDOM (_document = document, hooks, binding) {
const dom = _document.createTextNode(this.toString())
if (binding !== undefined) {
binding._createAssociation(dom, this)
@@ -32,7 +32,7 @@ export class YXmlText extends YText {
return dom
}
toDomString () {
toString () {
// @ts-ignore
return this.toDelta().map(delta => {
const nestedNodes = []
@@ -66,6 +66,10 @@ export class YXmlText extends YText {
}).join('')
}
toJSON () {
return this.toString()
}
/**
* @param {encoding.Encoder} encoder
*

2
src/utils/Y.js
View File

@@ -17,6 +17,8 @@ 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<string>