@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/parse/body/control/{select/ItemDefinition.ts → ItemDefinition.ts}

@@ -1,8 +1,10 @@
-import { getValueElement, type ItemElement } from '../../../../lib/dom/query.ts';
-import { ItemLabelDefinition } from '../../../text/ItemLabelDefinition.ts';
-import type { XFormDefinition } from '../../../XFormDefinition.ts';
-import { BodyElementDefinition } from '../../BodyElementDefinition.ts';
-import type { AnySelectDefinition } from './SelectDefinition.ts';
+import type { ItemElement } from '../../../lib/dom/query.ts';
+import { getValueElement } from '../../../lib/dom/query.ts';
+import { ItemLabelDefinition } from '../../text/ItemLabelDefinition.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import { BodyElementDefinition } from '../BodyElementDefinition.ts';
+import type { AnySelectControlDefinition } from './SelectControlDefinition.ts';
+import { RankControlDefinition } from './RankControlDefinition.ts';
 
 export class ItemDefinition extends BodyElementDefinition<'item'> {
 	override readonly category = 'support';
@@ -13,7 +15,7 @@ export class ItemDefinition extends BodyElementDefinition<'item'> {
 
 	constructor(
 		form: XFormDefinition,
-		override readonly parent: AnySelectDefinition,
+		override readonly parent: AnySelectControlDefinition | RankControlDefinition,
 		element: ItemElement
 	) {
 		const valueElement = getValueElement(element);

package/src/parse/body/control/{select/ItemsetDefinition.ts → ItemsetDefinition.ts}

@@ -1,11 +1,13 @@
-import { getValueElement, type ItemsetElement } from '../../../../lib/dom/query.ts';
-import { ItemsetNodesetExpression } from '../../../expression/ItemsetNodesetExpression.ts';
-import { ItemsetValueExpression } from '../../../expression/ItemsetValueExpression.ts';
-import { ItemsetLabelDefinition } from '../../../text/ItemsetLabelDefinition.ts';
-import type { XFormDefinition } from '../../../XFormDefinition.ts';
-import { parseNodesetReference } from '../../../xpath/reference-parsing.ts';
-import { BodyElementDefinition } from '../../BodyElementDefinition.ts';
-import type { AnySelectDefinition } from './SelectDefinition.ts';
+import type { ItemsetElement } from '../../../lib/dom/query.ts';
+import { getValueElement } from '../../../lib/dom/query.ts';
+import { ItemsetNodesetExpression } from '../../expression/ItemsetNodesetExpression.ts';
+import { ItemsetValueExpression } from '../../expression/ItemsetValueExpression.ts';
+import { ItemsetLabelDefinition } from '../../text/ItemsetLabelDefinition.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import { parseNodesetReference } from '../../xpath/reference-parsing.ts';
+import { BodyElementDefinition } from '../BodyElementDefinition.ts';
+import type { AnySelectControlDefinition } from './SelectControlDefinition.ts';
+import { RankControlDefinition } from './RankControlDefinition.ts';
 
 export class ItemsetDefinition extends BodyElementDefinition<'itemset'> {
 	override readonly category = 'support';
@@ -19,7 +21,7 @@ export class ItemsetDefinition extends BodyElementDefinition<'itemset'> {
 
 	constructor(
 		form: XFormDefinition,
-		override readonly parent: AnySelectDefinition,
+		override readonly parent: AnySelectControlDefinition | RankControlDefinition,
 		element: ItemsetElement
 	) {
 		super(form, parent, element);

package/src/parse/body/control/RangeControlDefinition.ts

@@ -1,23 +1,108 @@
+import { ErrorProductionDesignPendingError } from '../../../error/ErrorProductionDesignPendingError.ts';
 import type { XFormDefinition } from '../../XFormDefinition.ts';
-import {
-	unknownAppearanceParser,
-	type UnknownAppearanceDefinition,
-} from '../appearance/unknownAppearanceParser.ts';
+import type { RangeAppearanceDefinition } from '../appearance/rangeAppearanceParser.ts';
+import { rangeAppearanceParser } from '../appearance/rangeAppearanceParser.ts';
 import type { BodyElementParentContext } from '../BodyDefinition.ts';
 import { ControlDefinition } from './ControlDefinition.ts';
 
+type NumericString = `${number}`;
+
+/**
+ * @todo this should likely become a basis for generalizing how we parse number
+ * values from strings. Note for when we take that on: number semantics vary
+ * between:
+ *
+ * - {@link https://www.w3.org/TR/1999/REC-xpath-19991116/#numbers | XPath}:
+ *   XPath "64-bit [...] IEEE 754" number values are almost totally consistent
+ *   with JavaScript numbers; the main difference is that JavaScript's
+ *   {@link Number} factory is more flexible in casting from string than the
+ *   casting semantics specified by XPath
+ *
+ * - {@link https://getodk.github.io/xforms-spec/#data-types | [ODK] XForms}:
+ *   specifies both `int` and `decimal` types. Decimals are **NOT** expected to
+ *   have the same precision tradeoffs as IEEE 754 numbers, and we'll want to
+ *   take special care that parsing does not introduce precision errors.
+ */
+const NUMERIC_STRING_PATTERN = /^-?\d+(\.\d+)?$/;
+
+const isNumericString = (value: string): value is NumericString => {
+	return NUMERIC_STRING_PATTERN.test(value);
+};
+
+type AssertNumericStringAttribute = (
+	localName: string,
+	value: string | null
+) => asserts value is NumericString;
+
+const assertNumericStringAttribute: AssertNumericStringAttribute = (localName, value) => {
+	if (value == null) {
+		throw new ErrorProductionDesignPendingError(`Expected attribute ${localName} is not defined`);
+	}
+
+	if (!isNumericString(value)) {
+		throw new ErrorProductionDesignPendingError(
+			`Expected attribute ${localName} to be defined with numeric string, got: ${JSON.stringify(value)}`
+		);
+	}
+};
+
+const parseNumericStringAttribute = (element: Element, localName: string): NumericString => {
+	const value = element.getAttribute(localName);
+
+	assertNumericStringAttribute(localName, value);
+
+	return value;
+};
+
+/**
+ * Per
+ * {@link https://getodk.github.io/xforms-spec/#body-elements | ODK XForms spec},
+ * the following attributes are required:
+ *
+ * - `start`
+ * - `end`
+ * - `step`
+ *
+ * While we also know that a `<range>` control is expected to have a bind type
+ * of either `decimal` or `int`, at this parsing stage we do not yet know which
+ * type is associated with the control. So we parse the attributes as strings,
+ * checking only that they appear to be numeric values. We also preserve the
+ * attributes' names here, for consistency with the spec.
+ *
+ * Downstream, we parse these to their appropriate numeric runtime types, and
+ * alias them to their more conventional names (i.e. "start" -> "min", "end" ->
+ * "max").
+ */
+export class RangeControlBoundsDefinition {
+	static from(element: Element) {
+		const start = parseNumericStringAttribute(element, 'start');
+		const end = parseNumericStringAttribute(element, 'end');
+		const step = parseNumericStringAttribute(element, 'step');
+
+		return new this(start, end, step);
+	}
+
+	constructor(
+		readonly start: NumericString,
+		readonly end: NumericString,
+		readonly step: NumericString
+	) {}
+}
+
 export class RangeControlDefinition extends ControlDefinition<'range'> {
 	static override isCompatible(localName: string): boolean {
 		return localName === 'range';
 	}
 
 	readonly type = 'range';
-	readonly appearances: UnknownAppearanceDefinition;
+	readonly appearances: RangeAppearanceDefinition;
+	readonly bounds: RangeControlBoundsDefinition;
 
 	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
 		super(form, parent, element);
 
-		this.appearances = unknownAppearanceParser.parseFrom(element, 'appearance');
+		this.appearances = rangeAppearanceParser.parseFrom(element, 'appearance');
+		this.bounds = RangeControlBoundsDefinition.from(element);
 	}
 
 	override toJSON(): object {

package/src/parse/body/control/RankControlDefinition.ts

@@ -1,27 +1,45 @@
-import { ODK_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import { getItemElements, getItemsetElement } from '../../../lib/dom/query.ts';
 import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { BodyElementParentContext } from '../BodyDefinition.ts';
+import { ControlDefinition } from './ControlDefinition.ts';
+import { ItemsetDefinition } from './ItemsetDefinition.ts';
+import { ItemDefinition } from './ItemDefinition.ts';
 import {
-	unknownAppearanceParser,
 	type UnknownAppearanceDefinition,
+	unknownAppearanceParser,
 } from '../appearance/unknownAppearanceParser.ts';
-import type { BodyElementParentContext } from '../BodyDefinition.ts';
-import { ControlDefinition } from './ControlDefinition.ts';
 
 export class RankControlDefinition extends ControlDefinition<'rank'> {
-	static override isCompatible(localName: string, element: Element): boolean {
-		return localName === 'rank' && element.namespaceURI === ODK_NAMESPACE_URI;
+	static override isCompatible(localName: string): boolean {
+		return localName === 'rank';
 	}
 
 	readonly type = 'rank';
 	readonly appearances: UnknownAppearanceDefinition;
+	readonly itemset: ItemsetDefinition | null;
+	readonly items: readonly ItemDefinition[];
 
 	constructor(form: XFormDefinition, parent: BodyElementParentContext, element: Element) {
 		super(form, parent, element);
 
 		this.appearances = unknownAppearanceParser.parseFrom(element, 'appearance');
+		const itemsetElement = getItemsetElement(element);
+		const itemElements = getItemElements(element);
+
+		if (itemsetElement === null || itemElements === undefined) {
+			this.itemset = null;
+			this.items = itemElements.map((itemElement) => new ItemDefinition(form, this, itemElement));
+		} else {
+			if (itemElements.length > 0) {
+				throw new Error(`<${element.nodeName}> has both <itemset> and <item> children`);
+			}
+
+			this.items = [];
+			this.itemset = new ItemsetDefinition(form, this, itemsetElement);
+		}
 	}
 
-	override toJSON(): object {
+	override toJSON() {
 		return {};
 	}
 }

package/src/parse/body/control/{select/SelectDefinition.ts → SelectControlDefinition.ts}

@@ -1,11 +1,11 @@
 import type { CollectionValues } from '@getodk/common/types/collections/CollectionValues.ts';
 import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
-import { getItemElements, getItemsetElement } from '../../../../lib/dom/query.ts';
-import type { XFormDefinition } from '../../../XFormDefinition.ts';
-import type { SelectAppearanceDefinition } from '../../appearance/selectAppearanceParser.ts';
-import { selectAppearanceParser } from '../../appearance/selectAppearanceParser.ts';
-import type { AnyBodyElementDefinition, BodyElementParentContext } from '../../BodyDefinition.ts';
-import { ControlDefinition } from '../ControlDefinition.ts';
+import { getItemElements, getItemsetElement } from '../../../lib/dom/query.ts';
+import type { XFormDefinition } from '../../XFormDefinition.ts';
+import type { SelectAppearanceDefinition } from '../appearance/selectAppearanceParser.ts';
+import { selectAppearanceParser } from '../appearance/selectAppearanceParser.ts';
+import type { AnyBodyElementDefinition, BodyElementParentContext } from '../BodyDefinition.ts';
+import { ControlDefinition } from './ControlDefinition.ts';
 import { ItemDefinition } from './ItemDefinition.ts';
 import { ItemsetDefinition } from './ItemsetDefinition.ts';
 
@@ -22,12 +22,12 @@ const isSelectElement = (
 	return selectLocalNames.has(localName as SelectType);
 };
 
-export class SelectDefinition<Type extends SelectType> extends ControlDefinition<Type> {
+export class SelectControlDefinition<Type extends SelectType> extends ControlDefinition<Type> {
 	static override isCompatible(localName: string, element: Element): boolean {
 		return isSelectElement(element, localName);
 	}
 
-	static isSelect(element: AnyBodyElementDefinition): element is AnySelectDefinition {
+	static isSelect(element: AnyBodyElementDefinition): element is AnySelectControlDefinition {
 		return selectLocalNames.has(element.type as SelectType);
 	}
 
@@ -72,4 +72,4 @@ export class SelectDefinition<Type extends SelectType> extends ControlDefinition
 	}
 }
 
-export type AnySelectDefinition = SelectDefinition<SelectType>;
+export type AnySelectControlDefinition = SelectControlDefinition<SelectType>;

package/src/parse/expression/ItemsetNodesetExpression.ts

@@ -1,4 +1,4 @@
-import type { ItemsetDefinition } from '../body/control/select/ItemsetDefinition.ts';
+import type { ItemsetDefinition } from '../body/control/ItemsetDefinition.ts';
 import { DependentExpression } from './abstract/DependentExpression.ts';
 
 export class ItemsetNodesetExpression extends DependentExpression<'nodes'> {

package/src/parse/expression/ItemsetValueExpression.ts

@@ -1,4 +1,4 @@
-import type { ItemsetDefinition } from '../body/control/select/ItemsetDefinition.ts';
+import type { ItemsetDefinition } from '../body/control/ItemsetDefinition.ts';
 import { DependentExpression } from './abstract/DependentExpression.ts';
 
 export class ItemsetValueExpression extends DependentExpression<'string'> {

package/src/parse/expression/abstract/DependencyContext.ts

@@ -1,28 +1,7 @@
-import type { AnyDependentExpression } from './DependentExpression.ts';
-
 export abstract class DependencyContext {
 	abstract get parentReference(): string | null;
 	abstract get reference(): string | null;
 
-	protected readonly dependentExpressions = new Set<AnyDependentExpression>();
-
-	protected dependencyExpressionsCache: ReadonlySet<string> | null = null;
-
-	get dependencyExpressions(): ReadonlySet<string> {
-		let { dependencyExpressionsCache } = this;
-
-		if (dependencyExpressionsCache == null) {
-			dependencyExpressionsCache = new Set(
-				Array.from(this.dependentExpressions).flatMap((expression) => {
-					return Array.from(expression.dependencyReferences);
-				})
-			);
-			this.dependencyExpressionsCache = dependencyExpressionsCache;
-		}
-
-		return dependencyExpressionsCache;
-	}
-
 	get isTranslated(): boolean {
 		return this._isTranslated;
 	}
@@ -45,9 +24,4 @@ export abstract class DependencyContext {
 
 	// Update note on `set isTranslated` if this internal storage changes.
 	protected _isTranslated = false;
-
-	registerDependentExpression(expression: AnyDependentExpression): void {
-		this.dependencyExpressionsCache = null;
-		this.dependentExpressions.add(expression);
-	}
 }

package/src/parse/expression/abstract/DependentExpression.ts

@@ -1,5 +1,4 @@
-import type { XFormsXPathEvaluator } from '@getodk/xpath';
-import { resolveDependencyNodesets } from '../../xpath/dependency-analysis.ts';
+import type { EngineXPathEvaluator } from '../../../integration/xpath/EngineXPathEvaluator.ts';
 import type {
 	ConstantExpression,
 	ConstantTruthyExpression,
@@ -26,7 +25,7 @@ export type DependentExpressionEvaluatorMethod<Type extends DependentExpressionR
 	EvaluatorMethodsByResultType[Type];
 
 export type DependentExpressionResult<Type extends DependentExpressionResultType> = ReturnType<
-	XFormsXPathEvaluator[DependentExpressionEvaluatorMethod<Type>]
+	EngineXPathEvaluator[DependentExpressionEvaluatorMethod<Type>]
 >;
 
 interface SemanticDependencyOptions {
@@ -55,7 +54,6 @@ export interface ConstantTruthyDependentExpression extends ConstantDependentExpr
 }
 
 export abstract class DependentExpression<Type extends DependentExpressionResultType> {
-	readonly dependencyReferences: ReadonlySet<string> = new Set();
 	readonly isTranslated: boolean = false;
 	readonly evaluatorMethod: DependentExpressionEvaluatorMethod<Type>;
 	readonly constantExpression: ConstantExpression | null;
@@ -81,26 +79,17 @@ export abstract class DependentExpression<Type extends DependentExpressionResult
 		this.evaluatorMethod = evaluatorMethodsByResultType[resultType];
 
 		const {
-			ignoreContextReference = false,
 			semanticDependencies = {
 				translations: false,
 			},
 		} = options;
 
-		this.dependencyReferences = new Set(
-			resolveDependencyNodesets(context.reference, expression, {
-				ignoreReferenceToContextPath: ignoreContextReference,
-			})
-		);
-
 		const isTranslated = semanticDependencies.translations && isTranslationExpression(expression);
 
 		if (isTranslated) {
 			this.isTranslated = true;
 			context.isTranslated = true;
 		}
-
-		context.registerDependentExpression(this);
 	}
 
 	isConstantExpression(): this is ConstantDependentExpression<Type> {

package/src/parse/model/BindDefinition.ts

@@ -2,17 +2,19 @@ import { DependencyContext } from '../expression/abstract/DependencyContext.ts';
 import type { DependentExpression } from '../expression/abstract/DependentExpression.ts';
 import { BindComputationExpression } from '../expression/BindComputationExpression.ts';
 import { MessageDefinition } from '../text/MessageDefinition.ts';
-import type { XFormDataType } from '../XFormDataType.ts';
-import { bindDataType } from '../XFormDataType.ts';
 import type { XFormDefinition } from '../XFormDefinition.ts';
 import type { BindElement } from './BindElement.ts';
+import { BindPreloadDefinition, type AnyBindPreloadDefinition } from './BindPreloadDefinition.ts';
+import type { BindType } from './BindTypeDefinition.ts';
+import { BindTypeDefinition } from './BindTypeDefinition.ts';
 import type { ModelDefinition } from './ModelDefinition.ts';
 
-export class BindDefinition extends DependencyContext {
-	readonly bindType: string | null;
-	readonly dataType: XFormDataType;
+export class BindDefinition<T extends BindType = BindType> extends DependencyContext {
+	readonly type: BindTypeDefinition<T>;
 	readonly parentNodeset: string | null;
 
+	readonly preload: AnyBindPreloadDefinition | null;
+
 	readonly calculate: BindComputationExpression<'calculate'> | null;
 	readonly readonly: BindComputationExpression<'readonly'>;
 	readonly relevant: BindComputationExpression<'relevant'>;
@@ -78,13 +80,12 @@ export class BindDefinition extends DependencyContext {
 	) {
 		super();
 
-		const bindType = (this.bindType = bindElement.getAttribute('type'));
-
-		this.dataType = bindDataType(bindType);
+		this.type = BindTypeDefinition.from(bindElement);
 
 		const parentNodeset = nodeset.replace(/\/[^/]+$/, '');
 
 		this.parentNodeset = parentNodeset.length > 1 ? parentNodeset : null;
+		this.preload = BindPreloadDefinition.from(bindElement);
 		this.calculate = BindComputationExpression.forComputation(this, 'calculate');
 		this.readonly = BindComputationExpression.forComputation(this, 'readonly');
 		this.relevant = BindComputationExpression.forComputation(this, 'relevant');

package/src/parse/model/BindPreloadDefinition.ts

@@ -0,0 +1,100 @@
+import { JAVAROSA_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { PartiallyKnownString } from '@getodk/common/types/string/PartiallyKnownString.ts';
+import type { BindElement } from './BindElement.ts';
+
+type PartiallyKnownPreloadParameter<Known extends string> =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	PartiallyKnownString<NonNullable<Known>> | Extract<Known, null>;
+
+interface PreloadParametersByType {
+	readonly uid: string | null;
+	readonly date: PartiallyKnownPreloadParameter<'today'>;
+	readonly timestamp: PartiallyKnownPreloadParameter<'end' | 'start'>;
+
+	readonly property: PartiallyKnownPreloadParameter<
+		// prettier-ignore
+		'deviceid' | 'email' | 'phonenumber' | 'username'
+	>;
+}
+
+type PreloadType = PartiallyKnownString<keyof PreloadParametersByType>;
+
+// prettier-ignore
+type PreloadParameter<Type extends PreloadType> =
+	Type extends keyof PreloadParametersByType
+		? PreloadParametersByType[Type]
+		: string | null;
+
+interface PreloadInput<Type extends PreloadType> {
+	readonly type: Type;
+	readonly parameter: PreloadParameter<Type>;
+}
+
+type AnyPreloadInput = {
+	[Type in PreloadType]: PreloadInput<Type>;
+}[PreloadType];
+
+const getPreloadInput = (bindElement: BindElement): AnyPreloadInput | null => {
+	const type = bindElement.getAttributeNS(JAVAROSA_NAMESPACE_URI, 'preload');
+
+	if (type == null) {
+		return null;
+	}
+
+	const parameter: PreloadParameter<typeof type> = bindElement.getAttributeNS(
+		JAVAROSA_NAMESPACE_URI,
+		'preloadParams'
+	);
+
+	return {
+		type,
+		parameter,
+	};
+};
+
+/**
+ * Parsed representation of
+ * {@link https://getodk.github.io/xforms-spec/#preload-attributes | Preload Attributes}.
+ * If specified on a
+ * {@link https://getodk.github.io/xforms-spec/#bindings | binding}, this will
+ * be parsed to define:
+ *
+ * - {@link type}, a `jr:preload`
+ * - {@link parameter}, an associated `jr:preloadParams` value
+ *
+ * @todo It would probably make sense for the _definition_ to also convey:
+ *
+ * 1. Which {@link https://getodk.github.io/xforms-spec/#events | event} the
+ *    preload is semantically associated with (noting that the spec may be a tad
+ *    overzealous about this association).
+ *
+ * 2. The constant XPath expression (or other computation?) expressed by the
+ *    combined {@link type} and {@link parameter}.
+ */
+export class BindPreloadDefinition<Type extends PreloadType> implements PreloadInput<Type> {
+	static from(bindElement: BindElement): AnyBindPreloadDefinition | null {
+		const input = getPreloadInput(bindElement);
+
+		if (input == null) {
+			return null;
+		}
+
+		return new this(input);
+	}
+
+	readonly type: Type;
+	readonly parameter: PreloadParameter<Type>;
+
+	private constructor(input: PreloadInput<Type>) {
+		this.type = input.type;
+		this.parameter = input.parameter;
+	}
+}
+
+// prettier-ignore
+export type AnyBindPreloadDefinition =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| BindPreloadDefinition<'uid'>
+	| BindPreloadDefinition<'timestamp'>
+	| BindPreloadDefinition<'property'>
+	| BindPreloadDefinition<string>;