---
title: "Utilities"
description: "Utility functions exported by the Tiptap Compare package."
canonical_url: "https://tiptap.dev/docs/compare/api-reference/utilities"
---

# Utilities

Utility functions exported by the Tiptap Compare package.

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](https://tiptap.dev/docs/compare/api-reference/types.md#diffoptions).

### Returns (`Changeset`)

Returns a changeset containing both documents and their changes. See [Changeset](https://tiptap.dev/docs/compare/api-reference/utilities.md#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](https://tiptap.dev/docs/compare/api-reference/utilities.md#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](https://tiptap.dev/docs/compare/api-reference/utilities.md#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](https://tiptap.dev/docs/compare/api-reference/utilities.md#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](https://tiptap.dev/docs/editor/extensions/custom-extensions/node-views.md) 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](https://prosemirror.net/docs/ref/#model.Slice) as a document fragment for display in a diff.

### Parameters (`RenderSliceToHtmlOptions`)

- `slice` ([`Slice`](https://prosemirror.net/docs/ref/#model.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`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment))

Returns a [document fragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) 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](https://tiptap.dev/docs/tracked-changes/getting-started/overview.md). 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.