@getodk/xforms-engine 0.3.0 → 0.5.0

package/dist/model/BindDefinition.d.ts

@@ -1,34 +0,0 @@
-import { XFormDataType } from '../XFormDataType.ts';
-import { XFormDefinition } from '../XFormDefinition.ts';
-import { DependencyContext } from '../expression/DependencyContext.ts';
-import { MessageDefinition } from '../parse/text/MessageDefinition.ts';
-import { BindComputation } from './BindComputation.ts';
-import { BindElement } from './BindElement.ts';
-import { ModelDefinition } from './ModelDefinition.ts';
-
-export declare class BindDefinition extends DependencyContext {
-    readonly form: XFormDefinition;
-    protected readonly model: ModelDefinition;
-    readonly nodeset: string;
-    readonly bindElement: BindElement;
-    readonly bindType: string | null;
-    readonly dataType: XFormDataType;
-    readonly parentNodeset: string | null;
-    readonly calculate: BindComputation<'calculate'> | null;
-    readonly readonly: BindComputation<'readonly'>;
-    readonly relevant: BindComputation<'relevant'>;
-    readonly required: BindComputation<'required'>;
-    /**
-     * Diverges from {@link https://github.com/getodk/javarosa/blob/059321160e6f8dbb3e81d9add61d68dd35b13cc8/dag.md | JavaRosa's}, which excludes `constraint` expressions. We compute `constraint` dependencies like the other <bind> computation expressions, but explicitly ignore self-references (this is currently handled by {@link BindComputation}, via its {@link DependentExpression} parent class).
-     */
-    readonly constraint: BindComputation<'constraint'>;
-    readonly constraintMsg: MessageDefinition<'constraintMsg'> | null;
-    readonly requiredMsg: MessageDefinition<'requiredMsg'> | null;
-    readonly saveIncomplete: BindComputation<'saveIncomplete'>;
-    protected _parentBind: BindDefinition | null | undefined;
-    get parentBind(): BindDefinition | null;
-    get reference(): string;
-    get parentReference(): string | null;
-    constructor(form: XFormDefinition, model: ModelDefinition, nodeset: string, bindElement: BindElement);
-    toJSON(): Omit<this, "model" | "toJSON" | "form" | "reference" | "parentReference" | "isTranslated" | "registerDependentExpression" | "dependencyExpressions" | "bindElement" | "parentBind">;
-}

package/dist/parse/text/OutputChunkDefinition.d.ts

@@ -1,8 +0,0 @@
-import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
-import { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
-
-export declare class OutputChunkDefinition extends TextChunkDefinition<'output'> {
-    static from(context: AnyTextRangeDefinition, element: Element): OutputChunkDefinition | null;
-    readonly source = "output";
-    private constructor();
-}

package/dist/parse/text/ReferenceChunkDefinition.d.ts

@@ -1,8 +0,0 @@
-import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
-import { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
-
-export declare class ReferenceChunkDefinition extends TextChunkDefinition<'reference'> {
-    static from(context: AnyTextRangeDefinition, refExpression: string): ReferenceChunkDefinition;
-    readonly source = "reference";
-    private constructor();
-}

package/dist/parse/text/StaticTextChunkDefinition.d.ts

@@ -1,10 +0,0 @@
-import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
-import { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
-
-export type StaticTextChunkSourceNode = Attr | Text;
-export declare class StaticTextChunkDefinition extends TextChunkDefinition<'static'> {
-    readonly stringValue: string;
-    static from(context: AnyTextRangeDefinition, stringValue: string): StaticTextChunkDefinition;
-    readonly source = "static";
-    private constructor();
-}

package/dist/parse/text/TranslationChunkDefinition.d.ts

@@ -1,9 +0,0 @@
-import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
-import { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
-
-export declare class TranslationChunkDefinition extends TextChunkDefinition<'translation'> {
-    static fromMessage(context: AnyTextRangeDefinition, maybeExpression: string): TranslationChunkDefinition | null;
-    static from(context: AnyTextRangeDefinition, maybeExpression: string): TranslationChunkDefinition | null;
-    readonly source = "translation";
-    private constructor();
-}

package/dist/parse/text/abstract/TextChunkDefinition.d.ts

@@ -1,18 +0,0 @@
-import { TextChunkSource } from '../../../client/TextRange.ts';
-import { DependentExpression } from '../../../expression/DependentExpression.ts';
-import { OutputChunkDefinition } from '../OutputChunkDefinition.ts';
-import { ReferenceChunkDefinition } from '../ReferenceChunkDefinition.ts';
-import { StaticTextChunkDefinition } from '../StaticTextChunkDefinition.ts';
-import { TranslationChunkDefinition } from '../TranslationChunkDefinition.ts';
-import { AnyTextRangeDefinition } from './TextRangeDefinition.ts';
-
-interface TextChunkDefinitionOptions {
-    readonly isTranslated?: true;
-}
-export declare abstract class TextChunkDefinition<Source extends TextChunkSource> extends DependentExpression<'string'> {
-    abstract readonly source: Source;
-    readonly stringValue?: string;
-    constructor(context: AnyTextRangeDefinition, expression: string, options?: TextChunkDefinitionOptions);
-}
-export type AnyTextChunkDefinition = OutputChunkDefinition | ReferenceChunkDefinition | StaticTextChunkDefinition | TranslationChunkDefinition;
-export {};

package/src/XFormDataType.ts

@@ -1,64 +0,0 @@
-import type { CollectionValues } from '@getodk/common/types/collections/CollectionValues.ts';
-
-/**
- * Like JavaRosa. Presumably for explicit types which aren't impelemnted?
- */
-const UNSUPPORTED_DATA_TYPE = 'UNSUPPORTED';
-
-export type UnsupportedDataType = typeof UNSUPPORTED_DATA_TYPE;
-
-/**
- * Like JavaRosa. Presumably for e.g. groups with explicit binds (`relevant` etc)?
- */
-const NULL_DATA_TYPE = 'NULL';
-
-export type NullDataType = typeof NULL_DATA_TYPE;
-
-/**
- * As in ODK XForms Spec.
- *
- * TODO: it's unclear why JavaRosa's `DataType` hews closely to the spec, but
- * has certain differences (e.g. string -> TEXT, int -> INTEGER). It's also
- * not immediately clear how additive types like CHOICE and MULTIPLE_ITEMS
- * square with the underlying spec types.
- */
-export const XFORM_SPEC_DATA_TYPES = [
-	'string',
-	'int',
-	'boolean',
-	'decimal',
-	'date',
-	'time',
-	'dateTime',
-	'geopoint',
-	'geotrace',
-	'geoshape',
-	'binary',
-	'barcode',
-	'intent',
-] as const;
-
-const isSupportedDataType = (bindType: string): bindType is XFormSpecDataType =>
-	XFORM_SPEC_DATA_TYPES.includes(bindType as XFormSpecDataType);
-
-export type XFormSpecDataType = CollectionValues<typeof XFORM_SPEC_DATA_TYPES>;
-
-export type XFormDataType = NullDataType | UnsupportedDataType | XFormSpecDataType;
-
-const DEFAULT_XFORM_DATA_TYPE = 'string';
-
-export type DefaultXFormDataType = typeof DEFAULT_XFORM_DATA_TYPE;
-
-// TODO: groups -> NULL?
-// TODO: XSD namespace
-export const bindDataType = (bindType: string | null): XFormDataType => {
-	if (bindType == null) {
-		return DEFAULT_XFORM_DATA_TYPE;
-	}
-
-	if (isSupportedDataType(bindType)) {
-		return bindType;
-	}
-
-	return UNSUPPORTED_DATA_TYPE;
-};

package/src/client/StringNode.ts

@@ -1,52 +0,0 @@
-import type { InputDefinition } from '../body/control/InputDefinition.ts';
-import type { LeafNodeDefinition } from '../model/LeafNodeDefinition.ts';
-import type { BaseNode, BaseNodeState } from './BaseNode.ts';
-import type { NodeAppearances } from './NodeAppearances.ts';
-import type { RootNode } from './RootNode.ts';
-import type { GeneralParentNode } from './hierarchy.ts';
-import type { LeafNodeValidationState } from './validation.ts';
-
-export interface StringNodeState extends BaseNodeState {
-	get children(): null;
-	get valueOptions(): null;
-
-	/**
-	 * Reflects the current value of a {@link StringNode}. This value may be
-	 * populated when a form is loaded, and it may be updated by certain
-	 * computations defined by the form. It may also be updated by a client, using
-	 * the {@link StringNode.setValue} method.
-	 */
-	get value(): string;
-}
-
-export interface StringDefinition extends LeafNodeDefinition {
-	readonly bodyElement: InputDefinition;
-}
-
-export type StringNodeAppearances = NodeAppearances<StringDefinition>;
-
-/**
- * A node which can be assigned a string/text value. A string node **MAY**
- * correspond to form field defined as an XForms `<input>`, which a user-facing
- * client would likely present for a user to fill. It may not correspond to an
- * `<input>`, or necessarily have any presentational implications for a client
- * (for instance if the node is bound to an XForms `calculate` expression).
- */
-export interface StringNode extends BaseNode {
-	readonly nodeType: 'string';
-	readonly appearances: StringNodeAppearances;
-	readonly definition: StringDefinition;
-	readonly root: RootNode;
-	readonly parent: GeneralParentNode;
-	readonly currentState: StringNodeState;
-	readonly validationState: LeafNodeValidationState;
-
-	/**
-	 * For use by a client to update the value of a string node.
-	 *
-	 * @todo [how] should we express write restrictions to a client? E.g. what
-	 * happens when a string node is readonly, and a client attempts to call this
-	 * method?
-	 */
-	setValue(value: string): RootNode;
-}

package/src/instance/internal-api/SubscribableDependency.ts

@@ -1,61 +0,0 @@
-import type { ReactiveScope } from '../../lib/reactivity/scope.ts';
-import type { EvaluationContext } from './EvaluationContext.ts';
-
-/**
- * Provides a common interface to explicitly establish a reactive subscription
- * to a form node, regardless of which node-specific details might trigger
- * reactive updates. This is primarily intended for use in coordination with a
- * node's {@link EvaluationContext} interface, so that computed expression
- * evaluations can be re-executed when their dependencies update, without
- * requiring a given evaluation to handle node-specific logic to determine
- * when/whether updates have occurred.
- *
- * @example Given a form with these bindings:
- *
- * ```xml
- * <bind nodeset="/data/field-1" />
- * <bind nodeset="/data/field-2" type="int" />
- * <bind nodeset="/data/group-a" relevant="/data/field-1 != ''" />
- * <bind nodeset="/data/group-a/field-a-1" calculate="/data/field-2 * 2" />
- * ```
- *
- * The field `/data/group-a/field-a-1`'s calculate has two dependencies:
- *
- * - `/data-field-2` (explicit)
- * - `/data/group-a` (implicit: non-relevance is inherited)
- *
- * (This is an oversimplification, but it helps to illustrate the concept.)
- *
- * The first dependency's subscription is clearly concerned with that leaf
- * node's value. In which case, that node's `subscribe` method should react to
- * updates to its value (e.g. its `currentState.value` or the internal reactive
- * representation thereof).
- *
- * Whereas the second dependency has no value (no parent nodes do); instead, the
- * subscription would be concerned with that node's relevance. In which case,
- * that node's `subscribe` method should react to updates to its relevance state
- * (e.g. its `currentState.relevant` or the internal reactive represeentation
- * thereof).
- *
- * @example Given a form with:
- *
- * ```xml
- * <!-- model -->
- * <bind nodeset="/data/repeat-a/field-a-1" calculate="position(..)" />
- * <!-- body -->
- * <repeat nodeset="/data/repeat-a" />
- * ```
- *
- * The field `/data/repeat-a/field-a-1` has a dependency on its containing
- * repeat instance. That node also doesn't have a value, and here the dynamic
- * aspect of the dependency is the node's current position. Here the node's
- * `subscribe` method should react to changes in its position (likely indirectly
- * by reading its `contextReference`).
- *
- * @see {@link EvaluationContext}
- * @see {@link EvaluationContext.contextReference}
- */
-export interface SubscribableDependency {
-	readonly scope: ReactiveScope;
-	readonly subscribe: VoidFunction;
-}

package/src/model/BindDefinition.ts

@@ -1,106 +0,0 @@
-import type { XFormDataType } from '../XFormDataType.ts';
-import { bindDataType } from '../XFormDataType.ts';
-import type { XFormDefinition } from '../XFormDefinition.ts';
-import { DependencyContext } from '../expression/DependencyContext.ts';
-import type { DependentExpression } from '../expression/DependentExpression.ts';
-import { MessageDefinition } from '../parse/text/MessageDefinition.ts';
-import { BindComputation } from './BindComputation.ts';
-import type { BindElement } from './BindElement.ts';
-import type { ModelDefinition } from './ModelDefinition.ts';
-
-export class BindDefinition extends DependencyContext {
-	readonly bindType: string | null;
-	readonly dataType: XFormDataType;
-	readonly parentNodeset: string | null;
-
-	readonly calculate: BindComputation<'calculate'> | null;
-	readonly readonly: BindComputation<'readonly'>;
-	readonly relevant: BindComputation<'relevant'>;
-	readonly required: BindComputation<'required'>;
-
-	// According to
-	//
-	// this is not stored in the DAG. In contrast, we do compute constraint
-	// dependencies, but self-references are ignored (handled by `BindComputation`
-	// and its `DependentExpression` parent class).
-	/**
-	 * Diverges from {@link https://github.com/getodk/javarosa/blob/059321160e6f8dbb3e81d9add61d68dd35b13cc8/dag.md | JavaRosa's}, which excludes `constraint` expressions. We compute `constraint` dependencies like the other <bind> computation expressions, but explicitly ignore self-references (this is currently handled by {@link BindComputation}, via its {@link DependentExpression} parent class).
-	 */
-	readonly constraint: BindComputation<'constraint'>;
-
-	readonly constraintMsg: MessageDefinition<'constraintMsg'> | null;
-	readonly requiredMsg: MessageDefinition<'requiredMsg'> | null;
-
-	// TODO: it is unclear whether this will need to be supported.
-	// https://github.com/getodk/collect/issues/3758 mentions deprecation.
-	readonly saveIncomplete: BindComputation<'saveIncomplete'>;
-
-	// TODO: these are deferred until prioritized
-	// readonly preload: string | null;
-	// readonly preloadParams: string | null;
-	// readonly 'max-pixels': string | null;
-
-	protected _parentBind: BindDefinition | null | undefined;
-
-	get parentBind(): BindDefinition | null {
-		let bind = this._parentBind;
-
-		if (typeof bind === 'undefined') {
-			const { parentNodeset } = this;
-
-			if (parentNodeset == null) {
-				bind = null;
-			} else {
-				bind = this.form.model.binds.get(parentNodeset) ?? null;
-			}
-
-			this._parentBind = bind;
-		}
-
-		return bind;
-	}
-
-	// DependencyContext
-	get reference(): string {
-		return this.nodeset;
-	}
-
-	get parentReference(): string | null {
-		return this.parentNodeset;
-	}
-
-	constructor(
-		readonly form: XFormDefinition,
-		protected readonly model: ModelDefinition,
-		readonly nodeset: string,
-		readonly bindElement: BindElement
-	) {
-		super();
-
-		const bindType = (this.bindType = bindElement.getAttribute('type'));
-
-		this.dataType = bindDataType(bindType);
-
-		const parentNodeset = nodeset.replace(/\/[^/]+$/, '');
-
-		this.parentNodeset = parentNodeset.length > 1 ? parentNodeset : null;
-		this.calculate = BindComputation.forExpression(this, 'calculate');
-		this.readonly = BindComputation.forExpression(this, 'readonly');
-		this.relevant = BindComputation.forExpression(this, 'relevant');
-		this.required = BindComputation.forExpression(this, 'required');
-		this.constraint = BindComputation.forExpression(this, 'constraint');
-		this.saveIncomplete = BindComputation.forExpression(this, 'saveIncomplete');
-		this.constraintMsg = MessageDefinition.from(this, 'constraintMsg');
-		this.requiredMsg = MessageDefinition.from(this, 'requiredMsg');
-
-		// this.preload = BindComputation.forExpression(this, 'preload');
-		// this.preloadParams = BindComputation.forExpression(this, 'preloadParams');
-		// this['max-pixels'] = BindComputation.forExpression(this, 'max-pixels');
-	}
-
-	toJSON() {
-		const { form, model, /* modelElement, */ bindElement, ...rest } = this;
-
-		return rest;
-	}
-}

package/src/model/ModelDefinition.ts

@@ -1,19 +0,0 @@
-import type { XFormDefinition } from '../XFormDefinition.ts';
-import { ModelBindMap } from './ModelBindMap.ts';
-import { RootDefinition } from './RootDefinition.ts';
-
-export class ModelDefinition {
-	readonly binds: ModelBindMap;
-	readonly root: RootDefinition;
-
-	constructor(readonly form: XFormDefinition) {
-		this.binds = ModelBindMap.fromModel(this);
-		this.root = new RootDefinition(form, this, form.body.classes);
-	}
-
-	toJSON() {
-		const { form, ...rest } = this;
-
-		return rest;
-	}
-}

package/src/parse/TODO.md

@@ -1,3 +0,0 @@
-# @getodk/xforms-engine: parse
-
-Presence of this file is intended to be temporary! It is here to signal the intent to make a clearer distinction between the parsing and runtime aspects of the engine implementation. For entirely pragmatic purposes, newly introduced will be added here to start. We can decide in review if we want to move the rest into this directory right away. (For existing/untouched code, this would just mean moving the files and updating imports to reflect that. Small effort, lots of potential diff noise.)

package/src/parse/text/StaticTextChunkDefinition.ts

@@ -1,19 +0,0 @@
-import { TextChunkDefinition } from './abstract/TextChunkDefinition.ts';
-import type { AnyTextRangeDefinition } from './abstract/TextRangeDefinition.ts';
-
-export type StaticTextChunkSourceNode = Attr | Text;
-
-export class StaticTextChunkDefinition extends TextChunkDefinition<'static'> {
-	static from(context: AnyTextRangeDefinition, stringValue: string): StaticTextChunkDefinition {
-		return new this(context, stringValue);
-	}
-
-	readonly source = 'static';
-
-	private constructor(
-		context: AnyTextRangeDefinition,
-		override readonly stringValue: string
-	) {
-		super(context, 'null');
-	}
-}

package/src/parse/text/abstract/TextChunkDefinition.ts

@@ -1,38 +0,0 @@
-import type { TextChunkSource } from '../../../client/TextRange.ts';
-import { DependentExpression } from '../../../expression/DependentExpression.ts';
-import type { OutputChunkDefinition } from '../OutputChunkDefinition.ts';
-import type { ReferenceChunkDefinition } from '../ReferenceChunkDefinition.ts';
-import type { StaticTextChunkDefinition } from '../StaticTextChunkDefinition.ts';
-import type { TranslationChunkDefinition } from '../TranslationChunkDefinition.ts';
-import type { AnyTextRangeDefinition } from './TextRangeDefinition.ts';
-
-interface TextChunkDefinitionOptions {
-	readonly isTranslated?: true;
-}
-
-export abstract class TextChunkDefinition<
-	Source extends TextChunkSource,
-> extends DependentExpression<'string'> {
-	abstract readonly source: Source;
-	readonly stringValue?: string;
-
-	constructor(
-		context: AnyTextRangeDefinition,
-		expression: string,
-		options: TextChunkDefinitionOptions = {}
-	) {
-		super(context, 'string', expression, {
-			semanticDependencies: {
-				translations: options.isTranslated,
-			},
-			ignoreContextReference: true,
-		});
-	}
-}
-
-// prettier-ignore
-export type AnyTextChunkDefinition =
-	| OutputChunkDefinition
-	| ReferenceChunkDefinition
-	| StaticTextChunkDefinition
-	| TranslationChunkDefinition;