prosemirror-changeset 2.2.0 → 2.3.0

package/dist/index.d.cts

@@ -0,0 +1,156 @@
+import { Mark, Node } from 'prosemirror-model';
+import { StepMap } from 'prosemirror-transform';
+
+/**
+Stores metadata for a part of a change.
+*/
+declare class Span<Data = any> {
+    /**
+    The length of this span.
+    */
+    readonly length: number;
+    /**
+    The data associated with this span.
+    */
+    readonly data: Data;
+}
+/**
+A replaced range with metadata associated with it.
+*/
+declare class Change<Data = any> {
+    /**
+    The start of the range deleted/replaced in the old document.
+    */
+    readonly fromA: number;
+    /**
+    The end of the range in the old document.
+    */
+    readonly toA: number;
+    /**
+    The start of the range inserted in the new document.
+    */
+    readonly fromB: number;
+    /**
+    The end of the range in the new document.
+    */
+    readonly toB: number;
+    /**
+    Data associated with the deleted content. The length of these
+    spans adds up to `this.toA - this.fromA`.
+    */
+    readonly deleted: readonly Span<Data>[];
+    /**
+    Data associated with the inserted content. Length adds up to
+    `this.toB - this.fromB`.
+    */
+    readonly inserted: readonly Span<Data>[];
+    /**
+    This merges two changesets (the end document of x should be the
+    start document of y) into a single one spanning the start of x to
+    the end of y.
+    */
+    static merge<Data>(x: readonly Change<Data>[], y: readonly Change<Data>[], combine: (dataA: Data, dataB: Data) => Data): readonly Change<Data>[];
+}
+
+/**
+A token encoder can be passed when creating a `ChangeSet` in order
+to influence the way the library runs its diffing algorithm. The
+encoder determines how document tokens (such as nodes and
+characters) are encoded and compared.
+
+Note that both the encoding and the comparison may run a lot, and
+doing non-trivial work in these functions could impact
+performance.
+*/
+interface TokenEncoder<T> {
+    /**
+    Encode a given character, with the given marks applied.
+    */
+    encodeCharacter(char: number, marks: readonly Mark[]): T;
+    /**
+    Encode the start of a node or, if this is a leaf node, the
+    entire node.
+    */
+    encodeNodeStart(node: Node): T;
+    /**
+    Encode the end token for the given node. It is valid to encode
+    every end token in the same way.
+    */
+    encodeNodeEnd(node: Node): T;
+    /**
+    Compare the given tokens. Should return true when they count as
+    equal.
+    */
+    compareTokens(a: T, b: T): boolean;
+}
+
+/**
+Simplifies a set of changes for presentation. This makes the
+assumption that having both insertions and deletions within a word
+is confusing, and, when such changes occur without a word boundary
+between them, they should be expanded to cover the entire set of
+words (in the new document) they touch. An exception is made for
+single-character replacements.
+*/
+declare function simplifyChanges(changes: readonly Change[], doc: Node): Change<any>[];
+
+/**
+A change set tracks the changes to a document from a given point
+in the past. It condenses a number of step maps down to a flat
+sequence of replacements, and simplifies replacments that
+partially undo themselves by comparing their content.
+*/
+declare class ChangeSet<Data = any> {
+    /**
+    Replaced regions.
+    */
+    readonly changes: readonly Change<Data>[];
+    /**
+    Computes a new changeset by adding the given step maps and
+    metadata (either as an array, per-map, or as a single value to be
+    associated with all maps) to the current set. Will not mutate the
+    old set.
+    
+    Note that due to simplification that happens after each add,
+    incrementally adding steps might create a different final set
+    than adding all those changes at once, since different document
+    tokens might be matched during simplification depending on the
+    boundaries of the current changed ranges.
+    */
+    addSteps(newDoc: Node, maps: readonly StepMap[], data: Data | readonly Data[]): ChangeSet<Data>;
+    /**
+    The starting document of the change set.
+    */
+    get startDoc(): Node;
+    /**
+    Map the span's data values in the given set through a function
+    and construct a new set with the resulting data.
+    */
+    map(f: (range: Span<Data>) => Data): ChangeSet<Data>;
+    /**
+    Compare two changesets and return the range in which they are
+    changed, if any. If the document changed between the maps, pass
+    the maps for the steps that changed it as second argument, and
+    make sure the method is called on the old set and passed the new
+    set. The returned positions will be in new document coordinates.
+    */
+    changedRange(b: ChangeSet, maps?: readonly StepMap[]): {
+        from: number;
+        to: number;
+    } | null;
+    /**
+    Create a changeset with the given base object and configuration.
+    
+    The `combine` function is used to compare and combine metadata—it
+    should return null when metadata isn't compatible, and a combined
+    version for a merged range when it is.
+    
+    When given, a token encoder determines how document tokens are
+    serialized and compared when diffing the content produced by
+    changes. The default is to just compare nodes by name and text
+    by character, ignoring marks and attributes.
+    */
+    static create<Data = any>(doc: Node, combine?: (dataA: Data, dataB: Data) => Data, tokenEncoder?: TokenEncoder<any>): ChangeSet<Data>;
+}
+
+export { Change, ChangeSet, Span, type TokenEncoder, simplifyChanges };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Node } from 'prosemirror-model';
+import { Mark, Node } from 'prosemirror-model';
 import { StepMap } from 'prosemirror-transform';
 
 /**
@@ -41,7 +41,7 @@ declare class Change<Data = any> {
     readonly deleted: readonly Span<Data>[];
     /**
     Data associated with the inserted content. Length adds up to
-    `this.toB - this.toA`.
+    `this.toB - this.fromB`.
     */
     readonly inserted: readonly Span<Data>[];
     /**
@@ -52,6 +52,38 @@ declare class Change<Data = any> {
     static merge<Data>(x: readonly Change<Data>[], y: readonly Change<Data>[], combine: (dataA: Data, dataB: Data) => Data): readonly Change<Data>[];
 }
 
+/**
+A token encoder can be passed when creating a `ChangeSet` in order
+to influence the way the library runs its diffing algorithm. The
+encoder determines how document tokens (such as nodes and
+characters) are encoded and compared.
+
+Note that both the encoding and the comparison may run a lot, and
+doing non-trivial work in these functions could impact
+performance.
+*/
+interface TokenEncoder<T> {
+    /**
+    Encode a given character, with the given marks applied.
+    */
+    encodeCharacter(char: number, marks: readonly Mark[]): T;
+    /**
+    Encode the start of a node or, if this is a leaf node, the
+    entire node.
+    */
+    encodeNodeStart(node: Node): T;
+    /**
+    Encode the end token for the given node. It is valid to encode
+    every end token in the same way.
+    */
+    encodeNodeEnd(node: Node): T;
+    /**
+    Compare the given tokens. Should return true when they count as
+    equal.
+    */
+    compareTokens(a: T, b: T): boolean;
+}
+
 /**
 Simplifies a set of changes for presentation. This makes the
 assumption that having both insertions and deletions within a word
@@ -108,11 +140,17 @@ declare class ChangeSet<Data = any> {
     } | null;
     /**
     Create a changeset with the given base object and configuration.
+    
     The `combine` function is used to compare and combine metadata—it
     should return null when metadata isn't compatible, and a combined
     version for a merged range when it is.
+    
+    When given, a token encoder determines how document tokens are
+    serialized and compared when diffing the content produced by
+    changes. The default is to just compare nodes by name and text
+    by character, ignoring marks and attributes.
     */
-    static create<Data = any>(doc: Node, combine?: (dataA: Data, dataB: Data) => Data): ChangeSet<Data>;
+    static create<Data = any>(doc: Node, combine?: (dataA: Data, dataB: Data) => Data, tokenEncoder?: TokenEncoder<any>): ChangeSet<Data>;
 }
 
-export { Change, ChangeSet, Span, simplifyChanges };
+export { Change, ChangeSet, Span, type TokenEncoder, simplifyChanges };

package/dist/index.js

@@ -1,24 +1,30 @@
+const DefaultEncoder = {
+    encodeCharacter: char => char,
+    encodeNodeStart: node => node.type.name,
+    encodeNodeEnd: () => -1,
+    compareTokens: (a, b) => a === b
+};
 // Convert the given range of a fragment to tokens, where node open
 // tokens are encoded as strings holding the node name, characters as
 // their character code, and node close tokens as -1.
-function tokens(frag, start, end, target) {
+function tokens(frag, encoder, start, end, target) {
     for (let i = 0, off = 0; i < frag.childCount; i++) {
         let child = frag.child(i), endOff = off + child.nodeSize;
         let from = Math.max(off, start), to = Math.min(endOff, end);
         if (from < to) {
             if (child.isText) {
                 for (let j = from; j < to; j++)
-                    target.push(child.text.charCodeAt(j - off));
+                    target.push(encoder.encodeCharacter(child.text.charCodeAt(j - off), child.marks));
             }
             else if (child.isLeaf) {
-                target.push(child.type.name);
+                target.push(encoder.encodeNodeStart(child));
             }
             else {
                 if (from == off)
-                    target.push(child.type.name);
-                tokens(child.content, Math.max(off + 1, from) - off - 1, Math.min(endOff - 1, to) - off - 1, target);
+                    target.push(encoder.encodeNodeStart(child));
+                tokens(child.content, encoder, Math.max(off + 1, from) - off - 1, Math.min(endOff - 1, to) - off - 1, target);
                 if (to == endOff)
-                    target.push(-1);
+                    target.push(encoder.encodeNodeEnd(child));
             }
         }
         off = endOff;
@@ -37,16 +43,17 @@ const MAX_DIFF_SIZE = 5000;
 function minUnchanged(sizeA, sizeB) {
     return Math.min(15, Math.max(2, Math.floor(Math.max(sizeA, sizeB) / 10)));
 }
-function computeDiff(fragA, fragB, range) {
-    let tokA = tokens(fragA, range.fromA, range.toA, []);
-    let tokB = tokens(fragB, range.fromB, range.toB, []);
+function computeDiff(fragA, fragB, range, encoder = DefaultEncoder) {
+    let tokA = tokens(fragA, encoder, range.fromA, range.toA, []);
+    let tokB = tokens(fragB, encoder, range.fromB, range.toB, []);
     // Scan from both sides to cheaply eliminate work
     let start = 0, endA = tokA.length, endB = tokB.length;
-    while (start < tokA.length && start < tokB.length && tokA[start] === tokB[start])
+    let cmp = encoder.compareTokens;
+    while (start < tokA.length && start < tokB.length && cmp(tokA[start], tokB[start]))
         start++;
     if (start == tokA.length && start == tokB.length)
         return [];
-    while (endA > start && endB > start && tokA[endA - 1] === tokB[endB - 1])
+    while (endA > start && endB > start && cmp(tokA[endA - 1], tokB[endB - 1]))
         endA--, endB--;
     // If the result is simple _or_ too big to cheaply compute, return
     // the remaining region as the diff
@@ -65,7 +72,7 @@ function computeDiff(fragA, fragB, range) {
         for (let diag = -size; diag <= size; diag += 2) {
             let next = frontier[diag + 1 + max], prev = frontier[diag - 1 + max];
             let x = next < prev ? prev : next + 1, y = x + diag;
-            while (x < lenA && y < lenB && tokA[start + x] === tokB[start + y])
+            while (x < lenA && y < lenB && cmp(tokA[start + x], tokB[start + y]))
                 x++, y++;
             frontier[diag + max] = x;
             // Found a match
@@ -225,7 +232,7 @@ class Change {
     deleted, 
     /**
     Data associated with the inserted content. Length adds up to
-    `this.toB - this.toA`.
+    `this.toB - this.fromB`.
     */
     inserted) {
         this.fromA = fromA;
@@ -549,7 +556,7 @@ class ChangeSet {
                 // Only look at changes that touch newly added changed ranges
                 !newChanges.some(r => r.toB > change.fromB && r.fromB < change.toB))
                 continue;
-            let diff = computeDiff(this.config.doc.content, newDoc.content, change);
+            let diff = computeDiff(this.config.doc.content, newDoc.content, change, this.config.encoder);
             // Fast path: If they are completely different, don't do anything
             if (diff.length == 1 && diff[0].fromB == 0 && diff[0].toB == change.toB - change.fromB)
                 continue;
@@ -622,12 +629,18 @@ class ChangeSet {
     }
     /**
     Create a changeset with the given base object and configuration.
+    
     The `combine` function is used to compare and combine metadata—it
     should return null when metadata isn't compatible, and a combined
     version for a merged range when it is.
+    
+    When given, a token encoder determines how document tokens are
+    serialized and compared when diffing the content produced by
+    changes. The default is to just compare nodes by name and text
+    by character, ignoring marks and attributes.
     */
-    static create(doc, combine = (a, b) => a === b ? a : null) {
-        return new ChangeSet({ combine, doc }, []);
+    static create(doc, combine = (a, b) => a === b ? a : null, tokenEncoder = DefaultEncoder) {
+        return new ChangeSet({ combine, doc, encoder: tokenEncoder }, []);
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prosemirror-changeset",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Distills a series of editing steps into deleted and added ranges",
   "type": "module",
   "main": "dist/index.cjs",
@@ -15,7 +15,7 @@
   "maintainers": [
     {
       "name": "Marijn Haverbeke",
-      "email": "marijnh@gmail.com",
+      "email": "marijn@haverbeke.berlin",
       "web": "http://marijnhaverbeke.nl"
     }
   ],
@@ -29,11 +29,12 @@
   "devDependencies": {
     "@prosemirror/buildhelper": "^0.1.5",
     "prosemirror-model": "^1.0.0",
-    "prosemirror-test-builder": "^1.0.0"
+    "prosemirror-test-builder": "^1.0.0",
+    "builddocs": "^1.0.8"
   },
   "scripts": {
     "test": "pm-runtests",
     "prepare": "pm-buildhelper src/changeset.ts",
-    "build-readme": "FIXME"
+    "build-readme": "builddocs --format markdown --main src/README.md src/changeset.ts  > README.md"
   }
 }

package/src/README.md

@@ -25,4 +25,6 @@ it was made, or the step data necessary to invert it again.
 
 @ChangeSet
 
-@simplifyChanges
+@simplifyChanges
+
+@TokenEncoder

package/src/change.ts

@@ -66,7 +66,7 @@ export class Change<Data = any> {
     /// spans adds up to `this.toA - this.fromA`.
     readonly deleted: readonly Span<Data>[],
     /// Data associated with the inserted content. Length adds up to
-    /// `this.toB - this.toA`.
+    /// `this.toB - this.fromB`.
     readonly inserted: readonly Span<Data>[]
   ) {}
 

package/src/changeset.ts

@@ -1,9 +1,10 @@
 import {Node} from "prosemirror-model"
 import {StepMap} from "prosemirror-transform"
-import {computeDiff} from "./diff"
+import {computeDiff, TokenEncoder, DefaultEncoder} from "./diff"
 import {Change, Span} from "./change"
 export {Change, Span}
 export {simplifyChanges} from "./simplify"
+export {TokenEncoder}
 
 /// A change set tracks the changes to a document from a given point
 /// in the past. It condenses a number of step maps down to a flat
@@ -13,7 +14,11 @@ export class ChangeSet<Data = any> {
   /// @internal
   constructor(
     /// @internal
-    readonly config: {doc: Node, combine: (dataA: Data, dataB: Data) => Data},
+    readonly config: {
+      doc: Node,
+      combine: (dataA: Data, dataB: Data) => Data,
+      encoder: TokenEncoder<any>
+    },
     /// Replaced regions.
     readonly changes: readonly Change<Data>[]
   ) {}
@@ -69,7 +74,7 @@ export class ChangeSet<Data = any> {
       if (change.fromA == change.toA || change.fromB == change.toB ||
           // Only look at changes that touch newly added changed ranges
           !newChanges.some(r => r.toB > change.fromB && r.fromB < change.toB)) continue
-      let diff = computeDiff(this.config.doc.content, newDoc.content, change)
+      let diff = computeDiff(this.config.doc.content, newDoc.content, change, this.config.encoder)
 
       // Fast path: If they are completely different, don't do anything
       if (diff.length == 1 && diff[0].fromB == 0 && diff[0].toB == change.toB - change.fromB)
@@ -132,11 +137,21 @@ export class ChangeSet<Data = any> {
   }
 
   /// Create a changeset with the given base object and configuration.
+  ///
   /// The `combine` function is used to compare and combine metadata—it
   /// should return null when metadata isn't compatible, and a combined
   /// version for a merged range when it is.
-  static create<Data = any>(doc: Node, combine: (dataA: Data, dataB: Data) => Data = (a, b) => a === b ? a : null as any) {
-    return new ChangeSet({combine, doc}, [])
+  ///
+  /// When given, a token encoder determines how document tokens are
+  /// serialized and compared when diffing the content produced by
+  /// changes. The default is to just compare nodes by name and text
+  /// by character, ignoring marks and attributes.
+  static create<Data = any>(
+    doc: Node,
+    combine: (dataA: Data, dataB: Data) => Data = (a, b) => a === b ? a : null as any,
+    tokenEncoder: TokenEncoder<any> = DefaultEncoder
+  ) {
+    return new ChangeSet({combine, doc, encoder: tokenEncoder}, [])
   }
 
   /// Exported for testing @internal

package/src/diff.ts

@@ -1,22 +1,51 @@
-import {Fragment} from "prosemirror-model"
+import {Fragment, Node, Mark} from "prosemirror-model"
 import {Change} from "./change"
 
+/// A token encoder can be passed when creating a `ChangeSet` in order
+/// to influence the way the library runs its diffing algorithm. The
+/// encoder determines how document tokens (such as nodes and
+/// characters) are encoded and compared.
+///
+/// Note that both the encoding and the comparison may run a lot, and
+/// doing non-trivial work in these functions could impact
+/// performance.
+export interface TokenEncoder<T> {
+  /// Encode a given character, with the given marks applied.
+  encodeCharacter(char: number, marks: readonly Mark[]): T
+  /// Encode the start of a node or, if this is a leaf node, the
+  /// entire node.
+  encodeNodeStart(node: Node): T
+  /// Encode the end token for the given node. It is valid to encode
+  /// every end token in the same way.
+  encodeNodeEnd(node: Node): T
+  /// Compare the given tokens. Should return true when they count as
+  /// equal.
+  compareTokens(a: T, b: T): boolean
+}
+
+export const DefaultEncoder: TokenEncoder<number | string> = {
+  encodeCharacter: char => char,
+  encodeNodeStart: node => node.type.name,
+  encodeNodeEnd: () => -1,
+  compareTokens: (a, b) => a === b
+}
+
 // Convert the given range of a fragment to tokens, where node open
 // tokens are encoded as strings holding the node name, characters as
 // their character code, and node close tokens as -1.
-function tokens(frag: Fragment, start: number, end: number, target: (number | string)[]) {
+function tokens<T>(frag: Fragment, encoder: TokenEncoder<T>, start: number, end: number, target: T[]) {
   for (let i = 0, off = 0; i < frag.childCount; i++) {
     let child = frag.child(i), endOff = off + child.nodeSize
     let from = Math.max(off, start), to = Math.min(endOff, end)
     if (from < to) {
       if (child.isText) {
-        for (let j = from; j < to; j++) target.push(child.text!.charCodeAt(j - off))
+        for (let j = from; j < to; j++) target.push(encoder.encodeCharacter(child.text!.charCodeAt(j - off), child.marks))
       } else if (child.isLeaf) {
-        target.push(child.type.name)
+        target.push(encoder.encodeNodeStart(child))
       } else {
-        if (from == off) target.push(child.type.name)
-        tokens(child.content, Math.max(off + 1, from) - off - 1, Math.min(endOff - 1, to) - off - 1, target)
-        if (to == endOff) target.push(-1)
+        if (from == off) target.push(encoder.encodeNodeStart(child))
+        tokens(child.content, encoder, Math.max(off + 1, from) - off - 1, Math.min(endOff - 1, to) - off - 1, target)
+        if (to == endOff) target.push(encoder.encodeNodeEnd(child))
       }
     }
     off = endOff
@@ -38,15 +67,16 @@ function minUnchanged(sizeA: number, sizeB: number) {
   return Math.min(15, Math.max(2, Math.floor(Math.max(sizeA, sizeB) / 10)))
 }
 
-export function computeDiff(fragA: Fragment, fragB: Fragment, range: Change) {
-  let tokA = tokens(fragA, range.fromA, range.toA, [])
-  let tokB = tokens(fragB, range.fromB, range.toB, [])
+export function computeDiff(fragA: Fragment, fragB: Fragment, range: Change, encoder: TokenEncoder<any> = DefaultEncoder) {
+  let tokA = tokens(fragA, encoder, range.fromA, range.toA, [])
+  let tokB = tokens(fragB, encoder, range.fromB, range.toB, [])
 
   // Scan from both sides to cheaply eliminate work
   let start = 0, endA = tokA.length, endB = tokB.length
-  while (start < tokA.length && start < tokB.length && tokA[start] === tokB[start]) start++
+  let cmp = encoder.compareTokens
+  while (start < tokA.length && start < tokB.length && cmp(tokA[start], tokB[start])) start++
   if (start == tokA.length && start == tokB.length) return []
-  while (endA > start && endB > start && tokA[endA - 1] === tokB[endB - 1]) endA--, endB--
+  while (endA > start && endB > start && cmp(tokA[endA - 1], tokB[endB - 1])) endA--, endB--
   // If the result is simple _or_ too big to cheaply compute, return
   // the remaining region as the diff
   if (endA == start || endB == start || (endA == endB && endA == start + 1))
@@ -66,7 +96,7 @@ export function computeDiff(fragA: Fragment, fragB: Fragment, range: Change) {
     for (let diag = -size; diag <= size; diag += 2) {
       let next = frontier[diag + 1 + max], prev = frontier[diag - 1 + max]
       let x = next < prev ? prev : next + 1, y = x + diag
-      while (x < lenA && y < lenB && tokA[start + x] === tokB[start + y]) x++, y++
+      while (x < lenA && y < lenB && cmp(tokA[start + x], tokB[start + y])) x++, y++
       frontier[diag + max] = x
       // Found a match
       if (x >= lenA && y >= lenB) {