Skip to content

Smaller bundles ​

@exemplarjs/xpath includes the whole XPath 3.1 function library. Functions are looked up by name when an expression is compiled, so a bundler cannot tell which ones are unused, and tree-shaking removes none of them. The lean entry, @exemplarjs/xpath/lean, exports the same compiler with only the core functions; the rest of the library is added in groups that are imported explicitly.

ts
import { 
regexFunctions
} from '@exemplarjs/xpath/groups/regex';
import {
XPathCompiler
} from '@exemplarjs/xpath/lean';
const
compiler
= new
XPathCompiler
({
functions
: [
regexFunctions
] });
const
words
=
compiler
.
compile
('tokenize($text, ",")', {
variables
: ['text'] });
words
.
evaluateStrings
(null, {
variables
: {
text
: 'classic,desert' } }); // ['classic', 'desert']

Import the lean compiler ​

Change the import from @exemplarjs/xpath to @exemplarjs/xpath/lean. Its XPathCompiler takes the same options, compiles the same language and returns the same executables.

ts
import { 
XPathCompiler
} from '@exemplarjs/xpath/lean';
const
compiler
= new
XPathCompiler
();
compiler
.
compile
('//book[price > 10]/title ! upper-case(.)').
evaluateStrings
(
doc
); // ['DUNE', 'COSMOS']
compiler
.
compile
('sum(//price)').
evaluateNumber
(
doc
); // 35.5

With no groups added, it supports the whole language and the core functions:

  • paths, predicates, operators, for, let, if, some and every;
  • maps, arrays, the ? lookup, inline functions and function calls;
  • casts and constructors such as xs:date("2024-01-31"), and arithmetic on the values they make;
  • the functions on strings, numbers, booleans, sequences, nodes, names and URIs, the math: functions, and aggregates such as count, sum and max;
  • the collations.

The rest of the library is divided into nine function groups.

Add function groups ​

Each group is a separate module, so a bundle contains only the groups that are imported. Import the groups that your expressions use and pass them in the compiler's functions option.

ts
import { 
dateTimeFunctions
} from '@exemplarjs/xpath/groups/date-time';
import {
jsonFunctions
} from '@exemplarjs/xpath/groups/json';
import {
XPathCompiler
} from '@exemplarjs/xpath/lean';
const
compiler
= new
XPathCompiler
({
functions
: [
dateTimeFunctions
,
jsonFunctions
] });
GroupImportFunctions
date-timedateTimeFunctions from @exemplarjs/xpath/groups/date-timecurrent-date, current-dateTime, year-from-date and the other component accessors for dates, times and durations, the timezone adjustments, dateTime, implicit-timezone, parse-ietf-date
formattingformattingFunctions from @exemplarjs/xpath/groups/formattingformat-number, format-integer, format-date, format-dateTime, format-time
regexregexFunctions from @exemplarjs/xpath/groups/regexmatches, replace, tokenize, analyze-string
higher-orderhigherOrderFunctions from @exemplarjs/xpath/groups/higher-orderfor-each, filter, fold-left, fold-right, for-each-pair, sort, apply, function-lookup, function-name, function-arity, random-number-generator
mapsmapFunctions from @exemplarjs/xpath/groups/mapsThe map: functions, such as map:merge and map:keys
arraysarrayFunctions from @exemplarjs/xpath/groups/arraysThe array: functions, such as array:size and array:join
jsonjsonFunctions from @exemplarjs/xpath/groups/jsonparse-json, json-to-xml, xml-to-json
resourcesresourceFunctions from @exemplarjs/xpath/groups/resourcesdoc, doc-available, collection, uri-collection, the unparsed-text functions, json-doc, parse-xml, parse-xml-fragment
serializationserializationFunctions from @exemplarjs/xpath/groups/serializationserialize

The XPath functions reference lists every function.

Three cases are easy to miss:

  • Map and array constructors and the ? lookup need no group; only the map: and array: functions do.
  • Date values and date arithmetic are part of the language, so xs:date("2024-01-31") + xs:dayTimeDuration("P1D") works without the date-time group.
  • sort is in the higher-order group, even when it is called with no function.

When a group is missing ​

A call to a function in a group that the compiler lacks fails at compile time, not at evaluation. The error is an XPathException with the code XPST0017, and its description names the group and the import to add:

ts
const 
compiler
= new
XPathCompiler
();
compiler
.
compile
('format-number($n, "#,##0")', {
variables
: ['n'] });
// XPathException: XPST0017: There is no function format-number#2: it is in the formatting group; // add formattingFunctions from @exemplarjs/xpath/groups/formatting to the compiler's functions, // or compile with compileAsync at line 1, column 1

Because the check happens at compile time, a test that compiles each expression once finds every missing group.

Load groups on demand ​

When expressions are not known at build time, or some are rarely used, compileAsync loads groups on demand: it finds the function calls in the expression, imports the groups that the compiler lacks, and then compiles.

ts
const 
compiler
= new
XPathCompiler
();
const
formatted
= await
compiler
.
compileAsync
('format-number($n, "#,##0")', {
variables
: ['n'] });
formatted
.
evaluateString
(null, {
variables
: {
n
: 1234567 } }); // '1,234,567'

Each group is loaded with a dynamic import(), which bundlers emit as a separate chunk fetched on first use. A loaded group stays registered with the compiler, so later calls to compile can use it too.

Only compilation is asynchronous: the returned executable is the same as one from compile, with the same synchronous evaluation methods. compileAsync exists on the lean compiler only, because the full compiler already has every group. The two methods share the compiler's cache of executables.

WARNING

compileAsync detects function calls statically. A function that is looked up by a name computed at run time, with function-lookup, is found only if its group is already loaded. Add such groups in the functions option.

Keep the full compiler out ​

The saving depends on tree-shaking. Every exemplar package declares "sideEffects": false in its package.json, so bundlers drop unused modules without further configuration.

Import XPathCompiler from @exemplarjs/xpath/lean everywhere: a single import { XPathCompiler } from '@exemplarjs/xpath' anywhere in the bundle pulls in every group.

The lean entry also exports everything else that the full entry does, such as XPathException, XPathErrorCode, collectionMap and the types, so nothing needs to be imported from the full entry:

ts
import { 
XPathCompiler
,
XPathException
} from '@exemplarjs/xpath/lean';

Next steps ​

Released under the Apache License 2.0.