back-end biome combinator css dom dom-manipulation html igorskyflyer javascript js magic node query queryselector queryselectorall selector ts typescript

querySelector( 🪄 )

🪄 A TypeScript-types patch for querySelector() / querySelectorAll(), make them return types you expect them to! 🔮

💖 Support further development
I work hard for every project, including this one and your support means a lot to me!
Consider buying me a coffee. ☕
Thank you for supporting my efforts! 🙏😊

@igorskyflyer

📃 Table of contents

Demonstration
Usage
- TypeScript
  - Create a d.ts file
  - Add to the entrypoint
- JavaScript
Implementation
- API status table
Examples
Changelog
License
Related
Author

🎬 Demonstration

Here's magic-querySelector in action.

without-magic.mp4

Without magic-queryselector

with-magic.mp4

With magic-queryselector

Visual Studio Code theme used in the demonstration is Kai 🌊 .

🕵🏼 Usage

Install it by executing:

npm i -D "@igor.dvlpr/magic-queryselector"

Including the magic-queryselector into your project depends on the language of it.

Please see the appropriate section for your project:

TypeScript
JavaScript

TypeScript

If you want to use it with TypeScript, you need to copy the following code

import '@igor.dvlpr/magic-queryselector'

and then do one of the following:

[ 1st option ]

Create a `d.ts` file (recommended)

Warning

This method requires a valid tsconfig.json file to be present in the root of your project.

Create a magic.d.ts file in the root directory of your project and add the snippet you copied:

magic.d.ts

import '@igor.dvlpr/magic-queryselector'

That's it! 🥳 You're all set up.

Tip

TypeScript server sometimes likes to play games, if the patch doesn't work immediately please restart TypeScript server or Visual Studio Code.

[ 2nd option ]

Add to the entrypoint

Add the code snippet you copied to the top of your entrypoint/main TypeScript file.

index.ts

import '@igor.dvlpr/magic-queryselector'

Tip

TypeScript server sometimes likes to play games, if the patch doesn't work immediately please restart TypeScript server or Visual Studio Code.

JavaScript

Note

If you want to use it with JavaScript, you don't need to do anything besides installing the package.

Tip

TypeScript server sometimes likes to play games, if the patch doesn't work immediately please restart TypeScript server or Visual Studio Code.

🤖 Implementation

This patch extends the default (return) type inference of TypeScript by inferring the types from the input string containing selectors/combinators passed to querySelector() / querySelectorAll().

Note

querySelector() will return the type listed in the table below, e.g. HTMLDivElement, while querySelectorAll() will return NodeListOf<T> of the same type, e.g. NodeListOf<HTMLDivElement>.

For brevity this table only shows the types for querySelector().

Read more about selector structure and selectors and combinators on MDN.

The following table shows which selectors/combinators are supported along with the inferred return types for the given examples.

Implementation table

Selector/Combinator	Example	Compatibility	Inference	Before/After
Type + ID	`div#app`	✅	Patched	`Element`/`HTMLDivElement`
Type + Class	`a.myLink`	✅	Patched	`Element`/`HTMLAnchorElement`
Type + Attribute	`a[title]`	✅	Patched	`Element`/`HTMLAnchorElement`
Descendant	`div video`	✅	Patched	`Element`/`HTMLVideoElement`
Child	`main > a`	✅	Patched	`Element`/`HTMLAnchorElement`
Next-sibling	`div + span`	✅	Patched	`Element`/`HTMLSpanElement`
Subsequent-sibling	`h1 ~ pre`	✅	Patched	`Element`/`HTMLPreElement`
Pseudo-class :root	`:root`	✅	Patched	`Element`/`HTMLHtmlElement`
Column (1)	`col \|\| td`	✅	Patched	`Element`/`HTMLTableCellElement`
Universal	`*`	—	Native	`Element`/`Element`
Type	`li`	—	Native	`HTMLLIElement`/`HTMLLIElement`
ID	`#share`	—	Native	`Element`/`Element`
Class	`.footer`	—	Native	`Element`/`Element`
Attribute	`[title]`	—	Native	`Element`/`Element`

Table 1. implementation table

(1) The column combinator is a highly-experimental upcoming combinator "that is placed between two CSS selectors. It matches only those elements matched by the second selector that belong to the column elements matched by the first." (source: MDN )

✨ Examples

main.js

const video = document.querySelector('div#app > video') // HTMLVideoElement | null
const audios = document.querySelectorAll('div#app > audio') // NodeListOf<HTMLAudioElement>

if(video) {
  video.src = '<some_URL>' // now we can access all <video> properties and methods
}

if(audios.length > 0) {
  audios[0].src = '<some_URL>' // 😀😀😀
}