@igor.dvlpr/magic-queryselector NPM

📃 Table of contents

🎬 Demonstration

Here's magic-querySelector in action.

https://github.com/user-attachments/assets/eb0b6695-be60-4a6e-b935-5996b40c5d78

https://github.com/user-attachments/assets/2251724d-98d7-4deb-8a82-8b4f0a6a6e31

🕵🏼 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

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`

(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>' // 😀😀😀
}