@getodk/xforms-engine 0.4.0 → 0.5.0

package/dist/client/submission/SubmissionResult.d.ts

@@ -0,0 +1,91 @@
+import { DescendantNodeViolationReference } from '../validation.ts';
+import { SubmissionData } from './SubmissionData.ts';
+import { SubmissionDefinition } from './SubmissionDefinition.ts';
+import { SubmissionChunkedType } from './SubmissionOptions.ts';
+export type SubmissionResultStatus = 'pending' | 'max-size-exceeded' | 'ready';
+type SubmissionResultData<ChunkedType extends SubmissionChunkedType> = {
+    chunked: readonly [SubmissionData, ...SubmissionData[]];
+    monolithic: SubmissionData;
+}[ChunkedType];
+/**
+ * Provides detail about an individual submission attachment {@link File}s which
+ * exceeds the client-specified {@link maxSize} for a
+ * {@link SubmissionResult<'chunked'> | chunked submission result}. 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 on
+ * submission; 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 submission 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 PendingSubmissionResult} would then cover the case.
+ */
+interface MaxSizeViolation {
+    /**
+     * Specifies the index of
+     * {@link SubmissionResultData<'chunked'> | chunked submission data} where a
+     * submission 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}/submission attachment, in the {@link SubmissionData}
+     * at the specified {@link dataIndex}.
+     */
+    readonly fileName: string;
+    /**
+     * Reflects the client-specified maximum size for each chunk of a
+     * {@link SubmissionResult<'chunked'> | chunked submission result}.
+     */
+    readonly maxSize: number;
+    /**
+     * Details the actual size of the violating {@link File}/submission
+     * attachment. Along with {@link maxSize}. Clients may use the delta between
+     * this value and {@link maxSize} to provide detailed guidance to users.
+     */
+    readonly actualSize: number;
+}
+type SubmissionResultViolation = DescendantNodeViolationReference | MaxSizeViolation;
+interface BaseSubmissionResult<ChunkedType extends SubmissionChunkedType> {
+    readonly status: SubmissionResultStatus;
+    readonly definition: SubmissionDefinition;
+    get violations(): readonly SubmissionResultViolation[] | null;
+    /**
+     * Submission data may be chunked according to the
+     * {@link SubmissionOptions.maxSize | maxSize submission option}
+     */
+    readonly data: SubmissionResultData<ChunkedType>;
+}
+interface PendingSubmissionResult<ChunkedType extends SubmissionChunkedType> extends BaseSubmissionResult<ChunkedType> {
+    readonly status: 'pending';
+    get violations(): readonly DescendantNodeViolationReference[];
+}
+interface MaxSizeExceededResult extends BaseSubmissionResult<'chunked'> {
+    readonly status: 'max-size-exceeded';
+    get violations(): readonly MaxSizeViolation[];
+}
+interface ReadySubmissionResult<ChunkedType extends SubmissionChunkedType> extends BaseSubmissionResult<ChunkedType> {
+    readonly status: 'ready';
+    get violations(): null;
+}
+type CommonSubmissionResult<ChunkedType extends SubmissionChunkedType> = PendingSubmissionResult<ChunkedType> | ReadySubmissionResult<ChunkedType>;
+export type ChunkedSubmissionResult = CommonSubmissionResult<'chunked'> | MaxSizeExceededResult;
+export type MonolithicSubmissionResult = CommonSubmissionResult<'monolithic'>;
+export type SubmissionResult<ChunkedType extends SubmissionChunkedType> = {
+    chunked: ChunkedSubmissionResult;
+    monolithic: MonolithicSubmissionResult;
+}[ChunkedType];
+export {};

package/dist/client/submission/SubmissionState.d.ts

@@ -0,0 +1,12 @@
+export interface SubmissionState {
+    /**
+     * Represents the serialized XML state of a given node, as it will be prepared
+     * for submission. The value produced in {@link RootNode.submissionState} is
+     * the same serialization which will be produced for the complete submission.
+     *
+     * @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 submissionXML(): string;
+}

package/dist/client/validation.d.ts

@@ -1,4 +1,4 @@
-import { NodeID } from '../instance/identity.ts';
+import { FormNodeID } from './identity.ts';
 import { TextRange } from './TextRange.ts';
 interface BaseValidity {
     /**
@@ -144,7 +144,7 @@ export interface LeafNodeValidationState {
  * each property will be directly computed from the affected node.
  */
 export interface DescendantNodeViolationReference {
-    readonly nodeId: NodeID;
+    readonly nodeId: FormNodeID;
     get reference(): string;
     get violation(): AnyViolation;
 }

package/dist/error/ErrorProductionDesignPendingError.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Temporary representation of newly introduced error conditions which we may
+ * produce to clients (and beyond). Intentionally a stub pending a more concrete
+ * design and implementation of our approach to producing Result types.
+ */
+export declare class ErrorProductionDesignPendingError extends Error {
+}

package/dist/error/ValueTypeInvariantError.d.ts

@@ -0,0 +1,17 @@
+import { ValueType } from '../client/ValueType.ts';
+import { ErrorProductionDesignPendingError } from './ErrorProductionDesignPendingError.ts';
+/**
+ * Temporary(?) representation of error conditions arising from violation of
+ * invariants specific to {@link valueType}.
+ *
+ * @todo The intent of this distinct subclass of
+ * {@link ErrorProductionDesignPendingError} is to call out cases where we may
+ * want to represent such errors to clients as **validation errors** in the
+ * future. We identified this as probably desirable in the initial work on `int`
+ * and `decimal` value types, but held off on that aspect of implementation to
+ * tame scope.
+ */
+export declare class ValueTypeInvariantError extends ErrorProductionDesignPendingError {
+    readonly valueType: ValueType;
+    constructor(valueType: ValueType, message: string);
+}

package/dist/error/XPathFunctionalityError.d.ts

@@ -0,0 +1,14 @@
+import { AnyFunction, ExpandUnion } from '../../../common/types/helpers.js';
+import { XPathDOMAdapter, XPathNode } from '@getodk/xpath';
+/**
+ * @todo this is general enough to go in `@getodk/common`. Holding off until
+ * it's clear we actually benefit from this particular type gymnastic.
+ */
+type MethodNameOf<T> = {
+    [K in keyof T]: T[K] extends AnyFunction ? K : never;
+}[keyof T];
+export type XPathFunctionalityErrorCategory = ExpandUnion<MethodNameOf<XPathDOMAdapter<XPathNode>> | 'processing-instruction'>;
+export declare abstract class XPathFunctionalityError extends Error {
+    constructor(functionalityMessagePrefix: string, category: XPathFunctionalityErrorCategory);
+}
+export {};

package/dist/error/XPathFunctionalityNotSupportedError.d.ts

@@ -0,0 +1,7 @@
+import { XPathFunctionalityErrorCategory, XPathFunctionalityError } from './XPathFunctionalityError.ts';
+type XPathFunctionalityNotSupportedStub = () => never;
+export declare class XPathFunctionalityNotSupportedError extends XPathFunctionalityError {
+    static createStubImplementation(category: XPathFunctionalityErrorCategory): XPathFunctionalityNotSupportedStub;
+    private constructor();
+}
+export {};

package/dist/error/XPathFunctionalityPendingError.d.ts

@@ -0,0 +1,7 @@
+import { XPathFunctionalityErrorCategory, XPathFunctionalityError } from './XPathFunctionalityError.ts';
+type XPathFunctionalityPendingStub = () => never;
+export declare class XPathFunctionalityPendingError extends XPathFunctionalityError {
+    static createStubImplementation(category: XPathFunctionalityErrorCategory): XPathFunctionalityPendingStub;
+    private constructor();
+}
+export {};

package/dist/index.d.ts

@@ -1,20 +1,28 @@
 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/StringNode.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';
@@ -22,4 +30,5 @@ 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';