Request for support of console $ and $$

[coolaj86]

Will you add exports (or however you call it) for $ and $$, just as you have for ParentNode?

Rationale

$ and $$ are native to the browser, just like document.querySelector and document.querySelectorAll.

They are different in that

• they accept a ParentNode as an optional second parameter (the default being document)
• $$ returns a JavaScript Array rather than a NodeList

Since it's very common to use $ and $$ in this way, I hope it makes sense to include them here as well.

Implementation

/**
 * Select first matching element, just like console $
 * @param {String} cssSelector
 * @param {ParentNode} [$parent=document]
 */
function $(cssSelector, $parent = document) {
  let $child = $parent.querySelector(cssSelector);
  return $child;
}

/**
 * Select all matching child elements as a JS Array, just like console $$
 * @param {String} cssSelector
 * @param {ParentNode} [$parent=document]
 */
function $$(cssSelector, $parent = document) {
  let $children = $parent.querySelectorAll(cssSelector);
  let children = Array.from($children);
  return children;
}

Native to Browser, No JavaScript Loaded

As you can see here, the behavior is as I've described. There is no JavaScript on example.com, and all browsers that I'm aware of have the same implementation - both Firefox and everything else (Chromium- or Webkit-based).

[g-plane]

They're console-only, not available for your scripts.

[coolaj86]

@g-plane Yes and no. The built-ins are console only, but it's the standard that people use in their projects as well.

Most people are only going type document.querySelectorAll so many times before they take the 10 seconds to write those two one-line functions.

I know most codebases write it like this, but that makes my eyes bleed:

const $ = (s, e = document) => e.querySelector(s)
const $$ = (s, e = document) => Array.from(e.querySelectorAll(s))

What about just exporting it as a typedef rather than a global?

Or providing an example of how to apply the types you've created to that boilerplate?

[g-plane]

You can publish your own npm package to do this.

[fregante]

@coolaj86 the types are exported. See my own usage in:

https://github.com/fregante/select-dom/blob/afdd637791737fc9dbcc8590d6655246d16bb4d5/index.ts#L1

and actually I have that exact utility there so you can just npm install select-dom

[coolaj86]

You can publish your own npm package to do this.

@g-plane Can you give me an example of what it would look like to use this in JavaScript?

@fregante I don't know TS definitions well enough to know what question to ask, but is there some way that I could get those types working in JavaScript? I did look at the file you shared but, to put it bluntly, that's why I don't write TypeScript - I just can't understand things at that level.

This is the sort of thing I would expect to be able to do:

Option A: Apply the type directly to the function:

/** @typedef {@import("typed-query-selector/strict").RelativeSelectorCallbackDefinition} RelativeSelector */
/** @typedef {@import("typed-query-selector/strict").RelativeSelectorAllCallbackDefinition} RelativeSelectorAll */

/** @type {RelativeSelector} */
const $ = (s, e = document) => e.querySelector(s)

/** @type {RelativeSelectorAll} */
const $$ = (s, e = document) => Array.from(e.querySelectorAll(s))

Option B: Apply the return type:

/** @typedef {@import("typed-query-selector/strict").AmbiElement} AmbiElement */
/** @typedef {@import("typed-query-selector/strict").AmbiElement} AmbiElement */

/**
  * @param {String} s
  * @param {ParentNode} e
  * @returns {AmbiElement}
  */
const $ = (s, e = document) => e.querySelector(s)

/**
  * @param {String} s
  * @param {ParentNode} e
  * @returns {Array<AmbiElement>}
  */
const $$ = (s, e = document) => Array.from(e.querySelectorAll(s))

I tried giving all of Claude, Grok2, and GPT similar prompts to that and some other code samples, but they just hallucinated magic methods that work the way I expect, and other overly simplistic snippets that didn't do anything useful. 🤷‍♂️

I've never published a type definition before, but if you can help me figure out what the type definition is, I'll have no problem publishing it.

[fregante]

You don’t have to use JSDoc at all. Install select-dom and steal the whole index.d.ts file. Drop the parts you don’t need and ship in your npm package. Typescript will find those types and use them.

[coolaj86]

mkdir -p ./delete-me/
pushd ./delete-me/
npm init -y
npm install --save select-dom
cat node_modules/select-dom/index.d.ts

./node_modules/select-dom/index.d.ts:

/**
 * MIT License
 * Copyright (c) Federico Brigante Federico Brigante <[email protected]> (https://fregante.com)
 * Copyright (c) 2014 Azer Koçulu <[email protected]>
 */

import type { ParseSelector } from 'typed-query-selector/parser.js';

type BaseElements = ParentNode | Iterable<ParentNode>;

/**
 * @param selectors      One or more CSS selectors separated by commas
 * @param [baseElement]  The element to look inside of
 * @return               The element found, if any
 */
declare function $<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElement?: ParentNode): Selected | undefined;
declare function $<Selected extends Element = HTMLElement>(selectors: string | string[], baseElement?: ParentNode): Selected | undefined;

export declare class ElementNotFoundError extends Error {
    name: string;
}

/**
 * @param selectors      One or more CSS selectors separated by commas
 * @param [baseElement]  The element to look inside of
 * @return               The element found, or an error
 */
declare function expectElement<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElement?: ParentNode): Selected;
declare function expectElement<Selected extends Element = HTMLElement>(selectors: string | string[], baseElement?: ParentNode): Selected;

/**
 * @param selectors      One or more CSS selectors separated by commas
 * @param [baseElement]  The element to look inside of
 * @return               The element found, if any
 */
declare function lastElement<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElement?: ParentNode): Selected | undefined;
declare function lastElement<Selected extends Element = HTMLElement>(selectors: string | string[], baseElement?: ParentNode): Selected | undefined;

/**
 * @param selectors      One or more CSS selectors separated by commas
 * @param [baseElement]  The element to look inside of
 * @return               Whether it's been found
 */
declare function elementExists(selectors: string | string[], baseElement?: ParentNode): boolean;

/**
 * @param selectors       One or more CSS selectors separated by commas
 * @param [baseElements]  The element or list of elements to look inside of
 * @return                An array of elements found
 */
declare function $$<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElements?: BaseElements): Selected[];
declare function $$<Selected extends Element = HTMLElement>(selectors: string | string[], baseElements?: BaseElements): Selected[];

export { $, $$, lastElement, elementExists, expectElement };