@getodk/xpath 0.2.0 → 0.3.0

package/dist/.vite/manifest.json

@@ -1,6 +1,6 @@
 {
-  "_expressionParser-BRkDdCO9.js": {
-    "file": "expressionParser-BRkDdCO9.js",
+  "_expressionParser-DpqfmhIO.js": {
+    "file": "expressionParser-DpqfmhIO.js",
     "name": "expressionParser"
   },
   "src/expressionParser.ts": {
@@ -9,7 +9,7 @@
     "src": "src/expressionParser.ts",
     "isEntry": true,
     "imports": [
-      "_expressionParser-BRkDdCO9.js"
+      "_expressionParser-DpqfmhIO.js"
     ]
   },
   "src/index.ts": {
@@ -18,7 +18,7 @@
     "src": "src/index.ts",
     "isEntry": true,
     "imports": [
-      "_expressionParser-BRkDdCO9.js"
+      "_expressionParser-DpqfmhIO.js"
     ]
   }
 }

package/dist/adapter/WHAT/WHATNode.d.ts

@@ -0,0 +1,30 @@
+import { XPathCustomUnwrappableNode } from '../interface/XPathCustomUnwrappableNode.ts';
+import { XPathNodeKindKey } from '../interface/XPathNode.ts';
+export interface WHATDocument extends Document, XPathCustomUnwrappableNode<Document> {
+    readonly [XPathNodeKindKey]: 'document';
+}
+export interface WHATElement extends Element, XPathCustomUnwrappableNode<Element> {
+    readonly [XPathNodeKindKey]: 'element';
+}
+export interface WHATNamespaceDeclaration extends Attr, XPathCustomUnwrappableNode<Attr> {
+    readonly [XPathNodeKindKey]: 'namespace_declaration';
+}
+export interface WHATAttribute extends Attr, XPathCustomUnwrappableNode<Attr> {
+    readonly [XPathNodeKindKey]: 'attribute';
+}
+export interface WHATText extends CDATASection, Text, XPathCustomUnwrappableNode<CDATASection | Text> {
+    readonly [XPathNodeKindKey]: 'text';
+    readonly nodeType: Node['CDATA_SECTION_NODE'] | Node['TEXT_NODE'];
+}
+export interface WHATComment extends Comment, XPathCustomUnwrappableNode<Comment> {
+    readonly [XPathNodeKindKey]: 'comment';
+}
+export interface WHATProcessingInstruction extends ProcessingInstruction {
+    readonly [XPathNodeKindKey]: 'processing_instruction';
+}
+type UnwrappableWHATNodeUnion<T, U> = T & XPathCustomUnwrappableNode<U>;
+export type WHATNode = UnwrappableWHATNodeUnion<(WHATDocument | WHATElement | WHATNamespaceDeclaration | WHATAttribute | WHATText | WHATComment | WHATProcessingInstruction), Node>;
+export type WHATParentNode = UnwrappableWHATNodeUnion<WHATDocument | WHATElement, ParentNode>;
+export type WHATChildNode = UnwrappableWHATNodeUnion<(WHATElement | WHATText | WHATComment | WHATProcessingInstruction), ChildNode>;
+export type WHATNamedNode = UnwrappableWHATNodeUnion<WHATElement | WHATAttribute, Element | Attr>;
+export {};

package/dist/adapter/WHAT/kind.d.ts

@@ -0,0 +1,11 @@
+import { UnspecifiedNonXPathNodeKind, XPathNodeKind } from '../interface/XPathNode.ts';
+import { WHATAttribute, WHATDocument, WHATElement, WHATNamespaceDeclaration, WHATNode, WHATParentNode } from './WHATNode.ts';
+type WHATNodeKind = XPathNodeKind | UnspecifiedNonXPathNodeKind;
+export declare const getWHATNodeKind: (node: WHATNode) => WHATNodeKind;
+export declare const isWHATNode: (value: unknown) => value is WHATNode;
+export declare const isWHATDocument: (node: WHATNode) => node is WHATDocument;
+export declare const isWHATElement: (node: WHATNode) => node is WHATElement;
+export declare const isWHATNamespaceDeclaration: (node: Attr | WHATNode) => node is WHATNamespaceDeclaration;
+export declare const isWHATAttribute: (node: Attr | WHATNode) => node is WHATAttribute;
+export declare const isWHATParentNode: (node: WHATNode) => node is WHATParentNode;
+export {};

package/dist/adapter/WHAT/names.d.ts

@@ -0,0 +1,6 @@
+import { WHATNamedNode, WHATNode, WHATProcessingInstruction } from './WHATNode.ts';
+export declare const getWHATNamespaceURI: (node: WHATNamedNode) => string | null;
+export declare const getWHATQualifiedName: (node: WHATNamedNode) => string;
+export declare const getWHATLocalName: (node: WHATNamedNode) => string;
+export declare const getWHATProcessingInstructionName: (node: WHATProcessingInstruction) => string;
+export declare const resolveWHATNamespaceURI: (node: WHATNode, prefix: string | null) => string | null;

package/dist/adapter/WHAT/optimizations.d.ts

@@ -0,0 +1,37 @@
+import { WHATChildNode, WHATElement, WHATNode, WHATParentNode } from './WHATNode.ts';
+/**
+ * @todo optimization, but belongs in values.ts!
+ */
+export declare const getQualifiedNamedWHATAttributeValue: (node: WHATElement, namespaceURI: string | null, localName: string) => string | null;
+/**
+ * @todo optimization, but belongs in values.ts!
+ */
+export declare const getLocalNamedWHATAttributeValue: (node: WHATElement, localName: string) => string | null;
+/**
+ * @todo optimization, but belongs in traversal.ts!
+ */
+export declare const hasLocalNamedWHATAttribute: (node: WHATElement, localName: string) => boolean;
+/**
+ * @todo optimization, but belongs in traversal.ts!
+ */
+export declare const getWHATElementByUniqueId: (node: WHATParentNode, id: string) => WHATElement | null;
+/**
+ * @todo optimization, but belongs in traversal.ts!
+ */
+export declare const getWHATChildrenByLocalName: (node: WHATParentNode, localName: string) => readonly WHATElement[];
+/**
+ * @todo optimization, but belongs in traversal.ts!
+ */
+export declare const getFirstWHATChildNode: (node: WHATNode) => WHATChildNode | null;
+/**
+ * @todo optimization, but belongs in traversal.ts!
+ */
+export declare const getLastWHATChildNode: (node: WHATNode) => WHATChildNode | null;
+/**
+ * @todo optimization, but belongs in traversal.ts!
+ */
+export declare const getFirstChildWHATElement: (node: WHATNode) => WHATElement | null;
+/**
+ * @todo optimization, but belongs in traversal.ts!
+ */
+export declare const getLastChildWHATElement: (node: WHATNode) => WHATElement | null;

package/dist/adapter/WHAT/platform.d.ts

@@ -0,0 +1,6 @@
+interface NodeConstructor {
+    readonly prototype: Node;
+    new (): Node;
+}
+export declare const getNodeConstructor: () => NodeConstructor;
+export {};

package/dist/adapter/WHAT/traversal.d.ts

@@ -0,0 +1,14 @@
+import { DocumentOrderComparison } from '../interface/XPathTraversalAdapter.ts';
+import { WHATAttribute, WHATChildNode, WHATDocument, WHATElement, WHATNamespaceDeclaration, WHATNode, WHATParentNode } from './WHATNode.ts';
+export declare const getContainingWHATDocument: (node: WHATNode) => WHATDocument;
+export declare const getWHATNamespaceDeclarations: (node: WHATNode) => readonly WHATNamespaceDeclaration[];
+export declare const getWHATAttributes: (node: WHATNode) => readonly WHATAttribute[];
+export declare const getWHATParentNode: (node: WHATNode) => WHATParentNode | null;
+export declare const getWHATChildNodes: (node: WHATNode) => readonly WHATChildNode[];
+export declare const getChildWHATElements: (node: WHATNode) => readonly WHATElement[];
+export declare const getPreviousSiblingWHATNode: (node: WHATNode) => WHATChildNode | null;
+export declare const getPreviousSiblingWHATElement: (node: WHATNode) => WHATElement | null;
+export declare const getNextSiblingWHATNode: (node: WHATNode) => WHATChildNode | null;
+export declare const getNextSiblingWHATElement: (node: WHATNode) => WHATElement | null;
+export declare const isDescendantWHATNode: (ancestor: WHATNode, other: WHATNode) => boolean;
+export declare const compareWHATDocumentOrder: (a: WHATNode, b: WHATNode) => DocumentOrderComparison;

package/dist/adapter/WHAT/values.d.ts

@@ -0,0 +1,2 @@
+import { WHATNode } from './WHATNode.ts';
+export declare const getWHATNodeValue: (node: WHATNode) => string;

package/dist/adapter/WHAT/whatDOMAdapter.d.ts

@@ -0,0 +1,5 @@
+import { XPathDOMAdapter } from '../interface/XPathDOMAdapter.ts';
+import { WHATNode } from './WHATNode.ts';
+export interface WHATDOMAdapter extends XPathDOMAdapter<WHATNode> {
+}
+export declare const whatDOMAdapter: WHATDOMAdapter;

package/dist/adapter/defaults.d.ts

@@ -0,0 +1,26 @@
+import { WHATAttribute, WHATChildNode, WHATComment, WHATDocument, WHATElement, WHATNamespaceDeclaration, WHATNode, WHATParentNode, WHATProcessingInstruction, WHATText } from './WHAT/WHATNode.ts';
+import { WHATDOMAdapter } from './WHAT/whatDOMAdapter.ts';
+import { XPathDOMProvider } from './xpathDOMProvider.ts';
+/**
+ * Truly silly type hack so that TypeScript doesn't unwrap the names of Default*
+ * types to their WHAT* equivalent. This is for clarity at usage and reference
+ * sites, internally but especially at the package boundary.
+ */
+type AsDefault<T> = T | (T & {
+    readonly _?: never;
+});
+type DefaultDOMAdapter = AsDefault<WHATDOMAdapter>;
+type DefaultDOMProvider = AsDefault<XPathDOMProvider<WHATNode>>;
+export declare const DEFAULT_DOM_ADAPTER: DefaultDOMAdapter;
+export declare const DEFAULT_DOM_PROVIDER: DefaultDOMProvider;
+export type DefaultDOMAdapterDocument = AsDefault<WHATDocument>;
+export type DefaultDOMAdapterElement = AsDefault<WHATElement>;
+export type DefaultDOMAdapterNamespaceDeclaration = AsDefault<WHATNamespaceDeclaration>;
+export type DefaultDOMAdapterAttr = AsDefault<WHATAttribute>;
+export type DefaultDOMAdapterText = AsDefault<WHATText>;
+export type DefaultDOMAdapterComment = AsDefault<WHATComment>;
+export type DefaultDOMAdapterProcessingInstruction = AsDefault<WHATProcessingInstruction>;
+export type DefaultDOMAdapterNode = AsDefault<WHATNode>;
+export type DefaultDOMAdapterParentNode = AsDefault<WHATParentNode>;
+export type DefaultDOMAdapterChildNode = AsDefault<WHATChildNode>;
+export {};

package/dist/adapter/interface/XPathCustomUnwrappableNode.d.ts

@@ -0,0 +1,55 @@
+import { XPathNode, XPathNodeKindKey } from './XPathNode.ts';
+/**
+ * @see {@link XPathCustomUnwrappableNode}
+ */
+declare const UnwrappedAdapterNode: unique symbol;
+type UnwrappedAdapterNode = typeof UnwrappedAdapterNode;
+/**
+ * **!!! HERE BE DRAGONS !!!**
+ *
+ * Provides type-level support for {@link XPathDOMAdapter} implementations which
+ * operate on representations of {@link XPathNode} outside their control
+ * (typically as provided by either the runtime platform, or by a third party
+ * package). It may not be feasible to assign an {@link XPathNodeKindKey}
+ * property **at runtime**. In turn, this creates a conflict with the
+ * {@link XPathDOMAdapter} and {@link XPathNode} **types**.
+ *
+ * This conflict can be addressed **within** an adapter implementation by
+ * applying type assertions. Example:
+ *
+ * ```ts
+ * interface AdapterDocument extends PlatformDocument, XPathDocument {}
+ *
+ * declare const platformDocument: PlatformDocument;
+ * const adapterDocument: AdapterDocument = platformDocument satisfies PlatformDocument as AdapterDocument;
+ * ```
+ *
+ * Unfortunately, this **also** creates a type-level conflict for consumers of
+ * the adapter, when interacting with other `@getodk/xpath` APIs, such as
+ * {@link Evaluator} or any of its subclasses. There, it would be less than
+ * ideal to require users to perform the same sort of type assertions: the types
+ * are already correct _for their usage_ without such special casting logic.
+ *
+ * The {@link XPathNodeKindKey} property is a type-level implementation detail
+ * **between {@link XPathDOMAdapter} and {@link Evaluator}**, which should not
+ * concern end uers.
+ *
+ * To address this, adapter implementations may also extend their
+ * platform-/third party-provided node types with this custom unwrappable type,
+ * supplying the original base type which is expected from end users. Example:
+ *
+ * ```ts
+ * interface AdapterDocument extends PlatformDocument,
+ *   XPathDocument,
+ *   XPathCustomUnwrappableNode<PlatformDocument> {}
+ * ```
+ *
+ * This directs the end user-facing interfaces to accept the unwrapped type
+ * (`PlatformDocument` in the example above) anywhere the adapter's
+ * {@link XPathNode} representation would otherwise be accepted.
+ */
+export interface XPathCustomUnwrappableNode<T> {
+    readonly [UnwrappedAdapterNode]: T;
+}
+export type UnwrapAdapterNode<T extends XPathNode> = T extends XPathCustomUnwrappableNode<infer U> ? U : Omit<T, XPathNodeKindKey>;
+export {};

package/dist/adapter/interface/XPathDOMAdapter.d.ts

@@ -0,0 +1,16 @@
+import { XPathDOMOptimizableOperations } from './XPathDOMOptimizableOperations.ts';
+import { XPathNameAdapter } from './XPathNameAdapter.ts';
+import { XPathNode } from './XPathNode.ts';
+import { XPathNodeKindAdapter } from './XPathNodeKindAdapter.ts';
+import { XPathTraversalAdapter } from './XPathTraversalAdapter.ts';
+import { XPathValueAdapter } from './XPathValueAdapter.ts';
+export interface XPathDOMAdapter<T extends XPathNode> extends XPathNodeKindAdapter<T>, XPathNameAdapter<T>, XPathValueAdapter<T>, XPathTraversalAdapter<T>, Partial<XPathDOMOptimizableOperations<T>> {
+}
+export type * from './XPathNode.ts';
+export { XPathNodeKindKey } from './XPathNode.ts';
+export type { XPathCustomUnwrappableNode } from './XPathCustomUnwrappableNode.ts';
+export type * from './XPathDOMOptimizableOperations.ts';
+export type * from './XPathNameAdapter.ts';
+export type * from './XPathNodeKindAdapter.ts';
+export type * from './XPathTraversalAdapter.ts';
+export type * from './XPathValueAdapter.ts';

package/dist/adapter/interface/XPathDOMOptimizableOperations.d.ts

@@ -0,0 +1,13 @@
+import { XPathNode } from './XPathNode.ts';
+import { AdapterChildNode, AdapterDocument, AdapterElement, AdapterParentNode } from './XPathNodeKindAdapter.ts';
+export interface XPathDOMOptimizableOperations<T extends XPathNode> {
+    readonly getElementByUniqueId: (node: AdapterDocument<T>, id: string) => AdapterElement<T> | null;
+    readonly getQualifiedNamedAttributeValue: (node: AdapterElement<T>, namespaceURI: string | null, localName: string) => string | null;
+    readonly getLocalNamedAttributeValue: (node: AdapterElement<T>, localName: string) => string | null;
+    readonly hasLocalNamedAttribute: (node: AdapterElement<T>, localName: string) => boolean;
+    readonly getChildrenByLocalName: (node: AdapterParentNode<T>, localName: string) => Iterable<AdapterElement<T>>;
+    readonly getFirstChildNode: (node: T) => AdapterChildNode<T> | null;
+    readonly getFirstChildElement: (node: T) => AdapterElement<T> | null;
+    readonly getLastChildNode: (node: T) => AdapterChildNode<T> | null;
+    readonly getLastChildElement: (node: T) => AdapterElement<T> | null;
+}

package/dist/adapter/interface/XPathNameAdapter.d.ts

@@ -0,0 +1,23 @@
+import { XPathNode } from './XPathNode.ts';
+import { AdapterProcessingInstruction, AdapterQualifiedNamedNode } from './XPathNodeKindAdapter.ts';
+export interface XPathNameAdapter<T extends XPathNode> {
+    readonly getNamespaceURI: (node: AdapterQualifiedNamedNode<T>) => string | null;
+    /**
+     * @todo Confirm usage in the following function implementations:
+     *
+     * - `name` (fn namespace): Should we return the document-defined prefix, or
+     *   resolve it from the node's namespace URI? The WHAT Working Group
+     *   (default) adapter will do the former; downstream usage currently punts on
+     *   this!
+     * - `position` (xf namespace): extends XPath 1.0 spec semantics to support
+     *   lookup of position **among contiguous same-named nodes**. An answer to
+     *   the above question on `fn:name` may or may not impact whether usage of
+     *   this API for that purpose is appropriate.
+     *
+     * If either warrant correction, we'll want to revisit this type as well.
+     */
+    readonly getQualifiedName: (node: AdapterQualifiedNamedNode<T>) => string;
+    readonly getLocalName: (node: AdapterQualifiedNamedNode<T>) => string;
+    readonly getProcessingInstructionName: (node: AdapterProcessingInstruction<T>) => string;
+    readonly resolveNamespaceURI: (node: T, prefix: string | null) => string | null;
+}

package/dist/adapter/interface/XPathNode.d.ts

@@ -0,0 +1,164 @@
+export type XPathDocumentKind = 'document';
+export type XPathElementKind = 'element';
+export type XPathNamespaceDeclarationKind = 'namespace_declaration';
+export type XPathAttributeKind = 'attribute';
+export type XPathTextKind = 'text';
+export type XPathCommentKind = 'comment';
+export type XPathProcessingInstructionKind = 'processing_instruction';
+export type XPathNodeKind = XPathDocumentKind | XPathElementKind | XPathNamespaceDeclarationKind | XPathAttributeKind | XPathTextKind | XPathCommentKind | XPathProcessingInstructionKind;
+export declare const XPathNodeKindKey: unique symbol;
+export type XPathNodeKindKey = typeof XPathNodeKindKey;
+/**
+ * Any representation of a "document" (or "root") node, having semantics
+ * consistent with the
+ * {@link https://www.w3.org/TR/1999/REC-xpath-19991116/#data-model | XPath 1.0 data model},
+ * and as implemented/provided by an {@link XPathDOMAdapter}.
+ *
+ * @todo Since we're intentionally using XPath semantics throughout, should we
+ * consider renaming this `XPathRoot`? If we're going to use "root node" to
+ * refer to this concept, we'll want to (a) be sure we make the change
+ * thoroughly throughout `@getodk/xpath` and (b) think of how we make
+ * corresponding name changes downstream.
+ */
+export interface XPathDocument {
+    readonly [XPathNodeKindKey]: XPathDocumentKind;
+}
+/**
+ * Any representation of an "element" node, having semantics consistent with the
+ * {@link https://www.w3.org/TR/1999/REC-xpath-19991116/#data-model | XPath 1.0 data model},
+ * and as implemented/provided by an {@link XPathDOMAdapter}.
+ */
+export interface XPathElement {
+    readonly [XPathNodeKindKey]: XPathElementKind;
+}
+/**
+ * Any representation of a "namespace declaration" node, having semantics
+ * consistent with the
+ * {@link https://www.w3.org/TR/1999/REC-xpath-19991116/#data-model | XPath 1.0 data model},
+ * and as implemented/provided by an {@link XPathDOMAdapter}.
+ *
+ * Note: in XML syntax, a namespace declaration is defined as a qualified
+ * name/URI value pair, defined on an {@link XPathElement | element}, where:
+ *
+ * 1. The name is in the {@link XMLNS_NAMESPACE_URI | XMLNS namespace}, defined
+ *    in XML as one of:
+ *
+ *     - `xmlns` (representing the default namespace for that element and for
+ *       descendants which do not re-declare a default namespace)
+ *
+ *     - a colon-separated name with an `xmlns` prefix and an arbitrary local
+ *       name suffix (representing a prefix associated with the namespace
+ *       declaration, for that element and for descendants which do not
+ *       re-declare a namespace for that prefix)
+ *
+ * 2. The value is a URI representing the namespace being declared.
+ *
+ * This syntax is textually similar to that of
+ * {@link XPathAttribute | attributes}, but such nodes are **NOT** considered
+ * attributes in XPath semantics. The factor distinguishing namespace
+ * declarations from attributes is the node's name and/or prefix.
+ */
+export interface XPathNamespaceDeclaration {
+    readonly [XPathNodeKindKey]: XPathNamespaceDeclarationKind;
+}
+/**
+ * Any representation of an "attribute" node, having semantics consistent with
+ * the
+ * {@link https://www.w3.org/TR/1999/REC-xpath-19991116/#data-model | XPath 1.0 data model},
+ * and as implemented/provided by an {@link XPathDOMAdapter}.
+ *
+ * Note: XPath semantics distinguish attributes from namespace declarations,
+ * despite their XML syntax similarity.
+ *
+ * @see {@link XPathNamespaceDeclaration} for additional clarification of this
+ * distinction.
+ */
+export interface XPathAttribute {
+    readonly [XPathNodeKindKey]: XPathAttributeKind;
+}
+/**
+ * Any representation of a "text" node, having semantics
+ * consistent with the
+ * {@link https://www.w3.org/TR/1999/REC-xpath-19991116/#data-model | XPath 1.0 data model},
+ * and as implemented/provided by an {@link XPathDOMAdapter}.
+ */
+export interface XPathText {
+    readonly [XPathNodeKindKey]: XPathTextKind;
+}
+/**
+ * Any representation of a "comment" node, having semantics
+ * consistent with the
+ * {@link https://www.w3.org/TR/1999/REC-xpath-19991116/#data-model | XPath 1.0 data model},
+ * and as implemented/provided by an {@link XPathDOMAdapter}.
+ */
+export interface XPathComment {
+    readonly [XPathNodeKindKey]: XPathCommentKind;
+}
+/**
+ * Any representation of a "processing instruction" node, having semantics
+ * consistent with the
+ * {@link https://www.w3.org/TR/1999/REC-xpath-19991116/#data-model | XPath 1.0 data model},
+ * and as implemented/provided by an {@link XPathDOMAdapter}.
+ */
+export interface XPathProcessingInstruction {
+    readonly [XPathNodeKindKey]: XPathProcessingInstructionKind;
+}
+/**
+ * An {@link XPathNode} is a (mostly) opaque type, used generically throughout
+ * `@getodk/xpath` as any {@link XPathDOMAdapter}'s arbitrary node
+ * implementation/representation.
+ *
+ * The `@getodk/xpath` package **DOES NOT** directly access any details of an
+ * {@link XPathNode}, except through access points provided by a
+ * {@link XPathDOMAdapter}.
+ *
+ * While each {@link XPathNode} _type_ specifies a property associated with
+ * {@link XPathNodeKindKey}, `@getodk/xpath` does not even access this property
+ * directly (again, unless that access is implemented by an
+ * {@link XPathDOMAdapter}).
+ *
+ * The key **MAY** be used by an {@link XPathDOMAdapter} in its node
+ * representations, distinguishing their XPath semantic kind as defined in the
+ * types herein; this is **RECOMMENDED**, where possible for a particular
+ * adapter.
+ *
+ * But it is not strictly necessary for an {@link XPathDOMAdapter}
+ * implementation to use the {@link XPathNodeKindKey} for this purpose. The
+ * intent of including the key in these opaque node type definitions is to
+ * provide a clear type-level representation of "any node" (or "any [kind of]
+ * node" for each of its constituent union members), without expressing any
+ * further assumptions about those nodes' structures or capabilities.
+ *
+ * This allows `@getodk/xpath` itself to operate on nodes _in terms of their
+ * XPath semantics_, while otherwise deferring the implementation _of those
+ * semantics_ to {@link XPathDOMAdapter} implementations.
+ */
+export type XPathNode = XPathDocument | XPathElement | XPathNamespaceDeclaration | XPathAttribute | XPathText | XPathComment | XPathProcessingInstruction;
+/**
+ * **HERE BE DRAGONS!**
+ *
+ * In practice, real world XPathEvaluator implementations may produce a
+ * {@link https://www.w3.org/TR/xml/#dtd | Document Type Declaration (DTD)} node
+ * for certain expressions. (Most trivially: common browser implementations will
+ * return a DTD, if present in the context document, for the expression
+ * `/node()`!) Importantly, this behavior is **NOT SUPPORTED** by the XPath 1.0
+ * specification.
+ *
+ * We provide this type as an accommodation for {@link XPathDOMAdapter}
+ * implementations which opt to support this common-but-unspecified behavior. It
+ * is intentionally distinct from the other members of {@link XPathNodeKind}, in
+ * order to convey that:
+ *
+ * 1. If an adapter implementation produces a node associated with this kind, it
+ *    will not be regarded as any of the node kinds explicitly supported by
+ *    XPath.
+ *
+ * 2. Following from that: nodes of this kind cannot be accessed by any
+ *    (implicit or explicit) XPath syntax which should produce a node type more
+ *    specific than the `node()`
+ *    {@link https://www.w3.org/TR/1999/REC-xpath-19991116/#NT-NodeTest | NodeTest}
+ *    sub-expression.
+ *
+ * 3. Adapters implementing this node kind should **USE WITH CAUTION**!
+ */
+export type UnspecifiedNonXPathNodeKind = 'UNSPECIFIED_NON_XPATH_NODE';

package/dist/adapter/interface/XPathNodeKindAdapter.d.ts

@@ -0,0 +1,15 @@
+import { UnspecifiedNonXPathNodeKind, XPathAttribute, XPathComment, XPathDocument, XPathElement, XPathNamespaceDeclaration, XPathNode, XPathNodeKind, XPathProcessingInstruction, XPathText } from './XPathNode.ts';
+export type AdapterDocument<T extends XPathNode> = Extract<T, XPathDocument>;
+export type AdapterElement<T extends XPathNode> = Extract<T, XPathElement>;
+export type AdapterNamespaceDeclaration<T extends XPathNode> = Extract<T, XPathNamespaceDeclaration>;
+export type AdapterAttribute<T extends XPathNode> = Extract<T, XPathAttribute>;
+export type AdapterText<T extends XPathNode> = Extract<T, XPathText>;
+export type AdapterComment<T extends XPathNode> = Extract<T, XPathComment>;
+export type AdapterProcessingInstruction<T extends XPathNode> = Extract<T, XPathProcessingInstruction>;
+export type AdapterParentNode<T extends XPathNode> = AdapterDocument<T> | AdapterElement<T>;
+export type AdapterChildNode<T extends XPathNode> = AdapterElement<T> | AdapterText<T> | AdapterComment<T> | AdapterProcessingInstruction<T>;
+export type AdapterQualifiedNamedNode<T extends XPathNode> = AdapterElement<T> | AdapterAttribute<T>;
+export interface XPathNodeKindAdapter<T extends XPathNode> {
+    readonly isXPathNode: (value: unknown) => value is T;
+    readonly getNodeKind: (node: T) => XPathNodeKind | UnspecifiedNonXPathNodeKind;
+}

package/dist/adapter/interface/XPathTraversalAdapter.d.ts

@@ -0,0 +1,38 @@
+import { XPathNode } from './XPathNode.ts';
+import { AdapterAttribute, AdapterChildNode, AdapterDocument, AdapterElement, AdapterNamespaceDeclaration, AdapterParentNode } from './XPathNodeKindAdapter.ts';
+export type DocumentOrderComparison = -1 | 0 | 1;
+export interface XPathTraversalAdapter<T extends XPathNode> {
+    /**
+     * Gets the document containing {@link node}.
+     *
+     * Note: implementations are expected to operate on a fully "attached" tree of
+     * nodes, i.e. where any particular descendant node can ultimately be
+     * traversed up to the document node produced by this method. In that sense,
+     * implementations are also expected to provide this method as an explicit,
+     * mandatory optimization of that otherwise implicit expectation.
+     */
+    readonly getContainingDocument: (node: T) => AdapterDocument<T>;
+    readonly getNamespaceDeclarations: (node: T) => Iterable<AdapterNamespaceDeclaration<T>>;
+    readonly getAttributes: (node: T) => Iterable<AdapterAttribute<T>>;
+    readonly getParentNode: (node: T) => AdapterParentNode<T> | null;
+    readonly getChildNodes: (node: T) => Iterable<AdapterChildNode<T>>;
+    readonly getChildElements: (node: T) => Iterable<AdapterElement<T>>;
+    readonly getPreviousSiblingNode: (node: T) => AdapterChildNode<T> | null;
+    readonly getPreviousSiblingElement: (node: T) => AdapterElement<T> | null;
+    readonly getNextSiblingNode: (node: T) => AdapterChildNode<T> | null;
+    readonly getNextSiblingElement: (node: T) => AdapterElement<T> | null;
+    /**
+     * @todo Not entirely sure this is a "traversal" API! It may use traversal to
+     * produce the result? It doesn't really belong anywhere else, and unlike
+     * values it doesn't especially feel like it warrants a separate
+     * sub-interface namespace.
+     */
+    readonly compareDocumentOrder: (a: T, b: T) => DocumentOrderComparison;
+    /**
+     * Determines if {@link node} is a descendant of {@link ancestor}.
+     *
+     * @todo The parameter names are doing all of the self-documentation work
+     * here. Consider a better name for this!
+     */
+    readonly isDescendantNode: (ancestor: T, node: T) => boolean;
+}

package/dist/adapter/interface/XPathValueAdapter.d.ts

@@ -0,0 +1,9 @@
+import { XPathNode } from './XPathNode.ts';
+/**
+ * @todo Allow adapters to implement (optional) support for non-string types,
+ * e.g. when the adapter's node representation already implements the type with
+ * the same semantics.
+ */
+export interface XPathValueAdapter<T extends XPathNode> {
+    readonly getNodeValue: (node: T) => string;
+}

package/dist/adapter/xpathDOMProvider.d.ts

@@ -0,0 +1,80 @@
+import { XPathDOMAdapter } from './interface/XPathDOMAdapter.ts';
+import { XPathDOMOptimizableOperations } from './interface/XPathDOMOptimizableOperations.ts';
+import { XPathNode } from './interface/XPathNode.ts';
+import { AdapterAttribute, AdapterComment, AdapterDocument, AdapterElement, AdapterNamespaceDeclaration, AdapterParentNode, AdapterProcessingInstruction, AdapterQualifiedNamedNode, AdapterText } from './interface/XPathNodeKindAdapter.ts';
+type AssertXPathNode<T extends XPathNode> = <U>(value: U, message?: string) => asserts value is Extract<U, T>;
+type AssertParentNode<T extends XPathNode> = <U>(value: U, message?: string) => asserts value is Extract<U, AdapterParentNode<T>>;
+type NodeKindPredicate<T extends XPathNode, U extends T> = (node: T) => node is U;
+/**
+ * Provides frequently used type guards for narrowing an
+ * {@link XPathDOMAdapter}'s node representation to either:
+ *
+ * - A valid context node (as provided to evaluation API call sites)
+ * - Any one distinct semantic kind of XPath node
+ * - Useful unions of any subset thereof
+ */
+interface NodeKindGuards<T extends XPathNode> {
+    readonly assertXPathNode: AssertXPathNode<T>;
+    readonly assertParentNode: AssertParentNode<T>;
+    readonly isDocument: NodeKindPredicate<T, AdapterDocument<T>>;
+    readonly isElement: NodeKindPredicate<T, AdapterElement<T>>;
+    readonly isNamespaceDeclaration: NodeKindPredicate<T, AdapterNamespaceDeclaration<T>>;
+    readonly isAttribute: NodeKindPredicate<T, AdapterAttribute<T>>;
+    readonly isText: NodeKindPredicate<T, AdapterText<T>>;
+    readonly isComment: NodeKindPredicate<T, AdapterComment<T>>;
+    readonly isProcessingInstruction: NodeKindPredicate<T, AdapterProcessingInstruction<T>>;
+    readonly isParentNode: NodeKindPredicate<T, AdapterParentNode<T>>;
+    readonly isQualifiedNamedNode: NodeKindPredicate<T, AdapterQualifiedNamedNode<T>>;
+}
+type IterableNodeFilter<T extends XPathNode, U extends T> = (nodes: Iterable<T>) => Iterable<U>;
+/**
+ * Provides frequently used operations, such as filtering and sorting, on
+ * {@link Iterable} sequences of an {@link XPathDOMAdapter}'s node
+ * representation.
+ */
+interface IterableOperations<T extends XPathNode> {
+    readonly filterAttributes: IterableNodeFilter<T, AdapterAttribute<T>>;
+    readonly filterQualifiedNamedNodes: IterableNodeFilter<T, AdapterQualifiedNamedNode<T>>;
+    readonly filterComments: IterableNodeFilter<T, AdapterComment<T>>;
+    readonly filterNamespaceDeclarations: IterableNodeFilter<T, AdapterNamespaceDeclaration<T>>;
+    readonly filterProcessingInstructions: IterableNodeFilter<T, AdapterProcessingInstruction<T>>;
+    readonly filterTextNodes: IterableNodeFilter<T, AdapterText<T>>;
+    readonly sortInDocumentOrder: (nodes: Iterable<T>) => readonly T[];
+}
+/**
+ * Omitting XPathDOMOptimizableOperations keys here allows them to be made
+ * non-optional, without then repeating the exact same properties and their
+ * exact same signatures inline...
+ */
+type OmitOptionalOptimizableOperations<T> = Omit<T, keyof XPathDOMOptimizableOperations<XPathNode>>;
+/**
+ * An {@link XPathDOMProvider} is a superset of the {@link XPathDOMAdapter}
+ * interface. As such, a derived provider is assignable anywhere an adapter (or
+ * subset thereof) is expected. We assign this symbol as a means to check
+ * whether the adapter passed to {@link xpathDOMProvider} is already a derived
+ * provider. Checking for the symbol (via {@link isXPathDOMProvider}) is
+ * sufficient, because this symbol is module local and therefore is only ever
+ * assigned as part of a first pass through {@link xpathDOMProvider}.
+ *
+ * While repeated derivation of a DOM provider is not especially likely, and
+ * would probably not be particularly expensive even if it did occur, _this is
+ * not just an optimization!_ A few other `@getodk/xpath` internals depend on an
+ * **identity check** of a given {@link XPathDOMProvider} object as part of
+ * broader guard/assertion logic.
+ *
+ * (An alternate approach to achieve the same thing would involve assigning both
+ * the adapter and the provider as keys e.g. in an {@link UpsertableMap} cache,
+ * but that would exaggerate the performance consideration, obscuring the intent
+ * to preserve object identity.)
+ */
+declare const DERIVED_DOM_PROVIDER: unique symbol;
+/**
+ * @see {@link DERIVED_DOM_PROVIDER}
+ */
+interface DerivedDOMProvider {
+    readonly [DERIVED_DOM_PROVIDER]: true;
+}
+export interface XPathDOMProvider<T extends XPathNode> extends OmitOptionalOptimizableOperations<XPathDOMAdapter<T>>, NodeKindGuards<T>, IterableOperations<T>, XPathDOMOptimizableOperations<T>, DerivedDOMProvider {
+}
+export declare const xpathDOMProvider: <T extends XPathNode>(adapter: XPathDOMAdapter<T>) => XPathDOMProvider<T>;
+export {};

package/dist/context/Context.d.ts

@@ -1,14 +1,16 @@
 import { Temporal } from '@js-temporal/polyfill';
+import { XPathNode } from '../adapter/interface/XPathDOMAdapter.ts';
+import { AdapterDocument, AdapterParentNode } from '../adapter/interface/XPathNodeKindAdapter.ts';
+import { XPathDOMProvider } from '../adapter/xpathDOMProvider.ts';
 import { Evaluator } from '../evaluator/Evaluator.ts';
 import { FunctionLibraryCollection } from '../evaluator/functions/FunctionLibraryCollection.ts';
-import { ContextDocument, ContextNode, ContextParentNode } from '../lib/dom/types.ts';
-import { XPathNamespaceResolverObject } from '../shared/interface.ts';
-
+import { NamespaceResolver } from '../evaluator/NamespaceResolver.ts';
 /**
  * The context in which any XPath expression *or sub-expression* is evaluated.
  */
-export interface Context {
-    readonly evaluator: Evaluator;
+export interface Context<T extends XPathNode> {
+    readonly evaluator: Evaluator<T>;
+    readonly domProvider: XPathDOMProvider<T>;
     /**
      * The `contextNode` as specified at the {@link Evaluator.evaluate} call site.
      * This value is to remain constant for the entire scope of an evaluation.
@@ -16,13 +18,13 @@ export interface Context {
      * 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>;
+    readonly evaluationContextNode: T;
+    readonly contextDocument: AdapterDocument<T>;
+    readonly rootNode: AdapterParentNode<T>;
+    readonly contextNodes: Iterable<T>;
     contextPosition(): number;
     contextSize(): number;
     readonly functions: FunctionLibraryCollection;
-    readonly namespaceResolver: XPathNamespaceResolverObject;
+    readonly namespaceResolver: NamespaceResolver<T>;
     readonly timeZone: Temporal.TimeZone;
 }