repository·main·Indexed 22 days ago
https://github.com/bigskysoftware/idiomorphA lightweight, dependency-free JavaScript library for morphing one DOM tree into another. Idiomorph uses 'id sets' to match elements based on their descendants' IDs, providing more robust updates and better DOM stability than traditional morphing algorithms. It supports various module formats (AMD, CJS, ESM), provides a comprehensive lifecycle callback system, and includes a dedicated extension for integration with htmx.
Idiomorph is used as a core merging strategy in several high-profile projects:
Idiomorph uses id sets to achieve better DOM matching than traditional morphing libraries (like morphdom).
The Problem: In many HTML layouts, parent containers lack IDs (using classes for layout instead), while 'leaf' nodes (grandchildren) have IDs. When these leaf nodes change order, traditional morphing libraries often fail to realize the parent container is the same and may unnecessarily detach and re-attach the entire subtree.
The Idiomorph Solution: Idiomorph computes an id set for every node, which includes the IDs of all its descendants. This allows it to recognize that a node with specific grandchildren is the same as a node in the new structure, even if the parent itself has no ID. This results in fewer node detachments and better performance for complex reordering.
Idiomorph is a JavaScript DOM-merging algorithm designed to synchronize an oldNode with a newNode. Its primary goal is to minimize the number of nodes disconnected from the DOM (moves or replacements).
Minimizing disconnections is critical because browser state—such as input focus, video playback, or scroll position—is often lost when nodes are removed or replaced. Idiomorph achieves high fidelity by matching the new structure to the existing structure as closely as possible, rather than performing a generic tree merge.
Key concepts include:
nanomorph) that rely heavily on strict ID equivalence, Idiomorph uses a broader definition of "sameness" based on the intersection of ID sets. This allows nodes to be recognized as the same even if they don't share a direct ID, provided they contain related IDs in their subtree.In many DOM morphing libraries, "sameness" (determining if a new node can be merged into an existing old node) is strictly tied to whether elements have matching IDs.
Idiomorph improves this by using an ID Set Intersection approach:
Idiomorph treats the <head> tag specially to minimize network requests (like re-fetching stylesheets). By default, it uses a merge algorithm: elements in both tags are ignored, new elements are added, and missing elements are removed.
You can control this via the head.style option:
merge (default): Merges elements based on presence, ignoring order.append: Appends all content from the new head to the old head.morph: Uses the standard Idiomorph morphing algorithm for the head.none: Ignores the head tag entirely.You can use specific HTML attributes to fine-tune behavior:
im-re-append='true': Forces a <script> tag to re-evaluate even if it exists in both heads.im-preserve='true': Prevents an element from being removed even if it is not in the new head.Idiomorph.morph(document.documentElement, newPageSource, {head: {style: 'morph'}});Idiomorph provides superior DOM stability compared to morphdom when morphing elements that lack unique IDs.
While morphdom often fails to recognize when an element (like an <iframe>) has moved within the DOM tree—leading it to discard and recreate the element (which breaks state like video playback)—Idiomorph uses an internal id-set. This id-set includes the IDs of all descendant elements, allowing Idiomorph to track elements even if their parent containers do not have IDs. This enables Idiomorph to correctly identify that an element has moved rather than being replaced.
<!-- Example of HTML that Idiomorph handles more stably than morphdom -->
<div class="container">
<div class="header">
<h3>Above...</h3>
</div>
<div class="content">
<iframe id="video" src="..."></iframe>
</div>
</div>
<!-- When morphed to this, Idiomorph preserves the iframe state -->
<div class="container">
<div class="content">
<iframe id="video" src="..."></iframe>
</div>
<div class="header">
<h3>Below...</h3>
</div>
</div>perf/benchmarks directory using the naming convention [benchmark-name].old.html and [benchmark-name].new.html. The .old.html file should contain the starting HTML state, and the .new.html file should contain the final morphed HTML state.After running tests, coverage data is generated. You can view the visual report by opening coverage/lcov-report/index.html in a browser. On Ubuntu, use xdg-open to open it.
# Open coverage report (Ubuntu)
xdg-open coverage/lcov-report/index.htmlYou can target specific files or individual test cases to speed up development.
To run a specific test file (e.g., test/core.js) headlessly, pass the file path to the npm test command. To isolate a single test within that file, temporarily use it.only(...) in the source code.
For easier debugging, you can run tests directly in a browser using Mocha. Simply open the test/index.html file in your preferred browser. On Ubuntu, use xdg-open.
# Run a specific test file headlessly
npm test test/core.js
# Run tests in browser mode (Ubuntu)
xdg-open test/index.htmlTo set up the testing environment, ensure you have a supported version of Node.js and npm installed. You must install the project dependencies and the Playwright browser binaries.
npm install
npx playwright installIdiomorph includes a performance benchmarking suite located in the perf directory to compare the current implementation of src/idiomorph.js against morphdom or previous Idiomorph releases. These benchmarks are intended for manual execution during development to detect performance regressions and are not part of the standard CI or coverage reports.
npm run perf [versus=morphdom] [benchmarks...]Idiomorph.defaults object. This includes nested objects like Idiomorph.defaults.callbacks and Idiomorph.defaults.head.