Add improved docs

Author: wooorm

index.js

@@ -4,26 +4,24 @@
  * @typedef {import('hast').Element} Element
  *
  * @typedef {string} TagName
+ *
  * @typedef {null|undefined|TagName|TestFunctionAnything|Array<TagName|TestFunctionAnything>} Test
- */
-
-/**
- * @template {Element} T
- * @typedef {null|undefined|T['tagName']|TestFunctionPredicate<T>|Array<T['tagName']|TestFunctionPredicate<T>>} PredicateTest
- */
-
-/**
- * Check if an element passes a test
  *
  * @callback TestFunctionAnything
+ *   Check if an element passes a test.
  * @param {Element} element
  * @param {number|null|undefined} [index]
  * @param {Parent|null|undefined} [parent]
  * @returns {boolean|void}
  */
 
 /**
- * Check if an element passes a certain node test
+ * @template {Element} T
+ * @typedef {null|undefined|T['tagName']|TestFunctionPredicate<T>|Array<T['tagName']|TestFunctionPredicate<T>>} PredicateTest
+ */
+
+/**
+ * Check if an element passes a certain node test.
  *
  * @template {Element} X
  * @callback TestFunctionPredicate

readme.md

@@ -8,20 +8,61 @@
 [![Backers][backers-badge]][collective]
 [![Chat][chat-badge]][chat]
 
-[**hast**][hast] utility to check if a [*node*][node] is a (certain)
-[*element*][element].
+[hast][] utility to check if a node is a (certain) element.
 
-## Install
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`isElement(node[, test[, index, parent[, context]]])`](#iselementnode-test-index-parent-context)
+    *   [`convertElement(test)`](#convertelementtest)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
+
+This package is a small utility that checks that a node is a certain element.
+
+## When should I use this?
+
+Use this small utility if you find yourself repeating code for checking what
+elements nodes are.
+
+A similar package, [`unist-util-is`][unist-util-is], works on any unist node.
+
+For more advanced tests, [`hast-util-select`][hast-util-select] can be used
+to match against CSS selectors.
 
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
-Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
+## Install
 
-[npm][]:
+This package is [ESM only][esm].
+In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with [npm][]:
 
 ```sh
 npm install hast-util-is-element
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {isElement} from 'https://esm.sh/hast-util-is-element@2'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {isElement} from 'https://esm.sh/hast-util-is-element@2?bundle'
+</script>
+```
+
 ## Use
 
 ```js
@@ -36,46 +77,45 @@ isElement({type: 'element', tagName: 'a'}, ['a', 'area']) // => true
 
 ## API
 
-This package exports the following identifiers: `isElement`, `convertElement`.
+This package exports the identifiers `isElement` and `convertElement`.
 There is no default export.
 
 ### `isElement(node[, test[, index, parent[, context]]])`
 
 Check if the given value is a (certain) [*element*][element].
 
-*   `node` ([`Node`][node]) — Node to check.
+###### Parameters
+
+*   `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 `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
+*   `index` (`number`, optional) — [index][] of `node` in `parent`
+*   `parent` ([`Node`][node], optional) — [parent][] of `node`
+*   `context` (`*`, optional) — context object to call `test` with
 
 ###### Returns
 
-`boolean` — Whether `test` passed *and* `node` is an [`Element`][element].
+Whether `test` passed *and* `node` is an [`Element`][element] (`boolean`)
 
 ###### Throws
 
-`Error` — When an incorrect `test`, `index`, or `parent` is given.
+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
 
-*   `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`.
+*   `this` — the to `is` given `context` (`*`)
+*   `element` ([`Element`][element]) — element to check
+*   `index` (`number?`) — [index][] of `node` in `parent`
+*   `parent` ([`Node?`][node]) — [parent][] of `node`
 
 ###### Returns
 
-`boolean?` — Whether `element` matches.
+Whether `element` matches (`boolean?`).
 
 ### `convertElement(test)`
 
@@ -87,6 +127,31 @@ 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.
 
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional types:
+
+*   `TestFunctionAnything`
+    — models any test function
+*   `TestFunctionPredicate<T>` (where `T` extends `Element`)
+    — models a test function for `T`
+*   `Test`
+    — models any arbitrary test that can be given
+*   `PredicateTest<T>` (where `T` extends `Element`)
+    — models a test for `T`
+*   `AssertAnything`
+    — models a check function as returned by `convertElement`
+*   `AssertPredicate<T>` (where `T` extends `Element`)
+    — models a check function for `T` as returned by `convertElement`
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with all maintained
+versions of Node.js.
+As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
+Our projects sometimes work with older versions, but this is not guaranteed.
+
 ## Security
 
 `hast-util-is-element` does not change the syntax tree so there are no openings
@@ -96,21 +161,21 @@ for [cross-site scripting (XSS)][xss] attacks.
 
 *   [`hast-util-has-property`](https://github.com/syntax-tree/hast-util-has-property)
     — check if a node has a property
-*   [`hast-util-is-body-ok-link`](https://github.com/rehypejs/rehype-minify/tree/HEAD/packages/hast-util-is-body-ok-link)
+*   [`hast-util-is-body-ok-link`](https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-is-body-ok-link)
     — check if a node is “Body OK” link element
-*   [`hast-util-is-conditional-comment`](https://github.com/rehypejs/rehype-minify/tree/HEAD/packages/hast-util-is-conditional-comment)
+*   [`hast-util-is-conditional-comment`](https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-is-conditional-comment)
     — check if a node is a conditional comment
-*   [`hast-util-is-css-link`](https://github.com/rehypejs/rehype-minify/tree/HEAD/packages/hast-util-is-css-link)
+*   [`hast-util-is-css-link`](https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-is-css-link)
     — check if a node is a CSS link element
-*   [`hast-util-is-css-style`](https://github.com/rehypejs/rehype-minify/tree/HEAD/packages/hast-util-is-css-style)
+*   [`hast-util-is-css-style`](https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-is-css-style)
     — check if a node is a CSS style element
 *   [`hast-util-embedded`](https://github.com/syntax-tree/hast-util-embedded)
     — check if a node is an embedded element
 *   [`hast-util-heading`](https://github.com/syntax-tree/hast-util-heading)
     — check if a node is a heading element
 *   [`hast-util-interactive`](https://github.com/syntax-tree/hast-util-interactive)
     — check if a node is interactive
-*   [`hast-util-is-javascript`](https://github.com/rehypejs/rehype-minify/tree/HEAD/packages/hast-util-is-javascript)
+*   [`hast-util-is-javascript`](https://github.com/rehypejs/rehype-minify/tree/main/packages/hast-util-is-javascript)
     — check if a node is a JavaScript script element
 *   [`hast-util-labelable`](https://github.com/syntax-tree/hast-util-labelable)
     — check whether a node is labelable
@@ -127,8 +192,8 @@ for [cross-site scripting (XSS)][xss] attacks.
 
 ## Contribute
 
-See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
-started.
+See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
+ways to get started.
 See [`support.md`][support] for ways to get help.
 
 This project has a [code of conduct][coc].
@@ -169,15 +234,23 @@ abide by its terms.
 
 [npm]: https://docs.npmjs.com/cli/install
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
+
 [license]: license
 
 [author]: https://wooorm.com
 
-[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
+[health]: https://github.com/syntax-tree/.github
 
-[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
+[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
 
-[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
+[support]: https://github.com/syntax-tree/.github/blob/main/support.md
+
+[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
 
 [hast]: https://github.com/syntax-tree/hast
 
@@ -192,3 +265,7 @@ abide by its terms.
 [test]: #function-testelement-index-parent
 
 [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
+
+[unist-util-is]: https://github.com/syntax-tree/unist-util-is
+
+[hast-util-select]: https://github.com/syntax-tree/hast-util-select