lib0 0.2.112 → 0.2.115-0

package/delta/ops.js

@@ -0,0 +1,544 @@
+import * as d from './abstract.js'
+import * as object from '../object.js'
+import * as traits from '../traits.js'
+import * as fun from '../function.js'
+import * as s from '../schema.js'
+import * as list from '../list.js'
+
+/**
+ * @template {any} Content
+ * @typedef {TextOp|InsertOp<Content>|RetainOp|DeleteOp|(Content extends d.AbstractDelta ? ModifyOp<Extract<Content,d.AbstractDelta>> : never)} AbstractDeltaArrayOps
+ */
+
+/**
+ * @template Content
+ * @template {boolean} [WithText=false]
+ * @typedef {InsertOp<Content>|RetainOp|DeleteOp|(Content extends d.AbstractDelta ? ModifyOp<Extract<Content,d.AbstractDelta>> : never)|(WithText extends true ? TextOp : never)} DeltaArrayOps
+ */
+
+/**
+ * @template Embeds
+ * @typedef {TextOp|InsertOp<Embeds>|RetainOp|DeleteOp|(Embeds extends d.AbstractDelta ? ModifyOp<Extract<Embeds,d.AbstractDelta>> : never)} DeltaTextOps
+ */
+
+/**
+ * @template {any} Content
+ * @typedef {AbstractDeltaArrayOps<Content>} NodeChildrenOps
+ */
+
+/**
+ * @typedef {s.Unwrap<$anyOp>} DeltaOps
+ */
+
+/**
+ * @typedef {MapInsertOp<any>|MapDeleteOp<any>|MapModifyOp<any>} DeltaMapOps
+ */
+
+/**
+ * @typedef {MapInsertOp<any,''>|MapDeleteOp<any,''>|MapModifyOp<any,''>} DeltaValueOps
+ */
+
+/**
+ * @typedef {{ [key: string]: any }} FormattingAttributes
+ */
+
+/**
+ * @typedef {{ insert: string|object, attributes?: { [key: string]: any }, attribution?: d.Attribution } | { delete: number } | { retain: number, attributes?: { [key:string]: any }, attribution?: d.Attribution } | { modify: object }} DeltaJsonOp
+ */
+
+/**
+ * @template {{[key:string]: any} | null} Attrs
+ * @param {Attrs} attrs
+ * @return {Attrs}
+ */
+const _cloneAttrs = attrs => attrs == null ? attrs : { ...attrs }
+/**
+ * @template {any} MaybeDelta
+ * @param {MaybeDelta} maybeDelta
+ * @return {MaybeDelta}
+ */
+const _cloneMaybeDelta = maybeDelta => d.$delta.check(maybeDelta) ? maybeDelta.clone() : maybeDelta
+
+export class TextOp extends list.ListNode {
+  /**
+   * @param {string} insert
+   * @param {FormattingAttributes|null} attributes
+   * @param {d.Attribution|null} attribution
+   */
+  constructor (insert, attributes, attribution) {
+    super()
+    this.insert = insert
+    this.attributes = attributes
+    this.attribution = attribution
+  }
+
+  /**
+   * @return {'insert'}
+   */
+  get type () {
+    return 'insert'
+  }
+
+  get length () {
+    return this.insert.length
+  }
+
+  /**
+   * Remove a part of the operation (similar to Array.splice)
+   *
+   * @param {number} offset
+   * @param {number} len
+   */
+  _splice (offset, len) {
+    this.insert = this.insert.slice(0, offset) + this.insert.slice(offset + len)
+  }
+
+  /**
+   * @return {DeltaJsonOp}
+   */
+  toJSON () {
+    return object.assign({ insert: this.insert }, this.attributes ? { attributes: this.attributes } : ({}), this.attribution ? { attribution: this.attribution } : ({}))
+  }
+
+  /**
+   * @param {TextOp} other
+   */
+  [traits.EqualityTraitSymbol] (other) {
+    return fun.equalityDeep(this.insert, other.insert) && fun.equalityDeep(this.attributes, other.attributes) && fun.equalityDeep(this.attribution, other.attribution)
+  }
+
+  /**
+   * @return {TextOp}
+   */
+  clone () {
+    return new TextOp(this.insert, _cloneAttrs(this.attributes), _cloneAttrs(this.attribution))
+  }
+}
+
+/**
+ * @template {any} ArrayContent
+ */
+export class InsertOp extends list.ListNode {
+  /**
+   * @param {Array<ArrayContent>} insert
+   * @param {FormattingAttributes|null} attributes
+   * @param {d.Attribution|null} attribution
+   */
+  constructor (insert, attributes, attribution) {
+    super()
+    this.insert = insert
+    this.attributes = attributes
+    this.attribution = attribution
+  }
+
+  /**
+   * @return {'insert'}
+   */
+  get type () {
+    return 'insert'
+  }
+
+  get length () {
+    return this.insert.length
+  }
+
+  /**
+   * Remove a part of the operation (similar to Array.splice)
+   *
+   * @param {number} offset
+   * @param {number} len
+   */
+  _splice (offset, len) {
+    this.insert.splice(offset, len)
+  }
+
+  /**
+   * @return {DeltaJsonOp}
+   */
+  toJSON () {
+    return object.assign({ insert: this.insert.map(ins => d.$delta.check(ins) ? ins.toJSON() : ins) }, this.attributes ? { attributes: this.attributes } : ({}), this.attribution ? { attribution: this.attribution } : ({}))
+  }
+
+  /**
+   * @param {InsertOp<ArrayContent>} other
+   */
+  [traits.EqualityTraitSymbol] (other) {
+    return fun.equalityDeep(this.insert, other.insert) && fun.equalityDeep(this.attributes, other.attributes) && fun.equalityDeep(this.attribution, other.attribution)
+  }
+
+  /**
+   * @return {InsertOp<ArrayContent>}
+   */
+  clone () {
+    return new InsertOp(this.insert.slice(), _cloneAttrs(this.attributes), _cloneAttrs(this.attribution))
+  }
+}
+
+export class DeleteOp extends list.ListNode {
+  /**
+   * @param {number} len
+   */
+  constructor (len) {
+    super()
+    this.delete = len
+  }
+
+  /**
+   * @return {'delete'}
+   */
+  get type () {
+    return 'delete'
+  }
+
+  get length () {
+    return 0
+  }
+
+  /**
+   * Remove a part of the operation (similar to Array.splice)
+   *
+   * @param {number} offset
+   * @param {number} len
+   */
+  _splice (offset, len) {
+    this.delete -= len
+  }
+
+  /**
+   * @return {DeltaJsonOp}
+   */
+  toJSON () {
+    return { delete: this.delete }
+  }
+
+  /**
+   * @param {DeleteOp} other
+   */
+  [traits.EqualityTraitSymbol] (other) {
+    return this.delete === other.delete
+  }
+
+  clone () {
+    return new DeleteOp(this.delete)
+  }
+}
+
+export class RetainOp extends list.ListNode {
+  /**
+   * @param {number} retain
+   * @param {FormattingAttributes|null} attributes
+   * @param {d.Attribution|null} attribution
+   */
+  constructor (retain, attributes, attribution) {
+    super()
+    this.retain = retain
+    this.attributes = attributes
+    this.attribution = attribution
+  }
+
+  /**
+   * @return {'retain'}
+   */
+  get type () {
+    return 'retain'
+  }
+
+  get length () {
+    return this.retain
+  }
+
+  /**
+   * Remove a part of the operation (similar to Array.splice)
+   *
+   * @param {number} _offset
+   * @param {number} len
+   */
+  _splice (_offset, len) {
+    this.retain -= len
+  }
+
+  /**
+   * @return {DeltaJsonOp}
+   */
+  toJSON () {
+    return object.assign({ retain: this.retain }, this.attributes ? { attributes: this.attributes } : {}, this.attribution ? { attribution: this.attribution } : {})
+  }
+
+  /**
+   * @param {RetainOp} other
+   */
+  [traits.EqualityTraitSymbol] (other) {
+    return this.retain === other.retain && fun.equalityDeep(this.attributes, other.attributes) && fun.equalityDeep(this.attribution, other.attribution)
+  }
+
+  clone () {
+    return new RetainOp(this.retain, _cloneAttrs(this.attributes), _cloneAttrs(this.attribution))
+  }
+}
+
+/**
+ * Delta that can be applied on a YType Embed
+ *
+ * @template {{ toJSON(): any } & traits.EqualityTrait & { clone: any }} DTypes
+ */
+export class ModifyOp extends list.ListNode {
+  /**
+   * @param {DTypes} delta
+   * @param {FormattingAttributes|null} attributes
+   * @param {d.Attribution|null} attribution
+   */
+  constructor (delta, attributes, attribution) {
+    super()
+    this.modify = delta
+    this.attributes = attributes
+    this.attribution = attribution
+  }
+
+  /**
+   * @return {'modify'}
+   */
+  get type () {
+    return 'modify'
+  }
+
+  get length () {
+    return 1
+  }
+
+  /**
+   * Remove a part of the operation (similar to Array.splice)
+   *
+   * @param {number} _offset
+   * @param {number} len
+   */
+  _splice (_offset, len) {
+  }
+
+  /**
+   * @return {DeltaJsonOp}
+   */
+  toJSON () {
+    return object.assign({ modify: this.modify.toJSON() }, this.attributes ? { attributes: this.attributes } : {}, this.attribution ? { attribution: this.attribution } : {})
+  }
+
+  /**
+   * @param {ModifyOp<any>} other
+   */
+  [traits.EqualityTraitSymbol] (other) {
+    return this.modify[traits.EqualityTraitSymbol](other.modify) && fun.equalityDeep(this.attributes, other.attributes) && fun.equalityDeep(this.attribution, other.attribution)
+  }
+
+  /**
+   * @return {ModifyOp<DTypes>}
+   */
+  clone () {
+    return new ModifyOp(this.modify.clone(), _cloneAttrs(this.attributes), _cloneAttrs(this.attribution))
+  }
+}
+
+/**
+ * @template V
+ * @template [K=string]
+ */
+export class MapInsertOp {
+  /**
+   * @param {K} key
+   * @param {V} value
+   * @param {V|undefined} prevValue
+   * @param {s.TypeOf<d.$attribution>?} attribution
+   */
+  constructor (key, value, prevValue, attribution) {
+    /**
+     * @type {K}
+     */
+    this.key = key
+    /**
+     * @type {V}
+     */
+    this.value = value
+    /**
+     * @type {V|undefined}
+     */
+    this.prevValue = prevValue
+    this.attribution = attribution
+  }
+
+  /**
+   * @return {'insert'}
+   */
+  get type () { return 'insert' }
+
+  toJSON () {
+    return {
+      type: this.type,
+      value: d.$delta.check(this.value) ? this.value.toJSON() : this.value,
+      attribution: this.attribution
+    }
+  }
+
+  /**
+   * @param {MapInsertOp<V>} other
+   */
+  [traits.EqualityTraitSymbol] (other) {
+    return this.key === other.key && fun.equalityDeep(this.value, other.value) && fun.equalityDeep(this.attribution, other.attribution)
+  }
+
+  /**
+   * @return {MapInsertOp<V,K>}
+   */
+  clone () {
+    return new MapInsertOp(this.key, _cloneMaybeDelta(this.value), _cloneMaybeDelta(this.prevValue), _cloneAttrs(this.attribution))
+  }
+}
+
+/**
+ * @template V
+ * @template [K=string]
+ */
+export class MapDeleteOp {
+  /**
+   * @param {K} key
+   * @param {V|undefined} prevValue
+   * @param {s.TypeOf<d.$attribution>?} attribution
+   */
+  constructor (key, prevValue, attribution) {
+    /**
+     * @type {K}
+     */
+    this.key = key
+    /**
+     * @type {V|undefined}
+     */
+    this.prevValue = prevValue
+    this.attribution = attribution
+  }
+
+  get value () { return undefined }
+
+  /**
+   * @type {'delete'}
+   */
+  get type () { return 'delete' }
+
+  toJSON () {
+    return {
+      type: this.type,
+      attribution: this.attribution
+    }
+  }
+
+  /**
+   * @param {MapDeleteOp<V>} other
+   */
+  [traits.EqualityTraitSymbol] (other) {
+    return this.key === other.key && fun.equalityDeep(this.attribution, other.attribution)
+  }
+
+  clone () {
+    return new MapDeleteOp(this.key, _cloneMaybeDelta(this.prevValue), _cloneAttrs(this.attribution))
+  }
+}
+
+/**
+ * @template {d.AbstractDelta} Modifiers
+ * @template [K=string]
+ */
+export class MapModifyOp {
+  /**
+   * @param {K} key
+   * @param {Modifiers} delta
+   */
+  constructor (key, delta) {
+    /**
+     * @type {K}
+     */
+    this.key = key
+    /**
+     * @type {Modifiers}
+     */
+    this.value = delta
+  }
+
+  /**
+   * @type {'modify'}
+   */
+  get type () { return 'modify' }
+
+  toJSON () {
+    return {
+      type: this.type,
+      value: this.value.toJSON()
+    }
+  }
+
+  /**
+   * @param {MapModifyOp<Modifiers>} other
+   */
+  [traits.EqualityTraitSymbol] (other) {
+    return this.key === other.key && this.value[traits.EqualityTraitSymbol](other.value)
+  }
+
+  /**
+   * @return {MapModifyOp<Modifiers,K>}
+   */
+  clone () {
+    return new MapModifyOp(this.key, this.value.clone())
+  }
+}
+
+export const $deltaMapChangeJson = s.$union(
+  s.$object({ type: s.$literal('insert'), value: s.$any, attribution: d.$attribution.nullable.optional }),
+  s.$object({ type: s.$literal('modify'), value: s.$any }),
+  s.$object({ type: s.$literal('delete'), attribution: d.$attribution.nullable.optional })
+)
+
+/**
+ * @type {s.Schema<MapDeleteOp<any> | DeleteOp>}
+ */
+export const $deleteOp = s.$custom(o => o != null && (o.constructor === DeleteOp || o.constructor === MapDeleteOp))
+
+/**
+ * @type {s.Schema<MapInsertOp<any> | InsertOp<any>>}
+ */
+export const $insertOp = s.$custom(o => o != null && (o.constructor === MapInsertOp || o.constructor === InsertOp))
+
+/**
+ * @template Content
+ * @param {s.Schema<Content>} $content
+ * @return {s.Schema<MapInsertOp<Content> | InsertOp<Content>>}
+ */
+export const $insertOpWith = $content => s.$custom(o =>
+  o != null && (
+    (o.constructor === MapInsertOp && $content.check(/** @type {MapInsertOp<Content>} */ (o).value)) ||
+      (o.constructor === InsertOp && /** @type {InsertOp<Content>} */ (o).insert.every(ins => $content.check(ins)))
+  )
+)
+
+/**
+ * @type {s.Schema<TextOp>}
+ */
+export const $textOp = s.$constructedBy(TextOp)
+
+/**
+ * @type {s.Schema<RetainOp>}
+ */
+export const $retainOp = s.$constructedBy(RetainOp)
+
+/**
+ * @type {s.Schema<MapModifyOp<any> | ModifyOp<any>>}
+ */
+export const $modifyOp = s.$custom(o => o != null && (o.constructor === MapModifyOp || o.constructor === ModifyOp))
+
+/**
+ * @template {d.AbstractDelta} Modify
+ * @param {s.Schema<Modify>} $content
+ * @return {s.Schema<MapModifyOp<Modify> | ModifyOp<Modify>>}
+ */
+export const $modifyOpWith = $content => s.$custom(o =>
+  o != null && (
+    (o.constructor === MapModifyOp && $content.check(/** @type {MapModifyOp<Modify>} */ (o).value)) ||
+      (o.constructor === ModifyOp && $content.check(/** @type {ModifyOp<Modify>} */ (o).modify))
+  )
+)
+
+export const $anyOp = s.$union($insertOp, $deleteOp, $textOp, $modifyOp)

package/delta/readme.md

@@ -0,0 +1,129 @@
+# Deltas
+
+- Enable you to efficiently represent changes on all kinds of data structures.
+- Support schemas
+- Support OT-style conflict resolution `delta2.apply(delta1.rebase(delta2, true)) === delta1.apply(delta2.rebase(delta1, false))`
+- nice typings
+
+## Delta for Map-like structures
+
+```javascript
+// define schema
+const $d = delta.$delta(s.$any, { attr1: s.$string, attr2: s.$number })
+const d = delta.create($d)
+
+
+// create an update
+const update = delta.create().set('attr1', 'val1').set('attr2', 42)
+d.apply(update)
+
+// In case  of an invalid update
+const update2 = delta.create().set('attr1', 42)
+// it is possible to check an update beforehand
+$d.check(update2) // => false
+// and you also get type errors
+d.apply(update2) // type error: expected 'attr1' to be of type string
+```
+
+## Delta for Text-like structures
+
+Text-like deltas work similarly to [Quill Deltas]{https://quilljs.com/docs/delta}
+
+```javascript
+// define schema
+const $d = delta.$delta(s.$any, null, s.$string)
+const d = delta.create($d).insert('hello world')
+
+// create an update
+const update = delta.create().retain(11).insert('!')
+d.apply(update)
+
+// In case  of an invalid update
+const update2 = delta.create().insert([{ some: 'object' }])
+// it is possible to check an update beforehando
+$d.check(update2) // => false
+// and you also get type errors
+d.apply(update2) // type error: unexpected attribute 'attr1'
+```
+
+## Delta for Array-like structures
+
+```javascript
+// define schema
+const $d = delta.$delta(s.$any, null, s.$array(s.object({ some: s.$string }, s.$string)))
+const d = delta.create($d).insert(['hello world'])
+
+// create an update
+const update = delta.create().retain(1).insert({ some: 'object' })
+d.apply(update)
+
+// In case  of an invalid update
+const update2 = delta.create().insert([{ unknown: 'prop' }])
+// it is possible to check an update beforehando
+$d.check(update2) // => false
+// and you also get type errors
+d.apply(update2) // type error: { unknown: 'prop' } is not assignable to { some: string }
+```
+
+## Delta for Node-like structures (similar to XML,Trees with named nodes)
+
+```javascript
+// define schema for a 'p'|'h1' node that may contain text or other instances of itself
+const $d = delta.$delta(s.$literal('div', 'p', 'h1'), { style: s.$string }, s.$string, true))
+const d = delta.create('div', $d)
+
+// create an update - insert paragraph into the <div>
+const update = delta.create().insert([delta.create('p', { style: 'bold: true' }, 'hello world')])
+d.apply(update)
+
+// modify the paragraph by deleting the text 'world' and appending '!'
+d.apply(delta.create().modify(
+  delta.create().retain(6).delete(5).insert('!')
+))
+```
+
+# Transformers
+
+We often have two different data structures that we want to sync. There might be
+slight differences between those data structures. I.e. we might have a Yjs data
+structure containing the following content:
+
+```javascript
+/**
+ * { 
+ *   headline: {{ headline }},
+ *   content: {{ content }}
+ * }
+ */
+const $data = s.$delta(null, { headline: s.$string, content: s.$string })
+```
+
+A typical scenario is that we want to sync that to the dom and back. "two-way bindings"
+- When the Yjs struucture updates, we want to sync the changes to the dom.
+- When the dom is updated (because the dom is a `contenteditable` editor), we
+want to sync back the changes to the yjs structure.
+
+Now, the dom might look like this:
+
+```javascript
+/**
+ * <div>
+ *   <h1 style='some custom style'>{{headline}}</h1>
+ *   <span>dturianed</span>
+ *   <p>{{content}}</p>
+ * </div>
+ */
+```
+
+We can achieve automattic back-and-forth transformations with delta
+transformers:
+
+```javascript
+const Λdata = Λ.transform($data, $d =>
+    Λ.delta('div', {}, [
+        Λ.delta('h1', { style: 'bold:true' }, [Λ.query('headline')($d)], []),
+        Λ.delta('p', null, [Λ.query('content')($d)])
+    ])
+)
+```
+

package/delta/text.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @template Embeds
+ * @typedef {import('./abstract-array.js').AbstractDeltaArray<'text',import('./ops.js').DeltaTextOps<Embeds>>} DeltaText
+ */
+/**
+ * @template {any} Embeds
+ * @extends {AbstractDeltaArrayBuilder<'text',import('./ops.js').DeltaTextOps<Embeds>>}
+ */
+export class DeltaTextBuilder<Embeds extends unknown> extends AbstractDeltaArrayBuilder<"text", import("./ops.js").DeltaTextOps<Embeds>> {
+    /**
+     * @param {s.Schema<Embeds>} $embeds
+     */
+    constructor($embeds: s.Schema<Embeds>);
+}
+/**
+ * @overload
+ * @return {DeltaTextBuilder<never>}
+ */
+export function text(): DeltaTextBuilder<never>;
+/**
+ * @overload
+ * @param {string} [content]
+ * @return {DeltaTextBuilder<never>}
+ */
+export function text(content?: string | undefined): DeltaTextBuilder<never>;
+/**
+ * @template Embeds
+ * @overload
+ * @param {s.Schema<Embeds>} [$embeds]
+ * @return {DeltaTextBuilder<Embeds>}
+ */
+export function text<Embeds>($embeds?: s.Schema<Embeds> | undefined): DeltaTextBuilder<Embeds>;
+export function $text<Vals extends {
+    [key: string]: any;
+}>($embeds: s.Schema<Vals>): s.Schema<DeltaText<Vals>>;
+/**
+ * @return {s.Schema<DeltaText<any>>}
+ */
+export const $textAny: s.Schema<DeltaText<any>>;
+export type DeltaText<Embeds_1> = import("./abstract-array.js").AbstractDeltaArray<"text", import("./ops.js").DeltaTextOps<Embeds_1>>;
+import { AbstractDeltaArrayBuilder } from './abstract-array.js';
+import * as s from '../schema.js';
+//# sourceMappingURL=text.d.ts.map

package/delta/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["text.js"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;GAGG;AACH,8BAHmB,MAAM;IAIvB;;OAEG;IACH,qBAFW,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAI1B;CACF;;;;;AAGE,wBACS,gBAAgB,CAAC,KAAK,CAAC,CAClC;;;;;;AAEE,oDAES,gBAAgB,CAAC,KAAK,CAAC,CAClC;;;;;;;AAGE,qBADU,MAAM,2CAGP,gBAAgB,CAAC,MAAM,CAAC,CACnC;AAaM,sBAJ8B,IAAI,SAA5B;IAAG,CAAC,GAAG,EAAC,MAAM,GAAG,GAAG,CAAA;CAAG,WACzB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GACb,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAEsG;AAE3I;;GAEG;AACH,uBAAmC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAsC;kCAhDpF,OAAO,qBAAqB,EAAE,kBAAkB,CAAC,MAAM,EAAC,OAAO,UAAU,EAAE,YAAY,CAAC,QAAM,CAAC,CAAC;0CAJnE,qBAAqB;mBAD5C,cAAc"}