speced / speced/respec

Consider adopting typed-query-selector for type-safe DOM queries

Open
#5,171 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Feature request
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-error directives we need

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.