Refactor code-style

Author: wooorm

index.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('./lib/types.js').Space} Space
+ * @typedef {import('./lib/index.js').Space} Space
  */
 
 export {matches, select, selectAll} from './lib/index.js'

lib/attribute.js

@@ -1,14 +1,16 @@
 /**
- * @typedef {import('css-selector-parser').AstRule} AstRule
  * @typedef {import('css-selector-parser').AstAttribute} AstAttribute
+ * @typedef {import('css-selector-parser').AstRule} AstRule
+ *
  * @typedef {import('hast').Element} Element
  * @typedef {import('hast').Properties} Properties
- * @typedef {import('property-information').Schema} Schema
+ *
  * @typedef {import('property-information').Info} Info
+ * @typedef {import('property-information').Schema} Schema
  */
 
 import {stringify as commas} from 'comma-separated-tokens'
-import {ok as assert} from 'devlop'
+import {ok as assert, unreachable} from 'devlop'
 import {hasProperty} from 'hast-util-has-property'
 import {find} from 'property-information'
 import {stringify as spaces} from 'space-separated-tokens'
@@ -17,23 +19,27 @@ import {zwitch} from 'zwitch'
 /** @type {(query: AstAttribute, element: Element, info: Info) => boolean} */
 const handle = zwitch('operator', {
   unknown: unknownOperator,
-  // @ts-expect-error: hush.
+  // @ts-expect-error: `exists` is fine.
   invalid: exists,
   handlers: {
     '=': exact,
-    '~=': spaceSeparatedList,
-    '|=': exactOrPrefix,
-    '^=': begins,
     '$=': ends,
-    '*=': contains
+    '*=': contains,
+    '^=': begins,
+    '|=': exactOrPrefix,
+    '~=': spaceSeparatedList
   }
 })
 
 /**
  * @param {AstRule} query
+ *   Query.
  * @param {Element} element
+ *   Element.
  * @param {Schema} schema
+ *   Schema of element.
  * @returns {boolean}
+ *   Whether `element` matches `query`.
  */
 export function attribute(query, element, schema) {
   let index = -1
@@ -52,187 +58,165 @@ export function attribute(query, element, schema) {
 }
 
 /**
- * Check whether an attribute exists.
- *
- * `[attr]`
- *
- * @param {AstAttribute} _
- * @param {Element} element
- * @param {Info} info
- * @returns {boolean}
- */
-function exists(_, element, info) {
-  return hasProperty(element, info.property)
-}
-
-/**
- * Check whether an attribute has an exact value.
+ * Check whether an attribute has a substring as its start.
  *
- * `[attr=value]`
+ * `[attr^=value]`
  *
  * @param {AstAttribute} query
+ *   Query.
  * @param {Element} element
+ *   Element.
  * @param {Info} info
+ *   Property info.
  * @returns {boolean}
+ *   Whether `element` matches `query`.
  */
-function exact(query, element, info) {
+function begins(query, element, info) {
   assert(query.value, 'expected `value`')
   assert(query.value.type === 'String', 'expected plain string')
 
   return Boolean(
     hasProperty(element, info.property) &&
-      element.properties &&
-      normalizeValue(element.properties[info.property], info) ===
-        query.value.value
+      normalizeValue(element.properties[info.property], info).slice(
+        0,
+        query.value.value.length
+      ) === query.value.value
   )
 }
 
 /**
- * Check whether an attribute, interpreted as a space-separated list, contains
- * a value.
+ * Check whether an attribute contains a substring.
  *
- * `[attr~=value]`
+ * `[attr*=value]`
  *
  * @param {AstAttribute} query
+ *   Query.
  * @param {Element} element
+ *   Element.
  * @param {Info} info
+ *   Property info.
  * @returns {boolean}
+ *   Whether `element` matches `query`.
  */
-function spaceSeparatedList(query, element, info) {
+function contains(query, element, info) {
   assert(query.value, 'expected `value`')
   assert(query.value.type === 'String', 'expected plain string')
 
-  const value = element.properties && element.properties[info.property]
-
-  return (
-    // If this is a space-separated list, and the query is contained in it, return
-    // true.
-    (!info.commaSeparated &&
-      value &&
-      typeof value === 'object' &&
-      value.includes(query.value.value)) ||
-    // For all other values (including comma-separated lists), return whether this
-    // is an exact match.
-    (hasProperty(element, info.property) &&
-      normalizeValue(value, info) === query.value.value)
+  return Boolean(
+    hasProperty(element, info.property) &&
+      normalizeValue(element.properties[info.property], info).includes(
+        query.value.value
+      )
   )
 }
 
 /**
- * Check whether an attribute has a substring as either the exact value or a
- * prefix.
+ * Check whether an attribute has a substring as its end.
  *
- * `[attr|=value]`
+ * `[attr$=value]`
  *
  * @param {AstAttribute} query
+ *   Query.
  * @param {Element} element
+ *   Element.
  * @param {Info} info
+ *   Property info.
  * @returns {boolean}
+ *   Whether `element` matches `query`.
  */
-function exactOrPrefix(query, element, info) {
+function ends(query, element, info) {
   assert(query.value, 'expected `value`')
   assert(query.value.type === 'String', 'expected plain string')
 
-  const value = normalizeValue(
-    element.properties && element.properties[info.property],
-    info
-  )
-
   return Boolean(
     hasProperty(element, info.property) &&
-      (value === query.value.value ||
-        (value.slice(0, query.value.value.length) === query.value.value &&
-          value.charAt(query.value.value.length) === '-'))
+      normalizeValue(element.properties[info.property], info).slice(
+        -query.value.value.length
+      ) === query.value.value
   )
 }
 
 /**
- * Check whether an attribute has a substring as its start.
+ * Check whether an attribute has an exact value.
  *
- * `[attr^=value]`
+ * `[attr=value]`
  *
  * @param {AstAttribute} query
+ *   Query.
  * @param {Element} element
+ *   Element.
  * @param {Info} info
+ *   Property info.
  * @returns {boolean}
+ *   Whether `element` matches `query`.
  */
-function begins(query, element, info) {
+function exact(query, element, info) {
   assert(query.value, 'expected `value`')
   assert(query.value.type === 'String', 'expected plain string')
 
   return Boolean(
     hasProperty(element, info.property) &&
-      element.properties &&
-      normalizeValue(element.properties[info.property], info).slice(
-        0,
-        query.value.value.length
-      ) === query.value.value
+      normalizeValue(element.properties[info.property], info) ===
+        query.value.value
   )
 }
 
 /**
- * Check whether an attribute has a substring as its end.
+ * Check whether an attribute has a substring as either the exact value or a
+ * prefix.
  *
- * `[attr$=value]`
+ * `[attr|=value]`
  *
  * @param {AstAttribute} query
+ *   Query.
  * @param {Element} element
+ *   Element.
  * @param {Info} info
+ *   Property info.
  * @returns {boolean}
+ *   Whether `element` matches `query`.
  */
-function ends(query, element, info) {
+function exactOrPrefix(query, element, info) {
   assert(query.value, 'expected `value`')
   assert(query.value.type === 'String', 'expected plain string')
 
+  const value = normalizeValue(element.properties[info.property], info)
+
   return Boolean(
     hasProperty(element, info.property) &&
-      element.properties &&
-      normalizeValue(element.properties[info.property], info).slice(
-        -query.value.value.length
-      ) === query.value.value
+      (value === query.value.value ||
+        (value.slice(0, query.value.value.length) === query.value.value &&
+          value.charAt(query.value.value.length) === '-'))
   )
 }
 
 /**
- * Check whether an attribute contains a substring.
+ * Check whether an attribute exists.
  *
- * `[attr*=value]`
+ * `[attr]`
  *
- * @param {AstAttribute} query
+ * @param {AstAttribute} _
+ *   Query.
  * @param {Element} element
+ *   Element.
  * @param {Info} info
+ *   Property info.
  * @returns {boolean}
+ *   Whether `element` matches `query`.
  */
-function contains(query, element, info) {
-  assert(query.value, 'expected `value`')
-  assert(query.value.type === 'String', 'expected plain string')
-
-  return Boolean(
-    hasProperty(element, info.property) &&
-      element.properties &&
-      normalizeValue(element.properties[info.property], info).includes(
-        query.value.value
-      )
-  )
-}
-
-// Shouldn’t be called, Parser throws an error instead.
-/**
- * @param {unknown} query
- * @returns {never}
- */
-/* c8 ignore next 4 */
-function unknownOperator(query) {
-  // @ts-expect-error: `operator` guaranteed.
-  throw new Error('Unknown operator `' + query.operator + '`')
+function exists(_, element, info) {
+  return hasProperty(element, info.property)
 }
 
 /**
  * Stringify a hast value back to its HTML form.
  *
  * @param {Properties[keyof Properties]} value
+ *   hast property value.
  * @param {Info} info
+ *   Property info.
  * @returns {string}
+ *   Normalized value.
  */
 function normalizeValue(value, info) {
   if (typeof value === 'boolean') {
@@ -245,3 +229,54 @@ function normalizeValue(value, info) {
 
   return String(value)
 }
+
+/**
+ * Check whether an attribute, interpreted as a space-separated list, contains
+ * a value.
+ *
+ * `[attr~=value]`
+ *
+ * @param {AstAttribute} query
+ *   Query.
+ * @param {Element} element
+ *   Element.
+ * @param {Info} info
+ *   Property info.
+ * @returns {boolean}
+ *   Whether `element` matches `query`.
+ */
+function spaceSeparatedList(query, element, info) {
+  assert(query.value, 'expected `value`')
+  assert(query.value.type === 'String', 'expected plain string')
+
+  const value = element.properties[info.property]
+
+  return (
+    // If this is a space-separated list, and the query is contained in it, return
+    // true.
+    (!info.commaSeparated &&
+      value &&
+      typeof value === 'object' &&
+      value.includes(query.value.value)) ||
+    // For all other values (including comma-separated lists), return whether this
+    // is an exact match.
+    (hasProperty(element, info.property) &&
+      normalizeValue(value, info) === query.value.value)
+  )
+}
+
+// Shouldn’t be called, Parser throws an error instead.
+/**
+ * @param {unknown} query_
+ *   Query.
+ * @returns {never}
+ *   Nothing.
+ * @throws {Error}
+ *   Error.
+ */
+/* c8 ignore next 5 */
+function unknownOperator(query_) {
+  // Runtime guarantees `operator` exists.
+  const query = /** @type {AstAttribute} */ (query_)
+  unreachable('Unknown operator `' + query.operator + '`')
+}

lib/class-name.js

@@ -3,20 +3,24 @@
  * @typedef {import('hast').Element} Element
  */
 
-// Make VS Code see references to the above types.
-''
+/** @type {Array<never>} */
+const emptyClassNames = []
 
 /**
  * Check whether an element has all class names.
  *
  * @param {AstRule} query
+ *   AST rule (with `classNames`).
  * @param {Element} element
+ *   Element.
  * @returns {boolean}
+ *   Whether `element` matches `query`.
  */
 export function className(query, element) {
-  /** @type {Readonly<Array<string>>} */
-  // @ts-expect-error Assume array.
-  const value = element.properties.className || []
+  // Assume array.
+  const value = /** @type {Readonly<Array<string>>} */ (
+    element.properties.className || emptyClassNames
+  )
   let index = -1
 
   if (query.classNames) {