@speclynx/apidom-core 4.0.2 → 4.0.4

package/src/specification.mjs

@@ -0,0 +1,59 @@
+import { mapObjIndexed, path, has, propSatisfies } from 'ramda';
+import { isPlainObject, trimCharsStart, isString } from 'ramda-adjunct';
+
+/**
+ * Base type for resolved specification objects.
+ * Extend this in namespace packages to add specific type information.
+ * @public
+ */
+
+const specCache = new WeakMap();
+
+/**
+ * Resolves a specification object by:
+ * 1. Dereferencing all $ref pointers
+ * 2. Building elementMap from objects with `element` property
+ * 3. Caching results for efficiency
+ *
+ * @public
+ */
+export const resolveSpecification = specification => {
+  if (specCache.has(specification)) {
+    return specCache.get(specification);
+  }
+  const elementMap = {};
+  const traverse = (obj, root, currentPath) => {
+    // Collect element mapping
+    if (typeof obj.element === 'string') {
+      elementMap[obj.element] = obj.$visitor ? [...currentPath, '$visitor'] : currentPath;
+    }
+    return mapObjIndexed((val, key) => {
+      const newPath = [...currentPath, key];
+      if (isPlainObject(val) && has('$ref', val) && propSatisfies(isString, '$ref', val)) {
+        const $ref = path(['$ref'], val);
+        const pointer = trimCharsStart('#/', $ref);
+        const resolved = path(pointer.split('/'), root);
+        // merge extra properties (e.g. alias) from the $ref object into the resolved value
+        const {
+          $ref: _,
+          ...rest
+        } = val;
+        if (Object.keys(rest).length > 0 && isPlainObject(resolved)) {
+          return {
+            ...resolved,
+            ...rest
+          };
+        }
+        return resolved;
+      }
+      if (isPlainObject(val)) {
+        return traverse(val, root, newPath);
+      }
+      return val;
+    }, obj);
+  };
+  const resolved = traverse(specification, specification, []);
+  resolved.elementMap = elementMap;
+  specCache.set(specification, resolved);
+  return resolved;
+};

package/src/transcluder/Transcluder.cjs

@@ -0,0 +1,111 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _ramdaAdjunct = require("ramda-adjunct");
+const computeEdges = (element, edges = new WeakMap()) => {
+  if ((0, _apidomDatamodel.isMemberElement)(element)) {
+    // @ts-ignore
+    edges.set(element.key, element);
+    // @ts-ignore
+    computeEdges(element.key, edges);
+    // @ts-ignore
+    edges.set(element.value, element);
+    // @ts-ignore
+    computeEdges(element.value, edges);
+  } else {
+    element.children.forEach(childElement => {
+      edges.set(childElement, element);
+      computeEdges(childElement, edges);
+    });
+  }
+  return edges;
+};
+const transcludeChildOfMemberElement = (search, replace, edges) => {
+  const memberElement = edges.get(search);
+  if (!(0, _apidomDatamodel.isMemberElement)(memberElement)) {
+    return;
+  }
+  if (memberElement.key === search) {
+    memberElement.key = replace;
+    edges.delete(search);
+    edges.set(replace, memberElement);
+  }
+  if (memberElement.value === search) {
+    memberElement.value = replace;
+    edges.delete(search);
+    edges.set(replace, memberElement);
+  }
+};
+const transcludeChildOfObjectElement = (search, replace, edges) => {
+  const objectElement = edges.get(search);
+  if (!(0, _apidomDatamodel.isObjectElement)(objectElement)) {
+    return;
+  }
+  objectElement.content = objectElement.map((value, key, member) => {
+    if (member === search) {
+      edges.delete(search);
+      edges.set(replace, objectElement);
+      return replace;
+    }
+    return member;
+  });
+};
+const transcludeChildOfArrayElement = (search, replace, edges) => {
+  const arrayElement = edges.get(search);
+  if (!(0, _apidomDatamodel.isArrayElement)(arrayElement)) {
+    return;
+  }
+  arrayElement.content = arrayElement.map(element => {
+    if (element === search) {
+      edges.delete(search);
+      edges.set(replace, arrayElement);
+      return replace;
+    }
+    return element;
+  });
+};
+
+/**
+ * This is a mutating stamp. If you don't want your Element to be mutated,
+ * clone in before passing it to initializer of this stamp.
+ * @public
+ */
+
+class Transcluder {
+  element;
+  edges;
+  constructor({
+    element
+  }) {
+    this.element = element;
+  }
+  transclude(search, replace) {
+    // shortcut 1. - replacing entire ApiDOM tree
+    if (search === this.element) return replace;
+    // shortcut 2. - replacing nothing
+    if (search === replace) return this.element;
+    this.edges = this.edges ?? computeEdges(this.element);
+    const parent = this.edges.get(search);
+    if ((0, _ramdaAdjunct.isUndefined)(parent)) {
+      return undefined;
+    }
+
+    /**
+     * This predicate must be first because ObjectElement extends ArrayElement.
+     * isArrayElement returns true for ObjectElements.
+     * (classical problems with polymorphism)
+     */
+    if ((0, _apidomDatamodel.isObjectElement)(parent)) {
+      // @ts-ignore
+      transcludeChildOfObjectElement(search, replace, this.edges);
+    } else if ((0, _apidomDatamodel.isArrayElement)(parent)) {
+      transcludeChildOfArrayElement(search, replace, this.edges);
+    } else if ((0, _apidomDatamodel.isMemberElement)(parent)) {
+      transcludeChildOfMemberElement(search, replace, this.edges);
+    }
+    return this.element;
+  }
+}
+var _default = exports.default = Transcluder;

package/src/transcluder/Transcluder.mjs

@@ -0,0 +1,107 @@
+import { isObjectElement, isArrayElement, isMemberElement } from '@speclynx/apidom-datamodel';
+import { isUndefined } from 'ramda-adjunct';
+const computeEdges = (element, edges = new WeakMap()) => {
+  if (isMemberElement(element)) {
+    // @ts-ignore
+    edges.set(element.key, element);
+    // @ts-ignore
+    computeEdges(element.key, edges);
+    // @ts-ignore
+    edges.set(element.value, element);
+    // @ts-ignore
+    computeEdges(element.value, edges);
+  } else {
+    element.children.forEach(childElement => {
+      edges.set(childElement, element);
+      computeEdges(childElement, edges);
+    });
+  }
+  return edges;
+};
+const transcludeChildOfMemberElement = (search, replace, edges) => {
+  const memberElement = edges.get(search);
+  if (!isMemberElement(memberElement)) {
+    return;
+  }
+  if (memberElement.key === search) {
+    memberElement.key = replace;
+    edges.delete(search);
+    edges.set(replace, memberElement);
+  }
+  if (memberElement.value === search) {
+    memberElement.value = replace;
+    edges.delete(search);
+    edges.set(replace, memberElement);
+  }
+};
+const transcludeChildOfObjectElement = (search, replace, edges) => {
+  const objectElement = edges.get(search);
+  if (!isObjectElement(objectElement)) {
+    return;
+  }
+  objectElement.content = objectElement.map((value, key, member) => {
+    if (member === search) {
+      edges.delete(search);
+      edges.set(replace, objectElement);
+      return replace;
+    }
+    return member;
+  });
+};
+const transcludeChildOfArrayElement = (search, replace, edges) => {
+  const arrayElement = edges.get(search);
+  if (!isArrayElement(arrayElement)) {
+    return;
+  }
+  arrayElement.content = arrayElement.map(element => {
+    if (element === search) {
+      edges.delete(search);
+      edges.set(replace, arrayElement);
+      return replace;
+    }
+    return element;
+  });
+};
+
+/**
+ * This is a mutating stamp. If you don't want your Element to be mutated,
+ * clone in before passing it to initializer of this stamp.
+ * @public
+ */
+
+class Transcluder {
+  element;
+  edges;
+  constructor({
+    element
+  }) {
+    this.element = element;
+  }
+  transclude(search, replace) {
+    // shortcut 1. - replacing entire ApiDOM tree
+    if (search === this.element) return replace;
+    // shortcut 2. - replacing nothing
+    if (search === replace) return this.element;
+    this.edges = this.edges ?? computeEdges(this.element);
+    const parent = this.edges.get(search);
+    if (isUndefined(parent)) {
+      return undefined;
+    }
+
+    /**
+     * This predicate must be first because ObjectElement extends ArrayElement.
+     * isArrayElement returns true for ObjectElements.
+     * (classical problems with polymorphism)
+     */
+    if (isObjectElement(parent)) {
+      // @ts-ignore
+      transcludeChildOfObjectElement(search, replace, this.edges);
+    } else if (isArrayElement(parent)) {
+      transcludeChildOfArrayElement(search, replace, this.edges);
+    } else if (isMemberElement(parent)) {
+      transcludeChildOfMemberElement(search, replace, this.edges);
+    }
+    return this.element;
+  }
+}
+export default Transcluder;

package/src/transcluder/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.transclude = exports.default = void 0;
+var _Transcluder = _interopRequireDefault(require("./Transcluder.cjs"));
+/**
+ * This is a mutating function. If you don't want your Element to be mutated,
+ * clone in before passing it to this function.
+ * @public
+ */
+const transclude = (search, replace, element) => {
+  const transcluder = new _Transcluder.default({
+    element
+  });
+  return transcluder.transclude(search, replace);
+};
+exports.transclude = transclude;
+var _default = exports.default = _Transcluder.default;

package/src/transcluder/index.mjs

@@ -0,0 +1,13 @@
+import Transcluder from "./Transcluder.mjs";
+/**
+ * This is a mutating function. If you don't want your Element to be mutated,
+ * clone in before passing it to this function.
+ * @public
+ */
+export const transclude = (search, replace, element) => {
+  const transcluder = new Transcluder({
+    element
+  });
+  return transcluder.transclude(search, replace);
+};
+export default Transcluder;

package/src/transformers/dehydrate.cjs

@@ -0,0 +1,15 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _namespace = _interopRequireDefault(require("../namespace.cjs"));
+/**
+ * Creates a refract representation of an Element.
+ * https://github.com/refractproject/refract-spec
+ * @public
+ */
+const dehydrate = (element, namespace = _namespace.default) => {
+  return namespace.toRefract(element);
+};
+var _default = exports.default = dehydrate;

package/src/transformers/dehydrate.mjs

@@ -0,0 +1,10 @@
+import defaultNamespaceInstance from "../namespace.mjs";
+/**
+ * Creates a refract representation of an Element.
+ * https://github.com/refractproject/refract-spec
+ * @public
+ */
+const dehydrate = (element, namespace = defaultNamespaceInstance) => {
+  return namespace.toRefract(element);
+};
+export default dehydrate;

package/src/transformers/from.cjs

@@ -0,0 +1,34 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _ramdaAdjunct = require("ramda-adjunct");
+var _namespace = _interopRequireDefault(require("../namespace.cjs"));
+/**
+ * Transforms data to an Element from a particular namespace.
+ *
+ * The name of the function was originally `from`,
+ * but it was renamed to `fromFn` to avoid issues with Parcel.js:
+ *
+ * - https://github.com/parcel-bundler/parcel/issues/9473
+ * - https://github.com/swagger-api/swagger-ui/issues/9466#issuecomment-1881053410
+ * @public
+ */
+const fromFn = (data, namespace = _namespace.default) => {
+  if ((0, _ramdaAdjunct.isString)(data)) {
+    // JSON serialized refract
+    try {
+      return namespace.fromRefract(JSON.parse(data));
+    } catch {
+      // noop
+    }
+  }
+  if ((0, _ramdaAdjunct.isPlainObject)(data) && (0, _ramda.has)('element', data)) {
+    // refract javascript structure
+    return namespace.fromRefract(data);
+  }
+  return namespace.toElement(data);
+};
+var _default = exports.default = fromFn;

package/src/transformers/from.mjs

@@ -0,0 +1,29 @@
+import { has } from 'ramda';
+import { isPlainObject, isString } from 'ramda-adjunct';
+import defaultNamespace from "../namespace.mjs";
+/**
+ * Transforms data to an Element from a particular namespace.
+ *
+ * The name of the function was originally `from`,
+ * but it was renamed to `fromFn` to avoid issues with Parcel.js:
+ *
+ * - https://github.com/parcel-bundler/parcel/issues/9473
+ * - https://github.com/swagger-api/swagger-ui/issues/9466#issuecomment-1881053410
+ * @public
+ */
+const fromFn = (data, namespace = defaultNamespace) => {
+  if (isString(data)) {
+    // JSON serialized refract
+    try {
+      return namespace.fromRefract(JSON.parse(data));
+    } catch {
+      // noop
+    }
+  }
+  if (isPlainObject(data) && has('element', data)) {
+    // refract javascript structure
+    return namespace.fromRefract(data);
+  }
+  return namespace.toElement(data);
+};
+export default fromFn;

package/src/transformers/serializers/json.cjs

@@ -0,0 +1,75 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _value = _interopRequireDefault(require("./value.cjs"));
+const getStyle = element => {
+  return element.style?.json ?? {};
+};
+
+/**
+ * @public
+ */
+
+/**
+ * Builds a POJO from an ApiDOM element tree. Numbers with rawContent
+ * are replaced with sentinel strings; all other values go through toValue().
+ */
+const toPojo = (element, sentinels) => {
+  const visited = new WeakSet();
+  const convert = node => {
+    if (!(0, _apidomDatamodel.isElement)(node)) return node;
+    if (visited.has(node)) return null;
+    visited.add(node);
+    if ((0, _apidomDatamodel.isObjectElement)(node)) {
+      const obj = {};
+      node.forEach((value, key) => {
+        const k = (0, _apidomDatamodel.isElement)(key) ? (0, _value.default)(key) : key;
+        if (typeof k === 'string') obj[k] = convert(value);
+      });
+      return obj;
+    }
+    if ((0, _apidomDatamodel.isArrayElement)(node)) {
+      const arr = [];
+      node.forEach(item => arr.push(convert(item)));
+      return arr;
+    }
+    if ((0, _apidomDatamodel.isRefElement)(node)) return String((0, _value.default)(node));
+    if ((0, _apidomDatamodel.isLinkElement)(node)) return (0, _apidomDatamodel.isStringElement)(node.href) ? (0, _value.default)(node.href) : '';
+
+    // number with rawContent — substitute with sentinel
+    if ((0, _apidomDatamodel.isNumberElement)(node)) {
+      const style = getStyle(node);
+      if (typeof style.rawContent === 'string') {
+        const sentinel = `\0RAW${sentinels.size}\0`;
+        sentinels.set(sentinel, style.rawContent);
+        return sentinel;
+      }
+    }
+    return (0, _value.default)(node);
+  };
+  return convert(element);
+};
+
+/**
+ * @public
+ */
+const serializer = (element, replacer, space, options) => {
+  if (options?.preserveStyle) {
+    const style = getStyle(element);
+    const indent = typeof space === 'number' ? space : typeof style.indent === 'number' ? style.indent : 0;
+    const sentinels = new Map();
+    const pojo = toPojo(element, sentinels);
+    let serialized = JSON.stringify(pojo, null, indent);
+
+    // replace quoted sentinels with raw number representations
+    for (const [sentinel, raw] of sentinels) {
+      serialized = serialized.replace(JSON.stringify(sentinel), raw);
+    }
+    return serialized;
+  }
+  return JSON.stringify((0, _value.default)(element), replacer, space);
+};
+var _default = exports.default = serializer;

package/src/transformers/serializers/json.mjs

@@ -0,0 +1,70 @@
+import { isElement, isObjectElement, isArrayElement, isRefElement, isLinkElement, isStringElement, isNumberElement } from '@speclynx/apidom-datamodel';
+import toValue from "./value.mjs";
+const getStyle = element => {
+  return element.style?.json ?? {};
+};
+
+/**
+ * @public
+ */
+
+/**
+ * Builds a POJO from an ApiDOM element tree. Numbers with rawContent
+ * are replaced with sentinel strings; all other values go through toValue().
+ */
+const toPojo = (element, sentinels) => {
+  const visited = new WeakSet();
+  const convert = node => {
+    if (!isElement(node)) return node;
+    if (visited.has(node)) return null;
+    visited.add(node);
+    if (isObjectElement(node)) {
+      const obj = {};
+      node.forEach((value, key) => {
+        const k = isElement(key) ? toValue(key) : key;
+        if (typeof k === 'string') obj[k] = convert(value);
+      });
+      return obj;
+    }
+    if (isArrayElement(node)) {
+      const arr = [];
+      node.forEach(item => arr.push(convert(item)));
+      return arr;
+    }
+    if (isRefElement(node)) return String(toValue(node));
+    if (isLinkElement(node)) return isStringElement(node.href) ? toValue(node.href) : '';
+
+    // number with rawContent — substitute with sentinel
+    if (isNumberElement(node)) {
+      const style = getStyle(node);
+      if (typeof style.rawContent === 'string') {
+        const sentinel = `\0RAW${sentinels.size}\0`;
+        sentinels.set(sentinel, style.rawContent);
+        return sentinel;
+      }
+    }
+    return toValue(node);
+  };
+  return convert(element);
+};
+
+/**
+ * @public
+ */
+const serializer = (element, replacer, space, options) => {
+  if (options?.preserveStyle) {
+    const style = getStyle(element);
+    const indent = typeof space === 'number' ? space : typeof style.indent === 'number' ? style.indent : 0;
+    const sentinels = new Map();
+    const pojo = toPojo(element, sentinels);
+    let serialized = JSON.stringify(pojo, null, indent);
+
+    // replace quoted sentinels with raw number representations
+    for (const [sentinel, raw] of sentinels) {
+      serialized = serialized.replace(JSON.stringify(sentinel), raw);
+    }
+    return serialized;
+  }
+  return JSON.stringify(toValue(element), replacer, space);
+};
+export default serializer;

package/src/transformers/serializers/value.cjs

@@ -0,0 +1,50 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+/**
+ * Transforms the ApiDOM into JavaScript POJO.
+ * This POJO would be the result of interpreting the ApiDOM
+ * into JavaScript structure.
+ * @public
+ */
+const serializer = element => {
+  if (!(0, _apidomDatamodel.isElement)(element)) return element;
+
+  // Shortcut optimization for primitive element types
+  if ((0, _apidomDatamodel.isStringElement)(element) || (0, _apidomDatamodel.isNumberElement)(element) || (0, _apidomDatamodel.isBooleanElement)(element) || (0, _apidomDatamodel.isNullElement)(element)) {
+    return element.toValue();
+  }
+
+  // WeakMap for cycle handling - stores references to already-visited elements
+  const references = new WeakMap();
+  const serialize = node => {
+    if (!(0, _apidomDatamodel.isElement)(node)) return node;
+    if ((0, _apidomDatamodel.isObjectElement)(node)) {
+      if (references.has(node)) return references.get(node);
+      const obj = {};
+      references.set(node, obj);
+      node.forEach((value, key) => {
+        const k = serialize(key);
+        const v = serialize(value);
+        if (typeof k === 'string') obj[k] = v;
+      });
+      return obj;
+    }
+    if ((0, _apidomDatamodel.isArrayElement)(node)) {
+      if (references.has(node)) return references.get(node);
+      const arr = [];
+      references.set(node, arr);
+      node.forEach(item => arr.push(serialize(item)));
+      return arr;
+    }
+    if ((0, _apidomDatamodel.isRefElement)(node)) return String(node.toValue());
+    if ((0, _apidomDatamodel.isLinkElement)(node)) {
+      return (0, _apidomDatamodel.isStringElement)(node.href) ? node.href.toValue() : '';
+    }
+    return node.toValue();
+  };
+  return serialize(element);
+};
+var _default = exports.default = serializer;

package/src/transformers/serializers/value.mjs

@@ -0,0 +1,47 @@
+import { isElement, isObjectElement, isArrayElement, isRefElement, isLinkElement, isStringElement, isBooleanElement, isNumberElement, isNullElement } from '@speclynx/apidom-datamodel';
+
+/**
+ * Transforms the ApiDOM into JavaScript POJO.
+ * This POJO would be the result of interpreting the ApiDOM
+ * into JavaScript structure.
+ * @public
+ */
+const serializer = element => {
+  if (!isElement(element)) return element;
+
+  // Shortcut optimization for primitive element types
+  if (isStringElement(element) || isNumberElement(element) || isBooleanElement(element) || isNullElement(element)) {
+    return element.toValue();
+  }
+
+  // WeakMap for cycle handling - stores references to already-visited elements
+  const references = new WeakMap();
+  const serialize = node => {
+    if (!isElement(node)) return node;
+    if (isObjectElement(node)) {
+      if (references.has(node)) return references.get(node);
+      const obj = {};
+      references.set(node, obj);
+      node.forEach((value, key) => {
+        const k = serialize(key);
+        const v = serialize(value);
+        if (typeof k === 'string') obj[k] = v;
+      });
+      return obj;
+    }
+    if (isArrayElement(node)) {
+      if (references.has(node)) return references.get(node);
+      const arr = [];
+      references.set(node, arr);
+      node.forEach(item => arr.push(serialize(item)));
+      return arr;
+    }
+    if (isRefElement(node)) return String(node.toValue());
+    if (isLinkElement(node)) {
+      return isStringElement(node.href) ? node.href.toValue() : '';
+    }
+    return node.toValue();
+  };
+  return serialize(element);
+};
+export default serializer;