xpath: extract geotrace decoding (partial; prep for sharing logic)

This doesn’t introduce a codec, because the XPath call sites wouldn’t use it directly. But a hypothetical codec would presumably call into `fromEncodedGeotrace`.

Author: eyelidlessness

packages/xpath/src/functions/xforms/geo.ts

@@ -1,53 +1,9 @@
-import { pairwise } from 'itertools-ts/lib/single';
 import type { XPathNode } from '../../adapter/interface/XPathNode.ts';
 import { EvaluationContext } from '../../context/EvaluationContext.ts';
-import { JRCompatibleGeoValueError } from '../../error/JRCompatibleGeoValueError.ts';
 import type { EvaluableArgument } from '../../evaluator/functions/FunctionImplementation.ts';
 import { NumberFunction } from '../../evaluator/functions/NumberFunction.ts';
-import type { GeopointCoordinates } from '../../lib/geo/Geopoint.ts';
-import { geopointCodec } from '../../lib/geo/geopointCodec.ts';
-
-const evaluatePoints = <T extends XPathNode>(
-	context: EvaluationContext<T>,
-	expression: EvaluableArgument
-): GeopointCoordinates[] => {
-	const results = expression.evaluate(context);
-
-	const stringResults = [...results].map((result) => result.toString());
-	const geopointStrings = stringResults.flatMap((result) => {
-		const string = result.toString().trim();
-
-		return string.split(/\s*;\s*/);
-	});
-
-	return geopointStrings.map((string) => {
-		return geopointCodec.decodeValue(string);
-	});
-};
-
-interface Line {
-	readonly start: GeopointCoordinates;
-	readonly end: GeopointCoordinates;
-}
-
-const evaluateLines = <T extends XPathNode>(
-	context: EvaluationContext<T>,
-	expression: readonly EvaluableArgument[]
-): Line[] => {
-	const points = expression.flatMap((el) => evaluatePoints(context, el));
-	if (points.length < 2) {
-		throw new JRCompatibleGeoValueError();
-	}
-
-	return Array.from(pairwise(points)).map((line) => {
-		const [start, end] = line;
-
-		return {
-			start,
-			end,
-		};
-	});
-};
+import { Geotrace } from '../../lib/geo/Geotrace.ts';
+import type { GeotraceLine } from '../../lib/geo/GeotraceLine.ts';
 
 const EARTH_EQUATORIAL_RADIUS_METERS = 6_378_100;
 const PRECISION = 100;
@@ -70,7 +26,7 @@ const toAbsolutePrecision = (value: number, precision: number) => {
 	return Math.abs(toPrecision(value, precision));
 };
 
-const geodesicArea = (lines: readonly Line[]): number => {
+const geodesicArea = (lines: readonly GeotraceLine[]): number => {
 	const [firstLine, ...rest] = lines;
 	const lastLine = rest[rest.length - 1];
 
@@ -81,7 +37,7 @@ const geodesicArea = (lines: readonly Line[]): number => {
 	const { start } = firstLine;
 	const { end } = lastLine;
 
-	let shape: readonly Line[];
+	let shape: readonly GeotraceLine[];
 
 	if (start.latitude === end.latitude && start.longitude === end.longitude) {
 		shape = lines;
@@ -101,19 +57,24 @@ const geodesicArea = (lines: readonly Line[]): number => {
 	return (total * EARTH_EQUATORIAL_RADIUS_METERS * EARTH_EQUATORIAL_RADIUS_METERS) / 2;
 };
 
-export const area = new NumberFunction(
-	'area',
-	[{ arityType: 'required' }],
-	(context, [expression]) => {
-		const lines = evaluateLines(context, [expression!]);
+const evaluateArgumentValues = <T extends XPathNode>(
+	context: EvaluationContext<T>,
+	args: readonly EvaluableArgument[]
+): readonly string[] => {
+	const evaluations = args.flatMap((arg) => [...arg.evaluate(context)]);
 
-		const areaResult = geodesicArea(lines);
+	return evaluations.map((evaluation) => evaluation.toString());
+};
 
-		return toAbsolutePrecision(areaResult, PRECISION);
-	}
-);
+export const area = new NumberFunction('area', [{ arityType: 'required' }], (context, args) => {
+	const values = evaluateArgumentValues(context, args);
+	const { lines } = Geotrace.fromEncodedValues(values);
+	const areaResult = geodesicArea(lines);
+
+	return toAbsolutePrecision(areaResult, PRECISION);
+});
 
-const geodesicDistance = (line: Line): number => {
+const geodesicDistance = (line: GeotraceLine): number => {
 	const { start, end } = line;
 	const deltaLambda = toRadians(start.longitude - end.longitude);
 	const phi0 = toRadians(start.latitude);
@@ -140,7 +101,8 @@ export const distance = new NumberFunction(
 	'distance',
 	[{ arityType: 'required' }, { arityType: 'variadic' }],
 	(context, args) => {
-		const lines = evaluateLines(context, args);
+		const values = evaluateArgumentValues(context, args);
+		const { lines } = Geotrace.fromEncodedValues(values);
 		const distances = lines.map(geodesicDistance);
 
 		return toAbsolutePrecision(sum(distances), PRECISION);

packages/xpath/src/lib/geo/Geotrace.ts

@@ -0,0 +1,78 @@
+import { JRCompatibleGeoValueError } from '../../error/JRCompatibleGeoValueError.ts';
+import { Geopoint } from './Geopoint.ts';
+import { GeotraceLine } from './GeotraceLine.ts';
+
+export type GeotracePoints = readonly [Geopoint, Geopoint, ...Geopoint[]];
+
+const isGeotracePoints = (geopoints: readonly Geopoint[]): geopoints is GeotracePoints => {
+	return geopoints.length >= 2;
+};
+
+type AssertGeotracePoints = (geopoints: readonly Geopoint[]) => asserts geopoints is GeotracePoints;
+
+const assertGeotracePoints: AssertGeotracePoints = (geopoints) => {
+	if (!isGeotracePoints(geopoints)) {
+		throw new JRCompatibleGeoValueError();
+	}
+};
+
+const collectLines = (geopoints: GeotracePoints): readonly GeotraceLine[] => {
+	return geopoints.reduce((acc, geopoint, i) => {
+		if (i === 0) {
+			return acc;
+		}
+
+		// Non-null assertion safe: we ensure at least 2 points, and skip index 0.
+		const start = geopoints[i - 1]!;
+		const end = geopoint;
+
+		acc.push(
+			new GeotraceLine({
+				start,
+				end,
+			})
+		);
+
+		return acc;
+	}, Array<GeotraceLine>());
+};
+
+export class Geotrace {
+	static fromEncodedGeotrace(encoded: string): Geotrace {
+		const geopoints = encoded.split(/\s*;\s*/).map((value) => {
+			return Geopoint.fromNodeValue(value);
+		});
+
+		return this.fromGeopoints(geopoints);
+	}
+
+	static fromEncodedValues(values: readonly string[]): Geotrace {
+		const [head, ...tail] = values;
+
+		if (head == null) {
+			throw new JRCompatibleGeoValueError();
+		}
+
+		if (tail.length === 0) {
+			return this.fromEncodedGeotrace(head);
+		}
+
+		const geopoints = values.map((value) => {
+			return Geopoint.fromNodeValue(value);
+		});
+
+		return this.fromGeopoints(geopoints);
+	}
+
+	static fromGeopoints(geopoints: readonly Geopoint[]): Geotrace {
+		assertGeotracePoints(geopoints);
+
+		return new this(geopoints);
+	}
+
+	readonly lines: readonly GeotraceLine[];
+
+	private constructor(readonly geopoints: GeotracePoints) {
+		this.lines = collectLines(geopoints);
+	}
+}

packages/xpath/src/lib/geo/GeotraceLine.ts

@@ -0,0 +1,16 @@
+import type { Geopoint } from './Geopoint.ts';
+
+interface GeotraceLinePoints {
+	readonly start: Geopoint;
+	readonly end: Geopoint;
+}
+
+export class GeotraceLine implements GeotraceLinePoints {
+	readonly start: Geopoint;
+	readonly end: Geopoint;
+
+	constructor(points: GeotraceLinePoints) {
+		this.start = points.start;
+		this.end = points.end;
+	}
+}