Lookup following object (in tree order)

Author: Joris-van-der-Wel

lib/SymbolTree.js

@@ -141,6 +141,40 @@ module.exports = class SymbolTree {
                 return this._node(object).parent;
         }
 
+        /**
+         * Find the following object (A) of the given object (B).
+         * An object A is following an object B if A and B are in the same tree
+         * and A comes after B in tree order.
+         * @method following
+         * @param {!Object} object
+         * @param {Object} [treeRoot] If set, `treeRoot` must be an inclusive ancestor
+         *        of the return value (or else null is returned). This check _assumes_
+         *        that `root` is also an inclusive ancestor of the given `node`
+         * @returns {?Object}
+         */
+        following(object, treeRoot) {
+                if (this._node(object).first) {
+                        return this._node(object).first;
+                }
+
+                do {
+                        if (object === treeRoot) {
+                                return null;
+                        }
+
+                        if (this._node(object).next) {
+                                return this._node(object).next;
+                        }
+
+                        object = this._node(object).parent;
+                        // https://github.com/jscs-dev/node-jscs/commit/07d30b77388a2e182a40b00891c7ac1837281016
+                        // jscs:disable requirePaddingNewlinesBeforeKeywords
+                } while (object);
+                // jscs:enable requirePaddingNewlinesBeforeKeywords
+
+                return null;
+        }
+
         /**
          * Remove the object from this tree.
          * `O(1)`

test/SymbolTree.js

@@ -503,3 +503,79 @@ test('look up preceding using a specified root', function(t) {
 
         t.end();
 });
+
+test('following with a child', function(t) {
+        const tree = new SymbolTree();
+        const a = {};
+        const aa = {};
+
+        tree.insertLast(aa, a);
+
+        t.equal(aa  , tree.following(a));
+        t.equal(null, tree.following(aa));
+
+        t.end();
+});
+
+test('following with a next sibling', function(t) {
+        const tree = new SymbolTree();
+        const a = {};
+        const b = {};
+
+        tree.insertAfter(b, a);
+
+        t.equal(b   , tree.following(a));
+        t.equal(null, tree.following(b));
+
+        t.end();
+});
+
+test('following with sibling of parent', function(t) {
+        const tree = new SymbolTree();
+        const a = {};
+        const aa = {};
+        const b = {};
+
+        tree.insertLast(aa, a);
+        tree.insertAfter(b, a);
+
+        t.equal(b, tree.following(aa));
+
+        t.end();
+});
+
+test('following with sibling of grandparent', function(t) {
+        const tree = new SymbolTree();
+        const a = {};
+        const aa = {};
+        const aaa = {};
+        const b = {};
+
+        tree.insertLast(aa, a);
+        tree.insertLast(aaa, aa);
+        tree.insertAfter(b, a);
+
+        t.equal(b, tree.following(aaa));
+
+        t.end();
+});
+
+test('following using a specified root', function(t) {
+        const tree = new SymbolTree();
+        const a = {};
+        const aa = {};
+        const aaa = {};
+        const b = {};
+
+        tree.insertLast(aa, a);
+        tree.insertLast(aaa, aa);
+        tree.insertAfter(b, a);
+
+        t.equal(null, tree.following(aaa, aaa));
+        t.equal(null, tree.following(aaa, aa));
+        t.equal(null, tree.following(aaa, a));
+        t.equal(aa  , tree.following(a, a));
+        t.equal(aaa , tree.following(aa, a));
+
+        t.end();
+});