💃 Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @jolly-pixel/history
# or
$ yarn add @jolly-pixel/history

👀 Usage example

stats is a CommandDocument of named numbers, edited with { key, value } commands through set(key, value) and read with get(key). It starts with hp at 10.

import {
  CommandHistory,
  KeyedGuard
} from "@jolly-pixel/history";

const history = new CommandHistory<"build">();
history.register({
  id: "stats",
  document: stats,
  keys: {
    // the keys a change wrote
    written: ({ command }) => [command.key],
    // the values an undo of these commands writes back, which nobody else may change meanwhile
    guard: (commands) => new KeyedGuard(commands.map(({ key }) => {
      return { key, read: () => stats.get(key) };
    }))
  },
  // a change made outside record() becomes its own step in this scope
  resolveScope: () => "build"
});

history.record("build", "Set hp", () => stats.set("hp", 20));
history.undo("build"); // true, hp is 10 again

An undo never erases a peer's newer edit. When a peer wrote the same value, the step is refused and undo skips it:

history.record("build", "Set hp", () => stats.set("hp", 20));
stats.apply({ key: "hp", value: 99 }, "peer-1");
history.undo("build"); // false, emits "skipped", hp stays 99

A drag spanning several events opens a step and commits it at the end:

const step = history.open("build", "Paint");
// pointer moves edit the document
step.commit();

📚 API

Core

What an editor uses to add undo to its documents.

• CommandHistory: scopes, record, undo, redo and state.
• HistoryRegistration: registered documents, HistorySource, guards and KeyedGuard.
• CommandDocument: base class of a document edited by commands.

Integration

What sync clients and custom history sources use.

• CommandChange: the change a history source emits, built per origin.
• ChangeReceipts: the server's answers a sync client writes.
• ChangeSourceAdapter: a history source over a document that emits plain changes.

The collaborative undo guide explains steps, guards, refusals and receipts.

See ARCHITECTURE.md for how the pieces fit together and GLOSSARY.md for the terms used by the package.

✨ Contributors guide

If you are a developer looking to contribute to the project, you must first read the CONTRIBUTING guide.

Once you have finished your development, check that the tests (and linter) are still good by running the following script:

$ pnpm run test
$ pnpm run lint

CAUTION

In case you introduce a new feature or fix a bug, make sure to include tests for it as well.

📃 License

MIT