Return NodeList from querySelectorAll

[olavoasantos]

Problem

querySelectorAll() collected matches in a plain Array, even though the polyfill provides a NodeList collection with the DOM-compatible item() method. Array indexing, length, iteration, and forEach() happened to work, but callers using the standard NodeList.item() shape received a collection without that method.

Impact

Minor. Feature-compatible selector code that calls .item() on a querySelectorAll() result threw at runtime instead of receiving the matching element or null for an out-of-range index.

Reproduction

const container = document.createElement('div');
container.innerHTML = '<p class="text">First paragraph</p>';

const matches = container.querySelectorAll('.text');
matches.item(0);

Before this change, the final call failed because matches was a plain array. It now returns the paragraph; matches.item(-1) and matches.item(matches.length) return null. The captured result remains static after a later matching node is appended.

Change

Construct selector results as NodeList<Element> rather than Element[], and make NodeList generic so the public and internal query APIs retain element item types. The accompanying type refinements keep childNodes, children, and element collection helpers aligned with that collection shape.

Tests

Adds runtime coverage for the returned NodeList instance, indexing, iteration, forEach(), in-range and out-of-range item(), and static result behavior. Type assertions cover instance and standalone selector results as NodeList<Element> and .item() as Element | null.

Stack

• Stack: Namespace and selectors (#698), layer 3 of 3
• Base: correct-selector-matching
• Review after PR Correct selector matching #679.

Validation

Fresh GitHub CI on restacked head e08f0af passes:

• lint;
• type-check and build;
• unit tests with coverage;
• bundle-size checks;
• Playwright end-to-end tests;
• the classified Web Platform Test suite.

[henrytao-me]

The scoped production change looks good at e08f0af against #679 1204f44. I found one test correction to make before landing:

selectors.test.ts:243-260 assigns className to the newly appended paragraph:

container.appendChild(document.createElement('p')).className = 'text';

This polyfill does not implement className reflection. The assignment creates a plain property, leaves getAttribute('class') as null, and even a fresh query still returns three matches. Native's fresh query returns four. The test never adds a matching node, so the unchanged saved result does not demonstrate static membership.

Please use the supported attribute API and assert both the fresh and saved collections:

container
  .appendChild(document.createElement('p'))
  .setAttribute('class', 'text');

expect(container.querySelectorAll('.text')).toHaveLength(4);
expect(matches).toHaveLength(3);

Keep the existing order/iteration assertions. I independently verified this repaired fixture gives old 3 / fresh 4 on native, base, and head. No className implementation belongs in this narrow PR.

Otherwise, .item() now works for ordinary indices, result membership stays static while preserving node references, and existing live children/childNodes bookkeeping is unchanged. The shared NodeList helper still has pre-existing index-conversion and array-backed-shape limitations; this is not a request to bundle those broader corrections here.

Validation: 288 polyfill tests and 59 focused core tests pass; all three new tests fail the actual base. The locked-TypeScript polyfill check passes head, while base plus the new tests has four expected type errors. All 30 scoped native collection/snapshot/bookkeeping checks match, and 279 selector-result cases are unchanged from #679, including its known gaps. Formatting and reported CI are green. Full-repository/live validation and upstream corrections remain separate gates. No source fix or approval performed.

[olavoasantos]

yea, the fixture wasn't adding a matching node. i switched it to setAttribute('class', 'text') and now assert the fresh query has four results while the saved NodeList remains at three. No className implementation is added here.