Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/igorskyflyer/npm-magic-queryselector

🪄 A TypeScript-types patch for querySelector/querySelectorAll, make them return types you expect them to! 🔮
https://github.com/igorskyflyer/npm-magic-queryselector

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

Last synced: about 2 hours ago
JSON representation

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

Host: GitHub
URL: https://github.com/igorskyflyer/npm-magic-queryselector
Owner: igorskyflyer
License: mit
Created: 2024-07-16T17:44:26.000Z (4 months ago)
Default Branch: main
Last Pushed: 2024-07-28T21:39:29.000Z (3 months ago)
Last Synced: 2024-09-29T05:56:15.278Z (about 1 month ago)
Topics: back-end, biome, combinator, css, dom, dom-manipulation, html, igorskyflyer, javascript, js, magic, node, query, queryselector, queryselectorall, selector, ts, typescript
Homepage: https://www.npmjs.com/package/@igor.dvlpr/magic-queryselector
Size: 8.42 MB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

        
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](#-demonstration)

- [Usage](#-usage)

  - [TypeScript](#typescript)

	  - [Create a d.ts file](#create-a-dts-file-recommended)

	  - [Add to the entrypoint](#add-to-the-entrypoint)

  - [JavaScript](#javascript)

- [Implementation](#-implementation)

  - [API status table](#implementation-table)

- [Examples](#-examples)

- [Changelog](#-changelog)

- [License](#-license)

- [Related](#-related)

- [Author](#-author)

---







## 🎬 Demonstration

Here's `magic-querySelector` in action.




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



	Without magic-queryselector









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



	With magic-queryselector









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


---

## 🕵🏼 Usage

Install it by executing:

```shell

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](#typescript)

- [JavaScript](#javascript)

---

### TypeScript

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

```ts

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`

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

```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` of the same type, e.g. `NodeListOf`.

>

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

>

> Read more about [selector structure](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selector_structure) ![External link](https://raw.githubusercontent.com/igorskyflyer/igorskyflyer/main/assets/external.svg) and [selectors and combinators](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selectors_and_combinators) ![External link](https://raw.githubusercontent.com/igorskyflyer/igorskyflyer/main/assets/external.svg) 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](https://developer.mozilla.org/en-US/docs/Web/CSS/Column_combinator) )




---

## ✨ Examples

`main.js`

```js

const video = document.querySelector('div#app > video') // HTMLVideoElement | null

const audios = document.querySelectorAll('div#app > audio') // NodeListOf

if(video) {

  video.src = '' // now we can access all  properties and methods

}

if(audios.length > 0) {

  audios[0].src = '' // 😀😀😀

}

```

---

## 📝 Changelog

📑 Changelog is available here: [CHANGELOG.md](https://github.com/igorskyflyer/npm-magic-queryselector/blob/main/CHANGELOG.md).

---

## 🪪 License

Licensed under the MIT license which is available here, [MIT license](https://github.com/igorskyflyer/npm-magic-queryselector/blob/main/LICENSE).

---

## 🧬 Related

[@igor.dvlpr/jmap](https://www.npmjs.com/package/@igor.dvlpr/jmap)

> _🕶️ Reads a JSON file into a Map. 🌻_




[@igor.dvlpr/extendable-string](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@igor.dvlpr/unc-path)

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




[@igor.dvlpr/duoscribi](https://www.npmjs.com/package/@igor.dvlpr/duoscribi)

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




[@igor.dvlpr/node-clone-js](https://www.npmjs.com/package/@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*](https://github.com/igorskyflyer/)).