@getodk/xforms-engine 0.3.0 → 0.5.0

package/src/lib/codecs/IntValueCodec.ts

@@ -0,0 +1,100 @@
+import { ValueTypeInvariantError } from '../../error/ValueTypeInvariantError.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+/**
+ * Per {@link https://getodk.github.io/xforms-spec/#data-type:int}, which
+ * specifies "as in {@link https://www.w3.org/TR/xmlschema-2/#int | XML 1.0}":
+ *
+ * > int is ·derived· from long by setting the value of ·maxInclusive· to be
+ * > 2147483647 and ·minInclusive· to be -2147483648.
+ */
+const INT_BOUNDS = {
+	MIN: -2_147_483_648n,
+	MAX: 2_147_483_647n,
+};
+
+const assertIntBounds = <T extends bigint | null>(value: T): T => {
+	if (value == null) {
+		return value;
+	}
+
+	if (value < INT_BOUNDS.MIN || value > INT_BOUNDS.MAX) {
+		throw new ValueTypeInvariantError(
+			'int',
+			`Unable to decode int value from ${String(value)}: expected value to be between ${INT_BOUNDS.MIN} and ${INT_BOUNDS.MAX} (inclusive)`
+		);
+	}
+
+	return value;
+};
+
+const boundedInt = (value: bigint | number): bigint => {
+	const result = BigInt(value);
+
+	assertIntBounds(result);
+
+	return result;
+};
+
+export type IntInputValue = bigint | number | string | null;
+
+const numberToInt = (value: number): bigint | null => {
+	if (!Number.isFinite(value)) {
+		return null;
+	}
+
+	return boundedInt(Math.trunc(value));
+};
+
+const encodeInt = (value: IntInputValue): string => {
+	let intValue: bigint | null;
+
+	switch (typeof value) {
+		case 'object':
+			value satisfies null;
+			intValue = null;
+			break;
+
+		case 'number':
+			intValue = numberToInt(value);
+			break;
+
+		case 'string':
+			intValue = decodeInt(value);
+			break;
+
+		default:
+			value satisfies bigint;
+
+			intValue = boundedInt(value);
+	}
+
+	if (intValue == null) {
+		return '';
+	}
+
+	return String(intValue);
+};
+
+export type IntRuntimeValue = bigint | null;
+
+/**
+ * Note: Collect/JavaRosa trim decimal values (i.e. round closest to zero). We
+ * do the same.
+ *
+ * @todo Note that we enforce bounds **after** rounding, which may not be quite
+ * right! Look at actual Collect/JR implementation to align.
+ */
+const decodeInt = (value: string): IntRuntimeValue => {
+	if (value === '') {
+		return null;
+	}
+
+	return numberToInt(Number(value));
+};
+
+export class IntValueCodec extends ValueCodec<'int', IntRuntimeValue, IntInputValue> {
+	constructor() {
+		super('int', encodeInt, decodeInt);
+	}
+}

package/src/lib/codecs/StringValueCodec.ts

@@ -0,0 +1,11 @@
+import { identity } from '@getodk/common/lib/identity.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+export class StringValueCodec extends ValueCodec<'string', string, string> {
+	constructor() {
+		super('string', identity, identity, {
+			decodeInstanceValueFactory: () => identity,
+			runtimeValueStateFactory: () => identity,
+		});
+	}
+}

package/src/lib/codecs/ValueCodec.ts

@@ -0,0 +1,106 @@
+import type { Accessor } from 'solid-js';
+import type { ValueType } from '../../client/ValueType.ts';
+import type { DecodeInstanceValue } from '../../instance/internal-api/InstanceValueContext.ts';
+import type { SimpleAtomicState } from '../reactivity/types.ts';
+
+type CodecEncoder<RuntimeInputValue> = (input: RuntimeInputValue) => string;
+
+type CodecDecoder<RuntimeValue> = (value: string) => RuntimeValue;
+
+type RuntimeValueAccessor<RuntimeValue> = Accessor<RuntimeValue>;
+
+export type RuntimeValueSetter<
+	RuntimeValue extends RuntimeInputValue,
+	RuntimeInputValue = RuntimeValue,
+> = (input: RuntimeInputValue) => RuntimeValue;
+
+export type RuntimeValueState<
+	RuntimeValue extends RuntimeInputValue,
+	RuntimeInputValue = RuntimeValue,
+> = readonly [
+	get: RuntimeValueAccessor<RuntimeValue>,
+	set: RuntimeValueSetter<RuntimeValue, RuntimeInputValue>,
+];
+
+export type CreateRuntimeValueState<
+	RuntimeValue extends RuntimeInputValue,
+	RuntimeInputValue = RuntimeValue,
+> = (
+	instanceState: SimpleAtomicState<string>
+) => RuntimeValueState<RuntimeValue, RuntimeInputValue>;
+
+type RuntimeValueStateFactory<
+	RuntimeValue extends RuntimeInputValue,
+	RuntimeInputValue = RuntimeValue,
+> = (
+	encodeValue: CodecEncoder<RuntimeInputValue>,
+	decodeValue: CodecDecoder<RuntimeValue>
+) => CreateRuntimeValueState<RuntimeValue, RuntimeInputValue>;
+
+type DecodeInstanceValueFactory<
+	RuntimeValue extends RuntimeInputValue,
+	RuntimeInputValue = RuntimeValue,
+> = (
+	encodeValue: CodecEncoder<RuntimeInputValue>,
+	decodeValue: CodecDecoder<RuntimeValue>
+) => DecodeInstanceValue;
+
+interface ValueCodecOptions<RuntimeValue extends RuntimeInputValue, RuntimeInputValue> {
+	readonly decodeInstanceValueFactory?: DecodeInstanceValueFactory<RuntimeValue, RuntimeInputValue>;
+	readonly runtimeValueStateFactory?: RuntimeValueStateFactory<RuntimeValue, RuntimeInputValue>;
+}
+
+export abstract class ValueCodec<
+	V extends ValueType,
+	RuntimeValue extends RuntimeInputValue,
+	RuntimeInputValue = RuntimeValue,
+> {
+	protected readonly defaultRuntimeValueStateFactory: RuntimeValueStateFactory<
+		RuntimeValue,
+		RuntimeInputValue
+	> = (encodeValue, decodeValue) => {
+		return (instanceState) => {
+			const [getInstanceValue, setInstanceValue] = instanceState;
+
+			const getValue = (): RuntimeValue => {
+				return decodeValue(getInstanceValue());
+			};
+
+			const setValue = (runtimeValue: RuntimeInputValue): RuntimeValue => {
+				const encodedValue = encodeValue(runtimeValue);
+				const persistedValue = setInstanceValue(encodedValue);
+
+				return decodeValue(persistedValue);
+			};
+
+			return [getValue, setValue];
+		};
+	};
+
+	protected readonly defaultDecodeInstanceValueFactory: DecodeInstanceValueFactory<
+		RuntimeValue,
+		RuntimeInputValue
+	> = (encodeValue, decodeValue) => {
+		return (instanceValue) => {
+			return encodeValue(decodeValue(instanceValue));
+		};
+	};
+
+	readonly decodeInstanceValue: DecodeInstanceValue;
+	readonly createRuntimeValueState: CreateRuntimeValueState<RuntimeValue, RuntimeInputValue>;
+
+	constructor(
+		readonly valueType: V,
+		readonly encodeValue: CodecEncoder<RuntimeInputValue>,
+		readonly decodeValue: CodecDecoder<RuntimeValue>,
+		options: ValueCodecOptions<RuntimeValue, RuntimeInputValue> = {}
+	) {
+		const {
+			decodeInstanceValueFactory = this.defaultDecodeInstanceValueFactory,
+			runtimeValueStateFactory = this.defaultRuntimeValueStateFactory,
+		} = options;
+
+		this.decodeInstanceValue = decodeInstanceValueFactory(encodeValue, decodeValue);
+		this.createRuntimeValueState = runtimeValueStateFactory(encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/ValueTypePlaceholderCodec.ts

@@ -0,0 +1,19 @@
+import { identity } from '@getodk/common/lib/identity.ts';
+import type { ValueType } from '../../client/ValueType.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+/**
+ * Provides fallback functionality where a {@link ValueCodec} is expected, for
+ * those {@link ValueType | value types} which are still pending implementation.
+ * This allows consistent use of the {@link ValueCodec} interface while
+ * maintaining the current behavior of treating those unimplemented value types
+ * as string values.
+ */
+export class ValueTypePlaceholderCodec<V extends ValueType> extends ValueCodec<V, string, string> {
+	constructor(valueType: V) {
+		super(valueType, identity, identity, {
+			decodeInstanceValueFactory: () => identity,
+			runtimeValueStateFactory: () => identity,
+		});
+	}
+}

package/src/lib/codecs/getSharedValueCodec.ts

@@ -0,0 +1,77 @@
+import type { ValueType } from '../../client/ValueType.ts';
+import {
+	DecimalValueCodec,
+	type DecimalInputValue,
+	type DecimalRuntimeValue,
+} from './DecimalValueCodec.ts';
+import { IntValueCodec, type IntInputValue, type IntRuntimeValue } from './IntValueCodec.ts';
+import { StringValueCodec } from './StringValueCodec.ts';
+import type { ValueCodec } from './ValueCodec.ts';
+import { ValueTypePlaceholderCodec } from './ValueTypePlaceholderCodec.ts';
+
+interface RuntimeValuesByType {
+	readonly string: string;
+	readonly int: IntRuntimeValue;
+	readonly decimal: DecimalRuntimeValue;
+	readonly boolean: string;
+	readonly date: string;
+	readonly time: string;
+	readonly dateTime: string;
+	readonly geopoint: string;
+	readonly geotrace: string;
+	readonly geoshape: string;
+	readonly binary: string;
+	readonly barcode: string;
+	readonly intent: string;
+}
+
+export type RuntimeValue<V extends ValueType> = RuntimeValuesByType[V];
+
+interface RuntimeInputValuesByType {
+	readonly string: string;
+	readonly int: IntInputValue;
+	readonly decimal: DecimalInputValue;
+	readonly boolean: string;
+	readonly date: string;
+	readonly time: string;
+	readonly dateTime: string;
+	readonly geopoint: string;
+	readonly geotrace: string;
+	readonly geoshape: string;
+	readonly binary: string;
+	readonly barcode: string;
+	readonly intent: string;
+}
+
+export type RuntimeInputValue<V extends ValueType> = RuntimeInputValuesByType[V];
+
+type SharedValueCodecs = {
+	readonly [V in ValueType]: ValueCodec<V, RuntimeValue<V>, RuntimeInputValue<V>>;
+};
+
+export type SharedValueCodec<V extends ValueType> = SharedValueCodecs[V];
+
+/**
+ * Provides codecs for each {@link ValueType | value type}, for nodes with a
+ * common representation of those value types.
+ */
+export const sharedValueCodecs: SharedValueCodecs = {
+	string: new StringValueCodec(),
+
+	int: new IntValueCodec(),
+	decimal: new DecimalValueCodec(),
+	boolean: new ValueTypePlaceholderCodec('boolean'),
+	date: new ValueTypePlaceholderCodec('date'),
+	time: new ValueTypePlaceholderCodec('time'),
+	dateTime: new ValueTypePlaceholderCodec('dateTime'),
+	geopoint: new ValueTypePlaceholderCodec('geopoint'),
+	geotrace: new ValueTypePlaceholderCodec('geotrace'),
+	geoshape: new ValueTypePlaceholderCodec('geoshape'),
+	binary: new ValueTypePlaceholderCodec('binary'),
+	barcode: new ValueTypePlaceholderCodec('barcode'),
+	intent: new ValueTypePlaceholderCodec('intent'),
+};
+
+export const getSharedValueCodec = <V extends ValueType>(valueType: V): SharedValueCodec<V> => {
+	return sharedValueCodecs[valueType];
+};

package/src/lib/dom/query.ts

@@ -3,7 +3,7 @@ import type {
 	KnownAttributeLocalNamedElement,
 	LocalNamedElement,
 } from '@getodk/common/types/dom.ts';
-import type { SelectElement } from '../../body/control/select/SelectDefinition';
+import type { SelectElement } from '../../parse/body/control/select/SelectDefinition';
 
 const hintLookup = new ScopedElementLookup(':scope > hint', 'hint');
 const itemLookup = new ScopedElementLookup(':scope > item', 'item');
@@ -15,6 +15,7 @@ const repeatGroupLabelLookup = new ScopedElementLookup(
 );
 const repeatLookup = new ScopedElementLookup(':scope > repeat[nodeset]', 'repeat[nodeset]');
 const valueLookup = new ScopedElementLookup(':scope > value', 'value');
+const submissionLookup = new ScopedElementLookup(':scope > submission', 'submission');
 
 export interface HintElement extends LocalNamedElement<'hint'> {}
 
@@ -60,3 +61,9 @@ export const getRepeatElement = (parent: Element): RepeatElement | null => {
 export const getValueElement = (parent: ItemElement | ItemsetElement): ValueElement | null => {
 	return valueLookup.getElement<ValueElement>(parent);
 };
+
+export interface SubmissionElement extends LocalNamedElement<'submission'> {}
+
+export const getSubmissionElement = (parent: Element): SubmissionElement | null => {
+	return submissionLookup.getElement<SubmissionElement>(parent);
+};

package/src/lib/reactivity/createChildrenState.ts

@@ -1,8 +1,8 @@
 import type { Accessor, Setter, Signal } from 'solid-js';
 import { createSignal } from 'solid-js';
+import type { FormNodeID } from '../../client/identity.ts';
 import type { OpaqueReactiveObjectFactory } from '../../index.ts';
 import type { AnyChildNode, AnyParentNode } from '../../instance/hierarchy.ts';
-import type { NodeID } from '../../instance/identity.ts';
 import type { materializeCurrentStateChildren } from './materializeCurrentStateChildren.ts';
 import type { ClientState } from './node-state/createClientState.ts';
 import type { CurrentState } from './node-state/createCurrentState.ts';
@@ -12,14 +12,15 @@ export interface ChildrenState<Child extends AnyChildNode> {
 	readonly children: Signal<readonly Child[]>;
 	readonly getChildren: Accessor<readonly Child[]>;
 	readonly setChildren: Setter<readonly Child[]>;
-	readonly childIds: Accessor<readonly NodeID[]>;
+	readonly childIds: Accessor<readonly FormNodeID[]>;
 }
 
 /**
  * Creates a synchronized pair of:
  *
  * - Internal children state suitable for all parent node types
- * - The same children state computed as an array of each child's {@link NodeID}
+ * - The same children state computed as an array of each child's
+ *   {@link FormNodeID}
  *
  * This state is used, in tandem with {@link materializeCurrentStateChildren},
  * to ensure children in **client-facing** state are not written into nested
@@ -34,11 +35,12 @@ export interface ChildrenState<Child extends AnyChildNode> {
  * The produced {@link ChildrenState.childIds} memo is intended to be used to
  * specify each parent node's `children` in an instance of {@link EngineState}.
  * In so doing, the node's corresponding (internal, synchronized)
- * {@link ClientState} will likewise store only the children's {@link NodeID}s.
+ * {@link ClientState} will likewise store only the children's
+ * {@link FormNodeID}s.
  *
  * As a client reacts to changes in a given parent node's `children` state, that
  * node's {@link CurrentState} should produce the child nodes corresponding to
- * those {@link NodeID}s with the aforementioned
+ * those {@link FormNodeID}s with the aforementioned
  * {@link materializeCurrentStateChildren}.
  */
 export const createChildrenState = <Parent extends AnyParentNode, Child extends AnyChildNode>(
@@ -65,7 +67,7 @@ export const createChildrenState = <Parent extends AnyParentNode, Child extends
 		 * likely also slightly more efficient. We can revisit the tradeoff if/when
 		 * those hypothetical generalizations become a priority.
 		 */
-		const ids = createSignal<readonly NodeID[]>([]);
+		const ids = createSignal<readonly FormNodeID[]>([]);
 		const [childIds, setChildIds] = ids;
 
 		type ChildrenSetterCallback = (prev: readonly Child[]) => readonly Child[];

package/src/lib/reactivity/createComputedExpression.ts

@@ -1,18 +1,18 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
-import type { XFormsXPathEvaluator } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import { createMemo } from 'solid-js';
+import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
+import type { EngineXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
 import type {
 	DependentExpression,
 	DependentExpressionResultType,
-} from '../../expression/DependentExpression.ts';
-import type { EvaluationContext } from '../../instance/internal-api/EvaluationContext.ts';
-import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
+} from '../../parse/expression/abstract/DependentExpression.ts';
 import { isConstantExpression } from '../../parse/xpath/semantic-analysis.ts';
 
 interface ComputedExpressionResults {
 	readonly boolean: boolean;
-	readonly nodes: Node[];
+	readonly nodes: EngineXPathNode[];
 	readonly number: number;
 	readonly string: string;
 }
@@ -25,16 +25,18 @@ type EvaluatedExpression<
 // prettier-ignore
 type ExpressionEvaluator<
 	Type extends DependentExpressionResultType
-> = () => EvaluatedExpression<Type>
+> = () => EvaluatedExpression<Type>;
+
+interface ExpressionEvaluatorOptions {
+	get contextNode(): EngineXPathNode;
+}
 
 const expressionEvaluator = <Type extends DependentExpressionResultType>(
-	evaluator: XFormsXPathEvaluator,
-	contextNode: Node,
+	evaluator: EngineXPathEvaluator,
 	type: Type,
-	expression: string
+	expression: string,
+	options: ExpressionEvaluatorOptions
 ): ExpressionEvaluator<Type> => {
-	const options = { contextNode };
-
 	switch (type) {
 		case 'boolean':
 			return (() => {
@@ -61,50 +63,71 @@ const expressionEvaluator = <Type extends DependentExpressionResultType>(
 	}
 };
 
+type DefaultEvaluationsByType = {
+	readonly [Type in DependentExpressionResultType]: EvaluatedExpression<Type>;
+};
+
+const DEFAULT_BOOLEAN_EVALUATION = false;
+const DEFAULT_NODES_EVALUATION: [] = [];
+const DEFAULT_NUMBER_EVALUATION = NaN;
+const DEFAULT_STRING_EVALUATION = '';
+
+const defaultEvaluationsByType: DefaultEvaluationsByType = {
+	boolean: DEFAULT_BOOLEAN_EVALUATION,
+	nodes: DEFAULT_NODES_EVALUATION,
+	number: DEFAULT_NUMBER_EVALUATION,
+	string: DEFAULT_STRING_EVALUATION,
+};
+
 // prettier-ignore
 type ComputedExpression<Type extends DependentExpressionResultType> = Accessor<
 	EvaluatedExpression<Type>
 >;
 
-interface CreateComputedExpressionOptions {
-	readonly arbitraryDependencies?: readonly SubscribableDependency[];
+interface CreateComputedExpressionOptions<Type extends DependentExpressionResultType> {
+	/**
+	 * If a default value is provided, {@link createComputedExpression} will
+	 * produce this value for computations in a non-attached evaluation context,
+	 * i.e. when evaluating an expression against a node which has not yet been
+	 * appended to its parents children state (or which has since been removed
+	 * from that state). A non-attached state is detected when
+	 * {@link EvaluationContext.isAttached} returns false.
+	 *
+	 * If no default value is provided, an implicit default value is produced as
+	 * appropriate for the expression's intrinsic result type.
+	 *
+	 * @see {@link defaultEvaluationsByType} for these implicit defaults.
+	 */
+	readonly defaultValue?: EvaluatedExpression<Type>;
 }
 
 export const createComputedExpression = <Type extends DependentExpressionResultType>(
 	context: EvaluationContext,
 	dependentExpression: DependentExpression<Type>,
-	options: CreateComputedExpressionOptions = {}
+	options: CreateComputedExpressionOptions<Type> = {}
 ): ComputedExpression<Type> => {
-	const { contextNode, evaluator, root, scope } = context;
-	const { expression, isTranslated, resultType } = dependentExpression;
-	const dependencyReferences = Array.from(dependentExpression.dependencyReferences);
-	const evaluateExpression = expressionEvaluator(evaluator, contextNode, resultType, expression);
+	return context.scope.runTask(() => {
+		const { contextNode, evaluator } = context;
+		const { expression, isTranslated, resultType } = dependentExpression;
+		const evaluatePreInitializationDefaultValue = () => {
+			return options?.defaultValue ?? defaultEvaluationsByType[resultType];
+		};
+		const evaluateExpression = expressionEvaluator(evaluator, resultType, expression, {
+			contextNode,
+		});
 
-	return scope.runTask(() => {
 		if (isConstantExpression(expression)) {
 			return createMemo(evaluateExpression);
 		}
 
-		const { arbitraryDependencies = [] } = options;
-
-		const getReferencedDependencies = createMemo(() => {
-			return dependencyReferences.flatMap((reference) => {
-				return context.getSubscribableDependenciesByReference(reference) ?? [];
-			});
-		});
-
 		return createMemo(() => {
-			if (isTranslated) {
-				root.subscribe();
+			if (!context.isAttached()) {
+				return evaluatePreInitializationDefaultValue();
 			}
 
-			arbitraryDependencies.forEach((dependency) => {
-				dependency.subscribe();
-			});
-
-			getReferencedDependencies().forEach((dependency) => {
-				dependency.subscribe();
-			});
+			if (isTranslated) {
+				context.getActiveLanguage();
+			}
 
 			return evaluateExpression();
 		});