@getodk/xforms-engine 0.6.0 → 0.8.0

package/src/instance/abstract/DescendantNode.ts

@@ -11,9 +11,11 @@ import type {
 } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import { XFORMS_XPATH_NODE_RANGE_KIND } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import { createComputedExpression } from '../../lib/reactivity/createComputedExpression.ts';
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
+import type { DescendantNodeInitOptions } from '../children/DescendantNodeInitOptions.ts';
 import type { AnyChildNode, AnyParentNode, RepeatRange } from '../hierarchy.ts';
 import type { EvaluationContext } from '../internal-api/EvaluationContext.ts';
 import type { RepeatInstance } from '../repeat/RepeatInstance.ts';
@@ -50,6 +52,13 @@ interface DescendantNodeOptions {
 	readonly computeReference?: Accessor<string>;
 }
 
+/**
+ * @todo Unify constructor signatures of {@link DescendantNode} and its
+ * subclasses, which will simplify the branchy logic of child node construction
+ * and minimize internal churn as common themes evolve. A good starting point is
+ * beginning to form in {@link DescendantNodeInitOptions} (not to be confused
+ * with the current module-local {@link DescendantNodeOptions}).
+ */
 export abstract class DescendantNode<
 		Definition extends DescendantNodeDefinition,
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -128,10 +137,11 @@ export abstract class DescendantNode<
 
 	constructor(
 		override readonly parent: Parent,
+		override readonly instanceNode: StaticElement | null,
 		override readonly definition: Definition,
 		options?: DescendantNodeOptions
 	) {
-		super(parent.engineConfig, parent, definition, options);
+		super(parent.instanceConfig, parent, instanceNode, definition, options);
 
 		if (this.isRoot()) {
 			this.root = this;
@@ -142,7 +152,7 @@ export abstract class DescendantNode<
 		const { evaluator } = parent;
 
 		// See notes on property declaration
-		if (definition.type === 'repeat-range') {
+		if (definition.type === 'repeat') {
 			this[XPathNodeKindKey] = XFORMS_XPATH_NODE_RANGE_KIND;
 		} else {
 			this[XPathNodeKindKey] = 'element';

package/src/instance/abstract/InstanceNode.ts

@@ -4,7 +4,7 @@ import type { BaseNode } from '../../client/BaseNode.ts';
 import type { NodeAppearances } from '../../client/NodeAppearances.ts';
 import type { FormNodeID } from '../../client/identity.ts';
 import type { InstanceNodeType as ClientInstanceNodeType } from '../../client/node-types.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { NodeValidationState } from '../../client/validation.ts';
 import type { ActiveLanguage, TextRange } from '../../index.ts';
 import type { EngineXPathEvaluator } from '../../integration/xpath/EngineXPathEvaluator.ts';
@@ -13,6 +13,8 @@ import type {
 	XFormsXPathPrimaryInstanceNodeKind,
 } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
 import type { PrimaryInstanceXPathNode } from '../../integration/xpath/adapter/kind.ts';
+import type { StaticDocument } from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
 import type { MaterializedChildren } from '../../lib/reactivity/materializeCurrentStateChildren.ts';
 import type { CurrentState } from '../../lib/reactivity/node-state/createCurrentState.ts';
 import type { EngineState } from '../../lib/reactivity/node-state/createEngineState.ts';
@@ -20,6 +22,7 @@ import type { SharedNodeState } from '../../lib/reactivity/node-state/createShar
 import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
 import { createReactiveScope } from '../../lib/reactivity/scope.ts';
 import type { SimpleAtomicState } from '../../lib/reactivity/types.ts';
+import { createUniqueId } from '../../lib/unique-id.ts';
 import type { AnyNodeDefinition } from '../../parse/model/NodeDefinition.ts';
 import type { PrimaryInstance } from '../PrimaryInstance.ts';
 import type { Root } from '../Root.ts';
@@ -148,7 +151,7 @@ export abstract class InstanceNode<
 
 	abstract readonly validationState: NodeValidationState;
 
-	abstract readonly submissionState: SubmissionState;
+	abstract readonly instanceState: InstanceState;
 
 	// EvaluationContext: instance-global/shared
 	abstract readonly evaluator: EngineXPathEvaluator;
@@ -186,8 +189,9 @@ export abstract class InstanceNode<
 		this as AnyInstanceNode as PrimaryInstanceXPathNode;
 
 	constructor(
-		readonly engineConfig: InstanceConfig,
+		readonly instanceConfig: InstanceConfig,
 		readonly parent: Parent,
+		readonly instanceNode: StaticDocument | StaticElement | null,
 		readonly definition: Definition,
 		options?: InstanceNodeOptions
 	) {
@@ -208,8 +212,8 @@ export abstract class InstanceNode<
 		this.computeReference = options?.computeReference ?? this.computeChildStepReference;
 
 		this.scope = options?.scope ?? createReactiveScope();
-		this.engineConfig = engineConfig;
-		this.nodeId = nodeID(engineConfig.createUniqueId());
+		this.instanceConfig = instanceConfig;
+		this.nodeId = nodeID(createUniqueId());
 		this.definition = definition;
 	}
 

package/src/instance/abstract/ValueNode.ts

@@ -2,11 +2,12 @@ import { XPathNodeKindKey } from '@getodk/xpath';
 import type { Accessor } from 'solid-js';
 import type { BaseValueNode } from '../../client/BaseValueNode.ts';
 import type { LeafNodeType as ValueNodeType } from '../../client/node-types.ts';
-import type { SubmissionState } from '../../client/submission/SubmissionState.ts';
+import type { InstanceState } from '../../client/serialization/InstanceState.ts';
 import type { AnyViolation, LeafNodeValidationState } from '../../client/validation.ts';
 import type { ValueType } from '../../client/ValueType.ts';
 import type { XFormsXPathElement } from '../../integration/xpath/adapter/XFormsXPathNode.ts';
-import { createValueNodeSubmissionState } from '../../lib/client-reactivity/submission/createValueNodeSubmissionState.ts';
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import { createValueNodeInstanceState } from '../../lib/client-reactivity/instance-state/createValueNodeInstanceState.ts';
 import type {
 	RuntimeValueSetter,
 	RuntimeValueState,
@@ -26,7 +27,7 @@ import type {
 	DecodeInstanceValue,
 	InstanceValueContext,
 } from '../internal-api/InstanceValueContext.ts';
-import type { ClientReactiveSubmittableValueNode } from '../internal-api/submission/ClientReactiveSubmittableValueNode.ts';
+import type { ClientReactiveSerializableValueNode } from '../internal-api/serialization/ClientReactiveSerializableValueNode.ts';
 import type { ValidationContext } from '../internal-api/ValidationContext.ts';
 import type { DescendantNodeStateSpec } from './DescendantNode.ts';
 import { DescendantNode } from './DescendantNode.ts';
@@ -52,7 +53,7 @@ export abstract class ValueNode<
 		EvaluationContext,
 		InstanceValueContext,
 		ValidationContext,
-		ClientReactiveSubmittableValueNode
+		ClientReactiveSerializableValueNode
 {
 	protected readonly validation: SharedValidationState;
 	protected readonly getInstanceValue: Accessor<string>;
@@ -80,21 +81,20 @@ export abstract class ValueNode<
 		return this.validation.currentState;
 	}
 
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 
 	constructor(
 		parent: GeneralParentNode,
+		override readonly instanceNode: StaticLeafElement | null,
 		definition: Definition,
 		codec: ValueCodec<V, RuntimeValue, RuntimeInputValue>
 	) {
-		super(parent, definition);
+		super(parent, instanceNode, definition);
 
 		this.valueType = definition.valueType;
 		this.decodeInstanceValue = codec.decodeInstanceValue;
 
-		const instanceValueState = createInstanceValueState(this, {
-			initialValueSource: 'FORM_DEFAULT',
-		});
+		const instanceValueState = createInstanceValueState(this);
 		const valueState = codec.createRuntimeValueState(instanceValueState);
 
 		const [getInstanceValue] = instanceValueState;
@@ -106,10 +106,8 @@ export abstract class ValueNode<
 			return this.getInstanceValue();
 		};
 		this.valueState = valueState;
-		this.validation = createValidationState(this, {
-			clientStateFactory: this.engineConfig.stateFactory,
-		});
-		this.submissionState = createValueNodeSubmissionState(this);
+		this.validation = createValidationState(this, this.instanceConfig);
+		this.instanceState = createValueNodeInstanceState(this);
 	}
 
 	// ValidationContext

package/src/instance/attachments/InstanceAttachment.ts

@@ -0,0 +1,69 @@
+import type { Accessor } from 'solid-js';
+import type { InstancePayload } from '../../client/index.ts';
+import type { SimpleAtomicState, SimpleAtomicStateSetter } from '../../lib/reactivity/types.ts';
+import type { InstanceAttachmentContext } from '../internal-api/InstanceAttachmentContext.ts';
+import type { DecodeInstanceValue } from '../internal-api/InstanceValueContext.ts';
+import type { InstanceAttachmentsState } from './InstanceAttachmentsState.ts';
+
+export type InstanceAttachmentFileName = string;
+export type InstanceAttachmentRuntimeValue = File | null;
+
+export interface InstanceAttachmentOptions {
+	readonly getFileName: Accessor<InstanceAttachmentFileName | null>;
+	readonly getInstanceValue: Accessor<InstanceAttachmentFileName>;
+	readonly decodeInstanceValue: DecodeInstanceValue;
+
+	readonly getValue: Accessor<InstanceAttachmentRuntimeValue>;
+	readonly setValue: SimpleAtomicStateSetter<InstanceAttachmentRuntimeValue>;
+	readonly valueState: SimpleAtomicState<InstanceAttachmentRuntimeValue>;
+}
+
+export class InstanceAttachment {
+	/**
+	 * 1. Creates {@link InstanceAttachment | attachment state} from
+	 *    {@link InstanceAttachmentOptions}
+	 * 2. Registers that attachment state in an instance-global
+	 *    {@link InstanceAttachmentsState} entry
+	 *
+	 * This allows an instance to:
+	 *
+	 * - Produce distinct file names for each attachment
+	 * - Track all attachments so they can be serialized in an
+	 *   {@link InstancePayload}
+	 */
+	static init(
+		context: InstanceAttachmentContext,
+		options: InstanceAttachmentOptions
+	): InstanceAttachment {
+		const attachment = new this(options);
+		const { attachments } = context.rootDocument;
+
+		attachments.set(context, attachment);
+
+		return attachment;
+	}
+
+	/**
+	 * This property isn't used at runtime. It causes TypeScript to treat
+	 * {@link InstanceAttachment} as a nominal type, ensuring
+	 * {@link InstanceAttachment.init} is called to instantiate it.
+	 */
+	protected readonly _ = null;
+
+	readonly getFileName: Accessor<InstanceAttachmentFileName | null>;
+	readonly getInstanceValue: Accessor<InstanceAttachmentFileName>;
+	readonly decodeInstanceValue: DecodeInstanceValue;
+
+	readonly getValue: Accessor<InstanceAttachmentRuntimeValue>;
+	readonly setValue: SimpleAtomicStateSetter<InstanceAttachmentRuntimeValue>;
+	readonly valueState: SimpleAtomicState<InstanceAttachmentRuntimeValue>;
+
+	private constructor(options: InstanceAttachmentOptions) {
+		this.getFileName = options.getFileName;
+		this.getInstanceValue = options.getInstanceValue;
+		this.decodeInstanceValue = options.decodeInstanceValue;
+		this.getValue = options.getValue;
+		this.setValue = options.setValue;
+		this.valueState = options.valueState;
+	}
+}

package/src/instance/attachments/InstanceAttachmentsState.ts

@@ -0,0 +1,18 @@
+import type { StaticLeafElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { InstanceAttachmentMap } from '../input/InstanceAttachmentMap.ts';
+import type { InstanceAttachmentContext } from '../internal-api/InstanceAttachmentContext.ts';
+import type { InstanceAttachment, InstanceAttachmentRuntimeValue } from './InstanceAttachment.ts';
+
+export class InstanceAttachmentsState extends Map<InstanceAttachmentContext, InstanceAttachment> {
+	constructor(private readonly sourceAttachments: InstanceAttachmentMap | null = null) {
+		super();
+	}
+
+	getInitialFileValue(instanceNode: StaticLeafElement | null): InstanceAttachmentRuntimeValue {
+		if (instanceNode == null) {
+			return null;
+		}
+
+		return this.sourceAttachments?.get(instanceNode.value) ?? null;
+	}
+}

package/src/instance/children/DescendantNodeInitOptions.ts

@@ -0,0 +1,35 @@
+import type { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { ChildNodeDefinition } from '../../parse/model/NodeDefinition.ts';
+import type { DescendantNode } from '../abstract/DescendantNode.ts';
+import type { childrenInitOptions } from './childrenInitOptions.ts';
+
+/**
+ * @todo We could pretty significantly simplify downstream child node
+ * construction logic, if we break this down into a tagged union (essentially
+ * moving the branchy type refinement aspects up the stack, probably trimming
+ * the construction logic itself down to a switch statement). At which point,
+ * it'd also probably be easier to reason about each of those constructors
+ * accepting input exactly as it's represented as a member of this hypothetical
+ * tagged union. Something like this:
+ *
+ * - Revise each concrete {@link DescendantNode} class to accept an options-like
+ *   object suitable for its construction, each respectively defined by an
+ *   interface whose name is consistent with that node
+ * - Update this type to be a union of those interfaces
+ * - Implement that in {@link childrenInitOptions}
+ * - Update downstream construction to switch over whatever narrows the union
+ * - Bonus points: revise each concrete {@link DescendantNode} to use a common
+ *   constructor API (i.e. a static `from` method, since several such classes
+ *   already have private constructors). Then downstream isn't even a switch
+ *   statement, it's just a lookup table.
+ *
+ * @todo As of this commit, and as now mentioned on {@link DescendantNode}, and
+ * as discussed in
+ * {@link https://github.com/getodk/web-forms/pull/352#discussion_r2008237762}:
+ * this interface is intended as an intermediate step toward these goals.
+ */
+export interface DescendantNodeInitOptions {
+	readonly childNodeset: string;
+	readonly definition: ChildNodeDefinition;
+	readonly instanceNodes: readonly StaticElement[];
+}

package/src/instance/{children.ts → children/buildChildren.ts}

@@ -1,34 +1,35 @@
 import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
-import type { GroupDefinition } from '../client/GroupNode.ts';
-import type { InputDefinition } from '../client/InputNode.ts';
-import type { ModelValueDefinition } from '../client/ModelValueNode.ts';
-import type { SelectDefinition } from '../client/SelectNode.ts';
-import type { SubtreeDefinition } from '../client/SubtreeNode.ts';
-import type { TriggerNodeDefinition } from '../client/TriggerNode.ts';
-import type { RankDefinition } from '../client/RankNode.ts';
-import type { UploadNodeDefinition } from '../client/unsupported/UploadNode.ts';
-import { ErrorProductionDesignPendingError } from '../error/ErrorProductionDesignPendingError.ts';
-import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
-import { NoteNodeDefinition } from '../parse/model/NoteNodeDefinition.ts';
+import type { GroupDefinition } from '../../client/GroupNode.ts';
+import type { InputDefinition } from '../../client/InputNode.ts';
+import type { ModelValueDefinition } from '../../client/ModelValueNode.ts';
+import type { RankDefinition } from '../../client/RankNode.ts';
+import type { SelectDefinition } from '../../client/SelectNode.ts';
+import type { SubtreeDefinition } from '../../client/SubtreeNode.ts';
+import type { TriggerNodeDefinition } from '../../client/TriggerNode.ts';
+import type { UploadDefinition } from '../../client/UploadNode.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import type { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
+import { NoteNodeDefinition } from '../../parse/model/NoteNodeDefinition.ts';
 import type {
 	AnyRangeNodeDefinition,
 	RangeLeafNodeDefinition,
-} from '../parse/model/RangeNodeDefinition.ts';
-import { RangeNodeDefinition } from '../parse/model/RangeNodeDefinition.ts';
-import type { SubtreeDefinition as ModelSubtreeDefinition } from '../parse/model/SubtreeDefinition.ts';
-import { Group } from './Group.ts';
-import type { GeneralChildNode, GeneralParentNode } from './hierarchy.ts';
-import { InputControl } from './InputControl.ts';
-import { ModelValue } from './ModelValue.ts';
-import { Note } from './Note.ts';
-import { RangeControl } from './RangeControl.ts';
-import { RepeatRangeControlled } from './repeat/RepeatRangeControlled.ts';
-import { RepeatRangeUncontrolled } from './repeat/RepeatRangeUncontrolled.ts';
-import { SelectControl } from './SelectControl.ts';
-import { Subtree } from './Subtree.ts';
-import { TriggerControl } from './TriggerControl.ts';
-import { RankControl } from './RankControl.ts';
-import { UploadControl } from './unsupported/UploadControl.ts';
+} from '../../parse/model/RangeNodeDefinition.ts';
+import { RangeNodeDefinition } from '../../parse/model/RangeNodeDefinition.ts';
+import type { SubtreeDefinition as ModelSubtreeDefinition } from '../../parse/model/SubtreeDefinition.ts';
+import { Group } from '../Group.ts';
+import type { GeneralChildNode, GeneralParentNode } from '../hierarchy.ts';
+import { InputControl } from '../InputControl.ts';
+import { ModelValue } from '../ModelValue.ts';
+import { Note } from '../Note.ts';
+import { RangeControl } from '../RangeControl.ts';
+import { RankControl } from '../RankControl.ts';
+import { RepeatRangeControlled } from '../repeat/RepeatRangeControlled.ts';
+import { RepeatRangeUncontrolled } from '../repeat/RepeatRangeUncontrolled.ts';
+import { SelectControl } from '../SelectControl.ts';
+import { Subtree } from '../Subtree.ts';
+import { TriggerControl } from '../TriggerControl.ts';
+import { UploadControl } from '../UploadControl.ts';
+import { childrenInitOptions } from './childrenInitOptions.ts';
 
 const isSubtreeDefinition = (
 	definition: ModelSubtreeDefinition
@@ -36,9 +37,6 @@ const isSubtreeDefinition = (
 	return definition.bodyElement == null;
 };
 
-// prettier-ignore
-type AnyUnsupportedControlDefinition = UploadNodeDefinition;
-
 // prettier-ignore
 type ControlNodeDefinition =
 	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
@@ -47,7 +45,7 @@ type ControlNodeDefinition =
 	| SelectDefinition
 	| RankDefinition
 	| TriggerNodeDefinition
-	| AnyUnsupportedControlDefinition;
+	| UploadDefinition;
 
 type AnyLeafNodeDefinition = ControlNodeDefinition | ModelValueDefinition;
 
@@ -122,77 +120,83 @@ const isTriggerNodeDefinition = (
 
 const isUploadNodeDefinition = (
 	definition: ControlNodeDefinition
-): definition is UploadNodeDefinition => {
+): definition is UploadDefinition => {
 	return definition.bodyElement.type === 'upload';
 };
 
 export const buildChildren = (parent: GeneralParentNode): GeneralChildNode[] => {
-	const { children } = parent.definition;
+	const { children } = childrenInitOptions(parent);
+
+	return children.map(({ instanceNodes, definition }): GeneralChildNode => {
+		const [instanceNode = null] = instanceNodes;
 
-	return children.map((child): GeneralChildNode => {
-		switch (child.type) {
+		switch (definition.type) {
 			case 'subtree': {
-				if (isSubtreeDefinition(child)) {
-					return new Subtree(parent, child);
+				if (isSubtreeDefinition(definition)) {
+					return new Subtree(parent, instanceNode, definition);
 				}
 
 				// TODO: it'd be good to be able to do without this type assertion. The
 				// only distinction between the types is whether `bodyElement` is
 				// `null`, but for some reason that's insufficient to narrow the union.
-				return new Group(parent, child as GroupDefinition);
+				return new Group(parent, instanceNode, definition as GroupDefinition);
 			}
 
-			case 'repeat-range': {
-				if (child.isControlled()) {
-					return new RepeatRangeControlled(parent, child);
+			case 'repeat': {
+				if (definition.isControlled()) {
+					return new RepeatRangeControlled(parent, instanceNodes, definition);
 				}
 
-				return new RepeatRangeUncontrolled(parent, child);
+				return new RepeatRangeUncontrolled(parent, instanceNodes, definition);
 			}
 
 			case 'leaf-node': {
-				if (child instanceof NoteNodeDefinition) {
-					return new Note(parent, child);
+				if (instanceNode != null && !instanceNode.isLeafElement()) {
+					throw new ErrorProductionDesignPendingError();
+				}
+
+				if (definition instanceof NoteNodeDefinition) {
+					return new Note(parent, instanceNode, definition);
 				}
 
 				// More specific type helps with narrowing below
-				const leafChild: AnyLeafNodeDefinition = child;
+				const leafChild: AnyLeafNodeDefinition = definition;
 
 				if (isModelValueDefinition(leafChild)) {
-					return ModelValue.from(parent, leafChild);
+					return ModelValue.from(parent, instanceNode, leafChild);
 				}
 
 				if (isInputDefinition(leafChild)) {
-					return InputControl.from(parent, leafChild);
+					return InputControl.from(parent, instanceNode, leafChild);
 				}
 
 				if (isSelectDefinition(leafChild)) {
-					return SelectControl.from(parent, leafChild);
+					return SelectControl.from(parent, instanceNode, leafChild);
 				}
 
 				if (isRankDefinition(leafChild)) {
-					return RankControl.from(parent, leafChild);
+					return RankControl.from(parent, instanceNode, leafChild);
 				}
 
 				if (isTriggerNodeDefinition(leafChild)) {
-					return TriggerControl.from(parent, leafChild);
+					return TriggerControl.from(parent, instanceNode, leafChild);
 				}
 
 				if (isRangeLeafNodeDefinition(leafChild)) {
 					assertRangeNodeDefinition(leafChild);
 
-					return RangeControl.from(parent, leafChild);
+					return RangeControl.from(parent, instanceNode, leafChild);
 				}
 
 				if (isUploadNodeDefinition(leafChild)) {
-					return new UploadControl(parent, leafChild);
+					return UploadControl.from(parent, instanceNode, leafChild);
 				}
 
 				throw new UnreachableError(leafChild);
 			}
 
 			default: {
-				throw new UnreachableError(child);
+				throw new UnreachableError(definition);
 			}
 		}
 	});

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);
+};