@usearazzo/runner 1.0.1-alpha.18 → 1.0.1-alpha.20

package/types/runner.d.ts

@@ -473,7 +473,64 @@ export declare type CriterionContextResolver = (expression: string) => unknown;
 export declare class CriterionError extends ArazzoRunnerError {
     readonly condition?: string;
     readonly type?: string;
-    readonly reason?: string;
+    readonly reason?: CriterionErrorReason;
+}
+
+/**
+ * The `reason` a {@link CriterionError} carries.
+ *
+ * Structural reasons mark a criterion that is malformed as written; they are
+ * thrown as a plain `CriterionError`. Evaluation reasons (`InvalidSimple`,
+ * `InvalidRegex`, `InvalidJSONPath`, `InvalidXPath`, `InvalidXPathContext`) mark
+ * a condition that cannot be evaluated; they are thrown as a
+ * {@link CriterionEvaluationError}, which `CriterionEvaluator` turns into an
+ * unmet criterion.
+ * @public
+ */
+export declare const CriterionErrorReason: {
+    /** The element is not a Criterion Object. */
+    readonly InvalidCriterion: "invalid-criterion";
+    /** The `condition` is missing or empty. */
+    readonly MissingCondition: "missing-condition";
+    /** The `type` is present but unreadable. */
+    readonly InvalidType: "invalid-type";
+    /** The `type` names no known criterion type. */
+    readonly UnknownType: "unknown-type";
+    /** The expression type `version` is present but not a string. */
+    readonly InvalidVersion: "invalid-version";
+    /** The expression type `version` is not the one this runner supports. */
+    readonly UnsupportedVersion: "unsupported-version";
+    /** The `context` is not a runtime expression. */
+    readonly InvalidContext: "invalid-context";
+    /** A `regex`, `jsonpath` or `xpath` criterion has no `context`. */
+    readonly MissingContext: "missing-context";
+    /** The `simple` condition cannot be parsed. */
+    readonly InvalidSimple: "invalid-simple";
+    /** The `regex` condition is not a valid regular expression. */
+    readonly InvalidRegex: "invalid-regex";
+    /** The `jsonpath` condition is not a valid JSONPath query. */
+    readonly InvalidJSONPath: "invalid-jsonpath";
+    /** The `xpath` condition is invalid or fails to evaluate. */
+    readonly InvalidXPath: "invalid-xpath";
+    /** The resolved `xpath` context is not XML. */
+    readonly InvalidXPathContext: "invalid-xpath-context";
+};
+
+/**
+ * One of the `CriterionErrorReason` values.
+ * @public
+ */
+export declare type CriterionErrorReason = (typeof CriterionErrorReason)[keyof typeof CriterionErrorReason];
+
+/**
+ * A criterion condition that cannot be evaluated: a syntax error in the
+ * condition, a context the condition cannot apply to, or an error raised while
+ * evaluating it. The type-specific criterion evaluators throw it;
+ * `CriterionEvaluator` turns it into an unmet criterion, as Arazzo 1.1.0
+ * requires.
+ * @public
+ */
+export declare class CriterionEvaluationError extends CriterionError {
 }
 
 /**
@@ -486,12 +543,26 @@ export declare class CriterionError extends ArazzoRunnerError {
  *   pattern to the resolved value.
  * - `jsonpath` — resolves the `context` runtime expression, then applies the
  *   JSONPath query to the resolved value (met when the query matches). Only the
- *   `rfc9535` version is supported (the spec default); an explicit other version
- *   throws.
+ *   `rfc9535` version is supported; an explicit other version throws.
  * - `xpath` — resolves the `context` runtime expression, then applies the XPath
  *   3.1 query to the resolved XML value (met by the Effective Boolean Value).
- *   Only the `xpath-31` version is supported (the spec default); an explicit
- *   other version throws.
+ *   Only the `xpath-31` version is supported; an explicit other version throws.
+ *
+ * Versions follow Arazzo 1.1.0's Expression Type Object: `rfc9535` and
+ * `xpath-31` are allowed values, and an omitted `version` defaults to them.
+ * Arazzo 1.0.x lists neither and requires `version`; this evaluator applies
+ * the 1.1.0 rule to every document, which accepts more but never evaluates a
+ * query under the wrong dialect.
+ *
+ * A condition that cannot be evaluated fails the criterion (`false`), as
+ * Arazzo 1.1.0 requires: a syntax error in the condition, a context the
+ * condition cannot apply to (non-XML data for `xpath`), or an XPath evaluation
+ * error. The type-specific evaluators report these as a
+ * {@link CriterionEvaluationError}, which this facade absorbs; any other error
+ * they raise propagates. A criterion that is malformed as written still throws: a
+ * missing `condition`, an unknown or unreadable `type`, an unsupported
+ * expression `version`, or a `context` that is missing or not a runtime
+ * expression.
  *
  * The evaluator is agnostic about how runtime expressions are resolved: the
  * caller supplies a {@link CriterionContextResolver} per evaluation, keeping
@@ -514,6 +585,10 @@ export declare class CriterionEvaluator {
 
 /**
  * Options for the CriterionEvaluator.
+ *
+ * An injected evaluator signals a condition it cannot evaluate by throwing a
+ * {@link CriterionEvaluationError}, which fails the criterion; any other error
+ * it throws, a plain {@link CriterionError} included, propagates.
  * @public
  */
 export declare interface CriterionEvaluatorOptions {
@@ -701,7 +776,7 @@ export declare class JSONPathCriterionEvaluator {
      * whether it matched anything.
      *
      * Returns `false` when the context is `null` or `undefined`. Throws
-     * {@link CriterionError} when the condition is not a valid JSONPath query.
+     * {@link CriterionEvaluationError} when the condition is not a valid JSONPath query.
      */
     evaluate(condition: string, context: unknown): boolean;
 }
@@ -1420,7 +1495,7 @@ export declare class RegexCriterionEvaluator {
      * Tests the resolved context value against the regular expression `condition`.
      *
      * The context is coerced to a string before matching. Returns `false` when the
-     * context is `null` or `undefined`. Throws {@link CriterionError} when the
+     * context is `null` or `undefined`. Throws {@link CriterionEvaluationError} when the
      * condition is not a valid regular expression.
      */
     evaluate(condition: string, context: unknown): boolean;
@@ -1780,7 +1855,7 @@ export declare function settledResult(result: WorkflowExecutionResult): Workflow
  * compared per the library's rules (e.g. `undefined == x` and relational
  * comparisons are false, matching the spec's "null equals only null"), so a
  * negated or disjunctive condition may still pass. A malformed condition throws
- * {@link CriterionError}.
+ * {@link CriterionEvaluationError}.
  * @public
  */
 export declare class SimpleCriterionEvaluator {
@@ -2455,7 +2530,7 @@ export declare interface WorkflowReferenceContext {
  *
  * Only XPath 3.1 is supported (`fontoxpath`'s engine); version gating happens in
  * the facade. Per Arazzo 1.1.0, a `null` or `undefined` context fails the
- * condition. An invalid query throws {@link CriterionError}.
+ * condition. An invalid query throws {@link CriterionEvaluationError}.
  * @public
  */
 export declare class XPathCriterionEvaluator {
@@ -2465,7 +2540,7 @@ export declare class XPathCriterionEvaluator {
      * its Effective Boolean Value.
      *
      * Returns `false` when the context is `null` or `undefined`. Throws
-     * {@link CriterionError} when the context is not XML or the query is invalid.
+     * {@link CriterionEvaluationError} when the context is not XML or the query is invalid.
      */
     evaluate(condition: string, context: unknown): boolean;
 }