📃 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.

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
• 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 |

(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).