@usearazzo/runner 0.0.0-stage → 1.0.1-alpha.11

package/src/assembler/OpenAPIDocumentAssembler.cjs

@@ -0,0 +1,58 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
+var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
+var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
+var _AssemblerError = _interopRequireDefault(require("../errors/AssemblerError.cjs"));
+var _OpenAPI2DocumentAssembler = _interopRequireDefault(require("./OpenAPI2DocumentAssembler.cjs"));
+var _OpenAPI30DocumentAssembler = _interopRequireDefault(require("./OpenAPI30DocumentAssembler.cjs"));
+var _OpenAPI31DocumentAssembler = _interopRequireDefault(require("./OpenAPI31DocumentAssembler.cjs"));
+/**
+ * Options for the OpenAPI document assembler facade.
+ * @public
+ */
+
+/**
+ * Facade for assembling standalone OpenAPI documents across all supported versions.
+ *
+ * Detects the OpenAPI version from the source document and delegates to the
+ * appropriate version-specific assembler (2.0, 3.0, or 3.1).
+ *
+ * Custom assembler instances can be provided via constructor options.
+ * @public
+ */
+class OpenAPIDocumentAssembler {
+  #openapi2;
+  #openapi30;
+  #openapi31;
+  constructor(options = {}) {
+    this.#openapi2 = options.openapi2 ?? new _OpenAPI2DocumentAssembler.default();
+    this.#openapi30 = options.openapi30 ?? new _OpenAPI30DocumentAssembler.default();
+    this.#openapi31 = options.openapi31 ?? new _OpenAPI31DocumentAssembler.default();
+  }
+
+  /**
+   * Assembles a standalone OpenAPI document by delegating to the version-specific assembler.
+   */
+  assemble(operation, document) {
+    const root = document.parseResult.api;
+    if ((0, _apidomNsOpenapi.isSwaggerElement)(root)) {
+      return this.#openapi2.assemble(operation, document);
+    }
+    if ((0, _apidomNsOpenapi2.isOpenApi3_0Element)(root)) {
+      return this.#openapi30.assemble(operation, document);
+    }
+    if ((0, _apidomNsOpenapi3.isOpenApi3_1Element)(root)) {
+      return this.#openapi31.assemble(operation, document);
+    }
+    throw new _AssemblerError.default(`Unsupported OpenAPI version in document at "${document.uri}"`, {
+      uri: document.uri
+    });
+  }
+}
+var _default = exports.default = OpenAPIDocumentAssembler;

package/src/assembler/OpenAPIDocumentAssembler.mjs

@@ -0,0 +1,50 @@
+import { isSwaggerElement } from '@speclynx/apidom-ns-openapi-2';
+import { isOpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';
+import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
+import AssemblerError from "../errors/AssemblerError.mjs";
+import OpenAPI2DocumentAssembler from "./OpenAPI2DocumentAssembler.mjs";
+import OpenAPI30DocumentAssembler from "./OpenAPI30DocumentAssembler.mjs";
+import OpenAPI31DocumentAssembler from "./OpenAPI31DocumentAssembler.mjs";
+/**
+ * Options for the OpenAPI document assembler facade.
+ * @public
+ */
+/**
+ * Facade for assembling standalone OpenAPI documents across all supported versions.
+ *
+ * Detects the OpenAPI version from the source document and delegates to the
+ * appropriate version-specific assembler (2.0, 3.0, or 3.1).
+ *
+ * Custom assembler instances can be provided via constructor options.
+ * @public
+ */
+class OpenAPIDocumentAssembler {
+  #openapi2;
+  #openapi30;
+  #openapi31;
+  constructor(options = {}) {
+    this.#openapi2 = options.openapi2 ?? new OpenAPI2DocumentAssembler();
+    this.#openapi30 = options.openapi30 ?? new OpenAPI30DocumentAssembler();
+    this.#openapi31 = options.openapi31 ?? new OpenAPI31DocumentAssembler();
+  }
+
+  /**
+   * Assembles a standalone OpenAPI document by delegating to the version-specific assembler.
+   */
+  assemble(operation, document) {
+    const root = document.parseResult.api;
+    if (isSwaggerElement(root)) {
+      return this.#openapi2.assemble(operation, document);
+    }
+    if (isOpenApi3_0Element(root)) {
+      return this.#openapi30.assemble(operation, document);
+    }
+    if (isOpenApi3_1Element(root)) {
+      return this.#openapi31.assemble(operation, document);
+    }
+    throw new AssemblerError(`Unsupported OpenAPI version in document at "${document.uri}"`, {
+      uri: document.uri
+    });
+  }
+}
+export default OpenAPIDocumentAssembler;

package/src/client/HTTPClient.cjs

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/src/client/HTTPClient.mjs

@@ -0,0 +1 @@
+export {};

package/src/client/HTTPClientFetch.cjs

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+/**
+ * The default {@link HTTPClient}: global fetch.
+ *
+ * Mirrors swagger-client's own transport line — the request object doubles as
+ * fetch init, so `method`, `headers`, `body`, `credentials`, and `signal` are
+ * picked up from it directly.
+ * @public
+ */
+const httpClientFetch = request => fetch(request.url, request);
+var _default = exports.default = httpClientFetch;

package/src/client/HTTPClientFetch.mjs

@@ -0,0 +1,10 @@
+/**
+ * The default {@link HTTPClient}: global fetch.
+ *
+ * Mirrors swagger-client's own transport line — the request object doubles as
+ * fetch init, so `method`, `headers`, `body`, `credentials`, and `signal` are
+ * picked up from it directly.
+ * @public
+ */
+const httpClientFetch = request => fetch(request.url, request);
+export default httpClientFetch;

package/src/client/OpenAPIOperationRequest.cjs

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/src/client/OpenAPIOperationRequest.mjs

@@ -0,0 +1 @@
+export {};

package/src/client/OpenAPIOperationResponse.cjs

@@ -0,0 +1,42 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+/**
+ * The HTTP request an OpenAPI operation was executed with.
+ *
+ * An immutable snapshot of the request as actually sent, recorded by the
+ * executor after the interceptors ran and before the transport was called, so
+ * runtime expressions (`$url`, `$method`, `$request.header.*`, `$request.body`)
+ * can be evaluated against it after execution. `headers` is a copy taken at
+ * capture time; `body` shares its reference with the sent request.
+ * @public
+ */
+
+/**
+ * Response from an OpenAPI operation execution.
+ * @public
+ */
+class OpenAPIOperationResponse {
+  ok;
+  url;
+  status;
+  statusText;
+  headers;
+  text;
+  body;
+  request;
+  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.request = raw.request;
+  }
+}
+var _default = exports.default = OpenAPIOperationResponse;

package/src/client/OpenAPIOperationResponse.mjs

@@ -0,0 +1,36 @@
+/**
+ * The HTTP request an OpenAPI operation was executed with.
+ *
+ * An immutable snapshot of the request as actually sent, recorded by the
+ * executor after the interceptors ran and before the transport was called, so
+ * runtime expressions (`$url`, `$method`, `$request.header.*`, `$request.body`)
+ * can be evaluated against it after execution. `headers` is a copy taken at
+ * capture time; `body` shares its reference with the sent request.
+ * @public
+ */
+
+/**
+ * Response from an OpenAPI operation execution.
+ * @public
+ */
+class OpenAPIOperationResponse {
+  ok;
+  url;
+  status;
+  statusText;
+  headers;
+  text;
+  body;
+  request;
+  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.request = raw.request;
+  }
+}
+export default OpenAPIOperationResponse;

package/src/client/OpenAPIOperationResponseNormalizer.cjs

@@ -0,0 +1,48 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _swaggerClient = require("../vendor/swagger-client.cjs");
+var _OpenAPIOperationResponse = _interopRequireDefault(require("./OpenAPIOperationResponse.cjs"));
+// @ts-expect-error vendored swagger-client bundle has no type declarations
+
+/**
+ * Normalizes a raw WHATWG `Response` into an {@link OpenAPIOperationResponse}.
+ *
+ * Wraps the vendored swagger-client response deserializer (upstream
+ * `serializeRes`, aliased at the vendor boundary), whose battle-tested
+ * content-type dispatch (JSON/XML/YAML/text vs binary) means the response
+ * model runtime expressions and criteria see is defined here, on the runner's
+ * side of the {@link HTTPClient} seam, and stays identical across transports.
+ * 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`.
+ * @public
+ */
+class OpenAPIOperationResponseNormalizer {
+  /**
+   * Deserializes the response body by content type and maps the result into the
+   * runner's response model. `request` is the request the operation was
+   * executed with; its `url` doubles as the fallback when the `Response`
+   * carries none (e.g. a stubbed transport).
+   */
+  async normalize(response, request) {
+    const deserialized = await (0, _swaggerClient.deserializeResponse)(response, request?.url);
+    const headers = Object.fromEntries(Array.from(response.headers.keys(), name => [name, response.headers.get(name)]));
+    return new _OpenAPIOperationResponse.default({
+      ok: deserialized.ok,
+      url: deserialized.url,
+      status: deserialized.status,
+      statusText: deserialized.statusText,
+      headers,
+      text: deserialized.text,
+      body: deserialized.body,
+      request
+    });
+  }
+}
+var _default = exports.default = OpenAPIOperationResponseNormalizer;

package/src/client/OpenAPIOperationResponseNormalizer.mjs

@@ -0,0 +1,40 @@
+// @ts-expect-error vendored swagger-client bundle has no type declarations
+import { deserializeResponse } from '../vendor/swagger-client.mjs';
+import OpenAPIOperationResponse from "./OpenAPIOperationResponse.mjs";
+/**
+ * Normalizes a raw WHATWG `Response` into an {@link OpenAPIOperationResponse}.
+ *
+ * Wraps the vendored swagger-client response deserializer (upstream
+ * `serializeRes`, aliased at the vendor boundary), whose battle-tested
+ * content-type dispatch (JSON/XML/YAML/text vs binary) means the response
+ * model runtime expressions and criteria see is defined here, on the runner's
+ * side of the {@link HTTPClient} seam, and stays identical across transports.
+ * 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`.
+ * @public
+ */
+class OpenAPIOperationResponseNormalizer {
+  /**
+   * Deserializes the response body by content type and maps the result into the
+   * runner's response model. `request` is the request the operation was
+   * executed with; its `url` doubles as the fallback when the `Response`
+   * carries none (e.g. a stubbed transport).
+   */
+  async normalize(response, request) {
+    const deserialized = await deserializeResponse(response, request?.url);
+    const headers = Object.fromEntries(Array.from(response.headers.keys(), name => [name, response.headers.get(name)]));
+    return new OpenAPIOperationResponse({
+      ok: deserialized.ok,
+      url: deserialized.url,
+      status: deserialized.status,
+      statusText: deserialized.statusText,
+      headers,
+      text: deserialized.text,
+      body: deserialized.body,
+      request
+    });
+  }
+}
+export default OpenAPIOperationResponseNormalizer;

package/src/client/ParameterDelivery.cjs

@@ -0,0 +1,119 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+/**
+ * The outcome of claiming a delivery key: `claimed` for a first claim,
+ * `duplicate` when the same `(name, in)` parameter claims its key again, and
+ * `collision` when a *different* parameter produces an already-claimed key.
+ * @internal
+ */
+
+/**
+ * A parameter claim: the delivery key the `(location, name)` pair encodes to,
+ * and how the claim resolved against the map's earlier entries.
+ * @internal
+ */
+
+/**
+ * The parameters map an OpenAPI operation is executed with — the single owner
+ * of the vendored swagger-client's parameter-addressing scheme.
+ *
+ * The client accepts two key shapes in its `parameters` map and, for each
+ * parameter the operation declares, consults the bare `name` *before* the
+ * qualified `'{in}.{name}'` key (deminified from the vendored bundle:
+ * `r = m[e.name]; if (r === undefined) r = m[`${e.in}.${e.name}`]`). Two
+ * consequences shape everything that feeds the map:
+ *
+ * - qualified keys are what let parameters differing only in their location
+ *   coexist — the client builds the same key from the declared parameter and
+ *   matches it verbatim, never splitting it, so dots in a name are safe;
+ * - a bare key silently outranks the qualified keys of every declared
+ *   parameter bearing that name, so nothing may emit one for a location the
+ *   client can address.
+ *
+ * Arazzo's `querystring` is the one location the client cannot address — it
+ * names no OpenAPI location — so it keeps the bare name, which can still
+ * reach a same-named declared parameter. Every other location is qualified,
+ * including an unrecognized one: an unmatched qualified key is inert, where a
+ * bare one would capture.
+ *
+ * Keys are claimed first-wins. The scheme is not injective, so the map also
+ * discriminates a genuine duplicate from a collision of two different
+ * parameters on one key: given a key, the claimant's name is determined by
+ * its location (the key embeds the name, or is the name), so the location
+ * alone identifies the claimant. A bare key and a qualified key sharing one
+ * name are a collision too, even though the keys differ — the client consults
+ * the bare name first for every declared parameter bearing it, so the bare
+ * entry would silently capture the qualified one. What to do about a
+ * collision is the caller's policy — the map only reports it.
+ *
+ * Diff this against the vendored bundle's lookup when bumping swagger-client.
+ * @internal
+ */
+class ParameterDelivery {
+  /**
+   * The key a `(location, name)` pair is delivered under — `'{in}.{name}'`,
+   * or the bare name for `querystring`. See the class doc for why.
+   */
+  static keyFor(location, name) {
+    return location === 'querystring' ? name : `${location}.${name}`;
+  }
+  #values = {};
+  #claimedBy = new Map();
+  #bareNames = new Set();
+  #qualifiedNames = new Set();
+
+  /**
+   * Claims the delivery key for a `(location, name)` pair, first-wins.
+   * Only a `claimed` outcome entitles the caller to {@link ParameterDelivery.set}
+   * the key; a `duplicate` means the same parameter already holds it, and a
+   * `collision` means a different parameter does — on the same key, or across
+   * a bare/qualified pair sharing the name (see the class doc).
+   */
+  claim(location, name) {
+    const key = ParameterDelivery.keyFor(location, name);
+    const claimant = this.#claimedBy.get(key);
+    if (claimant !== undefined) {
+      return {
+        key,
+        outcome: claimant === location ? 'duplicate' : 'collision'
+      };
+    }
+    const bare = key === name;
+    if (bare ? this.#qualifiedNames.has(name) : this.#bareNames.has(name)) {
+      return {
+        key,
+        outcome: 'collision'
+      };
+    }
+    (bare ? this.#bareNames : this.#qualifiedNames).add(name);
+    this.#claimedBy.set(key, location);
+    return {
+      key,
+      outcome: 'claimed'
+    };
+  }
+  set(key, value) {
+    // defined rather than assigned: a key like `__proto__` hits the
+    // Object.prototype accessor on bracket assignment, so no own property is
+    // ever created and the parameter is silently lost — and an object value
+    // additionally rewrites the record's prototype
+    Object.defineProperty(this.#values, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+  }
+
+  /**
+   * The accumulated record, in the shape `buildRequest` consumes.
+   */
+  toRecord() {
+    return this.#values;
+  }
+}
+var _default = exports.default = ParameterDelivery;

package/src/client/ParameterDelivery.mjs

@@ -0,0 +1,113 @@
+/**
+ * The outcome of claiming a delivery key: `claimed` for a first claim,
+ * `duplicate` when the same `(name, in)` parameter claims its key again, and
+ * `collision` when a *different* parameter produces an already-claimed key.
+ * @internal
+ */
+
+/**
+ * A parameter claim: the delivery key the `(location, name)` pair encodes to,
+ * and how the claim resolved against the map's earlier entries.
+ * @internal
+ */
+
+/**
+ * The parameters map an OpenAPI operation is executed with — the single owner
+ * of the vendored swagger-client's parameter-addressing scheme.
+ *
+ * The client accepts two key shapes in its `parameters` map and, for each
+ * parameter the operation declares, consults the bare `name` *before* the
+ * qualified `'{in}.{name}'` key (deminified from the vendored bundle:
+ * `r = m[e.name]; if (r === undefined) r = m[`${e.in}.${e.name}`]`). Two
+ * consequences shape everything that feeds the map:
+ *
+ * - qualified keys are what let parameters differing only in their location
+ *   coexist — the client builds the same key from the declared parameter and
+ *   matches it verbatim, never splitting it, so dots in a name are safe;
+ * - a bare key silently outranks the qualified keys of every declared
+ *   parameter bearing that name, so nothing may emit one for a location the
+ *   client can address.
+ *
+ * Arazzo's `querystring` is the one location the client cannot address — it
+ * names no OpenAPI location — so it keeps the bare name, which can still
+ * reach a same-named declared parameter. Every other location is qualified,
+ * including an unrecognized one: an unmatched qualified key is inert, where a
+ * bare one would capture.
+ *
+ * Keys are claimed first-wins. The scheme is not injective, so the map also
+ * discriminates a genuine duplicate from a collision of two different
+ * parameters on one key: given a key, the claimant's name is determined by
+ * its location (the key embeds the name, or is the name), so the location
+ * alone identifies the claimant. A bare key and a qualified key sharing one
+ * name are a collision too, even though the keys differ — the client consults
+ * the bare name first for every declared parameter bearing it, so the bare
+ * entry would silently capture the qualified one. What to do about a
+ * collision is the caller's policy — the map only reports it.
+ *
+ * Diff this against the vendored bundle's lookup when bumping swagger-client.
+ * @internal
+ */
+class ParameterDelivery {
+  /**
+   * The key a `(location, name)` pair is delivered under — `'{in}.{name}'`,
+   * or the bare name for `querystring`. See the class doc for why.
+   */
+  static keyFor(location, name) {
+    return location === 'querystring' ? name : `${location}.${name}`;
+  }
+  #values = {};
+  #claimedBy = new Map();
+  #bareNames = new Set();
+  #qualifiedNames = new Set();
+
+  /**
+   * Claims the delivery key for a `(location, name)` pair, first-wins.
+   * Only a `claimed` outcome entitles the caller to {@link ParameterDelivery.set}
+   * the key; a `duplicate` means the same parameter already holds it, and a
+   * `collision` means a different parameter does — on the same key, or across
+   * a bare/qualified pair sharing the name (see the class doc).
+   */
+  claim(location, name) {
+    const key = ParameterDelivery.keyFor(location, name);
+    const claimant = this.#claimedBy.get(key);
+    if (claimant !== undefined) {
+      return {
+        key,
+        outcome: claimant === location ? 'duplicate' : 'collision'
+      };
+    }
+    const bare = key === name;
+    if (bare ? this.#qualifiedNames.has(name) : this.#bareNames.has(name)) {
+      return {
+        key,
+        outcome: 'collision'
+      };
+    }
+    (bare ? this.#bareNames : this.#qualifiedNames).add(name);
+    this.#claimedBy.set(key, location);
+    return {
+      key,
+      outcome: 'claimed'
+    };
+  }
+  set(key, value) {
+    // defined rather than assigned: a key like `__proto__` hits the
+    // Object.prototype accessor on bracket assignment, so no own property is
+    // ever created and the parameter is silently lost — and an object value
+    // additionally rewrites the record's prototype
+    Object.defineProperty(this.#values, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true
+    });
+  }
+
+  /**
+   * The accumulated record, in the shape `buildRequest` consumes.
+   */
+  toRecord() {
+    return this.#values;
+  }
+}
+export default ParameterDelivery;

package/src/constants.cjs

@@ -0,0 +1,9 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MAX_HTTP_CACHE_STALE_AGE = exports.MAX_HTTP_CACHE_ENTRIES = exports.MAX_DOCUMENT_REGISTRY_SIZE = void 0;
+const MAX_HTTP_CACHE_ENTRIES = exports.MAX_HTTP_CACHE_ENTRIES = 6;
+const MAX_HTTP_CACHE_STALE_AGE = exports.MAX_HTTP_CACHE_STALE_AGE = 120_000; // 2 minutes in milliseconds
+const MAX_DOCUMENT_REGISTRY_SIZE = exports.MAX_DOCUMENT_REGISTRY_SIZE = 4;

package/src/constants.mjs

@@ -0,0 +1,3 @@
+export const MAX_HTTP_CACHE_ENTRIES = 6;
+export const MAX_HTTP_CACHE_STALE_AGE = 120_000; // 2 minutes in milliseconds
+export const MAX_DOCUMENT_REGISTRY_SIZE = 4;