@getodk/xforms-engine 0.6.0 → 0.8.0

package/src/client/form/LoadForm.ts

@@ -0,0 +1,92 @@
+import type { loadForm } from '../../entrypoints/loadForm.ts';
+import type { MissingResourceBehavior } from '../constants.ts';
+import type { FetchFormAttachment, FetchResource } from '../resources.ts';
+import type { FormResource } from './FormResource.ts';
+import type { LoadFormFailureResult, 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.
+	 */
+	// TODO (internal): Also note that the current round of revisions to
+	// engine/client entrypoints are not directly designed to address the above
+	// `@todo`, but the offline use case in particular is very much in mind for
+	// these interface changes!
+	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/src/client/form/LoadFormResult.ts

@@ -0,0 +1,103 @@
+import type { UnknownObject } from '@getodk/common/lib/type-assertions/assertUnknownObject.ts';
+import type { AnyFunction } from '@getodk/common/types/helpers.js';
+import type { LoadFormFailureError } from '../../error/LoadFormFailureError.ts';
+import type { CreateFormInstance } from './CreateFormInstance.ts';
+import type { EditFormInstance } from './EditFormInstance.ts';
+import type { RestoreFormInstance } from './RestoreFormInstance.ts';
+
+// Re-export for client access
+export type { LoadFormFailureError };
+
+// prettier-ignore
+export type FormResultStatus =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'success'
+	| 'warning'
+	| 'failure';
+
+/**
+ * @todo Pending design and modeling of warning cases.
+ */
+export type LoadFormWarnings = UnknownObject;
+
+// prettier-ignore
+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;
+
+// prettier-ignore
+export type FallibleLoadFormResultMethod<T extends AnyFunction> =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 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>;
+}
+
+// prettier-ignore
+export type InstantiableLoadFormResult =
+	| LoadFormSuccessResult
+	| LoadFormWarningResult
+
+// prettier-ignore
+export type LoadFormResult =
+	| InstantiableLoadFormResult
+	| LoadFormFailureResult;

package/src/client/form/RestoreFormInstance.ts

@@ -0,0 +1,14 @@
+import type { InstanceData } from '../serialization/InstanceData.ts';
+import type { FormInstance, FormInstanceRestoreMode } from './FormInstance.ts';
+import type { 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/src/client/hierarchy.ts

@@ -4,6 +4,7 @@ import type { AnyInputNode } from './InputNode.ts';
 import type { AnyModelValueNode } from './ModelValueNode.ts';
 import type { AnyNoteNode } from './NoteNode.ts';
 import type { AnyRangeNode } from './RangeNode.ts';
+import type { RankNode } from './RankNode.ts';
 import type { RepeatInstanceNode } from './repeat/RepeatInstanceNode.ts';
 import type { RepeatRangeControlledNode } from './repeat/RepeatRangeControlledNode.ts';
 import type { RepeatRangeUncontrolledNode } from './repeat/RepeatRangeUncontrolledNode.ts';
@@ -11,11 +12,7 @@ import type { RootNode } from './RootNode.ts';
 import type { SelectNode } from './SelectNode.ts';
 import type { SubtreeNode } from './SubtreeNode.ts';
 import type { TriggerNode } from './TriggerNode.ts';
-import type { RankNode } from './RankNode.ts';
-import type { UploadNode } from './unsupported/UploadNode.ts';
-
-// prettier-ignore
-export type AnyUnsupportedControlNode = UploadNode;
+import type { UploadNode } from './UploadNode.ts';
 
 // prettier-ignore
 export type AnyControlNode =
@@ -24,13 +21,13 @@ export type AnyControlNode =
 	| AnyRangeNode
 	| RankNode
 	| SelectNode
-	| TriggerNode;
+	| TriggerNode
+	| UploadNode;
 
 // prettier-ignore
 export type AnyLeafNode =
 	| AnyControlNode
-	| AnyModelValueNode
-	| AnyUnsupportedControlNode;
+	| AnyModelValueNode;
 
 // prettier-ignore
 export type RepeatRangeNode =

package/src/client/index.ts

@@ -1,29 +1,49 @@
-import type { EngineConfig } from './EngineConfig.ts';
-import type { RootNode } from './RootNode.ts';
-
-export type FormResource = Blob | URL | string;
-
-export interface InitializeFormOptions {
-	readonly config: EngineConfig;
-
-	// E.g. opening a submitted form instance for edit. TDOO: the `FormResource`
-	// name is shared here for both init input and initial state, but the shape of
-	// those resources would differ. Probably a more generic name is appropriate.
-	readonly initialState?: FormResource;
-}
-
-/**
- * Creates an instance of a form to be filled (or edited) by a client.
- */
-// TODO: initialization is represented as asynchronous here, so that any
-// requisite resources can be retrieved before passing control to a client. This
-// is an obvious first step, but we can consider a more complex (if optional)
-// flow, e.g.:
-//
-// - Where it can be determined upfront that the form has no need to perform IO
-// - Where the IO may have already been performed (e.g. offline, other potential
-//   caching cases where appropriate)
-export type InitializeForm = (
-	input: FormResource,
-	options?: InitializeFormOptions
-) => Promise<RootNode>;
+export type * from './attachments/InstanceAttachmentMeta.ts';
+export type * from './attachments/InstanceAttachmentsConfig.ts';
+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,
+	GeneralChildNode,
+	GeneralParentNode,
+	RepeatRangeNode,
+} from './hierarchy.ts';
+export type * from './identity.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 './UploadNode.ts';
+export type * from './validation.ts';
+export type * from './ValueType.ts';

package/src/client/node-types.ts

@@ -1,8 +1,3 @@
-// prettier-ignore
-export type UnsupportedControlNodeType =
-	| 'rank'
-	| 'upload';
-
 // prettier-ignore
 export type RepeatRangeNodeType =
 	| 'repeat-range:controlled'
@@ -17,7 +12,8 @@ export type LeafNodeType =
 	| 'input'
 	| 'trigger'
 	| 'range'
-	| UnsupportedControlNodeType;
+	| 'rank'
+	| 'upload';
 
 // prettier-ignore
 export type InstanceNodeType =
@@ -27,5 +23,4 @@ export type InstanceNodeType =
 	| 'repeat-instance'
 	| 'group'
 	| 'subtree'
-	| LeafNodeType
-	| UnsupportedControlNodeType;
+	| LeafNodeType;

package/src/client/repeat/BaseRepeatRangeNode.ts

@@ -1,4 +1,3 @@
-import type { AnyRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
 import type { BaseNode, BaseNodeState } from '../BaseNode.ts';
 import type { NodeAppearances } from '../NodeAppearances.ts';
 import type { RootNode } from '../RootNode.ts';
@@ -6,7 +5,7 @@ import type { TextRange } from '../TextRange.ts';
 import type { GeneralParentNode } from '../hierarchy.ts';
 import type { RepeatRangeNodeType } from '../node-types.ts';
 import type { AncestorNodeValidationState } from '../validation.ts';
-import type { RepeatInstanceNode } from './RepeatInstanceNode.ts';
+import type { AnyRepeatDefinition, RepeatInstanceNode } from './RepeatInstanceNode.ts';
 
 export interface BaseRepeatRangeNodeState extends BaseNodeState {
 	get hint(): null;
@@ -26,7 +25,7 @@ export interface BaseRepeatRangeNodeState extends BaseNodeState {
 	get value(): null;
 }
 
-export type RepeatRangeNodeAppearances = NodeAppearances<AnyRepeatRangeDefinition>;
+export type RepeatRangeNodeAppearances = NodeAppearances<AnyRepeatDefinition>;
 
 /**
  * Represents a contiguous set of zero or more {@link RepeatInstanceNode}s
@@ -95,7 +94,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/src/client/repeat/RepeatInstanceNode.ts

@@ -1,5 +1,4 @@
-import type { RepeatInstanceDefinition } from '../../parse/model/RepeatInstanceDefinition.ts';
-import type { RepeatTemplateDefinition } from '../../parse/model/RepeatTemplateDefinition.ts';
+import type { AnyRepeatDefinition } from '../../parse/model/RepeatDefinition.ts';
 import type { BaseNode, BaseNodeState } from '../BaseNode.ts';
 import type { GeneralChildNode, RepeatRangeNode } from '../hierarchy.ts';
 import type { NodeAppearances } from '../NodeAppearances.ts';
@@ -19,17 +18,14 @@ export interface RepeatInstanceNodeState extends BaseNodeState {
 	get value(): null;
 }
 
-// prettier-ignore
-export type RepeatDefinition =
-	| RepeatInstanceDefinition
-	| RepeatTemplateDefinition;
+export type { AnyRepeatDefinition };
 
-export type RepeatInstanceNodeAppearances = NodeAppearances<RepeatDefinition>;
+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;
 
 	/**

package/src/client/repeat/RepeatRangeControlledNode.ts

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

package/src/client/repeat/RepeatRangeUncontrolledNode.ts

@@ -1,4 +1,4 @@
-import type { UncontrolledRepeatRangeDefinition } from '../../parse/model/RepeatRangeDefinition.ts';
+import type { UncontrolledRepeatDefinition } from '../../parse/model/RepeatDefinition.ts';
 import type { RootNode } from '../RootNode.ts';
 import type { BaseRepeatRangeNode, BaseRepeatRangeNodeState } from './BaseRepeatRangeNode.ts';
 
@@ -14,7 +14,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/src/client/resources.ts

@@ -1,5 +1,5 @@
 import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
-import type { initializeForm } from '../instance/index.ts';
+import type { loadForm } from '../entrypoints/loadForm.ts';
 
 interface FetchResourceHeadersIterator<T>
 	extends IteratorObject<
@@ -85,7 +85,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/src/client/serialization/InstanceData.ts

@@ -0,0 +1,24 @@
+import type { INSTANCE_FILE_NAME, InstanceFile } from './InstanceFile.ts';
+
+export type InstanceAttachmentFileName = string;
+
+export type InstanceDataEntryValue = File;
+
+export interface InstanceData extends FormData {
+	[Symbol.iterator](): FormDataIterator<[string, InstanceDataEntryValue]>;
+	entries(): FormDataIterator<[string, InstanceDataEntryValue]>;
+	values(): FormDataIterator<InstanceDataEntryValue>;
+
+	forEach(
+		callbackfn: (value: InstanceDataEntryValue, key: string, parent: InstanceData) => void,
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		thisArg?: any
+	): void;
+
+	get(name: INSTANCE_FILE_NAME): InstanceFile;
+	get(name: InstanceAttachmentFileName): InstanceDataEntryValue | null;
+	getAll(name: string): InstanceDataEntryValue[];
+
+	has(name: INSTANCE_FILE_NAME): true;
+	has(name: InstanceAttachmentFileName): boolean;
+}

package/src/client/serialization/InstanceFile.ts

@@ -0,0 +1,9 @@
+import type { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE } from '../constants.ts';
+
+// Re-export for convenient `InstanceFile` construction/access flows
+export type { INSTANCE_FILE_NAME, INSTANCE_FILE_TYPE };
+
+export interface InstanceFile extends File {
+	readonly name: INSTANCE_FILE_NAME;
+	readonly type: INSTANCE_FILE_TYPE;
+}

package/src/client/serialization/InstancePayload.ts

@@ -0,0 +1,126 @@
+import type { SubmissionMeta } from '../submission/SubmissionMeta.ts';
+import type { AnyViolation, DescendantNodeViolationReference } from '../validation.ts';
+import type { InstanceData } from './InstanceData.ts';
+import type { InstancePayloadOptions, InstancePayloadType } from './InstancePayloadOptions.ts';
+
+// prettier-ignore
+export type InstancePayloadStatus =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| 'pending'
+	| 'max-size-exceeded'
+	| 'ready';
+
+// prettier-ignore
+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;
+}
+
+// prettier-ignore
+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;
+}
+
+// prettier-ignore
+export type ChunkedInstancePayload =
+	| MaxSizeExceededResult
+	| PendingInstancePayload<'chunked'>
+	| ReadyInstancePayload<'chunked'>;
+
+export type MonolithicInstancePayload =
+	| PendingInstancePayload<'monolithic'>
+	| ReadyInstancePayload<'monolithic'>;
+
+// prettier-ignore
+export type InstancePayload<PayloadType extends InstancePayloadType> = {
+	chunked: ChunkedInstancePayload;
+	monolithic: MonolithicInstancePayload;
+}[PayloadType];

package/src/client/serialization/InstancePayloadOptions.ts

@@ -0,0 +1,29 @@
+export type InstancePayloadType = 'chunked' | 'monolithic';
+
+interface BaseInstancePayloadOptions<PayloadType extends InstancePayloadType> {
+	readonly payloadType: PayloadType;
+
+	/**
+	 * As described in the
+	 * {@link https://docs.getodk.org/openrosa-form-submission/#extended-transmission-considerations | OpenRosa Form Submission API},
+	 * clients may obtain this value from an OpenRosa server's
+	 * `X-OpenRosa-Accept-Content-Length` header.
+	 */
+	readonly maxSize?: number;
+}
+
+interface ChunkedInstancePayloadOptions extends BaseInstancePayloadOptions<'chunked'> {
+	readonly payloadType: 'chunked';
+	readonly maxSize: number;
+}
+
+interface MonolithicInstancePayloadOptions extends BaseInstancePayloadOptions<'monolithic'> {
+	readonly payloadType: 'monolithic';
+	readonly maxSize?: never;
+}
+
+// prettier-ignore
+export type InstancePayloadOptions<PayloadType extends InstancePayloadType = 'monolithic'> = {
+	chunked: ChunkedInstancePayloadOptions;
+	monolithic: MonolithicInstancePayloadOptions;
+}[PayloadType];