rework and document api

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<any>}
    */
   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<any>|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<any>} parent
  * @param {AbstractItem?} referenceItem
- * @param {Array<Object<string,any>|Array<any>|number|string|ArrayBuffer>} content
+ * @param {Array<Object<string,any>|Array<any>|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<any>} parent
  * @param {number} index
- * @param {Array<Object<string,any>|Array<any>|number|string|ArrayBuffer>} content
+ * @param {Array<Object<string,any>|Array<any>|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<any>} parent
  * @param {string} key
- * @param {Object|number|Array<any>|string|ArrayBuffer|AbstractType<any>} value
+ * @param {Object|number|Array<any>|string|Uint8Array|AbstractType<any>} 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<any>} parent
  * @param {string} key
- * @return {Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|undefined}
+ * @return {Object<string,any>|number|Array<any>|string|Uint8Array|AbstractType<any>|undefined}
  *
  * @private
  * @function
@@ -542,7 +541,7 @@ export const typeMapGet = (parent, key) => {
 
 /**
  * @param {AbstractType<any>} parent
- * @return {Object<string,Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|undefined>}
+ * @return {Object<string,Object<string,any>|number|Array<any>|string|Uint8Array|AbstractType<any>|undefined>}
  *
  * @private
  * @function
@@ -577,7 +576,7 @@ export const typeMapHas = (parent, key) => {
  * @param {AbstractType<any>} parent
  * @param {string} key
  * @param {Snapshot} snapshot
- * @return {Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|undefined}
+ * @return {Object<string,any>|number|Array<any>|string|Uint8Array|AbstractType<any>|undefined}
  *
  * @private
  * @function

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<T>} 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<T>}
    */
   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<T>):void} f A function to execute on every element of this YArray.
    */
   forEach (f) {
-    typeArrayForEach(this, f)
+    typeListForEach(this, f)
   }
 
   /**
    * @return {IterableIterator<T>}
    */
   [Symbol.iterator] () {
-    return typeArrayCreateIterator(this)
+    return typeListCreateIterator(this)
   }
 
   /**

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<YMapEvent<T>>
@@ -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 {

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)

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) {

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<YXmlElement|YXmlText>} 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<YXmlElement|YXmlText|YXmlHook>}
    */
   toArray () {
-    return typeArrayToArray(this)
+    return typeListToArray(this)
   }
   /**
    * Transform the properties of this type to binary and write it to an