querySelector return type could be more specific for compound selectors

[chharvey]

Search Terms

querySelector, return, type, selector

Suggestion

This issue closely follows #8114, which applies only to type selectors ("single-element selectors"). Related to #12568.

The return type of ParentNode#querySelector is Element by default, but when the string argument matches exactly a lower-case element name, the return type is the interface of that element.

For example, .querySelector('#hero.wide') returns an Element type, but .querySelector('img') returns an HTMLImageElement type.

This helpful behavior fails beyond simple type selectors (a selector containing only an element name). When the argument becomes a compound selector, such as .querySelector('img#hero.wide'), the return type is the more generic Element. This is unhelpful when the element name, img, remains in the selector.

My suggestion is to improve parsing of the string argument, so that when it is a compound selector that contains a type selector, the return type can still be a specific interface. Obviously, this would not apply to selectors not containing a type selector, e.g. there is no way to know for sure that .querySelector('#hero.wide') is indeed an HTMLImageElement.

Use Cases

document.querySelector('#hero.wide').src = '//example.com/hero.png' // Element
// Error: Property 'src' does not exist on type 'Element'

document.querySelector('img').src = '//example.com/hero.png' // HTMLImageElement
// no error, but cannot specify *which* image

document.querySelector('img#hero.wide').src = '//example.com/hero.png' // Element
// Error: Property 'src' does not exist on type 'Element'

(document.querySelector('img#hero.wide') as HTMLImageElement).src = '//example.com/hero.png'
// no error, and can specify which image, but must assert type manually

Summary: It would be nice for TS to infer that img#hero.wide selects an HTMLImageElement, based on the tag name img in the selector. This would eliminate the need to assert the type manually.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals. (Specifically: Goals 5, 6, and 9)

[weswigham]

Ref #21044 which'd enable us to support this.

[fregante]

Could this also work for complex selectors and lists of them?

document.querySelector('.wrapper div.box');
document.querySelector('.wrapper div.box, .sidebar div.alert');

[chharvey]

@bfred-it I could see it working for a single complex selector, since it selects only one element (or an array of the same type of element). But I don’t think it would work for selector lists, since there’s a chance more than one type of element could be selected.

To follow your example, what would .querySelector('.wrapper div.box, .sidebar p.alert') return?HTMLDivElement | HTMLParagraphElement? The idea is to get .querySelector() to have a return type that is a single subclass of Element (or Element[] for .querySelectorAll()).

[fregante]

return? HTMLDivElement | HTMLParagraphElement?

Yes, actually that's what I meant to write, two different elements.

If that's not possible, at least support for a homogeneous list of selectors would still be useful: 'div.a, div.b'

[bschlenk]

This is now possible with #40336.

See https://github.com/g-plane/type-gymnastics/blob/master/src/better-querySelector/index.ts

[fregante]

Wow, I never thought this was going to be possible.

@g-plane will you open a PR to merge it into lib.dom.ts?

[g-plane]

I'd like to hear opinions from TypeScript team before doing it.

[orta]

I made a playground to play about with it (interesting work @g-plane! ) - I'll bring it up in a design meeting (maybe next week will have some time), my bet is that we need to figure out the perf trade-offs for that feature. I'd use it a lot though, so you have me on your side at least!

<edit>Updated the playground - thanks @g-plane</edit>

[Manu1400]

@orta In xml, a <body></body> tag is not a HTMLBodyElement but an Element.
Testcase: In webpage https://www.w3schools.com/xml/note.xml select the node and then $0 instanceof Element in devtools return true.

[fregante]

@Manu1400 another way to say it is that these types depend on the current document’s namespace and therefore they probably can't be part of TypeScript (unless there's a way to specify this in the config)

[orta]

There is discussion about that here: #4689 (comment)