@getodk/xforms-engine 0.5.0 → 0.7.0

package/src/integration/xpath/static-dom/staticNodeName.ts

@@ -0,0 +1,20 @@
+import { QualifiedName, type QualifiedNameSource } from '../../../lib/names/QualifiedName.ts';
+import { UnprefixedXFormsName } from '../../../lib/names/UnprefixedXFormsName.ts';
+
+// prettier-ignore
+export type StaticNodeNameSource =
+	| QualifiedName
+	| QualifiedNameSource
+	| string;
+
+export const staticNodeName = (source: StaticNodeNameSource): QualifiedName => {
+	if (source instanceof QualifiedName) {
+		return source;
+	}
+
+	if (typeof source === 'string') {
+		return new UnprefixedXFormsName(source);
+	}
+
+	return new QualifiedName(source);
+};

package/src/lib/client-reactivity/instance-state/createNodeRangeInstanceState.ts

@@ -0,0 +1,17 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { ClientReactiveSerializableParentNode } from '../../../instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts';
+import type { RepeatInstance } from '../../../instance/repeat/RepeatInstance.ts';
+
+export const createNodeRangeInstanceState = (
+	node: ClientReactiveSerializableParentNode<RepeatInstance>
+): InstanceState => {
+	return {
+		get instanceXML() {
+			const serializedChildren = node.currentState.children.map((child) => {
+				return child.instanceState.instanceXML;
+			});
+
+			return serializedChildren.join('');
+		},
+	};
+};

package/src/lib/client-reactivity/instance-state/createParentNodeInstanceState.ts

@@ -0,0 +1,22 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { GeneralChildNode } from '../../../instance/hierarchy.ts';
+import type { ClientReactiveSerializableParentNode } from '../../../instance/internal-api/serialization/ClientReactiveSerializableParentNode.ts';
+import { serializeParentElementXML } from '../../xml-serialization.ts';
+
+export const createParentNodeInstanceState = (
+	node: ClientReactiveSerializableParentNode<GeneralChildNode>
+): InstanceState => {
+	return {
+		get instanceXML() {
+			if (!node.currentState.relevant) {
+				return '';
+			}
+
+			const serializedChildren = node.currentState.children.map((child) => {
+				return child.instanceState.instanceXML;
+			});
+
+			return serializeParentElementXML(node.definition.qualifiedName, serializedChildren);
+		},
+	};
+};

package/src/lib/client-reactivity/instance-state/createPrimaryInstanceState.ts

@@ -0,0 +1,12 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { ClientReactiveSerializableInstance } from '../../../instance/internal-api/serialization/ClientReactiveSerializableInstance.ts';
+
+export const createPrimaryInstanceState = (
+	node: ClientReactiveSerializableInstance
+): InstanceState => {
+	return {
+		get instanceXML(): string {
+			return node.root.instanceState.instanceXML;
+		},
+	};
+};

package/src/lib/client-reactivity/instance-state/createRootInstanceState.ts

@@ -0,0 +1,19 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { Root } from '../../../instance/Root.ts';
+import { serializeParentElementXML } from '../../xml-serialization.ts';
+
+export const createRootInstanceState = (node: Root): InstanceState => {
+	return {
+		get instanceXML() {
+			const { namespaceDeclarations, attributes } = node.definition;
+			const serializedChildren = node.currentState.children.map((child) => {
+				return child.instanceState.instanceXML;
+			});
+
+			return serializeParentElementXML(node.definition.qualifiedName, serializedChildren, {
+				namespaceDeclarations,
+				attributes: Array.from(attributes.values()),
+			});
+		},
+	};
+};

package/src/lib/client-reactivity/instance-state/createTemplatedNodeInstanceState.ts

@@ -0,0 +1,31 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import { TemplatedNodeAttributeSerializationError } from '../../../error/TemplatedNodeAttributeSerializationError.ts';
+import type { ClientReactiveSerializableTemplatedNode } from '../../../instance/internal-api/serialization/ClientReactiveSerializableTemplatedNode.ts';
+import { serializeParentElementXML } from '../../xml-serialization.ts';
+
+/**
+ * @see {@link TemplatedNodeAttributeSerializationError}
+ */
+export const createTemplatedNodeInstanceState = (
+	node: ClientReactiveSerializableTemplatedNode
+): InstanceState => {
+	return {
+		get instanceXML() {
+			if (!node.currentState.relevant) {
+				return '';
+			}
+
+			const serializedChildren = node.currentState.children.map((child) => {
+				return child.instanceState.instanceXML;
+			});
+
+			const { attributes } = node.currentState;
+
+			if (attributes != null) {
+				throw new TemplatedNodeAttributeSerializationError();
+			}
+
+			return serializeParentElementXML(node.definition.qualifiedName, serializedChildren);
+		},
+	};
+};

package/src/lib/client-reactivity/instance-state/createValueNodeInstanceState.ts

@@ -0,0 +1,21 @@
+import type { InstanceState } from '../../../client/serialization/InstanceState.ts';
+import type { ClientReactiveSerializableValueNode } from '../../../instance/internal-api/serialization/ClientReactiveSerializableValueNode.ts';
+import { escapeXMLText, serializeLeafElementXML } from '../../xml-serialization.ts';
+
+export const createValueNodeInstanceState = (
+	node: ClientReactiveSerializableValueNode
+): InstanceState => {
+	const { qualifiedName } = node.definition;
+
+	return {
+		get instanceXML() {
+			if (!node.currentState.relevant) {
+				return '';
+			}
+
+			const xmlValue = escapeXMLText(node.currentState.instanceValue);
+
+			return serializeLeafElementXML(qualifiedName, xmlValue);
+		},
+	};
+};

package/src/lib/client-reactivity/instance-state/prepareInstancePayload.ts

@@ -0,0 +1,173 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE } from '../../../client/constants.ts';
+import type { InstanceData as ClientInstanceData } from '../../../client/serialization/InstanceData.ts';
+import type { InstanceFile as ClientInstanceFile } from '../../../client/serialization/InstanceFile.ts';
+import type {
+	ChunkedInstancePayload,
+	InstancePayload,
+	MonolithicInstancePayload,
+} from '../../../client/serialization/InstancePayload.ts';
+import type { InstancePayloadType } from '../../../client/serialization/InstancePayloadOptions.ts';
+import type { SubmissionMeta } from '../../../client/submission/SubmissionMeta.ts';
+import type { DescendantNodeViolationReference } from '../../../client/validation.ts';
+import type { ClientReactiveSerializableInstance } from '../../../instance/internal-api/serialization/ClientReactiveSerializableInstance.ts';
+
+class InstanceFile extends File implements ClientInstanceFile {
+	override readonly name = INSTANCE_FILE_NAME;
+	override readonly type = INSTANCE_FILE_TYPE;
+
+	constructor(instanceRoot: ClientReactiveSerializableInstance) {
+		const { instanceXML } = instanceRoot.instanceState;
+
+		super([instanceXML], INSTANCE_FILE_NAME, {
+			type: INSTANCE_FILE_TYPE,
+		});
+	}
+}
+
+type AssertInstanceData = (data: FormData) => asserts data is ClientInstanceData;
+
+const assertInstanceData: AssertInstanceData = (data) => {
+	const instanceFile = data.get(INSTANCE_FILE_NAME);
+
+	if (!(instanceFile instanceof InstanceFile)) {
+		throw new Error(`Invalid InstanceData`);
+	}
+};
+
+class InstanceData extends FormData {
+	static from(instanceFile: InstanceFile, attachments: readonly File[]): ClientInstanceData {
+		const data = new this(instanceFile, attachments);
+
+		assertInstanceData(data);
+
+		return data;
+	}
+
+	private constructor(
+		readonly instanceFile: InstanceFile,
+		readonly attachments: readonly File[]
+	) {
+		super();
+
+		this.set(INSTANCE_FILE_NAME, instanceFile);
+
+		attachments.forEach((attachment) => {
+			const { name } = attachment;
+
+			if (name === INSTANCE_FILE_NAME && attachment !== instanceFile) {
+				throw new Error(`Failed to add conflicting attachment with name ${INSTANCE_FILE_NAME}`);
+			}
+
+			this.set(name, attachment);
+		});
+	}
+}
+
+interface PendingValidation {
+	readonly status: 'pending';
+	readonly violations: readonly DescendantNodeViolationReference[];
+}
+
+interface ReadyValidation {
+	readonly status: 'ready';
+	readonly violations: null;
+}
+
+type InstanceStateValidation = PendingValidation | ReadyValidation;
+
+const validateInstance = (
+	instanceRoot: ClientReactiveSerializableInstance
+): InstanceStateValidation => {
+	const { violations } = instanceRoot.validationState;
+
+	if (violations.length === 0) {
+		return {
+			status: 'ready',
+			violations: null,
+		};
+	}
+
+	return {
+		status: 'pending',
+		violations,
+	};
+};
+
+const monolithicInstancePayload = (
+	validation: InstanceStateValidation,
+	submissionMeta: SubmissionMeta,
+	instanceFile: InstanceFile,
+	attachments: readonly File[]
+): MonolithicInstancePayload => {
+	const data = InstanceData.from(instanceFile, attachments);
+
+	return {
+		payloadType: 'monolithic',
+		...validation,
+		submissionMeta,
+		data: [data],
+	};
+};
+
+interface ChunkedInstancePayloadOptions {
+	readonly maxSize: number;
+}
+
+const chunkedInstancePayload = (
+	validation: InstanceStateValidation,
+	submissionMeta: SubmissionMeta,
+	instanceFile: InstanceFile,
+	attachments: readonly File[],
+	options: ChunkedInstancePayloadOptions
+): ChunkedInstancePayload => {
+	if (attachments.length > 0 || options.maxSize !== Infinity) {
+		throw new Error('InstancePayload chunking pending implementation');
+	}
+
+	const data = InstanceData.from(instanceFile, attachments);
+
+	return {
+		payloadType: 'chunked',
+		...validation,
+		submissionMeta,
+		data: [data],
+	};
+};
+
+export interface PrepareInstancePayloadOptions<PayloadType extends InstancePayloadType> {
+	readonly payloadType: PayloadType;
+	readonly maxSize: number;
+}
+
+export const prepareInstancePayload = <PayloadType extends InstancePayloadType>(
+	instanceRoot: ClientReactiveSerializableInstance,
+	options: PrepareInstancePayloadOptions<PayloadType>
+): InstancePayload<PayloadType> => {
+	const validation = validateInstance(instanceRoot);
+	const submissionMeta = instanceRoot.definition.submission;
+	const instanceFile = new InstanceFile(instanceRoot);
+	const attachments: readonly File[] = [];
+
+	switch (options.payloadType) {
+		case 'chunked':
+			return chunkedInstancePayload(
+				validation,
+				submissionMeta,
+				instanceFile,
+				attachments,
+				options
+			) satisfies ChunkedInstancePayload as InstancePayload<PayloadType>;
+
+		case 'monolithic':
+			return monolithicInstancePayload(
+				validation,
+				submissionMeta,
+				instanceFile,
+				attachments
+			) satisfies MonolithicInstancePayload as InstancePayload<PayloadType>;
+
+		default:
+			throw new UnreachableError(options.payloadType);
+	}
+};

package/src/lib/codecs/Geopoint/Geopoint.ts

@@ -0,0 +1,150 @@
+/**
+ * This abstract class defines the minimal behavior for a default geopoint.
+ * It can be expanded later to support units (e.g., degrees or meters),
+ * which would also serve as documentation to clarify what each value represents.
+ */
+abstract class SemanticValue<Semantic extends string, Value extends number | null> {
+	abstract readonly semantic: Semantic;
+
+	constructor(readonly value: Value) {}
+}
+
+class Latitude extends SemanticValue<'latitude', number> {
+	readonly semantic = 'latitude';
+}
+
+class Longitude extends SemanticValue<'longitude', number> {
+	readonly semantic = 'longitude';
+}
+
+class Altitude<Value extends number | null = number> extends SemanticValue<'altitude', Value> {
+	readonly semantic = 'altitude';
+}
+
+class Accuracy<Value extends number | null = number> extends SemanticValue<'accuracy', Value> {
+	readonly semantic = 'accuracy';
+}
+
+export interface GeopointValue {
+	readonly latitude: number;
+	readonly longitude: number;
+	readonly altitude: number | null;
+	readonly accuracy: number | null;
+}
+
+export type GeopointRuntimeValue = GeopointValue | null;
+
+// TODO: Add support for GeoJSONValue
+export type GeopointInputValue = GeopointRuntimeValue | string;
+
+interface GeopointInternalValue {
+	readonly latitude: Latitude;
+	readonly longitude: Longitude;
+	readonly altitude: Altitude<null> | Altitude<number>;
+	readonly accuracy: Accuracy<null> | Accuracy<number>;
+}
+
+type GeopointTuple =
+	| readonly [
+			latitude: Latitude,
+			longitude: Longitude,
+			altitude: Altitude<null> | Altitude<number>,
+			accuracy: Accuracy,
+	  ]
+	| readonly [latitude: Latitude, longitude: Longitude, altitude: Altitude]
+	| readonly [latitude: Latitude, longitude: Longitude];
+
+const DEGREES_MAX = {
+	latitude: 90,
+	longitude: 180,
+} as const;
+
+type CoordinateType = keyof typeof DEGREES_MAX;
+
+export class Geopoint {
+	private readonly internalValue: GeopointInternalValue;
+
+	constructor(coordinates: GeopointValue) {
+		const { latitude, longitude, altitude, accuracy } = coordinates;
+
+		this.internalValue = {
+			latitude: new Latitude(latitude),
+			longitude: new Longitude(longitude),
+			altitude: this.isValidNumber(altitude) ? new Altitude(altitude) : new Altitude(null),
+			accuracy: this.isValidNumber(accuracy) ? new Accuracy(accuracy) : new Accuracy(null),
+		};
+	}
+
+	getTuple(): GeopointTuple {
+		const { latitude, longitude, altitude, accuracy } = this.internalValue;
+
+		if (accuracy.value != null) {
+			return [latitude, longitude, altitude, accuracy];
+		}
+
+		if (altitude.value != null) {
+			return [latitude, longitude, altitude];
+		}
+
+		return [latitude, longitude];
+	}
+
+	getRuntimeValue(): GeopointRuntimeValue {
+		const { latitude, longitude, altitude, accuracy } = this.internalValue;
+		const isLatitude = this.isValidDegrees('latitude', latitude.value);
+		const isLongitude = this.isValidDegrees('longitude', longitude.value);
+
+		if (!isLatitude || !isLongitude || Geopoint.isNullLocation(latitude.value, longitude.value)) {
+			return null;
+		}
+
+		return {
+			latitude: latitude.value,
+			longitude: longitude.value,
+			altitude: altitude.value,
+			accuracy: accuracy.value,
+		};
+	}
+
+	private isValidDegrees(coordinate: CoordinateType, degrees: number): degrees is number {
+		return this.isValidNumber(degrees) && Math.abs(degrees) <= DEGREES_MAX[coordinate];
+	}
+
+	private isValidNumber(value: number | null | undefined) {
+		return value != null && !Number.isNaN(value);
+	}
+
+	private static isNullLocation(latitude: number, longitude: number) {
+		return latitude === 0 && longitude === 0;
+	}
+
+	static parseString(value: string): GeopointRuntimeValue {
+		if (value.trim() === '') {
+			return null;
+		}
+
+		const [latitude, longitude, altitude = null, accuracy = null] = value.split(/\s+/).map(Number);
+
+		if (latitude == null || longitude == null || Number.isNaN(altitude) || Number.isNaN(accuracy)) {
+			return null;
+		}
+
+		return new this({ latitude, longitude, altitude, accuracy }).getRuntimeValue();
+	}
+
+	static toCoordinatesString(value: GeopointInputValue): string {
+		const decodedValue = typeof value === 'string' ? Geopoint.parseString(value) : value;
+
+		if (
+			decodedValue == null ||
+			Geopoint.isNullLocation(decodedValue.latitude, decodedValue.longitude)
+		) {
+			return '';
+		}
+
+		return new this(decodedValue)
+			.getTuple()
+			.map((item) => item.value ?? 0)
+			.join(' ');
+	}
+}

package/src/lib/codecs/Geopoint/GeopointValueCodec.ts

@@ -0,0 +1,20 @@
+import { type CodecDecoder, type CodecEncoder, ValueCodec } from '../ValueCodec.ts';
+import { Geopoint, type GeopointInputValue, type GeopointRuntimeValue } from './Geopoint.ts';
+
+export class GeopointValueCodec extends ValueCodec<
+	'geopoint',
+	GeopointRuntimeValue,
+	GeopointInputValue
+> {
+	constructor() {
+		const encodeValue: CodecEncoder<GeopointInputValue> = (value) => {
+			return Geopoint.toCoordinatesString(value);
+		};
+
+		const decodeValue: CodecDecoder<GeopointRuntimeValue> = (value: string) => {
+			return Geopoint.parseString(value);
+		};
+
+		super('geopoint', encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/NoteCodec.ts

@@ -0,0 +1,32 @@
+import type { ValueType } from '../../client/ValueType.ts';
+import type { RuntimeInputValue, RuntimeValue, SharedValueCodec } from './getSharedValueCodec.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+// prettier-ignore
+export type NoteRuntimeValue<V extends ValueType> =
+	| RuntimeValue<V>
+	| null;
+
+// prettier-ignore
+export type NoteInputValue<V extends ValueType> =
+	| RuntimeInputValue<V>
+	| RuntimeValue<V>
+	| null;
+
+export class NoteCodec<V extends ValueType> extends ValueCodec<
+	V,
+	NoteRuntimeValue<V>,
+	NoteInputValue<V>
+> {
+	constructor(baseCodec: SharedValueCodec<V>) {
+		const encodeValue = (value: NoteInputValue<V>): string => {
+			return baseCodec.encodeValue(value ?? '');
+		};
+
+		const decodeValue = (value: string): NoteRuntimeValue<V> => {
+			return value === '' ? null : baseCodec.decodeValue(value);
+		};
+
+		super(baseCodec.valueType, encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/RangeCodec.ts

@@ -0,0 +1,65 @@
+import type { RangeValue } from '../../client/RangeNode.ts';
+import { ValueTypeInvariantError } from '../../error/ValueTypeInvariantError.ts';
+import type { RangeNodeDefinition, RangeValueType } from '../../parse/model/RangeNodeDefinition.ts';
+import type { RuntimeInputValue, RuntimeValue, SharedValueCodec } from './getSharedValueCodec.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+export type RangeRuntimeValue<V extends RangeValueType> = RuntimeValue<V>;
+
+export type RangeInputValue<V extends RangeValueType> = RuntimeInputValue<V>;
+
+export class RangeCodec<V extends RangeValueType> extends ValueCodec<
+	V,
+	RangeRuntimeValue<V>,
+	RangeInputValue<V>
+> {
+	constructor(baseCodec: SharedValueCodec<V>, definition: RangeNodeDefinition<V>) {
+		const { valueType, bounds } = definition;
+		const { min, max } = bounds;
+
+		type ComparableRangeValue = bigint | number | null;
+
+		const toComparableValue = (value: RangeInputValue<V>): ComparableRangeValue => {
+			if (value == null) {
+				return value;
+			}
+
+			if (typeof value === 'string') {
+				return baseCodec.decodeValue(value);
+			}
+
+			return value;
+		};
+
+		const assertBounds = (value: RuntimeInputValue<V>) => {
+			const comparableValue = toComparableValue(value);
+
+			if (comparableValue == null) {
+				return;
+			}
+
+			if (comparableValue < min || comparableValue > max) {
+				throw new ValueTypeInvariantError(
+					valueType,
+					`Expected value to be within bounds [${min}, ${max}]. Got: ${value}`
+				);
+			}
+		};
+
+		const encodeValue = (value: RangeInputValue<V>): string => {
+			assertBounds(value);
+
+			return baseCodec.encodeValue(value);
+		};
+
+		const decodeValue = (value: string): RangeValue<V> => {
+			const decoded = baseCodec.decodeValue(value);
+
+			assertBounds(value);
+
+			return decoded;
+		};
+
+		super(valueType, encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/TempUnsupportedControlCodec.ts

@@ -0,0 +1,32 @@
+import { identity } from '@getodk/common/lib/identity.ts';
+import type { ValueType } from '../../client/ValueType.ts';
+import { ValueCodec, type CodecDecoder, type CodecEncoder } from './ValueCodec.ts';
+
+class TempUnsupportedControlEncodeError extends Error {
+	constructor() {
+		super(`Cannot encode state: not implemented`);
+	}
+}
+
+export type TempUnsupportedRuntimeValue = unknown;
+export type TempUnsupportedInputValue = unknown;
+
+export class TempUnsupportedControlCodec<V extends ValueType> extends ValueCodec<
+	V,
+	TempUnsupportedRuntimeValue,
+	TempUnsupportedInputValue
+> {
+	constructor(valueType: V) {
+		const encodeValue: CodecEncoder<TempUnsupportedRuntimeValue> = (input): string => {
+			if (typeof input === 'string') {
+				return input;
+			}
+
+			throw new TempUnsupportedControlEncodeError();
+		};
+
+		const decodeValue: CodecDecoder<TempUnsupportedInputValue> = identity;
+
+		super(valueType, encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/TriggerCodec.ts

@@ -0,0 +1,64 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+export type TriggerValueType = 'string';
+
+export type TriggerRuntimeValue = boolean;
+
+export type TriggerInputValue = boolean | '' | null;
+
+type BaseTriggerInstanceValueMapping = Readonly<Record<string, string>>;
+
+const TRIGGER_INSTANCE_VALUES = {
+	true: 'OK',
+	false: '',
+} as const satisfies BaseTriggerInstanceValueMapping;
+
+type TriggerInstanceValueMapping = typeof TRIGGER_INSTANCE_VALUES;
+
+type TriggerInstanceValue = TriggerInstanceValueMapping[keyof TriggerInstanceValueMapping];
+
+const encodeTriggerValue = (value: TriggerInputValue): TriggerInstanceValue => {
+	switch (value) {
+		case true:
+			return TRIGGER_INSTANCE_VALUES.true;
+
+		case false:
+		case '':
+		case null:
+			return TRIGGER_INSTANCE_VALUES.false;
+
+		default:
+			throw new UnreachableError(value);
+	}
+};
+
+const decodeTriggerValue = (value: string): TriggerRuntimeValue => {
+	if (value === 'OK') {
+		return true;
+	}
+
+	if (value === '') {
+		return false;
+	}
+
+	if (value.toLowerCase() === 'ok') {
+		// eslint-disable-next-line no-console
+		console.warn('Treating trigger value as case-insensitive:', value);
+
+		return true;
+	}
+
+	throw new ErrorProductionDesignPendingError(`Unexpected trigger value: ${value}`);
+};
+
+export class TriggerCodec extends ValueCodec<
+	TriggerValueType,
+	TriggerRuntimeValue,
+	TriggerInputValue
+> {
+	constructor() {
+		super('string', encodeTriggerValue, decodeTriggerValue);
+	}
+}