@getodk/xforms-engine 0.1.0

package/src/lib/reactivity/createValueState.ts

@@ -0,0 +1,258 @@
+import { createComputed, createMemo, createSignal, untrack } from 'solid-js';
+import type { DependentExpression } from '../../expression/DependentExpression.ts';
+import type { SubscribableDependency } from '../../instance/internal-api/SubscribableDependency.ts';
+import type { ValueContext } from '../../instance/internal-api/ValueContext.ts';
+import type { BindComputation } from '../../model/BindComputation.ts';
+import { createComputedExpression } from './createComputedExpression.ts';
+import type { SimpleAtomicState, SimpleAtomicStateSetter } from './types.ts';
+
+type InitialValueSource = 'FORM_DEFAULT' | 'PRIMARY_INSTANCE';
+
+export interface ValueStateOptions {
+	/**
+	 * Specifies the source of a {@link createValueState} signal's initial
+	 * value state, where:
+	 *
+	 * - 'FORM_DEFAULT': Derives the initial state from the form's
+	 *   definition of the node itself. This is the default option, appropriate
+	 *   when initializing a form without additional primary instance data. In
+	 *   other words, this value should not be used for edits.
+	 *
+	 * - 'PRIMARY_INSTANCE': Derives the initial state from the current text
+	 *   content of the {@link ValueNode.contextNode} (currently an XML DOM
+	 *   backing store/source of thruth for primary instance state). This option
+	 *   should be specified when initializing a form with existing primary
+	 *   instance data, such as when editing a previous submission.
+	 *
+	 * @default 'FORM_DEFAULT'
+	 *
+	 * Specifies whether a {@link createV} signal's initial state
+	 * should be derived from the current text content of the
+	 * {@link ValueNode.contextNode | primary instance DOM state}.
+	 */
+	readonly initialValueSource?: InitialValueSource;
+}
+
+interface PersistedValueState {
+	readonly isRelevant: boolean;
+	readonly value: string;
+}
+
+type PrimaryInstanceValueState = SimpleAtomicState<string>;
+
+type ValueState<RuntimeValue> = SimpleAtomicState<RuntimeValue>;
+
+/**
+ * Creates a signal which:
+ *
+ * 1. Persists its state to the primary instance's
+ *    {@link ValueContext.contextNode | contextNode} on state changes.
+ * 2. Propagates downstream reactivity only after that write is persisted.
+ *
+ * This ensures that reactive subscriptions get a consistent view of a node's
+ * current state, regardless of whether they derive state from values in the
+ * primary instance (currently: computed {@link DependentExpression}
+ * evaluations) or from other aspects of reactive runtime state (generally,
+ * everything besides computed {@link DependentExpression}s).
+ */
+const createPrimaryInstanceValueState = <RuntimeValue>(
+	context: ValueContext<RuntimeValue>,
+	options: ValueStateOptions
+): PrimaryInstanceValueState => {
+	const { contextNode, definition, scope } = context;
+	const { initialValueSource } = options;
+	const { defaultValue } = definition;
+
+	return scope.runTask(() => {
+		// prettier-ignore
+		const initialValue =
+			initialValueSource === 'PRIMARY_INSTANCE'
+				? contextNode.textContent ?? defaultValue
+				: defaultValue;
+
+		const persistedValueState = createSignal<PersistedValueState>(
+			{
+				isRelevant: context.isRelevant,
+				value: initialValue,
+			},
+			{
+				// This could return a single boolean expression, but checking each
+				// equality condition separately feels like it more clearly expresses
+				// the intent.
+				equals: (previous, updated) => {
+					if (updated.isRelevant !== previous.isRelevant) {
+						return false;
+					}
+
+					return updated.value === previous.value;
+				},
+			}
+		);
+		const [persistedValue, setValueForPersistence] = persistedValueState;
+
+		createComputed(() => {
+			const isRelevant = context.isRelevant;
+
+			setValueForPersistence((persisted) => {
+				return {
+					isRelevant,
+					value: persisted.value,
+				};
+			});
+		});
+
+		const toSignalValue = (current: PersistedValueState): string => {
+			if (current.isRelevant) {
+				return current.value;
+			}
+
+			return '';
+		};
+
+		const [signalValue, setSignalValue] = createSignal(toSignalValue(persistedValue()));
+
+		createComputed(() => {
+			const { isRelevant, value } = persistedValue();
+			const preparedTextContent = isRelevant ? value : '';
+			const assignedTextContent = (contextNode.textContent = preparedTextContent);
+
+			setSignalValue(assignedTextContent);
+		});
+
+		const setPrimaryInstanceValue: SimpleAtomicStateSetter<string> = (value) => {
+			// TODO: Check (error?) for non-relevant value change?
+			const persisted = setValueForPersistence({
+				isRelevant: context.isRelevant,
+				value,
+			});
+
+			return persisted.value;
+		};
+
+		return [signalValue, setPrimaryInstanceValue];
+	});
+};
+
+/**
+ * Wraps a node's {@link PrimaryInstanceValueState} in a signal-like interface
+ * which automatically encodes and decodes a node's runtime value
+ * representation:
+ *
+ * - Values read by a node will be read from the current state as persisted in
+ *   the primary instance, then {@link ValueContext.decodeValue | decoded} (as
+ *   implemented by that node) into a format suitable for the rest of the
+ *   functionality provided by that node.
+ *
+ * - Values written by a node will be {@link ValueContext.encodeValue | encoded}
+ *   (also as implemented by that node) into a string appropriate to persist to
+ *   the primary instance, and written to it as such.
+ *
+ * - Downstream reactive computations should subscribe to updates to this
+ *   runtime state (suggesting the value node itself should access this state in
+ *   its {@link SubscribableDependency.subscribe} implementation).
+ */
+const createRuntimeValueState = <RuntimeValue>(
+	context: ValueContext<RuntimeValue>,
+	primaryInstanceState: PrimaryInstanceValueState
+): ValueState<RuntimeValue> => {
+	const { decodeValue, encodeValue } = context;
+
+	return context.scope.runTask(() => {
+		const [primaryInstanceValue, setPrimaryInstanceValue] = primaryInstanceState;
+		const getRuntimeValue = createMemo(() => {
+			return decodeValue(primaryInstanceValue());
+		});
+		const setRuntimeValue: SimpleAtomicStateSetter<RuntimeValue> = (value) => {
+			const encodedValue = encodeValue(value);
+
+			return decodeValue(setPrimaryInstanceValue(encodedValue));
+		};
+
+		return [getRuntimeValue, setRuntimeValue];
+	});
+};
+
+/**
+ * For fields with a `readonly` bind expression, prevent downstream
+ * (client/user) writes when the field is in a `readonly` state.
+ */
+const guardDownstreamReadonlyWrites = <RuntimeValue>(
+	context: ValueContext<RuntimeValue>,
+	baseState: SimpleAtomicState<RuntimeValue>
+): SimpleAtomicState<RuntimeValue> => {
+	const { readonly } = context.definition.bind;
+
+	if (readonly.isDefaultExpression) {
+		return baseState;
+	}
+
+	const [getValue, baseSetValue] = baseState;
+
+	const setValue: SimpleAtomicStateSetter<RuntimeValue> = (value) => {
+		if (context.isReadonly) {
+			const reference = untrack(() => context.contextReference);
+
+			throw new Error(`Cannot write to readonly field: ${reference}`);
+		}
+
+		return baseSetValue(value);
+	};
+
+	return [getValue, setValue];
+};
+
+/**
+ * Defines a reactive effect which writes the result of `calculate` bind
+ * computations to the provided value setter, on initialization and any
+ * subsequent reactive update.
+ */
+const createCalculation = <RuntimeValue>(
+	context: ValueContext<RuntimeValue>,
+	setValue: SimpleAtomicStateSetter<RuntimeValue>,
+	calculateDefinition: BindComputation<'calculate'>
+): void => {
+	context.scope.runTask(() => {
+		const calculate = createComputedExpression(context, calculateDefinition);
+
+		createComputed(() => {
+			if (context.isRelevant) {
+				const calculated = calculate();
+				const value = context.decodeValue(calculated);
+
+				setValue(value);
+			}
+		});
+	});
+};
+
+/**
+ * Provides a consistent interface for value nodes of any type which:
+ *
+ * - derives initial state from either the existing primary instance state (e.g.
+ *   for edits) or the node's definition (e.g. initializing a new submission)
+ * - decodes primary instance state into the value node's runtime type
+ * - encodes and persists updated values to the primary instance
+ * - initializes reactive computation of `calculate` bind expressions for those
+ *   nodes defined with one
+ * - ensures any downstream reactive dependencies are updated only after writes
+ *   (whether performed by a client, or by a reactive `calculate` computation)
+ *   are persisted, ensuring a consistent view of state when downstream
+ *   computations perform XPath evaluations against that primary instance state
+ */
+export const createValueState = <RuntimeValue>(
+	context: ValueContext<RuntimeValue>,
+	options: ValueStateOptions = {}
+): ValueState<RuntimeValue> => {
+	const primaryInstanceState = createPrimaryInstanceValueState(context, options);
+	const runtimeState = createRuntimeValueState(context, primaryInstanceState);
+
+	const { calculate } = context.definition.bind;
+
+	if (calculate != null) {
+		const [, setValue] = runtimeState;
+
+		createCalculation(context, setValue, calculate);
+	}
+
+	return guardDownstreamReadonlyWrites(context, runtimeState);
+};

package/src/lib/reactivity/materializeCurrentStateChildren.ts

@@ -0,0 +1,121 @@
+import type { AnyChildNode } from '../../instance/hierarchy.ts';
+import type { NodeID } from '../../instance/identity.ts';
+import type { ChildrenState, createChildrenState } from './createChildrenState.ts';
+import type { ClientState } from './node-state/createClientState.ts';
+import type { CurrentState } from './node-state/createCurrentState.ts';
+
+interface InconsistentChildrenStateDetails {
+	readonly missingIds: readonly NodeID[];
+	readonly unexpectedIds: readonly NodeID[];
+}
+
+class InconsistentChildrenStateError extends Error {
+	constructor(details: InconsistentChildrenStateDetails) {
+		const { missingIds, unexpectedIds } = details;
+
+		const messageLines = ['Detected inconsistent engine/client child state.'];
+
+		if (missingIds.length > 0) {
+			const missingIdLines = missingIds.map((missingId) => {
+				return `- ${missingId}`;
+			});
+
+			messageLines.push('\nMissing child nodes for ids:\n', ...missingIdLines);
+		}
+
+		if (unexpectedIds.length > 0) {
+			const unexpectedIdLines = unexpectedIds.map((unexpectedId) => {
+				return `- ${unexpectedId}`;
+			});
+
+			messageLines.push('\nUnexpected child nodes with ids:\n', ...unexpectedIdLines);
+		}
+
+		super(messageLines.join('\n'));
+	}
+}
+
+export interface EncodedParentState {
+	readonly children: readonly NodeID[];
+}
+
+/**
+ * For potential use when debugging in dev mode. The assumption is that we do
+ * not believe the implementation **should** produce inconsistencies between:
+ *
+ * 1. The internal `children` state of a node
+ * 2. The corresponding, internally computed `engineState.children` node ID list
+ * 3. The reactively written `clientState.children` node ID list
+ * 4. The reactively read `currentState.children` node ID list
+ * 5. The read state of #1 as produced when a client reads #4
+ *
+ * For now we can check for this in dev mode and warn if any aspect of this
+ * assumption deviates from reality. We should aim to confirm this so that we
+ * can confidently skip this check in production (as it would effectively be
+ * wasted CPU cycles).
+ *
+ * @todo should we throw rather than warn until we have this confidence?
+ */
+const reportInconsistentChildrenState = (
+	expectedClientIds: readonly NodeID[],
+	actualNodes: readonly AnyChildNode[]
+): void => {
+	const actualIds = actualNodes.map((node) => node.nodeId);
+	const missingIds = expectedClientIds.filter((expectedId) => {
+		return !actualIds.includes(expectedId);
+	});
+	const unexpectedIds = actualIds.filter((actualId) => {
+		return !expectedClientIds.includes(actualId);
+	});
+
+	if (missingIds.length > 0 || unexpectedIds.length > 0) {
+		throw new InconsistentChildrenStateError({
+			missingIds,
+			unexpectedIds,
+		});
+	}
+};
+
+// prettier-ignore
+export type MaterializedChildren<
+	BaseState extends EncodedParentState,
+	Child extends AnyChildNode | null
+> =
+	& Omit<BaseState, 'children'>
+	& { readonly children: readonly Child[] };
+
+/**
+ * Creates a wrapper proxy around a parent node's {@link CurrentState} to map
+ * `children` state, which is written to the node's (internal, synchronized)
+ * {@link ClientState} as an array of {@link NodeID}s, back to the node objects
+ * corresponding to those IDs.
+ *
+ * @see {@link createChildrenState} for further detail.
+ */
+export const materializeCurrentStateChildren = <
+	Child extends AnyChildNode,
+	ParentState extends EncodedParentState,
+>(
+	currentState: ParentState,
+	childrenState: ChildrenState<Child>
+): MaterializedChildren<ParentState, Child> => {
+	const baseState: Omit<ParentState, 'children'> = currentState;
+	const proxyTarget = baseState as MaterializedChildren<ParentState, Child>;
+
+	return new Proxy(proxyTarget, {
+		get(_, key) {
+			if (key === 'children') {
+				const expectedChildIDs = currentState.children;
+				const children = childrenState.getChildren();
+
+				if (import.meta.env.DEV) {
+					reportInconsistentChildrenState(expectedChildIDs, children);
+				}
+
+				return children;
+			}
+
+			return baseState[key as Exclude<keyof ParentState, 'children'>];
+		},
+	});
+};

package/src/lib/reactivity/node-state/createClientState.ts

@@ -0,0 +1,51 @@
+import { getPropertyKeys } from '@getodk/common/lib/objects/structure.ts';
+import type { ShallowMutable } from '@getodk/common/types/helpers.js';
+import { createComputed, untrack } from 'solid-js';
+import type { OpaqueReactiveObjectFactory } from '../../../index.ts';
+import type { ReactiveScope } from '../scope.ts';
+import type { EngineState } from './createEngineState.ts';
+import type { SpecifiedState, StateSpec } from './createSpecifiedState.ts';
+import type { InternalClientRepresentation } from './representations.ts';
+import { declareInternalClientRepresentation } from './representations.ts';
+
+const deriveInitialState = <Spec extends StateSpec>(
+	scope: ReactiveScope,
+	engineState: EngineState<Spec>
+): ShallowMutable<SpecifiedState<Spec>> => {
+	return scope.runTask(() => {
+		return untrack(() => {
+			return { ...engineState };
+		});
+	});
+};
+
+export type SpecifiedClientStateFactory<
+	Factory extends OpaqueReactiveObjectFactory,
+	Spec extends StateSpec,
+> = ShallowMutable<SpecifiedState<Spec>> extends Parameters<Factory>[0] ? Factory : never;
+
+export type ClientState<Spec extends StateSpec> = InternalClientRepresentation<
+	SpecifiedState<Spec>
+>;
+
+export const createClientState = <
+	Factory extends OpaqueReactiveObjectFactory,
+	Spec extends StateSpec,
+>(
+	scope: ReactiveScope,
+	engineState: EngineState<Spec>,
+	clientStateFactory: SpecifiedClientStateFactory<Factory, Spec>
+): ClientState<Spec> => {
+	const initialState = deriveInitialState(scope, engineState);
+	const clientState = clientStateFactory(initialState);
+
+	scope.runTask(() => {
+		getPropertyKeys(initialState).forEach((key) => {
+			createComputed(() => {
+				clientState[key] = engineState[key];
+			});
+		});
+	});
+
+	return declareInternalClientRepresentation(clientState);
+};

package/src/lib/reactivity/node-state/createCurrentState.ts

@@ -0,0 +1,27 @@
+import type { ReactiveScope } from '../scope.ts';
+import type { ClientState } from './createClientState.ts';
+import type { SpecifiedState, StateSpec } from './createSpecifiedState.ts';
+import type { ReadonlyClientRepresentation } from './representations.ts';
+import { declareReadonlyClientRepresentation } from './representations.ts';
+
+export type CurrentState<Spec extends StateSpec> = ReadonlyClientRepresentation<
+	SpecifiedState<Spec>
+>;
+
+export const createCurrentState = <Spec extends StateSpec>(
+	scope: ReactiveScope,
+	clientState: ClientState<Spec>
+): CurrentState<Spec> => {
+	return scope.runTask(() => {
+		const currentStateProxy = new Proxy<Readonly<SpecifiedState<Spec>>>(clientState, {
+			get: (_, key) => {
+				return clientState[key as keyof SpecifiedState<Spec>];
+			},
+			set: () => {
+				throw new TypeError('Cannot write directly to client-facing currentState');
+			},
+		});
+
+		return declareReadonlyClientRepresentation(currentStateProxy);
+	});
+};

package/src/lib/reactivity/node-state/createEngineState.ts

@@ -0,0 +1,18 @@
+import type { ReactiveScope } from '../scope.ts';
+import type { SpecifiedState, StateSpec } from './createSpecifiedState.ts';
+import { createSpecifiedState } from './createSpecifiedState.ts';
+import type { EngineRepresentation } from './representations.ts';
+import { declareEngineRepresentation } from './representations.ts';
+
+export type EngineState<Spec extends StateSpec> = EngineRepresentation<SpecifiedState<Spec>>;
+
+export const createEngineState = <Spec extends StateSpec>(
+	scope: ReactiveScope,
+	spec: Spec
+): EngineState<Spec> => {
+	return scope.runTask(() => {
+		const state = createSpecifiedState(spec);
+
+		return declareEngineRepresentation(state);
+	});
+};

package/src/lib/reactivity/node-state/createSharedNodeState.ts

@@ -0,0 +1,79 @@
+import { getPropertyKeys } from '@getodk/common/lib/objects/structure.ts';
+import type { OpaqueReactiveObjectFactory } from '../../../index.ts';
+import type { ReactiveScope } from '../scope.ts';
+import type { ClientState, SpecifiedClientStateFactory } from './createClientState.ts';
+import { createClientState } from './createClientState.ts';
+import type { CurrentState } from './createCurrentState.ts';
+import { createCurrentState } from './createCurrentState.ts';
+import type { EngineState } from './createEngineState.ts';
+import { createEngineState } from './createEngineState.ts';
+import type { MutablePropertySpec, SpecifiedState, StateSpec } from './createSpecifiedState.ts';
+import { isComputedPropertySpec, isMutablePropertySpec } from './createSpecifiedState.ts';
+
+// prettier-ignore
+type MutableKeyOf<Spec extends StateSpec> = {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	[K in string & keyof Spec]: Spec[K] extends MutablePropertySpec<any>
+		? K
+		: never;
+}[string & keyof Spec];
+
+type SetEnginePropertyState<Spec extends StateSpec> = <K extends MutableKeyOf<Spec>>(
+	key: K,
+	newValue: SpecifiedState<Spec>[K]
+) => SpecifiedState<Spec>[K];
+
+export interface SharedNodeState<Spec extends StateSpec> {
+	readonly spec: Spec;
+	readonly engineState: EngineState<Spec>;
+	readonly clientState: ClientState<Spec>;
+	readonly currentState: CurrentState<Spec>;
+	readonly setProperty: SetEnginePropertyState<Spec>;
+}
+
+interface SharedNodeStateOptions<
+	Factory extends OpaqueReactiveObjectFactory,
+	Spec extends StateSpec,
+> {
+	readonly clientStateFactory: SpecifiedClientStateFactory<Factory, Spec>;
+}
+
+export const createSharedNodeState = <
+	Factory extends OpaqueReactiveObjectFactory,
+	Spec extends StateSpec,
+>(
+	scope: ReactiveScope,
+	spec: Spec,
+	options: SharedNodeStateOptions<Factory, Spec>
+): SharedNodeState<Spec> => {
+	const engineState = createEngineState(scope, spec);
+	const clientState = createClientState(scope, engineState, options.clientStateFactory);
+	const currentState = createCurrentState(scope, clientState);
+
+	const specKeys = getPropertyKeys(spec);
+	const mutableKeys = specKeys.filter((key) => {
+		return isMutablePropertySpec(spec[key]);
+	});
+	const computedKeys = specKeys.filter((key) => {
+		return isComputedPropertySpec(spec[key]);
+	});
+
+	const setProperty: SetEnginePropertyState<Spec> = (key, value) => {
+		if (!mutableKeys.includes(key)) {
+			const specType = computedKeys.includes(key) ? 'computed' : 'static';
+			throw new TypeError(`Cannot write to '${key}': property is ${specType}`);
+		}
+
+		return scope.runTask(() => {
+			return (engineState[key] = value);
+		});
+	};
+
+	return {
+		spec,
+		engineState,
+		clientState,
+		currentState,
+		setProperty,
+	};
+};

package/src/lib/reactivity/node-state/createSpecifiedPropertyDescriptor.ts

@@ -0,0 +1,85 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import type {
+	ComputedPropertySpec,
+	MutablePropertySpec,
+	StatePropertySpec,
+	StaticPropertySpec,
+} from './createSpecifiedState.ts';
+import {
+	isComputedPropertySpec,
+	isMutablePropertySpec,
+	isStaticPropertySpec,
+} from './createSpecifiedState.ts';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface SpecifiedPropertyDescriptor<T = any> extends TypedPropertyDescriptor<T> {
+	readonly configurable: true;
+	readonly enumerable: true;
+}
+
+interface MutableDescriptor<T> extends SpecifiedPropertyDescriptor<T> {
+	readonly get: () => T;
+	readonly set: (newValue: T) => void;
+	readonly writable?: never;
+	readonly value?: never;
+}
+
+const mutableDesciptor = <T>(propertySpec: MutablePropertySpec<T>): MutableDescriptor<T> => {
+	const [get, set] = propertySpec;
+
+	return {
+		configurable: true,
+		enumerable: true,
+		get,
+		set,
+	};
+};
+
+interface ComputedDescriptor<T> extends SpecifiedPropertyDescriptor<T> {
+	readonly get: () => T;
+	readonly set?: never;
+	readonly writable?: never;
+	readonly value?: never;
+}
+
+const computedDescriptor = <T>(propertySpec: ComputedPropertySpec<T>): ComputedDescriptor<T> => {
+	return {
+		configurable: true,
+		enumerable: true,
+		get: propertySpec,
+	};
+};
+
+interface StaticDescriptor<T> extends SpecifiedPropertyDescriptor<T> {
+	readonly get?: never;
+	readonly set?: never;
+	readonly writable: false;
+	readonly value: T;
+}
+
+const staticDescriptor = <T>(propertySpec: StaticPropertySpec<T>): StaticDescriptor<T> => {
+	return {
+		configurable: true,
+		enumerable: true,
+		writable: false,
+		value: propertySpec,
+	};
+};
+
+export const createSpecifiedPropertyDescriptor = <T>(
+	propertySpec: StatePropertySpec<T>
+): SpecifiedPropertyDescriptor<T> => {
+	if (isMutablePropertySpec(propertySpec)) {
+		return mutableDesciptor(propertySpec);
+	}
+
+	if (isComputedPropertySpec(propertySpec)) {
+		return computedDescriptor(propertySpec);
+	}
+
+	if (isStaticPropertySpec(propertySpec)) {
+		return staticDescriptor(propertySpec);
+	}
+
+	throw new UnreachableError(propertySpec);
+};