@getodk/xforms-engine 0.6.0 → 0.7.0

package/src/instance/children/childrenInitOptions.ts

@@ -0,0 +1,117 @@
+import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { ModelDefinition } from '../../parse/model/ModelDefinition.ts';
+import type {
+	AnyNodeDefinition,
+	ChildNodeDefinition,
+	NodeDefinition,
+} from '../../parse/model/NodeDefinition.ts';
+import type { InstanceNode } from '../abstract/InstanceNode.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { DescendantNodeInitOptions } from './DescendantNodeInitOptions.ts';
+import { normalizeChildInitOptions } from './normalizeChildInitOptions.ts';
+
+/**
+ * Child nodesets are collected from the {@link parent}'s
+ * {@link NodeDefinition.template}, ensuring that we produce
+ * {@link InstanceNode}s for every **model-defined** node, even if a
+ * corresponding node was not serialized in a {@link parent.instanceNode}.
+ *
+ * In other words, by referencing the model-defined template, we are able to
+ * reproduce nodes which were omitted as non-relevant in a prior serialization
+ * and/or submission.
+ *
+ * @todo Since we're building an instance node's children from the nodesets of
+ * the model-defined node's children, we are _implicitly dropping_ any excess
+ * nodes from non-model instance data. That's probably the right behavior, but
+ * we may want to warn for such nodes if/when we do drop them.
+ */
+const collectModelChildNodesets = (parentTemplate: StaticElement): readonly string[] => {
+	const nodesets = parentTemplate.childElements.map(({ nodeset }) => {
+		return nodeset;
+	});
+
+	return Array.from(new Set(nodesets));
+};
+
+type InstanceNodesByNodeset = ReadonlyMap<string, readonly [StaticElement, ...StaticElement[]]>;
+
+const groupChildElementsByNodeset = (
+	parent: StaticDocument | StaticElement
+): InstanceNodesByNodeset => {
+	const result = new Map<string, [StaticElement, ...StaticElement[]]>();
+
+	for (const child of parent.childElements) {
+		const { nodeset } = child;
+		const group = result.get(nodeset);
+
+		if (group == null) {
+			result.set(nodeset, [child]);
+		} else {
+			group.push(child);
+		}
+	}
+
+	return result;
+};
+
+type AssertChildNodeDefinition = (
+	definition: AnyNodeDefinition,
+	childNodeset: string
+) => asserts definition is ChildNodeDefinition;
+
+const assertChildNodeDefinition: AssertChildNodeDefinition = (definition, childNodeset) => {
+	if (definition.type === 'root') {
+		throw new Error(`Unexpected root definition for child nodeset: ${childNodeset}`);
+	}
+};
+
+export interface ChildrenInitOptions {
+	readonly parent: GeneralParentNode;
+	readonly model: ModelDefinition;
+	readonly children: readonly DescendantNodeInitOptions[];
+}
+
+export const childrenInitOptions = (parent: GeneralParentNode): ChildrenInitOptions => {
+	const { model } = parent.rootDocument;
+	const childNodesets = collectModelChildNodesets(parent.definition.template);
+
+	let instanceChildren: InstanceNodesByNodeset | null;
+
+	if (parent.instanceNode == null) {
+		instanceChildren = null;
+	} else {
+		instanceChildren = groupChildElementsByNodeset(parent.instanceNode);
+	}
+
+	const children = childNodesets.map((childNodeset) => {
+		const definition = model.getNodeDefinition(childNodeset);
+
+		assertChildNodeDefinition(definition, childNodeset);
+
+		/**
+		 * Get children of the target nodeset from {@link parent.instanceNode}, if
+		 * that node exists, and if children with that nodeset exist.
+		 *
+		 * If either does not exist (e.g. it was omitted as non-relevant in a prior
+		 * serialization), we continue to reference model-defined templates as we
+		 * recurse down the {@link InstanceNode} subtree.
+		 *
+		 * @see {@link childNodesets}
+		 */
+		const instanceNodes = instanceChildren?.get(childNodeset) ?? [];
+
+		return {
+			childNodeset,
+			definition,
+			instanceNodes,
+		};
+	});
+	const baseResult: ChildrenInitOptions = {
+		parent,
+		model,
+		children,
+	};
+
+	return normalizeChildInitOptions(baseResult);
+};

package/src/instance/children/normalizeChildInitOptions.ts

@@ -0,0 +1,332 @@
+import {
+	OPENROSA_XFORMS_NAMESPACE_URI,
+	XFORMS_NAMESPACE_URI,
+} from '@getodk/common/constants/xmlns.ts';
+import type { GroupDefinition } from '../../client/GroupNode.ts';
+import type { SubtreeDefinition } from '../../client/SubtreeNode.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { NamespaceURL } from '../../lib/names/NamespaceURL.ts';
+import type { QualifiedName } from '../../lib/names/QualifiedName.ts';
+import { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import type { SubtreeDefinition as ModelSubtreeDefinition } from '../../parse/model/SubtreeDefinition.ts';
+import type { XFormDOM } from '../../parse/XFormDOM.ts';
+import type { Group } from '../Group.ts';
+import type { GeneralParentNode } from '../hierarchy.ts';
+import type { PrimaryInstance } from '../PrimaryInstance.ts';
+import type { Root } from '../Root.ts';
+import type { Subtree } from '../Subtree.ts';
+import type { ChildrenInitOptions } from './childrenInitOptions.ts';
+import type { DescendantNodeInitOptions } from './DescendantNodeInitOptions.ts';
+
+const META_LOCAL_NAME = 'meta';
+const INSTANCE_ID_LOCAL_NAME = 'instanceID';
+const DEPRECATED_ID_LOCAL_NAME = 'deprecatedID';
+
+type MetaLocalName = typeof META_LOCAL_NAME;
+
+const META_NAMESPACE_URIS = [OPENROSA_XFORMS_NAMESPACE_URI, XFORMS_NAMESPACE_URI] as const;
+
+type MetaNamespaceURIValue = (typeof META_NAMESPACE_URIS)[number];
+
+interface MetaNamespaceURI extends NamespaceURL {
+	readonly href: MetaNamespaceURIValue;
+}
+
+interface MetaNamespacedName extends QualifiedName {
+	readonly namespaceURI: MetaNamespaceURI;
+}
+
+const isMetaNamespacedName = (
+	qualifiedName: QualifiedName
+): qualifiedName is MetaNamespacedName => {
+	const namespaceURI = qualifiedName.namespaceURI?.href;
+
+	return (
+		namespaceURI != null && META_NAMESPACE_URIS.includes(namespaceURI as MetaNamespaceURIValue)
+	);
+};
+
+interface MetaName extends MetaNamespacedName {
+	readonly localName: MetaLocalName;
+}
+
+const isMetaName = (qualifiedName: QualifiedName): qualifiedName is MetaName => {
+	return isMetaNamespacedName(qualifiedName) && qualifiedName.localName === META_LOCAL_NAME;
+};
+
+const isDirectRootDescendant = (parent: GeneralParentNode) => {
+	return parent.parent === parent.root;
+};
+
+interface BaseMetaDefinition {
+	readonly qualifiedName: MetaName;
+}
+
+const isBaseMetaDefinition = <T extends ModelSubtreeDefinition>(
+	definition: T
+): definition is BaseMetaDefinition & T => {
+	return isMetaName(definition.qualifiedName);
+};
+
+interface MetaSubtreeDefinition extends SubtreeDefinition {
+	readonly qualifiedName: MetaName;
+}
+
+interface MetaSubtree extends Subtree {
+	readonly parent: Root;
+	readonly definition: MetaSubtreeDefinition;
+}
+
+interface MetaGroupDefinition extends GroupDefinition {
+	readonly qualifiedName: MetaName;
+}
+
+interface MetaGroup extends Group {
+	readonly parent: Root;
+	readonly definition: MetaGroupDefinition;
+}
+
+type MetaSubroot = MetaGroup | MetaSubtree;
+
+interface MetaSubrootInitOptions extends ChildrenInitOptions {
+	readonly parent: MetaGroup | MetaSubtree;
+}
+
+const isMetaSubroot = (options: ChildrenInitOptions): options is MetaSubrootInitOptions => {
+	const { nodeType } = options.parent;
+
+	return (
+		(nodeType === 'subtree' || nodeType === 'group') &&
+		isDirectRootDescendant(options.parent) &&
+		isBaseMetaDefinition(options.parent.definition)
+	);
+};
+
+interface EditModeInstance extends PrimaryInstance {
+	readonly initializationMode: 'edit';
+}
+
+const isEditModeInstance = (
+	primaryInstance: PrimaryInstance
+): primaryInstance is EditModeInstance => {
+	return primaryInstance.initializationMode === 'edit';
+};
+
+interface EditModeInstanceDescendant {
+	readonly rootDocument: EditModeInstance;
+}
+
+type EditModeMetaSubroot = EditModeInstanceDescendant & MetaSubroot;
+
+interface EditModeMetaSubrootInitOptions extends MetaSubrootInitOptions {
+	readonly parent: EditModeMetaSubroot;
+}
+
+const isEditModeMetaSubroot = (
+	subroot: MetaSubrootInitOptions
+): subroot is EditModeMetaSubrootInitOptions => {
+	return isEditModeInstance(subroot.parent.rootDocument);
+};
+
+interface LeafNodeInitOptions extends DescendantNodeInitOptions {
+	readonly instanceNodes: readonly [StaticLeafElement];
+}
+
+const isLeafNodeInitOptions = (
+	options: DescendantNodeInitOptions
+): options is LeafNodeInitOptions => {
+	const { instanceNodes } = options;
+	const [instanceNode, ...rest] = instanceNodes;
+
+	return instanceNode != null && rest.length === 0 && instanceNode.isLeafElement();
+};
+
+type MetaLeafChildEntry = readonly [index: number, child: LeafNodeInitOptions];
+
+const findMetaLeafChild = (
+	subroot: MetaSubrootInitOptions,
+	localName: string
+): MetaLeafChildEntry | null => {
+	const metaName = subroot.parent.definition.qualifiedName satisfies MetaName;
+	const namespaceURI = metaName.namespaceURI.href satisfies MetaNamespaceURIValue;
+
+	const result = Array.from(subroot.children.entries()).find(
+		(entry): entry is [number, LeafNodeInitOptions] => {
+			const [, child] = entry;
+
+			if (!isLeafNodeInitOptions(child)) {
+				return false;
+			}
+
+			const [instanceNode] = child.instanceNodes;
+			const { qualifiedName } = instanceNode;
+
+			return (
+				qualifiedName.localName === localName && qualifiedName.namespaceURI?.href === namespaceURI
+			);
+		}
+	);
+
+	return result ?? null;
+};
+
+const getInstanceIDValue = (subroot: MetaSubrootInitOptions): string | null => {
+	const [, child = null] = findMetaLeafChild(subroot, INSTANCE_ID_LOCAL_NAME) ?? [];
+
+	if (child == null) {
+		return null;
+	}
+
+	const [instanceIDNode] = child.instanceNodes;
+
+	return instanceIDNode.value satisfies string;
+};
+
+type AssertStaticLeafElement = (element: StaticElement) => asserts element is StaticLeafElement;
+
+const assertStaticLeafElement: AssertStaticLeafElement = (element) => {
+	if (!element.isLeafElement()) {
+		throw new ErrorProductionDesignPendingError(
+			`Expected a leaf element, got a non-leaf element at nodeset: ${element.nodeset}`
+		);
+	}
+};
+
+/**
+ * @todo this name and signature are general, for the same reasons as the TODO
+ * on {@link populateDeprecatedID}.
+ */
+const buildMetaValueElement = (
+	subroot: MetaSubrootInitOptions,
+	localName: string,
+	value: string
+): StaticLeafElement => {
+	const { qualifiedName, nodeset } = subroot.parent.definition;
+	const { namespaceURI, prefix } = qualifiedName;
+	const { root } = new StaticDocument({
+		documentRoot: {
+			name: {
+				namespaceURI,
+				prefix,
+				localName,
+			},
+			children: [value],
+		},
+		nodesetPrefix: nodeset,
+	});
+
+	assertStaticLeafElement(root);
+
+	return root;
+};
+
+const buildDeprecatedIDDefinition = (
+	subroot: EditModeMetaSubrootInitOptions,
+	instanceNode: StaticLeafElement
+): LeafNodeDefinition => {
+	const nodeset = instanceNode.nodeset;
+	const bind = subroot.model.binds.getOrCreateBindDefinition(nodeset);
+
+	return new LeafNodeDefinition(subroot.parent.definition, bind, null, instanceNode);
+};
+
+const buildDeprecatedID = (
+	subroot: EditModeMetaSubrootInitOptions,
+	value: string
+): LeafNodeInitOptions => {
+	const instanceNode = buildMetaValueElement(subroot, DEPRECATED_ID_LOCAL_NAME, value);
+	const definition = buildDeprecatedIDDefinition(subroot, instanceNode);
+
+	return {
+		childNodeset: instanceNode.nodeset,
+		definition,
+		instanceNodes: [instanceNode],
+	};
+};
+
+const updateDeprecatedID = (
+	subroot: EditModeMetaSubrootInitOptions,
+	child: LeafNodeInitOptions,
+	value: string
+): LeafNodeInitOptions => {
+	const instanceNode = buildMetaValueElement(subroot, DEPRECATED_ID_LOCAL_NAME, value);
+
+	return {
+		childNodeset: child.childNodeset,
+		definition: child.definition,
+		instanceNodes: [instanceNode],
+	};
+};
+
+/**
+ * Should be: values.with(index, value)
+ *
+ * @todo update tsconfig.json `lib` throughout project!
+ */
+const replace = <T>(values: readonly T[], index: number, value: T): readonly T[] => {
+	const results = values.slice();
+
+	results.splice(index, 1, value);
+
+	return results;
+};
+
+const replaceOrConcat = <T>(values: readonly T[], index: number | null, value: T): readonly T[] => {
+	if (index == null) {
+		return values.concat(value);
+	}
+
+	return replace(values, index, value);
+};
+
+/**
+ * @todo Whenever we have bandwidth to start migrating away from DOM usage in
+ * {@link XFormDOM}, this is a good place to start for logic equivalent to the
+ * hacky normalization for `instanceID`.
+ */
+const populateDeprecatedID = (
+	subroot: EditModeMetaSubrootInitOptions
+): EditModeMetaSubrootInitOptions => {
+	const value = getInstanceIDValue(subroot);
+
+	if (value == null) {
+		return subroot;
+	}
+
+	const [index, currentDeprecatedID] = findMetaLeafChild(subroot, DEPRECATED_ID_LOCAL_NAME) ?? [
+		null,
+	];
+
+	let deprecatedID: LeafNodeInitOptions;
+
+	if (currentDeprecatedID == null) {
+		deprecatedID = buildDeprecatedID(subroot, value);
+	} else {
+		deprecatedID = updateDeprecatedID(subroot, currentDeprecatedID, value);
+	}
+
+	return {
+		model: subroot.model,
+		parent: subroot.parent,
+		children: replaceOrConcat(subroot.children, index, deprecatedID),
+	};
+};
+
+const normalizeMetaSubroot = (subroot: MetaSubrootInitOptions): MetaSubrootInitOptions => {
+	if (isEditModeMetaSubroot(subroot)) {
+		return populateDeprecatedID(subroot);
+	}
+
+	return subroot;
+};
+
+export const normalizeChildInitOptions = (options: ChildrenInitOptions): ChildrenInitOptions => {
+	if (isMetaSubroot(options)) {
+		return normalizeMetaSubroot(options);
+	}
+
+	return options;
+};

package/src/instance/input/InitialInstanceState.ts

@@ -0,0 +1,108 @@
+import { getBlobText } from '@getodk/common/lib/web-compat/blob.ts';
+import { INSTANCE_FILE_NAME } from '../../client/constants.ts';
+import type {
+	EditFormInstanceInput,
+	ResolvableFormInstanceInput,
+} from '../../client/form/EditFormInstance.ts';
+import type { InstanceData } from '../../client/serialization/InstanceData.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { ModelDefinition } from '../../parse/model/ModelDefinition.ts';
+import { parseInstanceXML } from '../../parse/shared/parseInstanceXML.ts';
+import type { XFormDOM } from '../../parse/XFormDOM.ts';
+import { InstanceAttachmentMap } from './InstanceAttachmentMap.ts';
+
+export type InitialInstanceStateSources = readonly [InstanceData, ...InstanceData[]];
+
+interface InitialInstanceStateOptions {
+	readonly instanceXML: string;
+	readonly attachments: InstanceAttachmentMap;
+}
+
+const resolveInstanceXML = async (input: ResolvableFormInstanceInput): Promise<string> => {
+	const instanceResult = await input.resolveInstance();
+
+	if (typeof instanceResult === 'string') {
+		return instanceResult;
+	}
+
+	if (instanceResult instanceof Blob) {
+		return getBlobText(instanceResult);
+	}
+
+	return instanceResult.text();
+};
+
+const parseInstanceDocument = (model: ModelDefinition, instanceXML: string): StaticDocument => {
+	const doc = parseInstanceXML(model, instanceXML);
+
+	/**
+	 * Note: this is presently inferred as nullable. Its presence is _currently_
+	 * enforced by {@link XFormDOM}, though that's definitely not ideal!
+	 *
+	 * @todo we would probably benefit from a single parse function responsible
+	 * for both instance documents (form and input), with all `id` enforcement
+	 * handled in one place (presence in both cases, matching in case of form +
+	 * input). We could then also express this at the type level without weird DOM
+	 * shenanigans in {@link XFormDOM} (which aren't likely to stick around in
+	 * their current state forever!).
+	 */
+	const expectedId = model.instance.root.getAttributeValue('id');
+	const actualId = doc.root.getAttributeValue('id');
+
+	if (expectedId !== actualId) {
+		throw new ErrorProductionDesignPendingError(
+			`Invalid instance input. Expected instance id to be "${expectedId}", got: "${actualId}"`
+		);
+	}
+
+	return doc;
+};
+
+export class InitialInstanceState {
+	static async from(
+		model: ModelDefinition,
+		data: InitialInstanceStateSources
+	): Promise<InitialInstanceState> {
+		return this.resolve(model, {
+			inputType: 'FORM_INSTANCE_INPUT_RESOLVED',
+			data,
+		});
+	}
+
+	static async resolve(
+		model: ModelDefinition,
+		input: EditFormInstanceInput
+	): Promise<InitialInstanceState> {
+		if (input.inputType === 'FORM_INSTANCE_INPUT_RESOLVED') {
+			const { data } = input;
+			const [instanceData] = data;
+			const instanceFile = instanceData.get(INSTANCE_FILE_NAME);
+			const instanceXML = await getBlobText(instanceFile);
+			const attachments = InstanceAttachmentMap.from(data);
+
+			return new this(model, {
+				instanceXML,
+				attachments,
+			});
+		}
+
+		const [instanceXML, attachments] = await Promise.all([
+			resolveInstanceXML(input),
+			InstanceAttachmentMap.resolve(input.attachments),
+		]);
+
+		return new this(model, {
+			instanceXML,
+			attachments,
+		});
+	}
+
+	readonly document: StaticDocument;
+	readonly attachments: InstanceAttachmentMap;
+
+	private constructor(model: ModelDefinition, options: InitialInstanceStateOptions) {
+		this.document = parseInstanceDocument(model, options.instanceXML);
+		this.attachments = options.attachments;
+	}
+}

package/src/instance/input/InstanceAttachmentMap.ts

@@ -0,0 +1,142 @@
+import { INSTANCE_FILE_NAME } from '../../client/constants.ts';
+import type { ResolvableInstanceAttachmentsMap } from '../../client/form/EditFormInstance.ts';
+import { MalformedInstanceDataError } from '../../error/MalformedInstanceDataError.ts';
+
+type InstanceAttachmentMapSourceEntry = readonly [key: string, value: FormDataEntryValue];
+
+interface InstanceAttachmentMapSource {
+	entries(): Iterable<InstanceAttachmentMapSourceEntry>;
+}
+
+type InstanceAttachmentMapSources = readonly [
+	InstanceAttachmentMapSource,
+	...InstanceAttachmentMapSource[],
+];
+
+/**
+ * @todo This currently short-circuits if there are actually any instance
+ * attachments to resolve. As described below, much of the approach is pretty
+ * naive now anyway, and none of it is really "ready" until we have something to
+ * actually _use the instance attachments_ once they're resolved! When we are
+ * ready, the functionality can be unblocked as in
+ * {@link https://github.com/getodk/web-forms/commit/88ee1b91c1f68d53ce9ba551bab334852e1e60cd | this commit}.
+ *
+ * @todo Everything about this is incredibly naive! We should almost certainly
+ * do _at least_ the following:
+ *
+ * - Limit how many attachments we attempt to resolve concurrently
+ * - Lazy resolution of large attachments (i.e. probably streaming, maybe range
+ *   requests, ?)
+ *
+ * @todo Once lazy resolution is a thing, we will **also** need a clear path
+ * from there to eager resolution (i.e. for offline caching: it doesn't make
+ * sense to cache a stream in progress, as it won't load the resource once the
+ * user actually is offline/lacks network access). This may be something we can
+ * evolve gradually!
+ */
+const resolveInstanceAttachmentMapSource = async (
+	input: ResolvableInstanceAttachmentsMap
+): Promise<InstanceAttachmentMapSource> => {
+	const inputEntries = Array.from(input.entries());
+
+	if (inputEntries.length > 0) {
+		const fileNames = Array.from(input.keys());
+		const errors = fileNames.map((fileName) => {
+			return new Error(`Failed to resolve instance attachment with file name "${fileName}"`);
+		});
+
+		throw new AggregateError(errors, 'Not implemented: instance attachment resource resolution');
+	}
+
+	const entries = await Promise.all<InstanceAttachmentMapSourceEntry>(
+		inputEntries.map(async ([fileName, resolveAttachment]) => {
+			const response = await resolveAttachment();
+			const blob = await response.blob();
+			const value = new File([blob], fileName);
+
+			return [fileName, value] as const;
+		})
+	);
+
+	return { entries: () => entries };
+};
+
+interface KeyedInstanceDataFile<Key extends string> extends File {
+	readonly name: Key;
+}
+
+type AssertKeyedInstanceDataFile = <Key extends string>(
+	key: Key,
+	file: File
+) => asserts file is KeyedInstanceDataFile<Key>;
+
+const assertKeyedInstanceDataFile: AssertKeyedInstanceDataFile = (key, file) => {
+	if (file.name !== key) {
+		throw new MalformedInstanceDataError(
+			`Unexpected InstanceData file. Expected file name to match key, got key: ${JSON.stringify(key)} and file name: ${JSON.stringify(file.name)}`
+		);
+	}
+};
+
+type UnknownInstanceDataEntry = readonly [key: string, value: FormDataEntryValue];
+
+type KeyedInstanceDataEntry<Key extends string> = readonly [key: Key, KeyedInstanceDataFile<Key>];
+
+type AssertInstanceDataEntry = <Key extends string>(
+	entry: UnknownInstanceDataEntry
+) => asserts entry is KeyedInstanceDataEntry<Key>;
+
+const assertInstanceDataEntry: AssertInstanceDataEntry = (entry) => {
+	const [key, value] = entry;
+
+	if (!(value instanceof File)) {
+		throw new MalformedInstanceDataError(
+			`Unexpected non-file attachment in InstanceData for key: ${key}`
+		);
+	}
+
+	assertKeyedInstanceDataFile(key, value);
+};
+
+export class InstanceAttachmentMap extends Map<string, File> {
+	static from(sources: InstanceAttachmentMapSources): InstanceAttachmentMap {
+		return new this(sources);
+	}
+
+	/**
+	 * @todo
+	 * @see {@link resolveInstanceAttachmentMapSource}
+	 */
+	static async resolve(input: ResolvableInstanceAttachmentsMap): Promise<InstanceAttachmentMap> {
+		const source = await resolveInstanceAttachmentMapSource(input);
+
+		return new this([source]);
+	}
+
+	private constructor(sources: InstanceAttachmentMapSources) {
+		super();
+
+		for (const source of sources) {
+			for (const entry of source.entries()) {
+				const [key] = entry;
+
+				// Skip the instance XML file: it's not an attachment!
+				if (key === INSTANCE_FILE_NAME) {
+					continue;
+				}
+
+				if (this.has(key)) {
+					throw new MalformedInstanceDataError(
+						`Unexpected InstanceData entry. Duplicate instance attachment for key: ${JSON.stringify(key)}`
+					);
+				}
+
+				assertInstanceDataEntry(entry);
+
+				const [, value] = entry;
+
+				this.set(key, value);
+			}
+		}
+	}
+}