@standard-library/q-prime

q'

A tiny library to be used with browserify (or webpack) that returns arrays rather than NodeLists from DOM queries and allows for composable queries.

Adapted from the original q by artcommacode, extracting optional parameters into additional functions.

Installation

npm install @standard-library/q-prime --save
# or
yarn add @standard-library/q-prime

Usage

q' wraps querySelectorAll into four exported functions; query, which returns arrays rather than NodeLists and queryOne, which returns a single element. Two additional functions queryChildren and queryChild allow scoping to a parent element.

import { query, queryOne, queryChildren, queryChild } from '@standard-library/q-prime'

query('ul li')
// => [ <li>...</li>, <li>...</li>, <li>...</li> ]

query('ul li')[0].textContent
// => $1

queryOne('ul li')
// => <li>...</li>

queryOne('ul li') === query('ul li')[0]
// => true

You can compose queries with queryChildren or queryChild, by passing an element as the first argument:

const ul = queryOne('ul')
queryChildren(ul, 'li')
// => [ <li>...</li>, <li>...</li>, <li>...</li> ]

query will return an empty array if no elements are found and queryOne will return undefined:

query('ul div')
// => []

queryOne('ul div')
// => undefined

q will throw an error if you try to run a query on an element that doesn't exist:

const li = 'not_an_element'
queryChildren(li, 'div')
// => Error: "not_an_element" does't exist in the document

Tiny

q is only 29 lines short, small enough to fit in this README:

type ParentElement = Document | HTMLElement;

const toArray = (list) => [].slice.call(list)

const first = <T>(xs: T[]): T => xs[0]

const elemError = (e: ParentElement): void => {
  throw new Error(`"${String(e)}" does\'t exist in the document`)
}

const getRoot = (e: ParentElement): ?ParentElement => {
  if (e === document) return e
  return document && document.body && document.body.contains(e) ? e : elemError(e)
}

export const queryChildren = (e: ParentElement, q: string): HTMLElement[] => {
  const root = getRoot(e)
  return root ? toArray(root.querySelectorAll(q)) : []
}

export const queryChild = (e: ParentElement, q: string): ?HTMLElement => {
  return first(queryChildren(e, q))
}

export const query = (q: string): HTMLElement[] => {
  return queryChildren(document, q)
}

export const queryOne = (q: string): ?HTMLElement => queryChild(document, q)

A couple things to note here:

1. I'm using flow for static type checking.
2. q' doesn't shim querySelectorAll and as such is meant for modern (post IE7 or post IE8 if you're using CSS 3 selectors) browsers.

Tests

$ npm install && npm test

This will open a tab in your browser to run tests against test/index.html with the results displayed in your terminal. If you see # ok then it all went well, if there are any errors please submit an issue.