@getodk/xforms-engine 0.5.0 → 0.7.0

package/dist/client/form/EditFormInstance.d.ts

@@ -0,0 +1,62 @@
+import { Awaitable, Thunk } from '../../../../common/types/helpers.d.ts';
+import { FetchResourceResponse } from '../resources.ts';
+import { InstanceAttachmentFileName, InstanceData } from '../serialization/InstanceData.ts';
+import { FormInstance, FormInstanceEditMode } from './FormInstance.ts';
+import { FormInstanceConfig } from './FormInstanceConfig.ts';
+import { RestoreFormInstanceInput } from './RestoreFormInstance.ts';
+export type ResolvableFormInstanceInputType = 'FORM_INSTANCE_INPUT_RESOLVABLE';
+export type ResolvedFormInstanceInputType = 'FORM_INSTANCE_INPUT_RESOLVED';
+export type EditFormInstanceInputType = ResolvableFormInstanceInputType | ResolvedFormInstanceInputType;
+export type ResolvedFormInstance = Blob | FetchResourceResponse | File | string;
+export type ResolvableFormInstance = Thunk<Awaitable<ResolvedFormInstance>>;
+export type ResolveFormInstanceResource = Thunk<Promise<FetchResourceResponse>>;
+export type ResolvableInstanceAttachmentsMap = ReadonlyMap<InstanceAttachmentFileName, ResolveFormInstanceResource>;
+interface BaseEditFormInstanceInput {
+    readonly inputType: EditFormInstanceInputType;
+    readonly data?: readonly [InstanceData, ...InstanceData[]];
+    readonly resolveInstance?: ResolvableFormInstance;
+    readonly attachments?: ResolvableInstanceAttachmentsMap;
+}
+export interface ResolvableFormInstanceInput extends BaseEditFormInstanceInput {
+    readonly inputType: ResolvableFormInstanceInputType;
+    readonly resolveInstance: ResolvableFormInstance;
+    readonly attachments: ResolvableInstanceAttachmentsMap;
+    readonly data?: never;
+}
+/**
+ * @todo This is included as a strawman for discussiong: "should we accept input
+ * to {@link EditFormInstance} in the same shape as input to
+ * {@link RestoreFormInstance}?".
+ *
+ * Pros:
+ *
+ * - More consistency between the two entrypoint APIs, which are pretty similar
+ *   _conceptually_.
+ * - ?
+ *
+ * Cons:
+ *
+ * - Less consistency between this entrypoint API and {@link LoadForm}, which is
+ *   also responsible for loading arbitrary attachments (presumably over a
+ *   network), which...
+ * - ... all but rules out flexibility to optimize loading large resources (i.e.
+ *   streaming video/audio)
+ *
+ * Alternative:
+ *
+ * - Increase consistency across the board by inverting the relationship between
+ *   edit/restore: {@link RestoreFormInstanceInput} could be the place where we
+ *   accept a union of resolved | resolvable input, and clients which might
+ *   benefit from this consistency could consolidate on the resolvable case
+ *   without sacrificing resource loading optimizations)
+ */
+export interface ResolvedFormInstanceInput extends BaseEditFormInstanceInput, RestoreFormInstanceInput {
+    readonly inputType: ResolvedFormInstanceInputType;
+    readonly data: readonly [InstanceData, ...InstanceData[]];
+    readonly resolveInstance?: never;
+    readonly attachments?: never;
+}
+export type EditFormInstanceInput = ResolvableFormInstanceInput | ResolvedFormInstanceInput;
+export type EditedFormInstance = FormInstance<FormInstanceEditMode>;
+export type EditFormInstance = (input: EditFormInstanceInput, config?: FormInstanceConfig) => Promise<EditedFormInstance>;
+export {};

package/dist/client/form/FormInstance.d.ts

@@ -0,0 +1,104 @@
+import { RootNode } from '../RootNode.ts';
+import { InstantiableLoadFormResult } from './LoadFormResult.ts';
+/**
+ * Represents an instance which is newly created from a form definition.
+ *
+ * A newly created instance is populated with default values and state defined
+ * by the form.
+ *
+ * Computations are performed on initialization as specified by
+ * {@link https://getodk.github.io/xforms-spec/ | ODK XForms}, as the instance's
+ * {@link https://getodk.github.io/xforms-spec/#event:odk-instance-first-load | first load}.
+ */
+export type FormInstanceCreateMode = 'create';
+/**
+ * Represents an instance restored from previously filled state, as represented
+ * in an {@link InstancePayload}. Clients may serialize and persist an instance
+ * payload as appropriate for their use cases, and can restore the instance with
+ * a partial instance payload structure, defined by the
+ * {@link RestoreFormInstanceInput} interface.
+ *
+ * A restored instance is populated by the engine with the answers as they had
+ * been filled at the time the {@link InstancePayload}
+ * ({@link RestoreFormInstanceInput}) was created.
+ *
+ * Computations are performed on initialization as specified by
+ * {@link https://getodk.github.io/xforms-spec/#event:odk-instance-load | ODK XForms},
+ * as a
+ * {@link https://getodk.github.io/xforms-spec/#event:odk-instance-load | subsequent load}
+ * (i.e. **NOT** "first load", as is the case with newly
+ * {@link FormInstanceCreateMode | created} instances}) of the instance.
+ */
+export type FormInstanceRestoreMode = 'restore';
+/**
+ * Represents an instance which:
+ *
+ * - was previously serialized
+ * - was **submitted**, often referred to as a "submission" (noun)
+ * - is being initialized to produce an edited instance of that "submission"
+ *
+ * An edited instance may be populated from one or more network-accessible
+ * resources—its serialized instance XML, and any _instance attachments_—which
+ * are resolved in a manner similar to that of a form definition and its _form
+ * attachments_.
+ *
+ * Once resolved, an edited instance is restored from its previously filled
+ * state _as it was submitted_, consistent with
+ * {@link FormInstanceRestoreMode | restoring an instance}, with the following
+ * exceptions:
+ *
+ * - If the form or instance does not define an explicit
+ *   {@link https://getodk.github.io/xforms-spec/#metadata | `deprecatedID` metadata element},
+ *   one will be created.
+ *
+ * - If the instance has an `instanceID` metadata element, that element's value
+ *   will be assigned to the instance's `deprecatedID`.
+ *
+ * - If applicable, a new instance id will be assigned:
+ *
+ *     - If the instance has an `instanceID` metadata element, and the form
+ *       explicitly defines a
+ *       {@link https://getodk.github.io/xforms-spec/#preload-attributes | `uid` preload attribute}
+ *       for its model binding, a new instance id value will be assigned to that
+ *       element _as if it were the
+ *       {@link https://getodk.github.io/xforms-spec/#event:odk-instance-first-load | instance's first load}_.
+ *
+ *     - **Consistent with {@link FormInstanceCreateMode | instance creation}:**
+ *       if the form **DOES NOT** define an `instanceID` element or model
+ *       binding, the `uid` preload behavior described above is **implied** as
+ *       the form's default behavior for that metadata; in which case whether
+ *       the instance defines an `instanceID` element explicitly or not, it will
+ *       be treated as if it had, behaving as described in the point above.
+ *
+ * **NOTE:** the behavior for an instance's `instanceID` metadata element and a
+ * form's `uid` preload attribute describe a special case, applying only to that
+ * specific preload attribute. In other words, when initializing instance state
+ * for editing:
+ *
+ * - The `odk-instance-first-load` event itself will **NOT** be triggered
+ * - Preload attributes _other than `uid`_ will **NOT** be recomputed
+ *
+ * **NOTE:** while the `uid` preload attribute is discussed above in terms of
+ * the `instanceID` meta element, its behavior is not applied specially to any
+ * particular node, regardless of
+ * {@link FormInstanceInitializationMode | initialization mode}.
+ */
+export type FormInstanceEditMode = 'edit';
+export type FormInstanceInitializationMode = FormInstanceCreateMode | FormInstanceEditMode | FormInstanceRestoreMode;
+/**
+ * @todo this could hypothetically convey warnings and/or errors, just as
+ * {@link LoadFormResult} does. This has been deferred because:
+ *
+ * - We really want a more thoughtful design for Result types
+ * - The `try`/`catch` approach to capturing all errors takes a huge performance
+ *   hit, which we should not incur if we have a more thoughtful design coming
+ *   eventually. It would be too easy to forget about, indefinitely!
+ */
+export interface FormInstance<Mode extends FormInstanceInitializationMode> {
+    readonly formResult: InstantiableLoadFormResult;
+    readonly mode: Mode;
+    readonly root: RootNode;
+}
+export type AnyFormInstance = {
+    [Mode in FormInstanceInitializationMode]: FormInstance<Mode>;
+}[FormInstanceInitializationMode];

package/dist/client/form/FormInstanceConfig.d.ts

@@ -0,0 +1,17 @@
+import { OpaqueReactiveObjectFactory } from '../OpaqueReactiveObjectFactory.ts';
+export interface FormInstanceConfig {
+    /**
+     * A client may specify a generic function for constructing stateful objects.
+     * The only hard requirement of this function is that it accepts an **object**
+     * and returns an object of the same shape. The engine will use this function
+     * to initialize client-facing state, and will mutate properties of the object
+     * when their corresponding state is changed.
+     *
+     * A client may use this function to provide its own implementation of
+     * reactivity with semantics like those described above. The mechanism of
+     * reactivity, if any, is at the discretion of the client. It is expected that
+     * clients providing this function will use a reactive subscribe-on-read
+     * mechanism to handle state updates conveyed by the engine.
+     */
+    readonly stateFactory?: OpaqueReactiveObjectFactory;
+}

package/dist/client/form/FormResource.d.ts

@@ -0,0 +1 @@
+export type FormResource = Blob | File | URL | string;

package/dist/client/form/LoadForm.d.ts

@@ -0,0 +1,79 @@
+import { MissingResourceBehavior } from '../constants.ts';
+import { FetchFormAttachment, FetchResource } from '../resources.ts';
+import { FormResource } from './FormResource.ts';
+import { LoadFormResult } from './LoadFormResult.ts';
+/**
+ * @see {@link LoadForm}
+ */
+export interface FormLoadPromise<T> extends PromiseLike<T> {
+}
+/**
+ * Any fetch-like {@link LoadFormOptions | form loading options} which are not
+ * provided will default to the global {@link fetch} function, if one is
+ * available in the calling environment. If a global {@link fetch} function is
+ * _is not available_, and if the associated form loading option is required for
+ * the provided {@link FormResource} to be loaded, a
+ * {@link LoadFormFailureResult} will be produced.
+ */
+export type GlobalFetchDefault = typeof fetch;
+export interface LoadFormOptions {
+    /**
+     * A client may specify an arbitrary {@link fetch}-like function for
+     * retrieving an XML XForm form definition.
+     *
+     * Calls to {@link loadForm | load a form} from a form definition provided as
+     * either a raw XML string or {@link Blob} data containing an XML string, this
+     * option will be ignored.
+     *
+     * Calls to load a form by {@link URL} will consult this option, if defined.
+     *
+     * If this option is omitted, loading a form by URL will use the
+     * {@link GlobalFetchDefault | global fetch function} by default.
+     */
+    readonly fetchFormDefinition?: FetchResource;
+    /**
+     * A client may specify an arbitrary {@link fetch}-like function to retrieve a
+     * form's attachments, i.e. any `jr:` URL referenced by the form (as specified
+     * by {@link https://getodk.github.io/xforms-spec/ | ODK XForms}).
+     *
+     * As part of {@link loadForm | loading a form}, once the form definition
+     * itself is resolved, this option (if provided) will be consulted to load any
+     * form attachments referenced by the form definition.
+     *
+     * If this option is omitted, the engine will attempt to load form attachments
+     * by calling the {@link GlobalFetchDefault | global fetch function} with each
+     * attachment's `jr:` URL. This default behavior will typically result in
+     * failure to load form attachments—and in most cases this will in most cases
+     * cause {@link loadForm | loading a form} to produce a
+     * {@link LoadFormFailureResult}, with the following exception:
+     *
+     * Clients implementing a
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API | Service Worker}
+     * (e.g. supporting offline functionality, or any other use case for
+     * intercepting network requests) may opt for the convenience of handling
+     * network requests _for form attachments' `jr:` URLs_ along with any other
+     * network interception logic. Client implementors should be warned, however,
+     * that such `jr:` URLs are not namespaced or otherwise scoped to a particular
+     * form definition! Such a client would therefore inherently need to
+     * coordinate state between the Service Worker and the main thread (or
+     * whatever other realm calls {@link loadForm}).
+     *
+     * @todo We can almost certainly address the scoping caveat! We'll probably
+     * want to design for that as part of offline support.
+     */
+    readonly fetchFormAttachment?: FetchFormAttachment;
+    /**
+     * @see {@link MissingResourceBehavior}
+     * @see {@link MissingResourceBehaviorDefault}
+     *
+     * @default MissingResourceBehaviorDefault
+     */
+    readonly missingResourceBehavior?: MissingResourceBehavior;
+}
+/**
+ * Note: loading a form produce a {@link Promise} which **will never reject**.
+ * Rather than rejecting, any errors encountered in the process of loading a
+ * form will be **resolved**, in a
+ * {@link LoadFormFailureResult.error | FormLoadFailureResult error}.
+ */
+export type LoadForm = (formResource: FormResource, options?: LoadFormOptions) => FormLoadPromise<LoadFormResult>;

package/dist/client/form/LoadFormResult.d.ts

@@ -0,0 +1,67 @@
+import { UnknownObject } from '../../../../common/src/lib/type-assertions/assertUnknownObject.ts';
+import { AnyFunction } from '../../../../common/types/helpers.js';
+import { LoadFormFailureError } from '../../error/LoadFormFailureError.ts';
+import { CreateFormInstance } from './CreateFormInstance.ts';
+import { EditFormInstance } from './EditFormInstance.ts';
+import { RestoreFormInstance } from './RestoreFormInstance.ts';
+export type { LoadFormFailureError };
+export type FormResultStatus = 'success' | 'warning' | 'failure';
+/**
+ * @todo Pending design and modeling of warning cases.
+ */
+export type LoadFormWarnings = UnknownObject;
+type FailedLoadFormResultMethodParameters<T extends AnyFunction> = readonly never[] & (Parameters<T> extends {
+    readonly length: infer Length extends number;
+} ? {
+    readonly length: Length;
+} : never);
+export type FailedLoadFormResultMethod<T extends AnyFunction> = (...args: FailedLoadFormResultMethodParameters<T>) => never;
+export type FallibleLoadFormResultMethod<T extends AnyFunction> = T | FailedLoadFormResultMethod<T>;
+interface BaseLoadFormResult {
+    readonly status: FormResultStatus;
+    readonly warnings: LoadFormWarnings | null;
+    readonly error: LoadFormFailureError | null;
+    readonly createInstance: FallibleLoadFormResultMethod<CreateFormInstance>;
+    readonly editInstance: FallibleLoadFormResultMethod<EditFormInstance>;
+    readonly restoreInstance: FallibleLoadFormResultMethod<RestoreFormInstance>;
+}
+export interface LoadFormSuccessResult extends BaseLoadFormResult {
+    readonly status: 'success';
+    readonly warnings: null;
+    readonly error: null;
+    readonly createInstance: CreateFormInstance;
+    readonly editInstance: EditFormInstance;
+    readonly restoreInstance: RestoreFormInstance;
+}
+export interface LoadFormWarningResult extends BaseLoadFormResult {
+    readonly status: 'warning';
+    readonly warnings: LoadFormWarnings;
+    readonly error: null;
+    readonly createInstance: CreateFormInstance;
+    readonly editInstance: EditFormInstance;
+    readonly restoreInstance: RestoreFormInstance;
+}
+export interface LoadFormFailureResult extends BaseLoadFormResult {
+    readonly status: 'failure';
+    readonly warnings: LoadFormWarnings | null;
+    readonly error: LoadFormFailureError;
+    /**
+     * @example A temporary demo integration was built during development of this
+     * interface.
+     *
+     * @see
+     * {@link https://github.com/getodk/web-forms/pull/345/commits/9ef36355d89dd1450d3a87c3a55506bb9b0fc414}
+     */
+    readonly createInstance: FailedLoadFormResultMethod<CreateFormInstance>;
+    readonly editInstance: FailedLoadFormResultMethod<EditFormInstance>;
+    /**
+     * @example A temporary demo integration was built during development of this
+     * interface.
+     *
+     * @see
+     * {@link https://github.com/getodk/web-forms/pull/345/commits/9ef36355d89dd1450d3a87c3a55506bb9b0fc414}
+     */
+    readonly restoreInstance: FailedLoadFormResultMethod<RestoreFormInstance>;
+}
+export type InstantiableLoadFormResult = LoadFormSuccessResult | LoadFormWarningResult;
+export type LoadFormResult = InstantiableLoadFormResult | LoadFormFailureResult;

package/dist/client/form/RestoreFormInstance.d.ts

@@ -0,0 +1,8 @@
+import { InstanceData } from '../serialization/InstanceData.ts';
+import { FormInstance, FormInstanceRestoreMode } from './FormInstance.ts';
+import { FormInstanceConfig } from './FormInstanceConfig.ts';
+export interface RestoreFormInstanceInput {
+    readonly data: readonly [InstanceData, ...InstanceData[]];
+}
+export type RestoredFormInstance = FormInstance<FormInstanceRestoreMode>;
+export type RestoreFormInstance = (input: RestoreFormInstanceInput, config?: FormInstanceConfig) => Promise<RestoredFormInstance>;

package/dist/client/hierarchy.d.ts

@@ -2,7 +2,8 @@ import { ExpandUnion } from '../../../common/types/helpers.d.ts';
 import { GroupNode } from './GroupNode.ts';
 import { AnyInputNode } from './InputNode.ts';
 import { AnyModelValueNode } from './ModelValueNode.ts';
-import { NoteNode } from './NoteNode.ts';
+import { AnyNoteNode } from './NoteNode.ts';
+import { AnyRangeNode } from './RangeNode.ts';
 import { RepeatInstanceNode } from './repeat/RepeatInstanceNode.ts';
 import { RepeatRangeControlledNode } from './repeat/RepeatRangeControlledNode.ts';
 import { RepeatRangeUncontrolledNode } from './repeat/RepeatRangeUncontrolledNode.ts';
@@ -10,11 +11,10 @@ import { RootNode } from './RootNode.ts';
 import { SelectNode } from './SelectNode.ts';
 import { SubtreeNode } from './SubtreeNode.ts';
 import { TriggerNode } from './TriggerNode.ts';
-import { RangeNode } from './unsupported/RangeNode.ts';
-import { RankNode } from './unsupported/RankNode.ts';
+import { RankNode } from './RankNode.ts';
 import { UploadNode } from './unsupported/UploadNode.ts';
-export type AnyUnsupportedControlNode = RangeNode | RankNode | UploadNode;
-export type AnyControlNode = AnyInputNode | NoteNode | SelectNode | TriggerNode;
+export type AnyUnsupportedControlNode = UploadNode;
+export type AnyControlNode = AnyInputNode | AnyNoteNode | AnyRangeNode | RankNode | SelectNode | TriggerNode;
 export type AnyLeafNode = AnyControlNode | AnyModelValueNode | AnyUnsupportedControlNode;
 export type RepeatRangeNode = RepeatRangeControlledNode | RepeatRangeUncontrolledNode;
 /**

package/dist/client/index.d.ts

@@ -1,11 +1,37 @@
-import { EngineConfig } from './EngineConfig.ts';
-import { RootNode } from './RootNode.ts';
-export type FormResource = Blob | URL | string;
-export interface InitializeFormOptions {
-    readonly config: EngineConfig;
-    readonly initialState?: FormResource;
-}
-/**
- * Creates an instance of a form to be filled (or edited) by a client.
- */
-export type InitializeForm = (input: FormResource, options?: InitializeFormOptions) => Promise<RootNode>;
+export type * from './constants.ts';
+export * as constants from './constants.ts';
+export type * from './form/CreateFormInstance.ts';
+export type * from './form/EditFormInstance.ts';
+export type * from './form/FormInstance.ts';
+export type * from './form/FormInstanceConfig.ts';
+export type * from './form/FormResource.ts';
+export type * from './form/LoadForm.ts';
+export type * from './form/LoadFormResult.ts';
+export type * from './form/RestoreFormInstance.ts';
+export type * from './FormLanguage.ts';
+export type * from './GroupNode.ts';
+export type { AnyChildNode, AnyControlNode, AnyLeafNode, AnyNode, AnyParentNode, AnyUnsupportedControlNode, GeneralChildNode, GeneralParentNode, RepeatRangeNode, } from './hierarchy.ts';
+export type * from './InputNode.ts';
+export type * from './ModelValueNode.ts';
+export type * from './NoteNode.ts';
+export type * from './OpaqueReactiveObjectFactory.ts';
+export type * from './RangeNode.ts';
+export type * from './RankNode.ts';
+export type * from './repeat/RepeatInstanceNode.ts';
+export type * from './repeat/RepeatRangeControlledNode.ts';
+export type * from './repeat/RepeatRangeUncontrolledNode.ts';
+export type * from './resources.ts';
+export type * from './RootNode.ts';
+export type * from './SelectNode.ts';
+export type * from './serialization/InstanceData.ts';
+export type * from './serialization/InstanceFile.ts';
+export type * from './serialization/InstancePayload.ts';
+export type * from './serialization/InstancePayloadOptions.ts';
+export type * from './serialization/InstanceState.ts';
+export type * from './submission/SubmissionMeta.ts';
+export type * from './SubtreeNode.ts';
+export type * from './TextRange.ts';
+export type * from './TriggerNode.ts';
+export type * from './unsupported/UploadNode.ts';
+export type * from './validation.ts';
+export type * from './ValueType.ts';

package/dist/client/node-types.d.ts

@@ -1,4 +1,4 @@
-export type UnsupportedControlNodeType = 'range' | 'rank' | 'upload';
+export type UnsupportedControlNodeType = 'upload';
 export type RepeatRangeNodeType = 'repeat-range:controlled' | 'repeat-range:uncontrolled';
-export type LeafNodeType = 'model-value' | 'note' | 'select' | 'input' | 'trigger' | UnsupportedControlNodeType;
+export type LeafNodeType = 'model-value' | 'note' | 'select' | 'input' | 'trigger' | 'range' | 'rank' | UnsupportedControlNodeType;
 export type InstanceNodeType = 'root' | RepeatRangeNodeType | 'repeat-instance' | 'group' | 'subtree' | LeafNodeType | UnsupportedControlNodeType;

package/dist/client/repeat/BaseRepeatRangeNode.d.ts

@@ -1,4 +1,3 @@
-import { AnyRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
 import { BaseNode, BaseNodeState } from '../BaseNode.ts';
 import { NodeAppearances } from '../NodeAppearances.ts';
 import { RootNode } from '../RootNode.ts';
@@ -6,7 +5,7 @@ import { TextRange } from '../TextRange.ts';
 import { GeneralParentNode } from '../hierarchy.ts';
 import { RepeatRangeNodeType } from '../node-types.ts';
 import { AncestorNodeValidationState } from '../validation.ts';
-import { RepeatInstanceNode } from './RepeatInstanceNode.ts';
+import { AnyRepeatDefinition, RepeatInstanceNode } from './RepeatInstanceNode.ts';
 export interface BaseRepeatRangeNodeState extends BaseNodeState {
     get hint(): null;
     get label(): TextRange<'label'> | null;
@@ -22,7 +21,7 @@ export interface BaseRepeatRangeNodeState extends BaseNodeState {
     get valueOptions(): null;
     get value(): null;
 }
-export type RepeatRangeNodeAppearances = NodeAppearances<AnyRepeatRangeDefinition>;
+export type RepeatRangeNodeAppearances = NodeAppearances<AnyRepeatDefinition>;
 /**
  * Represents a contiguous set of zero or more {@link RepeatInstanceNode}s
  * (accessed by its
@@ -90,7 +89,7 @@ export type RepeatRangeNodeAppearances = NodeAppearances<AnyRepeatRangeDefinitio
 export interface BaseRepeatRangeNode extends BaseNode {
     readonly nodeType: RepeatRangeNodeType;
     readonly appearances: RepeatRangeNodeAppearances;
-    readonly definition: AnyRepeatRangeDefinition;
+    readonly definition: AnyRepeatDefinition;
     readonly root: RootNode;
     readonly parent: GeneralParentNode;
     readonly currentState: BaseRepeatRangeNodeState;

package/dist/client/repeat/RepeatInstanceNode.d.ts

@@ -1,5 +1,4 @@
-import { RepeatInstanceDefinition } from '../../parse/model/RepeatInstanceDefinition.ts';
-import { RepeatTemplateDefinition } from '../../parse/model/RepeatTemplateDefinition.ts';
+import { AnyRepeatDefinition } from '../../parse/model/RepeatDefinition.ts';
 import { BaseNode, BaseNodeState } from '../BaseNode.ts';
 import { GeneralChildNode, RepeatRangeNode } from '../hierarchy.ts';
 import { NodeAppearances } from '../NodeAppearances.ts';
@@ -11,12 +10,12 @@ export interface RepeatInstanceNodeState extends BaseNodeState {
     get valueOptions(): null;
     get value(): null;
 }
-export type RepeatDefinition = RepeatInstanceDefinition | RepeatTemplateDefinition;
-export type RepeatInstanceNodeAppearances = NodeAppearances<RepeatDefinition>;
+export type { AnyRepeatDefinition };
+export type RepeatInstanceNodeAppearances = NodeAppearances<AnyRepeatDefinition>;
 export interface RepeatInstanceNode extends BaseNode {
     readonly nodeType: 'repeat-instance';
     readonly appearances: RepeatInstanceNodeAppearances;
-    readonly definition: RepeatDefinition;
+    readonly definition: AnyRepeatDefinition;
     readonly root: RootNode;
     /**
      * A repeat instance may only be a child of a {@link RepeatRangeNode}.

package/dist/client/repeat/RepeatRangeControlledNode.d.ts

@@ -1,4 +1,4 @@
-import { ControlledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import { ControlledRepeatDefinition } from '../../parse/model/RepeatDefinition.ts';
 import { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.ts';
 /**
  * {@inheritDoc BaseRepeatRangeNodeState}
@@ -14,5 +14,5 @@ export interface RepeatRangeControlledState extends BaseRepeatRangeNodeState {
  */
 export interface RepeatRangeControlledNode extends BaseRepeatRangeNode {
     readonly nodeType: 'repeat-range:controlled';
-    readonly definition: ControlledRepeatRangeDefinition;
+    readonly definition: ControlledRepeatDefinition;
 }

package/dist/client/repeat/RepeatRangeUncontrolledNode.d.ts

@@ -1,4 +1,4 @@
-import { UncontrolledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import { UncontrolledRepeatDefinition } from '../../parse/model/RepeatDefinition.ts';
 import { RootNode } from '../RootNode.ts';
 import { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.ts';
 /**
@@ -13,7 +13,7 @@ export interface RepeatRangeUncontrolledState extends BaseRepeatRangeNodeState {
  */
 export interface RepeatRangeUncontrolledNode extends BaseRepeatRangeNode {
     readonly nodeType: 'repeat-range:uncontrolled';
-    readonly definition: UncontrolledRepeatRangeDefinition;
+    readonly definition: UncontrolledRepeatDefinition;
     addInstances(afterIndex?: number, count?: number): RootNode;
     removeInstances(startIndex: number, count?: number): RootNode;
 }

package/dist/client/resources.d.ts

@@ -65,7 +65,7 @@ export interface FetchResourceResponseHeaders {
  *
  * Furthermore, if the engine intends to read {@link body} (or its indirect
  * {@link blob} or {@link text} consumers), it will do so in the course of a
- * client's call to {@link initializeForm}, and before the
+ * client's call to {@link loadForm}, and before the
  * {@link Promise<PrimaryInstance>} returned by that call is resolved.
  */
 export interface FetchResourceResponse {

package/dist/client/serialization/InstanceData.d.ts

@@ -0,0 +1,12 @@
+import { INSTANCE_FILE_NAME, InstanceFile } from './InstanceFile.ts';
+export type InstanceAttachmentFileName = string;
+export interface InstanceData extends FormData {
+    get(name: INSTANCE_FILE_NAME): InstanceFile;
+    /**
+     * @todo Can we guarantee (both in static types and at runtime) that
+     * {@link InstanceData} only contains files?
+     */
+    get(name: InstanceAttachmentFileName): FormDataEntryValue | null;
+    has(name: INSTANCE_FILE_NAME): true;
+    has(name: InstanceAttachmentFileName): boolean;
+}

package/dist/client/serialization/InstanceFile.d.ts

@@ -0,0 +1,6 @@
+import { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE } from '../constants.ts';
+export type { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE };
+export interface InstanceFile extends File {
+    readonly name: INSTANCE_FILE_NAME;
+    readonly type: INSTANCE_FILE_TYPE;
+}

package/dist/client/serialization/InstancePayload.d.ts

@@ -0,0 +1,93 @@
+import { SubmissionMeta } from '../submission/SubmissionMeta.ts';
+import { DescendantNodeViolationReference } from '../validation.ts';
+import { InstanceData } from './InstanceData.ts';
+import { InstancePayloadType } from './InstancePayloadOptions.ts';
+export type InstancePayloadStatus = 'pending' | 'max-size-exceeded' | 'ready';
+type InstancePayloadData<PayloadType extends InstancePayloadType> = {
+    chunked: readonly [InstanceData, ...InstanceData[]];
+    monolithic: readonly [InstanceData];
+}[PayloadType];
+/**
+ * Provides detail about an individual instance attachment {@link File}s which
+ * exceeds the client-specified {@link maxSize} for a
+ * {@link ChunkedInstancePayload | chunked instance payload}. Clients may use
+ * this value to provide guidance to users.
+ *
+ * @todo We may want to consider (a) making {@link maxSize} a configuration the
+ * client can provide when initializing a form instance, rather than only when
+ * serializing an instance payload; and then (b) treating a maximum size
+ * violation as another kind of node-level violation. This would go beyond the
+ * kinds of validation specified by ODK XForms, but it would make a lot of
+ * _conceptual sense_.
+ *
+ * It would almost certainly be helpful to alert users to violations as the
+ * occur, rather than only at instance payload serialization time (where they
+ * have likely already moved on). This is something clients can do without
+ * engine support, but it would likely promote good usability patterns if the
+ * engine makes it an obvious and uniform option at the main engine/client
+ * entrypoint.
+ *
+ * @todo If we consider the above, we'd want to reframe _this interface_ to
+ * match the shape of other {@link AnyViolation | violations} (adding it as a
+ * member of that union). We'd also likely eliminate
+ * {@link MaxSizeExceededResult} in the process, since
+ * {@link PendingInstancePayload} would then cover the case.
+ */
+interface MaxSizeViolation {
+    /**
+     * Specifies the index of
+     * {@link InstancePayloadData<'chunked'> | chunked instance payload data}
+     * where an instance attachment {@link File} exceeds the client-specified
+     * {@link maxSize}.
+     */
+    readonly dataIndex: number;
+    /**
+     * Specifies the name of the file which exceeds the client-specified
+     * {@link maxSize}. This name can also be used as a key to access the
+     * violating {@link File}/instance attachment, in the {@link InstanceData} at
+     * the specified {@link dataIndex}.
+     */
+    readonly fileName: string;
+    /**
+     * Reflects the client-specified maximum size for each chunk of a
+     * {@link ChunkedInstancePayload | chunked instance payload}.
+     */
+    readonly maxSize: number;
+    /**
+     * Details the actual size of the violating {@link File}/instance attachment.
+     * Along with {@link maxSize}. Clients may use the delta between this value
+     * and {@link maxSize} to provide detailed guidance to users.
+     */
+    readonly actualSize: number;
+}
+type InstancePayloadViolation = DescendantNodeViolationReference | MaxSizeViolation;
+interface BaseInstancePayload<PayloadType extends InstancePayloadType> {
+    readonly payloadType: PayloadType;
+    readonly status: InstancePayloadStatus;
+    readonly submissionMeta: SubmissionMeta;
+    get violations(): readonly InstancePayloadViolation[] | null;
+    /**
+     * Instance attachment data may be chunked according to the
+     * {@link InstancePayloadOptions.maxSize | maxSize instance payload option}
+     */
+    readonly data: InstancePayloadData<PayloadType>;
+}
+interface PendingInstancePayload<PayloadType extends InstancePayloadType> extends BaseInstancePayload<PayloadType> {
+    readonly status: 'pending';
+    get violations(): readonly DescendantNodeViolationReference[];
+}
+interface MaxSizeExceededResult extends BaseInstancePayload<'chunked'> {
+    readonly status: 'max-size-exceeded';
+    get violations(): readonly MaxSizeViolation[];
+}
+interface ReadyInstancePayload<PayloadType extends InstancePayloadType> extends BaseInstancePayload<PayloadType> {
+    readonly status: 'ready';
+    get violations(): null;
+}
+export type ChunkedInstancePayload = MaxSizeExceededResult | PendingInstancePayload<'chunked'> | ReadyInstancePayload<'chunked'>;
+export type MonolithicInstancePayload = PendingInstancePayload<'monolithic'> | ReadyInstancePayload<'monolithic'>;
+export type InstancePayload<PayloadType extends InstancePayloadType> = {
+    chunked: ChunkedInstancePayload;
+    monolithic: MonolithicInstancePayload;
+}[PayloadType];
+export {};