Skip to content
Edit on GitHub

Transactions

How a GoTipe document changes, steps, atomic dispatch, previews, filters, selection, undo history and UTF-16 offsets.

@gotipe/coreMIT

Every change to a document is a transaction: an ordered list of steps plus an optional selection. The editor checks the whole result against the schema before anything changes, then commits it as one undo step; text typed in a row shares one (see History). Typing, paste, commands and collaboration all go through this path. Use transactions directly when a command doesn't fit, for example to edit a block by ID from outside the editor.

Dispatch a transaction

dispatch.ts
import { createEditor } from "@gotipe/core";
import { DefaultPreset } from "@gotipe/core/presets";

const editor = await createEditor({
  extensions: [DefaultPreset],
  engine: "js",
  content: {
    version: 1,
    blocks: [
      {
        id: "intro",
        type: "paragraph",
        attrs: {},
        content: [{ text: "Hello world", marks: [] }],
        children: [],
      },
    ],
  },
});

editor.dispatch({
  steps: [
    { type: "insertText", blockId: "intro", offset: 11, text: "!", marks: [] },
    { type: "addMark", blockId: "intro", from: 0, to: 5, mark: { type: "bold", attrs: {} } },
  ],
  selection: { type: "cursor", blockId: "intro", offset: 12 },
});

console.log(editor.getMarkdown()); // "**Hello** world!\n"

dispatch returns true when the transaction was applied and false when a filter cancelled it. It throws when the transaction is invalid.

Field Type Description
steps Step[] Applied in order; each step sees the result of the previous ones.
selection Selection Optional selection after the change. Without it the editor maps the old selection.
metadata Record<string, AttrValue> Optional data for filters and transaction listeners.

Steps

Step Fields Effect
insertText blockId, offset, text, marks Inserts text with marks. The block must allow those marks. Of several marks of one type or one exclusive group, the last one counts.
deleteText blockId, from, to Deletes [from, to) inside one block. deleteRange is an alias.
addMark blockId, from, to, mark Adds mark to the range. A mark of the same type is replaced in its place, so the text takes the new attributes; marks of the same exclusive group are removed.
removeMark blockId, from, to, markType Removes marks of markType from the range.
insertBlock parentId, index, block Inserts a block tree; parentId: null means top level. Every ID in the tree must be new. An index past the end appends.
deleteBlock blockId Removes the block with its children.
moveBlock blockId, newParentId, newIndex Moves a block with its children. It can't move into its own subtree.
setBlockType blockId, newType, attrs Changes the type and replaces all attributes. Content converts to the content the new type declares: rich text, raw text or none; converting to a type without content drops the text. Without a schema the content stays as it is.
setBlockAttrs blockId, attrs Merges attrs into the existing attributes.
splitBlock blockId, offset Moves the text after offset into a new block below, with a new ID. A heading continues as a paragraph; other types keep type and attributes. Children stay in the first block.
mergeBlocks blockId, targetId Appends the text of blockId to targetId, moves its children to the end of the target's children and removes it. Both must hold rich text, or both raw text.

Steps carry attributes as written: unlike commands, they don't fill in the defaults a block or mark type declares.

Atomicity and errors

The editor applies all steps to a staged copy, validates every step and the final document against the schema, and only then commits. If any part fails, dispatch throws a GoTipeError and nothing changes: no document, selection, history or events.

Code Cause
VALIDATION_ERROR A step or the result doesn't match the schema: unknown type or mark, undeclared or wrong attribute, a block where its parent doesn't accept it.
TRANSFORM_ERROR A step can't apply: offset out of range or inside a surrogate pair, duplicate ID, a move into its own subtree, an invalid selection, or a filter that dispatches.

previewTransaction(transaction) runs the same staging and validation and returns the resulting Document without committing. It doesn't run filters, touch history or emit events, and throws the same errors:

TypeScript
const after = editor.previewTransaction({
  steps: [{ type: "deleteBlock", blockId: "intro" }],
});
console.log(after.blocks.length);

Filters

addTransactionFilter registers a function that sees every validated local dispatch before it commits. Return false to cancel it. The function receives detached copies of transaction, before and after, and returns an unsubscribe function.

limit.ts
import type { Block } from "@gotipe/core";

const LIMIT = 5000;
const textLength = (blocks: Block[]): number =>
  blocks.reduce((sum, block) => {
    const own =
      typeof block.content === "string"
        ? block.content.length
        : (block.content ?? []).reduce((n, span) => n + span.text.length, 0);
    return sum + own + textLength(block.children);
  }, 0);

// Reject changes that grow the text past the limit; deleting is always allowed.
const stop = editor.addTransactionFilter(
  ({ before, after }) => textLength(after.blocks) <= Math.max(LIMIT, textLength(before.blocks)),
);
// Later: stop();

A cancelled transaction makes dispatch and chain().run() return false; typing and paste are cancelled the same way. Filters apply to local dispatches only: Undo and Redo, setContent and remote collaboration updates are not filtered. A filter can't dispatch; doing so throws TRANSFORM_ERROR.

Selection

Selection Fields Meaning
cursor blockId, offset A caret.
text blockId, from, to A range inside one block; from ≤ to.
range anchor, head (each { blockId, offset }) A directional range, possibly across blocks.
block blockId A whole block, such as an image.
multi blockIds Several whole blocks; IDs must exist and be unique.

A transaction's selection is validated against the new document and becomes the selection afterwards. Without one, the editor keeps the old selection on the same block IDs and clamps offsets to the new text length; it does not shift a caret for text inserted before it, so pass selection when you insert at or before the caret. If the selected block is removed, the caret moves to the block now at its position.

getViewState().selection reports the live selection as text, block or multi, with anchor, head and, for multi, blockIds. To change only the selection, dispatch a transaction with no steps, or call editor.setSelection({ anchor, head }), which skips validation and filters.

Offsets are UTF-16

Offsets count UTF-16 code units, like JavaScript string indexes, in both engines. An emoji outside the Basic Multilingual Plane counts as two:

TypeScript
// The block text is "Hi 😀!" — "😀" occupies offsets 3 and 4.
editor.dispatch({ steps: [{ type: "insertText", blockId: "b1", offset: 5, text: "?", marks: [] }] }); // after the emoji
editor.dispatch({ steps: [{ type: "insertText", blockId: "b1", offset: 4, text: "?", marks: [] }] }); // throws TRANSFORM_ERROR

An offset inside a surrogate pair is rejected. The engine does not protect grapheme clusters, such as an emoji with a skin-tone modifier or a letter with a combining accent; use Intl.Segmenter when you compute offsets from what the user sees.

History

Each committed dispatch is one undo step that restores the document and the selection from before it. editor.undo() and editor.redo() return false when there is nothing to undo or redo, and getViewState().toolbar reports canUndo and canRedo.

Typing is the exception. Text typed in a row in one block is one undo step, and so is text deleted with Backspace or Delete in a row. Typing over selected text starts a step that the following typing joins, and deleting it one that the following deleting joins, also when the selection spans blocks: one Undo brings the selected text back. A whole selected block, such as an image, is replaced or deleted in a step of its own. The step ends when:

  • you pause for 500 ms;
  • the caret or the selection moves, even back to the same place, or typing goes to another block;
  • typing turns into deleting, or deleting into typing;
  • any other change commits: Enter, a line break, paste, an input rule, a command or a dispatch, a formatting toggle at the caret, Undo or Redo.

An IME composition is typing too: it goes on with the step of the typing before it, and typing after it goes on with its step. The pause before a composition counts from its start, so Korean, where every syllable is a composition of its own, is one step however long each syllable takes to compose. Only the editor's own input is grouped: every dispatch is a step of its own, even one that inserts a character at the caret.

  • A new dispatch clears the redo stack. The editor keeps the last 100 steps, and text typed in a row is one of them however long it is.
  • Selection-only transactions, stored-mark toggles, cancelled and failed dispatches add no undo step. A character a filter cancels doesn't end the typing step.
  • setContent clears the history. Pass { addToHistory: true } to make the replacement one undo step instead.
  • A transaction with metadata: { addToHistory: false } is committed without an undo step, leaves the redo stack as it is and doesn't end the typing step. Use it for changes the user did not make, as TrailingNode does. Without collaboration, Undo of an earlier step restores the document from before that step, so such a change goes with it.
  • After enableCollaboration, history moves to the CRDT: Undo reverts your own changes and keeps the other peers' edits. Your typing is grouped into the same steps as without collaboration. A peer's edit ends your typing step only when it moves your caret, by changing text before it in the same block.

To make several changes one undo step, put them in one transaction or one command chain.

Read-only

editable: false and setEditable(false) block user input, paste and drop. dispatch and commands still change the document, so programmatic edits keep working.