feat(core): add daffMerge (#3441)

libs/core/src/merge/merge.spec.ts

@@ -0,0 +1,52 @@
+import { daffMerge } from './merge';
+import {
+  daffArrayConcatMerger,
+  daffDictAssignMerger,
+} from './mergers/public_api';
+
+describe('@daffodil/core | daffMerge', () => {
+  const a = {
+    ary: [1, 2],
+    obj: {
+      foo: 'bar',
+      bar: 'baz',
+    },
+    fish: 'dumplings',
+  };
+  const b = {
+    ary: [3, 4],
+    obj: {
+      foo: 5,
+    },
+    fish: 'tacos',
+  };
+
+  describe('when there is no defined strategy', () => {
+    it('should merge the dicts with a shallow merge', () => {
+      expect(daffMerge([a, b])).toEqual({
+        ary: [3, 4],
+        obj: {
+          foo: 5,
+        },
+        fish: 'tacos',
+      });
+    });
+  });
+
+  describe('when there is a defined strategy', () => {
+    it('should merge the dicts according to the passed strategy', () => {
+      expect(daffMerge([a, b], {
+        ary: daffArrayConcatMerger,
+        obj: daffDictAssignMerger,
+        fish: (aa, bb) => aa.toUpperCase().concat(bb),
+      })).toEqual({
+        ary: [1, 2, 3, 4],
+        obj: {
+          foo: 5,
+          bar: 'baz',
+        },
+        fish: 'DUMPLINGStacos',
+      });
+    });
+  });
+});

libs/core/src/merge/merge.ts

@@ -0,0 +1,76 @@
+import { DaffMergeStrategy } from './strategy.type';
+
+/**
+ * Merges dictionaries with a specific strategy for handling collisions.
+ * @see {@link DaffMergeStrategy}.
+ *
+ * @example Merging two dictionaries with predefined mergers
+ *
+ * ```ts
+ * const a = {
+ * 	 ary: [1, 2],
+ *   obj: {foo: 5, bar: 10}
+ * }
+ * const a = {
+ * 	 ary: [3, 4],
+ *   obj: {foo: 6},
+ *   fish: 'tacos'
+ * }
+ * const result = daffMerge(
+ *   [a, b],
+ *   {
+ *     ary: daffArrayConcatMerger,
+ *     obj: daffDictAssignMerger
+ *   }
+ * )
+ * ```
+ * the value of result would be:
+ * ```ts
+ * {
+ *   ary: [1, 2, 3, 4],
+ *   obj: {foo: 6, bar: 10},
+ *   fish: 'tacos'
+ * }
+ * ```
+ *
+ * @example Merging two dictionaries with predefined mergers
+ *
+ * ```ts
+ * const a = {
+ * 	 ary: [1, 2],
+ *   obj: {foo: 5, bar: 10}
+ * }
+ * const a = {
+ * 	 ary: [3, 4],
+ *   obj: {foo: 6},
+ *   fish: 'tacos'
+ * }
+ * const result = daffMerge(
+ *   [a, b],
+ *   {
+ *     ary: daffArrayConcatMerger,
+ *     obj: daffDictAssignMerger
+ *   }
+ * )
+ * ```
+ * the value of result would be:
+ * ```ts
+ * {
+ *   ary: [1, 2, 3, 4],
+ *   obj: {foo: 6, bar: 10},
+ *   fish: 'tacos'
+ * }
+ * ```
+ */
+export const daffMerge = <T extends Record<string, unknown> = Record<string, unknown>>(dicts: Array<T>, strategy: DaffMergeStrategy<T> = {}): T =>
+  dicts.reduce((acc, dict) => {
+    for (const k in dict) {
+      if (Object.hasOwn(acc, k) && strategy[k]) {
+        acc[k] = strategy[k](acc[k], dict[k]);
+      } else {
+        acc[k] = dict[k];
+      }
+    }
+
+    return acc;
+  }, <T>{});

libs/core/src/merge/mergers/array-concat.ts

@@ -0,0 +1,3 @@
+export function daffArrayConcatMerger<T extends Array<unknown> = Array<unknown>>(a: T, b: T): T {
+  return <T>a.concat(b);
+}

libs/core/src/merge/mergers/dict-assign.ts

@@ -0,0 +1,3 @@
+export function daffDictAssignMerger<T extends Record<string, unknown> = Record<string, unknown>>(a: T, b: T): T {
+  return Object.assign(a, b);
+}

libs/core/src/merge/mergers/public_api.ts

@@ -0,0 +1,3 @@
+export * from './array-concat';
+export * from './dict-assign';
+export * from './type';

libs/core/src/merge/mergers/type.ts

@@ -0,0 +1,4 @@
+/**
+ * A way to merge two fields into one.
+ */
+export type DaffMerger<T> = (a: T, b: T) => T;

libs/core/src/merge/public_api.ts

@@ -0,0 +1,3 @@
+export * from './mergers/public_api';
+export * from './merge';
+export * from './strategy.type';

libs/core/src/merge/strategy.type.ts

@@ -0,0 +1,9 @@
+import { DaffMerger } from './mergers/public_api';
+
+/**
+ * A strategy for merging objects of the same structure.
+ * Each key can contain a merger function for handling collisions.
+ */
+export type DaffMergeStrategy<T extends Record<string, unknown> = Record<string, unknown>> = {
+  [k in keyof T]?: DaffMerger<T[k]>
+};

libs/core/src/public_api.ts

@@ -16,6 +16,7 @@ export * from './identifiable/public_api';
 export * from './filterable/public_api';
 export * from './filters/public_api';
 export * from './injection-tokens/public_api';
+export * from './merge/public_api';
 
 export { DaffOrderable } from './orderable/orderable';
 export { MaybeAsync } from './async/maybe.type';