Cross-Environment querySelectorAll Implementation

Common errors

• TypeError: require(...) is not a function

  cause In version 2.0.0+, the `querySelectorAll` function is exported as a default property on the module, not the module itself, in CommonJS.
  fix Change `const querySelectorAll = require('query-selector');` to `const querySelectorAll = require('query-selector').default;`

• TypeError: (0, _queryselector.default) is not a function

  cause This error typically occurs in a transpiled ESM environment when trying to import a CommonJS module's named export as a default, or when a default export is incorrectly accessed from an object.
  fix Ensure you are using `import querySelectorAll from 'query-selector';` for default imports, or verify your transpilation configuration correctly handles CommonJS default exports for modules like this.

• Cannot read properties of undefined (reading 'innerHTML') for a selected element

  cause The selector did not match any elements, resulting in an empty NodeList (or similar), and attempting to access an index like `[0]` on it returns `undefined`.
  fix Always check the `length` property of the returned `NodeList` before attempting to access elements by index: `const elements = querySelectorAll('.my-selector'); if (elements.length > 0) { console.log(elements[0].innerHTML); }`

Warnings

• gotcha Performance of this JavaScript-based implementation may be slower compared to native browser `querySelectorAll` methods, especially for complex selectors or large DOM trees. Modern browser engines are highly optimized for this task.
  Fix: For browser environments with native `querySelectorAll` support, prefer the native implementation. Use this package primarily for environments lacking native support or for specific polyfill requirements.
• gotcha The package, last updated in 2019, may not fully support all modern CSS Selectors Level 4 features or advanced pseudo-classes that newer browser engines have implemented. This could lead to unexpected results or unsupported selectors.
  Fix: Thoroughly test complex or newer CSS selectors when using this package. If specific modern selectors are critical, consider alternative, more actively maintained DOM manipulation libraries or ensure a modern browser environment.
• breaking Version 2.0.0 changed the CommonJS export mechanism, requiring developers to access the function via `.default`. Directly requiring the module `require('query-selector')` without `.default` will no longer return the `querySelectorAll` function itself, but the module object.
  Fix: Update all CommonJS `require` statements from `const querySelectorAll = require('query-selector');` to `const querySelectorAll = require('query-selector').default;`.
• gotcha The `querySelectorAll` function (both native and this implementation) returns a `NodeList` (or similar array-like object in Node.js with `jsdom`), not a standard JavaScript Array. This means methods like `map`, `filter`, or `reduce` are not directly available without explicit conversion (e.g., `Array.from(nodeList)` or `[...nodeList]`).
  Fix: Convert the `NodeList` to an Array when array methods are needed: `Array.from(querySelectorAll('.selector'))` or `[...querySelectorAll('.selector')]`.

Install

• npm install query-selector npm
• yarn add query-selector yarn
• pnpm add query-selector pnpm

Imports

• querySelectorAll
  wrong:

  const querySelectorAll = require('query-selector');

  correct:

  const querySelectorAll = require('query-selector').default;

  Since v2.0.0, the package exports the function as a default export on the module object for CommonJS. Attempting to require the module directly will return the module object, not the function.
• querySelectorAll (ESM)
  wrong:

  import { querySelectorAll } from 'query-selector';

  correct:

  import querySelectorAll from 'query-selector';

  While primarily a CommonJS package from 2019, if used in an ESM context via a transpiler or bundler, the CommonJS default export typically translates to a default ESM import.
• Standalone Browser Global

  <!-- In HTML: --><script src="/build/query-selector-standalone-debug.js"></script>
  <script>console.log(querySelectorAll('#t span'));</script>

  For standalone browser usage, the library exposes 'querySelectorAll' as a global variable after including its build script.

Quickstart

This quickstart demonstrates how to use `query-selector` within a Node.js environment by integrating it with `jsdom` to provide a document context. It shows both the native `querySelectorAll` (if available in the JSDOM instance) and the package's implementation, highlighting its usage and expected output.

const querySelectorAll = require('query-selector').default;
const { JSDOM } = require('jsdom');

// Create a JSDOM environment for Node.js to simulate a browser DOM
const dom = new JSDOM('<html><body><div id="t"><span>1</span><span>2</span></div></body></html>');
const doc = dom.window.document;

console.log('--- Using native doc.querySelectorAll ---');
const nativeElements = doc.querySelectorAll('#t span');
console.log('Native result length:', nativeElements.length);
console.log('Native first element innerHTML:', nativeElements[0].innerHTML);

console.log('\n--- Using query-selector package ---');
const customElements = querySelectorAll('#t span', doc);
console.log('Custom result length:', customElements.length);
console.log('Custom first element innerHTML:', customElements[0].innerHTML);

// Demonstrates calling the custom querySelectorAll with a specific context (the document)
// The output should be identical, showcasing its polyfill capability.
// In a browser, the 'doc' argument would often be 'document' or 'this'.