Transactions
How a GoTipe document changes, steps, atomic dispatch, previews, filters, selection, undo history and UTF-16 offsets.
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
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< |
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:
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.
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 { block) |
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:
// 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_ERRORAn 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.
setContentclears 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.
Related
- Commands build transactions from the selection.
- Events:
transactionandupdateafter a commit. - Document model.