@speclynx/apidom-core 4.0.2 → 4.0.4

package/src/merge/deepmerge.mjs

@@ -0,0 +1,149 @@
+import { ObjectElement, isObjectElement, isArrayElement, cloneDeep, cloneShallow } from '@speclynx/apidom-datamodel';
+import toValue from "../transformers/serializers/value.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+export const emptyElement = element => {
+  const meta = !element.isMetaEmpty ? element.meta.cloneDeep() : undefined;
+  const attributes = !element.isAttributesEmpty ? cloneDeep(element.attributes) : undefined;
+
+  // @ts-ignore
+  return new element.constructor(undefined, meta, attributes);
+};
+const cloneUnlessOtherwiseSpecified = (element, options) => options.clone && options.isMergeableElement(element) ? deepmerge(emptyElement(element), element, options) : element;
+const getMergeFunction = (keyElement, options) => {
+  if (typeof options.customMerge !== 'function') {
+    return deepmerge;
+  }
+  const customMerge = options.customMerge(keyElement, options);
+  return typeof customMerge === 'function' ? customMerge : deepmerge;
+};
+const getMetaMergeFunction = options => {
+  if (typeof options.customMetaMerge !== 'function') {
+    return targetMeta => targetMeta.cloneDeep();
+  }
+  return options.customMetaMerge;
+};
+const getAttributesMergeFunction = options => {
+  if (typeof options.customAttributesMerge !== 'function') {
+    return targetAttributes => cloneDeep(targetAttributes);
+  }
+  return options.customAttributesMerge;
+};
+const mergeArrayElement = (targetElement, sourceElement, options) => {
+  const Ctor = targetElement.constructor;
+  const merged = targetElement.concat(sourceElement);
+  return new Ctor(merged.map(item => cloneUnlessOtherwiseSpecified(item, options)));
+};
+const mergeObjectElement = (targetElement, sourceElement, options) => {
+  const destination = isObjectElement(targetElement) ? emptyElement(targetElement) : emptyElement(sourceElement);
+  if (isObjectElement(targetElement)) {
+    targetElement.forEach((value, key, member) => {
+      const clonedMember = cloneShallow(member);
+      clonedMember.value = cloneUnlessOtherwiseSpecified(value, options);
+      destination.content.push(clonedMember);
+    });
+  }
+  sourceElement.forEach((value, key, member) => {
+    const keyValue = toValue(key);
+    let clonedMember;
+    if (isObjectElement(targetElement) && targetElement.hasKey(keyValue) && options.isMergeableElement(value)) {
+      const targetValue = targetElement.get(keyValue);
+      clonedMember = cloneShallow(member);
+      clonedMember.value = getMergeFunction(key, options)(targetValue, value, options);
+    } else {
+      clonedMember = cloneShallow(member);
+      clonedMember.value = cloneUnlessOtherwiseSpecified(value, options);
+    }
+    destination.remove(keyValue);
+    destination.content.push(clonedMember);
+  });
+  return destination;
+};
+export const defaultOptions = {
+  clone: true,
+  isMergeableElement: element => isObjectElement(element) || isArrayElement(element),
+  arrayElementMerge: mergeArrayElement,
+  objectElementMerge: mergeObjectElement,
+  customMerge: undefined,
+  customMetaMerge: undefined,
+  customAttributesMerge: undefined
+};
+
+/**
+ * @public
+ */
+const deepmerge = (targetElement, sourceElement, options) => {
+  const mergedOptions = {
+    ...defaultOptions,
+    ...options
+  };
+  mergedOptions.isMergeableElement = mergedOptions.isMergeableElement ?? defaultOptions.isMergeableElement;
+  mergedOptions.arrayElementMerge = mergedOptions.arrayElementMerge ?? defaultOptions.arrayElementMerge;
+  mergedOptions.objectElementMerge = mergedOptions.objectElementMerge ?? defaultOptions.objectElementMerge;
+  const sourceIsArrayElement = isArrayElement(sourceElement);
+  const targetIsArrayElement = isArrayElement(targetElement);
+  const sourceAndTargetTypesMatch = sourceIsArrayElement === targetIsArrayElement;
+  if (!sourceAndTargetTypesMatch) {
+    return cloneUnlessOtherwiseSpecified(sourceElement, mergedOptions);
+  }
+
+  // merging two elements
+  const mergedElement = sourceIsArrayElement && typeof mergedOptions.arrayElementMerge === 'function' ? mergedOptions.arrayElementMerge(targetElement, sourceElement, mergedOptions) : mergedOptions.objectElementMerge(targetElement, sourceElement, mergedOptions);
+
+  // merging meta & attributes
+  if (!targetElement.isMetaEmpty && !sourceElement.isMetaEmpty) {
+    mergedElement.meta = getMetaMergeFunction(mergedOptions)(targetElement.meta, sourceElement.meta);
+  } else if (!targetElement.isMetaEmpty) {
+    mergedElement.meta = targetElement.meta.cloneDeep();
+  } else if (!sourceElement.isMetaEmpty) {
+    mergedElement.meta = sourceElement.meta.cloneDeep();
+  }
+  if (!targetElement.isAttributesEmpty && !sourceElement.isAttributesEmpty) {
+    mergedElement.attributes = getAttributesMergeFunction(mergedOptions)(targetElement.attributes, sourceElement.attributes);
+  } else if (!targetElement.isAttributesEmpty) {
+    mergedElement.attributes = cloneDeep(targetElement.attributes);
+  } else if (!sourceElement.isAttributesEmpty) {
+    mergedElement.attributes = cloneDeep(sourceElement.attributes);
+  }
+  return mergedElement;
+};
+deepmerge.all = (list, options) => {
+  if (!Array.isArray(list)) {
+    throw new TypeError('First argument of deepmerge should be an array.');
+  }
+  if (list.length === 0) {
+    return new ObjectElement();
+  }
+  return list.reduce((target, source) => {
+    return deepmerge(target, source, options);
+  }, emptyElement(list[0]));
+};
+export default deepmerge;

package/src/merge/merge-left.cjs

@@ -0,0 +1,16 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _mergeRight = _interopRequireDefault(require("./merge-right.cjs"));
+/**
+ * @public
+ */
+const mergeLeft = (...[sourceElement, targetElement, options]) => {
+  return (0, _mergeRight.default)(targetElement, sourceElement, options);
+};
+mergeLeft.all = (...[list, options]) => {
+  return _mergeRight.default.all([...list].reverse(), options);
+};
+var _default = exports.default = mergeLeft;

package/src/merge/merge-left.mjs

@@ -0,0 +1,11 @@
+import mergeRight from "./merge-right.mjs";
+/**
+ * @public
+ */
+const mergeLeft = (...[sourceElement, targetElement, options]) => {
+  return mergeRight(targetElement, sourceElement, options);
+};
+mergeLeft.all = (...[list, options]) => {
+  return mergeRight.all([...list].reverse(), options);
+};
+export default mergeLeft;

package/src/merge/merge-right.cjs

@@ -0,0 +1,35 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _deepmerge = _interopRequireWildcard(require("./deepmerge.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+const mergeRight = (targetElement, sourceElement, options) => {
+  const mergedOptions = {
+    ..._deepmerge.defaultOptions,
+    ...options,
+    customMerge: () => (target, source) => source,
+    clone: false
+  };
+  return (0, _deepmerge.default)(targetElement, sourceElement, mergedOptions);
+};
+mergeRight.all = (list, options) => {
+  if (!Array.isArray(list)) {
+    throw new TypeError('First argument of mergeRight should be an array.');
+  }
+  if (list.length === 0) {
+    return new _apidomDatamodel.ObjectElement();
+  }
+  return list.reduce((target, source) => {
+    return mergeRight(target, source, options);
+  }, (0, _deepmerge.emptyElement)(list[0]));
+};
+var _default = exports.default = mergeRight;

package/src/merge/merge-right.mjs

@@ -0,0 +1,29 @@
+import { ObjectElement } from '@speclynx/apidom-datamodel';
+import deepmerge, { defaultOptions as defaultDeepmergeOptions, emptyElement } from "./deepmerge.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+const mergeRight = (targetElement, sourceElement, options) => {
+  const mergedOptions = {
+    ...defaultDeepmergeOptions,
+    ...options,
+    customMerge: () => (target, source) => source,
+    clone: false
+  };
+  return deepmerge(targetElement, sourceElement, mergedOptions);
+};
+mergeRight.all = (list, options) => {
+  if (!Array.isArray(list)) {
+    throw new TypeError('First argument of mergeRight should be an array.');
+  }
+  if (list.length === 0) {
+    return new ObjectElement();
+  }
+  return list.reduce((target, source) => {
+    return mergeRight(target, source, options);
+  }, emptyElement(list[0]));
+};
+export default mergeRight;

package/src/namespace.cjs

@@ -0,0 +1,10 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+/**
+ * Default namespace instance with all base elements registered.
+ */
+const namespace = new _apidomDatamodel.Namespace();
+var _default = exports.default = namespace;

package/src/namespace.mjs

@@ -0,0 +1,7 @@
+import { Namespace } from '@speclynx/apidom-datamodel';
+
+/**
+ * Default namespace instance with all base elements registered.
+ */
+const namespace = new Namespace();
+export default namespace;

package/src/refractor/plugins/dispatcher/index.cjs

@@ -0,0 +1,64 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.dispatchPluginsSync = exports.dispatchPluginsAsync = void 0;
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _ramda = require("ramda");
+var _ramdaAdjunct = require("ramda-adjunct");
+var _toolbox = _interopRequireDefault(require("../../toolbox.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+const defaultDispatchPluginsOptions = {
+  toolboxCreator: _toolbox.default,
+  visitorOptions: {
+    exposeEdits: true
+  }
+};
+
+/**
+ * @public
+ */
+const dispatchPluginsSync = (element, plugins, options = {}) => {
+  if (plugins.length === 0) return element;
+  const mergedOptions = (0, _ramda.mergeDeepRight)(defaultDispatchPluginsOptions, options);
+  const {
+    toolboxCreator,
+    visitorOptions
+  } = mergedOptions;
+  const toolbox = toolboxCreator();
+  const pluginsSpecs = plugins.map(plugin => plugin(toolbox));
+  const mergedPluginsVisitor = (0, _apidomTraverse.mergeVisitors)(pluginsSpecs.map((0, _ramda.propOr)({}, 'visitor')), visitorOptions);
+  pluginsSpecs.forEach((0, _ramdaAdjunct.invokeArgs)(['pre'], []));
+  const newElement = (0, _apidomTraverse.traverse)(element, mergedPluginsVisitor);
+  pluginsSpecs.forEach((0, _ramdaAdjunct.invokeArgs)(['post'], []));
+  return newElement;
+};
+exports.dispatchPluginsSync = dispatchPluginsSync;
+const dispatchPluginsAsync = async (element, plugins, options = {}) => {
+  if (plugins.length === 0) return element;
+  const mergedOptions = (0, _ramda.mergeDeepRight)(defaultDispatchPluginsOptions, options);
+  const {
+    toolboxCreator,
+    visitorOptions
+  } = mergedOptions;
+  const toolbox = toolboxCreator();
+  const pluginsSpecs = plugins.map(plugin => plugin(toolbox));
+  const mergedPluginsVisitor = (0, _apidomTraverse.mergeVisitorsAsync)(pluginsSpecs.map((0, _ramda.propOr)({}, 'visitor')), visitorOptions);
+  await Promise.allSettled(pluginsSpecs.map((0, _ramdaAdjunct.invokeArgs)(['pre'], [])));
+  const newElement = await (0, _apidomTraverse.traverseAsync)(element, mergedPluginsVisitor);
+  await Promise.allSettled(pluginsSpecs.map((0, _ramdaAdjunct.invokeArgs)(['post'], [])));
+  return newElement;
+};
+exports.dispatchPluginsAsync = dispatchPluginsAsync;
+dispatchPluginsSync[Symbol.for('nodejs.util.promisify.custom')] = dispatchPluginsAsync;

package/src/refractor/plugins/dispatcher/index.mjs

@@ -0,0 +1,54 @@
+import { traverse, traverseAsync, mergeVisitors, mergeVisitorsAsync } from '@speclynx/apidom-traverse';
+import { mergeDeepRight, propOr } from 'ramda';
+import { invokeArgs } from 'ramda-adjunct';
+import createToolbox from "../../toolbox.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+const defaultDispatchPluginsOptions = {
+  toolboxCreator: createToolbox,
+  visitorOptions: {
+    exposeEdits: true
+  }
+};
+
+/**
+ * @public
+ */
+export const dispatchPluginsSync = (element, plugins, options = {}) => {
+  if (plugins.length === 0) return element;
+  const mergedOptions = mergeDeepRight(defaultDispatchPluginsOptions, options);
+  const {
+    toolboxCreator,
+    visitorOptions
+  } = mergedOptions;
+  const toolbox = toolboxCreator();
+  const pluginsSpecs = plugins.map(plugin => plugin(toolbox));
+  const mergedPluginsVisitor = mergeVisitors(pluginsSpecs.map(propOr({}, 'visitor')), visitorOptions);
+  pluginsSpecs.forEach(invokeArgs(['pre'], []));
+  const newElement = traverse(element, mergedPluginsVisitor);
+  pluginsSpecs.forEach(invokeArgs(['post'], []));
+  return newElement;
+};
+export const dispatchPluginsAsync = async (element, plugins, options = {}) => {
+  if (plugins.length === 0) return element;
+  const mergedOptions = mergeDeepRight(defaultDispatchPluginsOptions, options);
+  const {
+    toolboxCreator,
+    visitorOptions
+  } = mergedOptions;
+  const toolbox = toolboxCreator();
+  const pluginsSpecs = plugins.map(plugin => plugin(toolbox));
+  const mergedPluginsVisitor = mergeVisitorsAsync(pluginsSpecs.map(propOr({}, 'visitor')), visitorOptions);
+  await Promise.allSettled(pluginsSpecs.map(invokeArgs(['pre'], [])));
+  const newElement = await traverseAsync(element, mergedPluginsVisitor);
+  await Promise.allSettled(pluginsSpecs.map(invokeArgs(['post'], [])));
+  return newElement;
+};
+dispatchPluginsSync[Symbol.for('nodejs.util.promisify.custom')] = dispatchPluginsAsync;

package/src/refractor/plugins/element-identity.cjs

@@ -0,0 +1,31 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _index = require("../../identity/index.cjs");
+/**
+ * Plugin for decorating every element in ApiDOM tree with UUID.
+ * @public
+ */
+
+const plugin = ({
+  length = 6
+} = {}) => () => {
+  let identityManager;
+  return {
+    pre() {
+      identityManager = new _index.IdentityManager({
+        length
+      });
+    },
+    visitor: {
+      enter(path) {
+        path.node.id = identityManager.identify(path.node);
+      }
+    },
+    post() {
+      identityManager = null;
+    }
+  };
+};
+var _default = exports.default = plugin;

package/src/refractor/plugins/element-identity.mjs

@@ -0,0 +1,26 @@
+import { IdentityManager } from "../../identity/index.mjs";
+/**
+ * Plugin for decorating every element in ApiDOM tree with UUID.
+ * @public
+ */
+const plugin = ({
+  length = 6
+} = {}) => () => {
+  let identityManager;
+  return {
+    pre() {
+      identityManager = new IdentityManager({
+        length
+      });
+    },
+    visitor: {
+      enter(path) {
+        path.node.id = identityManager.identify(path.node);
+      }
+    },
+    post() {
+      identityManager = null;
+    }
+  };
+};
+export default plugin;

package/src/refractor/plugins/semantic-element-identity.cjs

@@ -0,0 +1,33 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _index = require("../../identity/index.cjs");
+/**
+ * Plugin for decorating every semantic element in ApiDOM tree with UUID.
+ * @public
+ */
+const plugin = ({
+  length = 6
+} = {}) => () => {
+  let identityManager;
+  return {
+    pre() {
+      identityManager = new _index.IdentityManager({
+        length
+      });
+    },
+    visitor: {
+      enter(path) {
+        if (!(0, _apidomDatamodel.isPrimitiveElement)(path.node)) {
+          path.node.id = identityManager.identify(path.node);
+        }
+      }
+    },
+    post() {
+      identityManager = null;
+    }
+  };
+};
+var _default = exports.default = plugin;

package/src/refractor/plugins/semantic-element-identity.mjs

@@ -0,0 +1,29 @@
+import { isPrimitiveElement } from '@speclynx/apidom-datamodel';
+import { IdentityManager } from "../../identity/index.mjs";
+/**
+ * Plugin for decorating every semantic element in ApiDOM tree with UUID.
+ * @public
+ */
+const plugin = ({
+  length = 6
+} = {}) => () => {
+  let identityManager;
+  return {
+    pre() {
+      identityManager = new IdentityManager({
+        length
+      });
+    },
+    visitor: {
+      enter(path) {
+        if (!isPrimitiveElement(path.node)) {
+          path.node.id = identityManager.identify(path.node);
+        }
+      }
+    },
+    post() {
+      identityManager = null;
+    }
+  };
+};
+export default plugin;

package/src/refractor/toolbox.cjs

@@ -0,0 +1,47 @@
+"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 _namespace = _interopRequireDefault(require("../namespace.cjs"));
+/**
+ * @public
+ */
+
+const predicates = {
+  isElement: _apidomDatamodel.isElement,
+  isStringElement: _apidomDatamodel.isStringElement,
+  isNumberElement: _apidomDatamodel.isNumberElement,
+  isNullElement: _apidomDatamodel.isNullElement,
+  isBooleanElement: _apidomDatamodel.isBooleanElement,
+  isArrayElement: _apidomDatamodel.isArrayElement,
+  isObjectElement: _apidomDatamodel.isObjectElement,
+  isMemberElement: _apidomDatamodel.isMemberElement,
+  isPrimitiveElement: _apidomDatamodel.isPrimitiveElement,
+  isLinkElement: _apidomDatamodel.isLinkElement,
+  isRefElement: _apidomDatamodel.isRefElement,
+  isAnnotationElement: _apidomDatamodel.isAnnotationElement,
+  isCommentElement: _apidomDatamodel.isCommentElement,
+  isParseResultElement: _apidomDatamodel.isParseResultElement,
+  isSourceMapElement: _apidomDatamodel.isSourceMapElement,
+  hasElementStyle: _apidomDatamodel.hasElementStyle,
+  hasElementSourceMap: _apidomDatamodel.hasElementSourceMap,
+  includesSymbols: _apidomDatamodel.includesSymbols,
+  includesClasses: _apidomDatamodel.includesClasses
+};
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+const createToolbox = () => {
+  return {
+    predicates,
+    namespace: _namespace.default
+  };
+};
+var _default = exports.default = createToolbox;

package/src/refractor/toolbox.mjs

@@ -0,0 +1,41 @@
+import { isElement, isStringElement, isNumberElement, isNullElement, isBooleanElement, isArrayElement, isObjectElement, isMemberElement, isPrimitiveElement, isLinkElement, isRefElement, isAnnotationElement, isCommentElement, isParseResultElement, isSourceMapElement, hasElementStyle, hasElementSourceMap, includesSymbols, includesClasses } from '@speclynx/apidom-datamodel';
+import defaultNamespace from "../namespace.mjs";
+/**
+ * @public
+ */
+const predicates = {
+  isElement,
+  isStringElement,
+  isNumberElement,
+  isNullElement,
+  isBooleanElement,
+  isArrayElement,
+  isObjectElement,
+  isMemberElement,
+  isPrimitiveElement,
+  isLinkElement,
+  isRefElement,
+  isAnnotationElement,
+  isCommentElement,
+  isParseResultElement,
+  isSourceMapElement,
+  hasElementStyle,
+  hasElementSourceMap,
+  includesSymbols,
+  includesClasses
+};
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+const createToolbox = () => {
+  return {
+    predicates,
+    namespace: defaultNamespace
+  };
+};
+export default createToolbox;

package/src/specification.cjs

@@ -0,0 +1,63 @@
+"use strict";
+
+exports.__esModule = true;
+exports.resolveSpecification = void 0;
+var _ramda = require("ramda");
+var _ramdaAdjunct = require("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
+ */
+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 (0, _ramda.mapObjIndexed)((val, key) => {
+      const newPath = [...currentPath, key];
+      if ((0, _ramdaAdjunct.isPlainObject)(val) && (0, _ramda.has)('$ref', val) && (0, _ramda.propSatisfies)(_ramdaAdjunct.isString, '$ref', val)) {
+        const $ref = (0, _ramda.path)(['$ref'], val);
+        const pointer = (0, _ramdaAdjunct.trimCharsStart)('#/', $ref);
+        const resolved = (0, _ramda.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 && (0, _ramdaAdjunct.isPlainObject)(resolved)) {
+          return {
+            ...resolved,
+            ...rest
+          };
+        }
+        return resolved;
+      }
+      if ((0, _ramdaAdjunct.isPlainObject)(val)) {
+        return traverse(val, root, newPath);
+      }
+      return val;
+    }, obj);
+  };
+  const resolved = traverse(specification, specification, []);
+  resolved.elementMap = elementMap;
+  specCache.set(specification, resolved);
+  return resolved;
+};
+exports.resolveSpecification = resolveSpecification;