feat(core): add mechanism for right shallow merge

Refs #3845

packages/apidom-core/README.md

@@ -104,6 +104,58 @@ transcluder.transclude(search, replace); // => ArrayElement<[1, 4, 3]>
 
 ---
 
+## Shallow merging
+
+`mergeRight` functions merged 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!' })
+```
+
+
 ## Deep merging
 
 `deepmerge` functions merged members of two or more ObjectElements deeply
@@ -115,7 +167,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 +225,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';

packages/apidom-core/src/deepmerge.ts

@@ -6,7 +6,7 @@ import toValue from './transformers/serializers/value';
 
 /* eslint-disable @typescript-eslint/no-use-before-define */
 
-type ObjectOrArrayElement = ObjectElement | ArrayElement;
+export type ObjectOrArrayElement = ObjectElement | ArrayElement;
 type AnyElement = ObjectElement | ArrayElement | Element;
 type DeepMerge = (
   targetElement: ObjectOrArrayElement,
@@ -24,7 +24,7 @@ type ObjectElementMerge = (
   source: ObjectElement,
   options: DeepMergeOptions,
 ) => ObjectElement;
-type DeepMergeUserOptions = {
+export type DeepMergeUserOptions = {
   clone?: boolean;
   isMergeableElement?: (element: Element) => boolean;
   arrayElementMerge?: ArrayElementMerge;
@@ -40,7 +40,7 @@ type DeepMergeOptions = DeepMergeUserOptions & {
   customMerge: CustomMerge | undefined;
 };
 
-const emptyElement = (element: ObjectElement | ArrayElement) => {
+export const emptyElement = (element: ObjectElement | ArrayElement) => {
   const meta = cloneDeep(element.meta);
   const attributes = cloneDeep(element.attributes);
 
@@ -113,18 +113,19 @@ const mergeObjectElement: ObjectElementMerge = (targetElement, sourceElement, op
   return destination;
 };
 
+export const defaultOptions: DeepMergeOptions = {
+  clone: true,
+  isMergeableElement: (element) => isObjectElement(element) || isArrayElement(element),
+  arrayElementMerge: mergeArrayElement,
+  objectElementMerge: mergeObjectElement,
+  customMerge: undefined,
+};
+
 export default function deepmerge(
   targetElement: ObjectOrArrayElement,
   sourceElement: ObjectOrArrayElement,
   options?: DeepMergeUserOptions,
 ): AnyElement {
-  const defaultOptions: DeepMergeOptions = {
-    clone: true,
-    isMergeableElement: (element) => isObjectElement(element) || isArrayElement(element),
-    arrayElementMerge: mergeArrayElement,
-    objectElementMerge: mergeObjectElement,
-    customMerge: undefined,
-  };
   const mergedOptions: DeepMergeOptions = { ...defaultOptions, ...options };
   mergedOptions.isMergeableElement =
     mergedOptions.isMergeableElement ?? defaultOptions.isMergeableElement;
@@ -156,7 +157,7 @@ export default function deepmerge(
   );
 }
 
-deepmerge.all = (list: ObjectOrArrayElement[], options?: DeepMergeOptions) => {
+deepmerge.all = (list: ObjectOrArrayElement[], options?: DeepMergeUserOptions) => {
   if (!Array.isArray(list)) {
     throw new TypeError('First argument of deepmerge should be an array.');
   }

packages/apidom-core/src/index.ts

@@ -104,3 +104,7 @@ export { default as toString } from './transformers/to-string';
 export { default as sexprs } from './transformers/sexprs';
 
 export { default as deepmerge } from './deepmerge';
+export type { DeepMergeUserOptions, ObjectOrArrayElement } from './deepmerge';
+
+export { default as mergeRight } from './merge/merge-right';
+export type { MergeRightOptions } from './merge/merge-right';

packages/apidom-core/src/merge/merge-right.ts

@@ -0,0 +1,36 @@
+import { ObjectElement } from 'minim';
+
+import deepmerge, { defaultOptions as defaultDeepmergeOptions, emptyElement } from '../deepmerge';
+import type { ObjectOrArrayElement, DeepMergeUserOptions } from '../deepmerge';
+
+export type MergeRightOptions = Omit<DeepMergeUserOptions, 'customMerge' | 'clone'>;
+
+const mergeRight = (
+  targetElement: ObjectOrArrayElement,
+  sourceElement: ObjectOrArrayElement,
+  options?: MergeRightOptions,
+) => {
+  const mergedOptions = {
+    ...defaultDeepmergeOptions,
+    ...options,
+    customMerge: () => (target: ObjectOrArrayElement, source: ObjectOrArrayElement) => source,
+    clone: false,
+  };
+
+  return deepmerge(targetElement, sourceElement, mergedOptions);
+};
+
+mergeRight.all = (list: ObjectOrArrayElement[], options?: MergeRightOptions) => {
+  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;

packages/apidom-core/test/deepmerge.ts

@@ -349,7 +349,7 @@ describe('deepmerge', function () {
     assert.strictEqual(merged.get(2), source.get(0), 'should not clone');
   });
 
-  context('deepmerge.all', function () {
+  specify('deepmerge.all', function () {
     const source = new ObjectElement({ key1: 'changed', key2: 'value2' });
     const target = new ObjectElement({ key1: 'value1', key3: 'value3' });
     const merged = deepmerge.all([target, source]);