@getodk/xpath 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# @getodk/xpath
+
+An XPath evaluator, with intent to support:
+
+- Full XPath 1.0 syntax and behavior
+- Context-based extensibility of behavior beyond the XPath 1.0 function library
+- [ODK XForms](https://getodk.github.io/xforms-spec/) XPath extensions
+- Non-browser environments (provided a subset of standard DOM APIs)
+- Minor accommodations for certain [Enketo](https://github.com/enketo/enketo/tree/main/packages/openrosa-xpath-evaluator) function aliases:
+  - `date-time` is an alias of `date`, which is assumed to be additive
+  - `format-date` function is an alias of `format-date-time`, which differs from the ODK XForms spec
+
+## Install
+
+Install this package and its required peer dependencies with `npm` (or the equivalent command for your preferred package manager):
+
+```sh
+npm install @getodk/tree-sitter-xpath @getodk/xpath web-tree-sitter
+```
+
+## Usage
+
+To use `@getodk/xpath` at runtime, first create an `XFormsXPathEvaluator`
+instance, specifying the XForm `rootNode`. Usage from that point is
+API-compatible with the standard DOM [`evaluate`
+method](https://developer.mozilla.org/en-US/docs/Web/API/XPathEvaluator/evaluate).
+
+```ts
+import { XFormsXPathEvaluator } from '@getodk/xpath';
+
+// Given an XForms DOM document...
+declare const xform: XMLDocument;
+
+const evaluator = new XFormsXPathEvaluator({ rootNode: xform });
+
+// A namespace resolver is optional, and the context node can be used (which is the default)
+const nsResolver: XPathNSResolver = xform;
+
+const result: XPathResult = evaluator.evaluate(
+  '/root/...',
+  xform,
+  nsResolver,
+  XPathResult.ORDERED_NODE_ITERATOR_TYPE
+);
+```
+
+For typical XForms usage, `rootNode` will be either an XForm `XMLDocument` or its primary instance `Element`.
+
+For XPath 1.0 functionality without XForms extension functions, you may use `Evaluator` the same way, and `rootNode` is optional:
+
+```ts
+import { Evaluator } from '@getodk/xpath';
+
+const evaluator = new Evaluator();
+
+// ...
+```
+
+In either case, the `result` returned by `evaluate` is API-compatible with the standard DOM [`XPathResult`](https://developer.mozilla.org/en-US/docs/Web/API/XPathResult).
+
+### XForms `itext` translations
+
+`XFormsXPathEvaluator` supports the JavaRosa `itext` function (`jr:itext` by convention), as specified in ODK XForms, which says:
+
+> Obtains an itext value for the provided reference in the active language from the `<itext>` block in the model.
+
+This active language state is managed at the `XFormXPathEvaluator` instance level, with the default language (again as specified in ODK XForms) active on construction. You can access a form's available languages, and get or set the active language under the `XFormXPathEvaluator.translations` object.
+
+Example:
+
+```ts
+const domParser = new DOMParser();
+const xform: XMLDocument = domParser.parseFromString(
+  `<h:html>
+  <h:head>
+    <model>
+      <itext>
+        <translation lang="English" default="true()">
+          <text id="hello">
+            <value>hello</value>
+          </text>
+        </translation>
+        <translation lang="Español">
+          <text id="hello">
+            <value>hola</value>
+          </text>
+        </translation>
+      </itext>
+    </model>
+  </h:head>
+  <!-- ... -->
+</h:html>`,
+  'text/xml'
+);
+const evaluator = new XFormsXPathEvaluator({ rootNode: xform });
+
+evaluator.translations.getLanguages(); // ['English', 'Español']
+evaluator.translations.getActiveLanguage(); // 'English'
+evaluator.evaluate('jr:itext("hello")', xform, null, XPathResult.STRING_TYPE).stringValue; // 'hello'
+
+evaluator.translations.setActiveLanguage('Español'); // 'Español'
+evaluator.translations.getActiveLanguage(); // 'Español'
+evaluator.evaluate('jr:itext("hello")', xform, null, XPathResult.STRING_TYPE).stringValue; // 'hola'
+```
+
+There are currently a few caveats to `jr:itext` use:
+
+- `<itext>` and its translations are evaluated from the **document root** of the `rootNode` specified in `XFormsXPathEvaluator` options. As such:
+
+  - translations _will_ be resolved if a descendant `rootNode` (e.g. the XForm's primary `<instance>` element) is specified
+
+  - translations _will not_ be resolved for an XForm in an unusual DOM structure (e.g. a `DocumentFragment`, or in an arbitrary subtree of an unrelated document)
+
+- Translations are treated as static, and cached during construction of `XFormsXPathEvaluator`. This is based on typical usage, wherein an XForm definition itself is expected to be static, but it will not (yet) support use cases like authoring an XForm definition.
+
+- `<value form="...anything...">` is not yet supported. It's unclear what the interface for this usage might be.
+
+- The interface for getting and setting language state is currently experimental pending integration experience, and may be changed in the future. The intent of this interface is to be relatively agnostic to outside state management, and to isolate this sort of stateful context from the XForm DOM, but that approach may also change.
+
+### Convenience APIs
+
+Both evaluator classes provide the following convenience methods:
+
+- `evaluateBoolean(expression: string, options?: { contextNode?: Node }): boolean`
+- `evaluateNumber(expression: string, options?: { contextNode?: Node }): number`
+- `evaluateString(expression: string, options?: { contextNode?: Node }): string`
+- `evaluateNode(expression: string, options?: { contextNode?: Node }): Node | null`
+- `evaluateNodes(expression: string, options?: { contextNode?: Node }): Node[]`
+
+(Also provided: `evaluateElement` and `evaluateNonNullElement`, but these are not type safe so use them at your own risk.)
+
+## Supported/tested environments
+
+- Browsers (latest versions):
+  - Chrome/Chromium-based browsers (tested only in Chromium)
+  - Firefox
+  - Safari/WebKit (tested in WebKit directly)
+- Non-browser runtimes with a DOM compatibility environement:
+  - Node (current/LTS; tested with [jsdom](https://github.com/jsdom/jsdom)). Node DOM compatibility **does not** require any native extensions for. DOM compatibility **does not** require any underlying XPath evaluation functionality (though it does currently rely on global constants like `XPathResult`).
+  - Other runtimes and DOM compatibility libraries are not currently tested, support is unknown.
+
+## Known issues and incompatibilities
+
+### XPath 1.0
+
+- Expressions with variable references are parsed incorrectly. There is also no API to provide variable values, even if variable references were supported.
+
+### ODK XForms
+
+We intend to support the full ODK XForms function library, but support is currently incomplete. The following functions are not yet supported (the `jr:` prefix is used by convention to refer to the JavaRosa namespace):
+
+- `indexed-repeat`
+- `pulldata`
+- `jr:choice-name`
+
+### Non-browser environments
+
+The DOM standard is very complex, and compatibility libraries sometimes differ in terms of standards compliance and compatibility with the major browser implementations. It is likely, perhaps inevitable, that there will be edge cases and minor compatiblity issues when using such a library. At time of writing, no such issues are known in our tested environments, but a couple of minor issues have already been found and fixed during the initial test setup.

package/dist/.vite/manifest.json

@@ -0,0 +1,21 @@
+{
+  "_expressionParser-1Kzq3bIy.js": {
+    "file": "expressionParser-1Kzq3bIy.js"
+  },
+  "src/expressionParser.ts": {
+    "file": "expressionParser.js",
+    "src": "src/expressionParser.ts",
+    "isEntry": true,
+    "imports": [
+      "_expressionParser-1Kzq3bIy.js"
+    ]
+  },
+  "src/index.ts": {
+    "file": "index.js",
+    "src": "src/index.ts",
+    "isEntry": true,
+    "imports": [
+      "_expressionParser-1Kzq3bIy.js"
+    ]
+  }
+}

package/dist/context/Context.d.ts

@@ -0,0 +1,27 @@
+import type { Temporal } from '@js-temporal/polyfill';
+import type { Evaluator } from '../evaluator/Evaluator.ts';
+import type { FunctionLibraryCollection } from '../evaluator/functions/FunctionLibraryCollection.ts';
+import type { ContextDocument, ContextNode, ContextParentNode } from '../lib/dom/types.ts';
+import type { XPathNamespaceResolverObject } from '../shared/interface.ts';
+/**
+ * The context in which any XPath expression *or sub-expression* is evaluated.
+ */
+export interface Context {
+    readonly evaluator: Evaluator;
+    /**
+     * The `contextNode` as specified at the {@link Evaluator.evaluate} call site.
+     * This value is to remain constant for the entire scope of an evaluation.
+     *
+     * This explicitly supports the `current()` function, but it may also support
+     * a variety of other use cases and optimizations in the future.
+     */
+    readonly evaluationContextNode: ContextNode;
+    readonly contextDocument: ContextDocument;
+    readonly rootNode: ContextParentNode;
+    readonly contextNodes: Iterable<ContextNode>;
+    contextPosition(): number;
+    contextSize(): number;
+    readonly functions: FunctionLibraryCollection;
+    readonly namespaceResolver: XPathNamespaceResolverObject;
+    readonly timeZone: Temporal.TimeZone;
+}

package/dist/context/EvaluationContext.d.ts

@@ -0,0 +1,48 @@
+import { Temporal } from '@js-temporal/polyfill';
+import { LocationPathEvaluation } from '../evaluations/LocationPathEvaluation.ts';
+import type { Evaluator } from '../evaluator/Evaluator.ts';
+import type { FunctionLibraryCollection } from '../evaluator/functions/FunctionLibraryCollection.ts';
+import type { FilteredTreeWalker, FilteredTreeWalkers } from '../lib/dom/traversal.ts';
+import type { ContextDocument, ContextNode, ContextParentNode } from '../lib/dom/types.ts';
+import type { XPathNamespaceResolverObject } from '../shared/interface.ts';
+import type { Context } from './Context.ts';
+declare class EvaluationContextTreeWalkers implements FilteredTreeWalkers {
+    readonly ANY: FilteredTreeWalker<'ANY'>;
+    readonly COMMENT: FilteredTreeWalker<'COMMENT'>;
+    readonly ELEMENT: FilteredTreeWalker<'ELEMENT'>;
+    readonly PROCESSING_INSTRUCTION: FilteredTreeWalker<'PROCESSING_INSTRUCTION'>;
+    readonly TEXT: FilteredTreeWalker<'TEXT'>;
+    constructor(contextDocument: ContextDocument, rootNode: ContextParentNode);
+}
+export type { EvaluationContextTreeWalkers };
+export interface EvaluationContextOptions {
+    readonly document: ContextDocument;
+    readonly rootNode: ContextParentNode;
+    readonly functions: FunctionLibraryCollection;
+    readonly namespaceResolver: XPathNamespaceResolverObject;
+    readonly timeZone: Temporal.TimeZone;
+    readonly treeWalkers: EvaluationContextTreeWalkers;
+}
+/**
+ * The context in which an XPath expression (**not** a sub-expression)
+ * is evaluated.
+ */
+export declare class EvaluationContext implements Context {
+    readonly evaluator: Evaluator;
+    /**
+     * @see {@link Context.evaluationContextNode}
+     */
+    readonly evaluationContextNode: ContextNode;
+    readonly contextDocument: ContextDocument;
+    readonly rootNode: ContextParentNode;
+    readonly contextNodes: Iterable<ContextNode>;
+    readonly functions: FunctionLibraryCollection;
+    readonly namespaceResolver: XPathNamespaceResolverObject;
+    readonly timeZone: Temporal.TimeZone;
+    readonly treeWalkers: EvaluationContextTreeWalkers;
+    constructor(evaluator: Evaluator, contextNode: ContextNode, options?: Partial<EvaluationContextOptions>);
+    contextPosition(): number;
+    contextSize(): number;
+    currentContext(): LocationPathEvaluation;
+    rootContext(): LocationPathEvaluation;
+}

package/dist/evaluations/BooleanEvaluation.d.ts

@@ -0,0 +1,12 @@
+import type { LocationPathEvaluation } from './LocationPathEvaluation.ts';
+import { ValueEvaluation } from './ValueEvaluation.ts';
+export declare class BooleanEvaluation extends ValueEvaluation<'BOOLEAN'> {
+    readonly context: LocationPathEvaluation;
+    readonly value: boolean;
+    readonly type = "BOOLEAN";
+    readonly nodes: null;
+    protected readonly booleanValue: boolean;
+    protected readonly numberValue: number;
+    protected readonly stringValue: string;
+    constructor(context: LocationPathEvaluation, value: boolean);
+}

package/dist/evaluations/DateTimeLikeEvaluation.d.ts

@@ -0,0 +1,23 @@
+import { Temporal } from '@js-temporal/polyfill';
+import type { LocationPathEvaluation } from './LocationPathEvaluation.ts';
+import { ValueEvaluation } from './ValueEvaluation.ts';
+interface PrecomputedXPathValues {
+    readonly booleanValue?: boolean;
+    readonly numberValue?: number;
+    readonly stringValue?: string;
+}
+export declare class DateTimeLikeEvaluation extends ValueEvaluation<'NUMBER'> {
+    readonly context: LocationPathEvaluation;
+    protected dateTime: Temporal.ZonedDateTime | null;
+    readonly type = "NUMBER";
+    readonly nodes: null;
+    readonly value: number;
+    protected readonly booleanValue: boolean;
+    protected readonly numberValue: number;
+    protected readonly stringValue: string;
+    protected readonly milliseconds: number;
+    protected readonly dateString: string;
+    protected readonly dateTimeString: string;
+    constructor(context: LocationPathEvaluation, dateTime: Temporal.ZonedDateTime | null, precomputedValues?: PrecomputedXPathValues);
+}
+export {};

package/dist/evaluations/Evaluation.d.ts

@@ -0,0 +1,18 @@
+import type { EvaluationType } from './EvaluationType.ts';
+import type { LocationPathEvaluation } from './LocationPathEvaluation.ts';
+export interface Evaluation<Type extends EvaluationType = EvaluationType> extends Iterable<Evaluation<Type>> {
+    readonly context: LocationPathEvaluation;
+    readonly type: Type;
+    first(): Evaluation<Type> | null;
+    values(): Iterable<Evaluation<Type>>;
+    eq(operand: Evaluation): boolean;
+    ne(operand: Evaluation): boolean;
+    lt(operand: Evaluation): boolean;
+    lte(operand: Evaluation): boolean;
+    gt(operand: Evaluation): boolean;
+    gte(operand: Evaluation): boolean;
+    toBoolean(): boolean;
+    toNumber(): number;
+    toString(): string;
+    readonly nodes: Type extends 'NODE' ? Iterable<Node> : null;
+}

package/dist/evaluations/EvaluationType.d.ts

@@ -0,0 +1,7 @@
+export interface EvaluationTypes {
+    readonly BOOLEAN: boolean;
+    readonly NODE: Node;
+    readonly NUMBER: number;
+    readonly STRING: string;
+}
+export type EvaluationType = keyof EvaluationTypes;

package/dist/evaluations/LocationPathEvaluation.d.ts

@@ -0,0 +1,113 @@
+import type { Temporal } from '@js-temporal/polyfill';
+import type { Context } from '../context/Context.ts';
+import type { EvaluationContext, EvaluationContextTreeWalkers } from '../context/EvaluationContext.ts';
+import type { Evaluator } from '../evaluator/Evaluator.ts';
+import type { FilterPathExpressionEvaluator } from '../evaluator/expression/FilterPathExpressionEvaluator.ts';
+import type { LocationPathEvaluator } from '../evaluator/expression/LocationPathEvaluator.ts';
+import type { LocationPathExpressionEvaluator } from '../evaluator/expression/LocationPathExpressionEvaluator.ts';
+import type { FunctionLibraryCollection } from '../evaluator/functions/FunctionLibraryCollection.ts';
+import type { NodeSetFunction } from '../evaluator/functions/NodeSetFunction.ts';
+import type { AnyStep } from '../evaluator/step/Step.ts';
+import type { ContextDocument, ContextNode, ContextParentNode } from '../lib/dom/types.ts';
+import { Reiterable } from '../lib/iterators/Reiterable.ts';
+import type { XPathNamespaceResolverObject } from '../shared/interface.ts';
+import type { Evaluation } from './Evaluation.ts';
+import { NodeEvaluation } from './NodeEvaluation.ts';
+type LocationPathParentContext = EvaluationContext | LocationPathEvaluation;
+type EvaluationComparator = (lhs: Evaluation, rhs: Evaluation) => boolean;
+export declare enum AxisName {
+    ANCESTOR = "ancestor",
+    ANCESTOR_OR_SELF = "ancestor-or-self",
+    ATTRIBUTE = "attribute",
+    CHILD = "child",
+    DESCENDANT = "descendant",
+    DESCENDANT_OR_SELF = "descendant-or-self",
+    FOLLOWING = "following",
+    FOLLOWING_SIBLING = "following-sibling",
+    NAMESPACE = "namespace",
+    PARENT = "parent",
+    PRECEDING = "preceding",
+    PRECEDING_SIBLING = "preceding-sibling",
+    SELF = "self"
+}
+interface LocationPathEvaluationOptions {
+    readonly contextPosition?: number;
+    contextSize?: () => number;
+}
+type ArbitraryNodesTemporaryCallee = FilterPathExpressionEvaluator | LocationPathEvaluator | NodeSetFunction<any>;
+export declare class LocationPathEvaluation implements Evaluation<'NODE'>, Context, Iterable<LocationPathEvaluation> {
+    readonly parentContext: LocationPathParentContext;
+    readonly type = "NODE";
+    protected readonly nodeEvaluations: Reiterable<NodeEvaluation>;
+    readonly evaluator: Evaluator;
+    readonly context: LocationPathEvaluation;
+    /**
+     * @see {@link Context.evaluationContextNode}
+     */
+    readonly evaluationContextNode: ContextNode;
+    readonly contextDocument: ContextDocument;
+    readonly rootNode: ContextParentNode;
+    nodes: Iterable<ContextNode>;
+    get contextNodes(): IterableIterator<ContextNode>;
+    protected computedContextSize: number | null;
+    protected readonly optionsContextSize?: () => number;
+    protected readonly initializedContextPosition: number;
+    readonly functions: FunctionLibraryCollection;
+    readonly namespaceResolver: XPathNamespaceResolverObject;
+    readonly treeWalkers: EvaluationContextTreeWalkers;
+    readonly timeZone: Temporal.TimeZone;
+    /**
+     * TODO: this is a temporary accommodation for these cases which are presently
+     * not especially well designed:
+     *
+     * - Functions returning node-sets (i.e. {@link NodeSetFunction} instances).
+     *   It may make sense to invert control, invoking them from here?
+     *
+     * - Nodes filtered by predicate in {@link LocationPathExpression}. Such
+     *   filtering almost certainly should be performed here, in {@link step}.
+     */
+    static fromArbitraryNodes(currentContext: LocationPathParentContext, nodes: Iterable<ContextNode>, _temporaryCallee: ArbitraryNodesTemporaryCallee): LocationPathEvaluation;
+    static fromCurrentContext(evaluationContext: EvaluationContext): LocationPathEvaluation;
+    static fromRoot(parentContext: LocationPathParentContext): LocationPathEvaluation;
+    protected constructor(parentContext: LocationPathParentContext, contextNodes: Iterable<ContextNode>, options?: LocationPathEvaluationOptions);
+    [Symbol.iterator](): {
+        next: () => IteratorResult<LocationPathEvaluation>;
+    };
+    values(): Iterable<NodeEvaluation>;
+    contextPosition(): number;
+    contextSize(): number;
+    currentContext(): LocationPathEvaluation;
+    rootContext(): LocationPathEvaluation;
+    protected _first?: NodeEvaluation | null;
+    first(): NodeEvaluation | null;
+    protected _isEmpty: boolean | null;
+    protected isEmpty(): boolean;
+    some(predicate: (evaluation: NodeEvaluation) => boolean): boolean;
+    toBoolean(): boolean;
+    toNumber(): number;
+    toString(): string;
+    protected compare(comparator: EvaluationComparator, operand: Evaluation): boolean;
+    eq(operand: Evaluation): boolean;
+    ne(operand: Evaluation): boolean;
+    lt(operand: Evaluation): boolean;
+    lte(operand: Evaluation): boolean;
+    gt(operand: Evaluation): boolean;
+    gte(operand: Evaluation): boolean;
+    protected getTreeWalker(step: AnyStep): TreeWalker;
+    protected ancestor(step: AnyStep): Iterable<ContextNode>;
+    protected ancestorOrSelf(step: AnyStep): Iterable<ContextNode>;
+    protected attribute(): Iterable<ContextNode>;
+    protected child(step: AnyStep): Iterable<ContextNode>;
+    protected descendant(step: AnyStep): Iterable<ContextNode>;
+    protected descendantOrSelf(step: AnyStep): Iterable<ContextNode>;
+    protected following(step: AnyStep): Iterable<ContextNode>;
+    protected followingSibling(step: AnyStep): Iterable<ContextNode>;
+    protected namespace(): Iterable<ContextNode>;
+    protected parent(step: AnyStep): Iterable<ContextNode>;
+    protected preceding(step: AnyStep): Iterable<ContextNode>;
+    protected precedingSibling(step: AnyStep): Iterable<ContextNode>;
+    protected self(): Iterable<ContextNode>;
+    step(step: AnyStep): LocationPathEvaluation;
+    evaluateLocationPathExpression(expression: LocationPathExpressionEvaluator): LocationPathEvaluation;
+}
+export {};

package/dist/evaluations/NodeEvaluation.d.ts

@@ -0,0 +1,22 @@
+import type { LocationPathEvaluation } from './LocationPathEvaluation.ts';
+import { ValueEvaluation } from './ValueEvaluation.ts';
+interface NodeEvaluationComputedValues {
+    readonly booleanValue: boolean;
+    readonly isEmpty: boolean;
+    readonly numberValue: number;
+    readonly stringValue: string;
+}
+export declare class NodeEvaluation extends ValueEvaluation<'NODE'> {
+    readonly context: LocationPathEvaluation;
+    readonly value: Node;
+    readonly type = "NODE";
+    readonly nodes: Iterable<Node>;
+    protected computedValues: NodeEvaluationComputedValues | null;
+    protected get booleanValue(): boolean;
+    protected get numberValue(): number;
+    protected get stringValue(): string;
+    get isEmpty(): boolean;
+    constructor(context: LocationPathEvaluation, value: Node);
+    protected computeValues(): NodeEvaluationComputedValues;
+}
+export {};

package/dist/evaluations/NumberEvaluation.d.ts

@@ -0,0 +1,12 @@
+import type { LocationPathEvaluation } from './LocationPathEvaluation.ts';
+import { ValueEvaluation } from './ValueEvaluation.ts';
+export declare class NumberEvaluation extends ValueEvaluation<'NUMBER'> {
+    readonly context: LocationPathEvaluation;
+    readonly value: number;
+    readonly type = "NUMBER";
+    readonly nodes: null;
+    protected readonly booleanValue: boolean;
+    protected readonly numberValue: number;
+    protected readonly stringValue: string;
+    constructor(context: LocationPathEvaluation, value: number);
+}

package/dist/evaluations/StringEvaluation.d.ts

@@ -0,0 +1,13 @@
+import type { LocationPathEvaluation } from './LocationPathEvaluation.ts';
+import { ValueEvaluation } from './ValueEvaluation.ts';
+export declare class StringEvaluation extends ValueEvaluation<'STRING'> {
+    readonly context: LocationPathEvaluation;
+    readonly value: string;
+    readonly isEmpty: boolean;
+    readonly type = "STRING";
+    readonly nodes: null;
+    protected readonly booleanValue: boolean;
+    protected readonly numberValue: number;
+    protected readonly stringValue: string;
+    constructor(context: LocationPathEvaluation, value: string, isEmpty?: boolean);
+}

package/dist/evaluations/ValueEvaluation.d.ts

@@ -0,0 +1,24 @@
+import type { Evaluation } from './Evaluation.ts';
+import type { EvaluationType, EvaluationTypes } from './EvaluationType.ts';
+import { LocationPathEvaluation } from './LocationPathEvaluation.ts';
+export declare abstract class ValueEvaluation<Type extends EvaluationType> implements Evaluation<Type> {
+    abstract readonly context: LocationPathEvaluation;
+    abstract readonly type: Type;
+    abstract readonly value: EvaluationTypes[Type];
+    abstract readonly nodes: Type extends 'NODE' ? Iterable<Node> : null;
+    protected abstract readonly booleanValue: boolean;
+    protected abstract readonly numberValue: number;
+    protected abstract readonly stringValue: string;
+    [Symbol.iterator](): IterableIterator<this>;
+    first(): this;
+    values(): IterableIterator<this>;
+    toBoolean(): boolean;
+    toNumber(): number;
+    toString(): string;
+    eq(operand: Evaluation): boolean;
+    ne(operand: Evaluation): boolean;
+    lt(operand: Evaluation): boolean;
+    lte(operand: Evaluation): boolean;
+    gt(operand: Evaluation): boolean;
+    gte(operand: Evaluation): boolean;
+}

package/dist/evaluator/Evaluator.d.ts

@@ -0,0 +1,41 @@
+import { Temporal } from '@js-temporal/polyfill';
+import type { EvaluationContextOptions } from '../context/EvaluationContext.ts';
+import type { AnyParentNode } from '../lib/dom/types.ts';
+import type { AnyXPathEvaluator, XPathNSResolver, XPathResultType } from '../shared/index.ts';
+import type { ExpressionParser, ParseOptions } from '../static/grammar/ExpressionParser.ts';
+import { FunctionLibraryCollection } from './functions/FunctionLibraryCollection.ts';
+import { ResultTypes } from './result/ResultType.ts';
+export interface EvaluatorOptions {
+    readonly functions?: FunctionLibraryCollection;
+    readonly parseOptions?: ParseOptions;
+    readonly rootNode?: AnyParentNode | null | undefined;
+    readonly timeZoneId?: string | undefined;
+}
+export interface EvaluatorConvenienceMethodOptions {
+    readonly contextNode?: Node;
+}
+export interface EvaluatorNodeConvenienceMethodOptions<AssertExists extends boolean = false> extends EvaluatorConvenienceMethodOptions {
+    readonly assertExists?: AssertExists;
+}
+type EvaluatedNode<AssertExists extends boolean, T extends Node> = AssertExists extends true ? T : T | null;
+export declare class Evaluator implements AnyXPathEvaluator {
+    protected readonly parser: ExpressionParser;
+    readonly functions: FunctionLibraryCollection;
+    readonly parseOptions: ParseOptions;
+    readonly resultTypes: ResultTypes;
+    readonly rootNodeDocument: Document | XMLDocument | null;
+    readonly rootNode: AnyParentNode | null;
+    readonly sharedContextOptions: Partial<EvaluationContextOptions>;
+    readonly timeZone: Temporal.TimeZone;
+    constructor(options?: EvaluatorOptions);
+    evaluate(expression: string, contextNode: Node, namespaceResolver: XPathNSResolver | null, resultType: XPathResultType | null): import("./result/BooleanResult.ts").BooleanResult | import("./result/NodeSetResult.ts").NodeSetSnapshotResult | import("./result/NodeSetResult.ts").NodeSetIteratorResult | import("./result/NumberResult.ts").NumberResult | import("./result/StringResult.ts").StringResult;
+    protected getContextNode(options: EvaluatorConvenienceMethodOptions): Node;
+    evaluateBoolean(expression: string, options?: EvaluatorConvenienceMethodOptions): boolean;
+    evaluateNumber(expression: string, options?: EvaluatorConvenienceMethodOptions): number;
+    evaluateString(expression: string, options?: EvaluatorConvenienceMethodOptions): string;
+    evaluateNode<T extends Node, AssertExists extends boolean = false>(expression: string, options?: EvaluatorNodeConvenienceMethodOptions<AssertExists>): EvaluatedNode<AssertExists, T>;
+    evaluateElement<AssertExists extends boolean = false>(expression: string, options?: EvaluatorNodeConvenienceMethodOptions<AssertExists>): EvaluatedNode<AssertExists, Element>;
+    evaluateNonNullElement(expression: string, options?: Omit<EvaluatorNodeConvenienceMethodOptions<true>, 'assertExists'>): Element;
+    evaluateNodes<T extends Node>(expression: string, options?: EvaluatorNodeConvenienceMethodOptions): T[];
+}
+export {};

package/dist/evaluator/NamespaceResolver.d.ts

@@ -0,0 +1,48 @@
+import { ENKETO_NAMESPACE_URI, ENKETO_PREFIX, FN_NAMESPACE_URI, FN_PREFIX, HTML_NAMESPACE_URI, HTML_PREFIX, JAVAROSA_NAMESPACE_URI, JAVAROSA_PREFIX, ODK_NAMESPACE_URI, ODK_PREFIX, OPENROSA_XFORMS_NAMESPACE_URI, OPENROSA_XFORMS_PREFIX, XFORMS_NAMESPACE_URI, XFORMS_PREFIX, XHTML_NAMESPACE_URI, XML_NAMESPACE_URI, XML_PREFIX, XMLNS_NAMESPACE_URI, XMLNS_PREFIX } from '../../../common/src/constants/xmlns.ts';
+import type { ContextParentNode } from '../lib/dom/types.ts';
+import type { XPathNamespaceResolverObject } from '../shared/interface.ts';
+export { ENKETO_NAMESPACE_URI, ENKETO_PREFIX, FN_NAMESPACE_URI, FN_PREFIX, HTML_NAMESPACE_URI, HTML_PREFIX, JAVAROSA_NAMESPACE_URI, JAVAROSA_PREFIX, ODK_NAMESPACE_URI, ODK_PREFIX, OPENROSA_XFORMS_NAMESPACE_URI, OPENROSA_XFORMS_PREFIX, XFORMS_NAMESPACE_URI, XFORMS_PREFIX, XHTML_NAMESPACE_URI, XML_NAMESPACE_URI, XML_PREFIX, XMLNS_NAMESPACE_URI, XMLNS_PREFIX, };
+export interface StaticNamespaces<DefaultPrefix extends string, DefaultURI extends string, Mapping extends Record<string, string>> {
+    get<Key extends string | null>(key: Key): Key extends null ? DefaultURI : Key extends DefaultPrefix ? DefaultURI : Key extends keyof Mapping ? Mapping[Key] : undefined;
+    has(key: null): true;
+    has(key: DefaultPrefix | keyof Mapping): true;
+    has(key: keyof Mapping): true;
+    has(key: string): false;
+}
+export declare class StaticNamespaces<DefaultPrefix extends string, DefaultURI extends string, const Mapping extends Record<string, string>> extends Map<string | null, string> implements ReadonlyMap<string | null, string> {
+    protected defaultPrefix: DefaultPrefix;
+    protected defaultURI: DefaultURI;
+    constructor(defaultPrefix: DefaultPrefix, defaultURI: DefaultURI, namespaces: Mapping);
+}
+export declare const staticNamespaces: StaticNamespaces<"xf", "http://www.w3.org/2002/xforms", {
+    readonly enk: "http://enketo.org/xforms";
+    readonly fn: "http://www.w3.org/2005/xpath-functions";
+    readonly h: "http://www.w3.org/1999/xhtml";
+    readonly html: "http://www.w3.org/1999/xhtml";
+    readonly xhtml: "http://www.w3.org/1999/xhtml";
+    readonly jr: "http://openrosa.org/javarosa";
+    readonly javarosa: "http://openrosa.org/javarosa";
+    readonly odk: "http://www.opendatakit.org/xforms";
+    readonly orx: "http://openrosa.org/xforms";
+    readonly 'openrosa-xforms': "http://openrosa.org/xforms";
+    readonly xf: "http://www.w3.org/2002/xforms";
+    readonly xml: "http://www.w3.org/XML/1998/namespace";
+    readonly xmlns: "http://www.w3.org/2000/xmlns/";
+}>;
+export declare class NamespaceResolver implements XPathNamespaceResolverObject {
+    protected readonly rootNode: ContextParentNode;
+    protected readonly referenceNode?: XPathNamespaceResolverObject | null | undefined;
+    protected readonly contextResolver: XPathNamespaceResolverObject;
+    constructor(rootNode: ContextParentNode, referenceNode?: XPathNamespaceResolverObject | null | undefined);
+    protected lookupNodeNamespaceURI: (node: Node, prefix: string | null) => string | null;
+    protected lookupStaticNamespaceURI: (prefix: string | null) => "http://www.w3.org/2002/xforms" | null;
+    /**
+     * Note: while it is likely consistent with the **spec** to resolve a `null`
+     * prefix, it's not typical in a browser environment for the resolver to be
+     * consulted for an unprefixed name test in an XPath expression.
+     *
+     * We _may_ elect to deviate from that typical behavior, as it is the much
+     * more **obvious** behavior.
+     */
+    lookupNamespaceURI(prefix: string | null): string | null;
+}

package/dist/evaluator/expression/AbsoluteLocationPathExpressionEvaluator.d.ts

@@ -0,0 +1,7 @@
+import type { AbsoluteLocationPathNode } from '../../static/grammar/SyntaxNode.ts';
+import type { ExpressionEvaluator } from './ExpressionEvaluator.ts';
+import { LocationPathEvaluator } from './LocationPathEvaluator.ts';
+export declare class AbsoluteLocationPathExpressionEvaluator extends LocationPathEvaluator implements ExpressionEvaluator {
+    readonly syntaxNode: AbsoluteLocationPathNode;
+    constructor(syntaxNode: AbsoluteLocationPathNode);
+}

package/dist/evaluator/expression/BinaryExpressionEvaluator.d.ts

@@ -0,0 +1,11 @@
+import type { EvaluationContext } from '../../context/EvaluationContext.ts';
+import type { Evaluation } from '../../evaluations/Evaluation.ts';
+import type { AnyBinaryExprNode } from '../../static/grammar/SyntaxNode.ts';
+import type { ExpressionEvaluator } from './ExpressionEvaluator.ts';
+export declare abstract class BinaryExpressionEvaluator<Node extends AnyBinaryExprNode> implements ExpressionEvaluator {
+    readonly syntaxNode: Node;
+    readonly lhs: ExpressionEvaluator;
+    readonly rhs: ExpressionEvaluator;
+    constructor(syntaxNode: Node);
+    abstract evaluate(context: EvaluationContext): Evaluation;
+}

package/dist/evaluator/expression/BooleanBinaryExpressionEvaluator.d.ts

@@ -0,0 +1,17 @@
+import type { EvaluationContext } from '../../context/EvaluationContext.ts';
+import { BooleanEvaluation } from '../../evaluations/BooleanEvaluation.ts';
+import type { Evaluation } from '../../evaluations/Evaluation.ts';
+import type { AndExprNode, EqExprNode, GtExprNode, GteExprNode, LtExprNode, LteExprNode, NeExprNode, OrExprNode } from '../../static/grammar/SyntaxNode.ts';
+import { BinaryExpressionEvaluator } from './BinaryExpressionEvaluator.ts';
+type BooleanBinaryExprNode = AndExprNode | EqExprNode | GteExprNode | GtExprNode | LteExprNode | LtExprNode | NeExprNode | OrExprNode;
+type BooleanOperator<Node extends BooleanBinaryExprNode> = Node extends AndExprNode ? 'and' : Node extends EqExprNode ? 'eq' : Node extends GtExprNode ? 'gt' : Node extends GteExprNode ? 'gte' : Node extends LtExprNode ? 'lt' : Node extends LteExprNode ? 'lte' : Node extends NeExprNode ? 'ne' : Node extends OrExprNode ? 'or' : never;
+type CompareOperator = 'eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'ne';
+export declare class BooleanBinaryExpressionEvaluator<Node extends BooleanBinaryExprNode> extends BinaryExpressionEvaluator<Node> {
+    readonly operator: BooleanOperator<Node>;
+    constructor(syntaxNode: Node);
+    protected and(context: EvaluationContext): Evaluation;
+    protected or(context: EvaluationContext): Evaluation;
+    protected compare(context: EvaluationContext, operator: CompareOperator): BooleanEvaluation;
+    evaluate(context: EvaluationContext): Evaluation;
+}
+export {};