implement getMap, getArray, getXml, ..

2019-04-03 03:08:10 +02:00
parent 415de1cc4c
commit 92ca001cdc
23 changed files with 159 additions and 103 deletions
--- a/src/types/AbstractType.js
+++ b/src/types/AbstractType.js
@@ -18,6 +18,7 @@ import { getItemCleanStart, getItemCleanEnd } from '../utils/StructStore.js'
 import * as iterator from 'lib0/iterator.js'

 /**
+ * @template EventType
 * Abstract Yjs Type class
 */
 export class AbstractType {
@@ -63,7 +64,7 @@ export class AbstractType {
  }

  /**
-   * @return {AbstractType}
+   * @return {AbstractType<EventType>}
   */
  _copy () {
    throw new Error('unimplemented')
@@ -110,10 +111,11 @@ export class AbstractType {
    const changedParentTypes = transaction.changedParentTypes
    this._eventHandler.callEventListeners(transaction, event)
    /**
-     * @type {AbstractType}
+     * @type {AbstractType<EventType>}
     */
    let type = this
    while (true) {
+      // @ts-ignore
      map.setIfUndefined(changedParentTypes, type, () => []).push(event)
      if (type._item === null) {
        break
@@ -125,7 +127,7 @@ export class AbstractType {
  /**
   * Observe all events that are created on this type.
   *
-   * @param {function(YEvent):void} f Observer function
+   * @param {function(EventType):void} f Observer function
   */
  observe (f) {
    this._eventHandler.addEventListener(f)
@@ -134,7 +136,7 @@ export class AbstractType {
  /**
   * Observe all events that are created by this type and its children.
   *
-   * @param {Function} f Observer function
+   * @param {function(Array<YEvent>):void} f Observer function
   */
  observeDeep (f) {
    this._deepEventHandler.addEventListener(f)
@@ -166,7 +168,7 @@ export class AbstractType {
 }

 /**
- * @param {AbstractType} type
+ * @param {AbstractType<any>} type
 * @return {Array<any>}
 */
 export const typeArrayToArray = type => {
@@ -187,8 +189,8 @@ export const typeArrayToArray = type => {
 /**
 * Executes a provided function on once on overy element of this YArray.
 *
- * @param {AbstractType} type
- * @param {function(any,number,AbstractType):void} f A function to execute on every 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.
 */
 export const typeArrayForEach = (type, f) => {
  let index = 0
@@ -206,8 +208,8 @@ export const typeArrayForEach = (type, f) => {

 /**
 * @template C,R
- * @param {AbstractType} type
- * @param {function(C,number,AbstractType):R} f
+ * @param {AbstractType<any>} type
+ * @param {function(C,number,AbstractType<any>):R} f
 * @return {Array<R>}
 */
 export const typeArrayMap = (type, f) => {
@@ -222,7 +224,7 @@ export const typeArrayMap = (type, f) => {
 }

 /**
- * @param {AbstractType} type
+ * @param {AbstractType<any>} type
 * @return {{next:function():{done:boolean,value:any|undefined}}}
 */
 export const typeArrayCreateIterator = type => {
@@ -270,8 +272,8 @@ export const typeArrayCreateIterator = type => {
 * Executes a provided function on once on overy element of this YArray.
 * Operates on a snapshotted state of the document.
 *
- * @param {AbstractType} type
- * @param {function(any,number,AbstractType):void} f A function to execute on every 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 {Snapshot} snapshot
 */
 export const typeArrayForEachSnapshot = (type, f, snapshot) => {
@@ -289,7 +291,7 @@ export const typeArrayForEachSnapshot = (type, f, snapshot) => {
 }

 /**
- * @param {AbstractType} type
+ * @param {AbstractType<any>} type
 * @param {number} index
 * @return {any}
 */
@@ -306,7 +308,7 @@ export const typeArrayGet = (type, index) => {

 /**
 * @param {Transaction} transaction
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {AbstractItem?} referenceItem
 * @param {Array<Object<string,any>|Array<any>|number|string|ArrayBuffer>} content
 */
@@ -349,7 +351,7 @@ export const typeArrayInsertGenericsAfter = (transaction, parent, referenceItem,

 /**
 * @param {Transaction} transaction
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {number} index
 * @param {Array<Object<string,any>|Array<any>|number|string|ArrayBuffer>} content
 */
@@ -373,7 +375,7 @@ export const typeArrayInsertGenerics = (transaction, parent, index, content) =>

 /**
 * @param {Transaction} transaction
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {number} index
 * @param {number} length
 */
@@ -404,7 +406,7 @@ export const typeArrayDelete = (transaction, parent, index, length) => {

 /**
 * @param {Transaction} transaction
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {string} key
 */
 export const typeMapDelete = (transaction, parent, key) => {
@@ -416,9 +418,9 @@ export const typeMapDelete = (transaction, parent, key) => {

 /**
 * @param {Transaction} transaction
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {string} key
- * @param {Object|number|Array<any>|string|ArrayBuffer|AbstractType} value
+ * @param {Object|number|Array<any>|string|ArrayBuffer|AbstractType<any>} value
 */
 export const typeMapSet = (transaction, parent, key, value) => {
  const right = parent._map.get(key) || null
@@ -442,9 +444,9 @@ export const typeMapSet = (transaction, parent, key, value) => {
 }

 /**
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {string} key
- * @return {Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType|undefined}
+ * @return {Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|undefined}
 */
 export const typeMapGet = (parent, key) => {
  const val = parent._map.get(key)
@@ -452,8 +454,8 @@ export const typeMapGet = (parent, key) => {
 }

 /**
- * @param {AbstractType} parent
- * @return {Object<string,Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType|undefined>}
+ * @param {AbstractType<any>} parent
+ * @return {Object<string,Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|undefined>}
 */
 export const typeMapGetAll = (parent) => {
  /**
@@ -469,7 +471,7 @@ export const typeMapGetAll = (parent) => {
 }

 /**
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {string} key
 * @return {boolean}
 */
@@ -479,10 +481,10 @@ export const typeMapHas = (parent, key) => {
 }

 /**
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {string} key
 * @param {Snapshot} snapshot
- * @return {Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType|undefined}
+ * @return {Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|undefined}
 */
 export const typeMapGetSnapshot = (parent, key, snapshot) => {
  let v = parent._map.get(key) || null
--- a/src/types/YArray.js
+++ b/src/types/YArray.js
@@ -11,10 +11,11 @@ import * as decoding from 'lib0/decoding.js' // eslint-disable-line

 /**
 * Event that describes the changes on a YArray
+ * @template T
 */
 export class YArrayEvent extends YEvent {
  /**
-   * @param {AbstractType} yarray The changed type
+   * @param {YArray<T>} yarray The changed type
   * @param {Transaction} transaction The transaction object
   */
  constructor (yarray, transaction) {
@@ -26,6 +27,7 @@ export class YArrayEvent extends YEvent {
 /**
 * A shared Array implementation.
 * @template T
+ * @extends AbstractType<YArrayEvent<T>>
 */
 export class YArray extends AbstractType {
  constructor () {
@@ -149,10 +151,10 @@ export class YArray extends AbstractType {
   *  // Insert character 'a' at position 0
   *  yarray.insert(0, ['a'])
   *  // Insert numbers 1, 2 at position 1
-   *  yarray.insert(2, [1, 2])
+   *  yarray.insert(1, [1, 2])
   *
   * @param {number} index The index to insert content at.
-   * @param {Array<number|string|ArrayBuffer|AbstractType>} content The array of content
+   * @param {Array<T>} content The array of content
   */
  insert (index, content) {
    if (this._y !== null) {
@@ -168,7 +170,7 @@ export class YArray extends AbstractType {
  /**
   * Appends content to this YArray.
   *
-   * @param {Array<number|string|ArrayBuffer|AbstractType>} content Array of content to append.
+   * @param {Array<T>} content Array of content to append.
   */
  push (content) {
    this.insert(this.length, content)
--- a/src/types/YMap.js
+++ b/src/types/YMap.js
@@ -28,6 +28,8 @@ export class YMapEvent extends YEvent {
 /**
 * @template T number|string|Object|Array|ArrayBuffer
 * A shared Map implementation.
+ *
+ * @extends AbstractType<YMapEvent<T>>
 */
 export class YMap extends AbstractType {
  constructor () {
--- a/src/types/YText.js
+++ b/src/types/YText.js
@@ -5,7 +5,7 @@
 import { ItemEmbed } from '../structs/ItemEmbed.js'
 import { ItemString } from '../structs/ItemString.js'
 import { ItemFormat } from '../structs/ItemFormat.js'
-import { YArrayEvent } from './YArray.js'
+import { YEvent } from '../utils/YEvent.js'
 import { ItemType } from '../structs/ItemType.js' // eslint-disable-line
 import { AbstractType } from './AbstractType.js'
 import { AbstractItem } from '../structs/AbstractItem.js' // eslint-disable-line
@@ -57,7 +57,7 @@ const findNextPosition = (transaction, store, currentAttributes, left, right, co
 * @private
 * @param {Transaction} transaction
 * @param {StructStore} store
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {number} index
 * @return {{left:AbstractItem|null,right:AbstractItem|null,currentAttributes:Map<string,any>}}
 */
@@ -73,7 +73,7 @@ const findPosition = (transaction, store, parent, index) => {
 *
 * @private
 * @param {Transaction} transaction
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {AbstractItem|null} left
 * @param {AbstractItem|null} right
 * @param {Map<string,any>} negatedAttributes
@@ -151,7 +151,7 @@ const minimizeAttributeChanges = (left, right, currentAttributes, attributes) =>
 /**
 * @private
 * @param {Transaction} transaction
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {AbstractItem|null} left
 * @param {AbstractItem|null} right
 * @param {Map<string,any>} currentAttributes
@@ -177,7 +177,7 @@ const insertAttributes = (transaction, parent, left, right, currentAttributes, a
 /**
 * @private
 * @param {Transaction} transaction
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {AbstractItem|null} left
 * @param {AbstractItem|null} right
 * @param {Map<string,any>} currentAttributes
@@ -206,7 +206,7 @@ const insertText = (transaction, parent, left, right, currentAttributes, text, a
 /**
 * @private
 * @param {Transaction} transaction
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {AbstractItem|null} left
 * @param {AbstractItem|null} right
 * @param {Map<string,any>} currentAttributes
@@ -260,7 +260,7 @@ const formatText = (transaction, parent, left, right, currentAttributes, length,
 /**
 * @private
 * @param {Transaction} transaction
- * @param {AbstractType} parent
+ * @param {AbstractType<any>} parent
 * @param {AbstractItem|null} left
 * @param {AbstractItem|null} right
 * @param {Map<string,any>} currentAttributes
@@ -324,9 +324,9 @@ const deleteText = (transaction, parent, left, right, currentAttributes, length)
 *
 * @private
 */
-class YTextEvent extends YArrayEvent {
+class YTextEvent extends YEvent {
  /**
-   * @param {AbstractType} ytext
+   * @param {YText} ytext
   * @param {Transaction} transaction
   */
  constructor (ytext, transaction) {
@@ -544,6 +544,8 @@ class YTextEvent extends YArrayEvent {
 * This type replaces y-richtext as this implementation is able to handle
 * block formats (format information on a paragraph), embeds (complex elements
 * like pictures and videos), and text formats (**bold**, *italic*).
+ *
+ * @extends AbstractType<YTextEvent>
 */
 export class YText extends AbstractType {
  /**
--- a/src/types/YXmlElement.js
+++ b/src/types/YXmlElement.js
@@ -11,7 +11,7 @@ import { YXmlEvent } from './YXmlEvent.js'
 import { ItemType } from '../structs/ItemType.js' // eslint-disable-line
 import { YXmlText } from './YXmlText.js' // eslint-disable-line
 import { YXmlHook } from './YXmlHook.js' // eslint-disable-line
-import { AbstractType, typeArrayMap, typeArrayForEach, typeMapGet, typeMapGetAll } from './AbstractType.js'
+import { AbstractType, typeArrayMap, typeArrayForEach, typeMapGet, typeMapGetAll, typeArrayInsertGenerics } from './AbstractType.js'
 import { Snapshot } from '../utils/Snapshot.js' // eslint-disable-line

 /**
@@ -46,7 +46,7 @@ import { Snapshot } from '../utils/Snapshot.js' // eslint-disable-line
 export class YXmlTreeWalker {
  /**
   * @param {YXmlFragment | YXmlElement} root
-   * @param {function(AbstractType):boolean} f
+   * @param {function(AbstractType<any>):boolean} f
   */
  constructor (root, f) {
    this._filter = f || (() => true)
@@ -107,6 +107,7 @@ export class YXmlTreeWalker {
 * element - in this case the attributes and the nodeName are not shared.
 *
 * @public
+ * @extends AbstractType<YXmlEvent>
 */
 export class YXmlFragment extends AbstractType {
  /**
@@ -119,7 +120,7 @@ export class YXmlFragment extends AbstractType {
   *   nop(node)
   * }
   *
-   * @param {function(AbstractType):boolean} filter Function that is called on each child element and
+   * @param {function(AbstractType<any>):boolean} filter Function that is called on each child element and
   *                          returns a Boolean indicating whether the child
   *                          is to be included in the subtree.
   * @return {YXmlTreeWalker} A subtree and a position within it.
@@ -340,6 +341,28 @@ export class YXmlElement extends YXmlFragment {
  getAttributes (snapshot) {
    return typeMapGetAll(this)
  }
+
+  /**
+   * Inserts new content at an index.
+   *
+   * @example
+   *  // Insert character 'a' at position 0
+   *  xml.insert(0, [new Y.XmlText('text')])
+   *
+   * @param {number} index The index to insert content at
+   * @param {Array<YXmlElement|YXmlText>} content The array of content
+   */
+  insert (index, content) {
+    if (this._y !== null) {
+      this._y.transact(transaction => {
+        typeArrayInsertGenerics(transaction, this, index, content)
+      })
+    } else {
+      // @ts-ignore _prelimContent is defined because this is not yet integrated
+      this._prelimContent.splice(index, 0, ...content)
+    }
+  }
+
  // TODO: outsource the binding property.
  /**
   * Creates a Dom Element that mirrors this YXmlElement.
--- a/src/types/YXmlEvent.js
+++ b/src/types/YXmlEvent.js
@@ -6,6 +6,7 @@ import { YEvent } from '../utils/YEvent.js'

 import { AbstractType } from './AbstractType.js' // eslint-disable-line
 import { Transaction } from '../utils/Transaction.js' // eslint-disable-line
+import { YXmlElement, YXmlFragment } from './YXmlElement.js' // eslint-disable-line

 /**
 * An Event that describes changes on a YXml Element or Yxml Fragment
@@ -14,14 +15,14 @@ import { Transaction } from '../utils/Transaction.js' // eslint-disable-line
 */
 export class YXmlEvent extends YEvent {
  /**
-   * @param {AbstractType} target The target on which the event is created.
+   * @param {YXmlElement|YXmlFragment} target The target on which the event is created.
   * @param {Set<string|null>} subs The set of changed attributes. `null` is included if the
   *                   child list changed.
   * @param {Transaction} transaction The transaction instance with wich the
   *                                  change was created.
   */
  constructor (target, subs, transaction) {
-    super(target)
+    super(target, transaction)
    /**
     * The transaction instance for the computed change.
     * @type {Transaction}