@usearazzo/runner 1.0.1-alpha.10 → 1.0.1-alpha.12

package/types/runner.d.ts

@@ -167,10 +167,79 @@ export declare class ArazzoDocumentRegistryProvider extends DocumentRegistryProv
  */
 export declare type ArazzoDocumentRegistryProviderOptions = DocumentRegistryProviderOptions;
 
+/**
+ * Runs the workflows of one Arazzo document.
+ *
+ * A thin facade over the building blocks: it wires a {@link DocumentRegistry},
+ * an {@link OpenAPIOperationExecutor}, a {@link StepExecutor} and a
+ * {@link WorkflowExecutor} with their defaults, so running a workflow takes a
+ * `load` and an `execute`. The building blocks stay public for callers that
+ * need to compose them differently.
+ * @public
+ */
+export declare class ArazzoRunner {
+    #private;
+    readonly document: ArazzoDocument;
+    readonly registry: DocumentRegistry;
+    /**
+     * Loads the entry Arazzo document at `uri` (a file system path or URL) and
+     * returns a runner bound to it.
+     *
+     * @throws UnmatchedProviderError - When no provider can load the document
+     * @throws InvalidEntryDocumentError - When the document is not an Arazzo
+     * document, or the given registry already backs another entry document
+     */
+    static load(uri: string, options?: ArazzoRunnerLoadOptions): Promise<ArazzoRunner>;
+    /**
+     * Binds a runner to an entry document the caller already acquired.
+     *
+     * @throws InvalidEntryDocumentError - When `document` is not the entry document of `registry`
+     */
+    constructor(options: ArazzoRunnerOptions);
+    /**
+     * Runs the named workflow to completion, returning its outcome; see
+     * {@link WorkflowExecutor.execute}.
+     */
+    execute(workflowId: WorkflowId, options?: WorkflowExecuteOptions): Promise<WorkflowExecutionResult>;
+}
+
 /** @public */
 export declare class ArazzoRunnerError extends ApiDOMStructuredError {
 }
 
+/**
+ * Options for {@link ArazzoRunner.load}.
+ *
+ * Every option is a seam of a building block the runner wires: `registry` is
+ * the {@link DocumentRegistry} the documents load into (a fresh one with the
+ * default providers when omitted), `httpClient` and `requestInterceptor` go to
+ * the {@link OpenAPIOperationExecutor}, and the rest go to the
+ * {@link WorkflowExecutor}.
+ * @public
+ */
+export declare interface ArazzoRunnerLoadOptions extends Pick<OpenAPIOperationExecutorOptions, 'httpClient' | 'requestInterceptor'>, Pick<WorkflowExecutorOptions, 'maxSteps' | 'maxWorkflowDepth' | 'sleep' | 'now'> {
+    /**
+     * The registry to load the documents into. A registry backs one entry
+     * document: loading a different one into it throws.
+     */
+    readonly registry?: DocumentRegistry;
+}
+
+/**
+ * Options for the ArazzoRunner constructor.
+ * @public
+ */
+export declare interface ArazzoRunnerOptions extends Omit<ArazzoRunnerLoadOptions, 'registry'> {
+    /**
+     * The entry Arazzo document holding the workflows to run.
+     */
+    readonly document: ArazzoDocument;
+    /**
+     * The document registry whose entry document is `document`.
+     */
+    readonly registry: DocumentRegistry;
+}
+
 /**
  * Index mapping a source description name to its element and canonical URI in
  * an Arazzo document.
@@ -1192,15 +1261,23 @@ export declare interface OpenAPIOperationRequestInfo {
 
 /**
  * Response from an OpenAPI operation execution.
+ *
+ * `body` is the payload parsed by its content type, what `$response.body`
+ * reads. The body as received is read through `text()`, `blob()` and
+ * `bytes()`, named after the WHATWG `Response` methods but synchronous, and
+ * empty when the response carried no body (e.g. `204`, `304`). `bytes()` and
+ * `blob()` always return the bytes received. A body that is valid UTF-8 is held
+ * as its decoded string, which a plain-text or XML `body` shares rather than
+ * duplicates, and is encoded back on read; any other body is held as bytes.
  * @public
  */
 export declare class OpenAPIOperationResponse {
+    #private;
     readonly ok: boolean;
     readonly url: string;
     readonly status: number;
     readonly statusText: string;
     readonly headers: Record<string, string>;
-    readonly text: string;
     readonly body: unknown;
     readonly request: OpenAPIOperationRequestInfo | undefined;
     constructor(raw: {
@@ -1209,10 +1286,24 @@ export declare class OpenAPIOperationResponse {
         status: number;
         statusText: string;
         headers: Record<string, string>;
-        text: string;
         body: unknown;
+        content: string | Uint8Array;
         request?: OpenAPIOperationRequestInfo;
     });
+    /**
+     * The body as text, like `Response.text()`; `''` when there is none.
+     */
+    text(): string;
+    /**
+     * The body as a `Blob` typed by the response's `Content-Type`, like
+     * `Response.blob()`.
+     */
+    blob(): Blob;
+    /**
+     * The body as bytes, like `Response.bytes()`; a fresh copy on every call, so
+     * the response stays immutable.
+     */
+    bytes(): Uint8Array;
 }
 
 /**
@@ -1226,10 +1317,15 @@ export declare class OpenAPIOperationResponse {
  * Headers are taken from the `Response` directly rather than from the
  * deserializer, which splits every value containing `", "` into an array:
  * values stay strings as sent, with repeated fields (`Set-Cookie` included)
- * combined by `Headers.get`.
+ * combined by `Headers.get`. The body is read once, as bytes, and handed to the
+ * deserializer from memory. A body that decodes as UTF-8 without loss is kept
+ * as that one string, the same one the deserializer parses, so a plain-text or
+ * XML `body` shares it; any other body (binary, another charset, a leading
+ * byte-order mark) is kept as the bytes, so they are never re-encoded lossily.
  * @public
  */
 export declare class OpenAPIOperationResponseNormalizer {
+    #private;
     /**
      * Deserializes the response body by content type and maps the result into the
      * runner's response model. `request` is the request the operation was