@usearazzo/runner 1.0.1-alpha.23 → 1.0.1-alpha.25

package/types/runner.d.ts

@@ -1,3 +1,4 @@
+import type { ApiDOMErrorOptions } from '@speclynx/apidom-error';
 import { ApiDOMReferenceOptions } from '@speclynx/apidom-reference/configuration/empty';
 import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { CriterionElement } from '@speclynx/apidom-ns-arazzo-1';
@@ -96,7 +97,7 @@ export declare abstract class APIDocument {
 /**
  * An Arazzo document held by the document registry: the parse result together
  * with the indexes the provider built over it — a container, not a logic
- * bearer. The methods below are thin reads of the source description index.
+ * bearer. The methods below are thin reads of those indexes.
  * @public
  */
 export declare class ArazzoDocument extends APIDocument {
@@ -122,6 +123,12 @@ export declare class ArazzoDocument extends APIDocument {
      * Type guard for ArazzoDocument.
      */
     static is(doc: APIDocument): doc is ArazzoDocument;
+    /**
+     * The workflows of this document that can be addressed by `workflowId`, in
+     * document order. Reads this document only: source descriptions are neither
+     * loaded nor listed.
+     */
+    listWorkflows(): WorkflowDescriptor[];
     /**
      * Resolves a source description name to its canonical URI — precomputed by
      * the provider, resolved against this document's base URI.
@@ -472,58 +479,62 @@ export declare interface ContextSource {
  */
 export declare type CriterionContextResolver = (expression: string) => unknown;
 
-/** @public */
-export declare class CriterionError extends ArazzoRunnerError {
-    readonly condition?: string;
-    readonly type?: string;
-    readonly reason?: CriterionErrorReason;
-}
-
 /**
- * The `reason` a {@link CriterionError} carries.
+ * Carries a `reason`, one of the class's static reason fields.
  *
- * 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.
+ * Every static on this class is a reason: {@link CriterionErrorReason} is
+ * derived from the class's own statics, so a non-reason static would join the
+ * union.
  * @public
  */
-export declare const CriterionErrorReason: {
+export declare class CriterionError extends ArazzoRunnerError {
     /** The element is not a Criterion Object. */
-    readonly InvalidCriterion: "invalid-criterion";
+    static readonly InvalidCriterion: "invalid-criterion";
     /** The `condition` is missing or empty. */
-    readonly MissingCondition: "missing-condition";
+    static readonly MissingCondition: "missing-condition";
     /** The `type` is present but unreadable. */
-    readonly InvalidType: "invalid-type";
+    static readonly InvalidType: "invalid-type";
     /** The `type` names no known criterion type. */
-    readonly UnknownType: "unknown-type";
+    static readonly UnknownType: "unknown-type";
     /** The expression type `version` is present but not a string. */
-    readonly InvalidVersion: "invalid-version";
+    static readonly InvalidVersion: "invalid-version";
     /** The expression type `version` is not the one this runner supports. */
-    readonly UnsupportedVersion: "unsupported-version";
+    static readonly UnsupportedVersion: "unsupported-version";
     /** The `context` is not a runtime expression. */
-    readonly InvalidContext: "invalid-context";
+    static readonly InvalidContext: "invalid-context";
     /** A `regex`, `jsonpath` or `xpath` criterion has no `context`. */
-    readonly MissingContext: "missing-context";
+    static readonly MissingContext: "missing-context";
     /** The `simple` condition cannot be parsed. */
-    readonly InvalidSimple: "invalid-simple";
+    static readonly InvalidSimple: "invalid-simple";
     /** The `regex` condition is not a valid regular expression. */
-    readonly InvalidRegex: "invalid-regex";
+    static readonly InvalidRegex: "invalid-regex";
     /** The `jsonpath` condition is not a valid JSONPath query. */
-    readonly InvalidJSONPath: "invalid-jsonpath";
+    static readonly InvalidJSONPath: "invalid-jsonpath";
     /** The `xpath` condition is invalid or fails to evaluate. */
-    readonly InvalidXPath: "invalid-xpath";
+    static readonly InvalidXPath: "invalid-xpath";
     /** The resolved `xpath` context is not XML. */
-    readonly InvalidXPathContext: "invalid-xpath-context";
-};
+    static readonly InvalidXPathContext: "invalid-xpath-context";
+    readonly condition?: string;
+    readonly type?: string;
+    readonly reason?: CriterionErrorReason;
+    constructor(message?: string, options?: ApiDOMErrorOptions & {
+        readonly reason?: CriterionErrorReason;
+    });
+}
 
 /**
- * One of the `CriterionErrorReason` values.
+ * One of the reasons a {@link CriterionError} carries: a `CriterionError`
+ * static such as `CriterionError.InvalidRegex`.
+ *
+ * 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 type CriterionErrorReason = (typeof CriterionErrorReason)[keyof typeof CriterionErrorReason];
+export declare type CriterionErrorReason = (typeof CriterionError)[Exclude<keyof typeof CriterionError, keyof typeof ArazzoRunnerError | 'prototype'>];
 
 /**
  * A criterion condition that cannot be evaluated: a syntax error in the
@@ -562,10 +573,10 @@ export declare interface CriterionEvaluationRecord {
     readonly diagnostic?: {
         /**
          * Machine-readable: the `reason` of the error that failed the criterion, a
-         * `CriterionErrorReason` value or `'unavailable-expression'` for an
-         * HTTP-exchange expression in a step that calls a workflow.
+         * `CriterionErrorReason` or `RuntimeExpressionError.UnavailableExpression`
+         * for an HTTP-exchange expression in a step that calls a workflow.
          */
-        readonly code?: CriterionErrorReason | 'unavailable-expression';
+        readonly code?: CriterionErrorReason | typeof RuntimeExpressionError.UnavailableExpression;
         /**
          * Human-readable: names the condition or expression and, for a syntax
          * error, what is wrong with it; never request or response data.
@@ -763,18 +774,83 @@ export declare abstract class DocumentRegistryProvider {
  */
 export declare type DocumentRegistryProviderOptions = PartialDeep<ApiDOMReferenceOptions>;
 
-/** @public */
+/**
+ * Carries a `reason`, one of the class's static reason fields.
+ *
+ * Every static on this class is a reason: {@link ExecutionErrorReason} is
+ * derived from the class's own statics, so a non-reason static would join the
+ * union.
+ * @public
+ */
 export declare class ExecutionError extends ArazzoRunnerError {
+    /** The run was cancelled through its `AbortSignal`; the signal's reason is the `cause`. */
+    static readonly Aborted: "aborted";
+    /** A step or a `goto`/`retry` action declares more than one mutually exclusive target. */
+    static readonly AmbiguousTarget: "ambiguous-target";
+    /** The `dependsOn` edges alone form a cycle between workflows. */
+    static readonly DependsOnCycle: "dependsOn-cycle";
+    /** A `goto` action declares neither a `stepId` nor a `workflowId`. */
+    static readonly GotoTargetMissing: "goto-target-missing";
+    /** A `goto` action's `stepId` names no step in the workflow. */
+    static readonly GotoTargetNotFound: "goto-target-not-found";
+    /** An `operationId` or `operationPath` is not a valid operation reference. */
+    static readonly InvalidOperationReference: "invalid-operation-reference";
+    /** A `workflowId` is not a valid `$sourceDescriptions.{name}.{workflowId}` expression. */
+    static readonly InvalidWorkflowReference: "invalid-workflow-reference";
+    /** A workflow's `dependsOn` is not a list or holds a non-string entry. */
+    static readonly MalformedDependsOn: "malformed-dependsOn";
+    /** A workflow's `steps` is not a list or holds an entry that is not a Step Object. */
+    static readonly MalformedSteps: "malformed-steps";
+    /** A step run as an operation declares neither an `operationId` nor an `operationPath`. */
+    static readonly MissingOperation: "missing-operation";
+    /** An operation reference locates no operation in its OpenAPI source description. */
+    static readonly OperationNotFound: "operation-not-found";
+    /** A `retry` action references a step or workflow, but no run reference was given to run it. */
+    static readonly RetryReferenceUnsupported: "retry-reference-unsupported";
+    /** A `retry` action's `stepId` names no step in the workflow. */
+    static readonly RetryTargetNotFound: "retry-target-not-found";
+    /** A workflow reference names a source description that is not an Arazzo document. */
+    static readonly SourceDescriptionNotArazzo: "source-description-not-arazzo";
+    /** A reference names a source description the Arazzo document does not define. */
+    static readonly SourceDescriptionNotFound: "source-description-not-found";
+    /** An operation reference names a source description that is not an OpenAPI document. */
+    static readonly SourceDescriptionNotOpenAPI: "source-description-not-openapi";
+    /** A workflow exceeded its budget of step attempts. */
+    static readonly StepBudget: "step-budget";
+    /** An action declares a `type` other than `end`, `goto` or `retry`. */
+    static readonly UnknownActionType: "unknown-action-type";
+    /** `execute` received an option it does not know. */
+    static readonly UnknownExecuteOption: "unknown-execute-option";
+    /** A step produced a transition the workflow executor does not recognize. */
+    static readonly UnknownTransitionKind: "unknown-transition-kind";
+    /** A sub-workflow call (alone or together with `dependsOn`) forms a cycle between workflows. */
+    static readonly WorkflowCycle: "workflow-cycle";
+    /** Workflows nest deeper than the configured limit. */
+    static readonly WorkflowDepth: "workflow-depth";
+    /** A workflow reference names a workflow the Arazzo document does not define. */
+    static readonly WorkflowNotFound: "workflow-not-found";
+    /** A step that targets a workflow was handed to the step executor, which runs operations only. */
+    static readonly WorkflowStep: "workflow-step";
     readonly stepId?: string;
     readonly workflowId?: string;
-    readonly reason?: string;
+    readonly reason?: ExecutionErrorReason;
     /**
      * The chain of workflowIds the error concerns — the loop A → B → A for a
      * cycle, or the call chain in progress when a budget ran out.
      */
     readonly path?: readonly string[];
+    constructor(message?: string, options?: ApiDOMErrorOptions & {
+        readonly reason?: ExecutionErrorReason;
+    });
 }
 
+/**
+ * One of the reasons an {@link ExecutionError} carries: an `ExecutionError`
+ * static such as `ExecutionError.OperationNotFound`.
+ * @public
+ */
+export declare type ExecutionErrorReason = (typeof ExecutionError)[Exclude<keyof typeof ExecutionError, keyof typeof ArazzoRunnerError | 'prototype'>];
+
 /** @public */
 export declare class ExtractionError extends ArazzoRunnerError {
     readonly workflowId?: string;
@@ -1533,7 +1609,7 @@ export declare class OutputResolver extends ArazzoValueResolver {
      *
      * `scope` names the step or workflow the outputs belong to, for a thrown
      * {@link ResolverError}. An output value that is not a valid runtime
-     * expression throws with `reason: 'invalid-expression'`.
+     * expression throws with reason `ResolverError.InvalidExpression`.
      */
     resolve(outputs: StepOutputsElement | WorkflowOutputsElement | undefined, resolve: RuntimeExpressionResolver, scope: ResolverScope): Record<string, unknown>;
 }
@@ -1629,14 +1705,65 @@ export declare interface ResolvedRequestBody {
     readonly contentType?: string;
 }
 
-/** @public */
+/**
+ * Carries a `reason`, one of the class's static reason fields.
+ *
+ * Every static on this class is a reason: {@link ResolverErrorReason} is
+ * derived from the class's own statics, so a non-reason static would join the
+ * union.
+ * @public
+ */
 export declare class ResolverError extends ArazzoRunnerError {
+    /** A parameter cannot be delivered unambiguously at its location. */
+    static readonly AmbiguousDelivery: "ambiguous-delivery";
+    /** An output or a request body payload holds a value that is not a valid runtime expression. */
+    static readonly InvalidExpression: "invalid-expression";
+    /** A parameter's location (`in`) is not one of the known locations. */
+    static readonly InvalidLocation: "invalid-location";
+    /** An `onSuccess`/`onFailure` list holds an entry that is not a Success/Failure Action Object. */
+    static readonly MalformedActionEntry: "malformed-action-entry";
+    /** A step's `onSuccess` or `onFailure` is present but is not a list. */
+    static readonly MalformedActions: "malformed-actions";
+    /** A step's `successCriteria` or an action's `criteria` is present but is not a list. */
+    static readonly MalformedCriteria: "malformed-criteria";
+    /** A criteria list holds an entry that is not a Criterion Object. */
+    static readonly MalformedCriterion: "malformed-criterion";
+    /** A parameter's location (`in`) is not a string. */
+    static readonly MalformedLocation: "malformed-location";
+    /** A step's or workflow's `outputs` is present but is not a map. */
+    static readonly MalformedOutputs: "malformed-outputs";
+    /** `parameters` is present but is not a list. */
+    static readonly MalformedParameters: "malformed-parameters";
+    /** `requestBody.replacements` is present but is not a list. */
+    static readonly MalformedReplacements: "malformed-replacements";
+    /** `requestBody` is present but is not a map. */
+    static readonly MalformedRequestBody: "malformed-request-body";
+    /** A parameter of a step that targets an operation declares no location (`in`). */
+    static readonly MissingLocation: "missing-location";
+    /** A parameter has a missing or non-string `name`. */
+    static readonly MissingName: "missing-name";
+    /** A runtime expression in the request body did not resolve. */
+    static readonly UnresolvedExpression: "unresolved-expression";
+    /** A `requestBody` replacement target does not resolve in the payload. */
+    static readonly UnresolvedTarget: "unresolved-target";
+    /** A `requestBody` replacement target is not a JSON Pointer. */
+    static readonly UnsupportedTarget: "unsupported-target";
     readonly stepId?: string;
     readonly workflowId?: string;
     readonly target?: string;
-    readonly reason?: string;
+    readonly reason?: ResolverErrorReason;
+    constructor(message?: string, options?: ApiDOMErrorOptions & {
+        readonly reason?: ResolverErrorReason;
+    });
 }
 
+/**
+ * One of the reasons a {@link ResolverError} carries: a `ResolverError`
+ * static such as `ResolverError.MalformedParameters`.
+ * @public
+ */
+export declare type ResolverErrorReason = (typeof ResolverError)[Exclude<keyof typeof ResolverError, keyof typeof ArazzoRunnerError | 'prototype'>];
+
 /**
  * Identifies the step or workflow a resolver is resolving for. The wider
  * union {@link OutputResolver} takes, since it resolves both a step's
@@ -1736,12 +1863,42 @@ export declare interface RuntimeExpressionContext {
     readonly calledWorkflow?: RuntimeExpressionCalledWorkflowContext;
 }
 
-/** @public */
+/**
+ * Carries a `reason`, one of the class's static reason fields.
+ *
+ * Every static on this class is a reason: {@link RuntimeExpressionErrorReason}
+ * is derived from the class's own statics, so a non-reason static would join
+ * the union.
+ * @public
+ */
 export declare class RuntimeExpressionError extends ArazzoRunnerError {
+    /** The expression is not a valid runtime expression. */
+    static readonly InvalidExpression: "invalid-expression";
+    /** The runtime expression parser failed on the expression. */
+    static readonly ParseError: "parse-error";
+    /**
+     * The expression reads HTTP data (`$statusCode`, `$url`, `$method`, `$request`,
+     * `$response`) in a step that calls a workflow and so made no HTTP call.
+     */
+    static readonly UnavailableExpression: "unavailable-expression";
+    /** The expression could not be resolved against the evaluation context. */
+    static readonly UnresolvedReference: "unresolved-reference";
+    /** The parsed expression contains a node the evaluator does not support. */
+    static readonly UnsupportedNode: "unsupported-node";
     readonly expression?: string;
-    readonly reason?: string;
+    readonly reason?: RuntimeExpressionErrorReason;
+    constructor(message?: string, options?: ApiDOMErrorOptions & {
+        readonly reason?: RuntimeExpressionErrorReason;
+    });
 }
 
+/**
+ * One of the reasons a {@link RuntimeExpressionError} carries: a
+ * `RuntimeExpressionError` static such as `RuntimeExpressionError.ParseError`.
+ * @public
+ */
+export declare type RuntimeExpressionErrorReason = (typeof RuntimeExpressionError)[Exclude<keyof typeof RuntimeExpressionError, keyof typeof ArazzoRunnerError | 'prototype'>];
+
 /**
  * Evaluates Arazzo runtime expressions against a context.
  *
@@ -2055,7 +2212,7 @@ export declare class StepExecutor {
      * take precedence over it.
      *
      * A `signal` in that bag is honored here and not only at the transport: an
-     * already-aborted signal throws `reason: 'aborted'` instead of issuing a
+     * already-aborted signal throws with reason `ExecutionError.Aborted` instead of issuing a
      * request nobody is waiting for, whose wire-level cancellation would surface
      * as a transport {@link ClientError} — a request that failed on its own terms
      * — rather than as the withdrawal it is.
@@ -2251,6 +2408,31 @@ export declare class UnmatchedProviderError extends ArazzoRunnerError {
     readonly uri?: string;
 }
 
+/**
+ * A workflow of an Arazzo document, as listed by
+ * {@link ArazzoDocument.listWorkflows}.
+ * @public
+ */
+export declare interface WorkflowDescriptor {
+    /**
+     * The id `ArazzoRunner.execute` takes to run the workflow.
+     */
+    workflowId: WorkflowId;
+    /**
+     * JSON Pointer to the workflow within the document.
+     */
+    jsonPointer: JSONPointer;
+    /**
+     * Present only when the workflow has a string `summary`.
+     */
+    summary?: string;
+    /**
+     * Present only when the workflow has a string `description`, as written
+     * (CommonMark).
+     */
+    description?: string;
+}
+
 /**
  * Per-call options for {@link WorkflowExecutor.execute}.
  * @public
@@ -2301,7 +2483,7 @@ export declare interface WorkflowExecuteOptions {
      * `retryAfter` waits between attempts, so an aborted run stops at the next
      * boundary rather than working its way to the end of the workflow.
      *
-     * An aborted run throws {@link ExecutionError} with `reason: 'aborted'`,
+     * An aborted run throws {@link ExecutionError} with reason `ExecutionError.Aborted`,
      * naming the boundary it stopped at and carrying the signal's own `reason` as
      * the error's `cause`. It does not resolve as a `failed` result: cancellation
      * is not something the steps did, and the steps that never ran were not
@@ -2549,9 +2731,9 @@ export declare interface WorkflowExecutorOptions {
     readonly maxSteps?: number;
     /**
      * Upper bound on how deeply workflows may nest — a workflow entered while
-     * this many are already in progress throws `reason: 'workflow-depth'`.
+     * this many are already in progress throws with reason `ExecutionError.WorkflowDepth`.
      * Bounds *legitimate* (acyclic) nesting; a genuine cycle is caught earlier and
-     * separately by `reason: 'workflow-cycle'`. Defaults to 32.
+     * separately by reason `ExecutionError.WorkflowCycle`. Defaults to 32.
      *
      * The count includes the workflow `execute` was called with, so `1` permits
      * that workflow and forbids all nesting; a value below 1 leaves no room for

package/src/criterion/CriterionErrorReason.cjs

@@ -1,51 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-/**
- * 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
- */
-const CriterionErrorReason = {
-  /** The element is not a Criterion Object. */
-  InvalidCriterion: 'invalid-criterion',
-  /** The `condition` is missing or empty. */
-  MissingCondition: 'missing-condition',
-  /** The `type` is present but unreadable. */
-  InvalidType: 'invalid-type',
-  /** The `type` names no known criterion type. */
-  UnknownType: 'unknown-type',
-  /** The expression type `version` is present but not a string. */
-  InvalidVersion: 'invalid-version',
-  /** The expression type `version` is not the one this runner supports. */
-  UnsupportedVersion: 'unsupported-version',
-  /** The `context` is not a runtime expression. */
-  InvalidContext: 'invalid-context',
-  /** A `regex`, `jsonpath` or `xpath` criterion has no `context`. */
-  MissingContext: 'missing-context',
-  /** The `simple` condition cannot be parsed. */
-  InvalidSimple: 'invalid-simple',
-  /** The `regex` condition is not a valid regular expression. */
-  InvalidRegex: 'invalid-regex',
-  /** The `jsonpath` condition is not a valid JSONPath query. */
-  InvalidJSONPath: 'invalid-jsonpath',
-  /** The `xpath` condition is invalid or fails to evaluate. */
-  InvalidXPath: 'invalid-xpath',
-  /** The resolved `xpath` context is not XML. */
-  InvalidXPathContext: 'invalid-xpath-context'
-};
-
-/**
- * One of the `CriterionErrorReason` values.
- * @public
- */
-var _default = exports.default = CriterionErrorReason;

package/src/criterion/CriterionErrorReason.mjs

@@ -1,46 +0,0 @@
-/**
- * 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
- */
-const CriterionErrorReason = {
-  /** The element is not a Criterion Object. */
-  InvalidCriterion: 'invalid-criterion',
-  /** The `condition` is missing or empty. */
-  MissingCondition: 'missing-condition',
-  /** The `type` is present but unreadable. */
-  InvalidType: 'invalid-type',
-  /** The `type` names no known criterion type. */
-  UnknownType: 'unknown-type',
-  /** The expression type `version` is present but not a string. */
-  InvalidVersion: 'invalid-version',
-  /** The expression type `version` is not the one this runner supports. */
-  UnsupportedVersion: 'unsupported-version',
-  /** The `context` is not a runtime expression. */
-  InvalidContext: 'invalid-context',
-  /** A `regex`, `jsonpath` or `xpath` criterion has no `context`. */
-  MissingContext: 'missing-context',
-  /** The `simple` condition cannot be parsed. */
-  InvalidSimple: 'invalid-simple',
-  /** The `regex` condition is not a valid regular expression. */
-  InvalidRegex: 'invalid-regex',
-  /** The `jsonpath` condition is not a valid JSONPath query. */
-  InvalidJSONPath: 'invalid-jsonpath',
-  /** The `xpath` condition is invalid or fails to evaluate. */
-  InvalidXPath: 'invalid-xpath',
-  /** The resolved `xpath` context is not XML. */
-  InvalidXPathContext: 'invalid-xpath-context'
-};
-
-/**
- * One of the `CriterionErrorReason` values.
- * @public
- */
-
-export default CriterionErrorReason;