Add improved jsdoc

index.js

@@ -2,38 +2,47 @@
  * @typedef {import('unist').Parent} Parent
  * @typedef {import('unist').Node} Node
  *
- * @typedef {Node} Proxy
- * @property {parent|null} parent
+ * @typedef ProxyFields
+ * @property {Parent|null} parent
+ * Parent link (or `null` for the root).
+ * @property {Node} node
+ * Link to the original node
+ *
+ * @typedef {Node & ProxyFields} Proxy
+ * Proxied node
  */
 
 /** @type {WeakMap<Node, Proxy>} */
-var cache = new WeakMap()
+const cache = new WeakMap()
 
 /**
- * @param {Node} tree
+ * @param {Node} node
+ * Create a proxy of `node` that acts like the original tree upon reading, but
+ * each proxied node has a reference to its parent node.
  * @returns {Proxy}
+ * Proxy of `node`.
  */
-export function parents(tree) {
- return wrapNode(tree, null)
+export function parents(node) {
+ return wrapNode(node, null)
 }
 
 /**
  * @param {Node} node
+ * Node to wrap.
  * @param {Parent|null} parent
+ * Parent of `node`.
  * @returns {Proxy}
+ * Proxy of `node`.
  */
 function wrapNode(node, parent) {
- /** @type {Node} */
- var proxy
- /** @type {string} */
- var key
-
  if (cache.has(node)) {
  return cache.get(node)
  }
 
- // @ts-ignore Assume `node` is a valid node.
- proxy = {}
+ /** @type {Proxy} */
+ const proxy = {}
+ /** @type {string} */
+ let key
 
  for (key in node) {
  if (key !== 'children') {
@@ -65,19 +74,27 @@ function wrapNode(node, parent) {
 
  return proxy
 
+ /**
+ * Get the `parent` reference of a proxied node.
+ */
  function getParent() {
  return parent
  }
 
  /**
+ * Set the `parent` reference of a proxied node.
+ *
  * @param {Parent} newParent
  */
  function setParent(newParent) {
  parent = newParent
  }
 
+ /**
+ * Get the wrapped children of a proxied node.
+ */
  function getChildren() {
- // @ts-ignore `node` is a parent.
+ // @ts-expect-error `node` is a parent.
  return node.children.map((/** @type {Node} */ c) => wrapNode(c, proxy))
  }
 }

package.json

@@ -71,9 +71,7 @@
  "xo": {
  "prettier": true,
  "rules": {
- "capitalized-comments": "off",
- "no-var": "off",
- "prefer-arrow-callback": "off"
+ "capitalized-comments": "off"
  }
  },
  "remarkConfig": {

test.js

@@ -7,7 +7,7 @@ import test from 'tape'
 import clone from 'clone'
 import {parents} from './index.js'
 
-var ast = {
+const ast = {
  type: 'root',
  children: [
  {
@@ -23,8 +23,8 @@ var ast = {
 }
 
 test('immutable', function (t) {
- var original = clone(ast)
- var root = parents(ast)
+ const original = clone(ast)
+ const root = parents(ast)
 
  t.deepEqual(ast, original, 'original AST is unchanged')
  t.notEqual(root, ast, 'returns a different object')
@@ -39,15 +39,13 @@ test('immutable', function (t) {
 })
 
 test('parent links', function (t) {
- var root = parents(clone(ast))
- /** @type {Parent} */ // @ts-expect-error: hush.
- var heading = root.children[0]
- /** @type {Parent} */ // @ts-expect-error: hush.
- var cogito = heading.children[0]
- /** @type {Parent} */ // @ts-expect-error: hush.
- var emphasis = heading.children[1]
- var ergo = emphasis.children[0]
- var sum = heading.children[2]
+ const root = parents(clone(ast))
+ // @ts-expect-error: hush
+ const heading = /** @type {Parent} */ (root.children[0])
+ const cogito = /** @type {Parent} */ (heading.children[0])
+ const emphasis = /** @type {Parent} */ (heading.children[1])
+ const ergo = emphasis.children[0]
+ const sum = heading.children[2]
 
  // @ts-expect-error: custom.
  t.equal(ergo.parent, emphasis, 'ergo.parent === emphasis')
@@ -59,7 +57,6 @@ test('parent links', function (t) {
  t.equal(sum.parent, heading, 'sum.parent === heading')
  // @ts-expect-error: custom.
  t.equal(heading.parent, root, 'heading.parent === root')
- // @ts-expect-error: custom.
  t.false(root.parent, 'root has no parent')
 
  t.equal(Object.keys(sum).indexOf('parent'), -1, 'not enumerable')
@@ -73,10 +70,10 @@ test('parent links', function (t) {
 })
 
 test('node links', function (t) {
- var root = parents(ast)
+ const root = parents(ast)
  /** @type {Parent} */ // @ts-expect-error: hush.
- var heading = root.children[0]
- var headingNode = ast.children[0]
+ const heading = root.children[0]
+ const headingNode = ast.children[0]
 
  // @ts-expect-error: custom.
  t.equal(heading.node, headingNode)