Extract query-selector package

Author: dgraham

.flowconfig

@@ -0,0 +1,9 @@
+[ignore]
+
+[include]
+
+[libs]
+
+[options]
+
+[lints]

.gitignore

@@ -0,0 +1,2 @@
+dist
+node_modules

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2018 GitHub, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,41 @@
+# A typed querySelector function for Flow
+
+## Installation
+
+```
+$ npm install @github/query-selector
+```
+
+## Usage
+
+```js
+import {closest, getAttribute, 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
+
+// Retrieve the attribute's value or throw.
+const url: string = getAttribute(image, 'data-url')
+
+// Filter all children by selector and type.
+const inputs: Array<HTMLInputElement> = querySelectorAll(document, 'input', HTMLInputElement)
+for (const input of inputs) {
+  input.value = ''
+}
+```
+
+## Development
+
+```
+npm install
+npm test
+```
+
+## License
+
+Distributed under the MIT license. See LICENSE for details.

index.js

@@ -0,0 +1,49 @@
+/* @flow strict */
+
+type Queryable = Document | DocumentFragment | Element
+
+export function closest<T: Element>(element: Element, selectors: string, type: Class<T>): T {
+  const klass = type || HTMLElement
+  const el = element.closest(selectors)
+  if (el instanceof klass) {
+    return el
+  }
+  throw new Error(`Element not found: <${klass.name}> ${selectors}`)
+}
+
+export function query<T: Element>(context: Queryable, selectors: string, type: Class<T>): T {
+  const klass = type || HTMLElement
+  const el = context.querySelector(selectors)
+  if (el instanceof klass) {
+    return el
+  }
+  throw new Error(`Element not found: <${klass.name}> ${selectors}`)
+}
+
+export function querySelectorAll<T: Element>(context: Queryable, selectors: string, type: Class<T>): Array<T> {
+  const klass = type || HTMLElement
+  const els: Array<T> = []
+  for (const el of context.querySelectorAll(selectors)) {
+    if (el instanceof klass) {
+      els.push(el)
+    }
+  }
+  return els
+}
+
+export function namedItem<T: HTMLElement>(form: HTMLFormElement, itemName: string, type: Class<T>): T {
+  const klass = type || HTMLInputElement
+  const el = form.elements.namedItem(itemName)
+  if (el instanceof klass) {
+    return el
+  }
+  throw new Error(`Element not found by name: <${klass.name}> ${itemName}`)
+}
+
+export function getAttribute(element: Element, attributeName: string): string {
+  const attribute = element.getAttribute(attributeName)
+  if (attribute != null) {
+    return attribute
+  }
+  throw new Error(`Attribute not found on element: ${attributeName}`)
+}

index.js.flow

@@ -0,0 +1,13 @@
+/* @flow strict */
+
+type Queryable = Document | DocumentFragment | Element;
+
+declare export function closest(context: Queryable, selectors: string): HTMLElement;
+declare export function closest<T: Element>(context: Queryable, selectors: string, klass: Class<T>): T;
+declare export function query(context: Queryable, selectors: string): HTMLElement;
+declare export function query<T: Element>(context: Queryable, selectors: string, klass: Class<T>): T;
+declare export function querySelectorAll(context: Queryable, selectors: string): Array<HTMLElement>;
+declare export function querySelectorAll<T: Element>(context: Queryable, selectors: string, klass: Class<T>): Array<T>;
+declare export function namedItem(form: HTMLFormElement, itemName: string): HTMLInputElement;
+declare export function namedItem<T: HTMLElement>(form: HTMLFormElement, itemName: string, klass: Class<T>): T;
+declare export function getAttribute(element: Element, attributeName: string): string;