Registry / dom-iterator

dom-iterator

JSON →
library1.0.2jsnpmunverified

dom-iterator is a JavaScript library providing a feature-rich, bidirectional iterator for traversing DOM nodes. It offers an enhanced alternative to the native `NodeIterator` API, capable of moving both forwards and backward through the DOM tree. The library allows for advanced filtering of nodes using `select` and `reject` methods based on `nodeType`, string expressions, or custom functions, and includes functionalities like `peek` for non-destructive inspection and methods to jump to `opening()` or `closing()` tags. Currently at version 1.0.2, the package appears to be unmaintained; it was last published on npm a year ago (as of April 2026) and its GitHub repository shows the last commit also from a year ago. Its primary usage pattern is CommonJS, reflecting its age, and it requires a separate DOM implementation (like `mini-html-parser`) to function in Node.js environments.

npm install dom-iterator
github ↗package ↗
INSTALL
IMPORT
SIG · DOM-ITERATOR
D
dom-iterator
javascriptv1.0.2
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

iterator
✓ const iterator = require('dom-iterator');
✗ import iterator from 'dom-iterator';
The package is primarily CommonJS (CJS) and does not officially support ESM imports. Direct ESM imports will fail unless a bundler handles CJS interoperability.
Node
✓ const { JSDOM } = require('jsdom'); const { window } = new JSDOM('<!DOCTYPE html>'); const { Node } = window;
`Node` constants (e.g., `Node.TEXT_NODE`, `Node.ELEMENT_NODE`) are global in browser environments. In Node.js, they must be imported from a DOM implementation library like `jsdom` or `mini-html-parser` if available.

This quickstart demonstrates initializing `dom-iterator` with `jsdom` for a Node.js environment, then using `next()` to traverse all nodes, filtering with `next(Node.TEXT_NODE)`, and traversing backward with `prev(Node.ELEMENT_NODE)`. It also showcases the `select()` method for compound filtering.

const { JSDOM } = require('jsdom'); const { window } = new JSDOM(` <!DOCTYPE html> <html> <body> <div id="root"> <!-- Comment Node --> <p>This is a <b>test</b> paragraph.</p> <div>Another div.</div> </div> </body> </html> `); const { document, Node } = window; const iterator = require('dom-iterator'); const rootNode = document.getElementById('root'); const it = iterator(rootNode); console.log('--- Traversing all nodes (next) ---'); let nextNode; while ((nextNode = it.next())) { console.log(`[${nextNode.nodeType}] ${nextNode.nodeValue || nextNode.nodeName}`); } // Reset iterator and demonstrate filtering console.log('\n--- Traversing only TEXT_NODE (next) ---'); const textIterator = iterator(rootNode); while ((nextNode = textIterator.next(Node.TEXT_NODE))) { console.log(`[TEXT] Value: "${nextNode.nodeValue.trim()}"`); } // Demonstrate previous traversal console.log('\n--- Traversing from the end (previous) ---'); // First, go to the last node to start 'prev' traversal let lastNode = iterator(rootNode); while(lastNode.next()); // move to the very end let prevNode; while ((prevNode = lastNode.prev(Node.ELEMENT_NODE))) { console.log(`[ELEMENT] Tag: ${prevNode.nodeName}`); } // Demonstrate chaining select/reject console.log('\n--- Selecting specific nodes (ELEMENT_NODE OR TEXT_NODE) ---'); const complexIterator = iterator(rootNode) .select(Node.ELEMENT_NODE) .select(Node.TEXT_NODE); while ((nextNode = complexIterator.next())) { if (nextNode.nodeType === Node.ELEMENT_NODE) { console.log(`[SELECTED ELEMENT] Tag: ${nextNode.nodeName}`); } else if (nextNode.nodeType === Node.TEXT_NODE && nextNode.nodeValue.trim()) { console.log(`[SELECTED TEXT] Value: "${nextNode.nodeValue.trim()}"`); } }
Debug
Known issues
breakingThe package is written in CommonJS (CJS) and does not provide native ES Module (ESM) exports. Attempting to `import` it directly in an ESM-only environment will result in a `TypeError: require() of ES Module` or similar error, unless a build tool (like Webpack or Rollup) is configured for CJS interoperability.
fix
Use `const iterator = require('dom-iterator');` in CommonJS files. For ESM projects, either configure your bundler for CJS interoperability or wrap the `require` call in a shim.
affects: >=1.0.0
gotchaThe `dom-iterator` library is unmaintained and has not received updates for approximately one year (as of April 2026). This means it may not be compatible with newer Node.js or browser DOM APIs, could contain unpatched bugs, or lack modern features and performance optimizations.
fix
Evaluate alternatives for active maintenance. If retained, thorough testing for compatibility and potential issues is required, especially in modern environments.
affects: >=1.0.0
gotchaWhen used in a Node.js environment, `dom-iterator` requires a separate DOM implementation (like `jsdom` or `mini-html-parser`) to provide the `Node` object and the DOM structure to traverse. Without a global `Node` object or a compatible DOM element, the iterator will not function correctly.
fix
Install and initialize a DOM parsing library (e.g., `npm install jsdom`). Pass elements from this library to `dom-iterator` and extract `Node` constants from its `window` object.
affects: >=1.0.0
deprecatedThe README mentions installation via `component(1)`, a package manager that has been deprecated and is no longer actively maintained or widely used.
fix
Always install via npm (`npm install dom-iterator`) and ignore references to `component(1)`.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: Node is not defined
Attempting to use `Node.ELEMENT_NODE` or other `Node` constants in a Node.js environment without a global DOM implementation like `jsdom`.
fix
In Node.js, instantiate `jsdom` or similar library and extract the `Node` object from its `window` property. Example: `const { JSDOM } = require('jsdom'); const { window } = new JSDOM(''); const { Node } = window;`
TypeError: iterator is not a function
Commonly occurs when trying to `import iterator from 'dom-iterator'` in an ES Module context where the package is CJS-only, and the interoperability isn't handled correctly by the runtime or bundler.
fix
If in a CJS file, use `const iterator = require('dom-iterator');`. If in an ESM file, and a bundler is not used or configured for CJS interop, you might need to use `import * as domIterator from 'dom-iterator'; const iterator = domIterator;` or consider using a wrapper or direct `require` if supported by your runtime.
Error: Cannot find module 'dom-iterator'
The package `dom-iterator` has not been installed, or the current working directory for `npm install` was not the project root, or there's an issue with module resolution paths.
fix
Ensure the package is installed by running `npm install dom-iterator` in your project's root directory. Verify that `node_modules/dom-iterator` exists.
Upgrade
Version history
1.0.2latest on npm
Audit
Dependencies
mini-html-parseroptionalRequired for `dom-iterator` to parse and traverse DOM nodes in a Node.js environment, as it does not include its own DOM implementation. This is a conceptual rather than direct npm dependency.
Agent activity
8 hits · last 30 days
node
8
Resources
githubhttps://github.com/MatthewMueller/dom-iterator ↗
packagehttps://www.npmjs.com/package/dom-iterator ↗
dom-iterator — npm install dom-iterator · libregistry