@getodk/xpath 0.2.1 → 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/dist/xforms/XFormsElementRepresentation.d.ts

@@ -0,0 +1,15 @@
+import { XPathNode } from '../adapter/interface/XPathNode.ts';
+import { AdapterElement } from '../adapter/interface/XPathNodeKindAdapter.ts';
+export declare const XFORMS_LOCAL_NAME: unique symbol;
+export type XFORMS_LOCAL_NAME = typeof XFORMS_LOCAL_NAME;
+export declare const XFORMS_KNOWN_ATTRIBUTE: unique symbol;
+export type XFORMS_KNOWN_ATTRIBUTE = typeof XFORMS_KNOWN_ATTRIBUTE;
+export type XFormsElementRepresentation<T extends XPathNode, LocalName extends string, KnownAttribute extends string = never> = AdapterElement<T> & {
+    readonly [XFORMS_LOCAL_NAME]: LocalName;
+} & ([
+    KnownAttribute
+] extends [string] ? {
+    readonly [XFORMS_KNOWN_ATTRIBUTE]: KnownAttribute;
+} : {
+    readonly [XFORMS_KNOWN_ATTRIBUTE]?: string;
+});

package/dist/xforms/XFormsItextTranslations.d.ts

@@ -1,26 +1,78 @@
-import { KnownAttributeLocalNamedElement, LocalNamedElement } from '../../../common/types/dom.ts';
-import { ModelElement, XFormsXPathEvaluator } from './XFormsXPathEvaluator.ts';
-export interface ItextRootElement extends LocalNamedElement<'itext'> {
+import { UpsertableWeakMap } from '../../../common/src/lib/collections/UpsertableWeakMap.ts';
+import { XPathNode } from '../adapter/interface/XPathNode.ts';
+import { XPathDOMProvider } from '../adapter/xpathDOMProvider.ts';
+import { XFormsElementRepresentation } from './XFormsElementRepresentation.ts';
+type XFormsItextTextID = string;
+type XFormsItextTranslationTextElement<T extends XPathNode> = XFormsElementRepresentation<T, 'text'>;
+export type XFormsItextTranslationElement<T extends XPathNode> = XFormsElementRepresentation<T, 'translation', 'lang'>;
+type XFormsItextTextMap<T extends XPathNode> = ReadonlyMap<XFormsItextTextID, XFormsItextTranslationTextElement<T>>;
+type XFormsItextTranslationsCache<T extends XPathNode> = UpsertableWeakMap<XFormsItextTranslationElement<T>, XFormsItextTextMap<T>>;
+export type XFormsItextTranslationLanguage = string;
+export type XFormsItextTranslationMap<T extends XPathNode> = ReadonlyMap<XFormsItextTranslationLanguage, XFormsItextTranslationElement<T>>;
+/**
+ * Public interface to an {@link XFormsXPathEvaluator}'s ODK XForms
+ * {@link https://getodk.github.io/xforms-spec/#languages | active language state}.
+ */
+export interface XFormsItextTranslationsState {
+    getLanguages(): readonly XFormsItextTranslationLanguage[];
+    getActiveLanguage(): XFormsItextTranslationLanguage | null;
+    setActiveLanguage(language: XFormsItextTranslationLanguage | null): XFormsItextTranslationLanguage | null;
 }
-export declare const getItextRoot: (modelElement: ModelElement) => ItextRootElement | null;
-type TranslationLanguage = string;
-interface TranslationTextElement extends KnownAttributeLocalNamedElement<'text', 'id'> {
-}
-type ItextID = string;
-export declare const getTranslationTextByLanguage: (modelElement: ModelElement, language: TranslationLanguage, itextID: ItextID) => TranslationTextElement | null;
-interface DefaultTextValueElement extends LocalNamedElement<'value'> {
-    getAttribute(name: 'form'): null;
-    getAttribute(name: string): string | null;
-}
-export declare const getDefaultTextValueElement: (textElement: TranslationTextElement) => DefaultTextValueElement | null;
-export declare class XFormsItextTranslations {
-    protected readonly evaluator: XFormsXPathEvaluator;
-    protected readonly defaultLanguage: string | null;
-    protected readonly languages: readonly string[];
-    protected activeLanguage: string | null;
-    constructor(evaluator: XFormsXPathEvaluator);
-    getLanguages(): readonly string[];
-    getActiveLanguage(): string | null;
-    setActiveLanguage(language: string | null): string | null;
+/**
+ * @package
+ *
+ * This is an internal implementation/API providing support for {@link itext}.
+ *
+ * As specified by
+ * {@link https://getodk.github.io/xforms-spec/#fn:jr:itext | ODK XForms `jr:itext`},
+ * the function depends on implicit "active language" state. The corresponding
+ * {@link XFormsItextTranslationsState} **public interface** exposes access to get
+ * and set that state for `@getodk/xpath` consumers.
+ *
+ * @see {@link XFormsItextTranslationsState} for the corresponding public interface.
+ */
+export declare class XFormsItextTranslations<T extends XPathNode> implements XFormsItextTranslationsState {
+    readonly domProvider: XPathDOMProvider<T>;
+    readonly translationElementMap: XFormsItextTranslationMap<T>;
+    protected readonly defaultLanguage: XFormsItextTranslationLanguage | null;
+    protected readonly languages: readonly XFormsItextTranslationLanguage[];
+    protected activeLanguage: XFormsItextTranslationLanguage | null;
+    readonly translationsCache: XFormsItextTranslationsCache<T>;
+    constructor(domProvider: XPathDOMProvider<T>, translationElementMap: XFormsItextTranslationMap<T>);
+    private getTranslationMetadata;
+    private getTranslationTextElement;
+    /**
+     * @package
+     *
+     * Here, "default" is meant as more precise language than "regular" as
+     * {@link https://getodk.github.io/xforms-spec/#languages | specified by ODK XForms}. In other words, this is equivalent to the following hypothetical XPath pseudo-code (whitespace added to improve structural clarity):
+     *
+     * ```xpath
+     * string(
+     *   imaginary:itext-translation(
+     *     xpath3-fn:environment-variable('activeLanguage')
+     *   )
+     *     /text[@id = $itextID]
+     *       /value[not(@form)]
+     * )
+     * ```
+     *
+     * Or alternately:
+     *
+     * ```xpath
+     * string(
+     *   imaginary:itext-root()
+     *     /translation[@lang = xpath3-fn:environment-variable('activeLanguage')]
+     *       /text[@id = $itextID]
+     *         /value[not(@form)]
+     * )
+     * ```
+     *
+     * @todo The above really feels like it adds some helpful clarity to how `jr:itext()` is designed to work, and the kinds of structures, state and input involved. Since there's already some discomfort around that API as specified, it's worth considering
+     */
+    getDefaultTranslationText(itextID: string): string;
+    getLanguages(): readonly XFormsItextTranslationLanguage[];
+    getActiveLanguage(): XFormsItextTranslationLanguage | null;
+    setActiveLanguage(language: XFormsItextTranslationLanguage | null): XFormsItextTranslationLanguage | null;
 }
 export {};

package/dist/xforms/XFormsSecondaryInstances.d.ts

@@ -0,0 +1,4 @@
+import { XPathNode } from '../adapter/interface/XPathNode.ts';
+import { XFormsElementRepresentation } from './XFormsElementRepresentation.ts';
+export type XFormsSecondaryInstanceElement<T extends XPathNode> = XFormsElementRepresentation<T, 'instance', 'id'>;
+export type XFormsSecondaryInstanceMap<T extends XPathNode> = ReadonlyMap<string, XFormsSecondaryInstanceElement<T>>;

package/dist/xforms/XFormsXPathEvaluator.d.ts

@@ -1,17 +1,38 @@
+import { UnwrapAdapterNode } from '../adapter/interface/XPathCustomUnwrappableNode.ts';
+import { XPathNode } from '../adapter/interface/XPathNode.ts';
+import { AdapterParentNode } from '../adapter/interface/XPathNodeKindAdapter.ts';
+import { EvaluationContext } from '../context/EvaluationContext.ts';
 import { EvaluatorOptions, Evaluator } from '../evaluator/Evaluator.ts';
-import { AnyParentNode } from '../lib/dom/types.ts';
-import { XFormsItextTranslations } from './XFormsItextTranslations.ts';
-export interface ModelElement extends Element {
-    readonly localName: 'model';
+import { XFormsItextTranslationLanguage, XFormsItextTranslationMap, XFormsItextTranslationsState } from './XFormsItextTranslations.ts';
+import { XFormsSecondaryInstanceElement, XFormsSecondaryInstanceMap } from './XFormsSecondaryInstances.ts';
+/**
+ * @todo We accept an arbitrary parent node specifically for legacy WHATWG DOM
+ * integration, which we will no longer be using _except in test_. We should
+ * consider narrowing this type to {@link AdapterDocument} for any other usage.
+ */
+export type XFormsXPathRootNode<T extends XPathNode> = AdapterParentNode<T> | UnwrapAdapterNode<AdapterParentNode<T>>;
+export interface XFormsXPathEvaluatorOptions<T extends XPathNode> extends EvaluatorOptions<T> {
+    readonly rootNode: XFormsXPathRootNode<T>;
+    readonly itextTranslationsByLanguage: XFormsItextTranslationMap<T>;
+    readonly secondaryInstancesById: XFormsSecondaryInstanceMap<T>;
 }
-interface XFormsXPathEvaluatorOptions extends EvaluatorOptions {
-    readonly rootNode: AnyParentNode;
+export declare class XFormsXPathEvaluator<T extends XPathNode> extends Evaluator<T> implements XFormsItextTranslationsState {
+    static getSecondaryInstance<T extends XPathNode>(context: EvaluationContext<T>, id: string): XFormsSecondaryInstanceElement<T> | null;
+    static getDefaultTranslationText<T extends XPathNode>(context: EvaluationContext<T>, itextID: string): string;
+    readonly rootNode: AdapterParentNode<T>;
+    /**
+     * @package
+     * @see {@link InternalXFormsXPathEvaluator}
+     */
+    protected readonly itextTranslations: XFormsItextTranslationsState;
+    /**
+     * @package
+     * @see {@link InternalXFormsXPathEvaluator}
+     */
+    protected readonly secondaryInstancesById: XFormsSecondaryInstanceMap<T>;
+    constructor(options: XFormsXPathEvaluatorOptions<T>);
+    getLanguages(): readonly XFormsItextTranslationLanguage[];
+    getActiveLanguage(): XFormsItextTranslationLanguage | null;
+    setActiveLanguage(language: XFormsItextTranslationLanguage | null): XFormsItextTranslationLanguage | null;
+    getSecondaryInstance(id: string): XFormsSecondaryInstanceElement<T> | undefined;
 }
-export declare class XFormsXPathEvaluator extends Evaluator {
-    readonly rootNode: AnyParentNode;
-    readonly rootNodeDocument: XMLDocument;
-    readonly modelElement: ModelElement | null;
-    readonly translations: XFormsItextTranslations;
-    constructor(options: XFormsXPathEvaluatorOptions);
-}
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getodk/xpath",
-  "version": "0.2.1",
+  "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": {
@@ -49,27 +49,32 @@
     "test-watch:chromium": "BROWSER_NAME=chromium vitest",
     "test-watch:firefox": "BROWSER_NAME=firefox vitest",
     "test-watch:webkit": "BROWSER_NAME=webkit vitest",
-    "test:types": "tsc --project ./tsconfig.json --emitDeclarationOnly false --noEmit"
+    "test:types": "npm-run-all -nl test:types:*",
+    "test:types:main": "tsc --project ./tsconfig.json --emitDeclarationOnly false --noEmit",
+    "test:types:test": "tsc --project ./test/tsconfig.json --emitDeclarationOnly false --noEmit"
   },
   "dependencies": {
-    "@getodk/common": "0.4.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"
   }
 }

package/dist/evaluator/result/ResultType.d.ts

@@ -1,13 +0,0 @@
-export declare const ResultTypes: {
-    readonly BOOLEAN_TYPE: 3;
-    readonly NUMBER_TYPE: 1;
-    readonly STRING_TYPE: 2;
-    readonly UNORDERED_NODE_ITERATOR_TYPE: 4;
-    readonly ORDERED_NODE_ITERATOR_TYPE: 5;
-    readonly UNORDERED_NODE_SNAPSHOT_TYPE: 6;
-    readonly ORDERED_NODE_SNAPSHOT_TYPE: 7;
-    readonly ANY_UNORDERED_NODE_TYPE: 8;
-    readonly FIRST_ORDERED_NODE_TYPE: 9;
-};
-export type ResultTypes = typeof ResultTypes;
-export type ResultType = ResultTypes[keyof ResultTypes];

package/dist/evaluator/result/index.d.ts

@@ -1,7 +0,0 @@
-import { Evaluation } from '../../evaluations/Evaluation.ts';
-import { XPathResultType } from '../../shared/index.ts';
-import { BooleanResult } from './BooleanResult';
-import { NodeSetIteratorResult, NodeSetSnapshotResult } from './NodeSetResult';
-import { NumberResult } from './NumberResult';
-import { StringResult } from './StringResult';
-export declare const toXPathResult: (resultType: XPathResultType, evaluation: Evaluation) => BooleanResult | NodeSetSnapshotResult | NodeSetIteratorResult | NumberResult | StringResult;