first commit

packages/nodes-base/nodes/Merge/v2/MergeV2.node.ts

@@ -0,0 +1,617 @@
+import merge from 'lodash/merge';
+import {
+	type IExecuteFunctions,
+	type IDataObject,
+	type INodeExecutionData,
+	type INodeType,
+	type INodeTypeBaseDescription,
+	type INodeTypeDescription,
+	type IPairedItemData,
+	NodeConnectionTypes,
+} from 'n8n-workflow';
+
+import { preparePairedItemDataArray } from '@utils/utilities';
+
+import { optionsDescription } from './descriptions';
+import type {
+	ClashResolveOptions,
+	MatchFieldsJoinMode,
+	MatchFieldsOptions,
+	MatchFieldsOutput,
+} from './interfaces';
+import {
+	addSourceField,
+	addSuffixToEntriesKeys,
+	checkInput,
+	checkMatchFieldsInput,
+	findMatches,
+	mergeMatched,
+	selectMergeMethod,
+} from './utils';
+
+export class MergeV2 implements INodeType {
+	description: INodeTypeDescription;
+
+	constructor(baseDescription: INodeTypeBaseDescription) {
+		this.description = {
+			...baseDescription,
+			version: [2, 2.1],
+			defaults: {
+				name: 'Merge',
+			},
+
+			inputs: [NodeConnectionTypes.Main, NodeConnectionTypes.Main],
+			outputs: [NodeConnectionTypes.Main],
+			inputNames: ['Input 1', 'Input 2'],
+			// If mode is chooseBranch data from both branches is required
+			// to continue, else data from any input suffices
+			requiredInputs: '={{ $parameter["mode"] === "chooseBranch" ? [0, 1] : 1 }}',
+			properties: [
+				{
+					displayName: 'Mode',
+					name: 'mode',
+					type: 'options',
+					options: [
+						{
+							name: 'Append',
+							value: 'append',
+							description: 'All items of input 1, then all items of input 2',
+						},
+						{
+							name: 'Combine',
+							value: 'combine',
+							description: 'Merge matching items together',
+						},
+						{
+							name: 'Choose Branch',
+							value: 'chooseBranch',
+							description: 'Output input data, without modifying it',
+						},
+					],
+					default: 'append',
+					description: 'How data of branches should be merged',
+				},
+				{
+					displayName: 'Combination Mode',
+					name: 'combinationMode',
+					type: 'options',
+					options: [
+						{
+							name: 'Merge By Fields',
+							value: 'mergeByFields',
+							description: 'Combine items with the same field values',
+						},
+						{
+							name: 'Merge By Position',
+							value: 'mergeByPosition',
+							description: 'Combine items based on their order',
+						},
+						{
+							name: 'Multiplex',
+							value: 'multiplex',
+							description: 'All possible item combinations (cross join)',
+						},
+					],
+					default: 'mergeByFields',
+					displayOptions: {
+						show: {
+							mode: ['combine'],
+						},
+					},
+				},
+				// mergeByFields ------------------------------------------------------------------
+				{
+					displayName: 'Fields to Match',
+					name: 'mergeByFields',
+					type: 'fixedCollection',
+					placeholder: 'Add Fields to Match',
+					default: { values: [{ field1: '', field2: '' }] },
+					typeOptions: {
+						multipleValues: true,
+					},
+					options: [
+						{
+							displayName: 'Values',
+							name: 'values',
+							values: [
+								{
+									displayName: 'Input 1 Field',
+									name: 'field1',
+									type: 'string',
+									default: '',
+									// eslint-disable-next-line n8n-nodes-base/node-param-placeholder-miscased-id
+									placeholder: 'e.g. id',
+									hint: ' Enter the field name as text',
+									requiresDataPath: 'single',
+								},
+								{
+									displayName: 'Input 2 Field',
+									name: 'field2',
+									type: 'string',
+									default: '',
+									// eslint-disable-next-line n8n-nodes-base/node-param-placeholder-miscased-id
+									placeholder: 'e.g. id',
+									hint: ' Enter the field name as text',
+									requiresDataPath: 'single',
+								},
+							],
+						},
+					],
+					displayOptions: {
+						show: {
+							mode: ['combine'],
+							combinationMode: ['mergeByFields'],
+						},
+					},
+				},
+				{
+					displayName: 'Output Type',
+					name: 'joinMode',
+					type: 'options',
+					// eslint-disable-next-line n8n-nodes-base/node-param-options-type-unsorted-items
+					options: [
+						{
+							name: 'Keep Matches',
+							value: 'keepMatches',
+							description: 'Items that match, merged together (inner join)',
+						},
+						{
+							name: 'Keep Non-Matches',
+							value: 'keepNonMatches',
+							description: "Items that don't match",
+						},
+						{
+							name: 'Keep Everything',
+							value: 'keepEverything',
+							description:
+								"Items that match merged together, plus items that don't match (outer join)",
+						},
+						{
+							name: 'Enrich Input 1',
+							value: 'enrichInput1',
+							description: 'All of input 1, with data from input 2 added in (left join)',
+						},
+						{
+							name: 'Enrich Input 2',
+							value: 'enrichInput2',
+							description: 'All of input 2, with data from input 1 added in (right join)',
+						},
+					],
+					default: 'keepMatches',
+					displayOptions: {
+						show: {
+							mode: ['combine'],
+							combinationMode: ['mergeByFields'],
+						},
+					},
+				},
+				{
+					displayName: 'Output Data From',
+					name: 'outputDataFrom',
+					type: 'options',
+					options: [
+						{
+							name: 'Both Inputs Merged Together',
+							value: 'both',
+						},
+						{
+							name: 'Input 1',
+							value: 'input1',
+						},
+						{
+							name: 'Input 2',
+							value: 'input2',
+						},
+					],
+					default: 'both',
+					displayOptions: {
+						show: {
+							mode: ['combine'],
+							combinationMode: ['mergeByFields'],
+							joinMode: ['keepMatches'],
+						},
+					},
+				},
+				{
+					displayName: 'Output Data From',
+					name: 'outputDataFrom',
+					type: 'options',
+					options: [
+						{
+							name: 'Both Inputs Appended Together',
+							value: 'both',
+						},
+						{
+							name: 'Input 1',
+							value: 'input1',
+						},
+						{
+							name: 'Input 2',
+							value: 'input2',
+						},
+					],
+					default: 'both',
+					displayOptions: {
+						show: {
+							mode: ['combine'],
+							combinationMode: ['mergeByFields'],
+							joinMode: ['keepNonMatches'],
+						},
+					},
+				},
+
+				// chooseBranch -----------------------------------------------------------------
+				{
+					displayName: 'Output Type',
+					name: 'chooseBranchMode',
+					type: 'options',
+					options: [
+						{
+							name: 'Wait for Both Inputs to Arrive',
+							value: 'waitForBoth',
+						},
+					],
+					default: 'waitForBoth',
+					displayOptions: {
+						show: {
+							mode: ['chooseBranch'],
+						},
+					},
+				},
+				{
+					displayName: 'Output',
+					name: 'output',
+					type: 'options',
+					options: [
+						{
+							name: 'Input 1 Data',
+							value: 'input1',
+						},
+						{
+							name: 'Input 2 Data',
+							value: 'input2',
+						},
+						{
+							name: 'A Single, Empty Item',
+							value: 'empty',
+						},
+					],
+					default: 'input1',
+					displayOptions: {
+						show: {
+							mode: ['chooseBranch'],
+							chooseBranchMode: ['waitForBoth'],
+						},
+					},
+				},
+
+				...optionsDescription,
+			],
+		};
+	}
+
+	async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
+		let returnData: INodeExecutionData[] = [];
+
+		const mode = this.getNodeParameter('mode', 0) as string;
+
+		if (mode === 'append') {
+			for (let i = 0; i < 2; i++) {
+				returnData.push.apply(returnData, this.getInputData(i));
+			}
+		}
+
+		if (mode === 'combine') {
+			const combinationMode = this.getNodeParameter('combinationMode', 0) as string;
+
+			if (combinationMode === 'multiplex') {
+				const clashHandling = this.getNodeParameter(
+					'options.clashHandling.values',
+					0,
+					{},
+				) as ClashResolveOptions;
+
+				let input1 = this.getInputData(0);
+				let input2 = this.getInputData(1);
+
+				if (clashHandling.resolveClash === 'preferInput1') {
+					[input1, input2] = [input2, input1];
+				}
+
+				if (clashHandling.resolveClash === 'addSuffix') {
+					input1 = addSuffixToEntriesKeys(input1, '1');
+					input2 = addSuffixToEntriesKeys(input2, '2');
+				}
+
+				const mergeIntoSingleObject = selectMergeMethod(clashHandling);
+
+				if (!input1 || !input2) {
+					return [returnData];
+				}
+
+				let entry1: INodeExecutionData;
+				let entry2: INodeExecutionData;
+
+				for (entry1 of input1) {
+					for (entry2 of input2) {
+						returnData.push({
+							json: {
+								...mergeIntoSingleObject(entry1.json, entry2.json),
+							},
+							binary: {
+								...merge({}, entry1.binary, entry2.binary),
+							},
+							pairedItem: [
+								entry1.pairedItem as IPairedItemData,
+								entry2.pairedItem as IPairedItemData,
+							],
+						});
+					}
+				}
+				return [returnData];
+			}
+
+			if (combinationMode === 'mergeByPosition') {
+				const clashHandling = this.getNodeParameter(
+					'options.clashHandling.values',
+					0,
+					{},
+				) as ClashResolveOptions;
+				const includeUnpaired = this.getNodeParameter(
+					'options.includeUnpaired',
+					0,
+					false,
+				) as boolean;
+
+				let input1 = this.getInputData(0);
+				let input2 = this.getInputData(1);
+
+				if (input1?.length === 0 || input2?.length === 0) {
+					// If data of any input is missing, return the data of
+					// the input that contains data
+					return [[...input1, ...input2]];
+				}
+
+				if (clashHandling.resolveClash === 'preferInput1') {
+					[input1, input2] = [input2, input1];
+				}
+
+				if (clashHandling.resolveClash === 'addSuffix') {
+					input1 = addSuffixToEntriesKeys(input1, '1');
+					input2 = addSuffixToEntriesKeys(input2, '2');
+				}
+
+				if (input1 === undefined || input1.length === 0) {
+					if (includeUnpaired) {
+						return [input2];
+					}
+					return [returnData];
+				}
+
+				if (input2 === undefined || input2.length === 0) {
+					if (includeUnpaired) {
+						return [input1];
+					}
+					return [returnData];
+				}
+
+				let numEntries: number;
+				if (includeUnpaired) {
+					numEntries = Math.max(input1.length, input2.length);
+				} else {
+					numEntries = Math.min(input1.length, input2.length);
+				}
+
+				const mergeIntoSingleObject = selectMergeMethod(clashHandling);
+
+				for (let i = 0; i < numEntries; i++) {
+					if (i >= input1.length) {
+						returnData.push(input2[i]);
+						continue;
+					}
+					if (i >= input2.length) {
+						returnData.push(input1[i]);
+						continue;
+					}
+
+					const entry1 = input1[i];
+					const entry2 = input2[i];
+
+					returnData.push({
+						json: {
+							...mergeIntoSingleObject(entry1.json, entry2.json),
+						},
+						binary: {
+							...merge({}, entry1.binary, entry2.binary),
+						},
+						pairedItem: [
+							entry1.pairedItem as IPairedItemData,
+							entry2.pairedItem as IPairedItemData,
+						],
+					});
+				}
+			}
+
+			if (combinationMode === 'mergeByFields') {
+				const matchFields = checkMatchFieldsInput(
+					this.getNodeParameter('mergeByFields.values', 0, []) as IDataObject[],
+				);
+
+				const joinMode = this.getNodeParameter('joinMode', 0) as MatchFieldsJoinMode;
+				const outputDataFrom = this.getNodeParameter(
+					'outputDataFrom',
+					0,
+					'both',
+				) as MatchFieldsOutput;
+				const options = this.getNodeParameter('options', 0, {}) as MatchFieldsOptions;
+
+				options.joinMode = joinMode;
+				options.outputDataFrom = outputDataFrom;
+
+				const nodeVersion = this.getNode().typeVersion;
+
+				let input1 = this.getInputData(0);
+				let input2 = this.getInputData(1);
+
+				if (nodeVersion < 2.1) {
+					input1 = checkInput(
+						this.getInputData(0),
+						matchFields.map((pair) => pair.field1),
+						options.disableDotNotation || false,
+						'Input 1',
+					);
+					if (!input1) return [returnData];
+
+					input2 = checkInput(
+						this.getInputData(1),
+						matchFields.map((pair) => pair.field2),
+						options.disableDotNotation || false,
+						'Input 2',
+					);
+				} else {
+					if (!input1) return [returnData];
+				}
+
+				if (input1?.length === 0 || input2?.length === 0) {
+					if (!input1?.length && joinMode === 'keepNonMatches' && outputDataFrom === 'input1')
+						return [returnData];
+					if (!input2?.length && joinMode === 'keepNonMatches' && outputDataFrom === 'input2')
+						return [returnData];
+
+					if (joinMode === 'keepMatches') {
+						// Stop the execution
+						return [[]];
+					} else if (joinMode === 'enrichInput1' && input1?.length === 0) {
+						// No data to enrich so stop
+						return [[]];
+					} else if (joinMode === 'enrichInput2' && input2?.length === 0) {
+						// No data to enrich so stop
+						return [[]];
+					} else {
+						// Return the data of any of the inputs that contains data
+						return [[...input1, ...input2]];
+					}
+				}
+
+				if (!input1) return [returnData];
+
+				if (!input2 || !matchFields.length) {
+					if (
+						joinMode === 'keepMatches' ||
+						joinMode === 'keepEverything' ||
+						joinMode === 'enrichInput2'
+					) {
+						return [returnData];
+					}
+					return [input1];
+				}
+
+				const matches = findMatches(input1, input2, matchFields, options);
+
+				if (joinMode === 'keepMatches' || joinMode === 'keepEverything') {
+					let output: INodeExecutionData[] = [];
+					const clashResolveOptions = this.getNodeParameter(
+						'options.clashHandling.values',
+						0,
+						{},
+					) as ClashResolveOptions;
+
+					if (outputDataFrom === 'input1') {
+						output = matches.matched.map((match) => match.entry);
+					}
+					if (outputDataFrom === 'input2') {
+						output = matches.matched2;
+					}
+					if (outputDataFrom === 'both') {
+						output = mergeMatched(matches.matched, clashResolveOptions);
+					}
+
+					if (joinMode === 'keepEverything') {
+						let unmatched1 = matches.unmatched1;
+						let unmatched2 = matches.unmatched2;
+						if (clashResolveOptions.resolveClash === 'addSuffix') {
+							unmatched1 = addSuffixToEntriesKeys(unmatched1, '1');
+							unmatched2 = addSuffixToEntriesKeys(unmatched2, '2');
+						}
+						output = [...output, ...unmatched1, ...unmatched2];
+					}
+
+					returnData = returnData.concat(output);
+				}
+
+				if (joinMode === 'keepNonMatches') {
+					if (outputDataFrom === 'input1') {
+						return [matches.unmatched1];
+					}
+					if (outputDataFrom === 'input2') {
+						return [matches.unmatched2];
+					}
+					if (outputDataFrom === 'both') {
+						let output: INodeExecutionData[] = [];
+						output = output.concat(addSourceField(matches.unmatched1, 'input1'));
+						output = output.concat(addSourceField(matches.unmatched2, 'input2'));
+						return [output];
+					}
+				}
+
+				if (joinMode === 'enrichInput1' || joinMode === 'enrichInput2') {
+					const clashResolveOptions = this.getNodeParameter(
+						'options.clashHandling.values',
+						0,
+						{},
+					) as ClashResolveOptions;
+
+					const mergedEntries = mergeMatched(matches.matched, clashResolveOptions, joinMode);
+
+					if (joinMode === 'enrichInput1') {
+						if (clashResolveOptions.resolveClash === 'addSuffix') {
+							returnData = returnData.concat(
+								mergedEntries,
+								addSuffixToEntriesKeys(matches.unmatched1, '1'),
+							);
+						} else {
+							returnData = returnData.concat(mergedEntries, matches.unmatched1);
+						}
+					} else {
+						if (clashResolveOptions.resolveClash === 'addSuffix') {
+							returnData = returnData.concat(
+								mergedEntries,
+								addSuffixToEntriesKeys(matches.unmatched2, '2'),
+							);
+						} else {
+							returnData = returnData.concat(mergedEntries, matches.unmatched2);
+						}
+					}
+				}
+			}
+		}
+
+		if (mode === 'chooseBranch') {
+			const chooseBranchMode = this.getNodeParameter('chooseBranchMode', 0) as string;
+
+			if (chooseBranchMode === 'waitForBoth') {
+				const output = this.getNodeParameter('output', 0) as string;
+
+				if (output === 'input1') {
+					returnData.push.apply(returnData, this.getInputData(0));
+				}
+				if (output === 'input2') {
+					returnData.push.apply(returnData, this.getInputData(1));
+				}
+				if (output === 'empty') {
+					const pairedItem = [
+						...this.getInputData(0).map((inputData) => inputData.pairedItem),
+						...this.getInputData(1).map((inputData) => inputData.pairedItem),
+					].flatMap(preparePairedItemDataArray);
+
+					returnData.push({
+						json: {},
+						pairedItem,
+					});
+				}
+			}
+		}
+
+		return [returnData];
+	}
+}

packages/nodes-base/nodes/Merge/v2/descriptions.ts

@@ -0,0 +1,213 @@
+import type { INodeProperties } from 'n8n-workflow';
+
+const clashHandlingProperties: INodeProperties = {
+	displayName: 'Clash Handling',
+	name: 'clashHandling',
+	type: 'fixedCollection',
+	default: {
+		values: { resolveClash: 'preferInput2', mergeMode: 'deepMerge', overrideEmpty: false },
+	},
+	options: [
+		{
+			displayName: 'Values',
+			name: 'values',
+			values: [
+				{
+					displayName: 'When Field Values Clash',
+					name: 'resolveClash',
+					type: 'options',
+					default: '',
+					options: [
+						{
+							name: 'Always Add Input Number to Field Names',
+							value: 'addSuffix',
+						},
+						{
+							name: 'Prefer Input 1 Version',
+							value: 'preferInput1',
+						},
+						{
+							name: 'Prefer Input 2 Version',
+							value: 'preferInput2',
+						},
+					],
+				},
+				{
+					displayName: 'Merging Nested Fields',
+					name: 'mergeMode',
+					type: 'options',
+					default: 'deepMerge',
+					options: [
+						{
+							name: 'Deep Merge',
+							value: 'deepMerge',
+							description: 'Merge at every level of nesting',
+						},
+						{
+							name: 'Shallow Merge',
+							value: 'shallowMerge',
+							description:
+								'Merge at the top level only (all nested fields will come from the same input)',
+						},
+					],
+					hint: 'How to merge when there are sub-fields below the top-level ones',
+					displayOptions: {
+						show: {
+							resolveClash: ['preferInput1', 'preferInput2'],
+						},
+					},
+				},
+				{
+					displayName: 'Minimize Empty Fields',
+					name: 'overrideEmpty',
+					type: 'boolean',
+					default: false,
+					description:
+						"Whether to override the preferred input version for a field if it is empty and the other version isn't. Here 'empty' means undefined, null or an empty string.",
+					displayOptions: {
+						show: {
+							resolveClash: ['preferInput1', 'preferInput2'],
+						},
+					},
+				},
+			],
+		},
+	],
+};
+
+export const optionsDescription: INodeProperties[] = [
+	{
+		displayName: 'Options',
+		name: 'options',
+		type: 'collection',
+		placeholder: 'Add option',
+		default: {},
+		options: [
+			{
+				...clashHandlingProperties,
+				displayOptions: {
+					show: {
+						'/mode': ['combine'],
+						'/combinationMode': ['mergeByFields'],
+					},
+					hide: {
+						'/joinMode': ['keepMatches', 'keepNonMatches'],
+					},
+				},
+			},
+			{
+				...clashHandlingProperties,
+				displayOptions: {
+					show: {
+						'/mode': ['combine'],
+						'/combinationMode': ['mergeByFields'],
+						'/joinMode': ['keepMatches'],
+						'/outputDataFrom': ['both'],
+					},
+				},
+			},
+			{
+				...clashHandlingProperties,
+				displayOptions: {
+					show: {
+						'/mode': ['combine'],
+						'/combinationMode': ['multiplex', 'mergeByPosition'],
+					},
+				},
+			},
+			{
+				displayName: 'Disable Dot Notation',
+				name: 'disableDotNotation',
+				type: 'boolean',
+				default: false,
+				description:
+					'Whether to disallow referencing child fields using `parent.child` in the field name',
+				displayOptions: {
+					show: {
+						'/mode': ['combine'],
+						'/combinationMode': ['mergeByFields'],
+					},
+				},
+			},
+			{
+				displayName: 'Fuzzy Compare',
+				name: 'fuzzyCompare',
+				type: 'boolean',
+				default: false,
+				description:
+					"Whether to tolerate small type differences when comparing fields. E.g. the number 3 and the string '3' are treated as the same.",
+			},
+			{
+				displayName: 'Include Any Unpaired Items',
+				name: 'includeUnpaired',
+				type: 'boolean',
+				default: false,
+				// eslint-disable-next-line n8n-nodes-base/node-param-description-boolean-without-whether
+				description:
+					'If there are different numbers of items in input 1 and input 2, whether to include the ones at the end with nothing to pair with',
+				displayOptions: {
+					show: {
+						'/mode': ['combine'],
+						'/combinationMode': ['mergeByPosition'],
+					},
+				},
+			},
+			{
+				displayName: 'Multiple Matches',
+				name: 'multipleMatches',
+				type: 'options',
+				default: 'all',
+				options: [
+					{
+						name: 'Include All Matches',
+						value: 'all',
+						description: 'Output multiple items if there are multiple matches',
+					},
+					{
+						name: 'Include First Match Only',
+						value: 'first',
+						description: 'Only ever output a single item per match',
+					},
+				],
+				displayOptions: {
+					show: {
+						'/mode': ['combine'],
+						'/combinationMode': ['mergeByFields'],
+						'/joinMode': ['keepMatches'],
+						'/outputDataFrom': ['both'],
+					},
+				},
+			},
+			{
+				displayName: 'Multiple Matches',
+				name: 'multipleMatches',
+				type: 'options',
+				default: 'all',
+				options: [
+					{
+						name: 'Include All Matches',
+						value: 'all',
+						description: 'Output multiple items if there are multiple matches',
+					},
+					{
+						name: 'Include First Match Only',
+						value: 'first',
+						description: 'Only ever output a single item per match',
+					},
+				],
+				displayOptions: {
+					show: {
+						'/mode': ['combine'],
+						'/combinationMode': ['mergeByFields'],
+						'/joinMode': ['enrichInput1', 'enrichInput2', 'keepEverything'],
+					},
+				},
+			},
+		],
+		displayOptions: {
+			hide: {
+				mode: ['chooseBranch', 'append'],
+			},
+		},
+	},
+];

packages/nodes-base/nodes/Merge/v2/interfaces.ts

@@ -0,0 +1,27 @@
+type MultipleMatches = 'all' | 'first';
+
+export type MatchFieldsOptions = {
+	joinMode: MatchFieldsJoinMode;
+	outputDataFrom: MatchFieldsOutput;
+	multipleMatches: MultipleMatches;
+	disableDotNotation: boolean;
+	fuzzyCompare?: boolean;
+};
+
+type ClashMergeMode = 'deepMerge' | 'shallowMerge';
+type ClashResolveMode = 'addSuffix' | 'preferInput1' | 'preferInput2';
+
+export type ClashResolveOptions = {
+	resolveClash: ClashResolveMode;
+	mergeMode: ClashMergeMode;
+	overrideEmpty: boolean;
+};
+
+export type MatchFieldsOutput = 'both' | 'input1' | 'input2';
+
+export type MatchFieldsJoinMode =
+	| 'keepEverything'
+	| 'keepMatches'
+	| 'keepNonMatches'
+	| 'enrichInput2'
+	| 'enrichInput1';

packages/nodes-base/nodes/Merge/v2/utils.ts

@@ -0,0 +1,361 @@
+import assign from 'lodash/assign';
+import assignWith from 'lodash/assignWith';
+import get from 'lodash/get';
+import merge from 'lodash/merge';
+import mergeWith from 'lodash/mergeWith';
+import type {
+	GenericValue,
+	IBinaryKeyData,
+	IDataObject,
+	INodeExecutionData,
+	IPairedItemData,
+} from 'n8n-workflow';
+import { ApplicationError } from '@n8n/errors';
+
+import { fuzzyCompare, preparePairedItemDataArray } from '@utils/utilities';
+
+import type { ClashResolveOptions, MatchFieldsJoinMode, MatchFieldsOptions } from './interfaces';
+
+type PairToMatch = {
+	field1: string;
+	field2: string;
+};
+
+type EntryMatches = {
+	entry: INodeExecutionData;
+	matches: INodeExecutionData[];
+};
+
+type CompareFunction = <T, U>(a: T, b: U) => boolean;
+
+export function addSuffixToEntriesKeys(data: INodeExecutionData[], suffix: string) {
+	return data.map((entry) => {
+		const json: IDataObject = {};
+		Object.keys(entry.json).forEach((key) => {
+			json[`${key}_${suffix}`] = entry.json[key];
+		});
+		return { ...entry, json };
+	});
+}
+
+function findAllMatches(
+	data: INodeExecutionData[],
+	lookup: IDataObject,
+	disableDotNotation: boolean,
+	isEntriesEqual: CompareFunction,
+) {
+	return data.reduce((acc, entry2, i) => {
+		if (entry2 === undefined) return acc;
+
+		for (const key of Object.keys(lookup)) {
+			const excpectedValue = lookup[key];
+			let entry2FieldValue;
+
+			if (disableDotNotation) {
+				entry2FieldValue = entry2.json[key];
+			} else {
+				entry2FieldValue = get(entry2.json, key);
+			}
+
+			if (!isEntriesEqual(excpectedValue, entry2FieldValue)) {
+				return acc;
+			}
+		}
+
+		return acc.concat({
+			entry: entry2,
+			index: i,
+		});
+	}, [] as IDataObject[]);
+}
+
+function findFirstMatch(
+	data: INodeExecutionData[],
+	lookup: IDataObject,
+	disableDotNotation: boolean,
+	isEntriesEqual: CompareFunction,
+) {
+	const index = data.findIndex((entry2) => {
+		if (entry2 === undefined) return false;
+
+		for (const key of Object.keys(lookup)) {
+			const excpectedValue = lookup[key];
+			let entry2FieldValue;
+
+			if (disableDotNotation) {
+				entry2FieldValue = entry2.json[key];
+			} else {
+				entry2FieldValue = get(entry2.json, key);
+			}
+
+			if (!isEntriesEqual(excpectedValue, entry2FieldValue)) {
+				return false;
+			}
+		}
+
+		return true;
+	});
+	if (index === -1) return [];
+
+	return [{ entry: data[index], index }];
+}
+
+export function findMatches(
+	input1: INodeExecutionData[],
+	input2: INodeExecutionData[],
+	fieldsToMatch: PairToMatch[],
+	options: MatchFieldsOptions,
+) {
+	const data1 = [...input1];
+	const data2 = [...input2];
+
+	const isEntriesEqual = fuzzyCompare(options.fuzzyCompare as boolean);
+	const disableDotNotation = options.disableDotNotation || false;
+	const multipleMatches = (options.multipleMatches as string) || 'all';
+
+	const filteredData = {
+		matched: [] as EntryMatches[],
+		matched2: [] as INodeExecutionData[],
+		unmatched1: [] as INodeExecutionData[],
+		unmatched2: [] as INodeExecutionData[],
+	};
+
+	const matchedInInput2 = new Set<number>();
+
+	matchesLoop: for (const entry1 of data1) {
+		const lookup: IDataObject = {};
+
+		fieldsToMatch.forEach((matchCase) => {
+			let valueToCompare;
+			if (disableDotNotation) {
+				valueToCompare = entry1.json[matchCase.field1];
+			} else {
+				valueToCompare = get(entry1.json, matchCase.field1);
+			}
+			lookup[matchCase.field2] = valueToCompare;
+		});
+
+		for (const fieldValue of Object.values(lookup)) {
+			if (fieldValue === undefined) {
+				filteredData.unmatched1.push(entry1);
+				continue matchesLoop;
+			}
+		}
+
+		const foundedMatches =
+			multipleMatches === 'all'
+				? findAllMatches(data2, lookup, disableDotNotation, isEntriesEqual)
+				: findFirstMatch(data2, lookup, disableDotNotation, isEntriesEqual);
+
+		const matches = foundedMatches.map((match) => match.entry) as INodeExecutionData[];
+		foundedMatches.map((match) => matchedInInput2.add(match.index as number));
+
+		if (matches.length) {
+			if (
+				options.outputDataFrom === 'both' ||
+				options.joinMode === 'enrichInput1' ||
+				options.joinMode === 'enrichInput2'
+			) {
+				matches.forEach((match) => {
+					filteredData.matched.push({
+						entry: entry1,
+						matches: [match],
+					});
+				});
+			} else {
+				filteredData.matched.push({
+					entry: entry1,
+					matches,
+				});
+			}
+		} else {
+			filteredData.unmatched1.push(entry1);
+		}
+	}
+
+	data2.forEach((entry, i) => {
+		if (matchedInInput2.has(i)) {
+			filteredData.matched2.push(entry);
+		} else {
+			filteredData.unmatched2.push(entry);
+		}
+	});
+
+	return filteredData;
+}
+
+export function selectMergeMethod(clashResolveOptions: ClashResolveOptions) {
+	const mergeMode = clashResolveOptions.mergeMode as string;
+
+	if (clashResolveOptions.overrideEmpty) {
+		function customizer(targetValue: GenericValue, srcValue: GenericValue) {
+			if (srcValue === undefined || srcValue === null || srcValue === '') {
+				return targetValue;
+			}
+		}
+		if (mergeMode === 'deepMerge') {
+			return (target: IDataObject, ...source: IDataObject[]) => {
+				const targetCopy = Object.assign({}, target);
+				return mergeWith(targetCopy, ...source, customizer);
+			};
+		}
+		if (mergeMode === 'shallowMerge') {
+			return (target: IDataObject, ...source: IDataObject[]) => {
+				const targetCopy = Object.assign({}, target);
+				return assignWith(targetCopy, ...source, customizer);
+			};
+		}
+	} else {
+		if (mergeMode === 'deepMerge') {
+			return (target: IDataObject, ...source: IDataObject[]) => merge({}, target, ...source);
+		}
+		if (mergeMode === 'shallowMerge') {
+			return (target: IDataObject, ...source: IDataObject[]) => assign({}, target, ...source);
+		}
+	}
+	return (target: IDataObject, ...source: IDataObject[]) => merge({}, target, ...source);
+}
+
+export function mergeMatched(
+	matched: EntryMatches[],
+	clashResolveOptions: ClashResolveOptions,
+	joinMode?: MatchFieldsJoinMode,
+) {
+	const returnData: INodeExecutionData[] = [];
+	let resolveClash = clashResolveOptions.resolveClash as string;
+
+	const mergeIntoSingleObject = selectMergeMethod(clashResolveOptions);
+
+	for (const match of matched) {
+		let { entry, matches } = match;
+
+		let json: IDataObject = {};
+		let binary: IBinaryKeyData = {};
+		let pairedItem: IPairedItemData[] = [];
+
+		if (resolveClash === 'addSuffix') {
+			const suffix1 = '1';
+			const suffix2 = '2';
+
+			[entry] = addSuffixToEntriesKeys([entry], suffix1);
+			matches = addSuffixToEntriesKeys(matches, suffix2);
+
+			json = mergeIntoSingleObject({ ...entry.json }, ...matches.map((item) => item.json));
+			binary = mergeIntoSingleObject(
+				{ ...entry.binary },
+				...matches.map((item) => item.binary as IDataObject),
+			);
+			pairedItem = [
+				...preparePairedItemDataArray(entry.pairedItem),
+				...matches.map((item) => preparePairedItemDataArray(item.pairedItem)).flat(),
+			];
+		} else {
+			const preferInput1 = 'preferInput1';
+			const preferInput2 = 'preferInput2';
+
+			if (resolveClash === undefined) {
+				if (joinMode !== 'enrichInput2') {
+					resolveClash = 'preferInput2';
+				} else {
+					resolveClash = 'preferInput1';
+				}
+			}
+
+			if (resolveClash === preferInput1) {
+				const [firstMatch, ...restMatches] = matches;
+				json = mergeIntoSingleObject(
+					{ ...firstMatch.json },
+					...restMatches.map((item) => item.json),
+					entry.json,
+				);
+				binary = mergeIntoSingleObject(
+					{ ...firstMatch.binary },
+					...restMatches.map((item) => item.binary as IDataObject),
+					entry.binary as IDataObject,
+				);
+
+				pairedItem = [
+					...preparePairedItemDataArray(firstMatch.pairedItem),
+					...restMatches.map((item) => preparePairedItemDataArray(item.pairedItem)).flat(),
+					...preparePairedItemDataArray(entry.pairedItem),
+				];
+			}
+
+			if (resolveClash === preferInput2) {
+				json = mergeIntoSingleObject({ ...entry.json }, ...matches.map((item) => item.json));
+				binary = mergeIntoSingleObject(
+					{ ...entry.binary },
+					...matches.map((item) => item.binary as IDataObject),
+				);
+				pairedItem = [
+					...preparePairedItemDataArray(entry.pairedItem),
+					...matches.map((item) => preparePairedItemDataArray(item.pairedItem)).flat(),
+				];
+			}
+		}
+
+		returnData.push({
+			json,
+			binary,
+			pairedItem,
+		});
+	}
+
+	return returnData;
+}
+
+export function checkMatchFieldsInput(data: IDataObject[]) {
+	if (data.length === 1 && data[0].field1 === '' && data[0].field2 === '') {
+		throw new ApplicationError(
+			'You need to define at least one pair of fields in "Fields to Match" to match on',
+			{ level: 'warning' },
+		);
+	}
+	for (const [index, pair] of data.entries()) {
+		if (pair.field1 === '' || pair.field2 === '') {
+			throw new ApplicationError(
+				`You need to define both fields in "Fields to Match" for pair ${index + 1},
+				 field 1 = '${pair.field1}'
+				 field 2 = '${pair.field2}'`,
+				{ level: 'warning' },
+			);
+		}
+	}
+	return data as PairToMatch[];
+}
+
+export function checkInput(
+	input: INodeExecutionData[],
+	fields: string[],
+	disableDotNotation: boolean,
+	inputLabel: string,
+) {
+	for (const field of fields) {
+		const isPresent = (input || []).some((entry) => {
+			if (disableDotNotation) {
+				return entry.json.hasOwnProperty(field);
+			}
+			return get(entry.json, field, undefined) !== undefined;
+		});
+		if (!isPresent) {
+			throw new ApplicationError(
+				`Field '${field}' is not present in any of items in '${inputLabel}'`,
+				{ level: 'warning' },
+			);
+		}
+	}
+	return input;
+}
+
+export function addSourceField(data: INodeExecutionData[], sourceField: string) {
+	return data.map((entry) => {
+		const json = {
+			...entry.json,
+			_source: sourceField,
+		};
+		return {
+			...entry,
+			json,
+		};
+	});
+}