@getodk/xforms-engine 0.6.0 → 0.8.0

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,237 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { bestFitDecreasing } from 'bin-packer';
+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 { ErrorProductionDesignPendingError } from '../../../error/ErrorProductionDesignPendingError.ts';
+import type { InstanceAttachmentsState } from '../../../instance/attachments/InstanceAttachmentsState.ts';
+import type { ClientReactiveSerializableInstance } from '../../../instance/internal-api/serialization/ClientReactiveSerializableInstance.ts';
+
+const collectInstanceAttachmentFiles = (attachments: InstanceAttachmentsState): readonly File[] => {
+	const files = Array.from(attachments.entries()).map(([context, attachment]) => {
+		if (!context.isAttached() || !context.isRelevant()) {
+			return null;
+		}
+
+		return attachment.getValue();
+	});
+
+	return files.filter((file) => file != null);
+};
+
+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 AssertFile = (value: FormDataEntryValue) => asserts value is File;
+
+const assertFile: AssertFile = (value) => {
+	if (!(value instanceof File)) {
+		throw new ErrorProductionDesignPendingError('Expected an instance of File');
+	}
+};
+
+type AssertInstanceData = (data: FormData) => asserts data is ClientInstanceData;
+
+const assertInstanceData: AssertInstanceData = (data) => {
+	let instanceFile: File | null = null;
+
+	for (const [key, value] of data.entries()) {
+		assertFile(value);
+
+		if (key === INSTANCE_FILE_NAME) {
+			instanceFile = value;
+		}
+	}
+
+	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;
+}
+
+type PartitionedInstanceData = readonly [ClientInstanceData, ...ClientInstanceData[]];
+
+const partitionInstanceData = (
+	instanceFile: InstanceFile,
+	attachments: readonly File[],
+	options: ChunkedInstancePayloadOptions
+): PartitionedInstanceData => {
+	const { maxSize } = options;
+	const maxAttachmentSize = maxSize - instanceFile.size;
+	const { bins, oversized } = bestFitDecreasing(
+		attachments,
+		(attachment) => {
+			return attachment.size;
+		},
+		maxAttachmentSize
+	);
+
+	const errors = oversized.map((attachment) => {
+		return new Error(
+			`Combined size of instance XML (${instanceFile.size}) and attachment (${attachment.size}) exceeds maxSize (${maxSize}).`
+		);
+	});
+
+	if (errors.length > 0) {
+		throw new AggregateError(errors, 'Failed to produce chunked instance payload');
+	}
+
+	const [
+		// Ensure at least one `InstanceData` is produced, in case there are no
+		// attachments present at all
+		head = InstanceData.from(instanceFile, []),
+		...tail
+	] = bins.map((bin) => InstanceData.from(instanceFile, bin));
+
+	return [head, ...tail];
+};
+
+const chunkedInstancePayload = (
+	validation: InstanceStateValidation,
+	submissionMeta: SubmissionMeta,
+	instanceFile: InstanceFile,
+	attachments: readonly File[],
+	options: ChunkedInstancePayloadOptions
+): ChunkedInstancePayload => {
+	const data = partitionInstanceData(instanceFile, attachments, options);
+
+	return {
+		payloadType: 'chunked',
+		...validation,
+		submissionMeta,
+		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 = collectInstanceAttachmentFiles(instanceRoot.attachments);
+
+	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/names/UnprefixedXFormsName.ts

@@ -0,0 +1,12 @@
+import { XFORMS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import { QualifiedName } from './QualifiedName.ts';
+
+export class UnprefixedXFormsName extends QualifiedName {
+	constructor(localName: string) {
+		super({
+			namespaceURI: XFORMS_NAMESPACE_URI,
+			prefix: null,
+			localName,
+		});
+	}
+}

package/src/lib/reactivity/createInstanceAttachment.ts

@@ -0,0 +1,212 @@
+import { createMemo, createSignal } from 'solid-js';
+import type { FormNodeID } from '../../client/identity.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { InstanceAttachmentFileName } from '../../instance/attachments/InstanceAttachment.ts';
+import { InstanceAttachment } from '../../instance/attachments/InstanceAttachment.ts';
+import type { InstanceAttachmentContext } from '../../instance/internal-api/InstanceAttachmentContext.ts';
+import type { DecodeInstanceValue } from '../../instance/internal-api/InstanceValueContext.ts';
+import type { SimpleAtomicStateSetter } from './types.ts';
+
+type FileNameExtension = `.${string}`;
+
+type AssertFileNameExtension = (value: string) => asserts value is FileNameExtension;
+
+const assertFileNameExtension: AssertFileNameExtension = (value) => {
+	if (!value.startsWith('.')) {
+		throw new ErrorProductionDesignPendingError('Expected file name extension to start with "."');
+	}
+};
+
+interface SplitFileNameResult {
+	readonly basename: string;
+	readonly extension: FileNameExtension | null;
+}
+
+const EXTENSION_PATTERN = /\.[^.]+?$/;
+
+interface SearchPatternResult extends Array<string> {
+	readonly 0?: string;
+	readonly index?: number;
+}
+
+const searchPattern = (pattern: RegExp, string: string): SearchPatternResult => {
+	return pattern.exec(string) ?? [];
+};
+
+const splitFileName = (fileName: string): SplitFileNameResult => {
+	const extensionMatches = searchPattern(EXTENSION_PATTERN, fileName);
+	const [extension = null] = extensionMatches;
+	const basename = fileName.slice(0, extensionMatches.index);
+
+	if (extension == null) {
+		return {
+			basename,
+			extension,
+		};
+	}
+
+	assertFileNameExtension(extension);
+
+	return {
+		basename,
+		extension,
+	};
+};
+
+export type InstanceAttachmentRuntimeValue = File | null;
+
+export type InstanceAttachmentFormDataEntry = readonly [
+	key: InstanceAttachmentFileName,
+	value: NonNullable<InstanceAttachmentRuntimeValue>,
+];
+
+interface InstanceAttachmentValueOptions {
+	readonly nodeId: FormNodeID;
+	readonly writtenAt: Date | null;
+	readonly file: InstanceAttachmentRuntimeValue;
+}
+
+interface BaseInstanceAttachmentState {
+	readonly computedName: string | null;
+	readonly intrinsicName: string | null;
+	readonly file: InstanceAttachmentRuntimeValue;
+}
+
+interface BlankInstanceAttachmentState extends BaseInstanceAttachmentState {
+	readonly computedName: null;
+	readonly intrinsicName: null;
+	readonly file: null;
+}
+
+interface NonBlankInstanceAttachmentState extends BaseInstanceAttachmentState {
+	readonly computedName: string | null;
+	readonly intrinsicName: string;
+	readonly file: NonNullable<InstanceAttachmentRuntimeValue>;
+}
+
+// prettier-ignore
+type InstanceAttachmentState =
+	| BlankInstanceAttachmentState
+	| NonBlankInstanceAttachmentState;
+
+const instanceAttachmentState = (
+	context: InstanceAttachmentContext,
+	options: InstanceAttachmentValueOptions
+): InstanceAttachmentState => {
+	const { nodeId, file, writtenAt } = options;
+
+	// No file -> no intrinsic name, no name to compute
+	if (file == null) {
+		return {
+			computedName: null,
+			intrinsicName: null,
+			file: null,
+		};
+	}
+
+	const intrinsicName = file.name;
+
+	// File exists, not written by client -> preserve instance input name
+	if (writtenAt == null) {
+		return {
+			computedName: null,
+			intrinsicName,
+			file,
+		};
+	}
+
+	// File was written by client, name is computed as configured by client
+	const { basename, extension } = splitFileName(intrinsicName);
+	const computedName = context.instanceConfig.computeAttachmentName({
+		nodeId,
+		writtenAt,
+		basename,
+		extension,
+	});
+
+	return {
+		computedName,
+		intrinsicName,
+		file,
+	};
+};
+
+export const createInstanceAttachment = (
+	context: InstanceAttachmentContext
+): InstanceAttachment => {
+	return context.scope.runTask(() => {
+		const { rootDocument, nodeId } = context;
+		const { attachments } = rootDocument;
+		const file = attachments.getInitialFileValue(context.instanceNode);
+		const initialState = instanceAttachmentState(context, {
+			nodeId,
+			file,
+			writtenAt: null,
+		});
+
+		const [getState, setState] = createSignal<InstanceAttachmentState>(initialState);
+
+		const decodeInstanceValue: DecodeInstanceValue = (value) => {
+			const { computedName, intrinsicName } = getState();
+
+			if (value === '') {
+				if (computedName != null || intrinsicName != null) {
+					throw new ErrorProductionDesignPendingError(
+						`Unexpected file name reference. Expected one of "${computedName}", "${intrinsicName}", got: ""`
+					);
+				}
+			}
+
+			if (value === intrinsicName) {
+				return computedName ?? intrinsicName;
+			}
+
+			if (value === computedName) {
+				return computedName;
+			}
+
+			throw new ErrorProductionDesignPendingError(
+				`Unexpected file name reference. Expected one of "${computedName}", "${intrinsicName}", got: "${value}"`
+			);
+		};
+
+		const getValue = createMemo(() => {
+			const { computedName, file: currentFile } = getState();
+
+			if (computedName == null) {
+				return currentFile;
+			}
+
+			return new File([currentFile], computedName, {
+				type: currentFile.type,
+			});
+		});
+		const setValue: SimpleAtomicStateSetter<InstanceAttachmentRuntimeValue> = (value) => {
+			const updatedState = instanceAttachmentState(context, {
+				nodeId,
+				file: value,
+				writtenAt: new Date(),
+			});
+
+			return setState(updatedState).file;
+		};
+		const valueState = [getValue, setValue] as const;
+
+		const getFileName = createMemo(() => {
+			const { computedName, intrinsicName } = getState();
+
+			return computedName ?? intrinsicName;
+		});
+		const getInstanceValue = createMemo(() => getFileName() ?? '');
+
+		return InstanceAttachment.init(context, {
+			getFileName,
+			getInstanceValue,
+			decodeInstanceValue,
+
+			getValue,
+			setValue,
+			valueState,
+		});
+	});
+};

package/src/lib/reactivity/createInstanceValueState.ts

@@ -1,57 +1,27 @@
 import type { Signal } from 'solid-js';
 import { createComputed, createMemo, createSignal, untrack } from 'solid-js';
-import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
 import type { InstanceValueContext } from '../../instance/internal-api/InstanceValueContext.ts';
 import type { BindComputationExpression } from '../../parse/expression/BindComputationExpression.ts';
 import { createComputedExpression } from './createComputedExpression.ts';
 import type { SimpleAtomicState, SimpleAtomicStateSetter } from './types.ts';
 
-type InitialValueSource = 'FORM_DEFAULT' | 'PRIMARY_INSTANCE';
+const isInstanceFirstLoad = (context: InstanceValueContext) => {
+	return context.rootDocument.initializationMode === 'create';
+};
 
 /**
- * @todo {@link InitialValueSource} naming leaves a lot to be desired. As described in {@link InstanceValueStateOptions.initialValueSource}, this check (for now) will effectively answer the question: "are we **NOT** editing instance state (e.g. a submission)?". This answer, in turn, determines whether to {@link setPreloadUIDValue}
+ * Special case, does not correspond to any event.
+ *
+ * @see {@link shouldPreloadUID}
  */
-const isInstanceFirstLoad = (valueSource?: InitialValueSource) => {
-	return valueSource === 'FORM_DEFAULT';
+const isEditInitialLoad = (context: InstanceValueContext) => {
+	return context.rootDocument.initializationMode === 'edit';
 };
 
-export interface InstanceValueStateOptions {
-	/**
-	 * Specifies the source of a {@link createInstanceValueState} 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}. 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 createInstanceValueState} signal's initial state
-	 * should be derived from the current text content of the
-	 * {@link ValueNode.contextNode | primary instance DOM state}.
-	 */
-	readonly initialValueSource?: InitialValueSource;
-}
-
-const getInitialValue = (
-	context: InstanceValueContext,
-	options: InstanceValueStateOptions
-): string => {
-	const { initialValueSource = 'FORM_DEFAULT' } = options;
-
-	if (initialValueSource === 'FORM_DEFAULT') {
-		const { defaultValue } = context.definition;
-
-		return context.decodeInstanceValue(defaultValue);
-	}
+const getInitialValue = (context: InstanceValueContext): string => {
+	const sourceNode = context.instanceNode ?? context.definition.template;
 
-	throw new ErrorProductionDesignPendingError('Edit implementation pending');
+	return context.decodeInstanceValue(sourceNode.value);
 };
 
 type BaseValueState = Signal<string>;
@@ -118,6 +88,16 @@ const guardDownstreamReadonlyWrites = (
  */
 const PRELOAD_UID_EXPRESSION = 'concat("uuid:", uuid())';
 
+/**
+ * @todo It feels increasingly awkward to keep piling up preload stuff here, but it won't stay that way for long. In the meantime, this seems like the best way to express the cases where `preload="uid"` should be effective, i.e.:
+ *
+ * - When an instance is first loaded ({@link isInstanceFirstLoad})
+ * - When an instance is initially loaded for editing ({@link isEditInitialLoad})
+ */
+const shouldPreloadUID = (context: InstanceValueContext) => {
+	return isInstanceFirstLoad(context) || isEditInitialLoad(context);
+};
+
 /**
  * @todo This is a temporary one-off, until we support the full range of
  * {@link https://getodk.github.io/xforms-spec/#preload-attributes | preloads}.
@@ -129,12 +109,11 @@ const PRELOAD_UID_EXPRESSION = 'concat("uuid:", uuid())';
  */
 const setPreloadUIDValue = (
 	context: InstanceValueContext,
-	valueState: RelevantValueState,
-	options: InstanceValueStateOptions
+	valueState: RelevantValueState
 ): void => {
 	const { preload } = context.definition.bind;
 
-	if (preload?.type !== 'uid' || !isInstanceFirstLoad(options?.initialValueSource)) {
+	if (preload?.type !== 'uid' || !shouldPreloadUID(context)) {
 		return;
 	}
 
@@ -182,26 +161,23 @@ export type InstanceValueState = SimpleAtomicState<string>;
  * Provides a consistent interface for value nodes of any type which:
  *
  * - derives initial state from either an existing instance (e.g. for edits) or
- *   the node's definition (e.g. initializing a new submission)
+ *   the node's definition (e.g. initializing a new instance)
  * - decodes current primary instance state into the value node's runtime type
  * - encodes updated runtime values to store updated instance state
  * - initializes reactive computation of `calculate` bind expressions for those
  *   nodes defined with one
  * - prevents downstream writes to nodes in a readonly state
  */
-export const createInstanceValueState = (
-	context: InstanceValueContext,
-	options: InstanceValueStateOptions = {}
-): InstanceValueState => {
+export const createInstanceValueState = (context: InstanceValueContext): InstanceValueState => {
 	return context.scope.runTask(() => {
-		const initialValue = getInitialValue(context, options);
+		const initialValue = getInitialValue(context);
 		const baseValueState = createSignal(initialValue);
 		const relevantValueState = createRelevantValueState(context, baseValueState);
 
 		/**
 		 * @see {@link setPreloadUIDValue} for important details about spec ordering of events and computations.
 		 */
-		setPreloadUIDValue(context, relevantValueState, options);
+		setPreloadUIDValue(context, relevantValueState);
 
 		const { calculate } = context.definition.bind;
 

package/src/lib/resource-helpers.ts

@@ -0,0 +1,33 @@
+import type { FetchResourceResponse } from '../client/resources.ts';
+
+const CONTENT_TYPE_CHARSET_PATTERN = /\s*;\s*charset\s*=.*$/;
+
+const stripContentTypeCharset = (contentType: string): string => {
+	return contentType.replace(CONTENT_TYPE_CHARSET_PATTERN, '');
+};
+
+export const getResponseContentType = (response: FetchResourceResponse): string | null => {
+	const { headers } = response;
+
+	if (headers == null) {
+		return null;
+	}
+
+	const contentType = headers.get('content-type');
+
+	if (contentType != null) {
+		return stripContentTypeCharset(contentType);
+	}
+
+	if (headers instanceof Headers) {
+		return contentType;
+	}
+
+	for (const [header, value] of headers) {
+		if (header.toLowerCase() === 'content-type') {
+			return stripContentTypeCharset(value);
+		}
+	}
+
+	return null;
+};

package/src/parse/XFormDOM.ts

@@ -104,9 +104,7 @@ const normalizeDefaultMetaBindings = (
 	let meta = getMetaElement(primaryInstanceRoot);
 	let instanceID = getMetaChildElement(meta, 'instanceID');
 
-	if (meta == null) {
-		meta = createNamespacedChildElement(primaryInstanceRoot, OPENROSA_XFORMS_NAMESPACE_URI, 'meta');
-	}
+	meta ??= createNamespacedChildElement(primaryInstanceRoot, OPENROSA_XFORMS_NAMESPACE_URI, 'meta');
 
 	if (instanceID == null) {
 		instanceID = createNamespacedChildElement(meta, meta.namespaceURI, 'instanceID');

package/src/parse/body/BodyDefinition.ts

@@ -207,6 +207,10 @@ export class BodyDefinition extends DependencyContext implements BodyElementPare
 		return this.elementsByReference.get(reference) ?? null;
 	}
 
+	getBodyElementType(reference: BodyElementReference): AnyBodyElementType | null {
+		return this.elementsByReference.getBodyElementType(reference);
+	}
+
 	getChildElementDefinitions(
 		form: XFormDefinition,
 		parent: BodyElementParentContext,