@getodk/xforms-engine 0.1.0

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

@@ -0,0 +1,229 @@
+import { getPropertyKeys } from '@getodk/common/lib/objects/structure.ts';
+import type { Accessor, Signal } from 'solid-js';
+import type { SimpleAtomicState } from '../types.ts';
+import type { SpecifiedPropertyDescriptor } from './createSpecifiedPropertyDescriptor.ts';
+import { createSpecifiedPropertyDescriptor } from './createSpecifiedPropertyDescriptor.ts';
+
+/**
+ * Specifies a state object's property as mutable. Basic usage:
+ *
+ * ```ts
+ * import { createSignal } from 'solid-js';
+ *
+ * const count = createSignal(1);
+ *
+ * const state = createSpecifiedState({ count });
+ * //    ^? { count: number }
+ * ```
+ *
+ * While basic usage involves passing a Solid {@link Signal}, a
+ * {@link SimpleAtomicState} type is also supported, allowing a slightly more
+ * permissive setter type.
+ *
+ * @see {@link SimpleAtomicState} and its related types for more detail.
+ *
+ * A property specified with this type will be used to define a reactively
+ * mutable property on the resulting state object where:
+ *
+ * - Reading the property will read its value from the provided spec's getter
+ *   function, establishing an internally reactive subscription.
+ *
+ * - Mutating the property will pass the assigned value to the provided spec's
+ *   setter function, triggering any downstream computations—whether that
+ *   computation is associated with the provided spec itself, or reads from the
+ *   derived property.
+ *
+ * - All such mutations will be propagated to any derived (client) state object.
+ */
+// prettier-ignore
+export type MutablePropertySpec<T> =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| SimpleAtomicState<T>
+	| Signal<T>;
+
+/**
+ * Specifies a state object's property as reactively computed, and read-only.
+ * Basic usage:
+ *
+ * ```ts
+ * import { createMemo, createSignal } from 'solid-js';
+ *
+ * const [count, setCount] = createSignal(1);
+ * const doubleCount = createMemo(() => count() * 2);
+ *
+ * const state = createSpecifiedState({ doubleCount });
+ * //    ^? { readonly doubleCount: number }
+ * ```
+ *
+ * Note: ideally, the produced type would better reflect the computed nature of
+ * the resulting property. Unfortunately this isn't currently supported by the
+ * TypeScript type system (by inferring the derived state type). This tradeoff
+ * is reasonable for internal engine use, but should not be used to derive types
+ * which will be directly consumed by clients.
+ *
+ * Any property specified by a thunk (zero-argument function) is supported. A
+ * property specified with this type will be used to define a reactively
+ * readable property on the resulting state object where:
+ *
+ * - Reading the property will read its value on each access, establishing an
+ *   internally reactive subscription (presuming the input property spec is
+ *   itself reactive).
+ *
+ * - Mutating the property will throw a {@link TypeError}, just as it would when
+ *   attempting to mutate a normal `get` accessor.
+ *
+ * - Any change which would result in a reactive update in the property spec
+ *   itself will be propagated to any derived (client) state object.
+ */
+export type ComputedPropertySpec<T> = Accessor<T>;
+
+/**
+ * @see {@link StaticPropertySpec}
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types, @typescript-eslint/no-explicit-any
+type NonStaticValue = Function | Signal<any> | SimpleAtomicState<any>;
+
+/**
+ * Specifies a state object's property with a static value, immutable for the
+ * lifetime of that state object. Basic usage:
+ *
+ * ```ts
+ * const state = createSpecifiedState({ num: 10 });
+ * //    ^? { readonly num: number }
+ * ```
+ *
+ * Properties will be specified as static when they are none of:
+ *
+ * - {@link MutablePropertySpec}
+ * - {@link ComputedPropertySpec}
+ * - Any function with a non-zero arity (which are not supported for specifying
+ *   a state object's properties at all)
+ *
+ * Any property so specified will produce a property where:
+ *
+ * - Reading the property will produce the provided static value.
+ *
+ * - Mutating the property will throw a {@link TypeError}, just as it would when
+ *   attempting to mutate a normal `get` accessor (or a
+ *   {@link PropertyDescriptor} with `writable: false`).
+ *
+ * - The property will reflect the same static value on any derived (client)
+ *   state object.
+ */
+export type StaticPropertySpec<T> = Exclude<T, NonStaticValue>;
+
+/**
+ * Every state property may be specified with any of these types:
+ *
+ * - {@link MutablePropertySpec}
+ * - {@link ComputedPropertySpec}
+ * - {@link StaticPropertySpec}
+ */
+// prettier-ignore
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type StatePropertySpec<T = any> =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| MutablePropertySpec<T>
+	| ComputedPropertySpec<T>
+	| StaticPropertySpec<T>;
+
+type ParametersOfArity<Arity extends number> = unknown[] & {
+	length: Arity;
+};
+
+type FunctionOfArity<Arity extends number> = (...args: ParametersOfArity<Arity>) => unknown;
+
+const isFunctionOfArity = <Arity extends number>(
+	arity: Arity,
+	value: unknown
+): value is FunctionOfArity<Arity> => {
+	return typeof value === 'function' && value.length === arity;
+};
+
+export const isMutablePropertySpec = <T>(
+	propertySpec: StatePropertySpec<T>
+): propertySpec is MutablePropertySpec<T> => {
+	if (!Array.isArray(propertySpec) || propertySpec.length !== 2) {
+		return false;
+	}
+
+	const [read, write] = propertySpec;
+
+	return isFunctionOfArity(0, read) && isFunctionOfArity(1, write);
+};
+
+export const isComputedPropertySpec = <T>(
+	propertySpec: StatePropertySpec<T>
+): propertySpec is ComputedPropertySpec<T> => {
+	return isFunctionOfArity(0, propertySpec);
+};
+
+export const isStaticPropertySpec = <T>(
+	propertySpec: StatePropertySpec<T>
+): propertySpec is StaticPropertySpec<T> => {
+	return !isMutablePropertySpec(propertySpec) && !isComputedPropertySpec(propertySpec);
+};
+
+export type StateSpec = Record<string, StatePropertySpec>;
+
+// prettier-ignore
+type SpecifiedStatePropertyValue<PropertySpec extends StatePropertySpec> =
+	PropertySpec extends StatePropertySpec<infer T>
+		? T
+		: never;
+
+// prettier-ignore
+type DerivedMutableKeys<Spec extends StateSpec> = {
+	[K in keyof Spec]:
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		Spec[K] extends MutablePropertySpec<any>
+			? K
+			: never;
+}[keyof Spec];
+
+type DerivedMutableState<Spec extends StateSpec> = {
+	-readonly [K in DerivedMutableKeys<Spec>]: SpecifiedStatePropertyValue<Spec[K]>;
+};
+
+type DerivedReadableKeys<Spec extends StateSpec> = Exclude<keyof Spec, DerivedMutableKeys<Spec>>;
+
+type DerivedReadableState<Spec extends StateSpec> = {
+	readonly [K in DerivedReadableKeys<Spec>]: SpecifiedStatePropertyValue<Spec[K]>;
+};
+
+// prettier-ignore
+export type SpecifiedState<Spec extends StateSpec> =(
+	& DerivedMutableState<Spec>
+	& DerivedReadableState<Spec>
+) extends infer DerivedState
+	? {
+			[K in keyof Spec]:
+				K extends keyof DerivedState
+					? DerivedState[K]
+					: never;
+		}
+	: never;
+
+/**
+ * Produces an (internally) reactive object whose properties may be a mix of:
+ *
+ * - {@link MutablePropertySpec | mutable} (atomically reactive when mutated by
+ *   engine internal logic; reactively propagated as read-only to clients)
+ * - {@link ComputedPropertySpec | computed} (read-only, reactive to changes in
+ *   derived state; reactively propagated as read-only to clients)
+ * - {@link StaticPropertySpec | static} (read-only, immutable after creation;
+ *   statically propagated as read-only to clients)
+ */
+export const createSpecifiedState = <Spec extends StateSpec>(spec: Spec): SpecifiedState<Spec> => {
+	const keys = getPropertyKeys(spec);
+	const descriptors = Object.fromEntries(
+		keys.map((key) => {
+			const propertySpec = spec[key];
+			const descriptor = createSpecifiedPropertyDescriptor(propertySpec);
+
+			return [key, descriptor];
+		})
+	) satisfies Record<string, SpecifiedPropertyDescriptor>;
+
+	return Object.create(null, descriptors) as SpecifiedState<Spec>;
+};

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

@@ -0,0 +1,64 @@
+import type { ShallowMutable } from '@getodk/common/types/helpers.js';
+
+const ENGINE_REPRESENTATION = Symbol('ENGINE_REPRESENTATION');
+type ENGINE_REPRESENTATION = typeof ENGINE_REPRESENTATION;
+
+const INTERNAL_CLIENT_REPRESENTATION = Symbol('INTERNAL_CLIENT_REPRESENTATION');
+type INTERNAL_CLIENT_REPRESENTATION = typeof INTERNAL_CLIENT_REPRESENTATION;
+
+const READONLY_CLIENT_REPRESENTATION = Symbol('READONLY_CLIENT_REPRESENTATION');
+type READONLY_CLIENT_REPRESENTATION = typeof READONLY_CLIENT_REPRESENTATION;
+
+// prettier-ignore
+type RepresentationType =
+	| ENGINE_REPRESENTATION
+	| INTERNAL_CLIENT_REPRESENTATION
+	| READONLY_CLIENT_REPRESENTATION;
+
+// prettier-ignore
+type TypedRepresentation<Type extends RepresentationType, T> =
+	& T
+	& { readonly [K in RepresentationType]?: K extends Type ? K : never };
+
+// prettier-ignore
+export type EngineRepresentation<T extends object> = TypedRepresentation<
+	ENGINE_REPRESENTATION,
+	ShallowMutable<T>
+>;
+
+export const declareEngineRepresentation = <T extends object>(
+	stateObject: T
+): EngineRepresentation<T> => {
+	return stateObject as EngineRepresentation<T>;
+};
+
+// prettier-ignore
+export type InternalClientRepresentation<T extends object> = TypedRepresentation<
+	INTERNAL_CLIENT_REPRESENTATION,
+	ShallowMutable<T>
+>;
+
+export const declareInternalClientRepresentation = <T extends object>(
+	stateObject: T
+): InternalClientRepresentation<T> => {
+	return stateObject as InternalClientRepresentation<T>;
+};
+
+// prettier-ignore
+export type ReadonlyClientRepresentation<T> = TypedRepresentation<
+	READONLY_CLIENT_REPRESENTATION,
+	T
+>;
+
+/**
+ * Provides a static type mechanism to reduce the chance of mistakenly assigning
+ * one state representation to another (e.g. `engineState = clientState` or
+ * `doSomethingWithCurrentState(engineState)`). Each representation is either
+ * fully or partially assignable to the other, but this bit of indirection should
+ * prevent that (unless one of the types is widened to {@link T}).
+ */
+export const declareReadonlyClientRepresentation = <T extends object>(
+	stateObject: Readonly<T>
+): ReadonlyClientRepresentation<T> => {
+	return stateObject as ReadonlyClientRepresentation<T>;
+};

package/src/lib/reactivity/scope.ts

@@ -0,0 +1,106 @@
+import type { Owner } from 'solid-js';
+import { runWithOwner as baseRunWithOwner, createRoot, getOwner } from 'solid-js';
+
+type ReactiveScopeTask<T> = (scope: ReactiveScope) => T;
+
+type RunReactiveScopeTask = <T>(task: ReactiveScopeTask<T>) => T;
+
+export interface ReactiveScope {
+	readonly owner: Owner;
+	readonly dispose: VoidFunction;
+	readonly runTask: RunReactiveScopeTask;
+}
+
+interface CreateReactiveScopeOptions {
+	readonly owner?: Owner | null;
+}
+
+/**
+ * Default types for these pertinent reactive scope APIs as produced by Solid.
+ * These types are correct, but only so restrictive to account for their
+ * behavior outside of a reactive root.
+ */
+interface UnknownReactiveScopeAPI {
+	/**
+	 * The type returned by Solid's {@link getOwner}. It will always produce
+	 * `Owner` when called in a reactive scope (created by {@link createRoot}).
+	 */
+	readonly owner: Owner | null;
+
+	/**
+	 * The unmodified type of Solid's {@link baseRunWithOwner | runWithOwner}.
+	 * It will return {@link T} when {@link owner} is not `null`.
+	 */
+	readonly runWithOwner: <T>(owner: Owner | null, fn: () => T) => T | undefined;
+}
+
+/**
+ * Refined types for the same reactive APIs as {@link UnknownReactiveScopeAPI},
+ * where their less restricted behavior is known when run within a reactive
+ * scope (via {@link createRoot}).
+ */
+interface ValidatedReactiveScopeAPI {
+	readonly owner: Owner;
+	readonly runWithOwner: <T>(owner: Owner, fn: () => T) => T;
+}
+
+/**
+ * @see {@link UnknownReactiveScopeAPI} and {@link ValidatedReactiveScopeAPI}
+ */
+const validateReactiveScopeAPI = (api: UnknownReactiveScopeAPI): ValidatedReactiveScopeAPI => {
+	if (api.owner == null) {
+		throw new Error('Must be run in a reactive scope');
+	}
+
+	return api as ValidatedReactiveScopeAPI;
+};
+
+/**
+ * Creates a reactive scope for internal engine use. This currently uses Solid's
+ * implementation of reactivity, and makes no attempt to obscure that. As such,
+ * all of the terms and types exposed are intentionally direct references to
+ * their concepts in Solid.
+ *
+ * This reactive scope is suitable for isolating reactivity between tests. It is
+ * also suitable for scoping reactivity for nodes in engine/client state, as
+ * well as creating nested scopes for their descendants.
+ */
+export const createReactiveScope = (options: CreateReactiveScopeOptions = {}): ReactiveScope => {
+	return createRoot((baseDispose) => {
+		let isDisposed = false;
+
+		const dispose: VoidFunction = () => {
+			if (isDisposed) {
+				throw new Error('Cannot dispose reactive scope multiple times');
+			}
+
+			baseDispose();
+			isDisposed = true;
+		};
+
+		const { owner, runWithOwner } = validateReactiveScopeAPI({
+			owner: getOwner(),
+			runWithOwner: baseRunWithOwner,
+		});
+
+		const runTask = <T>(task: ReactiveScopeTask<T>): T => {
+			if (isDisposed) {
+				throw new Error('Cannot run reactive task in reactive scope after it has been disposed');
+			}
+
+			return runWithOwner(owner, () => {
+				return task({
+					dispose,
+					owner,
+					runTask,
+				});
+			});
+		};
+
+		return {
+			dispose,
+			owner,
+			runTask,
+		};
+	}, options.owner ?? getOwner());
+};

package/src/lib/reactivity/text/createFieldHint.ts

@@ -0,0 +1,16 @@
+import { type Accessor } from 'solid-js';
+import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
+import { TextRange } from '../../../instance/text/TextRange.ts';
+import type { ValueNodeDefinition } from '../../../model/ValueNodeDefinition.ts';
+import { createTextRange } from './createTextRange.ts';
+
+export const createFieldHint = (
+	context: EvaluationContext,
+	definition: ValueNodeDefinition
+): Accessor<TextRange<'hint'> | null> => {
+	const hintDefinition = definition.bodyElement?.hint ?? null;
+
+	return createTextRange(context, 'hint', hintDefinition, {
+		fallbackValue: null,
+	});
+};

package/src/lib/reactivity/text/createNodeLabel.ts

@@ -0,0 +1,16 @@
+import { type Accessor } from 'solid-js';
+import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
+import { TextRange } from '../../../instance/text/TextRange.ts';
+import type { AnyNodeDefinition } from '../../../model/NodeDefinition.ts';
+import { createTextRange } from './createTextRange.ts';
+
+export const createNodeLabel = (
+	context: EvaluationContext,
+	definition: AnyNodeDefinition
+): Accessor<TextRange<'label'> | null> => {
+	const labelDefinition = definition.bodyElement?.label ?? null;
+
+	return createTextRange(context, 'label', labelDefinition, {
+		fallbackValue: null,
+	});
+};

package/src/lib/reactivity/text/createTextRange.ts

@@ -0,0 +1,155 @@
+import type { CollectionValues } from '@getodk/common/types/collections/CollectionValues.ts';
+import { createMemo, type Accessor } from 'solid-js';
+import type {
+	TextElementChild,
+	TextElementDefinition,
+} from '../../../body/text/TextElementDefinition.ts';
+import type { TextElementReferencePart } from '../../../body/text/TextElementReferencePart.ts';
+import type { TextChunkSource } from '../../../client/TextRange.ts';
+import type { EvaluationContext } from '../../../instance/internal-api/EvaluationContext.ts';
+import { TextChunk } from '../../../instance/text/TextChunk.ts';
+import { TextRange, type TextRole } from '../../../instance/text/TextRange.ts';
+import { createComputedExpression } from '../createComputedExpression.ts';
+
+// prettier-ignore
+type TextSources =
+	| readonly [TextElementReferencePart]
+	| readonly TextElementChild[];
+
+type TextSource = CollectionValues<TextSources>;
+
+interface TextChunkComputation {
+	readonly source: TextChunkSource;
+	readonly getText: Accessor<string>;
+}
+
+const createComputedTextChunk = (
+	context: EvaluationContext,
+	textSource: TextSource
+): TextChunkComputation => {
+	const { type } = textSource;
+
+	if (type === 'static') {
+		const { stringValue } = textSource;
+
+		return {
+			source: type,
+			getText: () => stringValue,
+		};
+	}
+
+	return context.scope.runTask(() => {
+		const source: TextChunkSource = type === 'reference' ? 'itext' : type;
+		const getText = createComputedExpression(context, textSource);
+
+		return {
+			source,
+			getText,
+		};
+	});
+};
+
+const createTextChunks = (
+	context: EvaluationContext,
+	textSources: TextSources
+): Accessor<readonly TextChunk[]> => {
+	return context.scope.runTask(() => {
+		const { root } = context;
+		const chunkComputations = textSources.map((textSource) => {
+			return createComputedTextChunk(context, textSource);
+		});
+
+		return createMemo(() => {
+			return chunkComputations.map(({ source, getText }) => {
+				return new TextChunk(root, source, getText());
+			});
+		});
+	});
+};
+
+interface CreateTextRangeOptions<FallbackValue extends string | null> {
+	readonly fallbackValue?: FallbackValue;
+}
+
+// prettier-ignore
+type ComputedTextRange<
+	Role extends TextRole,
+	Definition extends TextElementDefinition<Role> | null,
+	FallbackValue extends string | null
+> = Accessor<
+	Definition extends null
+		?  FallbackValue extends null
+			? TextRange<Role> | null
+			: TextRange<Role>
+		: TextRange<Role>
+>;
+
+// prettier-ignore
+type FallbackTextRange<
+	Role extends TextRole,
+	FallbackValue extends string | null
+> =
+	FallbackValue extends null
+		? TextRange<Role> | null
+		: TextRange<Role>;
+
+const createFallbackTextRange = <Role extends TextRole, FallbackValue extends string | null>(
+	context: EvaluationContext,
+	role: Role,
+	fallbackValue: FallbackValue
+): FallbackTextRange<Role, FallbackValue> => {
+	if (fallbackValue == null) {
+		return null as FallbackTextRange<Role, FallbackValue>;
+	}
+
+	const staticChunk = new TextChunk(context.root, 'static', fallbackValue);
+
+	return new TextRange(role, [staticChunk]);
+};
+
+/**
+ * Creates a text range (e.g. label or hint) from the provided definition,
+ * reactive to:
+ *
+ * - The form's current language (e.g. `<label ref="jr:itext('text-id')" />`)
+ * - Direct `<output>` references within the label's children
+ *
+ * @todo This does not yet handle itext translations **with** outputs!
+ */
+export const createTextRange = <
+	Role extends TextRole,
+	Definition extends TextElementDefinition<Role> | null,
+	FallbackValue extends string | null = null,
+>(
+	context: EvaluationContext,
+	role: Role,
+	definition: Definition,
+	options?: CreateTextRangeOptions<FallbackValue>
+): ComputedTextRange<Role, Definition, FallbackValue> => {
+	return context.scope.runTask(() => {
+		if (definition == null) {
+			const textRange = createFallbackTextRange(
+				context,
+				role,
+				options?.fallbackValue ?? (null as FallbackValue)
+			);
+			const getTextRange = () => textRange;
+
+			return getTextRange as ComputedTextRange<Role, Definition, FallbackValue>;
+		}
+
+		const { children, referenceExpression } = definition;
+
+		let getTextChunks: Accessor<readonly TextChunk[]>;
+
+		if (referenceExpression == null) {
+			getTextChunks = createTextChunks(context, children);
+		} else {
+			getTextChunks = createTextChunks(context, [referenceExpression]);
+		}
+
+		return createMemo(() => {
+			return new TextRange(role, getTextChunks());
+		});
+	});
+};

package/src/lib/reactivity/types.ts

@@ -0,0 +1,27 @@
+import type { Accessor, Setter, Signal } from 'solid-js';
+
+/**
+ * A write interface to reactive atomic state. This type is intended to be used
+ * as a relaxed version of {@link Setter}, where its callback form isn't
+ * required for conforming implementations.
+ */
+export type SimpleAtomicStateSetter<T> = (newValue: T) => T;
+
+/**
+ * A read/write interface to reactive atomic state. This type is intended to be
+ * used as a relaxed version of {@link Signal}, with a
+ * {@link SimpleAtomicStateSetter | simpler setter type}.
+ */
+// prettier-ignore
+export type SimpleAtomicState<T> = readonly [
+	get: Accessor<T>,
+	set: SimpleAtomicStateSetter<T>,
+];
+
+export type AtomicStateSetter<T> = Setter<T> | SimpleAtomicStateSetter<T>;
+
+// prettier-ignore
+export type AtomicState<T> = readonly [
+	get: Accessor<T>,
+	set: AtomicStateSetter<T>,
+];

package/src/lib/unique-id.ts

@@ -0,0 +1,34 @@
+import { createUniqueId as baseCreateUniqueId } from 'solid-js';
+
+/**
+ * **WARNING:** Uniqueness is not guaranteed across multiple sessions. Do not
+ * use IDs produced by this function in persistence scenarios, or where external
+ * interfaces expect stronger uniqueness guarantees.
+ */
+export type CreateUniqueId = () => string;
+
+/**
+ * Where available, uses the
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API | Web Crypto API}'s
+ * {@link crypto.randomUUID | `randomUUID`}.
+ *
+ * Notes on supported environments:
+ *
+ * - Browsers: only available in a
+ *   {@link https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts | secure context}
+ * - Node: >= v19.0.0
+ * - Deno: >= 1.11
+ * - Bun: fully supported, unknown minimum version
+ *
+ * Where `randomUUID` is not supported, falls back to an internal implementation
+ * with weaker uniqueness constraints.
+ *
+ * **WARNING:** Uniqueness is not guaranteed across multiple sessions. Do not
+ * use IDs produced by this function in persistence scenarios, or where external
+ * interfaces expect stronger uniqueness guarantees.
+ */
+export const createUniqueId: CreateUniqueId = (() => {
+	const { crypto } = globalThis;
+
+	return crypto?.randomUUID?.bind(crypto) ?? baseCreateUniqueId;
+})();