@getodk/xpath 0.3.0 → 0.4.0

package/dist/lib/collections/sort.d.ts

@@ -1 +1 @@
-export declare const seededRandomize: <T>(values: readonly T[], seed?: number) => T[];
+export declare const seededRandomize: <T>(values: readonly T[], seed?: number | bigint) => T[];

package/dist/lib/geo/EncodeGeoValueStubError.d.ts

@@ -0,0 +1,4 @@
+import { GeoValueType } from './GeoValueCodec.ts';
+export declare class EncodeGeoValueStubError extends Error {
+    constructor(valueType: GeoValueType);
+}

package/dist/lib/geo/GeoValueCodec.d.ts

@@ -0,0 +1,33 @@
+export type GeoValueType = 'geopoint' | 'geoshape' | 'geotrace';
+export type GeoValueEncoder<RuntimeInputValue> = (input: RuntimeInputValue) => string;
+export type GeoValueDecoder<RuntimeValue> = (value: string) => RuntimeValue;
+/**
+ * @todo This is based on the same concepts expressed by the extant
+ * `@getodk/xforms-engine` `ValueCodec` class. It has been stripped down a more
+ * minimal interface, which might form a basis for shared responsibilities for
+ * value type support between packages. Its introduction now anticipates an
+ * imminent opportunity for sharing logic for the following data types:
+ *
+ * - {@link https://getodk.github.io/xforms-spec/#data-type:geopoint | geopoint}
+ * - {@link https://getodk.github.io/xforms-spec/#data-type:geotrace | geotrace}
+ * - {@link https://getodk.github.io/xforms-spec/#data-type:geoshape | geoshape}
+ *
+ * It makes sense to consider how we share this responsibility as we expand the
+ * Web Forms project's support for geo-related features, as there are mutually
+ * dependent responsibilities for encoding/decoding between the `@getodk/xpath`
+ * and `@getodk/xforms-engine` packages.
+ *
+ * It's also worth considering how we might address similar shared
+ * responsibilities for:
+ *
+ * - non-geo data types, and potential nuances of how those types are expected
+ *   to behave at the boundary between an ODK XForm's model, and the XPath
+ *   expressions operating on that model's nodes
+ * - XPath casting semantics, and whether/how that responsiblity intersects with
+ *   those ODK XForms data types
+ */
+export interface GeoValueCodec<V extends GeoValueType, RuntimeValue extends RuntimeInputValue, RuntimeInputValue = RuntimeValue> {
+    readonly valueType: V;
+    readonly encodeValue: GeoValueEncoder<RuntimeInputValue>;
+    readonly decodeValue: GeoValueDecoder<RuntimeValue>;
+}

package/dist/lib/geo/Geopoint.d.ts

@@ -0,0 +1,28 @@
+export interface GeopointCoordinates {
+    readonly latitude: number;
+    readonly longitude: number;
+}
+/**
+ * @todo this is derived from an interface that was introduced _internally_, to
+ * support the initial implementation of these related geo functions:
+ *
+ * - {@link https://getodk.github.io/xforms-spec/#fn:area | area}
+ * - {@link https://getodk.github.io/xforms-spec/#fn:distance | distance}
+ *
+ * It has been extracted here as a class as a potential basis for sharing
+ * geo-related functionality between Web Forms packages.
+ *
+ * **IMPORTANT:** it's likely that we'll reconsider how we model a
+ * {@link https://getodk.github.io/xforms-spec/#data-type:geopoint | geopoint}
+ * value, as we consider several shared responsibilities between `@getodk/xpath`
+ * and `@getodk/xforms-engine`. Notably, the engine already has a conflicting
+ * structural runtime representation and encoding behavior, in its support for
+ * {@link https://getodk.github.io/xforms-spec/#secondary-instances---external | external secondary instances}
+ * with a {@link https://geojson.org/ | GeoJSON format}.
+ */
+export declare class Geopoint implements GeopointCoordinates {
+    static fromNodeValue(nodeValue: string): Geopoint | null;
+    readonly latitude: number;
+    readonly longitude: number;
+    private constructor();
+}

package/dist/lib/geo/Geotrace.d.ts

@@ -0,0 +1,12 @@
+import { Geopoint } from './Geopoint.ts';
+import { GeopointRuntimeValue } from './geopointCodec.ts';
+import { GeotraceLine } from './GeotraceLine.ts';
+export type GeotracePoints = readonly [Geopoint, Geopoint, ...Geopoint[]];
+export declare class Geotrace {
+    readonly geopoints: GeotracePoints;
+    static fromEncodedGeotrace(encoded: string): Geotrace | null;
+    static fromEncodedValues(values: readonly string[]): Geotrace | null;
+    static fromGeopoints(geopoints: readonly GeopointRuntimeValue[]): Geotrace | null;
+    readonly lines: readonly GeotraceLine[];
+    private constructor();
+}

package/dist/lib/geo/GeotraceLine.d.ts

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

package/dist/lib/geo/encodeGeoValueStubFactory.d.ts

@@ -0,0 +1,2 @@
+import { GeoValueEncoder, GeoValueType } from './GeoValueCodec.ts';
+export declare const encodeValueStubFactory: <RuntimeInputValue>(valueType: GeoValueType) => GeoValueEncoder<RuntimeInputValue>;

package/dist/lib/geo/geopointCodec.d.ts

@@ -0,0 +1,4 @@
+import { Geopoint } from './Geopoint.ts';
+import { GeoValueCodec } from './GeoValueCodec.ts';
+export type GeopointRuntimeValue = Geopoint | null;
+export declare const geopointCodec: GeoValueCodec<'geopoint', GeopointRuntimeValue>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getodk/xpath",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "Apache-2.0",
   "description": "XPath implementation for ODK Web Forms",
   "type": "module",
@@ -31,7 +31,7 @@
     "README.md"
   ],
   "engines": {
-    "node": "^18.20.4 || ^20.17.0 || ^22.9.0",
+    "node": "^18.20.5 || ^20.18.1 || ^22.12.0",
     "yarn": "1.22.22"
   },
   "scripts": {
@@ -54,24 +54,27 @@
     "test:types:test": "tsc --project ./test/tsconfig.json --emitDeclarationOnly false --noEmit"
   },
   "dependencies": {
-    "@getodk/common": "0.5.0",
+    "@getodk/common": "0.5.1",
     "@js-temporal/polyfill": "^0.4.4",
     "crypto-js": "^4.2.0",
     "itertools-ts": "^1.27.1"
   },
   "devDependencies": {
-    "@babel/core": "^7.25.2",
+    "@babel/core": "^7.26.0",
     "@getodk/tree-sitter-xpath": "0.1.2",
-    "@playwright/test": "^1.47.2",
+    "@playwright/test": "^1.49.1",
     "@types/crypto-js": "^4.2.2",
-    "@vitest/browser": "^2.1.1",
+    "@vitest/browser": "^2.1.8",
     "babel-plugin-transform-jsbi-to-bigint": "^1.4.0",
     "jsdom": "^25.0.1",
-    "vite": "^5.4.8",
-    "vite-plugin-babel": "^1.2.0",
-    "vite-plugin-dts": "^4.2.2",
+    "vite": "^5.4.11",
+    "vite-plugin-babel": "^1.3.0",
+    "vite-plugin-dts": "^4.3.0",
     "vite-plugin-no-bundle": "^4.0.0",
-    "vitest": "^2.1.1",
-    "web-tree-sitter": "0.23.0"
+    "vitest": "^2.1.8",
+    "web-tree-sitter": "0.24.5"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }