DOM Walk

0.1.2 · abandoned · verified Sun Apr 19

dom-walk is a minimalistic, client-side utility library designed for iteratively traversing a DOM node and its children. Currently at version 0.1.2, it was last published approximately six years ago (as of early 2020), indicating it is no longer actively maintained. Despite its age and low version number, it reports a surprisingly high weekly download count, suggesting it is a transitive dependency in many projects or widely used in legacy applications. The library provides a single `walk` function that takes a list of nodes and a callback to execute for each node. Its simplicity and small footprint were advantageous in older web development contexts, but its lack of ongoing development and reliance on CommonJS make it less suitable for modern projects that prioritize ESM, TypeScript, and active community support. Alternatives or native DOM traversal methods are generally preferred for new development.

Common errors

```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use `require('dom-walk')` directly within an ES Module (`.mjs` file or `"type": "module"` package).

fix If using a bundler, it might handle `import walk from 'dom-walk';`. Otherwise, in pure ESM, you cannot `require`. Consider using native DOM traversal or a modern, ESM-compatible library.
```
TypeError: Cannot read properties of undefined (reading 'childNodes')
```
cause Attempting to run `dom-walk` in a Node.js environment without a simulated DOM (`document` object is undefined).

fix Ensure the code runs in a browser. If you must run in Node.js, integrate JSDOM: `const { JSDOM } = require('jsdom'); const dom = new JSDOM('<!DOCTYPE html><body></body>'); global.document = dom.window.document;` before importing and using `dom-walk`.

Warnings

breaking The package is CommonJS-only (`require`) and does not officially support ES Modules (`import`). Direct `import` statements may require bundler configuration or result in errors in pure ESM environments.
Fix: Use `const walk = require('dom-walk');` in CommonJS modules. For ESM, consider native DOM traversal methods or modern alternatives, or ensure your bundler (e.g., Webpack, Rollup) is configured to handle CJS imports.
gotcha This package is unmaintained, with its last publish dating back approximately six years. It has not seen updates for new browser APIs, bug fixes, or security patches.
Fix: Avoid using in new projects. For existing projects, consider migrating to native DOM traversal (`Node.childNodes`, `Node.children`, `TreeWalker`) or a actively maintained modern DOM utility library to ensure compatibility and security.
gotcha The package does not provide official TypeScript type definitions. Usage in TypeScript projects will require manual declaration files (`.d.ts`) or reliance on `@ts-ignore`.
Fix: Create a `dom-walk.d.ts` file with `declare module 'dom-walk';` or define basic types for the `walk` function manually: `declare module 'dom-walk' { function walk(nodes: NodeListOf<ChildNode> | Node[], callback: (node: Node) => void): void; export = walk; }`.
gotcha This library is designed exclusively for browser DOM traversal and will not function in a Node.js environment without a DOM implementation like JSDOM.
Fix: Ensure the code is executed in a browser context. For server-side rendering or Node.js testing, use JSDOM or a similar library to simulate a DOM environment if `dom-walk` is a necessary dependency.

Install

npm install dom-walk npm
yarn add dom-walk yarn
pnpm add dom-walk pnpm

Imports

walk
wrong:
```
const walk = require('dom-walk')
```
correct:
```
import walk from 'dom-walk'
```
This package is CommonJS only. While `import walk from 'dom-walk'` might work with bundlers, the original intent was `require`.
walk
```
const walk = require('dom-walk')
```
This is the original and intended CommonJS usage as shown in the package's documentation.

Quickstart

Demonstrates how to import and use the `walk` function to traverse DOM nodes, logging the type and content of each visited node.

import walk from 'dom-walk';

// Ensure this code runs in a browser environment with a DOM.
// For Node.js, you would need a JSDOM-like environment.

function setupAndWalkDOM() {
  // Create some dummy DOM structure for the example
  document.body.innerHTML = `
    <div id="root">
      <p>Paragraph 1</p>
      <div>
        <span>Span 1</span>
        <p>Paragraph 2</p>
      </div>
    </div>
  `;

  const nodesToWalk = document.body.childNodes;

  console.log('Starting DOM walk...');
  walk(nodesToWalk, function (node) {
    if (node.nodeType === Node.ELEMENT_NODE) {
      console.log("Visited element node:", node.tagName.toLowerCase(), 'id:', node.id);
    } else if (node.nodeType === Node.TEXT_NODE && node.textContent.trim().length > 0) {
      console.log("Visited text node:", node.textContent.trim());
    }
  });
  console.log('DOM walk complete.');
}

// Execute the setup and walk once the DOM is ready
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', setupAndWalkDOM);
} else {
  setupAndWalkDOM();
}

view raw JSON →