raqb/src/ast/optimize/index.js

"use strict";

const util = require("util");
const syncpipe = require("syncpipe");
const debug = require("debug");

const NoChange = require("../../optimizers/util/no-change");
const RemoveNode = require("../../optimizers/util/remove-node");
const unreachable = require("../../unreachable");
const typeOf = require("../../type-of");
const measureTime = require("../../measure-time");

// FIXME: Consider deepcopying the tree once, and then mutating that tree, instead of doing everything immutably; this might be significantly faster when a few iterations are needed to stabilize the tree, as that might otherwise result in many copies of the subtree(s) leeding up to the changed node(s), one for each iteration.
// FIXME: Consider whether inverting the evaluation order (deepest-first rather than shallowest-first) can remove the need for multiple optimization passes and stabilization detection.
// FIXME: Verify that changed nodes actually result in a change in where the walker goes!

function createDebuggers(optimizers) {
	let debuggers = {};

	for (let optimizer of optimizers) {
		debuggers[optimizer.name] = debug(`raqb:ast:optimize:${optimizer.name}`);
	}

	return debuggers;
}

function createTimings(optimizers) {
	let timings = {};

	for (let optimizer of optimizers) {
		timings[optimizer.name] = 0n;
	}

	return timings;
}

function combineOptimizers(optimizers) {
	let allVisitors = {};

	for (let optimizer of optimizers) {
		for (let [ key, visitor ] of Object.entries(optimizer.visitors)) {
			if (allVisitors[key] == null) {
				allVisitors[key] = [];
			}

			allVisitors[key].push({
				name: optimizer.name,
				func: visitor
			});
		}
	}

	return allVisitors;
}

// FIXME: StopMatching marker to signal that eg. a generic visitor should no longer match after a specific one?
// FIXME: OriginalNode marker to explicitly indicate that any transformations applied by *other* visitors should be thrown out?

module.exports = function optimizeTree(ast, optimizers) {
	// NOTE: Depth-first!
	let visitors = combineOptimizers(optimizers);
	let timings = createTimings(optimizers);
	let debuggers = createDebuggers(optimizers);
	// FIXME: Dirty tracking for stabilization detection

	function applyVisitors(node, visitors) {
		if (visitors == null) {
			// We handle this here to make the `handle` pipeline more readable
			return node;
		} else {
			let lastNode = node;

			for (let visitor of visitors) {
				// eslint-disable-next-line no-loop-func
				let { value: result, time } = measureTime(() => {
					return visitor.func(lastNode);
				});

				timings[visitor.name] += time;

				if (result === NoChange) {
					// no-op
				} else if (result == null) {
					throw new Error(`A visitor is not allowed to return null or undefined; if you intended to leave the node untouched, return a NoChange marker instead`);
				} else if (result === RemoveNode) {
					debuggers[visitor.name](`Node of type '${typeOf(lastNode)}' removed`);
					lastNode = RemoveNode;
					break; // Node has gone stale, stop applying visitors to it
				} else if (result.__raqbASTNode === true) {
					// New subtree to replace the old one
					if (result === node) {
						// Visitor returned the original node again; but in this case, it should return NoChange instead. We enforce this because after future changes to the optimizer implementation (eg. using an internally-mutable deep copy of the tree), we may no longer be able to *reliably* detect when the original node is returned; so it's best to already get people into the habit of returning a NoChange marker in those cases, by disallowing this.
						throw new Error(`Visitor returned original node, but this may not work reliably; if you intended to leave the node untouched, return a NoChange marker instead`);
					} else {
						debuggers[visitor.name](`Node of type '${typeOf(lastNode)}' replaced by node of type '${typeOf(result)}'`);
						lastNode = result;
						break; // Node has gone stale, stop applying visitors to it
					}
				} else {
					throw new Error(`Visitor returned an unexpected type of return value: ${util.inspect(result)}`);
				}
			}

			if (lastNode !== node) {
				// We re-evalue the new node before leaving control to the children handler, as the old one has been substituted, and therefore new visitors might be applicable.
				return handleSelf(lastNode);
			} else {
				return lastNode;
			}
		}
	}

	function handleSelf(node) {
		return syncpipe(node, [
			(_) => applyVisitors(_, visitors[_.type]),
			(_) => applyVisitors(_, visitors["*"]),
		]);
	}

	function handleChildren(node) {
		// FIXME: Eventually hardcode the available properties for different node types (and them being single/multiple), for improved performance?
		let changedProperties = {};

		for (let [ property, value ] of Object.entries(node)) {
			if (value == null) {
				continue;
			} else if (value.__raqbASTNode === true) {
				changedProperties[property] = handle(value);
			} else if (Array.isArray(value) && value.length > 0 && value[0].__raqbASTNode === true) {
				// NOTE: We assume that if an array in an AST node property contains one AST node, *all* of its items are AST nodes. This should be ensured by the input wrapping in the operations API.
				changedProperties[property] = value
					.map((item) => handle(item))
					.filter((item) => item !== RemoveNode);
			} else {
				// Probably some kind of literal value; we don't touch these.
				continue;
			}
		}

		if (Object.keys(changedProperties).length === 0) {
			return node;
		} else {
			let newNode = Object.assign({}, node, changedProperties);

			// FIXME: Think carefully about whether there is *ever* a valid reason to remove a single node! As array items are already taken care of above, and leave an empty array at worst, which can make sense. Possibly we even need to encode this data into node type metadata.
			for (let [ key, value ] of Object.entries(newNode)) {
				if (value === RemoveNode) {
					delete newNode[key];
				}
			}

			return newNode;
		}
	}

	function handle(node) {
		// FIXME: Possibly optimize the "node gets returned unchanged" case, somehow? Perhaps by propagating the NoChange marker? But object creation is fast, so that may actually make things slower than just blindly creating new objects...
		return syncpipe(node, [
			(_) => handleSelf(_),
			(_) => handleChildren(_)
		]);
	}

	let { value: rootNode, time } = measureTime(() => {
		return handle(ast);
	});
	
	let timeSpentInOptimizers = Object.values(timings).reduce((sum, n) => sum + n, 0n);

	if (rootNode !== RemoveNode) {
		return {
			ast: rootNode,
			timings: {
				"# Total": time,
				"# Walker overhead": time - timeSpentInOptimizers,
				... timings,
			}
		};
	} else {
		unreachable("Root node was removed");
	}
};