README.md

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

---

📝 Changelog

📑 Changelog is available here: CHANGELOG.md.

---

🪪 License

Licensed under the MIT license which is available here, MIT license.

---

🧬 Related

@igor.dvlpr/jmap

🕶️ Reads a JSON file into a Map. 🌻

@igor.dvlpr/extendable-string

🦀 ExtendableString allows you to create strings on steroids that have custom transformations applied to them, unlike common, plain strings.. 🪀

@igor.dvlpr/unc-path

🥽 Provides ways of parsing UNC paths and checking whether they are valid. 🎱

@igor.dvlpr/duoscribi

✒ DúöScríbî allows you to convert letters with diacritics to regular letters. 🤓

@igor.dvlpr/node-clone-js

🧬 A lightweight JavaScript utility allowing deep copy-by-value of nested objects, arrays and arrays of objects. 🪁

---

👨🏻‍💻 Author

Created by Igor Dimitrijević (@igorskyflyer).