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

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@usearazzo/runner",
-  "version": "1.0.1-alpha.10",
+  "version": "1.0.1-alpha.12",
   "description": "Runner for Arazzo Workflows.",
   "keywords": [
     "arazzo",
     "arazzo-specification",
     "runner",
+    "execute",
+    "executor",
     "workflow",
-    "workflows"
+    "workflows",
+    "api",
+    "api-workflow"
   ],
   "publishConfig": {
     "access": "public",
@@ -68,8 +72,8 @@
     "@swaggerexpert/json-pointer": "^3.0.2",
     "@swaggerexpert/jsonpath": "^4.0.5",
     "@swaggerexpert/media-types": "^1.0.1",
-    "@usearazzo/parser": "1.0.1-alpha.10",
-    "@usearazzo/resolver": "1.0.1-alpha.10",
+    "@usearazzo/parser": "1.0.1-alpha.12",
+    "@usearazzo/resolver": "1.0.1-alpha.12",
     "@xmldom/xmldom": "^0.9.12",
     "fontoxpath": "^3.34.0",
     "ramda": "^0.32.0",
@@ -89,5 +93,5 @@
   "devDependencies": {
     "swagger-client": "^3.38.4"
   },
-  "gitHead": "b940d0343c00a30130ca1926479651bd45ee4bdb"
+  "gitHead": "cc5d9b2fb744662650068a5993ebcdd19e8568c2"
 }

package/src/ArazzoRunner.cjs

@@ -0,0 +1,122 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _DocumentRegistry = _interopRequireDefault(require("./registry/DocumentRegistry.cjs"));
+var _OpenAPIOperationExecutor = _interopRequireDefault(require("./executor/OpenAPIOperationExecutor.cjs"));
+var _StepExecutor = _interopRequireDefault(require("./executor/StepExecutor.cjs"));
+var _WorkflowExecutor = _interopRequireDefault(require("./executor/WorkflowExecutor.cjs"));
+var _InvalidEntryDocumentError = _interopRequireDefault(require("./errors/InvalidEntryDocumentError.cjs"));
+/**
+ * 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
+ */
+
+/**
+ * Options for the ArazzoRunner constructor.
+ * @public
+ */
+
+/**
+ * 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
+ */
+class ArazzoRunner {
+  document;
+  registry;
+  #executor;
+
+  /**
+   * 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 async load(uri, options = {}) {
+    const {
+      registry = new _DocumentRegistry.default(),
+      ...rest
+    } = options;
+    // acquiring a second entry would pin it for good and, through the LRU
+    // order, could displace the first as the registry's entry; a registry that
+    // already backs one only looks the document up.
+    const entry = registry.entryDocument ?? (await registry.acquireEntryDocument(uri));
+    const document = await registry.acquire(uri);
+    if (document !== entry) {
+      throw new _InvalidEntryDocumentError.default(`Document at "${uri}" is not the entry document of the given registry`, {
+        uri
+      });
+    }
+    return new ArazzoRunner({
+      ...rest,
+      document: entry,
+      registry
+    });
+  }
+
+  /**
+   * Binds a runner to an entry document the caller already acquired.
+   *
+   * @throws InvalidEntryDocumentError - When `document` is not the entry document of `registry`
+   */
+  constructor(options) {
+    const {
+      document,
+      registry,
+      httpClient,
+      requestInterceptor,
+      ...workflowExecutorOptions
+    } = options;
+
+    // a registry pins every entry document it acquires but reports only the
+    // first as its entry, so one registry serves one entry document.
+    if (registry.entryDocument !== document) {
+      throw new _InvalidEntryDocumentError.default(`Document at "${document.uri}" is not the entry document of the given registry`, {
+        uri: document.uri
+      });
+    }
+    const operationExecutor = new _OpenAPIOperationExecutor.default({
+      httpClient,
+      requestInterceptor
+    });
+    const stepExecutor = new _StepExecutor.default({
+      document,
+      registry,
+      operationExecutor
+    });
+    this.document = document;
+    this.registry = registry;
+    this.#executor = new _WorkflowExecutor.default({
+      ...workflowExecutorOptions,
+      document,
+      registry,
+      stepExecutor
+    });
+  }
+
+  /**
+   * Runs the named workflow to completion, returning its outcome; see
+   * {@link WorkflowExecutor.execute}.
+   */
+  execute(workflowId, options = {}) {
+    return this.#executor.execute(workflowId, options);
+  }
+}
+var _default = exports.default = ArazzoRunner;

package/src/ArazzoRunner.mjs

@@ -0,0 +1,113 @@
+import DocumentRegistry from "./registry/DocumentRegistry.mjs";
+import OpenAPIOperationExecutor from "./executor/OpenAPIOperationExecutor.mjs";
+import StepExecutor from "./executor/StepExecutor.mjs";
+import WorkflowExecutor from "./executor/WorkflowExecutor.mjs";
+import InvalidEntryDocumentError from "./errors/InvalidEntryDocumentError.mjs";
+/**
+ * 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
+ */
+/**
+ * Options for the ArazzoRunner constructor.
+ * @public
+ */
+/**
+ * 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
+ */
+class ArazzoRunner {
+  document;
+  registry;
+  #executor;
+
+  /**
+   * 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 async load(uri, options = {}) {
+    const {
+      registry = new DocumentRegistry(),
+      ...rest
+    } = options;
+    // acquiring a second entry would pin it for good and, through the LRU
+    // order, could displace the first as the registry's entry; a registry that
+    // already backs one only looks the document up.
+    const entry = registry.entryDocument ?? (await registry.acquireEntryDocument(uri));
+    const document = await registry.acquire(uri);
+    if (document !== entry) {
+      throw new InvalidEntryDocumentError(`Document at "${uri}" is not the entry document of the given registry`, {
+        uri
+      });
+    }
+    return new ArazzoRunner({
+      ...rest,
+      document: entry,
+      registry
+    });
+  }
+
+  /**
+   * Binds a runner to an entry document the caller already acquired.
+   *
+   * @throws InvalidEntryDocumentError - When `document` is not the entry document of `registry`
+   */
+  constructor(options) {
+    const {
+      document,
+      registry,
+      httpClient,
+      requestInterceptor,
+      ...workflowExecutorOptions
+    } = options;
+
+    // a registry pins every entry document it acquires but reports only the
+    // first as its entry, so one registry serves one entry document.
+    if (registry.entryDocument !== document) {
+      throw new InvalidEntryDocumentError(`Document at "${document.uri}" is not the entry document of the given registry`, {
+        uri: document.uri
+      });
+    }
+    const operationExecutor = new OpenAPIOperationExecutor({
+      httpClient,
+      requestInterceptor
+    });
+    const stepExecutor = new StepExecutor({
+      document,
+      registry,
+      operationExecutor
+    });
+    this.document = document;
+    this.registry = registry;
+    this.#executor = new WorkflowExecutor({
+      ...workflowExecutorOptions,
+      document,
+      registry,
+      stepExecutor
+    });
+  }
+
+  /**
+   * Runs the named workflow to completion, returning its outcome; see
+   * {@link WorkflowExecutor.execute}.
+   */
+  execute(workflowId, options = {}) {
+    return this.#executor.execute(workflowId, options);
+  }
+}
+export default ArazzoRunner;

package/src/client/OpenAPIOperationResponse.cjs

@@ -17,6 +17,14 @@ exports.default = void 0;
 
 /**
  * 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
  */
 class OpenAPIOperationResponse {
@@ -25,18 +33,45 @@ class OpenAPIOperationResponse {
   status;
   statusText;
   headers;
-  text;
   body;
   request;
+  #content;
   constructor(raw) {
     this.ok = raw.ok;
     this.url = raw.url;
     this.status = raw.status;
     this.statusText = raw.statusText;
     this.headers = raw.headers;
-    this.text = raw.text;
     this.body = raw.body;
+    this.#content = raw.content;
     this.request = raw.request;
   }
+
+  /**
+   * The body as text, like `Response.text()`; `''` when there is none.
+   */
+  text() {
+    return typeof this.#content === 'string' ? this.#content : new TextDecoder().decode(this.#content);
+  }
+
+  /**
+   * The body as a `Blob` typed by the response's `Content-Type`, like
+   * `Response.blob()`.
+   */
+  blob() {
+    // the lib types only take ArrayBuffer-backed views; the normalizer never
+    // produces a shared one.
+    return new Blob([this.#content], {
+      type: this.headers['content-type'] ?? ''
+    });
+  }
+
+  /**
+   * The body as bytes, like `Response.bytes()`; a fresh copy on every call, so
+   * the response stays immutable.
+   */
+  bytes() {
+    return typeof this.#content === 'string' ? new TextEncoder().encode(this.#content) : this.#content.slice();
+  }
 }
 var _default = exports.default = OpenAPIOperationResponse;

package/src/client/OpenAPIOperationResponse.mjs

@@ -11,6 +11,14 @@
 
 /**
  * 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
  */
 class OpenAPIOperationResponse {
@@ -19,18 +27,45 @@ class OpenAPIOperationResponse {
   status;
   statusText;
   headers;
-  text;
   body;
   request;
+  #content;
   constructor(raw) {
     this.ok = raw.ok;
     this.url = raw.url;
     this.status = raw.status;
     this.statusText = raw.statusText;
     this.headers = raw.headers;
-    this.text = raw.text;
     this.body = raw.body;
+    this.#content = raw.content;
     this.request = raw.request;
   }
+
+  /**
+   * The body as text, like `Response.text()`; `''` when there is none.
+   */
+  text() {
+    return typeof this.#content === 'string' ? this.#content : new TextDecoder().decode(this.#content);
+  }
+
+  /**
+   * The body as a `Blob` typed by the response's `Content-Type`, like
+   * `Response.blob()`.
+   */
+  blob() {
+    // the lib types only take ArrayBuffer-backed views; the normalizer never
+    // produces a shared one.
+    return new Blob([this.#content], {
+      type: this.headers['content-type'] ?? ''
+    });
+  }
+
+  /**
+   * The body as bytes, like `Response.bytes()`; a fresh copy on every call, so
+   * the response stays immutable.
+   */
+  bytes() {
+    return typeof this.#content === 'string' ? new TextEncoder().encode(this.#content) : this.#content.slice();
+  }
 }
 export default OpenAPIOperationResponse;

package/src/client/OpenAPIOperationResponseNormalizer.cjs

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
+var _mediaTypes = require("@swaggerexpert/media-types");
 var _swaggerClient = require("../vendor/swagger-client.cjs");
 var _OpenAPIOperationResponse = _interopRequireDefault(require("./OpenAPIOperationResponse.cjs"));
 // @ts-expect-error vendored swagger-client bundle has no type declarations
@@ -20,7 +21,11 @@ var _OpenAPIOperationResponse = _interopRequireDefault(require("./OpenAPIOperati
  * 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
  */
 class OpenAPIOperationResponseNormalizer {
@@ -31,7 +36,30 @@ class OpenAPIOperationResponseNormalizer {
    * carries none (e.g. a stubbed transport).
    */
   async normalize(response, request) {
-    const deserialized = await (0, _swaggerClient.deserializeResponse)(response, request?.url);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const text = this.#decodeLosslessly(bytes);
+    // the deserializer matches the raw Content-Type case-sensitively and against
+    // its parameters too, so it is handed only the parsed essence; the response's
+    // own `headers` below stay as sent.
+    const deserializerHeaders = new Headers(response.headers);
+    const contentType = response.headers.get('content-type');
+    const mediaType = contentType === null ? undefined : (0, _mediaTypes.parse)(contentType, {
+      type: 'media-type'
+    }).tree;
+    if (mediaType !== undefined) {
+      deserializerHeaders.set('content-type', `${mediaType.type}/${mediaType.subtype}`);
+    }
+    // the deserializer only reads the body through text() or blob(), by content
+    // type; answering from memory spares a second copy of the stream.
+    const deserialized = await (0, _swaggerClient.deserializeResponse)({
+      ok: response.ok,
+      url: response.url,
+      status: response.status,
+      statusText: response.statusText,
+      headers: deserializerHeaders,
+      text: async () => text ?? new TextDecoder().decode(bytes),
+      blob: async () => new Blob([bytes])
+    }, request?.url);
     const headers = Object.fromEntries(Array.from(response.headers.keys(), name => [name, response.headers.get(name)]));
     return new _OpenAPIOperationResponse.default({
       ok: deserialized.ok,
@@ -39,10 +67,26 @@ class OpenAPIOperationResponseNormalizer {
       status: deserialized.status,
       statusText: deserialized.statusText,
       headers,
-      text: deserialized.text,
       body: deserialized.body,
+      content: text ?? bytes,
       request
     });
   }
+
+  /**
+   * The bytes as a string that encodes back to exactly them, or `undefined`
+   * when there is none: invalid UTF-8, or a leading byte-order mark, which
+   * decoding strips.
+   */
+  #decodeLosslessly(bytes) {
+    if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return undefined;
+    try {
+      return new TextDecoder('utf-8', {
+        fatal: true
+      }).decode(bytes);
+    } catch {
+      return undefined;
+    }
+  }
 }
 var _default = exports.default = OpenAPIOperationResponseNormalizer;

package/src/client/OpenAPIOperationResponseNormalizer.mjs

@@ -1,3 +1,5 @@
+import { parse } from '@swaggerexpert/media-types';
+
 // @ts-expect-error vendored swagger-client bundle has no type declarations
 import { deserializeResponse } from '../vendor/swagger-client.mjs';
 import OpenAPIOperationResponse from "./OpenAPIOperationResponse.mjs";
@@ -12,7 +14,11 @@ import OpenAPIOperationResponse from "./OpenAPIOperationResponse.mjs";
  * 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
  */
 class OpenAPIOperationResponseNormalizer {
@@ -23,7 +29,30 @@ class OpenAPIOperationResponseNormalizer {
    * carries none (e.g. a stubbed transport).
    */
   async normalize(response, request) {
-    const deserialized = await deserializeResponse(response, request?.url);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const text = this.#decodeLosslessly(bytes);
+    // the deserializer matches the raw Content-Type case-sensitively and against
+    // its parameters too, so it is handed only the parsed essence; the response's
+    // own `headers` below stay as sent.
+    const deserializerHeaders = new Headers(response.headers);
+    const contentType = response.headers.get('content-type');
+    const mediaType = contentType === null ? undefined : parse(contentType, {
+      type: 'media-type'
+    }).tree;
+    if (mediaType !== undefined) {
+      deserializerHeaders.set('content-type', `${mediaType.type}/${mediaType.subtype}`);
+    }
+    // the deserializer only reads the body through text() or blob(), by content
+    // type; answering from memory spares a second copy of the stream.
+    const deserialized = await deserializeResponse({
+      ok: response.ok,
+      url: response.url,
+      status: response.status,
+      statusText: response.statusText,
+      headers: deserializerHeaders,
+      text: async () => text ?? new TextDecoder().decode(bytes),
+      blob: async () => new Blob([bytes])
+    }, request?.url);
     const headers = Object.fromEntries(Array.from(response.headers.keys(), name => [name, response.headers.get(name)]));
     return new OpenAPIOperationResponse({
       ok: deserialized.ok,
@@ -31,10 +60,26 @@ class OpenAPIOperationResponseNormalizer {
       status: deserialized.status,
       statusText: deserialized.statusText,
       headers,
-      text: deserialized.text,
       body: deserialized.body,
+      content: text ?? bytes,
       request
     });
   }
+
+  /**
+   * The bytes as a string that encodes back to exactly them, or `undefined`
+   * when there is none: invalid UTF-8, or a leading byte-order mark, which
+   * decoding strips.
+   */
+  #decodeLosslessly(bytes) {
+    if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return undefined;
+    try {
+      return new TextDecoder('utf-8', {
+        fatal: true
+      }).decode(bytes);
+    } catch {
+      return undefined;
+    }
+  }
 }
 export default OpenAPIOperationResponseNormalizer;

package/src/index.cjs

@@ -29,6 +29,12 @@ Object.defineProperty(exports, "ArazzoDocumentRegistryProvider", {
     return _ArazzoDocumentRegistryProvider.default;
   }
 });
+Object.defineProperty(exports, "ArazzoRunner", {
+  enumerable: true,
+  get: function () {
+    return _ArazzoRunner.default;
+  }
+});
 Object.defineProperty(exports, "ArazzoRunnerError", {
   enumerable: true,
   get: function () {
@@ -359,6 +365,7 @@ Object.defineProperty(exports, "settledResult", {
     return _WorkflowExecutor.settledResult;
   }
 });
+var _ArazzoRunner = _interopRequireDefault(require("./ArazzoRunner.cjs"));
 var _DocumentRegistry = _interopRequireDefault(require("./registry/DocumentRegistry.cjs"));
 var _DocumentRegistryProvider = _interopRequireDefault(require("./registry/providers/DocumentRegistryProvider.cjs"));
 var _ArazzoDocumentRegistryProvider = _interopRequireDefault(require("./registry/providers/ArazzoDocumentRegistryProvider.cjs"));

package/src/index.mjs

@@ -1,3 +1,5 @@
+/* Runner */
+export { default as ArazzoRunner } from "./ArazzoRunner.mjs";
 /* Document Registry */
 export { default as DocumentRegistry } from "./registry/DocumentRegistry.mjs";
 /* Document Registry Providers */