@getodk/xforms-engine 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getodk/xforms-engine",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "license": "Apache-2.0",
   "description": "XForms engine for ODK Web Forms",
   "type": "module",

package/src/client/BaseNode.ts

@@ -5,7 +5,7 @@ import type { OpaqueReactiveObjectFactory } from './OpaqueReactiveObjectFactory.
 import type { TextRange } from './TextRange.ts';
 import type { FormNodeID } from './identity.ts';
 import type { InstanceNodeType } from './node-types.ts';
-import type { SubmissionState } from './submission/SubmissionState.ts';
+import type { InstanceState } from './serialization/InstanceState.ts';
 import type {
 	AncestorNodeValidationState,
 	LeafNodeValidationState,
@@ -256,14 +256,14 @@ export interface BaseNode {
 	readonly validationState: NodeValidationState;
 
 	/**
-	 * Represents the current submission state of the node.
+	 * Represents the current instance state of the node.
 	 *
-	 * @see {@link SubmissionState.submissionXML} for additional detail.
+	 * @see {@link InstanceState.instanceXML} for additional detail.
 	 *
 	 * @todo Consider whether this can (should) be merged with
 	 * {@link currentState}, while providing the same client-reactivity
 	 * guarantees. (The challenge there is in defining client-reactive state which
 	 * self-referentially derives state from its own definition.)
 	 */
-	readonly submissionState: SubmissionState;
+	readonly instanceState: InstanceState;
 }

package/src/client/BaseValueNode.ts

@@ -2,6 +2,7 @@ import type { LeafNodeDefinition } from '../parse/model/LeafNodeDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { GeneralParentNode } from './hierarchy.ts';
 import type { LeafNodeType } from './node-types.ts';
+import type { InstanceState } from './serialization/InstanceState.ts';
 import type { LeafNodeValidationState } from './validation.ts';
 import type { ValueType } from './ValueType.ts';
 
@@ -15,12 +16,14 @@ export interface BaseValueNodeState<Value> extends BaseNodeState {
 	 * {@link value} state. This representation allows access to the node's value
 	 * _as primary instance state_. In other words, this is the value which:
 	 *
-	 * - would be serialized as a text node in
-	 *   {@link SubmissionState.submissionXML} (note: this value is **NOT**
-	 *   escaped for XML serialization, as it is there)
+	 * - would be serialized as a text node in {@link InstanceState.instanceXML}
+	 *   (note: this value is **NOT** escaped for XML serialization, as it is
+	 *   there)
 	 *
 	 * - is used when the node's value is referenced in any of a form's XPath
 	 *   expressions
+	 *
+	 * @todo Consider moving into {@link InstanceState}
 	 */
 	get instanceValue(): string;
 }
@@ -32,4 +35,5 @@ export interface BaseValueNode<V extends ValueType = ValueType, Value = string>
 	readonly parent: GeneralParentNode;
 	readonly currentState: BaseValueNodeState<Value>;
 	readonly validationState: LeafNodeValidationState;
+	readonly instanceState: InstanceState;
 }

package/src/client/RootNode.ts

@@ -3,12 +3,12 @@ import type { RootDefinition } from '../parse/model/RootDefinition.ts';
 import type { BaseNode, BaseNodeState } from './BaseNode.ts';
 import type { ActiveLanguage, FormLanguage, FormLanguages } from './FormLanguage.ts';
 import type { GeneralChildNode } from './hierarchy.ts';
-import type { SubmissionOptions } from './submission/SubmissionOptions.ts';
 import type {
-	ChunkedSubmissionResult,
-	MonolithicSubmissionResult,
-	SubmissionResult,
-} from './submission/SubmissionResult.ts';
+	ChunkedInstancePayload,
+	InstancePayload,
+	MonolithicInstancePayload,
+} from './serialization/InstancePayload.ts';
+import type { InstancePayloadOptions } from './serialization/InstancePayloadOptions.ts';
 import type { AncestorNodeValidationState } from './validation.ts';
 
 export interface RootNodeState extends BaseNodeState {
@@ -64,33 +64,41 @@ export interface RootNode extends BaseNode {
 	setLanguage(language: FormLanguage): RootNode;
 
 	/**
-	 * Prepares the current form instance state for submission.
+	 * Prepares the current form instance state as an {@link InstancePayload}.
 	 *
-	 * A {@link SubmissionResult} will be prepared even if the current form state
-	 * includes `constraint` or `required` violations. This is intended to serve
-	 * two purposes:
+	 * A payload will be prepared even if the current form state includes
+	 * `constraint` or `required` violations. This supports serveral purposes:
 	 *
-	 * - A client may effectively use this method as a part of its own "submit"
-	 *   routine, and use any violations included in the {@link SubmissionResult}
+	 * - A client may effectively use this method as a part of its "submit"
+	 *   workflow, and use any violations included in the {@link InstancePayload}
 	 *   to prompt users to address those violations.
 	 *
-	 * - A client may inspect the submission state of a form at any time.
+	 * - A client may inspect the serialized instance state of a form at any time.
 	 *   Depending on the client and use case, this may be a convenience (e.g. for
 	 *   developers to inspect that form state at a current point in time); or it
 	 *   may provide necessary functionality (e.g. for test or tooling clients).
 	 *
-	 * Note on asynchrony: preparing a {@link SubmissionResult} is expected to be
-	 * a fast operation. It may even be nearly instantaneous, or roughly
+	 * - A client may capture _incomplete_ instance state (e.g. for storage in
+	 *   client-side storage or similar persistance layer), to resume filling the
+	 *   instance at a later time.
+	 *
+	 * Note on asynchrony: preparing a {@link InstancePayload} is expected to be a
+	 * fast operation. It may even be nearly instantaneous, or roughly
 	 * proportionate to the size of the form itself. However, this method is
 	 * designed to be asynchronous out of an abundance of caution, anticipating
 	 * that some as-yet undeveloped operations on binary data (e.g. form
 	 * attachments) may themselves impose asynchrony (i.e. by interfaces provided
 	 * by the platform and/or external dependencies).
 	 *
-	 * A client may specify {@link SubmissionOptions<'chunked'>}, in which case a
-	 * {@link SubmissionResult<'chunked'>} will be produced, with form attachments
+	 * A client may specify {@link InstancePayloadOptions<'chunked'>}, in which
+	 * case a {@link ChunkedInstancePayload} will be produced, with form
+	 * attachments
 	 */
-	prepareSubmission(): Promise<MonolithicSubmissionResult>;
-	prepareSubmission(options: SubmissionOptions<'monolithic'>): Promise<MonolithicSubmissionResult>;
-	prepareSubmission(options: SubmissionOptions<'chunked'>): Promise<ChunkedSubmissionResult>;
+	prepareInstancePayload(): Promise<MonolithicInstancePayload>;
+	prepareInstancePayload(
+		options: InstancePayloadOptions<'monolithic'>
+	): Promise<MonolithicInstancePayload>;
+	prepareInstancePayload(
+		options: InstancePayloadOptions<'chunked'>
+	): Promise<ChunkedInstancePayload>;
 }

package/src/client/constants.ts

@@ -1,21 +1,19 @@
-import type { PrimaryInstance } from '../instance/PrimaryInstance.ts';
-import type { InitializeForm } from './index.ts';
+import type { LoadForm } from './form/LoadForm.ts';
 import type { ValidationTextRole } from './TextRange.ts';
 
 export const MISSING_RESOURCE_BEHAVIOR = {
 	/**
-	 * When this behavior is configured, {@link InitializeForm | initializing} a
-	 * {@link PrimaryInstance} for a form which references any **missing**
-	 * resources will fail, producing an error to the calling client.
+	 * When this behavior is configured, {@link LoadForm | loading a form} which
+	 * references any **missing** resources will fail, producing an error to the
+	 * calling client.
 	 *
 	 * @see {@link MissingResourceBehavior}
 	 */
 	ERROR: 'ERROR',
 
 	/**
-	 * When this behavior is configured, {@link InitializeForm | initializing} a
-	 * {@link PrimaryInstance} for a form which references any **missing**
-	 * resources will succeed (producing a warning).
+	 * When this behavior is configured, {@link LoadForm | loading a form} which
+	 * references any **missing** resources will succeed (producing a warning).
 	 *
 	 * Such missing resources will be parsed as if they are blank, as appropriate
 	 * for the resource's XForm semantic usage and/or format.
@@ -39,8 +37,8 @@ export type MissingResourceBehaviorBlank = typeof MISSING_RESOURCE_BEHAVIOR.BLAN
 export type MissingResourceBehaviorDefault = typeof MISSING_RESOURCE_BEHAVIOR.DEFAULT;
 
 /**
- * Specifies behavior for {@link InitializeForm | initializing} a form's
- * {@link PrimaryInstance} which references any **missing** resources.
+ * Specifies behavior for {@link LoadForm | loading a form} which references any
+ * **missing** resources.
  *
  * Here the term "missing" is consistent with
  * {@link https://www.rfc-editor.org/rfc/rfc9110#status.404 | HTTP 404 status}
@@ -70,8 +68,8 @@ type ValidationTextDefaults = typeof VALIDATION_TEXT;
 
 export type ValidationTextDefault<Role extends ValidationTextRole> = ValidationTextDefaults[Role];
 
-export const SUBMISSION_INSTANCE_FILE_NAME = 'xml_submission_file';
-export type SubmissionInstanceFileName = typeof SUBMISSION_INSTANCE_FILE_NAME;
+export const INSTANCE_FILE_NAME = 'xml_submission_file';
+export type INSTANCE_FILE_NAME = typeof INSTANCE_FILE_NAME;
 
-export const SUBMISSION_INSTANCE_FILE_TYPE = 'text/xml';
-export type SubmissionInstanceFileType = typeof SUBMISSION_INSTANCE_FILE_TYPE;
+export const INSTANCE_FILE_TYPE = 'text/xml';
+export type INSTANCE_FILE_TYPE = typeof INSTANCE_FILE_TYPE;

package/src/client/form/CreateFormInstance.ts

@@ -0,0 +1,19 @@
+import type { RootNode } from '../RootNode.ts';
+import type { FormInstance, FormInstanceCreateMode } from './FormInstance.ts';
+import type { FormInstanceConfig } from './FormInstanceConfig.ts';
+import type { LoadForm } from './LoadForm.ts';
+import type { LoadFormResult } from './LoadFormResult.ts';
+
+export type CreatedFormInstance = FormInstance<FormInstanceCreateMode>;
+
+/**
+ * @todo This is fallible! Client-facing interfaces will need to account for
+ * this. We've begun addressing fallibility _at the interface level_ in
+ * {@link LoadForm} (with {@link LoadFormResult}). We'll eventually have a more
+ * general interface pattern for this, and we'll apply it here as well. The baby
+ * step approach in {@link LoadFormResult} is impractical here due to
+ * engine-internal designs, and revising that is currently out of scope. As
+ * such, explicit interface-level documentation of fallibility is deferred here,
+ * on {@link RootNode} itself, and into any of its sub-interfaces.
+ */
+export type CreateFormInstance = (config?: FormInstanceConfig) => CreatedFormInstance;

package/src/client/form/EditFormInstance.ts

@@ -0,0 +1,93 @@
+import type { Awaitable, Thunk } from '@getodk/common/types/helpers.d.ts';
+import type { FetchResourceResponse } from '../resources.ts';
+import type { InstanceAttachmentFileName, InstanceData } from '../serialization/InstanceData.ts';
+import type { FormInstance, FormInstanceEditMode } from './FormInstance.ts';
+import type { FormInstanceConfig } from './FormInstanceConfig.ts';
+import type { LoadForm } from './LoadForm.ts';
+import type { RestoreFormInstance, RestoreFormInstanceInput } from './RestoreFormInstance.ts';
+
+export type ResolvableFormInstanceInputType = 'FORM_INSTANCE_INPUT_RESOLVABLE';
+export type ResolvedFormInstanceInputType = 'FORM_INSTANCE_INPUT_RESOLVED';
+
+// prettier-ignore
+export type EditFormInstanceInputType =
+	| ResolvableFormInstanceInputType
+	| ResolvedFormInstanceInputType;
+
+// prettier-ignore
+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;
+}
+
+// prettier-ignore
+export type EditFormInstanceInput =
+	| ResolvableFormInstanceInput
+	| ResolvedFormInstanceInput;
+
+export type EditedFormInstance = FormInstance<FormInstanceEditMode>;
+
+export type EditFormInstance = (
+	input: EditFormInstanceInput,
+	config?: FormInstanceConfig
+) => Promise<EditedFormInstance>;

package/src/client/form/FormInstance.ts

@@ -0,0 +1,114 @@
+import type { RootNode } from '../RootNode.ts';
+import type { InstantiableLoadFormResult, LoadFormResult } 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';
+
+// prettier-ignore
+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/src/client/form/FormInstanceConfig.ts

@@ -0,0 +1,18 @@
+import type { 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/src/client/form/FormResource.ts

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

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>;