@getodk/xforms-engine 0.2.0 → 0.3.0

package/dist/parse/xpath/predicate-analysis.d.ts

@@ -0,0 +1,30 @@
+import { PathNodeList } from './path-resolution.ts';
+import { PathExpressionNode } from './semantic-analysis.ts';
+
+/**
+ * Represents a pair of:
+ *
+ * - Path expression syntax referenced within a particular predicate, on any
+ *   Step within a source LocationPath and/or FilterExpr path. This
+ *   sub-expression is resolved as a member of the dependencies which may be
+ *   referenced by any arbitrary form expression.
+ *
+ * - The cumulative set of path nodes, from the start of the source path
+ *   expression, to the Step and Predicate where the sub-expression reference
+ *   was identified. This representation is used as **part** of the context used
+ *   to resolve the identified Predicate sub-expression for downstream
+ *   dependency subscriptions. (Each predicate sub-expression is **further
+ *   contextualized** by the original context in which the source path is
+ *   defined.)
+ */
+export interface PredicateReference {
+    readonly predicatePathNode: PathExpressionNode;
+    readonly stepContextNodes: PathNodeList;
+}
+/**
+ * Identifies path sub-expressions within any of a path's Predicates, along with
+ * the step context in which they are found.
+ *
+ * @see {@link PredicateReference} for details on the produced structures.
+ */
+export declare const findPredicateReferences: (pathNodes: PathNodeList) => readonly PredicateReference[];

package/dist/parse/xpath/reference-parsing.d.ts

@@ -0,0 +1,18 @@
+import { PartiallyKnownString } from '../../../../common/types/string/PartiallyKnownString.ts';
+
+interface ReferenceParsingContext {
+    readonly reference: string | null;
+    readonly parent?: ReferenceParsingContext | null;
+}
+type ReferenceAttributeName = PartiallyKnownString<'nodeset' | 'ref'>;
+interface KnownAttributeElement<AttributeName extends string> extends Element {
+    getAttribute(name: AttributeName): string;
+    getAttribute(name: string): string | null;
+}
+type ParsedReferenceAttribute<T extends Element, AttributeName extends string> = T extends KnownAttributeElement<AttributeName> ? string : string | null;
+/**
+ * Parses a `nodeset` reference from an arbitrary form definition element, and
+ * resolves that (potentially relative) reference to the provided context.
+ */
+export declare const parseNodesetReference: <const AttributeName extends ReferenceAttributeName, T extends Element | KnownAttributeElement<AttributeName>>(parentContext: ReferenceParsingContext, element: T, attributeName: AttributeName) => ParsedReferenceAttribute<T, AttributeName>;
+export {};

package/dist/parse/xpath/semantic-analysis.d.ts

@@ -0,0 +1,98 @@
+import { AbsoluteLocationPathNode, AnySyntaxNode, FilterPathExprNode, RelativeLocationPathNode } from '@getodk/xpath/static/grammar/SyntaxNode.js';
+
+type LocalNameLiteral<LocalName extends string> = LocalName | `${string}:${LocalName}`;
+type LocalNamedFunctionCallLiteral<LocalName extends string> = `${LocalNameLiteral<LocalName>}(${string})`;
+export type TranslationExpression = LocalNamedFunctionCallLiteral<'itext'>;
+/**
+ * Determines if an arbitrary XPath expression is (in whole) a translation
+ * expression (i.e. a call to `jr:itext`).
+ *
+ * @todo We may also want a companion function: `hasTranslationExpression`,
+ * which could be used for `<label ref>`/`<hint ref>` or anywhere else that an
+ * arbitrary expression may call `jr:itext`.
+ */
+export declare const isTranslationExpression: (expression: string) => expression is TranslationExpression;
+/**
+ * Predicate to determine if a FilterPathExpr (as currently produced by
+ * `tree-sitter-xpath`) is one of:
+ *
+ * - `current()`
+ * - `current()/...` (where `...` represents additional steps)
+ * - `current()//...` (^)
+ *
+ * @todo XPath grammar technically also allows for FilterExpr[Predicate],
+ * and our `tree-sitter-xpath` grammar/parser also allow for this. But
+ * `@getodk/xpath` types do not currently acknowledge this possibility.
+ */
+export declare const isCurrentPath: (syntaxNode: FilterPathExprNode) => boolean;
+declare const FILTER_PATH_NODE: unique symbol;
+/**
+ * Used to narrow types where a SyntaxNode with type 'filter_path_expr' is not
+ * **known to produce** a node-set result.
+ *
+ * This addresses some awkwardness in the XPath grammar (and our implementation
+ * parsing it) where FilterExpr _may be_ a FunctionCall, and one of the
+ * following _may also be true_:
+ *
+ * - The function call is known by name to produce a node-set result, **OR**
+ *
+ * - The function call is followed by one or more Steps (or the Step-like '//'
+ *   shorthand), which must produce a node-set **OR**
+ *
+ * - The function call is followed by one or more Predicates, which must produce
+ *   a node-set
+ *
+ * Any other FilterExpr (and thus our containing synthetic 'filter_path_expr'
+ * SyntaxNode) is treated as a non-path [sub-]expression, excluding it from
+ * analysis as such (and any downstream logic such as nodeset resolution).
+ */
+export interface FilterPathNode extends FilterPathExprNode {
+    readonly [FILTER_PATH_NODE]: true;
+}
+/**
+ * Determines whether a given expression beginning with a FilterExpr is known to
+ * produce a node-set result. Used in downstream dependency analysis, as well as
+ * path resolution.
+ */
+export declare const isNodeSetFilterPathExpression: (syntaxNode: FilterPathExprNode) => syntaxNode is FilterPathNode;
+export type PathExpressionNode = AbsoluteLocationPathNode | FilterPathNode | RelativeLocationPathNode;
+/**
+ * Locates sub-expression {@link PathExpressionNode}s within a parsed XPath
+ * expression (or any arbitrary sub-expression thereof).
+ */
+export declare const findLocationPathSubExpressionNodes: (syntaxNode: AnySyntaxNode) => readonly PathExpressionNode[];
+/**
+ * Gets the parsed representation of an XPath path expression, iff the complete
+ * expression is any {@link PathExpressionNode} syntax type.
+ */
+export declare const getPathExpressionNode: (expression: string) => PathExpressionNode | null;
+type BrandedExpression<Expression extends string, Brand extends symbol> = Expression & {
+    readonly [K in Brand]: true;
+};
+declare const CONSTANT_EXPRESSION: unique symbol;
+type CONSTANT_EXPRESSION = typeof CONSTANT_EXPRESSION;
+/**
+ * Represents an expression which produces a constant result:
+ *
+ * - Makes no reference to explicit dependencies
+ * - Does not depend on any known, implicit state
+ * - Evaluation does not depend in any way on context
+ * - Evaluation can be treated as referentially transparent
+ */
+export type ConstantExpression = BrandedExpression<string, CONSTANT_EXPRESSION>;
+/**
+ * @see {@link ConstantExpression}
+ */
+export declare const isConstantExpression: (expression: string) => expression is ConstantExpression;
+declare const CONSTANT_TRUTHY_EXPRESSION: unique symbol;
+type CONSTANT_TRUTHY_EXPRESSION = typeof CONSTANT_TRUTHY_EXPRESSION;
+/**
+ * Represents an expression which is {@link ConstantExpression | constant},
+ * and which will always produce `true` when evaluated as a boolean.
+ */
+export type ConstantTruthyExpression = BrandedExpression<ConstantExpression, CONSTANT_TRUTHY_EXPRESSION>;
+/**
+ * @see {@link ConstantTruthyExpression}
+ */
+export declare const isConstantTruthyExpression: (expression: string) => expression is ConstantTruthyExpression;
+export {};

package/dist/parse/xpath/syntax-traversal.d.ts

@@ -0,0 +1,69 @@
+import { Identity } from '../../../../common/types/helpers.js';
+import { AnySyntaxNode, XPathNode } from '@getodk/xpath/static/grammar/SyntaxNode.js';
+import { AnySyntaxType } from '@getodk/xpath/static/grammar/type-names.js';
+
+export type TypedSyntaxNode<Type extends AnySyntaxType> = Extract<AnySyntaxNode, {
+    readonly type: Type;
+}>;
+type CollectedNodes<Type extends AnySyntaxType> = Identity<ReadonlyArray<TypedSyntaxNode<Type>>>;
+interface CollectNodesOptions {
+    readonly recurseMatchedNodes?: boolean;
+}
+/**
+ * Collects XPath {@link SyntaxNode}s matching any of the specified
+ * {@link types}.
+ *
+ * By default, search is **shallowly recursive** (i.e. the descendants of
+ * matches are not searched).
+ *
+ * {@link CollectNodesOptions.recurseMatchedNodes | `options.recurseMatchedNodes: true`}
+ * can be specified to recursively search descendants of matches.
+ *
+ * This may be useful for analysis of XPath sub-expressions, for instance
+ * identifying all LocationPaths referenced by a broader expression.
+ */
+export declare const collectTypedNodes: <const Type extends AnySyntaxType>(types: readonly [Type, ...Type[]], currentNode: AnySyntaxNode, options?: CollectNodesOptions) => CollectedNodes<Type>;
+/**
+ * Predicate to determine whether {@link descendantNode} represents the complete
+ * syntax of {@link subExpressionNode}. This can be useful for targeting
+ * specific aspects of syntax which tend to be wrapped (sometimes several layers
+ * deep) in more general syntax types.
+ *
+ * @example
+ *
+ * ```ts
+ * const pathExpression = '/foo[@bar = 1]';
+ * const numericExpression = '2';
+ *
+ * const pathRootNode = expressionParser.parse(pathExpression).rootNode;
+ * //    ^?: XPathNode
+ * const [pathNumberNode] = collectTypedNodes(['number'], pathRootNode);
+ * //     ^?: NumberNode
+ *
+ * isCompleteSubExpression(pathRootNode, pathNumberNode); // false
+ *
+ * const numericRootNode = expressionParser.parse(numericExpression).rootNode;
+ * //    ^?: XPathNode
+ * const [numericNumberNode] = collectTypedNodes(['number'], numericRootNode);
+ * //     ^?: NumberNode
+ *
+ * isCompleteSubExpression(numericRootNode, numericNumberNode); // true
+ * ```
+ */
+export declare const isCompleteSubExpression: (subExpressionNode: AnySyntaxNode, descendantNode: AnySyntaxNode) => boolean;
+/**
+ * Finds a syntax node which:
+ *
+ * - Matches one of the specified {@link types}, and
+ * - Represents the complete expression
+ *
+ * This may be useful for performing semantic analysis on expressions, for
+ * instance identifying when an expression **is a FunctionCall**, and producing
+ * the {@link SyntaxNode} representing that FunctionCall.
+ *
+ * In contrast, this would produce `null` for an expression **containing a
+ * FunctionCall** in some sub-expression position (e.g. the call to `position`
+ * in `foo[position() = 2]`).
+ */
+export declare const findTypedPrincipalExpressionNode: <const Type extends AnySyntaxType>(types: readonly [Type, ...Type[]], xpathNode: XPathNode) => TypedSyntaxNode<Type> | null;
+export {};