@getodk/xpath 0.2.0 → 0.3.0

package/dist/lib/datetime/coercion.d.ts

@@ -1,5 +1,4 @@
 import { Temporal } from '@js-temporal/polyfill';
-
 export declare const tryParseDateString: (value: string) => Date | null;
 export declare const dateTimeFromString: (timeZone: Temporal.TimeZone, value: string) => Temporal.ZonedDateTime | null;
 export declare const dateTimeFromNumber: (timeZone: Temporal.TimeZone, milliseconds: number) => Temporal.ZonedDateTime | null;

package/dist/lib/datetime/functions.d.ts

@@ -1,5 +1,4 @@
 import { Temporal } from '@js-temporal/polyfill';
-
 export declare const currentLocalDateTimeString: (timeZone: Temporal.TimeZone) => string;
 export declare const localDateTimeString: (dateTime: Temporal.ZonedDateTime) => string;
 export declare const localDateTimeOrDateString: (dateTime: Temporal.ZonedDateTime) => string;

package/dist/static/grammar/ExpressionParser.d.ts

@@ -3,7 +3,6 @@ import { SyntaxLanguageTypeName, SyntaxLanguage as TreeSitterLanguage } from './
 import { XPathNode } from './SyntaxNode.ts';
 import { SyntaxTree as TreeSitterTree } from './SyntaxTree.ts';
 import { TreeSitterXPathParser, WebAssemblyResourceSpecifiers } from './TreeSitterXPathParser.ts';
-
 declare class SyntaxLanguage implements TreeSitterLanguage {
     readonly types: readonly SyntaxLanguageTypeName[];
     constructor(tsLanguage: TreeSitterLanguage);

package/dist/static/grammar/SyntaxLanguage.d.ts

@@ -1,5 +1,4 @@
 import { AnySyntaxType } from './type-names.ts';
-
 export type SyntaxLanguageTypeName = AnySyntaxType | undefined;
 export interface SyntaxLanguage {
     readonly types: readonly SyntaxLanguageTypeName[];

package/dist/static/grammar/SyntaxNode.d.ts

@@ -1,5 +1,4 @@
 import { AbbreviatedAbsoluteLocationPathType, AbbreviatedAxisTestType, AbbreviatedStepType, AbsoluteLocationPathType, AbsoluteRootLocationPathType, AdditionExprType, AndExprType, AnyBinaryExprType, AnySyntaxType, AnyUnaryExprType, ArgumentType, AxisNameType, AxisTestType, DivisionExprType, EqExprType, ExprType, FilterExprType, FilterPathExprType, FunctionCallType, FunctionNameType, GteExprType, GtExprType, LiteralType, LocalPartType, LteExprType, LtExprType, ModuloExprType, MultiplicationExprType, NeExprType, NodeTestType, NodeTypeTestType, NumberType, OrExprType, ParentType, PredicateType, PrefixedNameType, PrefixedWildcardNameTestType, PrefixType, ProcessingInstructionNameTestType, RelativeLocationPathType, RelativeStepSyntaxLiteral, SelfType, StepType, SubtractionExprType, UnionExprType, UnprefixedNameType, UnprefixedWildcardNameTestType, VariableReferenceType, XPathType } from './type-names.ts';
-
 export interface SyntaxNode<Type extends AnySyntaxType, Children extends readonly UnknownSyntaxNode[], Text extends string = string> {
     readonly type: Type;
     readonly childCount: Children['length'];

package/dist/static/grammar/SyntaxTree.d.ts

@@ -1,6 +1,5 @@
 import { SyntaxLanguage } from './SyntaxLanguage.ts';
 import { XPathNode } from './SyntaxNode.ts';
-
 export interface SyntaxTree {
     readonly language: SyntaxLanguage;
     readonly rootNode: XPathNode;

package/dist/static/grammar/TreeSitterXPathParser.d.ts

@@ -1,5 +1,4 @@
 import { default as WebTreeSitter } from 'web-tree-sitter';
-
 type ParserConstructor = typeof WebTreeSitter;
 type Parser = InstanceType<ParserConstructor>;
 declare let Parser: ParserConstructor;

package/dist/static/grammar/type-names.d.ts

@@ -1,5 +1,4 @@
 import { SyntaxType, UnnamedType } from '@getodk/tree-sitter-xpath';
-
 /**
  * The root node of any parsed XPath expression's syntax tree.
  *

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,27 +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,18 +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.0",
+  "version": "0.3.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.15.1 || ^22.4.1",
+    "node": "^18.20.4 || ^20.17.0 || ^22.9.0",
     "yarn": "1.22.22"
   },
   "scripts": {
@@ -49,27 +49,29 @@
     "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.5.0",
     "@js-temporal/polyfill": "^0.4.4",
-    "@getodk/common": "0.3.0",
     "crypto-js": "^4.2.0",
     "itertools-ts": "^1.27.1"
   },
   "devDependencies": {
-    "@babel/core": "^7.24.8",
+    "@babel/core": "^7.25.2",
     "@getodk/tree-sitter-xpath": "0.1.2",
-    "@playwright/test": "^1.45.1",
+    "@playwright/test": "^1.47.2",
     "@types/crypto-js": "^4.2.2",
-    "@vitest/browser": "^2.0.2",
+    "@vitest/browser": "^2.1.1",
     "babel-plugin-transform-jsbi-to-bigint": "^1.4.0",
-    "jsdom": "^24.1.0",
-    "vite": "^5.3.3",
+    "jsdom": "^25.0.1",
+    "vite": "^5.4.8",
     "vite-plugin-babel": "^1.2.0",
-    "vite-plugin-dts": "^3.9.1",
+    "vite-plugin-dts": "^4.2.2",
     "vite-plugin-no-bundle": "^4.0.0",
-    "vitest": "^2.0.2",
-    "web-tree-sitter": "0.22.6"
+    "vitest": "^2.1.1",
+    "web-tree-sitter": "0.23.0"
   }
 }

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,8 +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;