cvm/src/packages/tree-filter-flat-async/index.js

"use strict";

const isIterable = require("is-iterable");
const mapAsync = require("../map-async");

const Omitted = Symbol("Omitted");

async function testValue(value, predicate) {
	return (await predicate(value))
		? value
		: Omitted;
}

module.exports = async function treeFilterFlatAsync(tree, filter, options = {}) {
	let key = options.key ?? "children";
	let recurseFilteredSubtrees = options.recurseFilteredSubtrees ?? false;
	let concurrent = options.concurrent ?? true;
	let depthFirst = options.depthFirst ?? false; // NOTE: Only affects output order, not evaluation order

	let results = [];

	async function step(subtree) {
		// NOTE: The reason that we're tracking promises rather than outcomes, is because we want to make sure that (in breadth-first mode) we *immediately* push it into the results array, before the first async yield point. This is to ensure that the output is always in a consistent breadth-first order, even if the evaluation itself (being async) is out-of-order. This array of promises is resolved and post-processed at the end.
		// TODO: Consider rewriting this so that the step function *returns* a (correctly-ordered) array instead; however, this would require possibly a lot of array concatenations, which may negatively impact performance
		let resultPromise = await testValue(subtree, filter);

		if (!depthFirst) {
			results.push(resultPromise);
		}

		if (recurseFilteredSubtrees || (await resultPromise) !== Omitted) {
			if (isIterable(subtree[key])) {
				await mapAsync(subtree[key], step, { concurrent: concurrent });
			} else if (subtree[key] != null && typeof subtree[key] === "object") {
				await step(subtree[key]);
			}
		}

		if (depthFirst) {
			results.push(resultPromise);
		}

		return resultPromise;
	}

	if (isIterable(tree)) {
		await mapAsync(tree, step, { concurrent: concurrent });
	} else {
		await step(tree);
	}

	return results.filter((value) => value !== Omitted);
};