upgrade descendants and nodesBetween handlers to support aborting a graph scan

[st3v0]

Context

We need the ability to end the recursive scan (part way through the graph) which is performed by descendants and nodesBetween.

At the moment if we return false from the node handler; the scan continues to the next sibling in the graph. This is wasteful if there is a large amount of siblings and all we're trying to do is check if a node exists.

Proposed Solution

We could modify the nodesBetween node handler method to support more than returning boolean | void. If anything else is returned then the scan stops and returns that item.

This is a performance improvement solution with the added benefit of being able to use it for finding.

Checklist

Is this solution backwards compatible: ✅
Does this solution include tests: ❌

Examples

Say you want to get a text node from somewhere in the doc, which contains the text 'foobar', you could;

const node = doc.descendants((node) => node.isText && node.text === 'foobar' ? node : true);

Or you want to get the type of the first leaf node;

const type = doc.descendants((node) => node.isLeaf ? node.type : true);

[marijnh]

What I've been doing is just setting a flag (or storing a non-null result) when the search has finished, and putting a check for that at the top of the callback, making it return false right away. That seems to cover the cases where this is necessary with less complication.