Skip to content
Distills a series of editing steps into deleted and added ranges
Branch: master
Clone or download

Latest commit

Latest commit 099fe33 Nov 20, 2019


Type Name Latest commit message Commit time
Failed to load latest commit information.
src Output a bundled, Bublé-ed mjs file in dist/ Nov 19, 2019
test Remove unused imports Mar 27, 2019
.gitignore Move code from revision-browsing repo Sep 15, 2017 Mark version 2.1.2 Nov 20, 2019
LICENSE Add a README file and license Sep 21, 2017 typo fix Nov 21, 2019
package.json Mark version 2.1.2 Nov 20, 2019
rollup.config.js Make ES module files use .js extension Nov 20, 2019


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.

class Change

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: [Span]
    Data associated with the deleted content. The length of these spans adds up to this.toA - this.fromA.

  • inserted: [Span]
    Data associated with the inserted content. Length adds up to this.toB - this.toA.

class Span

Stores metadata for a part of a change.

  • length: number

  • data: any

class ChangeSet

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 replacements that partially undo themselves by comparing their content.

  • changes: [Change]
    Replaced regions.

  • addSteps(newDoc: Node, maps: [StepMap], data: [any] | any) → 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: Change) → any) → 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: ?[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(a: any, b: any) → any) → 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.

  • simplifyChanges(changes: [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.

You can’t perform that action at this time.