feat(core): Expression function $ifEmpty (#7660)

Github issue / Community forum post (link here to close automatically):

---------

Co-authored-by: Elias Meire <elias@meire.dev>

packages/workflow/src/Extensions/ExtendedFunctions.ts

@@ -1,4 +1,4 @@
-import { ExpressionExtensionError } from '../ExpressionError';
+import { ExpressionError, ExpressionExtensionError } from '../ExpressionError';
 import { average as aAverage } from './ArrayExtensions';
 
 const min = Math.min;
@@ -39,6 +39,36 @@ const not = (value: unknown): boolean => {
 	return !value;
 };
 
+function ifEmpty<T, V>(value: V, defaultValue: T) {
+	if (arguments.length !== 2) {
+		throw new ExpressionError('expected two arguments (value, defaultValue) for this function');
+	}
+	if (value === undefined || value === null || value === '') {
+		return defaultValue;
+	}
+	if (typeof value === 'object') {
+		if (Array.isArray(value) && !value.length) {
+			return defaultValue;
+		}
+		if (!Object.keys(value).length) {
+			return defaultValue;
+		}
+	}
+	return value;
+}
+
+ifEmpty.doc = {
+	name: 'ifEmpty',
+	description:
+		'Returns the default value if the value is empty. Empty values are undefined, null, empty strings, arrays without elements and objects without keys.',
+	returnType: 'any',
+	args: [
+		{ name: 'value', type: 'any' },
+		{ name: 'defaultValue', type: 'any' },
+	],
+	docURL: 'https://docs.n8n.io/code-examples/expressions/data-transformation-functions/#if-empty',
+};
+
 export const extendedFunctions = {
 	min,
 	max,
@@ -50,4 +80,5 @@ export const extendedFunctions = {
 	$max: max,
 	$average: average,
 	$not: not,
+	$ifEmpty: ifEmpty,
 };

packages/workflow/test/ExpressionExtensions/ExpressionExtension.test.ts

@@ -228,5 +228,18 @@ describe('tmpl Expression Parser', () => {
 			expect(evaluate('={{ $not("") }}')).toEqual(true);
 			expect(evaluate('={{ $not("a") }}')).toEqual(false);
 		});
+		test('$ifEmpty', () => {
+			expect(evaluate('={{ $ifEmpty(1, "default") }}')).toEqual(1);
+			expect(evaluate('={{ $ifEmpty(0, "default") }}')).toEqual(0);
+			expect(evaluate('={{ $ifEmpty(false, "default") }}')).toEqual(false);
+			expect(evaluate('={{ $ifEmpty(true, "default") }}')).toEqual(true);
+			expect(evaluate('={{ $ifEmpty("", "default") }}')).toEqual('default');
+			expect(evaluate('={{ $ifEmpty(null, "default") }}')).toEqual('default');
+			expect(evaluate('={{ $ifEmpty(undefined, "default") }}')).toEqual('default');
+			expect(evaluate('={{ $ifEmpty([], "default") }}')).toEqual('default');
+			expect(evaluate('={{ $ifEmpty({}, "default") }}')).toEqual('default');
+			expect(evaluate('={{ $ifEmpty([1], "default") }}')).toEqual([1]);
+			expect(evaluate('={{ $ifEmpty({a: 1}, "default") }}')).toEqual({ a: 1 });
+		});
 	});
 });