@swagger-api/apidom-core 0.95.0 → 0.97.0

package/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.97.0](https://github.com/swagger-api/apidom/compare/v0.96.0...v0.97.0) (2024-03-07)
+
+### Features
+
+- **core:** add support for RefElement and LinkElement ([#3884](https://github.com/swagger-api/apidom/issues/3884)) ([342ee3f](https://github.com/swagger-api/apidom/commit/342ee3f653f492d3b07ac9b467eba55f0d02b3f9)), closes [#3882](https://github.com/swagger-api/apidom/issues/3882)
+- **core:** handle RefElement serialization in toValue serializer ([#3901](https://github.com/swagger-api/apidom/issues/3901)) ([f205211](https://github.com/swagger-api/apidom/commit/f205211722481004b9c81d6dbe8477adbdbbca2d)), closes [#3894](https://github.com/swagger-api/apidom/issues/3894)
+
+# [0.96.0](https://github.com/swagger-api/apidom/compare/v0.95.0...v0.96.0) (2024-02-28)
+
+### Bug Fixes
+
+- **core:** assign unique ID to elements only when missing ([#3841](https://github.com/swagger-api/apidom/issues/3841)) ([89af0a9](https://github.com/swagger-api/apidom/commit/89af0a95c1675706c1b8aec6f67a656f5d85f96b)), closes [#3840](https://github.com/swagger-api/apidom/issues/3840)
+- **core:** retain meta & attributes during refracting ([#3843](https://github.com/swagger-api/apidom/issues/3843)) ([a7aac32](https://github.com/swagger-api/apidom/commit/a7aac3217730cb058370f906c2d8cc333c8111ee)), closes [#3842](https://github.com/swagger-api/apidom/issues/3842)
+- **playground:** fix bug related to instantiating parser ([#3851](https://github.com/swagger-api/apidom/issues/3851)) ([9b23628](https://github.com/swagger-api/apidom/commit/9b23628d20dda075cb844d5eca0f1d63018de70b))
+
+### Features
+
+- **core:** add mechanism for left shallow merge ([#3849](https://github.com/swagger-api/apidom/issues/3849)) ([3334c6b](https://github.com/swagger-api/apidom/commit/3334c6bd200adedf84c8215bb263ab9009b1d1de)), closes [#3845](https://github.com/swagger-api/apidom/issues/3845)
+- **core:** add mechanism for right shallow merge ([#3846](https://github.com/swagger-api/apidom/issues/3846)) ([2059f28](https://github.com/swagger-api/apidom/commit/2059f28b810c70159d6fa4ddec1115cb38fa330b)), closes [#3845](https://github.com/swagger-api/apidom/issues/3845)
+- **core:** customize meta & attributes merges for deepmerge function ([#3855](https://github.com/swagger-api/apidom/issues/3855)) ([1e94924](https://github.com/swagger-api/apidom/commit/1e94924ab474f4ce4773239f9a9b175d129602f0)), closes [#3853](https://github.com/swagger-api/apidom/issues/3853)
+
 # [0.95.0](https://github.com/swagger-api/apidom/compare/v0.94.0...v0.95.0) (2024-02-09)
 
 **Note:** Version bump only for package @swagger-api/apidom-core

package/README.md

@@ -104,6 +104,105 @@ transcluder.transclude(search, replace); // => ArrayElement<[1, 4, 3]>
 
 ---
 
+## Shallow merging
+
+`mergeRight` and `mergeLeft` functions merge members of two or more ObjectElements shallowly
+and handles shallow merging of ArrayElements as well.
+
+### API
+
+#### mergeRight(target, source, [options])
+
+Merges two ApiDOM elements target and source shallowly, returning a new merged ApiDOM element with the elements
+from both target and source. If an element at the same key is present for both target and source,
+the value from source will appear in the result. Merging creates a new ApiDOM element,
+so that neither target nor source is modified (operation is immutable).
+
+```js
+import { mergeRight, ObjectElement } from '@swagger-api/apidom-core';
+
+const x = new ObjectElement({
+  foo: { bar: 3 },
+});
+
+const y = new ObjectElement({
+  foo: { baz: 4 },
+  quux: 5,
+});
+
+const output = mergeRight(x, y);
+// =>
+// ObjectElement({
+//   foo: ObjectElement({
+//     baz: 4,
+//   }),
+//   quux: 5,
+// })
+```
+
+#### mergeRight.all([element1, element2, ...], [options])
+
+Merges shallowly any number of ApiDOM elements into a single ApiDOM element.
+
+```js
+import { mergeRight, ObjectElement } from '@swagger-api/apidom-core';
+
+const foobar = new ObjectElement({ foo: { bar: 3 } });
+const foobaz = new ObjectElement({ foo: { baz: 4 } });
+const bar = new ObjectElement({ bar: 'yay!' });
+
+const output = mergeRight.all([ foobar, foobaz, bar ]);
+// => ObjectElement({ foo: { baz: 4 }, bar: 'yay!' })
+```
+
+#### mergeLeft(source, target, [options])
+
+Merges two ApiDOM elements source and target shallowly, returning a new merged ApiDOM element with the elements
+from both target and source. If an element at the same key is present for both target and source,
+the value from source will appear in the result. Merging creates a new ApiDOM element,
+so that neither target nor source is modified (operation is immutable).
+
+```js
+import { mergeLeft, ObjectElement } from '@swagger-api/apidom-core';
+
+const x = new ObjectElement({
+  foo: { bar: 3 },
+});
+
+const y = new ObjectElement({
+  foo: { baz: 4 },
+  quux: 5,
+});
+
+const output = mergeLeft(x, y);
+// =>
+// ObjectElement({
+//   foo: ObjectElement({
+//     bar: 3,
+//   }),
+//   quux: 5,
+// })
+```
+
+#### mergeLeft.all([element1, element2, ...], [options])
+
+Merges shallowly any number of ApiDOM elements into a single ApiDOM element.
+
+```js
+import { mergeLeft, ObjectElement } from '@swagger-api/apidom-core';
+
+const foobar = new ObjectElement({ foo: { bar: 3 } });
+const foobaz = new ObjectElement({ foo: { baz: 4 } });
+const bar = new ObjectElement({ bar: 'yay!' });
+
+const output = mergeLeft.all([ foobar, foobaz, bar ]);
+// => ObjectElement({ foo: { baz: 3 }, bar: 'yay!' })
+```
+
+### Shallow merge Options
+
+`mergeRight` and `mergeLeft` take the same options as [deepmerge](#deepmerge-options), except for `customMerge` and `clone`.
+
 ## Deep merging
 
 `deepmerge` functions merged members of two or more ObjectElements deeply
@@ -115,7 +214,7 @@ that works equivalently on ApiDOM structures.
 
 #### deepmerge(target, source, [options])
 
-Merge two ApiDOM elements target and source deeply, returning a new merged ApiDOM element with the elements
+Merges two ApiDOM elements target and source deeply, returning a new merged ApiDOM element with the elements
 from both target and source. If an element at the same key is present for both target and source,
 the value from source will appear in the result. Merging creates a new ApiDOM element,
 so that neither target nor source is modified (operation is immutable).
@@ -173,7 +272,7 @@ const output = deepmerge(x, y);
 
 #### deepmerge.all([element1, element2, ...], [options])
 
-Merges any number of ApiDOM elements into a single ApiDOM element.
+Merges deeply any number of ApiDOM elements into a single ApiDOM element.
 
 ```js
 import { deepmerge, ObjectElement } from '@swagger-api/apidom-core';
@@ -186,7 +285,7 @@ const output = deepmerge.all([ foobar, foobaz, bar ]);
 // => ObjectElement({ foo: { bar: 3, baz: 4 }, bar: 'yay!' })
 ```
 
-### Options
+### Deepmerge Options
 
 #### arrayElementMerge
 
@@ -292,6 +391,42 @@ const output = deepmerge(alex, tony, { customMerge });
 // output.get('pets'); // => ArrayElement(['Cat', 'Parrot', 'Dog'])
 ```
 
+#### customMetaMerge
+
+Specifies a function which can be used to override the default metadata merge behavior.
+The `customMetaMerge` function will be passed target and source metadata. If not specified,
+the default behavior is to deep copy metadata from target to new merged element.
+
+```js
+import { deepmerge, ObjectElement } from '@swagger-api/apidom-core';
+
+const alex = new ObjectElement({ name: { first: 'Alex' } }, { metaKey: true });
+const tony = new ObjectElement({ name: { first: 'Tony' } }, { metaKey: false });
+
+const customMetaMerge = (targetMeta, sourceMeta) => deepmerge(targetMeta, sourceMeta);
+
+const output = deepmerge(alex, tony, { customMetaMerge });
+// output.meta.get('metaKey') // => BooleanElement(false)
+```
+
+#### customAttributesMerge
+
+Specifies a function which can be used to override the default attributes merge behavior.
+The `customAttributesMerge` function will be passed target and source attributes. If not specified,
+the default behavior is to deep copy attributes from target to new merged element.
+
+```js
+import { deepmerge, ObjectElement } from '@swagger-api/apidom-core';
+
+const alex = new ObjectElement({ name: { first: 'Alex' } }, undefined, { attributeKey: true });
+const tony = new ObjectElement({ name: { first: 'Tony' } }, undefined, { attributeKey: false });
+
+const customAttributesMerge = (targetMeta, sourceMeta) => deepmerge(targetMeta, sourceMeta);
+
+const output = deepmerge(alex, tony, { customAttributesMerge });
+// output.attributs.get('attributeKey') // => BooleanElement(false)
+```
+
 #### clone
 
 Defaults to `true`.

package/cjs/identity/index.cjs

@@ -33,7 +33,7 @@ const IdentityManager = exports.IdentityManager = (0, _stampit.default)({
       }
 
       // use already assigned identity
-      if (element.meta.hasKey('id') && (0, _index.isStringElement)(element.meta.id) && !element.meta.id.equals('')) {
+      if (element.meta.hasKey('id') && (0, _index.isStringElement)(element.meta.get('id')) && !element.meta.get('id').equals('')) {
         return element.id;
       }
 

package/cjs/index.cjs

@@ -3,7 +3,7 @@
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 exports.__esModule = true;
-exports.visit = exports.traverse = exports.transclude = exports.toYAML = exports.toValue = exports.toString = exports.toJSON = exports.some = exports.sexprs = exports.reject = exports.refractorPluginSemanticElementIdentity = exports.refractorPluginElementIdentity = exports.refract = exports.parents = exports.namespace = exports.mergeAllVisitors = exports.keyMap = exports.isStringElement = exports.isSourceMapElement = exports.isRefElement = exports.isPrimitiveElement = exports.isParseResultElement = exports.isObjectElement = exports.isNumberElement = exports.isNullElement = exports.isMemberElement = exports.isLinkElement = exports.isElement = exports.isBooleanElement = exports.isArrayElement = exports.isAnnotationElement = exports.includesSymbols = exports.includesClasses = exports.hasElementSourceMap = exports.getNodeType = exports.from = exports.findAtOffset = exports.find = exports.filter = exports.dispatchRefractorPlugins = exports.dereference = exports.dehydrate = exports.defaultIdentityManager = exports.deepmerge = exports.createPredicate = exports.createNamespace = exports.cloneShallow = exports.cloneNode = exports.cloneDeep = exports.Transcluder = exports.StringElement = exports.SourceMapElement = exports.ShallowCloneError = exports.RefElement = exports.ParseResultElement = exports.ObjectSlice = exports.ObjectElement = exports.NumberElement = exports.NullElement = exports.Namespace = exports.MemberElement = exports.MediaTypes = exports.LinkElement = exports.KeyValuePair = exports.IdentityManager = exports.ElementIdentityError = exports.Element = exports.DeepCloneError = exports.CommentElement = exports.CloneError = exports.BooleanElement = exports.BREAK = exports.ArraySlice = exports.ArrayElement = exports.AnnotationElement = void 0;
+exports.visit = exports.traverse = exports.transclude = exports.toYAML = exports.toValue = exports.toString = exports.toJSON = exports.some = exports.sexprs = exports.reject = exports.refractorPluginSemanticElementIdentity = exports.refractorPluginElementIdentity = exports.refract = exports.parents = exports.namespace = exports.mergeRight = exports.mergeLeft = exports.mergeAllVisitors = exports.keyMap = exports.isStringElement = exports.isSourceMapElement = exports.isRefElement = exports.isPrimitiveElement = exports.isParseResultElement = exports.isObjectElement = exports.isNumberElement = exports.isNullElement = exports.isMemberElement = exports.isLinkElement = exports.isElement = exports.isBooleanElement = exports.isArrayElement = exports.isAnnotationElement = exports.includesSymbols = exports.includesClasses = exports.hasElementSourceMap = exports.getNodeType = exports.from = exports.findAtOffset = exports.find = exports.filter = exports.dispatchRefractorPlugins = exports.dereference = exports.dehydrate = exports.defaultIdentityManager = exports.deepmerge = exports.createPredicate = exports.createNamespace = exports.cloneShallow = exports.cloneNode = exports.cloneDeep = exports.Transcluder = exports.StringElement = exports.SourceMapElement = exports.ShallowCloneError = exports.RefElement = exports.ParseResultElement = exports.ObjectSlice = exports.ObjectElement = exports.NumberElement = exports.NullElement = exports.Namespace = exports.MemberElement = exports.MediaTypes = exports.LinkElement = exports.KeyValuePair = exports.IdentityManager = exports.ElementIdentityError = exports.Element = exports.DeepCloneError = exports.CommentElement = exports.CloneError = exports.BooleanElement = exports.BREAK = exports.ArraySlice = exports.ArrayElement = exports.AnnotationElement = void 0;
 var _index = require("./refractor/plugins/utils/index.cjs");
 exports.dispatchRefractorPlugins = _index.dispatchPlugins;
 var _elementIdentity = _interopRequireDefault(require("./refractor/plugins/element-identity.cjs"));
@@ -104,5 +104,9 @@ var _toString = _interopRequireDefault(require("./transformers/to-string.cjs"));
 exports.toString = _toString.default;
 var _sexprs = _interopRequireDefault(require("./transformers/sexprs.cjs"));
 exports.sexprs = _sexprs.default;
-var _deepmerge = _interopRequireDefault(require("./deepmerge.cjs"));
-exports.deepmerge = _deepmerge.default;
+var _deepmerge = _interopRequireDefault(require("./merge/deepmerge.cjs"));
+exports.deepmerge = _deepmerge.default;
+var _mergeRight = _interopRequireDefault(require("./merge/merge-right.cjs"));
+exports.mergeRight = _mergeRight.default;
+var _mergeLeft = _interopRequireDefault(require("./merge/merge-left.cjs"));
+exports.mergeLeft = _mergeLeft.default;

package/cjs/{deepmerge.cjs → merge/deepmerge.cjs}

@@ -3,19 +3,21 @@
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 exports.__esModule = true;
 exports.default = deepmerge;
+exports.emptyElement = exports.defaultOptions = void 0;
 var _minim = require("minim");
-var _index = require("./predicates/index.cjs");
-var _index2 = require("./clone/index.cjs");
-var _index3 = _interopRequireDefault(require("./transformers/serializers/value/index.cjs"));
+var _index = require("../predicates/index.cjs");
+var _index2 = require("../clone/index.cjs");
+var _index3 = _interopRequireDefault(require("../transformers/serializers/value/index.cjs"));
 /* eslint-disable @typescript-eslint/no-use-before-define */
 
 const emptyElement = element => {
-  const meta = (0, _index2.cloneDeep)(element.meta);
-  const attributes = (0, _index2.cloneDeep)(element.attributes);
+  const meta = element.meta.length > 0 ? (0, _index2.cloneDeep)(element.meta) : undefined;
+  const attributes = element.attributes.length > 0 ? (0, _index2.cloneDeep)(element.attributes) : undefined;
 
   // @ts-ignore
   return new element.constructor(undefined, meta, attributes);
 };
+exports.emptyElement = emptyElement;
 const cloneUnlessOtherwiseSpecified = (element, options) => options.clone && options.isMergeableElement(element) ? deepmerge(emptyElement(element), element, options) : element;
 const getMergeFunction = (keyElement, options) => {
   if (typeof options.customMerge !== 'function') {
@@ -24,6 +26,18 @@ const getMergeFunction = (keyElement, options) => {
   const customMerge = options.customMerge(keyElement, options);
   return typeof customMerge === 'function' ? customMerge : deepmerge;
 };
+const getMetaMergeFunction = options => {
+  if (typeof options.customMetaMerge !== 'function') {
+    return targetMeta => (0, _index2.cloneDeep)(targetMeta);
+  }
+  return options.customMetaMerge;
+};
+const getAttributesMergeFunction = options => {
+  if (typeof options.customAttributesMerge !== 'function') {
+    return targetAttributes => (0, _index2.cloneDeep)(targetAttributes);
+  }
+  return options.customAttributesMerge;
+};
 const mergeArrayElement = (targetElement, sourceElement, options) => targetElement.concat(sourceElement)['fantasy-land/map'](item => cloneUnlessOtherwiseSpecified(item, options));
 const mergeObjectElement = (targetElement, sourceElement, options) => {
   const destination = (0, _index.isObjectElement)(targetElement) ? emptyElement(targetElement) : emptyElement(sourceElement);
@@ -50,15 +64,17 @@ const mergeObjectElement = (targetElement, sourceElement, options) => {
   });
   return destination;
 };
+const defaultOptions = exports.defaultOptions = {
+  clone: true,
+  isMergeableElement: element => (0, _index.isObjectElement)(element) || (0, _index.isArrayElement)(element),
+  arrayElementMerge: mergeArrayElement,
+  objectElementMerge: mergeObjectElement,
+  customMerge: undefined,
+  customMetaMerge: undefined,
+  customAttributesMerge: undefined
+};
 function deepmerge(targetElement, sourceElement, options) {
   var _mergedOptions$isMerg, _mergedOptions$arrayE, _mergedOptions$object;
-  const defaultOptions = {
-    clone: true,
-    isMergeableElement: element => (0, _index.isObjectElement)(element) || (0, _index.isArrayElement)(element),
-    arrayElementMerge: mergeArrayElement,
-    objectElementMerge: mergeObjectElement,
-    customMerge: undefined
-  };
   const mergedOptions = {
     ...defaultOptions,
     ...options
@@ -72,10 +88,14 @@ function deepmerge(targetElement, sourceElement, options) {
   if (!sourceAndTargetTypesMatch) {
     return cloneUnlessOtherwiseSpecified(sourceElement, mergedOptions);
   }
-  if (sourceIsArrayElement && typeof mergedOptions.arrayElementMerge === 'function') {
-    return mergedOptions.arrayElementMerge(targetElement, sourceElement, mergedOptions);
-  }
-  return mergedOptions.objectElementMerge(targetElement, 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
+  mergedElement.meta = getMetaMergeFunction(mergedOptions)(targetElement.meta, sourceElement.meta);
+  mergedElement.attributes = getAttributesMergeFunction(mergedOptions)(targetElement.attributes, sourceElement.attributes);
+  return mergedElement;
 }
 deepmerge.all = (list, options) => {
   if (!Array.isArray(list)) {

package/cjs/merge/merge-left.cjs

@@ -0,0 +1,13 @@
+"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"));
+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/cjs/merge/merge-right.cjs

@@ -0,0 +1,28 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _minim = require("minim");
+var _deepmerge = _interopRequireWildcard(require("./deepmerge.cjs"));
+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 _minim.ObjectElement();
+  }
+  return list.reduce((target, source) => {
+    return mergeRight(target, source, options);
+  }, (0, _deepmerge.emptyElement)(list[0]));
+};
+var _default = exports.default = mergeRight;

package/cjs/refractor/index.cjs

@@ -5,6 +5,8 @@ exports.__esModule = true;
 exports.default = exports.createRefractor = void 0;
 var _index = require("./plugins/utils/index.cjs");
 var _visitor = require("../traversal/visitor.cjs");
+var _index2 = require("../clone/index.cjs");
+var _index3 = require("../predicates/index.cjs");
 var _toolbox = _interopRequireDefault(require("./toolbox.cjs"));
 const refract = (value, {
   Type,
@@ -16,6 +18,14 @@ const refract = (value, {
    * Though we allow consumers to define their onw plugins on already transformed ApiDOM.
    */
   const element = new Type(value);
+  if ((0, _index3.isElement)(value)) {
+    if (value.meta.length > 0) {
+      element.meta = (0, _index2.cloneDeep)(value.meta);
+    }
+    if (value.attributes.length > 0) {
+      element.attributes = (0, _index2.cloneDeep)(value.attributes);
+    }
+  }
 
   /**
    * Run plugins only when necessary.

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

@@ -2,7 +2,6 @@
 
 exports.__esModule = true;
 exports.default = void 0;
-var _minim = require("minim");
 var _index = require("../../identity/index.cjs");
 /**
  * Plugin for decorating every element in ApiDOM tree with UUID.
@@ -20,7 +19,7 @@ const plugin = ({
     },
     visitor: {
       enter(element) {
-        element.id = new _minim.StringElement(identityManager.generateId()); // eslint-disable-line no-param-reassign
+        element.id = identityManager.identify(element); // eslint-disable-line no-param-reassign
       }
     },
     post() {

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

@@ -2,7 +2,6 @@
 
 exports.__esModule = true;
 exports.default = void 0;
-var _minim = require("minim");
 var _index = require("../../identity/index.cjs");
 /**
  * Plugin for decorating every semantic element in ApiDOM tree with UUID.
@@ -23,7 +22,7 @@ const plugin = ({
     visitor: {
       enter(element) {
         if (!predicates.isPrimitiveElement(element)) {
-          element.id = new _minim.StringElement(identityManager.generateId()); // eslint-disable-line no-param-reassign
+          element.id = identityManager.identify(element); // eslint-disable-line no-param-reassign
         }
       }
     },

package/cjs/transformers/serializers/value/index.cjs

@@ -58,6 +58,20 @@ class Visitor {
   NullElement() {
     return null;
   }
+  RefElement(element, ...rest) {
+    var _ancestors;
+    const ancestors = rest[3];
+    if (((_ancestors = ancestors[ancestors.length - 1]) == null ? void 0 : _ancestors.type) === 'EphemeralObject') {
+      return Symbol.for('delete-node');
+    }
+    return String(element.toValue());
+  }
+  LinkElement(element) {
+    if ((0, _index.isStringElement)(element.href)) {
+      return element.href.toValue();
+    }
+    return '';
+  }
 }
 const serializer = element => {
   if (!(0, _index.isElement)(element)) return element;