Add convert, support for functions as tests

Related-to syntax-tree/hast-util-find-and-replace#1.
Related-to syntax-tree/hast-util-find-and-replace#2.

Author: wooorm

convert.js

@@ -0,0 +1,82 @@
+'use strict'
+
+module.exports = convert
+
+function convert(test) {
+  if (typeof test === 'string') {
+    return tagNameFactory(test)
+  }
+
+  if (test === null || test === undefined) {
+    return element
+  }
+
+  if (typeof test === 'object') {
+    return any(test)
+  }
+
+  if (typeof test === 'function') {
+    return callFactory(test)
+  }
+
+  throw new Error('Expected function, string, or array as test')
+}
+
+function convertAll(tests) {
+  var length = tests.length
+  var index = -1
+  var results = []
+
+  while (++index < length) {
+    results[index] = convert(tests[index])
+  }
+
+  return results
+}
+
+function any(tests) {
+  var checks = convertAll(tests)
+  var length = checks.length
+
+  return matches
+
+  function matches() {
+    var index = -1
+
+    while (++index < length) {
+      if (checks[index].apply(this, arguments)) {
+        return true
+      }
+    }
+
+    return false
+  }
+}
+
+// Utility to convert a string a tag name check.
+function tagNameFactory(test) {
+  return tagName
+
+  function tagName(node) {
+    return element(node) && node.tagName === test
+  }
+}
+
+// Utility to convert a function check.
+function callFactory(test) {
+  return call
+
+  function call(node) {
+    return element(node) && Boolean(test.apply(this, arguments))
+  }
+}
+
+// Utility to return true if this is an element.
+function element(node) {
+  return (
+    node &&
+    typeof node === 'object' &&
+    node.type === 'element' &&
+    typeof node.tagName === 'string'
+  )
+}

index.js

@@ -1,45 +1,35 @@
 'use strict'
 
+var convert = require('./convert')
+
 module.exports = isElement
 
-// Check if if `node` is an `element` and, if `tagNames` is given, `node`
-// matches them `tagNames`.
-function isElement(node, tagNames) {
-  var name
+isElement.convert = convert
 
-  if (
-    !(
-      tagNames === null ||
-      tagNames === undefined ||
-      typeof tagNames === 'string' ||
-      (typeof tagNames === 'object' && tagNames.length !== 0)
-    )
-  ) {
-    throw new Error(
-      'Expected `string` or `Array.<string>` for `tagNames`, not `' +
-        tagNames +
-        '`'
-    )
-  }
+// Check if if `node` is an `element` and whether it passes the given test.
+function isElement(node, test, index, parent, context) {
+  var hasParent = parent !== null && parent !== undefined
+  var hasIndex = index !== null && index !== undefined
+  var check = convert(test)
 
   if (
-    !node ||
-    typeof node !== 'object' ||
-    node.type !== 'element' ||
-    typeof node.tagName !== 'string'
+    hasIndex &&
+    (typeof index !== 'number' || index < 0 || index === Infinity)
   ) {
-    return false
+    throw new Error('Expected positive finite index for child node')
   }
 
-  if (tagNames === null || tagNames === undefined) {
-    return true
+  if (hasParent && (!parent.type || !parent.children)) {
+    throw new Error('Expected parent node')
   }
 
-  name = node.tagName
+  if (!node || !node.type || typeof node.type !== 'string') {
+    return false
+  }
 
-  if (typeof tagNames === 'string') {
-    return name === tagNames
+  if (hasParent !== hasIndex) {
+    throw new Error('Expected both parent and index')
   }
 
-  return tagNames.indexOf(name) !== -1
+  return check.call(context, node, index, parent)
 }

package.json

@@ -24,6 +24,7 @@
     "Titus Wormer <[email protected]> (https://wooorm.com)"
   ],
   "files": [
+    "convert.js",
     "index.js"
   ],
   "dependencies": {},
@@ -58,7 +59,9 @@
     "prettier": true,
     "esnext": false,
     "rules": {
-      "unicorn/prefer-includes": "off"
+      "max-params": "off",
+      "unicorn/prefer-includes": "off",
+      "unicorn/prefer-reflect-apply": "off"
     },
     "ignores": [
       "hast-util-is-element.js"

readme.md

@@ -33,30 +33,55 @@ is({type: 'element', tagName: 'a'}, ['a', 'area']) // => true
 
 ## API
 
-### `isElement(node[, tagName|tagNames])`
+### `isElement(node[, test[, index, parent[, context]]])`
 
 Check if the given value is a (certain) [*element*][element].
 
-*   When given a `tagName` or `tagNames`, checks that `node` is an
-    [*element*][element] whose `tagName` field matches `tagName` or is included
-    in `tagNames`
-*   Otherwise checks that `node` is an [*element*][element]
+*   `node` ([`Node`][node]) — Node to check.
+*   `test` ([`Function`][test], `string`, or `Array.<Test>`, optional)
+    — When `array`, checks if any one of the subtests pass.
+    When `string`, checks that the element has that tag name.
+    When `function`, see [`test`][test]
+*   `index` (`number`, optional) — [Index][] of `node` in `parent`
+*   `parent` ([`Node`][node], optional) — [Parent][] of `node`
+*   `context` (`*`, optional) — Context object to invoke `test` with
+
+###### Returns
+
+`boolean` — Whether `test` passed *and* `node` is an [`Element`][element].
+
+###### Throws
+
+`Error` — When an incorrect `test`, `index`, or `parent` is given.
+A `node` that is not a node, or not an element, does not throw.
+
+#### `function test(element[, index, parent])`
 
 ###### Parameters
 
-*   `node` (`*`) — Value to check, probably [`Node`][node]
-*   `tagName` (`string`, optional) — Value that `node`s `tagName` field should
-    match
-*   `tagNames` (`Array.<string>`, optional) — Values that should include `node`s
-    `tagName` field should match
+*   `element` ([`Element`][element]) — Element to check
+*   `index` (`number?`) — [Index][] of `node` in `parent`
+*   `parent` ([`Node?`][node]) — [Parent][] of `node`
+
+###### Context
+
+`*` — The to `is` given `context`.
 
 ###### Returns
 
-`boolean` — whether `node` passes the test.
+`boolean?` — Whether `element` matches.
 
-###### Throws
+### `isElement.convert(test)`
+
+Create a test function from `test`, that can later be called with a `node`,
+`index`, and `parent`.
+Useful if you’re going to test many nodes, for example when creating a utility
+where something else passes a compatible test.
+
+The created function is slightly faster because it expects valid input only.
+Therefore, passing invalid input, yields unexpected results.
 
-`Error` — When the second parameter is given but invalid.
+Can also be accessed with `require('hast-util-is-element/convert')`.
 
 ## Security
 
@@ -156,4 +181,10 @@ abide by its terms.
 
 [element]: https://github.com/syntax-tree/hast#element
 
+[parent]: https://github.com/syntax-tree/unist#parent-1
+
+[index]: https://github.com/syntax-tree/unist#index
+
+[test]: #function-testelement-index-parent
+
 [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

test.js

@@ -11,7 +11,7 @@ test('isElement', function (t) {
     function () {
       isElement(null, true)
     },
-    'Expected `string` or `Array.<string>` for `tagNames`, not `true`',
+    /Expected function, string, or array as test/,
     'should throw when the second parameter is invalid'
   )
 
@@ -99,5 +99,115 @@ test('isElement', function (t) {
     st.end()
   })
 
+  t.test('isElement(node, test)', function (st) {
+    st.equal(
+      isElement({type: 'text'}, function () {
+        throw new Error('!')
+      }),
+      false,
+      'should not call `test` if the given node is not an element'
+    )
+
+    st.equal(
+      isElement({type: 'element', tagName: 'a', children: []}, function (node) {
+        return node.children.length === 0
+      }),
+      true,
+      'should call `test` if the given node is a valid element (1)'
+    )
+
+    st.equal(
+      isElement(
+        {type: 'element', tagName: 'a', children: [{type: 'text'}]},
+        function (node) {
+          return node.children.length === 0
+        }
+      ),
+      false,
+      'should call `test` if the given node is a valid element (2)'
+    )
+
+    var ctx = {}
+    var root = {
+      type: 'root',
+      children: [{type: 'element', tagName: 'a', children: []}]
+    }
+
+    st.equal(
+      isElement(
+        root.children[0],
+        function (node, index, parent) {
+          st.equal(node, root.children[0], 'should pass `node` to test')
+          st.equal(index, 0, 'should pass `index` to test')
+          st.equal(parent, root, 'should pass `parent` to test')
+          st.equal(this, ctx, 'should pass `context` to test')
+        },
+        0,
+        root,
+        ctx
+      ),
+      false,
+      'should call `test` if the given node is a valid element (2)'
+    )
+
+    st.throws(
+      function () {
+        isElement(root.children[0], function () {}, 0)
+      },
+      /Expected both parent and index/,
+      'should throw if `index` is passed but not `parent`'
+    )
+
+    st.throws(
+      function () {
+        isElement(root.children[0], function () {}, undefined, root)
+      },
+      /Expected both parent and index/,
+      'should throw if `parent` is passed but not `index`'
+    )
+
+    st.throws(
+      function () {
+        isElement(root.children[0], function () {}, false)
+      },
+      /Expected positive finite index for child node/,
+      'should throw if `index` is not a number'
+    )
+
+    st.throws(
+      function () {
+        isElement(root.children[0], function () {}, -1)
+      },
+      /Expected positive finite index for child node/,
+      'should throw if `index` is negative'
+    )
+
+    st.throws(
+      function () {
+        isElement(root.children[0], function () {}, Infinity)
+      },
+      /Expected positive finite index for child node/,
+      'should throw if `index` is infinity'
+    )
+
+    st.throws(
+      function () {
+        isElement(root.children[0], function () {}, 0, true)
+      },
+      /Expected parent node/,
+      'should throw if `parent` is not a node'
+    )
+
+    st.throws(
+      function () {
+        isElement(root.children[0], function () {}, 0, {type: 'root'})
+      },
+      /Expected parent node/,
+      'should throw if `parent` is not a parent'
+    )
+
+    st.end()
+  })
+
   t.end()
 })