Skip to content
Edit on GitHub

Versions

Save named and automatic snapshots with VersionsManager, compare them block by block, restore one as an undoable change, show them in the VersionHistory panel, and decide where versions are stored.

@gotipe/versions@gotipe/block-editor

VersionsManager saves snapshots of the document while it is open, by name or on a timer. You can compare two snapshots block by block and restore one; a restore is an ordinary edit that undo reverts. Snapshots live in memory: exportState() hands them to your storage and loadState() reads them back. @gotipe/versions is MIT and has no UI; the history panel, VersionHistory, is part of the commercial @gotipe/block-editor.

Live editorCompare versions
Loading the editor…

Install

npm install @gotipe/versions

Example

history.ts
import { createEditor } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";
import { VersionsManager, compareDocuments } from "@gotipe/versions";

const editor = await createEditor({ extensions: [DefaultPreset] });
editor.mount(document.querySelector<HTMLElement>("#editor")!);

const versions = new VersionsManager(editor, {
  autoSave: true,
  autoSaveInterval: 60_000,
  maxVersions: 50,
  onVersionCreated: (version) => console.log(`Saved ${version.name}`),
});

const draft = versions.createVersion("First draft", "Alice");

// Later: what changed since the draft?
const diff = compareDocuments(draft.snapshot, editor.getJSON());
console.log(diff.added, diff.removed, diff.modified, diff.moved);

// Put the draft back. Undo returns to the text before the restore.
versions.restoreVersion(draft.id);

With the defineVersions extension the editor creates the manager itself, with the same options; getVersionsManager(editor) returns it.

Options

Option Type Default Description
initialState unknown — A stored snapshot to start with, read as loadState() reads it. undefined starts empty; anything else that is not a snapshot, null included, throws from the constructor, and no auto-save starts.
autoSave boolean false Save a version on a timer.
autoSaveInterval number 300000 Timer period in ms. Must be positive.
maxVersions number 100 Versions kept. When a new one exceeds the limit, the oldest are dropped. Must be a positive integer.
onVersionCreated (version: Version) => void — A version was saved, by name or automatically.
onVersionRestored (version: Version) => void — A version was restored.

An invalid autoSaveInterval or maxVersions throws a RangeError. An auto-save happens only when the document differs from the last saved version; it is named Auto-save <local date and time> and created by system.

Methods

Method Description
createVersion(name, createdBy, description?) Saves the current document and returns a copy. Throws for an empty name.
restoreVersion(id) Replaces the document with the snapshot. Returns false for an unknown ID.
getVersions() / getVersion(id) Detached copies, oldest first.
deleteVersion(id) Removes a version. Returns false for an unknown ID.
compareVersions(a, b) compareDocuments of two saved versions, or null when one is missing.
exportState() { version: 1, versions }: every version, oldest first, detached and ready for JSON.
loadState(snapshot) Replaces the versions with a stored snapshot. See Store versions.
subscribe(listener) Called after every create, restore, delete and load. Returns an unsubscribe function.
getRevision() A counter that grows with every change, for UI memoization.
destroy() Stops the timer and drops every version. Destroying the editor destroys the manager.

A Version has id, name, description, createdAt, createdBy and snapshot, the whole document as public JSON.

Compare

compareDocuments(a, b) compares two documents by block ID and returns:

Field Blocks
added Only in b.
removed Only in a.
modified In both, with a different type, attributes or content. A change inside a child is reported on the child only.
moved In both, with a different parent, or out of order among the siblings both documents share. Inserting or removing a sibling moves nothing.

The result holds block IDs. For the text, diffText(before, after) compares two texts word by word and returns runs of equal, delete and insert; a no-break space keeps «10 %» one unit. countWordChanges(a, b) counts the words added and removed between two documents, and blockText(block) is a block's own text.

Restore

restoreVersion(id) sets the snapshot as the document in one undoable step and keeps the caret where its block still exists. The version list stays as it was, and later versions are kept.

History panel

VersionHistory (GoTipe Atlas, frame 30) stands beside the page. It lists versions by day — name, words added and removed, the author's initials and the time — and leads with the page as it is now. Choosing a version shows the page compared with it: a rule in the margin marks a block added (green), removed (red, struck through) or changed (blue), and a changed text shows the words that went and came. Restore puts the version back as one undo step and answers with a toast whose Undo takes it back. In a container narrower than 640 px the list and the comparison are two screens, the comparison with a back arrow.

history.tsx
import { PageEditor, VersionHistory } from "@gotipe/block-editor";
import { VersionsManager } from "@gotipe/versions";

function Page() {
  const [editor, setEditor] = useState<GoTipeEditor | null>(null);
  const [open, setOpen] = useState(false);
  const manager = useMemo(() => (editor ? new VersionsManager(editor) : null), [editor]);
  return (
    <VersionHistory
      editor={editor}
      source={manager ?? undefined}
      user={{ name: "Мария Лебедева" }}
      open={open}
      onClose={() => setOpen(false)}
    >
      <PageEditor markdown={markdown} onReady={setEditor} />
    </VersionHistory>
  );
}
Prop Type Description
editor GoTipeEditor | null The live page. While it is null only the page is shown.
source VersionHistorySource A VersionsManager or the same shape: getVersions, subscribe, optional createVersion and restoreVersion.
versions HistoryVersion[] Versions your app owns, in any order; used instead of source.
user { name, person? } Who works on the page: the row of the unsaved page and the entries of a restore are theirs. person (1–3) picks the avatar colour.
onRestore (version, { unsaved, names }) => void | Promise Called after the version is on the page. unsaved is the page before the restore when no saved version held it. A rejection undoes the restore and shows an error.
open boolean Default true. Closed, only the page stays, mounted as it was.
onClose () => void The close button and Escape. Focus returns to the control that opened the panel.
loading, error, onRetry The panel's loading and error states; onRetry adds a Try again button.
children ReactNode The live page. It stays mounted while a version is compared.

A HistoryVersion is a Version with optional auto (listed as Auto-save with its author) and person. A VersionsManager auto-save, created by system, is listed as Auto-save without an author.

When a version is restored from a source, the panel first saves the unsaved page as Before restore, then the result as Back to “…”, which leads the list. With versions, your app saves them in onRestore; names holds both names in the panel's language.

The list is a listbox: the arrows, Home and End move along it, Enter chooses. Strings come from @gotipe/i18n (history.*). Styles are in @gotipe/theme (theme/history.css).

Store versions

Your storage. Save exportState() whenever the list changes and pass it back as initialState (or to loadState()) when the document opens again:

stored-history.ts
const versions = new VersionsManager(editor, {
  autoSave: true,
  initialState: (await storage.read(documentId)) ?? undefined, // nothing stored yet
});
versions.subscribe(() => storage.write(documentId, versions.exportState()));

loadState() checks the whole snapshot before it changes anything: an unknown format, a repeated ID, an empty name, a date Date.parse cannot read or an invalid document throws a GoTipeError with code VALIDATION_ERROR, and the versions stay as they were. Versions are put oldest first by createdAt (equal times keep their order), and the newest maxVersions are kept, as when a new version exceeds the limit. A snapshot may hold up to 10,000 versions, or maxVersions when that is larger, so a manager always reads back what it exported. Auto-save then compares the document with the newest loaded version. Listeners are called; onVersionCreated is not.

GoTipe Cloud. POST /v1/documents/{docId}/versions with { name, description?, version_type? } (named or milestone) saves the document as Cloud stores it, not the editor's local state. GET lists versions a page at a time, and POST /v1/documents/{docId}/versions/{versionId}/restore replaces the document. Before it does, Cloud saves the previous content as a restore_point version. A restore starts a new collaboration log, so open editors must load the document again. Cloud has no endpoint that returns a version's content, so its versions cannot be loaded into VersionsManager. See REST API.

Limitations

  • Versions live in memory and disappear with the manager unless you store exportState().
  • Every version holds a full copy of the document.
  • The comparison shows a changed block's text without its marks; a change of marks alone marks the block as changed.