@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/integration/xpath/adapter/XFormsXPathNode.ts

@@ -0,0 +1,126 @@
+import type {
+	XPathAttributeKind,
+	XPathCommentKind,
+	XPathDocumentKind,
+	XPathElementKind,
+	XPathTextKind,
+} from '@getodk/xpath';
+import { XPathNodeKindKey } from '@getodk/xpath';
+
+const XFORMS_XPATH_NODE_RANGE_BRAND = Symbol('XFORMS_XPATH_NODE_RANGE_BRAND');
+
+/**
+ * To be used with any engine representation of a "range" of contiguous child
+ * nodes (also somewhat analogous to a DOM "fragment"). This mapping is
+ * conceptually disjoint, but serves an important purpose:
+ *
+ * - While such a "range" may increase the hierarchical depth of an
+ *   engine-internal representation, it **DOES NOT** contribute the same
+ *   hierarchy in XPath evaluation semantics.
+ * - Such a "range" may be treated as a distinct context node for evaluating an
+ *   expression. This most cleanly maps to XPath's comment semantics in that it
+ *   allows the "range" to have a clear document position (hierarchically a
+ *   child of its parent element; sequentially a sibling to that parent's other
+ *   child nodes).
+ *
+ * (Note: while this is phrased as an abstract concept, it is intended to
+ * correspond directly to the engine's "repeat range" concept. The specific type
+ * is not referenced here because they have an inverse relationship in the
+ * module/type graph.)
+ */
+// prettier-ignore
+export type XFormsXPathNodeRangeKind =
+	& 'comment'
+	& { readonly [XFORMS_XPATH_NODE_RANGE_BRAND]: true };
+
+export const XFORMS_XPATH_NODE_RANGE_KIND = 'comment' as XFormsXPathNodeRangeKind;
+
+// prettier-ignore
+export type XFormsXPathNodeKind =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| XPathDocumentKind
+	| XFormsXPathNodeRangeKind
+	| XPathElementKind
+	| XPathAttributeKind
+	| XPathTextKind
+	| XPathCommentKind;
+
+export interface XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XFormsXPathNodeKind;
+	readonly rootDocument: XFormsXPathDocument;
+	readonly root: XFormsXPathElement;
+
+	getXPathChildNodes(this: XFormsXPathNode): readonly XFormsXPathDescendantNode[];
+	getXPathValue(this: XFormsXPathNode): string;
+}
+
+export interface XFormsXPathDocument extends XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XPathDocumentKind;
+}
+
+export interface XFormsXPathElement extends XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XPathElementKind;
+}
+
+/**
+ * @see {@link XFormsXPathNodeRangeKind}
+ */
+export interface XFormsXPathNodeRange extends XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XFormsXPathNodeRangeKind;
+}
+
+export interface XFormsXPathAttribute extends XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XPathAttributeKind;
+}
+
+export interface XFormsXPathText extends XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XPathTextKind;
+}
+
+export interface XFormsXPathComment extends XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XPathCommentKind;
+}
+
+// prettier-ignore
+export type XPathNamedNodeKind =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| XPathElementKind
+	| XPathAttributeKind;
+
+export interface XFormsXPathNamedNode extends XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XPathNamedNodeKind;
+}
+
+// prettier-ignore
+export type XFormsXPathDescendantNodeKind =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| XFormsXPathNodeRangeKind
+	| XPathElementKind
+	| XPathTextKind
+	| XPathCommentKind;
+
+export interface XFormsXPathDescendantNode extends XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XFormsXPathDescendantNodeKind;
+}
+
+// prettier-ignore
+export type XFormsXPathPrimaryInstanceNodeKind =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| XPathDocumentKind
+	| XFormsXPathNodeRangeKind
+	| XPathElementKind
+	| XPathTextKind;
+
+export interface XFormsXPathPrimaryInstanceNode extends XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XFormsXPathPrimaryInstanceNodeKind;
+}
+
+// prettier-ignore
+export type XFormsXPathPrimaryInstanceDescendantNodeKind =
+	| XFormsXPathNodeRangeKind
+	| XPathElementKind
+	| XPathTextKind;
+
+export interface XFormsXPathPrimaryInstanceDescendantNode extends XFormsXPathNode {
+	readonly [XPathNodeKindKey]: XFormsXPathPrimaryInstanceDescendantNodeKind;
+}

package/src/integration/xpath/adapter/engineDOMAdapter.ts

@@ -0,0 +1,57 @@
+import type { XPathDOMAdapter } from '@getodk/xpath';
+import type { EngineXPathNode } from './kind.ts';
+import { getEngineXPathNodeKind, isEngineXPathNode } from './kind.ts';
+import {
+	getEngineProcessingInstructionName,
+	getEngineXPathNodeLocalName,
+	getEngineXPathNodeNamespaceURI,
+	getEngineXPathNodeQualifiedName,
+	resolveEngineXPathNodeNamespaceURI,
+} from './names.ts';
+import {
+	compareDocumentOrder,
+	getChildElements,
+	getChildNodes,
+	getContainingEngineXPathDocument,
+	getEngineXPathAttributes,
+	getNamespaceDeclarations,
+	getNextSiblingElement,
+	getNextSiblingNode,
+	getParentNode,
+	getPreviousSiblingElement,
+	getPreviousSiblingNode,
+	isDescendantNode,
+} from './traversal.ts';
+import { getEngineXPathNodeValue } from './values.ts';
+
+export interface EngineDOMAdapter extends XPathDOMAdapter<EngineXPathNode> {}
+
+export const engineDOMAdapter: EngineDOMAdapter = {
+	// XPathNodeKindAdapter
+	getNodeKind: getEngineXPathNodeKind,
+	isXPathNode: isEngineXPathNode,
+
+	// XPathNameAdapter
+	getLocalName: getEngineXPathNodeLocalName,
+	getNamespaceURI: getEngineXPathNodeNamespaceURI,
+	getQualifiedName: getEngineXPathNodeQualifiedName,
+	getProcessingInstructionName: getEngineProcessingInstructionName,
+	resolveNamespaceURI: resolveEngineXPathNodeNamespaceURI,
+
+	// XPathValueAdapter
+	getNodeValue: getEngineXPathNodeValue,
+
+	// XPathTraversalAdapter
+	compareDocumentOrder,
+	getAttributes: getEngineXPathAttributes,
+	getChildElements: getChildElements,
+	getChildNodes: getChildNodes,
+	getContainingDocument: getContainingEngineXPathDocument,
+	getNamespaceDeclarations: getNamespaceDeclarations,
+	getNextSiblingElement: getNextSiblingElement,
+	getNextSiblingNode: getNextSiblingNode,
+	getParentNode: getParentNode,
+	getPreviousSiblingElement: getPreviousSiblingElement,
+	getPreviousSiblingNode: getPreviousSiblingNode,
+	isDescendantNode: isDescendantNode,
+};

package/src/integration/xpath/adapter/kind.ts

@@ -0,0 +1,114 @@
+import type { XPathNodeKind } from '@getodk/xpath';
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type {
+	AnyChildNode,
+	AnyNode,
+	AnyParentNode,
+	AnyValueNode,
+} from '../../../instance/hierarchy.ts';
+import type { ValueContext } from '../../../instance/internal-api/ValueContext.ts';
+import type { PrimaryInstance } from '../../../instance/PrimaryInstance.ts';
+import type { ItextTranslationDefinition } from '../../../parse/model/ItextTranslation/ItextTranslationDefinition.ts';
+import type { ItextTranslationRootDefinition } from '../../../parse/model/ItextTranslation/ItextTranslationRootDefinition.ts';
+import type { SecondaryInstanceDefinition } from '../../../parse/model/SecondaryInstance/SecondaryInstanceDefinition.ts';
+import type { SecondaryInstanceRootDefinition } from '../../../parse/model/SecondaryInstance/SecondaryInstanceRootDefinition.ts';
+import type { StaticAttribute } from '../static-dom/StaticAttribute.ts';
+import type { StaticDocument } from '../static-dom/StaticDocument.ts';
+import type { StaticElement } from '../static-dom/StaticElement.ts';
+import type { StaticText } from '../static-dom/StaticText.ts';
+import type {
+	XFormsXPathComment,
+	XFormsXPathDocument,
+	XFormsXPathElement,
+	XFormsXPathPrimaryInstanceNode,
+} from './XFormsXPathNode.ts';
+
+export type PrimaryInstanceXPathNode = Extract<AnyNode, XFormsXPathPrimaryInstanceNode>;
+
+export type PrimaryInstanceXPathElement = Extract<AnyChildNode, XFormsXPathElement>;
+
+export type PrimaryInstanceXPathComment = Extract<AnyChildNode, XFormsXPathComment>;
+
+// prettier-ignore
+export type PrimaryInstanceXPathChildNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| PrimaryInstanceXPathElement
+	| PrimaryInstanceXPathComment;
+
+// prettier-ignore
+export type PrimaryInstanceXPathValueElement<Value> =
+	& AnyValueNode
+	& ValueContext<Value>
+	& XFormsXPathElement;
+
+// prettier-ignore
+export type EngineXPathDocument =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| PrimaryInstance
+	| ItextTranslationDefinition
+	| SecondaryInstanceDefinition
+	| StaticDocument;
+
+// prettier-ignore
+export type EngineXPathElement =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| PrimaryInstanceXPathElement
+	| ItextTranslationRootDefinition
+	| SecondaryInstanceRootDefinition
+	| StaticElement;
+
+// prettier-ignore
+export type EngineXPathComment =
+	| PrimaryInstanceXPathComment;
+
+// Giving this a type alias anticipates eventually implementing attributes
+// in primary instance state as well
+export type EngineXPathAttribute = StaticAttribute;
+
+export type EngineXPathText = StaticText;
+
+// prettier-ignore
+export type XFormsXPathChildNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| EngineXPathElement
+	| EngineXPathText
+	| EngineXPathComment;
+
+// prettier-ignore
+type XPathAdapterParentNode =
+	| XFormsXPathDocument
+	| XFormsXPathElement;
+
+type PrimaryInstanceXPathParentNode = Extract<AnyParentNode, XPathAdapterParentNode>;
+
+// prettier-ignore
+export type EngineXPathParentNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| PrimaryInstanceXPathParentNode
+	| ItextTranslationDefinition
+	| SecondaryInstanceDefinition
+	| ItextTranslationRootDefinition
+	| SecondaryInstanceRootDefinition
+	| StaticDocument
+	| StaticElement;
+
+// prettier-ignore
+export type EngineXPathNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| EngineXPathDocument
+	| EngineXPathElement
+	| EngineXPathAttribute
+	| EngineXPathText
+	| EngineXPathComment;
+
+export const isEngineXPathNode = (value: unknown): value is EngineXPathNode => {
+	return typeof value === 'object' && value != null && XPathNodeKindKey in value;
+};
+
+export const getEngineXPathNodeKind = (node: EngineXPathNode): XPathNodeKind => {
+	return node[XPathNodeKindKey];
+};
+
+export const isEngineXPathElement = (node: EngineXPathNode): node is EngineXPathElement => {
+	return getEngineXPathNodeKind(node) === 'element';
+};

package/src/integration/xpath/adapter/names.ts

@@ -0,0 +1,148 @@
+import {
+	ENKETO_NAMESPACE_URI,
+	ENKETO_PREFIX,
+	FN_NAMESPACE_URI,
+	FN_PREFIX,
+	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,
+} from '@getodk/common/constants/xmlns.ts';
+import { XPathFunctionalityNotSupportedError } from '../../../error/XPathFunctionalityNotSupportedError.ts';
+import type { AnyStaticNode } from '../static-dom/StaticNode.ts';
+import type { EngineXPathNode } from './kind.ts';
+
+export const getEngineXPathNodeNamespaceURI = (node: EngineXPathNode): string | null => {
+	switch (node.nodeType) {
+		case 'primary-instance':
+		case 'static-document':
+		case 'static-text':
+		case 'repeat-range:controlled':
+		case 'repeat-range:uncontrolled':
+			return null;
+
+		case 'static-attribute':
+		case 'static-element':
+			return node.qualifiedName.namespaceURI?.href ?? null;
+
+		default:
+			return node.definition.qualifiedName.namespaceURI?.href ?? null;
+	}
+};
+
+export const getEngineXPathNodeQualifiedName = (node: EngineXPathNode): string => {
+	switch (node.nodeType) {
+		case 'static-attribute':
+		case 'static-element':
+			return node.qualifiedName.getPrefixedName();
+
+		case 'static-document':
+		case 'static-text':
+			return '';
+
+		default:
+			return node.definition.qualifiedName.getPrefixedName();
+	}
+};
+
+export const getEngineXPathNodeLocalName = (node: EngineXPathNode): string => {
+	switch (node.nodeType) {
+		case 'static-attribute':
+		case 'static-element':
+			return node.qualifiedName.localName;
+
+		case 'static-document':
+		case 'static-text':
+			return '';
+
+		default:
+			return node.definition.qualifiedName.localName;
+	}
+};
+
+export const getEngineProcessingInstructionName =
+	XPathFunctionalityNotSupportedError.createStubImplementation('processing-instruction');
+
+/**
+ * @todo in most cases we should not have **custom** namespace resolution from a
+ * static node (e.g. external secondary instance, itext translation) context.
+ * The main exception to that would be _XML external secondary instances_, which
+ * of course can declare arbitrary namespaces on any arbitrary subtree, just
+ * like a form definition's XML. In all other cases, we'd want to resolve a
+ * prefix here from the _primary instance_ context. However, we don't (yet) have
+ * access to the primary instance context from a static node. So we currently
+ * fall back to the previous (incomplete/potentially wrong) default mapping.
+ *
+ * Note that this is relatively safe for the general case, and only potentially
+ * wrong for:
+ *
+ * 1. Forms authored as XML, with arbitrary/non-default namespace declarations
+ * 2. XML external secondary instances, also with arbitrary/non-default
+ *    namespace declarations
+ */
+const resolveNamespaceURIFromStaticNodeContext = (_: AnyStaticNode, prefix: string | null) => {
+	switch (prefix) {
+		case null:
+			return XFORMS_NAMESPACE_URI;
+
+		case ENKETO_PREFIX:
+			return ENKETO_NAMESPACE_URI;
+
+		case FN_PREFIX:
+			return FN_NAMESPACE_URI;
+
+		case HTML_PREFIX:
+			return XHTML_NAMESPACE_URI;
+
+		case JAVAROSA_PREFIX:
+			return JAVAROSA_NAMESPACE_URI;
+
+		case ODK_PREFIX:
+			return ODK_NAMESPACE_URI;
+
+		case OPENROSA_XFORMS_PREFIX:
+			return OPENROSA_XFORMS_NAMESPACE_URI;
+
+		case XFORMS_PREFIX:
+			return XFORMS_NAMESPACE_URI;
+
+		default:
+			return null;
+	}
+};
+
+export const resolveEngineXPathNodeNamespaceURI = (
+	node: EngineXPathNode,
+	prefix: string | null
+): string | null => {
+	switch (node.nodeType) {
+		case 'static-attribute':
+		case 'static-document':
+		case 'static-element':
+		case 'static-text':
+			return resolveNamespaceURIFromStaticNodeContext(node, prefix);
+
+		case 'group':
+		case 'input':
+		case 'model-value':
+		case 'note':
+		case 'primary-instance':
+		case 'range':
+		case 'rank':
+		case 'repeat-instance':
+		case 'repeat-range:controlled':
+		case 'repeat-range:uncontrolled':
+		case 'root':
+		case 'select':
+		case 'subtree':
+		case 'trigger':
+		case 'upload':
+			return node.definition.namespaceDeclarations.get(prefix)?.declaredURI?.href ?? null;
+	}
+};

package/src/integration/xpath/adapter/traversal.ts

@@ -0,0 +1,229 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { ErrorProductionDesignPendingError } from '../../../error/ErrorProductionDesignPendingError.ts';
+import { XPathFunctionalityPendingError } from '../../../error/XPathFunctionalityPendingError.ts';
+import type { AnyNode } from '../../../instance/hierarchy.ts';
+import type { AnyStaticNode, StaticParentNode } from '../static-dom/StaticNode.ts';
+import type {
+	EngineXPathAttribute,
+	EngineXPathDocument,
+	EngineXPathElement,
+	EngineXPathNode,
+	EngineXPathParentNode,
+	PrimaryInstanceXPathChildNode,
+	XFormsXPathChildNode,
+} from './kind.ts';
+import { isEngineXPathElement } from './kind.ts';
+
+export const getContainingEngineXPathDocument = (node: EngineXPathNode): EngineXPathDocument => {
+	return node.rootDocument;
+};
+
+export const getEngineXPathAttributes = (node: EngineXPathNode): Iterable<EngineXPathAttribute> => {
+	if (node.nodeType === 'static-element') {
+		return node.attributes;
+	}
+
+	return [];
+};
+
+/**
+ * @todo We've now laid most of the groundwork necessary to implement this
+ * properly. At time of writing it has still been deferred because:
+ *
+ * 1. The scope of changes enabling it is already a fairly large yak shave.
+ * 2. It is only used to support XPath LocationPath Steps whose AxisName is
+ *    `namespace`. If we _ever_ support this, it would probably be for extremely
+ *    niche use cases!
+ *
+ * @todo Since we've consciously deferred implementing this (twice now!), should
+ * it throw? It might be nice to be alerted if the assumptions in point 2 above
+ * are somehow wrong (or become wrong).
+ */
+export const getNamespaceDeclarations = (): Iterable<never> => [];
+
+export const getParentNode = (node: EngineXPathNode): EngineXPathParentNode | null => {
+	if (node.nodeType === 'repeat-instance') {
+		return node.parent.parent;
+	}
+
+	return node.parent;
+};
+
+export const getChildNodes = (node: EngineXPathNode): readonly XFormsXPathChildNode[] => {
+	return node.getXPathChildNodes();
+};
+
+export const getChildElements = (node: EngineXPathNode): readonly EngineXPathElement[] => {
+	return getChildNodes(node).filter(isEngineXPathElement);
+};
+
+export const getPreviousSiblingNode = (node: EngineXPathNode): XFormsXPathChildNode | null => {
+	const parent = getParentNode(node);
+
+	if (parent == null) {
+		return null;
+	}
+
+	let previous: EngineXPathNode | null = null;
+
+	for (const child of getChildNodes(parent)) {
+		if (child === node) {
+			return previous;
+		}
+
+		previous = child;
+	}
+
+	return null;
+};
+
+export const getPreviousSiblingElement = (node: EngineXPathNode): EngineXPathElement | null => {
+	const parent = getParentNode(node);
+
+	if (parent == null) {
+		return null;
+	}
+
+	let previous: EngineXPathElement | null = null;
+
+	for (const child of getChildNodes(parent)) {
+		if (child === node) {
+			return previous;
+		}
+
+		if (isEngineXPathElement(child)) {
+			previous = child;
+		}
+	}
+
+	return null;
+};
+
+export const getNextSiblingNode = (node: EngineXPathNode): XFormsXPathChildNode | null => {
+	const parent = getParentNode(node);
+
+	if (parent == null) {
+		return null;
+	}
+
+	let visitedCurrent = false;
+
+	for (const child of getChildNodes(parent)) {
+		if (child === node) {
+			visitedCurrent = true;
+		} else if (visitedCurrent) {
+			return child;
+		}
+	}
+
+	return null;
+};
+
+export const getNextSiblingElement = (node: EngineXPathNode): EngineXPathElement | null => {
+	const parent = getParentNode(node);
+
+	if (parent == null) {
+		return null;
+	}
+
+	let visitedCurrent = false;
+
+	for (const child of getChildNodes(parent)) {
+		if (child === node) {
+			visitedCurrent = true;
+		} else if (visitedCurrent && isEngineXPathElement(child)) {
+			return child;
+		}
+	}
+
+	return null;
+};
+
+const isPrimaryInstanceChildNode = (
+	node: EngineXPathNode
+): node is PrimaryInstanceXPathChildNode => {
+	switch (node.nodeType) {
+		case 'primary-instance':
+		case 'static-attribute':
+		case 'static-element':
+		case 'static-text':
+			return false;
+
+		default:
+			return true;
+	}
+};
+
+const primaryInstanceElementContains = (ancestor: AnyNode, other: AnyNode): boolean => {
+	if (other === ancestor) {
+		return true;
+	}
+
+	const { parent, root } = other;
+
+	if (parent == null || parent === root) {
+		return false;
+	}
+
+	return primaryInstanceElementContains(ancestor, parent);
+};
+
+const staticParentNodeContains = (ancestor: StaticParentNode, other: AnyStaticNode): boolean => {
+	if (ancestor === other) {
+		return false;
+	}
+
+	const { parent } = other;
+
+	if (parent == null) {
+		return false;
+	}
+
+	return staticParentNodeContains(ancestor, parent);
+};
+
+export const isDescendantNode = (ancestor: EngineXPathNode, other: EngineXPathNode) => {
+	// TODO: "descendant" semantics != "contains" semantics
+	if (ancestor === other) {
+		return true;
+	}
+
+	if (ancestor.nodeType === 'primary-instance') {
+		return isPrimaryInstanceChildNode(other);
+	}
+
+	if (other.nodeType === 'primary-instance') {
+		// TODO: in the event this does somehow occur, this is not the kind of error
+		// messaging we want to surface to users! It is, however, exactly the kind
+		// of messaging we want to surface to us.
+		throw new ErrorProductionDesignPendingError(
+			'Exhaustive check failed: comparing hierarchy of two primary instance documents. It is unclear how this could ever occur. If it has, something may have gone horribly wrong!'
+		);
+	}
+
+	if (isPrimaryInstanceChildNode(ancestor)) {
+		return isPrimaryInstanceChildNode(other) && primaryInstanceElementContains(ancestor, other);
+	}
+
+	if (isPrimaryInstanceChildNode(other)) {
+		return false;
+	}
+
+	switch (ancestor.nodeType) {
+		case 'static-attribute':
+		case 'static-text':
+			return false;
+
+		case 'static-document':
+		case 'static-element':
+			break;
+
+		default:
+			throw new UnreachableError(ancestor);
+	}
+
+	return staticParentNodeContains(ancestor, other);
+};
+
+export const compareDocumentOrder =
+	XPathFunctionalityPendingError.createStubImplementation('compareDocumentOrder');

package/src/integration/xpath/adapter/values.ts

@@ -0,0 +1,5 @@
+import type { EngineXPathNode } from './kind.ts';
+
+export const getEngineXPathNodeValue = (node: EngineXPathNode): string => {
+	return node.getXPathValue();
+};