@getodk/xforms-engine 0.1.0

package/src/lib/xpath/analysis.ts

@@ -0,0 +1,241 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError';
+import { expressionParser } from '@getodk/xpath/expressionParser.js';
+import type {
+	AbsoluteLocationPathNode,
+	AnyBinaryExprNode,
+	AnySyntaxNode,
+	FilterPathExprNode,
+	LocalPartNode,
+	PrefixedNameNode,
+	RelativeLocationPathNode,
+	UnprefixedNameNode,
+} from '@getodk/xpath/static/grammar/SyntaxNode.js';
+import type { AnyBinaryExprType } from '@getodk/xpath/static/grammar/type-names.js';
+
+export type SingleChildNode = Extract<
+	AnySyntaxNode,
+	{ readonly children: readonly [AnySyntaxNode] }
+>;
+
+const isSingleNodeChild = (node: AnySyntaxNode): node is SingleChildNode => {
+	return node.childCount === 1;
+};
+
+const binaryExprNodeTypes = new Set<AnyBinaryExprType>([
+	'addition_expr',
+	'and_expr',
+	'division_expr',
+	'eq_expr',
+	'gt_expr',
+	'gte_expr',
+	'lt_expr',
+	'lte_expr',
+	'modulo_expr',
+	'multiplication_expr',
+	'ne_expr',
+	'or_expr',
+	'subtraction_expr',
+	'union_expr',
+]);
+
+const isBinaryExprNode = (node: AnySyntaxNode): node is AnyBinaryExprNode => {
+	return binaryExprNodeTypes.has(node.type as AnyBinaryExprType);
+};
+
+const matchesLocalName = (
+	localName: string,
+	nameNode: PrefixedNameNode | UnprefixedNameNode
+): boolean => {
+	const localPartNode: LocalPartNode | UnprefixedNameNode =
+		nameNode.type === 'prefixed_name' ? nameNode.children[1] : nameNode;
+
+	return localPartNode.text === localName;
+};
+
+const isFunctionCalled = (localName: string, node: AnySyntaxNode): boolean => {
+	if (!node.text.includes(localName)) {
+		return false;
+	}
+
+	if (isSingleNodeChild(node)) {
+		const [child] = node.children;
+
+		return isFunctionCalled(localName, child);
+	}
+
+	if (isBinaryExprNode(node)) {
+		const [lhs, rhs] = node.children;
+
+		return isFunctionCalled(localName, lhs) || isFunctionCalled(localName, rhs);
+	}
+
+	switch (node.type) {
+		// Terminal nodes
+		case 'number':
+		case 'string_literal':
+		case 'variable_reference':
+
+		// Path sub-nodes which could not have a function call child
+		//
+		// This only errors because this set of cases is commented:
+		// eslint-disable-next-line no-fallthrough
+		case '//':
+		case 'absolute_root_location_path':
+		case 'axis_name':
+		case 'node_type_test':
+		case 'parent':
+		case 'self':
+
+		// Name nodes are also not function call parents
+		//
+		// This only errors because this set of cases is commented:
+		// eslint-disable-next-line no-fallthrough
+		case 'local_part':
+		case 'prefixed_name':
+		case 'prefix':
+		case 'unprefixed_name':
+		case 'unprefixed_wildcard_name_test':
+			return false;
+
+		// Path sub-nodes which could have a function call child
+		case 'abbreviated_absolute_location_path':
+		case 'abbreviated_step':
+		case 'absolute_location_path':
+		case 'axis_test':
+		case 'filter_path_expr':
+		case 'relative_location_path':
+		case 'step':
+			return node.children.some((childNode) => isFunctionCalled(localName, childNode));
+
+		case 'function_call': {
+			const [functionNameNode] = node.children;
+			const [nameNode] = functionNameNode.children;
+
+			return matchesLocalName(localName, nameNode);
+		}
+
+		default:
+			throw new UnreachableError(node);
+	}
+};
+
+export const isItextFunctionCalled = (expression: string): boolean => {
+	const { rootNode } = expressionParser.parse(expression);
+
+	return isFunctionCalled('itext', rootNode);
+};
+
+type LocationPathSubExpressionNode =
+	| AbsoluteLocationPathNode
+	| FilterPathExprNode
+	| RelativeLocationPathNode;
+
+const isAnyLocationPathExprNode = (node: AnySyntaxNode): node is LocationPathSubExpressionNode => {
+	const { type } = node;
+
+	if (type === 'absolute_location_path' || type === 'relative_location_path') {
+		return true;
+	}
+
+	return false;
+};
+
+// TODO: this does not currently even attempt to find sub-expressions nested
+// within sub-expressions.
+const findLocationPathExprNodes = (
+	node: AnySyntaxNode
+): readonly LocationPathSubExpressionNode[] => {
+	const results: LocationPathSubExpressionNode[] = [];
+
+	if (isAnyLocationPathExprNode(node)) {
+		results.push(node);
+	}
+
+	results.push(
+		...node.children.flatMap((childNode) => {
+			return findLocationPathExprNodes(childNode);
+		})
+	);
+
+	return results;
+};
+
+// TODO: this is a very small subset of resolution that needs to be supported,
+// and it's a hamfisted hack. **This is temporary** to unblock progress on
+// computations, but a longer term solution will need to address:
+//
+// - non-abbreviation axes (parent, child, self) according to XForms spec
+// - non-leading axes
+// - context expressions which are more complex than a series of explicit
+//   element name test steps (this may be fine for binds!)
+const resolveRelativeSubExpression = (contextReference: string | null, expression: string) => {
+	if (contextReference == null) {
+		return expression;
+	}
+
+	const [, axisAbbreviation, relativeExpression = ''] = expression.match(/^(\.{1,2})(\/.*$)?/) ?? [
+		null,
+		'',
+		expression,
+	];
+
+	switch (axisAbbreviation) {
+		case '':
+			return expression;
+
+		case '.':
+			return `${contextReference}${relativeExpression}`;
+
+		case '..':
+			return `${contextReference.replace(/\/[^/]+$/, '')}${relativeExpression}`;
+	}
+
+	throw new Error(`Unexpected relative expression: ${expression}`);
+};
+
+interface GetNodesetDependenciesOptions {
+	readonly contextReference?: string | null;
+
+	/**
+	 * @default false
+	 */
+	readonly ignoreContextReference?: boolean;
+
+	/**
+	 * Ignores location path sub-expressions whose full text is `null`. While this
+	 * is technically a valid relative name test step, it seems that real forms in
+	 * the wild use it as if XPath had an actual `null` token/value.
+	 *
+	 * @default true
+	 */
+	readonly ignoreNullExpressions?: boolean;
+}
+
+export const getNodesetDependencies = (
+	expression: string,
+	options: GetNodesetDependenciesOptions = {}
+): Set<string> => {
+	const { rootNode } = expressionParser.parse(expression);
+	const subExpressionNodes = findLocationPathExprNodes(rootNode);
+	const {
+		contextReference = null,
+		ignoreContextReference = false,
+		ignoreNullExpressions = true,
+	} = options;
+
+	const subExpressions = subExpressionNodes
+		.map((syntaxNode) => resolveRelativeSubExpression(contextReference, syntaxNode.text))
+		.filter((subExpression) => {
+			if (ignoreContextReference && subExpression === contextReference) {
+				return false;
+			}
+
+			if (ignoreNullExpressions && subExpression === 'null') {
+				return false;
+			}
+
+			return true;
+		});
+
+	return new Set(subExpressions);
+};

package/src/model/BindComputation.ts

@@ -0,0 +1,88 @@
+import { DependentExpression } from '../expression/DependentExpression.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+
+const defaultBindComputationExpressions = {
+	calculate: null,
+	constraint: 'true()',
+	readonly: 'false()',
+	relevant: 'true()',
+	required: 'false()',
+	saveIncomplete: 'false()',
+} as const;
+
+type DefaultBindComputationExpressions = typeof defaultBindComputationExpressions;
+
+export type BindComputationType = keyof DefaultBindComputationExpressions;
+
+type BindComputationFactoryResult<Type extends BindComputationType> =
+	DefaultBindComputationExpressions[Type] extends null
+		? BindComputation<Type> | null
+		: BindComputation<Type>;
+
+const bindComputationResultTypes = {
+	calculate: 'string',
+	constraint: 'boolean',
+	readonly: 'boolean',
+	relevant: 'boolean',
+	required: 'boolean',
+	saveIncomplete: 'boolean',
+} as const;
+
+type BindComputationResultTypes = typeof bindComputationResultTypes;
+
+export type BindComputationResultType<Computation extends BindComputationType> =
+	BindComputationResultTypes[Computation];
+
+export class BindComputation<Computation extends BindComputationType> extends DependentExpression<
+	BindComputationResultType<Computation>
+> {
+	static forExpression<Type extends BindComputationType>(
+		bind: BindDefinition,
+		computation: Type
+	): BindComputationFactoryResult<Type> {
+		const expression =
+			bind.bindElement.getAttribute(computation) ?? defaultBindComputationExpressions[computation];
+
+		if (expression == null) {
+			return null as BindComputationFactoryResult<Type>;
+		}
+
+		return new this(bind, computation, expression);
+	}
+
+	readonly isDefaultExpression: boolean;
+
+	protected constructor(
+		bind: BindDefinition,
+		readonly computation: Computation,
+		expression: string | null
+	) {
+		const isInherited = computation === 'readonly' || computation === 'relevant';
+		const ignoreContextReference = computation === 'constraint';
+
+		let isDefaultExpression: boolean;
+		let resolvedExpression: string;
+
+		if (expression == null) {
+			if (computation === 'calculate') {
+				throw new Error('No default expression for calculate');
+			}
+
+			resolvedExpression =
+				defaultBindComputationExpressions[computation as Exclude<Computation, 'calculate'>];
+			isDefaultExpression = true;
+		} else {
+			isDefaultExpression = false;
+			resolvedExpression = expression;
+		}
+
+		super(bind, bindComputationResultTypes[computation], resolvedExpression, {
+			ignoreContextReference,
+			semanticDependencies: {
+				parentContext: isInherited,
+			},
+		});
+
+		this.isDefaultExpression = isDefaultExpression;
+	}
+}

package/src/model/BindDefinition.ts

@@ -0,0 +1,104 @@
+import type { XFormDataType } from '../XFormDataType.ts';
+import { bindDataType } from '../XFormDataType.ts';
+import type { XFormDefinition } from '../XFormDefinition.ts';
+import { DependencyContext } from '../expression/DependencyContext.ts';
+import type { DependentExpression } from '../expression/DependentExpression.ts';
+import { BindComputation } from './BindComputation.ts';
+import type { BindElement } from './BindElement.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
+
+export class BindDefinition extends DependencyContext {
+	readonly bindType: string | null;
+	readonly dataType: XFormDataType;
+	readonly parentNodeset: string | null;
+
+	readonly calculate: BindComputation<'calculate'> | null;
+	readonly readonly: BindComputation<'readonly'>;
+	readonly relevant: BindComputation<'relevant'>;
+	readonly required: BindComputation<'required'>;
+
+	// According to
+	//
+	// this is not stored in the DAG. In contrast, we do compute constraint
+	// dependencies, but self-references are ignored (handled by `BindComputation`
+	// and its `DependentExpression` parent class).
+	/**
+	 * Diverges from {@link https://github.com/getodk/javarosa/blob/059321160e6f8dbb3e81d9add61d68dd35b13cc8/dag.md | JavaRosa's}, which excludes `constraint` expressions. We compute `constraint` dependencies like the other <bind> computation expressions, but explicitly ignore self-references (this is currently handled by {@link BindComputation}, via its {@link DependentExpression} parent class).
+	 */
+	readonly constraint: BindComputation<'constraint'> & DependentExpression<'boolean'>;
+
+	// TODO: it is unclear whether this will need to be supported.
+	// https://github.com/getodk/collect/issues/3758 mentions deprecation.
+	readonly saveIncomplete: BindComputation<'saveIncomplete'>;
+
+	// TODO: these are deferred just to put off sharing namespace stuff
+	// readonly requiredMsg: string | null;
+	// readonly constraintMsg: string | null;
+	// readonly preload: string | null;
+	// readonly preloadParams: string | null;
+	// readonly 'max-pixels': string | null;
+
+	protected _parentBind: BindDefinition | null | undefined;
+
+	get parentBind(): BindDefinition | null {
+		let bind = this._parentBind;
+
+		if (typeof bind === 'undefined') {
+			const { parentNodeset } = this;
+
+			if (parentNodeset == null) {
+				bind = null;
+			} else {
+				bind = this.form.model.binds.get(parentNodeset) ?? null;
+			}
+
+			this._parentBind = bind;
+		}
+
+		return bind;
+	}
+
+	// DependencyContext
+	get reference(): string {
+		return this.nodeset;
+	}
+
+	get parentReference(): string | null {
+		return this.parentNodeset;
+	}
+
+	constructor(
+		readonly form: XFormDefinition,
+		protected readonly model: ModelDefinition,
+		readonly nodeset: string,
+		readonly bindElement: BindElement
+	) {
+		super();
+
+		const bindType = (this.bindType = bindElement.getAttribute('type'));
+
+		this.dataType = bindDataType(bindType);
+
+		const parentNodeset = nodeset.replace(/\/[^/]+$/, '');
+
+		this.parentNodeset = parentNodeset.length > 1 ? parentNodeset : null;
+		this.calculate = BindComputation.forExpression(this, 'calculate');
+		this.readonly = BindComputation.forExpression(this, 'readonly');
+		this.relevant = BindComputation.forExpression(this, 'relevant');
+		this.required = BindComputation.forExpression(this, 'required');
+		this.constraint = BindComputation.forExpression(this, 'constraint');
+		this.saveIncomplete = BindComputation.forExpression(this, 'saveIncomplete');
+
+		// this.requiredMsg = BindComputation.forExpression(this, 'requiredMsg');
+		// this.constraintMsg = BindComputation.forExpression(this, 'constraintMsg');
+		// this.preload = BindComputation.forExpression(this, 'preload');
+		// this.preloadParams = BindComputation.forExpression(this, 'preloadParams');
+		// this['max-pixels'] = BindComputation.forExpression(this, 'max-pixels');
+	}
+
+	toJSON() {
+		const { form, model, /* modelElement, */ bindElement, ...rest } = this;
+
+		return rest;
+	}
+}

package/src/model/BindElement.ts

@@ -0,0 +1,8 @@
+export type BindNodeset = string;
+
+export interface BindElement {
+	readonly localName: 'bind';
+
+	getAttribute(name: 'nodeset'): BindNodeset;
+	getAttribute(name: string): string | null;
+}

package/src/model/DescendentNodeDefinition.ts

@@ -0,0 +1,56 @@
+import type { AnyBodyElementDefinition } from '../body/BodyDefinition.ts';
+import type { RepeatDefinition } from '../body/RepeatDefinition.ts';
+import type { BindDefinition } from './BindDefinition.ts';
+import type {
+	ModelNode,
+	NodeChildren,
+	NodeDefaultValue,
+	NodeDefinition,
+	NodeDefinitionType,
+	NodeInstances,
+	NodeParent,
+} from './NodeDefinition.ts';
+import type { RootDefinition } from './RootDefinition.ts';
+
+export type DescendentNodeType = Exclude<NodeDefinitionType, 'root'>;
+
+type DescendentNodeBodyElement = AnyBodyElementDefinition | RepeatDefinition;
+
+export abstract class DescendentNodeDefinition<
+	Type extends DescendentNodeType,
+	BodyElement extends DescendentNodeBodyElement | null = DescendentNodeBodyElement | null,
+> implements NodeDefinition<Type>
+{
+	abstract readonly type: Type;
+	abstract readonly children: NodeChildren<Type>;
+	abstract readonly instances: NodeInstances<Type>;
+	abstract readonly defaultValue: NodeDefaultValue<Type>;
+	abstract readonly node: ModelNode<Type>;
+	abstract readonly nodeName: string;
+
+	readonly root: RootDefinition;
+	readonly nodeset: string;
+	readonly dependencyExpressions: ReadonlySet<string>;
+	readonly isTranslated: boolean = false;
+
+	constructor(
+		readonly parent: NodeParent<Type>,
+		readonly bind: BindDefinition,
+		readonly bodyElement: BodyElement
+	) {
+		this.root = parent.root;
+		this.nodeset = bind.nodeset;
+
+		if (bind.isTranslated || bodyElement?.isTranslated) {
+			this.isTranslated = true;
+		}
+
+		this.dependencyExpressions = new Set([
+			...bind.dependencyExpressions,
+			...(bodyElement?.dependencyExpressions ?? []),
+		]);
+	}
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyDescendantNodeDefinition = DescendentNodeDefinition<any, any>;

package/src/model/ModelBindMap.ts

@@ -0,0 +1,71 @@
+import type { XFormDefinition } from '../XFormDefinition.ts';
+import { BindDefinition } from './BindDefinition.ts';
+import type { BindElement, BindNodeset } from './BindElement.ts';
+import type { ModelDefinition } from './ModelDefinition.ts';
+
+class ArtificialBindElement implements BindElement {
+	readonly localName = 'bind';
+
+	constructor(protected readonly ancestorNodeset: string) {}
+
+	getAttribute(name: 'nodeset'): string;
+	getAttribute(name: string): string | null;
+	getAttribute(name: string) {
+		if (name === 'nodeset') {
+			return this.ancestorNodeset;
+		}
+
+		return null;
+	}
+}
+
+type TopologicalSortIndex = number;
+
+export type SortedNodesetIndexes = ReadonlyMap<BindNodeset, TopologicalSortIndex>;
+
+export class ModelBindMap extends Map<BindNodeset, BindDefinition> {
+	// This is probably overkill, just produces a type that's readonly at call site.
+	static fromModel(model: ModelDefinition): ModelBindMap {
+		return new this(model.form, model);
+	}
+
+	protected constructor(
+		protected readonly form: XFormDefinition,
+		protected readonly model: ModelDefinition
+	) {
+		const bindElements = form.xformDOM.rootEvaluator.evaluateNodes<BindElement & Element>(
+			'./xf:bind[@nodeset]',
+			{
+				contextNode: form.xformDOM.model,
+			}
+		);
+
+		super(
+			bindElements.map((bindElement) => {
+				const nodeset = bindElement.getAttribute('nodeset');
+				const bind = new BindDefinition(form, model, nodeset, bindElement);
+
+				return [nodeset, bind];
+			})
+		);
+
+		this.getOrCreateBindDefinition(form.rootReference);
+	}
+
+	getOrCreateBindDefinition(nodeset: string): BindDefinition {
+		let bind = this.get(nodeset);
+
+		if (bind == null) {
+			const bindElement = new ArtificialBindElement(nodeset);
+
+			bind = new BindDefinition(this.form, this.model, nodeset, bindElement);
+			this.set(nodeset, bind);
+		}
+
+		return bind;
+	}
+
+	toJSON() {
+		return Array.from(this.entries());
+	}
+}

package/src/model/ModelDefinition.ts

@@ -0,0 +1,19 @@
+import type { XFormDefinition } from '../XFormDefinition.ts';
+import { ModelBindMap } from './ModelBindMap.ts';
+import { RootDefinition } from './RootDefinition.ts';
+
+export class ModelDefinition {
+	readonly binds: ModelBindMap;
+	readonly root: RootDefinition;
+
+	constructor(readonly form: XFormDefinition) {
+		this.binds = ModelBindMap.fromModel(this);
+		this.root = new RootDefinition(form, this);
+	}
+
+	toJSON() {
+		const { form, ...rest } = this;
+
+		return rest;
+	}
+}