@getodk/xforms-engine 0.5.0 → 0.7.0

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

@@ -0,0 +1,23 @@
+export type InstancePayloadType = 'chunked' | 'monolithic';
+interface BaseInstancePayloadOptions<PayloadType extends InstancePayloadType> {
+    readonly payloadType?: PayloadType | undefined;
+    /**
+     * 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 maxSize: number;
+}
+interface MonolithicInstancePayloadOptions extends BaseInstancePayloadOptions<'monolithic'> {
+    readonly payloadType?: 'monolithic' | undefined;
+    readonly maxSize?: never;
+}
+export type InstancePayloadOptions<PayloadType extends InstancePayloadType = 'monolithic'> = {
+    chunked: ChunkedInstancePayloadOptions;
+    monolithic: MonolithicInstancePayloadOptions;
+}[PayloadType];
+export {};

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

@@ -0,0 +1,12 @@
+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/dist/client/submission/{SubmissionDefinition.d.ts → SubmissionMeta.d.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/dist/client/unsupported/UnsupportedControlNode.d.ts

@@ -1,6 +1,4 @@
 import { UnknownAppearanceDefinition } from '../../parse/body/appearance/unknownAppearanceParser.ts';
-import { RangeControlDefinition } from '../../parse/body/control/RangeControlDefinition.ts';
-import { RankControlDefinition } from '../../parse/body/control/RankControlDefinition.ts';
 import { UploadControlDefinition } from '../../parse/body/control/UploadControlDefinition.ts';
 import { LeafNodeDefinition } from '../../parse/model/LeafNodeDefinition.ts';
 import { BaseNode, BaseNodeState } from '../BaseNode.ts';
@@ -13,7 +11,7 @@ export interface UnsupportedControlNodeState extends BaseNodeState {
     get valueOptions(): unknown;
     get value(): unknown;
 }
-export type UnsupportedControlElementDefinition = RangeControlDefinition | RankControlDefinition | UploadControlDefinition;
+export type UnsupportedControlElementDefinition = UploadControlDefinition;
 export interface UnsupportedControlDefinition extends LeafNodeDefinition {
     readonly bodyElement: UnsupportedControlElementDefinition;
 }

package/dist/entrypoints/FormInstance.d.ts

@@ -0,0 +1,20 @@
+import { FormInstance as ClientFormInstance, FormInstanceInitializationMode } from '../client/form/FormInstance.ts';
+import { FormInstanceConfig } from '../client/index.ts';
+import { BasePrimaryInstanceOptions, PrimaryInstanceInitialState } from '../instance/PrimaryInstance.ts';
+import { Root } from '../instance/Root.ts';
+import { FormSuccessResult } from './FormResult/FormSuccessResult.ts';
+import { FormWarningResult } from './FormResult/FormWarningResult.ts';
+export type InstantiableFormResult = FormSuccessResult | FormWarningResult;
+interface FormInstanceOptions<Mode extends FormInstanceInitializationMode> {
+    readonly mode: Mode;
+    readonly initialState: PrimaryInstanceInitialState<Mode>;
+    readonly instanceOptions: BasePrimaryInstanceOptions;
+    readonly instanceConfig: FormInstanceConfig;
+}
+export declare class FormInstance<Mode extends FormInstanceInitializationMode> implements ClientFormInstance<Mode> {
+    readonly formResult: InstantiableFormResult;
+    readonly mode: Mode;
+    readonly root: Root;
+    constructor(formResult: InstantiableFormResult, options: FormInstanceOptions<Mode>);
+}
+export {};

package/dist/entrypoints/FormResult/BaseFormResult.d.ts

@@ -0,0 +1,22 @@
+import { 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 declare 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>);
+}
+export {};

package/dist/entrypoints/FormResult/BaseInstantiableFormResult.d.ts

@@ -0,0 +1,25 @@
+import { CreateFormInstance } from '../../client/form/CreateFormInstance.ts';
+import { EditFormInstance } from '../../client/form/EditFormInstance.ts';
+import { RestoreFormInstance } from '../../client/form/RestoreFormInstance.ts';
+import { BasePrimaryInstanceOptions } from '../../instance/PrimaryInstance.ts';
+import { FormResource } from '../../instance/resource.ts';
+import { ReactiveScope } from '../../lib/reactivity/scope.ts';
+import { InstantiableFormResult } from '../FormInstance.ts';
+import { BaseFormResultProperty, BaseFormResult } from './BaseFormResult.ts';
+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 declare abstract class BaseInstantiableFormResult<Status extends InstantiableFormResultStatus> extends BaseFormResult<Status> {
+    readonly createInstance: CreateFormInstance;
+    readonly editInstance: EditFormInstance;
+    readonly restoreInstance: RestoreFormInstance;
+    constructor(options: BaseInstantiableFormResultOptions<Status>);
+    isInstantiable(): this is InstantiableFormResult;
+    assertInstantiable(): asserts this is InstantiableFormResult;
+}

package/dist/entrypoints/FormResult/FormFailureResult.d.ts

@@ -0,0 +1,17 @@
+import { CreateFormInstance } from '../../client/form/CreateFormInstance.ts';
+import { EditFormInstance } from '../../client/form/EditFormInstance.ts';
+import { FailedLoadFormResultMethod, LoadFormFailureResult, LoadFormWarnings } from '../../client/form/LoadFormResult.ts';
+import { 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;
+}
+export declare class FormFailureResult extends BaseFormResult<'failure'> implements LoadFormFailureResult {
+    readonly createInstance: FailedLoadFormResultMethod<CreateFormInstance>;
+    readonly editInstance: FailedLoadFormResultMethod<EditFormInstance>;
+    readonly restoreInstance: FailedLoadFormResultMethod<RestoreFormInstance>;
+    constructor(options: FormFailureOptions);
+}
+export {};

package/dist/entrypoints/FormResult/FormSuccessResult.d.ts

@@ -0,0 +1,15 @@
+import { LoadFormSuccessResult } from '../../client/index.ts';
+import { BasePrimaryInstanceOptions } from '../../instance/PrimaryInstance.ts';
+import { FormResource } from '../../instance/resource.ts';
+import { 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 declare class FormSuccessResult extends BaseInstantiableFormResult<'success'> implements LoadFormSuccessResult {
+    constructor(options: FormSuccessResultOptions);
+}

package/dist/entrypoints/FormResult/FormWarningResult.d.ts

@@ -0,0 +1,15 @@
+import { LoadFormWarningResult, LoadFormWarnings } from '../../client/form/LoadFormResult.ts';
+import { BasePrimaryInstanceOptions } from '../../instance/PrimaryInstance.ts';
+import { FormResource } from '../../instance/resource.ts';
+import { 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 declare class FormWarningResult extends BaseInstantiableFormResult<'warning'> implements LoadFormWarningResult {
+    constructor(options: FormWarningResultOptions);
+}

package/dist/entrypoints/createInstance.d.ts

@@ -0,0 +1,9 @@
+import { CreatedFormInstance } from '../client/form/CreateFormInstance.ts';
+import { FormInstanceConfig } from '../client/form/FormInstanceConfig.ts';
+import { LoadFormOptions } from '../client/form/LoadForm.ts';
+import { FormResource } from '../instance/resource.ts';
+export interface CreateInstanceOptions {
+    readonly form?: LoadFormOptions;
+    readonly instance?: FormInstanceConfig;
+}
+export declare const createInstance: (formResource: FormResource, options?: CreateInstanceOptions) => Promise<CreatedFormInstance>;

package/dist/entrypoints/editInstance.d.ts

@@ -0,0 +1,9 @@
+import { EditedFormInstance, EditFormInstanceInput } from '../client/form/EditFormInstance.ts';
+import { FormInstanceConfig } from '../client/form/FormInstanceConfig.ts';
+import { LoadFormOptions } from '../client/form/LoadForm.ts';
+import { FormResource } from '../instance/resource.ts';
+export interface EditInstanceOptions {
+    readonly form?: LoadFormOptions;
+    readonly instance?: FormInstanceConfig;
+}
+export declare const editInstance: (formResource: FormResource, input: EditFormInstanceInput, options?: EditInstanceOptions) => Promise<EditedFormInstance>;

package/dist/entrypoints/index.d.ts

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

package/dist/entrypoints/loadForm.d.ts

@@ -0,0 +1,4 @@
+import { FormResource } from '../client/form/FormResource.ts';
+import { LoadFormOptions } from '../client/form/LoadForm.ts';
+import { LoadFormResult } from '../client/form/LoadFormResult.ts';
+export declare const loadForm: (formResource: FormResource, options?: LoadFormOptions) => Promise<LoadFormResult>;

package/dist/entrypoints/restoreInstance.d.ts

@@ -0,0 +1,9 @@
+import { FormInstanceConfig } from '../client/form/FormInstanceConfig.ts';
+import { LoadFormOptions } from '../client/form/LoadForm.ts';
+import { RestoredFormInstance, RestoreFormInstanceInput } from '../client/form/RestoreFormInstance.ts';
+import { FormResource } from '../instance/resource.ts';
+export interface RestoreInstanceOptions {
+    readonly form?: LoadFormOptions;
+    readonly instance?: FormInstanceConfig;
+}
+export declare const restoreInstance: (formResource: FormResource, input: RestoreFormInstanceInput, options?: RestoreInstanceOptions) => Promise<RestoredFormInstance>;

package/dist/error/LoadFormFailureError.d.ts

@@ -0,0 +1,9 @@
+import { FormResource } from '../client/form/FormResource.ts';
+/**
+ * @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 declare class LoadFormFailureError extends AggregateError {
+    constructor(resource: FormResource, errors: readonly Error[]);
+}

package/dist/error/MalformedInstanceDataError.d.ts

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

package/dist/error/RankMissingValueError.d.ts

@@ -0,0 +1,3 @@
+export declare class RankMissingValueError extends Error {
+    constructor(message: string);
+}

package/dist/error/RankValueTypeError.d.ts

@@ -0,0 +1,6 @@
+import { XFormsSpecViolationError } from './XFormsSpecViolationError.ts';
+import { RankDefinition } from '../client/RankNode.ts';
+import { UnsupportedBaseItemValueType } from '../lib/codecs/items/BaseItemCodec.ts';
+export declare class RankValueTypeError extends XFormsSpecViolationError {
+    constructor(definition: RankDefinition<UnsupportedBaseItemValueType>);
+}

package/dist/error/SelectValueTypeError.d.ts

@@ -0,0 +1,15 @@
+import { SelectDefinition } from '../client/SelectNode.ts';
+import { UnsupportedBaseItemValueType } from '../lib/codecs/items/BaseItemCodec.ts';
+import { XFormsSpecViolationError } from './XFormsSpecViolationError.ts';
+/**
+ * @todo It would be good to have a standardized way to use specific types of
+ * errors as a prompt for feedback. There is currently a feedback link presented
+ * by `@getodk/web-forms`, which is conditionally displayed (condition is
+ * evidently controlled by a
+ * {@link https://vuejs.org/api/sfc-script-setup#defineoptions | Vue component option}).
+ *
+ * @see {@link https://github.com/getodk/web-forms/issues/276}
+ */
+export declare class SelectValueTypeError extends XFormsSpecViolationError {
+    constructor(definition: SelectDefinition<UnsupportedBaseItemValueType>);
+}

package/dist/error/TemplatedNodeAttributeSerializationError.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This error class is intended as a common point of reference for all of the
+ * related interfaces and implementation where we've deferred two concerns:
+ *
+ * 1. Support for attributes on instance nodes (which may be bound in a form's
+ *    model and/or may be expected to preserve model-defined defaults)
+ * 2. Present lack of logic to treat a `jr:template` attribute as a special
+ *    case: whereas in the general case we would expect to pass through a
+ *    form/model-defined attribute, we expect to specifically **omit**
+ *    `jr:template` from repeat instances derived from any of form's
+ *    explicitly-defined repeat templates
+ *
+ * Addressing #1 is (now) a prerequisite to addressing #2, and it is also a
+ * prerequisite for #2's unaddressed status to _become meaningfully observable
+ * and problematic_.
+ *
+ * By introducing this error at a point where a change in #1's status is likely
+ * to be implicated, we're also likely to be reminded to address #2 in tandem.
+ */
+export declare class TemplatedNodeAttributeSerializationError extends Error {
+    constructor();
+}

package/dist/error/XFormsSpecViolationError.d.ts

@@ -0,0 +1,2 @@
+export declare abstract class XFormsSpecViolationError extends Error {
+}

package/dist/index.d.ts

@@ -1,34 +1,2 @@
-import { InitializeForm } from './index.ts';
-export declare const initializeForm: InitializeForm;
-export type * from './client/constants.ts';
-export * as constants from './client/constants.ts';
-export type * from './client/EngineConfig.ts';
-export type * from './client/FormLanguage.ts';
-export type * from './client/GroupNode.ts';
-export type { AnyChildNode, AnyControlNode, AnyLeafNode, AnyNode, AnyParentNode, AnyUnsupportedControlNode, GeneralChildNode, GeneralParentNode, RepeatRangeNode, } from './client/hierarchy.ts';
-export type * from './client/index.ts';
-export type * from './client/InputNode.ts';
-export type * from './client/ModelValueNode.ts';
-export type * from './client/NoteNode.ts';
-export type * from './client/OpaqueReactiveObjectFactory.ts';
-export type * from './client/repeat/RepeatInstanceNode.ts';
-export type * from './client/repeat/RepeatRangeControlledNode.ts';
-export type * from './client/repeat/RepeatRangeUncontrolledNode.ts';
-export type * from './client/resources.ts';
-export type * from './client/RootNode.ts';
-export type * from './client/SelectNode.ts';
-export type * from './client/submission/SubmissionData.ts';
-export type * from './client/submission/SubmissionDefinition.ts';
-export type * from './client/submission/SubmissionInstanceFile.ts';
-export type * from './client/submission/SubmissionOptions.ts';
-export type * from './client/submission/SubmissionResult.ts';
-export type * from './client/submission/SubmissionState.ts';
-export type * from './client/SubtreeNode.ts';
-export type * from './client/TextRange.ts';
-export type * from './client/TriggerNode.ts';
-export type * from './client/unsupported/RangeNode.ts';
-export type * from './client/unsupported/RankNode.ts';
-export type * from './client/unsupported/UploadNode.ts';
-export type * from './client/validation.ts';
-export type * from './client/ValueType.ts';
-export type { AnySelectDefinition, SelectDefinition, } from './parse/body/control/select/SelectDefinition.ts';
+export * from './client/index.ts';
+export * from './entrypoints/index.ts';