@y/y 14.0.0-16

package/src/utils/RelativePosition.js

@@ -0,0 +1,352 @@
+import {
+  writeID,
+  readID,
+  compareIDs,
+  getState,
+  findRootTypeKey,
+  Item,
+  createID,
+  ContentType,
+  followRedone,
+  getItem,
+  StructStore, ID, Doc, AbstractType, noAttributionsManager, // eslint-disable-line
+} from '../internals.js'
+
+import * as encoding from 'lib0/encoding'
+import * as decoding from 'lib0/decoding'
+import * as error from 'lib0/error'
+
+/**
+ * A relative position is based on the Yjs model and is not affected by document changes.
+ * E.g. If you place a relative position before a certain character, it will always point to this character.
+ * If you place a relative position at the end of a type, it will always point to the end of the type.
+ *
+ * A numeric position is often unsuited for user selections, because it does not change when content is inserted
+ * before or after.
+ *
+ * ```Insert(0, 'x')('a|bc') = 'xa|bc'``` Where | is the relative position.
+ *
+ * One of the properties must be defined.
+ *
+ * @example
+ *   // Current cursor position is at position 10
+ *   const relativePosition = createRelativePositionFromIndex(yText, 10)
+ *   // modify yText
+ *   yText.insert(0, 'abc')
+ *   yText.delete(3, 10)
+ *   // Compute the cursor position
+ *   const absolutePosition = createAbsolutePositionFromRelativePosition(y, relativePosition)
+ *   absolutePosition.type === yText // => true
+ *   console.log('cursor location is ' + absolutePosition.index) // => cursor location is 3
+ *
+ */
+export class RelativePosition {
+  /**
+   * @param {ID|null} type
+   * @param {string|null} tname
+   * @param {ID|null} item
+   * @param {number} assoc
+   */
+  constructor (type, tname, item, assoc = 0) {
+    /**
+     * @type {ID|null}
+     */
+    this.type = type
+    /**
+     * @type {string|null}
+     */
+    this.tname = tname
+    /**
+     * @type {ID | null}
+     */
+    this.item = item
+    /**
+     * A relative position is associated to a specific character. By default
+     * assoc >= 0, the relative position is associated to the character
+     * after the meant position.
+     * I.e. position 1 in 'ab' is associated to character 'b'.
+     *
+     * If assoc < 0, then the relative position is associated to the character
+     * before the meant position.
+     *
+     * @type {number}
+     */
+    this.assoc = assoc
+  }
+}
+
+/**
+ * @param {RelativePosition} rpos
+ * @return {any}
+ */
+export const relativePositionToJSON = rpos => {
+  const json = {}
+  if (rpos.type) {
+    json.type = rpos.type
+  }
+  if (rpos.tname) {
+    json.tname = rpos.tname
+  }
+  if (rpos.item) {
+    json.item = rpos.item
+  }
+  if (rpos.assoc != null) {
+    json.assoc = rpos.assoc
+  }
+  return json
+}
+
+/**
+ * @param {any} 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), json.assoc == null ? 0 : json.assoc)
+
+export class AbsolutePosition {
+  /**
+   * @param {AbstractType<any>} type
+   * @param {number} index
+   * @param {number} [assoc]
+   */
+  constructor (type, index, assoc = 0) {
+    /**
+     * @type {AbstractType<any>}
+     */
+    this.type = type
+    /**
+     * @type {number}
+     */
+    this.index = index
+    this.assoc = assoc
+  }
+}
+
+/**
+ * @param {AbstractType<any>} type
+ * @param {number} index
+ * @param {number} [assoc]
+ *
+ * @function
+ */
+export const createAbsolutePosition = (type, index, assoc = 0) => new AbsolutePosition(type, index, assoc)
+
+/**
+ * @param {AbstractType<any>} type
+ * @param {ID|null} item
+ * @param {number} [assoc]
+ *
+ * @function
+ */
+export const createRelativePosition = (type, item, assoc) => {
+  let typeid = null
+  let tname = null
+  if (type._item === null) {
+    tname = findRootTypeKey(type)
+  } else {
+    typeid = createID(type._item.id.client, type._item.id.clock)
+  }
+  return new RelativePosition(typeid, tname, item, assoc)
+}
+
+/**
+ * Create a relativePosition based on a absolute position.
+ *
+ * @param {AbstractType} type The base type (e.g. YText or YArray).
+ * @param {number} index The absolute position.
+ * @param {number} [assoc]
+ * @param {import('../utils/AttributionManager.js').AbstractAttributionManager} attributionManager
+ * @return {RelativePosition}
+ *
+ * @function
+ */
+export const createRelativePositionFromTypeIndex = (type, index, assoc = 0, attributionManager = noAttributionsManager) => {
+  let t = type._start
+  if (assoc < 0) {
+    // associated to the left character or the beginning of a type, increment index if possible.
+    if (index === 0) {
+      return createRelativePosition(type, null, assoc)
+    }
+    index--
+  }
+  while (t !== null) {
+    const len = attributionManager.contentLength(t)
+    if (len > index) {
+      // case 1: found position somewhere in the linked list
+      return createRelativePosition(type, createID(t.id.client, t.id.clock + index), assoc)
+    }
+    index -= len
+    if (t.right === null && assoc < 0) {
+      // left-associated position, return last available id
+      return createRelativePosition(type, t.lastId, assoc)
+    }
+    t = t.right
+  }
+  return createRelativePosition(type, null, assoc)
+}
+
+/**
+ * @param {encoding.Encoder} encoder
+ * @param {RelativePosition} rpos
+ *
+ * @function
+ */
+export const writeRelativePosition = (encoder, rpos) => {
+  const { type, tname, item, assoc } = rpos
+  if (item !== null) {
+    encoding.writeVarUint(encoder, 0)
+    writeID(encoder, item)
+  } else if (tname !== null) {
+    // case 2: found position at the end of the list and type is stored in y.share
+    encoding.writeUint8(encoder, 1)
+    encoding.writeVarString(encoder, tname)
+  } else if (type !== null) {
+    // case 3: found position at the end of the list and type is attached to an item
+    encoding.writeUint8(encoder, 2)
+    writeID(encoder, type)
+  } else {
+    throw error.unexpectedCase()
+  }
+  encoding.writeVarInt(encoder, assoc)
+  return encoder
+}
+
+/**
+ * @param {RelativePosition} rpos
+ * @return {Uint8Array}
+ */
+export const encodeRelativePosition = rpos => {
+  const encoder = encoding.createEncoder()
+  writeRelativePosition(encoder, rpos)
+  return encoding.toUint8Array(encoder)
+}
+
+/**
+ * @param {decoding.Decoder} decoder
+ * @return {RelativePosition}
+ *
+ * @function
+ */
+export const readRelativePosition = decoder => {
+  let type = null
+  let tname = null
+  let itemID = null
+  switch (decoding.readVarUint(decoder)) {
+    case 0:
+      // case 1: found position somewhere in the linked list
+      itemID = readID(decoder)
+      break
+    case 1:
+      // case 2: found position at the end of the list and type is stored in y.share
+      tname = decoding.readVarString(decoder)
+      break
+    case 2: {
+      // case 3: found position at the end of the list and type is attached to an item
+      type = readID(decoder)
+    }
+  }
+  const assoc = decoding.hasContent(decoder) ? decoding.readVarInt(decoder) : 0
+  return new RelativePosition(type, tname, itemID, assoc)
+}
+
+/**
+ * @param {Uint8Array} uint8Array
+ * @return {RelativePosition}
+ */
+export const decodeRelativePosition = uint8Array => readRelativePosition(decoding.createDecoder(uint8Array))
+
+/**
+ * @param {StructStore} store
+ * @param {ID} id
+ */
+const getItemWithOffset = (store, id) => {
+  const item = getItem(store, id)
+  const diff = id.clock - item.id.clock
+  return {
+    item, diff
+  }
+}
+
+/**
+ * Transform a relative position to an absolute position.
+ *
+ * If you want to share the relative position with other users, you should set
+ * `followUndoneDeletions` to false to get consistent results across all clients.
+ *
+ * When calculating the absolute position, we try to follow the "undone deletions". This yields
+ * better results for the user who performed undo. However, only the user who performed the undo
+ * will get the better results, the other users don't know which operations recreated a deleted
+ * range of content. There is more information in this ticket: https://github.com/yjs/yjs/issues/638
+ *
+ * @param {RelativePosition} rpos
+ * @param {Doc} doc
+ * @param {boolean} followUndoneDeletions - whether to follow undone deletions - see https://github.com/yjs/yjs/issues/638
+ * @param {import('../utils/AttributionManager.js').AbstractAttributionManager} attributionManager
+ * @return {AbsolutePosition|null}
+ *
+ * @function
+ */
+export const createAbsolutePositionFromRelativePosition = (rpos, doc, followUndoneDeletions = true, attributionManager = noAttributionsManager) => {
+  const store = doc.store
+  const rightID = rpos.item
+  const typeID = rpos.type
+  const tname = rpos.tname
+  const assoc = rpos.assoc
+  let type = null
+  let index = 0
+  if (rightID !== null) {
+    if (getState(store, rightID.client) <= rightID.clock) {
+      return null
+    }
+    const res = followUndoneDeletions ? followRedone(store, rightID) : getItemWithOffset(store, rightID)
+    const right = res.item
+    if (!(right instanceof Item)) {
+      return null
+    }
+    type = /** @type {AbstractType<any>} */ (right.parent)
+    if (type._item === null || !type._item.deleted) {
+      index = attributionManager.contentLength(right) === 0 ? 0 : (res.diff + (assoc >= 0 ? 0 : 1)) // adjust position based on left association if necessary
+      let n = right.left
+      while (n !== null) {
+        index += attributionManager.contentLength(n)
+        n = n.left
+      }
+    }
+  } else {
+    if (tname !== null) {
+      type = doc.get(tname)
+    } else if (typeID !== null) {
+      if (getState(store, typeID.client) <= typeID.clock) {
+        // type does not exist yet
+        return null
+      }
+      const { item } = followUndoneDeletions ? followRedone(store, typeID) : { item: getItem(store, typeID) }
+      if (item instanceof Item && item.content instanceof ContentType) {
+        type = item.content.type
+      } else {
+        // struct is garbage collected
+        return null
+      }
+    } else {
+      throw error.unexpectedCase()
+    }
+    if (assoc >= 0) {
+      index = type._length
+    } else {
+      index = 0
+    }
+  }
+  return createAbsolutePosition(type, index, rpos.assoc)
+}
+
+/**
+ * @param {RelativePosition|null} a
+ * @param {RelativePosition|null} b
+ * @return {boolean}
+ *
+ * @function
+ */
+export const compareRelativePositions = (a, b) => a === b || (
+  a !== null && b !== null && a.tname === b.tname && compareIDs(a.item, b.item) && compareIDs(a.type, b.type) && a.assoc === b.assoc
+)

package/src/utils/Snapshot.js

@@ -0,0 +1,220 @@
+import {
+  createDeleteSetFromStructStore,
+  getStateVector,
+  getItemCleanStart,
+  iterateStructsByIdSet,
+  writeIdSet,
+  writeStateVector,
+  readIdSet,
+  readStateVector,
+  createIdSet,
+  createID,
+  getState,
+  findIndexSS,
+  UpdateEncoderV2,
+  applyUpdateV2,
+  LazyStructReader,
+  equalIdSets,
+  UpdateDecoderV1, UpdateDecoderV2, IdSetEncoderV1, IdSetEncoderV2, DSDecoderV1, DSDecoderV2, Transaction, Doc, IdSet, Item, // eslint-disable-line
+  mergeIdSets
+} from '../internals.js'
+
+import * as map from 'lib0/map'
+import * as set from 'lib0/set'
+import * as decoding from 'lib0/decoding'
+import * as encoding from 'lib0/encoding'
+
+export class Snapshot {
+  /**
+   * @param {IdSet} ds
+   * @param {Map<number,number>} sv state map
+   */
+  constructor (ds, sv) {
+    /**
+     * @type {IdSet}
+     */
+    this.ds = ds
+    /**
+     * State Map
+     * @type {Map<number,number>}
+     */
+    this.sv = sv
+  }
+}
+
+/**
+ * @param {Snapshot} snap1
+ * @param {Snapshot} snap2
+ * @return {boolean}
+ */
+export const equalSnapshots = (snap1, snap2) => {
+  const sv1 = snap1.sv
+  const sv2 = snap2.sv
+  if (sv1.size !== sv2.size) {
+    return false
+  }
+  for (const [key, value] of sv1.entries()) {
+    if (sv2.get(key) !== value) {
+      return false
+    }
+  }
+  return equalIdSets(snap1.ds, snap2.ds)
+}
+
+/**
+ * @param {Snapshot} snapshot
+ * @param {IdSetEncoderV1 | IdSetEncoderV2} [encoder]
+ * @return {Uint8Array}
+ */
+export const encodeSnapshotV2 = (snapshot, encoder = new IdSetEncoderV2()) => {
+  writeIdSet(encoder, snapshot.ds)
+  writeStateVector(encoder, snapshot.sv)
+  return encoder.toUint8Array()
+}
+
+/**
+ * @param {Snapshot} snapshot
+ * @return {Uint8Array}
+ */
+export const encodeSnapshot = snapshot => encodeSnapshotV2(snapshot, new IdSetEncoderV1())
+
+/**
+ * @param {Uint8Array} buf
+ * @param {DSDecoderV1 | DSDecoderV2} [decoder]
+ * @return {Snapshot}
+ */
+export const decodeSnapshotV2 = (buf, decoder = new DSDecoderV2(decoding.createDecoder(buf))) => {
+  return new Snapshot(readIdSet(decoder), readStateVector(decoder))
+}
+
+/**
+ * @param {Uint8Array} buf
+ * @return {Snapshot}
+ */
+export const decodeSnapshot = buf => decodeSnapshotV2(buf, new DSDecoderV1(decoding.createDecoder(buf)))
+
+/**
+ * @param {IdSet} ds
+ * @param {Map<number,number>} sm
+ * @return {Snapshot}
+ */
+export const createSnapshot = (ds, sm) => new Snapshot(ds, sm)
+
+export const emptySnapshot = createSnapshot(createIdSet(), new Map())
+
+/**
+ * @param {Doc} doc
+ * @return {Snapshot}
+ */
+export const snapshot = doc => createSnapshot(createDeleteSetFromStructStore(doc.store), getStateVector(doc.store))
+
+/**
+ * @param {Item} item
+ * @param {Snapshot|undefined} snapshot
+ *
+ * @protected
+ * @function
+ */
+export const isVisible = (item, snapshot) => snapshot === undefined
+  ? !item.deleted
+  : snapshot.sv.has(item.id.client) && (snapshot.sv.get(item.id.client) || 0) > item.id.clock && !snapshot.ds.hasId(item.id)
+
+/**
+ * @param {Transaction} transaction
+ * @param {Snapshot} snapshot
+ */
+export const splitSnapshotAffectedStructs = (transaction, snapshot) => {
+  const meta = map.setIfUndefined(transaction.meta, splitSnapshotAffectedStructs, set.create)
+  const store = transaction.doc.store
+  // check if we already split for this snapshot
+  if (!meta.has(snapshot)) {
+    snapshot.sv.forEach((clock, client) => {
+      if (clock < getState(store, client)) {
+        getItemCleanStart(transaction, createID(client, clock))
+      }
+    })
+    iterateStructsByIdSet(transaction, snapshot.ds, _item => {})
+    meta.add(snapshot)
+  }
+}
+
+/**
+ * @example
+ *  const ydoc = new Y.Doc({ gc: false })
+ *  ydoc.getText().insert(0, 'world!')
+ *  const snapshot = Y.snapshot(ydoc)
+ *  ydoc.getText().insert(0, 'hello ')
+ *  const restored = Y.createDocFromSnapshot(ydoc, snapshot)
+ *  assert(restored.getText().toString() === 'world!')
+ *
+ * @param {Doc} originDoc
+ * @param {Snapshot} snapshot
+ * @param {Doc} [newDoc] Optionally, you may define the Yjs document that receives the data from originDoc
+ * @return {Doc}
+ */
+export const createDocFromSnapshot = (originDoc, snapshot, newDoc = new Doc()) => {
+  if (originDoc.gc) {
+    // we should not try to restore a GC-ed document, because some of the restored items might have their content deleted
+    throw new Error('Garbage-collection must be disabled in `originDoc`!')
+  }
+  const { sv, ds } = snapshot
+
+  const encoder = new UpdateEncoderV2()
+  originDoc.transact(transaction => {
+    let size = 0
+    sv.forEach(clock => {
+      if (clock > 0) {
+        size++
+      }
+    })
+    encoding.writeVarUint(encoder.restEncoder, size)
+    // splitting the structs before writing them to the encoder
+    for (const [client, clock] of sv) {
+      if (clock === 0) {
+        continue
+      }
+      if (clock < getState(originDoc.store, client)) {
+        getItemCleanStart(transaction, createID(client, clock))
+      }
+      const structs = originDoc.store.clients.get(client) || []
+      const lastStructIndex = findIndexSS(structs, clock - 1)
+      // write # encoded structs
+      encoding.writeVarUint(encoder.restEncoder, lastStructIndex + 1)
+      encoder.writeClient(client)
+      // first clock written is 0
+      encoding.writeVarUint(encoder.restEncoder, 0)
+      for (let i = 0; i <= lastStructIndex; i++) {
+        structs[i].write(encoder, 0, 0)
+      }
+    }
+    writeIdSet(encoder, ds)
+  })
+
+  applyUpdateV2(newDoc, encoder.toUint8Array(), 'snapshot')
+  return newDoc
+}
+
+/**
+ * @param {Snapshot} snapshot
+ * @param {Uint8Array} update
+ * @param {typeof UpdateDecoderV2 | typeof UpdateDecoderV1} [YDecoder]
+ */
+export const snapshotContainsUpdateV2 = (snapshot, update, YDecoder = UpdateDecoderV2) => {
+  const structs = []
+  const updateDecoder = new YDecoder(decoding.createDecoder(update))
+  const lazyDecoder = new LazyStructReader(updateDecoder, false)
+  for (let curr = lazyDecoder.curr; curr !== null; curr = lazyDecoder.next()) {
+    structs.push(curr)
+    if ((snapshot.sv.get(curr.id.client) || 0) < curr.id.clock + curr.length) {
+      return false
+    }
+  }
+  const mergedDS = mergeIdSets([snapshot.ds, readIdSet(updateDecoder)])
+  return equalIdSets(snapshot.ds, mergedDS)
+}
+
+/**
+ * @param {Snapshot} snapshot
+ * @param {Uint8Array} update
+ */
+export const snapshotContainsUpdate = (snapshot, update) => snapshotContainsUpdateV2(snapshot, update, UpdateDecoderV1)

package/src/utils/StructSet.js

@@ -0,0 +1,137 @@
+import {
+  createID,
+  readItemContent,
+  findIndexCleanStart,
+  Skip,
+  UpdateDecoderV1, UpdateDecoderV2, IdSet, Doc, GC, Item, ID, // eslint-disable-line
+} from '../internals.js'
+
+import * as decoding from 'lib0/decoding'
+import * as binary from 'lib0/binary'
+import * as map from 'lib0/map'
+
+/**
+ * @param {UpdateDecoderV1 | UpdateDecoderV2} decoder The decoder object to read data from.
+ * @param {Doc} doc
+ * @return {StructSet}
+ *
+ * @private
+ * @function
+ */
+export const readStructSet = (decoder, doc) => {
+  const clientRefs = new StructSet()
+  const numOfStateUpdates = decoding.readVarUint(decoder.restDecoder)
+  for (let i = 0; i < numOfStateUpdates; i++) {
+    const numberOfStructs = decoding.readVarUint(decoder.restDecoder)
+    /**
+     * @type {Array<GC|Item>}
+     */
+    const refs = new Array(numberOfStructs)
+    const client = decoder.readClient()
+    let clock = decoding.readVarUint(decoder.restDecoder)
+    clientRefs.clients.set(client, new StructRange(refs))
+    for (let i = 0; i < numberOfStructs; i++) {
+      const info = decoder.readInfo()
+      switch (binary.BITS5 & info) {
+        case 0: { // GC
+          const len = decoder.readLen()
+          refs[i] = new GC(createID(client, clock), len)
+          clock += len
+          break
+        }
+        case 10: { // Skip Struct (nothing to apply)
+          // @todo we could reduce the amount of checks by adding Skip struct to clientRefs so we know that something is missing.
+          const len = decoding.readVarUint(decoder.restDecoder)
+          refs[i] = new Skip(createID(client, clock), len)
+          clock += len
+          break
+        }
+        default: { // Item with content
+          /**
+           * The optimized implementation doesn't use any variables because inlining variables is faster.
+           * Below a non-optimized version is shown that implements the basic algorithm with
+           * a few comments
+           */
+          const cantCopyParentInfo = (info & (binary.BIT7 | binary.BIT8)) === 0
+          // If parent = null and neither left nor right are defined, then we know that `parent` is child of `y`
+          // and we read the next string as parentYKey.
+          // It indicates how we store/retrieve parent from `y.share`
+          // @type {string|null}
+          const struct = new Item(
+            createID(client, clock),
+            null, // left
+            (info & binary.BIT8) === binary.BIT8 ? decoder.readLeftID() : null, // origin
+            null, // right
+            (info & binary.BIT7) === binary.BIT7 ? decoder.readRightID() : null, // right origin
+            cantCopyParentInfo ? (decoder.readParentInfo() ? doc.get(decoder.readString()) : decoder.readLeftID()) : null, // parent
+            cantCopyParentInfo && (info & binary.BIT6) === binary.BIT6 ? decoder.readString() : null, // parentSub
+            readItemContent(decoder, info) // item content
+          )
+          refs[i] = struct
+          clock += struct.length
+        }
+      }
+    }
+  }
+  return clientRefs
+}
+
+/**
+ * Remove item-ranges from the StructSet.
+ *
+ * @param {StructSet} ss
+ * @param {IdSet} exclude
+ */
+export const removeRangesFromStructSet = (ss, exclude) => {
+  // @todo walk through ss instead to reduce iterations
+  exclude.clients.forEach((range, client) => {
+    const structs = /** @type {StructRange} */ (ss.clients.get(client))?.refs
+    if (structs != null) {
+      const firstStruct = structs[0]
+      const lastStruct = structs[structs.length - 1]
+      const idranges = range.getIds()
+      for (let i = 0; i < idranges.length; i++) {
+        const range = idranges[i]
+        let startIndex = 0
+        if (range.clock >= lastStruct.id.clock + lastStruct.length) continue
+        if (range.clock > firstStruct.id.clock) {
+          startIndex = findIndexCleanStart(null, structs, range.clock)
+        }
+        let endIndex = structs.length // must be set here, after structs is modified
+        if (range.clock + range.len <= firstStruct.id.clock) continue
+        if (range.clock + range.len < lastStruct.id.clock + lastStruct.length) {
+          endIndex = findIndexCleanStart(null, structs, range.clock + range.len)
+        }
+        if (startIndex < endIndex) {
+          structs[startIndex] = new Skip(new ID(client, range.clock), range.len)
+          const d = endIndex - startIndex
+          if (d > 1) {
+            structs.splice(startIndex + 1, d - 1)
+          }
+        }
+      }
+    }
+  })
+}
+
+class StructRange {
+  /**
+   * @param {Array<Item|GC>} refs
+   */
+  constructor (refs) {
+    this.i = 0
+    /**
+     * @type {Array<Item | GC>}
+     */
+    this.refs = refs
+  }
+}
+
+export class StructSet {
+  constructor () {
+    /**
+     * @type {Map<number, StructRange>}
+     */
+    this.clients = map.create()
+  }
+}