@jentic/arazzo-resolver 1.0.0-alpha.32 → 1.0.0-alpha.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jentic/arazzo-resolver",
-  "version": "1.0.0-alpha.32",
+  "version": "1.0.0-alpha.33",
   "description": "Resolver for Arazzo Documents.",
   "keywords": [
     "arazzo",
@@ -49,7 +49,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^8.0.0",
-    "@jentic/arazzo-parser": "1.0.0-alpha.32",
+    "@jentic/arazzo-parser": "1.0.0-alpha.33",
     "@speclynx/apidom-datamodel": "^5.0.1",
     "@speclynx/apidom-error": "^5.0.1",
     "@speclynx/apidom-ns-arazzo-1": "^5.0.1",
@@ -72,5 +72,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "a5ea37ac6a1bd3b56df95cdb308a9b62a4cc375b"
+  "gitHead": "a17270442ac27615af0348fad9c71817d818151f"
 }

package/src/dereference/path-items.cjs

@@ -0,0 +1,117 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.dereferenceSourceDescriptionPathItems = dereferenceSourceDescriptionPathItems;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+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 _openapi = require("./openapi.cjs");
+const isPathItem = element => (0, _apidomNsOpenapi.isPathItemElement)(element) || (0, _apidomNsOpenapi2.isPathItemElement)(element);
+const MAX_REF_CHAIN = 20;
+
+// evaluates the JSON Pointer of a URI fragment against an element tree
+const evaluateFragment = (root, fragment) => {
+  const tokens = decodeURIComponent(fragment.replace(/^#/, '')).split('/').slice(1).map(token => token.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let current = root;
+  for (const token of tokens) {
+    if ((0, _apidomDatamodel.isObjectElement)(current)) current = current.get(token);else if ((0, _apidomDatamodel.isArrayElement)(current)) current = current.get(Number(token));else return undefined;
+  }
+  return current;
+};
+const refractorFor = api => {
+  if ((0, _apidomNsOpenapi.isSwaggerElement)(api)) return _apidomNsOpenapi.refractPathItem;
+  if ((0, _apidomNsOpenapi2.isOpenApi3_0Element)(api)) return _apidomNsOpenapi2.refractPathItem;
+  if ((0, _apidomNsOpenapi3.isOpenApi3_1Element)(api)) return _apidomNsOpenapi3.refractPathItem;
+  return undefined;
+};
+
+/**
+ * Replaces the Path Items that consist of a `$ref` in the `openapi` source descriptions parsed
+ * along with an Arazzo Document (see the `sourceDescriptions` parser option) with the Path Items
+ * they point to, whether local (`#/components/pathItems/...`) or external.
+ *
+ * Only the chain of Path Item `$ref`s is followed. Nothing inside the referenced Path Items
+ * (responses, schemas, ...) is dereferenced, so an unrelated nested reference that can't be
+ * resolved never hides the operations. The source descriptions are modified in place, which makes
+ * the operations behind such Path Items discoverable, e.g. by `findStepOperation` of
+ * \@jentic/arazzo-parser.
+ *
+ * This is best effort and never rejects: a Path Item that can't be resolved is left as is.
+ *
+ * @param parseResult - The result of parsing an Arazzo Document with source descriptions
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves once all resolvable Path Items have been replaced
+ * @public
+ */
+async function dereferenceSourceDescriptionPathItems(parseResult, options = {}) {
+  if (!(0, _apidomNsArazzo.isArazzoSpecification1Element)(parseResult.api)) return;
+  const mergedOptions = (0, _empty.mergeOptions)(_openapi.defaultOptions, options);
+  // external documents are fetched once, however many Path Items point into them
+  const documents = new Map();
+  const fetchDocument = uri => {
+    if (!documents.has(uri)) documents.set(uri, (0, _empty.parse)(uri, mergedOptions));
+    return documents.get(uri);
+  };
+  const pending = [];
+  parseResult.api.sourceDescriptions?.forEach(sourceDescription => {
+    if (!(0, _apidomNsArazzo.isSourceDescriptionElement)(sourceDescription)) return;
+    const sourceParseResult = sourceDescription.meta.get('parseResult');
+    const api = sourceParseResult?.api;
+    const sourceURI = sourceParseResult?.meta.get('retrievalURI');
+    if (!(0, _apidomNsOpenapi.isSwaggerElement)(api) && !(0, _apidomNsOpenapi2.isOpenApi3_0Element)(api) && !(0, _apidomNsOpenapi3.isOpenApi3_1Element)(api)) return;
+    const refract = refractorFor(api);
+    if (!refract || !sourceURI) return;
+
+    // follows the `$ref` of a Path Item to the Path Item it points to
+    const follow = async (pathItem, baseURI, root, visited) => {
+      if (!(0, _apidomDatamodel.isStringElement)(pathItem.$ref)) return pathItem;
+      const ref = pathItem.$ref.toValue();
+      const documentURI = _empty.url.resolve(baseURI, _empty.url.stripHash(ref));
+      const fragment = _empty.url.getHash(ref);
+      const key = `${documentURI}${fragment}`;
+      if (visited.has(key) || visited.size >= MAX_REF_CHAIN) return undefined;
+      visited.add(key);
+      let targetRoot = root;
+      if (documentURI !== _empty.url.stripHash(baseURI)) {
+        const document = await fetchDocument(documentURI);
+        targetRoot = (0, _apidomDatamodel.isObjectElement)(document.api) ? document.api : document.result;
+      }
+      const evaluated = evaluateFragment(targetRoot, fragment);
+      const target = isPathItem(evaluated) ? evaluated : refract(evaluated);
+      if (!isPathItem(target)) return undefined;
+
+      // fields next to the `$ref` override the ones of the referenced Path Item
+      const merged = (0, _apidomDatamodel.cloneShallow)(target);
+      if ((0, _apidomDatamodel.isObjectElement)(pathItem)) {
+        pathItem.forEach((value, member) => {
+          const name = String(member.toValue());
+          if (name !== '$ref') merged.set(name, value);
+        });
+      }
+      return follow(merged, documentURI, targetRoot, visited);
+    };
+
+    // Path Items in `paths` and in the reusable `components.pathItems` are both resolved, since
+    // steps can target either
+    const collections = [api.paths, api.components?.pathItems];
+    collections.forEach(collection => {
+      if (!(0, _apidomDatamodel.isObjectElement)(collection)) return;
+      collection.forEach((pathItem, member) => {
+        // in `components.pathItems` a `$ref`-only entry is refracted to a Reference, not a Path Item
+        const candidate = pathItem;
+        if (!(0, _apidomDatamodel.isObjectElement)(pathItem) || !(0, _apidomDatamodel.isStringElement)(candidate.$ref)) return;
+        pending.push(follow(candidate, sourceURI, api, new Set()).then(resolved => {
+          if (resolved) collection.set(String(member.toValue()), resolved);
+        }, () => {
+          // keep the unresolved Path Item
+        }));
+      });
+    });
+  });
+  await Promise.all(pending);
+}

package/src/dereference/path-items.mjs

@@ -0,0 +1,111 @@
+import { cloneShallow, isArrayElement, isObjectElement, isStringElement } from '@speclynx/apidom-datamodel';
+import { mergeOptions, parse, url } from '@speclynx/apidom-reference/configuration/empty';
+import { isArazzoSpecification1Element, isSourceDescriptionElement } from '@speclynx/apidom-ns-arazzo-1';
+import { isSwaggerElement, isPathItemElement as isPathItem2Element, refractPathItem as refractPathItem2 } from '@speclynx/apidom-ns-openapi-2';
+import { isOpenApi3_0Element, isPathItemElement as isPathItem3Element, refractPathItem as refractPathItem3_0 } from '@speclynx/apidom-ns-openapi-3-0';
+import { isOpenApi3_1Element, refractPathItem as refractPathItem3_1 } from '@speclynx/apidom-ns-openapi-3-1';
+import { defaultOptions as defaultOpenAPIOptions } from "./openapi.mjs";
+const isPathItem = element => isPathItem2Element(element) || isPathItem3Element(element);
+const MAX_REF_CHAIN = 20;
+
+// evaluates the JSON Pointer of a URI fragment against an element tree
+const evaluateFragment = (root, fragment) => {
+  const tokens = decodeURIComponent(fragment.replace(/^#/, '')).split('/').slice(1).map(token => token.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let current = root;
+  for (const token of tokens) {
+    if (isObjectElement(current)) current = current.get(token);else if (isArrayElement(current)) current = current.get(Number(token));else return undefined;
+  }
+  return current;
+};
+const refractorFor = api => {
+  if (isSwaggerElement(api)) return refractPathItem2;
+  if (isOpenApi3_0Element(api)) return refractPathItem3_0;
+  if (isOpenApi3_1Element(api)) return refractPathItem3_1;
+  return undefined;
+};
+
+/**
+ * Replaces the Path Items that consist of a `$ref` in the `openapi` source descriptions parsed
+ * along with an Arazzo Document (see the `sourceDescriptions` parser option) with the Path Items
+ * they point to, whether local (`#/components/pathItems/...`) or external.
+ *
+ * Only the chain of Path Item `$ref`s is followed. Nothing inside the referenced Path Items
+ * (responses, schemas, ...) is dereferenced, so an unrelated nested reference that can't be
+ * resolved never hides the operations. The source descriptions are modified in place, which makes
+ * the operations behind such Path Items discoverable, e.g. by `findStepOperation` of
+ * \@jentic/arazzo-parser.
+ *
+ * This is best effort and never rejects: a Path Item that can't be resolved is left as is.
+ *
+ * @param parseResult - The result of parsing an Arazzo Document with source descriptions
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves once all resolvable Path Items have been replaced
+ * @public
+ */
+export async function dereferenceSourceDescriptionPathItems(parseResult, options = {}) {
+  if (!isArazzoSpecification1Element(parseResult.api)) return;
+  const mergedOptions = mergeOptions(defaultOpenAPIOptions, options);
+  // external documents are fetched once, however many Path Items point into them
+  const documents = new Map();
+  const fetchDocument = uri => {
+    if (!documents.has(uri)) documents.set(uri, parse(uri, mergedOptions));
+    return documents.get(uri);
+  };
+  const pending = [];
+  parseResult.api.sourceDescriptions?.forEach(sourceDescription => {
+    if (!isSourceDescriptionElement(sourceDescription)) return;
+    const sourceParseResult = sourceDescription.meta.get('parseResult');
+    const api = sourceParseResult?.api;
+    const sourceURI = sourceParseResult?.meta.get('retrievalURI');
+    if (!isSwaggerElement(api) && !isOpenApi3_0Element(api) && !isOpenApi3_1Element(api)) return;
+    const refract = refractorFor(api);
+    if (!refract || !sourceURI) return;
+
+    // follows the `$ref` of a Path Item to the Path Item it points to
+    const follow = async (pathItem, baseURI, root, visited) => {
+      if (!isStringElement(pathItem.$ref)) return pathItem;
+      const ref = pathItem.$ref.toValue();
+      const documentURI = url.resolve(baseURI, url.stripHash(ref));
+      const fragment = url.getHash(ref);
+      const key = `${documentURI}${fragment}`;
+      if (visited.has(key) || visited.size >= MAX_REF_CHAIN) return undefined;
+      visited.add(key);
+      let targetRoot = root;
+      if (documentURI !== url.stripHash(baseURI)) {
+        const document = await fetchDocument(documentURI);
+        targetRoot = isObjectElement(document.api) ? document.api : document.result;
+      }
+      const evaluated = evaluateFragment(targetRoot, fragment);
+      const target = isPathItem(evaluated) ? evaluated : refract(evaluated);
+      if (!isPathItem(target)) return undefined;
+
+      // fields next to the `$ref` override the ones of the referenced Path Item
+      const merged = cloneShallow(target);
+      if (isObjectElement(pathItem)) {
+        pathItem.forEach((value, member) => {
+          const name = String(member.toValue());
+          if (name !== '$ref') merged.set(name, value);
+        });
+      }
+      return follow(merged, documentURI, targetRoot, visited);
+    };
+
+    // Path Items in `paths` and in the reusable `components.pathItems` are both resolved, since
+    // steps can target either
+    const collections = [api.paths, api.components?.pathItems];
+    collections.forEach(collection => {
+      if (!isObjectElement(collection)) return;
+      collection.forEach((pathItem, member) => {
+        // in `components.pathItems` a `$ref`-only entry is refracted to a Reference, not a Path Item
+        const candidate = pathItem;
+        if (!isObjectElement(pathItem) || !isStringElement(candidate.$ref)) return;
+        pending.push(follow(candidate, sourceURI, api, new Set()).then(resolved => {
+          if (resolved) collection.set(String(member.toValue()), resolved);
+        }, () => {
+          // keep the unresolved Path Item
+        }));
+      });
+    });
+  });
+  await Promise.all(pending);
+}

package/src/index.cjs

@@ -46,6 +46,13 @@ Object.defineProperty(exports, "dereferenceOpenAPIElement", {
     return _openapi.dereferenceElement;
   }
 });
+Object.defineProperty(exports, "dereferenceSourceDescriptionPathItems", {
+  enumerable: true,
+  get: function () {
+    return _pathItems.dereferenceSourceDescriptionPathItems;
+  }
+});
 var _arazzo = require("./dereference/arazzo.cjs");
 var _openapi = require("./dereference/openapi.cjs");
+var _pathItems = require("./dereference/path-items.cjs");
 var _DereferenceError = _interopRequireDefault(require("./errors/DereferenceError.cjs"));

package/src/index.mjs

@@ -1,3 +1,4 @@
 export { defaultOptions as defaultDereferenceArazzoOptions, dereference as dereferenceArazzo, dereferenceElement as dereferenceArazzoElement } from "./dereference/arazzo.mjs";
 export { defaultOptions as defaultDereferenceOpenAPIOptions, dereference as dereferenceOpenAPI, dereferenceElement as dereferenceOpenAPIElement } from "./dereference/openapi.mjs";
+export { dereferenceSourceDescriptionPathItems } from "./dereference/path-items.mjs";
 export { default as DereferenceError } from "./errors/DereferenceError.mjs";

package/types/arazzo-resolver.d.ts

@@ -216,4 +216,24 @@ export declare function dereferenceOpenAPIElement<T extends Element_2>(element:
  */
 export declare type DereferenceOpenAPIOptions = PartialDeep<ApiDOMReferenceOptions>;
 
+/**
+ * Replaces the Path Items that consist of a `$ref` in the `openapi` source descriptions parsed
+ * along with an Arazzo Document (see the `sourceDescriptions` parser option) with the Path Items
+ * they point to, whether local (`#/components/pathItems/...`) or external.
+ *
+ * Only the chain of Path Item `$ref`s is followed. Nothing inside the referenced Path Items
+ * (responses, schemas, ...) is dereferenced, so an unrelated nested reference that can't be
+ * resolved never hides the operations. The source descriptions are modified in place, which makes
+ * the operations behind such Path Items discoverable, e.g. by `findStepOperation` of
+ * \@jentic/arazzo-parser.
+ *
+ * This is best effort and never rejects: a Path Item that can't be resolved is left as is.
+ *
+ * @param parseResult - The result of parsing an Arazzo Document with source descriptions
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves once all resolvable Path Items have been replaced
+ * @public
+ */
+export declare function dereferenceSourceDescriptionPathItems(parseResult: ParseResultElement, options?: DereferenceOpenAPIOptions): Promise<void>;
+
 export { }