Utilities

A list of classes and functions exported by the @tiptap-pro/compare package.

Compare

The Compare Tiptap Editor extension. Add it to the editor that renders the diff. This extension does not take any configuration options.

compareDocuments

Compares two Tiptap JSON documents.

Parameters (CompareDocumentsOptions)

• schema (Schema): The ProseMirror schema used to parse both documents.
• docA (JSONContent): The original document.
• docB (JSONContent): The changed document.
• diffOptions? (DiffOptions): Options that control the comparison. See DiffOptions.

Returns (Changeset)

Returns a changeset containing both documents and their changes. See Changeset.

compareFragments

Compares two Tiptap JSON fragments.

Parameters (CompareFragmentsOptions)

• schema (Schema): The ProseMirror schema used to parse both fragments.
• fragmentA (JSONContent[] | null): The original fragment.
• fragmentB (JSONContent[] | null): The changed fragment.
• diffOptions? (DiffOptions): Options that control the comparison.

Returns (Changeset)

Returns a changeset containing both fragments and their changes. See Changeset.

compareSteps

Converts a StepSequence into non-overlapping changes.

Parameters (CompareStepsOptions)

• stepSequence (StepSequence): The document transitions to compare.
• compareMetadata? ((a: ChangeMetadata, b: ChangeMetadata) => boolean): Decides whether adjacent steps can be grouped.
• diffOptions? (DiffOptions): Options that control the comparison.

Returns (Changeset)

Returns a changeset containing the initial and final documents and their changes. Changes include metadata associated with the steps that produced them. See Changeset.

compareVersions

Compares two complete Yjs v2 updates and recovers collaboration metadata when available.

Parameters (CompareVersionsOptions)

• versionA (Uint8Array): The older Yjs v2 update.
• versionB (Uint8Array): The newer Yjs v2 update.
• schema (Schema): The schema used to hydrate both versions.
• diffOptions? (DiffOptions): Options that control the comparison.
• compareMetadata? ((a: ChangeMetadata, b: ChangeMetadata) => boolean): Decides whether adjacent changes can be grouped. By default, changes with the same userId are grouped.
• field? (string): The Yjs document field. Default: 'default'.
• permanentUserDataMapField? (string): The shared user-data map field. Default: '__tiptapcollab__users'.
• enableDebugging? (boolean): Enables extraction logging. Default: false.

Returns (Changeset)

Returns a changeset containing both versions and their changes. Changes include metadata from the change history, such as a userId when available. See Changeset.

Changeset

Represents the result of comparing two documents, fragments, steps, or versions.

Properties

• fragmentA (JSONFragment): The original fragment.
• fragmentB (JSONFragment): The modified fragment.
• changes (Change[]): The changes between both fragments.
• docA (JSONContent): The original document as a Tiptap JSON document.
• docB (JSONContent): The modified document as a Tiptap JSON document.

changeset.reverse

Creates a changeset in the opposite direction, where document A becomes document B, and vice versa.

Parameters

This method has no parameters.

Returns (Changeset)

• Changeset: A changeset with the original and modified documents reversed.

changeset.toJSON

Serializes the changeset.

Parameters

This method has no parameters.

Returns (ChangesetJSON)

• fragmentA (JSONFragment): The original fragment.
• fragmentB (JSONFragment): The modified fragment.
• changes (Change[]): The changes between both fragments.

Changeset.fromJSON

Hydrates a changeset from serialized JSON.

Parameters

• json (ChangesetJSON): The serialized changeset.

Returns (Changeset)

• Changeset: The hydrated changeset.

findDiffSuggestions

Returns the diff suggestions that are currently shown in the editor.

Parameters

• editor (Editor): The editor configured with Compare.

Returns (DiffSuggestion[])

Each DiffSuggestion contains:

• id (string): The suggestion ID.
• range (Range): The affected range in the editor.
• content (Slice): The replacement content.
• metadata? (Record<string, any>): Optional custom metadata.
• displayOptions? (DisplayOptions): Options used to render the suggestion.
• isInlineGroup? (boolean): Whether inline changes were grouped.
• mappableRange? (MappableRange): A range that can be mapped through transactions.
• nestedChanges? (DiffSuggestionNestedChange[]): Informational changes nested in this suggestion. Accept and reject actions target the parent suggestion.

getSuggestionNodeViewContext

Determines whether a Tiptap Node View is inside a diff suggestion, and returns the suggestion's context.

Parameters

• decorations (Decoration[]): The decorations passed to the custom node view.

Returns (SuggestionNodeViewContext)

• suggestion (DiffSuggestion | null): The suggestion where the node view is located or null if the node view is not part of a diff suggestion.
• isSelected (boolean): Whether the suggestion is selected. A suggestion is selected when the cursor is inside the suggestion.
• isReplacement (boolean): Whether the node view is inside replacement content. It is false for content in the current document.

renderSlice

Renders a ProseMirror slice as a document fragment for display in a diff.

Parameters (RenderSliceToHtmlOptions)

• slice (Slice): The slice to render.
• editor (Editor): The editor used to render the slice.
• suggestionNodeViewContext (SuggestionNodeViewContext): Context data provided to custom node views while rendering.

Returns (DocumentFragment)

Returns a document fragment containing the rendered slice.

generateSuggestionId

Creates a unique ID for a diff suggestion.

Parameters

This utility has no parameters.

Returns (string)

• string: A unique suggestion ID.

getVersions

Requests two snapshots from a collaboration provider.

Parameters

• provider (TiptapCollabProvider): A provider with version-listing and stateless-message methods.
• fromVersion (number): The first version ID.
• toVersion? (number): The second version ID. Defaults to the latest version.

Returns (Promise<{ snapshot: Uint8Array; prevSnapshot: Uint8Array }>)

The promise resolves with:

• snapshot (Uint8Array): The newer version update.
• prevSnapshot (Uint8Array): The older version update.

getDocumentFromVersion

Hydrates a Tiptap JSON document from a complete Yjs v2 update.

Parameters (GetDocumentFromVersionOptions)

• version (Uint8Array): The complete Yjs v2 update.
• schema (Schema): The schema used to hydrate the document.
• field? (string): The Yjs document field. Default: 'default'.

Returns (JSONContent)

The returned JSON document contains:

• type (string): The Tiptap node type, usually 'doc' for a complete document.
• content? (JSONContent[]): The document's child nodes.
• attrs? (Record<string, any>): Attributes on the document node.
• marks? (Mark[]): Marks on the node, when applicable.
• text? (string): Text content, when applicable.

TrackedChangesDocumentFactory

Creates a Tiptap JSON document with a Changeset encoded as Tracked Changes. Use this on the server or anywhere an editor instance is unavailable.

fromChangeset

Converts a changeset into a document containing tracked changes.

Parameters (TrackedChangesDocumentFactoryOptions)

• changeset (Changeset): The comparison result to encode.
• schema (Schema): The ProseMirror schema that includes the Tracked Changes extension.

Returns (TrackedChangesDocumentFactoryResult)

• doc (JSONContent): The document with tracked-change marks and node attributes.
• trackedChanges (TrackedChangeData[]): The encoded tracked changes and their ranges in doc.

serializeSchema

Serializes a ProseMirror schema into JSON-safe data.

Parameters

• schema (Schema): The schema to serialize.

Returns (SerializedSchema)

The Tiptap editor schema, encoded as a JSON object, so it can be sent over the network.

deserializeSchema

Creates a ProseMirror schema from serialized schema data.

Parameters

• jsonSchema (SerializedSchema): The JSON-safe schema data to deserialize.

Returns (Schema)

• Schema: The hydrated ProseMirror schema.

StepSequence

Stores a sequence of document states and the metadata for each transition.

StepSequence.fromInitialDocument

Creates an empty sequence.

Parameters

• before (Node): The initial document.

Returns (StepSequence)

• before (Node): The initial document.
• after (Node): The latest document, initially the same as before.
• stepCount (number): The number of recorded steps, initially 0.

StepSequence.fromJSON

Hydrates a sequence from JSON.

Parameters (StepSequenceFromJSONOptions)

• json (StepSequenceJSON): The serialized sequence.
• schema (Schema): The schema used to hydrate its documents.

Returns (StepSequence)

• before (Node): The initial document.
• after (Node): The latest document.
• stepCount (number): The number of recorded steps.

sequence.addStep

Appends a document transition.

Parameters (AddStepOptions)

• doc (Node): The document after the step.
• metadata (ChangeMetadata): Metadata for the step.
• changes? (Change[] | null): Cached changes. null means there are no cached changes so the diff will be computed. An empty array means there were no changes between the steps.
• changedArea? (Change | null): Cached changed area, when available.

Returns (void)

This method does not return a value.

sequence.copy and sequence.reverse

copy duplicates a sequence. reverse returns a sequence that runs from the final document back to the initial document.

Parameters

These methods have no parameters.

Returns (StepSequence)

• before (Node): The initial document for the returned sequence.
• after (Node): The final document for the returned sequence.
• stepCount (number): The number of recorded steps.

sequence.getSteps

Returns each recorded document transition.

Parameters

This method has no parameters.

Returns (Step[])

Each Step contains:

• before (Node): The document before the transition.
• after (Node): The document after the transition.
• metadata (ChangeMetadata): Metadata for the transition.
• changes (Change[] | null): Cached changes, when available.
• changedArea (Change | null): Cached changed area, when available.

sequence.toJSON

Serializes the sequence.

Parameters

This method has no parameters.

Returns (StepSequenceJSON)

• before (JSONContent): The initial document.
• docs (JSONContent[]): Documents after each transition.
• metadata (ChangeMetadata[]): Metadata for each transition.
• changes (Array<Change[] | null>): Cached changes for each transition.
• changedAreas (Array<Change | null>): Cached changed areas for each transition.