@getodk/xforms-engine 0.4.0 → 0.6.0

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/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/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/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/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);
+	}
+}

package/src/lib/codecs/ValueArrayCodec.ts

@@ -0,0 +1,42 @@
+import type { ValueType } from '../../client/ValueType.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { RuntimeValue, SharedValueCodec } from './getSharedValueCodec.ts';
+import type { CodecDecoder, CodecEncoder } from './ValueCodec.ts';
+import { ValueCodec } from './ValueCodec.ts';
+
+export type SplitInstanceValues = (value: string) => readonly string[];
+
+export type JoinInstnaceValues = (values: readonly string[]) => string;
+
+export type RuntimeItemValue<V extends ValueType> = NonNullable<RuntimeValue<V>>;
+
+export type RuntimeValues<V extends ValueType> = ReadonlyArray<RuntimeItemValue<V>>;
+
+export abstract class ValueArrayCodec<
+	V extends ValueType,
+	Values extends RuntimeValues<V> = RuntimeValues<V>,
+> extends ValueCodec<V, Values, Values> {
+	readonly decodeItemValue: CodecDecoder<RuntimeItemValue<V>>;
+
+	constructor(
+		baseCodec: SharedValueCodec<V>,
+		encodeValue: CodecEncoder<Values>,
+		decodeValue: CodecDecoder<Values>
+	) {
+		const decodeItemValue: CodecDecoder<RuntimeItemValue<V>> = (value) => {
+			const decoded = baseCodec.decodeValue(value);
+
+			if (decoded == null) {
+				throw new ErrorProductionDesignPendingError(
+					`Failed to decode item value: ${JSON.stringify(value)}`
+				);
+			}
+
+			return decoded;
+		};
+
+		super(baseCodec.valueType, encodeValue, decodeValue);
+
+		this.decodeItemValue = decodeItemValue;
+	}
+}

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';
+
+export type CodecEncoder<RuntimeInputValue> = (input: RuntimeInputValue) => string;
+
+export 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/getNoteCodec.ts

@@ -0,0 +1,27 @@
+import type { ValueType } from '../../client/ValueType.ts';
+import { sharedValueCodecs } from './getSharedValueCodec.ts';
+import { NoteCodec } from './NoteCodec.ts';
+
+type NoteCodecs = {
+	readonly [V in ValueType]: NoteCodec<V>;
+};
+
+const noteCodecs: NoteCodecs = {
+	string: new NoteCodec(sharedValueCodecs.string),
+	int: new NoteCodec(sharedValueCodecs.int),
+	decimal: new NoteCodec(sharedValueCodecs.decimal),
+	boolean: new NoteCodec(sharedValueCodecs.boolean),
+	date: new NoteCodec(sharedValueCodecs.date),
+	time: new NoteCodec(sharedValueCodecs.time),
+	dateTime: new NoteCodec(sharedValueCodecs.dateTime),
+	geopoint: new NoteCodec(sharedValueCodecs.geopoint),
+	geotrace: new NoteCodec(sharedValueCodecs.geotrace),
+	geoshape: new NoteCodec(sharedValueCodecs.geoshape),
+	binary: new NoteCodec(sharedValueCodecs.binary),
+	barcode: new NoteCodec(sharedValueCodecs.barcode),
+	intent: new NoteCodec(sharedValueCodecs.intent),
+};
+
+export const getNoteCodec = <V extends ValueType>(valueType: V): NoteCodec<V> => {
+	return noteCodecs[valueType];
+};

package/src/lib/codecs/getSelectCodec.ts

@@ -0,0 +1,27 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import type { SelectDefinition } from '../../client/SelectNode.ts';
+import { sharedValueCodecs } from './getSharedValueCodec.ts';
+import { MultipleValueItemCodec } from './items/MultipleValueItemCodec.ts';
+import { SingleValueItemCodec } from './items/SingleValueItemCodec.ts';
+
+const multipleValueSelectCodec = new MultipleValueItemCodec(sharedValueCodecs.string);
+
+const singleValueSelectCodec = new SingleValueItemCodec(sharedValueCodecs.string);
+
+// prettier-ignore
+export type SelectCodec =
+	| MultipleValueItemCodec
+	| SingleValueItemCodec;
+
+export const getSelectCodec = (definition: SelectDefinition<'string'>): SelectCodec => {
+	switch (definition.bodyElement.type) {
+		case 'select':
+			return multipleValueSelectCodec;
+
+		case 'select1':
+			return singleValueSelectCodec;
+
+		default:
+			throw new UnreachableError(definition.bodyElement.type);
+	}
+};