prosemirror-changeset

What is prosemirror-changeset?

The prosemirror-changeset package is a utility for managing and representing changes in ProseMirror documents. It helps in tracking changes, creating change sets, and applying them to documents. This is particularly useful for collaborative editing, version control, and undo/redo functionality.

What are prosemirror-changeset's main functionalities?

Creating a ChangeSet

This feature allows you to create a ChangeSet from a ProseMirror document. The ChangeSet can then be used to track changes over time.

const { ChangeSet } = require('prosemirror-changeset');
const { Schema, DOMParser } = require('prosemirror-model');
const { schema } = require('prosemirror-schema-basic');

const doc = DOMParser.fromSchema(schema).parse(document.querySelector('#content'));
const changeSet = ChangeSet.create(doc);
console.log(changeSet);

Applying Changes

This feature demonstrates how to apply changes to a ChangeSet. It shows how to simulate a change in the document and update the ChangeSet accordingly.

const { ChangeSet } = require('prosemirror-changeset');
const { Schema, DOMParser } = require('prosemirror-model');
const { schema } = require('prosemirror-schema-basic');

const doc = DOMParser.fromSchema(schema).parse(document.querySelector('#content'));
let changeSet = ChangeSet.create(doc);

// Simulate a change
const tr = doc.tr.insertText('Hello', 1);
changeSet = changeSet.addSteps(doc, tr.doc, tr.mapping.maps);
console.log(changeSet);

Reverting Changes

This feature shows how to revert changes using a ChangeSet. It demonstrates how to undo changes and revert the document to its previous state.

const { ChangeSet } = require('prosemirror-changeset');
const { Schema, DOMParser } = require('prosemirror-model');
const { schema } = require('prosemirror-schema-basic');

const doc = DOMParser.fromSchema(schema).parse(document.querySelector('#content'));
let changeSet = ChangeSet.create(doc);

// Simulate a change
const tr = doc.tr.insertText('Hello', 1);
changeSet = changeSet.addSteps(doc, tr.doc, tr.mapping.maps);

// Revert the change
const revertedDoc = changeSet.revert(doc);
console.log(revertedDoc);

Other packages similar to prosemirror-changeset

prosemirror-history

The prosemirror-history package provides undo/redo history management for ProseMirror editors. It allows you to track changes and revert them, similar to prosemirror-changeset, but focuses more on providing a history stack for undo/redo functionality.

prosemirror-collab

The prosemirror-collab package is designed for collaborative editing in ProseMirror. It provides tools for managing concurrent changes from multiple users, similar to prosemirror-changeset, but with a focus on real-time collaboration and conflict resolution.

prosemirror-transform

The prosemirror-transform package provides tools for transforming ProseMirror documents. It includes functionality for applying steps and mappings, similar to prosemirror-changeset, but with a broader focus on document transformations rather than just change tracking.

README

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.

class Change<Data = any>

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.toA.

• static merge<Data>(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.

class Span<Data = any>

Stores metadata for a part of a change.

• length: number
  The length of this span.

• data: Data
  The data associated with this span.

class ChangeSet<Data = 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.

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

Changelog

2.2.1 (2023-05-17)

Bug fixes

Include CommonJS type declarations in the package to please new TypeScript resolution settings.