Skip to content
This repository has been archived by the owner on Oct 21, 2021. It is now read-only.

1.0.2
Compare
Choose a tag to compare
@koddsson koddsson released this 06 Aug 14:39
1.0.2
ba14d58
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

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.

Assets 3
Loading