@getodk/xforms-engine 0.6.0 → 0.8.0

package/src/client/serialization/InstanceState.ts

@@ -0,0 +1,14 @@
+import type { RootNode } from '../RootNode.ts';
+
+export interface InstanceState {
+	/**
+	 * Represents the serialized XML state of a given node. The value produced in
+	 * {@link RootNode.instanceState} is the same serialization which will be
+	 * produced for a complete instance.
+	 *
+	 * @todo Note that this particular aspect of the design doesn't yet address
+	 * production of unique file names. As such, this may change as we introduce
+	 * affected data types (and their supporting nodes).
+	 */
+	get instanceXML(): string;
+}

package/src/client/submission/{SubmissionDefinition.ts → SubmissionMeta.ts}

@@ -1,4 +1,4 @@
-export interface SubmissionDefinition {
+export interface SubmissionMeta {
 	/**
 	 * @see {@link https://getodk.github.io/xforms-spec/#submission-attributes | `action` submission attribute}
 	 */

package/src/entrypoints/FormInstance.ts

@@ -0,0 +1,56 @@
+import { identity } from '@getodk/common/lib/identity.ts';
+import type {
+	FormInstance as ClientFormInstance,
+	FormInstanceInitializationMode,
+} from '../client/form/FormInstance.ts';
+import type { FormInstanceConfig } from '../client/index.ts';
+import type { InstanceConfig } from '../instance/internal-api/InstanceConfig.ts';
+import type {
+	BasePrimaryInstanceOptions,
+	PrimaryInstanceInitialState,
+	PrimaryInstanceOptions,
+} from '../instance/PrimaryInstance.ts';
+import { PrimaryInstance } from '../instance/PrimaryInstance.ts';
+import type { Root } from '../instance/Root.ts';
+import type { FormSuccessResult } from './FormResult/FormSuccessResult.ts';
+import type { FormWarningResult } from './FormResult/FormWarningResult.ts';
+
+// prettier-ignore
+export type InstantiableFormResult =
+	| FormSuccessResult
+	| FormWarningResult;
+
+interface FormInstanceOptions<Mode extends FormInstanceInitializationMode> {
+	readonly mode: Mode;
+	readonly initialState: PrimaryInstanceInitialState<Mode>;
+	readonly instanceOptions: BasePrimaryInstanceOptions;
+	readonly instanceConfig: FormInstanceConfig;
+}
+
+export class FormInstance<Mode extends FormInstanceInitializationMode>
+	implements ClientFormInstance<Mode>
+{
+	readonly mode: Mode;
+	readonly root: Root;
+
+	constructor(
+		readonly formResult: InstantiableFormResult,
+		options: FormInstanceOptions<Mode>
+	) {
+		const { mode, initialState, instanceConfig } = options;
+		const config: InstanceConfig = {
+			clientStateFactory: instanceConfig.stateFactory ?? identity,
+			computeAttachmentName: instanceConfig.instanceAttachments?.fileNameFactory ?? (() => null),
+		};
+		const primaryInstanceOptions: PrimaryInstanceOptions<Mode> = {
+			...options.instanceOptions,
+			mode,
+			initialState,
+			config,
+		};
+		const { root } = new PrimaryInstance(primaryInstanceOptions);
+
+		this.mode = mode;
+		this.root = root;
+	}
+}

package/src/entrypoints/FormResult/BaseFormResult.ts

@@ -0,0 +1,40 @@
+import type {
+	FormResultStatus,
+	LoadFormFailureResult,
+	LoadFormResult,
+	LoadFormSuccessResult,
+	LoadFormWarningResult,
+} from '../../client/form/LoadFormResult.ts';
+
+interface LoadFormResultByStatus {
+	readonly success: LoadFormSuccessResult;
+	readonly warning: LoadFormWarningResult;
+	readonly failure: LoadFormFailureResult;
+}
+
+export type BaseFormResultProperty<
+	Status extends FormResultStatus,
+	Key extends keyof LoadFormResult,
+> = LoadFormResultByStatus[Status][Key];
+
+export interface BaseFormResultOptions<Status extends FormResultStatus> {
+	readonly status: Status;
+	readonly warnings: BaseFormResultProperty<Status, 'warnings'>;
+	readonly error: BaseFormResultProperty<Status, 'error'>;
+}
+
+export abstract class BaseFormResult<Status extends FormResultStatus> {
+	readonly status: Status;
+	readonly warnings: BaseFormResultProperty<Status, 'warnings'>;
+	readonly error: BaseFormResultProperty<Status, 'error'>;
+
+	abstract readonly createInstance: BaseFormResultProperty<Status, 'createInstance'>;
+	abstract readonly editInstance: BaseFormResultProperty<Status, 'editInstance'>;
+	abstract readonly restoreInstance: BaseFormResultProperty<Status, 'restoreInstance'>;
+
+	constructor(options: BaseFormResultOptions<Status>) {
+		this.status = options.status;
+		this.warnings = options.warnings;
+		this.error = options.error;
+	}
+}

package/src/entrypoints/FormResult/BaseInstantiableFormResult.ts

@@ -0,0 +1,109 @@
+import type { CreateFormInstance } from '../../client/form/CreateFormInstance.ts';
+import type {
+	EditFormInstance,
+	EditFormInstanceInput,
+} from '../../client/form/EditFormInstance.ts';
+import type { FormInstanceConfig } from '../../client/form/FormInstanceConfig.ts';
+import type { FormResultStatus } from '../../client/form/LoadFormResult.ts';
+import type {
+	RestoreFormInstance,
+	RestoreFormInstanceInput,
+} from '../../client/form/RestoreFormInstance.ts';
+import { ErrorProductionDesignPendingError } from '../../error/ErrorProductionDesignPendingError.ts';
+import { InitialInstanceState } from '../../instance/input/InitialInstanceState.ts';
+import type { BasePrimaryInstanceOptions } from '../../instance/PrimaryInstance.ts';
+import type { FormResource } from '../../instance/resource.ts';
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import type { InstantiableFormResult } from '../FormInstance.ts';
+import { FormInstance } from '../FormInstance.ts';
+import type { BaseFormResultProperty } from './BaseFormResult.ts';
+import { BaseFormResult } from './BaseFormResult.ts';
+
+// prettier-ignore
+export type InstantiableFormResultStatus =
+	| 'success'
+	| 'warning';
+
+export interface BaseInstantiableFormResultOptions<Status extends InstantiableFormResultStatus> {
+	readonly status: Status;
+	readonly warnings: BaseFormResultProperty<Status, 'warnings'>;
+	readonly error: null;
+	readonly scope: ReactiveScope;
+	readonly formResource: FormResource;
+	readonly instanceOptions: BasePrimaryInstanceOptions;
+}
+
+export abstract class BaseInstantiableFormResult<
+	Status extends InstantiableFormResultStatus,
+> extends BaseFormResult<Status> {
+	readonly createInstance: CreateFormInstance;
+	readonly editInstance: EditFormInstance;
+	readonly restoreInstance: RestoreFormInstance;
+
+	constructor(options: BaseInstantiableFormResultOptions<Status>) {
+		const { status, warnings, error, instanceOptions } = options;
+
+		super({
+			status,
+			warnings,
+			error,
+		});
+
+		this.createInstance = (instanceConfig: FormInstanceConfig = {}) => {
+			this.assertInstantiable();
+
+			return new FormInstance(this, {
+				mode: 'create',
+				instanceOptions,
+				initialState: null,
+				instanceConfig,
+			});
+		};
+
+		this.editInstance = async (
+			input: EditFormInstanceInput,
+			instanceConfig: FormInstanceConfig = {}
+		) => {
+			this.assertInstantiable();
+
+			const initialState = await InitialInstanceState.resolve(instanceOptions.model, input);
+
+			return new FormInstance(this, {
+				mode: 'edit',
+				instanceOptions,
+				initialState,
+				instanceConfig,
+			});
+		};
+
+		this.restoreInstance = async (
+			input: RestoreFormInstanceInput,
+			instanceConfig: FormInstanceConfig = {}
+		) => {
+			this.assertInstantiable();
+
+			const initialState = await InitialInstanceState.from(instanceOptions.model, input.data);
+
+			return new FormInstance(this, {
+				mode: 'restore',
+				instanceOptions,
+				initialState,
+				instanceConfig,
+			});
+		};
+	}
+
+	isInstantiable(): this is InstantiableFormResult {
+		const self: BaseFormResult<FormResultStatus> = this satisfies BaseFormResult<FormResultStatus>;
+
+		return self.status !== 'failure';
+	}
+
+	assertInstantiable(): asserts this is InstantiableFormResult {
+		if (!this.isInstantiable()) {
+			throw new ErrorProductionDesignPendingError(
+				'Failed to instantiate from result with status: "failure"'
+			);
+		}
+	}
+}

package/src/entrypoints/FormResult/FormFailureResult.ts

@@ -0,0 +1,44 @@
+import type { AnyFunction } from '@getodk/common/types/helpers.js';
+import type { CreateFormInstance } from '../../client/form/CreateFormInstance.ts';
+import type { EditFormInstance } from '../../client/form/EditFormInstance.ts';
+import type {
+	FailedLoadFormResultMethod,
+	LoadFormFailureResult,
+	LoadFormWarnings,
+} from '../../client/form/LoadFormResult.ts';
+import type { RestoreFormInstance } from '../../client/form/RestoreFormInstance.ts';
+import { LoadFormFailureError } from '../../error/LoadFormFailureError.ts';
+import { BaseFormResult } from './BaseFormResult.ts';
+
+interface FormFailureOptions {
+	readonly error: LoadFormFailureError;
+	readonly warnings: LoadFormWarnings | null;
+}
+
+const failedFormResultMethodFactory = <T extends AnyFunction>(
+	cause: LoadFormFailureError
+): FailedLoadFormResultMethod<T> => {
+	return () => {
+		throw new Error(cause.message, { cause });
+	};
+};
+
+export class FormFailureResult extends BaseFormResult<'failure'> implements LoadFormFailureResult {
+	readonly createInstance: FailedLoadFormResultMethod<CreateFormInstance>;
+	readonly editInstance: FailedLoadFormResultMethod<EditFormInstance>;
+	readonly restoreInstance: FailedLoadFormResultMethod<RestoreFormInstance>;
+
+	constructor(options: FormFailureOptions) {
+		const { error, warnings } = options;
+
+		super({
+			status: 'failure',
+			warnings,
+			error,
+		});
+
+		this.createInstance = failedFormResultMethodFactory(error);
+		this.editInstance = failedFormResultMethodFactory(error);
+		this.restoreInstance = failedFormResultMethodFactory(error);
+	}
+}

package/src/entrypoints/FormResult/FormSuccessResult.ts

@@ -0,0 +1,25 @@
+import type { LoadFormSuccessResult } from '../../client/index.ts';
+import type { BasePrimaryInstanceOptions } from '../../instance/PrimaryInstance.ts';
+import type { FormResource } from '../../instance/resource.ts';
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import { BaseInstantiableFormResult } from './BaseInstantiableFormResult.ts';
+
+export interface FormSuccessResultOptions {
+	readonly warnings: null;
+	readonly error: null;
+	readonly scope: ReactiveScope;
+	readonly formResource: FormResource;
+	readonly instanceOptions: BasePrimaryInstanceOptions;
+}
+
+export class FormSuccessResult
+	extends BaseInstantiableFormResult<'success'>
+	implements LoadFormSuccessResult
+{
+	constructor(options: FormSuccessResultOptions) {
+		super({
+			status: 'success',
+			...options,
+		});
+	}
+}

package/src/entrypoints/FormResult/FormWarningResult.ts

@@ -0,0 +1,25 @@
+import type { LoadFormWarningResult, LoadFormWarnings } from '../../client/form/LoadFormResult.ts';
+import type { BasePrimaryInstanceOptions } from '../../instance/PrimaryInstance.ts';
+import type { FormResource } from '../../instance/resource.ts';
+import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import { BaseInstantiableFormResult } from './BaseInstantiableFormResult.ts';
+
+export interface FormWarningResultOptions {
+	readonly warnings: LoadFormWarnings;
+	readonly error: null;
+	readonly scope: ReactiveScope;
+	readonly formResource: FormResource;
+	readonly instanceOptions: BasePrimaryInstanceOptions;
+}
+
+export class FormWarningResult
+	extends BaseInstantiableFormResult<'warning'>
+	implements LoadFormWarningResult
+{
+	constructor(options: FormWarningResultOptions) {
+		super({
+			status: 'warning',
+			...options,
+		});
+	}
+}

package/src/entrypoints/createInstance.ts

@@ -0,0 +1,23 @@
+import type { CreatedFormInstance } from '../client/form/CreateFormInstance.ts';
+import type { FormInstanceConfig } from '../client/form/FormInstanceConfig.ts';
+import type { LoadFormOptions } from '../client/form/LoadForm.ts';
+import type { FormResource } from '../instance/resource.ts';
+import { loadForm } from './loadForm.ts';
+
+export interface CreateInstanceOptions {
+	readonly form?: LoadFormOptions;
+	readonly instance?: FormInstanceConfig;
+}
+
+export const createInstance = async (
+	formResource: FormResource,
+	options?: CreateInstanceOptions
+): Promise<CreatedFormInstance> => {
+	const form = await loadForm(formResource, options?.form);
+
+	if (form.status === 'failure') {
+		throw form.error;
+	}
+
+	return form.createInstance(options?.instance);
+};

package/src/entrypoints/editInstance.ts

@@ -0,0 +1,24 @@
+import type { EditedFormInstance, EditFormInstanceInput } from '../client/form/EditFormInstance.ts';
+import type { FormInstanceConfig } from '../client/form/FormInstanceConfig.ts';
+import type { LoadFormOptions } from '../client/form/LoadForm.ts';
+import type { FormResource } from '../instance/resource.ts';
+import { loadForm } from './loadForm.ts';
+
+export interface EditInstanceOptions {
+	readonly form?: LoadFormOptions;
+	readonly instance?: FormInstanceConfig;
+}
+
+export const editInstance = async (
+	formResource: FormResource,
+	input: EditFormInstanceInput,
+	options?: EditInstanceOptions
+): Promise<EditedFormInstance> => {
+	const form = await loadForm(formResource, options?.form);
+
+	if (form.status === 'failure') {
+		throw form.error;
+	}
+
+	return form.editInstance(input, options?.instance);
+};

package/src/entrypoints/index.ts

@@ -0,0 +1,4 @@
+export * from './createInstance.ts';
+export * from './editInstance.ts';
+export * from './loadForm.ts';
+export * from './restoreInstance.ts';

package/src/entrypoints/loadForm.ts

@@ -0,0 +1,154 @@
+import type { Owner } from 'solid-js';
+import { getOwner } from 'solid-js';
+import { MISSING_RESOURCE_BEHAVIOR } from '../client/constants.ts';
+import type { FormResource } from '../client/form/FormResource.ts';
+import type { LoadForm, LoadFormOptions } from '../client/form/LoadForm.ts';
+import type { LoadFormResult } from '../client/form/LoadFormResult.ts';
+import { LoadFormFailureError } from '../error/LoadFormFailureError.ts';
+import { retrieveFormDefinition } from '../instance/resource.ts';
+import type { ReactiveScope } from '../lib/reactivity/scope.ts';
+import { createReactiveScope } from '../lib/reactivity/scope.ts';
+import { XFormDOM } from '../parse/XFormDOM.ts';
+import { XFormDefinition } from '../parse/XFormDefinition.ts';
+import { SecondaryInstancesDefinition } from '../parse/model/SecondaryInstance/SecondaryInstancesDefinition.ts';
+import { FormFailureResult } from './FormResult/FormFailureResult.ts';
+import { FormSuccessResult } from './FormResult/FormSuccessResult.ts';
+
+/**
+ * Creates a {@link ReactiveScope | reactive scope} from which all form
+ * instances derive, and:
+ *
+ * - if a client loads a form within a Solid reactive context, the scope will be
+ *   disposed along with the client's reactive context; OR
+ * - if a client loads a form outside a Solid reactive context (typically: if a
+ *   client does not use Solid reactivity), the scope will disposed if and when
+ *   the engine drops access to the loaded form
+ *
+ * **IMPORTANT:** this **MUST** be called synchronously. If it is called in an
+ * `async` function, it **MUST** be called before any `await` expression; if it
+ * is called in any other flow with mixed synchrony, it must be called before
+ * yielding to the event loop. Failing to do this will cause the engine to lose
+ * access to a client's Solid reactive context, potentially leaking form
+ * reactivity indefinitely.
+ */
+const createPotentiallyClientOwnedReactiveScope = (): ReactiveScope => {
+	/**
+	 * A {@link clientOwner | client owner} is the owner of a client's Solid
+	 * reactive context, if one exists. If none exists, the {@link ReactiveScope}
+	 * is fully owned by the engine.
+	 */
+	const clientOwner: Owner | null = getOwner();
+
+	return createReactiveScope({ owner: clientOwner });
+};
+
+type GlobalFetch = typeof globalThis.fetch;
+
+type UnboundGlobalFetch = (this: void, ...args: Parameters<GlobalFetch>) => ReturnType<GlobalFetch>;
+
+/**
+ * @see {@link https://github.com/getodk/web-forms/pull/281}
+ */
+let unboundGlobalFetch: UnboundGlobalFetch;
+
+if (typeof globalThis.fetch === 'function') {
+	unboundGlobalFetch = (...args) => {
+		return globalThis.fetch(...args);
+	};
+} else {
+	unboundGlobalFetch = () => {
+		throw new Error('fetch is not supported in this environment');
+	};
+}
+
+interface ResolvedOptions extends Required<LoadFormOptions> {}
+
+/**
+ * Resolves {@link FormResultLoadOptions} from options directly passed by a
+ * client (if passed at all).
+ *
+ * Note that this function exists to be more resilient than the static types
+ * would technically require, i.e. anticipating any kind of nullish value where
+ * option properties are typed only as optional. This is an acknowledgement that
+ * the nuances of nullishness are a footgun in untyped JavaScript, and
+ * nested-optional semantics are a particularly likely source of mistakes in
+ * client, and especially host application, integrations.
+ */
+const resolveOptions = (options?: LoadFormOptions): ResolvedOptions => {
+	return {
+		fetchFormDefinition: options?.fetchFormDefinition ?? unboundGlobalFetch,
+		fetchFormAttachment: options?.fetchFormAttachment ?? unboundGlobalFetch,
+		missingResourceBehavior: options?.missingResourceBehavior ?? MISSING_RESOURCE_BEHAVIOR.DEFAULT,
+	};
+};
+
+/**
+ * **IMPORTANT:** This function is defined separately from, and to be called by,
+ * the {@link loadForm} entrypoint to ensure we satisfy the synchrony
+ * requirements of {@link createPotentiallyClientOwnedReactiveScope}.
+ */
+const loadFormResult = async (
+	scope: ReactiveScope,
+	formResource: FormResource,
+	options: ResolvedOptions
+): Promise<LoadFormResult> => {
+	const { fetchFormDefinition, fetchFormAttachment, missingResourceBehavior } = options;
+
+	// TODO: Currently, **all** of the intermediate calls in this `try` block
+	// may throw! Handling that fact at the source would provide a much more
+	// specific `LoadFormFailureResult`, and address performance regressions
+	// inherent to such a broad/mixed use of `try`/`catch`.
+	//
+	// Addressing this is deferred for now, to limit scope.
+	try {
+		const sourceXML = await retrieveFormDefinition(formResource, {
+			fetchFormDefinition,
+		});
+		const xformDOM = XFormDOM.from(sourceXML);
+		const { model } = new XFormDefinition(xformDOM);
+		const secondaryInstances = await SecondaryInstancesDefinition.load(xformDOM, {
+			fetchResource: fetchFormAttachment,
+			missingResourceBehavior,
+		});
+		const instanceOptions = {
+			scope,
+			model,
+			secondaryInstances,
+		};
+
+		return new FormSuccessResult({
+			warnings: null,
+			error: null,
+			scope,
+			formResource,
+			instanceOptions,
+		});
+	} catch (caught) {
+		let cause: Error;
+
+		if (caught instanceof Error) {
+			cause = caught;
+		} else {
+			cause = new Error('Unknown form load error', { cause: caught });
+		}
+
+		const error = new LoadFormFailureError(formResource, [cause]);
+
+		return new FormFailureResult({
+			warnings: null,
+			error,
+		});
+	}
+};
+
+export const loadForm = (
+	formResource: FormResource,
+	options?: LoadFormOptions
+): Promise<LoadFormResult> => {
+	const scope = createPotentiallyClientOwnedReactiveScope();
+	const resolvedOptions = resolveOptions(options);
+
+	return loadFormResult(scope, formResource, resolvedOptions);
+};
+
+loadForm satisfies LoadForm;

package/src/entrypoints/restoreInstance.ts

@@ -0,0 +1,27 @@
+import type { FormInstanceConfig } from '../client/form/FormInstanceConfig.ts';
+import type { LoadFormOptions } from '../client/form/LoadForm.ts';
+import type {
+	RestoredFormInstance,
+	RestoreFormInstanceInput,
+} from '../client/form/RestoreFormInstance.ts';
+import type { FormResource } from '../instance/resource.ts';
+import { loadForm } from './loadForm.ts';
+
+export interface RestoreInstanceOptions {
+	readonly form?: LoadFormOptions;
+	readonly instance?: FormInstanceConfig;
+}
+
+export const restoreInstance = async (
+	formResource: FormResource,
+	input: RestoreFormInstanceInput,
+	options?: RestoreInstanceOptions
+): Promise<RestoredFormInstance> => {
+	const form = await loadForm(formResource, options?.form);
+
+	if (form.status === 'failure') {
+		throw form.error;
+	}
+
+	return form.restoreInstance(input, options?.instance);
+};

package/src/error/LoadFormFailureError.ts

@@ -0,0 +1,114 @@
+import type { UnknownObject } from '@getodk/common/lib/type-assertions/assertUnknownObject.ts';
+import type { Primitive } from '@getodk/common/types/Primitive.ts';
+import type { FormResource } from '../client/form/FormResource.ts';
+
+// prettier-ignore
+type PartiallyKnownType<T> =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| T
+	| UnknownObject
+	| Primitive;
+
+/**
+ * A {@link Blob}, which _may be_ a {@link File}.
+ *
+ * Extends {@link Blob} with optional properties corresponding to {@link File}'s
+ * own extensions of the same interface, allowing inspection without an
+ * unnecessary type cast, and without unnecessary runtime/type reconciliation.
+ *
+ * @todo There's almost certainly no reason that this couldn't be a part of the
+ * client-facing {@link FormResource} union type. It's kept internal here for
+ * now, in case that could cause confusion in client integrations.
+ */
+interface MaybeFile extends Blob {
+	readonly lastModified?: PartiallyKnownType<number>;
+	readonly name?: PartiallyKnownType<string>;
+	readonly webkitRelativePath?: PartiallyKnownType<string>;
+}
+
+const blobDescription = (resource: MaybeFile): string => {
+	const { name } = resource;
+
+	if (typeof name === 'string') {
+		return name;
+	}
+
+	let commonConstructorName: 'Blob' | 'File';
+
+	if (resource instanceof File) {
+		commonConstructorName = 'File';
+	} else {
+		commonConstructorName = 'Blob';
+	}
+
+	return `Unknown ${commonConstructorName} data`;
+};
+
+interface FormResourceMetadata {
+	readonly description: string;
+	readonly rawData: string | null;
+}
+
+const formResourceMetadata = (resource: FormResource): FormResourceMetadata => {
+	if (resource instanceof Blob) {
+		return {
+			description: blobDescription(resource),
+			rawData: null,
+		};
+	}
+
+	if (resource instanceof URL) {
+		return {
+			description: resource.href,
+			rawData: null,
+		};
+	}
+
+	return {
+		description: 'Raw string data',
+		rawData: resource,
+	};
+};
+
+/**
+ * @todo This is a placeholder class, given a name so it can be referenced in
+ * client interfaces for form loading. It is pending design of errors (broadly)
+ * and modeling of form loading errors (specifically).
+ */
+export class LoadFormFailureError extends AggregateError {
+	constructor(resource: FormResource, errors: readonly Error[]) {
+		const { description, rawData } = formResourceMetadata(resource);
+		const messageLines: string[] = [
+			`Failed to load form resource: ${description}`,
+			'\n',
+
+			...errors.map((error) => {
+				const aggregatedMessage = error.message;
+
+				if (aggregatedMessage == null) {
+					return '- Unknown error';
+				}
+
+				return `- ${aggregatedMessage}`;
+			}),
+		];
+
+		if (rawData != null) {
+			messageLines.push('\n- - -\n', 'Raw resource data:', rawData);
+		}
+
+		const message = messageLines.join('\n');
+
+		super(errors, message);
+
+		const [head, ...tail] = errors;
+
+		if (head != null && tail.length === 0) {
+			const { stack } = head;
+
+			if (typeof stack === 'string') {
+				this.stack = stack;
+			}
+		}
+	}
+}

package/src/error/MalformedInstanceDataError.ts

@@ -0,0 +1,3 @@
+import { ErrorProductionDesignPendingError } from './ErrorProductionDesignPendingError.ts';
+
+export class MalformedInstanceDataError extends ErrorProductionDesignPendingError {}