@getodk/xforms-engine 0.3.0 → 0.5.0

package/src/parse/model/SecondaryInstance/sources/ExternalSecondaryInstanceResource.ts

@@ -0,0 +1,222 @@
+import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
+import type { MissingResourceBehavior } from '../../../../client/constants.ts';
+import type { FetchResource, FetchResourceResponse } from '../../../../client/resources.ts';
+import { ErrorProductionDesignPendingError } from '../../../../error/ErrorProductionDesignPendingError.ts';
+import { FormAttachmentResource } from '../../../attachments/FormAttachmentResource.ts';
+import type { ExternalSecondaryInstanceSourceFormat } from './SecondaryInstanceSource.ts';
+
+const assertResponseSuccess = (resourceURL: JRResourceURL, response: FetchResourceResponse) => {
+	const { ok = true, status = 200 } = response;
+
+	if (!ok || status !== 200) {
+		throw new ErrorProductionDesignPendingError(`Failed to load ${resourceURL.href}`);
+	}
+};
+
+const stripContentTypeCharset = (contentType: string): string => {
+	return contentType.replace(/;charset=.*$/, '');
+};
+
+const getResponseContentType = (response: FetchResourceResponse): string | null => {
+	const { headers } = response;
+
+	if (headers == null) {
+		return null;
+	}
+
+	const contentType = headers.get('content-type');
+
+	if (contentType != null) {
+		return stripContentTypeCharset(contentType);
+	}
+
+	if (headers instanceof Headers) {
+		return contentType;
+	}
+
+	for (const [header, value] of headers) {
+		if (header.toLowerCase() === 'content-type') {
+			return stripContentTypeCharset(value);
+		}
+	}
+
+	return null;
+};
+
+interface ExternalSecondaryInstanceResourceMetadata<
+	Format extends ExternalSecondaryInstanceSourceFormat = ExternalSecondaryInstanceSourceFormat,
+> {
+	readonly contentType: string;
+	readonly format: Format;
+}
+
+const inferSecondaryInstanceResourceMetadata = (
+	resourceURL: JRResourceURL,
+	contentType: string | null,
+	data: string
+): ExternalSecondaryInstanceResourceMetadata => {
+	const url = resourceURL.href;
+
+	let format: ExternalSecondaryInstanceSourceFormat | null = null;
+
+	if (url.endsWith('.xml') && data.startsWith('<')) {
+		format = 'xml';
+	} else if (url.endsWith('.csv')) {
+		format = 'csv';
+	} else if (url.endsWith('.geojson') && data.startsWith('{')) {
+		format = 'geojson';
+	}
+
+	if (format == null) {
+		throw new ErrorProductionDesignPendingError(
+			`Failed to infer external secondary instance format/content type for resource ${url} (response content type: ${contentType}, data: ${data})`
+		);
+	}
+
+	return {
+		contentType: contentType ?? 'text/plain',
+		format,
+	};
+};
+
+const detectSecondaryInstanceResourceMetadata = (
+	resourceURL: JRResourceURL,
+	response: FetchResourceResponse,
+	data: string
+): ExternalSecondaryInstanceResourceMetadata => {
+	const contentType = getResponseContentType(response);
+
+	if (contentType == null || contentType === 'text/plain') {
+		return inferSecondaryInstanceResourceMetadata(resourceURL, contentType, data);
+	}
+
+	let format: ExternalSecondaryInstanceSourceFormat | null = null;
+
+	switch (contentType) {
+		case 'text/csv':
+			format = 'csv';
+			break;
+
+		case 'application/geo+json':
+			format = 'geojson';
+			break;
+
+		case 'text/xml':
+			format = 'xml';
+			break;
+	}
+
+	if (format == null) {
+		throw new ErrorProductionDesignPendingError(
+			`Failed to detect external secondary instance format for resource ${resourceURL.href} (response content type: ${contentType}, data: ${data})`
+		);
+	}
+
+	return {
+		contentType,
+		format,
+	};
+};
+
+interface MissingResourceResponse extends FetchResourceResponse {
+	readonly status: 404;
+}
+
+export interface ExternalSecondaryInstanceResourceLoadOptions {
+	readonly fetchResource: FetchResource<JRResourceURL>;
+	readonly missingResourceBehavior: MissingResourceBehavior;
+}
+
+type LoadedExternalSecondaryInstanceResource = {
+	[Format in ExternalSecondaryInstanceSourceFormat]: ExternalSecondaryInstanceResource<Format>;
+}[ExternalSecondaryInstanceSourceFormat];
+
+interface ExternalSecondaryInstanceResourceOptions {
+	readonly isExplicitlyBlank?: boolean;
+}
+
+export class ExternalSecondaryInstanceResource<
+	Format extends ExternalSecondaryInstanceSourceFormat = ExternalSecondaryInstanceSourceFormat,
+> extends FormAttachmentResource<'secondary-instance'> {
+	private static isMissingResource(
+		response: FetchResourceResponse
+	): response is MissingResourceResponse {
+		return response.status === 404;
+	}
+
+	private static createBlankResource(
+		instanceId: string,
+		resourceURL: JRResourceURL,
+		response: MissingResourceResponse,
+		options: ExternalSecondaryInstanceResourceLoadOptions
+	) {
+		if (options.missingResourceBehavior === 'BLANK') {
+			return new this(
+				response.status,
+				instanceId,
+				resourceURL,
+				{
+					format: 'xml',
+					contentType: 'text/xml',
+				},
+				'',
+				{ isExplicitlyBlank: true }
+			);
+		}
+
+		throw new ErrorProductionDesignPendingError(
+			`Failed to load resource: ${resourceURL.href}: resource is missing (status: ${response.status})`
+		);
+	}
+
+	static async load(
+		instanceId: string,
+		resourceURL: JRResourceURL,
+		options: ExternalSecondaryInstanceResourceLoadOptions
+	): Promise<LoadedExternalSecondaryInstanceResource> {
+		const response = await options.fetchResource(resourceURL);
+
+		if (this.isMissingResource(response)) {
+			return this.createBlankResource(instanceId, resourceURL, response, options);
+		}
+
+		assertResponseSuccess(resourceURL, response);
+
+		const data = await response.text();
+		const metadata = detectSecondaryInstanceResourceMetadata(resourceURL, response, data);
+
+		return new this(response.status ?? null, instanceId, resourceURL, metadata, data, {
+			isExplicitlyBlank: false,
+		}) satisfies ExternalSecondaryInstanceResource as LoadedExternalSecondaryInstanceResource;
+	}
+
+	readonly format: Format;
+	readonly isBlank: boolean;
+
+	private constructor(
+		readonly responseStatus: number | null,
+		readonly instanceId: string,
+		resourceURL: JRResourceURL,
+		metadata: ExternalSecondaryInstanceResourceMetadata<Format>,
+		data: string,
+		options: ExternalSecondaryInstanceResourceOptions
+	) {
+		const { contentType, format } = metadata;
+
+		super('secondary-instance', resourceURL, contentType, data);
+
+		this.format = format;
+
+		if (data === '') {
+			if (options.isExplicitlyBlank) {
+				this.isBlank = true;
+			} else {
+				throw new ErrorProductionDesignPendingError(
+					`Failed to load blank external secndary instance ${resourceURL.href}`
+				);
+			}
+		} else {
+			this.isBlank = false;
+		}
+	}
+}

package/src/parse/model/SecondaryInstance/sources/ExternalSecondaryInstanceSource.ts

@@ -0,0 +1,22 @@
+import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
+import type { DOMSecondaryInstanceElement } from '../../../XFormDOM.ts';
+import type { ExternalSecondaryInstanceResource } from './ExternalSecondaryInstanceResource.ts';
+import type { ExternalSecondaryInstanceSourceFormat } from './SecondaryInstanceSource.ts';
+import { SecondaryInstanceSource } from './SecondaryInstanceSource.ts';
+
+export abstract class ExternalSecondaryInstanceSource<
+	Format extends ExternalSecondaryInstanceSourceFormat = ExternalSecondaryInstanceSourceFormat,
+> extends SecondaryInstanceSource<Format> {
+	override readonly resourceURL: JRResourceURL;
+
+	constructor(
+		domElement: DOMSecondaryInstanceElement,
+		protected readonly resource: ExternalSecondaryInstanceResource<Format>
+	) {
+		const { format, instanceId, resourceURL } = resource;
+
+		super(format, instanceId, resourceURL, domElement);
+
+		this.resourceURL = resourceURL;
+	}
+}

package/src/parse/model/SecondaryInstance/sources/GeoJSONExternalSecondaryInstance.ts

@@ -0,0 +1,414 @@
+import { XFORMS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { assertUnknownArray } from '@getodk/common/lib/type-assertions/assertUnknownArray.ts';
+import type { UnknownObject } from '@getodk/common/lib/type-assertions/assertUnknownObject.ts';
+import { assertUnknownObject } from '@getodk/common/lib/type-assertions/assertUnknownObject.ts';
+import type {
+	GeoJsonProperties as BaseGeoJSONProperties,
+	LineString as BaseLineString,
+	Point as BasePoint,
+	Polygon as BasePolygon,
+	Feature as GeoJSONFeature,
+	FeatureCollection as GeoJSONFeatureCollection,
+} from 'geojson';
+import { ErrorProductionDesignPendingError } from '../../../../error/ErrorProductionDesignPendingError.ts';
+import { StaticAttribute } from '../../../../integration/xpath/static-dom/StaticAttribute.ts';
+import { StaticElement } from '../../../../integration/xpath/static-dom/StaticElement.ts';
+import { StaticText } from '../../../../integration/xpath/static-dom/StaticText.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceRootDefinition } from '../SecondaryInstanceRootDefinition.ts';
+import { ExternalSecondaryInstanceSource } from './ExternalSecondaryInstanceSource.ts';
+
+const FEATURE_COLLECTION = 'FeatureCollection';
+type FEATURE_COLLECTION = typeof FEATURE_COLLECTION;
+
+const FEATURE = 'Feature';
+type FEATURE = typeof FEATURE;
+
+const POINT = 'Point';
+type POINT = typeof POINT;
+
+const LINE_STRING = 'LineString';
+type LINE_STRING = typeof LINE_STRING;
+
+const POLYGON = 'Polygon';
+type POLYGON = typeof POLYGON;
+
+type SupportedGeometryType = LINE_STRING | POINT | POLYGON;
+
+const SUPPORTED_TYPES = new Set<SupportedGeometryType>([POINT, LINE_STRING, POLYGON]);
+
+const SUPPORTED_TYPES_MESSAGE = 'Only Points, LineStrings and Polygons are currently supported';
+
+type LongLatCoordinates = readonly [longitude: number, latitude: number];
+
+interface UnknownCoordinatesObject {
+	readonly coordinates: unknown;
+}
+
+// prettier-ignore
+type ExtensibleBaseGeoJSONType<T> =
+	T extends UnknownCoordinatesObject
+		? Readonly<Omit<T, 'coordinates'>>
+		: Readonly<T>;
+
+interface Point extends ExtensibleBaseGeoJSONType<BasePoint> {
+	readonly coordinates: LongLatCoordinates;
+}
+
+type LineStringCoordinates = readonly LongLatCoordinates[];
+
+interface LineString extends ExtensibleBaseGeoJSONType<BaseLineString> {
+	readonly coordinates: LineStringCoordinates;
+}
+
+// prettier-ignore
+type PolygonCoordinates =
+	| readonly []
+	| readonly [LineStringCoordinates];
+
+interface Polygon extends ExtensibleBaseGeoJSONType<BasePolygon> {
+	readonly coordinates: PolygonCoordinates;
+}
+
+// prettier-ignore
+type SupportedGeometry =
+	| LineString
+	| Point
+	| Polygon;
+
+interface UnparsedGeometry<Type extends SupportedGeometryType> {
+	readonly type: Type;
+	readonly coordinates: readonly unknown[];
+}
+
+type UnknownGeometry = {
+	[Type in SupportedGeometryType]: UnparsedGeometry<Type>;
+}[SupportedGeometryType];
+
+/**
+ * This is a stricter variant of {@link BaseGeoJSONProperties}.
+ */
+type GeoJSONProperties = UnknownObject;
+
+/**
+ * This is our supported variant/subset of {@link GeoJSONFeature} where:
+ *
+ * - {@link geometry} is parsed/validated to be one of our
+ *   {@link SupportedGeometry | supported geometries}
+ *
+ * - all properties and non-primitive property values are deeply `readonly`
+ */
+interface Feature {
+	readonly type: FEATURE;
+	readonly geometry: SupportedGeometry;
+	readonly id?: number | string | undefined;
+
+	/**
+	 * Perhaps surprising: this property is required by the
+	 * {@link https://datatracker.ietf.org/doc/html/rfc7946#section-3.2 | GeoJSON spec}!
+	 */
+	readonly properties: GeoJSONProperties | null;
+}
+
+/**
+ * This is our supported variant/subset of {@link GeoJSONFeatureCollection}, as
+ * described for {@link Feature}.
+ */
+interface FeatureCollection {
+	readonly type: FEATURE_COLLECTION;
+	readonly features: readonly Feature[];
+}
+
+type AssertLongLatCoordinates = (data: unknown) => asserts data is LongLatCoordinates;
+
+const assertLongLatCoordinates: AssertLongLatCoordinates = (data) => {
+	assertUnknownArray(data);
+
+	const [longitude, latitude, ...rest] = data;
+
+	if (typeof longitude === 'number' && typeof latitude === 'number' && rest.length === 0) {
+		return;
+	}
+
+	throw new ErrorProductionDesignPendingError(
+		`Only ${POINT}s with latitude and longitude are currently supported`
+	);
+};
+
+type AssertUnknownGeometry = (value: unknown) => asserts value is UnknownGeometry;
+
+const assertUnknownGeometry: AssertUnknownGeometry = (value) => {
+	assertUnknownObject(value);
+
+	if (!SUPPORTED_TYPES.has(value.type as SupportedGeometryType)) {
+		throw new ErrorProductionDesignPendingError(SUPPORTED_TYPES_MESSAGE);
+	}
+
+	assertUnknownArray(value.coordinates);
+};
+
+type AssertSupportedGeometry = (value: unknown) => asserts value is SupportedGeometry;
+
+const assertSupportedGeometry: AssertSupportedGeometry = (value) => {
+	assertUnknownGeometry(value);
+
+	switch (value.type) {
+		case LINE_STRING:
+			value.coordinates.forEach(assertLongLatCoordinates);
+			break;
+
+		case POINT:
+			assertLongLatCoordinates(value.coordinates);
+			break;
+
+		case POLYGON: {
+			const [coordinates, ...rest] = value.coordinates;
+
+			if (coordinates == null) {
+				return;
+			}
+
+			if (rest.length > 0) {
+				throw new ErrorProductionDesignPendingError(
+					`Unsupported ${POLYGON}: multiple sets of coordinates`
+				);
+			}
+
+			assertUnknownArray(coordinates);
+			coordinates.forEach(assertLongLatCoordinates);
+
+			break;
+		}
+
+		default:
+			throw new UnreachableError(value);
+	}
+};
+
+type AssertFeature = (value: unknown) => asserts value is Feature;
+
+const assertFeature: AssertFeature = (value) => {
+	assertUnknownObject(value);
+
+	const { geometry, type, id, properties } = value;
+
+	if (type !== FEATURE) {
+		throw new ErrorProductionDesignPendingError(
+			`Expected Feature.type ${FEATURE}, got ${String(type)}`
+		);
+	}
+
+	assertSupportedGeometry(geometry);
+
+	if ('id' in value) {
+		const typeofId = typeof id;
+
+		switch (typeofId) {
+			case 'number':
+			case 'string':
+			case 'undefined':
+				break;
+
+			default:
+				throw new ErrorProductionDesignPendingError(
+					`Unexpected type of feature id property: ${typeofId}`
+				);
+		}
+	}
+
+	// Note: atypical strict check for `null` value! The `properties` key is
+	// required per
+	if (properties === null) {
+		return;
+	}
+
+	assertUnknownObject(properties);
+};
+
+type AssertFeatureCollection = (value: unknown) => asserts value is FeatureCollection;
+
+const assertFeatureCollection: AssertFeatureCollection = (value) => {
+	assertUnknownObject(value);
+
+	const { type, features } = value;
+
+	if (type !== FEATURE_COLLECTION) {
+		throw new ErrorProductionDesignPendingError(
+			`Expected FeatureCollection.type ${FEATURE_COLLECTION}, got ${String(type)}`
+		);
+	}
+
+	assertUnknownArray(features);
+
+	features.forEach(assertFeature);
+};
+
+type SerializedCoordinates = `${LongLatCoordinates[1]} ${LongLatCoordinates[0]} 0 0`;
+
+const serializeCoordinates = (coordinates: LongLatCoordinates): SerializedCoordinates => {
+	const [longitude, latitude] = coordinates;
+
+	return `${latitude} ${longitude} 0 0`;
+};
+
+class GeoJSONSecondaryInstanceFeatureGeometryElement extends StaticElement {
+	static from(
+		parent: StaticElement,
+		feature: Feature
+	): GeoJSONSecondaryInstanceFeatureGeometryElement {
+		const { geometry } = feature;
+
+		switch (geometry.type) {
+			case 'LineString':
+				return new this(parent, geometry.coordinates);
+
+			case 'Point':
+				return new this(parent, [geometry.coordinates]);
+
+			case 'Polygon':
+				return new this(parent, geometry.coordinates[0] ?? []);
+
+			default:
+				throw new UnreachableError(geometry);
+		}
+	}
+
+	constructor(parent: StaticElement, points: readonly LongLatCoordinates[]) {
+		const values = points.map(serializeCoordinates);
+		const value = values.join('; ');
+
+		super(
+			parent,
+			() => [],
+			(self) => [new StaticText(self, value)],
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'geometry',
+			}
+		);
+	}
+}
+
+class GeoJSONSecondaryInstanceFeaturePropertyElement extends StaticElement {
+	static *buildPropertyElements(
+		parent: StaticElement,
+		feature: Feature
+	): Iterable<GeoJSONSecondaryInstanceFeaturePropertyElement> {
+		const { properties } = feature;
+
+		if (properties == null) {
+			return [];
+		}
+
+		const { id: propertiesId, ...nonIdProperties } = properties;
+		const { id = propertiesId } = feature;
+
+		if (id !== undefined) {
+			yield new this(parent, 'id', String(id));
+		}
+
+		for (const [propertyName, propertyValue] of Object.entries(nonIdProperties)) {
+			yield new this(parent, propertyName, String(propertyValue));
+		}
+	}
+
+	constructor(parent: StaticElement, propertyName: string, propertyValue: string) {
+		super(
+			parent,
+			() => [],
+			(self) => [new StaticText(self, propertyValue)],
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: propertyName,
+			}
+		);
+	}
+}
+
+class GeoJSONSecondaryInstanceFeatureItemElement extends StaticElement {
+	constructor(parent: StaticElement, feature: Feature) {
+		super(
+			parent,
+			() => [],
+			(self) => {
+				const geometry = GeoJSONSecondaryInstanceFeatureGeometryElement.from(self, feature);
+				const properties = GeoJSONSecondaryInstanceFeaturePropertyElement.buildPropertyElements(
+					self,
+					feature
+				);
+
+				return [geometry, ...properties];
+			},
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'item',
+			}
+		);
+	}
+}
+
+class GeoJSONSecondaryInstanceRootElement extends StaticElement {
+	constructor(parent: StaticElement, featureCollection: FeatureCollection) {
+		super(
+			parent,
+			() => [],
+			(self) => {
+				return featureCollection.features.map((feature) => {
+					return new GeoJSONSecondaryInstanceFeatureItemElement(self, feature);
+				});
+			},
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'root',
+			}
+		);
+	}
+}
+
+class GeoJSONExternalSecondaryInstanceDocumentElement extends SecondaryInstanceRootDefinition {
+	constructor(
+		instanceId: string,
+		parent: GeoJSONExternalSecondaryInstanceDefinition,
+		featureCollection: FeatureCollection
+	) {
+		super(
+			parent,
+			(self) => [
+				new StaticAttribute(self, {
+					namespaceURI: XFORMS_NAMESPACE_URI,
+					localName: 'id',
+					value: instanceId,
+				}),
+			],
+			(self) => [new GeoJSONSecondaryInstanceRootElement(self, featureCollection)],
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'instance',
+			}
+		);
+	}
+}
+
+class GeoJSONExternalSecondaryInstanceDefinition extends SecondaryInstanceDefinition {
+	constructor(instanceId: string, featureCollection: FeatureCollection) {
+		super((self) => {
+			return new GeoJSONExternalSecondaryInstanceDocumentElement(
+				instanceId,
+				self,
+				featureCollection
+			);
+		});
+	}
+}
+
+export class GeoJSONExternalSecondaryInstanceSource extends ExternalSecondaryInstanceSource<'geojson'> {
+	parseDefinition(): SecondaryInstanceDefinition {
+		const { data } = this.resource;
+		const value = JSON.parse(data) as unknown;
+
+		assertFeatureCollection(value);
+
+		return new GeoJSONExternalSecondaryInstanceDefinition(this.instanceId, value);
+	}
+}

package/src/parse/model/SecondaryInstance/sources/InternalSecondaryInstanceSource.ts

@@ -0,0 +1,19 @@
+import { parseStaticDocumentFromDOMSubtree } from '../../../shared/parseStaticDocumentFromDOMSubtree.ts';
+import type { DOMSecondaryInstanceElement } from '../../../XFormDOM.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceRootDefinition } from '../SecondaryInstanceRootDefinition.ts';
+import { SecondaryInstanceSource } from './SecondaryInstanceSource.ts';
+
+export class InternalSecondaryInstanceSource extends SecondaryInstanceSource<'internal'> {
+	constructor(instanceId: string, resourceURL: null, domElement: DOMSecondaryInstanceElement) {
+		super('internal', instanceId, resourceURL, domElement);
+	}
+
+	parseDefinition(): SecondaryInstanceDefinition {
+		return parseStaticDocumentFromDOMSubtree(
+			SecondaryInstanceDefinition,
+			SecondaryInstanceRootDefinition,
+			this.domElement
+		);
+	}
+}

package/src/parse/model/SecondaryInstance/sources/SecondaryInstanceSource.ts

@@ -0,0 +1,29 @@
+import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
+import type { DOMSecondaryInstanceElement } from '../../../XFormDOM.ts';
+import type { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+
+// prettier-ignore
+export type ExternalSecondaryInstanceSourceFormat =
+	| 'csv'
+	| 'geojson'
+	| 'xml';
+
+// prettier-ignore
+export type SecondaryInstanceSourceFormat =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| ExternalSecondaryInstanceSourceFormat
+	| 'internal'
+	| 'blank';
+
+export abstract class SecondaryInstanceSource<
+	Format extends SecondaryInstanceSourceFormat = SecondaryInstanceSourceFormat,
+> {
+	constructor(
+		readonly format: Format,
+		readonly instanceId: string,
+		readonly resourceURL: JRResourceURL | null,
+		readonly domElement: DOMSecondaryInstanceElement
+	) {}
+
+	abstract parseDefinition(): SecondaryInstanceDefinition;
+}