Consider adopting typed-query-selector for type-safe DOM queries
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 806
- Forks
- 434
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 32
Description
Context
From review of #5169 (comment), @sidvishnoi suggested evaluating typed-query-selector to get type-safe querySelector / querySelectorAll results without manual casts.
Current state
We use /** @type {NodeListOf<HTMLElement>} */ and similar JSDoc casts extensively across the codebase (e.g. anchor-expander.js, linter rules, link-to-dfn.js). These are unchecked at runtime and can drift from the actual selectors.
Proposal
Evaluate typed-query-selector as a dev dependency. It augments the built-in querySelector / querySelectorAll types so TypeScript infers the correct element type from the selector string (e.g. document.querySelector("a.foo") returns HTMLAnchorElement | null without a cast).
Trade-offs to consider
- Adds a dev dependency (types only, no runtime cost)
- May not cover all our selector patterns (e.g. attribute selectors, complex combinators)
- Could reduce the number of
@ts-expect-errordirectives we need
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the existing JSDoc casts and selectors in anchor-expander.js, the linter rules, and link-to-dfn.js. Evaluate typed-query-selector against the selector patterns and current @ts-expect-error usage, then document whether the dependency can be adopted and which casts it would replace.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- frontend, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100