{"id":13837463,"url":"https://github.com/fiduswriter/diffDOM","last_synced_at":"2025-07-10T18:33:24.888Z","repository":{"id":11921017,"uuid":"14487686","full_name":"fiduswriter/diffDOM","owner":"fiduswriter","description":"A diff for DOM elements, as client-side JavaScript code. Gets all modifications, insertions and removals between two DOM fragments.","archived":false,"fork":false,"pushed_at":"2024-08-04T04:37:45.000Z","size":1440,"stargazers_count":816,"open_issues_count":13,"forks_count":103,"subscribers_count":21,"default_branch":"main","last_synced_at":"2024-10-29T23:18:44.897Z","etag":null,"topics":["diff","diffhtml","dom-element"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fiduswriter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-11-18T09:20:42.000Z","updated_at":"2024-10-25T15:23:11.000Z","dependencies_parsed_at":"2023-02-19T09:31:29.451Z","dependency_job_id":"4e322ea5-af00-4248-aa60-b3701f904330","html_url":"https://github.com/fiduswriter/diffDOM","commit_stats":{"total_commits":405,"total_committers":31,"mean_commits":"13.064516129032258","dds":"0.41481481481481486","last_synced_commit":"3e2015fc61dea6dd845245564cd551d63ab1f87c"},"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiduswriter%2FdiffDOM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiduswriter%2FdiffDOM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiduswriter%2FdiffDOM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiduswriter%2FdiffDOM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fiduswriter","download_url":"https://codeload.github.com/fiduswriter/diffDOM/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225653873,"owners_count":17502939,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diff","diffhtml","dom-element"],"created_at":"2024-08-04T15:01:10.360Z","updated_at":"2024-11-21T00:30:39.826Z","avatar_url":"https://github.com/fiduswriter.png","language":"HTML","readme":"# diffDOM - A JavaScript diffing algorithm for DOM elements\n\nThis library allows the abstraction of differences between DOM\nelements as a \"diff\" object, representing the sequence of modifications\nthat must be applied to one element in order to turn it into the other\nelement. This diff is non-destructive, meaning that relocations of\nDOM nodes are preferred over remove-insert operations.\n\n## License\n\nThis project is licensed under the LGPL v. 3. For details see LICENSE.txt.\n\n## Demo and tests\n\nCheck http://fiduswriter.github.io/diffDOM for demo and tests.\n\n## Usage\n\nInclude the diffDOM file in your HTML like this:\n\n```html\n\u003cscript src=\"browser/diffDOM.js\"\u003e\u003c/script\u003e\n```\n\nOr like this if you import from npm:\n\n```js\nimport { DiffDOM } from \"diff-dom\"\n```\n\nThen create an instance of diffDOM within the javascript code:\n\n```js\ndd = new diffDOM.DiffDOM()\n```\n\n(leave out the `diffdom.` if you use the npm-version)\n\nNow you can create a diff to get from dom `elementA` to dom `elementB` like this:\n\n```js\ndiff = dd.diff(elementA, elementB)\n```\n\nYou can now apply this diff like this:\n\n```js\ndd.apply(elementA, diff)\n```\n\nNow `elementA` will have been changed to be structurally equal to `elementB`.\n\n### Virtual DOM and HTML strings\n\nYou can also use HTML strings or the virtual DOM objects diffDOM uses internally to create diffs.\n\n```js\ndiff = dd.diff(elementA, \"\u003cdiv\u003ehello\u003c/div\u003e\")\n```\n\nYou can create the Virtual DOM objects diffDOM uses, create them like this:\n\n```js\nimport { nodeToObj, stringToObj } from \"diff-dom\"\n\nobj1 = nodeToObj(elementA)\nobj2 = stringToObj(\"\u003cdiv\u003ehello\u003c/div\u003e\")\n```\n\nDiffing between these objects will be faster than diffing DOM nodes and can be useful in environments\nwithout access to the DOM.\n\n### Advanced uses\n\n#### Undo\n\nContinuing on from the previous example, you can also undo a diff, like this:\n\n```js\ndd.undo(elementA, diff)\n```\n\nNow elementA will be what it was like before applying the diff.\n\n#### Remote changes\n\nIf you need to move diffs from one machine to another one, you will likely want to send the diffs through a websocket connection or as part of a form submit. In both cases you need to convert the diff to a json `string`.\n\nTo convert a diff to a json string which you can send over the network, do:\n\n```js\ndiffJson = JSON.stringify(diff)\n```\n\nOn the receiving end you then need to unpack it like this:\n\n```js\ndiff = JSON.parse(diffJson)\n```\n\n#### Error handling when patching/applying\n\nSometimes one may try to patch an elment without knowing whether the patch actually will apply cleanly. This should not be a problem. If diffDOM determines that a patch cannot be executed, it will simple return `false`. Else it will return `true`:\n\n```js\nresult = dd.apply(element, diff)\n\nif (result) {\n    console.log(\"no problem!\")\n} else {\n    console.log(\"diff could not be applied\")\n}\n```\n\n#### Advanced merging of text node changes\n\ndiffDOM does not include merging for changes to text nodes. However, it includes hooks so that you can add more advanced handling. Simple overwrite the `textDiff` function of the `diffDOM` instance. The functions TEXTDIFF and TEXTPATCH need to be defined in the code:\n\n```js\ndd = new diffDOM.DiffDOM({\n    textDiff: function (node, currentValue, expectedValue, newValue) {\n        if (currentValue === expectedValue) {\n            // The text node contains the text we expect it to contain, so we simple change the text of it to the new value.\n            node.data = newValue\n        } else {\n            // The text node currently does not contain what we expected it to contain, so we need to merge.\n            difference = TEXTDIFF(expectedValue, currentValue)\n            node.data = TEXTPATCH(newValue, difference)\n        }\n        return true\n    },\n})\n```\n\n#### Pre and post diff hooks\n\ndiffDOM provides extension points before and after virtual and actual diffs, exposing some of the internals of the diff algorithm, and allowing you to make additional decisions based on that information.\n\n```js\ndd = new diffDOM.DiffDOM({\n    preVirtualDiffApply: function (info) {\n        console.log(info)\n    },\n    postVirtualDiffApply: function (info) {\n        console.log(info)\n    },\n    preDiffApply: function (info) {\n        console.log(info)\n    },\n    postDiffApply: function (info) {\n        console.log(info)\n    },\n})\n```\n\nAdditionally, the _pre_ hooks allow you to shortcircuit the standard behaviour of the diff by returning `true` from this callback. This will cause the `diffApply` functions to return prematurely, skipping their standard behaviour.\n\n```js\ndd = new diffDOM.DiffDOM({\n    // prevent removal of attributes\n    preDiffApply: function (info) {\n        if (info.diff.action === \"removeAttribute\") {\n            console.log(\"preventing attribute removal\")\n            return true\n        }\n    },\n})\n```\n\n#### Outer and Inner diff hooks\n\ndiffDOM also provides a way to filter outer diff\n\n```js\ndd = new diffDOM.DiffDOM({\n    filterOuterDiff: function (t1, t2, diffs) {\n        // can change current outer diffs by returning a new array,\n        // or by mutating outerDiffs.\n        if (\n            !diffs.length \u0026\u0026\n            t1.nodeName == \"my-component\" \u0026\u0026\n            t2.nodeName == t1.nodeName\n        ) {\n            // will not diff childNodes\n            t1.innerDone = true\n        }\n    },\n})\n```\n\n#### Debugging\n\nFor debugging you might want to set a max number of diff changes between two elements before diffDOM gives up. To allow for a maximum of 500 differences between elements when diffing, initialize diffDOM like this:\n\n```js\ndd = new diffDOM.DiffDOM({\n    debug: true,\n    diffcap: 500,\n})\n```\n\n#### Disable value diff detection\n\nFor forms that have been filled out by a user in ways that have changed which value is associated with an input field or which options are checked/selected without\nthe DOM having been updated, the values are diffed. For use cases in which no changes have been made to any of the form values, one may choose to skip diffing the values. To do this, set `valueDiffing` to `false` as a configuration option to diffDOM:\n\n```js\ndd = new diffDOM.DiffDOM({\n    valueDiffing: false,\n})\n```\n\n#### Interprete strings as case caseSensitive\n\nStrings of HTML can normally be interpreted case-insensitively as HTML tags don't differentiate between uppercase and lowercase. However, in the case of XML (SVGs, XHTML) there is a difference and this should be enabled. To do this, set `caseSensitive` to `true` as a configuration option to diffDOM:\n\n\n```js\ndd = new diffDOM.DiffDOM({\n    caseSensitive: true,\n})\n```\n\n**NOTE!** If there is an SVG inside of the HTML in the string, diffDOM can automatically determine that it should switch to case sensitivity. It is only if the diff happens entirely within an SVG that it is required to specify this.\n","funding_links":[],"categories":["HTML"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffiduswriter%2FdiffDOM","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffiduswriter%2FdiffDOM","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffiduswriter%2FdiffDOM/lists"}