{"id":13082,"library":"dom-iterator","title":"DOM Node Iterator","description":"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.","status":"abandoned","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/MatthewMueller/dom-iterator","tags":["javascript","iterator","dom","mini-html-parser"],"install":[{"cmd":"npm install dom-iterator","lang":"bash","label":"npm"},{"cmd":"yarn add dom-iterator","lang":"bash","label":"yarn"},{"cmd":"pnpm add dom-iterator","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required 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.","package":"mini-html-parser","optional":true}],"imports":[{"note":"The package is primarily CommonJS (CJS) and does not officially support ESM imports. Direct ESM imports will fail unless a bundler handles CJS interoperability.","wrong":"import iterator from 'dom-iterator';","symbol":"iterator","correct":"const iterator = require('dom-iterator');"},{"note":"`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.","symbol":"Node","correct":"const { JSDOM } = require('jsdom');\nconst { window } = new JSDOM('');\nconst { Node } = window;"}],"quickstart":{"code":"const { JSDOM } = require('jsdom');\nconst { window } = new JSDOM(`\n \n \n \n

\n \n

This is a test paragraph.

Another div.

\n \n \n`);\nconst { document, Node } = window;\nconst iterator = require('dom-iterator');\n\nconst rootNode = document.getElementById('root');\nconst it = iterator(rootNode);\n\nconsole.log('--- Traversing all nodes (next) ---');\nlet nextNode;\nwhile ((nextNode = it.next())) {\n console.log(`[${nextNode.nodeType}] ${nextNode.nodeValue || nextNode.nodeName}`);\n}\n\n// Reset iterator and demonstrate filtering\nconsole.log('\\n--- Traversing only TEXT_NODE (next) ---');\nconst textIterator = iterator(rootNode);\nwhile ((nextNode = textIterator.next(Node.TEXT_NODE))) {\n console.log(`[TEXT] Value: \"${nextNode.nodeValue.trim()}\"`);\n}\n\n// Demonstrate previous traversal\nconsole.log('\\n--- Traversing from the end (previous) ---');\n// First, go to the last node to start 'prev' traversal\nlet lastNode = iterator(rootNode);\nwhile(lastNode.next()); // move to the very end\n\nlet prevNode;\nwhile ((prevNode = lastNode.prev(Node.ELEMENT_NODE))) {\n console.log(`[ELEMENT] Tag: ${prevNode.nodeName}`);\n}\n\n// Demonstrate chaining select/reject\nconsole.log('\\n--- Selecting specific nodes (ELEMENT_NODE OR TEXT_NODE) ---');\nconst complexIterator = iterator(rootNode)\n .select(Node.ELEMENT_NODE)\n .select(Node.TEXT_NODE);\n\nwhile ((nextNode = complexIterator.next())) {\n if (nextNode.nodeType === Node.ELEMENT_NODE) {\n console.log(`[SELECTED ELEMENT] Tag: ${nextNode.nodeName}`);\n } else if (nextNode.nodeType === Node.TEXT_NODE && nextNode.nodeValue.trim()) {\n console.log(`[SELECTED TEXT] Value: \"${nextNode.nodeValue.trim()}\"`);\n }\n}\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Evaluate alternatives for active maintenance. If retained, thorough testing for compatibility and potential issues is required, especially in modern environments.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always install via npm (`npm install dom-iterator`) and ignore references to `component(1)`.","message":"The README mentions installation via `component(1)`, a package manager that has been deprecated and is no longer actively maintained or widely used.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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;`","cause":"Attempting to use `Node.ELEMENT_NODE` or other `Node` constants in a Node.js environment without a global DOM implementation like `jsdom`.","error":"ReferenceError: Node is not defined"},{"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.","cause":"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.","error":"TypeError: iterator is not a function"},{"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.","cause":"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.","error":"Error: Cannot find module 'dom-iterator'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}