FontoXPath

The annotation process improves evaluation efficiency through Early Returns.

When types are known via annotation, FontoXPath can skip expensive runtime type checks. For example, binary and unary operators can skip type checking if the operand types are already known. If the annotated type is more general than what the operator requires, the system performs type narrowing; otherwise, it falls back to original dynamic type inference.

Currently optimized aspects include:

• Binary Operator
• Unary Operator
• Value Compare
• General Compare
• Node Compare

For performance-critical applications, you can compile a subset of XPath 3.1 into pure JavaScript. This can be 2 to 7 times faster than standard evaluation.

Workflow:

1. Use compileXPathToJavaScript to generate a compiled object.
2. Check if isAstAccepted is true (not all XPaths are supported for JS codegen).
3. If accepted, create a function using new Function(compiledResult.code).
4. Execute the function using executeJavaScriptCompiledXPath.

import { compileXPathToJavaScript, executeJavaScriptCompiledXPath } from 'fontoxpath';

const compiledXPathResult = compileXPathToJavaScript('/child::p/text()', evaluateXPath.BOOLEAN_TYPE);

if (compiledXPathResult.isAstAccepted) {
	const evalFunction = new Function(compiledXPathResult.code) as CompiledXPathFunction;
	const result = executeJavaScriptCompiledXPath(evalFunction, documentNode);
}

FontoXPath provides a profiler API to monitor the execution speed of your queries.

1. Provide a performance implementation (e.g., window.performance).
2. Start profiling with profiler.startProfiling().
3. Retrieve a summary using profiler.getPerformanceSummary(), which returns an array of XPaths with their execution times and runtimes.

import { profiler } from 'fontoxpath';

profiler.setPerformanceImplementation(window.performance);
profiler.startProfiling();

const summary = profiler.getPerformanceSummary();

To see a trace of where an XPath evaluation failed, set the debug: true option in the options object. This provides a line-by-line trace of the error location in the expression. Additionally, you can use the fn:trace function within your XPath/XQuery to output information to the developer console.

evaluateXPathToBoolean('...', null, null, null, { debug: true });

When passing JavaScript values as variables to an XPath expression, you can use createTypedValueFactory to ensure they are treated as specific XDM types (like xs:integer). Without this, plain JavaScript numbers are automatically converted to xs:double, which might cause type-check failures in your XPath (e.g., instance of xs:integer would return false).

const integerValueFactory = createTypedValueFactory('xs:integer');
const integerValue = integerValueFactory(123, domFacade);

evaluateXPathToBoolean('$value instance of xs:integer', null, null, {
	value: integerValue,
});

To test the type inference system using the qt3 test suite, run the tests with the --annotate flag. This ensures all XPath queries undergo the annotation step at the start of execution.

# Example command to run tests with annotation enabled
# (Note: exact command depends on your local test runner setup)
# The flag to pass to the test suite is:
--annotate

An EvaluableExpression is the input selector for evaluateXPath. It can be one of two types:

1. A string: A standard XPath or XQuery expression (e.g., //item/text()).
2. An Element: An element representing the root of an XQueryX DOM tree. These can be created manually or via a parseScript function.

You can identify queries that failed to be fully annotated by enabling the logUnannotatedQueries flag in the Options object.

When enabled, FontoXPath checks if a query was completely annotated at the end of its execution. If not, it logs the query to console.error. You can capture these errors by redirecting stderr to a file.

Example command to capture unannotated query logs:

npm run test 2> output.txt

To perform updates (insert, replace, delete) on XML, use evaluateUpdatingExpressionSync.

This function returns an object containing:

• xdmValue: The result of the query.
• pendingUpdateList: An array of update primitives.

To apply these changes to your DOM, you must pass the pendingUpdateList to executePendingUpdateList.

const { evaluateUpdatingExpressionSync, executePendingUpdateList } = require('fontoxpath');

const result = evaluateUpdatingExpressionSync('replace node /xml with <foo/>', documentNode);
executePendingUpdateList(result.pendingUpdateList, domFacade, nodesFactory, documentWriter);