Add support for null as input in types

Author: wooorm

index.js

@@ -17,16 +17,20 @@ import {parse} from './lib/parse.js'
  *
  * @param {string} selector
  *   CSS selector, such as (`h1`, `a, b`).
- * @param {Node|undefined} [node]
+ * @param {Node | null | undefined} [node]
  *   Node that might match `selector`, should be an element.
- * @param {Space|undefined} [space='html']
+ * @param {Space | null | undefined} [space='html']
  *   Name of namespace (`'svg'` or `'html'`).
  * @returns {boolean}
  *   Whether `node` matches `selector`.
  */
 export function matches(selector, node, space) {
   return Boolean(
-    any(parse(selector), node, {space, one: true, shallow: true})[0]
+    any(parse(selector), node || undefined, {
+      space: space || undefined,
+      one: true,
+      shallow: true
+    })[0]
   )
 }
 
@@ -36,17 +40,23 @@ export function matches(selector, node, space) {
  *
  * @param {string} selector
  *   CSS selector, such as (`h1`, `a, b`).
- * @param {Node|undefined} [tree]
+ * @param {Node | null | undefined} [tree]
  *   Tree to search.
- * @param {Space|undefined} [space='html']
+ * @param {Space | null | undefined} [space='html']
  *   Name of namespace (`'svg'` or `'html'`).
  * @returns {Element|null}
  *   First element in `tree` that matches `selector` or `null` if nothing is
  *   found.
  *   This could be `tree` itself.
  */
 export function select(selector, tree, space) {
-  return any(parse(selector), tree, {space, one: true})[0] || null
+  // To do in major: return `undefined` instead.
+  return (
+    any(parse(selector), tree || undefined, {
+      space: space || undefined,
+      one: true
+    })[0] || null
+  )
 }
 
 /**
@@ -55,14 +65,14 @@ export function select(selector, tree, space) {
  *
  * @param {string} selector
  *   CSS selector, such as (`h1`, `a, b`).
- * @param {Node|undefined} [tree]
+ * @param {Node | null | undefined} [tree]
  *   Tree to search.
- * @param {Space|undefined} [space='html']
+ * @param {Space | null | undefined} [space='html']
  *   Name of namespace (`'svg'` or `'html'`).
  * @returns {Array<Element>}
  *   Elements in `tree` that match `selector`.
  *   This could include `tree` itself.
  */
 export function selectAll(selector, tree, space) {
-  return any(parse(selector), tree, {space})
+  return any(parse(selector), tree || undefined, {space: space || undefined})
 }

lib/any.js

@@ -76,7 +76,7 @@ function rule(query, tree, state) {
     query,
     tree,
     0,
-    null,
+    undefined,
     configure(query, {
       // @ts-expect-error assume elements.
       scopeElements: tree.type === 'root' ? tree.children : [tree],

lib/enter-state.js

@@ -112,7 +112,7 @@ export function enterState(state, node) {
   function inferDirectionality(child) {
     if (child.type === 'text') {
       dirInferred = dirBidi(child.value)
-      return dirInferred ? EXIT : null
+      return dirInferred ? EXIT : undefined
     }
 
     if (

lib/nest.js

@@ -14,7 +14,7 @@ import {parent, element} from './util.js'
 
 const own = {}.hasOwnProperty
 
-/** @type {(query: Rule, node: Node, index: number|null, parent: Parent|null, state: SelectState) => void} */
+/** @type {(query: Rule, node: Node, index: number | undefined, parent: Parent | undefined, state: SelectState) => void} */
 const handle = zwitch('nestingOperator', {
   unknown: unknownNesting,
   // @ts-expect-error: hush.
@@ -47,7 +47,7 @@ function unknownNesting(query) {
 function topScan(query, node, index, parent, state) {
   // Shouldn’t happen.
   /* c8 ignore next 3 */
-  if (parent || index === null) {
+  if (parent || index === undefined) {
     throw new Error('topScan is supposed to be called from the root node')
   }
 
@@ -97,15 +97,15 @@ function child(query, node, _1, _2, state) {
 function adjacentSibling(query, _, index, parent, state) {
   // Shouldn’t happen.
   /* c8 ignore next */
-  if (!parent || index === null) return
+  if (!parent || index === undefined) return
   indexedSearch(query, parent, state, index + 1, true)
 }
 
 /** @type {Handler} */
 function generalSibling(query, _, index, parent, state) {
   // Shouldn’t happen.
   /* c8 ignore next */
-  if (!parent || index === null) return
+  if (!parent || index === undefined) return
   indexedSearch(query, parent, state, index + 1)
 }
 
@@ -129,7 +129,7 @@ function indexedSearch(query, parent, state, from, firstElementOnly) {
   const delayed = []
 
   // Start looking at `from`
-  if (from === undefined || from === null) from = 0
+  if (from === undefined || from === undefined) from = 0
 
   // Exit if there are no further nodes.
   if (from >= children.length) return

lib/pseudo.js

@@ -19,7 +19,7 @@ import {whitespace} from 'hast-util-whitespace'
 import {zwitch} from 'zwitch'
 import {any} from './any.js'
 
-/** @type {(rule: Rule|RulePseudo, element: Element, index: number|null, parent: Parent|null, state: SelectState) => boolean} */
+/** @type {(rule: Rule|RulePseudo, element: Element, index: number | undefined, parent: Parent | undefined, state: SelectState) => boolean} */
 const handle = zwitch('name', {
   unknown: unknownPseudo,
   invalid: invalidPseudo,
@@ -74,8 +74,8 @@ pseudo.needsIndex = [
 /**
  * @param {Rule} query
  * @param {Element} element
- * @param {number|null} index
- * @param {Parent|null} parent
+ * @param {number|undefined} index
+ * @param {Parent|undefined} parent
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -93,8 +93,8 @@ export function pseudo(query, element, index, parent, state) {
 /**
  * @param {RulePseudoSelector} query
  * @param {Element} element
- * @param {number|null} _
- * @param {Parent|null} parent
+ * @param {number|undefined} _
+ * @param {Parent|undefined} parent
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -116,8 +116,8 @@ function matches(query, element, _, parent, state) {
 /**
  * @param {RulePseudoSelector} query
  * @param {Element} element
- * @param {number|null} index
- * @param {Parent|null} parent
+ * @param {number|undefined} index
+ * @param {Parent|undefined} parent
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -161,8 +161,8 @@ function checked(_, element) {
 /**
  * @param {RulePseudo} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -223,8 +223,8 @@ function optional(query, element) {
 /**
  * @param {RulePseudo} _
  * @param {Element} element
- * @param {number|null} _1
- * @param {Parent|null} _2
+ * @param {number|undefined} _1
+ * @param {Parent|undefined} _2
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -237,8 +237,8 @@ function readWrite(_, element, _1, _2, state) {
 /**
  * @param {RulePseudo} query
  * @param {Element} element
- * @param {number|null} index
- * @param {Parent|null} parent
+ * @param {number|undefined} index
+ * @param {Parent|undefined} parent
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -249,8 +249,8 @@ function readOnly(query, element, index, parent, state) {
 /**
  * @param {RulePseudo} _
  * @param {Element} element
- * @param {number|null} _1
- * @param {Parent|null} parent
+ * @param {number|undefined} _1
+ * @param {Parent|undefined} parent
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -266,8 +266,8 @@ function root(_, element, _1, parent, state) {
 /**
  * @param {RulePseudo} _
  * @param {Element} element
- * @param {number|null} _1
- * @param {Parent|null} _2
+ * @param {number|undefined} _1
+ * @param {Parent|undefined} _2
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -318,8 +318,8 @@ function blank(_, element) {
 /**
  * @param {RulePseudo} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -331,16 +331,16 @@ function firstChild(query, _1, _2, _3, state) {
 /**
  * @param {RulePseudo} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
 function lang(query, _1, _2, _3, state) {
   return (
     state.language !== '' &&
     state.language !== undefined &&
-    state.language !== null &&
+    state.language !== undefined &&
     // @ts-expect-error never `selectors`.
     extendedFilter(state.language, commas(query.value)).length > 0
   )
@@ -349,8 +349,8 @@ function lang(query, _1, _2, _3, state) {
 /**
  * @param {RulePseudo} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -364,8 +364,8 @@ function lastChild(query, _1, _2, _3, state) {
 /**
  * @param {RulePseudo} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -377,8 +377,8 @@ function onlyChild(query, _1, _2, _3, state) {
 /**
  * @param {RulePseudoNth} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -392,8 +392,8 @@ function nthChild(query, _1, _2, _3, state) {
 /**
  * @param {RulePseudoNth} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -409,8 +409,8 @@ function nthLastChild(query, _1, _2, _3, state) {
 /**
  * @param {RulePseudoNth} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -422,8 +422,8 @@ function nthOfType(query, _1, _2, _3, state) {
 /**
  * @param {RulePseudoNth} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -439,8 +439,8 @@ function nthLastOfType(query, _1, _2, _3, state) {
 /**
  * @param {RulePseudo} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -452,8 +452,8 @@ function firstOfType(query, _1, _2, _3, state) {
 /**
  * @param {RulePseudo} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -469,8 +469,8 @@ function lastOfType(query, _1, _2, _3, state) {
 /**
  * @param {RulePseudo} query
  * @param {Element} _1
- * @param {number|null} _2
- * @param {Parent|null} _3
+ * @param {number|undefined} _2
+ * @param {Parent|undefined} _3
  * @param {SelectState} state
  * @returns {boolean}
  */
@@ -528,8 +528,8 @@ function assertDeep(state, query) {
 /**
  * @param {RulePseudoSelector} query
  * @param {Element} element
- * @param {number|null} _1
- * @param {Parent|null} _2
+ * @param {number|undefined} _1
+ * @param {Parent|undefined} _2
  * @param {SelectState} state
  * @returns {boolean}
  */

lib/test.js

@@ -15,8 +15,8 @@ import {element} from './util.js'
 /**
  * @param {Rule} query
  * @param {Node} node
- * @param {number|null} index
- * @param {Parent|null} parent
+ * @param {number|undefined} index
+ * @param {Parent|undefined} parent
  * @param {SelectState} state
  * @returns {boolean}
  */

lib/types.js

@@ -69,13 +69,13 @@
  * @param {Rule} query
  * @param {Node} node
  * @param {number} index
- * @param {Parent|null} parent
+ * @param {Parent|undefined} parent
  * @param {SelectState} state
  */
 
 /**
  * @typedef {(
- *  ((query: Rule, node: Node, index: number|null, parent: Parent|null, state: SelectState) => void)
+ *  ((query: Rule, node: Node, index: number | undefined, parent: Parent | undefined, state: SelectState) => void)
  * )} Handler
  */