@getodk/xpath 0.2.1 → 0.3.0

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.3.0",
   "license": "Apache-2.0",
   "description": "XPath implementation for ODK Web Forms",
   "type": "module",
@@ -49,10 +49,12 @@
     "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.0",
     "@js-temporal/polyfill": "^0.4.4",
     "crypto-js": "^4.2.0",
     "itertools-ts": "^1.27.1"

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;

package/dist/lib/dom/assertions.d.ts

@@ -1,4 +0,0 @@
-import { ContextParentNode } from './types.ts';
-type AssertParentNode = (node: Node) => asserts node is ContextParentNode;
-export declare const assertParentNode: AssertParentNode;
-export {};

package/dist/lib/dom/predicates.d.ts

@@ -1,11 +0,0 @@
-import { NamespaceAttribute } from './types';
-export declare const isAttributeNode: (node: Node) => node is Attr;
-export declare const isNamespaceAttribute: (attr: Attr) => attr is NamespaceAttribute;
-export declare const isNamespaceNode: (node: Node) => node is NamespaceAttribute;
-export declare const isCDataSection: (node: Node) => node is CDATASection;
-export declare const isCommentNode: (node: Node) => node is Comment;
-export declare const isDocumentNode: (node: Node) => node is Document;
-export declare const isDocumentFragmentNode: (node: Node) => node is DocumentFragment;
-export declare const isElementNode: (node: Node) => node is Element;
-export declare const isProcessingInstructionNode: (node: Node) => node is ProcessingInstruction;
-export declare const isTextNode: (node: Node) => node is Text;

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

@@ -1 +0,0 @@
-export declare const sortDocumentOrder: (nodes: Iterable<Node>) => Node[];

package/dist/lib/dom/traversal.d.ts

@@ -1,21 +0,0 @@
-import { ContextDocument, ContextNode, ContextParentNode } from './types.ts';
-export declare const getDocument: (node: Node) => Document;
-export declare const getRootNode: (node: ContextNode) => ContextParentNode;
-export declare const TreeWalkerFilter: {
-    readonly ANY: 975;
-    readonly ELEMENT: 1;
-    readonly TEXT: 12;
-    readonly COMMENT: 128;
-    readonly PROCESSING_INSTRUCTION: 64;
-};
-type TreeWalkerFilters = typeof TreeWalkerFilter;
-export type TreeWalkerFilter = keyof TreeWalkerFilters;
-export type TreeWalkerFilterFlag = TreeWalkerFilters[TreeWalkerFilter];
-export type FilteredTreeWalker<Filter extends TreeWalkerFilter = TreeWalkerFilter> = TreeWalker & {
-    readonly whatToShow: TreeWalkerFilters[Filter];
-};
-export declare const getTreeWalker: <Filter extends TreeWalkerFilter = "ANY">(contextDocument: ContextDocument, contextNode?: ContextNode, filter?: Filter) => FilteredTreeWalker<Filter>;
-export type FilteredTreeWalkers = {
-    readonly [Filter in TreeWalkerFilter]: FilteredTreeWalker<Filter>;
-};
-export {};

package/dist/lib/dom/types.d.ts

@@ -1,21 +0,0 @@
-export type ContextDocument = Document | XMLDocument;
-type AnyContextNode = Attr | CDATASection | Comment | ContextDocument | DocumentType | Element | ProcessingInstruction | Text;
-type MaybeNode<T extends Node> = Node & Partial<Omit<T, keyof Node>>;
-export type MaybeAttrNode = MaybeNode<Attr>;
-export type MaybeElementNode = AnyContextNode & Node & Partial<Element>;
-export type MaybeProcessingInstructionNode = MaybeNode<ProcessingInstruction>;
-export type MaybeNamedNode = MaybeNode<MaybeAttrNode | MaybeElementNode>;
-export type ContextNode = AnyContextNode & Node;
-export type MaybeDocumentOrElementNode = MaybeElementNode & Partial<ContextDocument>;
-export type AnyParentNode = Extract<AnyContextNode, {
-    readonly children: any;
-}>;
-export type ContextParentNode = AnyParentNode & Node;
-type AnyNamedNode = Attr | Element | ProcessingInstruction;
-export type NamedNode = AnyNamedNode & Node;
-export type NamespaceAttribute = Attr & ({
-    readonly name: 'xmlns';
-} | {
-    readonly prefix: 'xmlns';
-});
-export {};

package/dist/lib/dom/xml.d.ts

@@ -1 +0,0 @@
-export declare const parseXMLDocument: (xml: string) => Document;

package/dist/shared/constants.d.ts

@@ -1,13 +0,0 @@
-export declare const XPathResultTypes: {
-    readonly ANY_TYPE: 0;
-    readonly NUMBER_TYPE: 1;
-    readonly STRING_TYPE: 2;
-    readonly BOOLEAN_TYPE: 3;
-    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 XPathResultTypes = typeof XPathResultTypes;

package/dist/shared/index.d.ts

@@ -1,2 +0,0 @@
-export * from './constants.ts';
-export type * from './interface.ts';

package/dist/shared/interface.d.ts

@@ -1,33 +0,0 @@
-type LookupNamespaceURI = (prefix: string | null) => string | null;
-export interface XPathNamespaceResolverObject {
-    readonly lookupNamespaceURI: LookupNamespaceURI;
-}
-export type XPathNSResolver = LookupNamespaceURI | XPathNamespaceResolverObject;
-interface XPathResultStatic {
-    readonly ANY_TYPE: 0;
-    readonly NUMBER_TYPE: 1;
-    readonly STRING_TYPE: 2;
-    readonly BOOLEAN_TYPE: 3;
-    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 XPathResultType = XPathResultStatic[keyof XPathResultStatic];
-export interface XPathResult extends XPathResultStatic {
-    readonly booleanValue: boolean;
-    readonly invalidIteratorState: boolean;
-    readonly numberValue: number;
-    readonly resultType: XPathResultType;
-    readonly singleNodeValue: Node | null;
-    readonly snapshotLength: number;
-    readonly stringValue: string;
-    iterateNext(): Node | null;
-    snapshotItem(index: number): Node | null;
-}
-export interface AnyXPathEvaluator {
-    evaluate(expression: string, contextNode: Node, namespaceResolver: XPathNSResolver | null, resultType: XPathResultType | null): XPathResult;
-}
-export {};