@getodk/xforms-engine 0.3.0 → 0.5.0

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

@@ -0,0 +1,106 @@
+import { XFORMS_KNOWN_ATTRIBUTE, XFORMS_LOCAL_NAME, XPathNodeKindKey } from '@getodk/xpath';
+import type { EngineDOMAdapter } from '../adapter/engineDOMAdapter.ts';
+import type { XFormsXPathElement } from '../adapter/XFormsXPathNode.ts';
+import { StaticAttribute } from './StaticAttribute.ts';
+import type { StaticNamedNodeOptions } from './StaticNamedNode.ts';
+import { StaticNamedNode } from './StaticNamedNode.ts';
+import type { StaticChildNode, StaticParentNode } from './StaticNode.ts';
+
+export type StaticElementAttributesFactory = (element: StaticElement) => readonly StaticAttribute[];
+
+export type StaticElementChildNodesFactory = (element: StaticElement) => readonly StaticChildNode[];
+
+export interface StaticElementOptions extends StaticNamedNodeOptions {}
+
+type StaticElementKnownAttributeValue<
+	T extends StaticElement,
+	LocalName extends string,
+> = T extends { readonly [XFORMS_KNOWN_ATTRIBUTE]: LocalName } ? string : string | null;
+
+type AssertStaticElementKnownAttributeValue = <T extends StaticElement, LocalName extends string>(
+	element: T,
+	localName: LocalName,
+	value: string | null
+) => asserts value is StaticElementKnownAttributeValue<T, LocalName>;
+
+const assertStaticElementKnownAttributeValue: AssertStaticElementKnownAttributeValue = (
+	element,
+	localName,
+	value
+) => {
+	if (localName === element[XFORMS_KNOWN_ATTRIBUTE] && value == null) {
+		throw new Error(`Expected attribute: ${element[XFORMS_KNOWN_ATTRIBUTE]}`);
+	}
+};
+
+export class StaticElement<Parent extends StaticParentNode = StaticParentNode>
+	extends StaticNamedNode<'element'>
+	implements XFormsXPathElement
+{
+	readonly [XFORMS_LOCAL_NAME]?: string;
+	readonly [XFORMS_KNOWN_ATTRIBUTE]?: string;
+
+	readonly [XPathNodeKindKey] = 'element';
+	readonly nodeType = 'static-element';
+	readonly root: StaticElement;
+	readonly attributes: readonly StaticAttribute[];
+	readonly children: readonly StaticChildNode[];
+
+	constructor(
+		parent: Parent,
+		attributesFactory: StaticElementAttributesFactory,
+		childNodesFactory: StaticElementChildNodesFactory,
+		options: StaticElementOptions
+	) {
+		super(parent, options);
+
+		// Account for the fact that we may be constructing the document root!
+		if (parent === this.rootDocument) {
+			this.root = this;
+		} else {
+			this.root = parent.root;
+		}
+
+		this.attributes = attributesFactory(this);
+		this.children = childNodesFactory(this);
+	}
+
+	/**
+	 * @todo Generalize this, incorporate into {@link EngineDOMAdapter}
+	 * @todo Namespaced lookup
+	 * @todo Optimize: lookup from map and/or caching
+	 */
+	protected getAttributeNode(localName: string): StaticAttribute | null {
+		return (
+			this.attributes.find((attribute) => {
+				return attribute.localName === localName;
+			}) ?? null
+		);
+	}
+
+	/**
+	 * @todo Generalize this, incorporate into {@link EngineDOMAdapter}
+	 * @todo Namespaced lookup
+	 * @todo Optimize: lookup from map and/or caching (especially asserting known
+	 * attributes!)
+	 * @todo As long as this depends on {@link getAttributeNode}, push assertion
+	 * up. (This was put off because the types are already plenty complex as it
+	 * is.)
+	 */
+	getAttributeValue<This extends StaticElement, LocalName extends string>(
+		this: This,
+		localName: LocalName
+	): StaticElementKnownAttributeValue<This, LocalName> {
+		const attribute = this.getAttributeNode(localName);
+		const value = attribute?.value ?? null;
+
+		assertStaticElementKnownAttributeValue(this, localName, value);
+
+		return value;
+	}
+
+	// XFormsXPathElement
+	getXPathValue(): string {
+		return this.children.map((child) => child.getXPathValue()).join('');
+	}
+}

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

@@ -0,0 +1,45 @@
+import { XFORMS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import type { XFormsXPathNamedNode, XPathNamedNodeKind } from '../adapter/XFormsXPathNode.ts';
+import type { StaticDocument } from './StaticDocument.ts';
+import type { StaticParentNode } from './StaticNode.ts';
+import { StaticNode } from './StaticNode.ts';
+
+export interface StaticNamedNodeOptions {
+	readonly namespaceURI: string | null;
+	readonly localName: string;
+	readonly value?: string;
+}
+
+export abstract class StaticNamedNode<Kind extends XPathNamedNodeKind>
+	extends StaticNode<Kind>
+	implements XFormsXPathNamedNode
+{
+	readonly rootDocument: StaticDocument;
+	readonly isXFormsNamespace: boolean;
+	readonly namespaceURI: string | null;
+	readonly localName: string;
+	readonly value: string | null;
+
+	protected constructor(
+		readonly parent: StaticParentNode,
+		options: StaticNamedNodeOptions
+	) {
+		super();
+
+		this.rootDocument = parent.rootDocument;
+
+		const { namespaceURI, localName, value = null } = options;
+
+		this.namespaceURI = namespaceURI;
+		this.localName = localName;
+		this.value = value;
+
+		if (namespaceURI === XFORMS_NAMESPACE_URI) {
+			this.isXFormsNamespace = true;
+		} else if (parent == null || parent.isXFormsNamespace) {
+			this.isXFormsNamespace = namespaceURI == null;
+		} else {
+			this.isXFormsNamespace = false;
+		}
+	}
+}

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

@@ -0,0 +1,68 @@
+// import type { StaticNodeBrand } from '@getodk/xpath';
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { XFormsXPathNode } from '../adapter/XFormsXPathNode.ts';
+import type { StaticAttribute } from './StaticAttribute.ts';
+import type { StaticDocument } from './StaticDocument.ts';
+import type { StaticElement } from './StaticElement.ts';
+import type { StaticText } from './StaticText.ts';
+
+// prettier-ignore
+export type StaticNodeKind =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'document'
+	| 'element'
+	| 'attribute'
+	| 'text';
+
+// prettier-ignore
+export type StaticNodeType<Kind extends StaticNodeKind> = `static-${Kind}`;
+
+export abstract class StaticNode<Kind extends StaticNodeKind> implements XFormsXPathNode {
+	abstract readonly [XPathNodeKindKey]: Kind;
+
+	abstract readonly nodeType: StaticNodeType<Kind>;
+
+	/**
+	 * A concrete {@link StaticDocument} instance, representing the topmost node
+	 * of a static document tree, containing all of:
+	 *
+	 * - {@link root}
+	 * - {@link children}
+	 * - any {@link StaticChildNode} descendants of either of the above
+	 */
+	abstract readonly rootDocument: StaticDocument;
+
+	/**
+	 * A concrete {@link StaticElement} instance, representing the single,
+	 * immediate child of {@link rootDocument}, containing all other descendants
+	 * of its document tree.
+	 */
+	abstract readonly root: StaticElement;
+
+	abstract readonly children: readonly StaticChildNode[] | null;
+
+	// XFormsXPathNode
+	getXPathChildNodes(): readonly StaticChildNode[] {
+		return this.children ?? [];
+	}
+
+	abstract getXPathValue(): string;
+}
+
+// prettier-ignore
+export type AnyStaticNode =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| StaticDocument
+	| StaticElement
+	| StaticAttribute
+	| StaticText;
+
+// prettier-ignore
+export type StaticParentNode =
+	| StaticDocument
+	| StaticElement;
+
+// prettier-ignore
+export type StaticChildNode =
+	| StaticElement
+	| StaticText;

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

@@ -0,0 +1,28 @@
+import { XPathNodeKindKey } from '@getodk/xpath';
+import type { XFormsXPathText } from '../adapter/XFormsXPathNode.ts';
+import type { StaticDocument } from './StaticDocument.ts';
+import type { StaticElement } from './StaticElement.ts';
+import { StaticNode } from './StaticNode.ts';
+
+export class StaticText extends StaticNode<'text'> implements XFormsXPathText {
+	readonly [XPathNodeKindKey] = 'text';
+	readonly nodeType = 'static-text';
+	readonly rootDocument: StaticDocument;
+	readonly root: StaticElement;
+	readonly children = null;
+
+	constructor(
+		readonly parent: StaticElement,
+		readonly value: string
+	) {
+		super();
+
+		this.rootDocument = parent.rootDocument;
+		this.root = parent.root;
+	}
+
+	// XFormsXPathText
+	getXPathValue(): string {
+		return this.value;
+	}
+}

package/src/lib/TokenListParser.ts

@@ -11,16 +11,20 @@ type TokenListIterator<CanonicalToken extends string> = IterableIterator<
 	PartiallyKnownString<CanonicalToken>
 >;
 
+type PassthroughTokenList = Readonly<Record<string, boolean>>;
+
 /**
  * @see {@link TokenListParser}
  */
 // prettier-ignore
-export type TokenList<CanonicalToken extends string = string> = {
-	readonly [Key in TokenListKey<CanonicalToken>]:
-		Key extends SymbolIterator
-			? () => TokenListIterator<CanonicalToken>
-			: boolean;
-};
+export type TokenList<CanonicalToken extends string = string> =
+	& PassthroughTokenList
+	& {
+		readonly [Key in TokenListKey<CanonicalToken>]:
+			Key extends SymbolIterator
+				? () => TokenListIterator<CanonicalToken>
+				: boolean;
+	};
 
 interface TokenListAlias<CanonicalToken extends string> {
 	readonly fromAlias: string;
@@ -101,7 +105,7 @@ export class TokenListParser<
 	private readonly aliases: ReadonlyMap<string, CanonicalToken>;
 
 	constructor(
-		readonly canonicalTokens: readonly CanonicalToken[],
+		readonly canonicalTokens: readonly CanonicalToken[] = [],
 		options?: TokenListParserOptions<TokenAlias>
 	) {
 		this.aliases = new Map(

package/src/lib/client-reactivity/submission/createInstanceSubmissionState.ts

@@ -0,0 +1,12 @@
+import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
+
+export const createInstanceSubmissionState = (
+	node: ClientReactiveSubmittableInstance
+): SubmissionState => {
+	return {
+		get submissionXML(): string {
+			return node.root.submissionState.submissionXML;
+		},
+	};
+};

package/src/lib/client-reactivity/submission/createLeafNodeSubmissionState.ts

@@ -0,0 +1,20 @@
+import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { ClientReactiveSubmittableLeafNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableLeafNode.ts';
+import { escapeXMLText, serializeLeafElementXML } from '../../xml-serialization.ts';
+
+export const createLeafNodeSubmissionState = <Value>(
+	node: ClientReactiveSubmittableLeafNode<Value>
+): SubmissionState => {
+	return {
+		get submissionXML() {
+			if (!node.currentState.relevant) {
+				return '';
+			}
+
+			const value = node.encodeValue(node.currentState.value);
+			const xmlValue = escapeXMLText(value);
+
+			return serializeLeafElementXML(node.definition.nodeName, xmlValue);
+		},
+	};
+};

package/src/lib/client-reactivity/submission/createNodeRangeSubmissionState.ts

@@ -0,0 +1,17 @@
+import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { ClientReactiveSubmittableParentNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import type { RepeatInstance } from '../../../instance/repeat/RepeatInstance.ts';
+
+export const createNodeRangeSubmissionState = (
+	node: ClientReactiveSubmittableParentNode<RepeatInstance>
+): SubmissionState => {
+	return {
+		get submissionXML() {
+			const serializedChildren = node.currentState.children.map((child) => {
+				return child.submissionState.submissionXML;
+			});
+
+			return serializedChildren.join('');
+		},
+	};
+};

package/src/lib/client-reactivity/submission/createParentNodeSubmissionState.ts

@@ -0,0 +1,22 @@
+import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { GeneralChildNode } from '../../../instance/hierarchy.ts';
+import type { ClientReactiveSubmittableParentNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableParentNode.ts';
+import { serializeParentElementXML } from '../../xml-serialization.ts';
+
+export const createParentNodeSubmissionState = (
+	node: ClientReactiveSubmittableParentNode<GeneralChildNode>
+): SubmissionState => {
+	return {
+		get submissionXML() {
+			if (!node.currentState.relevant) {
+				return '';
+			}
+
+			const serializedChildren = node.currentState.children.map((child) => {
+				return child.submissionState.submissionXML;
+			});
+
+			return serializeParentElementXML(node.definition.nodeName, serializedChildren);
+		},
+	};
+};

package/src/lib/client-reactivity/submission/createValueNodeSubmissionState.ts

@@ -0,0 +1,21 @@
+import type { SubmissionState } from '../../../client/submission/SubmissionState.ts';
+import type { ClientReactiveSubmittableValueNode } from '../../../instance/internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import { escapeXMLText, serializeLeafElementXML } from '../../xml-serialization.ts';
+
+export const createValueNodeSubmissionState = (
+	node: ClientReactiveSubmittableValueNode
+): SubmissionState => {
+	const { nodeName } = node.definition;
+
+	return {
+		get submissionXML() {
+			if (!node.currentState.relevant) {
+				return '';
+			}
+
+			const xmlValue = escapeXMLText(node.currentState.instanceValue);
+
+			return serializeLeafElementXML(nodeName, xmlValue);
+		},
+	};
+};

package/src/lib/client-reactivity/submission/prepareSubmission.ts

@@ -0,0 +1,172 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import {
+	SUBMISSION_INSTANCE_FILE_NAME,
+	SUBMISSION_INSTANCE_FILE_TYPE,
+} from '../../../client/constants.ts';
+import type { SubmissionData } from '../../../client/submission/SubmissionData.ts';
+import type { SubmissionDefinition } from '../../../client/submission/SubmissionDefinition.ts';
+import type { SubmissionInstanceFile } from '../../../client/submission/SubmissionInstanceFile.ts';
+import type { SubmissionChunkedType } from '../../../client/submission/SubmissionOptions.ts';
+import type { SubmissionResult } from '../../../client/submission/SubmissionResult.ts';
+import type { DescendantNodeViolationReference } from '../../../client/validation.ts';
+import type { ClientReactiveSubmittableInstance } from '../../../instance/internal-api/submission/ClientReactiveSubmittableInstance.ts';
+
+class InstanceFile extends File implements SubmissionInstanceFile {
+	override readonly name = SUBMISSION_INSTANCE_FILE_NAME;
+	override readonly type = SUBMISSION_INSTANCE_FILE_TYPE;
+
+	constructor(instanceRoot: ClientReactiveSubmittableInstance) {
+		const { submissionXML } = instanceRoot.submissionState;
+
+		super([submissionXML], SUBMISSION_INSTANCE_FILE_NAME, {
+			type: SUBMISSION_INSTANCE_FILE_TYPE,
+		});
+	}
+}
+
+type AssertSubmissionData = (data: FormData) => asserts data is SubmissionData;
+
+const assertSubmissionData: AssertSubmissionData = (data) => {
+	const instanceFile = data.get(SUBMISSION_INSTANCE_FILE_NAME);
+
+	if (!(instanceFile instanceof InstanceFile)) {
+		throw new Error(`Invalid SubmissionData`);
+	}
+};
+
+class InstanceSubmissionData extends FormData {
+	static from(instanceFile: InstanceFile, attachments: readonly File[]): SubmissionData {
+		const data = new this(instanceFile, attachments);
+
+		assertSubmissionData(data);
+
+		return data;
+	}
+
+	private constructor(
+		readonly instanceFile: InstanceFile,
+		readonly attachments: readonly File[]
+	) {
+		super();
+
+		this.set(SUBMISSION_INSTANCE_FILE_NAME, instanceFile);
+
+		attachments.forEach((attachment) => {
+			const { name } = attachment;
+
+			if (name === SUBMISSION_INSTANCE_FILE_NAME && attachment !== instanceFile) {
+				throw new Error(
+					`Failed to add conflicting attachment with name ${SUBMISSION_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 SubmissionInstanceStateValidation = PendingValidation | ReadyValidation;
+
+const validateSubmission = (
+	instanceRoot: ClientReactiveSubmittableInstance
+): SubmissionInstanceStateValidation => {
+	const { violations } = instanceRoot.validationState;
+
+	if (violations.length === 0) {
+		return {
+			status: 'ready',
+			violations: null,
+		};
+	}
+
+	return {
+		status: 'pending',
+		violations,
+	};
+};
+
+const monolithicSubmissionResult = (
+	validation: SubmissionInstanceStateValidation,
+	definition: SubmissionDefinition,
+	instanceFile: InstanceFile,
+	attachments: readonly File[]
+): SubmissionResult<'monolithic'> => {
+	const data = InstanceSubmissionData.from(instanceFile, attachments);
+
+	return {
+		...validation,
+		definition,
+		data,
+	};
+};
+
+interface ChunkedSubmissionResultOptions {
+	readonly maxSize: number;
+}
+
+const chunkedSubmissionResult = (
+	validation: SubmissionInstanceStateValidation,
+	definition: SubmissionDefinition,
+	instanceFile: InstanceFile,
+	attachments: readonly File[],
+	options: ChunkedSubmissionResultOptions
+): SubmissionResult<'chunked'> => {
+	if (attachments.length > 0 || options.maxSize !== Infinity) {
+		throw new Error('Submission chunking pending implementation');
+	}
+
+	const data = InstanceSubmissionData.from(instanceFile, attachments);
+
+	return {
+		...validation,
+		definition,
+		data: [data],
+	};
+};
+
+export interface PrepeareSubmissionOptions<ChunkedType extends SubmissionChunkedType> {
+	readonly chunked: ChunkedType;
+	readonly maxSize: number;
+}
+
+export const prepareSubmission = <ChunkedType extends SubmissionChunkedType>(
+	instanceRoot: ClientReactiveSubmittableInstance,
+	options: PrepeareSubmissionOptions<ChunkedType>
+): SubmissionResult<ChunkedType> => {
+	const validation = validateSubmission(instanceRoot);
+	const definition = instanceRoot.definition.submission;
+	const instanceFile = new InstanceFile(instanceRoot);
+	const attachments: readonly File[] = [];
+
+	switch (options.chunked) {
+		case 'chunked':
+			return chunkedSubmissionResult(
+				validation,
+				definition,
+				instanceFile,
+				attachments,
+				options
+			) satisfies SubmissionResult<'chunked'> as SubmissionResult<ChunkedType>;
+
+		case 'monolithic':
+			return monolithicSubmissionResult(
+				validation,
+				definition,
+				instanceFile,
+				attachments
+			) satisfies SubmissionResult<'monolithic'> as SubmissionResult<ChunkedType>;
+
+		default:
+			throw new UnreachableError(options.chunked);
+	}
+};

package/src/lib/codecs/DecimalValueCodec.ts

@@ -0,0 +1,46 @@
+import { ValueCodec } from './ValueCodec.ts';
+
+export type DecimalInputValue = bigint | number | string | null;
+
+const encodeDecimal = (value: DecimalInputValue): string => {
+	if (value == null) {
+		return '';
+	}
+
+	if (typeof value === 'string') {
+		decodeDecimal(value);
+	}
+
+	return String(value);
+};
+
+export type DecimalRuntimeValue = number | null;
+
+const decodeDecimal = (value: string): DecimalRuntimeValue => {
+	if (value === '') {
+		return null;
+	}
+
+	const decoded = Number(value);
+
+	if (
+		// NaN is not a decimal value!
+		Number.isNaN(decoded) ||
+		// Infinity is not a decimal value!
+		!Number.isFinite(decoded)
+	) {
+		return null;
+	}
+
+	return decoded;
+};
+
+export class DecimalValueCodec extends ValueCodec<
+	'decimal',
+	DecimalRuntimeValue,
+	DecimalInputValue
+> {
+	constructor() {
+		super('decimal', encodeDecimal, decodeDecimal);
+	}
+}