@speclynx/apidom-ns-openapi-3-1 1.12.1

package/src/predicates.mjs

@@ -0,0 +1,357 @@
+import { createPredicate, isBooleanElement, isStringElement, toValue } from '@speclynx/apidom-core';
+import CallbackElement from "./elements/Callback.mjs";
+import ComponentsElement from "./elements/Components.mjs";
+import ContactElement from "./elements/Contact.mjs";
+import ExampleElement from "./elements/Example.mjs";
+import ExternalDocumentationElement from "./elements/ExternalDocumentation.mjs";
+import HeaderElement from "./elements/Header.mjs";
+import InfoElement from "./elements/Info.mjs";
+import JsonSchemaDialectElement from "./elements/JsonSchemaDialect.mjs";
+import LicenseElement from "./elements/License.mjs";
+import LinkElement from "./elements/Link.mjs";
+import OpenapiElement from "./elements/Openapi.mjs";
+import OpenApi3_1Element from "./elements/OpenApi3-1.mjs";
+import OperationElement from "./elements/Operation.mjs";
+import ParameterElement from "./elements/Parameter.mjs";
+import PathItemElement from "./elements/PathItem.mjs";
+import PathsElement from "./elements/Paths.mjs";
+import ReferenceElement from "./elements/Reference.mjs";
+import RequestBodyElement from "./elements/RequestBody.mjs";
+import ResponseElement from "./elements/Response.mjs";
+import ResponsesElement from "./elements/Responses.mjs";
+import SchemaElement from "./elements/Schema.mjs";
+import SecurityRequirementElement from "./elements/SecurityRequirement.mjs";
+import SecuritySchemeElement from "./elements/SecurityScheme.mjs";
+import ServerElement from "./elements/Server.mjs";
+import ServerVariableElement from "./elements/ServerVariable.mjs";
+import MediaTypeElement from "./elements/MediaType.mjs";
+/**
+ * @public
+ */
+export const isCallbackElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof CallbackElement || hasBasicElementProps(element) && isElementType('callback', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isComponentsElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof ComponentsElement || hasBasicElementProps(element) && isElementType('components', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isContactElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof ContactElement || hasBasicElementProps(element) && isElementType('contact', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isExampleElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof ExampleElement || hasBasicElementProps(element) && isElementType('example', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isExternalDocumentationElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof ExternalDocumentationElement || hasBasicElementProps(element) && isElementType('externalDocumentation', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isHeaderElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof HeaderElement || hasBasicElementProps(element) && isElementType('header', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isInfoElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof InfoElement || hasBasicElementProps(element) && isElementType('info', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isJsonSchemaDialectElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof JsonSchemaDialectElement || hasBasicElementProps(element) && isElementType('jsonSchemaDialect', element) && primitiveEq('string', element);
+});
+
+/**
+ * @public
+ */
+export const isLicenseElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof LicenseElement || hasBasicElementProps(element) && isElementType('license', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isLinkElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof LinkElement || hasBasicElementProps(element) && isElementType('link', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isOpenapiElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof OpenapiElement || hasBasicElementProps(element) && isElementType('openapi', element) && primitiveEq('string', element);
+});
+
+/**
+ * @public
+ */
+
+export const isOpenApi3_1Element = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq,
+  hasClass
+}) => {
+  return element => element instanceof OpenApi3_1Element || hasBasicElementProps(element) && isElementType('openApi3_1', element) && primitiveEq('object', element) && hasClass('api', element);
+});
+
+/**
+ * @public
+ */
+export const isOperationElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof OperationElement || hasBasicElementProps(element) && isElementType('operation', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isParameterElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof ParameterElement || hasBasicElementProps(element) && isElementType('parameter', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isPathItemElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof PathItemElement || hasBasicElementProps(element) && isElementType('pathItem', element) && primitiveEq('object', element);
+});
+
+/**
+ * @deprecated
+ * Determining whether a PathItemElement is external or internal is not possible by just looking
+ * at value of the $ref fixed field. The value of the $ref field needs to be resolved in runtime
+ * using the referring document as the Base URI.
+ * @public
+ */
+export const isPathItemElementExternal = element => {
+  if (!isPathItemElement(element)) {
+    return false;
+  }
+  if (!isStringElement(element.$ref)) {
+    return false;
+  }
+  const value = toValue(element.$ref);
+  return typeof value === 'string' && value.length > 0 && !value.startsWith('#');
+};
+
+/**
+ * @public
+ */
+export const isPathsElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof PathsElement || hasBasicElementProps(element) && isElementType('paths', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isReferenceElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof ReferenceElement || hasBasicElementProps(element) && isElementType('reference', element) && primitiveEq('object', element);
+});
+
+/**
+ * @deprecated
+ * Determining whether a ReferenceElement is external or internal is not possible by just looking
+ * at value of the $ref fixed field. The value of the $ref field needs to be resolved in runtime
+ * using the referring document as the Base URI.
+ * @public
+ */
+export const isReferenceElementExternal = element => {
+  if (!isReferenceElement(element)) {
+    return false;
+  }
+  if (!isStringElement(element.$ref)) {
+    return false;
+  }
+  const value = toValue(element.$ref);
+  return typeof value === 'string' && value.length > 0 && !value.startsWith('#');
+};
+
+/**
+ * @public
+ */
+export const isRequestBodyElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof RequestBodyElement || hasBasicElementProps(element) && isElementType('requestBody', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isResponseElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof ResponseElement || hasBasicElementProps(element) && isElementType('response', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isResponsesElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof ResponsesElement || hasBasicElementProps(element) && isElementType('responses', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isSchemaElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof SchemaElement || hasBasicElementProps(element) && isElementType('schema', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isBooleanJsonSchemaElement = element => {
+  return isBooleanElement(element) && element.classes.includes('boolean-json-schema');
+};
+
+/**
+ * @public
+ */
+export const isSecurityRequirementElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof SecurityRequirementElement || hasBasicElementProps(element) && isElementType('securityRequirement', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isSecuritySchemeElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof SecuritySchemeElement || hasBasicElementProps(element) && isElementType('securityScheme', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isServerElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof ServerElement || hasBasicElementProps(element) && isElementType('server', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isServerVariableElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof ServerVariableElement || hasBasicElementProps(element) && isElementType('serverVariable', element) && primitiveEq('object', element);
+});
+
+/**
+ * @public
+ */
+export const isMediaTypeElement = createPredicate(({
+  hasBasicElementProps,
+  isElementType,
+  primitiveEq
+}) => {
+  return element => element instanceof MediaTypeElement || hasBasicElementProps(element) && isElementType('mediaType', element) && primitiveEq('object', element);
+});

package/src/refractor/index.cjs

@@ -0,0 +1,45 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = exports.createRefractor = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+var _ramda = require("ramda");
+var _specification = _interopRequireDefault(require("./specification.cjs"));
+var _visitor = require("../traversal/visitor.cjs");
+var _toolbox = _interopRequireDefault(require("./toolbox.cjs"));
+const refract = (value, {
+  specPath = ['visitors', 'document', 'objects', 'OpenApi', '$visitor'],
+  plugins = []
+} = {}) => {
+  const element = (0, _apidomCore.refract)(value);
+  const resolvedSpec = (0, _apidomCore.dereference)(_specification.default);
+
+  /**
+   * This is where generic ApiDOM becomes semantic (namespace applied).
+   * We don't allow consumers to hook into this translation.
+   * Though we allow consumers to define their onw plugins on already transformed ApiDOM.
+   */
+  const RootVisitorClass = (0, _ramda.path)(specPath, resolvedSpec);
+  const rootVisitor = new RootVisitorClass({
+    specObj: resolvedSpec
+  });
+  (0, _apidomCore.visit)(element, rootVisitor);
+
+  /**
+   * Running plugins visitors means extra single traversal === performance hit.
+   */
+  return (0, _apidomCore.dispatchRefractorPlugins)(rootVisitor.element, plugins, {
+    toolboxCreator: _toolbox.default,
+    visitorOptions: {
+      keyMap: _visitor.keyMap,
+      nodeTypeGetter: _visitor.getNodeType
+    }
+  });
+};
+const createRefractor = specPath => (value, options = {}) => refract(value, {
+  specPath,
+  ...options
+});
+exports.createRefractor = createRefractor;
+var _default = exports.default = refract;

package/src/refractor/index.mjs

@@ -0,0 +1,39 @@
+import { visit, dereference, refract as baseRefract, dispatchRefractorPlugins } from '@speclynx/apidom-core';
+import { path } from 'ramda';
+import specification from "./specification.mjs";
+import { keyMap, getNodeType } from "../traversal/visitor.mjs";
+import createToolbox from "./toolbox.mjs";
+const refract = (value, {
+  specPath = ['visitors', 'document', 'objects', 'OpenApi', '$visitor'],
+  plugins = []
+} = {}) => {
+  const element = baseRefract(value);
+  const resolvedSpec = dereference(specification);
+
+  /**
+   * This is where generic ApiDOM becomes semantic (namespace applied).
+   * We don't allow consumers to hook into this translation.
+   * Though we allow consumers to define their onw plugins on already transformed ApiDOM.
+   */
+  const RootVisitorClass = path(specPath, resolvedSpec);
+  const rootVisitor = new RootVisitorClass({
+    specObj: resolvedSpec
+  });
+  visit(element, rootVisitor);
+
+  /**
+   * Running plugins visitors means extra single traversal === performance hit.
+   */
+  return dispatchRefractorPlugins(rootVisitor.element, plugins, {
+    toolboxCreator: createToolbox,
+    visitorOptions: {
+      keyMap,
+      nodeTypeGetter: getNodeType
+    }
+  });
+};
+export const createRefractor = specPath => (value, options = {}) => refract(value, {
+  specPath,
+  ...options
+});
+export default refract;

package/src/refractor/plugins/normalize-header-examples/NormalizeStorage.cjs

@@ -0,0 +1,38 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+class NormalizeStorage {
+  internalStore;
+  constructor(storageElement, storageField, storageSubField) {
+    this.storageElement = storageElement;
+    this.storageField = storageField;
+    this.storageSubField = storageSubField;
+  }
+  get store() {
+    if (!this.internalStore) {
+      let rootStore = this.storageElement.get(this.storageField);
+      if (!(0, _apidomCore.isObjectElement)(rootStore)) {
+        rootStore = new _apidomCore.ObjectElement();
+        this.storageElement.set(this.storageField, rootStore);
+      }
+      let store = rootStore.get(this.storageSubField);
+      if (!(0, _apidomCore.isArrayElement)(store)) {
+        store = new _apidomCore.ArrayElement();
+        rootStore.set(this.storageSubField, store);
+      }
+      this.internalStore = store;
+    }
+    return this.internalStore;
+  }
+  append(pointer) {
+    if (!this.includes(pointer)) {
+      this.store.push(pointer);
+    }
+  }
+  includes(pointer) {
+    return this.store.includes(pointer);
+  }
+}
+var _default = exports.default = NormalizeStorage;

package/src/refractor/plugins/normalize-header-examples/NormalizeStorage.mjs

@@ -0,0 +1,34 @@
+import { ArrayElement, ObjectElement, isObjectElement, isArrayElement } from '@speclynx/apidom-core';
+class NormalizeStorage {
+  internalStore;
+  constructor(storageElement, storageField, storageSubField) {
+    this.storageElement = storageElement;
+    this.storageField = storageField;
+    this.storageSubField = storageSubField;
+  }
+  get store() {
+    if (!this.internalStore) {
+      let rootStore = this.storageElement.get(this.storageField);
+      if (!isObjectElement(rootStore)) {
+        rootStore = new ObjectElement();
+        this.storageElement.set(this.storageField, rootStore);
+      }
+      let store = rootStore.get(this.storageSubField);
+      if (!isArrayElement(store)) {
+        store = new ArrayElement();
+        rootStore.set(this.storageSubField, store);
+      }
+      this.internalStore = store;
+    }
+    return this.internalStore;
+  }
+  append(pointer) {
+    if (!this.includes(pointer)) {
+      this.store.push(pointer);
+    }
+  }
+  includes(pointer) {
+    return this.store.includes(pointer);
+  }
+}
+export default NormalizeStorage;

package/src/refractor/plugins/normalize-header-examples/index.cjs

@@ -0,0 +1,105 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+var _NormalizeStorage = _interopRequireDefault(require("./NormalizeStorage.cjs"));
+/**
+ * Override of Schema.example and Schema.examples field inside the Header Objects.
+ *
+ * Header Object has two fixed fields:
+ *  - `example` of type `Any`
+ *  - `examples` of type `Map[string, Example Object | Reference Object]`
+ *
+ * OpenAPI 3.1 specification excerpt that defines the override behavior:
+ *
+ * The example value SHALL override the example provided by the schema.
+ * Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(element) {
+          storage = new _NormalizeStorage.default(element, storageField, 'header-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      HeaderElement: {
+        leave(headerElement, key, parent, path, ancestors) {
+          // skip visiting this Header Object
+          if (ancestors.some(predicates.isComponentsElement)) {
+            return;
+          }
+
+          // no Header.schema field present
+          if (typeof headerElement.schema === 'undefined' || !predicates.isSchemaElement(headerElement.schema)) {
+            return;
+          }
+          // Schema contains no example
+          if (typeof headerElement.schema?.example === 'undefined' && typeof headerElement.schema?.examples === 'undefined') {
+            return;
+          }
+          const headerJSONPointer = ancestorLineageToJSONPointer([...ancestors, parent, headerElement]);
+
+          // skip visiting this Header Object if it's already normalized
+          if (storage.includes(headerJSONPointer)) {
+            return;
+          }
+
+          /**
+           * Header.examples and Schema.examples have preferences over the older
+           * and deprected `example` field.
+           */
+          if (typeof headerElement.examples !== 'undefined' && predicates.isObjectElement(headerElement.examples)) {
+            // @ts-ignore
+            const examples = headerElement.examples.map(example => {
+              return _apidomCore.cloneDeep.safe(example.value);
+            });
+            if (typeof headerElement.schema.examples !== 'undefined') {
+              headerElement.schema.set('examples', examples);
+              storage.append(headerJSONPointer);
+            }
+            if (typeof headerElement.schema.example !== 'undefined') {
+              headerElement.schema.set('example', examples[0]);
+              storage.append(headerJSONPointer);
+            }
+            return;
+          }
+
+          /**
+           * Handle deprecated `example` field.
+           */
+          if (typeof headerElement.example !== 'undefined') {
+            if (typeof headerElement.schema.examples !== 'undefined') {
+              headerElement.schema.set('examples', [(0, _apidomCore.cloneDeep)(headerElement.example)]);
+              storage.append(headerJSONPointer);
+            }
+            if (typeof headerElement.schema.example !== 'undefined') {
+              headerElement.schema.set('example', (0, _apidomCore.cloneDeep)(headerElement.example));
+              storage.append(headerJSONPointer);
+            }
+          }
+        }
+      }
+    }
+  };
+};
+var _default = exports.default = plugin;