prosemirror-changeset

This is a helper module that can turn a sequence of document changes
into a set of insertions and deletions, for example to display them in
a change-tracking interface. Such a set can be built up incrementally,
in order to do such change tracking in a halfway performant way during
live editing.

This code is licensed under an MIT
licence.

Programming interface

Insertions and deletions are represented as ‘spans’—ranges in the
document. The deleted spans refer to the original document, whereas
the inserted ones point into the current document.

It is possible to associate arbitrary data values with such spans, for
example to track the user that made the change, the timestamp at which
it was made, or the step data necessary to invert it again.

$3

A replaced range with metadata associated with it.

* fromA: number\
The start of the range deleted/replaced in the old document.

* toA: number\
The end of the range in the old document.

* fromB: number\
The start of the range inserted in the new document.

* toB: number\
The end of the range in the new document.

* deleted: readonly Span[]\
Data associated with the deleted content. The length of these
spans adds up to this.toA - this.fromA.

* inserted: readonly Span[]\
Data associated with the inserted content. Length adds up to
this.toB - this.fromB.

* static merge(x: readonly Change[], y: readonly Change[], combine: fn(dataA: Data, dataB: Data) → Data) → readonly Change[]\
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.

$3

Stores metadata for a part of a change.

* length: number\
The length of this span.

* data: Data\
The data associated with this span.

$3

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.

* changes: readonly Change[]\
Replaced regions.

* addSteps(newDoc: Node, maps: readonly StepMap[], data: Data | readonly Data[]) → ChangeSet\
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.

* startDoc: Node\
The starting document of the change set.

* map(f: fn(range: Span) → Data) → ChangeSet\
Map the span's data values in the given set through a function
and construct a new set with the resulting data.

* changedRange(b: ChangeSet, maps?: readonly StepMap[]) → {from: number, to: number}\
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.

* static create(doc: Node, combine?: fn(dataA: Data, dataB: Data) → Data = (a, b) => a === b ? a : null as any, tokenEncoder?: TokenEncoder = DefaultEncoder) → 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.

* simplifyChanges(changes: readonly Change[], doc: Node) → Change[]\
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.

$3

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.

* encodeCharacter(char: number, marks: readonly Mark[]) → T\
Encode a given character, with the given marks applied.

* encodeNodeStart(node: Node) → T\
Encode the start of a node or, if this is a leaf node, the
entire node.

* encodeNodeEnd(node: Node) → T\
Encode the end token for the given node. It is valid to encode
every end token in the same way.

* compareTokens(a: T, b: T) → boolean\
Compare the given tokens. Should return true when they count as
equal.