Add improved docs

Author: wooorm

index.js

@@ -8,11 +8,14 @@ import {visit} from 'unist-util-visit'
 const own = {}.hasOwnProperty
 
 /**
+ * Find definitions in `node`.
+ * Uses CommonMark precedence, which means that earlier definitions are
+ * preferred over duplicate later definitions.
  *
  * @param {Node} node
  */
 export function definitions(node) {
-  /** @type {Object.<string, Definition>} */
+  /** @type {Record<string, Definition>} */
   const cache = Object.create(null)
 
   if (!node || !node.type) {
@@ -26,15 +29,15 @@ export function definitions(node) {
     }
   })
 
-  return getDefinition
+  return definition
 
   /**
-   * Get a node from the bound definition-cache.
+   * Get a node from the bound definition cache.
    *
    * @param {string} identifier
    * @returns {Definition|null}
    */
-  function getDefinition(identifier) {
+  function definition(identifier) {
     const id = clean(identifier)
     return id && own.call(cache, id) ? cache[id] : null
   }

readme.md

@@ -8,28 +8,64 @@
 [![Backers][backers-badge]][collective]
 [![Chat][chat-badge]][chat]
 
-[**mdast**][mdast] utility to get definitions by `identifier`.
+[mdast][] utility to find definitions by `identifier`.
 
-Supports funky keys, like `__proto__` or `toString`.
+## Contents
 
-## Install
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`definitions(node)`](#definitionsnode)
+    *   [`definition(identifier)`](#definitionidentifier)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
 
-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.
+This package is a tiny utility that lets you find definitions.
 
-[npm][]:
+## When should I use this?
+
+This utility can be useful because definitions can occur after the things that
+reference them.
+It’s small and protects against prototype pollution.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
 
 ```sh
 npm install mdast-util-definitions
 ```
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {definitions} from 'https://esm.sh/mdast-util-definitions@5'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {definitions} from 'https://esm.sh/mdast-util-definitions@5?bundle'
+</script>
+```
+
 ## Use
 
 ```js
-import {remark} from 'remark'
+import {fromMarkdown} from 'mdast-util-from-markdown'
 import {definitions} from 'mdast-util-definitions'
 
-const tree = remark().parse('[example]: https://example.com "Example"')
+const tree = fromMarkdown('[example]: https://example.com "Example"')
 
 const definition = definitions(tree)
 
@@ -42,35 +78,43 @@ definition('foo')
 
 ## API
 
-This package exports the following identifiers: `definitions`.
+This package exports the identifier `definitions`.
 There is no default export.
 
-### `definitions(tree)`
+### `definitions(node)`
 
-Create a cache of all [definition][]s in [`tree`][node].
-
-Uses CommonMark precedence: prefers the first definitions for duplicate
-definitions.
+Find [definition][]s in `node` ([`Node`][node]).
+Uses CommonMark precedence, which means that earlier definitions are preferred
+over duplicate later definitions.
 
 ###### Returns
 
-[`Function`][fn-definition]
+`definition` ([`Function`][fn-definition]).
 
 ### `definition(identifier)`
 
-###### Parameters
-
-*   `identifier` (`string`) — [Identifier][] of [definition][].
+Get a node from the bound definition cache by its `identifier` (`string`).
 
 ###### Returns
 
-[`Node?`][node] — [Definition][], if found.
+[Definition][], if found ([`Node?`][node])
 
-## Security
+## Types
+
+This package is fully typed with [TypeScript][].
+There are no additional exported types.
+
+## 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+, and 16.0+.
+Our projects sometimes work with older versions, but this is not guaranteed.
 
-Use of `mdast-util-definitions` does not involve [**hast**][hast] or user
-content so there are no openings for [cross-site scripting (XSS)][xss] attacks.
+## Security
 
+Use of `mdast-util-definitions` does not involve **[hast][]** or user content so
+there are no openings for [cross-site scripting (XSS)][xss] attacks.
 Additionally, safe guards are in place to protect against prototype poisoning.
 
 ## Related
@@ -80,8 +124,8 @@ Additionally, safe guards are in place to protect against prototype poisoning.
 
 ## 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].
@@ -126,11 +170,19 @@ abide by its terms.
 
 [npm]: https://docs.npmjs.com/cli/install
 
-[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
 
-[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
+[health]: https://github.com/syntax-tree/.github
 
-[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
+[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.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
 
 [mdast]: https://github.com/syntax-tree/mdast
 
@@ -140,8 +192,6 @@ abide by its terms.
 
 [definition]: https://github.com/syntax-tree/mdast#definition
 
-[identifier]: https://github.com/syntax-tree/mdast#association
-
 [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
 
 [hast]: https://github.com/syntax-tree/hast