MutationDiff

Private structure for holding raw attribute, character, or custom property changes. For performance reasons you may access this, but backwards compatibility is not guaranteed. See the source code for usage.

For memory optimization: Returns a value indicating the size of internal storage for tracking the mutations. You could use this to trigger periodic reversion/clearing or other mutation processing to keep memory lower.

Private structure for holding raw node additions, deletions, or movements. For performance reasons you may access this, but backwards compatibility is not guaranteed. See the source code for usage.

Moves groups of nodes inside the current DOM to new positions. You can use this to revert nodes' DOM positions, or apply mutated positions to an unchanged DOM. Out-of-the-box this does not support patching an unrelated DOM tree. However, this could be done easily by mapping nodes from one tree to another:

*function remapped_diff(){
	for (const group of diff.diff_grouped_children()){
		group.nodes = group.nodes.map(remap_fn)
		yield group;
	}
}
diff.patch_grouped_children(remapped_diff());

The remap_fn might consult a Map<Node,Node> or fetch a unique identifier for the node that we can find a correspondence to in the other DOM.

Indicate HTML attribute changed. Note this uses the current node.getAttribute() value for detecting when the attribute is modified.

Indicate nodes were added or removed as children of some parent node

Clear the internal log of mutations, effectively "committing" the current DOM. You may also wish to reattach a corresponding MutationObserver, as it can track DOM nodes outside root. After clearing/reverting, these disconnected trees do not matter anymore. See the MDN documetation for MutationObserver.observe() for details.

Indicate some custom property for the node has changed. A custom property is any user defined value derived from, or associated with a node. Custom properties are not automatically reverted; you must provide a callback to revert them yourself, see revert

Indicate data change for a CharacterData node (e.g. text content has changed). Note this uses the current node.data value for detecting when the text is modified.

Get the current diff. Mutated properties are not cached, so requesting MUTATED will mean the DOM will be queried for the current value. Additionally, you may consider using diff_grouped_children instead for the CHILDREN diff, as that may be more useful for downstream tasks.

Generator which yields groups of adjacent nodes whose DOM position was altered. When patching a DOM and rearranging the nodes to new positions, it is necessary to link adjacent nodes first. The reason is that DOM insertions require a reference sibling, e.g. Node.insertBefore(). If a reference sibling has not been patched first, a node could be moved to the incorrect position.

You can fetch groups of nodes for either the original or mutated DOM tree. The groups will not necessarily be the same.

This is implemented as a generator in case you want to process groups as they come and reduce memory usage. You can loop over the return value like any other iterable. If you'd like to get an array instead, simply use:

Array.from(diff.diff_grouped_children())

See MutationDiff.patch_grouped_children for using the result to patch a (possibly different) DOM.

Check if the DOM is mutated. If the DOM was changed, but the changes put the DOM back in its original state, the DOM is not mutated.

Get a BoundaryRange indicating bounds of the mutated parts of the DOM. You must call this prior to revert, since reverting resets diff tracking. The range returned is a BoundaryRange, utilizing the node-boundary package. A BoundaryRange is similar to a builtin Range, but uses a different internal representation that makes it robust to mutations. The range can still be used if the DOM is reverted, or additional changes occur within the range.

Add the changes indicated by a MutationRecord. Note for attributes and characterData records, you need to include the old value for diffing to function correctly.

Revert the DOM to its original state. This also produces the effects of clear. As noted in clear you may wish to reattach a corresponding MutationObserver.

Signals that all mutations have been recorded and the view of the DOM given to MutationDiff is up-to-date with the current DOM. This would be the case after MutationObserver.takeRecords() has been called, for example. This allows us to release some cached information about data/attributes/properties. This also can resolves untracked add mutations, which allows DOM trees disconnected from the root to be reverted correctly.

For use with MutationDiff#diff

For use with MutationDiff#revert

The output format returned by MutationDiff#diff

Gives the diff for a node addition, removal, or movement; for use inside MutationDiff~Diff

Gives a node's position in the DOM; for use inside MutationDiff~DiffChildren and yielded from diff_grouped_children.

Gives the diff for a data, attribute, or custom property change; for use inside MutationDiff~Diff