Note on mutation

This is a doc suggestion + a more general question.

It may be worth putting in the docs some thoughts on what the contract is wrt mutating the tree. In particular, modifying individual nodes is fine, but unist-util-visit assumes the visitor does not mutate the number of children of the parent.

This is a bit of a pitfall, as it’s not uncommon to want to traverse and mutate adjacent children. For example, see https://github.com/jackycute/remark-html-emoji-image/blob/master/index.js#L66-L69 — but it appears that approach is buggy, since unist-util-visit visits children sequentially by index.

More generally, I’d be interested to know what approach is best to handle the fully mutating use case. https://github.com/syntax-tree/unist-util-map and https://github.com/eush77/unist-util-filter are listed but cover different use cases. One easy option (but may not be the best) is to make a visit-dynamic variant, something like:

'use strict';

module.exports = visit;

/**
 * A mutating version of https://github.com/syntax-tree/unist-util-visit
 *
 * Traverse a Unist tree, while also allowing addition/deletion of children.
 * Visitor should return number of nodes added/deleted (positive for addition, negative for removal,
 * 0 if only visited), or false to terminate. To avoid confusion, we don't support reverse traversal.
 */
function visit(tree, type, visitor) {
  if (typeof type === 'function') {
    visitor = type;
    type = null;
  }

  one(tree);

  /* Visit a single node. */
  function one(node, index, parent) {
    let result;

    index = index || (parent ? 0 : null);

    if (!type || node.type === type) {
      result = visitor(node, index, parent || null);
    }

    if (node.children && result !== false) {
      all(node);
    }

    return result;
  }

  /* Visit children in `parent`, possibly adding or removing children. */
  function all(parent) {
    let child;
    let index = 0;
    while (index < parent.children.length) {
      child = parent.children[index];

      let delta = 0;
      if (child) {
        delta = one(child, index, parent);
        if (delta === false) {  // Abort.
          return;
        }
      }

      index += 1 + (delta || 0);
    }
  }
}

[wooorm]

Sweet, thanks! I added you to the org, so feel free to create a utility here and we’ll help maintain it!

How much code would it add in this utility to have this added here though, without breaking current things?

[jlevy]

Hey @wooorm ! Cool, thanks for the response. Well, good to hear my understanding matches yours. 😃

We ended up using visit-dynamic variant I put above, and it’s been working fine for our use cases. I’m not sure if I’ll have bandwidth to publish/maintain it myself right now — perhaps we can set it up under syntax-tree as an alternative to this visitor, if you think it’s useful? You’re welcome to the code above!

Also just PR’ed a doc clarification.