diff --git a/lib/index.js b/lib/index.js index 84d86e3..384cef0 100644 --- a/lib/index.js +++ b/lib/index.js @@ -17,13 +17,29 @@ const cache = new WeakMap() /** - * Add parent references to a proxy of `tree`. + * Create a proxy of `tree` that acts like the original tree upon reading, but + * each proxied node has a reference to its parent node. + * + * ###### Notes + * + * The returned proxy imposes two additional fields on all of its nodes: + * + * * `parent` β€” parent link (or `null` for the root) + * * `node` β€” link to the original node + * + * These new fields are not enumerable and the original tree is *not changed*. + * This means you can use `JSON.stringify` on the wrapped tree and it’s the + * same. + * + * `wrapped.children` returns array of wrapped child nodes, so that any + * recursive algorithm will work on a wrapped tree just as well. + * + * To write changes to the tree, use `.node` to access the original tree. * * @param {Node} tree - * Create a proxy of `node` that acts like the original tree upon reading, but - * each proxied node has a reference to its parent node. + * Tree to proxy. * @returns {Proxy} - * Proxy of `node`. + * Proxy of `tree`. */ export function parents(tree) { return wrapNode(tree, null) diff --git a/readme.md b/readme.md index e072cbf..6a028ec 100644 --- a/readme.md +++ b/readme.md @@ -17,7 +17,7 @@ * [Install](#install) * [Use](#use) * [API](#api) - * [`parents(node)`](#parentsnode) + * [`parents(tree)`](#parentstree) * [Types](#types) * [Compatibility](#compatibility) * [Related](#related) @@ -40,7 +40,7 @@ tree with [`unist-util-visit-parents`][unist-util-visit-parents]. ## Install This package is [ESM only][esm]. -In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with [npm][]: +In Node.js (version 14.14+ and 16.0+), install with [npm][]: ```sh npm install unist-util-parents @@ -49,14 +49,14 @@ npm install unist-util-parents In Deno with [`esm.sh`][esmsh]: ```js -import {parent} from "https://esm.sh/unist-util-parents@2" +import {parent} from 'https://esm.sh/unist-util-parents@2' ``` In browsers with [`esm.sh`][esmsh]: ```html ``` @@ -102,13 +102,15 @@ Yields: ## API -This package exports the identifier `parents`. +This package exports the identifier [`parents`][parents]. There is no default export. -### `parents(node)` +### `parents(tree)` -Create a proxy of `node` ([`Node`][node]) that acts like the original tree upon -reading, but each proxied node has a reference to its parent node. +Create a proxy of `tree` that acts like the original tree upon reading, but +each proxied node has a reference to its parent node. + +###### Notes The returned proxy imposes two additional fields on all of its nodes: @@ -123,11 +125,14 @@ algorithm will work on a wrapped tree just as well. To write changes to the tree, use `.node` to access the original tree. +###### Parameters + +* `tree` ([`Node`][node]) + β€” tree to proxy + ###### Returns -A wrapped node ([`Node`][node]), which is a shallow copy of the given node that -also includes non-enumerable references to `node` and `parent`, and if `tree` -had children, they are wrapped as well. +Proxy of `tree` (`Proxy`). ## Types @@ -138,7 +143,7 @@ It exports the additional type `Proxy`. 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+. +As of now, that is Node.js 14.14+ and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed. ## Related @@ -211,3 +216,5 @@ abide by its terms. [node]: https://github.com/syntax-tree/unist#node [unist-util-visit-parents]: https://github.com/syntax-tree/unist-util-visit-parents + +[parents]: #parentstree