Releases: github/query-selector
1.0.4
v1.0.3
v1.0.2
1.0.2
A typed querySelector function
Query the document tree by selector, filtering by element type.
Installation
$ npm install @github/query-selector
Usage
This library provides a set of functions to query the document tree with a
standard selector paired with an additional type filter applied to the result.
An element must match the selector as well as the type for it to be returned.
query(context, selector, klass)querySelectorAll(context, selector, klass)closest(element, selector, klass)namedItem(element, name, klass)getAttribute(element, name)
import {closest, getAttribute, namedItem, query, querySelectorAll} from '@github/query-selector'
// Find an element by selector and type, or throw if not found.
const image: HTMLImageElement = query(document, '.avatar', HTMLImageElement)
image.src = '/hubot.png'
// Find the parent by selector and type, or throw if not found.
const parent: HTMLDetailsElement = closest(image, '.container', HTMLDetailsElement)
parent.open = true
// Filter all children by selector and type.
const inputs: Array<HTMLInputElement> = querySelectorAll(document, 'input', HTMLInputElement)
for (const input of inputs) {
input.value = ''
}
// Retrieve the attribute's value or throw.
const url: string = getAttribute(image, 'data-url')
// Find the form's `input[name=login]` field or throw if not found.
const form: HTMLFormElement = query(document, 'form', HTMLFormElement)
const input: HTMLInputElement = namedItem(form, 'login')Motivation
Finding an individual element in the document tree and operating on it can
lead to null pointer exceptions.
const el = document.querySelector('.expected-element')
// el may be null!
el.classList.add('selected')
el.setAttribute('title', 'hello')A safer alternative is to guard against null values with a conditional statement.
const el = document.querySelector('.expected-element')
if (el) {
el.classList.add('selected')
el.setAttribute('title', 'hello')
}Even if found, the element may be of the wrong type.
const el = document.querySelector('.expected-element')
if (el) {
// Element might not have a value property!
el.value = 'hello'
}Adding an instanceof test would verify the element has the properties and
methods we expect.
const el = document.querySelector('.expected-element')
if (el instanceof HTMLInputElement) {
el.value = 'hello'
}Because document.querySelector is so frequently used in web applications,
and it's tedious to guard every element query with null checks, these tests
are most often omitted. When using Flow, however, these tests become
required to pass the type checker.
The combination of null tests and subclass type refinements feels like we're
working against the type system, rather than with it. So, typed query functions
consider a missing element, or an element of the wrong type, to be failed
assertions and throw an exception to fail as early as possible.
Development
npm install
npm test
License
Distributed under the MIT license. See LICENSE for details.